Document ncl admin CLI for v2.0.45

api/group-management.mdx

@@ -1,11 +1,15 @@
 ---
 title: Group management
 description: API reference for agent groups, messaging groups, wirings, and the v2 entity model
 tag: "UPDATED"
 ---
 
 In v2, NanoClaw uses a new entity model that separates agent groups (workspaces) from messaging groups (platform chats). These are connected through wirings — many-to-many relationships stored in `messaging_group_agents`.
 
+<Note>
+For day-to-day inspection and modification of these entities, use the [`ncl` admin CLI](/features/admin-cli). It exposes `groups`, `messaging-groups`, `wirings`, `users`, `roles`, `members`, and `destinations` as resources with `list`/`get`/`create`/`update`/`delete` (or composite-key equivalents).
+</Note>
+
 ## Entity model
 
 ### Agent groups
@@ -45,9 +49,9 @@
 - Auto-created on first mention or DM
 - `denied_at` silently drops future mentions
 
 ### Wirings (messaging_group_agents)
 
 Wirings connect messaging groups to agent groups:
 
 ```typescript
 interface MessagingGroupAgent {
@@ -129,8 +133,8 @@
 |-------|---------|
 | `agent_groups` | Agent workspaces |
 | `messaging_groups` | Platform chats/channels |
 | `messaging_group_agents` | Wirings with engage/scope/session config |
 | `users` | Namespaced platform identifiers |
 | `user_roles` | Owner and admin roles |
 | `agent_group_members` | Unprivileged membership |
 | `user_dms` | Cached DM channel mapping |
@@ -162,13 +166,13 @@
 
 ## Channel approval flow
 
 When a message arrives on an unwired channel:
 
 1. Router detects no wirings exist for this messaging group
 2. Channel-request gate sends approval card to the owner
 3. **Approve** — creates wiring with defaults:
    - Groups: `mention-sticky` engage mode
    - DMs: `pattern='.'` (always respond)
    - Triggering sender is auto-admitted as a member
    - Original event is replayed
 4. **Deny** — sets `denied_at` on the messaging group

changelog/docs-updates.mdx

@@ -5,20 +5,30 @@
 rss: true
 ---
 
+<Update label="v2.0.45 sync: ncl admin CLI" description="2026-05-08" tags={["New"]}>
+  Documented the `ncl` admin CLI introduced in upstream v2.0.45.
+
+  ## New
+  - **`features/admin-cli.mdx`**: full reference for `ncl` — resource/verb table, host vs container transports (Unix socket on the host, session DB inside containers), `list` filtering and `--limit`, the approval flow for container-side writes (`approval-pending` → admin card → re-dispatch on approve → system message back to the agent), and example read/write commands.
+  - **`api/group-management.mdx`**: added a callout pointing readers to `ncl` for runtime inspection and modification of agent groups, messaging groups, wirings, users, roles, members, and destinations.
+  - **`changelog/index.mdx`**: v2.0.45 entry covering `ncl`, the approval flow for container-side writes, list filtering and pagination, the `nc` → `ncl` rename, and the v1 → v2 migration script.
+  - **Navigation**: `features/admin-cli` added to the Features group in `docs.json`.
+</Update>
+
 <Update label="v2.0.0 launch readiness: front-door rewrites" description="2026-04-22" tags={["Updated"]}>
   Phase A of the v2 documentation sprint — bringing the pages every new user lands on into alignment with the v2 rewrite. All claims verified directly against upstream source (`src/db/schema.ts`, `src/types.ts`, `src/config.ts`, `container/Dockerfile`, `src/delivery.ts`) rather than upstream `docs/` (which includes a stale `architecture.md` draft and a `db-session.md` that omits the `container_state` table).
 
   ## 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
   Added `<Warning>` banners to pages pending a v2 rewrite (channel adapters moved to a single `channels` branch in v2, not per-channel `skill/*` branches):
   - `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
@@ -26,15 +36,15 @@
 </Update>
 
 <Update label="v2.0.0: architectural rewrite docs" description="2026-04-22" tags={["Updated"]}>
   Merged PR #187 — comprehensive rewrite of concepts, advanced, api, and features pages for the v2.0.0 ground-up architectural rewrite ([qwibitai/nanoclaw#1919](https://github.com/qwibitai/nanoclaw/pull/1919)). Closed PRs #184, #185, #186 as superseded.
 
   ## 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
 
@@ -59,14 +69,14 @@
   - **Architecture**: Documented auto-compact threshold at 165k tokens
 </Update>
 
 <Update label="v1.2.46–v1.2.47 sync: store mount, reply context, requiresTrigger" description="2026-04-04" tags={["Updated"]}>
   Triaged 3 automated Mintlify PRs (#175–#177). Merged #177 (most comprehensive), closed #175 and #176 (superseded). Cherry-picked unique content from closed PRs.
 
   ## 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
@@ -87,11 +97,11 @@
 </Update>
 
 <Update label="PR triage: v1.2.43–v1.2.46 sync" description="2026-04-02" tags={["Updated"]}>
   Reviewed and triaged 8 automated Mintlify PRs (#161–#168). Merged 4, closed 4 (superseded or stale token counts). Validated all changes against upstream source code at v1.2.46. Deleted 11 stale branches (4 PR + 7 orphan).
 
   ## 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
@@ -104,23 +114,23 @@
   Merged automated health check PR #158 (4 of 5 fixes verified against upstream). Corrected the remaining inaccurate claim in a follow-up (#159).
 
   ## 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.
 </Update>
 
 <Update label="Automated PR triage: v1.2.35–v1.2.42 sync" description="2026-03-28" tags={["Updated", "Fixed"]}>
   Reviewed and triaged 27 automated Mintlify PRs (#92–#151). Merged 6, consolidated 7 into a single verified PR (#153), closed 15 (superseded, fabricated, or conflicting). Validated all changes against upstream source code at v1.2.42. Deleted 41 stale `mintlify/*` branches.
 
   ## 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
@@ -130,9 +140,9 @@
   - **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)
 
@@ -143,7 +153,7 @@
 </Update>
 
 <Update label="Automated PR triage: v1.2.24–v1.2.34 sync" description="2026-03-26" tags={["New", "Updated", "Fixed"]}>
   Reviewed and triaged 43 automated Mintlify PRs (#86–#128). Merged 8, closed 30 (superseded or inaccurate), kept 5 pending v1.2.35 release. Validated all changes against upstream source code at v1.2.34.
 
   ## New sections
   - **Task scripts** (`concepts/tasks`, `features/scheduled-tasks`, `api/task-scheduling`) — pre-execution bash scripts with `wakeAgent` JSON contract, `ScriptResult` type, execution flow
@@ -151,7 +161,7 @@
   - **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
@@ -192,8 +202,8 @@
   - **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
 </Update>
 
@@ -215,7 +225,7 @@
 </Update>
 
 <Update label="PR consolidation and issue cleanup" description="2026-03-23" tags={["New", "Updated", "Fixed"]}>
   Reviewed, triaged, and consolidated 10 automated Mintlify PRs (#60–#69). Verified all changes against NanoClaw source code, excluded 6 incorrect changes, and resolved the final 2 open issues.
 
   ## New pages
   - **Claw CLI** (`features/cli`) — documents the `/claw` Python CLI for running agents from the command line (#64)
@@ -223,7 +233,7 @@
   ## 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)
 
@@ -235,12 +245,12 @@
   - **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
@@ -252,21 +262,21 @@
   Ran a full docs-gap analysis against the upstream codebase and resolved 13 of 15 content-gap issues. Two low-priority items remain open (#49, #50).
 
   ## 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
@@ -292,7 +302,7 @@
 
 <Update label="Source sync and remote control" description="2026-03-19" tags={["Updated"]}>
   - Fixed remote-control commands documentation
   - Deduplicated IPC docs
   - Added `update_task` to auth tables in API reference
 </Update>
 
@@ -308,12 +318,12 @@
 
 <Update label="v1.2.17 source sync" description="2026-03-18" tags={["New", "Updated"]}>
   - 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
 </Update>
 
 <Update label="Credential proxy and task lifecycle" description="2026-03-16" tags={["Fixed"]}>
   Fixed stale documentation for credential proxy, database path, mount allowlist, and task lifecycle to match current source code.
 </Update>
 
 <Update label="Automation workflows" description="2026-03-16" tags={["New"]}>
@@ -324,7 +334,7 @@
 <Update label="Portal branding and UX" description="2026-03-16" tags={["Updated"]}>
   - 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
 </Update>
 
 <Update label="Portal launch" description="2026-03-15" tags={["New"]}>

changelog/index.mdx

@@ -6,13 +6,22 @@
 tag: "UPDATED"
 ---
 
+<Update label="v2.0.45" description="2026-05-08" tags={["Feature"]}>
+  - **Admin CLI (`ncl`).** New command for querying and modifying NanoClaw's central DB — agent groups, messaging groups, wirings, users, roles, members, destinations, sessions, approvals, and dropped messages. Host transport runs over a Unix socket; container transport runs over the session DB.
+  - **Approval flow for container-side writes.** When an agent inside a container runs an `ncl` write command (`create`/`update`/`delete`/`grant`/`revoke`/`add`/`remove`), the dispatcher sends an approval card to an admin instead of executing inline. On approve, the original frame is re-dispatched on the host and the result is delivered back to the agent as a system message.
+  - **List filtering and pagination.** `ncl <resource> list` accepts column filters as flags (e.g. `--messaging-group-id mg_xyz`) and a `--limit` (default 200). Run `ncl help` for usage. See [Admin CLI](/features/admin-cli).
+  - **`nc` → `ncl` rename.** The CLI binary, socket path, container wrapper, and error prefixes were renamed from `nc` to `ncl`. Setup adds a `~/.local/bin/ncl` symlink and a pnpm script alias.
+  - **v1 → v2 migration.** Run `bash migrate-v2.sh` from a v2 checkout. The script merges `.env`, seeds the v2 DB from `registered_groups`, copies group folders (`CLAUDE.md` → `CLAUDE.local.md`), copies session data with conversation continuity, ports scheduled tasks, interactively installs channels, copies container skills, builds the agent container, and offers a service switchover. Hands off to Claude (`/migrate-from-v1`) for owner seeding, access policy, CLAUDE.md cleanup, and fork customization porting.
+  - **Migration fixes.** `1b-db` resolves Discord DMs as `discord:@me:<id>` (previously skipped any v1 chat that wasn't a guild channel). `1c-groups` skips symlinks instead of following them. When `1b-db` reuses an auto-created `messaging_group` with no wired agents, its `unknown_sender_policy` is reconciled to the migration's `public` default.
+</Update>
+
 <Update label="v2.0.0" description="2026-04-22" tags={["Breaking"]}>
   - Ground-up architectural rewrite with new entity model (users, roles, messaging groups, agent groups, wirings)
   - Two-database session model — `inbound.db` (host writes) and `outbound.db` (container writes) eliminate cross-mount SQLite contention
   - Agent-runner moved from Node.js to Bun — runs TypeScript directly without compilation
   - Shared-source agent-runner — `/app/src` is a read-only bind mount, source changes never require image rebuild
   - `tini` as PID 1 for proper signal forwarding
   - Three-level channel isolation model with `unknown_sender_policy` (strict, request_approval, public)
   - Per-wiring engage modes: `pattern`, `mention`, `mention-sticky`
   - Sender scope enforcement per wiring (`all` or `known`)
   - Channel and sender approval flows with interactive cards
@@ -38,20 +47,20 @@
 
 <Update label="v1.2.51" description="2026-04-05" tags={["Fix"]}>
   - Fixed writable global memory mount for main agent — corrected the path in container `CLAUDE.md`
   - Fixed three issues in the Karpathy wiki skill
   - Updated `init-onecli` skill to use `ONECLI_URL` variable
 </Update>
 
 <Update label="v1.2.50" description="2026-04-05" tags={["Feature", "Skill"]}>
   - Lowered auto-compact threshold to 165k tokens for better context fidelity
   - Added `/add-karpathy-llm-wiki` skill — persistent wiki knowledge base per group, based on Karpathy's LLM Wiki pattern
   - Added `/migrate-nanoclaw` skill — intent-based upgrade that extracts customizations into a migration guide and reapplies them on a clean upstream base
   - Added `/migrate-from-openclaw` skill — guided migration from OpenClaw installations
   - NanoClaw now suggests `/migrate-nanoclaw` when the user's fork is far behind upstream
 </Update>
 
 <Update label="v1.2.49" description="2026-04-04" tags={["Feature"]}>
   - Added automatic session artifact pruning on startup and daily — cleans up stale session JSONLs (7 days), debug logs (3 days), todo files (3 days), and telemetry (7 days) while preserving active sessions
 </Update>
 
 <Update label="v1.2.48" description="2026-04-04" tags={["Feature"]}>
@@ -66,7 +75,7 @@
 <Update label="v1.2.46" description="2026-04-03" tags={["Feature", "Channel"]}>
   - Added reply/quoted message context support — channels can now pass `reply_to_message_id`, `reply_to_message_content`, and `reply_to_sender_name` fields with messages
   - Reply context is rendered as `<quoted_message>` XML in agent prompts, giving agents full awareness of which message a user is responding to
   - Database migration adds reply context columns to the messages table (nullable for backward compatibility)
 </Update>
 
 <Update label="v1.2.45" description="2026-04-02" tags={["Skill", "Maintenance"]}>
@@ -76,7 +85,7 @@
 
 <Update label="v1.2.43" description="2026-03-29" tags={["Fix"]}>
   - Auto-recover from stale Claude Code session IDs instead of retrying infinitely — detects missing session transcripts and clears the broken session for a fresh retry
   - Removed built-in Ollama MCP server from core — Ollama integration is now exclusively available via the `/add-ollama-tool` skill
   - Fixed npm audit dependency errors
 </Update>
 
@@ -86,7 +95,7 @@
 </Update>
 
 <Update label="v1.2.41" description="2026-03-28" tags={["Fix", "Maintenance"]}>
   - Migrated `x-integration` host.ts from pino to built-in logger (follow-up to v1.2.36 cleanup)
   - Fixed `stopContainer()` test compatibility — mocked container-runtime so tests don't require Docker
   - Cleared stale Telegram token from `.env.example`
 </Update>
@@ -96,7 +105,7 @@
 </Update>
 
 <Update label="v1.2.39" description="2026-03-27" tags={["Fix", "Security"]}>
   - Security fixes: command injection prevention in `stopContainer` (name validation), mount path colon rejection, allowlist caching fix (contributed by @foxsky)
 </Update>
 
 <Update label="v1.2.38" description="2026-03-27" tags={["Fix"]}>
@@ -110,7 +119,7 @@
 <Update label="v1.2.36" description="2026-03-27" tags={["Maintenance", "Fix", "Breaking"]}>
   - **[BREAKING]** Replaced `pino` logger with built-in logger module — removes 2 runtime dependencies. WhatsApp users must re-merge the WhatsApp fork to pick up the Baileys logger compatibility fix: `git fetch whatsapp main && git merge whatsapp/main`. If the `whatsapp` remote is not configured: `git remote add whatsapp https://github.com/qwibitai/nanoclaw-whatsapp.git`
   - Removed `yaml` and `zod` dependencies — core runtime now uses only 3 packages
   - Updated Ollama skill with admin model management tools
   - Channel-formatting text-style fixes for WhatsApp and Telegram (contributed by @kenbolton)
 </Update>
 
@@ -133,7 +142,7 @@
 <Update label="v1.2.32" description="2026-03-25" tags={["Feature", "Skill", "Fix"]}>
   - Added `/channel-formatting` skill — channel-aware text formatting for WhatsApp, Telegram, Slack, and Signal
   - Fixed per-group trigger pattern matching — each group can now define its own trigger word (contributed by @mrbob-git)
   - Fixed `loginctl enable-linger` so systemd user service survives SSH logout (contributed by @IYENTeam)
   - Clarified WhatsApp phone number prompt to prevent auth failures (contributed by @ingyukoh)
   - Added Telegram forum topics contributor (contributed by @flobo3)
 </Update>
@@ -162,7 +171,7 @@
 </Update>
 
 <Update label="v1.2.26" description="2026-03-25" tags={["Fix"]}>
   - Enabled `loginctl linger` during setup so systemd user service survives SSH logout
   - Clarified WhatsApp phone number prompt format (digits only, no `+` prefix)
   - Added CLAUDE.md template copy during IPC group registration
 </Update>
@@ -181,7 +190,7 @@
   - Added `/use-native-credential-proxy` skill — opt-in restoration of the built-in `.env`-based credential proxy for users who prefer it over OneCLI
   - Removed dead `src/credential-proxy.ts` code (unused since v1.2.22)
   - Updated token count to 39.8k tokens (20% of context window)
   - Upgraded Zod dependency from v3 to v4 (`^4.3.6`)
 </Update>
 
 <Update label="v1.2.22" description="2026-03-24" tags={["Maintenance"]}>
@@ -229,7 +238,7 @@
 </Update>
 
 <Update label="v1.2.13" description="2026-03-14" tags={["Feature", "Breaking"]}>
   Major architecture change: skills are now git branches, channels are separate fork repos.
 
   ## Features
   - Skills live as `skill/*` git branches merged via `git merge` — no more marketplace or plugin system
@@ -299,7 +308,7 @@
 </Update>
 
 <Update label="v1.2.3" description="2026-03-04" tags={["Feature", "Security"]}>
   - Added sender allowlist for per-chat access control to restrict who can interact with the agent
 </Update>
 
 <Update label="v1.2.2" description="2026-03-04" tags={["Feature", "Fix"]}>
@@ -316,13 +325,13 @@
 </Update>
 
 <Update label="v1.2.0" description="2026-03-02" tags={["Feature", "Breaking", "Channel"]}>
   Major release introducing multi-channel architecture. WhatsApp is no longer hardcoded — all channels self-register via a channel registry.
 
   ## Features
   - **Channel registry**: Channels self-register at module load time via `registerChannel()` factory pattern
   - **`isMain` flag**: Explicit boolean replaces folder-name-based main group detection
   - **Channel-prefixed group folders**: Groups use `whatsapp_main`, `telegram_family-chat` convention to prevent cross-channel collisions
   - Unconfigured channels now emit WARN logs naming the exact missing variable
 
   ## Breaking
   - **WhatsApp moved to skill**: No longer part of core — apply with `/add-whatsapp`
@@ -363,7 +372,7 @@
 
   ## Fixes
   - Fixed WhatsApp QR data handling
   - Rebased core skills (Telegram, Discord, voice) to latest main
 </Update>
 
 <Update label="v1.1.2" description="2026-02-24" tags={["Fix"]}>
@@ -372,7 +381,7 @@
 
 <Update label="v1.1.1" description="2026-02-24" tags={["Feature", "Fix"]}>
   ## Features
   - Added official Qodo skills and codebase intelligence
   - Rewrote README for broader audience
 
   ## Fixes

docs.json

@@ -116,6 +116,7 @@
               "features/agent-swarms",
               "features/customization",
               "features/cli",
+              "features/admin-cli",
               "features/web-access",
               "features/voice-transcription",
               "features/image-vision",

features/admin-cli.mdx

@@ -0,0 +1,114 @@
+---
+title: Admin CLI (ncl)
+description: Query and modify NanoClaw's central configuration — agent groups, messaging groups, wirings, users, roles, members, and more — from the host or from inside an agent container
+keywords: ["ncl", "admin cli", "central db", "configuration", "approvals", "wirings", "roles"]
+tag: "NEW"
+---
+
+## Overview
+
+`ncl` is the admin CLI for NanoClaw. It reads and writes the central database — the single source of truth for agent groups, messaging groups, wirings, users, roles, members, destinations, sessions, approvals, and dropped messages.
+
+It runs in two places with the same surface:
+
+- **On the host**, talking to the running NanoClaw process over a Unix socket.
+- **Inside an agent container**, talking to the host through the session DB transport — so an agent can introspect or request changes without leaving its sandbox.
+
+The binary is `ncl` (renamed from `nc` in v2.0.45). On the host, setup symlinks it into `~/.local/bin`; inside containers it lives at `/usr/local/bin/ncl`.
+
+## Usage
+
+```
+ncl <resource> <verb> [<id>] [--flags]
+ncl <resource> help
+ncl help
+```
+
+- Flags use `--hyphen-case` (e.g. `--agent-group-id`); they are mapped to `underscore_case` columns automatically.
+- `list` accepts column filters (any non-auto column) and a `--limit` (default 200).
+- `<resource> help` prints all available fields, types, enums, and which fields are required or updatable.
+
+## Resources
+
+| Resource | Verbs | What it is |
+|----------|-------|------------|
+| `groups` | `list`, `get`, `create`, `update`, `delete` | Agent groups (workspace, personality, container config) |
+| `messaging-groups` | `list`, `get`, `create`, `update`, `delete` | A single chat or channel on one platform |
+| `wirings` | `list`, `get`, `create`, `update`, `delete` | Links a messaging group to an agent group (session mode, triggers) |
+| `users` | `list`, `get`, `create`, `update` | Platform identities (`<channel>:<handle>`) |
+| `roles` | `list`, `grant`, `revoke` | Owner / admin privileges (global or scoped to an agent group) |
+| `members` | `list`, `add`, `remove` | Unprivileged access gate for an agent group |
+| `destinations` | `list`, `add`, `remove` | Where an agent group can send messages |
+| `sessions` | `list`, `get` | Active sessions (read-only) |
+| `user-dms` | `list` | Cold-DM cache (read-only) |
+| `dropped-messages` | `list` | Messages from unregistered senders (read-only) |
+| `approvals` | `list`, `get` | Pending approval requests (read-only) |
+
+For composite-key resources (`roles`, `members`, `destinations`), use the custom verbs (`grant`/`revoke`, `add`/`remove`) instead of `create`/`delete`.
+
+## Access model
+
+- **Read commands** (`list`, `get`) are open from any caller.
+- **Write commands** (`create`, `update`, `delete`, `grant`, `revoke`, `add`, `remove`) run inline when invoked from the host. When invoked from inside a container, they go through the [approval flow](#approval-flow).
+
+## Approval flow
+
+When an agent inside a container runs a write command, the dispatcher does **not** execute it inline. Instead, it requests approval from an admin and notifies the agent when the result is ready.
+
+<Steps>
+  <Step title="Agent runs a write command">
+    For example: `ncl groups create --name "Research" --folder research`.
+  </Step>
+  <Step title="Dispatcher returns approval-pending">
+    The command returns immediately with `approval-pending`. It has **not** been executed yet.
+  </Step>
+  <Step title="Admin gets an approval card">
+    An admin or owner receives a notification (on the same channel when possible) showing exactly what the agent requested, with approve/reject options. Approvers are resolved from the `user_roles` table — preference order: scoped admins for the agent group, then global admins, then owners.
+  </Step>
+  <Step title="Result delivered as a system message">
+    On approve, the original frame is re-dispatched on the host (`caller: 'host'`) and the result is delivered back to the agent as a system message. On reject, the agent is told the request was rejected.
+  </Step>
+</Steps>
+
+The agent doesn't need to poll or retry — the result arrives automatically.
+
+<Note>
+`approval-pending` is not an error. Agents should treat it as the normal acknowledgement for any write command and wait for the system message with the final result.
+</Note>
+
+## Examples
+
+```bash
+# Read commands (no approval needed, work from host or container)
+ncl groups list
+ncl groups get abc123
+ncl wirings list --messaging-group-id mg_xyz
+ncl wirings list --limit 50
+ncl roles list
+ncl wirings help
+```
+
+```bash
+# Write commands (inline on host, approval-gated from container)
+ncl groups create --name "Research" --folder research
+ncl groups update abc123 --name "Research v2"
+ncl roles grant --user telegram:jane --role admin
+ncl roles grant --user discord:bob --role admin --group abc123
+ncl members add --user-id telegram:jane --agent-group-id abc123
+ncl destinations add --agent-group-id abc123 --messaging-group-id mg_xyz
+```
+
+## Transports
+
+| Caller | Transport | Source |
+|--------|-----------|--------|
+| Host shell | Unix socket | `src/cli/socket-server.ts`, `src/cli/socket-client.ts` |
+| Container agent | Session DB (request frame on outbound, response on inbound) | `container/agent-runner/src/cli/ncl.ts` |
+
+Both transports call the same dispatcher (`src/cli/dispatch.ts`); only the `CallerContext` differs. Generic CRUD is registered through `src/cli/crud.ts`, with per-resource definitions in `src/cli/resources/`.
+
+## Related
+
+- [Group management API](/api/group-management) — entity model behind the resources `ncl` exposes
+- [Message routing](/api/message-routing) — how wirings tie messaging groups to agent groups
+- [Security model](/advanced/security-model) — approval routing and role resolution