Docs updates

• Setup and operations: existing-install template choices, model fallback and fast mode, Docker inspection commands, image checks, credential admission, and scheduled-task cleanup now match the implementation.
• Session boundaries and recovery: the guides distinguish separate provider conversations from confidentiality. Agents can retrieve another session’s history within their own group. Lifecycle guidance describes driver-backed startup, adoption, durable claims, and event-driven reconciliation.
• Channels: Teams follows the CLI provisioning flow; Slack describes managed installation, mention-triggered shared rooms, and the limits of membership events. WhatsApp Cloud uses its actual webhook path.
• References and extensions: link-only cards, richer conversation metadata, default-instance DM caching, plugin-owned MCP servers, and skill refresh are aligned with source. Reserved wake-signal storage is clearly distinguished from active runtime coordination.
• Release scope: new main-branch behavior is listed under Unreleased, without inventing a numbered release.

• Explained the separate template-creation and conversation-connection steps, including a source-verified terminal path.
• Scoped routine inspection and activation to the chosen assistant, and corrected the existing-install and first-message guidance.
• Added a labeled conversation illustration, template-selection cards, and a real sign-in completion screenshot with provenance.

• Replaced the compressed wizard inventory with a guided path and optional alternatives.
• Added NanoClaw sign-in screenshots with action captions and a clearly labeled example conversation.
• Distinguished the NanoClaw download account from the AI account, and made the terminal-agent creation choice explicit.
• Moved technical installation details to the existing reference and added help for common setup interruptions.

• The changelog covers v2.3.0. The entry was reconstructed from the merge window between the two version bumps. It was checked against code rather than against the upstream CHANGELOG. It names five breaking changes: the container driver seam, the asynchronous central database, the agent mailbox seam, the Node 22 floor, and the Slack agents decision gate.
• Mattermost gets its own page. Mattermost covers server discovery, the bot account, authenticated card callbacks, and the optional local evaluation server the skill can create. /add-mattermost copies a vendored adapter from the channels branch instead of installing an npm package, which is unusual for a Chat SDK channel. The channels overview gains the row, the card, and the note that Mattermost takes chat over its own outbound WebSocket while card clicks come back on /webhook/mattermost.
• Architecture names the driver seam. Each session is composed as a validated spec and realized by a driver. Containers now carry key-derived ncl- names, and the old readable name survives as the nanoclaw-container-name label. The page also corrects the delivery model: for a provider that streams mid-turn text, closed <message> blocks are the only content door on a chat turn, and the final result no longer delivers content. It also drops claude-md-compose, which no longer exists, because src/project-doc-compose.ts now writes one flat project document with no @-imports.
• Adapter interface catches up with the hook series. The page adds the status-bearing setTyping, setThreadTitle, setSuggestedPrompts, and the defaults member. It also documents the hooks a channel module registers: membership, bridge inbound policy, session created, post delivery, tool extension, and wizard companions.
• Telegram matches what setup does now. The pairing code is 6 digits. /connect_group runs an owner-approval flow. The wizard offers a second bot through TELEGRAM_BOT_TOKEN_<NAME> and TELEGRAM_INSTANCES. The legacy Markdown sanitizer is gone because the adapter renders CommonMark to MarkdownV2 itself.

• New channels/dial — the native dial-CLI adapter, the setup-wizard flow (CLI install and DIAL_CLI_PATH, email one-time-code sign-in, owner-only vs public line, restart and line registration, 6-digit SMS pairing with QR, the 10DLC note, the optional tool install), the shared-line model (number = messaging group, each correspondent a thread), delivery verdicts and the [NanoClaw system notice: …] failure path, voice-call and transcript routing, the pairing brute-force guard and its DIAL_PAIRING_* knobs, /add-dial-number, and /add-dial-tool with its per-agent OneCLI block rules.
• Channels overview — Dial row (setup wizard: yes) and card; native-adapter and no-public-URL lists. Quick start and Installation — Dial in the wizard’s channel step, pair-dial in the setup steps list.
• Skills catalog — rows for /add-dial, /add-dial-number, /add-dial-tool, plus the rest of the trunk drift since the last stamp: /add-anydoc and /migrate-slack-agents added, /use-native-credential-proxy removed (retired upstream). Count 45 → 49. Tools — a Dial section next to Tavily and the local-model tools.

• Node 22 is now the minimum — installation no longer says Node 20 satisfies the host requirement. The package engine and bootstrap both require 22 or newer, and setup upgrades an older install.
• Unknown-sender policy coverage is complete — hardening, security, the entity model, adapter interface, both ncl pages, troubleshooting, and the database schema now include decline_notify: a polite unknown-DM decline plus an owner/admin FYI, deduplicated for 24 hours. Group chats still drop silently.
• Cross-session catch-up is documented — ncl sessions history merges inbound and outbound rows for another session in the same agent group, with scoped access, bounded human output, and full JSON output.
• Conversation lifecycle schema caught up — messaging groups now document detached_at, which preserves wiring and history while blocking delivery after the bot leaves, and pending approvals document the adapter instance used for later card edits. The CLI reference also fixes messaging-group identity to the full (channel_type, platform_id, instance) triple.
• Adapter defaults include sessionMode — channel authors can declare a thread-rooted context as per-thread; wiring creation stamps both the session mode and thread honoring together.

• Architecture — “one writer per file” now names its two deliberate host-side exceptions: command-gate denials written straight to outbound.db and clearing a killed container’s orphaned processing claims, both under the same DELETE journal and busy_timeout discipline. The intro also stops saying the agent “never talks to the network”: it never touches the messaging platforms; its own egress is open by default and lockable.
• Security model — “the blast radius is one session” corrected to one agent group: sessions share the group workspace read-write, so a compromise reaches the group’s files and memory/ tree, matching what the redrawn diagram already said. Conversation histories stay per-session.
• Isolation levels — the four levels are now ranked correctly, per-thread above shared, matching the page’s own decision tree and the code.
• Container lifecycle and installation — the image sections lead with the actual default: setup pulls the pinned hardened image, and building locally from container/Dockerfile is the explicit alternative.
• First agent — idle containers are killed by the host sweep; the runner has no idle self-exit.
• Submitting a template — registry pins bumped: nanoclaw-templates#20 merged 2026-08-14 as 2e0dcd01, so the CONTRIBUTING pin now points at templates main.

• Architecture — the seven-lifeline sequence chart became a boundary-first view: host process above, container below, the two SQLite files sitting on the Docker mount boundary as the only crossings, and the end-to-end message story riding as numbered steps.
• Container lifecycle — the state machine now sits above the persistent mounted session state it orbits, so the disposability thesis is visible: everything above the line dies, everything below survives.
• Entity model — the wiring is drawn as the join at the center, carrying its five behavior axes; the access chain sits beside it.
• Isolation levels — the decision tree lands on a most-to-least-isolated spectrum, with the shared-filesystem caveat bracketing the three session modes.
• Security model — containment instead of a pipeline: the assume-injected agent inside the container boundary, host-side gates inbound, bounded filesystem, network, and approval paths out.
• Channels overview (trunk infrastructure versus the channels-branch catalog), first agent, multi-agent swarm (directed destination edges, including the host rejecting a send with no row), installation, and migrate from v1 (two-actor swimlanes around handoff.json) follow the same treatment.

• New “Templates” nav group — getting started with a template (a standalone newcomer path from a fresh machine, built to be linked directly from social), overview (what a template is, why the format is a vendor-neutral standard, the catalog), using a template (the wizard’s library picker and the ncl path, ref resolution, post-stamp wiring and task activation), updating a stamped agent (the restamp dry run, what resets versus what is never touched, CUSTOMIZED flags), building (manifest, mcp.json, skills, persona, context extras, tasks, local testing, and the pre-plugin migration), and submitting (categories, registry standards, paid-service disclosure, check-templates.mjs, and the PR checklist).
• New template format reference — field-level validation for plugin.json and mcp.json, failure boundaries, the secret lint, size and containment caps, and the PLUGIN_ROOT/PLUGIN_DATA runtime contract.
• Breaking format change documented — plugin.json replaces context/instructions.md as the discovery marker, .mcp.json becomes mcp.json with a declared transport per server, and context//tasks/ move under ai.nanoco.nanoclaw/. The persona is now optional to the loader. Conversion steps are in building a template.
• Cross-links — the quickstart wizard list gains the first-agent template step, ncl CLI and the CLI reference document the restamp flags (--yes, --new, --id) and the plugin-owned MCP server guard, environment variables adds NANOCLAW_TEMPLATES_DIR and NANOCLAW_TEMPLATE_PATH, and first agent and scheduled tasks point at templates where readers will look for them.
• Registry standards — the submission page carries the rules a contribution is held to, including the paid-service disclosure rule (a template may depend on paid MCP servers or API tiers, but its README must say so up front, link the tool, name the tier the template needs, and state that the user brings their own key — tiers rather than prices, which go stale) and the ban on affiliate links, baked-in billing, and author monetization. The matching text landed upstream in nanoclaw-templates#20, which also records that check-templates.mjs fails on a credential-shaped key where NanoClaw’s stamp-time lint only warns, and corrects a checklist line that called the persona a registry requirement — it is optional, and a template without one uses NanoClaw’s default project doc.

• Remote Streamable HTTP MCP servers (nanoclaw#3092, #3221) — tools, container config, MCP tools, self-modification, and both ncl pages now document the --url form: add_mcp_server takes a name and exactly one of command or url, HTTPS enforced, credential-bearing URLs rejected.
• Gmail and Google Calendar tool skills removed upstream (nanoclaw#3172), Tavily added (nanoclaw#3190) — tools rewritten around /add-tavily-tool (keyless remote MCP), the skills catalog drops four rows and adds one (45 skills), credentials reframes its stub-pattern example, extend overview swaps its tool-install exemplar.
• iMessage Photon opt-in is now one text (nanoclaw#3181) — the wizard registers your number itself; the dashboard invite flow is gone from channels/imessage.
• OpenCode provider catch-up merged (nanoclaw#3122) — providers documents the three OPENCODE_MODEL_* passthrough vars.
• ncl CLI reference corrections — dashed positional ids resolve (the no-dashes rule was stale), group scope includes tasks plus current-chat wirings get/update (nanoclaw#3137), groups create is idempotent with --template/--timezone, messaging-groups send documented, tasks flags completed with the 4-fires/day recurrence cap.
• Approval cards keep their content at terminal states (nanoclaw#3143) — db-schema gains the question column (migration 021) and the missed container_configs.timezone (020); credentials updates the expiry wording.
• Architecture — host-module lifecycle registry startup step (nanoclaw#3214) and the warm-stream trigger guard; first agent — group creation initializes the filesystem inline (the lazy-init story was stale); multi-agent swarm — ncl wirings create does auto-create the channel destination; scheduled tasks — script failures back off and auto-pause after 8, wakeAgent: false is a quiet success; writing skills — the guidelines’ three principles (nanoclaw#3211); upgrading — [BREAKING] migration guides now execute, not “by hand”.

• channels/imessage — rewritten for the unified channel (nanoclaw#3164): local (chat.db + Full Disk Access) and hosted (native spectrum-ts line via photon.codes) backends, the Photon device-login wizard with its manual dashboard opt-in, the first-text requirement, hosted media handling, the deterministic backend-resolution ladder, and a full PHOTON_* configuration table. The removed remote mode, IMESSAGE_LOCAL/IMESSAGE_SERVER_URL/IMESSAGE_API_KEY, and imessage-cloud are flagged as a breaking change. Channels overview and the skills catalog rows now match.
• Vercel CLI is opt-in — installation, container lifecycle, and the skills catalog no longer list vercel among the image’s baked-in CLIs; the vercel-cli container skill moved out of the base image and ships with /add-vercel.
• Hardened-image fetch time — the quickstart and the Echo hardened runtime guide no longer say the fetch takes around 20 minutes; it’s now a few minutes, matching the installer’s wording.
• reference/environment-variables — the failure-assist row notes that a non-Claude install dispatches assist to its picked provider first (nanoclaw#3170).

• quickstart — the wizard’s sandbox step now describes both image paths: the recommended pre-built Echo image (sign-in, then a download that currently takes around 20 minutes) and the 3–10 minute local build. The walkthrough gained the sign-in step it was missing.
• operate/upgrading — image refresh guidance now branches by install: ./container/build.sh on local builds, pull on pinned installs (the bare form exits 3 there), and the refresh trigger includes the agent-image pin moving in versions.json.
• guides/scheduled-tasks — task times follow the owning group’s timezone override (ncl groups config update --timezone, applies immediately) before the install default; the restart-required note now applies only to the default.
• reference/environment-variables — the six new registry and hardened-image variables documented, and seven stale setup/auto.ts / setup/container.ts line citations recomputed (the file grew 253 lines under the feature).

• migrate-from-v1 — a flow diagram ahead of the step-by-step walkthrough, showing the migration’s two-actor shape: migrate-v2.sh does the deterministic phases, handoff.json carries the state, and the /migrate-from-v1 skill finishes the judgment calls before the health check
• installation — a small diagram of the three-stage installer chain (nanoclaw.sh → setup.sh → setup:auto) under “What the installer does under the hood”

• channels/signal — the managed daemon now starts with --send-read-receipts (nanoclaw#3062), so senders see messages marked read once the daemon receives them. New Platform notes bullet, including the caveat that an externally run daemon needs the flag added manually. Channels-branch stamp bumped to 7f24dd31 here and on channels/overview (whole-dir citation; overview’s claims are unaffected). The other channel pages cite files that are byte-identical across the two SHAs, so their stamps stay put per the drift-detection rule
• reference/environment-variables — 25 of the 35 file:line citations pointed at the wrong lines, and were already wrong at the e926e30e stamp (a src/config.ts restructure predates the sweep; the sweep verified names and defaults but not line numbers). Every citation is now script-verified against source: the cited line must actually mention the variable. Trunk stamp stays at e926e30e — the cited files are identical at d23db4f3 apart from a claude.ts change well below the cited region
• Checked, no docs impact: compaction no longer surfaces as a synthetic “Context compacted.” result — it logs as activity instead (nanoclaw#3083); no page ever claimed it appeared in chat. Upstream’s CHANGELOG dedup (nanoclaw#3063) touched unreleased entries the portal doesn’t mirror, and nanoclaw#3084 is test-only

• extend/overview + reference/skills-catalog — “a coding harness (Claude Code, Codex, OpenCode)”, not “Claude Code”. “Harness”, not “agent”, deliberately: NanoClaw already calls the container instance an agent, so reusing the word for the host-side tool meant one term for two layers on the same page (extend/overview describes both). Trunk makes the same split where both appear in one breath — .claude/skills/migrate-memory/SKILL.md:9 reads “The coding harness running this skill - Claude Code, Codex, or another harness - owns the whole migration”, then hands off to “the NanoClaw group”
• A syntax note on both pages — /name is Claude Code’s; Codex invokes the same skill as $add-telegram and does not accept /add-telegram (openai/codex#11817, closed “This is by design”); OpenCode has no typed form and loads skills through its own skill tool. Three invocation models, not two syntaxes. The pages listed 48 /name literals with nothing saying whose syntax that is, so a Codex reader following the catalog hit a rejection with no signpost. The note also says the skill file is the same one in every case, while flagging that a few skills still phrase steps in Claude Code’s tool vocabulary
• Removed a false claim — the opening sentence said the coding agent reads and performs the skill “or the setup wizard dispatches an /add-<channel> skill for you”. The wizard does not hand the SKILL.md to a harness; it applies the document itself through the directive engine (setup/lib/skill-driver.ts runs applySkill from scripts/skill-apply.ts against the nc: fences, every non-test caller under setup/). Two readers, one document — upstream’s own framing at docs/skills-model.md:39
• Not fixed here: the invocation syntax the trunk docs themselves use. No literal form is correct on all three harnesses, so trunk needs a convention — filed upstream as nanoclaw#3072. This pass only describes what each harness does today
• Scope note: this is an agents-convention mirror, not end-to-end harness neutrality. Setup remains Claude-Code-shaped (setup/lib/claude-assist.ts, claude-handoff.ts, install-claude.sh), and 13 of the 48 host skills name Claude Code tools in their steps
• Method note: the first revision of this PR deleted “as slash commands in Claude Code” while leaving every /name literal in place, which made the pages worse for exactly the reader they were meant to help. Three independent adversarial reviewers caught that, plus a stray “walks Claude through a task” the completeness grep had missed. verified-against SHAs left at e926e30e: narrow prose fix, not a re-verification

• The memory rework — CLAUDE.local.md is retired. Per-group memory is now the memory/ tree (scaffolded at boot, shared by every provider, carried across provider switches) plus instructions.prepend.md for standing instructions; usesMemoryScaffold is gone from the provider interface. Rewritten across concepts/*, guides/*, extend/providers, extend/self-modification, installation, and migrate-from-v1 (which now documents the staged-CLAUDE.local.md → /migrate-memory flow)
• Scheduled tasks moved to ncl tasks — the six scheduling MCP tools are gone; guides/scheduled-tasks got a ground-up rewrite, reference/mcp-tools lost its Scheduling section, and reference/ncl-cli + operate/ncl-cli gained the tasks resource (including this sweep’s correction: all task verbs are open, not approval-gated)
• SKILL.md-driven setup — the wizard now dispatches /add-<channel> skills; install prose corrected on the channels pages, extend/overview, and extend/writing-skills (which was still quoting a pre-flight block deleted in the nc: directive-fence rewrite)
• Per-wiring threads axis (migration 019) on concepts/entity-model, reference/db-schema, the ncl pages, and channels/discord
• Token badge ~204k → ~226k (now frozen — update-tokens.yml was deleted); container skills 8 → 6; DEFAULT_AGENT_PROVIDER; structured approval cards; host-only add-mount/remove-mount
• Method note: every area’s pre-verified “no content change, bump only” verdicts were re-checked adversarially before shipping — that re-check found real drift in all four areas it flagged, so it’s now a standing step of the sweep process

• extend/providers — the codex provider’s AGENTS.md compose now opens with the group’s template persona (instructions.prepend.md, exempt from the 32 KB-cap eviction), template skills are mirrored into .agents/skills as real directories (they’re stamped on the Claude plane, which Codex never reads), and the .agents dir is mounted at both /workspace/agent/.agents and /home/node/.agents — Codex only scans workspace-level .agents/skills inside a git repo, so the $HOME mount is what makes skills discoverable. Providers-branch anchor bumped to d2dd91b
• reference/environment-variables — all 37 source citations re-checked at b6cb53e: every variable and default still accurate; 10 drifted line numbers corrected and the “line numbers reference v2.1.4” disclaimer updated to v2.1.38
• reference/container-config — the two “as of v2.1.4” absence claims (no ncl groups config subcommand for skills; add-mcp-server / add_mcp_server don’t accept instructions) re-verified still true at v2.1.38 and restamped; anchor bumped to 08a1ac9
• concepts/contributing — pnpm run dev never had hot reload (tsx src/index.ts, no watch, unchanged since the initial commit); corrected the command comment. Surfaced by cross-checking the in-repo docs overhaul (nanoclaw #2961–#2964) against the portal
• OneCLI accuracy pass (operator-audited, all 26 OneCLI-mentioning pages): operate/troubleshooting’s “gateway not applied” hint told operators to check 127.0.0.1:10254, but the host dials whatever ONECLI_URL says — on installs where containers reach the gateway, that’s the Docker-bridge IP and nothing listens on localhost; reference/environment-variables listed https://api.onecli.sh as the default for NANOCLAW_ONECLI_API_HOST, but unset means “install a local vault” (setup/auto.ts:238) — the URL is only the advanced-settings form placeholder; operate/credentials now notes that OneCLI’s own docs reserve “gateway” for the separate egress-proxy listener, while these pages use it loosely for the whole vault
• New: “Accessing the OneCLI dashboard” (operate/credentials) — the tool pages referenced connecting OAuth services “in the OneCLI web UI” without ever saying where that lives. The new section anchors it to ONECLI_URL, covers the two headless-install gotchas (Docker-bridge bind not routable from your browser; OAuth Connect redirects need OneCLI’s APP_URL set to the URL you browse from), and links out to the OneCLI docs; extend/tools now links the section

• .env support arrived for vars the docs called process.env-only: config.ts now falls back to .env for CONTAINER_CPU_LIMIT, CONTAINER_MEMORY_LIMIT, and the three egress vars — corrected on reference/environment-variables, operate/configuration, operate/hardening, and operate/troubleshooting. WEBHOOK_PORT is the exception and stays documented as process.env-only.
• Five env vars removed upstream (the host-sweep loop replaced the old timeout/concurrency machinery): CONTAINER_TIMEOUT, IDLE_TIMEOUT, MAX_CONCURRENT_CONTAINERS, CONTAINER_MAX_OUTPUT_SIZE, MAX_MESSAGES_PER_PROMPT — dropped from reference/environment-variables, operate/configuration, operate/hardening, and guides/multi-agent-swarm.
• Security correction (operate/hardening): the readOnly key on additional mounts is no longer silently ignored — mount-security honors it, so {readOnly: false} grants read-write. The page said the opposite, understating permissiveness.
• reference/skills-catalog: 47 → 48 skills (/add-clidash)
• verified-against anchors bumped to 08a1ac9 on the touched pages

• introduction — plain-language page description (was architecture jargon); new “What can it do?” section with six concrete, code-verified capabilities; the message-flow diagram and design rationale compressed into a short “Under the hood, briefly” paragraph linking to concepts/architecture (which covers it in depth) — the intro no longer duplicates it
• quickstart — new “Things to try first” section: six copy-paste messages exercising web research, reminders, sandboxed code, inbound attachments, persistent memory, and companion agents, each verified against source (web tools are on the Claude provider’s allowlist; schedule_task routes back to the originating chat; attachments land in the session inbox; CLAUDE.local.md persists per group; the wizard’s first agent has global CLI scope so create_agent needs no approval card). Includes the CLI-channel gotcha: reminders that fire while the terminal is disconnected are saved, not pushed live
• Placeholder (comment) for a hero chat screenshot on introduction, pending a capture from a live install

• Inbox symlink-containment guard (concepts/security): documented the new shared host-write guard src/inbox-safety.ts under Container isolation — the one place files flow into the sandbox
• ncl messaging-groups --instance (reference/ncl-cli): new flag row — string, updatable, defaults to the --channel-type value
• WhatsApp media recovery (channels/whatsapp): failed inbound media downloads retry via WhatsApp’s re-upload path; still-failing media leaves a visible [<type> could not be downloaded] note instead of a silent drop
• Slack Socket Mode in guided setup: upstream’s setup wizard caught up with what channels/slack already documented — the page verified accurate as-is, no content change
• Full SHA re-verification: classified every page’s cited files against the trunk and channels diffs, re-verified the dirty set, and bumped verified-against anchors site-wide to cb6e3d1 / 90dd87d; fixed a transposed-digit providers-branch anchor (c576766 → c570766) on extend/providers. Codebase token count 199k → 204k

• Agent-to-agent approval policies (migrations 017/018): documented the per-message gate on connected agents (the new ncl policies resource, the agent_message_policies table), the strict named approver (approver_user_id), and reject-with-reason across guides/multi-agent-swarm, concepts/security, reference/{db-schema,ncl-cli}, operate/ncl-cli, and extend/self-modification.
• Codex provider v2 (extend/providers): install via the cli-tools.json manifest, vault-only auth, composed AGENTS.md + .agents/skills + per-group ~/.codex. Removed the stale .env / OPENAI_BASE_URL claims.
• Container resource caps + /learn: CONTAINER_CPU_LIMIT / CONTAINER_MEMORY_LIMIT added to reference/environment-variables, operate/{configuration,hardening}, and concepts/container-lifecycle; the /learn skill added to reference/skills-catalog (46 → 47) and extend/writing-skills.
• Upgrade flow (operate/upgrading): /update-nanoclaw now upgrades the OneCLI gateway when its versions.json pin moves (reversing the old “never upgraded for you”), and /update-skills rebuilds the container image when re-applied code lives under container/.
• Provider-aware install (installation, quickstart): the credential prerequisite is now “a credential for the provider you pick,” not Claude-only.
• Full SHA re-verification: re-verified every cited file’s diff e3986eb..2afbd182 and bumped the verified-against anchor on ~30 pages; bumped the channels registry branch to fdbfb6a and refreshed the channel-adapter pins to 4.29.0 (Chat SDK lock). Codebase token count 195k → 199k.

• Milestone entries for the versions upstream’s CHANGELOG.md documents — the ncl admin CLI + v1→v2 migration (2.0.45), container-config-in-DB + cli_scope (2.0.48), per-group model/effort (2.0.54), the per-install-service-names breaking rollup (2.0.55–2.0.63), the destinations-through-approval fix (2.0.64), and the startup upgrade-marker breaking change (2.1.0)
• Egress lockdown reconstructed for v2.1.1 from commits; honest rollups for the rapid-patch ranges (2.0.1–2.0.44 stabilization, 2.0.65–2.0.76) with a pointer to GitHub releases
• Every version 2.0.1–2.1.4 is now accounted for in a labeled entry. Closes the last known gap noted in the v2.1.16 sweep

• extend/tools.mdx: the local-model tool skills keep the agent as the orchestrator (not “Claude”)
• guides/scheduled-tasks.mdx: a firing is “a full model API call” / “the agent got called”
• reference/mcp-tools.mdx: “the tools the agent can call” (dropped the (Claude) parenthetical); create_agent seeds the provider’s own memory surface (CLAUDE.local.md for Claude, the memory/ scaffold otherwise), matching the multi-agent-swarm fix
• installation.mdx: the wizard does “provider auth”; quickstart.mdx: “AI-assisted recovery” (failure assist can be provider-owned since v2.1.16)

• Product changelog + token count: added the v2.1.16 release (operator-driven provider selection, per-group provider switching via ncl groups config update --provider, and /migrate-memory) and bumped the codebase token count to 195k.
• Provider selection (16 v2.1.15 pages): documented the setup-time runtime picker (quickstart), the memory-across-a-switch story and /migrate-memory (extend/providers), and fixed multi-agent-swarm (a spawned agent inherits its creator’s provider; the seed lands in the provider’s own memory surface) and upgrading (the /update-nanoclaw breaking-change check is skill-only now — it no longer diffs versions.json pins). Corrected six drifted file:line citations on reference/environment-variables.
• Re-verified the 19 v2.1.4 main pages: 14 were no-drift; 5 fixed — installation (new provider-auth setup step), concepts/contributing (185k → 195k, vitest globs), reference/skills-catalog (added /migrate-memory; 45 → 46 skills), operate/troubleshooting (boot failures now log Container exited non-zero with a stderrTail), extend/overview (provider installs span three barrels now — host, container, and setup).
• Re-verified the 8 channel pages: the channels registry branch is frozen at 8137440 (adapters unchanged since before v2.1.4), so no content drift — pinned that SHA on each page for precise future adapter-drift detection.

• changelog/index.mdx: reconstructed the v2.1.5–v2.1.15 product releases from upstream commits (the upstream CHANGELOG.md still parks everything under [Unreleased]). v2.1.5 was the big one — multi-instance adapters and the interactive uninstaller
• Re-verified and bumped verified-against SHAs to 435233a on pages whose cited files changed without any claim drifting: concepts/architecture, reference/container-config, guides/scheduled-tasks, concepts/isolation-levels, guides/multi-agent-swarm
• channels/teams: corrected the webhook-path note to /webhook/{routingPath} to match the raw-route change
• Known gap: the product changelog still jumps v2.0.0 → v2.1.5; the v2.0.1–v2.1.4 patch releases predate the docs site and remain unreconstructed

• The scan → confirm → execute flow, the four removal groups, and what’s deliberately left alone (the OneCLI vault, other NanoClaw copies — everything is scoped to the per-checkout install slug)
• The --dry-run and --yes flags, the .env backup, the Ctrl-C-safe confirm phase, and the manual fallback when node_modules/ is already gone
• Resolved a flag-spelling discrepancy against source: the flags are --dry-run/--yes (kebab-case), and they’re CLI-only — there are no NANOCLAW_* env vars for them
• reference/environment-variables.mdx re-verified (no env var drift in v2.1.15) and its SHA bumped

• operate/credentials.mdx: setup installs the gateway and onecli CLI at the versions.json pins (onecli-gateway, onecli-cli), never latest; it probes /v1/health and warns (never auto-upgrades) when the gateway predates the /v1 API, pointing to the docs/onecli-upgrades.md runbook
• operate/upgrading.mdx: the /update-nanoclaw breaking-changes step now also diffs versions.json for moved component pins and routes each to its migration path — a skill or a docs/ page

• usesMemoryScaffold: a provider without native memory opts in, and the runner builds an idempotent memory/ tree (index.md, system/definition.md, memories/, data/) in the agent’s host-backed workspace at boot. Claude omits it — it already has native memory (CLAUDE.local.md).
• onExchangeComplete: the poll loop hands each prompt/result round-trip to providers whose harness keeps no on-disk transcript, so they can archive exchanges themselves.
• providesAgentSurfaces: a provider can declare it owns the composed project doc, skill links, and state dir; the host then skips the default surfaces and the provider composes its own.
• Same pass nudged the page’s voice provider-neutral (Claude framed as the default, not the only brain).

• reference/adapter-interface.mdx: new optional instance field on the ChannelAdapter contract (defaults to channelType; URL-safe routing key); channelType clarified as the semantic platform key; webhook registration now uses a routingPath and the shared server also accepts raw registerWebhookHandler() routes
• reference/db-schema.mdx + concepts/entity-model.mdx: messaging_groups is now keyed (channel_type, platform_id, instance); documented the new instance column, migration 016’s backfill (instance = channel_type), and the per-instance chat_sdk_kv key prefix
• channels/overview.mdx + concepts/architecture.mdx: webhook server routes by routingPath with raw handlers taking priority; delivery resolves the owning adapter by instance so a reply leaves through the adapter the message arrived on

• introduction.mdx: codebase token count ~185k → ~194k (verified against repo-tokens/badge.svg)
• installation.mdx and concepts/container-lifecycle.mdx: the container’s pinned global CLIs now come from a container/cli-tools.json manifest installed by install-cli-tools.sh — agent-browser is pinned to an exact version rather than tracking latest

​

Structure

• New navigation with 7 Documentation groups and a 2-group Reference tab; Changelog is a global anchor
• 29+ redirects — no pre-refactor URL 404s
• The fictional HTTP “API Reference” tab is gone; reference/ now documents the real surfaces: the ncl admin CLI (all 11 resources), environment variables, container config, the skills catalog (45 + 8 container skills), the channel adapter contract, agent MCP tools, and the full database schema

​

Content

• Every page rewritten or written new against upstream source at nanocoai/nanoclaw@dc34ceb (v2.1.4) — never against upstream markdown, which has drifted
• Every page carries a verified-against comment naming the source files and SHA it was checked against, so future drift is detectable per page
• 12 v1 ghost pages deleted (x-twitter, parallel-ai, voice-transcription, image-vision, pdf-reader, remote-control, ipc-system and more — all verified absent from v2 code)
• New pages: v1/OpenClaw migration guide, Signal/iMessage/Teams/CLI-channel/more-channels, configuration, credentials, upgrading, isolation levels, self-modification, writing skills, first-agent tutorial, and the seven reference pages
• Code-first corrections shipped along the way: tini is not PID 1 at runtime, groups/global/ is dead code, skills were never git branches in v2, Gmail is an MCP tool rather than a channel, MAX_CONCURRENT_CONTAINERS is parsed but unenforced, and the Teams wizard prints a webhook path the server 404s (documented with a warning)

​

Meta

• The repo’s own CLAUDE.md and the three Mintlify automation workflows were rewritten so future sessions and automated PRs inherit the v2 model and the code-first verification rule

​

Rewritten

• introduction.mdx: v2 positioning — two-DB session IO, entity model, Node + Bun runtime split, OneCLI-only credentials. Token count updated to ~127k (~64% of context window). Source file table aligned with src/ as of v2.0.1.
• quickstart.mdx: one-command bash nanoclaw.sh flow replaces the v1 fork-and-clone + Claude Code + /setup dance. Documents the three-level setup log contract (terminal, logs/setup.log, per-step raw logs) and the Anthropic OAuth exception.
• installation.mdx: simplified to system requirements + platform prerequisites + bash nanoclaw.sh. Service management retained (launchd / systemd / WSL wrapper). File-structure tree updated for data/v2-sessions/, store/v2.db, and the per-session inbound.db + outbound.db layout.
• integrations/overview.mdx: reframed around channels (13+) and providers (4), both living on dedicated branches (channels, providers). Expanded channel list to cover Teams, iMessage, Matrix, Google Chat, Webex, Linear, GitHub, WeChat, Resend, and the local /claw CLI.
• features/customization.mdx: full v2 rewrite — verified trigger pattern code against src/config.ts, replaced nonexistent POLL_INTERVAL / SCHEDULER_POLL_INTERVAL with actual ACTIVE_POLL_MS / SWEEP_POLL_MS from src/delivery.ts, documented per-wiring engage config (engage_mode, sender_scope, ignored_message_policy, session_mode), kept OneCLI / legacy credential proxy as version tabs.

​

v2 update banners

• integrations/whatsapp.mdx, telegram.mdx, discord.mdx, slack.mdx, gmail.mdx, x-twitter.mdx, skills-system.mdx
• integrations/ollama.mdx (Ollama now lives on the providers branch — /add-ollama-provider or /add-ollama-tool)

​

Token count sync

• integrations/skills-system.mdx: 43.8k → 127k
• CLAUDE.md: maintenance note updated to reflect the v1.2.53 → v2.0.0 jump

​

Updated

• Two-database session model: inbound.db (host writes) + outbound.db (container writes) replace stdin/stdout piping and filesystem IPC — documented across concepts/architecture, advanced/ipc-system, advanced/container-runtime
• Entity model: agent groups, messaging groups, wirings (many-to-many), users, and roles replace the v1 group/channel model — new concepts/groups and api/group-management
• Bun-based agent runner: runs TypeScript directly (no compilation), shared source via read-only bind mount, tini as PID 1 — concepts/containers, advanced/container-runtime
• Permissions system: engage modes (pattern/mention/mention-sticky), sender scope (all/known), unknown sender policies (strict/request_approval/public), approval flows — concepts/security, advanced/security-model
• Delivery system: two-poll architecture (active 1s, sweep 60s) with delivery action registry — features/messaging
• Task model: tasks as messages_in rows with cron recurrence and series tracking — concepts/tasks, features/scheduled-tasks, api/task-scheduling
• OneCLI Agent Vault is the sole credential path; legacy credential proxy removed — advanced/security-model, api/configuration
• Changelog: v2.0.0 release entry

​

Archived

• v1 docs frozen at branch v1-docs (public-facing, docs only) and tag v1-docs-final (full repo snapshot)

​

Updated

• Token count: Updated from 43.7k to 43.8k in introduction and skills-system pages
• Configuration: Added ONECLI_API_KEY env var to OneCLI Agent Vault tab
• Container SDK config: Documented allowDangerouslySkipPermissions: true flag in containers page
• Changelog: Added v1.2.53 product release entry

​

Updated

• Token count: Updated from 43.4k to 43.7k in introduction and skills-system pages
• Changelog: Added v1.2.48–v1.2.52 product release entries
• Skills system: Added /add-karpathy-llm-wiki to upstream skills listing; added /migrate-nanoclaw and /migrate-from-openclaw to operational skills
• Troubleshooting: Added session artifact auto-pruning section with retention policy table
• Architecture: Documented auto-compact threshold at 165k tokens

​

Updated

• Store mount (rw): Documented store/ read-write mount for main agent across containers, container-runtime, security, security-model, groups, customization pages
• requiresTrigger parameter: Added to register_group MCP tool description in containers and messaging pages
• Reply context: Updated architecture database section with reply_to_message_id, reply_to_message_content, reply_to_sender_name columns
• isMain preservation: Updated register_group handler snippet in messaging page
• CONTAINER_MAX_OUTPUT_SIZE: Added truncation behavior note to configuration reference
• Token count: Updated from 43.3k to 43.4k in introduction and skills-system pages
• Changelog: Added v1.2.46 and v1.2.47 product release entries

• quickstart: Added breaking change changelog scan to /update-nanoclaw step list
• integrations/skills-system: Added “Breaking change detection” subsection documenting the [BREAKING] entry scan and migration skill prompts

​

Fixed

• concepts/containers: Removed incorrect “15-second exec timeout” claim from stopContainer — the source uses execSync with no timeout, falling back to SIGKILL on failure

​

Updated

• integrations/skills-system: Added /add-macos-statusbar utility skill to upstream skills listing
• changelog/index: Added v1.2.45 release entry with new contributors and skill

​

Updated

• OneCLI version labels: Corrected Agent Vault version from v1.2.22+ to v1.2.35+ across 8 pages, added tabbed 401 troubleshooting
• Ollama integration: Added 4 admin tools (ollama_pull_model, ollama_delete_model, ollama_show_model, ollama_list_running) gated by OLLAMA_ADMIN_TOOLS=true, noted Ollama removal from core
• Stale session recovery: Added auto-recovery docs to troubleshooting and container-runtime lifecycle, plus manual sqlite3 fallback
• Container runtime: Documented hostGatewayArgs(), --add-host flag, curl/git in container image
• SDK options: Added settingSources and sender parameter docs
• Reply context: Documented reply/quoted message support — reply_to attribute, <quoted_message> element, 4 new NewMessage fields, DB migration
• Token count: Updated from ~42.4k to ~43.3k (22%)
• v1.2.43 changelog: Added npm audit dependency fixes bullet

​

Fixed

• api/message-routing: Removed phantom channel?: ChannelType param from formatOutbound signature
• features/scheduled-tasks: Updated TIMEZONE snippet to current resolveConfigTimezone() with IANA validation and UTC fallback
• advanced/container-runtime: Fixed stopContainer code from async exec() callback to actual sync try/catch pattern
• api/configuration: Added trace as valid LOG_LEVEL value (used by container runner for verbose output)
• features/messaging: Corrected stale src/session-commands.ts reference to src/index.ts, and fixed misleading description of what index.ts does

​

Updated

• advanced/remote-control: Fixed inaccurate security section — the remote control URL requires Anthropic sign-in, not just URL secrecy. Based on feedback from Gavriel Cohen.

​

Updated

• OneCLI rebrand: Renamed “OneCLI Gateway” to “OneCLI Agent Vault” across 15 pages, updated URL to github.com/onecli/onecli. Code snippets preserved as-is (upstream source still uses “gateway” in code).
• Message limits: Corrected 200-message cap to MAX_MESSAGES_PER_PROMPT (default 10) across messaging, architecture, and configuration pages
• Dependencies: Removed phantom deps (pino, pino-pretty, yaml, zod), updated better-sqlite3 to 11.10.0 and cron-parser to 5.5.0
• Token count: Updated from ~41.3k to ~42.4k
• Mount property: Fixed containerConfig.mounts → additionalMounts with hostPath
• SQL column: Fixed trigger → trigger_pattern in troubleshooting query
• Product changelog: Added entries for v1.2.35 through v1.2.42

​

New sections

• Telegram forum topics (integrations/telegram) — message_thread_id tracking and automatic topic routing
• Task scripts cost guidance (concepts/tasks, features/scheduled-tasks, api/task-scheduling) — API credit awareness, testing guidance, when-not-to-use advice
• Auth 401 troubleshooting (advanced/troubleshooting) — short-lived vs long-lived OAuth tokens, claude setup-token fix
• K8s image GC (advanced/troubleshooting) — Rancher Desktop kubelet garbage collection known issue
• Text-style formatting (features/messaging) — corrected WhatsApp link rendering and Telegram Markdown v1 preservation
• Security fixes (advanced/container-runtime, advanced/security-model, concepts/security) — stopContainer name validation, mount path colon rejection, isMain preservation, allowlist caching behavior
• Configuration: Added MAX_MESSAGES_PER_PROMPT and LOG_LEVEL environment variables
• Skills: Added /init-onecli (operational) and /add-emacs (upstream)

​

Closed as invalid

• #150: Fabricated runtime-based credential routing — no such feature exists in upstream
• #149: Wrong context_mode default (group instead of actual isolated)
• #134: Promoted skill-only OLLAMA_ADMIN_TOOLS env var to core config

​

New sections

• Task scripts (concepts/tasks, features/scheduled-tasks, api/task-scheduling) — pre-execution bash scripts with wakeAgent JSON contract, ScriptResult type, execution flow
• Per-group trigger patterns (features/messaging, concepts/groups, api/configuration) — custom trigger words per group instead of global @{ASSISTANT_NAME}
• CLAUDE.md template system (concepts/groups, api/group-management) — automatic template copy during registration with isMain-based selection
• Channel-formatting skill (features/messaging, api/message-routing, integrations/slack, integrations/skills-system) — per-channel text transformation table
• WhatsApp pairing code auth (integrations/whatsapp) — tabbed QR code vs pairing code with phone number formatting rules
• loginctl linger (installation, quickstart, advanced/troubleshooting) — systemd user service persistence after SSH logout
• Mount-allowlist preservation (quickstart, advanced/troubleshooting) — /setup skips overwrite of existing config

​

Updated

• Container base image: Fixed node:24-slim → node:22-slim across 6 pages (v1.2.22 changelog never upgraded to Node 24)
• Timezone configuration: Added resolveConfigTimezone() with IANA validation and UTC fallback across 4 pages
• Token count: Updated from ~39.8k to ~41.3k in introduction and skills system pages
• Agent-runner cache: Documented mtime-based refresh instead of one-time copy
• Customization: Removed phantom MAIN_GROUP_FOLDER constant
• Product changelog: Added entries for v1.2.24 through v1.2.34

​

Closed as invalid

• #125: Fabricated upstream PR #1346 as “stdin secrets / remove OneCLI” — actual PR is macOS menu bar status indicator
• #119: Destructively removed credential proxy legacy tabs that are intentionally maintained
• #88: Incorrectly documented sender as IPC send_message parameter (it’s a NewMessage field)
• #89: Falsely claimed Telegram is a core channel on main (it lives in nanoclaw-telegram fork)

​

Updated

• Legacy credential proxy tabs: Updated to reference /use-native-credential-proxy skill instead of deleted src/credential-proxy.ts file path
• Skills system: Added /use-native-credential-proxy to upstream skills list
• Architecture: Fixed startup sequence order (OneCLI agent sync before Remote Control restore), enriched database schema descriptions
• IPC system: Documented in-container poll interval (500ms), removed undocumented sender field
• Containers: Fixed .env shadow mount to note conditional existence check, clarified container stop timeout cascade
• Configuration and installation: Added onecli --help references
• Introduction and skills system: Updated token count from ~41k to ~39.8k
• Product changelog: Updated v1.2.23 entry with credential proxy skill and dead code cleanup

​

Pages updated

• Security overview and deep dive: Credential handling sections now use tabs for OneCLI Agent Vault vs Credential Proxy (legacy)
• Configuration: Environment variables, example .env, and security notes updated with tabs
• Container runtime: Container arguments code and key flags documented for both methods
• Architecture: Startup sequence and container image updated
• Installation: OneCLI added as prerequisite #5, @onecli-sh/sdk dependency
• Containers, Ollama, Skills examples: Passing references updated to version-neutral language
• Customization: Mount allowlist format updated (allowedPaths → allowedRoots with per-root read/write control)
• Product changelog: Added v1.2.22 release entry and v1.2.0 scheduled task fix

​

Updated

• Installation, introduction, creating-skills: Added Windows (WSL2) to all platform references — NanoClaw supports macOS, Linux, and Windows via WSL2
• Introduction: Fixed token count from 34.9k to ~41k (matches auto-generated repo-tokens/badge.svg)
• CLAUDE.md: Added guidance for automated PR triage, changelogs, upstream PR workflow, and token count source of truth

​

Upstream PR (#1388)

• Added docs.nanoclaw.dev link to README header
• Populated CHANGELOG.md with all releases from v1.1.0 through v1.2.21
• Updated docs/REQUIREMENTS.md — multi-channel support, current RFS, WSL2 deployment
• Updated docs/SECURITY.md — channel-neutral language
• Updated docs/DEBUG_CHECKLIST.md — Docker (default) commands, channel-neutral
• Added docs/README.md — index pointing to docs portal as authoritative source

​

New pages

• Claw CLI (features/cli) — documents the /claw Python CLI for running agents from the command line (#64)

​

New sections

• Apple Container vs Docker (advanced/container-runtime) — when to use each runtime, key differences table, switching instructions (closes #50)
• Container internals (concepts/containers) — allowed tools table, conversation archival, global memory injection, additional directory auto-discovery
• Slack message formatting (integrations/slack) — mrkdwn syntax differences and /slack-formatting skill
• 200-message history cap (features/messaging) — documents the default query limit on message retrieval (closes #49)
• Opt-in diagnostics (concepts/security, quickstart) — PostHog telemetry, consent flow, permanent opt-out (#68)

​

Updated pages

• Skill system — updated from 3 to 4 skill types (feature, utility, operational, container) across 6 pages
• Skills documentation — added utility skill structure, creation steps, and /claw as example
• Architecture — fixed database table names (scheduled_tasks, task_run_logs), isScheduledTask flag, stdin description, startup sequence expansion
• Message routing — added syncGroups to Channel interface
• Configuration — fixed DATA_DIR description (runtime data, not legacy)
• Skills system — added missing skills (/get-qodo-rules, /qodo-pr-resolver, /x-integration, /add-compact, /add-parallel, /slack-formatting)
• Contributing — removed /clear from RFS (exists as /add-compact), updated to 4 skill types
• SEO descriptions — improved frontmatter across 10 pages for better search discoverability

​

Fixed

• 13-page factual error sweep against source code (#67) — credential proxy terminology, IPC operations, container mount behavior, removed phantom MCP tool
• Consolidated overlapping fixes from 6 PRs into 2 clean PRs (#70, #71), closing 7 automated PRs as superseded
• Excluded incorrect automated changes: Channel Factory rename, fabricated commit reference, speculative formatting table, unverified frontmatter claims

​

Housekeeping

• Product changelog: added v1.2.20 (ESLint) and v1.2.21 (diagnostics) entries, fixed version ordering
• Resolved all open issues — 0 issues remaining
• Token count updated from “under 35k” to “~41k”

​

New pages

• Ollama integration (integrations/ollama) — MCP server architecture, local model setup, third-party endpoints
• Voice transcription (features/voice-transcription) — Whisper API (cloud) and whisper.cpp (local) with comparison table
• Image vision (features/image-vision) — Multimodal image understanding for WhatsApp
• PDF reader (features/pdf-reader) — Text extraction via poppler-utils
• X (Twitter) integration (integrations/x-twitter) — Host+agent architecture, OAuth setup
• Parallel AI (integrations/parallel-ai) — Web research MCP servers (quick search + deep research)

​

Updated pages

• Skills system — Documented channel fork architecture (5 fork repos), updated merge workflows, separated upstream vs fork skills
• Installation — Added Windows (WSL) support across all sections: prerequisites, Docker Desktop WSL 2 backend, troubleshooting
• Security — Documented sender allowlist: trigger/drop modes, per-chat overrides, file format
• Messaging — Added /compact session command and authorization rules
• Telegram — Expanded agent swarm section with installation and per-bot config
• WhatsApp — Added skills summary table and emoji reactions section
• API reference — Fixed formatMessages signature (added timezone param and <context> header)
• Configuration — Added OLLAMA_HOST, expanded ANTHROPIC_BASE_URL and SENDER_ALLOWLIST_PATH docs

​

Housekeeping

• Deleted 6 stale mintlify/* branches
• Created tracking issues for 3 remaining low-priority gaps (#49, #50)

• Fixed credential proxy documentation — removed incorrect claims about hot-swapping and auto-refresh
• Corrected container runtime detection, base image references, and stdin secrets pattern
• Updated task scheduling docs with correct table names and interfaces
• Added missing .env shadow mount and CREDENTIAL_PROXY_HOST documentation
• Fixed syncGroupMetadata → syncGroups across IPC docs

• Updated error log examples to show prompt redaction — input metadata only, no full prompt content
• Added log privacy section to security docs
• Corrected docker stop grace period from 15s to 1 second across all references

• Fixed remote-control commands documentation
• Deduplicated IPC docs
• Added update_task to auth tables in API reference

• Added automatic sidebar tag management via Mintlify workflows (UPDATED and NEW tags)
• Replaced all ASCII directory trees with Mintlify <Tree> component across the site
• Tags auto-clean after 2 weeks via weekly audit workflow

• Documented /capabilities and /status container-agent skills as new pages
• Synced docs with source code v1.2.17 — corrected mount allowlist format, interval drift handling, credential proxy behavior, and IPC config
• Documented IPC task snapshot refresh and update_task operation

• Added Mintlify workflow to sync docs automatically on upstream code changes
• Added weekly docs audit and skill branch documentation workflows

• Applied NanoClaw branding with custom theme colors, fonts, and SEO metadata
• Switched theme from Aspen to Mint for better sidebar typography
• Cleaned up introduction page, footer, and removed callout CSS override

• Audited all content against v1.2.14 codebase
• Added Remote Control and Docker Sandboxes pages
• Made quickstart channel-agnostic (removed WhatsApp-as-default bias)
• Updated skills documentation to reflect git-branch architecture
• Fixed navigation structure with logical page ordering
• Added Mintlify skill for consistent docs development