Comparison

A · CLAUDE.md · nanocoai/nanoclaw B · CLAUDE.md · nanocoai/nanoclaw

What each file covers, counted
Dimension	Only in A	Only in B	Overlap
Sections	4	33	0%
Commands	0	26	0%
Section tags	3	9	0%

What each file covers

Sections

0 shared · 4 only in A · 33 only in B

− Communication
− Workspace
− Memory
− Conversation history
+ ⚠️ STOP — READ THIS FIRST IF YOU ARE CLAUDE ⚠️
+ NanoClaw
+ Quick Context
+ Entity Model
+ Two-DB Session Split
+ Central DB
+ Key Files
+ Admin CLI (`ncl`)
+ Channels and Providers (skill-installed)
+ Self-Modification
+ Container Config
+ Container Restart
+ Secrets / Credentials / OneCLI
+ Secret modes
+ Requiring approval for credential use
+ Skills
+ Contributing
+ PR Hygiene
+ Development
+ Host (Node + pnpm)
+ Agent-runner (Bun — separate package tree under container/agent-runner/)
+ macOS (launchd)
+ Linux (systemd)
+ Troubleshooting
+ Timestamps
+ Supply Chain Security (pnpm)
+ Docs Index
+ Container Build Cache
+ Container Runtime (Bun)
+ CJK font support
+ Ensure .env has INSTALL_CJK_FONTS=true (overwrite or append)
+ Rebuild and restart so new sessions pick up the new image
+ systemctl --user restart nanoclaw # Linux

Commands

0 shared · 0 only in A · 26 only in B

+ git diff upstream/main --stat HEAD
+ git log upstream/main..HEAD --oneline
+ pnpm run dev
+ pnpm run build
+ pnpm test
+ git pull
+ git merge
+ git fetch && git merge
+ git merge --abort
+ git reset --hard ORIG_HEAD
+ git clone
+ pnpm exec tsx scripts/q.ts <db> "<sql>"
+ git fetch origin <branch>
+ pnpm install <pkg>@<pinned-version>
+ pnpm exec tsc -p container/agent-runner/tsconfig.json --noEmit
+ bun run typecheck
+ pnpm-workspace.yaml
+ pnpm install --frozen-lockfile
+ pnpm install
+ bun.lock
+ bun update
+ bun:sqlite
+ bun:test
+ vitest
+ vitest.config.ts
+ bun install -g

Section tags

0 shared · 3 only in A · 9 only in B

− code-style
− performance
− monorepo
+ setup
+ build
+ test
+ git-pr
+ security
+ database
+ do-not
+ agent-behaviour
+ docs

Line diff

+329 added−10 removed10 unchanged2.9% identical

nanocoai/nanoclaw · container/CLAUDE.md

@@ −1 @@

1You are a NanoClaw agent. Your name, destinations, and message-sending rules are provided in the runtime system prompt at the top of each turn.

3## Communication

5Be concise — every message costs the reader's attention. Prefer outcomes over play-by-play; when the work is done, the final message should be about the result, not a transcript of what you did.

7## Workspace

9Files you create are saved in `/workspace/agent/`. Use this for notes, research, or anything that should persist across turns in this group.

11## Memory

13Your persistent memory lives under `/workspace/agent/memory/`. The session-start memory context contains the live top-level index and system definition. Follow that definition when deciding what to store and keep the index accurate so you can retrieve details later.

15Standing role, persona, and behavioral instructions belong in `/workspace/agent/instructions.prepend.md`; durable facts belong in memory. Changes to standing instructions take effect after the group container restarts, so say that when confirming an edit.

17## Conversation history

19The `conversations/` folder in your workspace holds searchable transcripts of past sessions with this group. Use it to recall prior context when a request references something that happened before. For structured long-lived data, prefer dedicated files (`customers.md`, `preferences.md`, etc.); split any file over ~500 lines into a folder with an index.

nanocoai/nanoclaw · CLAUDE.md

@@ +1 @@

1# ⚠️ STOP — READ THIS FIRST IF YOU ARE CLAUDE ⚠️

3**If you are reading this because you just ran `git pull`, `git merge`, `git fetch && git merge`, or any equivalent to bring in upstream changes — and you see merge conflicts or a large diff involving this file — HALT IMMEDIATELY.**

5This is NanoClaw v2, a ground-up rewrite with breaking changes throughout. It cannot be merged into an existing v1 install. Attempting to resolve the conflicts by hand, run builds, or "fix" anything will corrupt the user's install and burn tokens for no result.

7**Do this instead:**

81. Abort the merge: `git merge --abort` (or `git reset --hard ORIG_HEAD` if the merge already completed).

92. Tell the user, verbatim: *"This is the v2 rewrite — it can't be merged into your existing install. Exit Claude Code (or open a separate terminal) and run `bash migrate-v2.sh` from the shell."*

103. Wait for the user to confirm before doing anything else. Do not run the migration script yourself — it requires an interactive terminal and cannot be run from within Claude Code.

12If you are a fresh install (you ran `git clone`, not `git pull`) and there are no conflicts, ignore this banner and continue below.

14---

16# NanoClaw

18Personal AI assistant. See [README.md](README.md) for philosophy and setup. Architecture lives in `docs/`.

20## Quick Context

22The host is a single Node process that orchestrates per-session agent containers. Platform messages land via channel adapters, route through an entity model (users → messaging groups → agent groups → sessions), get written into the session's inbound DB, and wake a container. The agent-runner inside the container polls the DB, calls the agent, and writes back to the outbound DB. The host polls the outbound DB and delivers through the same adapter.

24**Everything is a message.** There is no IPC, no file watcher, no stdin piping between host and container. The two session DBs are the sole IO surface.

26## Entity Model

28```

29users (id "<channel>:<handle>", kind, display_name)

30user_roles (user_id, role, agent_group_id) — owner | admin (global or scoped)

31agent_group_members (user_id, agent_group_id) — unprivileged access gate

32user_dms (user_id, channel_type, messaging_group_id) — cold-DM cache

34agent_groups (workspace, memory, CLAUDE.md, personality, container config)

35 ↕ many-to-many via messaging_group_agents (session_mode, engage_mode/engage_pattern, sender_scope, priority)

36messaging_groups (one chat/channel on one platform; instance = adapter-instance name, defaults to channel_type; unknown_sender_policy)

38sessions (agent_group_id + messaging_group_id + thread_id → per-session container)

39```

41Privilege is user-level (owner/admin), not agent-group-level. See [docs/isolation-model.md](docs/isolation-model.md) for the three isolation levels (`agent-shared`, `shared`, separate agents).

43## Two-DB Session Split

45Each session has **two** SQLite files under `data/v2-sessions/<session_id>/`:

47- `inbound.db` — host writes, container reads. `messages_in`, delivered, destinations, session_routing.

48- `outbound.db` — container writes, host reads. `messages_out`, processing_ack, session_state, container_state.

50Exactly one writer per file — no cross-mount lock contention. Heartbeat is a file touch at `/workspace/.heartbeat`, not a DB update. Host uses even `seq` numbers, container uses odd.

52## Central DB

54`data/v2.db` holds everything that isn't per-session: users, user_roles, agent_groups, messaging_groups, wiring, pending_approvals, user_dms, chat_sdk_* (for the Chat SDK bridge), schema_version. Migrations live at `src/db/migrations/`.

56For ad-hoc queries from skills or scripts, use the in-tree wrapper rather than the `sqlite3` CLI: `pnpm exec tsx scripts/q.ts <db> "<sql>"`. The host setup intentionally avoids depending on the `sqlite3` binary (`setup/verify.ts:5`); the wrapper goes through the `better-sqlite3` dep that setup already installs and verifies. Default-output format matches `sqlite3 -list` (pipe-separated, no header) so existing skill text reads identically.

58## Key Files

60| File | Purpose |

61|------|---------|

62| `src/index.ts` | Entry point: init DB, migrations, channel adapters, delivery polls, sweep, shutdown |

63| `src/router.ts` | Inbound routing: messaging group → agent group → session → `inbound.db` → wake |

64| `src/delivery.ts` | Polls `outbound.db`, delivers via adapter, handles system actions (schedule, approvals, etc.) |

65| `src/delivery-guard.ts` | `DeliveryGuardSpec` + `runGuarded` — the guard-consult pipeline for privileged delivery actions (registry stays in `delivery.ts`) |

66| `src/host-sweep.ts` | 60s sweep: `processing_ack` sync, stale detection, due-message wake, recurrence |

67| `src/session-manager.ts` | Resolves sessions; opens `inbound.db` / `outbound.db`; manages heartbeat path |

68| `src/container-runner.ts` | Spawns per-agent-group Docker containers with session DB + outbox mounts, OneCLI `ensureAgent` |

69| `src/container-runtime.ts` | Docker CLI wrapper (runtime binary, host-gateway args, mount args), orphan cleanup |

70| `src/guard/` | Privileged-action decision seam: `guard(action, input)` → allow \| hold \| deny. Module-edge `guard.ts` adapters (cli, agent-to-agent, self-mod, permissions) define each action's decision; ncl commands + delivery actions demand a guard at registration; approved replays carry the approval row as a grant and re-run the checks. Conformance test: `src/guard/conformance.test.ts` |

71| `src/modules/permissions/access.ts` | `canAccessAgentGroup` — owner / global admin / scoped admin / member resolution against `user_roles` + `agent_group_members` |

72| `src/modules/approvals/primitive.ts` | `pickApprover`, `pickApprovalDelivery`, `requestApproval`, approval-handler registry |

73| `src/command-gate.ts` | Router-side admin command gate — queries `user_roles` directly (no env var, no container-side check) |

74| `src/modules/approvals/onecli-approvals.ts` | OneCLI credentialed-action approval bridge |

75| `src/modules/permissions/user-dm.ts` | Cold-DM resolution + `user_dms` cache |

76| `src/group-init.ts` | Per-agent-group filesystem scaffold (CLAUDE.md, skills) — agent-runner source is a shared read-only mount, not copied per group |

77| `src/db/container-configs.ts` | CRUD for `container_configs` table (per-group container runtime config) |

78| `src/backfill-container-configs.ts` | Migrates legacy `container.json` files into the DB on startup |

79| `src/container-restart.ts` | Kill + on-wake respawn for agent group containers |

80| `src/db/` | DB layer — agent_groups, messaging_groups, sessions, container_configs, user_roles, user_dms, pending_*, migrations |

81| `src/channels/` | Channel adapter infra (registry, Chat SDK bridge); specific channel adapters are skill-installed from the `channels` branch |

82| `src/channels/channel-defaults.ts` | Wiring-creation helpers over adapter-declared channel defaults (`resolveWiringDefaults`, `resolveThreadPolicy`, engage validation) |

83| `src/providers/` | Host-side provider container-config (`claude` baked in; `opencode` etc. installed from the `providers` branch) |

84| `container/agent-runner/src/` | Agent-runner: poll loop, formatter, provider abstraction, MCP tools, destinations |

85| `container/skills/` | Container skills mounted into every agent session (`agent-browser`, `frontend-engineer`, `onecli-gateway`, `self-customize`, `welcome`; opt-in skills like `vercel-cli`, `slack-formatting` and `whatsapp-formatting` install with the `/add-*` skill that adds their capability) |

86| `groups/<folder>/` | Per-agent-group filesystem (CLAUDE.md, skills) — agent-runner source is a shared read-only mount, not copied per group |

87| `scripts/init-first-agent.ts` | Bootstrap the first DM-wired agent (used by `/init-first-agent` skill) |

88| `scripts/skill-apply.ts` | Deterministic SKILL.md applier — executes `nc:` directive fences; declare/emit core, journaled + idempotent |

89| `scripts/skill-directives.ts` + `scripts/skill-policy.ts` | `nc:` grammar parser + lint; UI-free driver policy derived from document structure (gate confirm, URL offer) |

90| `setup/lib/skill-driver.ts` + `setup/channels/run-channel-skill.ts` | Setup wizard's skill consumer: clack rendering of engine events + the generic channel-install flow |

91| `migrate-v2.sh` + `setup/migrate-v2/` | v1→v2 migration. Standalone script: `bash migrate-v2.sh`. Seeds DB, copies groups/sessions, installs channels, builds container, offers service switchover, then hands off to `/migrate-from-v1` skill for owner setup and CLAUDE.md cleanup. See [docs/migration-dev.md](docs/migration-dev.md). |

92| `nanoclaw.sh --uninstall` + `setup/uninstall/` | Uninstall this copy only (slug-scoped): service, containers + image, `data/`, `logs/`, `groups/`, this copy's OneCLI agents. Confirms per group; `--dry-run` previews, `--yes` skips prompts. Other copies and the shared OneCLI app are untouched. Bypasses bootstrap entirely; `uninstall.sh` is a pointer that execs it. |

94## Admin CLI (`ncl`)

96`ncl` queries and modifies the central DB — agent groups, messaging groups, wirings, users, roles, and more. On the host it connects via Unix socket (`src/cli/socket-server.ts`); inside containers it uses the session DB transport (`container/agent-runner/src/cli/ncl.ts`).

98```

99ncl <resource> <verb> [<id>] [--flags]

100ncl <resource> help

101ncl help

102```

103

104| Resource | Verbs | What it is |

105|----------|-------|------------|

106| groups | list, get, create, update, delete, restart, config get/update, config add-mcp-server/remove-mcp-server, config add-package/remove-package | Agent groups (workspace, personality, container config) |

107| messaging-groups | list, get, create, update, delete | A single chat/channel on one platform |

108| wirings | list, get, create, update, delete | Links a messaging group to an agent group (session mode, triggers) |

109| users | list, get, create, update | Platform identities (`<channel>:<handle>`) |

110| roles | list, grant, revoke | Owner / admin privileges (global or scoped to an agent group) |

111| members | list, add, remove | Unprivileged access gate for an agent group |

112| destinations | list, add, remove | Where an agent group can send messages |

113| sessions | list, get | Active sessions (read-only) |

114| tasks | list, get, create, update, cancel, pause, resume, delete, run, append-log | Scheduled tasks for an agent group |

115| user-dms | list | Cold-DM cache (read-only) |

116| dropped-messages | list | Messages from unregistered senders (read-only) |

117| approvals | list, get | Pending approval requests (read-only) |

118

119Key files: `src/cli/dispatch.ts` (dispatcher + approval handler), `src/cli/crud.ts` (generic CRUD registration), `src/cli/resources/` (per-resource definitions).

120

121## Channels and Providers (skill-installed)

122

123Trunk does not ship any specific channel adapter or non-default agent provider. The codebase is the registry/infra; the actual adapters and providers live on long-lived sibling branches and get copied in by skills:

124

125- **`channels` branch** — Discord, Slack, Telegram, WhatsApp, Teams, Linear, GitHub, iMessage, Webex, Resend, Matrix, Google Chat, WhatsApp Cloud, Signal, WeChat, DeltaChat, Emacs (+ helpers, tests, channel-specific setup steps). Installed via `/add-<channel>` skills.

126- **`providers` branch** — OpenCode (and any future non-default agent providers). Installed via `/add-opencode`.

127

128Each `/add-<name>` skill is idempotent: `git fetch origin <branch>` → copy module(s) into the standard paths → append a self-registration import to the relevant barrel → `pnpm install <pkg>@<pinned-version>` → build. Channel skills carry these steps as `nc:` directive fences: setup applies them via the engine (`scripts/skill-apply.ts`), an agent applies the prose — same install either way. See [docs/skill-directives.md](docs/skill-directives.md).

129

130**Channel defaults.** Each adapter declares its wiring-time defaults (`ChannelDefaults`: per DM/group context — engage mode/pattern, thread policy, unknown-sender policy — plus mention signaling). Exactly two levels: the adapter declaration, and the per-wiring override chosen at creation — no per-instance DB config table. Undeclared (stale) adapters resolve through a behavior-faithful fallback, so a trunk update alone changes nothing. See [docs/api-details.md](docs/api-details.md#channel-defaults) and `src/channels/channel-defaults.ts`.

131

132## Self-Modification

133

134One tier of agent self-modification today:

135

1361. **`install_packages` / `add_mcp_server`** — changes to the per-agent-group container config in the DB (apt/npm deps, wire an existing MCP server). Single admin approval per request; on approve, the handler in `src/modules/self-mod/apply.ts` rebuilds the image when needed (`install_packages` only), writes an `on_wake` message, kills the container, and respawns via `onExit` callback. The on-wake message is only picked up by the fresh container's first poll — dying containers can never steal it. `container/agent-runner/src/mcp-tools/self-mod.ts`.

137

138A second tier (direct source-level self-edits via a draft/activate flow) is planned but not yet implemented.

139

140## Container Config

141

142Per-agent-group container runtime config (provider, model, packages, MCP servers, mounts, etc.) lives in the `container_configs` table in the central DB. Materialized to `groups/<folder>/container.json` at spawn time so the container runner can read it. Managed via `ncl groups config get/update` and the self-mod MCP tools.

143

144**`cli_scope`** — controls what the agent can do with `ncl` from inside the container:

145

146| Value | Behavior |

147|-------|----------|

148| `disabled` | Agent never learns about ncl (instructions excluded from CLAUDE.md). Host dispatch rejects any `cli_request`. |

149| `group` (default) | Agent can access `groups`, `sessions`, `destinations`, `members`, `tasks` only, scoped to its own agent group. `--id` and group args are auto-filled. Cross-group access rejected. `cli_scope` changes blocked. |

150| `global` | Unrestricted. Set automatically for owner agent groups via `init-first-agent`. |

151

152Key files: `src/db/container-configs.ts`, `src/container-config.ts`, `src/cli/dispatch.ts` (scope enforcement), `src/claude-md-compose.ts` (instructions exclusion).

153

154## Container Restart

155

156`ncl groups restart --id <group-id> [--rebuild] [--message <text>]`. Kills running containers; if `--message` is provided, writes an `on_wake` message and respawns via `onExit` callback. Without `--message`, containers come back on the next user message. From inside a container, `--id` is auto-filled and only the calling session is restarted.

157

158The `on_wake` column on `messages_in` ensures wake messages are only picked up by a fresh container's first poll iteration. This prevents the race where a dying container (still in its SIGTERM grace period) could steal the message. `killContainer` accepts an optional `onExit` callback that fires after the process exits, guaranteeing the old container is gone before the new one spawns.

159

160Key files: `src/container-restart.ts`, `src/container-runner.ts` (`killContainer`), `container/agent-runner/src/db/messages-in.ts` (`getPendingMessages`).

161

162## Secrets / Credentials / OneCLI

163

164API keys, OAuth tokens, and auth credentials are managed by the OneCLI gateway. Secrets are injected into per-agent containers at request time — none are passed in env vars or through chat context. The container agent sees this via the `onecli-gateway` container skill (`container/skills/onecli-gateway/SKILL.md`), which teaches it how the proxy works, how to handle auth errors, and to never ask for raw credentials. Host-side wiring: `src/modules/approvals/onecli-approvals.ts`, `ensureAgent()` in `container-runner.ts`. Run `onecli --help`.

165

166### Secret modes

167

168Auto-created agents default to `all` secret mode — every vault secret whose host pattern matches is injected automatically, so the common case needs no per-agent setup. If an agent is in `selective` mode it gets no secrets until you assign them, which shows up as a `401` from an API whose credential *is* in the vault. The SDK can't change this; use the CLI (or the web UI at `http://127.0.0.1:10254`):

169

170```bash

171onecli agents list # check secretMode

172onecli agents set-secret-mode --id <agent-id> --mode all # inject all matching secrets

173onecli agents set-secrets --id <agent-id> --secret-ids ... # or stay selective, assign specific ones

174```

175

176No container restart needed — the gateway looks up secrets per request.

177

178### Requiring approval for credential use

179

180Approval-gating credentialed actions is a **two-sided** flow:

181

182- **Server-side** (OneCLI gateway): decides *when* to hold a request and emit a pending approval. As of `onecli@2.2.5`, the CLI does **not** expose this — `rules create --action` only accepts `block` or `rate_limit`, and `secrets create` has no approval flag. Approval policies must be configured via the OneCLI web UI at `http://127.0.0.1:10254`. If/when the CLI grows an `approve` action, this section needs updating.

183- **Host-side** (nanoclaw): receives pending approvals and routes them to a human. `src/modules/approvals/onecli-approvals.ts` registers a callback via `onecli.configureManualApproval(cb)` (long-polls `GET /api/approvals/pending`). The callback uses `pickApprover` + `pickApprovalDelivery` from `src/modules/approvals/primitive.ts` to DM an approver. Approvers are resolved from the `user_roles` table — preference order: scoped admins for the agent group → global admins → owners. There is no env var like `NANOCLAW_ADMIN_USER_IDS`; roles are persisted in the central DB only.

184

185If approvals are configured server-side but the host callback isn't running (or throws), every credentialed call hangs until the gateway times out. Conversely, if the gateway has no rule asking for approval, the host callback never fires regardless of how it's wired.

186

187## Skills

188

189Four types of skills. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full taxonomy.

190

191- **Channel/provider install skills** — copy the relevant module(s) in from the `channels` or `providers` branch, wire imports, install pinned deps (e.g. `/add-discord`, `/add-slack`, `/add-whatsapp`, `/add-opencode`).

192- **Utility skills** — ship code files alongside `SKILL.md` (e.g. a `scripts/` CLI or helper).

193- **Operational skills** — instruction-only workflows (`/setup`, `/debug`, `/customize`, `/init-first-agent`, `/manage-channels`, `/init-onecli`, `/update-nanoclaw`).

194- **Container skills** — loaded inside agent containers at runtime (`container/skills/`: `agent-browser`, `frontend-engineer`, `onecli-gateway`, `self-customize`, `welcome`; opt-in skills like `vercel-cli` and the channel formatters are copied in by the `/add-*` skill that adds their capability).

195

196| Skill | When to Use |

197|-------|-------------|

198| `/setup` | First-time install, auth, service config |

199| `/init-first-agent` | Bootstrap the first DM-wired agent (channel pick → identity → wire → welcome DM) |

200| `/manage-channels` | Wire channels to agent groups with isolation level decisions |

201| `/customize` | Adding channels, integrations, behavior changes |

202| `/debug` | Container issues, logs, troubleshooting |

203| `/update-nanoclaw` | Bring upstream updates into a customized install |

204| `/init-onecli` | Install OneCLI Agent Vault and migrate `.env` credentials |

205| `/migrate-memory` | Carry a group's agent memory across a provider switch (operator-run, both directions) |

206

207## Contributing

208

209Before creating a PR, adding a skill, or preparing any contribution, you MUST read [CONTRIBUTING.md](CONTRIBUTING.md). It covers accepted change types, the four skill types and their guidelines, `SKILL.md` format rules, and the pre-submission checklist.

210

211## PR Hygiene

212

213Before creating a PR, run these checks:

214

215```bash

216git diff upstream/main --stat HEAD

217git log upstream/main..HEAD --oneline

218```

219

220Show the output and wait for approval. Installation-specific files (group files, .claude/settings.json, local configs) should not be included.

221

222## Development

223

224Run commands directly — don't tell the user to run them.

225

226```bash

227# Host (Node + pnpm)

228pnpm run dev # Host via tsx (no watch)

229pnpm run build # Compile host TypeScript (src/)

230./container/build.sh # Rebuild agent container image (nanoclaw-agent:latest)

231pnpm test # Host tests (vitest)

232

233# Agent-runner (Bun — separate package tree under container/agent-runner/)

234cd container/agent-runner && bun install # After editing agent-runner deps

235cd container/agent-runner && bun test # Container tests (bun:test)

236```

237

238Container typecheck is a separate tsconfig — if you edit `container/agent-runner/src/`, run `pnpm exec tsc -p container/agent-runner/tsconfig.json --noEmit` from root (or `bun run typecheck` from `container/agent-runner/`).

239

240Service management:

241```bash

242# macOS (launchd)

243launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist

244launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist

245launchctl kickstart -k gui/$(id -u)/com.nanoclaw # restart

246

247# Linux (systemd)

248systemctl --user start|stop|restart nanoclaw

249```

250

251## Troubleshooting

252

253Check these first when something goes wrong:

254

255| What | Where |

256|------|-------|

257| Host logs | `logs/nanoclaw.error.log` first (delivery failures, crash-loop backoff, warnings), then `logs/nanoclaw.log` for the full routing chain |

258| Setup logs | `logs/setup.log` (overall), `logs/setup-steps/*.log` (per-step: bootstrap, environment, container, onecli, mounts, service, etc.) |

259| Session DBs | `data/v2-sessions/<agent-group>/<session>/` — `inbound.db` (`messages_in`: did the message reach the container?), `outbound.db` (`messages_out`: did the agent produce a response?) |

260

261Note: container logs are lost after the container exits (`--rm` flag). If the agent silently failed inside the container, there's no persistent log to inspect.

262

263## Timestamps

264

265Two rules, no exceptions:

266

267- **Storage**: every timestamp written from JS is `new Date().toISOString()` (ISO-8601 UTC with `Z`). Never `datetime('now')` — its naive `YYYY-MM-DD HH:MM:SS` shape is misparsed as local time by `new Date()` and breaks string comparisons against ISO values. In pure-SQL contexts (skill snippets) use `strftime('%Y-%m-%dT%H:%M:%fZ','now')`. SQL-side *comparisons* wrap both sides in `datetime()`.

268- **Display**: anything shown to an agent or a user renders in the install timezone — `formatLocalTime` (prose) or `formatLocalStamp` (log lines) from `src/timezone.ts` / `container/agent-runner/src/timezone.ts`. `--json` output, DB values, and operator logs stay ISO.

269

270An agent group can override the install timezone (`ncl groups config update --timezone <IANA>`, `""` clears; approval-gated for agent callers). The override grounds that group's scheduling (cron interpretation, `--process-after`, run-log stamps — effective immediately) and the container's `TZ` env (effective on respawn). Host-side operator display (`ncl` human output) stays in the install timezone. Resolution: `resolveGroupTimezone` in `src/container-config.ts` — group override → install global.

271

272## Supply Chain Security (pnpm)

273

274This project uses pnpm with `minimumReleaseAge: 4320` (3 days) in `pnpm-workspace.yaml`. New package versions must exist on the npm registry for 3 days before pnpm will resolve them.

275

276**Rules — do not bypass without explicit human approval:**

277- **`minimumReleaseAgeExclude`**: Never add entries without human sign-off. If a package must bypass the release age gate, the human must approve and the entry must pin the exact version being excluded (e.g. `package@1.2.3`), never a range.

278- **`onlyBuiltDependencies`**: Never add packages to this list without human approval — build scripts execute arbitrary code during install.

279- **`pnpm install --frozen-lockfile`** should be used in CI, automation, and container builds. Never run bare `pnpm install` in those contexts.

280

281## Docs Index

282

283| Doc | Purpose |

284|-----|---------|

285| [docs/architecture.md](docs/architecture.md) | Full architecture writeup |

286| [docs/api-details.md](docs/api-details.md) | Host API + DB schema details |

287| [docs/db.md](docs/db.md) | DB architecture overview: three-DB model, cross-mount rules, readers/writers map |

288| [docs/db-central.md](docs/db-central.md) | Central DB (`data/v2.db`) — every table + migration system |

289| [docs/db-session.md](docs/db-session.md) | Per-session `inbound.db` + `outbound.db` schemas + seq parity |

290| [docs/agent-runner-details.md](docs/agent-runner-details.md) | Agent-runner internals + MCP tool interface |

291| [docs/isolation-model.md](docs/isolation-model.md) | Three-level channel isolation model |

292| [docs/setup-wiring.md](docs/setup-wiring.md) | What's wired, what's open in the setup flow |

293| [docs/architecture-diagram.md](docs/architecture-diagram.md) | Diagram version of the architecture |

294| [docs/build-and-runtime.md](docs/build-and-runtime.md) | Runtime split (Node host + Bun container), lockfiles, image build surface, CI, key invariants |

295| [docs/v1-to-v2-changes.md](docs/v1-to-v2-changes.md) | v1→v2 architecture diff — vocabulary for where v1 things moved |

296| [docs/migration-dev.md](docs/migration-dev.md) | Migration development guide — testing, debugging, dev loop |

297| [docs/provider-migration.md](docs/provider-migration.md) | Switching a live agent group between providers (e.g. Claude → Codex) — what carries over, rollback |

298| [docs/customizing.md](docs/customizing.md) | Short intro to customizing via skills |

299| [docs/skills-model.md](docs/skills-model.md) | The skills model in full: recipes, tests, upgrades, migrations |

300| [docs/skill-guidelines.md](docs/skill-guidelines.md) | Authoritative checklist for writing a skill |

301| [docs/skill-directives.md](docs/skill-directives.md) | `nc:` directive reference: fence grammar, the eight kinds, effects, guards, lint |

302| [docs/skill-engine-seam.md](docs/skill-engine-seam.md) | Skill-engine consumer contract (wizard / pipeline / agent-relay) + boundary-rule rationale |

303| [docs/templates.md](docs/templates.md) | Agent templates: what they are, stamping via `ncl groups create --template` + the setup wizard, the OneCLI/MCP-credential model, supported providers, and how to contribute one |

304| [docs/hardened-image.md](docs/hardened-image.md) | Opt-in: pull the agent image from a registry instead of building it |

305

306## Container Build Cache

307

308The container buildkit caches the build context aggressively. `--no-cache` alone does NOT invalidate COPY steps — the builder's volume retains stale files. To force a truly clean rebuild, prune the builder then re-run `./container/build.sh`.

309

310## Container Runtime (Bun)

311

312The agent container runs on **Bun**; the host runs on **Node** (pnpm). They communicate only via session DBs — no shared modules. Details and rationale: [docs/build-and-runtime.md](docs/build-and-runtime.md).

313

314**Gotchas — trigger + action:**

315

316- **Adding or bumping a runtime dep in `container/agent-runner/`** → edit `package.json`, then `cd container/agent-runner && bun install` and commit the updated `bun.lock`. Do not run `pnpm install` there — agent-runner is not a pnpm workspace.

317- **Bumping `@anthropic-ai/claude-agent-sdk`, `@modelcontextprotocol/sdk`, or any agent-runner runtime dep** → no `minimumReleaseAge` policy applies to this tree. Check the release date on npm, pin deliberately, never `bun update` blindly.

318- **Writing a new named-param SQL insert/update in the container** → use `$name` in both SQL and JS keys: `.run({ $id: msg.id })`. `bun:sqlite` does not auto-strip the prefix the way `better-sqlite3` does on the host. Positional `?` params work normally.

319- **Adding a test in `container/agent-runner/src/`** → import from `bun:test`, not `vitest`. Vitest runs on Node and can't load `bun:sqlite`. `vitest.config.ts` excludes this tree.

320- **Adding a Node CLI the agent invokes at runtime** (like `agent-browser`, `claude-code`, `vercel`) → put it in the Dockerfile's pnpm global-install block, pinned to an exact version via a new `ARG`. Don't use `bun install -g` — that bypasses the pnpm supply-chain policy.

321- **Changing the Dockerfile entrypoint or the dynamic-spawn command** (`src/container-runner.ts` line ~503) → keep `exec bun ...` so signals forward cleanly. The image has no `/app/dist`; don't reintroduce a tsc build step.

322- **Changing session-DB pragmas** (`container/agent-runner/src/db/connection.ts`) → `journal_mode=DELETE` is load-bearing for cross-mount visibility. Read the comment block at the top of the file first.

323

324## CJK font support

325

326Agent containers ship without CJK fonts by default (~200MB saved). If you notice signals the user works with Chinese/Japanese/Korean content — conversing in CJK, CJK timezone (e.g., `Asia/Tokyo`, `Asia/Shanghai`, `Asia/Seoul`, `Asia/Taipei`, `Asia/Hong_Kong`), system locale hint, or mentions of needing to render CJK in screenshots/PDFs/scraped pages — offer to enable it:

327

328```bash

329# Ensure .env has INSTALL_CJK_FONTS=true (overwrite or append)

330grep -q '^INSTALL_CJK_FONTS=' .env && sed -i.bak 's/^INSTALL_CJK_FONTS=.*/INSTALL_CJK_FONTS=true/' .env && rm -f .env.bak || echo 'INSTALL_CJK_FONTS=true' >> .env

331

332# Rebuild and restart so new sessions pick up the new image

333./container/build.sh

334launchctl kickstart -k gui/$(id -u)/com.nanoclaw # macOS

335# systemctl --user restart nanoclaw # Linux

336```

337

338`container/build.sh` reads `INSTALL_CJK_FONTS` from `.env` and passes it through as a Docker build-arg. Without CJK fonts, Chromium-rendered screenshots and PDFs containing CJK text show tofu (empty rectangles) instead of characters.

339

@@ −1 +1 @@

1−You are a NanoClaw agent. Your name, destinations, and message-sending rules are provided in the runtime system prompt at the top of each turn.

1+# ⚠️ STOP — READ THIS FIRST IF YOU ARE CLAUDE ⚠️

3−## Communication

3+**If you are reading this because you just ran `git pull`, `git merge`, `git fetch && git merge`, or any equivalent to bring in upstream changes — and you see merge conflicts or a large diff involving this file — HALT IMMEDIATELY.**

5−Be concise — every message costs the reader's attention. Prefer outcomes over play-by-play; when the work is done, the final message should be about the result, not a transcript of what you did.

5+This is NanoClaw v2, a ground-up rewrite with breaking changes throughout. It cannot be merged into an existing v1 install. Attempting to resolve the conflicts by hand, run builds, or "fix" anything will corrupt the user's install and burn tokens for no result.

7−## Workspace

7+**Do this instead:**

8+1. Abort the merge: `git merge --abort` (or `git reset --hard ORIG_HEAD` if the merge already completed).

9+2. Tell the user, verbatim: *"This is the v2 rewrite — it can't be merged into your existing install. Exit Claude Code (or open a separate terminal) and run `bash migrate-v2.sh` from the shell."*

10+3. Wait for the user to confirm before doing anything else. Do not run the migration script yourself — it requires an interactive terminal and cannot be run from within Claude Code.

811

9−Files you create are saved in `/workspace/agent/`. Use this for notes, research, or anything that should persist across turns in this group.

12+If you are a fresh install (you ran `git clone`, not `git pull`) and there are no conflicts, ignore this banner and continue below.

1013

11−## Memory

14+---

1215

13−Your persistent memory lives under `/workspace/agent/memory/`. The session-start memory context contains the live top-level index and system definition. Follow that definition when deciding what to store and keep the index accurate so you can retrieve details later.

16+# NanoClaw

1417

15−Standing role, persona, and behavioral instructions belong in `/workspace/agent/instructions.prepend.md`; durable facts belong in memory. Changes to standing instructions take effect after the group container restarts, so say that when confirming an edit.

18+Personal AI assistant. See [README.md](README.md) for philosophy and setup. Architecture lives in `docs/`.

1619

17−## Conversation history

20+## Quick Context

1821

19−The `conversations/` folder in your workspace holds searchable transcripts of past sessions with this group. Use it to recall prior context when a request references something that happened before. For structured long-lived data, prefer dedicated files (`customers.md`, `preferences.md`, etc.); split any file over ~500 lines into a folder with an index.

22+The host is a single Node process that orchestrates per-session agent containers. Platform messages land via channel adapters, route through an entity model (users → messaging groups → agent groups → sessions), get written into the session's inbound DB, and wake a container. The agent-runner inside the container polls the DB, calls the agent, and writes back to the outbound DB. The host polls the outbound DB and delivers through the same adapter.

23+

24+**Everything is a message.** There is no IPC, no file watcher, no stdin piping between host and container. The two session DBs are the sole IO surface.

25+

26+## Entity Model

27+

28+```

29+users (id "<channel>:<handle>", kind, display_name)

30+user_roles (user_id, role, agent_group_id) — owner | admin (global or scoped)

31+agent_group_members (user_id, agent_group_id) — unprivileged access gate

32+user_dms (user_id, channel_type, messaging_group_id) — cold-DM cache

33+

34+agent_groups (workspace, memory, CLAUDE.md, personality, container config)

35+ ↕ many-to-many via messaging_group_agents (session_mode, engage_mode/engage_pattern, sender_scope, priority)

36+messaging_groups (one chat/channel on one platform; instance = adapter-instance name, defaults to channel_type; unknown_sender_policy)

37+

38+sessions (agent_group_id + messaging_group_id + thread_id → per-session container)

39+```

40+

41+Privilege is user-level (owner/admin), not agent-group-level. See [docs/isolation-model.md](docs/isolation-model.md) for the three isolation levels (`agent-shared`, `shared`, separate agents).

42+

43+## Two-DB Session Split

44+

45+Each session has **two** SQLite files under `data/v2-sessions/<session_id>/`:

46+

47+- `inbound.db` — host writes, container reads. `messages_in`, delivered, destinations, session_routing.

48+- `outbound.db` — container writes, host reads. `messages_out`, processing_ack, session_state, container_state.

49+

50+Exactly one writer per file — no cross-mount lock contention. Heartbeat is a file touch at `/workspace/.heartbeat`, not a DB update. Host uses even `seq` numbers, container uses odd.

51+

52+## Central DB

53+

54+`data/v2.db` holds everything that isn't per-session: users, user_roles, agent_groups, messaging_groups, wiring, pending_approvals, user_dms, chat_sdk_* (for the Chat SDK bridge), schema_version. Migrations live at `src/db/migrations/`.

55+

56+For ad-hoc queries from skills or scripts, use the in-tree wrapper rather than the `sqlite3` CLI: `pnpm exec tsx scripts/q.ts <db> "<sql>"`. The host setup intentionally avoids depending on the `sqlite3` binary (`setup/verify.ts:5`); the wrapper goes through the `better-sqlite3` dep that setup already installs and verifies. Default-output format matches `sqlite3 -list` (pipe-separated, no header) so existing skill text reads identically.

57+

58+## Key Files

59+

60+| File | Purpose |

61+|------|---------|

62+| `src/index.ts` | Entry point: init DB, migrations, channel adapters, delivery polls, sweep, shutdown |

63+| `src/router.ts` | Inbound routing: messaging group → agent group → session → `inbound.db` → wake |

64+| `src/delivery.ts` | Polls `outbound.db`, delivers via adapter, handles system actions (schedule, approvals, etc.) |

65+| `src/delivery-guard.ts` | `DeliveryGuardSpec` + `runGuarded` — the guard-consult pipeline for privileged delivery actions (registry stays in `delivery.ts`) |

66+| `src/host-sweep.ts` | 60s sweep: `processing_ack` sync, stale detection, due-message wake, recurrence |

67+| `src/session-manager.ts` | Resolves sessions; opens `inbound.db` / `outbound.db`; manages heartbeat path |

68+| `src/container-runner.ts` | Spawns per-agent-group Docker containers with session DB + outbox mounts, OneCLI `ensureAgent` |

69+| `src/container-runtime.ts` | Docker CLI wrapper (runtime binary, host-gateway args, mount args), orphan cleanup |

70+| `src/guard/` | Privileged-action decision seam: `guard(action, input)` → allow \| hold \| deny. Module-edge `guard.ts` adapters (cli, agent-to-agent, self-mod, permissions) define each action's decision; ncl commands + delivery actions demand a guard at registration; approved replays carry the approval row as a grant and re-run the checks. Conformance test: `src/guard/conformance.test.ts` |

71+| `src/modules/permissions/access.ts` | `canAccessAgentGroup` — owner / global admin / scoped admin / member resolution against `user_roles` + `agent_group_members` |

72+| `src/modules/approvals/primitive.ts` | `pickApprover`, `pickApprovalDelivery`, `requestApproval`, approval-handler registry |

73+| `src/command-gate.ts` | Router-side admin command gate — queries `user_roles` directly (no env var, no container-side check) |

74+| `src/modules/approvals/onecli-approvals.ts` | OneCLI credentialed-action approval bridge |

75+| `src/modules/permissions/user-dm.ts` | Cold-DM resolution + `user_dms` cache |

76+| `src/group-init.ts` | Per-agent-group filesystem scaffold (CLAUDE.md, skills) — agent-runner source is a shared read-only mount, not copied per group |

77+| `src/db/container-configs.ts` | CRUD for `container_configs` table (per-group container runtime config) |

78+| `src/backfill-container-configs.ts` | Migrates legacy `container.json` files into the DB on startup |

79+| `src/container-restart.ts` | Kill + on-wake respawn for agent group containers |

80+| `src/db/` | DB layer — agent_groups, messaging_groups, sessions, container_configs, user_roles, user_dms, pending_*, migrations |

81+| `src/channels/` | Channel adapter infra (registry, Chat SDK bridge); specific channel adapters are skill-installed from the `channels` branch |

82+| `src/channels/channel-defaults.ts` | Wiring-creation helpers over adapter-declared channel defaults (`resolveWiringDefaults`, `resolveThreadPolicy`, engage validation) |

83+| `src/providers/` | Host-side provider container-config (`claude` baked in; `opencode` etc. installed from the `providers` branch) |

84+| `container/agent-runner/src/` | Agent-runner: poll loop, formatter, provider abstraction, MCP tools, destinations |

85+| `container/skills/` | Container skills mounted into every agent session (`agent-browser`, `frontend-engineer`, `onecli-gateway`, `self-customize`, `welcome`; opt-in skills like `vercel-cli`, `slack-formatting` and `whatsapp-formatting` install with the `/add-*` skill that adds their capability) |

86+| `groups/<folder>/` | Per-agent-group filesystem (CLAUDE.md, skills) — agent-runner source is a shared read-only mount, not copied per group |

87+| `scripts/init-first-agent.ts` | Bootstrap the first DM-wired agent (used by `/init-first-agent` skill) |

88+| `scripts/skill-apply.ts` | Deterministic SKILL.md applier — executes `nc:` directive fences; declare/emit core, journaled + idempotent |

89+| `scripts/skill-directives.ts` + `scripts/skill-policy.ts` | `nc:` grammar parser + lint; UI-free driver policy derived from document structure (gate confirm, URL offer) |

90+| `setup/lib/skill-driver.ts` + `setup/channels/run-channel-skill.ts` | Setup wizard's skill consumer: clack rendering of engine events + the generic channel-install flow |

91+| `migrate-v2.sh` + `setup/migrate-v2/` | v1→v2 migration. Standalone script: `bash migrate-v2.sh`. Seeds DB, copies groups/sessions, installs channels, builds container, offers service switchover, then hands off to `/migrate-from-v1` skill for owner setup and CLAUDE.md cleanup. See [docs/migration-dev.md](docs/migration-dev.md). |

92+| `nanoclaw.sh --uninstall` + `setup/uninstall/` | Uninstall this copy only (slug-scoped): service, containers + image, `data/`, `logs/`, `groups/`, this copy's OneCLI agents. Confirms per group; `--dry-run` previews, `--yes` skips prompts. Other copies and the shared OneCLI app are untouched. Bypasses bootstrap entirely; `uninstall.sh` is a pointer that execs it. |

93+

94+## Admin CLI (`ncl`)

95+

96+`ncl` queries and modifies the central DB — agent groups, messaging groups, wirings, users, roles, and more. On the host it connects via Unix socket (`src/cli/socket-server.ts`); inside containers it uses the session DB transport (`container/agent-runner/src/cli/ncl.ts`).

97+

98+```

99+ncl <resource> <verb> [<id>] [--flags]

100+ncl <resource> help

101+ncl help

102+```

103+

104+| Resource | Verbs | What it is |

105+|----------|-------|------------|

106+| groups | list, get, create, update, delete, restart, config get/update, config add-mcp-server/remove-mcp-server, config add-package/remove-package | Agent groups (workspace, personality, container config) |

107+| messaging-groups | list, get, create, update, delete | A single chat/channel on one platform |

108+| wirings | list, get, create, update, delete | Links a messaging group to an agent group (session mode, triggers) |

109+| users | list, get, create, update | Platform identities (`<channel>:<handle>`) |

110+| roles | list, grant, revoke | Owner / admin privileges (global or scoped to an agent group) |

111+| members | list, add, remove | Unprivileged access gate for an agent group |

112+| destinations | list, add, remove | Where an agent group can send messages |

113+| sessions | list, get | Active sessions (read-only) |

114+| tasks | list, get, create, update, cancel, pause, resume, delete, run, append-log | Scheduled tasks for an agent group |

115+| user-dms | list | Cold-DM cache (read-only) |

116+| dropped-messages | list | Messages from unregistered senders (read-only) |

117+| approvals | list, get | Pending approval requests (read-only) |

118+

119+Key files: `src/cli/dispatch.ts` (dispatcher + approval handler), `src/cli/crud.ts` (generic CRUD registration), `src/cli/resources/` (per-resource definitions).

120+

121+## Channels and Providers (skill-installed)

122+

123+Trunk does not ship any specific channel adapter or non-default agent provider. The codebase is the registry/infra; the actual adapters and providers live on long-lived sibling branches and get copied in by skills:

124+

125+- **`channels` branch** — Discord, Slack, Telegram, WhatsApp, Teams, Linear, GitHub, iMessage, Webex, Resend, Matrix, Google Chat, WhatsApp Cloud, Signal, WeChat, DeltaChat, Emacs (+ helpers, tests, channel-specific setup steps). Installed via `/add-<channel>` skills.

126+- **`providers` branch** — OpenCode (and any future non-default agent providers). Installed via `/add-opencode`.

127+

128+Each `/add-<name>` skill is idempotent: `git fetch origin <branch>` → copy module(s) into the standard paths → append a self-registration import to the relevant barrel → `pnpm install <pkg>@<pinned-version>` → build. Channel skills carry these steps as `nc:` directive fences: setup applies them via the engine (`scripts/skill-apply.ts`), an agent applies the prose — same install either way. See [docs/skill-directives.md](docs/skill-directives.md).

129+

130+**Channel defaults.** Each adapter declares its wiring-time defaults (`ChannelDefaults`: per DM/group context — engage mode/pattern, thread policy, unknown-sender policy — plus mention signaling). Exactly two levels: the adapter declaration, and the per-wiring override chosen at creation — no per-instance DB config table. Undeclared (stale) adapters resolve through a behavior-faithful fallback, so a trunk update alone changes nothing. See [docs/api-details.md](docs/api-details.md#channel-defaults) and `src/channels/channel-defaults.ts`.

131+

132+## Self-Modification

133+

134+One tier of agent self-modification today:

135+

136+1. **`install_packages` / `add_mcp_server`** — changes to the per-agent-group container config in the DB (apt/npm deps, wire an existing MCP server). Single admin approval per request; on approve, the handler in `src/modules/self-mod/apply.ts` rebuilds the image when needed (`install_packages` only), writes an `on_wake` message, kills the container, and respawns via `onExit` callback. The on-wake message is only picked up by the fresh container's first poll — dying containers can never steal it. `container/agent-runner/src/mcp-tools/self-mod.ts`.

137+

138+A second tier (direct source-level self-edits via a draft/activate flow) is planned but not yet implemented.

139+

140+## Container Config

141+

142+Per-agent-group container runtime config (provider, model, packages, MCP servers, mounts, etc.) lives in the `container_configs` table in the central DB. Materialized to `groups/<folder>/container.json` at spawn time so the container runner can read it. Managed via `ncl groups config get/update` and the self-mod MCP tools.

143+

144+**`cli_scope`** — controls what the agent can do with `ncl` from inside the container:

145+

146+| Value | Behavior |

147+|-------|----------|

148+| `disabled` | Agent never learns about ncl (instructions excluded from CLAUDE.md). Host dispatch rejects any `cli_request`. |

149+| `group` (default) | Agent can access `groups`, `sessions`, `destinations`, `members`, `tasks` only, scoped to its own agent group. `--id` and group args are auto-filled. Cross-group access rejected. `cli_scope` changes blocked. |

150+| `global` | Unrestricted. Set automatically for owner agent groups via `init-first-agent`. |

151+

152+Key files: `src/db/container-configs.ts`, `src/container-config.ts`, `src/cli/dispatch.ts` (scope enforcement), `src/claude-md-compose.ts` (instructions exclusion).

153+

154+## Container Restart

155+

156+`ncl groups restart --id <group-id> [--rebuild] [--message <text>]`. Kills running containers; if `--message` is provided, writes an `on_wake` message and respawns via `onExit` callback. Without `--message`, containers come back on the next user message. From inside a container, `--id` is auto-filled and only the calling session is restarted.

157+

158+The `on_wake` column on `messages_in` ensures wake messages are only picked up by a fresh container's first poll iteration. This prevents the race where a dying container (still in its SIGTERM grace period) could steal the message. `killContainer` accepts an optional `onExit` callback that fires after the process exits, guaranteeing the old container is gone before the new one spawns.

159+

160+Key files: `src/container-restart.ts`, `src/container-runner.ts` (`killContainer`), `container/agent-runner/src/db/messages-in.ts` (`getPendingMessages`).

161+

162+## Secrets / Credentials / OneCLI

163+

164+API keys, OAuth tokens, and auth credentials are managed by the OneCLI gateway. Secrets are injected into per-agent containers at request time — none are passed in env vars or through chat context. The container agent sees this via the `onecli-gateway` container skill (`container/skills/onecli-gateway/SKILL.md`), which teaches it how the proxy works, how to handle auth errors, and to never ask for raw credentials. Host-side wiring: `src/modules/approvals/onecli-approvals.ts`, `ensureAgent()` in `container-runner.ts`. Run `onecli --help`.

165+

166+### Secret modes

167+

168+Auto-created agents default to `all` secret mode — every vault secret whose host pattern matches is injected automatically, so the common case needs no per-agent setup. If an agent is in `selective` mode it gets no secrets until you assign them, which shows up as a `401` from an API whose credential *is* in the vault. The SDK can't change this; use the CLI (or the web UI at `http://127.0.0.1:10254`):

169+

170+```bash

171+onecli agents list # check secretMode

172+onecli agents set-secret-mode --id <agent-id> --mode all # inject all matching secrets

173+onecli agents set-secrets --id <agent-id> --secret-ids ... # or stay selective, assign specific ones

174+```

175+

176+No container restart needed — the gateway looks up secrets per request.

177+

178+### Requiring approval for credential use

179+

180+Approval-gating credentialed actions is a **two-sided** flow:

181+

182+- **Server-side** (OneCLI gateway): decides *when* to hold a request and emit a pending approval. As of `onecli@2.2.5`, the CLI does **not** expose this — `rules create --action` only accepts `block` or `rate_limit`, and `secrets create` has no approval flag. Approval policies must be configured via the OneCLI web UI at `http://127.0.0.1:10254`. If/when the CLI grows an `approve` action, this section needs updating.

183+- **Host-side** (nanoclaw): receives pending approvals and routes them to a human. `src/modules/approvals/onecli-approvals.ts` registers a callback via `onecli.configureManualApproval(cb)` (long-polls `GET /api/approvals/pending`). The callback uses `pickApprover` + `pickApprovalDelivery` from `src/modules/approvals/primitive.ts` to DM an approver. Approvers are resolved from the `user_roles` table — preference order: scoped admins for the agent group → global admins → owners. There is no env var like `NANOCLAW_ADMIN_USER_IDS`; roles are persisted in the central DB only.

184+

185+If approvals are configured server-side but the host callback isn't running (or throws), every credentialed call hangs until the gateway times out. Conversely, if the gateway has no rule asking for approval, the host callback never fires regardless of how it's wired.

186+

187+## Skills

188+

189+Four types of skills. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full taxonomy.

190+

191+- **Channel/provider install skills** — copy the relevant module(s) in from the `channels` or `providers` branch, wire imports, install pinned deps (e.g. `/add-discord`, `/add-slack`, `/add-whatsapp`, `/add-opencode`).

192+- **Utility skills** — ship code files alongside `SKILL.md` (e.g. a `scripts/` CLI or helper).

193+- **Operational skills** — instruction-only workflows (`/setup`, `/debug`, `/customize`, `/init-first-agent`, `/manage-channels`, `/init-onecli`, `/update-nanoclaw`).

194+- **Container skills** — loaded inside agent containers at runtime (`container/skills/`: `agent-browser`, `frontend-engineer`, `onecli-gateway`, `self-customize`, `welcome`; opt-in skills like `vercel-cli` and the channel formatters are copied in by the `/add-*` skill that adds their capability).

195+

196+| Skill | When to Use |

197+|-------|-------------|

198+| `/setup` | First-time install, auth, service config |

199+| `/init-first-agent` | Bootstrap the first DM-wired agent (channel pick → identity → wire → welcome DM) |

200+| `/manage-channels` | Wire channels to agent groups with isolation level decisions |

201+| `/customize` | Adding channels, integrations, behavior changes |

202+| `/debug` | Container issues, logs, troubleshooting |

203+| `/update-nanoclaw` | Bring upstream updates into a customized install |

204+| `/init-onecli` | Install OneCLI Agent Vault and migrate `.env` credentials |

205+| `/migrate-memory` | Carry a group's agent memory across a provider switch (operator-run, both directions) |

206+

207+## Contributing

208+

209+Before creating a PR, adding a skill, or preparing any contribution, you MUST read [CONTRIBUTING.md](CONTRIBUTING.md). It covers accepted change types, the four skill types and their guidelines, `SKILL.md` format rules, and the pre-submission checklist.

210+

211+## PR Hygiene

212+

213+Before creating a PR, run these checks:

214+

215+```bash

216+git diff upstream/main --stat HEAD

217+git log upstream/main..HEAD --oneline

218+```

219+

220+Show the output and wait for approval. Installation-specific files (group files, .claude/settings.json, local configs) should not be included.

221+

222+## Development

223+

224+Run commands directly — don't tell the user to run them.

225+

226+```bash

227+# Host (Node + pnpm)

228+pnpm run dev # Host via tsx (no watch)

229+pnpm run build # Compile host TypeScript (src/)

230+./container/build.sh # Rebuild agent container image (nanoclaw-agent:latest)

231+pnpm test # Host tests (vitest)

232+

233+# Agent-runner (Bun — separate package tree under container/agent-runner/)

234+cd container/agent-runner && bun install # After editing agent-runner deps

235+cd container/agent-runner && bun test # Container tests (bun:test)

236+```

237+

238+Container typecheck is a separate tsconfig — if you edit `container/agent-runner/src/`, run `pnpm exec tsc -p container/agent-runner/tsconfig.json --noEmit` from root (or `bun run typecheck` from `container/agent-runner/`).

239+

240+Service management:

241+```bash

242+# macOS (launchd)

243+launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist

244+launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist

245+launchctl kickstart -k gui/$(id -u)/com.nanoclaw # restart

246+

247+# Linux (systemd)

248+systemctl --user start|stop|restart nanoclaw

249+```

250+

251+## Troubleshooting

252+

253+Check these first when something goes wrong:

254+

255+| What | Where |

256+|------|-------|

257+| Host logs | `logs/nanoclaw.error.log` first (delivery failures, crash-loop backoff, warnings), then `logs/nanoclaw.log` for the full routing chain |

258+| Setup logs | `logs/setup.log` (overall), `logs/setup-steps/*.log` (per-step: bootstrap, environment, container, onecli, mounts, service, etc.) |

259+| Session DBs | `data/v2-sessions/<agent-group>/<session>/` — `inbound.db` (`messages_in`: did the message reach the container?), `outbound.db` (`messages_out`: did the agent produce a response?) |

260+

261+Note: container logs are lost after the container exits (`--rm` flag). If the agent silently failed inside the container, there's no persistent log to inspect.

262+

263+## Timestamps

264+

265+Two rules, no exceptions:

266+

267+- **Storage**: every timestamp written from JS is `new Date().toISOString()` (ISO-8601 UTC with `Z`). Never `datetime('now')` — its naive `YYYY-MM-DD HH:MM:SS` shape is misparsed as local time by `new Date()` and breaks string comparisons against ISO values. In pure-SQL contexts (skill snippets) use `strftime('%Y-%m-%dT%H:%M:%fZ','now')`. SQL-side *comparisons* wrap both sides in `datetime()`.

268+- **Display**: anything shown to an agent or a user renders in the install timezone — `formatLocalTime` (prose) or `formatLocalStamp` (log lines) from `src/timezone.ts` / `container/agent-runner/src/timezone.ts`. `--json` output, DB values, and operator logs stay ISO.

269+

270+An agent group can override the install timezone (`ncl groups config update --timezone <IANA>`, `""` clears; approval-gated for agent callers). The override grounds that group's scheduling (cron interpretation, `--process-after`, run-log stamps — effective immediately) and the container's `TZ` env (effective on respawn). Host-side operator display (`ncl` human output) stays in the install timezone. Resolution: `resolveGroupTimezone` in `src/container-config.ts` — group override → install global.

271+

272+## Supply Chain Security (pnpm)

273+

274+This project uses pnpm with `minimumReleaseAge: 4320` (3 days) in `pnpm-workspace.yaml`. New package versions must exist on the npm registry for 3 days before pnpm will resolve them.

275+

276+**Rules — do not bypass without explicit human approval:**

277+- **`minimumReleaseAgeExclude`**: Never add entries without human sign-off. If a package must bypass the release age gate, the human must approve and the entry must pin the exact version being excluded (e.g. `package@1.2.3`), never a range.

278+- **`onlyBuiltDependencies`**: Never add packages to this list without human approval — build scripts execute arbitrary code during install.

279+- **`pnpm install --frozen-lockfile`** should be used in CI, automation, and container builds. Never run bare `pnpm install` in those contexts.

280+

281+## Docs Index

282+

283+| Doc | Purpose |

284+|-----|---------|

285+| [docs/architecture.md](docs/architecture.md) | Full architecture writeup |

286+| [docs/api-details.md](docs/api-details.md) | Host API + DB schema details |

287+| [docs/db.md](docs/db.md) | DB architecture overview: three-DB model, cross-mount rules, readers/writers map |

288+| [docs/db-central.md](docs/db-central.md) | Central DB (`data/v2.db`) — every table + migration system |

289+| [docs/db-session.md](docs/db-session.md) | Per-session `inbound.db` + `outbound.db` schemas + seq parity |

290+| [docs/agent-runner-details.md](docs/agent-runner-details.md) | Agent-runner internals + MCP tool interface |

291+| [docs/isolation-model.md](docs/isolation-model.md) | Three-level channel isolation model |

292+| [docs/setup-wiring.md](docs/setup-wiring.md) | What's wired, what's open in the setup flow |

293+| [docs/architecture-diagram.md](docs/architecture-diagram.md) | Diagram version of the architecture |

294+| [docs/build-and-runtime.md](docs/build-and-runtime.md) | Runtime split (Node host + Bun container), lockfiles, image build surface, CI, key invariants |

295+| [docs/v1-to-v2-changes.md](docs/v1-to-v2-changes.md) | v1→v2 architecture diff — vocabulary for where v1 things moved |

296+| [docs/migration-dev.md](docs/migration-dev.md) | Migration development guide — testing, debugging, dev loop |

297+| [docs/provider-migration.md](docs/provider-migration.md) | Switching a live agent group between providers (e.g. Claude → Codex) — what carries over, rollback |

298+| [docs/customizing.md](docs/customizing.md) | Short intro to customizing via skills |

299+| [docs/skills-model.md](docs/skills-model.md) | The skills model in full: recipes, tests, upgrades, migrations |

300+| [docs/skill-guidelines.md](docs/skill-guidelines.md) | Authoritative checklist for writing a skill |

301+| [docs/skill-directives.md](docs/skill-directives.md) | `nc:` directive reference: fence grammar, the eight kinds, effects, guards, lint |

302+| [docs/skill-engine-seam.md](docs/skill-engine-seam.md) | Skill-engine consumer contract (wizard / pipeline / agent-relay) + boundary-rule rationale |

303+| [docs/templates.md](docs/templates.md) | Agent templates: what they are, stamping via `ncl groups create --template` + the setup wizard, the OneCLI/MCP-credential model, supported providers, and how to contribute one |

304+| [docs/hardened-image.md](docs/hardened-image.md) | Opt-in: pull the agent image from a registry instead of building it |

305+

306+## Container Build Cache

307+

308+The container buildkit caches the build context aggressively. `--no-cache` alone does NOT invalidate COPY steps — the builder's volume retains stale files. To force a truly clean rebuild, prune the builder then re-run `./container/build.sh`.

309+

310+## Container Runtime (Bun)

311+

312+The agent container runs on **Bun**; the host runs on **Node** (pnpm). They communicate only via session DBs — no shared modules. Details and rationale: [docs/build-and-runtime.md](docs/build-and-runtime.md).

313+

314+**Gotchas — trigger + action:**

315+

316+- **Adding or bumping a runtime dep in `container/agent-runner/`** → edit `package.json`, then `cd container/agent-runner && bun install` and commit the updated `bun.lock`. Do not run `pnpm install` there — agent-runner is not a pnpm workspace.

317+- **Bumping `@anthropic-ai/claude-agent-sdk`, `@modelcontextprotocol/sdk`, or any agent-runner runtime dep** → no `minimumReleaseAge` policy applies to this tree. Check the release date on npm, pin deliberately, never `bun update` blindly.

318+- **Writing a new named-param SQL insert/update in the container** → use `$name` in both SQL and JS keys: `.run({ $id: msg.id })`. `bun:sqlite` does not auto-strip the prefix the way `better-sqlite3` does on the host. Positional `?` params work normally.

319+- **Adding a test in `container/agent-runner/src/`** → import from `bun:test`, not `vitest`. Vitest runs on Node and can't load `bun:sqlite`. `vitest.config.ts` excludes this tree.

320+- **Adding a Node CLI the agent invokes at runtime** (like `agent-browser`, `claude-code`, `vercel`) → put it in the Dockerfile's pnpm global-install block, pinned to an exact version via a new `ARG`. Don't use `bun install -g` — that bypasses the pnpm supply-chain policy.

321+- **Changing the Dockerfile entrypoint or the dynamic-spawn command** (`src/container-runner.ts` line ~503) → keep `exec bun ...` so signals forward cleanly. The image has no `/app/dist`; don't reintroduce a tsc build step.

322+- **Changing session-DB pragmas** (`container/agent-runner/src/db/connection.ts`) → `journal_mode=DELETE` is load-bearing for cross-mount visibility. Read the comment block at the top of the file first.

323+

324+## CJK font support

325+

326+Agent containers ship without CJK fonts by default (~200MB saved). If you notice signals the user works with Chinese/Japanese/Korean content — conversing in CJK, CJK timezone (e.g., `Asia/Tokyo`, `Asia/Shanghai`, `Asia/Seoul`, `Asia/Taipei`, `Asia/Hong_Kong`), system locale hint, or mentions of needing to render CJK in screenshots/PDFs/scraped pages — offer to enable it:

327+

328+```bash

329+# Ensure .env has INSTALL_CJK_FONTS=true (overwrite or append)

330+grep -q '^INSTALL_CJK_FONTS=' .env && sed -i.bak 's/^INSTALL_CJK_FONTS=.*/INSTALL_CJK_FONTS=true/' .env && rm -f .env.bak || echo 'INSTALL_CJK_FONTS=true' >> .env

331+

332+# Rebuild and restart so new sessions pick up the new image

333+./container/build.sh

334+launchctl kickstart -k gui/$(id -u)/com.nanoclaw # macOS

335+# systemctl --user restart nanoclaw # Linux

336+```

337+

338+`container/build.sh` reads `INSTALL_CJK_FONTS` from `.env` and passes it through as a Docker build-arg. Without CJK fonts, Chromium-rendered screenshots and PDFs containing CJK text show tofu (empty rectangles) instead of characters.

20339