style: apply prettier formatting

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.claude/scheduled_tasks.lock

@@ -0,0 +1 @@
+{"sessionId":"bedd47ed-bfa0-41da-9a03-93d41159b4cd","pid":24606,"acquiredAt":1776194767342}

.claude/settings.json

@@ -0,0 +1,41 @@
+{
+  "sandbox": {
+    "enabled": false
+  },
+  "permissions": {
+    "allow": [
+      "Bash(bash setup.sh*)",
+      "Bash(git remote *)",
+      "Bash(pnpm exec tsx setup/index.ts*)",
+      "Bash(pnpm exec tsx scripts/init-first-agent.ts*)",
+      "Bash(pnpm install @chat-adapter/*)",
+      "Bash(pnpm install chat-adapter-imessage*)",
+      "Bash(pnpm install @bitbasti/chat-adapter-webex*)",
+      "Bash(pnpm install @resend/chat-sdk-adapter*)",
+      "Bash(pnpm install @whiskeysockets/baileys*)",
+      "Bash(pnpm install @beeper/chat-adapter-matrix*)",
+      "Bash(pnpm install @nanoco/nanoclaw-dashboard*)",
+      "Bash(pnpm install --frozen-lockfile*)",
+      "Bash(pnpm run build*)",
+      "Bash(curl -fsSL onecli.sh*)",
+      "Bash(onecli *)",
+      "Bash(grep -q *)",
+      "Bash(echo *>> .env)",
+      "Bash(ls *)",
+      "Bash(cat ~/.config/nanoclaw/*)",
+      "Bash(tail *logs/*)",
+      "Bash(launchctl *nanoclaw*)",
+      "Bash(sqlite3 data/*)",
+      "Bash(docker info*)",
+      "Bash(docker logs *)",
+      "Bash(mkdir -p *)",
+      "Bash(cp .env *)",
+      "Bash(rsync -a .claude/skills/*)",
+      "Bash(head *)",
+      "Bash(xattr *)",
+      "Bash(find ~/.npm *)",
+      "Bash(which onecli*)",
+      "Bash(./container/build.sh*)"
+    ]
+  }
+}

.claude/skills/add-compact/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: add-compact
+description: Add /compact command for manual context compaction. Solves context rot in long sessions by forwarding the SDK's built-in /compact slash command. Main-group or trusted sender only.
+---
+
+# Add /compact Command
+
+Adds a `/compact` session command that compacts conversation history to fight context rot in long-running sessions. Uses the Claude Agent SDK's built-in `/compact` slash command — no synthetic system prompts.
+
+**Session contract:** `/compact` keeps the same logical session alive. The SDK returns a new session ID after compaction (via the `init` system message), which the agent-runner forwards to the orchestrator as `newSessionId`. No destructive reset occurs — the agent retains summarized context.
+
+## Phase 1: Pre-flight
+
+Check if `src/session-commands.ts` exists:
+
+```bash
+test -f src/session-commands.ts && echo "Already applied" || echo "Not applied"
+```
+
+If already applied, skip to Phase 3 (Verify).
+
+## Phase 2: Apply Code Changes
+
+Merge the skill branch:
+
+```bash
+git fetch upstream skill/compact
+git merge upstream/skill/compact
+```
+
+> **Note:** `upstream` is the remote pointing to `qwibitai/nanoclaw`. If using a different remote name, substitute accordingly.
+
+This adds:
+- `src/session-commands.ts` (extract and authorize session commands)
+- `src/session-commands.test.ts` (unit tests for command parsing and auth)
+- Session command interception in `src/index.ts` (both `processGroupMessages` and `startMessageLoop`)
+- Slash command handling in `container/agent-runner/src/index.ts`
+
+### Validate
+
+```bash
+pnpm test
+pnpm run build
+```
+
+### Rebuild container
+
+```bash
+./container/build.sh
+```
+
+### Restart service
+
+```bash
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
+# Linux: systemctl --user restart nanoclaw
+```
+
+## Phase 3: Verify
+
+### Integration Test
+
+1. Start NanoClaw in dev mode: `pnpm run dev`
+2. From the **main group** (self-chat), send exactly: `/compact`
+3. Verify:
+   - The agent acknowledges compaction (e.g., "Conversation compacted.")
+   - The session continues — send a follow-up message and verify the agent responds coherently
+   - A conversation archive is written to `groups/{folder}/conversations/` (by the PreCompact hook)
+   - Container logs show `Compact boundary observed` (confirms SDK actually compacted)
+   - If `compact_boundary` was NOT observed, the response says "compact_boundary was not observed"
+4. From a **non-main group** as a non-admin user, send: `@<assistant> /compact`
+5. Verify:
+   - The bot responds with "Session commands require admin access."
+   - No compaction occurs, no container is spawned for the command
+6. From a **non-main group** as the admin (device owner / `is_from_me`), send: `@<assistant> /compact`
+7. Verify:
+   - Compaction proceeds normally (same behavior as main group)
+8. While an **active container** is running for the main group, send `/compact`
+9. Verify:
+   - The active container is signaled to close (authorized senders only — untrusted senders cannot kill in-flight work)
+   - Compaction proceeds via a new container once the active one exits
+   - The command is not dropped (no cursor race)
+10. Send a normal message, then `/compact`, then another normal message in quick succession (same polling batch):
+11. Verify:
+    - Pre-compact messages are sent to the agent first (check container logs for two `runAgent` calls)
+    - Compaction proceeds after pre-compact messages are processed
+    - Messages **after** `/compact` in the batch are preserved (cursor advances to `/compact`'s timestamp only) and processed on the next poll cycle
+12. From a **non-main group** as a non-admin user, send `@<assistant> /compact`:
+13. Verify:
+    - Denial message is sent ("Session commands require admin access.")
+    - The `/compact` is consumed (cursor advanced) — it does NOT replay on future polls
+    - Other messages in the same batch are also consumed (cursor is a high-water mark — this is an accepted tradeoff for the narrow edge case of denied `/compact` + other messages in the same polling interval)
+    - No container is killed or interrupted
+14. From a **non-main group** (with `requiresTrigger` enabled) as a non-admin user, send bare `/compact` (no trigger prefix):
+15. Verify:
+    - No denial message is sent (trigger policy prevents untrusted bot responses)
+    - The `/compact` is consumed silently
+    - Note: in groups where `requiresTrigger` is `false`, a denial message IS sent because the sender is considered reachable
+16. After compaction, verify **no auto-compaction** behavior — only manual `/compact` triggers it
+
+### Validation on Fresh Clone
+
+```bash
+git clone <your-fork> /tmp/nanoclaw-test
+cd /tmp/nanoclaw-test
+claude  # then run /add-compact
+pnpm run build
+pnpm test
+./container/build.sh
+# Manual: send /compact from main group, verify compaction + continuation
+# Manual: send @<assistant> /compact from non-main as non-admin, verify denial
+# Manual: send @<assistant> /compact from non-main as admin, verify allowed
+# Manual: verify no auto-compaction behavior
+```
+
+## Security Constraints
+
+- **Main-group or trusted/admin sender only.** The main group is the user's private self-chat and is trusted (see `docs/SECURITY.md`). Non-main groups are untrusted — a careless or malicious user could wipe the agent's short-term memory. However, the device owner (`is_from_me`) is always trusted and can compact from any group.
+- **No auto-compaction.** This skill implements manual compaction only. Automatic threshold-based compaction is a separate concern and should be a separate skill.
+- **No config file.** NanoClaw's philosophy is customization through code changes, not configuration sprawl.
+- **Transcript archived before compaction.** The existing `PreCompact` hook in the agent-runner archives the full transcript to `conversations/` before the SDK compacts it.
+- **Session continues after compaction.** This is not a destructive reset. The conversation continues with summarized context.
+
+## What This Does NOT Do
+
+- No automatic compaction threshold (add separately if desired)
+- No `/clear` command (separate skill, separate semantics — `/clear` is a destructive reset)
+- No cross-group compaction (each group's session is isolated)
+- No changes to the container image, Dockerfile, or build script
+
+## Troubleshooting
+
+- **"Session commands require admin access"**: Only the device owner (`is_from_me`) or main-group senders can use `/compact`. Other users are denied.
+- **No compact_boundary in logs**: The SDK may not emit this event in all versions. Check the agent-runner logs for the warning message. Compaction may still have succeeded.
+- **Pre-compact failure**: If messages before `/compact` fail to process, the error message says "Failed to process messages before /compact." The cursor advances past sent output to prevent duplicates; `/compact` remains pending for the next attempt.

.claude/skills/add-dashboard/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: add-dashboard
+description: Add a monitoring dashboard to NanoClaw v2. Installs @nanoco/nanoclaw-dashboard and a pusher that sends periodic JSON snapshots.
+---
+
+# /add-dashboard — NanoClaw Dashboard
+
+Adds a local monitoring dashboard showing agent groups, sessions, channels, users, token usage, context windows, message activity, and real-time logs.
+
+## Architecture
+
+```
+NanoClaw (pusher)              Dashboard (npm package)
+┌──────────┐    POST JSON      ┌──────────────┐
+│ collects │ ────────────────→ │ /api/ingest  │
+│ DB data  │   every 60s       │ in-memory    │
+│ tails    │ ────────────────→ │ /api/logs/   │
+│ log file │   every 2s        │   push       │
+└──────────┘                   │ serves UI    │
+                               └──────────────┘
+```
+
+## Steps
+
+### 1. Install the npm package
+
+```bash
+pnpm install @nanoco/nanoclaw-dashboard
+```
+
+### 2. Copy the pusher module
+
+Copy the resource file into src:
+
+```
+.claude/skills/add-dashboard/resources/dashboard-pusher.ts → src/dashboard-pusher.ts
+```
+
+### 3. Add exports to src/db/index.ts
+
+Add these two export blocks if not already present:
+
+```typescript
+// After the messaging-groups exports, add:
+export {
+  getMessagingGroupsByAgentGroup,
+} from './messaging-groups.js';
+
+// Before the credentials exports, add:
+export {
+  createDestination,
+  getDestinations,
+  getDestinationByName,
+  getDestinationByTarget,
+  hasDestination,
+  deleteDestination,
+} from './agent-destinations.js';
+```
+
+### 4. Wire into src/index.ts
+
+Add the `readEnvFile` import at the top if not already present:
+
+```typescript
+import { readEnvFile } from './env.js';
+```
+
+Add after step 7 (OneCLI approval handler), before the `log.info('NanoClaw v2 running')` line:
+
+```typescript
+  // 8. Dashboard (optional)
+  const dashboardEnv = readEnvFile(['DASHBOARD_SECRET', 'DASHBOARD_PORT']);
+  const dashboardSecret = process.env.DASHBOARD_SECRET || dashboardEnv.DASHBOARD_SECRET;
+  const dashboardPort = parseInt(process.env.DASHBOARD_PORT || dashboardEnv.DASHBOARD_PORT || '3100', 10);
+  if (dashboardSecret) {
+    const { startDashboard } = await import('@nanoco/nanoclaw-dashboard');
+    const { startDashboardPusher } = await import('./dashboard-pusher.js');
+    startDashboard({ port: dashboardPort, secret: dashboardSecret });
+    startDashboardPusher({ port: dashboardPort, secret: dashboardSecret, intervalMs: 60000 });
+  } else {
+    log.info('Dashboard disabled (no DASHBOARD_SECRET)');
+  }
+```
+
+### 5. Add environment variables to .env
+
+```
+DASHBOARD_SECRET=<generate-a-random-secret>
+DASHBOARD_PORT=3100
+```
+
+Generate the secret: `node -e "console.log('nc-' + require('crypto').randomBytes(16).toString('hex'))"`
+
+### 6. Build and restart
+
+```bash
+pnpm run build
+systemctl --user restart nanoclaw   # Linux
+# or: launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
+```
+
+### 7. Verify
+
+```bash
+curl -s http://localhost:3100/api/status
+curl -s -H "Authorization: Bearer <secret>" http://localhost:3100/api/overview
+```
+
+Open `http://localhost:3100/dashboard` in a browser.
+
+## Dashboard Pages
+
+| Page | Shows |
+|------|-------|
+| Overview | Stats, token usage + cache hit rate, context windows, activity chart |
+| Agent Groups | Sessions, wirings, destinations, members, admins |
+| Sessions | Status, container state, context window usage bars |
+| Channels | Live/offline status, messaging groups, sender policies |
+| Messages | Per-session inbound/outbound messages |
+| Users | Privilege hierarchy: owner > admin > member |
+| Logs | Real-time log streaming with level filter |
+
+## Troubleshooting
+
+- **"No data yet"**: Wait 60s for first push, or check logs for push errors
+- **401 errors**: Verify `DASHBOARD_SECRET` matches in `.env`
+- **Port conflict**: Change `DASHBOARD_PORT` in `.env`
+- **No logs**: Check `logs/nanoclaw.log` exists
+
+## Removal
+
+```bash
+pnpm uninstall @nanoco/nanoclaw-dashboard
+rm src/dashboard-pusher.ts
+# Remove the dashboard block from src/index.ts
+# Remove DASHBOARD_SECRET and DASHBOARD_PORT from .env
+pnpm run build
+```

.claude/skills/add-dashboard/resources/dashboard-pusher.ts

@@ -0,0 +1,495 @@
+/**
+ * Dashboard pusher — collects NanoClaw state and POSTs a JSON
+ * snapshot to the dashboard's /api/ingest endpoint every interval.
+ */
+import fs from 'fs';
+import path from 'path';
+import http from 'http';
+import Database from 'better-sqlite3';
+
+import { getAllAgentGroups, getAgentGroup } from './db/agent-groups.js';
+import { getSessionsByAgentGroup } from './db/sessions.js';
+import { getAllMessagingGroups, getMessagingGroupAgents } from './db/messaging-groups.js';
+import { getDestinations } from './db/agent-destinations.js';
+import { getMembers } from './db/agent-group-members.js';
+import { getAllUsers, getUser } from './db/users.js';
+import { getUserRoles, getAdminsOfAgentGroup } from './db/user-roles.js';
+import { getUserDmsForUser } from './db/user-dms.js';
+import { getActiveAdapters, getRegisteredChannelNames } from './channels/channel-registry.js';
+import { DATA_DIR, ASSISTANT_NAME } from './config.js';
+import { getDb } from './db/connection.js';
+import { log } from './log.js';
+
+interface PusherConfig {
+  port: number;
+  secret: string;
+  intervalMs?: number;
+}
+
+let timer: ReturnType<typeof setInterval> | null = null;
+let logTimer: ReturnType<typeof setInterval> | null = null;
+let logOffset = 0;
+
+export function startDashboardPusher(config: PusherConfig): void {
+  const interval = config.intervalMs || 60000;
+
+  // Push immediately on start, then on interval
+  push(config).catch((err) => log.error('Dashboard push failed', { err }));
+  timer = setInterval(() => {
+    push(config).catch((err) => log.error('Dashboard push failed', { err }));
+  }, interval);
+
+  // Start log file tailing
+  startLogTail(config);
+
+  log.info('Dashboard pusher started', { intervalMs: interval });
+}
+
+export function stopDashboardPusher(): void {
+  if (timer) {
+    clearInterval(timer);
+    timer = null;
+  }
+  if (logTimer) {
+    clearInterval(logTimer);
+    logTimer = null;
+  }
+}
+
+/** Fire-and-forget POST to the dashboard. */
+function postJson(config: PusherConfig, urlPath: string, data: unknown): void {
+  const body = JSON.stringify(data);
+  const req = http.request({
+    hostname: '127.0.0.1',
+    port: config.port,
+    path: urlPath,
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Content-Length': Buffer.byteLength(body),
+      Authorization: `Bearer ${config.secret}`,
+    },
+  });
+  req.on('error', () => {});
+  req.write(body);
+  req.end();
+}
+
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+function startLogTail(config: PusherConfig): void {
+  const logFile = path.resolve(process.cwd(), 'logs', 'nanoclaw.log');
+  if (!fs.existsSync(logFile)) return;
+
+  // Send last 200 lines as backfill
+  try {
+    const allLines = fs.readFileSync(logFile, 'utf-8').split('\n').filter((l) => l.trim());
+    logOffset = fs.statSync(logFile).size;
+    const tail = allLines.slice(-200).map((l) => l.replace(ANSI_RE, ''));
+    if (tail.length > 0) postJson(config, '/api/logs/push', { lines: tail });
+  } catch { return; }
+
+  // Poll every 2s for new lines
+  logTimer = setInterval(() => {
+    try {
+      const stat = fs.statSync(logFile);
+      if (stat.size <= logOffset) { logOffset = stat.size; return; }
+      const buf = Buffer.alloc(stat.size - logOffset);
+      const fd = fs.openSync(logFile, 'r');
+      fs.readSync(fd, buf, 0, buf.length, logOffset);
+      fs.closeSync(fd);
+      logOffset = stat.size;
+      const lines = buf.toString().split('\n').filter((l) => l.trim()).map((l) => l.replace(ANSI_RE, ''));
+      if (lines.length > 0) postJson(config, '/api/logs/push', { lines });
+    } catch { /* ignore */ }
+  }, 2000);
+}
+
+async function push(config: PusherConfig): Promise<void> {
+  const snapshot = collectSnapshot();
+  postJson(config, '/api/ingest', snapshot);
+  log.debug('Dashboard snapshot pushed');
+}
+
+function collectSnapshot(): Record<string, unknown> {
+  return {
+    timestamp: new Date().toISOString(),
+    assistant_name: ASSISTANT_NAME,
+    uptime: Math.floor(process.uptime()),
+    agent_groups: collectAgentGroups(),
+    sessions: collectSessions(),
+    channels: collectChannels(),
+    users: collectUsers(),
+    tokens: collectTokens(),
+    context_windows: collectContextWindows(),
+    activity: collectActivity(),
+    messages: collectMessages(),
+  };
+}
+
+function collectAgentGroups() {
+  return getAllAgentGroups().map((g) => {
+    const sessions = getSessionsByAgentGroup(g.id);
+    const running = sessions.filter((s) => s.container_status === 'running' || s.container_status === 'idle');
+    const destinations = getDestinations(g.id);
+    const members = getMembers(g.id).map((m) => {
+      const user = getUser(m.user_id);
+      return { ...m, display_name: user?.display_name ?? null };
+    });
+    const admins = getAdminsOfAgentGroup(g.id).map((a) => {
+      const user = getUser(a.user_id);
+      return { ...a, display_name: user?.display_name ?? null };
+    });
+
+    // Wirings
+    const db = getDb();
+    const wirings = db
+      .prepare(
+        `SELECT mga.*, mg.channel_type, mg.platform_id, mg.name as mg_name, mg.is_group, mg.unknown_sender_policy
+         FROM messaging_group_agents mga
+         JOIN messaging_groups mg ON mg.id = mga.messaging_group_id
+         WHERE mga.agent_group_id = ?`,
+      )
+      .all(g.id) as Array<Record<string, unknown>>;
+
+    return {
+      id: g.id,
+      name: g.name,
+      folder: g.folder,
+      agent_provider: g.agent_provider,
+      container_config: g.container_config ? JSON.parse(g.container_config) : null,
+      sessionCount: sessions.length,
+      runningSessions: running.length,
+      wirings,
+      destinations,
+      members,
+      admins,
+      created_at: g.created_at,
+    };
+  });
+}
+
+function collectSessions() {
+  const db = getDb();
+  return db
+    .prepare(
+      `SELECT s.*, ag.name as agent_group_name, ag.folder as agent_group_folder,
+              mg.channel_type, mg.platform_id, mg.name as messaging_group_name
+       FROM sessions s
+       LEFT JOIN agent_groups ag ON ag.id = s.agent_group_id
+       LEFT JOIN messaging_groups mg ON mg.id = s.messaging_group_id
+       ORDER BY s.last_active DESC NULLS LAST`,
+    )
+    .all() as Array<Record<string, unknown>>;
+}
+
+function collectChannels() {
+  const messagingGroups = getAllMessagingGroups();
+  const liveAdapters = getActiveAdapters().map((a) => a.channelType);
+  const registeredChannels = getRegisteredChannelNames();
+
+  const byType: Record<string, { channelType: string; isLive: boolean; isRegistered: boolean; groups: unknown[] }> = {};
+
+  for (const mg of messagingGroups) {
+    if (!byType[mg.channel_type]) {
+      byType[mg.channel_type] = {
+        channelType: mg.channel_type,
+        isLive: liveAdapters.includes(mg.channel_type),
+        isRegistered: registeredChannels.includes(mg.channel_type),
+        groups: [],
+      };
+    }
+
+    const agents = getMessagingGroupAgents(mg.id).map((a) => {
+      const group = getAgentGroup(a.agent_group_id);
+      return { agent_group_id: a.agent_group_id, agent_group_name: group?.name ?? null, priority: a.priority };
+    });
+
+    byType[mg.channel_type].groups.push({
+      messagingGroup: {
+        id: mg.id,
+        platform_id: mg.platform_id,
+        name: mg.name,
+        is_group: mg.is_group,
+        unknown_sender_policy: (mg as unknown as Record<string, unknown>).unknown_sender_policy ?? 'strict',
+      },
+      agents,
+    });
+  }
+
+  // Include live adapters with no messaging groups
+  for (const ct of liveAdapters) {
+    if (!byType[ct]) {
+      byType[ct] = { channelType: ct, isLive: true, isRegistered: true, groups: [] };
+    }
+  }
+
+  return Object.values(byType).sort((a, b) => a.channelType.localeCompare(b.channelType));
+}
+
+function collectUsers() {
+  return getAllUsers().map((u) => {
+    const roles = getUserRoles(u.id);
+    const dms = getUserDmsForUser(u.id);
+
+    const db = getDb();
+    const memberships = db
+      .prepare(
+        `SELECT agm.agent_group_id, ag.name as agent_group_name
+         FROM agent_group_members agm
+         JOIN agent_groups ag ON ag.id = agm.agent_group_id
+         WHERE agm.user_id = ?`,
+      )
+      .all(u.id) as Array<Record<string, unknown>>;
+
+    let privilege = 'none';
+    if (roles.some((r) => r.role === 'owner')) privilege = 'owner';
+    else if (roles.some((r) => r.role === 'admin' && !r.agent_group_id)) privilege = 'global_admin';
+    else if (roles.some((r) => r.role === 'admin')) privilege = 'admin';
+    else if (memberships.length > 0) privilege = 'member';
+
+    return {
+      id: u.id,
+      kind: u.kind,
+      display_name: u.display_name,
+      privilege,
+      roles,
+      memberships,
+      dmChannels: dms.map((d) => ({ channel_type: d.channel_type })),
+      created_at: u.created_at,
+    };
+  });
+}
+
+function collectTokens() {
+  const sessionsDir = path.join(DATA_DIR, 'v2-sessions');
+  const allEntries: Array<{ model: string; inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheCreationTokens: number; agentGroupId: string }> = [];
+  const agentGroups = getAllAgentGroups();
+  const nameMap = new Map(agentGroups.map((g) => [g.id, g.name]));
+
+  if (fs.existsSync(sessionsDir)) {
+    for (const agDir of fs.readdirSync(sessionsDir).filter((d) => d.startsWith('ag-'))) {
+      const entries = scanJsonlTokens(path.join(sessionsDir, agDir));
+      allEntries.push(...entries.map((e) => ({ ...e, agentGroupId: agDir })));
+    }
+  }
+
+  const byModel: Record<string, { requests: number; inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheCreationTokens: number }> = {};
+  const byGroup: Record<string, { requests: number; inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheCreationTokens: number; name: string }> = {};
+  const totals = { requests: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 };
+
+  for (const e of allEntries) {
+    if (!byModel[e.model]) byModel[e.model] = { requests: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 };
+    byModel[e.model].requests++;
+    byModel[e.model].inputTokens += e.inputTokens;
+    byModel[e.model].outputTokens += e.outputTokens;
+    byModel[e.model].cacheReadTokens += e.cacheReadTokens;
+    byModel[e.model].cacheCreationTokens += e.cacheCreationTokens;
+
+    if (!byGroup[e.agentGroupId]) byGroup[e.agentGroupId] = { requests: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0, name: nameMap.get(e.agentGroupId) || e.agentGroupId };
+    byGroup[e.agentGroupId].requests++;
+    byGroup[e.agentGroupId].inputTokens += e.inputTokens;
+    byGroup[e.agentGroupId].outputTokens += e.outputTokens;
+    byGroup[e.agentGroupId].cacheReadTokens += e.cacheReadTokens;
+    byGroup[e.agentGroupId].cacheCreationTokens += e.cacheCreationTokens;
+
+    totals.requests++;
+    totals.inputTokens += e.inputTokens;
+    totals.outputTokens += e.outputTokens;
+    totals.cacheReadTokens += e.cacheReadTokens;
+    totals.cacheCreationTokens += e.cacheCreationTokens;
+  }
+
+  return { totals, byModel, byGroup };
+}
+
+function scanJsonlTokens(agentDir: string) {
+  const claudeDir = path.join(agentDir, '.claude-shared', 'projects');
+  if (!fs.existsSync(claudeDir)) return [];
+
+  const entries: Array<{ model: string; inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheCreationTokens: number }> = [];
+
+  const walk = (dir: string): void => {
+    try {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) walk(full);
+        else if (entry.name.endsWith('.jsonl')) {
+          try {
+            for (const line of fs.readFileSync(full, 'utf-8').split('\n')) {
+              if (!line.trim()) continue;
+              try {
+                const r = JSON.parse(line);
+                if (r.type === 'assistant' && r.message?.usage) {
+                  const u = r.message.usage;
+                  entries.push({
+                    model: r.message.model || 'unknown',
+                    inputTokens: u.input_tokens || 0,
+                    outputTokens: u.output_tokens || 0,
+                    cacheReadTokens: u.cache_read_input_tokens || 0,
+                    cacheCreationTokens: u.cache_creation_input_tokens || 0,
+                  });
+                }
+              } catch { /* skip line */ }
+            }
+          } catch { /* skip file */ }
+        }
+      }
+    } catch { /* skip dir */ }
+  };
+  walk(claudeDir);
+  return entries;
+}
+
+function collectContextWindows() {
+  const sessionsDir = path.join(DATA_DIR, 'v2-sessions');
+  if (!fs.existsSync(sessionsDir)) return [];
+
+  const results: unknown[] = [];
+  const agentGroups = getAllAgentGroups();
+  const nameMap = new Map(agentGroups.map((g) => [g.id, g.name]));
+
+  for (const agDir of fs.readdirSync(sessionsDir).filter((d) => d.startsWith('ag-'))) {
+    const claudeDir = path.join(sessionsDir, agDir, '.claude-shared', 'projects');
+    if (!fs.existsSync(claudeDir)) continue;
+
+    // Find most recent JSONL
+    const jsonlFiles: string[] = [];
+    const walk = (dir: string): void => {
+      try {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+          const full = path.join(dir, entry.name);
+          if (entry.isDirectory()) walk(full);
+          else if (entry.name.endsWith('.jsonl')) jsonlFiles.push(full);
+        }
+      } catch { /* skip */ }
+    };
+    walk(claudeDir);
+    if (jsonlFiles.length === 0) continue;
+
+    jsonlFiles.sort((a, b) => {
+      try { return fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs; } catch { return 0; }
+    });
+
+    // Read last assistant turn from newest file
+    const content = fs.readFileSync(jsonlFiles[0], 'utf-8');
+    const lines = content.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+      if (!lines[i].trim()) continue;
+      try {
+        const r = JSON.parse(lines[i]);
+        if (r.type === 'assistant' && r.message?.usage) {
+          const u = r.message.usage;
+          const model = r.message.model || 'unknown';
+          const ctx = (u.input_tokens || 0) + (u.cache_read_input_tokens || 0) + (u.cache_creation_input_tokens || 0);
+          const max = 200000;
+          results.push({
+            agentGroupId: agDir,
+            agentGroupName: nameMap.get(agDir),
+            sessionId: path.basename(jsonlFiles[0], '.jsonl'),
+            model,
+            contextTokens: ctx,
+            outputTokens: u.output_tokens || 0,
+            cacheReadTokens: u.cache_read_input_tokens || 0,
+            cacheCreationTokens: u.cache_creation_input_tokens || 0,
+            maxContext: max,
+            usagePercent: max > 0 ? Math.round((ctx / max) * 100) : 0,
+            timestamp: r.timestamp || '',
+          });
+          break;
+        }
+      } catch { /* skip */ }
+    }
+  }
+
+  return results;
+}
+
+function collectActivity() {
+  const now = Date.now();
+  const buckets: Record<string, { inbound: number; outbound: number }> = {};
+
+  for (let i = 0; i < 24; i++) {
+    const key = new Date(now - i * 3600000).toISOString().slice(0, 13);
+    buckets[key] = { inbound: 0, outbound: 0 };
+  }
+
+  const sessionsDir = path.join(DATA_DIR, 'v2-sessions');
+  if (!fs.existsSync(sessionsDir)) return toBucketArray(buckets);
+
+  const cutoff = new Date(now - 86400000).toISOString();
+
+  try {
+    for (const agDir of fs.readdirSync(sessionsDir).filter((d) => d.startsWith('ag-'))) {
+      const agPath = path.join(sessionsDir, agDir);
+      for (const sessDir of fs.readdirSync(agPath).filter((d) => d.startsWith('sess-'))) {
+        for (const [dbName, direction] of [['outbound.db', 'outbound'], ['inbound.db', 'inbound']] as const) {
+          const dbPath = path.join(agPath, sessDir, dbName);
+          if (!fs.existsSync(dbPath)) continue;
+          try {
+            const db = new Database(dbPath, { readonly: true });
+            const table = direction === 'outbound' ? 'messages_out' : 'messages_in';
+            const rows = db.prepare(`SELECT timestamp FROM ${table} WHERE timestamp > ?`).all(cutoff) as { timestamp: string }[];
+            for (const row of rows) {
+              const key = row.timestamp.slice(0, 13);
+              if (buckets[key]) buckets[key][direction]++;
+            }
+            db.close();
+          } catch { /* skip */ }
+        }
+      }
+    }
+  } catch { /* skip */ }
+
+  return toBucketArray(buckets);
+}
+
+function toBucketArray(buckets: Record<string, { inbound: number; outbound: number }>) {
+  return Object.entries(buckets)
+    .map(([hour, counts]) => ({ hour, ...counts }))
+    .sort((a, b) => a.hour.localeCompare(b.hour));
+}
+
+function collectMessages() {
+  const sessionsDir = path.join(DATA_DIR, 'v2-sessions');
+  if (!fs.existsSync(sessionsDir)) return [];
+
+  const results: Array<{ agentGroupId: string; sessionId: string; inbound: unknown[]; outbound: unknown[] }> = [];
+  const limit = 50;
+
+  try {
+    for (const agDir of fs.readdirSync(sessionsDir).filter((d) => d.startsWith('ag-'))) {
+      const agPath = path.join(sessionsDir, agDir);
+      for (const sessDir of fs.readdirSync(agPath).filter((d) => d.startsWith('sess-'))) {
+        const inbound: unknown[] = [];
+        const outbound: unknown[] = [];
+
+        const inDbPath = path.join(agPath, sessDir, 'inbound.db');
+        if (fs.existsSync(inDbPath)) {
+          try {
+            const db = new Database(inDbPath, { readonly: true });
+            const rows = db.prepare('SELECT * FROM messages_in ORDER BY seq DESC LIMIT ?').all(limit);
+            inbound.push(...(rows as unknown[]).reverse());
+            db.close();
+          } catch { /* skip */ }
+        }
+
+        const outDbPath = path.join(agPath, sessDir, 'outbound.db');
+        if (fs.existsSync(outDbPath)) {
+          try {
+            const db = new Database(outDbPath, { readonly: true });
+            const rows = db.prepare('SELECT * FROM messages_out ORDER BY seq DESC LIMIT ?').all(limit);
+            outbound.push(...(rows as unknown[]).reverse());
+            db.close();
+          } catch { /* skip */ }
+        }
+
+        if (inbound.length > 0 || outbound.length > 0) {
+          results.push({ agentGroupId: agDir, sessionId: sessDir, inbound, outbound });
+        }
+      }
+    }
+  } catch { /* skip */ }
+
+  return results;
+}

.claude/skills/add-discord-v2/REMOVE.md

@@ -0,0 +1,7 @@
+# Remove Discord
+
+1. Comment out `import './discord.js'` in `src/channels/index.ts`
+2. Remove `DISCORD_BOT_TOKEN` from `.env`
+3. Rebuild and restart
+
+No package to uninstall — Discord is built in.

.claude/skills/add-discord-v2/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: add-discord-v2
+description: Add Discord bot channel integration to NanoClaw v2 via Chat SDK.
+---
+
+# Add Discord Channel
+
+Adds Discord bot support to NanoClaw v2. Discord is built in — no adapter package to install.
+
+## Pre-flight
+
+Check if `src/channels/discord.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Credentials.
+
+## Install
+
+Discord support is bundled with NanoClaw — there is no separate package to install.
+
+### Enable the channel
+
+Uncomment the Discord import in `src/channels/index.ts`:
+
+```typescript
+import './discord.js';
+```
+
+### Build
+
+```bash
+pnpm run build
+```
+
+## Credentials
+
+### Create Discord Bot
+
+1. Go to the [Discord Developer Portal](https://discord.com/developers/applications)
+2. Click **New Application** and give it a name (e.g., "NanoClaw Assistant")
+3. From the **General Information** tab, copy the **Application ID** and **Public Key**
+4. Go to the **Bot** tab and click **Add Bot** if needed
+5. Copy the Bot Token (click **Reset Token** if you need a new one — you can only see it once)
+6. Under **Privileged Gateway Intents**, enable **Message Content Intent**
+7. Go to **OAuth2** > **URL Generator**:
+   - Scopes: select `bot`
+   - Bot Permissions: select `Send Messages`, `Read Message History`, `Add Reactions`, `Attach Files`, `Use Slash Commands`
+8. Copy the generated URL and open it in your browser to invite the bot to your server
+
+### Configure environment
+
+All three values are required — the adapter will fail to start without `DISCORD_PUBLIC_KEY` and `DISCORD_APPLICATION_ID`.
+
+Add to `.env`:
+
+```bash
+DISCORD_BOT_TOKEN=your-bot-token
+DISCORD_APPLICATION_ID=your-application-id
+DISCORD_PUBLIC_KEY=your-public-key
+```
+
+Sync to container: `mkdir -p data/env && cp .env data/env/env`
+
+## Next Steps
+
+If you're in the middle of `/setup`, return to the setup flow now.
+
+Otherwise, run `/manage-channels` to wire this channel to an agent group.
+
+## Channel Info
+
+- **type**: `discord`
+- **terminology**: Discord has "servers" (also called "guilds") containing "channels." Text channels start with #. The bot can also receive direct messages.
+- **how-to-find-id**: Enable Developer Mode in Discord (Settings > App Settings > Advanced > Developer Mode). Then right-click a server and select "Copy Server ID" for the guild ID, and right-click the text channel and select "Copy Channel ID." The platform ID format used in registration is `discord:{guildId}:{channelId}` — both IDs are required.
+- **supports-threads**: yes
+- **typical-use**: Interactive chat — server channels or direct messages
+- **default-isolation**: Same agent group for your personal server. Separate agent group for servers with different communities or where different members have different information boundaries.

.claude/skills/add-discord-v2/VERIFY.md

@@ -0,0 +1,3 @@
+# Verify Discord
+
+Send a message in a channel where the bot has access, or DM the bot directly. The bot should respond within a few seconds.

.claude/skills/add-discord/SKILL.md

@@ -1,12 +1,17 @@
+---
+name: add-discord
+description: Add Discord bot channel integration to NanoClaw.
+---
+
 # Add Discord Channel
 
-This skill adds Discord support to NanoClaw using the skills engine for deterministic code changes, then walks through interactive setup.
+This skill adds Discord support to NanoClaw, then walks through interactive setup.
 
 ## Phase 1: Pre-flight
 
 ### Check if already applied
 
-Read `.nanoclaw/state.yaml`. If `discord` is in `applied_skills`, skip to Phase 3 (Setup). The code changes are already in place.
+Check if `src/channels/discord.ts` exists. If it does, skip to Phase 3 (Setup). The code changes are already in place.
 
 ### Ask the user
 
@@ -18,39 +23,44 @@ If they have one, collect it now. If not, we'll create one in Phase 3.
 
 ## Phase 2: Apply Code Changes
 
-Run the skills engine to apply this skill's code package. The package files are in this directory alongside this SKILL.md.
-
-### Initialize skills system (if needed)
-
-If `.nanoclaw/` directory doesn't exist yet:
+### Ensure channel remote
 
 ```bash
-npx tsx scripts/apply-skill.ts --init
+git remote -v
 ```
 
-Or call `initSkillsSystem()` from `skills-engine/migrate.ts`.
-
-### Apply the skill
+If `discord` is missing, add it:
 
 ```bash
-npx tsx scripts/apply-skill.ts .claude/skills/add-discord
+git remote add discord https://github.com/qwibitai/nanoclaw-discord.git
 ```
 
-This deterministically:
-- Adds `src/channels/discord.ts` (DiscordChannel class with self-registration via `registerChannel`)
-- Adds `src/channels/discord.test.ts` (unit tests with discord.js mock)
-- Appends `import './discord.js'` to the channel barrel file `src/channels/index.ts`
-- Installs the `discord.js` npm dependency
-- Records the application in `.nanoclaw/state.yaml`
+### Merge the skill branch
 
-If the apply reports merge conflicts, read the intent file:
-- `modify/src/channels/index.ts.intent.md` — what changed and invariants
+```bash
+git fetch discord main
+git merge discord/main || {
+  git checkout --theirs pnpm-lock.yaml
+  git add pnpm-lock.yaml
+  git merge --continue
+}
+```
+
+This merges in:
+- `src/channels/discord.ts` (DiscordChannel class with self-registration via `registerChannel`)
+- `src/channels/discord.test.ts` (unit tests with discord.js mock)
+- `import './discord.js'` appended to the channel barrel file `src/channels/index.ts`
+- `discord.js` npm dependency in `package.json`
+- `DISCORD_BOT_TOKEN` in `.env.example`
+
+If the merge reports conflicts, resolve them by reading the conflicted files and understanding the intent of both sides.
 
 ### Validate code changes
 
 ```bash
-npm test
-npm run build
+pnpm install
+pnpm run build
+pnpm exec vitest run src/channels/discord.test.ts
 ```
 
 All tests must pass (including the new Discord tests) and build must be clean before proceeding.
@@ -98,7 +108,7 @@ The container reads environment from `data/env/env`, not `.env` directly.
 ### Build and restart
 
 ```bash
-npm run build
+pnpm run build
 launchctl kickstart -k gui/$(id -u)/com.nanoclaw
 ```
 
@@ -120,31 +130,18 @@ Wait for the user to provide the channel ID (format: `dc:1234567890123456`).
 
 ### Register the channel
 
-Use the IPC register flow or register directly. The channel ID, name, and folder name are needed.
+The channel ID, name, and folder name are needed. Use `pnpm exec tsx setup/index.ts --step register` with the appropriate flags.
 
 For a main channel (responds to all messages):
 
-```typescript
-registerGroup("dc:<channel-id>", {
-  name: "<server-name> #<channel-name>",
-  folder: "discord_main",
-  trigger: `@${ASSISTANT_NAME}`,
-  added_at: new Date().toISOString(),
-  requiresTrigger: false,
-  isMain: true,
-});
+```bash
+pnpm exec tsx setup/index.ts --step register -- --jid "dc:<channel-id>" --name "<server-name> #<channel-name>" --folder "discord_main" --trigger "@${ASSISTANT_NAME}" --channel discord --no-trigger-required --is-main
 ```
 
 For additional channels (trigger-only):
 
-```typescript
-registerGroup("dc:<channel-id>", {
-  name: "<server-name> #<channel-name>",
-  folder: "discord_<channel-name>",
-  trigger: `@${ASSISTANT_NAME}`,
-  added_at: new Date().toISOString(),
-  requiresTrigger: true,
-});
+```bash
+pnpm exec tsx setup/index.ts --step register -- --jid "dc:<channel-id>" --name "<server-name> #<channel-name>" --folder "discord_<channel-name>" --trigger "@${ASSISTANT_NAME}" --channel discord
 ```
 
 ## Phase 5: Verify

.claude/skills/add-discord/add/src/channels/discord.test.ts

@@ -1,776 +0,0 @@
-import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
-
-// --- Mocks ---
-
-// Mock registry (registerChannel runs at import time)
-vi.mock('./registry.js', () => ({ registerChannel: vi.fn() }));
-
-// Mock env reader (used by the factory, not needed in unit tests)
-vi.mock('../env.js', () => ({ readEnvFile: vi.fn(() => ({})) }));
-
-// Mock config
-vi.mock('../config.js', () => ({
-  ASSISTANT_NAME: 'Andy',
-  TRIGGER_PATTERN: /^@Andy\b/i,
-}));
-
-// Mock logger
-vi.mock('../logger.js', () => ({
-  logger: {
-    debug: vi.fn(),
-    info: vi.fn(),
-    warn: vi.fn(),
-    error: vi.fn(),
-  },
-}));
-
-// --- discord.js mock ---
-
-type Handler = (...args: any[]) => any;
-
-const clientRef = vi.hoisted(() => ({ current: null as any }));
-
-vi.mock('discord.js', () => {
-  const Events = {
-    MessageCreate: 'messageCreate',
-    ClientReady: 'ready',
-    Error: 'error',
-  };
-
-  const GatewayIntentBits = {
-    Guilds: 1,
-    GuildMessages: 2,
-    MessageContent: 4,
-    DirectMessages: 8,
-  };
-
-  class MockClient {
-    eventHandlers = new Map<string, Handler[]>();
-    user: any = { id: '999888777', tag: 'Andy#1234' };
-    private _ready = false;
-
-    constructor(_opts: any) {
-      clientRef.current = this;
-    }
-
-    on(event: string, handler: Handler) {
-      const existing = this.eventHandlers.get(event) || [];
-      existing.push(handler);
-      this.eventHandlers.set(event, existing);
-      return this;
-    }
-
-    once(event: string, handler: Handler) {
-      return this.on(event, handler);
-    }
-
-    async login(_token: string) {
-      this._ready = true;
-      // Fire the ready event
-      const readyHandlers = this.eventHandlers.get('ready') || [];
-      for (const h of readyHandlers) {
-        h({ user: this.user });
-      }
-    }
-
-    isReady() {
-      return this._ready;
-    }
-
-    channels = {
-      fetch: vi.fn().mockResolvedValue({
-        send: vi.fn().mockResolvedValue(undefined),
-        sendTyping: vi.fn().mockResolvedValue(undefined),
-      }),
-    };
-
-    destroy() {
-      this._ready = false;
-    }
-  }
-
-  // Mock TextChannel type
-  class TextChannel {}
-
-  return {
-    Client: MockClient,
-    Events,
-    GatewayIntentBits,
-    TextChannel,
-  };
-});
-
-import { DiscordChannel, DiscordChannelOpts } from './discord.js';
-
-// --- Test helpers ---
-
-function createTestOpts(
-  overrides?: Partial<DiscordChannelOpts>,
-): DiscordChannelOpts {
-  return {
-    onMessage: vi.fn(),
-    onChatMetadata: vi.fn(),
-    registeredGroups: vi.fn(() => ({
-      'dc:1234567890123456': {
-        name: 'Test Server #general',
-        folder: 'test-server',
-        trigger: '@Andy',
-        added_at: '2024-01-01T00:00:00.000Z',
-      },
-    })),
-    ...overrides,
-  };
-}
-
-function createMessage(overrides: {
-  channelId?: string;
-  content?: string;
-  authorId?: string;
-  authorUsername?: string;
-  authorDisplayName?: string;
-  memberDisplayName?: string;
-  isBot?: boolean;
-  guildName?: string;
-  channelName?: string;
-  messageId?: string;
-  createdAt?: Date;
-  attachments?: Map<string, any>;
-  reference?: { messageId?: string };
-  mentionsBotId?: boolean;
-}) {
-  const channelId = overrides.channelId ?? '1234567890123456';
-  const authorId = overrides.authorId ?? '55512345';
-  const botId = '999888777'; // matches mock client user id
-
-  const mentionsMap = new Map();
-  if (overrides.mentionsBotId) {
-    mentionsMap.set(botId, { id: botId });
-  }
-
-  return {
-    channelId,
-    id: overrides.messageId ?? 'msg_001',
-    content: overrides.content ?? 'Hello everyone',
-    createdAt: overrides.createdAt ?? new Date('2024-01-01T00:00:00.000Z'),
-    author: {
-      id: authorId,
-      username: overrides.authorUsername ?? 'alice',
-      displayName: overrides.authorDisplayName ?? 'Alice',
-      bot: overrides.isBot ?? false,
-    },
-    member: overrides.memberDisplayName
-      ? { displayName: overrides.memberDisplayName }
-      : null,
-    guild: overrides.guildName
-      ? { name: overrides.guildName }
-      : null,
-    channel: {
-      name: overrides.channelName ?? 'general',
-      messages: {
-        fetch: vi.fn().mockResolvedValue({
-          author: { username: 'Bob', displayName: 'Bob' },
-          member: { displayName: 'Bob' },
-        }),
-      },
-    },
-    mentions: {
-      users: mentionsMap,
-    },
-    attachments: overrides.attachments ?? new Map(),
-    reference: overrides.reference ?? null,
-  };
-}
-
-function currentClient() {
-  return clientRef.current;
-}
-
-async function triggerMessage(message: any) {
-  const handlers = currentClient().eventHandlers.get('messageCreate') || [];
-  for (const h of handlers) await h(message);
-}
-
-// --- Tests ---
-
-describe('DiscordChannel', () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  // --- Connection lifecycle ---
-
-  describe('connection lifecycle', () => {
-    it('resolves connect() when client is ready', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-
-      await channel.connect();
-
-      expect(channel.isConnected()).toBe(true);
-    });
-
-    it('registers message handlers on connect', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-
-      await channel.connect();
-
-      expect(currentClient().eventHandlers.has('messageCreate')).toBe(true);
-      expect(currentClient().eventHandlers.has('error')).toBe(true);
-      expect(currentClient().eventHandlers.has('ready')).toBe(true);
-    });
-
-    it('disconnects cleanly', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-
-      await channel.connect();
-      expect(channel.isConnected()).toBe(true);
-
-      await channel.disconnect();
-      expect(channel.isConnected()).toBe(false);
-    });
-
-    it('isConnected() returns false before connect', () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-
-      expect(channel.isConnected()).toBe(false);
-    });
-  });
-
-  // --- Text message handling ---
-
-  describe('text message handling', () => {
-    it('delivers message for registered channel', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-      await channel.connect();
-
-      const msg = createMessage({
-        content: 'Hello everyone',
-        guildName: 'Test Server',
-        channelName: 'general',
-      });
-      await triggerMessage(msg);
-
-      expect(opts.onChatMetadata).toHaveBeenCalledWith(
-        'dc:1234567890123456',
-        expect.any(String),
-        'Test Server #general',
-        'discord',
-        true,
-      );
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'dc:1234567890123456',
-        expect.objectContaining({
-          id: 'msg_001',
-          chat_jid: 'dc:1234567890123456',
-          sender: '55512345',
-          sender_name: 'Alice',
-          content: 'Hello everyone',
-          is_from_me: false,
-        }),
-      );
-    });
-
-    it('only emits metadata for unregistered channels', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-      await channel.connect();
-
-      const msg = createMessage({
-        channelId: '9999999999999999',
-        content: 'Unknown channel',
-        guildName: 'Other Server',
-      });
-      await triggerMessage(msg);
-
-      expect(opts.onChatMetadata).toHaveBeenCalledWith(
-        'dc:9999999999999999',
-        expect.any(String),
-        expect.any(String),
-        'discord',
-        true,
-      );
-      expect(opts.onMessage).not.toHaveBeenCalled();
-    });
-
-    it('ignores bot messages', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-      await channel.connect();
-
-      const msg = createMessage({ isBot: true, content: 'I am a bot' });
-      await triggerMessage(msg);
-
-      expect(opts.onMessage).not.toHaveBeenCalled();
-      expect(opts.onChatMetadata).not.toHaveBeenCalled();
-    });
-
-    it('uses member displayName when available (server nickname)', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-      await channel.connect();
-
-      const msg = createMessage({
-        content: 'Hi',
-        memberDisplayName: 'Alice Nickname',
-        authorDisplayName: 'Alice Global',
-        guildName: 'Server',
-      });
-      await triggerMessage(msg);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'dc:1234567890123456',
-        expect.objectContaining({ sender_name: 'Alice Nickname' }),
-      );
-    });
-
-    it('falls back to author displayName when no member', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-      await channel.connect();
-
-      const msg = createMessage({
-        content: 'Hi',
-        memberDisplayName: undefined,
-        authorDisplayName: 'Alice Global',
-        guildName: 'Server',
-      });
-      await triggerMessage(msg);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'dc:1234567890123456',
-        expect.objectContaining({ sender_name: 'Alice Global' }),
-      );
-    });
-
-    it('uses sender name for DM chats (no guild)', async () => {
-      const opts = createTestOpts({
-        registeredGroups: vi.fn(() => ({
-          'dc:1234567890123456': {
-            name: 'DM',
-            folder: 'dm',
-            trigger: '@Andy',
-            added_at: '2024-01-01T00:00:00.000Z',
-          },
-        })),
-      });
-      const channel = new DiscordChannel('test-token', opts);
-      await channel.connect();
-
-      const msg = createMessage({
-        content: 'Hello',
-        guildName: undefined,
-        authorDisplayName: 'Alice',
-      });
-      await triggerMessage(msg);
-
-      expect(opts.onChatMetadata).toHaveBeenCalledWith(
-        'dc:1234567890123456',
-        expect.any(String),
-        'Alice',
-        'discord',
-        false,
-      );
-    });
-
-    it('uses guild name + channel name for server messages', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-      await channel.connect();
-
-      const msg = createMessage({
-        content: 'Hello',
-        guildName: 'My Server',
-        channelName: 'bot-chat',
-      });
-      await triggerMessage(msg);
-
-      expect(opts.onChatMetadata).toHaveBeenCalledWith(
-        'dc:1234567890123456',
-        expect.any(String),
-        'My Server #bot-chat',
-        'discord',
-        true,
-      );
-    });
-  });
-
-  // --- @mention translation ---
-
-  describe('@mention translation', () => {
-    it('translates <@botId> mention to trigger format', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-      await channel.connect();
-
-      const msg = createMessage({
-        content: '<@999888777> what time is it?',
-        mentionsBotId: true,
-        guildName: 'Server',
-      });
-      await triggerMessage(msg);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'dc:1234567890123456',
-        expect.objectContaining({
-          content: '@Andy what time is it?',
-        }),
-      );
-    });
-
-    it('does not translate if message already matches trigger', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-      await channel.connect();
-
-      const msg = createMessage({
-        content: '@Andy hello <@999888777>',
-        mentionsBotId: true,
-        guildName: 'Server',
-      });
-      await triggerMessage(msg);
-
-      // Should NOT prepend @Andy — already starts with trigger
-      // But the <@botId> should still be stripped
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'dc:1234567890123456',
-        expect.objectContaining({
-          content: '@Andy hello',
-        }),
-      );
-    });
-
-    it('does not translate when bot is not mentioned', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-      await channel.connect();
-
-      const msg = createMessage({
-        content: 'hello everyone',
-        guildName: 'Server',
-      });
-      await triggerMessage(msg);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'dc:1234567890123456',
-        expect.objectContaining({
-          content: 'hello everyone',
-        }),
-      );
-    });
-
-    it('handles <@!botId> (nickname mention format)', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-      await channel.connect();
-
-      const msg = createMessage({
-        content: '<@!999888777> check this',
-        mentionsBotId: true,
-        guildName: 'Server',
-      });
-      await triggerMessage(msg);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'dc:1234567890123456',
-        expect.objectContaining({
-          content: '@Andy check this',
-        }),
-      );
-    });
-  });
-
-  // --- Attachments ---
-
-  describe('attachments', () => {
-    it('stores image attachment with placeholder', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-      await channel.connect();
-
-      const attachments = new Map([
-        ['att1', { name: 'photo.png', contentType: 'image/png' }],
-      ]);
-      const msg = createMessage({
-        content: '',
-        attachments,
-        guildName: 'Server',
-      });
-      await triggerMessage(msg);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'dc:1234567890123456',
-        expect.objectContaining({
-          content: '[Image: photo.png]',
-        }),
-      );
-    });
-
-    it('stores video attachment with placeholder', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-      await channel.connect();
-
-      const attachments = new Map([
-        ['att1', { name: 'clip.mp4', contentType: 'video/mp4' }],
-      ]);
-      const msg = createMessage({
-        content: '',
-        attachments,
-        guildName: 'Server',
-      });
-      await triggerMessage(msg);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'dc:1234567890123456',
-        expect.objectContaining({
-          content: '[Video: clip.mp4]',
-        }),
-      );
-    });
-
-    it('stores file attachment with placeholder', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-      await channel.connect();
-
-      const attachments = new Map([
-        ['att1', { name: 'report.pdf', contentType: 'application/pdf' }],
-      ]);
-      const msg = createMessage({
-        content: '',
-        attachments,
-        guildName: 'Server',
-      });
-      await triggerMessage(msg);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'dc:1234567890123456',
-        expect.objectContaining({
-          content: '[File: report.pdf]',
-        }),
-      );
-    });
-
-    it('includes text content with attachments', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-      await channel.connect();
-
-      const attachments = new Map([
-        ['att1', { name: 'photo.jpg', contentType: 'image/jpeg' }],
-      ]);
-      const msg = createMessage({
-        content: 'Check this out',
-        attachments,
-        guildName: 'Server',
-      });
-      await triggerMessage(msg);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'dc:1234567890123456',
-        expect.objectContaining({
-          content: 'Check this out\n[Image: photo.jpg]',
-        }),
-      );
-    });
-
-    it('handles multiple attachments', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-      await channel.connect();
-
-      const attachments = new Map([
-        ['att1', { name: 'a.png', contentType: 'image/png' }],
-        ['att2', { name: 'b.txt', contentType: 'text/plain' }],
-      ]);
-      const msg = createMessage({
-        content: '',
-        attachments,
-        guildName: 'Server',
-      });
-      await triggerMessage(msg);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'dc:1234567890123456',
-        expect.objectContaining({
-          content: '[Image: a.png]\n[File: b.txt]',
-        }),
-      );
-    });
-  });
-
-  // --- Reply context ---
-
-  describe('reply context', () => {
-    it('includes reply author in content', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-      await channel.connect();
-
-      const msg = createMessage({
-        content: 'I agree with that',
-        reference: { messageId: 'original_msg_id' },
-        guildName: 'Server',
-      });
-      await triggerMessage(msg);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'dc:1234567890123456',
-        expect.objectContaining({
-          content: '[Reply to Bob] I agree with that',
-        }),
-      );
-    });
-  });
-
-  // --- sendMessage ---
-
-  describe('sendMessage', () => {
-    it('sends message via channel', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-      await channel.connect();
-
-      await channel.sendMessage('dc:1234567890123456', 'Hello');
-
-      const fetchedChannel = await currentClient().channels.fetch('1234567890123456');
-      expect(currentClient().channels.fetch).toHaveBeenCalledWith('1234567890123456');
-    });
-
-    it('strips dc: prefix from JID', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-      await channel.connect();
-
-      await channel.sendMessage('dc:9876543210', 'Test');
-
-      expect(currentClient().channels.fetch).toHaveBeenCalledWith('9876543210');
-    });
-
-    it('handles send failure gracefully', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-      await channel.connect();
-
-      currentClient().channels.fetch.mockRejectedValueOnce(
-        new Error('Channel not found'),
-      );
-
-      // Should not throw
-      await expect(
-        channel.sendMessage('dc:1234567890123456', 'Will fail'),
-      ).resolves.toBeUndefined();
-    });
-
-    it('does nothing when client is not initialized', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-
-      // Don't connect — client is null
-      await channel.sendMessage('dc:1234567890123456', 'No client');
-
-      // No error, no API call
-    });
-
-    it('splits messages exceeding 2000 characters', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-      await channel.connect();
-
-      const mockChannel = {
-        send: vi.fn().mockResolvedValue(undefined),
-        sendTyping: vi.fn(),
-      };
-      currentClient().channels.fetch.mockResolvedValue(mockChannel);
-
-      const longText = 'x'.repeat(3000);
-      await channel.sendMessage('dc:1234567890123456', longText);
-
-      expect(mockChannel.send).toHaveBeenCalledTimes(2);
-      expect(mockChannel.send).toHaveBeenNthCalledWith(1, 'x'.repeat(2000));
-      expect(mockChannel.send).toHaveBeenNthCalledWith(2, 'x'.repeat(1000));
-    });
-  });
-
-  // --- ownsJid ---
-
-  describe('ownsJid', () => {
-    it('owns dc: JIDs', () => {
-      const channel = new DiscordChannel('test-token', createTestOpts());
-      expect(channel.ownsJid('dc:1234567890123456')).toBe(true);
-    });
-
-    it('does not own WhatsApp group JIDs', () => {
-      const channel = new DiscordChannel('test-token', createTestOpts());
-      expect(channel.ownsJid('12345@g.us')).toBe(false);
-    });
-
-    it('does not own Telegram JIDs', () => {
-      const channel = new DiscordChannel('test-token', createTestOpts());
-      expect(channel.ownsJid('tg:123456789')).toBe(false);
-    });
-
-    it('does not own unknown JID formats', () => {
-      const channel = new DiscordChannel('test-token', createTestOpts());
-      expect(channel.ownsJid('random-string')).toBe(false);
-    });
-  });
-
-  // --- setTyping ---
-
-  describe('setTyping', () => {
-    it('sends typing indicator when isTyping is true', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-      await channel.connect();
-
-      const mockChannel = {
-        send: vi.fn(),
-        sendTyping: vi.fn().mockResolvedValue(undefined),
-      };
-      currentClient().channels.fetch.mockResolvedValue(mockChannel);
-
-      await channel.setTyping('dc:1234567890123456', true);
-
-      expect(mockChannel.sendTyping).toHaveBeenCalled();
-    });
-
-    it('does nothing when isTyping is false', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-      await channel.connect();
-
-      await channel.setTyping('dc:1234567890123456', false);
-
-      // channels.fetch should NOT be called
-      expect(currentClient().channels.fetch).not.toHaveBeenCalled();
-    });
-
-    it('does nothing when client is not initialized', async () => {
-      const opts = createTestOpts();
-      const channel = new DiscordChannel('test-token', opts);
-
-      // Don't connect
-      await channel.setTyping('dc:1234567890123456', true);
-
-      // No error
-    });
-  });
-
-  // --- Channel properties ---
-
-  describe('channel properties', () => {
-    it('has name "discord"', () => {
-      const channel = new DiscordChannel('test-token', createTestOpts());
-      expect(channel.name).toBe('discord');
-    });
-  });
-});

.claude/skills/add-discord/add/src/channels/discord.ts

@@ -1,250 +0,0 @@
-import { Client, Events, GatewayIntentBits, Message, TextChannel } from 'discord.js';
-
-import { ASSISTANT_NAME, TRIGGER_PATTERN } from '../config.js';
-import { readEnvFile } from '../env.js';
-import { logger } from '../logger.js';
-import { registerChannel, ChannelOpts } from './registry.js';
-import {
-  Channel,
-  OnChatMetadata,
-  OnInboundMessage,
-  RegisteredGroup,
-} from '../types.js';
-
-export interface DiscordChannelOpts {
-  onMessage: OnInboundMessage;
-  onChatMetadata: OnChatMetadata;
-  registeredGroups: () => Record<string, RegisteredGroup>;
-}
-
-export class DiscordChannel implements Channel {
-  name = 'discord';
-
-  private client: Client | null = null;
-  private opts: DiscordChannelOpts;
-  private botToken: string;
-
-  constructor(botToken: string, opts: DiscordChannelOpts) {
-    this.botToken = botToken;
-    this.opts = opts;
-  }
-
-  async connect(): Promise<void> {
-    this.client = new Client({
-      intents: [
-        GatewayIntentBits.Guilds,
-        GatewayIntentBits.GuildMessages,
-        GatewayIntentBits.MessageContent,
-        GatewayIntentBits.DirectMessages,
-      ],
-    });
-
-    this.client.on(Events.MessageCreate, async (message: Message) => {
-      // Ignore bot messages (including own)
-      if (message.author.bot) return;
-
-      const channelId = message.channelId;
-      const chatJid = `dc:${channelId}`;
-      let content = message.content;
-      const timestamp = message.createdAt.toISOString();
-      const senderName =
-        message.member?.displayName ||
-        message.author.displayName ||
-        message.author.username;
-      const sender = message.author.id;
-      const msgId = message.id;
-
-      // Determine chat name
-      let chatName: string;
-      if (message.guild) {
-        const textChannel = message.channel as TextChannel;
-        chatName = `${message.guild.name} #${textChannel.name}`;
-      } else {
-        chatName = senderName;
-      }
-
-      // Translate Discord @bot mentions into TRIGGER_PATTERN format.
-      // Discord mentions look like <@botUserId> — these won't match
-      // TRIGGER_PATTERN (e.g., ^@Andy\b), so we prepend the trigger
-      // when the bot is @mentioned.
-      if (this.client?.user) {
-        const botId = this.client.user.id;
-        const isBotMentioned =
-          message.mentions.users.has(botId) ||
-          content.includes(`<@${botId}>`) ||
-          content.includes(`<@!${botId}>`);
-
-        if (isBotMentioned) {
-          // Strip the <@botId> mention to avoid visual clutter
-          content = content
-            .replace(new RegExp(`<@!?${botId}>`, 'g'), '')
-            .trim();
-          // Prepend trigger if not already present
-          if (!TRIGGER_PATTERN.test(content)) {
-            content = `@${ASSISTANT_NAME} ${content}`;
-          }
-        }
-      }
-
-      // Handle attachments — store placeholders so the agent knows something was sent
-      if (message.attachments.size > 0) {
-        const attachmentDescriptions = [...message.attachments.values()].map((att) => {
-          const contentType = att.contentType || '';
-          if (contentType.startsWith('image/')) {
-            return `[Image: ${att.name || 'image'}]`;
-          } else if (contentType.startsWith('video/')) {
-            return `[Video: ${att.name || 'video'}]`;
-          } else if (contentType.startsWith('audio/')) {
-            return `[Audio: ${att.name || 'audio'}]`;
-          } else {
-            return `[File: ${att.name || 'file'}]`;
-          }
-        });
-        if (content) {
-          content = `${content}\n${attachmentDescriptions.join('\n')}`;
-        } else {
-          content = attachmentDescriptions.join('\n');
-        }
-      }
-
-      // Handle reply context — include who the user is replying to
-      if (message.reference?.messageId) {
-        try {
-          const repliedTo = await message.channel.messages.fetch(
-            message.reference.messageId,
-          );
-          const replyAuthor =
-            repliedTo.member?.displayName ||
-            repliedTo.author.displayName ||
-            repliedTo.author.username;
-          content = `[Reply to ${replyAuthor}] ${content}`;
-        } catch {
-          // Referenced message may have been deleted
-        }
-      }
-
-      // Store chat metadata for discovery
-      const isGroup = message.guild !== null;
-      this.opts.onChatMetadata(chatJid, timestamp, chatName, 'discord', isGroup);
-
-      // Only deliver full message for registered groups
-      const group = this.opts.registeredGroups()[chatJid];
-      if (!group) {
-        logger.debug(
-          { chatJid, chatName },
-          'Message from unregistered Discord channel',
-        );
-        return;
-      }
-
-      // Deliver message — startMessageLoop() will pick it up
-      this.opts.onMessage(chatJid, {
-        id: msgId,
-        chat_jid: chatJid,
-        sender,
-        sender_name: senderName,
-        content,
-        timestamp,
-        is_from_me: false,
-      });
-
-      logger.info(
-        { chatJid, chatName, sender: senderName },
-        'Discord message stored',
-      );
-    });
-
-    // Handle errors gracefully
-    this.client.on(Events.Error, (err) => {
-      logger.error({ err: err.message }, 'Discord client error');
-    });
-
-    return new Promise<void>((resolve) => {
-      this.client!.once(Events.ClientReady, (readyClient) => {
-        logger.info(
-          { username: readyClient.user.tag, id: readyClient.user.id },
-          'Discord bot connected',
-        );
-        console.log(`\n  Discord bot: ${readyClient.user.tag}`);
-        console.log(
-          `  Use /chatid command or check channel IDs in Discord settings\n`,
-        );
-        resolve();
-      });
-
-      this.client!.login(this.botToken);
-    });
-  }
-
-  async sendMessage(jid: string, text: string): Promise<void> {
-    if (!this.client) {
-      logger.warn('Discord client not initialized');
-      return;
-    }
-
-    try {
-      const channelId = jid.replace(/^dc:/, '');
-      const channel = await this.client.channels.fetch(channelId);
-
-      if (!channel || !('send' in channel)) {
-        logger.warn({ jid }, 'Discord channel not found or not text-based');
-        return;
-      }
-
-      const textChannel = channel as TextChannel;
-
-      // Discord has a 2000 character limit per message — split if needed
-      const MAX_LENGTH = 2000;
-      if (text.length <= MAX_LENGTH) {
-        await textChannel.send(text);
-      } else {
-        for (let i = 0; i < text.length; i += MAX_LENGTH) {
-          await textChannel.send(text.slice(i, i + MAX_LENGTH));
-        }
-      }
-      logger.info({ jid, length: text.length }, 'Discord message sent');
-    } catch (err) {
-      logger.error({ jid, err }, 'Failed to send Discord message');
-    }
-  }
-
-  isConnected(): boolean {
-    return this.client !== null && this.client.isReady();
-  }
-
-  ownsJid(jid: string): boolean {
-    return jid.startsWith('dc:');
-  }
-
-  async disconnect(): Promise<void> {
-    if (this.client) {
-      this.client.destroy();
-      this.client = null;
-      logger.info('Discord bot stopped');
-    }
-  }
-
-  async setTyping(jid: string, isTyping: boolean): Promise<void> {
-    if (!this.client || !isTyping) return;
-    try {
-      const channelId = jid.replace(/^dc:/, '');
-      const channel = await this.client.channels.fetch(channelId);
-      if (channel && 'sendTyping' in channel) {
-        await (channel as TextChannel).sendTyping();
-      }
-    } catch (err) {
-      logger.debug({ jid, err }, 'Failed to send Discord typing indicator');
-    }
-  }
-}
-
-registerChannel('discord', (opts: ChannelOpts) => {
-  const envVars = readEnvFile(['DISCORD_BOT_TOKEN']);
-  const token =
-    process.env.DISCORD_BOT_TOKEN || envVars.DISCORD_BOT_TOKEN || '';
-  if (!token) {
-    logger.warn('Discord: DISCORD_BOT_TOKEN not set');
-    return null;
-  }
-  return new DiscordChannel(token, opts);
-});

.claude/skills/add-discord/manifest.yaml

@@ -1,17 +0,0 @@
-skill: discord
-version: 1.0.0
-description: "Discord Bot integration via discord.js"
-core_version: 0.1.0
-adds:
-  - src/channels/discord.ts
-  - src/channels/discord.test.ts
-modifies:
-  - src/channels/index.ts
-structured:
-  npm_dependencies:
-    discord.js: "^14.18.0"
-  env_additions:
-    - DISCORD_BOT_TOKEN
-conflicts: []
-depends: []
-test: "npx vitest run src/channels/discord.test.ts"

.claude/skills/add-discord/modify/src/channels/index.ts

@@ -1,13 +0,0 @@
-// Channel self-registration barrel file.
-// Each import triggers the channel module's registerChannel() call.
-
-// discord
-import './discord.js';
-
-// gmail
-
-// slack
-
-// telegram
-
-// whatsapp

.claude/skills/add-discord/modify/src/channels/index.ts.intent.md

@@ -1,7 +0,0 @@
-# Intent: Add Discord channel import
-
-Add `import './discord.js';` to the channel barrel file so the Discord
-module self-registers with the channel registry on startup.
-
-This is an append-only change — existing import lines for other channels
-must be preserved.

.claude/skills/add-discord/tests/discord.test.ts

@@ -1,69 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import fs from 'fs';
-import path from 'path';
-
-describe('discord skill package', () => {
-  const skillDir = path.resolve(__dirname, '..');
-
-  it('has a valid manifest', () => {
-    const manifestPath = path.join(skillDir, 'manifest.yaml');
-    expect(fs.existsSync(manifestPath)).toBe(true);
-
-    const content = fs.readFileSync(manifestPath, 'utf-8');
-    expect(content).toContain('skill: discord');
-    expect(content).toContain('version: 1.0.0');
-    expect(content).toContain('discord.js');
-  });
-
-  it('has all files declared in adds', () => {
-    const channelFile = path.join(
-      skillDir,
-      'add',
-      'src',
-      'channels',
-      'discord.ts',
-    );
-    expect(fs.existsSync(channelFile)).toBe(true);
-
-    const content = fs.readFileSync(channelFile, 'utf-8');
-    expect(content).toContain('class DiscordChannel');
-    expect(content).toContain('implements Channel');
-    expect(content).toContain("registerChannel('discord'");
-
-    // Test file for the channel
-    const testFile = path.join(
-      skillDir,
-      'add',
-      'src',
-      'channels',
-      'discord.test.ts',
-    );
-    expect(fs.existsSync(testFile)).toBe(true);
-
-    const testContent = fs.readFileSync(testFile, 'utf-8');
-    expect(testContent).toContain("describe('DiscordChannel'");
-  });
-
-  it('has all files declared in modifies', () => {
-    // Channel barrel file
-    const indexFile = path.join(
-      skillDir,
-      'modify',
-      'src',
-      'channels',
-      'index.ts',
-    );
-    expect(fs.existsSync(indexFile)).toBe(true);
-
-    const indexContent = fs.readFileSync(indexFile, 'utf-8');
-    expect(indexContent).toContain("import './discord.js'");
-  });
-
-  it('has intent files for modified files', () => {
-    expect(
-      fs.existsSync(
-        path.join(skillDir, 'modify', 'src', 'channels', 'index.ts.intent.md'),
-      ),
-    ).toBe(true);
-  });
-});

.claude/skills/add-emacs/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: add-emacs
+description: Add Emacs as a channel. Opens an interactive chat buffer and org-mode integration so you can talk to NanoClaw from within Emacs (Doom, Spacemacs, or vanilla). Uses a local HTTP bridge — no bot token or external service needed.
+---
+
+# Add Emacs Channel
+
+This skill adds Emacs support to NanoClaw, then walks through interactive setup.
+Works with Doom Emacs, Spacemacs, and vanilla Emacs 27.1+.
+
+## What you can do with this
+
+- **Ask while coding** — open the chat buffer (`C-c n c` / `SPC N c`), ask about a function or error without leaving Emacs
+- **Code review** — select a region and send it with `nanoclaw-org-send`; the response appears as a child heading inline in your org file
+- **Meeting notes** — send an org agenda entry; get a summary or action item list back as a child node
+- **Draft writing** — send org prose; receive revisions or continuations in place
+- **Research capture** — ask a question directly in your org notes; the answer lands exactly where you need it
+- **Schedule tasks** — ask Andy to set a reminder or create a scheduled NanoClaw task (e.g. "remind me tomorrow to review the PR")
+
+## Phase 1: Pre-flight
+
+### Check if already applied
+
+Check if `src/channels/emacs.ts` exists:
+
+```bash
+test -f src/channels/emacs.ts && echo "already applied" || echo "not applied"
+```
+
+If it exists, skip to Phase 3 (Setup). The code changes are already in place.
+
+## Phase 2: Apply Code Changes
+
+### Ensure the upstream remote
+
+```bash
+git remote -v
+```
+
+If an `upstream` remote pointing to `https://github.com/qwibitai/nanoclaw.git` is missing,
+add it:
+
+```bash
+git remote add upstream https://github.com/qwibitai/nanoclaw.git
+```
+
+### Merge the skill branch
+
+```bash
+git fetch upstream skill/emacs
+git merge upstream/skill/emacs
+```
+
+If there are merge conflicts on `pnpm-lock.yaml`, resolve them by accepting the incoming
+version and continuing:
+
+```bash
+git checkout --theirs pnpm-lock.yaml
+git add pnpm-lock.yaml
+git merge --continue
+```
+
+For any other conflict, read the conflicted file and reconcile both sides manually.
+
+This adds:
+- `src/channels/emacs.ts` — `EmacsBridgeChannel` HTTP server (port 8766)
+- `src/channels/emacs.test.ts` — unit tests
+- `emacs/nanoclaw.el` — Emacs Lisp package (`nanoclaw-chat`, `nanoclaw-org-send`)
+- `import './emacs.js'` appended to `src/channels/index.ts`
+
+If the merge reports conflicts, resolve them by reading the conflicted files and understanding the intent of both sides.
+
+### Validate code changes
+
+```bash
+pnpm run build
+pnpm exec vitest run src/channels/emacs.test.ts
+```
+
+Build must be clean and tests must pass before proceeding.
+
+## Phase 3: Setup
+
+### Configure environment (optional)
+
+The channel works out of the box with defaults. Add to `.env` only if you need non-defaults:
+
+```bash
+EMACS_CHANNEL_PORT=8766     # default — change if 8766 is already in use
+EMACS_AUTH_TOKEN=<random>   # optional — locks the endpoint to Emacs only
+```
+
+If you change or add values, sync to the container environment:
+
+```bash
+mkdir -p data/env && cp .env data/env/env
+```
+
+### Configure Emacs
+
+The `nanoclaw.el` package requires only Emacs 27.1+ built-in libraries (`url`, `json`, `org`) — no package manager setup needed.
+
+AskUserQuestion: Which Emacs distribution are you using?
+- **Doom Emacs** - config.el with map! keybindings
+- **Spacemacs** - dotspacemacs/user-config in ~/.spacemacs
+- **Vanilla Emacs / other** - init.el with global-set-key
+
+**Doom Emacs** — add to `~/.config/doom/config.el` (or `~/.doom.d/config.el`):
+
+```elisp
+;; NanoClaw — personal AI assistant channel
+(load (expand-file-name "~/src/nanoclaw/emacs/nanoclaw.el"))
+
+(map! :leader
+      :prefix ("N" . "NanoClaw")
+      :desc "Chat buffer"  "c" #'nanoclaw-chat
+      :desc "Send org"     "o" #'nanoclaw-org-send)
+```
+
+Then reload: `M-x doom/reload`
+
+**Spacemacs** — add to `dotspacemacs/user-config` in `~/.spacemacs`:
+
+```elisp
+;; NanoClaw — personal AI assistant channel
+(load-file "~/src/nanoclaw/emacs/nanoclaw.el")
+
+(spacemacs/set-leader-keys "aNc" #'nanoclaw-chat)
+(spacemacs/set-leader-keys "aNo" #'nanoclaw-org-send)
+```
+
+Then reload: `M-x dotspacemacs/sync-configuration-layers` or restart Emacs.
+
+**Vanilla Emacs** — add to `~/.emacs.d/init.el` (or `~/.emacs`):
+
+```elisp
+;; NanoClaw — personal AI assistant channel
+(load-file "~/src/nanoclaw/emacs/nanoclaw.el")
+
+(global-set-key (kbd "C-c n c") #'nanoclaw-chat)
+(global-set-key (kbd "C-c n o") #'nanoclaw-org-send)
+```
+
+Then reload: `M-x eval-buffer` or restart Emacs.
+
+If `EMACS_AUTH_TOKEN` was set, also add (any distribution):
+
+```elisp
+(setq nanoclaw-auth-token "<your-token>")
+```
+
+If `EMACS_CHANNEL_PORT` was changed from the default, also add:
+
+```elisp
+(setq nanoclaw-port <your-port>)
+```
+
+### Restart NanoClaw
+
+```bash
+pnpm run build
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
+# Linux: systemctl --user restart nanoclaw
+```
+
+## Phase 4: Verify
+
+### Test the HTTP endpoint
+
+```bash
+curl -s "http://localhost:8766/api/messages?since=0"
+```
+
+Expected: `{"messages":[]}`
+
+If you set `EMACS_AUTH_TOKEN`:
+
+```bash
+curl -s -H "Authorization: Bearer <token>" "http://localhost:8766/api/messages?since=0"
+```
+
+### Test from Emacs
+
+Tell the user:
+
+> 1. Open the chat buffer with your keybinding (`SPC N c`, `SPC a N c`, or `C-c n c`)
+> 2. Type a message and press `RET`
+> 3. A response from Andy should appear within a few seconds
+>
+> For org-mode: open any `.org` file, position the cursor on a heading, and use `SPC N o` / `SPC a N o` / `C-c n o`
+
+### Check logs if needed
+
+```bash
+tail -f logs/nanoclaw.log
+```
+
+Look for `Emacs channel listening` at startup and `Emacs message received` when a message is sent.
+
+## Troubleshooting
+
+### Port already in use
+
+```
+Error: listen EADDRINUSE: address already in use :::8766
+```
+
+Either a stale NanoClaw process is running, or 8766 is taken by another app.
+
+Find and kill the stale process:
+
+```bash
+lsof -ti :8766 | xargs kill -9
+```
+
+Or change the port in `.env` (`EMACS_CHANNEL_PORT=8767`) and update `nanoclaw-port` in Emacs config.
+
+### No response from agent
+
+Check:
+1. NanoClaw is running: `launchctl list | grep nanoclaw` (macOS) or `systemctl --user status nanoclaw` (Linux)
+2. Emacs group is registered: `sqlite3 store/messages.db "SELECT * FROM registered_groups WHERE jid = 'emacs:default'"`
+3. Logs show activity: `tail -50 logs/nanoclaw.log`
+
+If the group is not registered, it will be created automatically on the next NanoClaw restart.
+
+### Auth token mismatch (401 Unauthorized)
+
+Verify the token in Emacs matches `.env`:
+
+```elisp
+;; M-x describe-variable RET nanoclaw-auth-token RET
+```
+
+Must exactly match `EMACS_AUTH_TOKEN` in `.env`.
+
+### nanoclaw.el not loading
+
+Check the path is correct:
+
+```bash
+ls ~/src/nanoclaw/emacs/nanoclaw.el
+```
+
+If NanoClaw is cloned elsewhere, update the `load`/`load-file` path in your Emacs config.
+
+## After Setup
+
+If running `pnpm run dev` while the service is active:
+
+```bash
+# macOS:
+launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
+pnpm run dev
+# When done testing:
+launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
+
+# Linux:
+# systemctl --user stop nanoclaw
+# pnpm run dev
+# systemctl --user start nanoclaw
+```
+
+## Agent Formatting
+
+The Emacs bridge converts markdown → org-mode automatically. Agents should
+output standard markdown — **not** org-mode syntax. The conversion handles:
+
+| Markdown | Org-mode |
+|----------|----------|
+| `**bold**` | `*bold*` |
+| `*italic*` | `/italic/` |
+| `~~text~~` | `+text+` |
+| `` `code` `` | `~code~` |
+| ` ```lang ` | `#+begin_src lang` |
+
+If an agent outputs org-mode directly, bold/italic/etc. will be double-converted
+and render incorrectly.
+
+## Removal
+
+To remove the Emacs channel:
+
+1. Delete `src/channels/emacs.ts`, `src/channels/emacs.test.ts`, and `emacs/nanoclaw.el`
+2. Remove `import './emacs.js'` from `src/channels/index.ts`
+3. Remove the NanoClaw block from your Emacs config file
+4. Remove Emacs registration from SQLite: `sqlite3 store/messages.db "DELETE FROM registered_groups WHERE jid = 'emacs:default'"`
+5. Remove `EMACS_CHANNEL_PORT` and `EMACS_AUTH_TOKEN` from `.env` if set
+6. Rebuild: `pnpm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw` (macOS) or `pnpm run build && systemctl --user restart nanoclaw` (Linux)

.claude/skills/add-gchat-v2/REMOVE.md

@@ -0,0 +1,6 @@
+# Remove Google Chat Channel
+
+1. Comment out `import './gchat.js'` in `src/channels/index.ts`
+2. Remove `GCHAT_CREDENTIALS` from `.env`
+3. `pnpm uninstall @chat-adapter/gchat`
+4. Rebuild and restart

.claude/skills/add-gchat-v2/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: add-gchat-v2
+description: Add Google Chat channel integration to NanoClaw v2 via Chat SDK.
+---
+
+# Add Google Chat Channel
+
+Adds Google Chat support to NanoClaw v2 using the Chat SDK bridge.
+
+## Pre-flight
+
+Check if `src/channels/gchat.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Credentials.
+
+## Install
+
+```bash
+pnpm install @chat-adapter/gchat
+```
+
+Uncomment the Google Chat import in `src/channels/index.ts`:
+
+```typescript
+import './gchat.js';
+```
+
+```bash
+pnpm run build
+```
+
+## Credentials
+
+> 1. Go to [Google Cloud Console](https://console.cloud.google.com)
+> 2. Create or select a project
+> 3. Enable the **Google Chat API**
+> 4. Go to **Google Chat API** > **Configuration**:
+>    - App name and description
+>    - Connection settings: select **HTTP endpoint URL** and set to `https://your-domain/webhook/gchat`
+> 5. Create a **Service Account**:
+>    - Go to **IAM & Admin** > **Service Accounts** > **Create Service Account**
+>    - Grant the Chat Bot role
+>    - Create a JSON key and download it
+
+### Configure environment
+
+Add the service account JSON as a single-line string to `.env`:
+
+```bash
+GCHAT_CREDENTIALS={"type":"service_account","project_id":"...","private_key":"...","client_email":"..."}
+```
+
+Sync to container: `mkdir -p data/env && cp .env data/env/env`
+
+## Next Steps
+
+If you're in the middle of `/setup`, return to the setup flow now.
+
+Otherwise, run `/manage-channels` to wire this channel to an agent group.
+
+## Channel Info
+
+- **type**: `gchat`
+- **terminology**: Google Chat has "spaces." A space can be a group conversation or a direct message with the bot.
+- **how-to-find-id**: Open the space in Google Chat, look at the URL — the space ID is the segment after `/space/` (e.g. `spaces/AAAA...`). Or use the Google Chat API to list spaces.
+- **supports-threads**: yes
+- **typical-use**: Interactive chat — team spaces or direct messages
+- **default-isolation**: Same agent group for spaces where you're the primary user. Separate agent group for spaces with different teams or sensitive contexts.

.claude/skills/add-gchat-v2/VERIFY.md

@@ -0,0 +1,3 @@
+# Verify Google Chat Channel
+
+Add the bot to a Google Chat space, then send a message or @mention the bot. The bot should respond within a few seconds.

.claude/skills/add-github-v2/REMOVE.md

@@ -0,0 +1,6 @@
+# Remove GitHub Channel
+
+1. Comment out `import './github.js'` in `src/channels/index.ts`
+2. Remove `GITHUB_TOKEN` and `GITHUB_WEBHOOK_SECRET` from `.env`
+3. `pnpm uninstall @chat-adapter/github`
+4. Rebuild and restart

.claude/skills/add-github-v2/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: add-github-v2
+description: Add GitHub channel integration to NanoClaw v2 via Chat SDK. PR and issue comment threads as conversations.
+---
+
+# Add GitHub Channel
+
+Adds GitHub support to NanoClaw v2 using the Chat SDK bridge. The agent participates in PR and issue comment threads.
+
+## Pre-flight
+
+Check if `src/channels/github.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Credentials.
+
+## Install
+
+```bash
+pnpm install @chat-adapter/github
+```
+
+Uncomment the GitHub import in `src/channels/index.ts`:
+
+```typescript
+import './github.js';
+```
+
+```bash
+pnpm run build
+```
+
+## Credentials
+
+> 1. Go to [GitHub Settings > Developer Settings > Personal Access Tokens](https://github.com/settings/tokens)
+> 2. Create a **Fine-grained token** with:
+>    - Repository access: select the repos you want the bot to monitor
+>    - Permissions: **Pull requests** (Read & Write), **Issues** (Read & Write)
+> 3. Copy the token
+> 4. Set up a webhook on your repo(s):
+>    - Go to **Settings** > **Webhooks** > **Add webhook**
+>    - Payload URL: `https://your-domain/webhook/github`
+>    - Content type: `application/json`
+>    - Secret: generate a random string
+>    - Events: select **Issue comments**, **Pull request review comments**
+
+### Configure environment
+
+Add to `.env`:
+
+```bash
+GITHUB_TOKEN=github_pat_...
+GITHUB_WEBHOOK_SECRET=your-webhook-secret
+```
+
+Sync to container: `mkdir -p data/env && cp .env data/env/env`
+
+## Next Steps
+
+If you're in the middle of `/setup`, return to the setup flow now.
+
+Otherwise, run `/manage-channels` to wire this channel to an agent group.
+
+## Channel Info
+
+- **type**: `github`
+- **terminology**: GitHub has "repositories" containing "pull requests" and "issues." Each PR or issue comment thread is a separate conversation.
+- **how-to-find-id**: The platform ID is `owner/repo` (e.g. `acme/backend`). Each PR/issue becomes its own thread automatically.
+- **supports-threads**: yes (PR and issue comment threads are native conversations)
+- **typical-use**: Webhook/notification — the agent receives PR and issue events and responds in comment threads
+- **default-isolation**: Typically shares a session with a chat channel (e.g. Slack) so the agent can summarize PRs and respond to reviews in the same context. Use a separate agent group if the repo contains sensitive code that other channels shouldn't access.

.claude/skills/add-github-v2/VERIFY.md

@@ -0,0 +1,3 @@
+# Verify GitHub Channel
+
+@mention the bot in a PR comment or issue comment. The bot should respond within a few seconds.

.claude/skills/add-gmail/SKILL.md

@@ -11,7 +11,7 @@ This skill adds Gmail support to NanoClaw — either as a tool (read, send, sear
 
 ### Check if already applied
 
-Read `.nanoclaw/state.yaml`. If `gmail` is in `applied_skills`, skip to Phase 3 (Setup). The code changes are already in place.
+Check if `src/channels/gmail.ts` exists. If it does, skip to Phase 3 (Setup). The code changes are already in place.
 
 ### Ask the user
 
@@ -24,65 +24,42 @@ AskUserQuestion: Should incoming emails be able to trigger the agent?
 
 ## Phase 2: Apply Code Changes
 
-### Initialize skills system (if needed)
-
-If `.nanoclaw/` directory doesn't exist yet:
+### Ensure channel remote
 
 ```bash
-npx tsx scripts/apply-skill.ts --init
+git remote -v
 ```
 
-### Path A: Tool-only (user chose "No")
-
-Do NOT run the full apply script. Only two source files need changes. This avoids adding dead code (`gmail.ts`, `gmail.test.ts`, index.ts channel logic, routing tests, `googleapis` dependency).
-
-#### 1. Mount Gmail credentials in container
-
-Apply the changes described in `modify/src/container-runner.ts.intent.md` to `src/container-runner.ts`: import `os`, add a conditional read-write mount of `~/.gmail-mcp` to `/home/node/.gmail-mcp` in `buildVolumeMounts()` after the session mounts.
-
-#### 2. Add Gmail MCP server to agent runner
-
-Apply the changes described in `modify/container/agent-runner/src/index.ts.intent.md` to `container/agent-runner/src/index.ts`: add `gmail` MCP server (`npx -y @gongrzhe/server-gmail-autoauth-mcp`) and `'mcp__gmail__*'` to `allowedTools`.
-
-#### 3. Record in state
-
-Add `gmail` to `.nanoclaw/state.yaml` under `applied_skills` with `mode: tool-only`.
-
-#### 4. Validate
+If `gmail` is missing, add it:
 
 ```bash
-npm run build
+git remote add gmail https://github.com/qwibitai/nanoclaw-gmail.git
 ```
 
-Build must be clean before proceeding. Skip to Phase 3.
-
-### Path B: Channel mode (user chose "Yes")
-
-Run the full skills engine to apply all code changes:
+### Merge the skill branch
 
 ```bash
-npx tsx scripts/apply-skill.ts .claude/skills/add-gmail
+git fetch gmail main
+git merge gmail/main || {
+  git checkout --theirs pnpm-lock.yaml
+  git add pnpm-lock.yaml
+  git merge --continue
+}
 ```
 
-This deterministically:
+This merges in:
+- `src/channels/gmail.ts` (GmailChannel class with self-registration via `registerChannel`)
+- `src/channels/gmail.test.ts` (unit tests)
+- `import './gmail.js'` appended to the channel barrel file `src/channels/index.ts`
+- Gmail credentials mount (`~/.gmail-mcp`) in `src/container-runner.ts`
+- Gmail MCP server (`@gongrzhe/server-gmail-autoauth-mcp`) and `mcp__gmail__*` allowed tool in `container/agent-runner/src/index.ts`
+- `googleapis` npm dependency in `package.json`
 
-- Adds `src/channels/gmail.ts` (GmailChannel class with self-registration via `registerChannel`)
-- Adds `src/channels/gmail.test.ts` (unit tests)
-- Appends `import './gmail.js'` to the channel barrel file `src/channels/index.ts`
-- Three-way merges Gmail credentials mount into `src/container-runner.ts` (~/.gmail-mcp -> /home/node/.gmail-mcp)
-- Three-way merges Gmail MCP server into `container/agent-runner/src/index.ts` (@gongrzhe/server-gmail-autoauth-mcp)
-- Installs the `googleapis` npm dependency
-- Records the application in `.nanoclaw/state.yaml`
+If the merge reports conflicts, resolve them by reading the conflicted files and understanding the intent of both sides.
 
-If the apply reports merge conflicts, read the intent files:
+### Add email handling instructions (Channel mode only)
 
-- `modify/src/channels/index.ts.intent.md` — what changed for the barrel file
-- `modify/src/container-runner.ts.intent.md` — what changed for container-runner.ts
-- `modify/container/agent-runner/src/index.ts.intent.md` — what changed for agent-runner
-
-#### Add email handling instructions
-
-Append the following to `groups/main/CLAUDE.md` (before the formatting section):
+If the user chose channel mode, append the following to `groups/main/CLAUDE.md` (before the formatting section):
 
 ```markdown
 ## Email Notifications
@@ -90,14 +67,15 @@ Append the following to `groups/main/CLAUDE.md` (before the formatting section):
 When you receive an email notification (messages starting with `[Email from ...`), inform the user about it but do NOT reply to the email unless specifically asked. You have Gmail tools available — use them only when the user explicitly asks you to reply, forward, or take action on an email.
 ```
 
-#### Validate
+### Validate code changes
 
 ```bash
-npm test
-npm run build
+pnpm install
+pnpm run build
+pnpm exec vitest run src/channels/gmail.test.ts
 ```
 
-All tests must pass (including the new gmail tests) and build must be clean before proceeding.
+All tests must pass (including the new Gmail tests) and build must be clean before proceeding.
 
 ## Phase 3: Setup
 
@@ -107,11 +85,27 @@ All tests must pass (including the new gmail tests) and build must be clean befo
 ls -la ~/.gmail-mcp/ 2>/dev/null || echo "No Gmail config found"
 ```
 
-If `credentials.json` already exists, skip to "Build and restart" below.
+If `credentials.json` already exists with real tokens (not `onecli-managed` values), skip to "Build and restart" below.
 
 ### GCP Project Setup
 
-Tell the user:
+Check if OneCLI is configured:
+
+```bash
+grep -q 'ONECLI_URL=.' .env 2>/dev/null && echo "onecli" || echo "manual"
+```
+
+**If OneCLI:** Tell the user to open `${ONECLI_URL}/connections?connect=gmail` to set up their Gmail connection. The dashboard walks them through creating a Google Cloud OAuth app and authorizing it. Ask them to let you know when done.
+
+Once the user confirms, run:
+
+```bash
+onecli apps get --provider gmail
+```
+
+Check that `config.hasCredentials` is `true` or `connection` is not null. The response `hint` field has instructions and a docs URL for what stub credential files to create under `~/.gmail-mcp/`. Follow the hint — never overwrite existing files that don't contain `onecli-managed` values.
+
+**If manual:** Tell the user:
 
 > I need you to set up Google Cloud OAuth credentials:
 >
@@ -142,10 +136,10 @@ Tell the user:
 Run the authorization:
 
 ```bash
-npx -y @gongrzhe/server-gmail-autoauth-mcp auth
+pnpm dlx @gongrzhe/server-gmail-autoauth-mcp auth
 ```
 
-If that fails (some versions don't have an auth subcommand), try `timeout 60 npx -y @gongrzhe/server-gmail-autoauth-mcp || true`. Verify with `ls ~/.gmail-mcp/credentials.json`.
+If that fails (some versions don't have an auth subcommand), try `timeout 60 pnpm dlx @gongrzhe/server-gmail-autoauth-mcp || true`. Verify with `ls ~/.gmail-mcp/credentials.json`.
 
 ### Build and restart
 
@@ -164,7 +158,7 @@ cd container && ./build.sh
 Then compile and restart:
 
 ```bash
-npm run build
+pnpm run build
 launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
 # Linux: systemctl --user restart nanoclaw
 ```
@@ -198,7 +192,7 @@ tail -f logs/nanoclaw.log
 Test directly:
 
 ```bash
-npx -y @gongrzhe/server-gmail-autoauth-mcp
+pnpm dlx @gongrzhe/server-gmail-autoauth-mcp
 ```
 
 ### OAuth token expired
@@ -207,7 +201,7 @@ Re-authorize:
 
 ```bash
 rm ~/.gmail-mcp/credentials.json
-npx -y @gongrzhe/server-gmail-autoauth-mcp
+pnpm dlx @gongrzhe/server-gmail-autoauth-mcp
 ```
 
 ### Container can't access Gmail
@@ -226,9 +220,9 @@ npx -y @gongrzhe/server-gmail-autoauth-mcp
 
 1. Remove `~/.gmail-mcp` mount from `src/container-runner.ts`
 2. Remove `gmail` MCP server and `mcp__gmail__*` from `container/agent-runner/src/index.ts`
-3. Remove `gmail` from `.nanoclaw/state.yaml`
+3. Rebuild and restart
 4. Clear stale agent-runner copies: `rm -r data/sessions/*/agent-runner-src 2>/dev/null || true`
-5. Rebuild: `cd container && ./build.sh && cd .. && npm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw` (macOS) or `systemctl --user restart nanoclaw` (Linux)
+5. Rebuild: `cd container && ./build.sh && cd .. && pnpm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw` (macOS) or `systemctl --user restart nanoclaw` (Linux)
 
 ### Channel mode
 
@@ -236,7 +230,7 @@ npx -y @gongrzhe/server-gmail-autoauth-mcp
 2. Remove `import './gmail.js'` from `src/channels/index.ts`
 3. Remove `~/.gmail-mcp` mount from `src/container-runner.ts`
 4. Remove `gmail` MCP server and `mcp__gmail__*` from `container/agent-runner/src/index.ts`
-5. Uninstall: `npm uninstall googleapis`
-6. Remove `gmail` from `.nanoclaw/state.yaml`
+5. Uninstall: `pnpm uninstall googleapis`
+6. Rebuild and restart
 7. Clear stale agent-runner copies: `rm -r data/sessions/*/agent-runner-src 2>/dev/null || true`
-8. Rebuild: `cd container && ./build.sh && cd .. && npm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw` (macOS) or `systemctl --user restart nanoclaw` (Linux)
+8. Rebuild: `cd container && ./build.sh && cd .. && pnpm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw` (macOS) or `systemctl --user restart nanoclaw` (Linux)

.claude/skills/add-gmail/add/src/channels/gmail.test.ts

@@ -1,74 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-
-// Mock registry (registerChannel runs at import time)
-vi.mock('./registry.js', () => ({ registerChannel: vi.fn() }));
-
-import { GmailChannel, GmailChannelOpts } from './gmail.js';
-
-function makeOpts(overrides?: Partial<GmailChannelOpts>): GmailChannelOpts {
-  return {
-    onMessage: vi.fn(),
-    onChatMetadata: vi.fn(),
-    registeredGroups: () => ({}),
-    ...overrides,
-  };
-}
-
-describe('GmailChannel', () => {
-  let channel: GmailChannel;
-
-  beforeEach(() => {
-    channel = new GmailChannel(makeOpts());
-  });
-
-  describe('ownsJid', () => {
-    it('returns true for gmail: prefixed JIDs', () => {
-      expect(channel.ownsJid('gmail:abc123')).toBe(true);
-      expect(channel.ownsJid('gmail:thread-id-456')).toBe(true);
-    });
-
-    it('returns false for non-gmail JIDs', () => {
-      expect(channel.ownsJid('12345@g.us')).toBe(false);
-      expect(channel.ownsJid('tg:123')).toBe(false);
-      expect(channel.ownsJid('dc:456')).toBe(false);
-      expect(channel.ownsJid('user@s.whatsapp.net')).toBe(false);
-    });
-  });
-
-  describe('name', () => {
-    it('is gmail', () => {
-      expect(channel.name).toBe('gmail');
-    });
-  });
-
-  describe('isConnected', () => {
-    it('returns false before connect', () => {
-      expect(channel.isConnected()).toBe(false);
-    });
-  });
-
-  describe('disconnect', () => {
-    it('sets connected to false', async () => {
-      await channel.disconnect();
-      expect(channel.isConnected()).toBe(false);
-    });
-  });
-
-  describe('constructor options', () => {
-    it('accepts custom poll interval', () => {
-      const ch = new GmailChannel(makeOpts(), 30000);
-      expect(ch.name).toBe('gmail');
-    });
-
-    it('defaults to unread query when no filter configured', () => {
-      const ch = new GmailChannel(makeOpts());
-      const query = (ch as unknown as { buildQuery: () => string }).buildQuery();
-      expect(query).toBe('is:unread category:primary');
-    });
-
-    it('defaults with no options provided', () => {
-      const ch = new GmailChannel(makeOpts());
-      expect(ch.name).toBe('gmail');
-    });
-  });
-});

.claude/skills/add-gmail/add/src/channels/gmail.ts

@@ -1,352 +0,0 @@
-import fs from 'fs';
-import os from 'os';
-import path from 'path';
-
-import { google, gmail_v1 } from 'googleapis';
-import { OAuth2Client } from 'google-auth-library';
-
-// isMain flag is used instead of MAIN_GROUP_FOLDER constant
-import { logger } from '../logger.js';
-import { registerChannel, ChannelOpts } from './registry.js';
-import {
-  Channel,
-  OnChatMetadata,
-  OnInboundMessage,
-  RegisteredGroup,
-} from '../types.js';
-
-export interface GmailChannelOpts {
-  onMessage: OnInboundMessage;
-  onChatMetadata: OnChatMetadata;
-  registeredGroups: () => Record<string, RegisteredGroup>;
-}
-
-interface ThreadMeta {
-  sender: string;
-  senderName: string;
-  subject: string;
-  messageId: string; // RFC 2822 Message-ID for In-Reply-To
-}
-
-export class GmailChannel implements Channel {
-  name = 'gmail';
-
-  private oauth2Client: OAuth2Client | null = null;
-  private gmail: gmail_v1.Gmail | null = null;
-  private opts: GmailChannelOpts;
-  private pollIntervalMs: number;
-  private pollTimer: ReturnType<typeof setTimeout> | null = null;
-  private processedIds = new Set<string>();
-  private threadMeta = new Map<string, ThreadMeta>();
-  private consecutiveErrors = 0;
-  private userEmail = '';
-
-  constructor(opts: GmailChannelOpts, pollIntervalMs = 60000) {
-    this.opts = opts;
-    this.pollIntervalMs = pollIntervalMs;
-  }
-
-  async connect(): Promise<void> {
-    const credDir = path.join(os.homedir(), '.gmail-mcp');
-    const keysPath = path.join(credDir, 'gcp-oauth.keys.json');
-    const tokensPath = path.join(credDir, 'credentials.json');
-
-    if (!fs.existsSync(keysPath) || !fs.existsSync(tokensPath)) {
-      logger.warn(
-        'Gmail credentials not found in ~/.gmail-mcp/. Skipping Gmail channel. Run /add-gmail to set up.',
-      );
-      return;
-    }
-
-    const keys = JSON.parse(fs.readFileSync(keysPath, 'utf-8'));
-    const tokens = JSON.parse(fs.readFileSync(tokensPath, 'utf-8'));
-
-    const clientConfig = keys.installed || keys.web || keys;
-    const { client_id, client_secret, redirect_uris } = clientConfig;
-    this.oauth2Client = new google.auth.OAuth2(
-      client_id,
-      client_secret,
-      redirect_uris?.[0],
-    );
-    this.oauth2Client.setCredentials(tokens);
-
-    // Persist refreshed tokens
-    this.oauth2Client.on('tokens', (newTokens) => {
-      try {
-        const current = JSON.parse(fs.readFileSync(tokensPath, 'utf-8'));
-        Object.assign(current, newTokens);
-        fs.writeFileSync(tokensPath, JSON.stringify(current, null, 2));
-        logger.debug('Gmail OAuth tokens refreshed');
-      } catch (err) {
-        logger.warn({ err }, 'Failed to persist refreshed Gmail tokens');
-      }
-    });
-
-    this.gmail = google.gmail({ version: 'v1', auth: this.oauth2Client });
-
-    // Verify connection
-    const profile = await this.gmail.users.getProfile({ userId: 'me' });
-    this.userEmail = profile.data.emailAddress || '';
-    logger.info({ email: this.userEmail }, 'Gmail channel connected');
-
-    // Start polling with error backoff
-    const schedulePoll = () => {
-      const backoffMs = this.consecutiveErrors > 0
-        ? Math.min(this.pollIntervalMs * Math.pow(2, this.consecutiveErrors), 30 * 60 * 1000)
-        : this.pollIntervalMs;
-      this.pollTimer = setTimeout(() => {
-        this.pollForMessages()
-          .catch((err) => logger.error({ err }, 'Gmail poll error'))
-          .finally(() => {
-            if (this.gmail) schedulePoll();
-          });
-      }, backoffMs);
-    };
-
-    // Initial poll
-    await this.pollForMessages();
-    schedulePoll();
-  }
-
-  async sendMessage(jid: string, text: string): Promise<void> {
-    if (!this.gmail) {
-      logger.warn('Gmail not initialized');
-      return;
-    }
-
-    const threadId = jid.replace(/^gmail:/, '');
-    const meta = this.threadMeta.get(threadId);
-
-    if (!meta) {
-      logger.warn({ jid }, 'No thread metadata for reply, cannot send');
-      return;
-    }
-
-    const subject = meta.subject.startsWith('Re:')
-      ? meta.subject
-      : `Re: ${meta.subject}`;
-
-    const headers = [
-      `To: ${meta.sender}`,
-      `From: ${this.userEmail}`,
-      `Subject: ${subject}`,
-      `In-Reply-To: ${meta.messageId}`,
-      `References: ${meta.messageId}`,
-      'Content-Type: text/plain; charset=utf-8',
-      '',
-      text,
-    ].join('\r\n');
-
-    const encodedMessage = Buffer.from(headers)
-      .toString('base64')
-      .replace(/\+/g, '-')
-      .replace(/\//g, '_')
-      .replace(/=+$/, '');
-
-    try {
-      await this.gmail.users.messages.send({
-        userId: 'me',
-        requestBody: {
-          raw: encodedMessage,
-          threadId,
-        },
-      });
-      logger.info({ to: meta.sender, threadId }, 'Gmail reply sent');
-    } catch (err) {
-      logger.error({ jid, err }, 'Failed to send Gmail reply');
-    }
-  }
-
-  isConnected(): boolean {
-    return this.gmail !== null;
-  }
-
-  ownsJid(jid: string): boolean {
-    return jid.startsWith('gmail:');
-  }
-
-  async disconnect(): Promise<void> {
-    if (this.pollTimer) {
-      clearTimeout(this.pollTimer);
-      this.pollTimer = null;
-    }
-    this.gmail = null;
-    this.oauth2Client = null;
-    logger.info('Gmail channel stopped');
-  }
-
-  // --- Private ---
-
-  private buildQuery(): string {
-    return 'is:unread category:primary';
-  }
-
-  private async pollForMessages(): Promise<void> {
-    if (!this.gmail) return;
-
-    try {
-      const query = this.buildQuery();
-      const res = await this.gmail.users.messages.list({
-        userId: 'me',
-        q: query,
-        maxResults: 10,
-      });
-
-      const messages = res.data.messages || [];
-
-      for (const stub of messages) {
-        if (!stub.id || this.processedIds.has(stub.id)) continue;
-        this.processedIds.add(stub.id);
-
-        await this.processMessage(stub.id);
-      }
-
-      // Cap processed ID set to prevent unbounded growth
-      if (this.processedIds.size > 5000) {
-        const ids = [...this.processedIds];
-        this.processedIds = new Set(ids.slice(ids.length - 2500));
-      }
-
-      this.consecutiveErrors = 0;
-    } catch (err) {
-      this.consecutiveErrors++;
-      const backoffMs = Math.min(this.pollIntervalMs * Math.pow(2, this.consecutiveErrors), 30 * 60 * 1000);
-      logger.error({ err, consecutiveErrors: this.consecutiveErrors, nextPollMs: backoffMs }, 'Gmail poll failed');
-    }
-  }
-
-  private async processMessage(messageId: string): Promise<void> {
-    if (!this.gmail) return;
-
-    const msg = await this.gmail.users.messages.get({
-      userId: 'me',
-      id: messageId,
-      format: 'full',
-    });
-
-    const headers = msg.data.payload?.headers || [];
-    const getHeader = (name: string) =>
-      headers.find((h) => h.name?.toLowerCase() === name.toLowerCase())
-        ?.value || '';
-
-    const from = getHeader('From');
-    const subject = getHeader('Subject');
-    const rfc2822MessageId = getHeader('Message-ID');
-    const threadId = msg.data.threadId || messageId;
-    const timestamp = new Date(
-      parseInt(msg.data.internalDate || '0', 10),
-    ).toISOString();
-
-    // Extract sender name and email
-    const senderMatch = from.match(/^(.+?)\s*<(.+?)>$/);
-    const senderName = senderMatch ? senderMatch[1].replace(/"/g, '') : from;
-    const senderEmail = senderMatch ? senderMatch[2] : from;
-
-    // Skip emails from self (our own replies)
-    if (senderEmail === this.userEmail) return;
-
-    // Extract body text
-    const body = this.extractTextBody(msg.data.payload);
-
-    if (!body) {
-      logger.debug({ messageId, subject }, 'Skipping email with no text body');
-      return;
-    }
-
-    const chatJid = `gmail:${threadId}`;
-
-    // Cache thread metadata for replies
-    this.threadMeta.set(threadId, {
-      sender: senderEmail,
-      senderName,
-      subject,
-      messageId: rfc2822MessageId,
-    });
-
-    // Store chat metadata for group discovery
-    this.opts.onChatMetadata(chatJid, timestamp, subject, 'gmail', false);
-
-    // Find the main group to deliver the email notification
-    const groups = this.opts.registeredGroups();
-    const mainEntry = Object.entries(groups).find(
-      ([, g]) => g.isMain === true,
-    );
-
-    if (!mainEntry) {
-      logger.debug(
-        { chatJid, subject },
-        'No main group registered, skipping email',
-      );
-      return;
-    }
-
-    const mainJid = mainEntry[0];
-    const content = `[Email from ${senderName} <${senderEmail}>]\nSubject: ${subject}\n\n${body}`;
-
-    this.opts.onMessage(mainJid, {
-      id: messageId,
-      chat_jid: mainJid,
-      sender: senderEmail,
-      sender_name: senderName,
-      content,
-      timestamp,
-      is_from_me: false,
-    });
-
-    // Mark as read
-    try {
-      await this.gmail.users.messages.modify({
-        userId: 'me',
-        id: messageId,
-        requestBody: { removeLabelIds: ['UNREAD'] },
-      });
-    } catch (err) {
-      logger.warn({ messageId, err }, 'Failed to mark email as read');
-    }
-
-    logger.info(
-      { mainJid, from: senderName, subject },
-      'Gmail email delivered to main group',
-    );
-  }
-
-  private extractTextBody(
-    payload: gmail_v1.Schema$MessagePart | undefined,
-  ): string {
-    if (!payload) return '';
-
-    // Direct text/plain body
-    if (payload.mimeType === 'text/plain' && payload.body?.data) {
-      return Buffer.from(payload.body.data, 'base64').toString('utf-8');
-    }
-
-    // Multipart: search parts recursively
-    if (payload.parts) {
-      // Prefer text/plain
-      for (const part of payload.parts) {
-        if (part.mimeType === 'text/plain' && part.body?.data) {
-          return Buffer.from(part.body.data, 'base64').toString('utf-8');
-        }
-      }
-      // Recurse into nested multipart
-      for (const part of payload.parts) {
-        const text = this.extractTextBody(part);
-        if (text) return text;
-      }
-    }
-
-    return '';
-  }
-}
-
-registerChannel('gmail', (opts: ChannelOpts) => {
-  const credDir = path.join(os.homedir(), '.gmail-mcp');
-  if (
-    !fs.existsSync(path.join(credDir, 'gcp-oauth.keys.json')) ||
-    !fs.existsSync(path.join(credDir, 'credentials.json'))
-  ) {
-    logger.warn('Gmail: credentials not found in ~/.gmail-mcp/');
-    return null;
-  }
-  return new GmailChannel(opts);
-});

.claude/skills/add-gmail/manifest.yaml

@@ -1,17 +0,0 @@
-skill: gmail
-version: 1.0.0
-description: "Gmail integration via Google APIs"
-core_version: 0.1.0
-adds:
-  - src/channels/gmail.ts
-  - src/channels/gmail.test.ts
-modifies:
-  - src/channels/index.ts
-  - src/container-runner.ts
-  - container/agent-runner/src/index.ts
-structured:
-  npm_dependencies:
-    googleapis: "^144.0.0"
-conflicts: []
-depends: []
-test: "npx vitest run src/channels/gmail.test.ts"

.claude/skills/add-gmail/modify/container/agent-runner/src/index.ts.intent.md

@@ -1,32 +0,0 @@
-# Intent: container/agent-runner/src/index.ts modifications
-
-## What changed
-Added Gmail MCP server to the agent's available tools so it can read and send emails.
-
-## Key sections
-
-### mcpServers (inside runQuery → query() call)
-- Added: `gmail` MCP server alongside the existing `nanoclaw` server:
-  ```
-  gmail: {
-    command: 'npx',
-    args: ['-y', '@gongrzhe/server-gmail-autoauth-mcp'],
-  },
-  ```
-
-### allowedTools (inside runQuery → query() call)
-- Added: `'mcp__gmail__*'` to allow all Gmail MCP tools
-
-## Invariants
-- The `nanoclaw` MCP server configuration is unchanged
-- All existing allowed tools are preserved
-- The query loop, IPC handling, MessageStream, and all other logic is untouched
-- Hooks (PreCompact, sanitize Bash) are unchanged
-- Output protocol (markers) is unchanged
-
-## Must-keep
-- The `nanoclaw` MCP server with its environment variables
-- All existing allowedTools entries
-- The hook system (PreCompact, PreToolUse sanitize)
-- The IPC input/close sentinel handling
-- The MessageStream class and query loop

.claude/skills/add-gmail/modify/src/channels/index.ts

@@ -1,13 +0,0 @@
-// Channel self-registration barrel file.
-// Each import triggers the channel module's registerChannel() call.
-
-// discord
-
-// gmail
-import './gmail.js';
-
-// slack
-
-// telegram
-
-// whatsapp

.claude/skills/add-gmail/modify/src/channels/index.ts.intent.md

@@ -1,7 +0,0 @@
-# Intent: Add Gmail channel import
-
-Add `import './gmail.js';` to the channel barrel file so the Gmail
-module self-registers with the channel registry on startup.
-
-This is an append-only change — existing import lines for other channels
-must be preserved.

.claude/skills/add-gmail/modify/src/container-runner.ts

@@ -1,661 +0,0 @@
-/**
- * Container Runner for NanoClaw
- * Spawns agent execution in containers and handles IPC
- */
-import { ChildProcess, exec, spawn } from 'child_process';
-import fs from 'fs';
-import os from 'os';
-import path from 'path';
-
-import {
-  CONTAINER_IMAGE,
-  CONTAINER_MAX_OUTPUT_SIZE,
-  CONTAINER_TIMEOUT,
-  DATA_DIR,
-  GROUPS_DIR,
-  IDLE_TIMEOUT,
-  TIMEZONE,
-} from './config.js';
-import { readEnvFile } from './env.js';
-import { resolveGroupFolderPath, resolveGroupIpcPath } from './group-folder.js';
-import { logger } from './logger.js';
-import { CONTAINER_RUNTIME_BIN, readonlyMountArgs, stopContainer } from './container-runtime.js';
-import { validateAdditionalMounts } from './mount-security.js';
-import { RegisteredGroup } from './types.js';
-
-// Sentinel markers for robust output parsing (must match agent-runner)
-const OUTPUT_START_MARKER = '---NANOCLAW_OUTPUT_START---';
-const OUTPUT_END_MARKER = '---NANOCLAW_OUTPUT_END---';
-
-export interface ContainerInput {
-  prompt: string;
-  sessionId?: string;
-  groupFolder: string;
-  chatJid: string;
-  isMain: boolean;
-  isScheduledTask?: boolean;
-  assistantName?: string;
-  secrets?: Record<string, string>;
-}
-
-export interface ContainerOutput {
-  status: 'success' | 'error';
-  result: string | null;
-  newSessionId?: string;
-  error?: string;
-}
-
-interface VolumeMount {
-  hostPath: string;
-  containerPath: string;
-  readonly: boolean;
-}
-
-function buildVolumeMounts(
-  group: RegisteredGroup,
-  isMain: boolean,
-): VolumeMount[] {
-  const mounts: VolumeMount[] = [];
-  const projectRoot = process.cwd();
-  const homeDir = os.homedir();
-  const groupDir = resolveGroupFolderPath(group.folder);
-
-  if (isMain) {
-    // Main gets the project root read-only. Writable paths the agent needs
-    // (group folder, IPC, .claude/) are mounted separately below.
-    // Read-only prevents the agent from modifying host application code
-    // (src/, dist/, package.json, etc.) which would bypass the sandbox
-    // entirely on next restart.
-    mounts.push({
-      hostPath: projectRoot,
-      containerPath: '/workspace/project',
-      readonly: true,
-    });
-
-    // Main also gets its group folder as the working directory
-    mounts.push({
-      hostPath: groupDir,
-      containerPath: '/workspace/group',
-      readonly: false,
-    });
-  } else {
-    // Other groups only get their own folder
-    mounts.push({
-      hostPath: groupDir,
-      containerPath: '/workspace/group',
-      readonly: false,
-    });
-
-    // Global memory directory (read-only for non-main)
-    // Only directory mounts are supported, not file mounts
-    const globalDir = path.join(GROUPS_DIR, 'global');
-    if (fs.existsSync(globalDir)) {
-      mounts.push({
-        hostPath: globalDir,
-        containerPath: '/workspace/global',
-        readonly: true,
-      });
-    }
-  }
-
-  // Per-group Claude sessions directory (isolated from other groups)
-  // Each group gets their own .claude/ to prevent cross-group session access
-  const groupSessionsDir = path.join(
-    DATA_DIR,
-    'sessions',
-    group.folder,
-    '.claude',
-  );
-  fs.mkdirSync(groupSessionsDir, { recursive: true });
-  const settingsFile = path.join(groupSessionsDir, 'settings.json');
-  if (!fs.existsSync(settingsFile)) {
-    fs.writeFileSync(settingsFile, JSON.stringify({
-      env: {
-        // Enable agent swarms (subagent orchestration)
-        // https://code.claude.com/docs/en/agent-teams#orchestrate-teams-of-claude-code-sessions
-        CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: '1',
-        // Load CLAUDE.md from additional mounted directories
-        // https://code.claude.com/docs/en/memory#load-memory-from-additional-directories
-        CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD: '1',
-        // Enable Claude's memory feature (persists user preferences between sessions)
-        // https://code.claude.com/docs/en/memory#manage-auto-memory
-        CLAUDE_CODE_DISABLE_AUTO_MEMORY: '0',
-      },
-    }, null, 2) + '\n');
-  }
-
-  // Sync skills from container/skills/ into each group's .claude/skills/
-  const skillsSrc = path.join(process.cwd(), 'container', 'skills');
-  const skillsDst = path.join(groupSessionsDir, 'skills');
-  if (fs.existsSync(skillsSrc)) {
-    for (const skillDir of fs.readdirSync(skillsSrc)) {
-      const srcDir = path.join(skillsSrc, skillDir);
-      if (!fs.statSync(srcDir).isDirectory()) continue;
-      const dstDir = path.join(skillsDst, skillDir);
-      fs.cpSync(srcDir, dstDir, { recursive: true });
-    }
-  }
-  mounts.push({
-    hostPath: groupSessionsDir,
-    containerPath: '/home/node/.claude',
-    readonly: false,
-  });
-
-  // Gmail credentials directory (for Gmail MCP inside the container)
-  const gmailDir = path.join(homeDir, '.gmail-mcp');
-  if (fs.existsSync(gmailDir)) {
-    mounts.push({
-      hostPath: gmailDir,
-      containerPath: '/home/node/.gmail-mcp',
-      readonly: false, // MCP may need to refresh OAuth tokens
-    });
-  }
-
-  // Per-group IPC namespace: each group gets its own IPC directory
-  // This prevents cross-group privilege escalation via IPC
-  const groupIpcDir = resolveGroupIpcPath(group.folder);
-  fs.mkdirSync(path.join(groupIpcDir, 'messages'), { recursive: true });
-  fs.mkdirSync(path.join(groupIpcDir, 'tasks'), { recursive: true });
-  fs.mkdirSync(path.join(groupIpcDir, 'input'), { recursive: true });
-  mounts.push({
-    hostPath: groupIpcDir,
-    containerPath: '/workspace/ipc',
-    readonly: false,
-  });
-
-  // Copy agent-runner source into a per-group writable location so agents
-  // can customize it (add tools, change behavior) without affecting other
-  // groups. Recompiled on container startup via entrypoint.sh.
-  const agentRunnerSrc = path.join(projectRoot, 'container', 'agent-runner', 'src');
-  const groupAgentRunnerDir = path.join(DATA_DIR, 'sessions', group.folder, 'agent-runner-src');
-  if (!fs.existsSync(groupAgentRunnerDir) && fs.existsSync(agentRunnerSrc)) {
-    fs.cpSync(agentRunnerSrc, groupAgentRunnerDir, { recursive: true });
-  }
-  mounts.push({
-    hostPath: groupAgentRunnerDir,
-    containerPath: '/app/src',
-    readonly: false,
-  });
-
-  // Additional mounts validated against external allowlist (tamper-proof from containers)
-  if (group.containerConfig?.additionalMounts) {
-    const validatedMounts = validateAdditionalMounts(
-      group.containerConfig.additionalMounts,
-      group.name,
-      isMain,
-    );
-    mounts.push(...validatedMounts);
-  }
-
-  return mounts;
-}
-
-/**
- * Read allowed secrets from .env for passing to the container via stdin.
- * Secrets are never written to disk or mounted as files.
- */
-function readSecrets(): Record<string, string> {
-  return readEnvFile(['CLAUDE_CODE_OAUTH_TOKEN', 'ANTHROPIC_API_KEY']);
-}
-
-function buildContainerArgs(mounts: VolumeMount[], containerName: string): string[] {
-  const args: string[] = ['run', '-i', '--rm', '--name', containerName];
-
-  // Pass host timezone so container's local time matches the user's
-  args.push('-e', `TZ=${TIMEZONE}`);
-
-  // Run as host user so bind-mounted files are accessible.
-  // Skip when running as root (uid 0), as the container's node user (uid 1000),
-  // or when getuid is unavailable (native Windows without WSL).
-  const hostUid = process.getuid?.();
-  const hostGid = process.getgid?.();
-  if (hostUid != null && hostUid !== 0 && hostUid !== 1000) {
-    args.push('--user', `${hostUid}:${hostGid}`);
-    args.push('-e', 'HOME=/home/node');
-  }
-
-  for (const mount of mounts) {
-    if (mount.readonly) {
-      args.push(...readonlyMountArgs(mount.hostPath, mount.containerPath));
-    } else {
-      args.push('-v', `${mount.hostPath}:${mount.containerPath}`);
-    }
-  }
-
-  args.push(CONTAINER_IMAGE);
-
-  return args;
-}
-
-export async function runContainerAgent(
-  group: RegisteredGroup,
-  input: ContainerInput,
-  onProcess: (proc: ChildProcess, containerName: string) => void,
-  onOutput?: (output: ContainerOutput) => Promise<void>,
-): Promise<ContainerOutput> {
-  const startTime = Date.now();
-
-  const groupDir = resolveGroupFolderPath(group.folder);
-  fs.mkdirSync(groupDir, { recursive: true });
-
-  const mounts = buildVolumeMounts(group, input.isMain);
-  const safeName = group.folder.replace(/[^a-zA-Z0-9-]/g, '-');
-  const containerName = `nanoclaw-${safeName}-${Date.now()}`;
-  const containerArgs = buildContainerArgs(mounts, containerName);
-
-  logger.debug(
-    {
-      group: group.name,
-      containerName,
-      mounts: mounts.map(
-        (m) =>
-          `${m.hostPath} -> ${m.containerPath}${m.readonly ? ' (ro)' : ''}`,
-      ),
-      containerArgs: containerArgs.join(' '),
-    },
-    'Container mount configuration',
-  );
-
-  logger.info(
-    {
-      group: group.name,
-      containerName,
-      mountCount: mounts.length,
-      isMain: input.isMain,
-    },
-    'Spawning container agent',
-  );
-
-  const logsDir = path.join(groupDir, 'logs');
-  fs.mkdirSync(logsDir, { recursive: true });
-
-  return new Promise((resolve) => {
-    const container = spawn(CONTAINER_RUNTIME_BIN, containerArgs, {
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-
-    onProcess(container, containerName);
-
-    let stdout = '';
-    let stderr = '';
-    let stdoutTruncated = false;
-    let stderrTruncated = false;
-
-    // Pass secrets via stdin (never written to disk or mounted as files)
-    input.secrets = readSecrets();
-    container.stdin.write(JSON.stringify(input));
-    container.stdin.end();
-    // Remove secrets from input so they don't appear in logs
-    delete input.secrets;
-
-    // Streaming output: parse OUTPUT_START/END marker pairs as they arrive
-    let parseBuffer = '';
-    let newSessionId: string | undefined;
-    let outputChain = Promise.resolve();
-
-    container.stdout.on('data', (data) => {
-      const chunk = data.toString();
-
-      // Always accumulate for logging
-      if (!stdoutTruncated) {
-        const remaining = CONTAINER_MAX_OUTPUT_SIZE - stdout.length;
-        if (chunk.length > remaining) {
-          stdout += chunk.slice(0, remaining);
-          stdoutTruncated = true;
-          logger.warn(
-            { group: group.name, size: stdout.length },
-            'Container stdout truncated due to size limit',
-          );
-        } else {
-          stdout += chunk;
-        }
-      }
-
-      // Stream-parse for output markers
-      if (onOutput) {
-        parseBuffer += chunk;
-        let startIdx: number;
-        while ((startIdx = parseBuffer.indexOf(OUTPUT_START_MARKER)) !== -1) {
-          const endIdx = parseBuffer.indexOf(OUTPUT_END_MARKER, startIdx);
-          if (endIdx === -1) break; // Incomplete pair, wait for more data
-
-          const jsonStr = parseBuffer
-            .slice(startIdx + OUTPUT_START_MARKER.length, endIdx)
-            .trim();
-          parseBuffer = parseBuffer.slice(endIdx + OUTPUT_END_MARKER.length);
-
-          try {
-            const parsed: ContainerOutput = JSON.parse(jsonStr);
-            if (parsed.newSessionId) {
-              newSessionId = parsed.newSessionId;
-            }
-            hadStreamingOutput = true;
-            // Activity detected — reset the hard timeout
-            resetTimeout();
-            // Call onOutput for all markers (including null results)
-            // so idle timers start even for "silent" query completions.
-            outputChain = outputChain.then(() => onOutput(parsed));
-          } catch (err) {
-            logger.warn(
-              { group: group.name, error: err },
-              'Failed to parse streamed output chunk',
-            );
-          }
-        }
-      }
-    });
-
-    container.stderr.on('data', (data) => {
-      const chunk = data.toString();
-      const lines = chunk.trim().split('\n');
-      for (const line of lines) {
-        if (line) logger.debug({ container: group.folder }, line);
-      }
-      // Don't reset timeout on stderr — SDK writes debug logs continuously.
-      // Timeout only resets on actual output (OUTPUT_MARKER in stdout).
-      if (stderrTruncated) return;
-      const remaining = CONTAINER_MAX_OUTPUT_SIZE - stderr.length;
-      if (chunk.length > remaining) {
-        stderr += chunk.slice(0, remaining);
-        stderrTruncated = true;
-        logger.warn(
-          { group: group.name, size: stderr.length },
-          'Container stderr truncated due to size limit',
-        );
-      } else {
-        stderr += chunk;
-      }
-    });
-
-    let timedOut = false;
-    let hadStreamingOutput = false;
-    const configTimeout = group.containerConfig?.timeout || CONTAINER_TIMEOUT;
-    // Grace period: hard timeout must be at least IDLE_TIMEOUT + 30s so the
-    // graceful _close sentinel has time to trigger before the hard kill fires.
-    const timeoutMs = Math.max(configTimeout, IDLE_TIMEOUT + 30_000);
-
-    const killOnTimeout = () => {
-      timedOut = true;
-      logger.error({ group: group.name, containerName }, 'Container timeout, stopping gracefully');
-      exec(stopContainer(containerName), { timeout: 15000 }, (err) => {
-        if (err) {
-          logger.warn({ group: group.name, containerName, err }, 'Graceful stop failed, force killing');
-          container.kill('SIGKILL');
-        }
-      });
-    };
-
-    let timeout = setTimeout(killOnTimeout, timeoutMs);
-
-    // Reset the timeout whenever there's activity (streaming output)
-    const resetTimeout = () => {
-      clearTimeout(timeout);
-      timeout = setTimeout(killOnTimeout, timeoutMs);
-    };
-
-    container.on('close', (code) => {
-      clearTimeout(timeout);
-      const duration = Date.now() - startTime;
-
-      if (timedOut) {
-        const ts = new Date().toISOString().replace(/[:.]/g, '-');
-        const timeoutLog = path.join(logsDir, `container-${ts}.log`);
-        fs.writeFileSync(timeoutLog, [
-          `=== Container Run Log (TIMEOUT) ===`,
-          `Timestamp: ${new Date().toISOString()}`,
-          `Group: ${group.name}`,
-          `Container: ${containerName}`,
-          `Duration: ${duration}ms`,
-          `Exit Code: ${code}`,
-          `Had Streaming Output: ${hadStreamingOutput}`,
-        ].join('\n'));
-
-        // Timeout after output = idle cleanup, not failure.
-        // The agent already sent its response; this is just the
-        // container being reaped after the idle period expired.
-        if (hadStreamingOutput) {
-          logger.info(
-            { group: group.name, containerName, duration, code },
-            'Container timed out after output (idle cleanup)',
-          );
-          outputChain.then(() => {
-            resolve({
-              status: 'success',
-              result: null,
-              newSessionId,
-            });
-          });
-          return;
-        }
-
-        logger.error(
-          { group: group.name, containerName, duration, code },
-          'Container timed out with no output',
-        );
-
-        resolve({
-          status: 'error',
-          result: null,
-          error: `Container timed out after ${configTimeout}ms`,
-        });
-        return;
-      }
-
-      const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-      const logFile = path.join(logsDir, `container-${timestamp}.log`);
-      const isVerbose = process.env.LOG_LEVEL === 'debug' || process.env.LOG_LEVEL === 'trace';
-
-      const logLines = [
-        `=== Container Run Log ===`,
-        `Timestamp: ${new Date().toISOString()}`,
-        `Group: ${group.name}`,
-        `IsMain: ${input.isMain}`,
-        `Duration: ${duration}ms`,
-        `Exit Code: ${code}`,
-        `Stdout Truncated: ${stdoutTruncated}`,
-        `Stderr Truncated: ${stderrTruncated}`,
-        ``,
-      ];
-
-      const isError = code !== 0;
-
-      if (isVerbose || isError) {
-        logLines.push(
-          `=== Input ===`,
-          JSON.stringify(input, null, 2),
-          ``,
-          `=== Container Args ===`,
-          containerArgs.join(' '),
-          ``,
-          `=== Mounts ===`,
-          mounts
-            .map(
-              (m) =>
-                `${m.hostPath} -> ${m.containerPath}${m.readonly ? ' (ro)' : ''}`,
-            )
-            .join('\n'),
-          ``,
-          `=== Stderr${stderrTruncated ? ' (TRUNCATED)' : ''} ===`,
-          stderr,
-          ``,
-          `=== Stdout${stdoutTruncated ? ' (TRUNCATED)' : ''} ===`,
-          stdout,
-        );
-      } else {
-        logLines.push(
-          `=== Input Summary ===`,
-          `Prompt length: ${input.prompt.length} chars`,
-          `Session ID: ${input.sessionId || 'new'}`,
-          ``,
-          `=== Mounts ===`,
-          mounts
-            .map((m) => `${m.containerPath}${m.readonly ? ' (ro)' : ''}`)
-            .join('\n'),
-          ``,
-        );
-      }
-
-      fs.writeFileSync(logFile, logLines.join('\n'));
-      logger.debug({ logFile, verbose: isVerbose }, 'Container log written');
-
-      if (code !== 0) {
-        logger.error(
-          {
-            group: group.name,
-            code,
-            duration,
-            stderr,
-            stdout,
-            logFile,
-          },
-          'Container exited with error',
-        );
-
-        resolve({
-          status: 'error',
-          result: null,
-          error: `Container exited with code ${code}: ${stderr.slice(-200)}`,
-        });
-        return;
-      }
-
-      // Streaming mode: wait for output chain to settle, return completion marker
-      if (onOutput) {
-        outputChain.then(() => {
-          logger.info(
-            { group: group.name, duration, newSessionId },
-            'Container completed (streaming mode)',
-          );
-          resolve({
-            status: 'success',
-            result: null,
-            newSessionId,
-          });
-        });
-        return;
-      }
-
-      // Legacy mode: parse the last output marker pair from accumulated stdout
-      try {
-        // Extract JSON between sentinel markers for robust parsing
-        const startIdx = stdout.indexOf(OUTPUT_START_MARKER);
-        const endIdx = stdout.indexOf(OUTPUT_END_MARKER);
-
-        let jsonLine: string;
-        if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
-          jsonLine = stdout
-            .slice(startIdx + OUTPUT_START_MARKER.length, endIdx)
-            .trim();
-        } else {
-          // Fallback: last non-empty line (backwards compatibility)
-          const lines = stdout.trim().split('\n');
-          jsonLine = lines[lines.length - 1];
-        }
-
-        const output: ContainerOutput = JSON.parse(jsonLine);
-
-        logger.info(
-          {
-            group: group.name,
-            duration,
-            status: output.status,
-            hasResult: !!output.result,
-          },
-          'Container completed',
-        );
-
-        resolve(output);
-      } catch (err) {
-        logger.error(
-          {
-            group: group.name,
-            stdout,
-            stderr,
-            error: err,
-          },
-          'Failed to parse container output',
-        );
-
-        resolve({
-          status: 'error',
-          result: null,
-          error: `Failed to parse container output: ${err instanceof Error ? err.message : String(err)}`,
-        });
-      }
-    });
-
-    container.on('error', (err) => {
-      clearTimeout(timeout);
-      logger.error({ group: group.name, containerName, error: err }, 'Container spawn error');
-      resolve({
-        status: 'error',
-        result: null,
-        error: `Container spawn error: ${err.message}`,
-      });
-    });
-  });
-}
-
-export function writeTasksSnapshot(
-  groupFolder: string,
-  isMain: boolean,
-  tasks: Array<{
-    id: string;
-    groupFolder: string;
-    prompt: string;
-    schedule_type: string;
-    schedule_value: string;
-    status: string;
-    next_run: string | null;
-  }>,
-): void {
-  // Write filtered tasks to the group's IPC directory
-  const groupIpcDir = resolveGroupIpcPath(groupFolder);
-  fs.mkdirSync(groupIpcDir, { recursive: true });
-
-  // Main sees all tasks, others only see their own
-  const filteredTasks = isMain
-    ? tasks
-    : tasks.filter((t) => t.groupFolder === groupFolder);
-
-  const tasksFile = path.join(groupIpcDir, 'current_tasks.json');
-  fs.writeFileSync(tasksFile, JSON.stringify(filteredTasks, null, 2));
-}
-
-export interface AvailableGroup {
-  jid: string;
-  name: string;
-  lastActivity: string;
-  isRegistered: boolean;
-}
-
-/**
- * Write available groups snapshot for the container to read.
- * Only main group can see all available groups (for activation).
- * Non-main groups only see their own registration status.
- */
-export function writeGroupsSnapshot(
-  groupFolder: string,
-  isMain: boolean,
-  groups: AvailableGroup[],
-  registeredJids: Set<string>,
-): void {
-  const groupIpcDir = resolveGroupIpcPath(groupFolder);
-  fs.mkdirSync(groupIpcDir, { recursive: true });
-
-  // Main sees all groups; others see nothing (they can't activate groups)
-  const visibleGroups = isMain ? groups : [];
-
-  const groupsFile = path.join(groupIpcDir, 'available_groups.json');
-  fs.writeFileSync(
-    groupsFile,
-    JSON.stringify(
-      {
-        groups: visibleGroups,
-        lastSync: new Date().toISOString(),
-      },
-      null,
-      2,
-    ),
-  );
-}

.claude/skills/add-gmail/modify/src/container-runner.ts.intent.md

@@ -1,37 +0,0 @@
-# Intent: src/container-runner.ts modifications
-
-## What changed
-Added a volume mount for Gmail OAuth credentials (`~/.gmail-mcp/`) so the Gmail MCP server inside the container can authenticate with Google.
-
-## Key sections
-
-### buildVolumeMounts()
-- Added: Gmail credentials mount after the `.claude` sessions mount:
-  ```
-  const gmailDir = path.join(homeDir, '.gmail-mcp');
-  if (fs.existsSync(gmailDir)) {
-    mounts.push({
-      hostPath: gmailDir,
-      containerPath: '/home/node/.gmail-mcp',
-      readonly: false,  // MCP may need to refresh OAuth tokens
-    });
-  }
-  ```
-- Uses `os.homedir()` to resolve the home directory
-- Mount is read-write because the Gmail MCP server needs to refresh OAuth tokens
-- Mount is conditional — only added if `~/.gmail-mcp/` exists on the host
-
-### Imports
-- Added: `os` import for `os.homedir()`
-
-## Invariants
-- All existing mounts are unchanged
-- Mount ordering is preserved (Gmail added after session mounts, before additional mounts)
-- The `buildContainerArgs`, `runContainerAgent`, and all other functions are untouched
-- Additional mount validation via `validateAdditionalMounts` is unchanged
-
-## Must-keep
-- All existing volume mounts (project root, group dir, global, sessions, IPC, agent-runner, additional)
-- The mount security model (allowlist validation for additional mounts)
-- The `readSecrets` function and stdin-based secret passing
-- Container lifecycle (spawn, timeout, output parsing)

.claude/skills/add-gmail/tests/gmail.test.ts

@@ -1,98 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import fs from 'fs';
-import path from 'path';
-
-describe('add-gmail skill package', () => {
-  const skillDir = path.resolve(__dirname, '..');
-
-  it('has a valid manifest', () => {
-    const manifestPath = path.join(skillDir, 'manifest.yaml');
-    expect(fs.existsSync(manifestPath)).toBe(true);
-
-    const content = fs.readFileSync(manifestPath, 'utf-8');
-    expect(content).toContain('skill: gmail');
-    expect(content).toContain('version: 1.0.0');
-    expect(content).toContain('googleapis');
-  });
-
-  it('has channel file with self-registration', () => {
-    const channelFile = path.join(
-      skillDir,
-      'add',
-      'src',
-      'channels',
-      'gmail.ts',
-    );
-    expect(fs.existsSync(channelFile)).toBe(true);
-
-    const content = fs.readFileSync(channelFile, 'utf-8');
-    expect(content).toContain('class GmailChannel');
-    expect(content).toContain('implements Channel');
-    expect(content).toContain("registerChannel('gmail'");
-  });
-
-  it('has channel barrel file modification', () => {
-    const indexFile = path.join(
-      skillDir,
-      'modify',
-      'src',
-      'channels',
-      'index.ts',
-    );
-    expect(fs.existsSync(indexFile)).toBe(true);
-
-    const indexContent = fs.readFileSync(indexFile, 'utf-8');
-    expect(indexContent).toContain("import './gmail.js'");
-  });
-
-  it('has intent files for modified files', () => {
-    expect(
-      fs.existsSync(
-        path.join(skillDir, 'modify', 'src', 'channels', 'index.ts.intent.md'),
-      ),
-    ).toBe(true);
-  });
-
-  it('has container-runner mount modification', () => {
-    const crFile = path.join(
-      skillDir,
-      'modify',
-      'src',
-      'container-runner.ts',
-    );
-    expect(fs.existsSync(crFile)).toBe(true);
-
-    const content = fs.readFileSync(crFile, 'utf-8');
-    expect(content).toContain('.gmail-mcp');
-  });
-
-  it('has agent-runner Gmail MCP server modification', () => {
-    const arFile = path.join(
-      skillDir,
-      'modify',
-      'container',
-      'agent-runner',
-      'src',
-      'index.ts',
-    );
-    expect(fs.existsSync(arFile)).toBe(true);
-
-    const content = fs.readFileSync(arFile, 'utf-8');
-    expect(content).toContain('mcp__gmail__*');
-    expect(content).toContain('@gongrzhe/server-gmail-autoauth-mcp');
-  });
-
-  it('has test file for the channel', () => {
-    const testFile = path.join(
-      skillDir,
-      'add',
-      'src',
-      'channels',
-      'gmail.test.ts',
-    );
-    expect(fs.existsSync(testFile)).toBe(true);
-
-    const testContent = fs.readFileSync(testFile, 'utf-8');
-    expect(testContent).toContain("describe('GmailChannel'");
-  });
-});

.claude/skills/add-image-vision/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: add-image-vision
+description: Add image vision to NanoClaw agents. Resizes and processes WhatsApp image attachments, then sends them to Claude as multimodal content blocks.
+---
+
+# Image Vision Skill
+
+Adds the ability for NanoClaw agents to see and understand images sent via WhatsApp. Images are downloaded, resized with sharp, saved to the group workspace, and passed to the agent as base64-encoded multimodal content blocks.
+
+## Phase 1: Pre-flight
+
+1. Check if `src/image.ts` exists — skip to Phase 3 if already applied
+2. Confirm `sharp` is installable (native bindings require build tools)
+
+**Prerequisite:** WhatsApp must be installed first (`skill/whatsapp` merged). This skill modifies WhatsApp channel files.
+
+## Phase 2: Apply Code Changes
+
+### Ensure WhatsApp fork remote
+
+```bash
+git remote -v
+```
+
+If `whatsapp` is missing, add it:
+
+```bash
+git remote add whatsapp https://github.com/qwibitai/nanoclaw-whatsapp.git
+```
+
+### Merge the skill branch
+
+```bash
+git fetch whatsapp skill/image-vision
+git merge whatsapp/skill/image-vision || {
+  git checkout --theirs pnpm-lock.yaml
+  git add pnpm-lock.yaml
+  git merge --continue
+}
+```
+
+This merges in:
+- `src/image.ts` (image download, resize via sharp, base64 encoding)
+- `src/image.test.ts` (8 unit tests)
+- Image attachment handling in `src/channels/whatsapp.ts`
+- Image passing to agent in `src/index.ts` and `src/container-runner.ts`
+- Image content block support in `container/agent-runner/src/index.ts`
+- `sharp` npm dependency in `package.json`
+
+If the merge reports conflicts, resolve them by reading the conflicted files and understanding the intent of both sides.
+
+### Validate code changes
+
+```bash
+pnpm install
+pnpm run build
+pnpm exec vitest run src/image.test.ts
+```
+
+All tests must pass and build must be clean before proceeding.
+
+## Phase 3: Configure
+
+1. Rebuild the container (agent-runner changes need a rebuild):
+   ```bash
+   ./container/build.sh
+   ```
+
+2. Sync agent-runner source to group caches:
+   ```bash
+   for dir in data/sessions/*/agent-runner-src/; do
+     cp container/agent-runner/src/*.ts "$dir"
+   done
+   ```
+
+3. Restart the service:
+   ```bash
+   launchctl kickstart -k gui/$(id -u)/com.nanoclaw
+   ```
+
+## Phase 4: Verify
+
+1. Send an image in a registered WhatsApp group
+2. Check the agent responds with understanding of the image content
+3. Check logs for "Processed image attachment":
+   ```bash
+   tail -50 groups/*/logs/container-*.log
+   ```
+
+## Troubleshooting
+
+- **"Image - download failed"**: Check WhatsApp connection stability. The download may timeout on slow connections.
+- **"Image - processing failed"**: Sharp may not be installed correctly. Run `pnpm ls sharp` to verify.
+- **Agent doesn't mention image content**: Check container logs for "Loaded image" messages. If missing, ensure agent-runner source was synced to group caches.

.claude/skills/add-imessage-v2/REMOVE.md

@@ -0,0 +1,6 @@
+# Remove iMessage Channel
+
+1. Comment out `import './imessage.js'` in `src/channels/index.ts`
+2. Remove iMessage env vars (`IMESSAGE_ENABLED`, `IMESSAGE_LOCAL`, `IMESSAGE_SERVER_URL`, `IMESSAGE_API_KEY`) from `.env`
+3. `pnpm uninstall chat-adapter-imessage`
+4. Rebuild and restart

.claude/skills/add-imessage-v2/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: add-imessage-v2
+description: Add iMessage channel integration to NanoClaw v2 via Chat SDK. Local (macOS) or remote (Photon API) mode.
+---
+
+# Add iMessage Channel
+
+Adds iMessage support to NanoClaw v2 using the Chat SDK bridge. Two modes: local (macOS with Full Disk Access) or remote (Photon API).
+
+## Pre-flight
+
+Check if `src/channels/imessage.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Credentials.
+
+## Install
+
+```bash
+pnpm install chat-adapter-imessage
+```
+
+Uncomment the iMessage import in `src/channels/index.ts`:
+
+```typescript
+import './imessage.js';
+```
+
+```bash
+pnpm run build
+```
+
+## Credentials
+
+### Local Mode (macOS)
+
+Requirements: macOS with Full Disk Access granted to the Node.js binary.
+
+The Node binary path is buried deep (e.g. `~/.nvm/versions/node/v22.x.x/bin/node`). To make it easy, open the folder in Finder so the user can drag the file into System Settings:
+
+```bash
+open "$(dirname "$(which node)")"
+```
+
+Then tell the user:
+
+1. Open **System Settings** > **Privacy & Security** > **Full Disk Access**
+2. Click **+**, then drag the `node` file from the Finder window that just opened
+3. Toggle it on
+
+Stop and wait for the user to confirm before continuing.
+
+### Remote Mode (Photon API)
+
+1. Set up a [Photon](https://photon.im) account
+2. Get your server URL and API key
+
+### Configure environment
+
+**Local mode** -- add to `.env`:
+
+```bash
+IMESSAGE_ENABLED=true
+IMESSAGE_LOCAL=true
+```
+
+**Remote mode** -- add to `.env`:
+
+```bash
+IMESSAGE_LOCAL=false
+IMESSAGE_SERVER_URL=https://your-photon-server.com
+IMESSAGE_API_KEY=your-api-key
+```
+
+Sync to container: `mkdir -p data/env && cp .env data/env/env`
+
+## Next Steps
+
+If you're in the middle of `/setup`, return to the setup flow now.
+
+Otherwise, run `/manage-channels` to wire this channel to an agent group.
+
+## Channel Info
+
+- **type**: `imessage`
+- **terminology**: iMessage has "conversations." Each conversation is with a contact identified by phone number or email address. Group chats are also supported.
+- **how-to-find-id**: The platform ID is the contact's phone number (e.g. `+15551234567`) or email address. For group chats, the ID is assigned by iMessage internally.
+- **supports-threads**: no
+- **typical-use**: Interactive 1:1 chat — personal messaging
+- **default-isolation**: Same agent group if you're the only person messaging the bot across iMessage and other channels. Separate agent group if different contacts should have information isolation.

.claude/skills/add-imessage-v2/VERIFY.md

@@ -0,0 +1,3 @@
+# Verify iMessage Channel
+
+Send an iMessage to the account running NanoClaw. The bot should respond within a few seconds.

.claude/skills/add-karpathy-llm-wiki/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: add-karpathy-llm-wiki
+description: Add a persistent wiki knowledge base to a NanoClaw group. Based on Karpathy's LLM Wiki pattern. Triggers on "add wiki", "wiki", "knowledge base", "llm wiki", "karpathy wiki".
+---
+
+# Add Karpathy LLM Wiki
+
+Set up a persistent wiki knowledge base on NanoClaw, based on Karpathy's LLM Wiki pattern.
+
+## Step 1: Read the pattern
+
+Read `${CLAUDE_SKILL_DIR}/llm-wiki.md` — this is the full LLM Wiki idea as written by Karpathy. Understand it thoroughly before proceeding. Summarize the core idea to the user briefly, then discuss what they want to build.
+
+## Step 2: Choose a group
+
+AskUserQuestion: "Which group should have the wiki?"
+
+1. **Main group** — add to your existing main chat
+2. **Dedicated group** — create a new group just for the wiki
+3. **Other** — pick an existing group
+
+If dedicated: ask which channel and chat, then register with `pnpm exec tsx setup/index.ts --step register`.
+
+## Step 3: Design collaboratively
+
+Discuss with the user based on the pattern:
+- What's the wiki's domain or topic?
+- What kinds of sources will they add? (URLs, PDFs, images, voice notes, books, transcripts)
+- Do they want the full three-layer architecture or a lighter version?
+- Any specific conventions they care about? (The pattern intentionally leaves this open.)
+
+Based on this discussion, create three things:
+
+### 3a. Directory structure
+
+Create `wiki/` and `sources/` directories in the group folder. Create initial `index.md` and `log.md` per the pattern's Indexing and Logging section. Adapt to the user's domain.
+
+### 3b. Container skill
+
+Create a `container/skills/wiki/SKILL.md` tailored to this user's wiki. This is the schema layer from the pattern — it tells the agent how to maintain the wiki. Base it on the pattern's Operations section (ingest, query, lint) and the conventions you agreed on with the user. Don't over-prescribe — the pattern says "your LLM figures out the rest."
+
+### 3c. Group CLAUDE.md
+
+Edit the group's CLAUDE.md to add a wiki section. This is critical — it's what turns the agent into a wiki maintainer. It should:
+
+- Explain the wiki system concisely: what it is, the three layers (sources, wiki, schema), the three operations (ingest, query, lint)
+- Index the key files and folders (`wiki/`, `sources/`, `wiki/index.md`, `wiki/log.md`)
+- Point to the container skill for detailed workflow
+- **Ingest discipline:** Be very explicit that when the user provides multiple files or points at a folder with many files, the agent MUST process them one at a time. For each file: read it, discuss takeaways, create/update all wiki pages (summary, entities, concepts, cross-references, index, log), and completely finish with that file before moving to the next. Never batch-read all files and then process them together — this produces shallow, generic pages instead of the deep integration the pattern requires.
+
+## Step 4: Source handling capabilities
+
+Based on the source types the user plans to ingest (discussed in Step 3), check whether the agent can already handle those formats — some are supported natively, others need a skill (e.g. `/add-image-vision`, `/add-pdf-reader`, `/add-voice-transcription`). If a needed capability isn't installed, check if there's an available skill for it and help the user get it set up.
+
+### URL handling note
+
+claude has built-in `WebFetch`, but it returns a summary, not the full document. For wiki ingestion of a URL where the full text matters, the container skill and CLAUDE.md should instruct claude to use bash commands to download full files instead. For example:
+
+```bash
+curl -sLo sources/filename.pdf "<url>"
+```
+
+If the document is a webpage, then claude can use fetch or `agent-browser` to open the page and extract full text if available. The container skill and CLAUDE.md should note this so claude gets full content for sources rather than summaries.
+
+
+## Step 5: Optional lint schedule
+
+AskUserQuestion: "Want periodic wiki health checks?"
+
+1. **Weekly**
+2. **Monthly**
+3. **Skip** — lint manually
+
+If yes, create a NanoClaw scheduled task that runs in the wiki group. This is NOT a Claude Code cron job — it's a NanoClaw group task that runs in the agent container. Insert it into the SQLite database:
+
+```bash
+pnpm exec tsx -e "
+const Database = require('better-sqlite3');
+const { CronExpressionParser } = require('cron-parser');
+const db = new Database('store/messages.db');
+const interval = CronExpressionParser.parse('<cron-expr>', { tz: process.env.TZ || 'UTC' });
+const nextRun = interval.next().toISOString();
+db.prepare('INSERT INTO scheduled_tasks (id, group_folder, chat_jid, prompt, schedule_type, schedule_value, context_mode, next_run, status, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)').run(
+  'wiki-lint',
+  '<group_folder>',
+  '<chat_jid>',
+  'Run a wiki lint pass per the wiki container skill. Check for contradictions, orphan pages, stale content, missing cross-references, and gaps. Report findings and offer to fix issues.',
+  'cron',
+  '<cron-expr>',
+  'group',
+  nextRun,
+  'active',
+  new Date().toISOString()
+);
+db.close();
+"
+```
+
+Use the group's `folder` and `chat_jid` from the registered groups table. Cron expressions: `0 10 * * 0` (weekly Sunday 10am) or `0 10 1 * *` (monthly 1st at 10am).
+
+## Step 6: Build and restart
+
+```bash
+pnpm run build
+./container/build.sh
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
+# Linux: systemctl --user restart nanoclaw
+```
+
+Tell the user to test by sending a source to the wiki group.

.claude/skills/add-karpathy-llm-wiki/llm-wiki.md

@@ -0,0 +1,75 @@
+# LLM Wiki
+
+> Source: [karpathy/llm-wiki.md](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
+
+A pattern for building personal knowledge bases using LLMs.
+
+This is an idea file, designed to be copied to your own LLM Agent (e.g. OpenAI Codex, Claude Code, OpenCode / Pi, etc.). Its goal is to communicate the high-level idea, with your agent building out specifics through collaboration with you.
+
+## The Core Idea
+
+Most interactions with LLMs and documents follow RAG patterns: upload files, retrieve relevant chunks at query time, generate answers. The knowledge is re-derived on each question with no accumulation.
+
+The concept here differs fundamentally. Rather than just retrieving from raw documents, the LLM incrementally builds and maintains a persistent wiki — a structured, interlinked markdown collection sitting between you and raw sources. When adding new material, the LLM reads it, extracts key information, and integrates it into existing wiki pages—updating entities, revising summaries, flagging contradictions, strengthening synthesis. Knowledge compiles once and stays current rather than re-deriving on every query.
+
+The wiki becomes a persistent, compounding artifact. Cross-references already exist. Contradictions are flagged. Synthesis reflects everything read. The wiki enriches with every source added and question asked.
+
+You source material and ask questions; the LLM maintains everything—summarizing, cross-referencing, filing, and organizing. The LLM acts as programmer; Obsidian serves as IDE; the wiki functions as codebase.
+
+**Applications include:**
+- Personal: tracking goals, health, self-improvement
+- Research: deep dives over weeks/months
+- Reading: building companion wikis while progressing through books
+- Business/teams: internal wikis fed by Slack, transcripts, documents
+- Analysis: competitive research, due diligence, trip planning, hobby deep-dives
+
+## Architecture
+
+Three layers comprise the system:
+
+**Raw sources** — immutable curated documents (articles, papers, images, data). The LLM reads but never modifies these.
+
+**The wiki** — LLM-generated markdown directories containing summaries, entity pages, concept pages, comparisons, syntheses. The LLM owns this entirely, creating and updating pages while maintaining cross-references and consistency.
+
+**The schema** — configuration document (e.g., CLAUDE.md) explaining wiki structure, conventions, and workflows for ingestion, querying, and maintenance. This key file transforms the LLM into disciplined wiki maintainer rather than generic chatbot.
+
+## Operations
+
+**Ingest:** Drop new sources into the raw collection; the LLM processes them. The agent reads sources, discusses takeaways, writes summaries, updates indexes, refreshes entity and concept pages, logs entries. Single sources might touch 10-15 wiki pages. Prefer ingesting individually while staying involved, though batch ingestion with less oversight is possible.
+
+**Query:** Ask questions against the wiki. The LLM searches relevant pages, synthesizes answers with citations. Answers take various forms—markdown pages, comparison tables, slide decks, charts, canvas. Good answers can be filed back into the wiki as new pages—explorations compound in the knowledge base rather than disappearing into chat history.
+
+**Lint:** Periodically health-check the wiki. Look for contradictions, stale claims superseded by newer sources, orphan pages lacking inbound links, important concepts lacking dedicated pages, missing cross-references, data gaps. The LLM suggests investigations and sources to pursue, keeping the wiki healthy as it grows.
+
+## Indexing and Logging
+
+Two special files help navigate the growing wiki:
+
+**index.md** — content-oriented catalog of everything (each page with link, one-line summary, optional metadata like dates or source counts), organized by category. The LLM updates it on every ingest. When answering queries, read the index first to locate relevant pages before drilling deeper. This approach works surprisingly well at moderate scale (~100 sources, ~hundreds of pages) while avoiding embedding-based RAG infrastructure needs.
+
+**log.md** — append-only chronological record of what happened and when (ingests, queries, lint passes). Each entry beginning with consistent prefix (e.g., `## [2026-04-02] ingest | Article Title`) becomes parseable with simple tools—`grep "^## \[" log.md | tail -5` yields last 5 entries. The log shows wiki evolution timeline and helps the LLM understand recent activity.
+
+## Optional: CLI Tools
+
+At scale, small tools help the LLM operate more efficiently. Search engine over wiki pages is most obvious—at small scale the index suffices, but as the wiki grows, proper search becomes necessary. qmd (https://github.com/tobi/qmd) offers local search with hybrid BM25/vector search and LLM re-ranking, entirely on-device. It includes both CLI (so LLMs can shell out) and MCP server (native tool integration). Build simpler custom search scripts as needs arise.
+
+## Tips and Tricks
+
+- **Obsidian Web Clipper** converts web articles to markdown for quick source collection
+- **Download images locally:** Set attachment folder in Obsidian Settings, bind download hotkey. All images store locally; LLM views and references directly instead of relying on potentially broken URLs
+- **Obsidian's graph view** visualizes wiki connectivity—what connects to what, hub pages, orphans
+- **Marp** provides markdown-based slide deck format with Obsidian plugin integration
+- **Dataview** plugin queries page frontmatter, generating dynamic tables/lists when LLM adds YAML frontmatter
+- The wiki is simply a git-backed markdown directory—version history, branching, collaboration included
+
+## Why This Works
+
+Knowledge base maintenance's tedious part is bookkeeping, not reading/thinking: updating cross-references, keeping summaries current, noting data contradictions, maintaining consistency across pages. Humans abandon wikis as maintenance burden outpaces value. LLMs don't bore, don't forget updates, can touch 15 files in one pass. Wiki maintenance becomes nearly free.
+
+Humans curate sources, direct analysis, ask good questions, think about meaning. LLMs handle everything else.
+
+This relates in spirit to Vannevar Bush's 1945 Memex—personal curated knowledge stores with associative document trails. Bush's vision resembled this more than what the web became: private, actively curated, with connections between documents as valuable as documents themselves. Bush couldn't solve maintenance; LLMs handle that.
+
+## Note
+
+This document intentionally remains abstract, describing the idea rather than specific implementation. Directory structure, schema conventions, page formats, tooling—all depend on domain, preferences, and LLM choice. Everything is optional and modular. Pick what's useful; ignore what isn't. Your sources might be text-only (no image handling needed). Your wiki might stay small enough that index files suffice (no search engine required). You might want different output formats entirely. Share this with your LLM agent and work collaboratively to instantiate a version fitting your needs. This document's sole purpose is communicating the pattern; your LLM figures out the rest.

.claude/skills/add-linear-v2/REMOVE.md

@@ -0,0 +1,6 @@
+# Remove Linear Channel
+
+1. Comment out `import './linear.js'` in `src/channels/index.ts`
+2. Remove `LINEAR_API_KEY` and `LINEAR_WEBHOOK_SECRET` from `.env`
+3. `pnpm uninstall @chat-adapter/linear`
+4. Rebuild and restart

.claude/skills/add-linear-v2/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: add-linear-v2
+description: Add Linear channel integration to NanoClaw v2 via Chat SDK. Issue comment threads as conversations.
+---
+
+# Add Linear Channel
+
+Adds Linear support to NanoClaw v2 using the Chat SDK bridge. The agent participates in issue comment threads.
+
+## Pre-flight
+
+Check if `src/channels/linear.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Credentials.
+
+## Install
+
+```bash
+pnpm install @chat-adapter/linear
+```
+
+Uncomment the Linear import in `src/channels/index.ts`:
+
+```typescript
+import './linear.js';
+```
+
+```bash
+pnpm run build
+```
+
+## Credentials
+
+> 1. Go to [Linear Settings > API Keys](https://linear.app/settings/account/security/api-keys/new)
+> 2. Create a **Personal API Key** (or use an OAuth application for team-wide access)
+> 3. Copy the API key
+> 4. Set up a webhook:
+>    - Go to **Settings** > **API** > **Webhooks** > **New webhook**
+>    - URL: `https://your-domain/webhook/linear`
+>    - Select events: **Comment** (created, updated)
+>    - Copy the signing secret
+
+### Configure environment
+
+Add to `.env`:
+
+```bash
+LINEAR_API_KEY=lin_api_...
+LINEAR_WEBHOOK_SECRET=your-webhook-secret
+```
+
+Sync to container: `mkdir -p data/env && cp .env data/env/env`
+
+## Next Steps
+
+If you're in the middle of `/setup`, return to the setup flow now.
+
+Otherwise, run `/manage-channels` to wire this channel to an agent group.
+
+## Channel Info
+
+- **type**: `linear`
+- **terminology**: Linear has "teams" containing "issues." Each issue's comment thread is a separate conversation.
+- **how-to-find-id**: The platform ID is your team key (e.g. `ENG`). Find it in Linear under Settings > Teams. Each issue becomes its own thread automatically.
+- **supports-threads**: yes (issue comment threads are native conversations)
+- **typical-use**: Webhook/notification — the agent receives issue comment events and responds in threads
+- **default-isolation**: Typically shares a session with a chat channel (e.g. Slack) so the agent can discuss issues in the same context as team chat. Use a separate agent group if the Linear team tracks sensitive work.

.claude/skills/add-linear-v2/VERIFY.md

@@ -0,0 +1,3 @@
+# Verify Linear Channel
+
+@mention the bot in a Linear issue comment. The bot should respond within a few seconds.

.claude/skills/add-macos-statusbar/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: add-macos-statusbar
+description: Add a macOS menu bar status indicator for NanoClaw. Shows a bolt icon with a green/red dot indicating whether NanoClaw is running, with Start, Stop, and Restart controls. macOS only.
+---
+
+# Add macOS Menu Bar Status Indicator
+
+Adds a persistent menu bar icon that shows NanoClaw's running status and lets the user
+start, stop, or restart the service — similar to how Docker Desktop appears in the menu bar.
+
+**macOS only.** Requires Xcode Command Line Tools (`swiftc`).
+
+## Phase 1: Pre-flight
+
+### Check platform
+
+If not on macOS, stop and tell the user:
+
+> This skill is macOS only. The menu bar status indicator uses AppKit and requires `swiftc` (Xcode Command Line Tools).
+
+### Check for swiftc
+
+```bash
+which swiftc
+```
+
+If not found, tell the user:
+
+> Xcode Command Line Tools are required. Install them by running:
+>
+> ```bash
+> xcode-select --install
+> ```
+>
+> Then re-run `/add-macos-statusbar`.
+
+### Check if already installed
+
+```bash
+launchctl list | grep com.nanoclaw.statusbar
+```
+
+If it returns a PID (not `-`), tell the user it's already installed and skip to Phase 3 (Verify).
+
+## Phase 2: Compile and Install
+
+### Compile the Swift binary
+
+The source lives in the skill directory. Compile it into `dist/`:
+
+```bash
+mkdir -p dist
+swiftc -O -o dist/statusbar "${CLAUDE_SKILL_DIR}/add/src/statusbar.swift"
+```
+
+This produces a small native binary at `dist/statusbar`.
+
+On macOS Sequoia or later, clear the quarantine attribute so the binary can run:
+
+```bash
+xattr -cr dist/statusbar
+```
+
+### Create the launchd plist
+
+Determine the absolute project root and home directory:
+
+```bash
+pwd
+echo $HOME
+```
+
+Create `~/Library/LaunchAgents/com.nanoclaw.statusbar.plist`, substituting the actual values
+for `{PROJECT_ROOT}` and `{HOME}`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.nanoclaw.statusbar</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>{PROJECT_ROOT}/dist/statusbar</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>HOME</key>
+        <string>{HOME}</string>
+    </dict>
+    <key>StandardOutPath</key>
+    <string>{PROJECT_ROOT}/logs/statusbar.log</string>
+    <key>StandardErrorPath</key>
+    <string>{PROJECT_ROOT}/logs/statusbar.error.log</string>
+</dict>
+</plist>
+```
+
+### Load the service
+
+```bash
+launchctl load ~/Library/LaunchAgents/com.nanoclaw.statusbar.plist
+```
+
+## Phase 3: Verify
+
+```bash
+launchctl list | grep com.nanoclaw.statusbar
+```
+
+The first column should show a PID (not `-`).
+
+Tell the user:
+
+> The bolt icon should now appear in your macOS menu bar. Click it to see NanoClaw's status and control the service.
+>
+> - **Green dot** — NanoClaw is running
+> - **Red dot** — NanoClaw is stopped
+>
+> Use **Restart** after making code changes, and **View Logs** to open the log file directly.
+
+## Removal
+
+```bash
+launchctl unload ~/Library/LaunchAgents/com.nanoclaw.statusbar.plist
+rm ~/Library/LaunchAgents/com.nanoclaw.statusbar.plist
+rm dist/statusbar
+```

.claude/skills/add-macos-statusbar/add/src/statusbar.swift

@@ -0,0 +1,147 @@
+import AppKit
+
+class StatusBarController: NSObject {
+    private var statusItem: NSStatusItem!
+    private var isRunning = false
+    private var timer: Timer?
+
+    private let plistPath = "\(NSHomeDirectory())/Library/LaunchAgents/com.nanoclaw.plist"
+
+    /// Derive the NanoClaw project root from the binary location.
+    /// The binary is compiled to {project}/dist/statusbar, so the parent of
+    /// the parent directory is the project root.
+    private static let projectRoot: String = {
+        let binary = URL(fileURLWithPath: CommandLine.arguments[0]).resolvingSymlinksInPath()
+        return binary.deletingLastPathComponent().deletingLastPathComponent().path
+    }()
+
+    override init() {
+        super.init()
+        setupStatusItem()
+        isRunning = checkRunning()
+        updateMenu()
+        // Poll every 5 seconds to reflect external state changes
+        timer = Timer.scheduledTimer(withTimeInterval: 5.0, repeats: true) { [weak self] _ in
+            guard let self else { return }
+            let current = self.checkRunning()
+            if current != self.isRunning {
+                self.isRunning = current
+                self.updateMenu()
+            }
+        }
+    }
+
+    private func setupStatusItem() {
+        statusItem = NSStatusBar.system.statusItem(withLength: NSStatusItem.variableLength)
+        if let button = statusItem.button {
+            if let image = NSImage(systemSymbolName: "bolt.fill", accessibilityDescription: "NanoClaw") {
+                image.isTemplate = true
+                button.image = image
+            } else {
+                button.title = "⚡"
+            }
+            button.toolTip = "NanoClaw"
+        }
+    }
+
+    private func checkRunning() -> Bool {
+        let task = Process()
+        task.launchPath = "/bin/launchctl"
+        task.arguments = ["list", "com.nanoclaw"]
+        let pipe = Pipe()
+        task.standardOutput = pipe
+        task.standardError = Pipe()
+        guard (try? task.run()) != nil else { return false }
+        task.waitUntilExit()
+        if task.terminationStatus != 0 { return false }
+        let output = String(data: pipe.fileHandleForReading.readDataToEndOfFile(), encoding: .utf8) ?? ""
+        // launchctl list output: "PID\tExitCode\tLabel" — "-" means not running
+        let pid = output.trimmingCharacters(in: .whitespacesAndNewlines).components(separatedBy: "\t").first ?? "-"
+        return pid != "-"
+    }
+
+    private func updateMenu() {
+        let menu = NSMenu()
+
+        // Status row with colored dot
+        let statusItem = NSMenuItem()
+        let dot = "● "
+        let dotColor: NSColor = isRunning ? .systemGreen : .systemRed
+        let attr = NSMutableAttributedString(string: dot, attributes: [.foregroundColor: dotColor])
+        let label = isRunning ? "NanoClaw is running" : "NanoClaw is stopped"
+        attr.append(NSAttributedString(string: label, attributes: [.foregroundColor: NSColor.labelColor]))
+        statusItem.attributedTitle = attr
+        statusItem.isEnabled = false
+        menu.addItem(statusItem)
+
+        menu.addItem(NSMenuItem.separator())
+
+        if isRunning {
+            let stop = NSMenuItem(title: "Stop", action: #selector(stopService), keyEquivalent: "")
+            stop.target = self
+            menu.addItem(stop)
+
+            let restart = NSMenuItem(title: "Restart", action: #selector(restartService), keyEquivalent: "r")
+            restart.target = self
+            menu.addItem(restart)
+        } else {
+            let start = NSMenuItem(title: "Start", action: #selector(startService), keyEquivalent: "")
+            start.target = self
+            menu.addItem(start)
+        }
+
+        menu.addItem(NSMenuItem.separator())
+
+        let logs = NSMenuItem(title: "View Logs", action: #selector(viewLogs), keyEquivalent: "")
+        logs.target = self
+        menu.addItem(logs)
+
+        self.statusItem.menu = menu
+    }
+
+    @objc private func startService() {
+        run("/bin/launchctl", ["load", plistPath])
+        refresh(after: 2)
+    }
+
+    @objc private func stopService() {
+        run("/bin/launchctl", ["unload", plistPath])
+        refresh(after: 2)
+    }
+
+    @objc private func restartService() {
+        let uid = getuid()
+        run("/bin/launchctl", ["kickstart", "-k", "gui/\(uid)/com.nanoclaw"])
+        refresh(after: 3)
+    }
+
+    @objc private func viewLogs() {
+        let logPath = "\(StatusBarController.projectRoot)/logs/nanoclaw.log"
+        NSWorkspace.shared.open(URL(fileURLWithPath: logPath))
+    }
+
+    private func refresh(after seconds: Double) {
+        DispatchQueue.main.asyncAfter(deadline: .now() + seconds) { [weak self] in
+            guard let self else { return }
+            self.isRunning = self.checkRunning()
+            self.updateMenu()
+        }
+    }
+
+    @discardableResult
+    private func run(_ path: String, _ args: [String]) -> Int32 {
+        let task = Process()
+        task.launchPath = path
+        task.arguments = args
+        task.standardOutput = Pipe()
+        task.standardError = Pipe()
+        try? task.run()
+        task.waitUntilExit()
+        return task.terminationStatus
+    }
+}
+
+let app = NSApplication.shared
+app.setActivationPolicy(.accessory)
+let controller = StatusBarController()
+app.run()

.claude/skills/add-matrix-v2/REMOVE.md

@@ -0,0 +1,6 @@
+# Remove Matrix Channel
+
+1. Comment out `import './matrix.js'` in `src/channels/index.ts`
+2. Remove `MATRIX_BASE_URL`, `MATRIX_ACCESS_TOKEN`, `MATRIX_USER_ID`, `MATRIX_BOT_USERNAME` from `.env`
+3. `pnpm uninstall @beeper/chat-adapter-matrix`
+4. Rebuild and restart

.claude/skills/add-matrix-v2/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: add-matrix-v2
+description: Add Matrix channel integration to NanoClaw v2 via Chat SDK. Works with any Matrix homeserver.
+---
+
+# Add Matrix Channel
+
+Adds Matrix support to NanoClaw v2 using the Chat SDK bridge.
+
+## Pre-flight
+
+Check if `src/channels/matrix.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Credentials.
+
+## Install
+
+```bash
+pnpm install @beeper/chat-adapter-matrix
+```
+
+Uncomment the Matrix import in `src/channels/index.ts`:
+
+```typescript
+import './matrix.js';
+```
+
+```bash
+pnpm run build
+```
+
+## Credentials
+
+1. Register a bot account on your Matrix homeserver (e.g., via Element)
+2. Get the homeserver URL (e.g., `https://matrix.org` or your self-hosted URL)
+3. Get an access token:
+   - In Element: **Settings** > **Help & About** > **Access Token** (advanced)
+   - Or via API: `curl -XPOST 'https://matrix.org/_matrix/client/r0/login' -d '{"type":"m.login.password","user":"botuser","password":"..."}'`
+4. Note the bot's user ID (e.g., `@botuser:matrix.org`)
+
+### Configure environment
+
+Add to `.env`:
+
+```bash
+MATRIX_BASE_URL=https://matrix.org
+MATRIX_ACCESS_TOKEN=your-access-token
+MATRIX_USER_ID=@botuser:matrix.org
+MATRIX_BOT_USERNAME=botuser
+```
+
+Sync to container: `mkdir -p data/env && cp .env data/env/env`
+
+## Next Steps
+
+If you're in the middle of `/setup`, return to the setup flow now.
+
+Otherwise, run `/manage-channels` to wire this channel to an agent group.
+
+## Channel Info
+
+- **type**: `matrix`
+- **terminology**: Matrix has "rooms." A room can be a group chat or a direct message. Rooms have internal IDs (like `!abc123:matrix.org`) and optional aliases (like `#general:matrix.org`).
+- **how-to-find-id**: In Element, click the room name > Settings > Advanced — the "Internal room ID" is the platform ID (starts with `!`). Or use a room alias like `#general:matrix.org`.
+- **supports-threads**: partial (some clients support threads, but not all — treat as no for reliability)
+- **typical-use**: Interactive chat — rooms or direct messages
+- **default-isolation**: Same agent group for rooms where you're the primary user. Separate agent group for rooms with different communities or sensitive contexts.

.claude/skills/add-matrix-v2/VERIFY.md

@@ -0,0 +1,3 @@
+# Verify Matrix Channel
+
+Invite the bot to a Matrix room and send a message. The bot should respond within a few seconds.

.claude/skills/add-ollama-tool/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: add-ollama-tool
+description: Add Ollama MCP server so the container agent can call local models and optionally manage the Ollama model library.
+---
+
+# Add Ollama Integration
+
+This skill adds a stdio-based MCP server that exposes local Ollama models as tools for the container agent. Claude remains the orchestrator but can offload work to local models, and can optionally manage the model library directly.
+
+Core tools (always available):
+- `ollama_list_models` — list installed Ollama models with name, size, and family
+- `ollama_generate` — send a prompt to a specified model and return the response
+
+Management tools (opt-in via `OLLAMA_ADMIN_TOOLS=true`):
+- `ollama_pull_model` — pull (download) a model from the Ollama registry
+- `ollama_delete_model` — delete a locally installed model to free disk space
+- `ollama_show_model` — show model details: modelfile, parameters, and architecture info
+- `ollama_list_running` — list models currently loaded in memory with memory usage and processor type
+
+## Phase 1: Pre-flight
+
+### Check if already applied
+
+Check if `container/agent-runner/src/ollama-mcp-stdio.ts` exists. If it does, skip to Phase 3 (Configure).
+
+### Check prerequisites
+
+Verify Ollama is installed and running on the host:
+
+```bash
+ollama list
+```
+
+If Ollama is not installed, direct the user to https://ollama.com/download.
+
+If no models are installed, suggest pulling one:
+
+> You need at least one model. I recommend:
+>
+> ```bash
+> ollama pull gemma3:1b    # Small, fast (1GB)
+> ollama pull llama3.2     # Good general purpose (2GB)
+> ollama pull qwen3-coder:30b  # Best for code tasks (18GB)
+> ```
+
+## Phase 2: Apply Code Changes
+
+### Ensure upstream remote
+
+```bash
+git remote -v
+```
+
+If `upstream` is missing, add it:
+
+```bash
+git remote add upstream https://github.com/qwibitai/nanoclaw.git
+```
+
+### Merge the skill branch
+
+```bash
+git fetch upstream skill/ollama-tool
+git merge upstream/skill/ollama-tool
+```
+
+This merges in:
+- `container/agent-runner/src/ollama-mcp-stdio.ts` (Ollama MCP server)
+- `scripts/ollama-watch.sh` (macOS notification watcher)
+- Ollama MCP config in `container/agent-runner/src/index.ts` (allowedTools + mcpServers)
+- `[OLLAMA]` log surfacing in `src/container-runner.ts`
+- `OLLAMA_HOST` in `.env.example`
+
+If the merge reports conflicts, resolve them by reading the conflicted files and understanding the intent of both sides.
+
+### Copy to per-group agent-runner
+
+Existing groups have a cached copy of the agent-runner source. Copy the new files:
+
+```bash
+for dir in data/sessions/*/agent-runner-src; do
+  cp container/agent-runner/src/ollama-mcp-stdio.ts "$dir/"
+  cp container/agent-runner/src/index.ts "$dir/"
+done
+```
+
+### Validate code changes
+
+```bash
+pnpm run build
+./container/build.sh
+```
+
+Build must be clean before proceeding.
+
+## Phase 3: Configure
+
+### Enable model management tools (optional)
+
+Ask the user:
+
+> Would you like the agent to be able to **manage Ollama models** (pull, delete, inspect, list running)?
+>
+> - **Yes** — adds tools to pull new models, delete old ones, show model info, and check what's loaded in memory
+> - **No** — the agent can only list installed models and generate responses (you manage models yourself on the host)
+
+If the user wants management tools, add to `.env`:
+
+```bash
+OLLAMA_ADMIN_TOOLS=true
+```
+
+If they decline (or don't answer), do not add the variable — management tools will be disabled by default.
+
+### Set Ollama host (optional)
+
+By default, the MCP server connects to `http://host.docker.internal:11434` (Docker Desktop) with a fallback to `localhost`. To use a custom Ollama host, add to `.env`:
+
+```bash
+OLLAMA_HOST=http://your-ollama-host:11434
+```
+
+### Restart the service
+
+```bash
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
+# Linux: systemctl --user restart nanoclaw
+```
+
+## Phase 4: Verify
+
+### Test inference
+
+Tell the user:
+
+> Send a message like: "use ollama to tell me the capital of France"
+>
+> The agent should use `ollama_list_models` to find available models, then `ollama_generate` to get a response.
+
+### Test model management (if enabled)
+
+If `OLLAMA_ADMIN_TOOLS=true` was set, tell the user:
+
+> Send a message like: "pull the gemma3:1b model" or "which ollama models are currently loaded in memory?"
+>
+> The agent should call `ollama_pull_model` or `ollama_list_running` respectively.
+
+### Monitor activity (optional)
+
+Run the watcher script for macOS notifications when Ollama is used:
+
+```bash
+./scripts/ollama-watch.sh
+```
+
+### Check logs if needed
+
+```bash
+tail -f logs/nanoclaw.log | grep -i ollama
+```
+
+Look for:
+- `[OLLAMA] >>> Generating` — generation started
+- `[OLLAMA] <<< Done` — generation completed
+- `[OLLAMA] Pulling model:` — pull in progress (management tools)
+- `[OLLAMA] Deleted:` — model removed (management tools)
+
+## Troubleshooting
+
+### Agent says "Ollama is not installed"
+
+The agent is trying to run `ollama` CLI inside the container instead of using the MCP tools. This means:
+1. The MCP server wasn't registered — check `container/agent-runner/src/index.ts` has the `ollama` entry in `mcpServers`
+2. The per-group source wasn't updated — re-copy files (see Phase 2)
+3. The container wasn't rebuilt — run `./container/build.sh`
+
+### "Failed to connect to Ollama"
+
+1. Verify Ollama is running: `ollama list`
+2. Check Docker can reach the host: `docker run --rm curlimages/curl curl -s http://host.docker.internal:11434/api/tags`
+3. If using a custom host, check `OLLAMA_HOST` in `.env`
+
+### Agent doesn't use Ollama tools
+
+The agent may not know about the tools. Try being explicit: "use the ollama_generate tool with gemma3:1b to answer: ..."
+
+### `ollama_pull_model` times out on large models
+
+Large models (7B+) can take several minutes. The tool uses `stream: false` so it blocks until complete — this is intentional. For very large pulls, use the host CLI directly: `ollama pull <model>`
+
+### Management tools not showing up
+
+Ensure `OLLAMA_ADMIN_TOOLS=true` is set in `.env` and the service was restarted after adding it.

.claude/skills/add-opencode/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: add-opencode
+description: Use OpenCode as an agent provider on NanoClaw v2 (AGENT_PROVIDER=opencode). OpenRouter, OpenAI, Google, DeepSeek, etc. via OpenCode config — not the Anthropic Agent SDK. Per-session and per-group via agent_provider; host passes OPENCODE_* and XDG mount when spawning containers.
+---
+
+# OpenCode agent provider (v2)
+
+NanoClaw **v2** runs agents in a long-lived **poll loop** inside the container. The backend is selected with **`AGENT_PROVIDER`** (`claude` | `opencode` | `mock`), not the v1 `AGENT_RUNNER` env var.
+
+## What it does (upstream v2)
+
+- **`container/agent-runner/src/providers/opencode.ts`** — `OpenCodeProvider` implementing `AgentProvider` (SSE via OpenCode server, session resume, MCP from merged `ProviderOptions.mcpServers` only — no `settings.json` MCP bridge).
+- **`container/agent-runner/src/providers/mcp-to-opencode.ts`** — maps v2 `McpServerConfig` to OpenCode `mcp` entries.
+- **`container/agent-runner/src/providers/factory.ts`** — registers `opencode`.
+- **`container/agent-runner/package.json`** — dependency `@opencode-ai/sdk`.
+- **`container/Dockerfile`** — global **`opencode-ai`** CLI for `opencode serve`.
+- **`src/container-runner.ts`** — when effective provider is `opencode`: `XDG_DATA_HOME=/opencode-xdg`, session-scoped host mount, `NO_PROXY`/`no_proxy` merge for `127.0.0.1,localhost`, passes through `OPENCODE_PROVIDER`, `OPENCODE_MODEL`, `OPENCODE_SMALL_MODEL` from the host environment.
+
+## Configuration
+
+### Host `.env` (typical)
+
+Set model/provider strings in the form OpenCode expects (often `provider/model-id`). **Put comments on their own lines** — a `#` inside a value is kept verbatim and breaks model IDs.
+
+These variables are read **on the host** and passed into the container only when the effective provider is `opencode` (see `src/container-runner.ts`). They do not switch the provider by themselves; the DB still needs `agent_provider` set (below).
+
+- `OPENCODE_PROVIDER` — OpenCode provider id, e.g. `openrouter`, `anthropic` (if unset, the runner defaults to `anthropic`).
+- `OPENCODE_MODEL` — full model id, e.g. `openrouter/anthropic/claude-sonnet-4`.
+- `OPENCODE_SMALL_MODEL` — optional second model for “small” tasks.
+
+Credentials: OneCLI / credential proxy patterns are unchanged. For non-`anthropic` OpenCode providers, the runner registers a placeholder API key and **`ANTHROPIC_BASE_URL`** (the credential proxy) as `baseURL` so the real key never lives in the container.
+
+#### Example: OpenRouter
+
+Use ids that match OpenCode’s registry / your custom registrations. Adjust names to what you actually run.
+
+```env
+# OpenCode — host passes these into the container when agent_provider is opencode
+OPENCODE_PROVIDER=openrouter
+OPENCODE_MODEL=openrouter/anthropic/claude-sonnet-4
+OPENCODE_SMALL_MODEL=openrouter/anthropic/claude-haiku-4.5
+```
+
+#### Example: Anthropic via existing proxy env
+
+When `OPENCODE_PROVIDER` is `anthropic`, OpenCode uses normal Anthropic env inside the container (proxy + placeholder key pattern unchanged).
+
+```env
+OPENCODE_PROVIDER=anthropic
+OPENCODE_MODEL=anthropic/claude-sonnet-4-20250514
+```
+
+#### Example: only a main model
+
+```env
+OPENCODE_PROVIDER=openrouter
+OPENCODE_MODEL=openrouter/google/gemini-2.5-pro-preview
+```
+
+#### OpenCode Zen (`x-api-key`, not Bearer)
+
+Zen’s HTTP API (e.g. `POST …/zen/v1/messages`) expects the key in the **`x-api-key`** header. If OneCLI injects **`Authorization: Bearer …`** only, Zen often returns **401 / “Missing API key”** even though the gateway is working.
+
+**Naming:** NanoClaw **`AGENT_PROVIDER=opencode`** (v2 DB `agent_provider`) means “run the **OpenCode agent provider**.” Separately, **`OPENCODE_PROVIDER=opencode`** in `.env` is OpenCode’s **Zen provider id** inside the OpenCode config (see [Zen docs](https://opencode.ai/docs/zen/)).
+
+**Host `.env` (typical Zen shape):**
+
+```env
+# NanoClaw still resolves AGENT_PROVIDER from agent_groups / sessions; set agent_provider to opencode there.
+# OpenCode SDK: Zen as the upstream provider + models under opencode/…
+OPENCODE_PROVIDER=opencode
+OPENCODE_MODEL=opencode/big-pickle
+OPENCODE_SMALL_MODEL=opencode/big-pickle
+
+# Point the credential proxy at Zen’s Anthropic-compatible base URL (host + OneCLI must forward this host).
+ANTHROPIC_BASE_URL=https://opencode.ai/zen/v1
+```
+
+Use a real Zen model id from the docs; `big-pickle` is one example.
+
+**OneCLI:** register the Zen key with **`x-api-key`**, not Bearer:
+
+```bash
+onecli secrets create --name "OpenCode Zen" --type generic \
+  --value YOUR_ZEN_KEY --host-pattern opencode.ai \
+  --header-name "x-api-key" --value-format "{value}"
+```
+
+For comparison, OpenRouter uses `Authorization` + `Bearer {value}`. Zen is different by design.
+
+### Per group / per session
+
+v2 schema: **`agent_groups.agent_provider`** and **`sessions.agent_provider`**. Set to `opencode` for groups or sessions that should use OpenCode. The container receives `AGENT_PROVIDER` from the resolved value (session overrides group).
+
+Extra MCP servers still come from **`NANOCLAW_MCP_SERVERS`** / `container_config.mcpServers` on the host; the runner merges them into the same `mcpServers` object passed to **both** Claude and OpenCode providers.
+
+## Operational notes
+
+- OpenCode keeps a local **`opencode serve`** process and SSE subscription; the provider tears down with **`stream.return`** and **SIGKILL** on the server process on **`abort()`** / shared runtime reset to avoid MCP/zombie hangs.
+- Session continuation is opaque (`ses_*` ids); stale sessions are cleared using **`isSessionInvalid`** on OpenCode-specific errors (timeouts, connection resets, not-found patterns) in addition to the poll-loop’s existing recovery.
+- **`NO_PROXY`** for localhost matters when the OpenCode client talks to `127.0.0.1` inside the container while HTTP(S)_PROXY is set (e.g. OneCLI).
+
+## Verify
+
+```bash
+grep -q opencode container/agent-runner/src/providers/factory.ts && echo "OpenCode registered" || echo "Missing"
+npm run build --prefix container/agent-runner
+```
+
+Rebuild the agent image after Dockerfile changes: `./container/build.sh` (or your usual image build).
+
+## Migrate from v1 wording
+
+If documentation or habits still say **`AGENT_RUNNER=opencode`**, update to **`AGENT_PROVIDER=opencode`** and store **`agent_provider`** in v2 tables, not v1 runner columns.

.claude/skills/add-parallel/SKILL.md

@@ -232,7 +232,7 @@ echo '{}' | docker run -i --entrypoint /bin/echo nanoclaw-agent:latest "Containe
 Rebuild the main app and restart:
 
 ```bash
-npm run build
+pnpm run build
 launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
 # Linux: systemctl --user restart nanoclaw
 ```
@@ -286,5 +286,5 @@ To remove Parallel AI integration:
 1. Remove from .env: `sed -i.bak '/PARALLEL_API_KEY/d' .env`
 2. Revert changes to container-runner.ts and agent-runner/src/index.ts
 3. Remove Web Research Tools section from groups/main/CLAUDE.md
-4. Rebuild: `./container/build.sh && npm run build`
+4. Rebuild: `./container/build.sh && pnpm run build`
 5. Restart: `launchctl kickstart -k gui/$(id -u)/com.nanoclaw` (macOS) or `systemctl --user restart nanoclaw` (Linux)

.claude/skills/add-pdf-reader/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: add-pdf-reader
+description: Add PDF reading to NanoClaw agents. Extracts text from PDFs via pdftotext CLI. Handles WhatsApp attachments, URLs, and local files.
+---
+
+# Add PDF Reader
+
+Adds PDF reading capability to all container agents using poppler-utils (pdftotext/pdfinfo). PDFs sent as WhatsApp attachments are auto-downloaded to the group workspace.
+
+## Phase 1: Pre-flight
+
+1. Check if `container/skills/pdf-reader/pdf-reader` exists — skip to Phase 3 if already applied
+2. Confirm WhatsApp is installed first (`skill/whatsapp` merged). This skill modifies WhatsApp channel files.
+
+## Phase 2: Apply Code Changes
+
+### Ensure WhatsApp fork remote
+
+```bash
+git remote -v
+```
+
+If `whatsapp` is missing, add it:
+
+```bash
+git remote add whatsapp https://github.com/qwibitai/nanoclaw-whatsapp.git
+```
+
+### Merge the skill branch
+
+```bash
+git fetch whatsapp skill/pdf-reader
+git merge whatsapp/skill/pdf-reader || {
+  git checkout --theirs pnpm-lock.yaml
+  git add pnpm-lock.yaml
+  git merge --continue
+}
+```
+
+This merges in:
+- `container/skills/pdf-reader/SKILL.md` (agent-facing documentation)
+- `container/skills/pdf-reader/pdf-reader` (CLI script)
+- `poppler-utils` in `container/Dockerfile`
+- PDF attachment download in `src/channels/whatsapp.ts`
+- PDF tests in `src/channels/whatsapp.test.ts`
+
+If the merge reports conflicts, resolve them by reading the conflicted files and understanding the intent of both sides.
+
+### Validate
+
+```bash
+pnpm run build
+pnpm exec vitest run src/channels/whatsapp.test.ts
+```
+
+### Rebuild container
+
+```bash
+./container/build.sh
+```
+
+### Restart service
+
+```bash
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
+# Linux: systemctl --user restart nanoclaw
+```
+
+## Phase 3: Verify
+
+### Test PDF extraction
+
+Send a PDF file in any registered WhatsApp chat. The agent should:
+1. Download the PDF to `attachments/`
+2. Respond acknowledging the PDF
+3. Be able to extract text when asked
+
+### Test URL fetching
+
+Ask the agent to read a PDF from a URL. It should use `pdf-reader fetch <url>`.
+
+### Check logs if needed
+
+```bash
+tail -f logs/nanoclaw.log | grep -i pdf
+```
+
+Look for:
+- `Downloaded PDF attachment` — successful download
+- `Failed to download PDF attachment` — media download issue
+
+## Troubleshooting
+
+### Agent says pdf-reader command not found
+
+Container needs rebuilding. Run `./container/build.sh` and restart the service.
+
+### PDF text extraction is empty
+
+The PDF may be scanned (image-based). pdftotext only handles text-based PDFs. Consider using the agent-browser to open the PDF visually instead.
+
+### WhatsApp PDF not detected
+
+Verify the message has `documentMessage` with `mimetype: application/pdf`. Some file-sharing apps send PDFs as generic files without the correct mimetype.

.claude/skills/add-reactions/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: add-reactions
+description: Add WhatsApp emoji reaction support — receive, send, store, and search reactions.
+---
+
+# Add Reactions
+
+This skill adds emoji reaction support to NanoClaw's WhatsApp channel: receive and store reactions, send reactions from the container agent via MCP tool, and query reaction history from SQLite.
+
+## Phase 1: Pre-flight
+
+### Check if already applied
+
+Check if `src/status-tracker.ts` exists:
+
+```bash
+test -f src/status-tracker.ts && echo "Already applied" || echo "Not applied"
+```
+
+If already applied, skip to Phase 3 (Verify).
+
+## Phase 2: Apply Code Changes
+
+### Ensure WhatsApp fork remote
+
+```bash
+git remote -v
+```
+
+If `whatsapp` is missing, add it:
+
+```bash
+git remote add whatsapp https://github.com/qwibitai/nanoclaw-whatsapp.git
+```
+
+### Merge the skill branch
+
+```bash
+git fetch whatsapp skill/reactions
+git merge whatsapp/skill/reactions || {
+  git checkout --theirs pnpm-lock.yaml
+  git add pnpm-lock.yaml
+  git merge --continue
+}
+```
+
+This adds:
+- `scripts/migrate-reactions.ts` (database migration for `reactions` table with composite PK and indexes)
+- `src/status-tracker.ts` (forward-only emoji state machine for message lifecycle signaling, with persistence and retry)
+- `src/status-tracker.test.ts` (unit tests for StatusTracker)
+- `container/skills/reactions/SKILL.md` (agent-facing documentation for the `react_to_message` MCP tool)
+- Reaction support in `src/db.ts`, `src/channels/whatsapp.ts`, `src/types.ts`, `src/ipc.ts`, `src/index.ts`, `src/group-queue.ts`, and `container/agent-runner/src/ipc-mcp-stdio.ts`
+
+### Run database migration
+
+```bash
+pnpm exec tsx scripts/migrate-reactions.ts
+```
+
+### Validate code changes
+
+```bash
+pnpm test
+pnpm run build
+```
+
+All tests must pass and build must be clean before proceeding.
+
+## Phase 3: Verify
+
+### Build and restart
+
+```bash
+pnpm run build
+```
+
+Linux:
+```bash
+systemctl --user restart nanoclaw
+```
+
+macOS:
+```bash
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw
+```
+
+### Test receiving reactions
+
+1. Send a message from your phone
+2. React to it with an emoji on WhatsApp
+3. Check the database:
+
+```bash
+sqlite3 store/messages.db "SELECT * FROM reactions ORDER BY timestamp DESC LIMIT 5;"
+```
+
+### Test sending reactions
+
+Ask the agent to react to a message via the `react_to_message` MCP tool. Check your phone — the reaction should appear on the message.
+
+## Troubleshooting
+
+### Reactions not appearing in database
+
+- Check NanoClaw logs for `Failed to process reaction` errors
+- Verify the chat is registered
+- Confirm the service is running
+
+### Migration fails
+
+- Ensure `store/messages.db` exists and is accessible
+- If "table reactions already exists", the migration already ran — skip it
+
+### Agent can't send reactions
+
+- Check IPC logs for `Unauthorized IPC reaction attempt blocked` — the agent can only react in its own group's chat
+- Verify WhatsApp is connected: check logs for connection status

.claude/skills/add-resend-v2/REMOVE.md

@@ -0,0 +1,6 @@
+# Remove Resend Email Channel
+
+1. Comment out `import './resend.js'` in `src/channels/index.ts`
+2. Remove `RESEND_API_KEY`, `RESEND_FROM_ADDRESS`, `RESEND_FROM_NAME`, `RESEND_WEBHOOK_SECRET` from `.env`
+3. `pnpm uninstall @resend/chat-sdk-adapter`
+4. Rebuild and restart

.claude/skills/add-resend-v2/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: add-resend-v2
+description: Add Resend (email) channel integration to NanoClaw v2 via Chat SDK.
+---
+
+# Add Resend Email Channel
+
+Connect NanoClaw to email via Resend for async email conversations.
+
+## Pre-flight
+
+Check if `src/channels/resend.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Credentials.
+
+## Install
+
+```bash
+pnpm install @resend/chat-sdk-adapter
+```
+
+Uncomment the Resend import in `src/channels/index.ts`:
+
+```typescript
+import './resend.js';
+```
+
+Build:
+
+```bash
+pnpm run build
+```
+
+## Credentials
+
+1. Go to [resend.com](https://resend.com) and create an account.
+2. Add and verify your sending domain.
+3. Go to **API Keys** and create a new key.
+4. Set up a webhook:
+   - Go to **Webhooks** > **Add webhook**.
+   - URL: `https://your-domain/webhook/resend`.
+   - Events: select **email.received**.
+   - Copy the signing secret.
+
+### Configure environment
+
+Add to `.env`:
+
+```bash
+RESEND_API_KEY=re_...
+RESEND_FROM_ADDRESS=bot@yourdomain.com
+RESEND_FROM_NAME=NanoClaw
+RESEND_WEBHOOK_SECRET=your-webhook-secret
+```
+
+Sync to container: `mkdir -p data/env && cp .env data/env/env`
+
+## Next Steps
+
+If you're in the middle of `/setup`, return to the setup flow now.
+
+Otherwise, run `/manage-channels` to wire this channel to an agent group.
+
+## Channel Info
+
+- **type**: `resend`
+- **terminology**: Resend handles email. Each email thread (identified by subject/In-Reply-To headers) is a separate conversation. The "from address" is the bot's identity.
+- **how-to-find-id**: The platform ID is the from email address (e.g. `bot@yourdomain.com`). Each sender's email thread becomes its own conversation.
+- **supports-threads**: yes (via email threading headers -- replies to the same thread stay together)
+- **typical-use**: Async communication -- email conversations with longer response expectations
+- **default-isolation**: Same agent group if you want your agent to handle email alongside other channels. Separate agent group if email contains sensitive correspondence that shouldn't be accessible from other channels.

.claude/skills/add-resend-v2/VERIFY.md

@@ -0,0 +1,3 @@
+# Verify Resend Email Channel
+
+Send an email to the configured from address. The bot should respond via email within a few seconds.

.claude/skills/add-slack-v2/REMOVE.md

@@ -0,0 +1,6 @@
+# Remove Slack
+
+1. Comment out `import './slack.js'` in `src/channels/index.ts`
+2. Remove `SLACK_BOT_TOKEN` and `SLACK_SIGNING_SECRET` from `.env`
+3. `pnpm uninstall @chat-adapter/slack`
+4. Rebuild and restart

.claude/skills/add-slack-v2/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: add-slack-v2
+description: Add Slack channel integration to NanoClaw v2 via Chat SDK.
+---
+
+# Add Slack Channel
+
+Adds Slack support to NanoClaw v2 using the Chat SDK bridge.
+
+## Pre-flight
+
+Check if `src/channels/slack.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Credentials.
+
+## Install
+
+### Install the adapter package
+
+```bash
+pnpm install @chat-adapter/slack
+```
+
+### Enable the channel
+
+Uncomment the Slack import in `src/channels/index.ts`:
+
+```typescript
+import './slack.js';
+```
+
+### Build
+
+```bash
+pnpm run build
+```
+
+## Credentials
+
+### Create Slack App
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App** > **From scratch**
+2. Name it (e.g., "NanoClaw") and select your workspace
+3. Go to **OAuth & Permissions** and add Bot Token Scopes:
+   - `chat:write`, `channels:history`, `groups:history`, `im:history`, `channels:read`, `groups:read`, `users:read`, `reactions:write`
+4. Click **Install to Workspace** and copy the **Bot User OAuth Token** (`xoxb-...`)
+5. Go to **Basic Information** and copy the **Signing Secret**
+
+### Enable DMs
+
+6. Go to **App Home** and enable the **Messages Tab**
+7. Check **"Allow users to send Slash commands and messages from the messages tab"**
+
+### Event Subscriptions
+
+8. Go to **Event Subscriptions** and toggle **Enable Events**
+9. Set the **Request URL** to `https://your-domain/webhook/slack` — Slack will send a verification challenge; it must pass before you can save
+10. Under **Subscribe to bot events**, add:
+    - `message.channels`, `message.groups`, `message.im`, `app_mention`
+11. Click **Save Changes**
+12. Slack will show a banner asking you to **reinstall the app** — click it to apply the new event subscriptions
+
+### Configure environment
+
+Add to `.env`:
+
+```bash
+SLACK_BOT_TOKEN=xoxb-your-bot-token
+SLACK_SIGNING_SECRET=your-signing-secret
+```
+
+Sync to container: `mkdir -p data/env && cp .env data/env/env`
+
+### Webhook server
+
+The Chat SDK bridge automatically starts a shared webhook server on port 3000 (configurable via `WEBHOOK_PORT` env var). The server handles `/webhook/slack` for Slack and other webhook-based adapters. This port must be publicly reachable from the internet for Slack to deliver events.
+
+If running locally, discuss options for exposing the server — e.g. ngrok (`ngrok http 3000`), Cloudflare Tunnel, or a reverse proxy on a VPS. The resulting public URL becomes the base for `https://your-domain/webhook/slack`.
+
+## Next Steps
+
+If you're in the middle of `/setup`, return to the setup flow now.
+
+Otherwise, run `/manage-channels` to wire this channel to an agent group.
+
+## Channel Info
+
+- **type**: `slack`
+- **terminology**: Slack has "workspaces" containing "channels." Channels can be public (#general) or private. The bot can also receive direct messages.
+- **platform-id-format**: `slack:{channelId}` for channels (e.g., `slack:C0123ABC`), `slack:{dmId}` for DMs (e.g., `slack:D0ARWEBLV63`)
+- **how-to-find-id**: Right-click a channel name > "View channel details" — the Channel ID is at the bottom (starts with C). For DMs, the ID starts with D. Or copy the channel link — the ID is the last segment of the URL.
+- **supports-threads**: yes
+- **typical-use**: Interactive chat — team channels or direct messages
+- **default-isolation**: Same agent group for channels where you're the primary user. Separate agent group for channels with different teams or sensitive contexts.

.claude/skills/add-slack-v2/VERIFY.md

@@ -0,0 +1,3 @@
+# Verify Slack
+
+Add the bot to a Slack channel, then send a message or @mention the bot. The bot should respond within a few seconds.

.claude/skills/add-slack/SKILL.md

@@ -5,13 +5,13 @@ description: Add Slack as a channel. Can replace WhatsApp entirely or run alongs
 
 # Add Slack Channel
 
-This skill adds Slack support to NanoClaw using the skills engine for deterministic code changes, then walks through interactive setup.
+This skill adds Slack support to NanoClaw, then walks through interactive setup.
 
 ## Phase 1: Pre-flight
 
 ### Check if already applied
 
-Read `.nanoclaw/state.yaml`. If `slack` is in `applied_skills`, skip to Phase 3 (Setup). The code changes are already in place.
+Check if `src/channels/slack.ts` exists. If it does, skip to Phase 3 (Setup). The code changes are already in place.
 
 ### Ask the user
 
@@ -19,42 +19,47 @@ Read `.nanoclaw/state.yaml`. If `slack` is in `applied_skills`, skip to Phase 3
 
 ## Phase 2: Apply Code Changes
 
-Run the skills engine to apply this skill's code package. The package files are in this directory alongside this SKILL.md.
-
-### Initialize skills system (if needed)
-
-If `.nanoclaw/` directory doesn't exist yet:
+### Ensure channel remote
 
 ```bash
-npx tsx scripts/apply-skill.ts --init
+git remote -v
 ```
 
-Or call `initSkillsSystem()` from `skills-engine/migrate.ts`.
-
-### Apply the skill
+If `slack` is missing, add it:
 
 ```bash
-npx tsx scripts/apply-skill.ts .claude/skills/add-slack
+git remote add slack https://github.com/qwibitai/nanoclaw-slack.git
 ```
 
-This deterministically:
-- Adds `src/channels/slack.ts` (SlackChannel class with self-registration via `registerChannel`)
-- Adds `src/channels/slack.test.ts` (46 unit tests)
-- Appends `import './slack.js'` to the channel barrel file `src/channels/index.ts`
-- Installs the `@slack/bolt` npm dependency
-- Records the application in `.nanoclaw/state.yaml`
+### Merge the skill branch
 
-If the apply reports merge conflicts, read the intent file:
-- `modify/src/channels/index.ts.intent.md` — what changed and invariants
+```bash
+git fetch slack main
+git merge slack/main || {
+  git checkout --theirs pnpm-lock.yaml
+  git add pnpm-lock.yaml
+  git merge --continue
+}
+```
+
+This merges in:
+- `src/channels/slack.ts` (SlackChannel class with self-registration via `registerChannel`)
+- `src/channels/slack.test.ts` (46 unit tests)
+- `import './slack.js'` appended to the channel barrel file `src/channels/index.ts`
+- `@slack/bolt` npm dependency in `package.json`
+- `SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN` in `.env.example`
+
+If the merge reports conflicts, resolve them by reading the conflicted files and understanding the intent of both sides.
 
 ### Validate code changes
 
 ```bash
-npm test
-npm run build
+pnpm install
+pnpm run build
+pnpm exec vitest run src/channels/slack.test.ts
 ```
 
-All tests must pass (including the new slack tests) and build must be clean before proceeding.
+All tests must pass (including the new Slack tests) and build must be clean before proceeding.
 
 ## Phase 3: Setup
 
@@ -93,7 +98,7 @@ The container reads environment from `data/env/env`, not `.env` directly.
 ### Build and restart
 
 ```bash
-npm run build
+pnpm run build
 launchctl kickstart -k gui/$(id -u)/com.nanoclaw
 ```
 
@@ -113,31 +118,18 @@ Wait for the user to provide the channel ID.
 
 ### Register the channel
 
-Use the IPC register flow or register directly. The channel ID, name, and folder name are needed.
+The channel ID, name, and folder name are needed. Use `pnpm exec tsx setup/index.ts --step register` with the appropriate flags.
 
 For a main channel (responds to all messages):
 
-```typescript
-registerGroup("slack:<channel-id>", {
-  name: "<channel-name>",
-  folder: "slack_main",
-  trigger: `@${ASSISTANT_NAME}`,
-  added_at: new Date().toISOString(),
-  requiresTrigger: false,
-  isMain: true,
-});
+```bash
+pnpm exec tsx setup/index.ts --step register -- --jid "slack:<channel-id>" --name "<channel-name>" --folder "slack_main" --trigger "@${ASSISTANT_NAME}" --channel slack --no-trigger-required --is-main
 ```
 
 For additional channels (trigger-only):
 
-```typescript
-registerGroup("slack:<channel-id>", {
-  name: "<channel-name>",
-  folder: "slack_<channel-name>",
-  trigger: `@${ASSISTANT_NAME}`,
-  added_at: new Date().toISOString(),
-  requiresTrigger: true,
-});
+```bash
+pnpm exec tsx setup/index.ts --step register -- --jid "slack:<channel-id>" --name "<channel-name>" --folder "slack_<channel-name>" --trigger "@${ASSISTANT_NAME}" --channel slack
 ```
 
 ## Phase 5: Verify

.claude/skills/add-slack/SLACK_SETUP.md

@@ -1,149 +0,0 @@
-# Slack App Setup for NanoClaw
-
-Step-by-step guide to creating and configuring a Slack app for use with NanoClaw.
-
-## Prerequisites
-
-- A Slack workspace where you have admin permissions (or permission to install apps)
-- Your NanoClaw instance with the `/add-slack` skill applied
-
-## Step 1: Create the Slack App
-
-1. Go to [api.slack.com/apps](https://api.slack.com/apps)
-2. Click **Create New App**
-3. Choose **From scratch**
-4. Enter an app name (e.g., your `ASSISTANT_NAME` value, or any name you like)
-5. Select the workspace you want to install it in
-6. Click **Create App**
-
-## Step 2: Enable Socket Mode
-
-Socket Mode lets the bot connect to Slack without needing a public URL. This is what makes it work from your local machine.
-
-1. In the sidebar, click **Socket Mode**
-2. Toggle **Enable Socket Mode** to **On**
-3. When prompted for a token name, enter something like `nanoclaw`
-4. Click **Generate**
-5. **Copy the App-Level Token** — it starts with `xapp-`. Save this somewhere safe; you'll need it later.
-
-## Step 3: Subscribe to Events
-
-This tells Slack which messages to forward to your bot.
-
-1. In the sidebar, click **Event Subscriptions**
-2. Toggle **Enable Events** to **On**
-3. Under **Subscribe to bot events**, click **Add Bot User Event** and add these three events:
-
-| Event | What it does |
-|-------|-------------|
-| `message.channels` | Receive messages in public channels the bot is in |
-| `message.groups` | Receive messages in private channels the bot is in |
-| `message.im` | Receive direct messages to the bot |
-
-4. Click **Save Changes** at the bottom of the page
-
-## Step 4: Set Bot Permissions (OAuth Scopes)
-
-These scopes control what the bot is allowed to do.
-
-1. In the sidebar, click **OAuth & Permissions**
-2. Scroll down to **Scopes** > **Bot Token Scopes**
-3. Click **Add an OAuth Scope** and add each of these:
-
-| Scope | Why it's needed |
-|-------|----------------|
-| `chat:write` | Send messages to channels and DMs |
-| `channels:history` | Read messages in public channels |
-| `groups:history` | Read messages in private channels |
-| `im:history` | Read direct messages |
-| `channels:read` | List channels (for metadata sync) |
-| `groups:read` | List private channels (for metadata sync) |
-| `users:read` | Look up user display names |
-
-## Step 5: Install to Workspace
-
-1. In the sidebar, click **Install App**
-2. Click **Install to Workspace**
-3. Review the permissions and click **Allow**
-4. **Copy the Bot User OAuth Token** — it starts with `xoxb-`. Save this somewhere safe.
-
-## Step 6: Configure NanoClaw
-
-Add both tokens to your `.env` file:
-
-```
-SLACK_BOT_TOKEN=xoxb-your-bot-token-here
-SLACK_APP_TOKEN=xapp-your-app-token-here
-```
-
-If you want Slack to replace WhatsApp entirely (no WhatsApp channel), also add:
-
-```
-SLACK_ONLY=true
-```
-
-Then sync the environment to the container:
-
-```bash
-mkdir -p data/env && cp .env data/env/env
-```
-
-## Step 7: Add the Bot to Channels
-
-The bot only receives messages from channels it has been explicitly added to.
-
-1. Open the Slack channel you want the bot to monitor
-2. Click the channel name at the top to open channel details
-3. Go to **Integrations** > **Add apps**
-4. Search for your bot name and add it
-
-Repeat for each channel you want the bot in.
-
-## Step 8: Get Channel IDs for Registration
-
-You need the Slack channel ID to register it with NanoClaw.
-
-**Option A — From the URL:**
-Open the channel in Slack on the web. The URL looks like:
-```
-https://app.slack.com/client/TXXXXXXX/C0123456789
-```
-The `C0123456789` part is the channel ID.
-
-**Option B — Right-click:**
-Right-click the channel name in Slack > **Copy link** > the channel ID is the last path segment.
-
-**Option C — Via API:**
-```bash
-curl -s -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
-  "https://slack.com/api/conversations.list" | jq '.channels[] | {id, name}'
-```
-
-The NanoClaw JID format is `slack:` followed by the channel ID, e.g., `slack:C0123456789`.
-
-## Token Reference
-
-| Token | Prefix | Where to find it |
-|-------|--------|-----------------|
-| Bot User OAuth Token | `xoxb-` | **OAuth & Permissions** > **Bot User OAuth Token** |
-| App-Level Token | `xapp-` | **Basic Information** > **App-Level Tokens** (or during Socket Mode setup) |
-
-## Troubleshooting
-
-**Bot not receiving messages:**
-- Verify Socket Mode is enabled (Step 2)
-- Verify all three events are subscribed (Step 3)
-- Verify the bot has been added to the channel (Step 7)
-
-**"missing_scope" errors:**
-- Go back to **OAuth & Permissions** and add the missing scope
-- After adding scopes, you must **reinstall the app** to your workspace (Slack will show a banner prompting you to do this)
-
-**Bot can't send messages:**
-- Verify the `chat:write` scope is added
-- Verify the bot has been added to the target channel
-
-**Token not working:**
-- Bot tokens start with `xoxb-` — if yours doesn't, you may have copied the wrong token
-- App tokens start with `xapp-` — these are generated in the Socket Mode or Basic Information pages
-- If you regenerated a token, update `.env` and re-sync: `cp .env data/env/env`

.claude/skills/add-slack/add/src/channels/slack.test.ts

@@ -1,851 +0,0 @@
-import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
-
-// --- Mocks ---
-
-// Mock registry (registerChannel runs at import time)
-vi.mock('./registry.js', () => ({ registerChannel: vi.fn() }));
-
-// Mock config
-vi.mock('../config.js', () => ({
-  ASSISTANT_NAME: 'Jonesy',
-  TRIGGER_PATTERN: /^@Jonesy\b/i,
-}));
-
-// Mock logger
-vi.mock('../logger.js', () => ({
-  logger: {
-    debug: vi.fn(),
-    info: vi.fn(),
-    warn: vi.fn(),
-    error: vi.fn(),
-  },
-}));
-
-// Mock db
-vi.mock('../db.js', () => ({
-  updateChatName: vi.fn(),
-}));
-
-// --- @slack/bolt mock ---
-
-type Handler = (...args: any[]) => any;
-
-const appRef = vi.hoisted(() => ({ current: null as any }));
-
-vi.mock('@slack/bolt', () => ({
-  App: class MockApp {
-    eventHandlers = new Map<string, Handler>();
-    token: string;
-    appToken: string;
-
-    client = {
-      auth: {
-        test: vi.fn().mockResolvedValue({ user_id: 'U_BOT_123' }),
-      },
-      chat: {
-        postMessage: vi.fn().mockResolvedValue(undefined),
-      },
-      conversations: {
-        list: vi.fn().mockResolvedValue({
-          channels: [],
-          response_metadata: {},
-        }),
-      },
-      users: {
-        info: vi.fn().mockResolvedValue({
-          user: { real_name: 'Alice Smith', name: 'alice' },
-        }),
-      },
-    };
-
-    constructor(opts: any) {
-      this.token = opts.token;
-      this.appToken = opts.appToken;
-      appRef.current = this;
-    }
-
-    event(name: string, handler: Handler) {
-      this.eventHandlers.set(name, handler);
-    }
-
-    async start() {}
-    async stop() {}
-  },
-  LogLevel: { ERROR: 'error' },
-}));
-
-// Mock env
-vi.mock('../env.js', () => ({
-  readEnvFile: vi.fn().mockReturnValue({
-    SLACK_BOT_TOKEN: 'xoxb-test-token',
-    SLACK_APP_TOKEN: 'xapp-test-token',
-  }),
-}));
-
-import { SlackChannel, SlackChannelOpts } from './slack.js';
-import { updateChatName } from '../db.js';
-import { readEnvFile } from '../env.js';
-
-// --- Test helpers ---
-
-function createTestOpts(
-  overrides?: Partial<SlackChannelOpts>,
-): SlackChannelOpts {
-  return {
-    onMessage: vi.fn(),
-    onChatMetadata: vi.fn(),
-    registeredGroups: vi.fn(() => ({
-      'slack:C0123456789': {
-        name: 'Test Channel',
-        folder: 'test-channel',
-        trigger: '@Jonesy',
-        added_at: '2024-01-01T00:00:00.000Z',
-      },
-    })),
-    ...overrides,
-  };
-}
-
-function createMessageEvent(overrides: {
-  channel?: string;
-  channelType?: string;
-  user?: string;
-  text?: string;
-  ts?: string;
-  threadTs?: string;
-  subtype?: string;
-  botId?: string;
-}) {
-  return {
-    channel: overrides.channel ?? 'C0123456789',
-    channel_type: overrides.channelType ?? 'channel',
-    user: overrides.user ?? 'U_USER_456',
-    text: 'text' in overrides ? overrides.text : 'Hello everyone',
-    ts: overrides.ts ?? '1704067200.000000',
-    thread_ts: overrides.threadTs,
-    subtype: overrides.subtype,
-    bot_id: overrides.botId,
-  };
-}
-
-function currentApp() {
-  return appRef.current;
-}
-
-async function triggerMessageEvent(event: ReturnType<typeof createMessageEvent>) {
-  const handler = currentApp().eventHandlers.get('message');
-  if (handler) await handler({ event });
-}
-
-// --- Tests ---
-
-describe('SlackChannel', () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  // --- Connection lifecycle ---
-
-  describe('connection lifecycle', () => {
-    it('resolves connect() when app starts', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-
-      await channel.connect();
-
-      expect(channel.isConnected()).toBe(true);
-    });
-
-    it('registers message event handler on construction', () => {
-      const opts = createTestOpts();
-      new SlackChannel(opts);
-
-      expect(currentApp().eventHandlers.has('message')).toBe(true);
-    });
-
-    it('gets bot user ID on connect', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-
-      await channel.connect();
-
-      expect(currentApp().client.auth.test).toHaveBeenCalled();
-    });
-
-    it('disconnects cleanly', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-
-      await channel.connect();
-      expect(channel.isConnected()).toBe(true);
-
-      await channel.disconnect();
-      expect(channel.isConnected()).toBe(false);
-    });
-
-    it('isConnected() returns false before connect', () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-
-      expect(channel.isConnected()).toBe(false);
-    });
-  });
-
-  // --- Message handling ---
-
-  describe('message handling', () => {
-    it('delivers message for registered channel', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-      await channel.connect();
-
-      const event = createMessageEvent({ text: 'Hello everyone' });
-      await triggerMessageEvent(event);
-
-      expect(opts.onChatMetadata).toHaveBeenCalledWith(
-        'slack:C0123456789',
-        expect.any(String),
-        undefined,
-        'slack',
-        true,
-      );
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'slack:C0123456789',
-        expect.objectContaining({
-          id: '1704067200.000000',
-          chat_jid: 'slack:C0123456789',
-          sender: 'U_USER_456',
-          content: 'Hello everyone',
-          is_from_me: false,
-        }),
-      );
-    });
-
-    it('only emits metadata for unregistered channels', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-      await channel.connect();
-
-      const event = createMessageEvent({ channel: 'C9999999999' });
-      await triggerMessageEvent(event);
-
-      expect(opts.onChatMetadata).toHaveBeenCalledWith(
-        'slack:C9999999999',
-        expect.any(String),
-        undefined,
-        'slack',
-        true,
-      );
-      expect(opts.onMessage).not.toHaveBeenCalled();
-    });
-
-    it('skips non-text subtypes (channel_join, etc.)', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-      await channel.connect();
-
-      const event = createMessageEvent({ subtype: 'channel_join' });
-      await triggerMessageEvent(event);
-
-      expect(opts.onMessage).not.toHaveBeenCalled();
-      expect(opts.onChatMetadata).not.toHaveBeenCalled();
-    });
-
-    it('allows bot_message subtype through', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-      await channel.connect();
-
-      const event = createMessageEvent({
-        subtype: 'bot_message',
-        botId: 'B_OTHER_BOT',
-        text: 'Bot message',
-      });
-      await triggerMessageEvent(event);
-
-      expect(opts.onChatMetadata).toHaveBeenCalled();
-    });
-
-    it('skips messages with no text', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-      await channel.connect();
-
-      const event = createMessageEvent({ text: undefined as any });
-      await triggerMessageEvent(event);
-
-      expect(opts.onMessage).not.toHaveBeenCalled();
-    });
-
-    it('detects bot messages by bot_id', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-      await channel.connect();
-
-      const event = createMessageEvent({
-        subtype: 'bot_message',
-        botId: 'B_MY_BOT',
-        text: 'Bot response',
-      });
-      await triggerMessageEvent(event);
-
-      // Has bot_id so should be marked as bot message
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'slack:C0123456789',
-        expect.objectContaining({
-          is_from_me: true,
-          is_bot_message: true,
-          sender_name: 'Jonesy',
-        }),
-      );
-    });
-
-    it('detects bot messages by matching bot user ID', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-      await channel.connect();
-
-      const event = createMessageEvent({ user: 'U_BOT_123', text: 'Self message' });
-      await triggerMessageEvent(event);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'slack:C0123456789',
-        expect.objectContaining({
-          is_from_me: true,
-          is_bot_message: true,
-        }),
-      );
-    });
-
-    it('identifies IM channel type as non-group', async () => {
-      const opts = createTestOpts({
-        registeredGroups: vi.fn(() => ({
-          'slack:D0123456789': {
-            name: 'DM',
-            folder: 'dm',
-            trigger: '@Jonesy',
-            added_at: '2024-01-01T00:00:00.000Z',
-          },
-        })),
-      });
-      const channel = new SlackChannel(opts);
-      await channel.connect();
-
-      const event = createMessageEvent({
-        channel: 'D0123456789',
-        channelType: 'im',
-      });
-      await triggerMessageEvent(event);
-
-      expect(opts.onChatMetadata).toHaveBeenCalledWith(
-        'slack:D0123456789',
-        expect.any(String),
-        undefined,
-        'slack',
-        false, // IM is not a group
-      );
-    });
-
-    it('converts ts to ISO timestamp', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-      await channel.connect();
-
-      const event = createMessageEvent({ ts: '1704067200.000000' });
-      await triggerMessageEvent(event);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'slack:C0123456789',
-        expect.objectContaining({
-          timestamp: '2024-01-01T00:00:00.000Z',
-        }),
-      );
-    });
-
-    it('resolves user name from Slack API', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-      await channel.connect();
-
-      const event = createMessageEvent({ user: 'U_USER_456', text: 'Hello' });
-      await triggerMessageEvent(event);
-
-      expect(currentApp().client.users.info).toHaveBeenCalledWith({
-        user: 'U_USER_456',
-      });
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'slack:C0123456789',
-        expect.objectContaining({
-          sender_name: 'Alice Smith',
-        }),
-      );
-    });
-
-    it('caches user names to avoid repeated API calls', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-      await channel.connect();
-
-      // First message — API call
-      await triggerMessageEvent(createMessageEvent({ user: 'U_USER_456', text: 'First' }));
-      // Second message — should use cache
-      await triggerMessageEvent(createMessageEvent({
-        user: 'U_USER_456',
-        text: 'Second',
-        ts: '1704067201.000000',
-      }));
-
-      expect(currentApp().client.users.info).toHaveBeenCalledTimes(1);
-    });
-
-    it('falls back to user ID when API fails', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-      await channel.connect();
-
-      currentApp().client.users.info.mockRejectedValueOnce(new Error('API error'));
-
-      const event = createMessageEvent({ user: 'U_UNKNOWN', text: 'Hi' });
-      await triggerMessageEvent(event);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'slack:C0123456789',
-        expect.objectContaining({
-          sender_name: 'U_UNKNOWN',
-        }),
-      );
-    });
-
-    it('flattens threaded replies into channel messages', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-      await channel.connect();
-
-      const event = createMessageEvent({
-        ts: '1704067201.000000',
-        threadTs: '1704067200.000000', // parent message ts — this is a reply
-        text: 'Thread reply',
-      });
-      await triggerMessageEvent(event);
-
-      // Threaded replies are delivered as regular channel messages
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'slack:C0123456789',
-        expect.objectContaining({
-          content: 'Thread reply',
-        }),
-      );
-    });
-
-    it('delivers thread parent messages normally', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-      await channel.connect();
-
-      const event = createMessageEvent({
-        ts: '1704067200.000000',
-        threadTs: '1704067200.000000', // same as ts — this IS the parent
-        text: 'Thread parent',
-      });
-      await triggerMessageEvent(event);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'slack:C0123456789',
-        expect.objectContaining({
-          content: 'Thread parent',
-        }),
-      );
-    });
-
-    it('delivers messages without thread_ts normally', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-      await channel.connect();
-
-      const event = createMessageEvent({ text: 'Normal message' });
-      await triggerMessageEvent(event);
-
-      expect(opts.onMessage).toHaveBeenCalled();
-    });
-  });
-
-  // --- @mention translation ---
-
-  describe('@mention translation', () => {
-    it('prepends trigger when bot is @mentioned via Slack format', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-      await channel.connect(); // sets botUserId to 'U_BOT_123'
-
-      const event = createMessageEvent({
-        text: 'Hey <@U_BOT_123> what do you think?',
-        user: 'U_USER_456',
-      });
-      await triggerMessageEvent(event);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'slack:C0123456789',
-        expect.objectContaining({
-          content: '@Jonesy Hey <@U_BOT_123> what do you think?',
-        }),
-      );
-    });
-
-    it('does not prepend trigger when trigger pattern already matches', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-      await channel.connect();
-
-      const event = createMessageEvent({
-        text: '@Jonesy <@U_BOT_123> hello',
-        user: 'U_USER_456',
-      });
-      await triggerMessageEvent(event);
-
-      // Content should be unchanged since it already matches TRIGGER_PATTERN
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'slack:C0123456789',
-        expect.objectContaining({
-          content: '@Jonesy <@U_BOT_123> hello',
-        }),
-      );
-    });
-
-    it('does not translate mentions in bot messages', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-      await channel.connect();
-
-      const event = createMessageEvent({
-        text: 'Echo: <@U_BOT_123>',
-        subtype: 'bot_message',
-        botId: 'B_MY_BOT',
-      });
-      await triggerMessageEvent(event);
-
-      // Bot messages skip mention translation
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'slack:C0123456789',
-        expect.objectContaining({
-          content: 'Echo: <@U_BOT_123>',
-        }),
-      );
-    });
-
-    it('does not translate mentions for other users', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-      await channel.connect();
-
-      const event = createMessageEvent({
-        text: 'Hey <@U_OTHER_USER> look at this',
-        user: 'U_USER_456',
-      });
-      await triggerMessageEvent(event);
-
-      // Mention is for a different user, not the bot
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'slack:C0123456789',
-        expect.objectContaining({
-          content: 'Hey <@U_OTHER_USER> look at this',
-        }),
-      );
-    });
-  });
-
-  // --- sendMessage ---
-
-  describe('sendMessage', () => {
-    it('sends message via Slack client', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-      await channel.connect();
-
-      await channel.sendMessage('slack:C0123456789', 'Hello');
-
-      expect(currentApp().client.chat.postMessage).toHaveBeenCalledWith({
-        channel: 'C0123456789',
-        text: 'Hello',
-      });
-    });
-
-    it('strips slack: prefix from JID', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-      await channel.connect();
-
-      await channel.sendMessage('slack:D9876543210', 'DM message');
-
-      expect(currentApp().client.chat.postMessage).toHaveBeenCalledWith({
-        channel: 'D9876543210',
-        text: 'DM message',
-      });
-    });
-
-    it('queues message when disconnected', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-
-      // Don't connect — should queue
-      await channel.sendMessage('slack:C0123456789', 'Queued message');
-
-      expect(currentApp().client.chat.postMessage).not.toHaveBeenCalled();
-    });
-
-    it('queues message on send failure', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-      await channel.connect();
-
-      currentApp().client.chat.postMessage.mockRejectedValueOnce(
-        new Error('Network error'),
-      );
-
-      // Should not throw
-      await expect(
-        channel.sendMessage('slack:C0123456789', 'Will fail'),
-      ).resolves.toBeUndefined();
-    });
-
-    it('splits long messages at 4000 character boundary', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-      await channel.connect();
-
-      // Create a message longer than 4000 chars
-      const longText = 'A'.repeat(4500);
-      await channel.sendMessage('slack:C0123456789', longText);
-
-      // Should be split into 2 messages: 4000 + 500
-      expect(currentApp().client.chat.postMessage).toHaveBeenCalledTimes(2);
-      expect(currentApp().client.chat.postMessage).toHaveBeenNthCalledWith(1, {
-        channel: 'C0123456789',
-        text: 'A'.repeat(4000),
-      });
-      expect(currentApp().client.chat.postMessage).toHaveBeenNthCalledWith(2, {
-        channel: 'C0123456789',
-        text: 'A'.repeat(500),
-      });
-    });
-
-    it('sends exactly-4000-char messages as a single message', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-      await channel.connect();
-
-      const text = 'B'.repeat(4000);
-      await channel.sendMessage('slack:C0123456789', text);
-
-      expect(currentApp().client.chat.postMessage).toHaveBeenCalledTimes(1);
-      expect(currentApp().client.chat.postMessage).toHaveBeenCalledWith({
-        channel: 'C0123456789',
-        text,
-      });
-    });
-
-    it('splits messages into 3 parts when over 8000 chars', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-      await channel.connect();
-
-      const longText = 'C'.repeat(8500);
-      await channel.sendMessage('slack:C0123456789', longText);
-
-      // 4000 + 4000 + 500 = 3 messages
-      expect(currentApp().client.chat.postMessage).toHaveBeenCalledTimes(3);
-    });
-
-    it('flushes queued messages on connect', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-
-      // Queue messages while disconnected
-      await channel.sendMessage('slack:C0123456789', 'First queued');
-      await channel.sendMessage('slack:C0123456789', 'Second queued');
-
-      expect(currentApp().client.chat.postMessage).not.toHaveBeenCalled();
-
-      // Connect triggers flush
-      await channel.connect();
-
-      expect(currentApp().client.chat.postMessage).toHaveBeenCalledWith({
-        channel: 'C0123456789',
-        text: 'First queued',
-      });
-      expect(currentApp().client.chat.postMessage).toHaveBeenCalledWith({
-        channel: 'C0123456789',
-        text: 'Second queued',
-      });
-    });
-  });
-
-  // --- ownsJid ---
-
-  describe('ownsJid', () => {
-    it('owns slack: JIDs', () => {
-      const channel = new SlackChannel(createTestOpts());
-      expect(channel.ownsJid('slack:C0123456789')).toBe(true);
-    });
-
-    it('owns slack: DM JIDs', () => {
-      const channel = new SlackChannel(createTestOpts());
-      expect(channel.ownsJid('slack:D0123456789')).toBe(true);
-    });
-
-    it('does not own WhatsApp group JIDs', () => {
-      const channel = new SlackChannel(createTestOpts());
-      expect(channel.ownsJid('12345@g.us')).toBe(false);
-    });
-
-    it('does not own WhatsApp DM JIDs', () => {
-      const channel = new SlackChannel(createTestOpts());
-      expect(channel.ownsJid('12345@s.whatsapp.net')).toBe(false);
-    });
-
-    it('does not own Telegram JIDs', () => {
-      const channel = new SlackChannel(createTestOpts());
-      expect(channel.ownsJid('tg:123456')).toBe(false);
-    });
-
-    it('does not own unknown JID formats', () => {
-      const channel = new SlackChannel(createTestOpts());
-      expect(channel.ownsJid('random-string')).toBe(false);
-    });
-  });
-
-  // --- syncChannelMetadata ---
-
-  describe('syncChannelMetadata', () => {
-    it('calls conversations.list and updates chat names', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-
-      currentApp().client.conversations.list.mockResolvedValue({
-        channels: [
-          { id: 'C001', name: 'general', is_member: true },
-          { id: 'C002', name: 'random', is_member: true },
-          { id: 'C003', name: 'external', is_member: false },
-        ],
-        response_metadata: {},
-      });
-
-      await channel.connect();
-
-      // connect() calls syncChannelMetadata internally
-      expect(updateChatName).toHaveBeenCalledWith('slack:C001', 'general');
-      expect(updateChatName).toHaveBeenCalledWith('slack:C002', 'random');
-      // Non-member channels are skipped
-      expect(updateChatName).not.toHaveBeenCalledWith('slack:C003', 'external');
-    });
-
-    it('handles API errors gracefully', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-
-      currentApp().client.conversations.list.mockRejectedValue(
-        new Error('API error'),
-      );
-
-      // Should not throw
-      await expect(channel.connect()).resolves.toBeUndefined();
-    });
-  });
-
-  // --- setTyping ---
-
-  describe('setTyping', () => {
-    it('resolves without error (no-op)', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-
-      // Should not throw — Slack has no bot typing indicator API
-      await expect(
-        channel.setTyping('slack:C0123456789', true),
-      ).resolves.toBeUndefined();
-    });
-
-    it('accepts false without error', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-
-      await expect(
-        channel.setTyping('slack:C0123456789', false),
-      ).resolves.toBeUndefined();
-    });
-  });
-
-  // --- Constructor error handling ---
-
-  describe('constructor', () => {
-    it('throws when SLACK_BOT_TOKEN is missing', () => {
-      vi.mocked(readEnvFile).mockReturnValueOnce({
-        SLACK_BOT_TOKEN: '',
-        SLACK_APP_TOKEN: 'xapp-test-token',
-      });
-
-      expect(() => new SlackChannel(createTestOpts())).toThrow(
-        'SLACK_BOT_TOKEN and SLACK_APP_TOKEN must be set in .env',
-      );
-    });
-
-    it('throws when SLACK_APP_TOKEN is missing', () => {
-      vi.mocked(readEnvFile).mockReturnValueOnce({
-        SLACK_BOT_TOKEN: 'xoxb-test-token',
-        SLACK_APP_TOKEN: '',
-      });
-
-      expect(() => new SlackChannel(createTestOpts())).toThrow(
-        'SLACK_BOT_TOKEN and SLACK_APP_TOKEN must be set in .env',
-      );
-    });
-  });
-
-  // --- syncChannelMetadata pagination ---
-
-  describe('syncChannelMetadata pagination', () => {
-    it('paginates through multiple pages of channels', async () => {
-      const opts = createTestOpts();
-      const channel = new SlackChannel(opts);
-
-      // First page returns a cursor; second page returns no cursor
-      currentApp().client.conversations.list
-        .mockResolvedValueOnce({
-          channels: [
-            { id: 'C001', name: 'general', is_member: true },
-          ],
-          response_metadata: { next_cursor: 'cursor_page2' },
-        })
-        .mockResolvedValueOnce({
-          channels: [
-            { id: 'C002', name: 'random', is_member: true },
-          ],
-          response_metadata: {},
-        });
-
-      await channel.connect();
-
-      // Should have called conversations.list twice (once per page)
-      expect(currentApp().client.conversations.list).toHaveBeenCalledTimes(2);
-      expect(currentApp().client.conversations.list).toHaveBeenNthCalledWith(2,
-        expect.objectContaining({ cursor: 'cursor_page2' }),
-      );
-
-      // Both channels from both pages stored
-      expect(updateChatName).toHaveBeenCalledWith('slack:C001', 'general');
-      expect(updateChatName).toHaveBeenCalledWith('slack:C002', 'random');
-    });
-  });
-
-  // --- Channel properties ---
-
-  describe('channel properties', () => {
-    it('has name "slack"', () => {
-      const channel = new SlackChannel(createTestOpts());
-      expect(channel.name).toBe('slack');
-    });
-  });
-});

.claude/skills/add-slack/add/src/channels/slack.ts

@@ -1,300 +0,0 @@
-import { App, LogLevel } from '@slack/bolt';
-import type { GenericMessageEvent, BotMessageEvent } from '@slack/types';
-
-import { ASSISTANT_NAME, TRIGGER_PATTERN } from '../config.js';
-import { updateChatName } from '../db.js';
-import { readEnvFile } from '../env.js';
-import { logger } from '../logger.js';
-import { registerChannel, ChannelOpts } from './registry.js';
-import {
-  Channel,
-  OnInboundMessage,
-  OnChatMetadata,
-  RegisteredGroup,
-} from '../types.js';
-
-// Slack's chat.postMessage API limits text to ~4000 characters per call.
-// Messages exceeding this are split into sequential chunks.
-const MAX_MESSAGE_LENGTH = 4000;
-
-// The message subtypes we process. Bolt delivers all subtypes via app.event('message');
-// we filter to regular messages (GenericMessageEvent, subtype undefined) and bot messages
-// (BotMessageEvent, subtype 'bot_message') so we can track our own output.
-type HandledMessageEvent = GenericMessageEvent | BotMessageEvent;
-
-export interface SlackChannelOpts {
-  onMessage: OnInboundMessage;
-  onChatMetadata: OnChatMetadata;
-  registeredGroups: () => Record<string, RegisteredGroup>;
-}
-
-export class SlackChannel implements Channel {
-  name = 'slack';
-
-  private app: App;
-  private botUserId: string | undefined;
-  private connected = false;
-  private outgoingQueue: Array<{ jid: string; text: string }> = [];
-  private flushing = false;
-  private userNameCache = new Map<string, string>();
-
-  private opts: SlackChannelOpts;
-
-  constructor(opts: SlackChannelOpts) {
-    this.opts = opts;
-
-    // Read tokens from .env (not process.env — keeps secrets off the environment
-    // so they don't leak to child processes, matching NanoClaw's security pattern)
-    const env = readEnvFile(['SLACK_BOT_TOKEN', 'SLACK_APP_TOKEN']);
-    const botToken = env.SLACK_BOT_TOKEN;
-    const appToken = env.SLACK_APP_TOKEN;
-
-    if (!botToken || !appToken) {
-      throw new Error(
-        'SLACK_BOT_TOKEN and SLACK_APP_TOKEN must be set in .env',
-      );
-    }
-
-    this.app = new App({
-      token: botToken,
-      appToken,
-      socketMode: true,
-      logLevel: LogLevel.ERROR,
-    });
-
-    this.setupEventHandlers();
-  }
-
-  private setupEventHandlers(): void {
-    // Use app.event('message') instead of app.message() to capture all
-    // message subtypes including bot_message (needed to track our own output)
-    this.app.event('message', async ({ event }) => {
-      // Bolt's event type is the full MessageEvent union (17+ subtypes).
-      // We filter on subtype first, then narrow to the two types we handle.
-      const subtype = (event as { subtype?: string }).subtype;
-      if (subtype && subtype !== 'bot_message') return;
-
-      // After filtering, event is either GenericMessageEvent or BotMessageEvent
-      const msg = event as HandledMessageEvent;
-
-      if (!msg.text) return;
-
-      // Threaded replies are flattened into the channel conversation.
-      // The agent sees them alongside channel-level messages; responses
-      // always go to the channel, not back into the thread.
-
-      const jid = `slack:${msg.channel}`;
-      const timestamp = new Date(parseFloat(msg.ts) * 1000).toISOString();
-      const isGroup = msg.channel_type !== 'im';
-
-      // Always report metadata for group discovery
-      this.opts.onChatMetadata(jid, timestamp, undefined, 'slack', isGroup);
-
-      // Only deliver full messages for registered groups
-      const groups = this.opts.registeredGroups();
-      if (!groups[jid]) return;
-
-      const isBotMessage =
-        !!msg.bot_id || msg.user === this.botUserId;
-
-      let senderName: string;
-      if (isBotMessage) {
-        senderName = ASSISTANT_NAME;
-      } else {
-        senderName =
-          (await this.resolveUserName(msg.user)) ||
-          msg.user ||
-          'unknown';
-      }
-
-      // Translate Slack <@UBOTID> mentions into TRIGGER_PATTERN format.
-      // Slack encodes @mentions as <@U12345>, which won't match TRIGGER_PATTERN
-      // (e.g., ^@<ASSISTANT_NAME>\b), so we prepend the trigger when the bot is @mentioned.
-      let content = msg.text;
-      if (this.botUserId && !isBotMessage) {
-        const mentionPattern = `<@${this.botUserId}>`;
-        if (content.includes(mentionPattern) && !TRIGGER_PATTERN.test(content)) {
-          content = `@${ASSISTANT_NAME} ${content}`;
-        }
-      }
-
-      this.opts.onMessage(jid, {
-        id: msg.ts,
-        chat_jid: jid,
-        sender: msg.user || msg.bot_id || '',
-        sender_name: senderName,
-        content,
-        timestamp,
-        is_from_me: isBotMessage,
-        is_bot_message: isBotMessage,
-      });
-    });
-  }
-
-  async connect(): Promise<void> {
-    await this.app.start();
-
-    // Get bot's own user ID for self-message detection.
-    // Resolve this BEFORE setting connected=true so that messages arriving
-    // during startup can correctly detect bot-sent messages.
-    try {
-      const auth = await this.app.client.auth.test();
-      this.botUserId = auth.user_id as string;
-      logger.info({ botUserId: this.botUserId }, 'Connected to Slack');
-    } catch (err) {
-      logger.warn(
-        { err },
-        'Connected to Slack but failed to get bot user ID',
-      );
-    }
-
-    this.connected = true;
-
-    // Flush any messages queued before connection
-    await this.flushOutgoingQueue();
-
-    // Sync channel names on startup
-    await this.syncChannelMetadata();
-  }
-
-  async sendMessage(jid: string, text: string): Promise<void> {
-    const channelId = jid.replace(/^slack:/, '');
-
-    if (!this.connected) {
-      this.outgoingQueue.push({ jid, text });
-      logger.info(
-        { jid, queueSize: this.outgoingQueue.length },
-        'Slack disconnected, message queued',
-      );
-      return;
-    }
-
-    try {
-      // Slack limits messages to ~4000 characters; split if needed
-      if (text.length <= MAX_MESSAGE_LENGTH) {
-        await this.app.client.chat.postMessage({ channel: channelId, text });
-      } else {
-        for (let i = 0; i < text.length; i += MAX_MESSAGE_LENGTH) {
-          await this.app.client.chat.postMessage({
-            channel: channelId,
-            text: text.slice(i, i + MAX_MESSAGE_LENGTH),
-          });
-        }
-      }
-      logger.info({ jid, length: text.length }, 'Slack message sent');
-    } catch (err) {
-      this.outgoingQueue.push({ jid, text });
-      logger.warn(
-        { jid, err, queueSize: this.outgoingQueue.length },
-        'Failed to send Slack message, queued',
-      );
-    }
-  }
-
-  isConnected(): boolean {
-    return this.connected;
-  }
-
-  ownsJid(jid: string): boolean {
-    return jid.startsWith('slack:');
-  }
-
-  async disconnect(): Promise<void> {
-    this.connected = false;
-    await this.app.stop();
-  }
-
-  // Slack does not expose a typing indicator API for bots.
-  // This no-op satisfies the Channel interface so the orchestrator
-  // doesn't need channel-specific branching.
-  async setTyping(_jid: string, _isTyping: boolean): Promise<void> {
-    // no-op: Slack Bot API has no typing indicator endpoint
-  }
-
-  /**
-   * Sync channel metadata from Slack.
-   * Fetches channels the bot is a member of and stores their names in the DB.
-   */
-  async syncChannelMetadata(): Promise<void> {
-    try {
-      logger.info('Syncing channel metadata from Slack...');
-      let cursor: string | undefined;
-      let count = 0;
-
-      do {
-        const result = await this.app.client.conversations.list({
-          types: 'public_channel,private_channel',
-          exclude_archived: true,
-          limit: 200,
-          cursor,
-        });
-
-        for (const ch of result.channels || []) {
-          if (ch.id && ch.name && ch.is_member) {
-            updateChatName(`slack:${ch.id}`, ch.name);
-            count++;
-          }
-        }
-
-        cursor = result.response_metadata?.next_cursor || undefined;
-      } while (cursor);
-
-      logger.info({ count }, 'Slack channel metadata synced');
-    } catch (err) {
-      logger.error({ err }, 'Failed to sync Slack channel metadata');
-    }
-  }
-
-  private async resolveUserName(
-    userId: string,
-  ): Promise<string | undefined> {
-    if (!userId) return undefined;
-
-    const cached = this.userNameCache.get(userId);
-    if (cached) return cached;
-
-    try {
-      const result = await this.app.client.users.info({ user: userId });
-      const name = result.user?.real_name || result.user?.name;
-      if (name) this.userNameCache.set(userId, name);
-      return name;
-    } catch (err) {
-      logger.debug({ userId, err }, 'Failed to resolve Slack user name');
-      return undefined;
-    }
-  }
-
-  private async flushOutgoingQueue(): Promise<void> {
-    if (this.flushing || this.outgoingQueue.length === 0) return;
-    this.flushing = true;
-    try {
-      logger.info(
-        { count: this.outgoingQueue.length },
-        'Flushing Slack outgoing queue',
-      );
-      while (this.outgoingQueue.length > 0) {
-        const item = this.outgoingQueue.shift()!;
-        const channelId = item.jid.replace(/^slack:/, '');
-        await this.app.client.chat.postMessage({
-          channel: channelId,
-          text: item.text,
-        });
-        logger.info(
-          { jid: item.jid, length: item.text.length },
-          'Queued Slack message sent',
-        );
-      }
-    } finally {
-      this.flushing = false;
-    }
-  }
-}
-
-registerChannel('slack', (opts: ChannelOpts) => {
-  const envVars = readEnvFile(['SLACK_BOT_TOKEN', 'SLACK_APP_TOKEN']);
-  if (!envVars.SLACK_BOT_TOKEN || !envVars.SLACK_APP_TOKEN) {
-    logger.warn('Slack: SLACK_BOT_TOKEN or SLACK_APP_TOKEN not set');
-    return null;
-  }
-  return new SlackChannel(opts);
-});

.claude/skills/add-slack/manifest.yaml

@@ -1,18 +0,0 @@
-skill: slack
-version: 1.0.0
-description: "Slack Bot integration via @slack/bolt with Socket Mode"
-core_version: 0.1.0
-adds:
-  - src/channels/slack.ts
-  - src/channels/slack.test.ts
-modifies:
-  - src/channels/index.ts
-structured:
-  npm_dependencies:
-    "@slack/bolt": "^4.6.0"
-  env_additions:
-    - SLACK_BOT_TOKEN
-    - SLACK_APP_TOKEN
-conflicts: []
-depends: []
-test: "npx vitest run src/channels/slack.test.ts"

.claude/skills/add-slack/modify/src/channels/index.ts

@@ -1,13 +0,0 @@
-// Channel self-registration barrel file.
-// Each import triggers the channel module's registerChannel() call.
-
-// discord
-
-// gmail
-
-// slack
-import './slack.js';
-
-// telegram
-
-// whatsapp

.claude/skills/add-slack/modify/src/channels/index.ts.intent.md

@@ -1,7 +0,0 @@
-# Intent: Add Slack channel import
-
-Add `import './slack.js';` to the channel barrel file so the Slack
-module self-registers with the channel registry on startup.
-
-This is an append-only change — existing import lines for other channels
-must be preserved.

.claude/skills/add-slack/tests/slack.test.ts

@@ -1,100 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import fs from 'fs';
-import path from 'path';
-
-describe('slack skill package', () => {
-  const skillDir = path.resolve(__dirname, '..');
-
-  it('has a valid manifest', () => {
-    const manifestPath = path.join(skillDir, 'manifest.yaml');
-    expect(fs.existsSync(manifestPath)).toBe(true);
-
-    const content = fs.readFileSync(manifestPath, 'utf-8');
-    expect(content).toContain('skill: slack');
-    expect(content).toContain('version: 1.0.0');
-    expect(content).toContain('@slack/bolt');
-  });
-
-  it('has all files declared in adds', () => {
-    const channelFile = path.join(
-      skillDir,
-      'add',
-      'src',
-      'channels',
-      'slack.ts',
-    );
-    expect(fs.existsSync(channelFile)).toBe(true);
-
-    const content = fs.readFileSync(channelFile, 'utf-8');
-    expect(content).toContain('class SlackChannel');
-    expect(content).toContain('implements Channel');
-    expect(content).toContain("registerChannel('slack'");
-
-    // Test file for the channel
-    const testFile = path.join(
-      skillDir,
-      'add',
-      'src',
-      'channels',
-      'slack.test.ts',
-    );
-    expect(fs.existsSync(testFile)).toBe(true);
-
-    const testContent = fs.readFileSync(testFile, 'utf-8');
-    expect(testContent).toContain("describe('SlackChannel'");
-  });
-
-  it('has all files declared in modifies', () => {
-    // Channel barrel file
-    const indexFile = path.join(
-      skillDir,
-      'modify',
-      'src',
-      'channels',
-      'index.ts',
-    );
-    expect(fs.existsSync(indexFile)).toBe(true);
-
-    const indexContent = fs.readFileSync(indexFile, 'utf-8');
-    expect(indexContent).toContain("import './slack.js'");
-  });
-
-  it('has intent files for modified files', () => {
-    expect(
-      fs.existsSync(
-        path.join(skillDir, 'modify', 'src', 'channels', 'index.ts.intent.md'),
-      ),
-    ).toBe(true);
-  });
-
-  it('has setup documentation', () => {
-    expect(fs.existsSync(path.join(skillDir, 'SKILL.md'))).toBe(true);
-    expect(fs.existsSync(path.join(skillDir, 'SLACK_SETUP.md'))).toBe(true);
-  });
-
-  it('slack.ts implements required Channel interface methods', () => {
-    const content = fs.readFileSync(
-      path.join(skillDir, 'add', 'src', 'channels', 'slack.ts'),
-      'utf-8',
-    );
-
-    // Channel interface methods
-    expect(content).toContain('async connect()');
-    expect(content).toContain('async sendMessage(');
-    expect(content).toContain('isConnected()');
-    expect(content).toContain('ownsJid(');
-    expect(content).toContain('async disconnect()');
-    expect(content).toContain('async setTyping(');
-
-    // Security pattern: reads tokens from .env, not process.env
-    expect(content).toContain('readEnvFile');
-    expect(content).not.toContain('process.env.SLACK_BOT_TOKEN');
-    expect(content).not.toContain('process.env.SLACK_APP_TOKEN');
-
-    // Key behaviors
-    expect(content).toContain('socketMode: true');
-    expect(content).toContain('MAX_MESSAGE_LENGTH');
-    expect(content).toContain('TRIGGER_PATTERN');
-    expect(content).toContain('userNameCache');
-  });
-});

.claude/skills/add-teams-v2/REMOVE.md

@@ -0,0 +1,6 @@
+# Remove Microsoft Teams Channel
+
+1. Comment out `import './teams.js'` in `src/channels/index.ts`
+2. Remove `TEAMS_APP_ID` and `TEAMS_APP_PASSWORD` from `.env`
+3. `pnpm uninstall @chat-adapter/teams`
+4. Rebuild and restart

.claude/skills/add-teams-v2/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: add-teams-v2
+description: Add Microsoft Teams channel integration to NanoClaw v2 via Chat SDK.
+---
+
+# Add Microsoft Teams Channel
+
+Connect NanoClaw to Microsoft Teams for interactive chat in team channels, group chats, and direct messages.
+
+## Pre-flight
+
+Check if `src/channels/teams.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Credentials.
+
+## Install
+
+```bash
+pnpm install @chat-adapter/teams
+```
+
+Uncomment the Teams import in `src/channels/index.ts`:
+
+```typescript
+import './teams.js';
+```
+
+Build:
+
+```bash
+pnpm run build
+```
+
+## Credentials
+
+### Step 1: Create an Azure AD App Registration
+
+1. Go to [Azure Portal](https://portal.azure.com) > **App registrations** > **New registration**
+2. Name it (e.g., "NanoClaw")
+3. Supported account types: **Single tenant** (your org only) or **Multi tenant** (any org)
+4. Click **Register**
+5. Copy the **Application (client) ID** and **Directory (tenant) ID** from the Overview page
+
+### Step 2: Create a Client Secret
+
+1. In the App Registration, go to **Certificates & secrets**
+2. Click **New client secret**, description "nanoclaw", expiry 180 days
+3. Click **Add** and **copy the Value immediately** (shown only once)
+
+### Step 3: Create an Azure Bot
+
+1. Go to Azure Portal > search **Azure Bot** > **Create**
+2. Fill in:
+   - **Bot handle**: unique name (e.g., "nanoclaw-bot")
+   - **Type of App**: match your app registration (Single or Multi Tenant)
+   - **Creation type**: **Use existing app registration**
+   - **App ID**: paste from Step 1
+   - **App tenant ID**: paste from Step 1 (Single Tenant only)
+3. Click **Review + create** > **Create**
+
+Or use Azure CLI:
+
+```bash
+az group create --name nanoclaw-rg --location eastus
+az bot create \
+  --resource-group nanoclaw-rg \
+  --name nanoclaw-bot \
+  --app-type SingleTenant \
+  --appid YOUR_APP_ID \
+  --tenant-id YOUR_TENANT_ID \
+  --endpoint "https://your-domain/api/webhooks/teams"
+```
+
+### Step 4: Configure Messaging Endpoint
+
+1. Go to your Azure Bot resource > **Configuration**
+2. Set **Messaging endpoint** to `https://your-domain/api/webhooks/teams`
+3. Click **Apply**
+
+### Step 5: Enable Teams Channel
+
+1. In the Azure Bot resource, go to **Channels**
+2. Click **Microsoft Teams** > Accept terms > **Apply**
+
+Or via CLI:
+
+```bash
+az bot msteams create --resource-group nanoclaw-rg --name nanoclaw-bot
+```
+
+### Step 6: Create and Sideload Teams App
+
+Create a `manifest.json`:
+
+```json
+{
+  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.16/MicrosoftTeams.schema.json",
+  "manifestVersion": "1.16",
+  "version": "1.0.0",
+  "id": "YOUR_APP_ID",
+  "packageName": "com.nanoclaw.bot",
+  "developer": {
+    "name": "NanoClaw",
+    "websiteUrl": "https://your-domain",
+    "privacyUrl": "https://your-domain",
+    "termsOfUseUrl": "https://your-domain"
+  },
+  "name": { "short": "NanoClaw", "full": "NanoClaw Assistant" },
+  "description": {
+    "short": "NanoClaw assistant bot",
+    "full": "NanoClaw personal assistant powered by Claude."
+  },
+  "icons": { "outline": "outline.png", "color": "color.png" },
+  "accentColor": "#4A90D9",
+  "bots": [{
+    "botId": "YOUR_APP_ID",
+    "scopes": ["personal", "team", "groupchat"],
+    "supportsFiles": false,
+    "isNotificationOnly": false
+  }],
+  "permissions": ["identity", "messageTeamMembers"],
+  "validDomains": ["your-domain"]
+}
+```
+
+Create two icon PNGs (32x32 `outline.png`, 192x192 `color.png`), zip all three files together.
+
+**Sideload in Teams:**
+1. Open Teams > **Apps** > **Manage your apps**
+2. Click **Upload an app** > **Upload a custom app**
+3. Select the zip file
+
+Sideloading requires Teams admin access. Free personal Teams does NOT support sideloading. Use a Microsoft 365 Business account or developer tenant.
+
+### Step 7: Receive All Messages (Optional)
+
+By default, the bot only receives messages when @-mentioned. To receive all messages in a channel without @-mention, add RSC permissions to `manifest.json`:
+
+```json
+{
+  "authorization": {
+    "permissions": {
+      "resourceSpecific": [
+        { "name": "ChannelMessage.Read.Group", "type": "Application" }
+      ]
+    }
+  }
+}
+```
+
+### Configure environment
+
+Add to `.env`:
+
+```bash
+TEAMS_APP_ID=your-app-id
+TEAMS_APP_PASSWORD=your-client-secret
+# For Single Tenant only:
+TEAMS_APP_TENANT_ID=your-tenant-id
+TEAMS_APP_TYPE=SingleTenant
+```
+
+Sync to container: `mkdir -p data/env && cp .env data/env/env`
+
+### Webhook server
+
+The Chat SDK bridge automatically starts a shared webhook server on port 3000 (configurable via `WEBHOOK_PORT` env var). The server handles `/api/webhooks/teams` for Teams and other webhook-based adapters. This port must be publicly reachable from the internet for Azure Bot Service to deliver activities.
+
+For local development without a public URL, use a tunnel (e.g., `ngrok http 3000`) and update the messaging endpoint in Azure Bot Configuration.
+
+## Next Steps
+
+If you're in the middle of `/setup`, return to the setup flow now.
+
+Otherwise, run `/manage-channels` to wire this channel to an agent group.
+
+## Channel Info
+
+- **type**: `teams`
+- **terminology**: Teams has "teams" containing "channels." The bot can also receive DMs (personal scope) and group chat messages. Channels support threaded replies.
+- **platform-id-format**: `teams:{base64-encoded-conversation-id}:{base64-encoded-service-url}` — auto-generated by the adapter, not human-readable. Use the auto-created messaging group ID for wiring.
+- **how-to-find-id**: Send a message to the bot in the channel. NanoClaw auto-creates a messaging group and logs the platform ID. Use that messaging group ID for wiring.
+- **supports-threads**: yes (channels only; DMs and group chats are flat)
+- **typical-use**: Team collaboration with the bot in channels; personal assistant via DMs
+- **default-isolation**: Separate agent group per team. DMs can share an agent group with your main channel for unified personal memory.

.claude/skills/add-teams-v2/VERIFY.md

@@ -0,0 +1,3 @@
+# Verify Microsoft Teams Channel
+
+Add the bot to a Teams channel or send it a direct message. The bot should respond within a few seconds.

.claude/skills/add-telegram-swarm/SKILL.md

@@ -319,7 +319,7 @@ Also add `TELEGRAM_BOT_POOL` to the launchd plist (`~/Library/LaunchAgents/com.n
 ### Step 7: Rebuild and Restart
 
 ```bash
-npm run build
+pnpm run build
 ./container/build.sh  # Required — MCP tool changed
 # macOS:
 launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
@@ -381,4 +381,4 @@ To remove Agent Swarm support while keeping basic Telegram:
 5. Remove `sender` param from MCP tool in `container/agent-runner/src/ipc-mcp-stdio.ts`
 6. Remove Agent Teams section from group CLAUDE.md files
 7. Remove `TELEGRAM_BOT_POOL` from `.env`, `data/env/env`, and launchd plist/systemd unit
-8. Rebuild: `npm run build && ./container/build.sh && launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist && launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist` (macOS) or `npm run build && ./container/build.sh && systemctl --user restart nanoclaw` (Linux)
+8. Rebuild: `pnpm run build && ./container/build.sh && launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist && launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist` (macOS) or `pnpm run build && ./container/build.sh && systemctl --user restart nanoclaw` (Linux)

.claude/skills/add-telegram-v2/REMOVE.md

@@ -0,0 +1,6 @@
+# Remove Telegram
+
+1. Comment out `import './telegram.js'` in `src/channels/index.ts`
+2. Remove `TELEGRAM_BOT_TOKEN` from `.env`
+3. `pnpm uninstall @chat-adapter/telegram`
+4. Rebuild and restart

.claude/skills/add-telegram-v2/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: add-telegram-v2
+description: Add Telegram channel integration to NanoClaw v2 via Chat SDK.
+---
+
+# Add Telegram Channel
+
+Adds Telegram bot support to NanoClaw v2 using the Chat SDK bridge.
+
+## Pre-flight
+
+Check if `src/channels/telegram.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Credentials.
+
+## Install
+
+### Install the adapter package
+
+```bash
+pnpm install @chat-adapter/telegram
+```
+
+### Enable the channel
+
+Uncomment the Telegram import in `src/channels/index.ts`:
+
+```typescript
+import './telegram.js';
+```
+
+### Build
+
+```bash
+pnpm run build
+```
+
+## Credentials
+
+### Create Telegram Bot
+
+1. Open Telegram and search for `@BotFather`
+2. Send `/newbot` and follow the prompts:
+   - Bot name: Something friendly (e.g., "NanoClaw Assistant")
+   - Bot username: Must end with "bot" (e.g., "nanoclaw_bot")
+3. Copy the bot token (looks like `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`)
+
+**Important for group chats**: By default, Telegram bots only see @mentions and commands in groups. To let the bot see all messages:
+
+1. Open `@BotFather` > `/mybots` > select your bot
+2. **Bot Settings** > **Group Privacy** > **Turn off**
+
+### Configure environment
+
+Add to `.env`:
+
+```bash
+TELEGRAM_BOT_TOKEN=your-bot-token
+```
+
+Sync to container: `mkdir -p data/env && cp .env data/env/env`
+
+## Next Steps
+
+If you're in the middle of `/setup`, return to the setup flow now.
+
+Otherwise, run `/manage-channels` to wire this channel to an agent group.
+
+## Channel Info
+
+- **type**: `telegram`
+- **terminology**: Telegram calls them "groups" and "chats." A "group" has multiple members; a "chat" is a 1:1 conversation with the bot.
+- **how-to-find-id**: Do NOT ask the user for a chat ID. Telegram registration uses pairing — run `pnpm exec tsx setup/index.ts --step pair-telegram -- --intent <main|wire-to:folder|new-agent:folder>`, show the user the 4-digit `CODE` from the `PAIR_TELEGRAM_ISSUED` block (follow the `REMINDER_TO_ASSISTANT` line in that block), and tell them to send just the 4 digits as a message from the chat they want to register (DM the bot for `main`, post in the group otherwise). In groups with Group Privacy ON, prefix with the bot handle: `@<botname> CODE`. Wrong guesses invalidate the code — if a `PAIR_TELEGRAM_ATTEMPT` block arrives with a mismatched `RECEIVED_CODE`, a `PAIR_TELEGRAM_NEW_CODE` block will follow automatically (up to 5 regenerations); show the new code. On `PAIR_TELEGRAM STATUS=failed ERROR=max-regenerations-exceeded`, ask the user if they want to try again and re-invoke the step — each invocation starts a fresh 5-attempt batch. Success emits `PAIR_TELEGRAM STATUS=success` with `PLATFORM_ID`, `IS_GROUP`, and `ADMIN_USER_ID`. The service must be running for this to work (the polling adapter is what observes the code).
+- **supports-threads**: no
+- **typical-use**: Interactive chat — direct messages or small groups
+- **default-isolation**: Same agent group if you're the only participant across multiple chats. Separate agent group if different people are in different groups.

.claude/skills/add-telegram-v2/VERIFY.md

@@ -0,0 +1,3 @@
+# Verify Telegram
+
+Send a message to your bot in Telegram (search for its username), or add the bot to a group and send a message there. The bot should respond within a few seconds.

.claude/skills/add-telegram/SKILL.md

@@ -5,13 +5,13 @@ description: Add Telegram as a channel. Can replace WhatsApp entirely or run alo
 
 # Add Telegram Channel
 
-This skill adds Telegram support to NanoClaw using the skills engine for deterministic code changes, then walks through interactive setup.
+This skill adds Telegram support to NanoClaw, then walks through interactive setup.
 
 ## Phase 1: Pre-flight
 
 ### Check if already applied
 
-Read `.nanoclaw/state.yaml`. If `telegram` is in `applied_skills`, skip to Phase 3 (Setup). The code changes are already in place.
+Check if `src/channels/telegram.ts` exists. If it does, skip to Phase 3 (Setup). The code changes are already in place.
 
 ### Ask the user
 
@@ -23,43 +23,47 @@ If they have one, collect it now. If not, we'll create one in Phase 3.
 
 ## Phase 2: Apply Code Changes
 
-Run the skills engine to apply this skill's code package. The package files are in this directory alongside this SKILL.md.
-
-### Initialize skills system (if needed)
-
-If `.nanoclaw/` directory doesn't exist yet:
+### Ensure channel remote
 
 ```bash
-npx tsx scripts/apply-skill.ts --init
+git remote -v
 ```
 
-Or call `initSkillsSystem()` from `skills-engine/migrate.ts`.
-
-### Apply the skill
+If `telegram` is missing, add it:
 
 ```bash
-npx tsx scripts/apply-skill.ts .claude/skills/add-telegram
+git remote add telegram https://github.com/qwibitai/nanoclaw-telegram.git
 ```
 
-This deterministically:
-- Adds `src/channels/telegram.ts` (TelegramChannel class with self-registration via `registerChannel`)
-- Adds `src/channels/telegram.test.ts` (46 unit tests)
-- Appends `import './telegram.js'` to the channel barrel file `src/channels/index.ts`
-- Installs the `grammy` npm dependency
-- Updates `.env.example` with `TELEGRAM_BOT_TOKEN`
-- Records the application in `.nanoclaw/state.yaml`
+### Merge the skill branch
 
-If the apply reports merge conflicts, read the intent file:
-- `modify/src/channels/index.ts.intent.md` — what changed and invariants
+```bash
+git fetch telegram main
+git merge telegram/main || {
+  git checkout --theirs pnpm-lock.yaml
+  git add pnpm-lock.yaml
+  git merge --continue
+}
+```
+
+This merges in:
+- `src/channels/telegram.ts` (TelegramChannel class with self-registration via `registerChannel`)
+- `src/channels/telegram.test.ts` (unit tests with grammy mock)
+- `import './telegram.js'` appended to the channel barrel file `src/channels/index.ts`
+- `grammy` npm dependency in `package.json`
+- `TELEGRAM_BOT_TOKEN` in `.env.example`
+
+If the merge reports conflicts, resolve them by reading the conflicted files and understanding the intent of both sides.
 
 ### Validate code changes
 
 ```bash
-npm test
-npm run build
+pnpm install
+pnpm run build
+pnpm exec vitest run src/channels/telegram.test.ts
 ```
 
-All tests must pass (including the new telegram tests) and build must be clean before proceeding.
+All tests must pass (including the new Telegram tests) and build must be clean before proceeding.
 
 ## Phase 3: Setup
 
@@ -110,7 +114,7 @@ Tell the user:
 ### Build and restart
 
 ```bash
-npm run build
+pnpm run build
 launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
 # Linux: systemctl --user restart nanoclaw
 ```
@@ -129,31 +133,18 @@ Wait for the user to provide the chat ID (format: `tg:123456789` or `tg:-1001234
 
 ### Register the chat
 
-Use the IPC register flow or register directly. The chat ID, name, and folder name are needed.
+The chat ID, name, and folder name are needed. Use `pnpm exec tsx setup/index.ts --step register` with the appropriate flags.
 
 For a main chat (responds to all messages):
 
-```typescript
-registerGroup("tg:<chat-id>", {
-  name: "<chat-name>",
-  folder: "telegram_main",
-  trigger: `@${ASSISTANT_NAME}`,
-  added_at: new Date().toISOString(),
-  requiresTrigger: false,
-  isMain: true,
-});
+```bash
+pnpm exec tsx setup/index.ts --step register -- --jid "tg:<chat-id>" --name "<chat-name>" --folder "telegram_main" --trigger "@${ASSISTANT_NAME}" --channel telegram --no-trigger-required --is-main
 ```
 
 For additional chats (trigger-only):
 
-```typescript
-registerGroup("tg:<chat-id>", {
-  name: "<chat-name>",
-  folder: "telegram_<group-name>",
-  trigger: `@${ASSISTANT_NAME}`,
-  added_at: new Date().toISOString(),
-  requiresTrigger: true,
-});
+```bash
+pnpm exec tsx setup/index.ts --step register -- --jid "tg:<chat-id>" --name "<chat-name>" --folder "telegram_<group-name>" --trigger "@${ASSISTANT_NAME}" --channel telegram
 ```
 
 ## Phase 5: Verify
@@ -198,27 +189,19 @@ If `/chatid` doesn't work:
 
 ## After Setup
 
-If running `npm run dev` while the service is active:
+If running `pnpm run dev` while the service is active:
 ```bash
 # macOS:
 launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
-npm run dev
+pnpm run dev
 # When done testing:
 launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
 # Linux:
 # systemctl --user stop nanoclaw
-# npm run dev
+# pnpm run dev
 # systemctl --user start nanoclaw
 ```
 
-## Agent Swarms (Teams)
-
-After completing the Telegram setup, use `AskUserQuestion`:
-
-AskUserQuestion: Would you like to add Agent Swarm support? Without it, Agent Teams still work — they just operate behind the scenes. With Swarm support, each subagent appears as a different bot in the Telegram group so you can see who's saying what and have interactive team sessions.
-
-If they say yes, invoke the `/add-telegram-swarm` skill.
-
 ## Removal
 
 To remove Telegram integration:
@@ -227,5 +210,5 @@ To remove Telegram integration:
 2. Remove `import './telegram.js'` from `src/channels/index.ts`
 3. Remove `TELEGRAM_BOT_TOKEN` from `.env`
 4. Remove Telegram registrations from SQLite: `sqlite3 store/messages.db "DELETE FROM registered_groups WHERE jid LIKE 'tg:%'"`
-5. Uninstall: `npm uninstall grammy`
-6. Rebuild: `npm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw` (macOS) or `npm run build && systemctl --user restart nanoclaw` (Linux)
+5. Uninstall: `pnpm uninstall grammy`
+6. Rebuild: `pnpm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw` (macOS) or `pnpm run build && systemctl --user restart nanoclaw` (Linux)

.claude/skills/add-telegram/add/src/channels/telegram.test.ts

@@ -1,932 +0,0 @@
-import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
-
-// --- Mocks ---
-
-// Mock registry (registerChannel runs at import time)
-vi.mock('./registry.js', () => ({ registerChannel: vi.fn() }));
-
-// Mock env reader (used by the factory, not needed in unit tests)
-vi.mock('../env.js', () => ({ readEnvFile: vi.fn(() => ({})) }));
-
-// Mock config
-vi.mock('../config.js', () => ({
-  ASSISTANT_NAME: 'Andy',
-  TRIGGER_PATTERN: /^@Andy\b/i,
-}));
-
-// Mock logger
-vi.mock('../logger.js', () => ({
-  logger: {
-    debug: vi.fn(),
-    info: vi.fn(),
-    warn: vi.fn(),
-    error: vi.fn(),
-  },
-}));
-
-// --- Grammy mock ---
-
-type Handler = (...args: any[]) => any;
-
-const botRef = vi.hoisted(() => ({ current: null as any }));
-
-vi.mock('grammy', () => ({
-  Bot: class MockBot {
-    token: string;
-    commandHandlers = new Map<string, Handler>();
-    filterHandlers = new Map<string, Handler[]>();
-    errorHandler: Handler | null = null;
-
-    api = {
-      sendMessage: vi.fn().mockResolvedValue(undefined),
-      sendChatAction: vi.fn().mockResolvedValue(undefined),
-    };
-
-    constructor(token: string) {
-      this.token = token;
-      botRef.current = this;
-    }
-
-    command(name: string, handler: Handler) {
-      this.commandHandlers.set(name, handler);
-    }
-
-    on(filter: string, handler: Handler) {
-      const existing = this.filterHandlers.get(filter) || [];
-      existing.push(handler);
-      this.filterHandlers.set(filter, existing);
-    }
-
-    catch(handler: Handler) {
-      this.errorHandler = handler;
-    }
-
-    start(opts: { onStart: (botInfo: any) => void }) {
-      opts.onStart({ username: 'andy_ai_bot', id: 12345 });
-    }
-
-    stop() {}
-  },
-}));
-
-import { TelegramChannel, TelegramChannelOpts } from './telegram.js';
-
-// --- Test helpers ---
-
-function createTestOpts(
-  overrides?: Partial<TelegramChannelOpts>,
-): TelegramChannelOpts {
-  return {
-    onMessage: vi.fn(),
-    onChatMetadata: vi.fn(),
-    registeredGroups: vi.fn(() => ({
-      'tg:100200300': {
-        name: 'Test Group',
-        folder: 'test-group',
-        trigger: '@Andy',
-        added_at: '2024-01-01T00:00:00.000Z',
-      },
-    })),
-    ...overrides,
-  };
-}
-
-function createTextCtx(overrides: {
-  chatId?: number;
-  chatType?: string;
-  chatTitle?: string;
-  text: string;
-  fromId?: number;
-  firstName?: string;
-  username?: string;
-  messageId?: number;
-  date?: number;
-  entities?: any[];
-}) {
-  const chatId = overrides.chatId ?? 100200300;
-  const chatType = overrides.chatType ?? 'group';
-  return {
-    chat: {
-      id: chatId,
-      type: chatType,
-      title: overrides.chatTitle ?? 'Test Group',
-    },
-    from: {
-      id: overrides.fromId ?? 99001,
-      first_name: overrides.firstName ?? 'Alice',
-      username: overrides.username ?? 'alice_user',
-    },
-    message: {
-      text: overrides.text,
-      date: overrides.date ?? Math.floor(Date.now() / 1000),
-      message_id: overrides.messageId ?? 1,
-      entities: overrides.entities ?? [],
-    },
-    me: { username: 'andy_ai_bot' },
-    reply: vi.fn(),
-  };
-}
-
-function createMediaCtx(overrides: {
-  chatId?: number;
-  chatType?: string;
-  fromId?: number;
-  firstName?: string;
-  date?: number;
-  messageId?: number;
-  caption?: string;
-  extra?: Record<string, any>;
-}) {
-  const chatId = overrides.chatId ?? 100200300;
-  return {
-    chat: {
-      id: chatId,
-      type: overrides.chatType ?? 'group',
-      title: 'Test Group',
-    },
-    from: {
-      id: overrides.fromId ?? 99001,
-      first_name: overrides.firstName ?? 'Alice',
-      username: 'alice_user',
-    },
-    message: {
-      date: overrides.date ?? Math.floor(Date.now() / 1000),
-      message_id: overrides.messageId ?? 1,
-      caption: overrides.caption,
-      ...(overrides.extra || {}),
-    },
-    me: { username: 'andy_ai_bot' },
-  };
-}
-
-function currentBot() {
-  return botRef.current;
-}
-
-async function triggerTextMessage(ctx: ReturnType<typeof createTextCtx>) {
-  const handlers = currentBot().filterHandlers.get('message:text') || [];
-  for (const h of handlers) await h(ctx);
-}
-
-async function triggerMediaMessage(
-  filter: string,
-  ctx: ReturnType<typeof createMediaCtx>,
-) {
-  const handlers = currentBot().filterHandlers.get(filter) || [];
-  for (const h of handlers) await h(ctx);
-}
-
-// --- Tests ---
-
-describe('TelegramChannel', () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  // --- Connection lifecycle ---
-
-  describe('connection lifecycle', () => {
-    it('resolves connect() when bot starts', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-
-      await channel.connect();
-
-      expect(channel.isConnected()).toBe(true);
-    });
-
-    it('registers command and message handlers on connect', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-
-      await channel.connect();
-
-      expect(currentBot().commandHandlers.has('chatid')).toBe(true);
-      expect(currentBot().commandHandlers.has('ping')).toBe(true);
-      expect(currentBot().filterHandlers.has('message:text')).toBe(true);
-      expect(currentBot().filterHandlers.has('message:photo')).toBe(true);
-      expect(currentBot().filterHandlers.has('message:video')).toBe(true);
-      expect(currentBot().filterHandlers.has('message:voice')).toBe(true);
-      expect(currentBot().filterHandlers.has('message:audio')).toBe(true);
-      expect(currentBot().filterHandlers.has('message:document')).toBe(true);
-      expect(currentBot().filterHandlers.has('message:sticker')).toBe(true);
-      expect(currentBot().filterHandlers.has('message:location')).toBe(true);
-      expect(currentBot().filterHandlers.has('message:contact')).toBe(true);
-    });
-
-    it('registers error handler on connect', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-
-      await channel.connect();
-
-      expect(currentBot().errorHandler).not.toBeNull();
-    });
-
-    it('disconnects cleanly', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-
-      await channel.connect();
-      expect(channel.isConnected()).toBe(true);
-
-      await channel.disconnect();
-      expect(channel.isConnected()).toBe(false);
-    });
-
-    it('isConnected() returns false before connect', () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-
-      expect(channel.isConnected()).toBe(false);
-    });
-  });
-
-  // --- Text message handling ---
-
-  describe('text message handling', () => {
-    it('delivers message for registered group', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const ctx = createTextCtx({ text: 'Hello everyone' });
-      await triggerTextMessage(ctx);
-
-      expect(opts.onChatMetadata).toHaveBeenCalledWith(
-        'tg:100200300',
-        expect.any(String),
-        'Test Group',
-        'telegram',
-        true,
-      );
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'tg:100200300',
-        expect.objectContaining({
-          id: '1',
-          chat_jid: 'tg:100200300',
-          sender: '99001',
-          sender_name: 'Alice',
-          content: 'Hello everyone',
-          is_from_me: false,
-        }),
-      );
-    });
-
-    it('only emits metadata for unregistered chats', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const ctx = createTextCtx({ chatId: 999999, text: 'Unknown chat' });
-      await triggerTextMessage(ctx);
-
-      expect(opts.onChatMetadata).toHaveBeenCalledWith(
-        'tg:999999',
-        expect.any(String),
-        'Test Group',
-        'telegram',
-        true,
-      );
-      expect(opts.onMessage).not.toHaveBeenCalled();
-    });
-
-    it('skips command messages (starting with /)', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const ctx = createTextCtx({ text: '/start' });
-      await triggerTextMessage(ctx);
-
-      expect(opts.onMessage).not.toHaveBeenCalled();
-      expect(opts.onChatMetadata).not.toHaveBeenCalled();
-    });
-
-    it('extracts sender name from first_name', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const ctx = createTextCtx({ text: 'Hi', firstName: 'Bob' });
-      await triggerTextMessage(ctx);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'tg:100200300',
-        expect.objectContaining({ sender_name: 'Bob' }),
-      );
-    });
-
-    it('falls back to username when first_name missing', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const ctx = createTextCtx({ text: 'Hi' });
-      ctx.from.first_name = undefined as any;
-      await triggerTextMessage(ctx);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'tg:100200300',
-        expect.objectContaining({ sender_name: 'alice_user' }),
-      );
-    });
-
-    it('falls back to user ID when name and username missing', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const ctx = createTextCtx({ text: 'Hi', fromId: 42 });
-      ctx.from.first_name = undefined as any;
-      ctx.from.username = undefined as any;
-      await triggerTextMessage(ctx);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'tg:100200300',
-        expect.objectContaining({ sender_name: '42' }),
-      );
-    });
-
-    it('uses sender name as chat name for private chats', async () => {
-      const opts = createTestOpts({
-        registeredGroups: vi.fn(() => ({
-          'tg:100200300': {
-            name: 'Private',
-            folder: 'private',
-            trigger: '@Andy',
-            added_at: '2024-01-01T00:00:00.000Z',
-          },
-        })),
-      });
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const ctx = createTextCtx({
-        text: 'Hello',
-        chatType: 'private',
-        firstName: 'Alice',
-      });
-      await triggerTextMessage(ctx);
-
-      expect(opts.onChatMetadata).toHaveBeenCalledWith(
-        'tg:100200300',
-        expect.any(String),
-        'Alice', // Private chats use sender name
-        'telegram',
-        false,
-      );
-    });
-
-    it('uses chat title as name for group chats', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const ctx = createTextCtx({
-        text: 'Hello',
-        chatType: 'supergroup',
-        chatTitle: 'Project Team',
-      });
-      await triggerTextMessage(ctx);
-
-      expect(opts.onChatMetadata).toHaveBeenCalledWith(
-        'tg:100200300',
-        expect.any(String),
-        'Project Team',
-        'telegram',
-        true,
-      );
-    });
-
-    it('converts message.date to ISO timestamp', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const unixTime = 1704067200; // 2024-01-01T00:00:00.000Z
-      const ctx = createTextCtx({ text: 'Hello', date: unixTime });
-      await triggerTextMessage(ctx);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'tg:100200300',
-        expect.objectContaining({
-          timestamp: '2024-01-01T00:00:00.000Z',
-        }),
-      );
-    });
-  });
-
-  // --- @mention translation ---
-
-  describe('@mention translation', () => {
-    it('translates @bot_username mention to trigger format', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const ctx = createTextCtx({
-        text: '@andy_ai_bot what time is it?',
-        entities: [{ type: 'mention', offset: 0, length: 12 }],
-      });
-      await triggerTextMessage(ctx);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'tg:100200300',
-        expect.objectContaining({
-          content: '@Andy @andy_ai_bot what time is it?',
-        }),
-      );
-    });
-
-    it('does not translate if message already matches trigger', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const ctx = createTextCtx({
-        text: '@Andy @andy_ai_bot hello',
-        entities: [{ type: 'mention', offset: 6, length: 12 }],
-      });
-      await triggerTextMessage(ctx);
-
-      // Should NOT double-prepend — already starts with @Andy
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'tg:100200300',
-        expect.objectContaining({
-          content: '@Andy @andy_ai_bot hello',
-        }),
-      );
-    });
-
-    it('does not translate mentions of other bots', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const ctx = createTextCtx({
-        text: '@some_other_bot hi',
-        entities: [{ type: 'mention', offset: 0, length: 15 }],
-      });
-      await triggerTextMessage(ctx);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'tg:100200300',
-        expect.objectContaining({
-          content: '@some_other_bot hi', // No translation
-        }),
-      );
-    });
-
-    it('handles mention in middle of message', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const ctx = createTextCtx({
-        text: 'hey @andy_ai_bot check this',
-        entities: [{ type: 'mention', offset: 4, length: 12 }],
-      });
-      await triggerTextMessage(ctx);
-
-      // Bot is mentioned, message doesn't match trigger → prepend trigger
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'tg:100200300',
-        expect.objectContaining({
-          content: '@Andy hey @andy_ai_bot check this',
-        }),
-      );
-    });
-
-    it('handles message with no entities', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const ctx = createTextCtx({ text: 'plain message' });
-      await triggerTextMessage(ctx);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'tg:100200300',
-        expect.objectContaining({
-          content: 'plain message',
-        }),
-      );
-    });
-
-    it('ignores non-mention entities', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const ctx = createTextCtx({
-        text: 'check https://example.com',
-        entities: [{ type: 'url', offset: 6, length: 19 }],
-      });
-      await triggerTextMessage(ctx);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'tg:100200300',
-        expect.objectContaining({
-          content: 'check https://example.com',
-        }),
-      );
-    });
-  });
-
-  // --- Non-text messages ---
-
-  describe('non-text messages', () => {
-    it('stores photo with placeholder', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const ctx = createMediaCtx({});
-      await triggerMediaMessage('message:photo', ctx);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'tg:100200300',
-        expect.objectContaining({ content: '[Photo]' }),
-      );
-    });
-
-    it('stores photo with caption', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const ctx = createMediaCtx({ caption: 'Look at this' });
-      await triggerMediaMessage('message:photo', ctx);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'tg:100200300',
-        expect.objectContaining({ content: '[Photo] Look at this' }),
-      );
-    });
-
-    it('stores video with placeholder', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const ctx = createMediaCtx({});
-      await triggerMediaMessage('message:video', ctx);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'tg:100200300',
-        expect.objectContaining({ content: '[Video]' }),
-      );
-    });
-
-    it('stores voice message with placeholder', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const ctx = createMediaCtx({});
-      await triggerMediaMessage('message:voice', ctx);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'tg:100200300',
-        expect.objectContaining({ content: '[Voice message]' }),
-      );
-    });
-
-    it('stores audio with placeholder', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const ctx = createMediaCtx({});
-      await triggerMediaMessage('message:audio', ctx);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'tg:100200300',
-        expect.objectContaining({ content: '[Audio]' }),
-      );
-    });
-
-    it('stores document with filename', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const ctx = createMediaCtx({
-        extra: { document: { file_name: 'report.pdf' } },
-      });
-      await triggerMediaMessage('message:document', ctx);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'tg:100200300',
-        expect.objectContaining({ content: '[Document: report.pdf]' }),
-      );
-    });
-
-    it('stores document with fallback name when filename missing', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const ctx = createMediaCtx({ extra: { document: {} } });
-      await triggerMediaMessage('message:document', ctx);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'tg:100200300',
-        expect.objectContaining({ content: '[Document: file]' }),
-      );
-    });
-
-    it('stores sticker with emoji', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const ctx = createMediaCtx({
-        extra: { sticker: { emoji: '😂' } },
-      });
-      await triggerMediaMessage('message:sticker', ctx);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'tg:100200300',
-        expect.objectContaining({ content: '[Sticker 😂]' }),
-      );
-    });
-
-    it('stores location with placeholder', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const ctx = createMediaCtx({});
-      await triggerMediaMessage('message:location', ctx);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'tg:100200300',
-        expect.objectContaining({ content: '[Location]' }),
-      );
-    });
-
-    it('stores contact with placeholder', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const ctx = createMediaCtx({});
-      await triggerMediaMessage('message:contact', ctx);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'tg:100200300',
-        expect.objectContaining({ content: '[Contact]' }),
-      );
-    });
-
-    it('ignores non-text messages from unregistered chats', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const ctx = createMediaCtx({ chatId: 999999 });
-      await triggerMediaMessage('message:photo', ctx);
-
-      expect(opts.onMessage).not.toHaveBeenCalled();
-    });
-  });
-
-  // --- sendMessage ---
-
-  describe('sendMessage', () => {
-    it('sends message via bot API', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      await channel.sendMessage('tg:100200300', 'Hello');
-
-      expect(currentBot().api.sendMessage).toHaveBeenCalledWith(
-        '100200300',
-        'Hello',
-      );
-    });
-
-    it('strips tg: prefix from JID', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      await channel.sendMessage('tg:-1001234567890', 'Group message');
-
-      expect(currentBot().api.sendMessage).toHaveBeenCalledWith(
-        '-1001234567890',
-        'Group message',
-      );
-    });
-
-    it('splits messages exceeding 4096 characters', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const longText = 'x'.repeat(5000);
-      await channel.sendMessage('tg:100200300', longText);
-
-      expect(currentBot().api.sendMessage).toHaveBeenCalledTimes(2);
-      expect(currentBot().api.sendMessage).toHaveBeenNthCalledWith(
-        1,
-        '100200300',
-        'x'.repeat(4096),
-      );
-      expect(currentBot().api.sendMessage).toHaveBeenNthCalledWith(
-        2,
-        '100200300',
-        'x'.repeat(904),
-      );
-    });
-
-    it('sends exactly one message at 4096 characters', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const exactText = 'y'.repeat(4096);
-      await channel.sendMessage('tg:100200300', exactText);
-
-      expect(currentBot().api.sendMessage).toHaveBeenCalledTimes(1);
-    });
-
-    it('handles send failure gracefully', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      currentBot().api.sendMessage.mockRejectedValueOnce(
-        new Error('Network error'),
-      );
-
-      // Should not throw
-      await expect(
-        channel.sendMessage('tg:100200300', 'Will fail'),
-      ).resolves.toBeUndefined();
-    });
-
-    it('does nothing when bot is not initialized', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-
-      // Don't connect — bot is null
-      await channel.sendMessage('tg:100200300', 'No bot');
-
-      // No error, no API call
-    });
-  });
-
-  // --- ownsJid ---
-
-  describe('ownsJid', () => {
-    it('owns tg: JIDs', () => {
-      const channel = new TelegramChannel('test-token', createTestOpts());
-      expect(channel.ownsJid('tg:123456')).toBe(true);
-    });
-
-    it('owns tg: JIDs with negative IDs (groups)', () => {
-      const channel = new TelegramChannel('test-token', createTestOpts());
-      expect(channel.ownsJid('tg:-1001234567890')).toBe(true);
-    });
-
-    it('does not own WhatsApp group JIDs', () => {
-      const channel = new TelegramChannel('test-token', createTestOpts());
-      expect(channel.ownsJid('12345@g.us')).toBe(false);
-    });
-
-    it('does not own WhatsApp DM JIDs', () => {
-      const channel = new TelegramChannel('test-token', createTestOpts());
-      expect(channel.ownsJid('12345@s.whatsapp.net')).toBe(false);
-    });
-
-    it('does not own unknown JID formats', () => {
-      const channel = new TelegramChannel('test-token', createTestOpts());
-      expect(channel.ownsJid('random-string')).toBe(false);
-    });
-  });
-
-  // --- setTyping ---
-
-  describe('setTyping', () => {
-    it('sends typing action when isTyping is true', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      await channel.setTyping('tg:100200300', true);
-
-      expect(currentBot().api.sendChatAction).toHaveBeenCalledWith(
-        '100200300',
-        'typing',
-      );
-    });
-
-    it('does nothing when isTyping is false', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      await channel.setTyping('tg:100200300', false);
-
-      expect(currentBot().api.sendChatAction).not.toHaveBeenCalled();
-    });
-
-    it('does nothing when bot is not initialized', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-
-      // Don't connect
-      await channel.setTyping('tg:100200300', true);
-
-      // No error, no API call
-    });
-
-    it('handles typing indicator failure gracefully', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      currentBot().api.sendChatAction.mockRejectedValueOnce(
-        new Error('Rate limited'),
-      );
-
-      await expect(
-        channel.setTyping('tg:100200300', true),
-      ).resolves.toBeUndefined();
-    });
-  });
-
-  // --- Bot commands ---
-
-  describe('bot commands', () => {
-    it('/chatid replies with chat ID and metadata', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const handler = currentBot().commandHandlers.get('chatid')!;
-      const ctx = {
-        chat: { id: 100200300, type: 'group' as const },
-        from: { first_name: 'Alice' },
-        reply: vi.fn(),
-      };
-
-      await handler(ctx);
-
-      expect(ctx.reply).toHaveBeenCalledWith(
-        expect.stringContaining('tg:100200300'),
-        expect.objectContaining({ parse_mode: 'Markdown' }),
-      );
-    });
-
-    it('/chatid shows chat type', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const handler = currentBot().commandHandlers.get('chatid')!;
-      const ctx = {
-        chat: { id: 555, type: 'private' as const },
-        from: { first_name: 'Bob' },
-        reply: vi.fn(),
-      };
-
-      await handler(ctx);
-
-      expect(ctx.reply).toHaveBeenCalledWith(
-        expect.stringContaining('private'),
-        expect.any(Object),
-      );
-    });
-
-    it('/ping replies with bot status', async () => {
-      const opts = createTestOpts();
-      const channel = new TelegramChannel('test-token', opts);
-      await channel.connect();
-
-      const handler = currentBot().commandHandlers.get('ping')!;
-      const ctx = { reply: vi.fn() };
-
-      await handler(ctx);
-
-      expect(ctx.reply).toHaveBeenCalledWith('Andy is online.');
-    });
-  });
-
-  // --- Channel properties ---
-
-  describe('channel properties', () => {
-    it('has name "telegram"', () => {
-      const channel = new TelegramChannel('test-token', createTestOpts());
-      expect(channel.name).toBe('telegram');
-    });
-  });
-});

.claude/skills/add-telegram/add/src/channels/telegram.ts

@@ -1,257 +0,0 @@
-import { Bot } from 'grammy';
-
-import { ASSISTANT_NAME, TRIGGER_PATTERN } from '../config.js';
-import { readEnvFile } from '../env.js';
-import { logger } from '../logger.js';
-import { registerChannel, ChannelOpts } from './registry.js';
-import {
-  Channel,
-  OnChatMetadata,
-  OnInboundMessage,
-  RegisteredGroup,
-} from '../types.js';
-
-export interface TelegramChannelOpts {
-  onMessage: OnInboundMessage;
-  onChatMetadata: OnChatMetadata;
-  registeredGroups: () => Record<string, RegisteredGroup>;
-}
-
-export class TelegramChannel implements Channel {
-  name = 'telegram';
-
-  private bot: Bot | null = null;
-  private opts: TelegramChannelOpts;
-  private botToken: string;
-
-  constructor(botToken: string, opts: TelegramChannelOpts) {
-    this.botToken = botToken;
-    this.opts = opts;
-  }
-
-  async connect(): Promise<void> {
-    this.bot = new Bot(this.botToken);
-
-    // Command to get chat ID (useful for registration)
-    this.bot.command('chatid', (ctx) => {
-      const chatId = ctx.chat.id;
-      const chatType = ctx.chat.type;
-      const chatName =
-        chatType === 'private'
-          ? ctx.from?.first_name || 'Private'
-          : (ctx.chat as any).title || 'Unknown';
-
-      ctx.reply(
-        `Chat ID: \`tg:${chatId}\`\nName: ${chatName}\nType: ${chatType}`,
-        { parse_mode: 'Markdown' },
-      );
-    });
-
-    // Command to check bot status
-    this.bot.command('ping', (ctx) => {
-      ctx.reply(`${ASSISTANT_NAME} is online.`);
-    });
-
-    this.bot.on('message:text', async (ctx) => {
-      // Skip commands
-      if (ctx.message.text.startsWith('/')) return;
-
-      const chatJid = `tg:${ctx.chat.id}`;
-      let content = ctx.message.text;
-      const timestamp = new Date(ctx.message.date * 1000).toISOString();
-      const senderName =
-        ctx.from?.first_name ||
-        ctx.from?.username ||
-        ctx.from?.id.toString() ||
-        'Unknown';
-      const sender = ctx.from?.id.toString() || '';
-      const msgId = ctx.message.message_id.toString();
-
-      // Determine chat name
-      const chatName =
-        ctx.chat.type === 'private'
-          ? senderName
-          : (ctx.chat as any).title || chatJid;
-
-      // Translate Telegram @bot_username mentions into TRIGGER_PATTERN format.
-      // Telegram @mentions (e.g., @andy_ai_bot) won't match TRIGGER_PATTERN
-      // (e.g., ^@Andy\b), so we prepend the trigger when the bot is @mentioned.
-      const botUsername = ctx.me?.username?.toLowerCase();
-      if (botUsername) {
-        const entities = ctx.message.entities || [];
-        const isBotMentioned = entities.some((entity) => {
-          if (entity.type === 'mention') {
-            const mentionText = content
-              .substring(entity.offset, entity.offset + entity.length)
-              .toLowerCase();
-            return mentionText === `@${botUsername}`;
-          }
-          return false;
-        });
-        if (isBotMentioned && !TRIGGER_PATTERN.test(content)) {
-          content = `@${ASSISTANT_NAME} ${content}`;
-        }
-      }
-
-      // Store chat metadata for discovery
-      const isGroup = ctx.chat.type === 'group' || ctx.chat.type === 'supergroup';
-      this.opts.onChatMetadata(chatJid, timestamp, chatName, 'telegram', isGroup);
-
-      // Only deliver full message for registered groups
-      const group = this.opts.registeredGroups()[chatJid];
-      if (!group) {
-        logger.debug(
-          { chatJid, chatName },
-          'Message from unregistered Telegram chat',
-        );
-        return;
-      }
-
-      // Deliver message — startMessageLoop() will pick it up
-      this.opts.onMessage(chatJid, {
-        id: msgId,
-        chat_jid: chatJid,
-        sender,
-        sender_name: senderName,
-        content,
-        timestamp,
-        is_from_me: false,
-      });
-
-      logger.info(
-        { chatJid, chatName, sender: senderName },
-        'Telegram message stored',
-      );
-    });
-
-    // Handle non-text messages with placeholders so the agent knows something was sent
-    const storeNonText = (ctx: any, placeholder: string) => {
-      const chatJid = `tg:${ctx.chat.id}`;
-      const group = this.opts.registeredGroups()[chatJid];
-      if (!group) return;
-
-      const timestamp = new Date(ctx.message.date * 1000).toISOString();
-      const senderName =
-        ctx.from?.first_name ||
-        ctx.from?.username ||
-        ctx.from?.id?.toString() ||
-        'Unknown';
-      const caption = ctx.message.caption ? ` ${ctx.message.caption}` : '';
-
-      const isGroup = ctx.chat.type === 'group' || ctx.chat.type === 'supergroup';
-      this.opts.onChatMetadata(chatJid, timestamp, undefined, 'telegram', isGroup);
-      this.opts.onMessage(chatJid, {
-        id: ctx.message.message_id.toString(),
-        chat_jid: chatJid,
-        sender: ctx.from?.id?.toString() || '',
-        sender_name: senderName,
-        content: `${placeholder}${caption}`,
-        timestamp,
-        is_from_me: false,
-      });
-    };
-
-    this.bot.on('message:photo', (ctx) => storeNonText(ctx, '[Photo]'));
-    this.bot.on('message:video', (ctx) => storeNonText(ctx, '[Video]'));
-    this.bot.on('message:voice', (ctx) =>
-      storeNonText(ctx, '[Voice message]'),
-    );
-    this.bot.on('message:audio', (ctx) => storeNonText(ctx, '[Audio]'));
-    this.bot.on('message:document', (ctx) => {
-      const name = ctx.message.document?.file_name || 'file';
-      storeNonText(ctx, `[Document: ${name}]`);
-    });
-    this.bot.on('message:sticker', (ctx) => {
-      const emoji = ctx.message.sticker?.emoji || '';
-      storeNonText(ctx, `[Sticker ${emoji}]`);
-    });
-    this.bot.on('message:location', (ctx) => storeNonText(ctx, '[Location]'));
-    this.bot.on('message:contact', (ctx) => storeNonText(ctx, '[Contact]'));
-
-    // Handle errors gracefully
-    this.bot.catch((err) => {
-      logger.error({ err: err.message }, 'Telegram bot error');
-    });
-
-    // Start polling — returns a Promise that resolves when started
-    return new Promise<void>((resolve) => {
-      this.bot!.start({
-        onStart: (botInfo) => {
-          logger.info(
-            { username: botInfo.username, id: botInfo.id },
-            'Telegram bot connected',
-          );
-          console.log(`\n  Telegram bot: @${botInfo.username}`);
-          console.log(
-            `  Send /chatid to the bot to get a chat's registration ID\n`,
-          );
-          resolve();
-        },
-      });
-    });
-  }
-
-  async sendMessage(jid: string, text: string): Promise<void> {
-    if (!this.bot) {
-      logger.warn('Telegram bot not initialized');
-      return;
-    }
-
-    try {
-      const numericId = jid.replace(/^tg:/, '');
-
-      // Telegram has a 4096 character limit per message — split if needed
-      const MAX_LENGTH = 4096;
-      if (text.length <= MAX_LENGTH) {
-        await this.bot.api.sendMessage(numericId, text);
-      } else {
-        for (let i = 0; i < text.length; i += MAX_LENGTH) {
-          await this.bot.api.sendMessage(
-            numericId,
-            text.slice(i, i + MAX_LENGTH),
-          );
-        }
-      }
-      logger.info({ jid, length: text.length }, 'Telegram message sent');
-    } catch (err) {
-      logger.error({ jid, err }, 'Failed to send Telegram message');
-    }
-  }
-
-  isConnected(): boolean {
-    return this.bot !== null;
-  }
-
-  ownsJid(jid: string): boolean {
-    return jid.startsWith('tg:');
-  }
-
-  async disconnect(): Promise<void> {
-    if (this.bot) {
-      this.bot.stop();
-      this.bot = null;
-      logger.info('Telegram bot stopped');
-    }
-  }
-
-  async setTyping(jid: string, isTyping: boolean): Promise<void> {
-    if (!this.bot || !isTyping) return;
-    try {
-      const numericId = jid.replace(/^tg:/, '');
-      await this.bot.api.sendChatAction(numericId, 'typing');
-    } catch (err) {
-      logger.debug({ jid, err }, 'Failed to send Telegram typing indicator');
-    }
-  }
-}
-
-registerChannel('telegram', (opts: ChannelOpts) => {
-  const envVars = readEnvFile(['TELEGRAM_BOT_TOKEN']);
-  const token =
-    process.env.TELEGRAM_BOT_TOKEN || envVars.TELEGRAM_BOT_TOKEN || '';
-  if (!token) {
-    logger.warn('Telegram: TELEGRAM_BOT_TOKEN not set');
-    return null;
-  }
-  return new TelegramChannel(token, opts);
-});

.claude/skills/add-telegram/manifest.yaml

@@ -1,17 +0,0 @@
-skill: telegram
-version: 1.0.0
-description: "Telegram Bot API integration via Grammy"
-core_version: 0.1.0
-adds:
-  - src/channels/telegram.ts
-  - src/channels/telegram.test.ts
-modifies:
-  - src/channels/index.ts
-structured:
-  npm_dependencies:
-    grammy: "^1.39.3"
-  env_additions:
-    - TELEGRAM_BOT_TOKEN
-conflicts: []
-depends: []
-test: "npx vitest run src/channels/telegram.test.ts"

.claude/skills/add-telegram/modify/src/channels/index.ts

@@ -1,13 +0,0 @@
-// Channel self-registration barrel file.
-// Each import triggers the channel module's registerChannel() call.
-
-// discord
-
-// gmail
-
-// slack
-
-// telegram
-import './telegram.js';
-
-// whatsapp

.claude/skills/add-telegram/modify/src/channels/index.ts.intent.md

@@ -1,7 +0,0 @@
-# Intent: Add Telegram channel import
-
-Add `import './telegram.js';` to the channel barrel file so the Telegram
-module self-registers with the channel registry on startup.
-
-This is an append-only change — existing import lines for other channels
-must be preserved.

.claude/skills/add-telegram/tests/telegram.test.ts

@@ -1,69 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import fs from 'fs';
-import path from 'path';
-
-describe('telegram skill package', () => {
-  const skillDir = path.resolve(__dirname, '..');
-
-  it('has a valid manifest', () => {
-    const manifestPath = path.join(skillDir, 'manifest.yaml');
-    expect(fs.existsSync(manifestPath)).toBe(true);
-
-    const content = fs.readFileSync(manifestPath, 'utf-8');
-    expect(content).toContain('skill: telegram');
-    expect(content).toContain('version: 1.0.0');
-    expect(content).toContain('grammy');
-  });
-
-  it('has all files declared in adds', () => {
-    const channelFile = path.join(
-      skillDir,
-      'add',
-      'src',
-      'channels',
-      'telegram.ts',
-    );
-    expect(fs.existsSync(channelFile)).toBe(true);
-
-    const content = fs.readFileSync(channelFile, 'utf-8');
-    expect(content).toContain('class TelegramChannel');
-    expect(content).toContain('implements Channel');
-    expect(content).toContain("registerChannel('telegram'");
-
-    // Test file for the channel
-    const testFile = path.join(
-      skillDir,
-      'add',
-      'src',
-      'channels',
-      'telegram.test.ts',
-    );
-    expect(fs.existsSync(testFile)).toBe(true);
-
-    const testContent = fs.readFileSync(testFile, 'utf-8');
-    expect(testContent).toContain("describe('TelegramChannel'");
-  });
-
-  it('has all files declared in modifies', () => {
-    // Channel barrel file
-    const indexFile = path.join(
-      skillDir,
-      'modify',
-      'src',
-      'channels',
-      'index.ts',
-    );
-    expect(fs.existsSync(indexFile)).toBe(true);
-
-    const indexContent = fs.readFileSync(indexFile, 'utf-8');
-    expect(indexContent).toContain("import './telegram.js'");
-  });
-
-  it('has intent files for modified files', () => {
-    expect(
-      fs.existsSync(
-        path.join(skillDir, 'modify', 'src', 'channels', 'index.ts.intent.md'),
-      ),
-    ).toBe(true);
-  });
-});

.claude/skills/add-vercel/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: add-vercel
+description: Add Vercel deployment capability to NanoClaw agents. Installs the Vercel CLI in agent containers and sets up OneCLI credential injection for api.vercel.com. Use when the user wants agents to deploy web applications to Vercel.
+---
+
+# Add Vercel
+
+This skill gives NanoClaw agents the ability to deploy web applications to Vercel. It installs the Vercel CLI in agent containers and configures OneCLI to inject Vercel credentials automatically.
+
+**Principle:** Do the work — don't tell the user to do it. Only ask for their input when it genuinely requires manual action (pasting a token).
+
+## Phase 1: Pre-flight
+
+### Check if already applied
+
+Check if the container skill exists:
+
+```bash
+test -d container/skills/vercel-cli && echo "INSTALLED" || echo "NOT_INSTALLED"
+```
+
+If `INSTALLED`, skip to Phase 3 (Configure Credentials).
+
+### Check prerequisites
+
+Verify OneCLI is working (required for credential injection):
+
+```bash
+onecli version 2>/dev/null && echo "ONECLI_OK" || echo "ONECLI_MISSING"
+```
+
+If `ONECLI_MISSING`, tell the user to run `/init-onecli` first, then retry `/add-vercel`. Stop here.
+
+## Phase 2: Install Container Skill
+
+Copy the bundled container skill into the container skills directory:
+
+```bash
+rsync -a .claude/skills/add-vercel/container-skills/ container/skills/
+```
+
+Verify:
+
+```bash
+head -5 container/skills/vercel-cli/SKILL.md
+```
+
+## Phase 3: Configure Credentials
+
+### Check if Vercel credential already exists
+
+```bash
+onecli secrets list 2>/dev/null | grep -i vercel
+```
+
+If a Vercel credential already exists, skip to Phase 4.
+
+### Set up Vercel API credential
+
+The agent needs a Vercel personal access token. Tell the user:
+
+> I need your Vercel personal access token. Go to https://vercel.com/account/tokens and create one with these settings:
+>
+> - **Token name:** `nanoclaw` (or any name you'll recognize)
+> - **Scope:** "Full Account" — the agent needs to create projects, deploy, and manage domains
+> - **Expiration:** "No expiration" recommended (avoids credential rotation), or pick a date if your security policy requires it
+>
+> After creating the token, copy it — you'll only see it once.
+
+Once the user provides the token, add it to OneCLI:
+
+```bash
+onecli secrets create \
+  --name "Vercel API Token" \
+  --type generic \
+  --value "<TOKEN>" \
+  --host-pattern "api.vercel.com" \
+  --header-name "Authorization" \
+  --value-format "Bearer {value}"
+```
+
+Verify:
+
+```bash
+onecli secrets list | grep -i vercel
+```
+
+### Assign the secret to all agents
+
+OneCLI uses selective secret mode — secrets must be explicitly assigned to each agent. Get the Vercel secret ID from the output above, then assign it to every agent:
+
+```bash
+# For each agent, add the Vercel secret to its assigned secrets list.
+# First get current assignments, then set them with the new secret appended.
+VERCEL_SECRET_ID=$(onecli secrets list 2>/dev/null | grep -B2 "Vercel" | grep '"id"' | head -1 | sed 's/.*"id": "//;s/".*//')
+for agent in $(onecli agents list 2>/dev/null | grep '"id"' | sed 's/.*"id": "//;s/".*//'); do
+  CURRENT=$(onecli agents secrets --id "$agent" 2>/dev/null | grep '"' | grep -v hint | grep -v data | sed 's/.*"//;s/".*//' | tr '\n' ',' | sed 's/,$//')
+  onecli agents set-secrets --id "$agent" --secret-ids "${CURRENT:+$CURRENT,}$VERCEL_SECRET_ID"
+done
+```
+
+## Phase 4: Ensure Vercel CLI in Container Image
+
+Check if `vercel` is already in the Dockerfile:
+
+```bash
+grep -q 'vercel' container/Dockerfile && echo "PRESENT" || echo "MISSING"
+```
+
+If `MISSING`, add `vercel` to the global npm install line in `container/Dockerfile`, then rebuild:
+
+```bash
+./container/build.sh
+```
+
+If `PRESENT`, skip — no rebuild needed.
+
+## Phase 5: Sync Skills to Running Agent Groups
+
+Container skills are copied once at group creation and not auto-synced. After installing or updating a container skill, sync it to all existing agent groups:
+
+```bash
+for session_dir in data/v2-sessions/ag-*; do
+  if [ -d "$session_dir/.claude-shared/skills" ]; then
+    rsync -a container/skills/ "$session_dir/.claude-shared/skills/"
+    echo "Synced skills to: $session_dir"
+  fi
+done
+```
+
+## Phase 6: Restart Running Containers
+
+Stop all running agent containers so they pick up the new skills on next wake:
+
+```bash
+docker ps --format "{{.ID}} {{.Names}}" | grep nanoclaw-v2 | awk '{print $1}' | xargs -r docker stop
+```
+
+## Done
+
+The agent can now deploy web applications to Vercel. Key commands:
+
+- `vercel deploy --yes --prod --token placeholder` — deploy to production
+- `vercel ls --token placeholder` — list deployments
+- `vercel whoami --token placeholder` — check auth
+
+For the full command reference, the agent has the `vercel-cli` container skill loaded automatically.

.claude/skills/add-vercel/container-skills/vercel-cli/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: vercel-cli
+description: Deploy apps to Vercel. Use when asked to deploy, ship, or publish a web application, or manage Vercel projects, domains, and environment variables.
+---
+
+# Vercel CLI
+
+You can deploy web applications to Vercel using the `vercel` CLI.
+
+## Auth
+
+Auth is handled by OneCLI — the HTTPS_PROXY injects the real token into API requests automatically. The Vercel CLI requires a token to be present to skip its local credential check, so **always pass `--token placeholder`** on every command. OneCLI replaces this with the real token at the proxy level.
+
+Before any Vercel operation, verify auth:
+
+```bash
+vercel whoami --token placeholder
+```
+
+If this fails with an auth error, ask the user to add a Vercel token to OneCLI. They can create one at https://vercel.com/account/tokens and register it via `onecli secrets create` on the host. Once added, retry `vercel whoami`.
+
+## Deploying
+
+Always use `--yes` to skip interactive prompts and `--token placeholder` for auth (OneCLI replaces with real token).
+
+```bash
+# Deploy to production
+vercel deploy --yes --prod --token placeholder
+
+# Deploy from a specific directory
+vercel deploy --yes --prod --token placeholder --cwd /path/to/project
+
+# Preview deployment (not production)
+vercel deploy --yes --token placeholder
+```
+
+After deploying, verify the live URL:
+
+```bash
+# Check deployment status
+vercel inspect <deployment-url> --token placeholder
+```
+
+## Pre-Send Checks (do this before sharing the URL)
+
+Don't send the deployment URL to the user until you've confirmed it's actually working. At minimum:
+
+1. **Local build passes** — run `npm run build` (or the project's build command) before `vercel deploy`. If the build fails locally, fix it first; don't deploy broken code.
+2. **Deployment succeeded** — the `vercel deploy` output shows a "Production: https://..." URL and the status is READY (confirm with `vercel inspect`).
+3. **Live URL responds** — `curl -sI <url> | head -1` should return `HTTP/2 200` (or another 2xx/3xx). A 404/500 means something's broken even though Vercel reported success.
+4. **Optional visual check** — if `agent-browser` is loaded, open the URL and eyeball it. Helpful for catching broken layouts that a 200 response wouldn't reveal.
+
+If any check fails, fix the issue and redeploy before reporting to the user.
+
+## Project Management
+
+```bash
+# Link to an existing Vercel project (non-interactive)
+vercel link --yes --token placeholder
+
+# List recent deployments
+vercel ls --token placeholder
+
+# List all projects
+vercel project ls --token placeholder
+```
+
+## Domains
+
+```bash
+# List domains
+vercel domains ls --token placeholder
+
+# Add a domain to the current project
+vercel domains add example.com --token placeholder
+```
+
+## Environment Variables
+
+```bash
+# Pull env vars from Vercel to local .env
+vercel env pull --token placeholder
+
+# Add an env var (use echo to pipe the value — avoids interactive prompt)
+echo "value" | vercel env add VAR_NAME production --token placeholder
+```
+
+## Common Errors
+
+| Error | Fix |
+|-------|-----|
+| `Error: No framework detected` | Ensure the project has a `package.json` with a `build` script, or set the framework in `vercel.json` |
+| `Error: Rate limited` | Wait and retry. Don't loop — report to user |
+| `Error: You have reached your project limit` | User needs to upgrade Vercel plan or delete unused projects |
+| `ENOTFOUND api.vercel.com` | Network issue. Check proxy connectivity |
+| Auth error after `vercel whoami` | Credential may be expired. Ask the user to refresh the Vercel token in OneCLI |
+
+## Best Practices
+
+- Run `npm run build` locally before deploying to catch build errors early
+- Use `--cwd` instead of `cd` to keep your working directory stable
+- For Next.js projects, `vercel deploy` auto-detects the framework — no extra config needed
+- Use `vercel.json` only when you need custom build settings, rewrites, or headers

.claude/skills/add-voice-transcription/SKILL.md

@@ -11,7 +11,7 @@ This skill adds automatic voice message transcription to NanoClaw's WhatsApp cha
 
 ### Check if already applied
 
-Read `.nanoclaw/state.yaml`. If `voice-transcription` is in `applied_skills`, skip to Phase 3 (Configure). The code changes are already in place.
+Check if `src/transcription.ts` exists. If it does, skip to Phase 3 (Configure). The code changes are already in place.
 
 ### Ask the user
 
@@ -23,42 +23,49 @@ If yes, collect it now. If no, direct them to create one at https://platform.ope
 
 ## Phase 2: Apply Code Changes
 
-Run the skills engine to apply this skill's code package.
+**Prerequisite:** WhatsApp must be installed first (`skill/whatsapp` merged). This skill modifies WhatsApp channel files.
 
-### Initialize skills system (if needed)
-
-If `.nanoclaw/` directory doesn't exist yet:
+### Ensure WhatsApp fork remote
 
 ```bash
-npx tsx scripts/apply-skill.ts --init
+git remote -v
 ```
 
-### Apply the skill
+If `whatsapp` is missing, add it:
 
 ```bash
-npx tsx scripts/apply-skill.ts .claude/skills/add-voice-transcription
+git remote add whatsapp https://github.com/qwibitai/nanoclaw-whatsapp.git
 ```
 
-This deterministically:
-- Adds `src/transcription.ts` (voice transcription module using OpenAI Whisper)
-- Three-way merges voice handling into `src/channels/whatsapp.ts` (isVoiceMessage check, transcribeAudioMessage call)
-- Three-way merges transcription tests into `src/channels/whatsapp.test.ts` (mock + 3 test cases)
-- Installs the `openai` npm dependency
-- Updates `.env.example` with `OPENAI_API_KEY`
-- Records the application in `.nanoclaw/state.yaml`
+### Merge the skill branch
 
-If the apply reports merge conflicts, read the intent files:
-- `modify/src/channels/whatsapp.ts.intent.md` — what changed and invariants for whatsapp.ts
-- `modify/src/channels/whatsapp.test.ts.intent.md` — what changed for whatsapp.test.ts
+```bash
+git fetch whatsapp skill/voice-transcription
+git merge whatsapp/skill/voice-transcription || {
+  git checkout --theirs pnpm-lock.yaml
+  git add pnpm-lock.yaml
+  git merge --continue
+}
+```
+
+This merges in:
+- `src/transcription.ts` (voice transcription module using OpenAI Whisper)
+- Voice handling in `src/channels/whatsapp.ts` (isVoiceMessage check, transcribeAudioMessage call)
+- Transcription tests in `src/channels/whatsapp.test.ts`
+- `openai` npm dependency in `package.json`
+- `OPENAI_API_KEY` in `.env.example`
+
+If the merge reports conflicts, resolve them by reading the conflicted files and understanding the intent of both sides.
 
 ### Validate code changes
 
 ```bash
-npm test
-npm run build
+pnpm install
+pnpm run build
+pnpm exec vitest run src/channels/whatsapp.test.ts
 ```
 
-All tests must pass (including the 3 new voice transcription tests) and build must be clean before proceeding.
+All tests must pass and build must be clean before proceeding.
 
 ## Phase 3: Configure
 
@@ -96,7 +103,7 @@ The container reads environment from `data/env/env`, not `.env` directly.
 ### Build and restart
 
 ```bash
-npm run build
+pnpm run build
 launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
 # Linux: systemctl --user restart nanoclaw
 ```

.claude/skills/add-voice-transcription/add/src/transcription.ts

@@ -1,98 +0,0 @@
-import { downloadMediaMessage } from '@whiskeysockets/baileys';
-import { WAMessage, WASocket } from '@whiskeysockets/baileys';
-
-import { readEnvFile } from './env.js';
-
-interface TranscriptionConfig {
-  model: string;
-  enabled: boolean;
-  fallbackMessage: string;
-}
-
-const DEFAULT_CONFIG: TranscriptionConfig = {
-  model: 'whisper-1',
-  enabled: true,
-  fallbackMessage: '[Voice Message - transcription unavailable]',
-};
-
-async function transcribeWithOpenAI(
-  audioBuffer: Buffer,
-  config: TranscriptionConfig,
-): Promise<string | null> {
-  const env = readEnvFile(['OPENAI_API_KEY']);
-  const apiKey = env.OPENAI_API_KEY;
-
-  if (!apiKey) {
-    console.warn('OPENAI_API_KEY not set in .env');
-    return null;
-  }
-
-  try {
-    const openaiModule = await import('openai');
-    const OpenAI = openaiModule.default;
-    const toFile = openaiModule.toFile;
-
-    const openai = new OpenAI({ apiKey });
-
-    const file = await toFile(audioBuffer, 'voice.ogg', {
-      type: 'audio/ogg',
-    });
-
-    const transcription = await openai.audio.transcriptions.create({
-      file: file,
-      model: config.model,
-      response_format: 'text',
-    });
-
-    // When response_format is 'text', the API returns a plain string
-    return transcription as unknown as string;
-  } catch (err) {
-    console.error('OpenAI transcription failed:', err);
-    return null;
-  }
-}
-
-export async function transcribeAudioMessage(
-  msg: WAMessage,
-  sock: WASocket,
-): Promise<string | null> {
-  const config = DEFAULT_CONFIG;
-
-  if (!config.enabled) {
-    return config.fallbackMessage;
-  }
-
-  try {
-    const buffer = (await downloadMediaMessage(
-      msg,
-      'buffer',
-      {},
-      {
-        logger: console as any,
-        reuploadRequest: sock.updateMediaMessage,
-      },
-    )) as Buffer;
-
-    if (!buffer || buffer.length === 0) {
-      console.error('Failed to download audio message');
-      return config.fallbackMessage;
-    }
-
-    console.log(`Downloaded audio message: ${buffer.length} bytes`);
-
-    const transcript = await transcribeWithOpenAI(buffer, config);
-
-    if (!transcript) {
-      return config.fallbackMessage;
-    }
-
-    return transcript.trim();
-  } catch (err) {
-    console.error('Transcription error:', err);
-    return config.fallbackMessage;
-  }
-}
-
-export function isVoiceMessage(msg: WAMessage): boolean {
-  return msg.message?.audioMessage?.ptt === true;
-}

.claude/skills/add-voice-transcription/manifest.yaml

@@ -1,17 +0,0 @@
-skill: voice-transcription
-version: 1.0.0
-description: "Voice message transcription via OpenAI Whisper"
-core_version: 0.1.0
-adds:
-  - src/transcription.ts
-modifies:
-  - src/channels/whatsapp.ts
-  - src/channels/whatsapp.test.ts
-structured:
-  npm_dependencies:
-    openai: "^4.77.0"
-  env_additions:
-    - OPENAI_API_KEY
-conflicts: []
-depends: []
-test: "npx vitest run src/channels/whatsapp.test.ts"

.claude/skills/add-voice-transcription/modify/src/channels/whatsapp.test.ts

@@ -1,963 +0,0 @@
-import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
-import { EventEmitter } from 'events';
-
-// --- Mocks ---
-
-// Mock config
-vi.mock('../config.js', () => ({
-  STORE_DIR: '/tmp/nanoclaw-test-store',
-  ASSISTANT_NAME: 'Andy',
-  ASSISTANT_HAS_OWN_NUMBER: false,
-}));
-
-// Mock logger
-vi.mock('../logger.js', () => ({
-  logger: {
-    debug: vi.fn(),
-    info: vi.fn(),
-    warn: vi.fn(),
-    error: vi.fn(),
-  },
-}));
-
-// Mock db
-vi.mock('../db.js', () => ({
-  getLastGroupSync: vi.fn(() => null),
-  setLastGroupSync: vi.fn(),
-  updateChatName: vi.fn(),
-}));
-
-// Mock transcription
-vi.mock('../transcription.js', () => ({
-  isVoiceMessage: vi.fn((msg: any) => msg.message?.audioMessage?.ptt === true),
-  transcribeAudioMessage: vi.fn().mockResolvedValue('Hello this is a voice message'),
-}));
-
-// Mock fs
-vi.mock('fs', async () => {
-  const actual = await vi.importActual<typeof import('fs')>('fs');
-  return {
-    ...actual,
-    default: {
-      ...actual,
-      existsSync: vi.fn(() => true),
-      mkdirSync: vi.fn(),
-    },
-  };
-});
-
-// Mock child_process (used for osascript notification)
-vi.mock('child_process', () => ({
-  exec: vi.fn(),
-}));
-
-// Build a fake WASocket that's an EventEmitter with the methods we need
-function createFakeSocket() {
-  const ev = new EventEmitter();
-  const sock = {
-    ev: {
-      on: (event: string, handler: (...args: unknown[]) => void) => {
-        ev.on(event, handler);
-      },
-    },
-    user: {
-      id: '1234567890:1@s.whatsapp.net',
-      lid: '9876543210:1@lid',
-    },
-    sendMessage: vi.fn().mockResolvedValue(undefined),
-    sendPresenceUpdate: vi.fn().mockResolvedValue(undefined),
-    groupFetchAllParticipating: vi.fn().mockResolvedValue({}),
-    end: vi.fn(),
-    // Expose the event emitter for triggering events in tests
-    _ev: ev,
-  };
-  return sock;
-}
-
-let fakeSocket: ReturnType<typeof createFakeSocket>;
-
-// Mock Baileys
-vi.mock('@whiskeysockets/baileys', () => {
-  return {
-    default: vi.fn(() => fakeSocket),
-    Browsers: { macOS: vi.fn(() => ['macOS', 'Chrome', '']) },
-    DisconnectReason: {
-      loggedOut: 401,
-      badSession: 500,
-      connectionClosed: 428,
-      connectionLost: 408,
-      connectionReplaced: 440,
-      timedOut: 408,
-      restartRequired: 515,
-    },
-    makeCacheableSignalKeyStore: vi.fn((keys: unknown) => keys),
-    useMultiFileAuthState: vi.fn().mockResolvedValue({
-      state: {
-        creds: {},
-        keys: {},
-      },
-      saveCreds: vi.fn(),
-    }),
-  };
-});
-
-import { WhatsAppChannel, WhatsAppChannelOpts } from './whatsapp.js';
-import { getLastGroupSync, updateChatName, setLastGroupSync } from '../db.js';
-import { transcribeAudioMessage } from '../transcription.js';
-
-// --- Test helpers ---
-
-function createTestOpts(overrides?: Partial<WhatsAppChannelOpts>): WhatsAppChannelOpts {
-  return {
-    onMessage: vi.fn(),
-    onChatMetadata: vi.fn(),
-    registeredGroups: vi.fn(() => ({
-      'registered@g.us': {
-        name: 'Test Group',
-        folder: 'test-group',
-        trigger: '@Andy',
-        added_at: '2024-01-01T00:00:00.000Z',
-      },
-    })),
-    ...overrides,
-  };
-}
-
-function triggerConnection(state: string, extra?: Record<string, unknown>) {
-  fakeSocket._ev.emit('connection.update', { connection: state, ...extra });
-}
-
-function triggerDisconnect(statusCode: number) {
-  fakeSocket._ev.emit('connection.update', {
-    connection: 'close',
-    lastDisconnect: {
-      error: { output: { statusCode } },
-    },
-  });
-}
-
-async function triggerMessages(messages: unknown[]) {
-  fakeSocket._ev.emit('messages.upsert', { messages });
-  // Flush microtasks so the async messages.upsert handler completes
-  await new Promise((r) => setTimeout(r, 0));
-}
-
-// --- Tests ---
-
-describe('WhatsAppChannel', () => {
-  beforeEach(() => {
-    fakeSocket = createFakeSocket();
-    vi.mocked(getLastGroupSync).mockReturnValue(null);
-  });
-
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  /**
-   * Helper: start connect, flush microtasks so event handlers are registered,
-   * then trigger the connection open event. Returns the resolved promise.
-   */
-  async function connectChannel(channel: WhatsAppChannel): Promise<void> {
-    const p = channel.connect();
-    // Flush microtasks so connectInternal completes its await and registers handlers
-    await new Promise((r) => setTimeout(r, 0));
-    triggerConnection('open');
-    return p;
-  }
-
-  // --- Connection lifecycle ---
-
-  describe('connection lifecycle', () => {
-    it('resolves connect() when connection opens', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      expect(channel.isConnected()).toBe(true);
-    });
-
-    it('sets up LID to phone mapping on open', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      // The channel should have mapped the LID from sock.user
-      // We can verify by sending a message from a LID JID
-      // and checking the translated JID in the callback
-    });
-
-    it('flushes outgoing queue on reconnect', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      // Disconnect
-      (channel as any).connected = false;
-
-      // Queue a message while disconnected
-      await channel.sendMessage('test@g.us', 'Queued message');
-      expect(fakeSocket.sendMessage).not.toHaveBeenCalled();
-
-      // Reconnect
-      (channel as any).connected = true;
-      await (channel as any).flushOutgoingQueue();
-
-      // Group messages get prefixed when flushed
-      expect(fakeSocket.sendMessage).toHaveBeenCalledWith(
-        'test@g.us',
-        { text: 'Andy: Queued message' },
-      );
-    });
-
-    it('disconnects cleanly', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await channel.disconnect();
-      expect(channel.isConnected()).toBe(false);
-      expect(fakeSocket.end).toHaveBeenCalled();
-    });
-  });
-
-  // --- QR code and auth ---
-
-  describe('authentication', () => {
-    it('exits process when QR code is emitted (no auth state)', async () => {
-      vi.useFakeTimers();
-      const mockExit = vi.spyOn(process, 'exit').mockImplementation(() => undefined as never);
-
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      // Start connect but don't await (it won't resolve - process exits)
-      channel.connect().catch(() => {});
-
-      // Flush microtasks so connectInternal registers handlers
-      await vi.advanceTimersByTimeAsync(0);
-
-      // Emit QR code event
-      fakeSocket._ev.emit('connection.update', { qr: 'some-qr-data' });
-
-      // Advance timer past the 1000ms setTimeout before exit
-      await vi.advanceTimersByTimeAsync(1500);
-
-      expect(mockExit).toHaveBeenCalledWith(1);
-      mockExit.mockRestore();
-      vi.useRealTimers();
-    });
-  });
-
-  // --- Reconnection behavior ---
-
-  describe('reconnection', () => {
-    it('reconnects on non-loggedOut disconnect', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      expect(channel.isConnected()).toBe(true);
-
-      // Disconnect with a non-loggedOut reason (e.g., connectionClosed = 428)
-      triggerDisconnect(428);
-
-      expect(channel.isConnected()).toBe(false);
-      // The channel should attempt to reconnect (calls connectInternal again)
-    });
-
-    it('exits on loggedOut disconnect', async () => {
-      const mockExit = vi.spyOn(process, 'exit').mockImplementation(() => undefined as never);
-
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      // Disconnect with loggedOut reason (401)
-      triggerDisconnect(401);
-
-      expect(channel.isConnected()).toBe(false);
-      expect(mockExit).toHaveBeenCalledWith(0);
-      mockExit.mockRestore();
-    });
-
-    it('retries reconnection after 5s on failure', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      // Disconnect with stream error 515
-      triggerDisconnect(515);
-
-      // The channel sets a 5s retry — just verify it doesn't crash
-      await new Promise((r) => setTimeout(r, 100));
-    });
-  });
-
-  // --- Message handling ---
-
-  describe('message handling', () => {
-    it('delivers message for registered group', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-1',
-            remoteJid: 'registered@g.us',
-            participant: '5551234@s.whatsapp.net',
-            fromMe: false,
-          },
-          message: { conversation: 'Hello Andy' },
-          pushName: 'Alice',
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      expect(opts.onChatMetadata).toHaveBeenCalledWith(
-        'registered@g.us',
-        expect.any(String),
-        undefined,
-        'whatsapp',
-        true,
-      );
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'registered@g.us',
-        expect.objectContaining({
-          id: 'msg-1',
-          content: 'Hello Andy',
-          sender_name: 'Alice',
-          is_from_me: false,
-        }),
-      );
-    });
-
-    it('only emits metadata for unregistered groups', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-2',
-            remoteJid: 'unregistered@g.us',
-            participant: '5551234@s.whatsapp.net',
-            fromMe: false,
-          },
-          message: { conversation: 'Hello' },
-          pushName: 'Bob',
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      expect(opts.onChatMetadata).toHaveBeenCalledWith(
-        'unregistered@g.us',
-        expect.any(String),
-        undefined,
-        'whatsapp',
-        true,
-      );
-      expect(opts.onMessage).not.toHaveBeenCalled();
-    });
-
-    it('ignores status@broadcast messages', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-3',
-            remoteJid: 'status@broadcast',
-            fromMe: false,
-          },
-          message: { conversation: 'Status update' },
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      expect(opts.onChatMetadata).not.toHaveBeenCalled();
-      expect(opts.onMessage).not.toHaveBeenCalled();
-    });
-
-    it('ignores messages with no content', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-4',
-            remoteJid: 'registered@g.us',
-            fromMe: false,
-          },
-          message: null,
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      expect(opts.onMessage).not.toHaveBeenCalled();
-    });
-
-    it('extracts text from extendedTextMessage', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-5',
-            remoteJid: 'registered@g.us',
-            participant: '5551234@s.whatsapp.net',
-            fromMe: false,
-          },
-          message: {
-            extendedTextMessage: { text: 'A reply message' },
-          },
-          pushName: 'Charlie',
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'registered@g.us',
-        expect.objectContaining({ content: 'A reply message' }),
-      );
-    });
-
-    it('extracts caption from imageMessage', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-6',
-            remoteJid: 'registered@g.us',
-            participant: '5551234@s.whatsapp.net',
-            fromMe: false,
-          },
-          message: {
-            imageMessage: { caption: 'Check this photo', mimetype: 'image/jpeg' },
-          },
-          pushName: 'Diana',
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'registered@g.us',
-        expect.objectContaining({ content: 'Check this photo' }),
-      );
-    });
-
-    it('extracts caption from videoMessage', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-7',
-            remoteJid: 'registered@g.us',
-            participant: '5551234@s.whatsapp.net',
-            fromMe: false,
-          },
-          message: {
-            videoMessage: { caption: 'Watch this', mimetype: 'video/mp4' },
-          },
-          pushName: 'Eve',
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'registered@g.us',
-        expect.objectContaining({ content: 'Watch this' }),
-      );
-    });
-
-    it('transcribes voice messages', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-8',
-            remoteJid: 'registered@g.us',
-            participant: '5551234@s.whatsapp.net',
-            fromMe: false,
-          },
-          message: {
-            audioMessage: { mimetype: 'audio/ogg; codecs=opus', ptt: true },
-          },
-          pushName: 'Frank',
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      expect(transcribeAudioMessage).toHaveBeenCalled();
-      expect(opts.onMessage).toHaveBeenCalledTimes(1);
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'registered@g.us',
-        expect.objectContaining({ content: '[Voice: Hello this is a voice message]' }),
-      );
-    });
-
-    it('falls back when transcription returns null', async () => {
-      vi.mocked(transcribeAudioMessage).mockResolvedValueOnce(null);
-
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-8b',
-            remoteJid: 'registered@g.us',
-            participant: '5551234@s.whatsapp.net',
-            fromMe: false,
-          },
-          message: {
-            audioMessage: { mimetype: 'audio/ogg; codecs=opus', ptt: true },
-          },
-          pushName: 'Frank',
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      expect(opts.onMessage).toHaveBeenCalledTimes(1);
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'registered@g.us',
-        expect.objectContaining({ content: '[Voice Message - transcription unavailable]' }),
-      );
-    });
-
-    it('falls back when transcription throws', async () => {
-      vi.mocked(transcribeAudioMessage).mockRejectedValueOnce(new Error('API error'));
-
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-8c',
-            remoteJid: 'registered@g.us',
-            participant: '5551234@s.whatsapp.net',
-            fromMe: false,
-          },
-          message: {
-            audioMessage: { mimetype: 'audio/ogg; codecs=opus', ptt: true },
-          },
-          pushName: 'Frank',
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      expect(opts.onMessage).toHaveBeenCalledTimes(1);
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'registered@g.us',
-        expect.objectContaining({ content: '[Voice Message - transcription failed]' }),
-      );
-    });
-
-    it('uses sender JID when pushName is absent', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-9',
-            remoteJid: 'registered@g.us',
-            participant: '5551234@s.whatsapp.net',
-            fromMe: false,
-          },
-          message: { conversation: 'No push name' },
-          // pushName is undefined
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'registered@g.us',
-        expect.objectContaining({ sender_name: '5551234' }),
-      );
-    });
-  });
-
-  // --- LID ↔ JID translation ---
-
-  describe('LID to JID translation', () => {
-    it('translates known LID to phone JID', async () => {
-      const opts = createTestOpts({
-        registeredGroups: vi.fn(() => ({
-          '1234567890@s.whatsapp.net': {
-            name: 'Self Chat',
-            folder: 'self-chat',
-            trigger: '@Andy',
-            added_at: '2024-01-01T00:00:00.000Z',
-          },
-        })),
-      });
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      // The socket has lid '9876543210:1@lid' → phone '1234567890@s.whatsapp.net'
-      // Send a message from the LID
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-lid',
-            remoteJid: '9876543210@lid',
-            fromMe: false,
-          },
-          message: { conversation: 'From LID' },
-          pushName: 'Self',
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      // Should be translated to phone JID
-      expect(opts.onChatMetadata).toHaveBeenCalledWith(
-        '1234567890@s.whatsapp.net',
-        expect.any(String),
-        undefined,
-        'whatsapp',
-        false,
-      );
-    });
-
-    it('passes through non-LID JIDs unchanged', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-normal',
-            remoteJid: 'registered@g.us',
-            participant: '5551234@s.whatsapp.net',
-            fromMe: false,
-          },
-          message: { conversation: 'Normal JID' },
-          pushName: 'Grace',
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      expect(opts.onChatMetadata).toHaveBeenCalledWith(
-        'registered@g.us',
-        expect.any(String),
-        undefined,
-        'whatsapp',
-        true,
-      );
-    });
-
-    it('passes through unknown LID JIDs unchanged', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-unknown-lid',
-            remoteJid: '0000000000@lid',
-            fromMe: false,
-          },
-          message: { conversation: 'Unknown LID' },
-          pushName: 'Unknown',
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      // Unknown LID passes through unchanged
-      expect(opts.onChatMetadata).toHaveBeenCalledWith(
-        '0000000000@lid',
-        expect.any(String),
-        undefined,
-        'whatsapp',
-        false,
-      );
-    });
-  });
-
-  // --- Outgoing message queue ---
-
-  describe('outgoing message queue', () => {
-    it('sends message directly when connected', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await channel.sendMessage('test@g.us', 'Hello');
-      // Group messages get prefixed with assistant name
-      expect(fakeSocket.sendMessage).toHaveBeenCalledWith('test@g.us', { text: 'Andy: Hello' });
-    });
-
-    it('prefixes direct chat messages on shared number', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await channel.sendMessage('123@s.whatsapp.net', 'Hello');
-      // Shared number: DMs also get prefixed (needed for self-chat distinction)
-      expect(fakeSocket.sendMessage).toHaveBeenCalledWith('123@s.whatsapp.net', { text: 'Andy: Hello' });
-    });
-
-    it('queues message when disconnected', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      // Don't connect — channel starts disconnected
-      await channel.sendMessage('test@g.us', 'Queued');
-      expect(fakeSocket.sendMessage).not.toHaveBeenCalled();
-    });
-
-    it('queues message on send failure', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      // Make sendMessage fail
-      fakeSocket.sendMessage.mockRejectedValueOnce(new Error('Network error'));
-
-      await channel.sendMessage('test@g.us', 'Will fail');
-
-      // Should not throw, message queued for retry
-      // The queue should have the message
-    });
-
-    it('flushes multiple queued messages in order', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      // Queue messages while disconnected
-      await channel.sendMessage('test@g.us', 'First');
-      await channel.sendMessage('test@g.us', 'Second');
-      await channel.sendMessage('test@g.us', 'Third');
-
-      // Connect — flush happens automatically on open
-      await connectChannel(channel);
-
-      // Give the async flush time to complete
-      await new Promise((r) => setTimeout(r, 50));
-
-      expect(fakeSocket.sendMessage).toHaveBeenCalledTimes(3);
-      // Group messages get prefixed
-      expect(fakeSocket.sendMessage).toHaveBeenNthCalledWith(1, 'test@g.us', { text: 'Andy: First' });
-      expect(fakeSocket.sendMessage).toHaveBeenNthCalledWith(2, 'test@g.us', { text: 'Andy: Second' });
-      expect(fakeSocket.sendMessage).toHaveBeenNthCalledWith(3, 'test@g.us', { text: 'Andy: Third' });
-    });
-  });
-
-  // --- Group metadata sync ---
-
-  describe('group metadata sync', () => {
-    it('syncs group metadata on first connection', async () => {
-      fakeSocket.groupFetchAllParticipating.mockResolvedValue({
-        'group1@g.us': { subject: 'Group One' },
-        'group2@g.us': { subject: 'Group Two' },
-      });
-
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      // Wait for async sync to complete
-      await new Promise((r) => setTimeout(r, 50));
-
-      expect(fakeSocket.groupFetchAllParticipating).toHaveBeenCalled();
-      expect(updateChatName).toHaveBeenCalledWith('group1@g.us', 'Group One');
-      expect(updateChatName).toHaveBeenCalledWith('group2@g.us', 'Group Two');
-      expect(setLastGroupSync).toHaveBeenCalled();
-    });
-
-    it('skips sync when synced recently', async () => {
-      // Last sync was 1 hour ago (within 24h threshold)
-      vi.mocked(getLastGroupSync).mockReturnValue(
-        new Date(Date.now() - 60 * 60 * 1000).toISOString(),
-      );
-
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await new Promise((r) => setTimeout(r, 50));
-
-      expect(fakeSocket.groupFetchAllParticipating).not.toHaveBeenCalled();
-    });
-
-    it('forces sync regardless of cache', async () => {
-      vi.mocked(getLastGroupSync).mockReturnValue(
-        new Date(Date.now() - 60 * 60 * 1000).toISOString(),
-      );
-
-      fakeSocket.groupFetchAllParticipating.mockResolvedValue({
-        'group@g.us': { subject: 'Forced Group' },
-      });
-
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await channel.syncGroupMetadata(true);
-
-      expect(fakeSocket.groupFetchAllParticipating).toHaveBeenCalled();
-      expect(updateChatName).toHaveBeenCalledWith('group@g.us', 'Forced Group');
-    });
-
-    it('handles group sync failure gracefully', async () => {
-      fakeSocket.groupFetchAllParticipating.mockRejectedValue(
-        new Error('Network timeout'),
-      );
-
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      // Should not throw
-      await expect(channel.syncGroupMetadata(true)).resolves.toBeUndefined();
-    });
-
-    it('skips groups with no subject', async () => {
-      fakeSocket.groupFetchAllParticipating.mockResolvedValue({
-        'group1@g.us': { subject: 'Has Subject' },
-        'group2@g.us': { subject: '' },
-        'group3@g.us': {},
-      });
-
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      // Clear any calls from the automatic sync on connect
-      vi.mocked(updateChatName).mockClear();
-
-      await channel.syncGroupMetadata(true);
-
-      expect(updateChatName).toHaveBeenCalledTimes(1);
-      expect(updateChatName).toHaveBeenCalledWith('group1@g.us', 'Has Subject');
-    });
-  });
-
-  // --- JID ownership ---
-
-  describe('ownsJid', () => {
-    it('owns @g.us JIDs (WhatsApp groups)', () => {
-      const channel = new WhatsAppChannel(createTestOpts());
-      expect(channel.ownsJid('12345@g.us')).toBe(true);
-    });
-
-    it('owns @s.whatsapp.net JIDs (WhatsApp DMs)', () => {
-      const channel = new WhatsAppChannel(createTestOpts());
-      expect(channel.ownsJid('12345@s.whatsapp.net')).toBe(true);
-    });
-
-    it('does not own Telegram JIDs', () => {
-      const channel = new WhatsAppChannel(createTestOpts());
-      expect(channel.ownsJid('tg:12345')).toBe(false);
-    });
-
-    it('does not own unknown JID formats', () => {
-      const channel = new WhatsAppChannel(createTestOpts());
-      expect(channel.ownsJid('random-string')).toBe(false);
-    });
-  });
-
-  // --- Typing indicator ---
-
-  describe('setTyping', () => {
-    it('sends composing presence when typing', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await channel.setTyping('test@g.us', true);
-      expect(fakeSocket.sendPresenceUpdate).toHaveBeenCalledWith('composing', 'test@g.us');
-    });
-
-    it('sends paused presence when stopping', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await channel.setTyping('test@g.us', false);
-      expect(fakeSocket.sendPresenceUpdate).toHaveBeenCalledWith('paused', 'test@g.us');
-    });
-
-    it('handles typing indicator failure gracefully', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      fakeSocket.sendPresenceUpdate.mockRejectedValueOnce(new Error('Failed'));
-
-      // Should not throw
-      await expect(channel.setTyping('test@g.us', true)).resolves.toBeUndefined();
-    });
-  });
-
-  // --- Channel properties ---
-
-  describe('channel properties', () => {
-    it('has name "whatsapp"', () => {
-      const channel = new WhatsAppChannel(createTestOpts());
-      expect(channel.name).toBe('whatsapp');
-    });
-
-    it('does not expose prefixAssistantName (prefix handled internally)', () => {
-      const channel = new WhatsAppChannel(createTestOpts());
-      expect('prefixAssistantName' in channel).toBe(false);
-    });
-  });
-});

.claude/skills/add-voice-transcription/modify/src/channels/whatsapp.test.ts.intent.md

@@ -1,26 +0,0 @@
-# Intent: src/channels/whatsapp.test.ts modifications
-
-## What changed
-Added mock for the transcription module and 3 new test cases for voice message handling.
-
-## Key sections
-
-### Mocks (top of file)
-- Added: `vi.mock('../transcription.js', ...)` with `isVoiceMessage` and `transcribeAudioMessage` mocks
-- Added: `import { transcribeAudioMessage } from '../transcription.js'` for test assertions
-
-### Test cases (inside "message handling" describe block)
-- Changed: "handles message with no extractable text (e.g. voice note without caption)" → "transcribes voice messages"
-  - Now expects `[Voice: Hello this is a voice message]` instead of empty content
-- Added: "falls back when transcription returns null" — expects `[Voice Message - transcription unavailable]`
-- Added: "falls back when transcription throws" — expects `[Voice Message - transcription failed]`
-
-## Invariants (must-keep)
-- All existing test cases for text, extendedTextMessage, imageMessage, videoMessage unchanged
-- All connection lifecycle tests unchanged
-- All LID translation tests unchanged
-- All outgoing queue tests unchanged
-- All group metadata sync tests unchanged
-- All ownsJid and setTyping tests unchanged
-- All existing mocks (config, logger, db, fs, child_process, baileys) unchanged
-- Test helpers (createTestOpts, triggerConnection, triggerDisconnect, triggerMessages, connectChannel) unchanged

.claude/skills/add-voice-transcription/modify/src/channels/whatsapp.ts

@@ -1,356 +0,0 @@
-import { exec } from 'child_process';
-import fs from 'fs';
-import path from 'path';
-
-import makeWASocket, {
-  Browsers,
-  DisconnectReason,
-  WASocket,
-  fetchLatestWaWebVersion,
-  makeCacheableSignalKeyStore,
-  useMultiFileAuthState,
-} from '@whiskeysockets/baileys';
-
-import { ASSISTANT_HAS_OWN_NUMBER, ASSISTANT_NAME, STORE_DIR } from '../config.js';
-import {
-  getLastGroupSync,
-  setLastGroupSync,
-  updateChatName,
-} from '../db.js';
-import { logger } from '../logger.js';
-import { isVoiceMessage, transcribeAudioMessage } from '../transcription.js';
-import { Channel, OnInboundMessage, OnChatMetadata, RegisteredGroup } from '../types.js';
-
-const GROUP_SYNC_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
-
-export interface WhatsAppChannelOpts {
-  onMessage: OnInboundMessage;
-  onChatMetadata: OnChatMetadata;
-  registeredGroups: () => Record<string, RegisteredGroup>;
-}
-
-export class WhatsAppChannel implements Channel {
-  name = 'whatsapp';
-
-  private sock!: WASocket;
-  private connected = false;
-  private lidToPhoneMap: Record<string, string> = {};
-  private outgoingQueue: Array<{ jid: string; text: string }> = [];
-  private flushing = false;
-  private groupSyncTimerStarted = false;
-
-  private opts: WhatsAppChannelOpts;
-
-  constructor(opts: WhatsAppChannelOpts) {
-    this.opts = opts;
-  }
-
-  async connect(): Promise<void> {
-    return new Promise<void>((resolve, reject) => {
-      this.connectInternal(resolve).catch(reject);
-    });
-  }
-
-  private async connectInternal(onFirstOpen?: () => void): Promise<void> {
-    const authDir = path.join(STORE_DIR, 'auth');
-    fs.mkdirSync(authDir, { recursive: true });
-
-    const { state, saveCreds } = await useMultiFileAuthState(authDir);
-
-    const { version } = await fetchLatestWaWebVersion({}).catch((err) => {
-      logger.warn({ err }, 'Failed to fetch latest WA Web version, using default');
-      return { version: undefined };
-    });
-    this.sock = makeWASocket({
-      version,
-      auth: {
-        creds: state.creds,
-        keys: makeCacheableSignalKeyStore(state.keys, logger),
-      },
-      printQRInTerminal: false,
-      logger,
-      browser: Browsers.macOS('Chrome'),
-    });
-
-    this.sock.ev.on('connection.update', (update) => {
-      const { connection, lastDisconnect, qr } = update;
-
-      if (qr) {
-        const msg =
-          'WhatsApp authentication required. Run /setup in Claude Code.';
-        logger.error(msg);
-        exec(
-          `osascript -e 'display notification "${msg}" with title "NanoClaw" sound name "Basso"'`,
-        );
-        setTimeout(() => process.exit(1), 1000);
-      }
-
-      if (connection === 'close') {
-        this.connected = false;
-        const reason = (lastDisconnect?.error as { output?: { statusCode?: number } })?.output?.statusCode;
-        const shouldReconnect = reason !== DisconnectReason.loggedOut;
-        logger.info({ reason, shouldReconnect, queuedMessages: this.outgoingQueue.length }, 'Connection closed');
-
-        if (shouldReconnect) {
-          logger.info('Reconnecting...');
-          this.connectInternal().catch((err) => {
-            logger.error({ err }, 'Failed to reconnect, retrying in 5s');
-            setTimeout(() => {
-              this.connectInternal().catch((err2) => {
-                logger.error({ err: err2 }, 'Reconnection retry failed');
-              });
-            }, 5000);
-          });
-        } else {
-          logger.info('Logged out. Run /setup to re-authenticate.');
-          process.exit(0);
-        }
-      } else if (connection === 'open') {
-        this.connected = true;
-        logger.info('Connected to WhatsApp');
-
-        // Announce availability so WhatsApp relays subsequent presence updates (typing indicators)
-        this.sock.sendPresenceUpdate('available').catch((err) => {
-          logger.warn({ err }, 'Failed to send presence update');
-        });
-
-        // Build LID to phone mapping from auth state for self-chat translation
-        if (this.sock.user) {
-          const phoneUser = this.sock.user.id.split(':')[0];
-          const lidUser = this.sock.user.lid?.split(':')[0];
-          if (lidUser && phoneUser) {
-            this.lidToPhoneMap[lidUser] = `${phoneUser}@s.whatsapp.net`;
-            logger.debug({ lidUser, phoneUser }, 'LID to phone mapping set');
-          }
-        }
-
-        // Flush any messages queued while disconnected
-        this.flushOutgoingQueue().catch((err) =>
-          logger.error({ err }, 'Failed to flush outgoing queue'),
-        );
-
-        // Sync group metadata on startup (respects 24h cache)
-        this.syncGroupMetadata().catch((err) =>
-          logger.error({ err }, 'Initial group sync failed'),
-        );
-        // Set up daily sync timer (only once)
-        if (!this.groupSyncTimerStarted) {
-          this.groupSyncTimerStarted = true;
-          setInterval(() => {
-            this.syncGroupMetadata().catch((err) =>
-              logger.error({ err }, 'Periodic group sync failed'),
-            );
-          }, GROUP_SYNC_INTERVAL_MS);
-        }
-
-        // Signal first connection to caller
-        if (onFirstOpen) {
-          onFirstOpen();
-          onFirstOpen = undefined;
-        }
-      }
-    });
-
-    this.sock.ev.on('creds.update', saveCreds);
-
-    this.sock.ev.on('messages.upsert', async ({ messages }) => {
-      for (const msg of messages) {
-        if (!msg.message) continue;
-        const rawJid = msg.key.remoteJid;
-        if (!rawJid || rawJid === 'status@broadcast') continue;
-
-        // Translate LID JID to phone JID if applicable
-        const chatJid = await this.translateJid(rawJid);
-
-        const timestamp = new Date(
-          Number(msg.messageTimestamp) * 1000,
-        ).toISOString();
-
-        // Always notify about chat metadata for group discovery
-        const isGroup = chatJid.endsWith('@g.us');
-        this.opts.onChatMetadata(chatJid, timestamp, undefined, 'whatsapp', isGroup);
-
-        // Only deliver full message for registered groups
-        const groups = this.opts.registeredGroups();
-        if (groups[chatJid]) {
-          const content =
-            msg.message?.conversation ||
-            msg.message?.extendedTextMessage?.text ||
-            msg.message?.imageMessage?.caption ||
-            msg.message?.videoMessage?.caption ||
-            '';
-
-          // Skip protocol messages with no text content (encryption keys, read receipts, etc.)
-          // but allow voice messages through for transcription
-          if (!content && !isVoiceMessage(msg)) continue;
-
-          const sender = msg.key.participant || msg.key.remoteJid || '';
-          const senderName = msg.pushName || sender.split('@')[0];
-
-          const fromMe = msg.key.fromMe || false;
-          // Detect bot messages: with own number, fromMe is reliable
-          // since only the bot sends from that number.
-          // With shared number, bot messages carry the assistant name prefix
-          // (even in DMs/self-chat) so we check for that.
-          const isBotMessage = ASSISTANT_HAS_OWN_NUMBER
-            ? fromMe
-            : content.startsWith(`${ASSISTANT_NAME}:`);
-
-          // Transcribe voice messages before storing
-          let finalContent = content;
-          if (isVoiceMessage(msg)) {
-            try {
-              const transcript = await transcribeAudioMessage(msg, this.sock);
-              if (transcript) {
-                finalContent = `[Voice: ${transcript}]`;
-                logger.info({ chatJid, length: transcript.length }, 'Transcribed voice message');
-              } else {
-                finalContent = '[Voice Message - transcription unavailable]';
-              }
-            } catch (err) {
-              logger.error({ err }, 'Voice transcription error');
-              finalContent = '[Voice Message - transcription failed]';
-            }
-          }
-
-          this.opts.onMessage(chatJid, {
-            id: msg.key.id || '',
-            chat_jid: chatJid,
-            sender,
-            sender_name: senderName,
-            content: finalContent,
-            timestamp,
-            is_from_me: fromMe,
-            is_bot_message: isBotMessage,
-          });
-        }
-      }
-    });
-  }
-
-  async sendMessage(jid: string, text: string): Promise<void> {
-    // Prefix bot messages with assistant name so users know who's speaking.
-    // On a shared number, prefix is also needed in DMs (including self-chat)
-    // to distinguish bot output from user messages.
-    // Skip only when the assistant has its own dedicated phone number.
-    const prefixed = ASSISTANT_HAS_OWN_NUMBER
-      ? text
-      : `${ASSISTANT_NAME}: ${text}`;
-
-    if (!this.connected) {
-      this.outgoingQueue.push({ jid, text: prefixed });
-      logger.info({ jid, length: prefixed.length, queueSize: this.outgoingQueue.length }, 'WA disconnected, message queued');
-      return;
-    }
-    try {
-      await this.sock.sendMessage(jid, { text: prefixed });
-      logger.info({ jid, length: prefixed.length }, 'Message sent');
-    } catch (err) {
-      // If send fails, queue it for retry on reconnect
-      this.outgoingQueue.push({ jid, text: prefixed });
-      logger.warn({ jid, err, queueSize: this.outgoingQueue.length }, 'Failed to send, message queued');
-    }
-  }
-
-  isConnected(): boolean {
-    return this.connected;
-  }
-
-  ownsJid(jid: string): boolean {
-    return jid.endsWith('@g.us') || jid.endsWith('@s.whatsapp.net');
-  }
-
-  async disconnect(): Promise<void> {
-    this.connected = false;
-    this.sock?.end(undefined);
-  }
-
-  async setTyping(jid: string, isTyping: boolean): Promise<void> {
-    try {
-      const status = isTyping ? 'composing' : 'paused';
-      logger.debug({ jid, status }, 'Sending presence update');
-      await this.sock.sendPresenceUpdate(status, jid);
-    } catch (err) {
-      logger.debug({ jid, err }, 'Failed to update typing status');
-    }
-  }
-
-  /**
-   * Sync group metadata from WhatsApp.
-   * Fetches all participating groups and stores their names in the database.
-   * Called on startup, daily, and on-demand via IPC.
-   */
-  async syncGroupMetadata(force = false): Promise<void> {
-    if (!force) {
-      const lastSync = getLastGroupSync();
-      if (lastSync) {
-        const lastSyncTime = new Date(lastSync).getTime();
-        if (Date.now() - lastSyncTime < GROUP_SYNC_INTERVAL_MS) {
-          logger.debug({ lastSync }, 'Skipping group sync - synced recently');
-          return;
-        }
-      }
-    }
-
-    try {
-      logger.info('Syncing group metadata from WhatsApp...');
-      const groups = await this.sock.groupFetchAllParticipating();
-
-      let count = 0;
-      for (const [jid, metadata] of Object.entries(groups)) {
-        if (metadata.subject) {
-          updateChatName(jid, metadata.subject);
-          count++;
-        }
-      }
-
-      setLastGroupSync();
-      logger.info({ count }, 'Group metadata synced');
-    } catch (err) {
-      logger.error({ err }, 'Failed to sync group metadata');
-    }
-  }
-
-  private async translateJid(jid: string): Promise<string> {
-    if (!jid.endsWith('@lid')) return jid;
-    const lidUser = jid.split('@')[0].split(':')[0];
-
-    // Check local cache first
-    const cached = this.lidToPhoneMap[lidUser];
-    if (cached) {
-      logger.debug({ lidJid: jid, phoneJid: cached }, 'Translated LID to phone JID (cached)');
-      return cached;
-    }
-
-    // Query Baileys' signal repository for the mapping
-    try {
-      const pn = await this.sock.signalRepository?.lidMapping?.getPNForLID(jid);
-      if (pn) {
-        const phoneJid = `${pn.split('@')[0].split(':')[0]}@s.whatsapp.net`;
-        this.lidToPhoneMap[lidUser] = phoneJid;
-        logger.info({ lidJid: jid, phoneJid }, 'Translated LID to phone JID (signalRepository)');
-        return phoneJid;
-      }
-    } catch (err) {
-      logger.debug({ err, jid }, 'Failed to resolve LID via signalRepository');
-    }
-
-    return jid;
-  }
-
-  private async flushOutgoingQueue(): Promise<void> {
-    if (this.flushing || this.outgoingQueue.length === 0) return;
-    this.flushing = true;
-    try {
-      logger.info({ count: this.outgoingQueue.length }, 'Flushing outgoing message queue');
-      while (this.outgoingQueue.length > 0) {
-        const item = this.outgoingQueue.shift()!;
-        // Send directly — queued items are already prefixed by sendMessage
-        await this.sock.sendMessage(item.jid, { text: item.text });
-        logger.info({ jid: item.jid, length: item.text.length }, 'Queued message sent');
-      }
-    } finally {
-      this.flushing = false;
-    }
-  }
-}

.claude/skills/add-voice-transcription/modify/src/channels/whatsapp.ts.intent.md

@@ -1,27 +0,0 @@
-# Intent: src/channels/whatsapp.ts modifications
-
-## What changed
-Added voice message transcription support. When a WhatsApp voice note (PTT audio) arrives, it is downloaded and transcribed via OpenAI Whisper before being stored as message content.
-
-## Key sections
-
-### Imports (top of file)
-- Added: `isVoiceMessage`, `transcribeAudioMessage` from `../transcription.js`
-
-### messages.upsert handler (inside connectInternal)
-- Added: `let finalContent = content` variable to allow voice transcription to override text content
-- Added: `isVoiceMessage(msg)` check after content extraction
-- Added: try/catch block calling `transcribeAudioMessage(msg, this.sock)`
-  - Success: `finalContent = '[Voice: <transcript>]'`
-  - Null result: `finalContent = '[Voice Message - transcription unavailable]'`
-  - Error: `finalContent = '[Voice Message - transcription failed]'`
-- Changed: `this.opts.onMessage()` call uses `finalContent` instead of `content`
-
-## Invariants (must-keep)
-- All existing message handling (conversation, extendedTextMessage, imageMessage, videoMessage) unchanged
-- Connection lifecycle (connect, reconnect, disconnect) unchanged
-- LID translation logic unchanged
-- Outgoing message queue unchanged
-- Group metadata sync unchanged
-- sendMessage prefix logic unchanged
-- setTyping, ownsJid, isConnected — all unchanged

.claude/skills/add-voice-transcription/tests/voice-transcription.test.ts

@@ -1,123 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import fs from 'fs';
-import path from 'path';
-
-describe('voice-transcription skill package', () => {
-  const skillDir = path.resolve(__dirname, '..');
-
-  it('has a valid manifest', () => {
-    const manifestPath = path.join(skillDir, 'manifest.yaml');
-    expect(fs.existsSync(manifestPath)).toBe(true);
-
-    const content = fs.readFileSync(manifestPath, 'utf-8');
-    expect(content).toContain('skill: voice-transcription');
-    expect(content).toContain('version: 1.0.0');
-    expect(content).toContain('openai');
-    expect(content).toContain('OPENAI_API_KEY');
-  });
-
-  it('has all files declared in adds', () => {
-    const transcriptionFile = path.join(skillDir, 'add', 'src', 'transcription.ts');
-    expect(fs.existsSync(transcriptionFile)).toBe(true);
-
-    const content = fs.readFileSync(transcriptionFile, 'utf-8');
-    expect(content).toContain('transcribeAudioMessage');
-    expect(content).toContain('isVoiceMessage');
-    expect(content).toContain('transcribeWithOpenAI');
-    expect(content).toContain('downloadMediaMessage');
-    expect(content).toContain('readEnvFile');
-  });
-
-  it('has all files declared in modifies', () => {
-    const whatsappFile = path.join(skillDir, 'modify', 'src', 'channels', 'whatsapp.ts');
-    const whatsappTestFile = path.join(skillDir, 'modify', 'src', 'channels', 'whatsapp.test.ts');
-
-    expect(fs.existsSync(whatsappFile)).toBe(true);
-    expect(fs.existsSync(whatsappTestFile)).toBe(true);
-  });
-
-  it('has intent files for modified files', () => {
-    expect(fs.existsSync(path.join(skillDir, 'modify', 'src', 'channels', 'whatsapp.ts.intent.md'))).toBe(true);
-    expect(fs.existsSync(path.join(skillDir, 'modify', 'src', 'channels', 'whatsapp.test.ts.intent.md'))).toBe(true);
-  });
-
-  it('modified whatsapp.ts preserves core structure', () => {
-    const content = fs.readFileSync(
-      path.join(skillDir, 'modify', 'src', 'channels', 'whatsapp.ts'),
-      'utf-8',
-    );
-
-    // Core class and methods preserved
-    expect(content).toContain('class WhatsAppChannel');
-    expect(content).toContain('implements Channel');
-    expect(content).toContain('async connect()');
-    expect(content).toContain('async sendMessage(');
-    expect(content).toContain('isConnected()');
-    expect(content).toContain('ownsJid(');
-    expect(content).toContain('async disconnect()');
-    expect(content).toContain('async setTyping(');
-    expect(content).toContain('async syncGroupMetadata(');
-    expect(content).toContain('private async translateJid(');
-    expect(content).toContain('private async flushOutgoingQueue(');
-
-    // Core imports preserved
-    expect(content).toContain('ASSISTANT_HAS_OWN_NUMBER');
-    expect(content).toContain('ASSISTANT_NAME');
-    expect(content).toContain('STORE_DIR');
-  });
-
-  it('modified whatsapp.ts includes transcription integration', () => {
-    const content = fs.readFileSync(
-      path.join(skillDir, 'modify', 'src', 'channels', 'whatsapp.ts'),
-      'utf-8',
-    );
-
-    // Transcription imports
-    expect(content).toContain("import { isVoiceMessage, transcribeAudioMessage } from '../transcription.js'");
-
-    // Voice message handling
-    expect(content).toContain('isVoiceMessage(msg)');
-    expect(content).toContain('transcribeAudioMessage(msg, this.sock)');
-    expect(content).toContain('finalContent');
-    expect(content).toContain('[Voice:');
-    expect(content).toContain('[Voice Message - transcription unavailable]');
-    expect(content).toContain('[Voice Message - transcription failed]');
-  });
-
-  it('modified whatsapp.test.ts includes transcription mock and tests', () => {
-    const content = fs.readFileSync(
-      path.join(skillDir, 'modify', 'src', 'channels', 'whatsapp.test.ts'),
-      'utf-8',
-    );
-
-    // Transcription mock
-    expect(content).toContain("vi.mock('../transcription.js'");
-    expect(content).toContain('isVoiceMessage');
-    expect(content).toContain('transcribeAudioMessage');
-
-    // Voice transcription test cases
-    expect(content).toContain('transcribes voice messages');
-    expect(content).toContain('falls back when transcription returns null');
-    expect(content).toContain('falls back when transcription throws');
-    expect(content).toContain('[Voice: Hello this is a voice message]');
-  });
-
-  it('modified whatsapp.test.ts preserves all existing test sections', () => {
-    const content = fs.readFileSync(
-      path.join(skillDir, 'modify', 'src', 'channels', 'whatsapp.test.ts'),
-      'utf-8',
-    );
-
-    // All existing test describe blocks preserved
-    expect(content).toContain("describe('connection lifecycle'");
-    expect(content).toContain("describe('authentication'");
-    expect(content).toContain("describe('reconnection'");
-    expect(content).toContain("describe('message handling'");
-    expect(content).toContain("describe('LID to JID translation'");
-    expect(content).toContain("describe('outgoing message queue'");
-    expect(content).toContain("describe('group metadata sync'");
-    expect(content).toContain("describe('ownsJid'");
-    expect(content).toContain("describe('setTyping'");
-    expect(content).toContain("describe('channel properties'");
-  });
-});

.claude/skills/add-webex-v2/REMOVE.md

@@ -0,0 +1,6 @@
+# Remove Webex Channel
+
+1. Comment out `import './webex.js'` in `src/channels/index.ts`
+2. Remove `WEBEX_BOT_TOKEN` and `WEBEX_WEBHOOK_SECRET` from `.env`
+3. `pnpm uninstall @bitbasti/chat-adapter-webex`
+4. Rebuild and restart

.claude/skills/add-webex-v2/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: add-webex-v2
+description: Add Webex channel integration to NanoClaw v2 via Chat SDK.
+---
+
+# Add Webex Channel
+
+Adds Cisco Webex support to NanoClaw v2 using the Chat SDK bridge.
+
+## Pre-flight
+
+Check if `src/channels/webex.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Credentials.
+
+## Install
+
+```bash
+pnpm install @bitbasti/chat-adapter-webex
+```
+
+Uncomment the Webex import in `src/channels/index.ts`:
+
+```typescript
+import './webex.js';
+```
+
+```bash
+pnpm run build
+```
+
+## Credentials
+
+1. Go to [developer.webex.com](https://developer.webex.com/my-apps/new/bot) and create a new bot
+2. Copy the **Bot Access Token**
+3. Set up a webhook:
+   - Use the Webex API or Developer Portal to create a webhook pointing to `https://your-domain/webhook/webex`
+   - Set a webhook secret for signature verification
+
+### Configure environment
+
+Add to `.env`:
+
+```bash
+WEBEX_BOT_TOKEN=your-bot-token
+WEBEX_WEBHOOK_SECRET=your-webhook-secret
+```
+
+Sync to container: `mkdir -p data/env && cp .env data/env/env`
+
+## Next Steps
+
+If you're in the middle of `/setup`, return to the setup flow now.
+
+Otherwise, run `/manage-channels` to wire this channel to an agent group.
+
+## Channel Info
+
+- **type**: `webex`
+- **terminology**: Webex has "spaces." A space can be a group conversation or a 1:1 direct message with the bot.
+- **how-to-find-id**: Open the space in Webex, click the space name > Settings — the Space ID is listed there. Or use the Webex API (`GET /rooms`) to list spaces and their IDs.
+- **supports-threads**: yes
+- **typical-use**: Interactive chat — team spaces or direct messages
+- **default-isolation**: Same agent group for spaces where you're the primary user. Separate agent group for spaces with different teams or sensitive information.

.claude/skills/add-webex-v2/VERIFY.md

@@ -0,0 +1,3 @@
+# Verify Webex Channel
+
+Add the bot to a Webex space or send it a direct message. The bot should respond within a few seconds.

.claude/skills/add-whatsapp-cloud-v2/REMOVE.md

@@ -0,0 +1,6 @@
+# Remove WhatsApp Cloud API Channel
+
+1. Comment out `import './whatsapp-cloud.js'` in `src/channels/index.ts`
+2. Remove `WHATSAPP_ACCESS_TOKEN`, `WHATSAPP_PHONE_NUMBER_ID`, `WHATSAPP_APP_SECRET`, `WHATSAPP_VERIFY_TOKEN` from `.env`
+3. `pnpm uninstall @chat-adapter/whatsapp`
+4. Rebuild and restart

.claude/skills/add-whatsapp-cloud-v2/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: add-whatsapp-cloud-v2
+description: Add WhatsApp Business Cloud API channel to NanoClaw v2 via Chat SDK. Official Meta API.
+---
+
+# Add WhatsApp Cloud API Channel
+
+Connect NanoClaw to WhatsApp via the official Meta WhatsApp Business Cloud API.
+
+## Pre-flight
+
+Check if `src/channels/whatsapp-cloud.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Credentials.
+
+## Install
+
+```bash
+pnpm install @chat-adapter/whatsapp
+```
+
+Uncomment the WhatsApp Cloud API import in `src/channels/index.ts`:
+
+```typescript
+import './whatsapp-cloud.js';
+```
+
+Build:
+
+```bash
+pnpm run build
+```
+
+## Credentials
+
+1. Go to [Meta for Developers](https://developers.facebook.com/apps/) and create an app (type: Business).
+2. Add the **WhatsApp** product.
+3. Go to **WhatsApp** > **API Setup**:
+   - Note the **Phone Number ID** (not the phone number itself).
+   - Generate a **permanent System User access token** with `whatsapp_business_messaging` permission.
+4. Go to **WhatsApp** > **Configuration**:
+   - Set webhook URL: `https://your-domain/webhook/whatsapp`.
+   - Set a **Verify Token** (any random string you choose).
+   - Subscribe to webhook fields: `messages`.
+5. Copy the **App Secret** from **Settings** > **Basic**.
+
+### Configure environment
+
+Add to `.env`:
+
+```bash
+WHATSAPP_ACCESS_TOKEN=your-system-user-access-token
+WHATSAPP_PHONE_NUMBER_ID=your-phone-number-id
+WHATSAPP_APP_SECRET=your-app-secret
+WHATSAPP_VERIFY_TOKEN=your-verify-token
+```
+
+Sync to container: `mkdir -p data/env && cp .env data/env/env`
+
+## Next Steps
+
+If you're in the middle of `/setup`, return to the setup flow now.
+
+Otherwise, run `/manage-channels` to wire this channel to an agent group.
+
+## Channel Info
+
+- **type**: `whatsapp-cloud`
+- **terminology**: WhatsApp Cloud API supports 1:1 conversations only (no group chats). Each conversation is with a phone number.
+- **how-to-find-id**: The platform ID is the Phone Number ID from the Meta Business dashboard (not the phone number itself). Find it under WhatsApp > API Setup.
+- **supports-threads**: no
+- **typical-use**: Interactive 1:1 chat -- direct messages only
+- **default-isolation**: Same agent group if you're the only person messaging the bot. Each additional person who messages gets their own conversation automatically, but they share the agent's workspace and memory -- use a separate agent group if you need information isolation between different contacts.

.claude/skills/add-whatsapp-cloud-v2/VERIFY.md

@@ -0,0 +1,3 @@
+# Verify WhatsApp Cloud API Channel
+
+Send a message to your WhatsApp Business number. The bot should respond within a few seconds. Note: WhatsApp Cloud API only supports 1:1 DMs, not group chats.

.claude/skills/add-whatsapp-v2/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: add-whatsapp-v2
+description: Add WhatsApp channel to NanoClaw v2 using native Baileys adapter. Direct connection — no Chat SDK bridge. Uses QR code or pairing code for authentication.
+---
+
+# Add WhatsApp Channel
+
+Adds WhatsApp support to NanoClaw v2 using the native Baileys adapter (no Chat SDK bridge).
+
+## Pre-flight
+
+Check if `src/channels/whatsapp.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Credentials.
+
+## Install
+
+### Install the adapter packages
+
+```bash
+pnpm install @whiskeysockets/baileys@^6.7.21 pino@^9.6.0 qrcode@^1.5.4 @types/qrcode@^1.5.6
+```
+
+### Enable the channel
+
+If `src/channels/whatsapp.ts` is missing, fetch it from upstream:
+
+```bash
+git remote -v | grep -q upstream || git remote add upstream https://github.com/qwibitai/nanoclaw.git
+git fetch upstream v2
+git checkout upstream/v2 -- src/channels/whatsapp.ts
+```
+
+Uncomment or add the WhatsApp import in `src/channels/index.ts`:
+
+```typescript
+// whatsapp (native, no Chat SDK)
+import './whatsapp.js';
+```
+
+### Build
+
+```bash
+pnpm run build
+```
+
+## Credentials
+
+WhatsApp uses linked-device authentication — no API key, just a one-time pairing from your phone.
+
+### Check current state
+
+Check if WhatsApp is already authenticated. If `store/auth/creds.json` exists, skip to "Shared vs dedicated number".
+
+```bash
+test -f store/auth/creds.json && echo "WhatsApp auth exists" || echo "No WhatsApp auth"
+```
+
+### Detect environment
+
+Check whether the environment is headless (no display server):
+
+```bash
+[[ -z "$DISPLAY" && -z "$WAYLAND_DISPLAY" && "$OSTYPE" != darwin* ]] && echo "IS_HEADLESS=true" || echo "IS_HEADLESS=false"
+```
+
+### Ask the user
+
+Use `AskUserQuestion` to collect configuration. **Adapt auth options based on environment:**
+
+If IS_HEADLESS=true AND not WSL → AskUserQuestion: How do you want to authenticate WhatsApp?
+- **Pairing code** (Recommended) - Enter a numeric code on your phone (no camera needed, requires phone number)
+- **QR code in terminal** - Displays QR code in the terminal (can be too small on some displays)
+
+Otherwise (macOS, desktop Linux, or WSL) → AskUserQuestion: How do you want to authenticate WhatsApp?
+- **QR code in browser** (Recommended) - Opens a browser window with a large, scannable QR code
+- **Pairing code** - Enter a numeric code on your phone (no camera needed, requires phone number)
+- **QR code in terminal** - Displays QR code in the terminal (can be too small on some displays)
+
+If they chose pairing code:
+
+AskUserQuestion: What is your phone number? (Digits only — country code followed by your 10-digit number, no + prefix, spaces, or dashes. Example: 14155551234 where 1 is the US country code and 4155551234 is the phone number.)
+
+### Clean previous auth state (if re-authenticating)
+
+```bash
+rm -rf store/auth/
+```
+
+### Run WhatsApp authentication
+
+For QR code in browser (recommended):
+
+```bash
+pnpm exec tsx setup/index.ts --step whatsapp-auth -- --method qr-browser
+```
+
+(Bash timeout: 150000ms)
+
+Tell the user:
+
+> A browser window will open with a QR code.
+>
+> 1. Open WhatsApp > **Settings** > **Linked Devices** > **Link a Device**
+> 2. Scan the QR code in the browser
+> 3. The page will show "Authenticated!" when done
+
+For QR code in terminal:
+
+```bash
+pnpm exec tsx setup/index.ts --step whatsapp-auth -- --method qr-terminal
+```
+
+(Bash timeout: 150000ms)
+
+Tell the user:
+
+> 1. Open WhatsApp > **Settings** > **Linked Devices** > **Link a Device**
+> 2. Scan the QR code displayed in the terminal
+
+For pairing code:
+
+Tell the user to have WhatsApp open on **Settings > Linked Devices > Link a Device**, ready to tap **"Link with phone number instead"** — the code expires in ~60 seconds and must be entered immediately.
+
+Run the auth process in the background and poll `store/pairing-code.txt` for the code:
+
+```bash
+rm -f store/pairing-code.txt && pnpm exec tsx setup/index.ts --step whatsapp-auth -- --method pairing-code --phone <their-phone-number> > /tmp/wa-auth.log 2>&1 &
+```
+
+Then immediately poll for the code (do NOT wait for the background command to finish):
+
+```bash
+for i in $(seq 1 20); do [ -f store/pairing-code.txt ] && cat store/pairing-code.txt && break; sleep 1; done
+```
+
+Display the code to the user the moment it appears. Tell them:
+
+> **Enter this code now** — it expires in ~60 seconds.
+>
+> 1. Open WhatsApp > **Settings** > **Linked Devices** > **Link a Device**
+> 2. Tap **Link with phone number instead**
+> 3. Enter the code immediately
+
+After the user enters the code, poll for authentication to complete:
+
+```bash
+for i in $(seq 1 60); do grep -q 'STATUS: authenticated' /tmp/wa-auth.log 2>/dev/null && echo "authenticated" && break; grep -q 'STATUS: failed' /tmp/wa-auth.log 2>/dev/null && echo "failed" && break; sleep 2; done
+```
+
+**If failed:** logged_out → delete `store/auth/` and re-run. timeout → ask user, offer retry.
+
+### Verify authentication succeeded
+
+```bash
+test -f store/auth/creds.json && echo "Authentication successful" || echo "Authentication failed"
+```
+
+### Shared vs dedicated number
+
+AskUserQuestion: Is this a shared phone number (personal WhatsApp) or a dedicated number?
+- **Shared number** — your personal WhatsApp (bot prefixes messages with its name)
+- **Dedicated number** — a separate phone/SIM for the assistant
+
+If dedicated, add to `.env`:
+
+```bash
+ASSISTANT_HAS_OWN_NUMBER=true
+```
+
+## Next Steps
+
+If you're in the middle of `/setup`, return to the setup flow now.
+
+Otherwise, run `/manage-channels` to wire this channel to an agent group.
+
+## Channel Info
+
+- **type**: `whatsapp`
+- **terminology**: WhatsApp calls them "groups" and "chats." A "chat" is a 1:1 DM; a "group" has multiple members.
+- **how-to-find-id**: DMs use `<phone>@s.whatsapp.net` (e.g. `14155551234@s.whatsapp.net`). Groups use `<id>@g.us`. To find your number: `node -e "const c=JSON.parse(require('fs').readFileSync('store/auth/creds.json','utf-8'));console.log(c.me?.id?.split(':')[0]+'@s.whatsapp.net')"`. Groups are auto-discovered — check `sqlite3 data/v2.db "SELECT platform_id, name FROM messaging_groups WHERE channel_type='whatsapp' AND is_group=1"`.
+- **supports-threads**: no
+- **typical-use**: Interactive chat — direct messages or small groups
+- **default-isolation**: Same agent group if you're the only participant across multiple chats. Separate agent group if different people are in different groups.
+
+### Features
+
+- Markdown formatting — `**bold**`→`*bold*`, `*italic*`→`_italic_`, headings→bold, code blocks preserved
+- Approval questions — `ask_user_question` renders with `/approve`, `/reject` slash commands
+- File attachments — send and receive images, video, audio, documents
+- Reactions — send emoji reactions on messages
+- Typing indicators — composing presence updates
+- Credential requests — text fallback (WhatsApp has no modal support)
+
+Not supported (WhatsApp linked device limitation): edit messages, delete messages.
+
+## Troubleshooting
+
+### QR code expired
+
+QR codes expire after ~60 seconds. Re-run the auth command:
+
+```bash
+rm -rf store/auth/ && pnpm exec tsx setup/index.ts --step whatsapp-auth -- --method qr-browser
+```
+
+### Pairing code not working
+
+Codes expire in ~60 seconds. Delete auth and retry:
+
+```bash
+rm -rf store/auth/ && pnpm exec tsx setup/index.ts --step whatsapp-auth -- --method pairing-code --phone <phone>
+```
+
+Ensure: digits only (no `+`), phone has internet, WhatsApp is updated.
+
+If pairing code keeps failing, switch to QR-browser auth instead:
+
+```bash
+rm -rf store/auth/ && pnpm exec tsx setup/index.ts --step whatsapp-auth -- --method qr-browser
+```
+
+### "waiting for this message" on reactions
+
+Signal sessions corrupted from rapid restarts. Clear sessions:
+
+```bash
+systemctl --user stop nanoclaw
+rm store/auth/session-*.json
+systemctl --user start nanoclaw
+```
+
+### Bot not responding
+
+1. Auth exists: `test -f store/auth/creds.json`
+2. Connected: `grep "Connected to WhatsApp" logs/nanoclaw.log | tail -1`
+3. Channel wired: `sqlite3 data/v2.db "SELECT mg.platform_id, mg.name FROM messaging_groups mg JOIN messaging_group_agents mga ON mg.id=mga.messaging_group_id WHERE mg.channel_type='whatsapp'"`
+4. Service running: `systemctl --user status nanoclaw`
+
+### "conflict" disconnection
+
+Two instances connected with same credentials. Ensure only one NanoClaw process is running.

.claude/skills/add-whatsapp/SKILL.md

@@ -40,41 +40,56 @@ Otherwise (macOS, desktop Linux, or WSL) → AskUserQuestion: How do you want to
 
 If they chose pairing code:
 
-AskUserQuestion: What is your phone number? (Include country code without +, e.g., 1234567890)
+AskUserQuestion: What is your phone number? (Digits only — country code followed by your 10-digit number, no + prefix, spaces, or dashes. Example: 14155551234 where 1 is the US country code and 4155551234 is the phone number.)
 
-## Phase 2: Verify Code
+## Phase 2: Apply Code Changes
 
-Apply the skill to install the WhatsApp channel code and dependencies:
+Check if `src/channels/whatsapp.ts` already exists. If it does, skip to Phase 3 (Authentication).
+
+### Ensure channel remote
 
 ```bash
-npx tsx scripts/apply-skill.ts .claude/skills/add-whatsapp
+git remote -v
 ```
 
-Verify the code was placed correctly:
+If `whatsapp` is missing, add it:
 
 ```bash
-test -f src/channels/whatsapp.ts && echo "WhatsApp channel code present" || echo "ERROR: WhatsApp channel code missing — re-run skill apply"
+git remote add whatsapp https://github.com/qwibitai/nanoclaw-whatsapp.git
 ```
 
-### Verify dependencies
+### Merge the skill branch
 
 ```bash
-node -e "require('@whiskeysockets/baileys')" 2>/dev/null && echo "Baileys installed" || echo "Installing Baileys..."
+git fetch whatsapp main
+git merge whatsapp/main || {
+  git checkout --theirs pnpm-lock.yaml
+  git add pnpm-lock.yaml
+  git merge --continue
+}
 ```
 
-If not installed:
+This merges in:
+- `src/channels/whatsapp.ts` (WhatsAppChannel class with self-registration via `registerChannel`)
+- `src/channels/whatsapp.test.ts` (41 unit tests)
+- `src/whatsapp-auth.ts` (standalone WhatsApp authentication script)
+- `setup/whatsapp-auth.ts` (WhatsApp auth setup step)
+- `import './whatsapp.js'` appended to the channel barrel file `src/channels/index.ts`
+- `'whatsapp-auth'` step added to `setup/index.ts`
+- `@whiskeysockets/baileys`, `qrcode`, `qrcode-terminal` npm dependencies in `package.json`
+- `ASSISTANT_HAS_OWN_NUMBER` in `.env.example`
+
+If the merge reports conflicts, resolve them by reading the conflicted files and understanding the intent of both sides.
+
+### Validate code changes
 
 ```bash
-npm install @whiskeysockets/baileys qrcode qrcode-terminal
+pnpm install
+pnpm run build
+pnpm exec vitest run src/channels/whatsapp.test.ts
 ```
 
-### Validate build
-
-```bash
-npm run build
-```
-
-Build must be clean before proceeding.
+All tests must pass and build must be clean before proceeding.
 
 ## Phase 3: Authentication
 
@@ -89,7 +104,7 @@ rm -rf store/auth/
 For QR code in browser (recommended):
 
 ```bash
-npx tsx setup/index.ts --step whatsapp-auth -- --method qr-browser
+pnpm exec tsx setup/index.ts --step whatsapp-auth -- --method qr-browser
 ```
 
 (Bash timeout: 150000ms)
@@ -105,31 +120,43 @@ Tell the user:
 For QR code in terminal:
 
 ```bash
-npx tsx setup/index.ts --step whatsapp-auth -- --method qr-terminal
+pnpm exec tsx setup/index.ts --step whatsapp-auth -- --method qr-terminal
 ```
 
-Tell the user to run `npm run auth` in another terminal, then:
+Tell the user to run `pnpm run auth` in another terminal, then:
 
 > 1. Open WhatsApp > **Settings** > **Linked Devices** > **Link a Device**
 > 2. Scan the QR code displayed in the terminal
 
 For pairing code:
 
+Tell the user to have WhatsApp open on **Settings > Linked Devices > Link a Device**, ready to tap **"Link with phone number instead"** — the code expires in ~60 seconds and must be entered immediately.
+
+Run the auth process in the background and poll `store/pairing-code.txt` for the code:
+
 ```bash
-npx tsx setup/index.ts --step whatsapp-auth -- --method pairing-code --phone <their-phone-number>
+rm -f store/pairing-code.txt && pnpm exec tsx setup/index.ts --step whatsapp-auth -- --method pairing-code --phone <their-phone-number> > /tmp/wa-auth.log 2>&1 &
 ```
 
-(Bash timeout: 150000ms). Display PAIRING_CODE from output.
+Then immediately poll for the code (do NOT wait for the background command to finish):
 
-Tell the user:
+```bash
+for i in $(seq 1 20); do [ -f store/pairing-code.txt ] && cat store/pairing-code.txt && break; sleep 1; done
+```
 
-> A pairing code will appear. **Enter it within 60 seconds** — codes expire quickly.
+Display the code to the user the moment it appears. Tell them:
+
+> **Enter this code now** — it expires in ~60 seconds.
 >
 > 1. Open WhatsApp > **Settings** > **Linked Devices** > **Link a Device**
 > 2. Tap **Link with phone number instead**
 > 3. Enter the code immediately
->
-> If the code expires, re-run the command — a new code will be generated.
+
+After the user enters the code, poll for authentication to complete:
+
+```bash
+for i in $(seq 1 60); do grep -q 'AUTH_STATUS: authenticated' /tmp/wa-auth.log 2>/dev/null && echo "authenticated" && break; grep -q 'AUTH_STATUS: failed' /tmp/wa-auth.log 2>/dev/null && echo "failed" && break; sleep 2; done
+```
 
 **If failed:** qr_timeout → re-run. logged_out → delete `store/auth/` and re-run. 515 → re-run. timeout → ask user, offer retry.
 
@@ -194,8 +221,8 @@ node -e "const c=JSON.parse(require('fs').readFileSync('store/auth/creds.json','
 **Group (solo, existing):** Run group sync and list available groups:
 
 ```bash
-npx tsx setup/index.ts --step groups
-npx tsx setup/index.ts --step groups --list
+pnpm exec tsx setup/index.ts --step groups
+pnpm exec tsx setup/index.ts --step groups --list
 ```
 
 The output shows `JID|GroupName` pairs. Present candidates as AskUserQuestion (names only, not JIDs).
@@ -203,7 +230,7 @@ The output shows `JID|GroupName` pairs. Present candidates as AskUserQuestion (n
 ### Register the chat
 
 ```bash
-npx tsx setup/index.ts --step register \
+pnpm exec tsx setup/index.ts --step register \
   --jid "<jid>" \
   --name "<chat-name>" \
   --trigger "@<trigger>" \
@@ -217,7 +244,7 @@ npx tsx setup/index.ts --step register \
 For additional groups (trigger-required):
 
 ```bash
-npx tsx setup/index.ts --step register \
+pnpm exec tsx setup/index.ts --step register \
   --jid "<group-jid>" \
   --name "<group-name>" \
   --trigger "@<trigger>" \
@@ -230,7 +257,7 @@ npx tsx setup/index.ts --step register \
 ### Build and restart
 
 ```bash
-npm run build
+pnpm run build
 ```
 
 Restart the service:
@@ -269,7 +296,7 @@ tail -f logs/nanoclaw.log
 QR codes expire after ~60 seconds. Re-run the auth command:
 
 ```bash
-rm -rf store/auth/ && npx tsx src/whatsapp-auth.ts
+rm -rf store/auth/ && pnpm exec tsx src/whatsapp-auth.ts
 ```
 
 ### Pairing code not working
@@ -277,18 +304,18 @@ rm -rf store/auth/ && npx tsx src/whatsapp-auth.ts
 Codes expire in ~60 seconds. To retry:
 
 ```bash
-rm -rf store/auth/ && npx tsx src/whatsapp-auth.ts --pairing-code --phone <phone>
+rm -rf store/auth/ && pnpm exec tsx src/whatsapp-auth.ts --pairing-code --phone <phone>
 ```
 
 Enter the code **immediately** when it appears. Also ensure:
-1. Phone number includes country code without `+` (e.g., `1234567890`)
+1. Phone number is digits only — country code + number, no `+` prefix (e.g., `14155551234` where `1` is country code, `4155551234` is the number)
 2. Phone has internet access
 3. WhatsApp is updated to the latest version
 
 If pairing code keeps failing, switch to QR-browser auth instead:
 
 ```bash
-rm -rf store/auth/ && npx tsx setup/index.ts --step whatsapp-auth -- --method qr-browser
+rm -rf store/auth/ && pnpm exec tsx setup/index.ts --step whatsapp-auth -- --method qr-browser
 ```
 
 ### "conflict" disconnection
@@ -313,25 +340,25 @@ Check:
 Run group metadata sync:
 
 ```bash
-npx tsx setup/index.ts --step groups
+pnpm exec tsx setup/index.ts --step groups
 ```
 
 This fetches all group names from WhatsApp. Runs automatically every 24 hours.
 
 ## After Setup
 
-If running `npm run dev` while the service is active:
+If running `pnpm run dev` while the service is active:
 
 ```bash
 # macOS:
 launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
-npm run dev
+pnpm run dev
 # When done testing:
 launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
 
 # Linux:
 # systemctl --user stop nanoclaw
-# npm run dev
+# pnpm run dev
 # systemctl --user start nanoclaw
 ```
 
@@ -342,4 +369,4 @@ To remove WhatsApp integration:
 1. Delete auth credentials: `rm -rf store/auth/`
 2. Remove WhatsApp registrations: `sqlite3 store/messages.db "DELETE FROM registered_groups WHERE jid LIKE '%@g.us' OR jid LIKE '%@s.whatsapp.net'"`
 3. Sync env: `mkdir -p data/env && cp .env data/env/env`
-4. Rebuild and restart: `npm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw` (macOS) or `npm run build && systemctl --user restart nanoclaw` (Linux)
+4. Rebuild and restart: `pnpm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw` (macOS) or `pnpm run build && systemctl --user restart nanoclaw` (Linux)

.claude/skills/add-whatsapp/add/setup/whatsapp-auth.ts

@@ -1,358 +0,0 @@
-/**
- * Step: whatsapp-auth — WhatsApp interactive auth (QR code / pairing code).
- */
-import { execSync, spawn } from 'child_process';
-import fs from 'fs';
-import path from 'path';
-
-import { logger } from '../src/logger.js';
-import { openBrowser, isHeadless } from './platform.js';
-import { emitStatus } from './status.js';
-
-const QR_AUTH_TEMPLATE = `<!DOCTYPE html>
-<html><head><title>NanoClaw - WhatsApp Auth</title>
-<meta http-equiv="refresh" content="3">
-<style>
-  body { font-family: -apple-system, sans-serif; display: flex; flex-direction: column; align-items: center; justify-content: center; min-height: 100vh; margin: 0; background: #f5f5f5; }
-  .card { background: white; border-radius: 16px; padding: 40px; box-shadow: 0 4px 24px rgba(0,0,0,0.1); text-align: center; max-width: 400px; }
-  h2 { margin: 0 0 8px; }
-  .timer { font-size: 18px; color: #666; margin: 12px 0; }
-  .timer.urgent { color: #e74c3c; font-weight: bold; }
-  .instructions { color: #666; font-size: 14px; margin-top: 16px; }
-  svg { width: 280px; height: 280px; }
-</style></head><body>
-<div class="card">
-  <h2>Scan with WhatsApp</h2>
-  <div class="timer" id="timer">Expires in <span id="countdown">60</span>s</div>
-  <div id="qr">{{QR_SVG}}</div>
-  <div class="instructions">Settings \\u2192 Linked Devices \\u2192 Link a Device</div>
-</div>
-<script>
-  var startKey = 'nanoclaw_qr_start';
-  var start = localStorage.getItem(startKey);
-  if (!start) { start = Date.now().toString(); localStorage.setItem(startKey, start); }
-  var elapsed = Math.floor((Date.now() - parseInt(start)) / 1000);
-  var remaining = Math.max(0, 60 - elapsed);
-  var countdown = document.getElementById('countdown');
-  var timer = document.getElementById('timer');
-  countdown.textContent = remaining;
-  if (remaining <= 10) timer.classList.add('urgent');
-  if (remaining <= 0) {
-    timer.textContent = 'QR code expired \\u2014 a new one will appear shortly';
-    timer.classList.add('urgent');
-    localStorage.removeItem(startKey);
-  }
-</script></body></html>`;
-
-const SUCCESS_HTML = `<!DOCTYPE html>
-<html><head><title>NanoClaw - Connected!</title>
-<style>
-  body { font-family: -apple-system, sans-serif; display: flex; align-items: center; justify-content: center; min-height: 100vh; margin: 0; background: #f5f5f5; }
-  .card { background: white; border-radius: 16px; padding: 40px; box-shadow: 0 4px 24px rgba(0,0,0,0.1); text-align: center; max-width: 400px; }
-  h2 { color: #27ae60; margin: 0 0 8px; }
-  p { color: #666; }
-  .check { font-size: 64px; margin-bottom: 16px; }
-</style></head><body>
-<div class="card">
-  <div class="check">&#10003;</div>
-  <h2>Connected to WhatsApp</h2>
-  <p>You can close this tab.</p>
-</div>
-<script>localStorage.removeItem('nanoclaw_qr_start');</script>
-</body></html>`;
-
-function parseArgs(args: string[]): { method: string; phone: string } {
-  let method = '';
-  let phone = '';
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--method' && args[i + 1]) {
-      method = args[i + 1];
-      i++;
-    }
-    if (args[i] === '--phone' && args[i + 1]) {
-      phone = args[i + 1];
-      i++;
-    }
-  }
-  return { method, phone };
-}
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-function readFileSafe(filePath: string): string {
-  try {
-    return fs.readFileSync(filePath, 'utf-8');
-  } catch {
-    return '';
-  }
-}
-
-function getPhoneNumber(projectRoot: string): string {
-  try {
-    const creds = JSON.parse(
-      fs.readFileSync(
-        path.join(projectRoot, 'store', 'auth', 'creds.json'),
-        'utf-8',
-      ),
-    );
-    if (creds.me?.id) {
-      return creds.me.id.split(':')[0].split('@')[0];
-    }
-  } catch {
-    // Not available yet
-  }
-  return '';
-}
-
-function emitAuthStatus(
-  method: string,
-  authStatus: string,
-  status: string,
-  extra: Record<string, string> = {},
-): void {
-  const fields: Record<string, string> = {
-    AUTH_METHOD: method,
-    AUTH_STATUS: authStatus,
-    ...extra,
-    STATUS: status,
-    LOG: 'logs/setup.log',
-  };
-  emitStatus('AUTH_WHATSAPP', fields);
-}
-
-export async function run(args: string[]): Promise<void> {
-  const projectRoot = process.cwd();
-
-  const { method, phone } = parseArgs(args);
-  const statusFile = path.join(projectRoot, 'store', 'auth-status.txt');
-  const qrFile = path.join(projectRoot, 'store', 'qr-data.txt');
-
-  if (!method) {
-    emitAuthStatus('unknown', 'failed', 'failed', {
-      ERROR: 'missing_method_flag',
-    });
-    process.exit(4);
-  }
-
-  // qr-terminal is a manual flow
-  if (method === 'qr-terminal') {
-    emitAuthStatus('qr-terminal', 'manual', 'manual', {
-      PROJECT_PATH: projectRoot,
-    });
-    return;
-  }
-
-  if (method === 'pairing-code' && !phone) {
-    emitAuthStatus('pairing-code', 'failed', 'failed', {
-      ERROR: 'missing_phone_number',
-    });
-    process.exit(4);
-  }
-
-  if (!['qr-browser', 'pairing-code'].includes(method)) {
-    emitAuthStatus(method, 'failed', 'failed', { ERROR: 'unknown_method' });
-    process.exit(4);
-  }
-
-  // Clean stale state
-  logger.info({ method }, 'Starting channel authentication');
-  try {
-    fs.rmSync(path.join(projectRoot, 'store', 'auth'), {
-      recursive: true,
-      force: true,
-    });
-  } catch {
-    /* ok */
-  }
-  try {
-    fs.unlinkSync(qrFile);
-  } catch {
-    /* ok */
-  }
-  try {
-    fs.unlinkSync(statusFile);
-  } catch {
-    /* ok */
-  }
-
-  // Start auth process in background
-  const authArgs =
-    method === 'pairing-code'
-      ? ['src/whatsapp-auth.ts', '--pairing-code', '--phone', phone]
-      : ['src/whatsapp-auth.ts'];
-
-  const authProc = spawn('npx', ['tsx', ...authArgs], {
-    cwd: projectRoot,
-    stdio: ['ignore', 'pipe', 'pipe'],
-    detached: false,
-  });
-
-  const logFile = path.join(projectRoot, 'logs', 'setup.log');
-  const logStream = fs.createWriteStream(logFile, { flags: 'a' });
-  authProc.stdout?.pipe(logStream);
-  authProc.stderr?.pipe(logStream);
-
-  // Cleanup on exit
-  const cleanup = () => {
-    try {
-      authProc.kill();
-    } catch {
-      /* ok */
-    }
-  };
-  process.on('exit', cleanup);
-
-  try {
-    if (method === 'qr-browser') {
-      await handleQrBrowser(projectRoot, statusFile, qrFile);
-    } else {
-      await handlePairingCode(projectRoot, statusFile, phone);
-    }
-  } finally {
-    cleanup();
-    process.removeListener('exit', cleanup);
-  }
-}
-
-async function handleQrBrowser(
-  projectRoot: string,
-  statusFile: string,
-  qrFile: string,
-): Promise<void> {
-  // Poll for QR data (15s)
-  let qrReady = false;
-  for (let i = 0; i < 15; i++) {
-    const statusContent = readFileSafe(statusFile);
-    if (statusContent === 'already_authenticated') {
-      emitAuthStatus('qr-browser', 'already_authenticated', 'success');
-      return;
-    }
-    if (fs.existsSync(qrFile)) {
-      qrReady = true;
-      break;
-    }
-    await sleep(1000);
-  }
-
-  if (!qrReady) {
-    emitAuthStatus('qr-browser', 'failed', 'failed', { ERROR: 'qr_timeout' });
-    process.exit(3);
-  }
-
-  // Generate QR SVG and HTML
-  const qrData = fs.readFileSync(qrFile, 'utf-8');
-  try {
-    const svg = execSync(
-      `node -e "const QR=require('qrcode');const data='${qrData}';QR.toString(data,{type:'svg'},(e,s)=>{if(e)process.exit(1);process.stdout.write(s)})"`,
-      { cwd: projectRoot, encoding: 'utf-8' },
-    );
-    const html = QR_AUTH_TEMPLATE.replace('{{QR_SVG}}', svg);
-    const htmlPath = path.join(projectRoot, 'store', 'qr-auth.html');
-    fs.writeFileSync(htmlPath, html);
-
-    // Open in browser (cross-platform)
-    if (!isHeadless()) {
-      const opened = openBrowser(htmlPath);
-      if (!opened) {
-        logger.warn(
-          'Could not open browser — display QR in terminal as fallback',
-        );
-      }
-    } else {
-      logger.info(
-        'Headless environment — QR HTML saved but browser not opened',
-      );
-    }
-  } catch (err) {
-    logger.error({ err }, 'Failed to generate QR HTML');
-  }
-
-  // Poll for completion (120s)
-  await pollAuthCompletion('qr-browser', statusFile, projectRoot);
-}
-
-async function handlePairingCode(
-  projectRoot: string,
-  statusFile: string,
-  phone: string,
-): Promise<void> {
-  // Poll for pairing code (15s)
-  let pairingCode = '';
-  for (let i = 0; i < 15; i++) {
-    const statusContent = readFileSafe(statusFile);
-    if (statusContent === 'already_authenticated') {
-      emitAuthStatus('pairing-code', 'already_authenticated', 'success');
-      return;
-    }
-    if (statusContent.startsWith('pairing_code:')) {
-      pairingCode = statusContent.replace('pairing_code:', '');
-      break;
-    }
-    if (statusContent.startsWith('failed:')) {
-      emitAuthStatus('pairing-code', 'failed', 'failed', {
-        ERROR: statusContent.replace('failed:', ''),
-      });
-      process.exit(1);
-    }
-    await sleep(1000);
-  }
-
-  if (!pairingCode) {
-    emitAuthStatus('pairing-code', 'failed', 'failed', {
-      ERROR: 'pairing_code_timeout',
-    });
-    process.exit(3);
-  }
-
-  // Emit pairing code immediately so the caller can display it to the user
-  emitAuthStatus('pairing-code', 'pairing_code_ready', 'waiting', {
-    PAIRING_CODE: pairingCode,
-  });
-
-  // Poll for completion (120s)
-  await pollAuthCompletion(
-    'pairing-code',
-    statusFile,
-    projectRoot,
-    pairingCode,
-  );
-}
-
-async function pollAuthCompletion(
-  method: string,
-  statusFile: string,
-  projectRoot: string,
-  pairingCode?: string,
-): Promise<void> {
-  const extra: Record<string, string> = {};
-  if (pairingCode) extra.PAIRING_CODE = pairingCode;
-
-  for (let i = 0; i < 60; i++) {
-    const content = readFileSafe(statusFile);
-
-    if (content === 'authenticated' || content === 'already_authenticated') {
-      // Write success page if qr-auth.html exists
-      const htmlPath = path.join(projectRoot, 'store', 'qr-auth.html');
-      if (fs.existsSync(htmlPath)) {
-        fs.writeFileSync(htmlPath, SUCCESS_HTML);
-      }
-      const phoneNumber = getPhoneNumber(projectRoot);
-      if (phoneNumber) extra.PHONE_NUMBER = phoneNumber;
-      emitAuthStatus(method, content, 'success', extra);
-      return;
-    }
-
-    if (content.startsWith('failed:')) {
-      const error = content.replace('failed:', '');
-      emitAuthStatus(method, 'failed', 'failed', { ERROR: error, ...extra });
-      process.exit(1);
-    }
-
-    await sleep(2000);
-  }
-
-  emitAuthStatus(method, 'failed', 'failed', { ERROR: 'timeout', ...extra });
-  process.exit(3);
-}

.claude/skills/add-whatsapp/add/src/channels/whatsapp.test.ts

@@ -1,950 +0,0 @@
-import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
-import { EventEmitter } from 'events';
-
-// --- Mocks ---
-
-// Mock config
-vi.mock('../config.js', () => ({
-  STORE_DIR: '/tmp/nanoclaw-test-store',
-  ASSISTANT_NAME: 'Andy',
-  ASSISTANT_HAS_OWN_NUMBER: false,
-}));
-
-// Mock logger
-vi.mock('../logger.js', () => ({
-  logger: {
-    debug: vi.fn(),
-    info: vi.fn(),
-    warn: vi.fn(),
-    error: vi.fn(),
-  },
-}));
-
-// Mock db
-vi.mock('../db.js', () => ({
-  getLastGroupSync: vi.fn(() => null),
-  setLastGroupSync: vi.fn(),
-  updateChatName: vi.fn(),
-}));
-
-// Mock fs
-vi.mock('fs', async () => {
-  const actual = await vi.importActual<typeof import('fs')>('fs');
-  return {
-    ...actual,
-    default: {
-      ...actual,
-      existsSync: vi.fn(() => true),
-      mkdirSync: vi.fn(),
-    },
-  };
-});
-
-// Mock child_process (used for osascript notification)
-vi.mock('child_process', () => ({
-  exec: vi.fn(),
-}));
-
-// Build a fake WASocket that's an EventEmitter with the methods we need
-function createFakeSocket() {
-  const ev = new EventEmitter();
-  const sock = {
-    ev: {
-      on: (event: string, handler: (...args: unknown[]) => void) => {
-        ev.on(event, handler);
-      },
-    },
-    user: {
-      id: '1234567890:1@s.whatsapp.net',
-      lid: '9876543210:1@lid',
-    },
-    sendMessage: vi.fn().mockResolvedValue(undefined),
-    sendPresenceUpdate: vi.fn().mockResolvedValue(undefined),
-    groupFetchAllParticipating: vi.fn().mockResolvedValue({}),
-    end: vi.fn(),
-    // Expose the event emitter for triggering events in tests
-    _ev: ev,
-  };
-  return sock;
-}
-
-let fakeSocket: ReturnType<typeof createFakeSocket>;
-
-// Mock Baileys
-vi.mock('@whiskeysockets/baileys', () => {
-  return {
-    default: vi.fn(() => fakeSocket),
-    Browsers: { macOS: vi.fn(() => ['macOS', 'Chrome', '']) },
-    DisconnectReason: {
-      loggedOut: 401,
-      badSession: 500,
-      connectionClosed: 428,
-      connectionLost: 408,
-      connectionReplaced: 440,
-      timedOut: 408,
-      restartRequired: 515,
-    },
-    fetchLatestWaWebVersion: vi
-      .fn()
-      .mockResolvedValue({ version: [2, 3000, 0] }),
-    normalizeMessageContent: vi.fn((content: unknown) => content),
-    makeCacheableSignalKeyStore: vi.fn((keys: unknown) => keys),
-    useMultiFileAuthState: vi.fn().mockResolvedValue({
-      state: {
-        creds: {},
-        keys: {},
-      },
-      saveCreds: vi.fn(),
-    }),
-  };
-});
-
-import { WhatsAppChannel, WhatsAppChannelOpts } from './whatsapp.js';
-import { getLastGroupSync, updateChatName, setLastGroupSync } from '../db.js';
-
-// --- Test helpers ---
-
-function createTestOpts(
-  overrides?: Partial<WhatsAppChannelOpts>,
-): WhatsAppChannelOpts {
-  return {
-    onMessage: vi.fn(),
-    onChatMetadata: vi.fn(),
-    registeredGroups: vi.fn(() => ({
-      'registered@g.us': {
-        name: 'Test Group',
-        folder: 'test-group',
-        trigger: '@Andy',
-        added_at: '2024-01-01T00:00:00.000Z',
-      },
-    })),
-    ...overrides,
-  };
-}
-
-function triggerConnection(state: string, extra?: Record<string, unknown>) {
-  fakeSocket._ev.emit('connection.update', { connection: state, ...extra });
-}
-
-function triggerDisconnect(statusCode: number) {
-  fakeSocket._ev.emit('connection.update', {
-    connection: 'close',
-    lastDisconnect: {
-      error: { output: { statusCode } },
-    },
-  });
-}
-
-async function triggerMessages(messages: unknown[]) {
-  fakeSocket._ev.emit('messages.upsert', { messages });
-  // Flush microtasks so the async messages.upsert handler completes
-  await new Promise((r) => setTimeout(r, 0));
-}
-
-// --- Tests ---
-
-describe('WhatsAppChannel', () => {
-  beforeEach(() => {
-    fakeSocket = createFakeSocket();
-    vi.mocked(getLastGroupSync).mockReturnValue(null);
-  });
-
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  /**
-   * Helper: start connect, flush microtasks so event handlers are registered,
-   * then trigger the connection open event. Returns the resolved promise.
-   */
-  async function connectChannel(channel: WhatsAppChannel): Promise<void> {
-    const p = channel.connect();
-    // Flush microtasks so connectInternal completes its await and registers handlers
-    await new Promise((r) => setTimeout(r, 0));
-    triggerConnection('open');
-    return p;
-  }
-
-  // --- Version fetch ---
-
-  describe('version fetch', () => {
-    it('connects with fetched version', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-      await connectChannel(channel);
-
-      const { fetchLatestWaWebVersion } =
-        await import('@whiskeysockets/baileys');
-      expect(fetchLatestWaWebVersion).toHaveBeenCalledWith({});
-    });
-
-    it('falls back gracefully when version fetch fails', async () => {
-      const { fetchLatestWaWebVersion } =
-        await import('@whiskeysockets/baileys');
-      vi.mocked(fetchLatestWaWebVersion).mockRejectedValueOnce(
-        new Error('network error'),
-      );
-
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-      await connectChannel(channel);
-
-      // Should still connect successfully despite fetch failure
-      expect(channel.isConnected()).toBe(true);
-    });
-  });
-
-  // --- Connection lifecycle ---
-
-  describe('connection lifecycle', () => {
-    it('resolves connect() when connection opens', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      expect(channel.isConnected()).toBe(true);
-    });
-
-    it('sets up LID to phone mapping on open', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      // The channel should have mapped the LID from sock.user
-      // We can verify by sending a message from a LID JID
-      // and checking the translated JID in the callback
-    });
-
-    it('flushes outgoing queue on reconnect', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      // Disconnect
-      (channel as any).connected = false;
-
-      // Queue a message while disconnected
-      await channel.sendMessage('test@g.us', 'Queued message');
-      expect(fakeSocket.sendMessage).not.toHaveBeenCalled();
-
-      // Reconnect
-      (channel as any).connected = true;
-      await (channel as any).flushOutgoingQueue();
-
-      // Group messages get prefixed when flushed
-      expect(fakeSocket.sendMessage).toHaveBeenCalledWith('test@g.us', {
-        text: 'Andy: Queued message',
-      });
-    });
-
-    it('disconnects cleanly', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await channel.disconnect();
-      expect(channel.isConnected()).toBe(false);
-      expect(fakeSocket.end).toHaveBeenCalled();
-    });
-  });
-
-  // --- QR code and auth ---
-
-  describe('authentication', () => {
-    it('exits process when QR code is emitted (no auth state)', async () => {
-      vi.useFakeTimers();
-      const mockExit = vi
-        .spyOn(process, 'exit')
-        .mockImplementation(() => undefined as never);
-
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      // Start connect but don't await (it won't resolve - process exits)
-      channel.connect().catch(() => {});
-
-      // Flush microtasks so connectInternal registers handlers
-      await vi.advanceTimersByTimeAsync(0);
-
-      // Emit QR code event
-      fakeSocket._ev.emit('connection.update', { qr: 'some-qr-data' });
-
-      // Advance timer past the 1000ms setTimeout before exit
-      await vi.advanceTimersByTimeAsync(1500);
-
-      expect(mockExit).toHaveBeenCalledWith(1);
-      mockExit.mockRestore();
-      vi.useRealTimers();
-    });
-  });
-
-  // --- Reconnection behavior ---
-
-  describe('reconnection', () => {
-    it('reconnects on non-loggedOut disconnect', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      expect(channel.isConnected()).toBe(true);
-
-      // Disconnect with a non-loggedOut reason (e.g., connectionClosed = 428)
-      triggerDisconnect(428);
-
-      expect(channel.isConnected()).toBe(false);
-      // The channel should attempt to reconnect (calls connectInternal again)
-    });
-
-    it('exits on loggedOut disconnect', async () => {
-      const mockExit = vi
-        .spyOn(process, 'exit')
-        .mockImplementation(() => undefined as never);
-
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      // Disconnect with loggedOut reason (401)
-      triggerDisconnect(401);
-
-      expect(channel.isConnected()).toBe(false);
-      expect(mockExit).toHaveBeenCalledWith(0);
-      mockExit.mockRestore();
-    });
-
-    it('retries reconnection after 5s on failure', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      // Disconnect with stream error 515
-      triggerDisconnect(515);
-
-      // The channel sets a 5s retry — just verify it doesn't crash
-      await new Promise((r) => setTimeout(r, 100));
-    });
-  });
-
-  // --- Message handling ---
-
-  describe('message handling', () => {
-    it('delivers message for registered group', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-1',
-            remoteJid: 'registered@g.us',
-            participant: '5551234@s.whatsapp.net',
-            fromMe: false,
-          },
-          message: { conversation: 'Hello Andy' },
-          pushName: 'Alice',
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      expect(opts.onChatMetadata).toHaveBeenCalledWith(
-        'registered@g.us',
-        expect.any(String),
-        undefined,
-        'whatsapp',
-        true,
-      );
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'registered@g.us',
-        expect.objectContaining({
-          id: 'msg-1',
-          content: 'Hello Andy',
-          sender_name: 'Alice',
-          is_from_me: false,
-        }),
-      );
-    });
-
-    it('only emits metadata for unregistered groups', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-2',
-            remoteJid: 'unregistered@g.us',
-            participant: '5551234@s.whatsapp.net',
-            fromMe: false,
-          },
-          message: { conversation: 'Hello' },
-          pushName: 'Bob',
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      expect(opts.onChatMetadata).toHaveBeenCalledWith(
-        'unregistered@g.us',
-        expect.any(String),
-        undefined,
-        'whatsapp',
-        true,
-      );
-      expect(opts.onMessage).not.toHaveBeenCalled();
-    });
-
-    it('ignores status@broadcast messages', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-3',
-            remoteJid: 'status@broadcast',
-            fromMe: false,
-          },
-          message: { conversation: 'Status update' },
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      expect(opts.onChatMetadata).not.toHaveBeenCalled();
-      expect(opts.onMessage).not.toHaveBeenCalled();
-    });
-
-    it('ignores messages with no content', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-4',
-            remoteJid: 'registered@g.us',
-            fromMe: false,
-          },
-          message: null,
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      expect(opts.onMessage).not.toHaveBeenCalled();
-    });
-
-    it('extracts text from extendedTextMessage', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-5',
-            remoteJid: 'registered@g.us',
-            participant: '5551234@s.whatsapp.net',
-            fromMe: false,
-          },
-          message: {
-            extendedTextMessage: { text: 'A reply message' },
-          },
-          pushName: 'Charlie',
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'registered@g.us',
-        expect.objectContaining({ content: 'A reply message' }),
-      );
-    });
-
-    it('extracts caption from imageMessage', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-6',
-            remoteJid: 'registered@g.us',
-            participant: '5551234@s.whatsapp.net',
-            fromMe: false,
-          },
-          message: {
-            imageMessage: {
-              caption: 'Check this photo',
-              mimetype: 'image/jpeg',
-            },
-          },
-          pushName: 'Diana',
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'registered@g.us',
-        expect.objectContaining({ content: 'Check this photo' }),
-      );
-    });
-
-    it('extracts caption from videoMessage', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-7',
-            remoteJid: 'registered@g.us',
-            participant: '5551234@s.whatsapp.net',
-            fromMe: false,
-          },
-          message: {
-            videoMessage: { caption: 'Watch this', mimetype: 'video/mp4' },
-          },
-          pushName: 'Eve',
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'registered@g.us',
-        expect.objectContaining({ content: 'Watch this' }),
-      );
-    });
-
-    it('handles message with no extractable text (e.g. voice note without caption)', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-8',
-            remoteJid: 'registered@g.us',
-            participant: '5551234@s.whatsapp.net',
-            fromMe: false,
-          },
-          message: {
-            audioMessage: { mimetype: 'audio/ogg; codecs=opus', ptt: true },
-          },
-          pushName: 'Frank',
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      // Skipped — no text content to process
-      expect(opts.onMessage).not.toHaveBeenCalled();
-    });
-
-    it('uses sender JID when pushName is absent', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-9',
-            remoteJid: 'registered@g.us',
-            participant: '5551234@s.whatsapp.net',
-            fromMe: false,
-          },
-          message: { conversation: 'No push name' },
-          // pushName is undefined
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      expect(opts.onMessage).toHaveBeenCalledWith(
-        'registered@g.us',
-        expect.objectContaining({ sender_name: '5551234' }),
-      );
-    });
-  });
-
-  // --- LID ↔ JID translation ---
-
-  describe('LID to JID translation', () => {
-    it('translates known LID to phone JID', async () => {
-      const opts = createTestOpts({
-        registeredGroups: vi.fn(() => ({
-          '1234567890@s.whatsapp.net': {
-            name: 'Self Chat',
-            folder: 'self-chat',
-            trigger: '@Andy',
-            added_at: '2024-01-01T00:00:00.000Z',
-          },
-        })),
-      });
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      // The socket has lid '9876543210:1@lid' → phone '1234567890@s.whatsapp.net'
-      // Send a message from the LID
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-lid',
-            remoteJid: '9876543210@lid',
-            fromMe: false,
-          },
-          message: { conversation: 'From LID' },
-          pushName: 'Self',
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      // Should be translated to phone JID
-      expect(opts.onChatMetadata).toHaveBeenCalledWith(
-        '1234567890@s.whatsapp.net',
-        expect.any(String),
-        undefined,
-        'whatsapp',
-        false,
-      );
-    });
-
-    it('passes through non-LID JIDs unchanged', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-normal',
-            remoteJid: 'registered@g.us',
-            participant: '5551234@s.whatsapp.net',
-            fromMe: false,
-          },
-          message: { conversation: 'Normal JID' },
-          pushName: 'Grace',
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      expect(opts.onChatMetadata).toHaveBeenCalledWith(
-        'registered@g.us',
-        expect.any(String),
-        undefined,
-        'whatsapp',
-        true,
-      );
-    });
-
-    it('passes through unknown LID JIDs unchanged', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await triggerMessages([
-        {
-          key: {
-            id: 'msg-unknown-lid',
-            remoteJid: '0000000000@lid',
-            fromMe: false,
-          },
-          message: { conversation: 'Unknown LID' },
-          pushName: 'Unknown',
-          messageTimestamp: Math.floor(Date.now() / 1000),
-        },
-      ]);
-
-      // Unknown LID passes through unchanged
-      expect(opts.onChatMetadata).toHaveBeenCalledWith(
-        '0000000000@lid',
-        expect.any(String),
-        undefined,
-        'whatsapp',
-        false,
-      );
-    });
-  });
-
-  // --- Outgoing message queue ---
-
-  describe('outgoing message queue', () => {
-    it('sends message directly when connected', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await channel.sendMessage('test@g.us', 'Hello');
-      // Group messages get prefixed with assistant name
-      expect(fakeSocket.sendMessage).toHaveBeenCalledWith('test@g.us', {
-        text: 'Andy: Hello',
-      });
-    });
-
-    it('prefixes direct chat messages on shared number', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await channel.sendMessage('123@s.whatsapp.net', 'Hello');
-      // Shared number: DMs also get prefixed (needed for self-chat distinction)
-      expect(fakeSocket.sendMessage).toHaveBeenCalledWith(
-        '123@s.whatsapp.net',
-        { text: 'Andy: Hello' },
-      );
-    });
-
-    it('queues message when disconnected', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      // Don't connect — channel starts disconnected
-      await channel.sendMessage('test@g.us', 'Queued');
-      expect(fakeSocket.sendMessage).not.toHaveBeenCalled();
-    });
-
-    it('queues message on send failure', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      // Make sendMessage fail
-      fakeSocket.sendMessage.mockRejectedValueOnce(new Error('Network error'));
-
-      await channel.sendMessage('test@g.us', 'Will fail');
-
-      // Should not throw, message queued for retry
-      // The queue should have the message
-    });
-
-    it('flushes multiple queued messages in order', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      // Queue messages while disconnected
-      await channel.sendMessage('test@g.us', 'First');
-      await channel.sendMessage('test@g.us', 'Second');
-      await channel.sendMessage('test@g.us', 'Third');
-
-      // Connect — flush happens automatically on open
-      await connectChannel(channel);
-
-      // Give the async flush time to complete
-      await new Promise((r) => setTimeout(r, 50));
-
-      expect(fakeSocket.sendMessage).toHaveBeenCalledTimes(3);
-      // Group messages get prefixed
-      expect(fakeSocket.sendMessage).toHaveBeenNthCalledWith(1, 'test@g.us', {
-        text: 'Andy: First',
-      });
-      expect(fakeSocket.sendMessage).toHaveBeenNthCalledWith(2, 'test@g.us', {
-        text: 'Andy: Second',
-      });
-      expect(fakeSocket.sendMessage).toHaveBeenNthCalledWith(3, 'test@g.us', {
-        text: 'Andy: Third',
-      });
-    });
-  });
-
-  // --- Group metadata sync ---
-
-  describe('group metadata sync', () => {
-    it('syncs group metadata on first connection', async () => {
-      fakeSocket.groupFetchAllParticipating.mockResolvedValue({
-        'group1@g.us': { subject: 'Group One' },
-        'group2@g.us': { subject: 'Group Two' },
-      });
-
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      // Wait for async sync to complete
-      await new Promise((r) => setTimeout(r, 50));
-
-      expect(fakeSocket.groupFetchAllParticipating).toHaveBeenCalled();
-      expect(updateChatName).toHaveBeenCalledWith('group1@g.us', 'Group One');
-      expect(updateChatName).toHaveBeenCalledWith('group2@g.us', 'Group Two');
-      expect(setLastGroupSync).toHaveBeenCalled();
-    });
-
-    it('skips sync when synced recently', async () => {
-      // Last sync was 1 hour ago (within 24h threshold)
-      vi.mocked(getLastGroupSync).mockReturnValue(
-        new Date(Date.now() - 60 * 60 * 1000).toISOString(),
-      );
-
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await new Promise((r) => setTimeout(r, 50));
-
-      expect(fakeSocket.groupFetchAllParticipating).not.toHaveBeenCalled();
-    });
-
-    it('forces sync regardless of cache', async () => {
-      vi.mocked(getLastGroupSync).mockReturnValue(
-        new Date(Date.now() - 60 * 60 * 1000).toISOString(),
-      );
-
-      fakeSocket.groupFetchAllParticipating.mockResolvedValue({
-        'group@g.us': { subject: 'Forced Group' },
-      });
-
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await channel.syncGroupMetadata(true);
-
-      expect(fakeSocket.groupFetchAllParticipating).toHaveBeenCalled();
-      expect(updateChatName).toHaveBeenCalledWith('group@g.us', 'Forced Group');
-    });
-
-    it('handles group sync failure gracefully', async () => {
-      fakeSocket.groupFetchAllParticipating.mockRejectedValue(
-        new Error('Network timeout'),
-      );
-
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      // Should not throw
-      await expect(channel.syncGroupMetadata(true)).resolves.toBeUndefined();
-    });
-
-    it('skips groups with no subject', async () => {
-      fakeSocket.groupFetchAllParticipating.mockResolvedValue({
-        'group1@g.us': { subject: 'Has Subject' },
-        'group2@g.us': { subject: '' },
-        'group3@g.us': {},
-      });
-
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      // Clear any calls from the automatic sync on connect
-      vi.mocked(updateChatName).mockClear();
-
-      await channel.syncGroupMetadata(true);
-
-      expect(updateChatName).toHaveBeenCalledTimes(1);
-      expect(updateChatName).toHaveBeenCalledWith('group1@g.us', 'Has Subject');
-    });
-  });
-
-  // --- JID ownership ---
-
-  describe('ownsJid', () => {
-    it('owns @g.us JIDs (WhatsApp groups)', () => {
-      const channel = new WhatsAppChannel(createTestOpts());
-      expect(channel.ownsJid('12345@g.us')).toBe(true);
-    });
-
-    it('owns @s.whatsapp.net JIDs (WhatsApp DMs)', () => {
-      const channel = new WhatsAppChannel(createTestOpts());
-      expect(channel.ownsJid('12345@s.whatsapp.net')).toBe(true);
-    });
-
-    it('does not own Telegram JIDs', () => {
-      const channel = new WhatsAppChannel(createTestOpts());
-      expect(channel.ownsJid('tg:12345')).toBe(false);
-    });
-
-    it('does not own unknown JID formats', () => {
-      const channel = new WhatsAppChannel(createTestOpts());
-      expect(channel.ownsJid('random-string')).toBe(false);
-    });
-  });
-
-  // --- Typing indicator ---
-
-  describe('setTyping', () => {
-    it('sends composing presence when typing', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await channel.setTyping('test@g.us', true);
-      expect(fakeSocket.sendPresenceUpdate).toHaveBeenCalledWith(
-        'composing',
-        'test@g.us',
-      );
-    });
-
-    it('sends paused presence when stopping', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      await channel.setTyping('test@g.us', false);
-      expect(fakeSocket.sendPresenceUpdate).toHaveBeenCalledWith(
-        'paused',
-        'test@g.us',
-      );
-    });
-
-    it('handles typing indicator failure gracefully', async () => {
-      const opts = createTestOpts();
-      const channel = new WhatsAppChannel(opts);
-
-      await connectChannel(channel);
-
-      fakeSocket.sendPresenceUpdate.mockRejectedValueOnce(new Error('Failed'));
-
-      // Should not throw
-      await expect(
-        channel.setTyping('test@g.us', true),
-      ).resolves.toBeUndefined();
-    });
-  });
-
-  // --- Channel properties ---
-
-  describe('channel properties', () => {
-    it('has name "whatsapp"', () => {
-      const channel = new WhatsAppChannel(createTestOpts());
-      expect(channel.name).toBe('whatsapp');
-    });
-
-    it('does not expose prefixAssistantName (prefix handled internally)', () => {
-      const channel = new WhatsAppChannel(createTestOpts());
-      expect('prefixAssistantName' in channel).toBe(false);
-    });
-  });
-});

.claude/skills/add-whatsapp/add/src/channels/whatsapp.ts

@@ -1,391 +0,0 @@
-import { exec } from 'child_process';
-import fs from 'fs';
-import path from 'path';
-
-import makeWASocket, {
-  Browsers,
-  DisconnectReason,
-  WASocket,
-  fetchLatestWaWebVersion,
-  makeCacheableSignalKeyStore,
-  normalizeMessageContent,
-  useMultiFileAuthState,
-} from '@whiskeysockets/baileys';
-
-import {
-  ASSISTANT_HAS_OWN_NUMBER,
-  ASSISTANT_NAME,
-  STORE_DIR,
-} from '../config.js';
-import { getLastGroupSync, setLastGroupSync, updateChatName } from '../db.js';
-import { logger } from '../logger.js';
-import {
-  Channel,
-  OnInboundMessage,
-  OnChatMetadata,
-  RegisteredGroup,
-} from '../types.js';
-import { registerChannel, ChannelOpts } from './registry.js';
-
-const GROUP_SYNC_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
-
-export interface WhatsAppChannelOpts {
-  onMessage: OnInboundMessage;
-  onChatMetadata: OnChatMetadata;
-  registeredGroups: () => Record<string, RegisteredGroup>;
-}
-
-export class WhatsAppChannel implements Channel {
-  name = 'whatsapp';
-
-  private sock!: WASocket;
-  private connected = false;
-  private lidToPhoneMap: Record<string, string> = {};
-  private outgoingQueue: Array<{ jid: string; text: string }> = [];
-  private flushing = false;
-  private groupSyncTimerStarted = false;
-
-  private opts: WhatsAppChannelOpts;
-
-  constructor(opts: WhatsAppChannelOpts) {
-    this.opts = opts;
-  }
-
-  async connect(): Promise<void> {
-    return new Promise<void>((resolve, reject) => {
-      this.connectInternal(resolve).catch(reject);
-    });
-  }
-
-  private async connectInternal(onFirstOpen?: () => void): Promise<void> {
-    const authDir = path.join(STORE_DIR, 'auth');
-    fs.mkdirSync(authDir, { recursive: true });
-
-    const { state, saveCreds } = await useMultiFileAuthState(authDir);
-
-    const { version } = await fetchLatestWaWebVersion({}).catch((err) => {
-      logger.warn(
-        { err },
-        'Failed to fetch latest WA Web version, using default',
-      );
-      return { version: undefined };
-    });
-    this.sock = makeWASocket({
-      version,
-      auth: {
-        creds: state.creds,
-        keys: makeCacheableSignalKeyStore(state.keys, logger),
-      },
-      printQRInTerminal: false,
-      logger,
-      browser: Browsers.macOS('Chrome'),
-    });
-
-    this.sock.ev.on('connection.update', (update) => {
-      const { connection, lastDisconnect, qr } = update;
-
-      if (qr) {
-        const msg =
-          'WhatsApp authentication required. Run /setup in Claude Code.';
-        logger.error(msg);
-        exec(
-          `osascript -e 'display notification "${msg}" with title "NanoClaw" sound name "Basso"'`,
-        );
-        setTimeout(() => process.exit(1), 1000);
-      }
-
-      if (connection === 'close') {
-        this.connected = false;
-        const reason = (
-          lastDisconnect?.error as { output?: { statusCode?: number } }
-        )?.output?.statusCode;
-        const shouldReconnect = reason !== DisconnectReason.loggedOut;
-        logger.info(
-          {
-            reason,
-            shouldReconnect,
-            queuedMessages: this.outgoingQueue.length,
-          },
-          'Connection closed',
-        );
-
-        if (shouldReconnect) {
-          logger.info('Reconnecting...');
-          this.connectInternal().catch((err) => {
-            logger.error({ err }, 'Failed to reconnect, retrying in 5s');
-            setTimeout(() => {
-              this.connectInternal().catch((err2) => {
-                logger.error({ err: err2 }, 'Reconnection retry failed');
-              });
-            }, 5000);
-          });
-        } else {
-          logger.info('Logged out. Run /setup to re-authenticate.');
-          process.exit(0);
-        }
-      } else if (connection === 'open') {
-        this.connected = true;
-        logger.info('Connected to WhatsApp');
-
-        // Announce availability so WhatsApp relays subsequent presence updates (typing indicators)
-        this.sock.sendPresenceUpdate('available').catch((err) => {
-          logger.warn({ err }, 'Failed to send presence update');
-        });
-
-        // Build LID to phone mapping from auth state for self-chat translation
-        if (this.sock.user) {
-          const phoneUser = this.sock.user.id.split(':')[0];
-          const lidUser = this.sock.user.lid?.split(':')[0];
-          if (lidUser && phoneUser) {
-            this.lidToPhoneMap[lidUser] = `${phoneUser}@s.whatsapp.net`;
-            logger.debug({ lidUser, phoneUser }, 'LID to phone mapping set');
-          }
-        }
-
-        // Flush any messages queued while disconnected
-        this.flushOutgoingQueue().catch((err) =>
-          logger.error({ err }, 'Failed to flush outgoing queue'),
-        );
-
-        // Sync group metadata on startup (respects 24h cache)
-        this.syncGroupMetadata().catch((err) =>
-          logger.error({ err }, 'Initial group sync failed'),
-        );
-        // Set up daily sync timer (only once)
-        if (!this.groupSyncTimerStarted) {
-          this.groupSyncTimerStarted = true;
-          setInterval(() => {
-            this.syncGroupMetadata().catch((err) =>
-              logger.error({ err }, 'Periodic group sync failed'),
-            );
-          }, GROUP_SYNC_INTERVAL_MS);
-        }
-
-        // Signal first connection to caller
-        if (onFirstOpen) {
-          onFirstOpen();
-          onFirstOpen = undefined;
-        }
-      }
-    });
-
-    this.sock.ev.on('creds.update', saveCreds);
-
-    this.sock.ev.on('messages.upsert', async ({ messages }) => {
-      for (const msg of messages) {
-        if (!msg.message) continue;
-        // Unwrap container types (viewOnceMessageV2, ephemeralMessage,
-        // editedMessage, etc.) so that conversation, extendedTextMessage,
-        // imageMessage, etc. are accessible at the top level.
-        const normalized = normalizeMessageContent(msg.message);
-        if (!normalized) continue;
-        const rawJid = msg.key.remoteJid;
-        if (!rawJid || rawJid === 'status@broadcast') continue;
-
-        // Translate LID JID to phone JID if applicable
-        const chatJid = await this.translateJid(rawJid);
-
-        const timestamp = new Date(
-          Number(msg.messageTimestamp) * 1000,
-        ).toISOString();
-
-        // Always notify about chat metadata for group discovery
-        const isGroup = chatJid.endsWith('@g.us');
-        this.opts.onChatMetadata(
-          chatJid,
-          timestamp,
-          undefined,
-          'whatsapp',
-          isGroup,
-        );
-
-        // Only deliver full message for registered groups
-        const groups = this.opts.registeredGroups();
-        if (groups[chatJid]) {
-          const content =
-            normalized.conversation ||
-            normalized.extendedTextMessage?.text ||
-            normalized.imageMessage?.caption ||
-            normalized.videoMessage?.caption ||
-            '';
-
-          // Skip protocol messages with no text content (encryption keys, read receipts, etc.)
-          if (!content) continue;
-
-          const sender = msg.key.participant || msg.key.remoteJid || '';
-          const senderName = msg.pushName || sender.split('@')[0];
-
-          const fromMe = msg.key.fromMe || false;
-          // Detect bot messages: with own number, fromMe is reliable
-          // since only the bot sends from that number.
-          // With shared number, bot messages carry the assistant name prefix
-          // (even in DMs/self-chat) so we check for that.
-          const isBotMessage = ASSISTANT_HAS_OWN_NUMBER
-            ? fromMe
-            : content.startsWith(`${ASSISTANT_NAME}:`);
-
-          this.opts.onMessage(chatJid, {
-            id: msg.key.id || '',
-            chat_jid: chatJid,
-            sender,
-            sender_name: senderName,
-            content,
-            timestamp,
-            is_from_me: fromMe,
-            is_bot_message: isBotMessage,
-          });
-        }
-      }
-    });
-  }
-
-  async sendMessage(jid: string, text: string): Promise<void> {
-    // Prefix bot messages with assistant name so users know who's speaking.
-    // On a shared number, prefix is also needed in DMs (including self-chat)
-    // to distinguish bot output from user messages.
-    // Skip only when the assistant has its own dedicated phone number.
-    const prefixed = ASSISTANT_HAS_OWN_NUMBER
-      ? text
-      : `${ASSISTANT_NAME}: ${text}`;
-
-    if (!this.connected) {
-      this.outgoingQueue.push({ jid, text: prefixed });
-      logger.info(
-        { jid, length: prefixed.length, queueSize: this.outgoingQueue.length },
-        'WA disconnected, message queued',
-      );
-      return;
-    }
-    try {
-      await this.sock.sendMessage(jid, { text: prefixed });
-      logger.info({ jid, length: prefixed.length }, 'Message sent');
-    } catch (err) {
-      // If send fails, queue it for retry on reconnect
-      this.outgoingQueue.push({ jid, text: prefixed });
-      logger.warn(
-        { jid, err, queueSize: this.outgoingQueue.length },
-        'Failed to send, message queued',
-      );
-    }
-  }
-
-  isConnected(): boolean {
-    return this.connected;
-  }
-
-  ownsJid(jid: string): boolean {
-    return jid.endsWith('@g.us') || jid.endsWith('@s.whatsapp.net');
-  }
-
-  async disconnect(): Promise<void> {
-    this.connected = false;
-    this.sock?.end(undefined);
-  }
-
-  async setTyping(jid: string, isTyping: boolean): Promise<void> {
-    try {
-      const status = isTyping ? 'composing' : 'paused';
-      logger.debug({ jid, status }, 'Sending presence update');
-      await this.sock.sendPresenceUpdate(status, jid);
-    } catch (err) {
-      logger.debug({ jid, err }, 'Failed to update typing status');
-    }
-  }
-
-  async syncGroups(force: boolean): Promise<void> {
-    return this.syncGroupMetadata(force);
-  }
-
-  /**
-   * Sync group metadata from WhatsApp.
-   * Fetches all participating groups and stores their names in the database.
-   * Called on startup, daily, and on-demand via IPC.
-   */
-  async syncGroupMetadata(force = false): Promise<void> {
-    if (!force) {
-      const lastSync = getLastGroupSync();
-      if (lastSync) {
-        const lastSyncTime = new Date(lastSync).getTime();
-        if (Date.now() - lastSyncTime < GROUP_SYNC_INTERVAL_MS) {
-          logger.debug({ lastSync }, 'Skipping group sync - synced recently');
-          return;
-        }
-      }
-    }
-
-    try {
-      logger.info('Syncing group metadata from WhatsApp...');
-      const groups = await this.sock.groupFetchAllParticipating();
-
-      let count = 0;
-      for (const [jid, metadata] of Object.entries(groups)) {
-        if (metadata.subject) {
-          updateChatName(jid, metadata.subject);
-          count++;
-        }
-      }
-
-      setLastGroupSync();
-      logger.info({ count }, 'Group metadata synced');
-    } catch (err) {
-      logger.error({ err }, 'Failed to sync group metadata');
-    }
-  }
-
-  private async translateJid(jid: string): Promise<string> {
-    if (!jid.endsWith('@lid')) return jid;
-    const lidUser = jid.split('@')[0].split(':')[0];
-
-    // Check local cache first
-    const cached = this.lidToPhoneMap[lidUser];
-    if (cached) {
-      logger.debug(
-        { lidJid: jid, phoneJid: cached },
-        'Translated LID to phone JID (cached)',
-      );
-      return cached;
-    }
-
-    // Query Baileys' signal repository for the mapping
-    try {
-      const pn = await this.sock.signalRepository?.lidMapping?.getPNForLID(jid);
-      if (pn) {
-        const phoneJid = `${pn.split('@')[0].split(':')[0]}@s.whatsapp.net`;
-        this.lidToPhoneMap[lidUser] = phoneJid;
-        logger.info(
-          { lidJid: jid, phoneJid },
-          'Translated LID to phone JID (signalRepository)',
-        );
-        return phoneJid;
-      }
-    } catch (err) {
-      logger.debug({ err, jid }, 'Failed to resolve LID via signalRepository');
-    }
-
-    return jid;
-  }
-
-  private async flushOutgoingQueue(): Promise<void> {
-    if (this.flushing || this.outgoingQueue.length === 0) return;
-    this.flushing = true;
-    try {
-      logger.info(
-        { count: this.outgoingQueue.length },
-        'Flushing outgoing message queue',
-      );
-      while (this.outgoingQueue.length > 0) {
-        const item = this.outgoingQueue.shift()!;
-        // Send directly — queued items are already prefixed by sendMessage
-        await this.sock.sendMessage(item.jid, { text: item.text });
-        logger.info(
-          { jid: item.jid, length: item.text.length },
-          'Queued message sent',
-        );
-      }
-    } finally {
-      this.flushing = false;
-    }
-  }
-}
-
-registerChannel('whatsapp', (opts: ChannelOpts) => new WhatsAppChannel(opts));