@quantumclaw/quantumclaw 2026.3.22

package/docs/channels/zalouser.md

@@ -0,0 +1,181 @@
+---
+summary: "Zalo personal account support via native zca-js (QR login), capabilities, and configuration"
+read_when:
+  - Setting up Zalo Personal for QuantumClaw
+  - Debugging Zalo Personal login or message flow
+title: "Zalo Personal"
+---
+
+# Zalo Personal (unofficial)
+
+Status: experimental. This integration automates a **personal Zalo account** via native `zca-js` inside QuantumClaw.
+
+> **Warning:** This is an unofficial integration and may result in account suspension/ban. Use at your own risk.
+
+## Plugin required
+
+Zalo Personal ships as a plugin and is not bundled with the core install.
+
+- Install via CLI: `quantumclaw plugins install @quantumclaw/zalouser`
+- Or from a source checkout: `quantumclaw plugins install ./extensions/zalouser`
+- Details: [Plugins](/tools/plugin)
+
+No external `zca`/`openzca` CLI binary is required.
+
+## Quick setup (beginner)
+
+1. Install the plugin (see above).
+2. Login (QR, on the Gateway machine):
+   - `quantumclaw channels login --channel zalouser`
+   - Scan the QR code with the Zalo mobile app.
+3. Enable the channel:
+
+```json5
+{
+  channels: {
+    zalouser: {
+      enabled: true,
+      dmPolicy: "pairing",
+    },
+  },
+}
+```
+
+4. Restart the Gateway (or finish setup).
+5. DM access defaults to pairing; approve the pairing code on first contact.
+
+## What it is
+
+- Runs entirely in-process via `zca-js`.
+- Uses native event listeners to receive inbound messages.
+- Sends replies directly through the JS API (text/media/link).
+- Designed for “personal account” use cases where Zalo Bot API is not available.
+
+## Naming
+
+Channel id is `zalouser` to make it explicit this automates a **personal Zalo user account** (unofficial). We keep `zalo` reserved for a potential future official Zalo API integration.
+
+## Finding IDs (directory)
+
+Use the directory CLI to discover peers/groups and their IDs:
+
+```bash
+quantumclaw directory self --channel zalouser
+quantumclaw directory peers list --channel zalouser --query "name"
+quantumclaw directory groups list --channel zalouser --query "work"
+```
+
+## Limits
+
+- Outbound text is chunked to ~2000 characters (Zalo client limits).
+- Streaming is blocked by default.
+
+## Access control (DMs)
+
+`channels.zalouser.dmPolicy` supports: `pairing | allowlist | open | disabled` (default: `pairing`).
+
+`channels.zalouser.allowFrom` accepts user IDs or names. During setup, names are resolved to IDs using the plugin's in-process contact lookup.
+
+Approve via:
+
+- `quantumclaw pairing list zalouser`
+- `quantumclaw pairing approve zalouser <code>`
+
+## Group access (optional)
+
+- Default: `channels.zalouser.groupPolicy = "open"` (groups allowed). Use `channels.defaults.groupPolicy` to override the default when unset.
+- Restrict to an allowlist with:
+  - `channels.zalouser.groupPolicy = "allowlist"`
+  - `channels.zalouser.groups` (keys should be stable group IDs; names are resolved to IDs on startup when possible)
+  - `channels.zalouser.groupAllowFrom` (controls which senders in allowed groups can trigger the bot)
+- Block all groups: `channels.zalouser.groupPolicy = "disabled"`.
+- The configure wizard can prompt for group allowlists.
+- On startup, QuantumClaw resolves group/user names in allowlists to IDs and logs the mapping.
+- Group allowlist matching is ID-only by default. Unresolved names are ignored for auth unless `channels.zalouser.dangerouslyAllowNameMatching: true` is enabled.
+- `channels.zalouser.dangerouslyAllowNameMatching: true` is a break-glass compatibility mode that re-enables mutable group-name matching.
+- If `groupAllowFrom` is unset, runtime falls back to `allowFrom` for group sender checks.
+- Sender checks apply to both normal group messages and control commands (for example `/new`, `/reset`).
+
+Example:
+
+```json5
+{
+  channels: {
+    zalouser: {
+      groupPolicy: "allowlist",
+      groupAllowFrom: ["1471383327500481391"],
+      groups: {
+        "123456789": { allow: true },
+        "Work Chat": { allow: true },
+      },
+    },
+  },
+}
+```
+
+### Group mention gating
+
+- `channels.zalouser.groups.<group>.requireMention` controls whether group replies require a mention.
+- Resolution order: exact group id/name -> normalized group slug -> `*` -> default (`true`).
+- This applies both to allowlisted groups and open group mode.
+- Authorized control commands (for example `/new`) can bypass mention gating.
+- When a group message is skipped because mention is required, QuantumClaw stores it as pending group history and includes it on the next processed group message.
+- Group history limit defaults to `messages.groupChat.historyLimit` (fallback `50`). You can override per account with `channels.zalouser.historyLimit`.
+
+Example:
+
+```json5
+{
+  channels: {
+    zalouser: {
+      groupPolicy: "allowlist",
+      groups: {
+        "*": { allow: true, requireMention: true },
+        "Work Chat": { allow: true, requireMention: false },
+      },
+    },
+  },
+}
+```
+
+## Multi-account
+
+Accounts map to `zalouser` profiles in QuantumClaw state. Example:
+
+```json5
+{
+  channels: {
+    zalouser: {
+      enabled: true,
+      defaultAccount: "default",
+      accounts: {
+        work: { enabled: true, profile: "work" },
+      },
+    },
+  },
+}
+```
+
+## Typing, reactions, and delivery acknowledgements
+
+- QuantumClaw sends a typing event before dispatching a reply (best-effort).
+- Message reaction action `react` is supported for `zalouser` in channel actions.
+  - Use `remove: true` to remove a specific reaction emoji from a message.
+  - Reaction semantics: [Reactions](/tools/reactions)
+- For inbound messages that include event metadata, QuantumClaw sends delivered + seen acknowledgements (best-effort).
+
+## Troubleshooting
+
+**Login doesn't stick:**
+
+- `quantumclaw channels status --probe`
+- Re-login: `quantumclaw channels logout --channel zalouser && quantumclaw channels login --channel zalouser`
+
+**Allowlist/group name didn't resolve:**
+
+- Use numeric IDs in `allowFrom`/`groupAllowFrom`/`groups`, or exact friend/group names.
+
+**Upgraded from old CLI-based setup:**
+
+- Remove any old external `zca` process assumptions.
+- The channel now runs fully in QuantumClaw without external CLI binaries.

package/docs/ci.md

@@ -0,0 +1,55 @@
+---
+title: CI Pipeline
+summary: "CI job graph, scope gates, and local command equivalents"
+read_when:
+  - You need to understand why a CI job did or did not run
+  - You are debugging failing GitHub Actions checks
+---
+
+# CI Pipeline
+
+The CI runs on every push to `main` and every pull request. It uses smart scoping to skip expensive jobs when only unrelated areas changed.
+
+## Job Overview
+
+| Job               | Purpose                                                 | When it runs                       |
+| ----------------- | ------------------------------------------------------- | ---------------------------------- |
+| `docs-scope`      | Detect docs-only changes                                | Always                             |
+| `changed-scope`   | Detect which areas changed (node/macos/android/windows) | Non-doc changes                    |
+| `check`           | TypeScript types, lint, format                          | Non-docs, node changes             |
+| `check-docs`      | Markdown lint + broken link check                       | Docs changed                       |
+| `secrets`         | Detect leaked secrets                                   | Always                             |
+| `build-artifacts` | Build dist once, share with `release-check`             | Pushes to `main`, node changes     |
+| `release-check`   | Validate npm pack contents                              | Pushes to `main` after build       |
+| `checks`          | Node tests + protocol check on PRs; Bun compat on push  | Non-docs, node changes             |
+| `compat-node22`   | Minimum supported Node runtime compatibility            | Pushes to `main`, node changes     |
+| `checks-windows`  | Windows-specific tests                                  | Non-docs, windows-relevant changes |
+| `macos`           | Swift lint/build/test + TS tests                        | PRs with macos changes             |
+| `android`         | Gradle build + tests                                    | Non-docs, android changes          |
+
+## Fail-Fast Order
+
+Jobs are ordered so cheap checks fail before expensive ones run:
+
+1. `docs-scope` + `changed-scope` + `check` + `secrets` (parallel, cheap gates first)
+2. PRs: `checks` (Linux Node test split into 2 shards), `checks-windows`, `macos`, `android`
+3. Pushes to `main`: `build-artifacts` + `release-check` + Bun compat + `compat-node22`
+
+Scope logic lives in `scripts/ci-changed-scope.mjs` and is covered by unit tests in `src/scripts/ci-changed-scope.test.ts`.
+
+## Runners
+
+| Runner                           | Jobs                                       |
+| -------------------------------- | ------------------------------------------ |
+| `blacksmith-16vcpu-ubuntu-2404`  | Most Linux jobs, including scope detection |
+| `blacksmith-32vcpu-windows-2025` | `checks-windows`                           |
+| `macos-latest`                   | `macos`, `ios`                             |
+
+## Local Equivalents
+
+```bash
+pnpm check          # types + lint + format
+pnpm test           # vitest tests
+pnpm check:docs     # docs format + lint + broken links
+pnpm release:check  # validate npm pack
+```

package/docs/cli/acp.md

@@ -0,0 +1,288 @@
+---
+summary: "Run the ACP bridge for IDE integrations"
+read_when:
+  - Setting up ACP-based IDE integrations
+  - Debugging ACP session routing to the Gateway
+title: "acp"
+---
+
+# acp
+
+Run the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) bridge that talks to an QuantumClaw Gateway.
+
+This command speaks ACP over stdio for IDEs and forwards prompts to the Gateway
+over WebSocket. It keeps ACP sessions mapped to Gateway session keys.
+
+`quantumclaw acp` is a Gateway-backed ACP bridge, not a full ACP-native editor
+runtime. It focuses on session routing, prompt delivery, and basic streaming
+updates.
+
+## Compatibility Matrix
+
+| ACP area                                                              | Status      | Notes                                                                                                                                                                                                                                            |
+| --------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `initialize`, `newSession`, `prompt`, `cancel`                        | Implemented | Core bridge flow over stdio to Gateway chat/send + abort.                                                                                                                                                                                        |
+| `listSessions`, slash commands                                        | Implemented | Session list works against Gateway session state; commands are advertised via `available_commands_update`.                                                                                                                                       |
+| `loadSession`                                                         | Partial     | Rebinds the ACP session to a Gateway session key and replays stored user/assistant text history. Tool/system history is not reconstructed yet.                                                                                                   |
+| Prompt content (`text`, embedded `resource`, images)                  | Partial     | Text/resources are flattened into chat input; images become Gateway attachments.                                                                                                                                                                 |
+| Session modes                                                         | Partial     | `session/set_mode` is supported and the bridge exposes initial Gateway-backed session controls for thought level, tool verbosity, reasoning, usage detail, and elevated actions. Broader ACP-native mode/config surfaces are still out of scope. |
+| Session info and usage updates                                        | Partial     | The bridge emits `session_info_update` and best-effort `usage_update` notifications from cached Gateway session snapshots. Usage is approximate and only sent when Gateway token totals are marked fresh.                                        |
+| Tool streaming                                                        | Partial     | `tool_call` / `tool_call_update` events include raw I/O, text content, and best-effort file locations when Gateway tool args/results expose them. Embedded terminals and richer diff-native output are still not exposed.                        |
+| Per-session MCP servers (`mcpServers`)                                | Unsupported | Bridge mode rejects per-session MCP server requests. Configure MCP on the QuantumClaw gateway or agent instead.                                                                                                                                     |
+| Client filesystem methods (`fs/read_text_file`, `fs/write_text_file`) | Unsupported | The bridge does not call ACP client filesystem methods.                                                                                                                                                                                          |
+| Client terminal methods (`terminal/*`)                                | Unsupported | The bridge does not create ACP client terminals or stream terminal ids through tool calls.                                                                                                                                                       |
+| Session plans / thought streaming                                     | Unsupported | The bridge currently emits output text and tool status, not ACP plan or thought updates.                                                                                                                                                         |
+
+## Known Limitations
+
+- `loadSession` replays stored user and assistant text history, but it does not
+  reconstruct historic tool calls, system notices, or richer ACP-native event
+  types.
+- If multiple ACP clients share the same Gateway session key, event and cancel
+  routing are best-effort rather than strictly isolated per client. Prefer the
+  default isolated `acp:<uuid>` sessions when you need clean editor-local
+  turns.
+- Gateway stop states are translated into ACP stop reasons, but that mapping is
+  less expressive than a fully ACP-native runtime.
+- Initial session controls currently surface a focused subset of Gateway knobs:
+  thought level, tool verbosity, reasoning, usage detail, and elevated
+  actions. Model selection and exec-host controls are not yet exposed as ACP
+  config options.
+- `session_info_update` and `usage_update` are derived from Gateway session
+  snapshots, not live ACP-native runtime accounting. Usage is approximate,
+  carries no cost data, and is only emitted when the Gateway marks total token
+  data as fresh.
+- Tool follow-along data is best-effort. The bridge can surface file paths that
+  appear in known tool args/results, but it does not yet emit ACP terminals or
+  structured file diffs.
+
+## Usage
+
+```bash
+quantumclaw acp
+
+# Remote Gateway
+quantumclaw acp --url wss://gateway-host:18789 --token <token>
+
+# Remote Gateway (token from file)
+quantumclaw acp --url wss://gateway-host:18789 --token-file ~/.quantumclaw/gateway.token
+
+# Attach to an existing session key
+quantumclaw acp --session agent:main:main
+
+# Attach by label (must already exist)
+quantumclaw acp --session-label "support inbox"
+
+# Reset the session key before the first prompt
+quantumclaw acp --session agent:main:main --reset-session
+```
+
+## ACP client (debug)
+
+Use the built-in ACP client to sanity-check the bridge without an IDE.
+It spawns the ACP bridge and lets you type prompts interactively.
+
+```bash
+quantumclaw acp client
+
+# Point the spawned bridge at a remote Gateway
+quantumclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.quantumclaw/gateway.token
+
+# Override the server command (default: quantumclaw)
+quantumclaw acp client --server "node" --server-args quantumclaw.mjs acp --url ws://127.0.0.1:19001
+```
+
+Permission model (client debug mode):
+
+- Auto-approval is allowlist-based and only applies to trusted core tool IDs.
+- `read` auto-approval is scoped to the current working directory (`--cwd` when set).
+- Unknown/non-core tool names, out-of-scope reads, and dangerous tools always require explicit prompt approval.
+- Server-provided `toolCall.kind` is treated as untrusted metadata (not an authorization source).
+
+## How to use this
+
+Use ACP when an IDE (or other client) speaks Agent Client Protocol and you want
+it to drive an QuantumClaw Gateway session.
+
+1. Ensure the Gateway is running (local or remote).
+2. Configure the Gateway target (config or flags).
+3. Point your IDE to run `quantumclaw acp` over stdio.
+
+Example config (persisted):
+
+```bash
+quantumclaw config set gateway.remote.url wss://gateway-host:18789
+quantumclaw config set gateway.remote.token <token>
+```
+
+Example direct run (no config write):
+
+```bash
+quantumclaw acp --url wss://gateway-host:18789 --token <token>
+# preferred for local process safety
+quantumclaw acp --url wss://gateway-host:18789 --token-file ~/.quantumclaw/gateway.token
+```
+
+## Selecting agents
+
+ACP does not pick agents directly. It routes by the Gateway session key.
+
+Use agent-scoped session keys to target a specific agent:
+
+```bash
+quantumclaw acp --session agent:main:main
+quantumclaw acp --session agent:design:main
+quantumclaw acp --session agent:qa:bug-123
+```
+
+Each ACP session maps to a single Gateway session key. One agent can have many
+sessions; ACP defaults to an isolated `acp:<uuid>` session unless you override
+the key or label.
+
+Per-session `mcpServers` are not supported in bridge mode. If an ACP client
+sends them during `newSession` or `loadSession`, the bridge returns a clear
+error instead of silently ignoring them.
+
+## Use from `acpx` (Codex, Claude, other ACP clients)
+
+If you want a coding agent such as Codex or Claude Code to talk to your
+QuantumClaw bot over ACP, use `acpx` with its built-in `quantumclaw` target.
+
+Typical flow:
+
+1. Run the Gateway and make sure the ACP bridge can reach it.
+2. Point `acpx quantumclaw` at `quantumclaw acp`.
+3. Target the QuantumClaw session key you want the coding agent to use.
+
+Examples:
+
+```bash
+# One-shot request into your default QuantumClaw ACP session
+acpx quantumclaw exec "Summarize the active QuantumClaw session state."
+
+# Persistent named session for follow-up turns
+acpx quantumclaw sessions ensure --name codex-bridge
+acpx quantumclaw -s codex-bridge --cwd /path/to/repo \
+  "Ask my QuantumClaw work agent for recent context relevant to this repo."
+```
+
+If you want `acpx quantumclaw` to target a specific Gateway and session key every
+time, override the `quantumclaw` agent command in `~/.acpx/config.json`:
+
+```json
+{
+  "agents": {
+    "quantumclaw": {
+      "command": "env QUANTUMCLAW_HIDE_BANNER=1 QUANTUMCLAW_SUPPRESS_NOTES=1 quantumclaw acp --url ws://127.0.0.1:18789 --token-file ~/.quantumclaw/gateway.token --session agent:main:main"
+    }
+  }
+}
+```
+
+For a repo-local QuantumClaw checkout, use the direct CLI entrypoint instead of the
+dev runner so the ACP stream stays clean. For example:
+
+```bash
+env QUANTUMCLAW_HIDE_BANNER=1 QUANTUMCLAW_SUPPRESS_NOTES=1 node quantumclaw.mjs acp ...
+```
+
+This is the easiest way to let Codex, Claude Code, or another ACP-aware client
+pull contextual information from an QuantumClaw agent without scraping a terminal.
+
+## Zed editor setup
+
+Add a custom ACP agent in `~/.config/zed/settings.json` (or use Zed’s Settings UI):
+
+```json
+{
+  "agent_servers": {
+    "QuantumClaw ACP": {
+      "type": "custom",
+      "command": "quantumclaw",
+      "args": ["acp"],
+      "env": {}
+    }
+  }
+}
+```
+
+To target a specific Gateway or agent:
+
+```json
+{
+  "agent_servers": {
+    "QuantumClaw ACP": {
+      "type": "custom",
+      "command": "quantumclaw",
+      "args": [
+        "acp",
+        "--url",
+        "wss://gateway-host:18789",
+        "--token",
+        "<token>",
+        "--session",
+        "agent:design:main"
+      ],
+      "env": {}
+    }
+  }
+}
+```
+
+In Zed, open the Agent panel and select “QuantumClaw ACP” to start a thread.
+
+## Session mapping
+
+By default, ACP sessions get an isolated Gateway session key with an `acp:` prefix.
+To reuse a known session, pass a session key or label:
+
+- `--session <key>`: use a specific Gateway session key.
+- `--session-label <label>`: resolve an existing session by label.
+- `--reset-session`: mint a fresh session id for that key (same key, new transcript).
+
+If your ACP client supports metadata, you can override per session:
+
+```json
+{
+  "_meta": {
+    "sessionKey": "agent:main:main",
+    "sessionLabel": "support inbox",
+    "resetSession": true
+  }
+}
+```
+
+Learn more about session keys at [/concepts/session](/concepts/session).
+
+## Options
+
+- `--url <url>`: Gateway WebSocket URL (defaults to gateway.remote.url when configured).
+- `--token <token>`: Gateway auth token.
+- `--token-file <path>`: read Gateway auth token from file.
+- `--password <password>`: Gateway auth password.
+- `--password-file <path>`: read Gateway auth password from file.
+- `--session <key>`: default session key.
+- `--session-label <label>`: default session label to resolve.
+- `--require-existing`: fail if the session key/label does not exist.
+- `--reset-session`: reset the session key before first use.
+- `--no-prefix-cwd`: do not prefix prompts with the working directory.
+- `--verbose, -v`: verbose logging to stderr.
+
+Security note:
+
+- `--token` and `--password` can be visible in local process listings on some systems.
+- Prefer `--token-file`/`--password-file` or environment variables (`QUANTUMCLAW_GATEWAY_TOKEN`, `QUANTUMCLAW_GATEWAY_PASSWORD`).
+- Gateway auth resolution follows the shared contract used by other Gateway clients:
+  - local mode: env (`QUANTUMCLAW_GATEWAY_*`) -> `gateway.auth.*` -> `gateway.remote.*` fallback only when `gateway.auth.*` is unset (configured-but-unresolved local SecretRefs fail closed)
+  - remote mode: `gateway.remote.*` with env/config fallback per remote precedence rules
+  - `--url` is override-safe and does not reuse implicit config/env credentials; pass explicit `--token`/`--password` (or file variants)
+- ACP runtime backend child processes receive `QUANTUMCLAW_SHELL=acp`, which can be used for context-specific shell/profile rules.
+- `quantumclaw acp client` sets `QUANTUMCLAW_SHELL=acp-client` on the spawned bridge process.
+
+### `acp client` options
+
+- `--cwd <dir>`: working directory for the ACP session.
+- `--server <command>`: ACP server command (default: `quantumclaw`).
+- `--server-args <args...>`: extra arguments passed to the ACP server.
+- `--server-verbose`: enable verbose logging on the ACP server.
+- `--verbose, -v`: verbose client logging.

package/docs/cli/agent.md

@@ -0,0 +1,29 @@
+---
+summary: "CLI reference for `quantumclaw agent` (send one agent turn via the Gateway)"
+read_when:
+  - You want to run one agent turn from scripts (optionally deliver reply)
+title: "agent"
+---
+
+# `quantumclaw agent`
+
+Run an agent turn via the Gateway (use `--local` for embedded).
+Use `--agent <id>` to target a configured agent directly.
+
+Related:
+
+- Agent send tool: [Agent send](/tools/agent-send)
+
+## Examples
+
+```bash
+quantumclaw agent --to +15555550123 --message "status update" --deliver
+quantumclaw agent --agent ops --message "Summarize logs"
+quantumclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium
+quantumclaw agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"
+```
+
+## Notes
+
+- When this command triggers `models.json` regeneration, SecretRef-managed provider credentials are persisted as non-secret markers (for example env var names, `secretref-env:ENV_VAR_NAME`, or `secretref-managed`), not resolved secret plaintext.
+- Marker writes are source-authoritative: QuantumClaw persists markers from the active source config snapshot, not from resolved runtime secret values.

package/docs/cli/agents.md

@@ -0,0 +1,123 @@
+---
+summary: "CLI reference for `quantumclaw agents` (list/add/delete/bindings/bind/unbind/set identity)"
+read_when:
+  - You want multiple isolated agents (workspaces + routing + auth)
+title: "agents"
+---
+
+# `quantumclaw agents`
+
+Manage isolated agents (workspaces + auth + routing).
+
+Related:
+
+- Multi-agent routing: [Multi-Agent Routing](/concepts/multi-agent)
+- Agent workspace: [Agent workspace](/concepts/agent-workspace)
+
+## Examples
+
+```bash
+quantumclaw agents list
+quantumclaw agents add work --workspace ~/.quantumclaw/workspace-work
+quantumclaw agents bindings
+quantumclaw agents bind --agent work --bind telegram:ops
+quantumclaw agents unbind --agent work --bind telegram:ops
+quantumclaw agents set-identity --workspace ~/.quantumclaw/workspace --from-identity
+quantumclaw agents set-identity --agent main --avatar avatars/quantumclaw.png
+quantumclaw agents delete work
+```
+
+## Routing bindings
+
+Use routing bindings to pin inbound channel traffic to a specific agent.
+
+List bindings:
+
+```bash
+quantumclaw agents bindings
+quantumclaw agents bindings --agent work
+quantumclaw agents bindings --json
+```
+
+Add bindings:
+
+```bash
+quantumclaw agents bind --agent work --bind telegram:ops --bind discord:guild-a
+```
+
+If you omit `accountId` (`--bind <channel>`), QuantumClaw resolves it from channel defaults and plugin setup hooks when available.
+
+### Binding scope behavior
+
+- A binding without `accountId` matches the channel default account only.
+- `accountId: "*"` is the channel-wide fallback (all accounts) and is less specific than an explicit account binding.
+- If the same agent already has a matching channel binding without `accountId`, and you later bind with an explicit or resolved `accountId`, QuantumClaw upgrades that existing binding in place instead of adding a duplicate.
+
+Example:
+
+```bash
+# initial channel-only binding
+quantumclaw agents bind --agent work --bind telegram
+
+# later upgrade to account-scoped binding
+quantumclaw agents bind --agent work --bind telegram:ops
+```
+
+After the upgrade, routing for that binding is scoped to `telegram:ops`. If you also want default-account routing, add it explicitly (for example `--bind telegram:default`).
+
+Remove bindings:
+
+```bash
+quantumclaw agents unbind --agent work --bind telegram:ops
+quantumclaw agents unbind --agent work --all
+```
+
+## Identity files
+
+Each agent workspace can include an `IDENTITY.md` at the workspace root:
+
+- Example path: `~/.quantumclaw/workspace/IDENTITY.md`
+- `set-identity --from-identity` reads from the workspace root (or an explicit `--identity-file`)
+
+Avatar paths resolve relative to the workspace root.
+
+## Set identity
+
+`set-identity` writes fields into `agents.list[].identity`:
+
+- `name`
+- `theme`
+- `emoji`
+- `avatar` (workspace-relative path, http(s) URL, or data URI)
+
+Load from `IDENTITY.md`:
+
+```bash
+quantumclaw agents set-identity --workspace ~/.quantumclaw/workspace --from-identity
+```
+
+Override fields explicitly:
+
+```bash
+quantumclaw agents set-identity --agent main --name "QuantumClaw" --emoji "🦞" --avatar avatars/quantumclaw.png
+```
+
+Config sample:
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "main",
+        identity: {
+          name: "QuantumClaw",
+          theme: "space lobster",
+          emoji: "🦞",
+          avatar: "avatars/quantumclaw.png",
+        },
+      },
+    ],
+  },
+}
+```