feat(providers): generalize provider output substitutions

Adds a per-provider `errorSubstitutions` array on AgentProvider — each
entry is a `(name, test, replace)` triple. The poll-loop iterates the
provider's rules (in declaration order) before delivering result text
or error text to the user; the first matching `test` regex wins and
its `replace` string is sent in place of the raw output. If no rule
matches, the original text passes through unchanged — there is no
fallback message.

Replaces the single-purpose `isAuthRequired` / `authRequiredMessage`
shape with a list of typed rules so providers can declare any number
of swap-this-for-that mappings (auth banners, rate-limit hints,
context-too-long errors, etc.). New rule types just add an entry.

ClaudeProvider ships one rule today: `auth-required`, matching Claude
Code's "Not logged in · Please run /login" / "Invalid API key …"
banners with a host-aware remediation (re-run setup or run `claude`
in the project directory).

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,5 @@
+{
+  "sandbox": {
+    "enabled": false
+  }
+}

.claude/skills/add-atomic-chat-tool/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: add-atomic-chat-tool
+description: Add Atomic Chat MCP server so the container agent can call local models served by the Atomic Chat desktop app via its OpenAI-compatible API.
+---
+
+# Add Atomic Chat Integration
+
+This skill adds a stdio-based MCP server that exposes models running in the local [Atomic Chat](https://github.com/AtomicBot-ai/Atomic-Chat) desktop app as tools for the container agent. Claude remains the orchestrator but can offload work to local models served by Atomic Chat on `http://127.0.0.1:1337/v1` (OpenAI-compatible).
+
+Tools exposed:
+- `atomic_chat_list_models` — list models currently available in Atomic Chat (`GET /v1/models`)
+- `atomic_chat_generate` — send a prompt to a specified model and return the response (`POST /v1/chat/completions`)
+
+Model management (download, delete) is done through the **Atomic Chat desktop UI** — the app is a fork of Jan and manages its own model library.
+
+The skill ships the MCP server source in this folder and copies it into the agent-runner tree at install time, then wires it up with small edits to `index.ts`, `providers/claude.ts`, and `container-runner.ts`. No branch merge — all edits are additive and idempotent.
+
+## Phase 1: Pre-flight
+
+### Check if already applied
+
+Check if `container/agent-runner/src/atomic-chat-mcp-stdio.ts` exists. If it does, skip to Phase 3 (Configure).
+
+### Check prerequisites
+
+Verify Atomic Chat is installed and its local API server is running. On the host:
+
+```bash
+curl -s http://127.0.0.1:1337/v1/models | head
+```
+
+If the request fails:
+
+1. Install Atomic Chat from the [latest release](https://github.com/AtomicBot-ai/Atomic-Chat/releases) (macOS only for now — `atomic-chat.dmg`).
+2. Open the app.
+3. Open **Settings → Local API Server** and make sure it's enabled on port `1337`.
+4. Go to the **Hub** (or **Models**) tab and download at least one model (e.g. Llama 3.2 3B, Qwen 2.5 Coder 7B).
+5. Load the model once by sending any message in Atomic Chat's UI to warm it up.
+
+## Phase 2: Apply Code Changes
+
+### Copy the MCP server source
+
+```bash
+cp .claude/skills/add-atomic-chat-tool/atomic-chat-mcp-stdio.ts container/agent-runner/src/atomic-chat-mcp-stdio.ts
+```
+
+### Register the MCP server in the agent-runner
+
+Edit `container/agent-runner/src/index.ts`. Find the `mcpServers` object that currently looks like this:
+
+```ts
+  const mcpServers: Record<string, { command: string; args: string[]; env: Record<string, string> }> = {
+    nanoclaw: {
+      command: 'bun',
+      args: ['run', mcpServerPath],
+      env: {},
+    },
+  };
+```
+
+Add an `atomic_chat` entry alongside `nanoclaw`:
+
+```ts
+  const mcpServers: Record<string, { command: string; args: string[]; env: Record<string, string> }> = {
+    nanoclaw: {
+      command: 'bun',
+      args: ['run', mcpServerPath],
+      env: {},
+    },
+    atomic_chat: {
+      command: 'bun',
+      args: ['run', path.join(__dirname, 'atomic-chat-mcp-stdio.ts')],
+      env: {
+        ...(process.env.ATOMIC_CHAT_HOST ? { ATOMIC_CHAT_HOST: process.env.ATOMIC_CHAT_HOST } : {}),
+        ...(process.env.ATOMIC_CHAT_API_KEY ? { ATOMIC_CHAT_API_KEY: process.env.ATOMIC_CHAT_API_KEY } : {}),
+      },
+    },
+  };
+```
+
+### Add the tool glob to the allowlist
+
+Edit `container/agent-runner/src/providers/claude.ts`. Find `'mcp__nanoclaw__*',` in the `TOOL_ALLOWLIST` array and add `'mcp__atomic_chat__*',` on the following line:
+
+```ts
+  'mcp__nanoclaw__*',
+  'mcp__atomic_chat__*',
+];
+```
+
+### Forward host env vars into the container
+
+Edit `src/container-runner.ts` in `buildContainerArgs`. Find the `TZ` env line:
+
+```ts
+  args.push('-e', `TZ=${TIMEZONE}`);
+```
+
+Add ATOMIC_CHAT forwarding right after it:
+
+```ts
+  args.push('-e', `TZ=${TIMEZONE}`);
+
+  // Atomic Chat MCP tool: forward host overrides if set (default is host.docker.internal:1337).
+  if (process.env.ATOMIC_CHAT_HOST) {
+    args.push('-e', `ATOMIC_CHAT_HOST=${process.env.ATOMIC_CHAT_HOST}`);
+  }
+  if (process.env.ATOMIC_CHAT_API_KEY) {
+    args.push('-e', `ATOMIC_CHAT_API_KEY=${process.env.ATOMIC_CHAT_API_KEY}`);
+  }
+```
+
+### Surface `[ATOMIC]` log lines at info level
+
+In the same file, find the stderr logger:
+
+```ts
+  container.stderr?.on('data', (data) => {
+    for (const line of data.toString().trim().split('\n')) {
+      if (line) log.debug(line, { container: agentGroup.folder });
+    }
+  });
+```
+
+Replace it with:
+
+```ts
+  container.stderr?.on('data', (data) => {
+    for (const line of data.toString().trim().split('\n')) {
+      if (!line) continue;
+      if (line.includes('[ATOMIC]')) {
+        log.info(line, { container: agentGroup.folder });
+      } else {
+        log.debug(line, { container: agentGroup.folder });
+      }
+    }
+  });
+```
+
+### Add env-var stubs to `.env.example`
+
+Append to `.env.example`:
+
+```bash
+# Atomic Chat MCP tool (.claude/skills/add-atomic-chat-tool)
+# Override the host where Atomic Chat exposes its OpenAI-compatible API.
+# Default: http://host.docker.internal:1337 (with fallback to localhost)
+# ATOMIC_CHAT_HOST=http://host.docker.internal:1337
+
+# Optional API key. Leave unset for a local Atomic Chat install — it does not require auth.
+# ATOMIC_CHAT_API_KEY=
+```
+
+### Validate code changes
+
+```bash
+pnpm run build
+pnpm exec tsc -p container/agent-runner/tsconfig.json --noEmit
+./container/build.sh
+```
+
+All three must be clean before proceeding.
+
+## Phase 3: Configure
+
+### Set Atomic Chat host (optional)
+
+By default, the MCP server connects to `http://host.docker.internal:1337` (Docker Desktop) with a fallback to `localhost`. To use a custom host, add to `.env`:
+
+```bash
+ATOMIC_CHAT_HOST=http://your-atomic-chat-host:1337
+```
+
+### Set API key (optional)
+
+Atomic Chat does **not require authentication** when running locally — leave this unset. Only set it if you've put Atomic Chat behind a reverse proxy that enforces auth:
+
+```bash
+ATOMIC_CHAT_API_KEY=sk-...
+```
+
+### 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 atomic chat to tell me the capital of France"
+>
+> The agent should use `atomic_chat_list_models` to find available models, then `atomic_chat_generate` to get a response.
+
+### Check logs if needed
+
+```bash
+tail -f logs/nanoclaw.log | grep -i atomic
+```
+
+Look for:
+- `[ATOMIC] Listing models...` — list request started
+- `[ATOMIC] Found N models` — models discovered
+- `[ATOMIC] >>> Generating with <model>` — generation started
+- `[ATOMIC] <<< Done: <model> | Xs | N tokens | M chars` — generation completed
+
+## Troubleshooting
+
+### Agent says "Atomic Chat is not installed" or tries to run a CLI
+
+The agent is looking for a CLI that doesn't exist instead of using the MCP tools. This means:
+1. The MCP server wasn't copied — check `container/agent-runner/src/atomic-chat-mcp-stdio.ts` exists
+2. The MCP server wasn't registered — check `container/agent-runner/src/index.ts` has the `atomic_chat` entry in `mcpServers`
+3. The allowlist wasn't updated — check `container/agent-runner/src/providers/claude.ts` includes `mcp__atomic_chat__*` in `TOOL_ALLOWLIST`
+4. The container wasn't rebuilt — run `./container/build.sh`
+
+### "Failed to connect to Atomic Chat"
+
+1. Verify the host API is reachable: `curl http://127.0.0.1:1337/v1/models`
+2. Confirm the Local API Server is enabled in Atomic Chat's settings
+3. Check Docker can reach the host: `docker run --rm curlimages/curl curl -s http://host.docker.internal:1337/v1/models`
+4. If using a custom host, check `ATOMIC_CHAT_HOST` in `.env`
+
+### `model not found` / 404 on generate
+
+The model ID passed to `atomic_chat_generate` must exactly match one of the IDs returned by `atomic_chat_list_models`. Ask the agent to list models first, then pick one from that list.
+
+### Slow first response
+
+Atomic Chat lazy-loads models into memory on first use. The initial call may take longer while the model warms up. Subsequent calls against the same model are fast.
+
+### Agent doesn't use Atomic Chat tools
+
+The agent may not know about the tools. Try being explicit: "use the atomic_chat_generate tool with llama3.2-3b-instruct to answer: ..."
+
+### Context window or output size issues
+
+Atomic Chat respects each model's native context length. If you hit limits, pass `max_tokens` explicitly when calling `atomic_chat_generate`, or switch to a model with a larger context window in the Atomic Chat UI.

.claude/skills/add-atomic-chat-tool/atomic-chat-mcp-stdio.ts

@@ -0,0 +1,229 @@
+/**
+ * Atomic Chat MCP Server for NanoClaw
+ * Exposes local Atomic Chat models (OpenAI-compatible, /v1) as tools for the container agent.
+ * Uses host.docker.internal to reach the host's Atomic Chat desktop app from Docker.
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+import fs from 'fs';
+import path from 'path';
+
+const ATOMIC_CHAT_HOST =
+  process.env.ATOMIC_CHAT_HOST || 'http://host.docker.internal:1337';
+const ATOMIC_CHAT_API_KEY = process.env.ATOMIC_CHAT_API_KEY || '';
+const ATOMIC_CHAT_STATUS_FILE = '/workspace/ipc/atomic_chat_status.json';
+
+function log(msg: string): void {
+  console.error(`[ATOMIC] ${msg}`);
+}
+
+function writeStatus(status: string, detail?: string): void {
+  try {
+    const data = { status, detail, timestamp: new Date().toISOString() };
+    const tmpPath = `${ATOMIC_CHAT_STATUS_FILE}.tmp`;
+    fs.mkdirSync(path.dirname(ATOMIC_CHAT_STATUS_FILE), { recursive: true });
+    fs.writeFileSync(tmpPath, JSON.stringify(data));
+    fs.renameSync(tmpPath, ATOMIC_CHAT_STATUS_FILE);
+  } catch {
+    /* best-effort */
+  }
+}
+
+async function atomicFetch(
+  apiPath: string,
+  options?: RequestInit,
+): Promise<Response> {
+  const url = `${ATOMIC_CHAT_HOST}${apiPath}`;
+  const headers: Record<string, string> = {
+    ...((options?.headers as Record<string, string>) || {}),
+  };
+  if (ATOMIC_CHAT_API_KEY) {
+    headers.Authorization = `Bearer ${ATOMIC_CHAT_API_KEY}`;
+  }
+  const finalOptions: RequestInit = { ...options, headers };
+  try {
+    return await fetch(url, finalOptions);
+  } catch (err) {
+    // Fallback to localhost if host.docker.internal fails
+    if (ATOMIC_CHAT_HOST.includes('host.docker.internal')) {
+      const fallbackUrl = url.replace('host.docker.internal', 'localhost');
+      return await fetch(fallbackUrl, finalOptions);
+    }
+    throw err;
+  }
+}
+
+const server = new McpServer({
+  name: 'atomic_chat',
+  version: '1.0.0',
+});
+
+server.tool(
+  'atomic_chat_list_models',
+  'List all models available in the local Atomic Chat desktop app. Use this to see which models are loaded before calling atomic_chat_generate.',
+  {},
+  async () => {
+    log('Listing models...');
+    writeStatus('listing', 'Listing available models');
+    try {
+      const res = await atomicFetch('/v1/models');
+      if (!res.ok) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Atomic Chat API error: ${res.status} ${res.statusText}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      const data = (await res.json()) as {
+        data?: Array<{ id: string; owned_by?: string }>;
+      };
+      const models = data.data || [];
+
+      if (models.length === 0) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: 'No models available. Open Atomic Chat on the host and download a model from the Hub.',
+            },
+          ],
+        };
+      }
+
+      const list = models
+        .map((m) => `- ${m.id}${m.owned_by ? ` (${m.owned_by})` : ''}`)
+        .join('\n');
+
+      log(`Found ${models.length} models`);
+      return {
+        content: [
+          { type: 'text' as const, text: `Available models:\n${list}` },
+        ],
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Failed to connect to Atomic Chat at ${ATOMIC_CHAT_HOST}: ${err instanceof Error ? err.message : String(err)}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  },
+);
+
+server.tool(
+  'atomic_chat_generate',
+  'Send a prompt to a local Atomic Chat model and get a response. Good for cheaper/faster tasks like summarization, translation, or general queries. Use atomic_chat_list_models first to see available models.',
+  {
+    model: z
+      .string()
+      .describe(
+        'The model ID as returned by atomic_chat_list_models (e.g. "llama3.2-3b-instruct")',
+      ),
+    prompt: z.string().describe('The prompt to send to the model'),
+    system: z
+      .string()
+      .optional()
+      .describe('Optional system prompt to set model behavior'),
+    temperature: z
+      .number()
+      .optional()
+      .describe('Sampling temperature (0.0–2.0). Defaults to model default.'),
+    max_tokens: z
+      .number()
+      .optional()
+      .describe('Maximum number of tokens to generate in the response.'),
+  },
+  async (args) => {
+    log(`>>> Generating with ${args.model} (${args.prompt.length} chars)...`);
+    writeStatus('generating', `Generating with ${args.model}`);
+    try {
+      const messages: Array<{ role: string; content: string }> = [];
+      if (args.system) {
+        messages.push({ role: 'system', content: args.system });
+      }
+      messages.push({ role: 'user', content: args.prompt });
+
+      const body: Record<string, unknown> = {
+        model: args.model,
+        messages,
+        stream: false,
+      };
+      if (args.temperature !== undefined) body.temperature = args.temperature;
+      if (args.max_tokens !== undefined) body.max_tokens = args.max_tokens;
+
+      const startedAt = Date.now();
+      const res = await atomicFetch('/v1/chat/completions', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+      });
+
+      if (!res.ok) {
+        const errorText = await res.text();
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Atomic Chat error (${res.status}): ${errorText}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      const data = (await res.json()) as {
+        choices?: Array<{ message?: { content?: string } }>;
+        usage?: {
+          prompt_tokens?: number;
+          completion_tokens?: number;
+          total_tokens?: number;
+        };
+      };
+
+      const response = data.choices?.[0]?.message?.content ?? '';
+      const elapsedSec = ((Date.now() - startedAt) / 1000).toFixed(1);
+      const completionTokens = data.usage?.completion_tokens;
+
+      const meta = `\n\n[${args.model} | ${elapsedSec}s${
+        completionTokens !== undefined ? ` | ${completionTokens} tokens` : ''
+      }]`;
+
+      log(
+        `<<< Done: ${args.model} | ${elapsedSec}s | ${
+          completionTokens ?? '?'
+        } tokens | ${response.length} chars`,
+      );
+      writeStatus(
+        'done',
+        `${args.model} | ${elapsedSec}s | ${completionTokens ?? '?'} tokens`,
+      );
+
+      return { content: [{ type: 'text' as const, text: response + meta }] };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Failed to call Atomic Chat: ${err instanceof Error ? err.message : String(err)}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  },
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

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

@@ -0,0 +1,161 @@
+---
+name: add-codex
+description: Use Codex (CLI + AppServer) as the full agent provider — planning, tool orchestration, native compaction, MCP tools, session resume — in place of the Claude Agent SDK. ChatGPT subscription or OPENAI_API_KEY. Per-group via agent_provider. Distinct from using OpenAI as an MCP tool (where Claude remains the planner).
+---
+
+# Codex agent provider
+
+NanoClaw runs agents in a long-lived **poll loop** inside the container. The backend is selected with **`AGENT_PROVIDER`** (`claude` | `opencode` | `codex` | `mock`).
+
+Trunk ships with only the `claude` provider baked in. This skill copies the Codex provider files in from the `providers` branch, wires them into the host and container barrels, updates the Dockerfile to install the Codex CLI, and rebuilds the image.
+
+The Codex provider runs `codex app-server` as a child process and speaks JSON-RPC over stdio. That gives it native session resume, streaming events, MCP tool access, and `thread/compact/start` compaction — same feature bar as the Claude Agent SDK, without the Anthropic-only lock-in.
+
+## Install
+
+### Pre-flight
+
+If all of the following are already present, skip to **Configuration**:
+
+- `src/providers/codex.ts`
+- `container/agent-runner/src/providers/codex.ts`
+- `container/agent-runner/src/providers/codex-app-server.ts`
+- `container/agent-runner/src/providers/codex.factory.test.ts`
+- `import './codex.js';` line in `src/providers/index.ts`
+- `import './codex.js';` line in `container/agent-runner/src/providers/index.ts`
+- `ARG CODEX_VERSION` and `"@openai/codex@${CODEX_VERSION}"` in the pnpm global-install block in `container/Dockerfile`
+
+Missing pieces — continue below. All steps are idempotent; re-running is safe.
+
+### 1. Fetch the providers branch
+
+```bash
+git fetch origin providers
+```
+
+### 2. Copy the Codex source files
+
+Wholesale copies (owned entirely by this skill — user edits to these files won't survive a re-run, as designed):
+
+```bash
+git show origin/providers:src/providers/codex.ts                                      > src/providers/codex.ts
+git show origin/providers:container/agent-runner/src/providers/codex.ts               > container/agent-runner/src/providers/codex.ts
+git show origin/providers:container/agent-runner/src/providers/codex-app-server.ts    > container/agent-runner/src/providers/codex-app-server.ts
+git show origin/providers:container/agent-runner/src/providers/codex.factory.test.ts  > container/agent-runner/src/providers/codex.factory.test.ts
+```
+
+### 3. Append the self-registration imports
+
+Each barrel gets one line — alphabetical placement keeps diffs small.
+
+`src/providers/index.ts`:
+
+```typescript
+import './codex.js';
+```
+
+`container/agent-runner/src/providers/index.ts`:
+
+```typescript
+import './codex.js';
+```
+
+### 4. Add the Codex CLI to the container Dockerfile
+
+Two edits to `container/Dockerfile`, both idempotent (skip if already present):
+
+**(a)** In the "Pin CLI versions" ARG block (around line 18), add after `ARG CLAUDE_CODE_VERSION=...`:
+
+```dockerfile
+ARG CODEX_VERSION=0.124.0
+```
+
+**(b)** Add a new standalone `RUN` block for the Codex CLI, after the existing per-CLI install blocks (around line 106, right after the `@anthropic-ai/claude-code` block). The Dockerfile splits each global CLI into its own layer for cache granularity — keep that pattern; do not collapse them into a single combined `pnpm install -g` call:
+
+```dockerfile
+RUN --mount=type=cache,target=/root/.cache/pnpm \
+    pnpm install -g "@openai/codex@${CODEX_VERSION}"
+```
+
+Note: **no agent-runner package dependency** — Codex is a CLI binary, not a library. Unlike OpenCode, there's nothing to add to `container/agent-runner/package.json`.
+
+### 5. Build
+
+```bash
+pnpm run build                                         # host
+pnpm exec tsc -p container/agent-runner/tsconfig.json --noEmit   # container typecheck
+./container/build.sh                                   # agent image
+```
+
+## Configuration
+
+Codex supports two primary auth paths and one experimental BYO-endpoint path. Pick the one that matches your setup.
+
+### Option A — ChatGPT subscription (recommended for individuals)
+
+On the host (not inside the container), run Codex's OAuth login:
+
+```bash
+codex login
+```
+
+This writes `~/.codex/auth.json` with a subscription token. The host-side Codex provider ([src/providers/codex.ts](../../../src/providers/codex.ts)) copies `auth.json` into a per-session `~/.codex` directory mounted into the container — your host's own Codex CLI is never touched.
+
+No `.env` variables required for this mode.
+
+### Option B — API key (recommended for CI or API billing)
+
+```env
+OPENAI_API_KEY=sk-...
+CODEX_MODEL=gpt-5.4-mini
+```
+
+The host forwards both variables into the container. If both subscription (`auth.json`) and `OPENAI_API_KEY` are present, Codex prefers the subscription.
+
+### Option C — BYO OpenAI-compatible endpoint (experimental)
+
+Codex's built-in `openai` provider honors the `OPENAI_BASE_URL` env var directly. Point it at any OpenAI-compatible endpoint — Groq, Together, self-hosted vLLM, an OpenAI proxy, etc.
+
+```env
+OPENAI_API_KEY=...
+OPENAI_BASE_URL=https://api.groq.com/openai/v1
+CODEX_MODEL=llama-3.3-70b-versatile
+```
+
+Codex also ships first-class local-runner flags — `codex --oss --local-provider ollama` or `--local-provider lmstudio` — that auto-detect a local server. To use those inside NanoClaw, set `CODEX_MODEL` to a model your local runner serves and add the corresponding base URL; see the Codex CLI docs for the full `model_provider = oss` configuration.
+
+**Experimental caveat:** tool-calling quality depends on the model and endpoint. Not every OpenAI-compat provider implements the full function-calling spec, and smaller models (< 30B) often struggle with multi-step tool orchestration. Test before committing.
+
+### Per group / per session
+
+Set `"provider": "codex"` in the group's **`container.json`** (`groups/<folder>/container.json`) — the in-container runner reads `provider` from there, not from the DB. The DB columns **`agent_groups.agent_provider`** and **`sessions.agent_provider`** (session overrides group) only drive host-side provider contribution — per-session `~/.codex` mount, `OPENAI_*` / `CODEX_MODEL` env passthrough — and do not propagate into `container.json` at spawn time. Set both, or just edit `container.json`; if they disagree, the runner uses `container.json` and the host-side resolver falls back through session → group → `container.json` → `'claude'`.
+
+`CODEX_MODEL` applies process-wide via `.env`; if you need different models for different groups, set them via `container_config.env` on the 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 all providers.
+
+## Operational notes
+
+- **Spawn-per-query:** Codex's app-server is spawned fresh per query invocation, matching the OpenCode pattern. No long-lived daemon to keep healthy across sessions.
+- **Per-session `~/.codex` isolation:** each group gets its own copy of the host's `auth.json`. The container can rewrite `config.toml` freely on every wake without touching the host's Codex config.
+- **Native compaction:** kicks in automatically at 40K cumulative input tokens between turns, via `thread/compact/start`. If compaction fails, the provider logs and continues uncompacted — no fatal error.
+- **Approvals:** auto-accepted inside the container (the container is the sandbox; same posture as Claude/OpenCode).
+- **Mid-turn input:** Codex turns don't accept mid-turn messages. Follow-up `push()` calls queue and drain between turns, matching the OpenCode pattern. The poll-loop only pushes between turns anyway, so no messages are dropped.
+- **Stale thread recovery:** `isSessionInvalid` matches on stale-thread-ID errors (`thread not found`, `unknown thread`, etc.) so a cold-started app-server can recover cleanly when it sees a stored continuation it no longer has.
+
+## Verify
+
+```bash
+grep -q "./codex.js" container/agent-runner/src/providers/index.ts && echo "container barrel: OK"
+grep -q "./codex.js" src/providers/index.ts && echo "host barrel: OK"
+grep -q "@openai/codex@" container/Dockerfile && echo "Dockerfile install: OK"
+cd container/agent-runner && bun test src/providers/codex.factory.test.ts && cd -
+```
+
+After the image rebuild, set `agent_provider = 'codex'` on a test group and send a message. Successful round-trip looks like:
+
+- `init` event with a stable thread ID as continuation
+- One or more `activity` / `progress` events during the turn
+- `result` event with the model's reply
+
+If the agent hangs or errors, check `~/.codex/auth.json` exists on the host (Option A) or that `OPENAI_API_KEY` is forwarding correctly (Option B) — `docker exec` into a running container and `env | grep -i openai` to confirm.

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

@@ -0,0 +1,138 @@
+---
+name: add-dashboard
+description: Add a monitoring dashboard to NanoClaw. 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 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/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/SKILL.md

@@ -1,206 +1,98 @@
+---
+name: add-discord
+description: Add Discord bot channel integration via Chat SDK.
+---
+
 # Add Discord Channel
 
-This skill adds Discord support to NanoClaw using the skills engine for deterministic code changes, then walks through interactive setup.
+Adds Discord bot support via the Chat SDK bridge.
 
-## Phase 1: Pre-flight
+## Install
 
-### Check if already applied
+NanoClaw doesn't ship channels in trunk. This skill copies the Discord adapter in from the `channels` branch.
 
-Read `.nanoclaw/state.yaml`. If `discord` is in `applied_skills`, skip to Phase 3 (Setup). The code changes are already in place.
+### Pre-flight (idempotent)
 
-### Ask the user
+Skip to **Credentials** if all of these are already in place:
 
-Use `AskUserQuestion` to collect configuration:
+- `src/channels/discord.ts` exists
+- `src/channels/index.ts` contains `import './discord.js';`
+- `@chat-adapter/discord` is listed in `package.json` dependencies
 
-AskUserQuestion: Do you have a Discord bot token, or do you need to create one?
+Otherwise continue. Every step below is safe to re-run.
 
-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:
+### 1. Fetch the channels branch
 
 ```bash
-npx tsx scripts/apply-skill.ts --init
+git fetch origin channels
 ```
 
-Or call `initSkillsSystem()` from `skills-engine/migrate.ts`.
-
-### Apply the skill
+### 2. Copy the adapter
 
 ```bash
-npx tsx scripts/apply-skill.ts .claude/skills/add-discord
+git show origin/channels:src/channels/discord.ts > src/channels/discord.ts
 ```
 
-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`
+### 3. Append the self-registration import
 
-If the apply reports merge conflicts, read the intent file:
-- `modify/src/channels/index.ts.intent.md` — what changed and invariants
+Append to `src/channels/index.ts` (skip if the line is already present):
 
-### Validate code changes
+```typescript
+import './discord.js';
+```
+
+### 4. Install the adapter package (pinned)
 
 ```bash
-npm test
-npm run build
+pnpm install @chat-adapter/discord@4.26.0
 ```
 
-All tests must pass (including the new Discord tests) and build must be clean before proceeding.
+### 5. Build
 
-## Phase 3: Setup
+```bash
+pnpm run build
+```
 
-### Create Discord Bot (if needed)
+## Credentials
 
-If the user doesn't have a bot token, tell them:
+### Create Discord Bot
 
-> I need you to create a 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., "Andy Assistant")
-> 3. Go to the **Bot** tab on the left sidebar
-> 4. Click **Reset Token** to generate a new bot token — copy it immediately (you can only see it once)
-> 5. Under **Privileged Gateway Intents**, enable:
->    - **Message Content Intent** (required to read message text)
->    - **Server Members Intent** (optional, for member display names)
-> 6. Go to **OAuth2** > **URL Generator**:
->    - Scopes: select `bot`
->    - Bot Permissions: select `Send Messages`, `Read Message History`, `View Channels`
->    - Copy the generated URL and open it in your browser to invite the bot to your server
-
-Wait for the user to provide the token.
+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=<their-token>
+DISCORD_BOT_TOKEN=your-bot-token
+DISCORD_APPLICATION_ID=your-application-id
+DISCORD_PUBLIC_KEY=your-public-key
 ```
 
-Channels auto-enable when their credentials are present — no extra configuration needed.
+Sync to container: `mkdir -p data/env && cp .env data/env/env`
 
-Sync to container environment:
+## Next Steps
 
-```bash
-mkdir -p data/env && cp .env data/env/env
-```
+If you're in the middle of `/setup`, return to the setup flow now.
 
-The container reads environment from `data/env/env`, not `.env` directly.
+Otherwise, run `/manage-channels` to wire this channel to an agent group.
 
-### Build and restart
+## Channel Info
 
-```bash
-npm run build
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw
-```
-
-## Phase 4: Registration
-
-### Get Channel ID
-
-Tell the user:
-
-> To get the channel ID for registration:
->
-> 1. In Discord, go to **User Settings** > **Advanced** > Enable **Developer Mode**
-> 2. Right-click the text channel you want the bot to respond in
-> 3. Click **Copy Channel ID**
->
-> The channel ID will be a long number like `1234567890123456`.
-
-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.
-
-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,
-});
-```
-
-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,
-});
-```
-
-## Phase 5: Verify
-
-### Test the connection
-
-Tell the user:
-
-> Send a message in your registered Discord channel:
-> - For main channel: Any message works
-> - For non-main: @mention the bot in Discord
->
-> The bot should respond within a few seconds.
-
-### Check logs if needed
-
-```bash
-tail -f logs/nanoclaw.log
-```
-
-## Troubleshooting
-
-### Bot not responding
-
-1. Check `DISCORD_BOT_TOKEN` is set in `.env` AND synced to `data/env/env`
-2. Check channel is registered: `sqlite3 store/messages.db "SELECT * FROM registered_groups WHERE jid LIKE 'dc:%'"`
-3. For non-main channels: message must include trigger pattern (@mention the bot)
-4. Service is running: `launchctl list | grep nanoclaw`
-5. Verify the bot has been invited to the server (check OAuth2 URL was used)
-
-### Bot only responds to @mentions
-
-This is the default behavior for non-main channels (`requiresTrigger: true`). To change:
-- Update the registered group's `requiresTrigger` to `false`
-- Or register the channel as the main channel
-
-### Message Content Intent not enabled
-
-If the bot connects but can't read messages, ensure:
-1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
-2. Select your application > **Bot** tab
-3. Under **Privileged Gateway Intents**, enable **Message Content Intent**
-4. Restart NanoClaw
-
-### Getting Channel ID
-
-If you can't copy the channel ID:
-- Ensure **Developer Mode** is enabled: User Settings > Advanced > Developer Mode
-- Right-click the channel name in the server sidebar > Copy Channel ID
-
-## After Setup
-
-The Discord bot supports:
-- Text messages in registered channels
-- Attachment descriptions (images, videos, files shown as placeholders)
-- Reply context (shows who the user is replying to)
-- @mention translation (Discord `<@botId>` → NanoClaw trigger format)
-- Message splitting for responses over 2000 characters
-- Typing indicators while the agent processes
+- **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/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/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,296 @@
+---
+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). Local HTTP bridge — no bot token or external service needed.
+---
+
+# Add Emacs Channel
+
+Adds Emacs support via a local HTTP bridge. 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
+
+## Install
+
+NanoClaw doesn't ship channels in trunk. This skill copies the Emacs adapter and the Lisp client in from the `channels` branch. Native HTTP bridge — no Chat SDK, no adapter package.
+
+### Pre-flight (idempotent)
+
+Skip to **Enable** if all of these are already in place:
+
+- `src/channels/emacs.ts` exists
+- `emacs/nanoclaw.el` exists
+- `src/channels/index.ts` contains `import './emacs.js';`
+
+Otherwise continue. Every step below is safe to re-run.
+
+### 1. Fetch the channels branch
+
+```bash
+git fetch origin channels
+```
+
+### 2. Copy the adapter and Lisp client
+
+```bash
+mkdir -p emacs
+git show origin/channels:src/channels/emacs.ts      > src/channels/emacs.ts
+git show origin/channels:src/channels/emacs.test.ts > src/channels/emacs.test.ts
+git show origin/channels:emacs/nanoclaw.el          > emacs/nanoclaw.el
+```
+
+### 3. Append the self-registration import
+
+Append to `src/channels/index.ts` (skip if the line is already present):
+
+```typescript
+import './emacs.js';
+```
+
+### 4. Build
+
+```bash
+pnpm run build
+```
+
+No npm package to install — the adapter uses only Node builtins (`http`).
+
+## Enable
+
+The adapter is gated by `EMACS_ENABLED` so the HTTP port isn't opened on hosts that aren't running Emacs. Add to `.env`:
+
+```bash
+EMACS_ENABLED=true
+EMACS_CHANNEL_PORT=8766       # optional — change only if 8766 is taken
+EMACS_AUTH_TOKEN=             # optional — set to a random string to lock the endpoint
+EMACS_PLATFORM_ID=default     # optional — only change if you want a non-default chat id
+```
+
+Generate an auth token (recommended even on single-user machines — prevents other local processes from poking the endpoint):
+
+```bash
+node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"
+```
+
+## Wire the channel
+
+Emacs is a single-user, single-chat channel. One host = one messaging group with `platform_id = "default"`.
+
+### If this is your first agent group
+
+Run `/init-first-agent` — pick **Emacs** as the channel, use any short handle as the "user id" (e.g. your OS username), and the skill will create the agent group, wire the channel, and write a welcome message that the agent delivers back to your Emacs buffer.
+
+### Otherwise — wire to an existing agent group
+
+Run the `register` step directly. The `EMACS_PLATFORM_ID` (default `default`) becomes the messaging group's platform id:
+
+```bash
+pnpm exec tsx setup/index.ts --step register -- \
+  --platform-id "default" --name "Emacs" \
+  --folder "<existing-folder>" --channel "emacs" \
+  --session-mode "agent-shared" \
+  --assistant-name "<existing-assistant-name>"
+```
+
+`agent-shared` puts Emacs messages in the same session as any other channel wired to the same agent group — so a conversation you started in Telegram continues in Emacs. Use `shared` to keep an independent Emacs thread with the same workspace, or a new `--folder` for a dedicated Emacs-only agent.
+
+## Configure Emacs
+
+`nanoclaw.el` needs only Emacs 27.1+ builtins (`url`, `json`, `org`) — no package manager.
+
+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)
+```
+
+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)
+```
+
+Reload: `M-x dotspacemacs/sync-configuration-layers` or restart Emacs.
+
+**Vanilla Emacs** — add to `~/.emacs.d/init.el`:
+
+```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)
+```
+
+Reload: `M-x eval-buffer` or restart Emacs.
+
+Replace `~/src/nanoclaw/emacs/nanoclaw.el` with your actual NanoClaw checkout path.
+
+If `EMACS_AUTH_TOKEN` is set, also add (any distribution):
+
+```elisp
+(setq nanoclaw-auth-token "<your-token>")
+```
+
+If you changed `EMACS_CHANNEL_PORT` from the default:
+
+```elisp
+(setq nanoclaw-port <your-port>)
+```
+
+## Restart NanoClaw
+
+```bash
+pnpm run build
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw   # macOS
+# systemctl --user restart nanoclaw                # Linux
+```
+
+## Verify
+
+### HTTP endpoint
+
+```bash
+curl -s http://localhost:8766/api/messages?since=0
+```
+
+Expected: `{"messages":[]}`. With an auth token:
+
+```bash
+curl -s -H "Authorization: Bearer <token>" http://localhost:8766/api/messages?since=0
+```
+
+### 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 `C-c C-c` to send (RET inserts newlines)
+> 3. A response 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`
+
+### Log line
+
+`tail -f logs/nanoclaw.log` should show `Emacs channel listening` at startup.
+
+## Channel Info
+
+- **type**: `emacs`
+- **terminology**: Single local buffer. There are no "groups" or separate chats — one host = one chat, addressed by a `platform_id` string (default `default`).
+- **how-to-find-id**: The platform id is whatever you set in `EMACS_PLATFORM_ID` (default `default`). User handles are arbitrary; your OS username or first name is fine (e.g. `emacs:<username>`).
+- **supports-threads**: no
+- **typical-use**: Single developer talking to the assistant from within Emacs, alongside whatever other channel they use (Slack, Telegram, Discord).
+- **default-isolation**: Same agent group as the primary DM, with `session-mode = agent-shared` so a conversation started elsewhere continues in Emacs. Pick a separate folder only if you specifically want an Emacs-only persona.
+
+### Features
+
+- Interactive chat buffer (`nanoclaw-chat`) with markdown → org-mode rendering
+- Org integration (`nanoclaw-org-send`) — sends the current subtree or region; reply lands as a child heading
+- Optional bearer-token auth for the local endpoint
+- Single-user: the adapter exposes exactly one messaging group per host
+
+Not applicable (design): multi-user channels, threads, cold DM initiation, typing indicators, attachments.
+
+## Troubleshooting
+
+### Port already in use
+
+```
+Error: listen EADDRINUSE: address already in use :::8766
+```
+
+Either a stale NanoClaw is running or another app has the port. Kill stale process or change port:
+
+```bash
+lsof -ti :8766 | xargs kill -9
+# or set EMACS_CHANNEL_PORT in .env and mirror in Emacs config (nanoclaw-port)
+```
+
+### Adapter not starting
+
+If `grep "Emacs channel listening" logs/nanoclaw.log` returns nothing, check that `EMACS_ENABLED=true` is in `.env` and that the adapter import is present:
+
+```bash
+grep -q '^EMACS_ENABLED=true' .env && echo "enabled" || echo "not enabled"
+grep -q "import './emacs.js'" src/channels/index.ts && echo "imported" || echo "not imported"
+```
+
+### No response from agent
+
+1. NanoClaw running: `launchctl list | grep nanoclaw` (macOS) / `systemctl --user status nanoclaw` (Linux)
+2. Messaging group wired: `sqlite3 data/v2.db "SELECT mg.platform_id, ag.folder FROM messaging_groups mg JOIN messaging_group_agents mga ON mg.id = mga.messaging_group_id JOIN agent_groups ag ON ag.id = mga.agent_group_id WHERE mg.channel_type = 'emacs'"`
+3. Logs show inbound: `grep 'channel_type=emacs\|Emacs' logs/nanoclaw.log | tail -20`
+
+If no messaging group row exists, run the `register` command above.
+
+### Auth token mismatch (401 Unauthorized)
+
+```elisp
+M-x describe-variable RET nanoclaw-auth-token RET
+```
+
+Must match `EMACS_AUTH_TOKEN` in `.env`. If you didn't set one server-side, clear it in Emacs too:
+
+```elisp
+(setq nanoclaw-auth-token nil)
+```
+
+### nanoclaw.el not loading
+
+```bash
+ls ~/src/nanoclaw/emacs/nanoclaw.el
+```
+
+If NanoClaw is cloned elsewhere, update the `load`/`load-file` path in your Emacs config.
+
+## Agent Formatting
+
+The Emacs bridge converts markdown → org-mode automatically. Agents should output standard markdown, **not** org-mode syntax:
+
+| Markdown | Org-mode |
+|----------|----------|
+| `**bold**` | `*bold*` |
+| `*italic*` | `/italic/` |
+| `~~text~~` | `+text+` |
+| `` `code` `` | `~code~` |
+| ` ```lang ` | `#+begin_src lang` |
+
+If an agent outputs org-mode directly, markers get double-converted and render incorrectly.
+
+## Removal
+
+```bash
+rm src/channels/emacs.ts src/channels/emacs.test.ts emacs/nanoclaw.el
+# Remove the `import './emacs.js';` line from src/channels/index.ts
+# Remove EMACS_* lines from .env
+pnpm run build
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw   # macOS
+# systemctl --user restart nanoclaw                # Linux
+
+# Remove the NanoClaw block from your Emacs config
+# Optionally clean up the messaging group:
+sqlite3 data/v2.db "DELETE FROM messaging_group_agents WHERE messaging_group_id IN (SELECT id FROM messaging_groups WHERE channel_type='emacs'); DELETE FROM messaging_groups WHERE channel_type='emacs';"
+```

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

@@ -0,0 +1,210 @@
+---
+name: add-gcal-tool
+description: Add Google Calendar as an MCP tool (list calendars, list/search/create events, free/busy queries) using OneCLI-managed OAuth. Multi-calendar and multi-account supported. Mirrors /add-gmail-tool's stub pattern — no raw credentials ever reach the container; OneCLI injects real tokens at request time.
+---
+
+# Add Google Calendar Tool (OneCLI-native)
+
+This skill wires [`@cocal/google-calendar-mcp`](https://github.com/cocal-com/google-calendar-mcp) into selected agent groups. The MCP server reads stub credentials containing the `onecli-managed` placeholder; the OneCLI gateway intercepts outbound calls to `calendar.googleapis.com` / `oauth2.googleapis.com` and swaps the bearer for the real OAuth token from its vault.
+
+**Why this package (and not gongrzhe's):** `@gongrzhe/server-calendar-autoauth-mcp` only supports the `primary` calendar and exposes 5 tools (no `list_calendars`). `@cocal/google-calendar-mcp` explicitly supports multi-calendar and multi-account, and is actively maintained.
+
+Tools exposed (surfaced as `mcp__calendar__<name>`, exact set depends on version — run `tools/list` against the MCP server to enumerate): `list-calendars`, `list-events`, `search-events`, `create-event`, `update-event`, `delete-event`, `get-event`, `list-colors`, `get-freebusy`, `get-current-time`, plus multi-account management tools.
+
+**Why this pattern:** v2's invariant is that containers never receive raw API keys (CHANGELOG 2.0.0). Same stub pattern `/add-gmail-tool` uses. This skill is deliberately a sibling, not a combined "Google Workspace" skill — installs independently and removes cleanly.
+
+## Phase 1: Pre-flight
+
+### Verify OneCLI has Google Calendar connected
+
+```bash
+onecli apps get --provider google-calendar
+```
+
+Expected: `"connection": { "status": "connected" }` with scopes including `calendar.readonly` and `calendar.events`.
+
+If not connected, tell the user:
+
+> Open the OneCLI web UI at http://127.0.0.1:10254, go to Apps → Google Calendar, and click Connect. Sign in with the Google account the agent should act as. `calendar.readonly` + `calendar.events` are the minimum useful scopes.
+
+### Verify stub credentials exist
+
+The stub lives at `~/.calendar-mcp/` by convention (shared with `/add-gmail-tool`'s sibling). cocal doesn't default to this path (it uses `~/.config/google-calendar-mcp/tokens.json`) — we override via env vars below so it reads our stubs instead.
+
+```bash
+ls -la ~/.calendar-mcp/gcp-oauth.keys.json ~/.calendar-mcp/credentials.json 2>&1
+```
+
+If both exist with `onecli-managed`:
+
+```bash
+grep -l onecli-managed ~/.calendar-mcp/gcp-oauth.keys.json ~/.calendar-mcp/credentials.json
+```
+
+...skip to Phase 2. If either file has real credentials (no `onecli-managed`), **STOP** — back up and delete before proceeding.
+
+If absent, write them:
+
+```bash
+mkdir -p ~/.calendar-mcp
+cat > ~/.calendar-mcp/gcp-oauth.keys.json <<'EOF'
+{
+  "installed": {
+    "client_id": "onecli-managed.apps.googleusercontent.com",
+    "client_secret": "onecli-managed",
+    "redirect_uris": ["http://localhost:3000/oauth2callback"]
+  }
+}
+EOF
+cat > ~/.calendar-mcp/credentials.json <<'EOF'
+{
+  "access_token": "onecli-managed",
+  "refresh_token": "onecli-managed",
+  "token_type": "Bearer",
+  "expiry_date": 99999999999999,
+  "scope": "https://www.googleapis.com/auth/calendar.readonly https://www.googleapis.com/auth/calendar.events"
+}
+EOF
+chmod 600 ~/.calendar-mcp/*.json
+```
+
+### Verify mount allowlist covers the path
+
+```bash
+cat ~/.config/nanoclaw/mount-allowlist.json
+```
+
+`~/.calendar-mcp` must sit under an `allowedRoots` entry.
+
+### Check agent secret-mode
+
+For each target agent group, confirm OneCLI will inject the Google Calendar token:
+
+```bash
+onecli agents list
+```
+
+`secretMode: all` is sufficient. If `selective`, explicitly assign the Calendar secret.
+
+## Phase 2: Apply Code Changes
+
+### Check if already applied
+
+```bash
+grep -q 'CALENDAR_MCP_VERSION' container/Dockerfile && \
+grep -q "mcp__calendar__\*" container/agent-runner/src/providers/claude.ts && \
+echo "ALREADY APPLIED — skip to Phase 3"
+```
+
+### Add MCP server to Dockerfile
+
+Edit `container/Dockerfile`. Find the pinned-version ARG block and add:
+
+```dockerfile
+ARG CALENDAR_MCP_VERSION=2.6.1
+```
+
+If `/add-gmail-tool` has already been applied, the pnpm global-install block already exists with its `zod-to-json-schema@3.22.5` pin. Just append the calendar package — **the calendar-mcp uses `zod@4.x` and does NOT need that pin**, but it's harmless to share the block:
+
+```dockerfile
+RUN --mount=type=cache,target=/root/.cache/pnpm \
+    pnpm install -g \
+        "@gongrzhe/server-gmail-autoauth-mcp@${GMAIL_MCP_VERSION}" \
+        "@cocal/google-calendar-mcp@${CALENDAR_MCP_VERSION}" \
+        "zod-to-json-schema@3.22.5"
+```
+
+If `/add-gmail-tool` hasn't been applied, install Calendar standalone:
+
+```dockerfile
+RUN --mount=type=cache,target=/root/.cache/pnpm \
+    pnpm install -g "@cocal/google-calendar-mcp@${CALENDAR_MCP_VERSION}"
+```
+
+### Add tools to allowlist
+
+Edit `container/agent-runner/src/providers/claude.ts`. Add `'mcp__calendar__*'` to `TOOL_ALLOWLIST` after `'mcp__nanoclaw__*'` (or after `'mcp__gmail__*'` if present).
+
+### Rebuild the container image
+
+```bash
+./container/build.sh
+```
+
+## Phase 3: Wire Per-Agent-Group
+
+For each agent group, merge into `groups/<folder>/container.json`:
+
+```jsonc
+{
+  "mcpServers": {
+    "calendar": {
+      "command": "google-calendar-mcp",
+      "args": [],
+      "env": {
+        "GOOGLE_OAUTH_CREDENTIALS": "/workspace/extra/.calendar-mcp/gcp-oauth.keys.json",
+        "GOOGLE_CALENDAR_MCP_TOKEN_PATH": "/workspace/extra/.calendar-mcp/credentials.json"
+      }
+    }
+  },
+  "additionalMounts": [
+    {
+      "hostPath": "/home/<user>/.calendar-mcp",
+      "containerPath": ".calendar-mcp",
+      "readonly": false
+    }
+  ]
+}
+```
+
+Substitute `<user>` with `echo $HOME`. `containerPath` is relative (mount-security rejects absolute paths — additional mounts land at `/workspace/extra/<relative>`).
+
+**Same-group-as-gmail tip:** if this group already has the gmail MCP + `.gmail-mcp` mount, **merge, don't replace** — both entries coexist in `mcpServers` and `additionalMounts`.
+
+## Phase 4: Build and Restart
+
+```bash
+pnpm run build
+systemctl --user restart nanoclaw   # Linux
+# launchctl kickstart -k gui/$(id -u)/com.nanoclaw   # macOS
+```
+
+Kill any existing agent containers so they respawn with the new mcpServers config:
+
+```bash
+docker ps -q --filter 'name=nanoclaw-v2-' | xargs -r docker kill
+```
+
+## Phase 5: Verify
+
+### Test from a wired agent
+
+> Send: **"list my calendars"** or **"what's on my work calendar next Monday?"**.
+>
+> First call takes 2–3s while the MCP server starts and OneCLI does the token exchange.
+
+### Check logs if the tool isn't working
+
+```bash
+tail -100 logs/nanoclaw.log | grep -iE 'calendar|mcp'
+```
+
+Common signals:
+- `command not found: google-calendar-mcp` → image not rebuilt.
+- `ENOENT ...credentials.json` → mount missing. Check the mount allowlist.
+- `401 Unauthorized` from `*.googleapis.com` → OneCLI isn't injecting; verify agent's secret mode and that Google Calendar is connected.
+- Agent says "I don't have calendar tools" → `mcp__calendar__*` missing from `TOOL_ALLOWLIST`, or image cache stale (`./container/build.sh` again).
+
+## Removal
+
+1. Delete `"calendar"` from `mcpServers` and the `.calendar-mcp` mount from `additionalMounts` in each group's `container.json`.
+2. Remove `'mcp__calendar__*'` from `TOOL_ALLOWLIST`.
+3. Remove `CALENDAR_MCP_VERSION` ARG and the calendar package from the Dockerfile install block.
+4. `pnpm run build && ./container/build.sh && systemctl --user restart nanoclaw`.
+5. Optional: `rm -rf ~/.calendar-mcp/` and `onecli apps disconnect --provider google-calendar`.
+
+## Credits & references
+
+- **MCP server:** [`@cocal/google-calendar-mcp`](https://github.com/cocal-com/google-calendar-mcp) — MIT-licensed, actively maintained, multi-account and multi-calendar.
+- **Why not gongrzhe:** earlier versions of this skill used `@gongrzhe/server-calendar-autoauth-mcp@1.0.2` which only supports the primary calendar with 5 event-level tools. The cocal server supersedes it.
+- **Skill pattern:** direct sibling of [`/add-gmail-tool`](../add-gmail-tool/SKILL.md); same OneCLI stub mechanism.

.claude/skills/add-gchat/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/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: add-gchat
+description: Add Google Chat channel integration via Chat SDK.
+---
+
+# Add Google Chat Channel
+
+Adds Google Chat support via the Chat SDK bridge.
+
+## Install
+
+NanoClaw doesn't ship channels in trunk. This skill copies the Google Chat adapter in from the `channels` branch.
+
+### Pre-flight (idempotent)
+
+Skip to **Credentials** if all of these are already in place:
+
+- `src/channels/gchat.ts` exists
+- `src/channels/index.ts` contains `import './gchat.js';`
+- `@chat-adapter/gchat` is listed in `package.json` dependencies
+
+Otherwise continue. Every step below is safe to re-run.
+
+### 1. Fetch the channels branch
+
+```bash
+git fetch origin channels
+```
+
+### 2. Copy the adapter
+
+```bash
+git show origin/channels:src/channels/gchat.ts > src/channels/gchat.ts
+```
+
+### 3. Append the self-registration import
+
+Append to `src/channels/index.ts` (skip if the line is already present):
+
+```typescript
+import './gchat.js';
+```
+
+### 4. Install the adapter package (pinned)
+
+```bash
+pnpm install @chat-adapter/gchat@4.26.0
+```
+
+### 5. Build
+
+```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/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/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/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: add-github
+description: Add GitHub channel integration via Chat SDK. PR and issue comment threads as conversations.
+---
+
+# Add GitHub Channel
+
+Adds GitHub support via the Chat SDK bridge. The agent participates in PR and issue comment threads.
+
+## Prerequisites
+
+You need a **dedicated GitHub bot account** (not your personal account). The adapter uses this account to post replies and filters out its own messages to avoid loops. Create a free GitHub account for your bot (e.g. `my-org-bot`), then invite it as a collaborator with write access to the repos you want monitored.
+
+## Install
+
+NanoClaw doesn't ship channels in trunk. This skill copies the GitHub adapter in from the `channels` branch.
+
+### Pre-flight (idempotent)
+
+Skip to **Credentials** if all of these are already in place:
+
+- `src/channels/github.ts` exists
+- `src/channels/index.ts` contains `import './github.js';`
+- `@chat-adapter/github` is listed in `package.json` dependencies
+
+Otherwise continue. Every step below is safe to re-run.
+
+### 1. Fetch the channels branch
+
+```bash
+git fetch origin channels
+```
+
+### 2. Copy the adapter
+
+```bash
+git show origin/channels:src/channels/github.ts > src/channels/github.ts
+```
+
+### 3. Append the self-registration import
+
+Append to `src/channels/index.ts` (skip if the line is already present):
+
+```typescript
+import './github.js';
+```
+
+### 4. Install the adapter package (pinned)
+
+```bash
+pnpm install @chat-adapter/github@4.26.0
+```
+
+### 5. Build
+
+```bash
+pnpm run build
+```
+
+## Credentials
+
+### 1. Create a Personal Access Token for the bot account
+
+Log in as your **bot account**, then:
+
+1. Go to [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
+
+### 2. Set up a webhook on each repo
+
+On each repo (logged in as the repo owner/admin):
+
+1. Go to **Settings** > **Webhooks** > **Add webhook**
+2. Payload URL: `https://your-domain/webhook/github` (the shared webhook server, default port 3000)
+3. Content type: `application/json`
+4. Secret: generate a random string (e.g. `openssl rand -hex 20`)
+5. Events: select **Issue comments** and **Pull request review comments**
+
+### 3. Configure environment
+
+Add to `.env`:
+
+```bash
+GITHUB_TOKEN=github_pat_...
+GITHUB_WEBHOOK_SECRET=your-webhook-secret
+GITHUB_BOT_USERNAME=your-bot-username
+```
+
+`GITHUB_BOT_USERNAME` must match the bot account's GitHub username exactly. This is used for @-mention detection — the agent responds when someone writes `@your-bot-username` in a PR or issue comment.
+
+Sync to container: `mkdir -p data/env && cp .env data/env/env`
+
+## Wiring
+
+Ask the user: **Is this a private or public repo?**
+
+- **Private repo** — use `unknown_sender_policy: 'public'`. Only collaborators can comment anyway, so it's safe to let all comments through.
+- **Public repo** — use `unknown_sender_policy: 'strict'`. Only registered members can trigger the agent, preventing strangers from consuming agent resources. Add trusted collaborators as members (see below).
+
+Run `/manage-channels` to wire the GitHub channel to an agent group, or insert manually:
+
+```sql
+-- Create messaging group (one per repo)
+INSERT INTO messaging_groups (id, channel_type, platform_id, name, is_group, unknown_sender_policy, created_at)
+VALUES ('mg-github-myrepo', 'github', 'github:owner/repo', 'owner/repo', 1, '<policy>', datetime('now'));
+
+-- Wire to agent group
+INSERT INTO messaging_group_agents (id, messaging_group_id, agent_group_id, trigger_rules, response_scope, session_mode, priority, created_at)
+VALUES ('mga-github-myrepo', 'mg-github-myrepo', '<your-agent-group-id>', '', 'all', 'per-thread', 10, datetime('now'));
+```
+
+Replace `<policy>` with `public` or `strict` based on the user's choice above.
+
+### Adding members (for strict mode)
+
+When using `strict`, add each GitHub user who should be able to trigger the agent:
+
+```sql
+-- Add user (kind = 'github', id = 'github:<numeric-user-id>')
+INSERT OR IGNORE INTO users (id, kind, display_name, created_at)
+VALUES ('github:<user-id>', 'github', '<username>', datetime('now'));
+
+-- Grant membership to the agent group
+INSERT OR IGNORE INTO agent_group_members (user_id, agent_group_id)
+VALUES ('github:<user-id>', '<agent-group-id>');
+```
+
+To find a GitHub user's numeric ID: `gh api users/<username> --jq .id`
+
+Use `per-thread` session mode so each PR/issue gets its own agent session.
+
+## Next Steps
+
+If you're in the middle of `/setup`, return to the setup flow now.
+
+Otherwise, restart the service (`systemctl --user restart nanoclaw` or `launchctl kickstart -k gui/$(id -u)/com.nanoclaw`) to pick up the new channel.
+
+## 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 `github:owner/repo` (e.g. `github:acme/backend`). Each PR/issue becomes its own thread automatically.
+- **supports-threads**: yes (PR and issue comment threads are native conversations)
+- **typical-use**: Webhook-driven — the agent receives PR and issue comment events and responds in comment threads when @-mentioned. After the first mention, the thread is subscribed and the agent responds to all follow-up comments.
+- **default-isolation**: Use `per-thread` session mode. Each PR or issue gets its own isolated agent session. Typically wire to a dedicated agent group if the repo contains sensitive code.

.claude/skills/add-github/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-tool/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: add-gmail-tool
+description: Add Gmail as an MCP tool (read, search, send, label, draft) using OneCLI-managed OAuth. The agent gets Gmail tools in every enabled group; OneCLI injects real tokens at request time so no raw credentials are ever in the container or on disk in usable form.
+---
+
+# Add Gmail Tool (OneCLI-native)
+
+This skill wires the [`@gongrzhe/server-gmail-autoauth-mcp`](https://www.npmjs.com/package/@gongrzhe/server-gmail-autoauth-mcp) stdio MCP server into selected agent groups. The MCP server reads stub credentials containing the `onecli-managed` placeholder; the OneCLI gateway intercepts outbound calls to `gmail.googleapis.com` and injects the real OAuth bearer from its vault.
+
+Tools exposed (from `gmail-mcp@1.1.11`, surfaced to the agent as `mcp__gmail__<name>`): `search_emails`, `read_email`, `send_email`, `draft_email`, `delete_email`, `modify_email`, `batch_modify_emails`, `batch_delete_emails`, `download_attachment`, `list_email_labels`, `create_label`, `update_label`, `delete_label`, `get_or_create_label`, `list_filters`, `get_filter`, `create_filter`, `create_filter_from_template`, `delete_filter`.
+
+**Why this pattern:** v2's invariant is that containers never receive raw API keys — OneCLI is the sole credential path (see CHANGELOG v2.0.0). The stub-file pattern satisfies this: the container sees `"onecli-managed"` placeholders, the gateway swaps them in flight.
+
+## Phase 1: Pre-flight
+
+### Verify OneCLI has Gmail connected
+
+```bash
+onecli apps get --provider gmail
+```
+
+Expected: `"connection": { "status": "connected" }` with scopes including `gmail.readonly`, `gmail.modify`, `gmail.send`.
+
+If not connected, tell the user:
+
+> Open the OneCLI web UI at http://127.0.0.1:10254, go to Apps → Gmail, and click Connect. Sign in with the Google account you want the agent to act as.
+
+### Verify stub credentials exist
+
+```bash
+ls -la ~/.gmail-mcp/gcp-oauth.keys.json ~/.gmail-mcp/credentials.json 2>&1
+```
+
+If both exist and contain `"onecli-managed"`:
+
+```bash
+grep -l onecli-managed ~/.gmail-mcp/gcp-oauth.keys.json ~/.gmail-mcp/credentials.json
+```
+
+...skip to Phase 2.
+
+If either file exists but does **not** contain `onecli-managed`, **STOP** and tell the user — these are real OAuth credentials from a previous non-OneCLI install. Back them up, then delete before proceeding. The OneCLI migration normally handles this; if it didn't, something is wrong.
+
+If both files are absent, write them now:
+
+```bash
+mkdir -p ~/.gmail-mcp
+cat > ~/.gmail-mcp/gcp-oauth.keys.json <<'EOF'
+{
+  "installed": {
+    "client_id": "onecli-managed.apps.googleusercontent.com",
+    "client_secret": "onecli-managed",
+    "redirect_uris": ["http://localhost:3000/oauth2callback"]
+  }
+}
+EOF
+cat > ~/.gmail-mcp/credentials.json <<'EOF'
+{
+  "access_token": "onecli-managed",
+  "refresh_token": "onecli-managed",
+  "token_type": "Bearer",
+  "expiry_date": 99999999999999,
+  "scope": "https://www.googleapis.com/auth/gmail.readonly https://www.googleapis.com/auth/gmail.modify https://www.googleapis.com/auth/gmail.send"
+}
+EOF
+chmod 600 ~/.gmail-mcp/gcp-oauth.keys.json ~/.gmail-mcp/credentials.json
+```
+
+### Verify mount allowlist covers the path
+
+```bash
+cat ~/.config/nanoclaw/mount-allowlist.json
+```
+
+`~/.gmail-mcp` must sit under an `allowedRoots` entry (e.g. `/home/<user>`). If it doesn't, tell the user to run `/manage-mounts` first or add their home directory.
+
+### Check agent secret-mode
+
+For each target agent group, confirm OneCLI will inject Gmail secrets into its container. Find the OneCLI agent ID that matches the group's `agentGroupId`:
+
+```bash
+onecli agents list
+```
+
+If that agent's `secretMode` is `all`, you're done — Gmail secrets (identified by OneCLI's Gmail hostPattern) will auto-inject. If it's `selective`, explicitly assign the Gmail secrets:
+
+```bash
+onecli secrets list     # find Gmail secret IDs (OneCLI creates one per connected app)
+onecli agents set-secrets --id <agent-id> --secret-ids <gmail-secret-id>
+```
+
+## Phase 2: Apply Code Changes
+
+### Check if already applied
+
+```bash
+grep -q 'GMAIL_MCP_VERSION' container/Dockerfile && \
+grep -q "mcp__gmail__\*" container/agent-runner/src/providers/claude.ts && \
+echo "ALREADY APPLIED — skip to Phase 3"
+```
+
+### Add MCP server to Dockerfile
+
+Edit `container/Dockerfile`. Find the pinned-version ARG block:
+
+```dockerfile
+ARG CLAUDE_CODE_VERSION=2.1.116
+ARG AGENT_BROWSER_VERSION=latest
+ARG VERCEL_VERSION=latest
+ARG BUN_VERSION=1.3.12
+```
+
+Add a new line:
+
+```dockerfile
+ARG GMAIL_MCP_VERSION=1.1.11
+```
+
+Then find the last pnpm global-install `RUN` block (the one that installs `@anthropic-ai/claude-code`) and add a new block after it, before `# ---- Entrypoint`:
+
+```dockerfile
+RUN --mount=type=cache,target=/root/.cache/pnpm \
+    pnpm install -g \
+        "@gongrzhe/server-gmail-autoauth-mcp@${GMAIL_MCP_VERSION}" \
+        "zod-to-json-schema@3.22.5"
+```
+
+Pinned version matters — `minimumReleaseAge` in `pnpm-workspace.yaml` gates trunk installs, and CLAUDE.md requires a fixed ARG version for all Node CLIs installed into the image.
+
+**Why the `zod-to-json-schema` pin:** `@gongrzhe/server-gmail-autoauth-mcp@1.1.11` has loose deps (`zod-to-json-schema: ^3.22.1`, `zod: ^3.22.4`). pnpm resolves `zod-to-json-schema` to the latest 3.25.x, which imports `zod/v3` — a subpath that only exists in `zod>=3.25`. But `zod` resolves to `3.24.x` (highest satisfying `^3.22.4` without breaking peer ranges). Result: `ERR_PACKAGE_PATH_NOT_EXPORTED` at import time. Pinning `zod-to-json-schema` to a pre-v3-subpath version avoids it. Re-check if you bump `GMAIL_MCP_VERSION`.
+
+### Add tools to allowlist
+
+Edit `container/agent-runner/src/providers/claude.ts`. Find `'mcp__nanoclaw__*',` in `TOOL_ALLOWLIST` and add `'mcp__gmail__*',` after it.
+
+### Rebuild the container image
+
+```bash
+./container/build.sh
+```
+
+Must complete cleanly. The new `pnpm install -g` layer is ~60s first time (cached on rebuild).
+
+## Phase 3: Wire Per-Agent-Group
+
+For each agent group that should have Gmail (ask the user — typically their personal DM and CLI agents, sometimes shared household agents), edit `groups/<folder>/container.json` to add the mount and MCP server.
+
+Merge these into the group's `container.json`:
+
+```jsonc
+{
+  "mcpServers": {
+    "gmail": {
+      "command": "gmail-mcp",
+      "args": [],
+      "env": {
+        "GMAIL_OAUTH_PATH": "/workspace/extra/.gmail-mcp/gcp-oauth.keys.json",
+        "GMAIL_CREDENTIALS_PATH": "/workspace/extra/.gmail-mcp/credentials.json"
+      }
+    }
+  },
+  "additionalMounts": [
+    {
+      "hostPath": "/home/<user>/.gmail-mcp",
+      "containerPath": ".gmail-mcp",
+      "readonly": false
+    }
+  ]
+}
+```
+
+Substitute `<user>` with the host user's home (use `echo $HOME`, don't assume `~` will expand — `container-runner.ts` does expand `~` via `expandPath`, but an explicit absolute path is clearer and matches what `/manage-mounts` writes).
+
+**Why the container path is relative:** `mount-security` rejects absolute `containerPath` values. Additional mounts are prefixed with `/workspace/extra/`, so `containerPath: ".gmail-mcp"` lands at `/workspace/extra/.gmail-mcp`. The MCP server's `GMAIL_OAUTH_PATH` / `GMAIL_CREDENTIALS_PATH` env vars point at that absolute location inside the container.
+
+## Phase 4: Build and Restart
+
+```bash
+pnpm run build
+systemctl --user restart nanoclaw  # Linux
+# launchctl kickstart -k gui/$(id -u)/com.nanoclaw   # macOS
+```
+
+## Phase 5: Verify
+
+### Test from the wired agent
+
+Tell the user:
+
+> In your `<agent-name>` chat, send: **"list my gmail labels"** or **"search my inbox for invoices from last month"**.
+>
+> The agent should use `mcp__gmail__list_labels` / `mcp__gmail__search`. The first call may take a second or two while the MCP server starts and OneCLI does the token exchange.
+
+### Check logs if the tool isn't working
+
+```bash
+tail -100 logs/nanoclaw.log logs/nanoclaw.error.log | grep -iE 'gmail|mcp'
+# Per-container logs — session-scoped:
+ls data/v2-sessions/*/stderr.log | head
+```
+
+Common signals:
+- `command not found: gmail-mcp` → image wasn't rebuilt or PATH doesn't include `/pnpm` (should — `ENV PATH="$PNPM_HOME:$PATH"` in Dockerfile).
+- `ENOENT: no such file or directory, open '/workspace/extra/.gmail-mcp/credentials.json'` → mount is missing. Check `~/.config/nanoclaw/mount-allowlist.json` includes a parent of `~/.gmail-mcp`.
+- `401 Unauthorized` from `gmail.googleapis.com` → OneCLI isn't injecting. Check the agent's secret mode (`onecli agents secrets --id <agent-id>`) and that the Gmail app is connected (`onecli apps get --provider gmail`).
+- Agent says "I don't have Gmail tools" → `mcp__gmail__*` wasn't added to `TOOL_ALLOWLIST`, or the agent-runner wasn't rebuilt (image cache — run `./container/build.sh` again with `--no-cache` if suspicious).
+
+## Removal
+
+1. Delete the `"gmail"` entry from `mcpServers` and the `.gmail-mcp` entry from `additionalMounts` in each group's `container.json`.
+2. Remove `'mcp__gmail__*'` from `TOOL_ALLOWLIST` in `container/agent-runner/src/providers/claude.ts`.
+3. Remove the `GMAIL_MCP_VERSION` ARG and the `pnpm install -g @gongrzhe/server-gmail-autoauth-mcp` block from `container/Dockerfile`.
+4. `pnpm run build && ./container/build.sh && systemctl --user restart nanoclaw`.
+5. (Optional) `rm -rf ~/.gmail-mcp/` if no other host-side tool needs the stubs.
+6. (Optional) Disconnect Gmail in OneCLI: `onecli apps disconnect --provider gmail`.
+
+## Notes
+
+- **Stub format is OneCLI-prescribed.** The `access_token: "onecli-managed"` pattern with `expiry_date: 99999999999999` tells the Google auth client the token is valid; OneCLI intercepts the outgoing Gmail API call and rewrites `Authorization: Bearer onecli-managed` to the real token. `expiry_date: 0` (refresh-interception) is an alternative the OneCLI docs describe — both work but OneCLI's own `migrate` command writes the far-future variant, which is what this skill assumes.
+- **Scopes are set at OAuth connect time.** If the agent needs scopes beyond what's currently connected (e.g. the user later wants `calendar.readonly` for combined email/calendar workflows), disconnect and reconnect Gmail in the OneCLI web UI with the expanded scope set.
+- **This is tool-only.** Inbound email as a channel (emails trigger the agent) is a separate piece of work — it needs a `src/channels/gmail.ts` adapter that polls the inbox and routes to a messaging group. The pre-v2 qwibitai skill had this; it has not been ported to v2's channel architecture as of v2.0.0.
+
+## Credits & references
+
+- **MCP server:** [`@gongrzhe/server-gmail-autoauth-mcp`](https://github.com/GongRzhe/Gmail-MCP-Server) by GongRzhe — MIT-licensed.
+- **OneCLI credential stubs:** pattern documented at `https://onecli.sh/docs/guides/credential-stubs/gmail.md`.
+- **Skill pattern:** modeled on [`add-atomic-chat-tool`](../add-atomic-chat-tool/SKILL.md) and [`add-vercel`](../add-vercel/SKILL.md).
+- **Addresses:** [issue #1500](https://github.com/qwibitai/nanoclaw/issues/1500) (proxy Gmail/Calendar OAuth tokens through credential proxy) for the Gmail side.
+- **Related PRs:** [#1810](https://github.com/qwibitai/nanoclaw/pull/1810) (pre-install Gmail/Notion MCP) overlaps on the "install the MCP server in the image" idea but bundles many unrelated changes; this skill is the focused OneCLI-native version.

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

@@ -1,242 +0,0 @@
----
-name: add-gmail
-description: Add Gmail integration to NanoClaw. Can be configured as a tool (agent reads/sends emails when triggered from WhatsApp) or as a full channel (emails can trigger the agent, schedule tasks, and receive replies). Guides through GCP OAuth setup and implements the integration.
----
-
-# Add Gmail Integration
-
-This skill adds Gmail support to NanoClaw — either as a tool (read, send, search, draft) or as a full channel that polls the inbox.
-
-## Phase 1: Pre-flight
-
-### 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.
-
-### Ask the user
-
-Use `AskUserQuestion`:
-
-AskUserQuestion: Should incoming emails be able to trigger the agent?
-
-- **Yes** — Full channel mode: the agent listens on Gmail and responds to incoming emails automatically
-- **No** — Tool-only: the agent gets full Gmail tools (read, send, search, draft) but won't monitor the inbox. No channel code is added.
-
-## Phase 2: Apply Code Changes
-
-### Initialize skills system (if needed)
-
-If `.nanoclaw/` directory doesn't exist yet:
-
-```bash
-npx tsx scripts/apply-skill.ts --init
-```
-
-### 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
-
-```bash
-npm run build
-```
-
-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:
-
-```bash
-npx tsx scripts/apply-skill.ts .claude/skills/add-gmail
-```
-
-This deterministically:
-
-- 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 apply reports merge conflicts, read the intent files:
-
-- `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):
-
-```markdown
-## Email Notifications
-
-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
-
-```bash
-npm test
-npm run build
-```
-
-All tests must pass (including the new gmail tests) and build must be clean before proceeding.
-
-## Phase 3: Setup
-
-### Check existing Gmail credentials
-
-```bash
-ls -la ~/.gmail-mcp/ 2>/dev/null || echo "No Gmail config found"
-```
-
-If `credentials.json` already exists, skip to "Build and restart" below.
-
-### GCP Project Setup
-
-Tell the user:
-
-> I need you to set up Google Cloud OAuth credentials:
->
-> 1. Open https://console.cloud.google.com — create a new project or select existing
-> 2. Go to **APIs & Services > Library**, search "Gmail API", click **Enable**
-> 3. Go to **APIs & Services > Credentials**, click **+ CREATE CREDENTIALS > OAuth client ID**
->    - If prompted for consent screen: choose "External", fill in app name and email, save
->    - Application type: **Desktop app**, name: anything (e.g., "NanoClaw Gmail")
-> 4. Click **DOWNLOAD JSON** and save as `gcp-oauth.keys.json`
->
-> Where did you save the file? (Give me the full path, or paste the file contents here)
-
-If user provides a path, copy it:
-
-```bash
-mkdir -p ~/.gmail-mcp
-cp "/path/user/provided/gcp-oauth.keys.json" ~/.gmail-mcp/gcp-oauth.keys.json
-```
-
-If user pastes JSON content, write it to `~/.gmail-mcp/gcp-oauth.keys.json`.
-
-### OAuth Authorization
-
-Tell the user:
-
-> I'm going to run Gmail authorization. A browser window will open — sign in and grant access. If you see an "app isn't verified" warning, click "Advanced" then "Go to [app name] (unsafe)" — this is normal for personal OAuth apps.
-
-Run the authorization:
-
-```bash
-npx -y @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`.
-
-### Build and restart
-
-Clear stale per-group agent-runner copies (they only get re-created if missing, so existing copies won't pick up the new Gmail server):
-
-```bash
-rm -r data/sessions/*/agent-runner-src 2>/dev/null || true
-```
-
-Rebuild the container (agent-runner changed):
-
-```bash
-cd container && ./build.sh
-```
-
-Then compile and restart:
-
-```bash
-npm run build
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
-# Linux: systemctl --user restart nanoclaw
-```
-
-## Phase 4: Verify
-
-### Test tool access (both modes)
-
-Tell the user:
-
-> Gmail is connected! Send this in your main channel:
->
-> `@Andy check my recent emails` or `@Andy list my Gmail labels`
-
-### Test channel mode (Channel mode only)
-
-Tell the user to send themselves a test email. The agent should pick it up within a minute. Monitor: `tail -f logs/nanoclaw.log | grep -iE "(gmail|email)"`.
-
-Once verified, offer filter customization via `AskUserQuestion` — by default, only emails in the Primary inbox trigger the agent (Promotions, Social, Updates, and Forums are excluded). The user can keep this default or narrow further by sender, label, or keywords. No code changes needed for filters.
-
-### Check logs if needed
-
-```bash
-tail -f logs/nanoclaw.log
-```
-
-## Troubleshooting
-
-### Gmail connection not responding
-
-Test directly:
-
-```bash
-npx -y @gongrzhe/server-gmail-autoauth-mcp
-```
-
-### OAuth token expired
-
-Re-authorize:
-
-```bash
-rm ~/.gmail-mcp/credentials.json
-npx -y @gongrzhe/server-gmail-autoauth-mcp
-```
-
-### Container can't access Gmail
-
-- Verify `~/.gmail-mcp` is mounted: check `src/container-runner.ts` for the `.gmail-mcp` mount
-- Check container logs: `cat groups/main/logs/container-*.log | tail -50`
-
-### Emails not being detected (Channel mode only)
-
-- By default, the channel polls unread Primary inbox emails (`is:unread category:primary`)
-- Check logs for Gmail polling errors
-
-## Removal
-
-### Tool-only mode
-
-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`
-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)
-
-### Channel mode
-
-1. Delete `src/channels/gmail.ts` and `src/channels/gmail.test.ts`
-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`
-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)

.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

@@ -1,593 +0,0 @@
-/**
- * NanoClaw Agent Runner
- * Runs inside a container, receives config via stdin, outputs result to stdout
- *
- * Input protocol:
- *   Stdin: Full ContainerInput JSON (read until EOF, like before)
- *   IPC:   Follow-up messages written as JSON files to /workspace/ipc/input/
- *          Files: {type:"message", text:"..."}.json — polled and consumed
- *          Sentinel: /workspace/ipc/input/_close — signals session end
- *
- * Stdout protocol:
- *   Each result is wrapped in OUTPUT_START_MARKER / OUTPUT_END_MARKER pairs.
- *   Multiple results may be emitted (one per agent teams result).
- *   Final marker after loop ends signals completion.
- */
-
-import fs from 'fs';
-import path from 'path';
-import { query, HookCallback, PreCompactHookInput, PreToolUseHookInput } from '@anthropic-ai/claude-agent-sdk';
-import { fileURLToPath } from 'url';
-
-interface ContainerInput {
-  prompt: string;
-  sessionId?: string;
-  groupFolder: string;
-  chatJid: string;
-  isMain: boolean;
-  isScheduledTask?: boolean;
-  assistantName?: string;
-  secrets?: Record<string, string>;
-}
-
-interface ContainerOutput {
-  status: 'success' | 'error';
-  result: string | null;
-  newSessionId?: string;
-  error?: string;
-}
-
-interface SessionEntry {
-  sessionId: string;
-  fullPath: string;
-  summary: string;
-  firstPrompt: string;
-}
-
-interface SessionsIndex {
-  entries: SessionEntry[];
-}
-
-interface SDKUserMessage {
-  type: 'user';
-  message: { role: 'user'; content: string };
-  parent_tool_use_id: null;
-  session_id: string;
-}
-
-const IPC_INPUT_DIR = '/workspace/ipc/input';
-const IPC_INPUT_CLOSE_SENTINEL = path.join(IPC_INPUT_DIR, '_close');
-const IPC_POLL_MS = 500;
-
-/**
- * Push-based async iterable for streaming user messages to the SDK.
- * Keeps the iterable alive until end() is called, preventing isSingleUserTurn.
- */
-class MessageStream {
-  private queue: SDKUserMessage[] = [];
-  private waiting: (() => void) | null = null;
-  private done = false;
-
-  push(text: string): void {
-    this.queue.push({
-      type: 'user',
-      message: { role: 'user', content: text },
-      parent_tool_use_id: null,
-      session_id: '',
-    });
-    this.waiting?.();
-  }
-
-  end(): void {
-    this.done = true;
-    this.waiting?.();
-  }
-
-  async *[Symbol.asyncIterator](): AsyncGenerator<SDKUserMessage> {
-    while (true) {
-      while (this.queue.length > 0) {
-        yield this.queue.shift()!;
-      }
-      if (this.done) return;
-      await new Promise<void>(r => { this.waiting = r; });
-      this.waiting = null;
-    }
-  }
-}
-
-async function readStdin(): Promise<string> {
-  return new Promise((resolve, reject) => {
-    let data = '';
-    process.stdin.setEncoding('utf8');
-    process.stdin.on('data', chunk => { data += chunk; });
-    process.stdin.on('end', () => resolve(data));
-    process.stdin.on('error', reject);
-  });
-}
-
-const OUTPUT_START_MARKER = '---NANOCLAW_OUTPUT_START---';
-const OUTPUT_END_MARKER = '---NANOCLAW_OUTPUT_END---';
-
-function writeOutput(output: ContainerOutput): void {
-  console.log(OUTPUT_START_MARKER);
-  console.log(JSON.stringify(output));
-  console.log(OUTPUT_END_MARKER);
-}
-
-function log(message: string): void {
-  console.error(`[agent-runner] ${message}`);
-}
-
-function getSessionSummary(sessionId: string, transcriptPath: string): string | null {
-  const projectDir = path.dirname(transcriptPath);
-  const indexPath = path.join(projectDir, 'sessions-index.json');
-
-  if (!fs.existsSync(indexPath)) {
-    log(`Sessions index not found at ${indexPath}`);
-    return null;
-  }
-
-  try {
-    const index: SessionsIndex = JSON.parse(fs.readFileSync(indexPath, 'utf-8'));
-    const entry = index.entries.find(e => e.sessionId === sessionId);
-    if (entry?.summary) {
-      return entry.summary;
-    }
-  } catch (err) {
-    log(`Failed to read sessions index: ${err instanceof Error ? err.message : String(err)}`);
-  }
-
-  return null;
-}
-
-/**
- * Archive the full transcript to conversations/ before compaction.
- */
-function createPreCompactHook(assistantName?: string): HookCallback {
-  return async (input, _toolUseId, _context) => {
-    const preCompact = input as PreCompactHookInput;
-    const transcriptPath = preCompact.transcript_path;
-    const sessionId = preCompact.session_id;
-
-    if (!transcriptPath || !fs.existsSync(transcriptPath)) {
-      log('No transcript found for archiving');
-      return {};
-    }
-
-    try {
-      const content = fs.readFileSync(transcriptPath, 'utf-8');
-      const messages = parseTranscript(content);
-
-      if (messages.length === 0) {
-        log('No messages to archive');
-        return {};
-      }
-
-      const summary = getSessionSummary(sessionId, transcriptPath);
-      const name = summary ? sanitizeFilename(summary) : generateFallbackName();
-
-      const conversationsDir = '/workspace/group/conversations';
-      fs.mkdirSync(conversationsDir, { recursive: true });
-
-      const date = new Date().toISOString().split('T')[0];
-      const filename = `${date}-${name}.md`;
-      const filePath = path.join(conversationsDir, filename);
-
-      const markdown = formatTranscriptMarkdown(messages, summary, assistantName);
-      fs.writeFileSync(filePath, markdown);
-
-      log(`Archived conversation to ${filePath}`);
-    } catch (err) {
-      log(`Failed to archive transcript: ${err instanceof Error ? err.message : String(err)}`);
-    }
-
-    return {};
-  };
-}
-
-// Secrets to strip from Bash tool subprocess environments.
-// These are needed by claude-code for API auth but should never
-// be visible to commands Kit runs.
-const SECRET_ENV_VARS = ['ANTHROPIC_API_KEY', 'CLAUDE_CODE_OAUTH_TOKEN'];
-
-function createSanitizeBashHook(): HookCallback {
-  return async (input, _toolUseId, _context) => {
-    const preInput = input as PreToolUseHookInput;
-    const command = (preInput.tool_input as { command?: string })?.command;
-    if (!command) return {};
-
-    const unsetPrefix = `unset ${SECRET_ENV_VARS.join(' ')} 2>/dev/null; `;
-    return {
-      hookSpecificOutput: {
-        hookEventName: 'PreToolUse',
-        updatedInput: {
-          ...(preInput.tool_input as Record<string, unknown>),
-          command: unsetPrefix + command,
-        },
-      },
-    };
-  };
-}
-
-function sanitizeFilename(summary: string): string {
-  return summary
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '')
-    .slice(0, 50);
-}
-
-function generateFallbackName(): string {
-  const time = new Date();
-  return `conversation-${time.getHours().toString().padStart(2, '0')}${time.getMinutes().toString().padStart(2, '0')}`;
-}
-
-interface ParsedMessage {
-  role: 'user' | 'assistant';
-  content: string;
-}
-
-function parseTranscript(content: string): ParsedMessage[] {
-  const messages: ParsedMessage[] = [];
-
-  for (const line of content.split('\n')) {
-    if (!line.trim()) continue;
-    try {
-      const entry = JSON.parse(line);
-      if (entry.type === 'user' && entry.message?.content) {
-        const text = typeof entry.message.content === 'string'
-          ? entry.message.content
-          : entry.message.content.map((c: { text?: string }) => c.text || '').join('');
-        if (text) messages.push({ role: 'user', content: text });
-      } else if (entry.type === 'assistant' && entry.message?.content) {
-        const textParts = entry.message.content
-          .filter((c: { type: string }) => c.type === 'text')
-          .map((c: { text: string }) => c.text);
-        const text = textParts.join('');
-        if (text) messages.push({ role: 'assistant', content: text });
-      }
-    } catch {
-    }
-  }
-
-  return messages;
-}
-
-function formatTranscriptMarkdown(messages: ParsedMessage[], title?: string | null, assistantName?: string): string {
-  const now = new Date();
-  const formatDateTime = (d: Date) => d.toLocaleString('en-US', {
-    month: 'short',
-    day: 'numeric',
-    hour: 'numeric',
-    minute: '2-digit',
-    hour12: true
-  });
-
-  const lines: string[] = [];
-  lines.push(`# ${title || 'Conversation'}`);
-  lines.push('');
-  lines.push(`Archived: ${formatDateTime(now)}`);
-  lines.push('');
-  lines.push('---');
-  lines.push('');
-
-  for (const msg of messages) {
-    const sender = msg.role === 'user' ? 'User' : (assistantName || 'Assistant');
-    const content = msg.content.length > 2000
-      ? msg.content.slice(0, 2000) + '...'
-      : msg.content;
-    lines.push(`**${sender}**: ${content}`);
-    lines.push('');
-  }
-
-  return lines.join('\n');
-}
-
-/**
- * Check for _close sentinel.
- */
-function shouldClose(): boolean {
-  if (fs.existsSync(IPC_INPUT_CLOSE_SENTINEL)) {
-    try { fs.unlinkSync(IPC_INPUT_CLOSE_SENTINEL); } catch { /* ignore */ }
-    return true;
-  }
-  return false;
-}
-
-/**
- * Drain all pending IPC input messages.
- * Returns messages found, or empty array.
- */
-function drainIpcInput(): string[] {
-  try {
-    fs.mkdirSync(IPC_INPUT_DIR, { recursive: true });
-    const files = fs.readdirSync(IPC_INPUT_DIR)
-      .filter(f => f.endsWith('.json'))
-      .sort();
-
-    const messages: string[] = [];
-    for (const file of files) {
-      const filePath = path.join(IPC_INPUT_DIR, file);
-      try {
-        const data = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
-        fs.unlinkSync(filePath);
-        if (data.type === 'message' && data.text) {
-          messages.push(data.text);
-        }
-      } catch (err) {
-        log(`Failed to process input file ${file}: ${err instanceof Error ? err.message : String(err)}`);
-        try { fs.unlinkSync(filePath); } catch { /* ignore */ }
-      }
-    }
-    return messages;
-  } catch (err) {
-    log(`IPC drain error: ${err instanceof Error ? err.message : String(err)}`);
-    return [];
-  }
-}
-
-/**
- * Wait for a new IPC message or _close sentinel.
- * Returns the messages as a single string, or null if _close.
- */
-function waitForIpcMessage(): Promise<string | null> {
-  return new Promise((resolve) => {
-    const poll = () => {
-      if (shouldClose()) {
-        resolve(null);
-        return;
-      }
-      const messages = drainIpcInput();
-      if (messages.length > 0) {
-        resolve(messages.join('\n'));
-        return;
-      }
-      setTimeout(poll, IPC_POLL_MS);
-    };
-    poll();
-  });
-}
-
-/**
- * Run a single query and stream results via writeOutput.
- * Uses MessageStream (AsyncIterable) to keep isSingleUserTurn=false,
- * allowing agent teams subagents to run to completion.
- * Also pipes IPC messages into the stream during the query.
- */
-async function runQuery(
-  prompt: string,
-  sessionId: string | undefined,
-  mcpServerPath: string,
-  containerInput: ContainerInput,
-  sdkEnv: Record<string, string | undefined>,
-  resumeAt?: string,
-): Promise<{ newSessionId?: string; lastAssistantUuid?: string; closedDuringQuery: boolean }> {
-  const stream = new MessageStream();
-  stream.push(prompt);
-
-  // Poll IPC for follow-up messages and _close sentinel during the query
-  let ipcPolling = true;
-  let closedDuringQuery = false;
-  const pollIpcDuringQuery = () => {
-    if (!ipcPolling) return;
-    if (shouldClose()) {
-      log('Close sentinel detected during query, ending stream');
-      closedDuringQuery = true;
-      stream.end();
-      ipcPolling = false;
-      return;
-    }
-    const messages = drainIpcInput();
-    for (const text of messages) {
-      log(`Piping IPC message into active query (${text.length} chars)`);
-      stream.push(text);
-    }
-    setTimeout(pollIpcDuringQuery, IPC_POLL_MS);
-  };
-  setTimeout(pollIpcDuringQuery, IPC_POLL_MS);
-
-  let newSessionId: string | undefined;
-  let lastAssistantUuid: string | undefined;
-  let messageCount = 0;
-  let resultCount = 0;
-
-  // Load global CLAUDE.md as additional system context (shared across all groups)
-  const globalClaudeMdPath = '/workspace/global/CLAUDE.md';
-  let globalClaudeMd: string | undefined;
-  if (!containerInput.isMain && fs.existsSync(globalClaudeMdPath)) {
-    globalClaudeMd = fs.readFileSync(globalClaudeMdPath, 'utf-8');
-  }
-
-  // Discover additional directories mounted at /workspace/extra/*
-  // These are passed to the SDK so their CLAUDE.md files are loaded automatically
-  const extraDirs: string[] = [];
-  const extraBase = '/workspace/extra';
-  if (fs.existsSync(extraBase)) {
-    for (const entry of fs.readdirSync(extraBase)) {
-      const fullPath = path.join(extraBase, entry);
-      if (fs.statSync(fullPath).isDirectory()) {
-        extraDirs.push(fullPath);
-      }
-    }
-  }
-  if (extraDirs.length > 0) {
-    log(`Additional directories: ${extraDirs.join(', ')}`);
-  }
-
-  for await (const message of query({
-    prompt: stream,
-    options: {
-      cwd: '/workspace/group',
-      additionalDirectories: extraDirs.length > 0 ? extraDirs : undefined,
-      resume: sessionId,
-      resumeSessionAt: resumeAt,
-      systemPrompt: globalClaudeMd
-        ? { type: 'preset' as const, preset: 'claude_code' as const, append: globalClaudeMd }
-        : undefined,
-      allowedTools: [
-        'Bash',
-        'Read', 'Write', 'Edit', 'Glob', 'Grep',
-        'WebSearch', 'WebFetch',
-        'Task', 'TaskOutput', 'TaskStop',
-        'TeamCreate', 'TeamDelete', 'SendMessage',
-        'TodoWrite', 'ToolSearch', 'Skill',
-        'NotebookEdit',
-        'mcp__nanoclaw__*',
-        'mcp__gmail__*',
-      ],
-      env: sdkEnv,
-      permissionMode: 'bypassPermissions',
-      allowDangerouslySkipPermissions: true,
-      settingSources: ['project', 'user'],
-      mcpServers: {
-        nanoclaw: {
-          command: 'node',
-          args: [mcpServerPath],
-          env: {
-            NANOCLAW_CHAT_JID: containerInput.chatJid,
-            NANOCLAW_GROUP_FOLDER: containerInput.groupFolder,
-            NANOCLAW_IS_MAIN: containerInput.isMain ? '1' : '0',
-          },
-        },
-        gmail: {
-          command: 'npx',
-          args: ['-y', '@gongrzhe/server-gmail-autoauth-mcp'],
-        },
-      },
-      hooks: {
-        PreCompact: [{ hooks: [createPreCompactHook(containerInput.assistantName)] }],
-        PreToolUse: [{ matcher: 'Bash', hooks: [createSanitizeBashHook()] }],
-      },
-    }
-  })) {
-    messageCount++;
-    const msgType = message.type === 'system' ? `system/${(message as { subtype?: string }).subtype}` : message.type;
-    log(`[msg #${messageCount}] type=${msgType}`);
-
-    if (message.type === 'assistant' && 'uuid' in message) {
-      lastAssistantUuid = (message as { uuid: string }).uuid;
-    }
-
-    if (message.type === 'system' && message.subtype === 'init') {
-      newSessionId = message.session_id;
-      log(`Session initialized: ${newSessionId}`);
-    }
-
-    if (message.type === 'system' && (message as { subtype?: string }).subtype === 'task_notification') {
-      const tn = message as { task_id: string; status: string; summary: string };
-      log(`Task notification: task=${tn.task_id} status=${tn.status} summary=${tn.summary}`);
-    }
-
-    if (message.type === 'result') {
-      resultCount++;
-      const textResult = 'result' in message ? (message as { result?: string }).result : null;
-      log(`Result #${resultCount}: subtype=${message.subtype}${textResult ? ` text=${textResult.slice(0, 200)}` : ''}`);
-      writeOutput({
-        status: 'success',
-        result: textResult || null,
-        newSessionId
-      });
-    }
-  }
-
-  ipcPolling = false;
-  log(`Query done. Messages: ${messageCount}, results: ${resultCount}, lastAssistantUuid: ${lastAssistantUuid || 'none'}, closedDuringQuery: ${closedDuringQuery}`);
-  return { newSessionId, lastAssistantUuid, closedDuringQuery };
-}
-
-async function main(): Promise<void> {
-  let containerInput: ContainerInput;
-
-  try {
-    const stdinData = await readStdin();
-    containerInput = JSON.parse(stdinData);
-    // Delete the temp file the entrypoint wrote — it contains secrets
-    try { fs.unlinkSync('/tmp/input.json'); } catch { /* may not exist */ }
-    log(`Received input for group: ${containerInput.groupFolder}`);
-  } catch (err) {
-    writeOutput({
-      status: 'error',
-      result: null,
-      error: `Failed to parse input: ${err instanceof Error ? err.message : String(err)}`
-    });
-    process.exit(1);
-  }
-
-  // Build SDK env: merge secrets into process.env for the SDK only.
-  // Secrets never touch process.env itself, so Bash subprocesses can't see them.
-  const sdkEnv: Record<string, string | undefined> = { ...process.env };
-  for (const [key, value] of Object.entries(containerInput.secrets || {})) {
-    sdkEnv[key] = value;
-  }
-
-  const __dirname = path.dirname(fileURLToPath(import.meta.url));
-  const mcpServerPath = path.join(__dirname, 'ipc-mcp-stdio.js');
-
-  let sessionId = containerInput.sessionId;
-  fs.mkdirSync(IPC_INPUT_DIR, { recursive: true });
-
-  // Clean up stale _close sentinel from previous container runs
-  try { fs.unlinkSync(IPC_INPUT_CLOSE_SENTINEL); } catch { /* ignore */ }
-
-  // Build initial prompt (drain any pending IPC messages too)
-  let prompt = containerInput.prompt;
-  if (containerInput.isScheduledTask) {
-    prompt = `[SCHEDULED TASK - The following message was sent automatically and is not coming directly from the user or group.]\n\n${prompt}`;
-  }
-  const pending = drainIpcInput();
-  if (pending.length > 0) {
-    log(`Draining ${pending.length} pending IPC messages into initial prompt`);
-    prompt += '\n' + pending.join('\n');
-  }
-
-  // Query loop: run query → wait for IPC message → run new query → repeat
-  let resumeAt: string | undefined;
-  try {
-    while (true) {
-      log(`Starting query (session: ${sessionId || 'new'}, resumeAt: ${resumeAt || 'latest'})...`);
-
-      const queryResult = await runQuery(prompt, sessionId, mcpServerPath, containerInput, sdkEnv, resumeAt);
-      if (queryResult.newSessionId) {
-        sessionId = queryResult.newSessionId;
-      }
-      if (queryResult.lastAssistantUuid) {
-        resumeAt = queryResult.lastAssistantUuid;
-      }
-
-      // If _close was consumed during the query, exit immediately.
-      // Don't emit a session-update marker (it would reset the host's
-      // idle timer and cause a 30-min delay before the next _close).
-      if (queryResult.closedDuringQuery) {
-        log('Close sentinel consumed during query, exiting');
-        break;
-      }
-
-      // Emit session update so host can track it
-      writeOutput({ status: 'success', result: null, newSessionId: sessionId });
-
-      log('Query ended, waiting for next IPC message...');
-
-      // Wait for the next message or _close sentinel
-      const nextMessage = await waitForIpcMessage();
-      if (nextMessage === null) {
-        log('Close sentinel received, exiting');
-        break;
-      }
-
-      log(`Got new message (${nextMessage.length} chars), starting new query`);
-      prompt = nextMessage;
-    }
-  } catch (err) {
-    const errorMessage = err instanceof Error ? err.message : String(err);
-    log(`Agent error: ${errorMessage}`);
-    writeOutput({
-      status: 'error',
-      result: null,
-      newSessionId: sessionId,
-      error: errorMessage
-    });
-    process.exit(1);
-  }
-}
-
-main();

.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-imessage/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/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: add-imessage
+description: Add iMessage channel integration via Chat SDK. Local (macOS) or remote (Photon API) mode.
+---
+
+# Add iMessage Channel
+
+Adds iMessage support via the Chat SDK bridge. Two modes: local (macOS with Full Disk Access) or remote (Photon API).
+
+## Install
+
+NanoClaw doesn't ship channels in trunk. This skill copies the iMessage adapter in from the `channels` branch.
+
+### Pre-flight (idempotent)
+
+Skip to **Credentials** if all of these are already in place:
+
+- `src/channels/imessage.ts` exists
+- `src/channels/index.ts` contains `import './imessage.js';`
+- `chat-adapter-imessage` is listed in `package.json` dependencies
+
+Otherwise continue. Every step below is safe to re-run.
+
+### 1. Fetch the channels branch
+
+```bash
+git fetch origin channels
+```
+
+### 2. Copy the adapter
+
+```bash
+git show origin/channels:src/channels/imessage.ts > src/channels/imessage.ts
+```
+
+### 3. Append the self-registration import
+
+Append to `src/channels/index.ts` (skip if the line is already present):
+
+```typescript
+import './imessage.js';
+```
+
+### 4. Install the adapter package (pinned)
+
+```bash
+pnpm install chat-adapter-imessage@0.1.1
+```
+
+### 5. Build
+
+```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/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/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/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: add-linear
+description: Add Linear channel integration via Chat SDK. Issue comment threads as conversations.
+---
+
+# Add Linear Channel
+
+Adds Linear support via the Chat SDK bridge. The agent participates in issue comment threads. Every comment on a Linear issue triggers the agent — no @-mention needed.
+
+## Prerequisites
+
+**Recommended:** Create a Linear **OAuth application** so the agent posts as an app identity, not as you. This prevents the adapter from filtering your own comments as self-messages.
+
+1. Go to [Linear Settings > API > OAuth Applications](https://linear.app/settings/api/applications/new)
+2. Create an app (e.g. "NanoClaw Bot")
+   - Developer URL: your repo URL (e.g. `https://github.com/your-org/nanoclaw`)
+   - Callback URL: `http://localhost`
+3. After creating, click the app and enable **Client credentials** under grant types
+4. Copy the **Client ID** and **Client Secret**
+
+**Alternative:** Use a Personal API Key (`LINEAR_API_KEY`) for simpler setup. The agent will post as you, and your own comments will be filtered (other team members' comments still work).
+
+## Install
+
+NanoClaw doesn't ship channels in trunk. This skill copies the Linear adapter in from the `channels` branch and patches the Chat SDK bridge to support catch-all message forwarding (Linear OAuth apps can't be @-mentioned).
+
+### Pre-flight (idempotent)
+
+Skip to **Credentials** if all of these are already in place:
+
+- `src/channels/linear.ts` exists
+- `src/channels/index.ts` contains `import './linear.js';`
+- `@chat-adapter/linear` is listed in `package.json` dependencies
+- `src/channels/chat-sdk-bridge.ts` contains `catchAll`
+
+Otherwise continue. Every step below is safe to re-run.
+
+### 1. Fetch the channels branch
+
+```bash
+git fetch origin channels
+```
+
+### 2. Copy the adapter
+
+```bash
+git show origin/channels:src/channels/linear.ts > src/channels/linear.ts
+```
+
+### 3. Append the self-registration import
+
+Append to `src/channels/index.ts` (skip if the line is already present):
+
+```typescript
+import './linear.js';
+```
+
+### 4. Patch the Chat SDK bridge for catch-all message forwarding
+
+Linear OAuth apps can't be @-mentioned, so the bridge's `onNewMention` handler never fires. Add `catchAll` support to `src/channels/chat-sdk-bridge.ts`:
+
+**4a.** Add `catchAll?: boolean` to the `ChatSdkBridgeConfig` interface:
+
+```typescript
+  /**
+   * Forward ALL messages in unsubscribed threads, not just @-mentions.
+   * Use for platforms where the bot identity can't be @-mentioned (e.g.
+   * Linear OAuth apps). The thread is auto-subscribed on first message.
+   */
+  catchAll?: boolean;
+```
+
+**4b.** Add this handler block right after the `chat.onNewMention(...)` block (before the DMs block):
+
+```typescript
+      // Catch-all for platforms where @-mention isn't possible (e.g. Linear
+      // OAuth apps). Forward every unsubscribed message and auto-subscribe.
+      if (config.catchAll) {
+        chat.onNewMessage(/.*/, async (thread, message) => {
+          const channelId = adapter.channelIdFromThreadId(thread.id);
+          await setupConfig.onInbound(channelId, thread.id, await messageToInbound(message));
+          await thread.subscribe();
+        });
+      }
+```
+
+### 5. Install the adapter package (pinned)
+
+```bash
+pnpm install @chat-adapter/linear@4.26.0
+```
+
+### 6. Build
+
+```bash
+pnpm run build
+```
+
+## Credentials
+
+### 1. Set up a webhook
+
+1. Go to **Linear Settings** > **API** > **Webhooks** > **New webhook**
+2. Label: `NanoClaw`
+3. URL: `https://your-domain/webhook/linear` (the shared webhook server, default port 3000)
+4. Team: select the team you want to monitor
+5. Events: check **Comment**
+6. Save — copy the **signing secret**
+
+Note: Linear webhook delivery may be delayed 1-5 minutes for new webhooks. This is normal.
+
+### 2. Configure environment
+
+Add to `.env`:
+
+```bash
+# OAuth app (recommended)
+LINEAR_CLIENT_ID=your-client-id
+LINEAR_CLIENT_SECRET=your-client-secret
+
+# OR Personal API key (simpler, but agent posts as you)
+# LINEAR_API_KEY=lin_api_...
+
+LINEAR_WEBHOOK_SECRET=your-webhook-signing-secret
+LINEAR_BOT_USERNAME=NanoClaw Bot
+LINEAR_TEAM_KEY=ENG
+```
+
+- `LINEAR_BOT_USERNAME`: display name for the bot (used for self-message detection when using a Personal API Key)
+- `LINEAR_TEAM_KEY`: the Linear team key (e.g. `ENG`, `NAN`). Find it in Linear under Settings > Teams. All issues in this team route to one messaging group.
+
+Sync to container: `mkdir -p data/env && cp .env data/env/env`
+
+## Wiring
+
+Ask the user: **Is this a private or public Linear workspace?**
+
+- **Private workspace** — use `unknown_sender_policy: 'public'`. Only workspace members can comment.
+- **Public workspace** — use `unknown_sender_policy: 'strict'` and add trusted members (see GitHub skill for member registration example).
+
+Run `/manage-channels` to wire the Linear channel to an agent group, or insert manually:
+
+```sql
+-- Create messaging group (one per team)
+INSERT INTO messaging_groups (id, channel_type, platform_id, name, is_group, unknown_sender_policy, created_at)
+VALUES ('mg-linear-eng', 'linear', 'linear:ENG', 'Engineering', 1, 'public', datetime('now'));
+
+-- Wire to agent group
+INSERT INTO messaging_group_agents (id, messaging_group_id, agent_group_id, trigger_rules, response_scope, session_mode, priority, created_at)
+VALUES ('mga-linear-eng', 'mg-linear-eng', '<your-agent-group-id>', '', 'all', 'per-thread', 10, datetime('now'));
+```
+
+The `platform_id` must be `linear:<TEAM_KEY>` matching the `LINEAR_TEAM_KEY` env var. Use `per-thread` session mode so each issue comment thread gets its own agent session.
+
+## Next Steps
+
+If you're in the middle of `/setup`, return to the setup flow now.
+
+Otherwise, restart the service (`systemctl --user restart nanoclaw` or `launchctl kickstart -k gui/$(id -u)/com.nanoclaw`) to pick up the new channel.
+
+## 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 `linear:<TEAM_KEY>` (e.g. `linear:ENG`). Find your team key in Linear under Settings > Teams. Each issue becomes its own thread automatically.
+- **supports-threads**: yes (issue comment threads are native conversations)
+- **typical-use**: Webhook-driven — the agent receives all issue comment events and responds automatically. No @-mention needed (Linear OAuth apps can't be @-mentioned).
+- **default-isolation**: Use `per-thread` session mode. Each issue comment thread gets its own isolated agent session.

.claude/skills/add-linear/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/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/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: add-matrix
+description: Add Matrix channel integration via Chat SDK. Works with any Matrix homeserver.
+---
+
+# Add Matrix Channel
+
+Adds Matrix support via the Chat SDK bridge.
+
+## Install
+
+NanoClaw doesn't ship channels in trunk. This skill copies the Matrix adapter in from the `channels` branch.
+
+### Pre-flight (idempotent)
+
+Skip to **Credentials** if all of these are already in place:
+
+- `src/channels/matrix.ts` exists
+- `src/channels/index.ts` contains `import './matrix.js';`
+- `@beeper/chat-adapter-matrix` is listed in `package.json` dependencies
+
+Otherwise continue. Every step below is safe to re-run.
+
+### 1. Fetch the channels branch
+
+```bash
+git fetch origin channels
+```
+
+### 2. Copy the adapter
+
+```bash
+git show origin/channels:src/channels/matrix.ts > src/channels/matrix.ts
+```
+
+### 3. Append the self-registration import
+
+Append to `src/channels/index.ts` (skip if the line is already present):
+
+```typescript
+import './matrix.js';
+```
+
+### 4. Install the adapter package (pinned)
+
+```bash
+pnpm install @beeper/chat-adapter-matrix@0.2.0
+```
+
+### 5. Patch matrix-js-sdk ESM imports
+
+The adapter's published dist references `matrix-js-sdk/lib/...` without `.js`
+extensions, which fails under Node 22 strict ESM resolution. Add the missing
+extensions (idempotent — safe to re-run):
+
+```bash
+node -e '
+  const fs = require("fs"), path = require("path");
+  const root = "node_modules/.pnpm";
+  const dir = fs.readdirSync(root).find(d => d.startsWith("@beeper+chat-adapter-matrix@"));
+  if (!dir) { console.log("Matrix adapter not installed"); process.exit(0); }
+  const f = path.join(root, dir, "node_modules/@beeper/chat-adapter-matrix/dist/index.js");
+  fs.writeFileSync(f, fs.readFileSync(f, "utf8").replace(
+    /from "(matrix-js-sdk\/lib\/[^"]+?)(?<!\.js)"/g, "from \"$1.js\""
+  ));
+  console.log("Patched", f);
+'
+```
+
+Re-run this after every `pnpm install` that touches the adapter.
+
+### 6. Build
+
+```bash
+pnpm run build
+```
+
+## Credentials
+
+The bot needs its own Matrix account — separate from the user's account. This is required because Matrix cannot send DMs to yourself.
+
+### Create a bot account
+
+1. Open [app.element.io](https://app.element.io) in a private/incognito window (or sign out first)
+2. Register a new account for the bot (e.g. `andybot` on matrix.org)
+3. Note the bot's user ID (e.g. `@andybot:matrix.org`)
+
+### Choose an auth method
+
+**Option A: Username + Password (simpler)**
+
+No extra steps — just use the bot account's credentials directly. The adapter logs in automatically.
+
+```bash
+MATRIX_BASE_URL=https://matrix.org
+MATRIX_USERNAME=andybot
+MATRIX_PASSWORD=your-bot-password
+MATRIX_USER_ID=@andybot:matrix.org
+MATRIX_BOT_USERNAME=Andy
+```
+
+**Option B: Access Token (recommended for production)**
+
+Get an access token from Element: sign into the bot account → **Settings** > **Help & About** > **Access Token** (under Advanced). Or via API:
+
+```bash
+curl -XPOST 'https://matrix.org/_matrix/client/r0/login' \
+  -d '{"type":"m.login.password","user":"andybot","password":"..."}'
+```
+
+```bash
+MATRIX_BASE_URL=https://matrix.org
+MATRIX_ACCESS_TOKEN=your-access-token
+MATRIX_USER_ID=@andybot:matrix.org
+MATRIX_BOT_USERNAME=Andy
+```
+
+### Optional settings
+
+```bash
+MATRIX_INVITE_AUTOJOIN=true                    # Auto-accept room invites (default: true)
+MATRIX_INVITE_AUTOJOIN_ALLOWLIST=@you:matrix.org  # Only accept invites from these users
+MATRIX_RECOVERY_KEY=your-recovery-key          # Enable E2EE cross-signing
+MATRIX_DEVICE_ID=NANOCLAW01                    # Stable device ID across restarts
+```
+
+### Configure environment
+
+Add the chosen env vars to `.env`, then sync:
+
+```bash
+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**: For DMs, use the bot's `openDM` to resolve the room automatically. For group rooms, 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. Requires a separate bot account (the agent cannot DM users from their own account).
+- **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/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-provider/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: add-ollama-provider
+description: Route a NanoClaw agent group to a local Ollama model instead of the Anthropic API. Ollama speaks the Anthropic API natively (v1/messages), so no provider code changes are needed — just env var overrides and a model setting. Use when the user wants to run their agent locally, cut API costs, or experiment with open-weight models. See docs/ollama.md for background.
+---
+
+# Add Ollama Provider
+
+Routes an agent group to a local Ollama instance instead of the Anthropic API.
+See `docs/ollama.md` for how this works and the tradeoffs involved.
+
+## Prerequisites
+
+1. **Ollama is installed and running** on the host — verify: `curl -s http://localhost:11434/api/tags`
+2. **A model is pulled** — e.g. `ollama pull gemma4` or `ollama pull qwen3-coder`
+3. **The agent group already exists** — run `/init-first-agent` first if needed
+
+## 1. Check source support
+
+The feature requires two fields in `ContainerConfig` (`env` and `blockedHosts`) and their
+corresponding wiring in `container-runner.ts`. Check if already present:
+
+```bash
+grep -c 'blockedHosts' src/container-config.ts src/container-runner.ts
+```
+
+If either count is 0, apply the changes in steps 1a and 1b. Otherwise skip to step 2.
+
+### 1a. Extend ContainerConfig
+
+In `src/container-config.ts`, add to the `ContainerConfig` interface:
+
+```typescript
+env?: Record<string, string>;
+blockedHosts?: string[];
+```
+
+And in `readContainerConfig`, add inside the returned object:
+
+```typescript
+env: raw.env,
+blockedHosts: raw.blockedHosts,
+```
+
+### 1b. Wire into container-runner
+
+In `src/container-runner.ts`, after the `NANOCLAW_MCP_SERVERS` block, add:
+
+```typescript
+// Per-agent-group env overrides — applied last to win over OneCLI values.
+if (containerConfig.env) {
+  for (const [key, value] of Object.entries(containerConfig.env)) {
+    args.push('-e', `${key}=${value}`);
+  }
+}
+
+// Blocked hosts: resolve to 0.0.0.0 so they are unreachable inside the container.
+if (containerConfig.blockedHosts) {
+  for (const host of containerConfig.blockedHosts) {
+    args.push('--add-host', `${host}:0.0.0.0`);
+  }
+}
+```
+
+### 1c. Fix home directory permissions (if not already done)
+
+The container may run as your host uid (not uid 1000). Check the Dockerfile:
+
+```bash
+grep 'chmod.*home/node' container/Dockerfile
+```
+
+If it shows `chmod 755`, change it to `chmod 777` so any uid can write there.
+Then rebuild the container image: `./container/build.sh`
+
+## 2. Identify the setup
+
+Ask the user (plain text, not AskUserQuestion):
+
+1. **Which agent group?** List available groups: `sqlite3 data/v2.db "SELECT folder, name FROM agent_groups;"`
+2. **Which Ollama model?** List available: `curl -s http://localhost:11434/api/tags | grep '"name"'`
+3. **Block Anthropic API?** Recommended yes — prevents accidental spend if config drifts.
+
+Record as `FOLDER`, `MODEL`, and `BLOCK_ANTHROPIC`.
+
+## 3. Configure container.json
+
+Read `groups/<FOLDER>/container.json`. Add (or merge into) an `env` block and optionally `blockedHosts`:
+
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "http://host.docker.internal:11434",
+    "ANTHROPIC_API_KEY": "ollama",
+    "NO_PROXY": "host.docker.internal",
+    "no_proxy": "host.docker.internal"
+  },
+  "blockedHosts": ["api.anthropic.com"]
+}
+```
+
+Omit `blockedHosts` if the user declined step 2.
+
+**Why these vars:** `ANTHROPIC_BASE_URL` redirects the Anthropic SDK to Ollama.
+`ANTHROPIC_API_KEY=ollama` satisfies the SDK's key requirement (Ollama ignores it).
+`NO_PROXY` bypasses the OneCLI HTTPS proxy for requests to `host.docker.internal`
+so they reach Ollama directly instead of going through the credential gateway.
+
+## 4. Set the model
+
+Read the agent group's shared Claude settings:
+
+```bash
+# Find the agent group ID
+AG_ID=$(sqlite3 data/v2.db "SELECT id FROM agent_groups WHERE folder='<FOLDER>';")
+SETTINGS=data/v2-sessions/$AG_ID/.claude-shared/settings.json
+```
+
+Add `"model": "<MODEL>"` to that settings file. Create the file if it doesn't exist:
+
+```json
+{
+  "model": "gemma4:latest"
+}
+```
+
+If the file already has content, merge the `model` key in — don't overwrite existing keys.
+
+**Why here and not container.json:** Claude Code reads its model from its own settings
+file, not from env vars. This file is bind-mounted into the container as `~/.claude/settings.json`.
+
+## 5. Build and restart
+
+```bash
+export PATH="/opt/homebrew/bin:$PATH"
+pnpm run build
+launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
+launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
+# Linux: systemctl --user restart nanoclaw
+```
+
+## 6. Verify
+
+Send a message to the agent. Then confirm:
+
+```bash
+# Ollama shows the model as active
+curl -s http://localhost:11434/api/ps | grep '"name"'
+
+# Container has the right env vars
+CTR=$(docker ps --filter "name=nanoclaw-v2-<FOLDER>" --format "{{.Names}}" | head -1)
+docker inspect "$CTR" --format '{{json .HostConfig.ExtraHosts}}'
+docker exec "$CTR" env | grep ANTHROPIC
+```
+
+Expected: `api.anthropic.com:0.0.0.0` in ExtraHosts, `ANTHROPIC_BASE_URL=http://host.docker.internal:11434`.
+
+## Reverting to Claude
+
+To switch back to the Anthropic API:
+
+1. Remove the `env` and `blockedHosts` keys from `groups/<FOLDER>/container.json`
+2. Remove `"model"` from the shared settings file
+3. Restart the service
+
+No rebuild needed — both files are read at container spawn time.
+
+## Troubleshooting
+
+**Agent hangs, no response:** Ollama may be loading the model cold (large models take 10–30s).
+Watch `curl -s http://localhost:11434/api/ps` — the model appears once loaded.
+
+**"model not found" error in container logs:** The model name in settings.json doesn't match
+what Ollama has. Run `ollama list` on the host and use the exact name shown.
+
+**Responses claim to be Claude:** The model was trained on data that includes Claude conversations.
+Add a line to `groups/<FOLDER>/CLAUDE.md` telling it what model it runs on.
+
+**Agent responds but Ollama shows no activity:** `NO_PROXY` may not have taken effect for
+`http_proxy` (lowercase). Add both `NO_PROXY` and `no_proxy` to the env block.

.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,229 @@
+---
+name: add-opencode
+description: Use OpenCode as an agent provider (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
+
+NanoClaw runs agents in a long-lived **poll loop** inside the container. The backend is selected with **`AGENT_PROVIDER`** (`claude` | `opencode` | `mock`).
+
+Trunk ships with only the `claude` provider baked in. This skill copies the OpenCode provider files in from the `providers` branch, wires them into the host and container barrels, installs dependencies, and rebuilds the image.
+
+## Install
+
+### Pre-flight
+
+If all of the following are already present, skip to **Configuration**:
+
+- `src/providers/opencode.ts`
+- `container/agent-runner/src/providers/opencode.ts`
+- `import './opencode.js';` line in `src/providers/index.ts`
+- `import './opencode.js';` line in `container/agent-runner/src/providers/index.ts`
+- `@opencode-ai/sdk` in `container/agent-runner/package.json`
+- `opencode-ai@${OPENCODE_VERSION}` in the pnpm global-install block in `container/Dockerfile`
+
+Missing pieces — continue below. All steps are idempotent; re-running is safe.
+
+### 1. Fetch the providers branch
+
+```bash
+git fetch origin providers
+```
+
+### 2. Copy the OpenCode source files
+
+Wholesale copies (owned entirely by this skill — user edits to these files won't survive a re-run, as designed):
+
+```bash
+git show origin/providers:src/providers/opencode.ts                                    > src/providers/opencode.ts
+git show origin/providers:container/agent-runner/src/providers/opencode.ts             > container/agent-runner/src/providers/opencode.ts
+git show origin/providers:container/agent-runner/src/providers/mcp-to-opencode.ts      > container/agent-runner/src/providers/mcp-to-opencode.ts
+git show origin/providers:container/agent-runner/src/providers/mcp-to-opencode.test.ts > container/agent-runner/src/providers/mcp-to-opencode.test.ts
+git show origin/providers:container/agent-runner/src/providers/opencode.factory.test.ts > container/agent-runner/src/providers/opencode.factory.test.ts
+```
+
+### 3. Append the self-registration imports
+
+Each barrel gets one line appended at the end — skip if the line is already present.
+
+`src/providers/index.ts`:
+
+```typescript
+import './opencode.js';
+```
+
+`container/agent-runner/src/providers/index.ts`:
+
+```typescript
+import './opencode.js';
+```
+
+### 4. Add the agent-runner dependency
+
+Pinned. Bump deliberately, not with `bun update`. Use `1.4.17` — must match the `opencode-ai` CLI version pinned in step 5. The 1.14.x SDK has a completely different API and is **incompatible** with the current provider code.
+
+```bash
+cd container/agent-runner && bun add @opencode-ai/sdk@1.4.17 && cd -
+```
+
+### 5. Add `opencode-ai` to the container Dockerfile
+
+Two edits to `container/Dockerfile`, both idempotent (skip if already present):
+
+**(a)** In the "Pin CLI versions" ARG block (around line 18), add after `ARG VERCEL_VERSION=latest`:
+
+```dockerfile
+ARG OPENCODE_VERSION=1.4.17
+```
+
+> **Do not use `latest`** — the CLI and SDK must be the same version. `latest` silently upgrades the CLI to 1.14.x which has a breaking session API change (UUID session IDs → `ses_` prefix) incompatible with SDK 1.4.x.
+
+**(b)** In the `pnpm install -g` block (around line 80), append `"opencode-ai@${OPENCODE_VERSION}"` to the list:
+
+```dockerfile
+    pnpm install -g \
+        "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}" \
+        "agent-browser@${AGENT_BROWSER_VERSION}" \
+        "vercel@${VERCEL_VERSION}" \
+        "opencode-ai@${OPENCODE_VERSION}"
+```
+
+### 6. Build
+
+```bash
+pnpm run build                                         # host
+pnpm exec tsc -p container/agent-runner/tsconfig.json --noEmit   # container typecheck
+./container/build.sh                                   # agent image
+```
+
+> **Build cache gotcha:** The container buildkit caches COPY steps aggressively. If provider files were already present in the build context before, the new files may not be picked up. If you see "Unknown provider: opencode" after the build, prune the builder and rebuild:
+> ```bash
+> docker builder prune -f && ./container/build.sh
+> ```
+
+### 7. Propagate to existing per-group overlays
+
+Each agent group has a live source overlay at `data/v2-sessions/<group-id>/agent-runner-src/providers/` that **overrides the image at runtime**. This overlay is created when the group is first wired and never auto-updated by image rebuilds. Any group that already existed before this skill ran needs the new files copied in manually.
+
+```bash
+for overlay in data/v2-sessions/*/agent-runner-src/providers/; do
+  [ -d "$overlay" ] || continue
+  cp container/agent-runner/src/providers/opencode.ts "$overlay"
+  cp container/agent-runner/src/providers/mcp-to-opencode.ts "$overlay"
+  cp container/agent-runner/src/providers/index.ts "$overlay"
+  echo "Updated: $overlay"
+done
+```
+
+## 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`. 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`, `deepseek`.
+- `OPENCODE_MODEL` — full model id in `provider/model` form, e.g. `deepseek/deepseek-chat`.
+- `OPENCODE_SMALL_MODEL` — optional second model for lighter tasks; defaults to `OPENCODE_MODEL` if unset.
+- `ANTHROPIC_BASE_URL` — **required for non-`anthropic` providers.** The opencode container provider passes this as the `baseURL` for the upstream provider config so requests route through OneCLI's credential proxy or directly to the provider's API. Set it to the provider's API base URL (e.g. `https://api.deepseek.com/v1`, `https://openrouter.ai/api/v1`).
+
+Credentials: register provider API keys in OneCLI with the matching `--host-pattern` (e.g. `api.deepseek.com`, `openrouter.ai`). OneCLI injects them via `HTTPS_PROXY` in the container — the key never lives in `.env` or the container environment.
+
+After adding a secret, **grant the agent access** — agents in `selective` mode only receive secrets they've been explicitly assigned:
+
+```bash
+# Find the agent id and secret id, then:
+onecli agents set-secrets --id <agent-id> --secret-ids <existing-ids>,<new-secret-id>
+```
+
+Always include existing secret IDs in the list — `set-secrets` replaces, not appends.
+
+#### Example: DeepSeek
+
+```env
+OPENCODE_PROVIDER=deepseek
+OPENCODE_MODEL=deepseek/deepseek-chat
+OPENCODE_SMALL_MODEL=deepseek/deepseek-chat
+ANTHROPIC_BASE_URL=https://api.deepseek.com/v1
+```
+
+Register the key:
+```bash
+onecli secrets create --name "DeepSeek" --type generic \
+  --value YOUR_KEY --host-pattern "api.deepseek.com" \
+  --header-name "Authorization" --value-format "Bearer {value}"
+```
+
+#### Example: OpenRouter
+
+```env
+OPENCODE_PROVIDER=openrouter
+OPENCODE_MODEL=openrouter/anthropic/claude-sonnet-4
+OPENCODE_SMALL_MODEL=openrouter/anthropic/claude-haiku-4.5
+ANTHROPIC_BASE_URL=https://openrouter.ai/api/v1
+```
+
+Register the key:
+```bash
+onecli secrets create --name "OpenRouter" --type generic \
+  --value YOUR_KEY --host-pattern "openrouter.ai" \
+  --header-name "Authorization" --value-format "Bearer {value}"
+```
+
+#### Example: Anthropic (no ANTHROPIC_BASE_URL needed)
+
+When `OPENCODE_PROVIDER` is `anthropic`, OpenCode uses normal Anthropic env inside the container — the proxy + placeholder key pattern is unchanged and `ANTHROPIC_BASE_URL` is not required.
+
+```env
+OPENCODE_PROVIDER=anthropic
+OPENCODE_MODEL=anthropic/claude-sonnet-4-20250514
+OPENCODE_SMALL_MODEL=anthropic/claude-haiku-4-5-20251001
+```
+
+#### 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`** (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
+OPENCODE_PROVIDER=opencode
+OPENCODE_MODEL=opencode/big-pickle
+OPENCODE_SMALL_MODEL=opencode/big-pickle
+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}"
+```
+
+### Per group / per session
+
+Set `"provider": "opencode"` in the group's **`container.json`** (`groups/<folder>/container.json`) — the in-container runner reads `provider` from there, not from the DB. The DB columns **`agent_groups.agent_provider`** and **`sessions.agent_provider`** (session overrides group) only drive host-side provider contribution — per-session XDG mount, `OPENCODE_*` env passthrough — and do not propagate into `container.json` at spawn time. Set both, or just edit `container.json`; if they disagree, the runner uses `container.json` and the host-side resolver falls back through session → group → `container.json` → `'claude'`.
+
+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 uses UUID format (SDK 1.4.x / CLI 1.4.x). Stale sessions are cleared by `isSessionInvalid` on OpenCode-specific error patterns. If you see UUID-related errors after an accidental CLI upgrade, clear `session_state` in `outbound.db` and wipe the `opencode-xdg` directory under the session folder.
+- **`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.js" container/agent-runner/src/providers/index.ts && echo "container barrel: OK"
+grep -q "./opencode.js" src/providers/index.ts && echo "host barrel: OK"
+grep -q "@opencode-ai/sdk" container/agent-runner/package.json && echo "agent-runner dep: OK"
+grep -q "opencode-ai@" container/Dockerfile && echo "Dockerfile install: OK"
+cd container/agent-runner && bun test src/providers/ && cd -
+```

.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-resend/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/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: add-resend
+description: Add Resend (email) channel integration via Chat SDK.
+---
+
+# Add Resend Email Channel
+
+Connect NanoClaw to email via Resend for async email conversations.
+
+## Install
+
+NanoClaw doesn't ship channels in trunk. This skill copies the Resend adapter in from the `channels` branch.
+
+### Pre-flight (idempotent)
+
+Skip to **Credentials** if all of these are already in place:
+
+- `src/channels/resend.ts` exists
+- `src/channels/index.ts` contains `import './resend.js';`
+- `@resend/chat-sdk-adapter` is listed in `package.json` dependencies
+
+Otherwise continue. Every step below is safe to re-run.
+
+### 1. Fetch the channels branch
+
+```bash
+git fetch origin channels
+```
+
+### 2. Copy the adapter
+
+```bash
+git show origin/channels:src/channels/resend.ts > src/channels/resend.ts
+```
+
+### 3. Append the self-registration import
+
+Append to `src/channels/index.ts` (skip if the line is already present):
+
+```typescript
+import './resend.js';
+```
+
+### 4. Install the adapter package (pinned)
+
+```bash
+pnpm install @resend/chat-sdk-adapter@0.1.1
+```
+
+### 5. 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/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-signal/REMOVE.md

@@ -0,0 +1,13 @@
+# Remove Signal
+
+1. Comment out `import './signal.js'` in `src/channels/index.ts`
+2. Remove `SIGNAL_ACCOUNT` (and any other `SIGNAL_*` vars) from `.env`
+3. Rebuild and restart
+
+If you also want to unlink the Signal account from `signal-cli`:
+
+```bash
+signal-cli -a +1YOURNUMBER removeDevice --deviceId <id>
+```
+
+(Find the device id with `signal-cli -a +1YOURNUMBER listDevices`.)

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

@@ -0,0 +1,318 @@
+---
+name: add-signal
+description: Add Signal channel integration via signal-cli TCP daemon. Native adapter — no Chat SDK bridge.
+---
+
+# Add Signal Channel
+
+Adds Signal messaging support via a native adapter that speaks JSON-RPC to a [signal-cli](https://github.com/AsamK/signal-cli) TCP daemon. No Chat SDK bridge — only Node.js builtins (`node:net`, `node:child_process`, `node:fs`).
+
+Unlike Telegram or Discord, Signal has no bot API. NanoClaw registers as a full Signal account on a dedicated phone number (recommended) or links as a secondary device on your existing number.
+
+## Prerequisites
+
+### Java
+
+signal-cli requires Java 17+:
+
+```bash
+java -version
+```
+
+If missing:
+- **macOS:** `brew install --cask temurin@17`
+- **Debian/Ubuntu:** `sudo apt-get install -y default-jre`
+- **RHEL/Fedora:** `sudo dnf install -y java-17-openjdk`
+
+Java 17–25 all work.
+
+### signal-cli
+
+- **macOS:** `brew install signal-cli`
+- **Linux:** download the native binary from [GitHub releases](https://github.com/AsamK/signal-cli/releases):
+
+```bash
+SIGNAL_CLI_VERSION=$(curl -fsSL https://api.github.com/repos/AsamK/signal-cli/releases/latest | python3 -c "import sys,json; print(json.load(sys.stdin)['tag_name'][1:])")
+curl -fsSL "https://github.com/AsamK/signal-cli/releases/download/v${SIGNAL_CLI_VERSION}/signal-cli-${SIGNAL_CLI_VERSION}-Linux-native.tar.gz" \
+  | tar -xz -C ~/.local
+ln -sf ~/.local/signal-cli ~/.local/bin/signal-cli
+signal-cli --version
+```
+
+> The Linux native tarball extracts a single binary directly to `~/.local/signal-cli` (not into a subdirectory). The symlink above puts it on PATH.
+
+## Registration
+
+Two paths. The new-number path is recommended and battle-tested.
+
+### Path A: Register a new number (recommended)
+
+Use a dedicated SIM or VoIP number. NanoClaw owns it entirely.
+
+> **VoIP numbers:** Signal requires SMS verification before voice. Some VoIP providers are blocked even for voice calls. If registration fails with an auth error, try a different provider or a physical SIM.
+
+**Step 1: Solve the CAPTCHA**
+
+Signal requires a CAPTCHA on first registration:
+
+1. Open `https://signalcaptchas.org/registration/generate.html` in a browser
+2. Solve the captcha
+3. Right-click the **"Open Signal"** button → **Copy Link**
+4. The link starts with `signalcaptcha://` — the token is everything after that prefix
+
+**Step 2: Request SMS verification**
+
+```bash
+signal-cli -a +1YOURNUMBER register --captcha "PASTE_TOKEN_HERE"
+```
+
+**Step 3: Voice call fallback (if your number can't receive SMS)**
+
+Wait ~60 seconds after the SMS request, then:
+
+```bash
+signal-cli -a +1YOURNUMBER register --voice --captcha "SAME_TOKEN"
+```
+
+Signal calls your number and reads a 6-digit code. The same captcha token is reusable — no need to solve a new one.
+
+> You must request SMS first. Requesting voice immediately fails with `Invalid verification method: Before requesting voice verification…`
+
+**Step 4: Verify**
+
+```bash
+signal-cli -a +1YOURNUMBER verify CODE
+```
+
+No output = success.
+
+**Step 5: Set profile name (optional)**
+
+> ⚠ Stop NanoClaw before running signal-cli commands — the daemon holds an exclusive lock on its data directory while running.
+
+```bash
+# macOS
+launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
+signal-cli -a +1YOURNUMBER updateProfile --name "YourBotName"
+# optionally: --avatar /path/to/avatar.jpg
+launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
+
+# Linux
+systemctl --user stop nanoclaw
+signal-cli -a +1YOURNUMBER updateProfile --name "YourBotName"
+systemctl --user start nanoclaw
+```
+
+### Path B: Link as secondary device
+
+Joins an existing Signal account as a secondary device. Simpler, but NanoClaw shares your personal number.
+
+```bash
+signal-cli -a +1YOURNUMBER link --name "NanoClaw"
+```
+
+This prints a `tsdevice:` URI. Scan it as a QR code on your phone: **Settings → Linked Devices → Link New Device**. QR codes expire in ~30 seconds — re-run if it expires.
+
+## Install
+
+### Pre-flight (idempotent)
+
+Skip to **Credentials** if all of these are already in place:
+
+- `src/channels/signal.ts` and `src/channels/signal.test.ts` both exist
+- `src/channels/index.ts` contains `import './signal.js';`
+
+Otherwise continue. Every step below is safe to re-run.
+
+### 1. Fetch the channels branch
+
+```bash
+git fetch origin channels
+```
+
+### 2. Copy the adapter and tests
+
+```bash
+git show origin/channels:src/channels/signal.ts      > src/channels/signal.ts
+git show origin/channels:src/channels/signal.test.ts > src/channels/signal.test.ts
+```
+
+### 3. Append the self-registration import
+
+Append to `src/channels/index.ts` (skip if the line is already present):
+
+```typescript
+import './signal.js';
+```
+
+### 4. Build
+
+```bash
+pnpm run build
+```
+
+No npm packages to install — the adapter uses only Node.js builtins.
+
+## Credentials
+
+Add to `.env`:
+
+```bash
+SIGNAL_ACCOUNT=+1YOURNUMBER
+```
+
+### Optional settings
+
+```bash
+# TCP daemon host and port (default: 127.0.0.1:7583)
+SIGNAL_TCP_HOST=127.0.0.1
+SIGNAL_TCP_PORT=7583
+
+# Path to the signal-cli binary (default: resolved on PATH)
+SIGNAL_CLI_PATH=/usr/local/bin/signal-cli
+
+# Whether NanoClaw manages the daemon lifecycle (default: true).
+# Set to false if you run signal-cli daemon externally.
+SIGNAL_MANAGE_DAEMON=true
+
+# signal-cli data directory (default: ~/.local/share/signal-cli)
+SIGNAL_DATA_DIR=~/.local/share/signal-cli
+```
+
+**Security note:** keep the TCP host on `127.0.0.1`. The daemon has no auth — binding it to a public interface would expose your full Signal account to the network.
+
+Sync to container: `mkdir -p data/env && cp .env data/env/env`
+
+### Restart
+
+```bash
+# macOS
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw
+
+# Linux
+systemctl --user restart nanoclaw
+```
+
+## Wiring
+
+### DMs
+
+After the service starts, send any message to the Signal number from your personal Signal app. The router auto-creates a `messaging_groups` row. Then:
+
+```bash
+sqlite3 data/v2.db \
+  "SELECT id, platform_id FROM messaging_groups WHERE channel_type='signal' ORDER BY created_at DESC LIMIT 5"
+```
+
+Pass the `id` to `/init-first-agent` or `/manage-channels` to wire it to an agent group.
+
+### Groups
+
+Add the Signal number to a group from your phone, send any message, then wire the resulting row the same way. For isolated per-group sessions:
+
+```bash
+NOW=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")
+sqlite3 data/v2.db "
+INSERT OR IGNORE INTO messaging_group_agents
+  (id, messaging_group_id, agent_group_id, session_mode, priority, created_at)
+VALUES
+  ('mga-'||hex(randomblob(8)), 'mg-GROUPID', 'ag-AGENTID', 'isolated', 0, '$NOW');
+"
+```
+
+### Grant user access
+
+New Signal users (including the owner's Signal identity) are silently dropped with `not_member` until granted access. After the user's first message appears in `messaging_groups`:
+
+```bash
+NOW=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")
+sqlite3 data/v2.db "
+INSERT OR REPLACE INTO user_roles (user_id, role, agent_group_id, granted_by, granted_at)
+  VALUES ('signal:UUID', 'owner', NULL, 'system', '$NOW');
+INSERT OR IGNORE INTO agent_group_members (user_id, agent_group_id, added_by, added_at)
+  VALUES ('signal:UUID', 'ag-AGENTID', 'system', '$NOW');
+"
+```
+
+Find the UUID from `messaging_groups.platform_id` or the `users` table.
+
+## Next Steps
+
+If you're in the middle of `/setup`, return to the setup flow now.
+
+Otherwise, run `/init-first-agent` to create an agent and wire it to your Signal DM, or `/manage-channels` to wire this channel to an existing agent group.
+
+## Channel Info
+
+- **type**: `signal`
+- **terminology**: Signal has "chats" (1:1 DMs) and "groups"
+- **supports-threads**: no
+- **platform-id-format**:
+  - DM: `signal:{UUID}` — sender's Signal UUID (ACI), **not** their phone number
+  - Group: `signal:{base64GroupId}` — base64-encoded GroupV2 ID
+- **how-to-find-id**: Send a message to the bot, then query `messaging_groups` as shown above
+- **typical-use**: Personal assistant via Signal DMs or small group chats
+- **default-isolation**: One agent per Signal account. Multiple chats with the same operator can share an agent group; groups with other people should typically use `isolated` session mode
+
+### Features
+
+- Markdown formatting — `**bold**`, `*italic*` / `_italic_`, `` `code` ``, ` ```code fence``` `, `~~strike~~`, `||spoiler||` (converted to Signal's offset-based text styles)
+- Quoted replies — `replyTo*` fields populated from Signal quotes
+- Typing indicators — DMs only (Signal doesn't support group typing)
+- Echo suppression — outbound messages matched on `(platformId, text)` within a 10 s TTL to avoid syncMessage loops
+- Note to Self — messages you send to your own account from another device route to the agent as inbound with `isFromMe: true`
+- Voice attachments — detected but not transcribed by default; the agent receives `[Voice Message]` placeholder text. Run `/add-voice-transcription` for local transcription via parakeet-mlx
+
+Not supported yet: outbound file attachments (logged and dropped), edit/delete messages, reactions.
+
+## Troubleshooting
+
+### Daemon not reachable
+
+```bash
+grep "Signal" logs/nanoclaw.log | tail
+```
+
+If you see `Signal daemon failed to start. Is signal-cli installed and your account linked?`:
+- Confirm `signal-cli` is on PATH (or set `SIGNAL_CLI_PATH`)
+- Confirm the account is linked: `signal-cli -a +1YOURNUMBER listIdentities` should succeed without prompting
+
+If you see `Signal daemon not reachable at 127.0.0.1:7583` and `SIGNAL_MANAGE_DAEMON=false`, start the daemon yourself: `signal-cli -a +1YOURNUMBER daemon --tcp 127.0.0.1:7583`.
+
+### Bot not responding
+
+1. Channel initialized: `grep "Signal channel connected" logs/nanoclaw.log | tail -1`
+2. 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='signal'"`
+3. Service running: `launchctl print gui/$(id -u)/com.nanoclaw` (macOS) / `systemctl --user status nanoclaw` (Linux)
+
+### Lost connection mid-session
+
+If you see `Signal channel lost TCP connection to signal-cli daemon` in the logs, the daemon dropped the connection. Restart the service to re-establish.
+
+### Messages dropped with `not_member`
+
+The Signal user hasn't been granted membership. See "Grant user access" above. This affects every new Signal user, including the owner's Signal identity — which is a separate user record from their identity on other channels even if it's the same person.
+
+### Captcha required
+
+Signal requires a captcha for new registrations. Go to `https://signalcaptchas.org/registration/generate.html`, solve it, right-click "Open Signal", copy the link, extract the token after `signalcaptcha://`.
+
+### `Invalid verification method: Before requesting voice verification…`
+
+You must request SMS first, wait ~60 seconds, then request voice. Both steps can use the same captcha token.
+
+### Config file in use / daemon lock
+
+signal-cli holds an exclusive lock on its data directory while the daemon is running. Stop NanoClaw before running any `signal-cli` commands directly, then restart afterward.
+
+### Group replies going to DM instead of group
+
+Modern Signal groups use GroupV2. The adapter must extract the group ID from `envelope?.dataMessage?.groupV2?.id` — not `groupInfo?.groupId`, which is GroupV1/legacy. If group messages are routing as DMs, check `src/channels/signal.ts` and confirm the groupId extraction falls through to `groupV2.id`.
+
+### Java not found
+
+Install Java 17+ — see the Prerequisites section above.
+
+### QR code expired (Path B)
+
+QR codes expire in ~30 seconds. Re-run the link command to generate a new one.

.claude/skills/add-signal/VERIFY.md

@@ -0,0 +1,5 @@
+# Verify Signal
+
+Send a message to your own Signal number (Note to Self) from another device, or have someone send your linked number a DM. The bot should respond within a few seconds.
+
+If nothing happens, tail `logs/nanoclaw.log` for `Signal channel connected` and `Signal message received`.

.claude/skills/add-slack/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/SKILL.md

@@ -1,75 +1,88 @@
 ---
 name: add-slack
-description: Add Slack as a channel. Can replace WhatsApp entirely or run alongside it. Uses Socket Mode (no public URL needed).
+description: Add Slack channel integration via Chat SDK.
 ---
 
 # Add Slack Channel
 
-This skill adds Slack support to NanoClaw using the skills engine for deterministic code changes, then walks through interactive setup.
+Adds Slack support via the Chat SDK bridge.
 
-## Phase 1: Pre-flight
+## Install
 
-### Check if already applied
+NanoClaw doesn't ship channels in trunk. This skill copies the Slack adapter in from the `channels` branch.
 
-Read `.nanoclaw/state.yaml`. If `slack` is in `applied_skills`, skip to Phase 3 (Setup). The code changes are already in place.
+### Pre-flight (idempotent)
 
-### Ask the user
+Skip to **Credentials** if all of these are already in place:
 
-**Do they already have a Slack app configured?** If yes, collect the Bot Token and App Token now. If no, we'll create one in Phase 3.
+- `src/channels/slack.ts` exists
+- `src/channels/index.ts` contains `import './slack.js';`
+- `@chat-adapter/slack` is listed in `package.json` dependencies
 
-## Phase 2: Apply Code Changes
+Otherwise continue. Every step below is safe to re-run.
 
-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:
+### 1. Fetch the channels branch
 
 ```bash
-npx tsx scripts/apply-skill.ts --init
+git fetch origin channels
 ```
 
-Or call `initSkillsSystem()` from `skills-engine/migrate.ts`.
-
-### Apply the skill
+### 2. Copy the adapter
 
 ```bash
-npx tsx scripts/apply-skill.ts .claude/skills/add-slack
+git show origin/channels:src/channels/slack.ts > src/channels/slack.ts
 ```
 
-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`
+### 3. Append the self-registration import
 
-If the apply reports merge conflicts, read the intent file:
-- `modify/src/channels/index.ts.intent.md` — what changed and invariants
+Append to `src/channels/index.ts` (skip if the line is already present):
 
-### Validate code changes
+```typescript
+import './slack.js';
+```
+
+### 4. Install the adapter package (pinned)
 
 ```bash
-npm test
-npm run build
+pnpm install @chat-adapter/slack@4.26.0
 ```
 
-All tests must pass (including the new slack tests) and build must be clean before proceeding.
+### 5. Build
 
-## Phase 3: Setup
+```bash
+pnpm run build
+```
 
-### Create Slack App (if needed)
+## Credentials
 
-If the user doesn't have a Slack app, share [SLACK_SETUP.md](SLACK_SETUP.md) which has step-by-step instructions with screenshots guidance, troubleshooting, and a token reference table.
+### Create Slack App
 
-Quick summary of what's needed:
-1. Create a Slack app at [api.slack.com/apps](https://api.slack.com/apps)
-2. Enable Socket Mode and generate an App-Level Token (`xapp-...`)
-3. Subscribe to bot events: `message.channels`, `message.groups`, `message.im`
-4. Add OAuth scopes: `chat:write`, `channels:history`, `groups:history`, `im:history`, `channels:read`, `groups:read`, `users:read`
-5. Install to workspace and copy the Bot Token (`xoxb-...`)
+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`, `im: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**
 
-Wait for the user to provide both tokens.
+### 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**
+
+### Interactivity
+
+12. Go to **Interactivity & Shortcuts** and toggle **Interactivity** on
+13. Set the **Request URL** to the same `https://your-domain/webhook/slack`
+14. Click **Save Changes**
+15. Slack will show a banner asking you to **reinstall the app** — click it to apply the new settings
 
 ### Configure environment
 
@@ -77,139 +90,29 @@ Add to `.env`:
 
 ```bash
 SLACK_BOT_TOKEN=xoxb-your-bot-token
-SLACK_APP_TOKEN=xapp-your-app-token
+SLACK_SIGNING_SECRET=your-signing-secret
 ```
 
-Channels auto-enable when their credentials are present — no extra configuration needed.
+Sync to container: `mkdir -p data/env && cp .env data/env/env`
 
-Sync to container environment:
+### Webhook server
 
-```bash
-mkdir -p data/env && cp .env data/env/env
-```
+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.
 
-The container reads environment from `data/env/env`, not `.env` directly.
+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`.
 
-### Build and restart
+## Next Steps
 
-```bash
-npm run build
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw
-```
+If you're in the middle of `/setup`, return to the setup flow now.
 
-## Phase 4: Registration
+Otherwise, run `/manage-channels` to wire this channel to an agent group.
 
-### Get Channel ID
+## Channel Info
 
-Tell the user:
-
-> 1. Add the bot to a Slack channel (right-click channel → **View channel details** → **Integrations** → **Add apps**)
-> 2. In that channel, the channel ID is in the URL when you open it in a browser: `https://app.slack.com/client/T.../C0123456789` — the `C...` part is the channel ID
-> 3. Alternatively, right-click the channel name → **Copy link** — the channel ID is the last path segment
->
-> The JID format for NanoClaw is: `slack:C0123456789`
-
-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.
-
-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,
-});
-```
-
-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,
-});
-```
-
-## Phase 5: Verify
-
-### Test the connection
-
-Tell the user:
-
-> Send a message in your registered Slack channel:
-> - For main channel: Any message works
-> - For non-main: `@<assistant-name> hello` (using the configured trigger word)
->
-> The bot should respond within a few seconds.
-
-### Check logs if needed
-
-```bash
-tail -f logs/nanoclaw.log
-```
-
-## Troubleshooting
-
-### Bot not responding
-
-1. Check `SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN` are set in `.env` AND synced to `data/env/env`
-2. Check channel is registered: `sqlite3 store/messages.db "SELECT * FROM registered_groups WHERE jid LIKE 'slack:%'"`
-3. For non-main channels: message must include trigger pattern
-4. Service is running: `launchctl list | grep nanoclaw`
-
-### Bot connected but not receiving messages
-
-1. Verify Socket Mode is enabled in the Slack app settings
-2. Verify the bot is subscribed to the correct events (`message.channels`, `message.groups`, `message.im`)
-3. Verify the bot has been added to the channel
-4. Check that the bot has the required OAuth scopes
-
-### Bot not seeing messages in channels
-
-By default, bots only see messages in channels they've been explicitly added to. Make sure to:
-1. Add the bot to each channel you want it to monitor
-2. Check the bot has `channels:history` and/or `groups:history` scopes
-
-### "missing_scope" errors
-
-If the bot logs `missing_scope` errors:
-1. Go to **OAuth & Permissions** in your Slack app settings
-2. Add the missing scope listed in the error message
-3. **Reinstall the app** to your workspace — scope changes require reinstallation
-4. Copy the new Bot Token (it changes on reinstall) and update `.env`
-5. Sync: `mkdir -p data/env && cp .env data/env/env`
-6. Restart: `launchctl kickstart -k gui/$(id -u)/com.nanoclaw`
-
-### Getting channel ID
-
-If the channel ID is hard to find:
-- In Slack desktop: right-click channel → **Copy link** → extract the `C...` ID from the URL
-- In Slack web: the URL shows `https://app.slack.com/client/TXXXXXXX/C0123456789`
-- Via API: `curl -s -H "Authorization: Bearer $SLACK_BOT_TOKEN" "https://slack.com/api/conversations.list" | jq '.channels[] | {id, name}'`
-
-## After Setup
-
-The Slack channel supports:
-- **Public channels** — Bot must be added to the channel
-- **Private channels** — Bot must be invited to the channel
-- **Direct messages** — Users can DM the bot directly
-- **Multi-channel** — Can run alongside WhatsApp or other channels (auto-enabled by credentials)
-
-## Known Limitations
-
-- **Threads are flattened** — Threaded replies are delivered to the agent as regular channel messages. The agent sees them but has no awareness they originated in a thread. Responses always go to the channel, not back into the thread. Users in a thread will need to check the main channel for the bot's reply. Full thread-aware routing (respond in-thread) requires pipeline-wide changes: database schema, `NewMessage` type, `Channel.sendMessage` interface, and routing logic.
-- **No typing indicator** — Slack's Bot API does not expose a typing indicator endpoint. The `setTyping()` method is a no-op. Users won't see "bot is typing..." while the agent works.
-- **Message splitting is naive** — Long messages are split at a fixed 4000-character boundary, which may break mid-word or mid-sentence. A smarter split (on paragraph or sentence boundaries) would improve readability.
-- **No file/image handling** — The bot only processes text content. File uploads, images, and rich message blocks are not forwarded to the agent.
-- **Channel metadata sync is unbounded** — `syncChannelMetadata()` paginates through all channels the bot is a member of, but has no upper bound or timeout. Workspaces with thousands of channels may experience slow startup.
-- **Workspace admin policies not detected** — If the Slack workspace restricts bot app installation, the setup will fail at the "Install to Workspace" step with no programmatic detection or guidance. See SLACK_SETUP.md troubleshooting section.
+- **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/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/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/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/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/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: add-teams
+description: Add Microsoft Teams channel integration via Chat SDK.
+---
+
+# Add Microsoft Teams Channel
+
+Connect NanoClaw to Microsoft Teams for interactive chat in team channels, group chats, and direct messages.
+
+## Install
+
+NanoClaw doesn't ship channels in trunk. This skill copies the Teams adapter in from the `channels` branch.
+
+### Pre-flight (idempotent)
+
+Skip to **Credentials** if all of these are already in place:
+
+- `src/channels/teams.ts` exists
+- `src/channels/index.ts` contains `import './teams.js';`
+- `@chat-adapter/teams` is listed in `package.json` dependencies
+
+Otherwise continue. Every step below is safe to re-run.
+
+### 1. Fetch the channels branch
+
+```bash
+git fetch origin channels
+```
+
+### 2. Copy the adapter
+
+```bash
+git show origin/channels:src/channels/teams.ts > src/channels/teams.ts
+```
+
+### 3. Append the self-registration import
+
+Append to `src/channels/index.ts` (skip if the line is already present):
+
+```typescript
+import './teams.js';
+```
+
+### 4. Install the adapter package (pinned)
+
+```bash
+pnpm install @chat-adapter/teams@4.26.0
+```
+
+### 5. 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/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

@@ -1,384 +0,0 @@
----
-name: add-telegram-swarm
-description: Add Agent Swarm (Teams) support to Telegram. Each subagent gets its own bot identity in the group. Requires Telegram channel to be set up first (use /add-telegram). Triggers on "agent swarm", "agent teams telegram", "telegram swarm", "bot pool".
----
-
-# Add Agent Swarm to Telegram
-
-This skill adds Agent Teams (Swarm) support to an existing Telegram channel. Each subagent in a team gets its own bot identity in the Telegram group, so users can visually distinguish which agent is speaking.
-
-**Prerequisite**: Telegram must already be set up via the `/add-telegram` skill. If `src/telegram.ts` does not exist or `TELEGRAM_BOT_TOKEN` is not configured, tell the user to run `/add-telegram` first.
-
-## How It Works
-
-- The **main bot** receives messages and sends lead agent responses (already set up by `/add-telegram`)
-- **Pool bots** are send-only — each gets a Grammy `Api` instance (no polling)
-- When a subagent calls `send_message` with a `sender` parameter, the host assigns a pool bot and renames it to match the sender's role
-- Messages appear in Telegram from different bot identities
-
-```
-Subagent calls send_message(text: "Found 3 results", sender: "Researcher")
-  → MCP writes IPC file with sender field
-  → Host IPC watcher picks it up
-  → Assigns pool bot #2 to "Researcher" (round-robin, stable per-group)
-  → Renames pool bot #2 to "Researcher" via setMyName
-  → Sends message via pool bot #2's Api instance
-  → Appears in Telegram from "Researcher" bot
-```
-
-## Prerequisites
-
-### 1. Create Pool Bots
-
-Tell the user:
-
-> I need you to create 3-5 Telegram bots to use as the agent pool. These will be renamed dynamically to match agent roles.
->
-> 1. Open Telegram and search for `@BotFather`
-> 2. Send `/newbot` for each bot:
->    - Give them any placeholder name (e.g., "Bot 1", "Bot 2")
->    - Usernames like `myproject_swarm_1_bot`, `myproject_swarm_2_bot`, etc.
-> 3. Copy all the tokens
-> 4. Add all bots to your Telegram group(s) where you want agent teams
-
-Wait for user to provide the tokens.
-
-### 2. Disable Group Privacy for Pool Bots
-
-Tell the user:
-
-> **Important**: Each pool bot needs Group Privacy disabled so it can send messages in groups.
->
-> For each pool bot in `@BotFather`:
-> 1. Send `/mybots` and select the bot
-> 2. Go to **Bot Settings** > **Group Privacy** > **Turn off**
->
-> Then add all pool bots to your Telegram group(s).
-
-## Implementation
-
-### Step 1: Update Configuration
-
-Read `src/config.ts` and add the bot pool config near the other Telegram exports:
-
-```typescript
-export const TELEGRAM_BOT_POOL = (process.env.TELEGRAM_BOT_POOL || '')
-  .split(',')
-  .map((t) => t.trim())
-  .filter(Boolean);
-```
-
-### Step 2: Add Bot Pool to Telegram Module
-
-Read `src/telegram.ts` and add the following:
-
-1. **Update imports** — add `Api` to the Grammy import:
-
-```typescript
-import { Api, Bot } from 'grammy';
-```
-
-2. **Add pool state** after the existing `let bot` declaration:
-
-```typescript
-// Bot pool for agent teams: send-only Api instances (no polling)
-const poolApis: Api[] = [];
-// Maps "{groupFolder}:{senderName}" → pool Api index for stable assignment
-const senderBotMap = new Map<string, number>();
-let nextPoolIndex = 0;
-```
-
-3. **Add pool functions** — place these before the `isTelegramConnected` function:
-
-```typescript
-/**
- * Initialize send-only Api instances for the bot pool.
- * Each pool bot can send messages but doesn't poll for updates.
- */
-export async function initBotPool(tokens: string[]): Promise<void> {
-  for (const token of tokens) {
-    try {
-      const api = new Api(token);
-      const me = await api.getMe();
-      poolApis.push(api);
-      logger.info(
-        { username: me.username, id: me.id, poolSize: poolApis.length },
-        'Pool bot initialized',
-      );
-    } catch (err) {
-      logger.error({ err }, 'Failed to initialize pool bot');
-    }
-  }
-  if (poolApis.length > 0) {
-    logger.info({ count: poolApis.length }, 'Telegram bot pool ready');
-  }
-}
-
-/**
- * Send a message via a pool bot assigned to the given sender name.
- * Assigns bots round-robin on first use; subsequent messages from the
- * same sender in the same group always use the same bot.
- * On first assignment, renames the bot to match the sender's role.
- */
-export async function sendPoolMessage(
-  chatId: string,
-  text: string,
-  sender: string,
-  groupFolder: string,
-): Promise<void> {
-  if (poolApis.length === 0) {
-    // No pool bots — fall back to main bot
-    await sendTelegramMessage(chatId, text);
-    return;
-  }
-
-  const key = `${groupFolder}:${sender}`;
-  let idx = senderBotMap.get(key);
-  if (idx === undefined) {
-    idx = nextPoolIndex % poolApis.length;
-    nextPoolIndex++;
-    senderBotMap.set(key, idx);
-    // Rename the bot to match the sender's role, then wait for Telegram to propagate
-    try {
-      await poolApis[idx].setMyName(sender);
-      await new Promise((r) => setTimeout(r, 2000));
-      logger.info({ sender, groupFolder, poolIndex: idx }, 'Assigned and renamed pool bot');
-    } catch (err) {
-      logger.warn({ sender, err }, 'Failed to rename pool bot (sending anyway)');
-    }
-  }
-
-  const api = poolApis[idx];
-  try {
-    const numericId = chatId.replace(/^tg:/, '');
-    const MAX_LENGTH = 4096;
-    if (text.length <= MAX_LENGTH) {
-      await api.sendMessage(numericId, text);
-    } else {
-      for (let i = 0; i < text.length; i += MAX_LENGTH) {
-        await api.sendMessage(numericId, text.slice(i, i + MAX_LENGTH));
-      }
-    }
-    logger.info({ chatId, sender, poolIndex: idx, length: text.length }, 'Pool message sent');
-  } catch (err) {
-    logger.error({ chatId, sender, err }, 'Failed to send pool message');
-  }
-}
-```
-
-### Step 3: Add sender Parameter to MCP Tool
-
-Read `container/agent-runner/src/ipc-mcp-stdio.ts` and update the `send_message` tool to accept an optional `sender` parameter:
-
-Change the tool's schema from:
-```typescript
-{ text: z.string().describe('The message text to send') },
-```
-
-To:
-```typescript
-{
-  text: z.string().describe('The message text to send'),
-  sender: z.string().optional().describe('Your role/identity name (e.g. "Researcher"). When set, messages appear from a dedicated bot in Telegram.'),
-},
-```
-
-And update the handler to include `sender` in the IPC data:
-
-```typescript
-async (args) => {
-    const data: Record<string, string | undefined> = {
-      type: 'message',
-      chatJid,
-      text: args.text,
-      sender: args.sender || undefined,
-      groupFolder,
-      timestamp: new Date().toISOString(),
-    };
-
-    writeIpcFile(MESSAGES_DIR, data);
-
-    return { content: [{ type: 'text' as const, text: 'Message sent.' }] };
-  },
-```
-
-### Step 4: Update Host IPC Routing
-
-Read `src/ipc.ts` and make these changes:
-
-1. **Add imports** — add `sendPoolMessage` and `initBotPool` from the Telegram swarm module, and `TELEGRAM_BOT_POOL` from config.
-
-2. **Update IPC message routing** — in `src/ipc.ts`, find where the `sendMessage` dependency is called to deliver IPC messages (inside `processIpcFiles`). The `sendMessage` is passed in via the `IpcDeps` parameter. Wrap it to route Telegram swarm messages through the bot pool:
-
-```typescript
-if (data.sender && data.chatJid.startsWith('tg:')) {
-  await sendPoolMessage(
-    data.chatJid,
-    data.text,
-    data.sender,
-    sourceGroup,
-  );
-} else {
-  await deps.sendMessage(data.chatJid, data.text);
-}
-```
-
-Note: The assistant name prefix is handled by `formatOutbound()` in the router — Telegram channels have `prefixAssistantName = false` so no prefix is added for `tg:` JIDs.
-
-3. **Initialize pool in `main()` in `src/index.ts`** — after creating the Telegram channel, add:
-
-```typescript
-if (TELEGRAM_BOT_POOL.length > 0) {
-  await initBotPool(TELEGRAM_BOT_POOL);
-}
-```
-
-### Step 5: Update CLAUDE.md Files
-
-#### 5a. Add global message formatting rules
-
-Read `groups/global/CLAUDE.md` and add a Message Formatting section:
-
-```markdown
-## Message Formatting
-
-NEVER use markdown. Only use WhatsApp/Telegram formatting:
-- *single asterisks* for bold (NEVER **double asterisks**)
-- _underscores_ for italic
-- • bullet points
-- ```triple backticks``` for code
-
-No ## headings. No [links](url). No **double stars**.
-```
-
-#### 5b. Update existing group CLAUDE.md headings
-
-In any group CLAUDE.md that has a "WhatsApp Formatting" section (e.g. `groups/main/CLAUDE.md`), rename the heading to reflect multi-channel support:
-
-```
-## WhatsApp Formatting (and other messaging apps)
-```
-
-#### 5c. Add Agent Teams instructions to Telegram groups
-
-For each Telegram group that will use agent teams, create or update its `groups/{folder}/CLAUDE.md` with these instructions. Read the existing CLAUDE.md first (or `groups/global/CLAUDE.md` as a base) and add the Agent Teams section:
-
-```markdown
-## Agent Teams
-
-When creating a team to tackle a complex task, follow these rules:
-
-### CRITICAL: Follow the user's prompt exactly
-
-Create *exactly* the team the user asked for — same number of agents, same roles, same names. Do NOT add extra agents, rename roles, or use generic names like "Researcher 1". If the user says "a marine biologist, a physicist, and Alexander Hamilton", create exactly those three agents with those exact names.
-
-### Team member instructions
-
-Each team member MUST be instructed to:
-
-1. *Share progress in the group* via `mcp__nanoclaw__send_message` with a `sender` parameter matching their exact role/character name (e.g., `sender: "Marine Biologist"` or `sender: "Alexander Hamilton"`). This makes their messages appear from a dedicated bot in the Telegram group.
-2. *Also communicate with teammates* via `SendMessage` as normal for coordination.
-3. Keep group messages *short* — 2-4 sentences max per message. Break longer content into multiple `send_message` calls. No walls of text.
-4. Use the `sender` parameter consistently — always the same name so the bot identity stays stable.
-5. NEVER use markdown formatting. Use ONLY WhatsApp/Telegram formatting: single *asterisks* for bold (NOT **double**), _underscores_ for italic, • for bullets, ```backticks``` for code. No ## headings, no [links](url), no **double asterisks**.
-
-### Example team creation prompt
-
-When creating a teammate, include instructions like:
-
-\```
-You are the Marine Biologist. When you have findings or updates for the user, send them to the group using mcp__nanoclaw__send_message with sender set to "Marine Biologist". Keep each message short (2-4 sentences max). Use emojis for strong reactions. ONLY use single *asterisks* for bold (never **double**), _underscores_ for italic, • for bullets. No markdown. Also communicate with teammates via SendMessage.
-\```
-
-### Lead agent behavior
-
-As the lead agent who created the team:
-
-- You do NOT need to react to or relay every teammate message. The user sees those directly from the teammate bots.
-- Send your own messages only to comment, share thoughts, synthesize, or direct the team.
-- When processing an internal update from a teammate that doesn't need a user-facing response, wrap your *entire* output in `<internal>` tags.
-- Focus on high-level coordination and the final synthesis.
-```
-
-### Step 6: Update Environment
-
-Add pool tokens to `.env`:
-
-```bash
-TELEGRAM_BOT_POOL=TOKEN1,TOKEN2,TOKEN3,...
-```
-
-**Important**: Sync to all required locations:
-
-```bash
-cp .env data/env/env
-```
-
-Also add `TELEGRAM_BOT_POOL` to the launchd plist (`~/Library/LaunchAgents/com.nanoclaw.plist`) in the `EnvironmentVariables` dict if using launchd.
-
-### Step 7: Rebuild and Restart
-
-```bash
-npm run build
-./container/build.sh  # Required — MCP tool changed
-# macOS:
-launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
-launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
-# Linux:
-# systemctl --user restart nanoclaw
-```
-
-Must use `unload/load` (macOS) or `restart` (Linux) because the service env vars changed.
-
-### Step 8: Test
-
-Tell the user:
-
-> Send a message in your Telegram group asking for a multi-agent task, e.g.:
-> "Assemble a team of a researcher and a coder to build me a hello world app"
->
-> You should see:
-> - The lead agent (main bot) acknowledging and creating the team
-> - Each subagent messaging from a different bot, renamed to their role
-> - Short, scannable messages from each agent
->
-> Check logs: `tail -f logs/nanoclaw.log | grep -i pool`
-
-## Architecture Notes
-
-- Pool bots use Grammy's `Api` class — lightweight, no polling, just send
-- Bot names are set via `setMyName` — changes are global to the bot, not per-chat
-- A 2-second delay after `setMyName` allows Telegram to propagate the name change before the first message
-- Sender→bot mapping is stable within a group (keyed as `{groupFolder}:{senderName}`)
-- Mapping resets on service restart — pool bots get reassigned fresh
-- If pool runs out, bots are reused (round-robin wraps)
-
-## Troubleshooting
-
-### Pool bots not sending messages
-
-1. Verify tokens: `curl -s "https://api.telegram.org/botTOKEN/getMe"`
-2. Check pool initialized: `grep "Pool bot" logs/nanoclaw.log`
-3. Ensure all pool bots are members of the Telegram group
-4. Check Group Privacy is disabled for each pool bot
-
-### Bot names not updating
-
-Telegram caches bot names client-side. The 2-second delay after `setMyName` helps, but users may need to restart their Telegram client to see updated names immediately.
-
-### Subagents not using send_message
-
-Check the group's `CLAUDE.md` has the Agent Teams instructions. The lead agent reads this when creating teammates and must include the `send_message` + `sender` instructions in each teammate's prompt.
-
-## Removal
-
-To remove Agent Swarm support while keeping basic Telegram:
-
-1. Remove `TELEGRAM_BOT_POOL` from `src/config.ts`
-2. Remove pool code from `src/telegram.ts` (`poolApis`, `senderBotMap`, `initBotPool`, `sendPoolMessage`)
-3. Remove pool routing from IPC handler in `src/index.ts` (revert to plain `sendMessage`)
-4. Remove `initBotPool` call from `main()`
-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)

.claude/skills/add-telegram/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/SKILL.md

@@ -1,231 +1,108 @@
 ---
 name: add-telegram
-description: Add Telegram as a channel. Can replace WhatsApp entirely or run alongside it. Also configurable as a control-only channel (triggers actions) or passive channel (receives notifications only).
+description: Add Telegram channel integration via Chat SDK.
 ---
 
 # Add Telegram Channel
 
-This skill adds Telegram support to NanoClaw using the skills engine for deterministic code changes, then walks through interactive setup.
+Adds Telegram bot support via the Chat SDK bridge.
 
-## Phase 1: Pre-flight
+## Install
 
-### Check if already applied
+NanoClaw doesn't ship channels in trunk. This skill copies the Telegram adapter, its formatting/pairing helpers, their tests, and the `pair-telegram` setup step in from the `channels` branch.
 
-Read `.nanoclaw/state.yaml`. If `telegram` is in `applied_skills`, skip to Phase 3 (Setup). The code changes are already in place.
+### Pre-flight (idempotent)
 
-### Ask the user
+Skip to **Credentials** if all of these are already in place:
 
-Use `AskUserQuestion` to collect configuration:
+- `src/channels/telegram.ts`, `telegram-pairing.ts`, `telegram-markdown-sanitize.ts` (and their `.test.ts` siblings) all exist
+- `src/channels/index.ts` contains `import './telegram.js';`
+- `setup/pair-telegram.ts` exists and `setup/index.ts`'s `STEPS` map contains `'pair-telegram':`
+- `@chat-adapter/telegram` is listed in `package.json` dependencies
 
-AskUserQuestion: Do you have a Telegram bot token, or do you need to create one?
+Otherwise continue. Every step below is safe to re-run.
 
-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:
+### 1. Fetch the channels branch
 
 ```bash
-npx tsx scripts/apply-skill.ts --init
+git fetch origin channels
 ```
 
-Or call `initSkillsSystem()` from `skills-engine/migrate.ts`.
-
-### Apply the skill
+### 2. Copy the adapter, helpers, tests, and setup step
 
 ```bash
-npx tsx scripts/apply-skill.ts .claude/skills/add-telegram
+git show origin/channels:src/channels/telegram.ts                        > src/channels/telegram.ts
+git show origin/channels:src/channels/telegram-pairing.ts                > src/channels/telegram-pairing.ts
+git show origin/channels:src/channels/telegram-pairing.test.ts           > src/channels/telegram-pairing.test.ts
+git show origin/channels:src/channels/telegram-markdown-sanitize.ts      > src/channels/telegram-markdown-sanitize.ts
+git show origin/channels:src/channels/telegram-markdown-sanitize.test.ts > src/channels/telegram-markdown-sanitize.test.ts
+git show origin/channels:setup/pair-telegram.ts                          > setup/pair-telegram.ts
 ```
 
-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`
+### 3. Append the self-registration import
 
-If the apply reports merge conflicts, read the intent file:
-- `modify/src/channels/index.ts.intent.md` — what changed and invariants
+Append to `src/channels/index.ts` (skip if already present):
 
-### Validate code changes
+```typescript
+import './telegram.js';
+```
+
+### 4. Register the setup step
+
+In `setup/index.ts`, add this entry to the `STEPS` map (right after the `register` line is fine; skip if already present):
+
+```typescript
+'pair-telegram': () => import('./pair-telegram.js'),
+```
+
+### 5. Install the adapter package (pinned)
 
 ```bash
-npm test
-npm run build
+pnpm install @chat-adapter/telegram@4.26.0
 ```
 
-All tests must pass (including the new telegram tests) and build must be clean before proceeding.
+### 6. Build
 
-## Phase 3: Setup
+```bash
+pnpm run build
+```
 
-### Create Telegram Bot (if needed)
+## Credentials
 
-If the user doesn't have a bot token, tell them:
+### Create Telegram Bot
 
-> I need you to create a Telegram bot:
->
-> 1. Open Telegram and search for `@BotFather`
-> 2. Send `/newbot` and follow prompts:
->    - Bot name: Something friendly (e.g., "Andy Assistant")
->    - Bot username: Must end with "bot" (e.g., "andy_ai_bot")
-> 3. Copy the bot token (looks like `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`)
+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`)
 
-Wait for the user to provide the token.
+**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=<their-token>
+TELEGRAM_BOT_TOKEN=your-bot-token
 ```
 
-Channels auto-enable when their credentials are present — no extra configuration needed.
+Sync to container: `mkdir -p data/env && cp .env data/env/env`
 
-Sync to container environment:
+## Next Steps
 
-```bash
-mkdir -p data/env && cp .env data/env/env
-```
+If you're in the middle of `/setup`, return to the setup flow now.
 
-The container reads environment from `data/env/env`, not `.env` directly.
+Otherwise, run `/manage-channels` to wire this channel to an agent group.
 
-### Disable Group Privacy (for group chats)
+## Channel Info
 
-Tell the user:
-
-> **Important for group chats**: By default, Telegram bots only see @mentions and commands in groups. To let the bot see all messages:
->
-> 1. Open Telegram and search for `@BotFather`
-> 2. Send `/mybots` and select your bot
-> 3. Go to **Bot Settings** > **Group Privacy** > **Turn off**
->
-> This is optional if you only want trigger-based responses via @mentioning the bot.
-
-### Build and restart
-
-```bash
-npm run build
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
-# Linux: systemctl --user restart nanoclaw
-```
-
-## Phase 4: Registration
-
-### Get Chat ID
-
-Tell the user:
-
-> 1. Open your bot in Telegram (search for its username)
-> 2. Send `/chatid` — it will reply with the chat ID
-> 3. For groups: add the bot to the group first, then send `/chatid` in the group
-
-Wait for the user to provide the chat ID (format: `tg:123456789` or `tg:-1001234567890`).
-
-### Register the chat
-
-Use the IPC register flow or register directly. The chat ID, name, and folder name are needed.
-
-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,
-});
-```
-
-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,
-});
-```
-
-## Phase 5: Verify
-
-### Test the connection
-
-Tell the user:
-
-> Send a message to your registered Telegram chat:
-> - For main chat: Any message works
-> - For non-main: `@Andy hello` or @mention the bot
->
-> The bot should respond within a few seconds.
-
-### Check logs if needed
-
-```bash
-tail -f logs/nanoclaw.log
-```
-
-## Troubleshooting
-
-### Bot not responding
-
-Check:
-1. `TELEGRAM_BOT_TOKEN` is set in `.env` AND synced to `data/env/env`
-2. Chat is registered in SQLite (check with: `sqlite3 store/messages.db "SELECT * FROM registered_groups WHERE jid LIKE 'tg:%'"`)
-3. For non-main chats: message includes trigger pattern
-4. Service is running: `launchctl list | grep nanoclaw` (macOS) or `systemctl --user status nanoclaw` (Linux)
-
-### Bot only responds to @mentions in groups
-
-Group Privacy is enabled (default). Fix:
-1. `@BotFather` > `/mybots` > select bot > **Bot Settings** > **Group Privacy** > **Turn off**
-2. Remove and re-add the bot to the group (required for the change to take effect)
-
-### Getting chat ID
-
-If `/chatid` doesn't work:
-- Verify token: `curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMe"`
-- Check bot is started: `tail -f logs/nanoclaw.log`
-
-## After Setup
-
-If running `npm run dev` while the service is active:
-```bash
-# macOS:
-launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
-npm run dev
-# When done testing:
-launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
-# Linux:
-# systemctl --user stop nanoclaw
-# npm 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:
-
-1. Delete `src/channels/telegram.ts` and `src/channels/telegram.test.ts`
-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)
+- **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/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/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

@@ -1,141 +0,0 @@
----
-name: add-voice-transcription
-description: Add voice message transcription to NanoClaw using OpenAI's Whisper API. Automatically transcribes WhatsApp voice notes so the agent can read and respond to them.
----
-
-# Add Voice Transcription
-
-This skill adds automatic voice message transcription to NanoClaw's WhatsApp channel using OpenAI's Whisper API. When a voice note arrives, it is downloaded, transcribed, and delivered to the agent as `[Voice: <transcript>]`.
-
-## Phase 1: Pre-flight
-
-### 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.
-
-### Ask the user
-
-Use `AskUserQuestion` to collect information:
-
-AskUserQuestion: Do you have an OpenAI API key for Whisper transcription?
-
-If yes, collect it now. If no, direct them to create one at https://platform.openai.com/api-keys.
-
-## Phase 2: Apply Code Changes
-
-Run the skills engine to apply this skill's code package.
-
-### Initialize skills system (if needed)
-
-If `.nanoclaw/` directory doesn't exist yet:
-
-```bash
-npx tsx scripts/apply-skill.ts --init
-```
-
-### Apply the skill
-
-```bash
-npx tsx scripts/apply-skill.ts .claude/skills/add-voice-transcription
-```
-
-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`
-
-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
-
-### Validate code changes
-
-```bash
-npm test
-npm run build
-```
-
-All tests must pass (including the 3 new voice transcription tests) and build must be clean before proceeding.
-
-## Phase 3: Configure
-
-### Get OpenAI API key (if needed)
-
-If the user doesn't have an API key:
-
-> I need you to create an OpenAI API key:
->
-> 1. Go to https://platform.openai.com/api-keys
-> 2. Click "Create new secret key"
-> 3. Give it a name (e.g., "NanoClaw Transcription")
-> 4. Copy the key (starts with `sk-`)
->
-> Cost: ~$0.006 per minute of audio (~$0.003 per typical 30-second voice note)
-
-Wait for the user to provide the key.
-
-### Add to environment
-
-Add to `.env`:
-
-```bash
-OPENAI_API_KEY=<their-key>
-```
-
-Sync to container environment:
-
-```bash
-mkdir -p data/env && cp .env data/env/env
-```
-
-The container reads environment from `data/env/env`, not `.env` directly.
-
-### Build and restart
-
-```bash
-npm run build
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
-# Linux: systemctl --user restart nanoclaw
-```
-
-## Phase 4: Verify
-
-### Test with a voice note
-
-Tell the user:
-
-> Send a voice note in any registered WhatsApp chat. The agent should receive it as `[Voice: <transcript>]` and respond to its content.
-
-### Check logs if needed
-
-```bash
-tail -f logs/nanoclaw.log | grep -i voice
-```
-
-Look for:
-- `Transcribed voice message` — successful transcription with character count
-- `OPENAI_API_KEY not set` — key missing from `.env`
-- `OpenAI transcription failed` — API error (check key validity, billing)
-- `Failed to download audio message` — media download issue
-
-## Troubleshooting
-
-### Voice notes show "[Voice Message - transcription unavailable]"
-
-1. Check `OPENAI_API_KEY` is set in `.env` AND synced to `data/env/env`
-2. Verify key works: `curl -s https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY" | head -c 200`
-3. Check OpenAI billing — Whisper requires a funded account
-
-### Voice notes show "[Voice Message - transcription failed]"
-
-Check logs for the specific error. Common causes:
-- Network timeout — transient, will work on next message
-- Invalid API key — regenerate at https://platform.openai.com/api-keys
-- Rate limiting — wait and retry
-
-### Agent doesn't respond to voice notes
-
-Verify the chat is registered and the agent is running. Voice transcription only runs for registered groups.

.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/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/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: add-webex
+description: Add Webex channel integration via Chat SDK.
+---
+
+# Add Webex Channel
+
+Adds Cisco Webex support via the Chat SDK bridge.
+
+## Install
+
+NanoClaw doesn't ship channels in trunk. This skill copies the Webex adapter in from the `channels` branch.
+
+### Pre-flight (idempotent)
+
+Skip to **Credentials** if all of these are already in place:
+
+- `src/channels/webex.ts` exists
+- `src/channels/index.ts` contains `import './webex.js';`
+- `@bitbasti/chat-adapter-webex` is listed in `package.json` dependencies
+
+Otherwise continue. Every step below is safe to re-run.
+
+### 1. Fetch the channels branch
+
+```bash
+git fetch origin channels
+```
+
+### 2. Copy the adapter
+
+```bash
+git show origin/channels:src/channels/webex.ts > src/channels/webex.ts
+```
+
+### 3. Append the self-registration import
+
+Append to `src/channels/index.ts` (skip if the line is already present):
+
+```typescript
+import './webex.js';
+```
+
+### 4. Install the adapter package (pinned)
+
+```bash
+pnpm install @bitbasti/chat-adapter-webex@0.1.0
+```
+
+### 5. Build
+
+```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/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-wechat/REMOVE.md

@@ -0,0 +1,49 @@
+# Remove WeChat Channel
+
+Undo `/add-wechat`.
+
+### 1. Remove credentials
+
+Delete WeChat lines from `.env`:
+
+```bash
+sed -i.bak '/^WECHAT_ENABLED=/d' .env && rm -f .env.bak
+cp .env data/env/env
+```
+
+### 2. Remove adapter and import
+
+```bash
+rm -f src/channels/wechat.ts
+sed -i.bak "/import '\.\/wechat\.js';/d" src/channels/index.ts && rm -f src/channels/index.ts.bak
+```
+
+### 3. Uninstall the package
+
+```bash
+pnpm remove wechat-ilink-client
+```
+
+### 4. Remove saved auth + sync state
+
+```bash
+rm -rf data/wechat
+```
+
+### 5. Remove DB wiring
+
+```sql
+-- Remove any sessions first (foreign key)
+DELETE FROM sessions WHERE messaging_group_id IN (SELECT id FROM messaging_groups WHERE channel_type = 'wechat');
+DELETE FROM messaging_group_agents WHERE messaging_group_id IN (SELECT id FROM messaging_groups WHERE channel_type = 'wechat');
+DELETE FROM messaging_groups WHERE channel_type = 'wechat';
+```
+
+### 6. Rebuild and restart
+
+```bash
+pnpm run build
+systemctl --user restart nanoclaw   # Linux
+# or
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw   # macOS
+```

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

@@ -0,0 +1,170 @@
+---
+name: add-wechat
+description: Add WeChat (personal) channel integration via Tencent's official iLink Bot API. Uses long-polling and QR scan — no webhook, no ToS risk, no paid token.
+---
+
+# Add WeChat Channel
+
+Adds WeChat support via **iLink Bot API** — the first-party Tencent API for personal WeChat bots (different from WeCom / Official Account).
+
+**Why this is different from wechaty/PadLocal:**
+
+- Official Tencent API — no ToS violation, no ban risk
+- Free — no PadLocal token required
+- No public webhook URL needed — uses long-poll
+- Works with any personal WeChat account
+
+## Prerequisites
+
+- A **personal WeChat account** with the mobile app installed
+- A phone to scan the QR code for login
+- Node.js >= 20 (already required by NanoClaw)
+
+## Install
+
+NanoClaw doesn't ship channels in trunk. This skill copies the WeChat adapter in from the `channels` branch.
+
+### Pre-flight (idempotent)
+
+Skip to **Credentials** if all of these are already in place:
+
+- `src/channels/wechat.ts` exists
+- `src/channels/index.ts` contains `import './wechat.js';`
+- `wechat-ilink-client` is listed in `package.json` dependencies
+
+Otherwise continue. Every step below is safe to re-run.
+
+### 1. Fetch the channels branch
+
+```bash
+git fetch origin channels
+```
+
+### 2. Copy the adapter
+
+```bash
+git show origin/channels:src/channels/wechat.ts > src/channels/wechat.ts
+```
+
+### 3. Append the self-registration import
+
+Append to `src/channels/index.ts` (skip if the line is already present):
+
+```typescript
+import './wechat.js';
+```
+
+### 4. Install the library (pinned)
+
+```bash
+pnpm install wechat-ilink-client@0.1.0
+```
+
+### 5. Build
+
+```bash
+pnpm run build
+```
+
+## Credentials
+
+Unlike most channels, WeChat requires **no pre-configured API keys**. Auth happens via QR code scan from your phone.
+
+### 1. Enable the channel
+
+Add to `.env`:
+
+```bash
+WECHAT_ENABLED=true
+```
+
+Sync to container: `mkdir -p data/env && cp .env data/env/env`
+
+### 2. Start the service and scan the QR
+
+Restart NanoClaw:
+
+```bash
+systemctl --user restart nanoclaw   # Linux
+# or
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw   # macOS
+```
+
+The adapter will print a **QR URL** to the logs and save it to `data/wechat/qr.txt`:
+
+```bash
+tail -f logs/nanoclaw.log | grep WeChat
+# or
+cat data/wechat/qr.txt
+```
+
+Open the URL in a browser (it renders a QR code), then:
+
+1. Open WeChat on your phone
+2. Use its built-in QR scanner (top-right "+" → Scan)
+3. Approve the authorization on your phone
+4. Auth credentials are saved to `data/wechat/auth.json` — do not commit this file
+
+The bot is now connected as your WeChat account.
+
+## Wire your first DM
+
+A successful QR login alone isn't enough — the adapter still needs to be wired to an agent group before it can respond.
+
+### 1. Trigger the first inbound message
+
+Have a different WeChat account send a message to the bot account. This auto-creates a `messaging_groups` row with the sender's `platform_id`.
+
+### 2. Run the wire script
+
+```bash
+pnpm exec tsx .claude/skills/add-wechat/scripts/wire-dm.ts
+```
+
+Interactive flow: the script lists all unwired WeChat messaging groups, asks which agent group to wire it to, and creates the `messaging_group_agents` row with sensible defaults (sender policy `request_approval`, session mode `shared`).
+
+With `request_approval`, the next DM from the stranger fires an approval card to the admin — admin taps Approve/Deny, approved users are added as members and their queued message replays through the agent.
+
+Non-interactive:
+
+```bash
+pnpm exec tsx .claude/skills/add-wechat/scripts/wire-dm.ts \
+  --platform-id wechat:wxid_xxxxx \
+  --agent-group ag-xxxxx \
+  --non-interactive
+```
+
+Flags:
+
+- `--platform-id <id>` — wire a specific messaging group (default: most recent unwired)
+- `--agent-group <id>` — target agent group (default: prompt; or solo admin group in non-interactive)
+- `--sender-policy public|strict|request_approval` — default `request_approval` (fires an admin approval card on unknown-sender DMs)
+- `--session-mode shared|per-thread` — default `shared`
+
+### 3. Test
+
+Have the sender message the bot again — the agent should respond.
+
+## Operational notes
+
+- **Only one instance can use a given token at a time.** Don't run multiple NanoClaw instances pointing to the same `data/wechat/auth.json`.
+- **Re-login on session expiry:** if you see `WeChat: session expired` in logs, delete `data/wechat/auth.json` and restart — you'll be asked to re-scan.
+- **Sync cursor persistence:** `data/wechat/sync-buf.txt` holds the long-poll cursor. Deleting it replays recent history on next start; don't delete it in normal operation.
+- **Account safety:** this uses the official Tencent API, so account bans for bot automation aren't a risk. That said, don't spam — normal rate limits still apply.
+
+## Next Steps
+
+If you're in the middle of `/setup`, return to the setup flow now.
+
+Otherwise, restart the service to pick up the new channel and wiring.
+
+## Channel Info
+
+- **type**: `wechat`
+- **terminology**: WeChat has "contacts" (DMs) and "group chats" (rooms). Each DM or group is a separate messaging group.
+- **how-to-find-id**: Send a message to the bot from the target account; the adapter auto-creates a messaging group and logs `WeChat inbound platformId=wechat:<id>`. Use `wechat:<user_id>` for DMs, `wechat:<group_id>` for rooms.
+- **admin-user-id**: The operator's WeChat user_id (for `init-first-agent.ts --admin-user-id`) is saved to `data/wechat/auth.json` as `operatorUserId` after the QR scan. Read it with `cat data/wechat/auth.json | jq -r .operatorUserId` and prefix with `wechat:` (i.e. `wechat:<operatorUserId>`).
+- **supports-threads**: no (WeChat has no reply threads)
+- **typical-use**: Long-poll — the adapter holds a persistent connection to Tencent's iLink API and receives messages in real time. No webhook URL needed.
+- **default-isolation**: `shared` session mode per messaging group (DM or room). Use `strict` sender policy if you want only specific users to reach the agent; `public` opens it to anyone who messages the bot.
+- **post-install-wiring**: Use the `wire-dm.ts` helper (see the "Wire your first DM" section above) if running this skill standalone. If running as part of `bash nanoclaw.sh`, `init-first-agent.ts` handles wiring — just pass the `platform-id` and `admin-user-id` captured above.

.claude/skills/add-wechat/scripts/wire-dm.ts

@@ -0,0 +1,172 @@
+#!/usr/bin/env pnpm exec tsx
+/**
+ * Wire a WeChat DM (or group) to an agent group.
+ *
+ * After /add-wechat installs the adapter and the user scans the QR login,
+ * the first inbound message from another WeChat account auto-creates a
+ * `messaging_groups` row. This script finds that row, asks the operator
+ * which agent group to wire it to, and inserts the `messaging_group_agents`
+ * join row with sensible defaults — the "post-login wiring" step /add-wechat
+ * otherwise requires manual SQL for.
+ *
+ * Usage:
+ *   pnpm exec tsx .claude/skills/add-wechat/scripts/wire-dm.ts
+ *
+ * Flags:
+ *   --platform-id <id>      Wire a specific messaging group (default: most recent unwired)
+ *   --agent-group <id>      Target agent group (default: interactive pick; or solo admin group)
+ *   --sender-policy <p>     public | strict (default: public)
+ *   --session-mode <m>      shared | per-thread (default: shared)
+ *   --non-interactive       Fail instead of prompting
+ */
+import Database from 'better-sqlite3';
+import path from 'node:path';
+import readline from 'node:readline';
+
+const DB_PATH = process.env.NANOCLAW_DB_PATH ?? path.join(process.cwd(), 'data', 'v2.db');
+
+type SenderPolicy = 'public' | 'strict' | 'request_approval';
+
+interface Args {
+  platformId?: string;
+  agentGroupId?: string;
+  senderPolicy: SenderPolicy;
+  sessionMode: 'shared' | 'per-thread';
+  interactive: boolean;
+}
+
+function parseArgs(argv: string[]): Args {
+  const args: Args = {
+    // Default matches the router's auto-create (`request_approval`) so the
+    // admin gets an approval card on the next unknown-sender DM rather than
+    // a silent allow. Pass `--sender-policy public` to open the channel to
+    // anyone, or `strict` to require explicit membership.
+    senderPolicy: 'request_approval',
+    sessionMode: 'shared',
+    interactive: true,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    const val = argv[i + 1];
+    switch (flag) {
+      case '--platform-id': args.platformId = val; i++; break;
+      case '--agent-group': args.agentGroupId = val; i++; break;
+      case '--sender-policy':
+        if (val !== 'public' && val !== 'strict' && val !== 'request_approval') {
+          throw new Error(`bad --sender-policy: ${val} (use public | strict | request_approval)`);
+        }
+        args.senderPolicy = val; i++; break;
+      case '--session-mode':
+        if (val !== 'shared' && val !== 'per-thread') throw new Error(`bad --session-mode: ${val}`);
+        args.sessionMode = val; i++; break;
+      case '--non-interactive': args.interactive = false; break;
+      case '--help': case '-h':
+        console.log('See .claude/skills/add-wechat/scripts/wire-dm.ts header for usage.');
+        process.exit(0);
+    }
+  }
+  return args;
+}
+
+async function prompt(q: string): Promise<string> {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => rl.question(q, (a) => { rl.close(); resolve(a.trim()); }));
+}
+
+function generateId(prefix: string): string {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+  const db = new Database(DB_PATH);
+  db.pragma('journal_mode = WAL');
+
+  // 1. Pick the messaging group
+  let platformId = args.platformId;
+  if (!platformId) {
+    const rows = db.prepare(`
+      SELECT mg.id, mg.platform_id, mg.name, mg.is_group, mg.created_at
+      FROM messaging_groups mg
+      LEFT JOIN messaging_group_agents mga ON mga.messaging_group_id = mg.id
+      WHERE mg.channel_type = 'wechat' AND mga.id IS NULL
+      ORDER BY mg.created_at DESC
+    `).all() as Array<{ id: string; platform_id: string; name: string | null; is_group: number; created_at: string }>;
+
+    if (rows.length === 0) {
+      console.error('No unwired WeChat messaging groups found.');
+      console.error('Send a message to the bot first (from another WeChat account), then re-run.');
+      process.exit(1);
+    }
+
+    if (rows.length === 1 || !args.interactive) {
+      platformId = rows[0].platform_id;
+      console.log(`Using most recent unwired group: ${platformId} (${rows[0].is_group ? 'group' : 'DM'})`);
+    } else {
+      console.log('Unwired WeChat messaging groups:');
+      rows.forEach((r, i) => {
+        console.log(`  ${i + 1}. ${r.platform_id}  (${r.is_group ? 'group' : 'DM'}, ${r.created_at})`);
+      });
+      const pick = await prompt('Pick one [1]: ');
+      const idx = pick === '' ? 0 : parseInt(pick, 10) - 1;
+      if (Number.isNaN(idx) || idx < 0 || idx >= rows.length) throw new Error('invalid choice');
+      platformId = rows[idx].platform_id;
+    }
+  }
+
+  const mg = db.prepare(
+    'SELECT id, platform_id, is_group FROM messaging_groups WHERE channel_type = ? AND platform_id = ?'
+  ).get('wechat', platformId) as { id: string; platform_id: string; is_group: number } | undefined;
+  if (!mg) throw new Error(`no wechat messaging_group with platform_id = ${platformId}`);
+
+  // 2. Pick the agent group
+  let agentGroupId = args.agentGroupId;
+  if (!agentGroupId) {
+    const agents = db.prepare('SELECT id, name, is_admin FROM agent_groups ORDER BY is_admin DESC, created_at ASC')
+      .all() as Array<{ id: string; name: string; is_admin: number }>;
+    if (agents.length === 0) throw new Error('no agent groups exist — create one first');
+
+    const adminAgents = agents.filter((a) => a.is_admin === 1);
+    if (adminAgents.length === 1 && !args.interactive) {
+      agentGroupId = adminAgents[0].id;
+      console.log(`Auto-selected sole admin agent group: ${adminAgents[0].name} (${agentGroupId})`);
+    } else if (args.interactive) {
+      console.log('Agent groups:');
+      agents.forEach((a, i) => {
+        console.log(`  ${i + 1}. ${a.name} (${a.id})${a.is_admin ? ' [admin]' : ''}`);
+      });
+      const pick = await prompt('Pick one [1]: ');
+      const idx = pick === '' ? 0 : parseInt(pick, 10) - 1;
+      if (Number.isNaN(idx) || idx < 0 || idx >= agents.length) throw new Error('invalid choice');
+      agentGroupId = agents[idx].id;
+    } else {
+      throw new Error('multiple agent groups exist; pass --agent-group <id>');
+    }
+  }
+
+  const ag = db.prepare('SELECT id, name FROM agent_groups WHERE id = ?').get(agentGroupId) as
+    { id: string; name: string } | undefined;
+  if (!ag) throw new Error(`no agent_group with id = ${agentGroupId}`);
+
+  // 3. Update sender policy + wire
+  const tx = db.transaction(() => {
+    db.prepare('UPDATE messaging_groups SET unknown_sender_policy = ? WHERE id = ?')
+      .run(args.senderPolicy, mg.id);
+
+    db.prepare(`
+      INSERT INTO messaging_group_agents
+        (id, messaging_group_id, agent_group_id, trigger_rules, response_scope, session_mode, priority, created_at)
+      VALUES (?, ?, ?, '', 'all', ?, 10, datetime('now'))
+    `).run(generateId('mga'), mg.id, ag.id, args.sessionMode);
+  });
+  tx();
+
+  console.log('');
+  console.log(`WIRED platform_id=${mg.platform_id} agent_group=${ag.name} policy=${args.senderPolicy} mode=${args.sessionMode}`);
+  db.close();
+}
+
+main().catch((err) => {
+  console.error('FAILED:', err.message);
+  process.exit(1);
+});

.claude/skills/add-whatsapp-cloud/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/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: add-whatsapp-cloud
+description: Add WhatsApp Business Cloud API channel via Chat SDK. Official Meta API.
+---
+
+# Add WhatsApp Cloud API Channel
+
+Connect NanoClaw to WhatsApp via the official Meta WhatsApp Business Cloud API.
+
+## Install
+
+NanoClaw doesn't ship channels in trunk. This skill copies the WhatsApp Cloud adapter in from the `channels` branch.
+
+### Pre-flight (idempotent)
+
+Skip to **Credentials** if all of these are already in place:
+
+- `src/channels/whatsapp-cloud.ts` exists
+- `src/channels/index.ts` contains `import './whatsapp-cloud.js';`
+- `@chat-adapter/whatsapp` is listed in `package.json` dependencies
+
+Otherwise continue. Every step below is safe to re-run.
+
+### 1. Fetch the channels branch
+
+```bash
+git fetch origin channels
+```
+
+### 2. Copy the adapter
+
+```bash
+git show origin/channels:src/channels/whatsapp-cloud.ts > src/channels/whatsapp-cloud.ts
+```
+
+### 3. Append the self-registration import
+
+Append to `src/channels/index.ts` (skip if the line is already present):
+
+```typescript
+import './whatsapp-cloud.js';
+```
+
+### 4. Install the adapter package (pinned)
+
+```bash
+pnpm install @chat-adapter/whatsapp@4.26.0
+```
+
+### 5. 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.