refactor: implement pluggable multi-channel architecture

[gabi-simons]

Type of Change

• Skill - adds a new skill in .claude/skills/
• Fix - bug fix or security fix to source code
• Simplification - reduces or simplifies source code

🚀 Description

This PR introduces a major architectural shift, transforming NanoClaw from a hardcoded WhatsApp application into a fully pluggable, multi-channel platform.

Communication channels (WhatsApp, Telegram, Slack, Discord, and Gmail) have been entirely decoupled from the core engine. They now operate as self-contained skills that auto-register at startup. This enables a clean, zero-config channel discovery process and paves the way for easily adding new platforms in the future without modifying core orchestrator logic.

🏗️ Key Changes

Architecture & Registry

• Channel Registry (src/channels/registry.ts): Introduced a centralized registry using the Factory pattern. It exposes registerChannel(name, factory), getRegisteredChannelNames(), and getChannelFactory(name).
• Barrel-File Pattern: Channels now self-register via side-effect imports in src/channels/index.ts (e.g., import './slack.js'). The orchestrator simply initializes whatever is registered.
• Factory Pattern Implementation: Each channel exports a factory function that returns a Channel instance, or null if the required credentials are missing (allowing it to gracefully skip initialization).

Skills & Modules

• WhatsApp Decoupling: Extracted all WhatsApp-specific logic into a standalone add-whatsapp skill package (including manifest, channel code, auth setup, and tests).
• Skills Migration: Successfully converted all 5 existing channel skills (Telegram, Discord, Slack, Gmail, WhatsApp) from the old main-branch modify pattern to the new pluggable self-registration architecture.

[gavrielc]

Looks good!!

Added one comment. Besides that, this should be added to the changelog with a tag as a breaking change and in the changelog should direct what to run to keep current behavior (/add-whatsapp).

Also, should put a reference to the changelog in the CLAUDE.md so if someone is troubleshooting why they don't have whatsapp claude will see straight away.

And we should also post in Discord ahead of merging

[antonlobanovskiy]

Discord Setup — Field Notes

Tested the add-discord skill on this branch. Everything worked end-to-end, but the Discord bot invite flow in SKILL.md needs a few clarifications for first-time users:

1. Skip the OAuth2 URL Generator — use a direct invite link instead

The SKILL.md instructions say to use OAuth2 → URL Generator and select the bot scope. In practice this is confusing:

• The bot scope doesn't appear in the URL Generator's scope list (it's hidden unless the app already has a bot configured in a certain way)
• When other scopes are selected, it demands a redirect URI

It's simpler to just construct the invite URL directly from the Client ID:

https://discord.com/oauth2/authorize?client_id=<CLIENT_ID>&scope=bot&permissions=68608

Permissions breakdown: View Channels (1024) + Send Messages (2048) + Read Message History (65536) = 68608

The Client ID is visible on the General Information tab of the Developer Portal.

2. Disable "Requires OAuth2 Code Grant"

New applications sometimes have "Requires OAuth2 Code Grant" enabled on the Bot tab. With it on, the invite link above returns "This integration requires a code grant" and the bot can't be added to a server.

Fix: Bot tab → scroll down → toggle "Requires OAuth2 Code Grant" OFF → Save Changes

Worth adding a troubleshooting entry for this in the skill.

---

Otherwise the skill applied cleanly, tests all passed (349/349), and the bot connected and responded correctly on first message. Great work on the pluggable architecture!

[gavrielc]

Suggested change

	All notable changes to NanoClaw will be documented in this file.
	## BREAKING CHANGE — Pluggable Channel Architecture
	NanoClaw now uses a pluggable channel architecture. WhatsApp is no longer
	bundled in core — it is a skill that must be explicitly applied.
	**What changed:**
	- Channels (WhatsApp, Telegram, Slack, Discord, Gmail) are now pluggable
	skills that self-register at startup via `registerChannel()`.
	- The `ENABLED_CHANNELS` environment variable has been removed. Channels
	auto-enable when their credentials are present (e.g., WhatsApp activates
	when `store/auth/creds.json` exists; Telegram activates when
	`TELEGRAM_BOT_TOKEN` is set in `.env`).
	- The `setup/channels` step has been removed from the setup wizard.
	**Migration for existing WhatsApp users:**
	If you are upgrading from a previous version and use WhatsApp, you must
	install the WhatsApp skill:
	```bash
	npx tsx skills-engine/apply.ts .claude/skills/add-whatsapp
	npm run build
	```
	Then restart the service. Your existing auth credentials and registered
	groups are preserved — no re-authentication needed.
	[BREAKING] WhatsApp removed from core, now a skill. Run `/add-whatsapp` to re-add (existing auth/groups preserved).

[antonlobanovskiy]

Forgot to add link to PR
antonlobanovskiy:fix/discord-skill-invite-flow-clean

[gavrielc]

Since we're adding the changelog, we should reference it from README.md. Suggested addition before the ## License section:

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for breaking changes and migration notes.

[neutmute]

Installed clean for first time from this branch, it all worked. Authenticated WA via QR code. 👍

It does assume you will follow through with whatsapp skill - so perhaps a follow up PR would be to give the user a prompt as to which messenger skill to plugin?

● User answered Claude's questions:
  ⎿  · How would you like to authenticate with Claude? → Anthropic API key

● Please add your Anthropic API key to the .env file in the project root:

  ANTHROPIC_API_KEY=sk-ant-...

  You can get your key from https://console.anthropic.com. Let me know once you've added it and I'll continue with the next step.

✻ Cooked for 2m 56s

❯ done, continue

● Searched for 1 pattern (ctrl+o to expand)

● Good. Now let's authenticate WhatsApp. Since this is a headless server, how would you like to authenticate?

● User answered Claude's questions:
  ⎿  · How would you like to authenticate WhatsApp? → QR code in terminal

● Please open another terminal in this directory and run:

  npm run auth

  Scan the QR code with WhatsApp (Settings → Linked Devices → Link a Device). Once you've scanned and it connects, come back here and let me know.

❯ done

Added PR into this PR to improve docs

[gavrielc]

Three files reference skills-engine/apply.ts as a CLI command, but that file is a module with no entry point — it exports applySkill() but has no main() or arg parsing. Running it with npx tsx loads the module and exits silently (code 0, no output, no files copied).

The correct CLI wrapper is scripts/apply-skill.ts, which parses args and calls the function. All the other channel skills (discord, telegram, slack, gmail, voice-transcription, apple-container) already use the correct path.

[glifocat]

Hey @gabi-simons ! While reviewing this PR's impact on our fork, we found two bugs in the current main that this refactor would carry
forward into the new architecture. We've submitted fixes as separate PRs — it would be ideal to merge them into main
before this lands, so the new add-whatsapp skill package starts from a correct baseline:

1. fix: inject date/time context into all agent prompts #627 — normalizeMessageContent() before reading message fields
   WhatsApp wraps view-once, ephemeral, and edited messages in container types (viewOnceMessageV2, ephemeralMessage,
   editedMessage). Without calling Baileys' normalizeMessageContent(), voice notes, images, and PDFs sent in these modes are
   silently dropped. The fix adds a single normalizeMessageContent() call before field access in whatsapp.ts.
2. fix: normalize wrapped WhatsApp messages before reading content #628 — Inject date/time context into all agent prompts
   LLMs can't reliably derive day-of-week from ISO timestamps. Currently only the task scheduler path had a date prefix (and
   even that was missing upstream). This fix extracts datePrefix() into a shared date-utils.ts module and applies it to all
   three prompt paths: processGroupMessages, startMessageLoop, and runTask.

Both are small, focused fixes with no overlap with the channel refactor. Merging them first means this PR's add-whatsapp
skill inherits the fixes automatically, and forks doing a fresh install on the new architecture get them out of the box.