vilvona 1.0.0

package/docs/concepts/agent-workspace.md

@@ -0,0 +1,230 @@
+---
+summary: "Agent workspace: location, layout, and backup strategy"
+read_when:
+  - You need to explain the agent workspace or its file layout
+  - You want to back up or migrate an agent workspace
+title: "Agent workspace"
+sidebarTitle: "Agent workspace"
+---
+
+The workspace is the agent's home. It is the only working directory used for file tools and for workspace context. Keep it private and treat it as memory.
+
+This is separate from `~/.openclaw/`, which stores config, credentials, and sessions.
+
+<Warning>
+The workspace is the **default cwd**, not a hard sandbox. Tools resolve relative paths against the workspace, but absolute paths can still reach elsewhere on the host unless sandboxing is enabled. If you need isolation, use [`agents.defaults.sandbox`](/gateway/sandboxing) (and/or per-agent sandbox config).
+
+When sandboxing is enabled and `workspaceAccess` is not `"rw"`, tools operate inside a sandbox workspace under `~/.openclaw/sandboxes`, not your host workspace.
+</Warning>
+
+## Default location
+
+- Default: `~/.openclaw/workspace`
+- If `OPENCLAW_PROFILE` is set and not `"default"`, the default becomes `~/.openclaw/workspace-<profile>`.
+- Override in `~/.openclaw/openclaw.json`:
+
+```json5
+{
+  agents: {
+    defaults: {
+      workspace: "~/.openclaw/workspace",
+    },
+  },
+}
+```
+
+`openclaw onboard`, `openclaw configure`, or `openclaw setup` will create the workspace and seed the bootstrap files if they are missing.
+
+<Note>
+Sandbox seed copies only accept regular in-workspace files; symlink/hardlink aliases that resolve outside the source workspace are ignored.
+</Note>
+
+If you already manage the workspace files yourself, you can disable bootstrap file creation:
+
+```json5
+{ agents: { defaults: { skipBootstrap: true } } }
+```
+
+## Extra workspace folders
+
+Older installs may have created `~/openclaw`. Keeping multiple workspace directories around can cause confusing auth or state drift, because only one workspace is active at a time.
+
+<Note>
+**Recommendation:** keep a single active workspace. If you no longer use the extra folders, archive or move them to Trash (for example `trash ~/openclaw`). If you intentionally keep multiple workspaces, make sure `agents.defaults.workspace` points to the active one.
+
+`openclaw doctor` warns when it detects extra workspace directories.
+</Note>
+
+## Workspace file map
+
+These are the standard files OpenClaw expects inside the workspace:
+
+<AccordionGroup>
+  <Accordion title="AGENTS.md - operating instructions">
+    Operating instructions for the agent and how it should use memory. Loaded at the start of every session. Good place for rules, priorities, and "how to behave" details.
+  </Accordion>
+  <Accordion title="SOUL.md - persona and tone">
+    Persona, tone, and boundaries. Loaded every session. Guide: [SOUL.md personality guide](/concepts/soul).
+  </Accordion>
+  <Accordion title="USER.md - who the user is">
+    Who the user is and how to address them. Loaded every session.
+  </Accordion>
+  <Accordion title="IDENTITY.md - name, vibe, emoji">
+    The agent's name, vibe, and emoji. Created/updated during the bootstrap ritual.
+  </Accordion>
+  <Accordion title="TOOLS.md - local tool conventions">
+    Notes about your local tools and conventions. Does not control tool availability; it is only guidance.
+  </Accordion>
+  <Accordion title="HEARTBEAT.md - heartbeat checklist">
+    Optional tiny checklist for heartbeat runs. Keep it short to avoid token burn.
+  </Accordion>
+  <Accordion title="BOOT.md - startup checklist">
+    Optional startup checklist run automatically on gateway restart (when [internal hooks](/automation/hooks) are enabled). Keep it short; use the message tool for outbound sends.
+  </Accordion>
+  <Accordion title="BOOTSTRAP.md - first-run ritual">
+    One-time first-run ritual. Only created for a brand-new workspace. Delete it after the ritual is complete.
+  </Accordion>
+  <Accordion title="memory/YYYY-MM-DD.md - daily memory log">
+    Daily memory log (one file per day). Recommended to read today + yesterday on session start.
+  </Accordion>
+  <Accordion title="MEMORY.md - curated long-term memory (optional)">
+    Curated long-term memory: durable facts, preferences, decisions, and short summaries. Keep detailed logs in `memory/YYYY-MM-DD.md` so memory tools can retrieve them on demand without injecting them into every prompt. Only load `MEMORY.md` in the main, private session (not shared/group contexts). See [Memory](/concepts/memory) for the workflow and automatic memory flush.
+  </Accordion>
+  <Accordion title="skills/ - workspace skills (optional)">
+    Workspace-specific skills. Highest-precedence skill location for that workspace. Overrides project agent skills, personal agent skills, managed skills, bundled skills, and `skills.load.extraDirs` when names collide.
+  </Accordion>
+  <Accordion title="canvas/ - Canvas UI files (optional)">
+    Canvas UI files for node displays (for example `canvas/index.html`).
+  </Accordion>
+</AccordionGroup>
+
+<Note>
+If any bootstrap file is missing, OpenClaw injects a "missing file" marker into the session and continues. Large bootstrap files are truncated when injected; adjust limits with `agents.defaults.bootstrapMaxChars` (default: 20000) and `agents.defaults.bootstrapTotalMaxChars` (default: 60000). `openclaw setup` can recreate missing defaults without overwriting existing files.
+</Note>
+
+## What is NOT in the workspace
+
+These live under `~/.openclaw/` and should NOT be committed to the workspace repo:
+
+- `~/.openclaw/openclaw.json` (config)
+- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (model auth profiles: OAuth + API keys)
+- `~/.openclaw/agents/<agentId>/agent/codex-home/` (per-agent Codex runtime account, config, skills, plugins, and native thread state)
+- `~/.openclaw/credentials/` (channel/provider state plus legacy OAuth import data)
+- `~/.openclaw/agents/<agentId>/sessions/` (session transcripts + metadata)
+- `~/.openclaw/skills/` (managed skills)
+
+If you need to migrate sessions or config, copy them separately and keep them out of version control.
+
+## Git backup (recommended, private)
+
+Treat the workspace as private memory. Put it in a **private** git repo so it is backed up and recoverable.
+
+Run these steps on the machine where the Gateway runs (that is where the workspace lives).
+
+<Steps>
+  <Step title="Initialize the repo">
+    If git is installed, brand-new workspaces are initialized automatically. If this workspace is not already a repo, run:
+
+    ```bash
+    cd ~/.openclaw/workspace
+    git init
+    git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
+    git commit -m "Add agent workspace"
+    ```
+
+  </Step>
+  <Step title="Add a private remote">
+    <Tabs>
+      <Tab title="GitHub web UI">
+        1. Create a new **private** repository on GitHub.
+        2. Do not initialize with a README (avoids merge conflicts).
+        3. Copy the HTTPS remote URL.
+        4. Add the remote and push:
+
+        ```bash
+        git branch -M main
+        git remote add origin <https-url>
+        git push -u origin main
+        ```
+      </Tab>
+      <Tab title="GitHub CLI (gh)">
+        ```bash
+        gh auth login
+        gh repo create openclaw-workspace --private --source . --remote origin --push
+        ```
+      </Tab>
+      <Tab title="GitLab web UI">
+        1. Create a new **private** repository on GitLab.
+        2. Do not initialize with a README (avoids merge conflicts).
+        3. Copy the HTTPS remote URL.
+        4. Add the remote and push:
+
+        ```bash
+        git branch -M main
+        git remote add origin <https-url>
+        git push -u origin main
+        ```
+      </Tab>
+    </Tabs>
+
+  </Step>
+  <Step title="Ongoing updates">
+    ```bash
+    git status
+    git add .
+    git commit -m "Update memory"
+    git push
+    ```
+  </Step>
+</Steps>
+
+## Do not commit secrets
+
+<Warning>
+Even in a private repo, avoid storing secrets in the workspace:
+
+- API keys, OAuth tokens, passwords, or private credentials.
+- Anything under `~/.openclaw/`.
+- Raw dumps of chats or sensitive attachments.
+
+If you must store sensitive references, use placeholders and keep the real secret elsewhere (password manager, environment variables, or `~/.openclaw/`).
+</Warning>
+
+Suggested `.gitignore` starter:
+
+```gitignore
+.DS_Store
+.env
+**/*.key
+**/*.pem
+**/secrets*
+```
+
+## Moving the workspace to a new machine
+
+<Steps>
+  <Step title="Clone the repo">
+    Clone the repo to the desired path (default `~/.openclaw/workspace`).
+  </Step>
+  <Step title="Update config">
+    Set `agents.defaults.workspace` to that path in `~/.openclaw/openclaw.json`.
+  </Step>
+  <Step title="Seed missing files">
+    Run `openclaw setup --workspace <path>` to seed any missing files.
+  </Step>
+  <Step title="Copy sessions (optional)">
+    If you need sessions, copy `~/.openclaw/agents/<agentId>/sessions/` from the old machine separately.
+  </Step>
+</Steps>
+
+## Advanced notes
+
+- Multi-agent routing can use different workspaces per agent. See [Channel routing](/channels/channel-routing) for routing configuration.
+- If `agents.defaults.sandbox` is enabled, non-main sessions can use per-session sandbox workspaces under `agents.defaults.sandbox.workspaceRoot`.
+
+## Related
+
+- [Heartbeat](/gateway/heartbeat) - HEARTBEAT.md workspace file
+- [Sandboxing](/gateway/sandboxing) - workspace access in sandboxed environments
+- [Session](/concepts/session) - session storage paths
+- [Standing orders](/automation/standing-orders) - persistent instructions in workspace files

package/docs/concepts/agent.md

@@ -0,0 +1,142 @@
+---
+summary: "Agent runtime, workspace contract, and session bootstrap"
+read_when:
+  - Changing agent runtime, workspace bootstrap, or session behavior
+title: "Agent runtime"
+---
+
+OpenClaw runs a **single embedded agent runtime** - one agent process per
+Gateway, with its own workspace, bootstrap files, and session store. This page
+covers that runtime contract: what the workspace must contain, which files get
+injected, and how sessions bootstrap against it.
+
+## Workspace (required)
+
+OpenClaw uses a single agent workspace directory (`agents.defaults.workspace`) as the agent's **only** working directory (`cwd`) for tools and context.
+
+Recommended: use `openclaw setup` to create `~/.openclaw/openclaw.json` if missing and initialize the workspace files.
+
+Full workspace layout + backup guide: [Agent workspace](/concepts/agent-workspace)
+
+If `agents.defaults.sandbox` is enabled, non-main sessions can override this with
+per-session workspaces under `agents.defaults.sandbox.workspaceRoot` (see
+[Gateway configuration](/gateway/configuration)).
+
+## Bootstrap files (injected)
+
+Inside `agents.defaults.workspace`, OpenClaw expects these user-editable files:
+
+- `AGENTS.md` - operating instructions + "memory"
+- `SOUL.md` - persona, boundaries, tone
+- `TOOLS.md` - user-maintained tool notes (e.g. `imsg`, `sag`, conventions)
+- `BOOTSTRAP.md` - one-time first-run ritual (deleted after completion)
+- `IDENTITY.md` - agent name/vibe/emoji
+- `USER.md` - user profile + preferred address
+
+On the first turn of a new session, OpenClaw injects the contents of these files into the system prompt's Project Context.
+
+Blank files are skipped. Large files are trimmed and truncated with a marker so prompts stay lean (read the file for full content).
+
+If a file is missing, OpenClaw injects a single "missing file" marker line (and `openclaw setup` will create a safe default template).
+
+`BOOTSTRAP.md` is only created for a **brand new workspace** (no other bootstrap files present). While it is pending, OpenClaw keeps it in Project Context and adds system-prompt bootstrap guidance for the initial ritual instead of copying it into the user message. If you delete it after completing the ritual, it should not be recreated on later restarts.
+
+After a workspace has been observed, OpenClaw also keeps a state-dir attestation marker for the workspace path. If a recently attested workspace disappears or is wiped, startup refuses to silently re-seed `BOOTSTRAP.md`; restore the workspace or use a full onboard reset so the workspace and marker are cleared together.
+
+To disable bootstrap file creation entirely (for pre-seeded workspaces), set:
+
+```json5
+{ agents: { defaults: { skipBootstrap: true } } }
+```
+
+## Built-in tools
+
+Core tools (read/exec/edit/write and related system tools) are always available,
+subject to tool policy. `apply_patch` is optional and gated by
+`tools.exec.applyPatch`. `TOOLS.md` does **not** control which tools exist; it's
+guidance for how _you_ want them used.
+
+## Skills
+
+OpenClaw loads skills from these locations (highest precedence first):
+
+- Workspace: `<workspace>/skills`
+- Project agent skills: `<workspace>/.agents/skills`
+- Personal agent skills: `~/.agents/skills`
+- Managed/local: `~/.openclaw/skills`
+- Bundled (shipped with the install)
+- Extra skill folders: `skills.load.extraDirs`
+
+Skill roots can contain grouped folders such as
+`<workspace>/skills/personal/foo/SKILL.md`; the skill is still exposed by its
+flat frontmatter name, for example `foo`.
+
+Skills can be gated by config/env (see `skills` in [Gateway configuration](/gateway/configuration)).
+
+## Runtime boundaries
+
+The embedded agent runtime is OpenClaw-owned: model discovery, tool wiring,
+prompt assembly, session management, and channel delivery share one integrated
+runtime surface.
+
+## Sessions
+
+Session transcripts are stored as JSONL at:
+
+- `~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl`
+
+The session ID is stable and chosen by OpenClaw.
+Legacy session folders from other tools are not read.
+
+## Steering while streaming
+
+Inbound prompts that arrive mid-run are steered into the current run by default.
+Steering is delivered **after the current assistant turn finishes executing its
+tool calls**, before the next LLM call, and no longer skips remaining tool calls
+from the current assistant message.
+
+`/queue steer` is the default active-run behavior. `/queue followup` and
+`/queue collect` make messages wait for a later turn instead of steering.
+`/queue interrupt` aborts the active run instead. See [Queue](/concepts/queue)
+and [Steering queue](/concepts/queue-steering) for queue and boundary behavior.
+
+Block streaming sends completed assistant blocks as soon as they finish; it is
+**off by default** (`agents.defaults.blockStreamingDefault: "off"`).
+Tune the boundary via `agents.defaults.blockStreamingBreak` (`text_end` vs `message_end`; defaults to text_end).
+Control soft block chunking with `agents.defaults.blockStreamingChunk` (defaults to
+800-1200 chars; prefers paragraph breaks, then newlines; sentences last).
+Coalesce streamed chunks with `agents.defaults.blockStreamingCoalesce` to reduce
+single-line spam (idle-based merging before send). Non-Telegram channels require
+explicit `*.blockStreaming: true` to enable block replies.
+Verbose tool summaries are emitted at tool start (no debounce); Control UI
+streams tool output via agent events when available.
+More details: [Streaming + chunking](/concepts/streaming).
+
+## Model refs
+
+Model refs in config (for example `agents.defaults.model` and `agents.defaults.models`) are parsed by splitting on the **first** `/`.
+
+- Use `provider/model` when configuring models.
+- If the model ID itself contains `/` (OpenRouter-style), include the provider prefix (example: `openrouter/moonshotai/kimi-k2`).
+- If you omit the provider, OpenClaw tries an alias first, then a unique
+  configured-provider match for that exact model id, and only then falls back
+  to the configured default provider. If that provider no longer exposes the
+  configured default model, OpenClaw falls back to the first configured
+  provider/model instead of surfacing a stale removed-provider default.
+
+## Configuration (minimal)
+
+At minimum, set:
+
+- `agents.defaults.workspace`
+- `channels.whatsapp.allowFrom` (strongly recommended)
+
+---
+
+_Next: [Group Chats](/channels/group-messages)_ 🦞
+
+## Related
+
+- [Agent workspace](/concepts/agent-workspace)
+- [Multi-agent routing](/concepts/multi-agent)
+- [Session management](/concepts/session)

package/docs/concepts/architecture.md

@@ -0,0 +1,154 @@
+---
+summary: "WebSocket gateway architecture, components, and client flows"
+read_when:
+  - Working on gateway protocol, clients, or transports
+title: "Gateway architecture"
+---
+
+## Overview
+
+- A single long-lived **Gateway** owns all messaging surfaces (WhatsApp via
+  Baileys, Telegram via grammY, Slack, Discord, Signal, iMessage, WebChat).
+- Control-plane clients (macOS app, CLI, web UI, automations) connect to the
+  Gateway over **WebSocket** on the configured bind host (default
+  `127.0.0.1:18789`).
+- **Nodes** (macOS/iOS/Android/headless) also connect over **WebSocket**, but
+  declare `role: node` with explicit caps/commands.
+- One Gateway per host; it is the only place that opens a WhatsApp session.
+- The **canvas host** is served by the Gateway HTTP server under:
+  - `/__openclaw__/canvas/` (agent-editable HTML/CSS/JS)
+  - `/__openclaw__/a2ui/` (A2UI host)
+    It uses the same port as the Gateway (default `18789`).
+
+## Components and flows
+
+### Gateway (daemon)
+
+- Maintains provider connections.
+- Exposes a typed WS API (requests, responses, server-push events).
+- Validates inbound frames against JSON Schema.
+- Emits events like `agent`, `chat`, `presence`, `health`, `heartbeat`, `cron`.
+
+### Clients (mac app / CLI / web admin)
+
+- One WS connection per client.
+- Send requests (`health`, `status`, `send`, `agent`, `system-presence`).
+- Subscribe to events (`tick`, `agent`, `presence`, `shutdown`).
+
+### Nodes (macOS / iOS / Android / headless)
+
+- Connect to the **same WS server** with `role: node`.
+- Provide a device identity in `connect`; pairing is **device-based** (role `node`) and
+  approval lives in the device pairing store.
+- Expose commands like `canvas.*`, `camera.*`, `screen.record`, `location.get`.
+
+Protocol details:
+
+- [Gateway protocol](/gateway/protocol)
+
+### WebChat
+
+- Static UI that uses the Gateway WS API for chat history and sends.
+- In remote setups, connects through the same SSH/Tailscale tunnel as other
+  clients.
+
+## Connection lifecycle (single client)
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Gateway
+
+    Client->>Gateway: req:connect
+    Gateway-->>Client: res (ok)
+    Note right of Gateway: or res error + close
+    Note left of Client: payload=hello-ok<br>snapshot: presence + health
+
+    Gateway-->>Client: event:presence
+    Gateway-->>Client: event:tick
+
+    Client->>Gateway: req:agent
+    Gateway-->>Client: res:agent<br>ack {runId, status:"accepted"}
+    Gateway-->>Client: event:agent<br>(streaming)
+    Gateway-->>Client: res:agent<br>final {runId, status, summary}
+```
+
+## Wire protocol (summary)
+
+- Transport: WebSocket, text frames with JSON payloads.
+- First frame **must** be `connect`.
+- After handshake:
+  - Requests: `{type:"req", id, method, params}` → `{type:"res", id, ok, payload|error}`
+  - Events: `{type:"event", event, payload, seq?, stateVersion?}`
+- `hello-ok.features.methods` / `events` are discovery metadata, not a
+  generated dump of every callable helper route.
+- Shared-secret auth uses `connect.params.auth.token` or
+  `connect.params.auth.password`, depending on the configured gateway auth mode.
+- Identity-bearing modes such as Tailscale Serve
+  (`gateway.auth.allowTailscale: true`) or non-loopback
+  `gateway.auth.mode: "trusted-proxy"` satisfy auth from request headers
+  instead of `connect.params.auth.*`.
+- Private-ingress `gateway.auth.mode: "none"` disables shared-secret auth
+  entirely; keep that mode off public/untrusted ingress.
+- Idempotency keys are required for side-effecting methods (`send`, `agent`) to
+  safely retry; the server keeps a short-lived dedupe cache.
+- Nodes must include `role: "node"` plus caps/commands/permissions in `connect`.
+
+## Pairing + local trust
+
+- All WS clients (operators + nodes) include a **device identity** on `connect`.
+- New device IDs require pairing approval; the Gateway issues a **device token**
+  for subsequent connects.
+- Direct local loopback connects can be auto-approved to keep same-host UX
+  smooth.
+- OpenClaw also has a narrow backend/container-local self-connect path for
+  trusted shared-secret helper flows.
+- Tailnet and LAN connects, including same-host tailnet binds, still require
+  explicit pairing approval.
+- All connects must sign the `connect.challenge` nonce.
+- Signature payload `v3` also binds `platform` + `deviceFamily`; the gateway
+  pins paired metadata on reconnect and requires repair pairing for metadata
+  changes.
+- **Non-local** connects still require explicit approval.
+- Gateway auth (`gateway.auth.*`) still applies to **all** connections, local or
+  remote.
+
+Details: [Gateway protocol](/gateway/protocol), [Pairing](/channels/pairing),
+[Security](/gateway/security).
+
+## Protocol typing and codegen
+
+- TypeBox schemas define the protocol.
+- JSON Schema is generated from those schemas.
+- Swift models are generated from the JSON Schema.
+
+## Remote access
+
+- Preferred: Tailscale or VPN.
+- Alternative: SSH tunnel
+
+  ```bash
+  ssh -N -L 18789:127.0.0.1:18789 user@host
+  ```
+
+- The same handshake + auth token apply over the tunnel.
+- TLS + optional pinning can be enabled for WS in remote setups.
+
+## Operations snapshot
+
+- Start: `openclaw gateway` (foreground, logs to stdout).
+- Health: `health` over WS (also included in `hello-ok`).
+- Supervision: launchd/systemd for auto-restart.
+
+## Invariants
+
+- Exactly one Gateway controls a single Baileys session per host.
+- Handshake is mandatory; any non-JSON or non-connect first frame is a hard close.
+- Events are not replayed; clients must refresh on gaps.
+
+## Related
+
+- [Agent Loop](/concepts/agent-loop) — detailed agent execution cycle
+- [Gateway Protocol](/gateway/protocol) — WebSocket protocol contract
+- [Queue](/concepts/queue) — command queue and concurrency
+- [Security](/gateway/security) — trust model and hardening

package/docs/concepts/channel-docking.md

@@ -0,0 +1,145 @@
+---
+summary: "Move one OpenClaw session's reply route between linked chat channels"
+title: "Channel docking"
+read_when:
+  - You want replies for one active session to move from Telegram to Discord, Slack, Mattermost, or another linked channel
+  - You are configuring session.identityLinks for cross-channel direct messages
+  - A /dock command says the sender is not linked or no active session exists
+---
+
+Channel docking is call forwarding for one OpenClaw session.
+
+It keeps the same conversation context, but changes where future replies for
+that session are delivered.
+
+## Example
+
+Alice can message OpenClaw on Telegram and Discord:
+
+```json5
+{
+  session: {
+    identityLinks: {
+      alice: ["telegram:123", "discord:456"],
+    },
+  },
+}
+```
+
+If Alice sends this from Telegram:
+
+```text
+/dock_discord
+```
+
+OpenClaw keeps the current session context and changes the reply route:
+
+| Before docking               | After `/dock_discord`       |
+| ---------------------------- | --------------------------- |
+| Replies go to Telegram `123` | Replies go to Discord `456` |
+
+The session is not recreated. The transcript history stays attached to the
+same session.
+
+## Why use it
+
+Use docking when a task starts in one chat app but the next replies should land
+somewhere else.
+
+Common flow:
+
+1. Start an agent task from Telegram.
+2. Move to Discord where you are coordinating work.
+3. Send `/dock_discord` from the Telegram session.
+4. Keep the same OpenClaw session, but receive future replies in Discord.
+
+## Required config
+
+Docking requires `session.identityLinks`. The source sender and target peer
+must be in the same identity group:
+
+```json5
+{
+  session: {
+    identityLinks: {
+      alice: ["telegram:123", "discord:456", "slack:U123"],
+    },
+  },
+}
+```
+
+The values are channel-prefixed peer ids:
+
+| Value          | Meaning                      |
+| -------------- | ---------------------------- |
+| `telegram:123` | Telegram sender id `123`     |
+| `discord:456`  | Discord direct peer id `456` |
+| `slack:U123`   | Slack user id `U123`         |
+
+The canonical key (`alice` above) is only the shared identity group name. Dock
+commands use the channel-prefixed values to prove that the source sender and
+target peer are the same person.
+
+## Commands
+
+Dock commands are generated from loaded channel plugins that support native
+commands. Current bundled commands:
+
+| Target channel | Command            | Alias              |
+| -------------- | ------------------ | ------------------ |
+| Discord        | `/dock-discord`    | `/dock_discord`    |
+| Mattermost     | `/dock-mattermost` | `/dock_mattermost` |
+| Slack          | `/dock-slack`      | `/dock_slack`      |
+| Telegram       | `/dock-telegram`   | `/dock_telegram`   |
+
+The underscore aliases are useful on native command surfaces such as Telegram.
+
+## What changes
+
+Docking updates the active session delivery fields:
+
+| Session field   | Example after `/dock_discord`            |
+| --------------- | ---------------------------------------- |
+| `lastChannel`   | `discord`                                |
+| `lastTo`        | `456`                                    |
+| `lastAccountId` | the target channel account, or `default` |
+
+Those fields are persisted in the session store and used by later reply
+delivery for that session.
+
+## What does not change
+
+Docking does not:
+
+- create channel accounts
+- connect a new Discord, Telegram, Slack, or Mattermost bot
+- grant access to a user
+- bypass channel allowlists or DM policies
+- move transcript history to another session
+- make unrelated users share a session
+
+It only changes the delivery route for the current session.
+
+## Troubleshooting
+
+**The command says the sender is not linked.**
+
+Add both the current sender and the target peer to the same
+`session.identityLinks` group. For example, if Telegram sender `123` should dock
+to Discord peer `456`, include both `telegram:123` and `discord:456`.
+
+**The command says no active session exists.**
+
+Dock from an existing direct-chat session. The command needs an active session
+entry so it can persist the new route.
+
+**Replies still go to the old channel.**
+
+Check that the command replied with a success message, and confirm the target
+peer id matches the id used by that channel. Docking only changes the active
+session route; another session may still route elsewhere.
+
+**I need to switch back.**
+
+Send the matching command for the original channel, such as `/dock_telegram` or
+`/dock-telegram`, from a linked sender.