diff --git a/CLAUDE.md b/CLAUDE.md index 92824fb..e941490 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -81,6 +81,32 @@ For ad-hoc queries from skills or scripts, use the in-tree wrapper rather than t | `scripts/init-first-agent.ts` | Bootstrap the first DM-wired agent (used by `/init-first-agent` skill) | | `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). | +## Admin CLI (`ncl`) + +`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`). + +``` +ncl [] [--flags] +ncl help +ncl help +``` + +| 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/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 (`:`) | +| 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) | + +Key files: `src/cli/dispatch.ts` (dispatcher + approval handler), `src/cli/crud.ts` (generic CRUD registration), `src/cli/resources/` (per-resource definitions). + ## Channels and Providers (skill-installed) 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: diff --git a/container/agent-runner/src/mcp-tools/cli.instructions.md b/container/agent-runner/src/mcp-tools/cli.instructions.md index 5bec167..f9965f5 100644 --- a/container/agent-runner/src/mcp-tools/cli.instructions.md +++ b/container/agent-runner/src/mcp-tools/cli.instructions.md @@ -1,13 +1,13 @@ -## Admin CLI (`nc`) +## Admin CLI (`ncl`) -The `nc` command is available at `/usr/local/bin/nc`. It lets you query and modify NanoClaw's central configuration — agent groups, messaging groups, wirings, users, roles, and more. +The `ncl` command is available at `/usr/local/bin/ncl`. It lets you query and modify NanoClaw's central configuration — agent groups, messaging groups, wirings, users, roles, and more. ### Usage ``` -nc [] [--flags] -nc help -nc help +ncl [] [--flags] +ncl help +ncl help ``` ### Resources @@ -28,33 +28,50 @@ nc help ### When to use -- **Looking up your own config** — `nc groups get ` to see your agent group settings. -- **Finding who you're wired to** — `nc wirings list` to see which messaging groups route to which agent groups. -- **Checking user roles** — `nc roles list` to see who is an owner/admin. -- **Answering questions about the system** — when the user asks about groups, channels, users, or configuration, query `nc` rather than guessing. +- **Looking up your own config** — `ncl groups get ` to see your agent group settings. +- **Finding who you're wired to** — `ncl wirings list` to see which messaging groups route to which agent groups. +- **Checking user roles** — `ncl roles list` to see who is an owner/admin. +- **Answering questions about the system** — when the user asks about groups, channels, users, or configuration, query `ncl` rather than guessing. ### Access rules Read commands (list, get) are open. Write commands (create, update, delete, grant, revoke, add, remove) require admin approval — the request is held until an admin approves it. +### Approval flow + +Write commands (create, update, delete, grant, revoke, add, remove) require admin approval. Here's what happens: + +1. You run the command (e.g. `ncl groups create --name "Research" --folder research`). +2. The command returns immediately with an `approval-pending` response — it has **not** been executed yet. +3. An admin or owner gets a notification (on the same channel when possible) showing exactly what you requested, with approve/reject options. +4. Once the admin responds: + - **Approved:** the command executes and the result is delivered back to you as a system message in this conversation. + - **Rejected:** you get a system message saying the request was rejected. + +You don't need to poll or retry — the result arrives automatically. + ### Examples ```bash -# List all agent groups -nc groups list +# Read commands (no approval needed) +ncl groups list +ncl groups get abc123 +ncl wirings list --messaging-group-id mg_xyz +ncl roles list +ncl wirings help -# Get details for a specific group -nc groups get abc123 - -# See field definitions for a resource -nc wirings help - -# List all wirings for a specific messaging group -nc wirings list --messaging-group-id mg_xyz +# Write commands (approval required) +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 ``` ### Tips -- Use `nc help` to see all available fields, types, enums, and which fields are required or updatable. +- Use `ncl help` to see all available fields, types, enums, and which fields are required or updatable. - Flags use `--hyphen-case` (e.g. `--agent-group-id`), mapped to `underscore_case` DB columns automatically. - For composite-key resources (roles, members, destinations), use the custom verbs (grant/revoke, add/remove) instead of create/delete. +- Write commands return `approval-pending` immediately — don't treat this as an error. Wait for the system message with the result.