From 2aeafdde0c75fe300fb619ff2b376eddfc51bb12 Mon Sep 17 00:00:00 2001
From: Aaron Stannard <aaron@petabridge.com>
Date: Thu, 29 Oct 2026 14:08:13 -0500
Subject: [PATCH] docs: getting started and CLI reference for 0.28

---
 src/content/docs/cli/approvals.md             | 225 +++----
 src/content/docs/cli/chat.md                  | 294 ++++++---
 src/content/docs/cli/config.md                | 220 +++++--
 src/content/docs/cli/daemon.md                | 186 ++++++
 src/content/docs/cli/doctor.md                | 284 +++++----
 src/content/docs/cli/init.md                  | 223 ++++---
 src/content/docs/cli/mcp-tools.md             | 324 +++++-----
 src/content/docs/cli/memory.md                |  93 +++
 src/content/docs/cli/model.md                 | 202 +++++--
 src/content/docs/cli/overview.md              | 218 +++----
 src/content/docs/cli/provider.md              | 202 +++++--
 src/content/docs/cli/reminder.md              | 229 ++++---
 src/content/docs/cli/secrets.md               | 130 ++--
 src/content/docs/cli/sessions.md              | 197 +++---
 src/content/docs/cli/skill.md                 | 321 +++++-----
 src/content/docs/cli/stats.md                 | 167 +++---
 src/content/docs/cli/status.md                | 180 ++++--
 src/content/docs/cli/update.md                | 144 +++++
 src/content/docs/cli/webhooks.md              | 137 +++--
 .../docs/getting-started/first-assistant.md   | 560 ++++++++++++++++++
 .../getting-started/first-conversation.md     | 174 ++++--
 .../docs/getting-started/installation.md      | 291 +++++----
 .../docs/getting-started/quickstart.md        | 128 ++--
 23 files changed, 3510 insertions(+), 1619 deletions(-)
 create mode 100644 src/content/docs/cli/daemon.md
 create mode 100644 src/content/docs/cli/memory.md
 create mode 100644 src/content/docs/cli/update.md
 create mode 100644 src/content/docs/getting-started/first-assistant.md

diff --git a/src/content/docs/cli/approvals.md b/src/content/docs/cli/approvals.md
index 130cf43..cc6bf5b 100644
--- a/src/content/docs/cli/approvals.md
+++ b/src/content/docs/cli/approvals.md
@@ -1,187 +1,212 @@
 ---
 title: "netclaw approvals"
-description: "Inspect, revoke, and manage persistent tool approvals."
+description: "List, revoke and pre-approve the grants netclaw saves when you answer Always at an approval prompt."
 ---
 
-When netclaw's [approval gates](/architecture/security-model/#human-in-the-loop-as-a-layer-not-a-crutch) prompt you to allow a tool invocation, your "always allow" choices get saved to `~/.netclaw/config/tool-approvals.json`. This command lets you see what's been approved, revoke entries you no longer want, and add global trust rules. Running `netclaw approvals` with no subcommand opens the [interactive TUI](#tui).
+When you answer **Always here**, **This repository** or **Always anywhere** at an approval prompt, netclaw saves a grant to `~/.netclaw/config/tool-approvals.json`. `netclaw approvals` lists those grants, revokes the ones you no longer want, and adds new ones before a prompt ever appears. Run it with no subcommand to open the [interactive TUI](#tui).
 
-![Approval gate prompt in a Slack thread, with approve and deny options](/assets/approval-prompt.png)
+This page is the reference for the command and the file. For how grants fit into the authorization model, see [How tool approvals work](/security/approvals/). To stop prompts for a command or a tool, see [Reduce or turn off approval prompts](/guides/reduce-approval-prompts/).
 
-The two "Always" options in the channel prompt — **Always here** (the command's verb, scoped to the current directory) and **Always anywhere** (a global grant) — are what create persistent entries in `tool-approvals.json`.
-
-Audiences (`personal`, `team`, `public`) scope approvals to who's talking to the agent. An approval granted under `personal` doesn't apply when a team member triggers the same command. See [audience dispositions](/architecture/security-model/#audience-as-the-trust-primitive) for background.
-
-Don't hand-edit the JSON file. Use this command instead.
+Grants belong to one audience (`personal`, `team` or `public`) and one tool. A `personal` grant doesn't apply when a Team user triggers the same command. Don't hand-edit the file. The CLI keeps entries valid.
 
 ## Usage
 
 ```bash
-netclaw approvals                         # open TUI
-netclaw approvals list [options]          # print approvals
-netclaw approvals revoke <pattern> [options]  # remove an approval
-netclaw approvals trust-verb <verb> [options] # add a global approval
-netclaw approvals tui                     # open TUI (explicit)
-netclaw approvals help                    # show help
+netclaw approvals                              # open the TUI
+netclaw approvals list [options]               # print grants
+netclaw approvals revoke <label> [options]     # remove one grant
+netclaw approvals revoke --tool <name> --all [--audience <name>]
+netclaw approvals trust-verb <phrase> [options]  # add a global grant
+netclaw approvals tui                          # open the TUI (explicit)
+netclaw approvals help
 ```
 
-## Subcommands
-
-### list
+Changes take effect on the next approval check. The daemon doesn't need a restart and doesn't watch the file.
 
-Show what's currently approved. Filter by audience or tool.
+## list
 
 ```bash
 netclaw approvals list
-netclaw approvals list --audience personal
-netclaw approvals list --tool shell_execute
-netclaw approvals list --json
+netclaw approvals list --audience team
+netclaw approvals list --tool shell_execute --json
 ```
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `--audience <name>` | Filter to `personal`, `team`, or `public` | all audiences |
-| `--tool <name>` | Filter to a specific tool (e.g., `shell_execute`, `mcp:demo-utilities:write_file`) | all tools |
-| `--json` | Machine-readable JSON output | off |
+| `--audience <name>` | `personal`, `team` or `public` | all audiences |
+| `--tool <name>` | One tool: `shell_execute`, or `server/tool` for an MCP tool | all tools |
+| `--json` | Machine-readable output | off |
+
+Human output groups grants by audience and tool, with the typed label you pass to `revoke` and how long ago each was added:
+
+```text
+personal / shell_execute
+  PowerShell token-prefix "Get-ChildItem" anywhere   added just now
+  Bash token-prefix "gh" anywhere                    added just now
+  Bash token-prefix "git push" anywhere              added just now
 
-![netclaw approvals list output](/screenshots/output/approvals-list.png)
+team / shell_execute
+  Bash token-prefix "npm run" anywhere   added just now
+```
+
+With no grants it prints `No persistent approvals.` and exits 0.
+
+![netclaw approvals list output grouping six grants under personal demo-utilities/calculate, personal shell_execute and team shell_execute](/screenshots/output/approvals-list.png)
 
-The `--json` output follows a stable schema — safe to pipe into `jq` for scripting:
+The scope is the end of each label. `anywhere` came from **Always anywhere**, `in /home/netclaw/projects/website` from **Always here**, and `in repository ...` from **This repository**, which names the repository's `.git`. The MCP tool's grant is an exact match.
+
+`--json` output has an `audiences` root, then tool names, then entries. Shell entries carry `shell`, `match`, `verbTokens`, `directory` and `createdAt`. Entries for other tools carry `verb` instead of `verbTokens`:
 
 ```bash
-# List all directory-scoped shell approvals
+# Directories you've granted shell access in
 netclaw approvals list --json \
-  | jq '.audiences.personal.shell_execute[] | select(.directory != null)'
+  | jq -r '.audiences.personal.shell_execute[] | select(.directory != null) | .directory'
 ```
 
-### revoke
+## revoke
 
-Remove a specific approval entry. The pattern format matches the display output from `list`: `<verb> in <directory>` for directory-scoped entries, or `<verb> anywhere` for global approvals.
+Pass the exact label `list` prints. Quote it, because the phrase has quotes inside:
 
 ```bash
-netclaw approvals revoke 'git push anywhere'
-netclaw approvals revoke 'docker compose in /home/user/repos/netclaw/'
-netclaw approvals revoke 'git push anywhere' --audience team
+netclaw approvals revoke 'Bash token-prefix "git push" anywhere'
+netclaw approvals revoke 'Bash token-prefix "git push" anywhere' --audience team
 ```
 
-Remove all approvals for a tool:
+With no `--audience` and no `--tool`, `revoke` searches every audience and every tool for a matching label. It removes each match. Narrow it when the same label exists in more than one audience.
+
+The older `<phrase> anywhere` and `<phrase> in <directory>` forms still work as a fallback, but only when exactly one entry matches. If more than one does, `revoke` stops with `The old approval scope matches more than one typed phrase.` and asks for the typed label.
+
+To clear every grant for a tool:
 
 ```bash
 netclaw approvals revoke --tool shell_execute --all
-netclaw approvals revoke --tool mcp:demo-utilities:write_file --all
+netclaw approvals revoke --tool shell_execute --all --audience team
+netclaw approvals revoke --tool demo-utilities/calculate --all
 ```
 
+Without `--audience`, `--all` clears that tool in **all three audiences**. `--all` requires `--tool`.
+
 | Flag | Description | Default |
 |------|-------------|---------|
-| `--audience <name>` | Target audience | `personal` |
-| `--tool <name>` | Target tool | `shell_execute` |
-| `--all` | Remove all entries for the tool (requires `--tool`) | off |
+| `--audience <name>` | Limit to one audience | all audiences |
+| `--tool <name>` | Limit to one tool. Accepts `server/tool` or the model-facing `server__tool` | all tools |
+| `--all` | Remove every grant for `--tool` | off |
 
-Changes take effect immediately — no daemon restart needed.
+## trust-verb
 
-### trust-verb
-
-Add a global-wildcard approval so the verb runs in any working directory without prompting.
+Adds a global ("anywhere") grant so a phrase never prompts, in any directory. Use it for scheduled or unattended work, or to pre-approve something you know you'll want.
 
 ```bash
 netclaw approvals trust-verb 'git push'
 netclaw approvals trust-verb 'npm run' --audience team
-netclaw approvals trust-verb 'write_file' --tool mcp:demo-utilities:write_file
+netclaw approvals trust-verb 'Get-ChildItem' --shell powershell
+netclaw approvals trust-verb demo-utilities/calculate --tool demo-utilities/calculate
 ```
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `--audience <name>` | Target audience | `personal` |
-| `--tool <name>` | Target tool | `shell_execute` |
+| `--audience <name>` | Audience the grant belongs to | `personal` |
+| `--tool <name>` | Tool the grant belongs to | `shell_execute` |
+| `--shell <bash\|powershell>` | Shell dialect of the phrase. Only valid for `shell_execute` | the native shell |
+
+For shell, the phrase is a token prefix. Two or more words (`git push`) cover those words plus any later arguments, so `git push origin main` is covered and `git pull` isn't. One word covers the program alone: `gh` doesn't cover `gh pr view`, so grant `gh pr` if you want that family.
+
+`trust-verb` accepts one complete static command. It rejects flags, arguments, redirects and assignments with `The shell phrase must have no argument, flag, assignment, redirect, or control effect.`, and compound or unparseable phrases such as `git push && rm x` with `The shell phrase must contain one complete static command.` The phrase must also be in canonical spacing (`git  push` is refused with `The shell phrase must equal its canonical form: git push`), and a program path must be absolute.
+
+For a tool that isn't shell, including every MCP tool, the grant matches exactly and the phrase must be the tool's canonical name, as in the last example above. Any other phrase is refused with exit 1 and the command that would work:
+
+```text
+Error: 'calculate' never matches a call to demo-utilities/calculate. Grants for this tool match only the phrase 'demo-utilities/calculate'.
+If the tool is named 'demo-utilities/calculate', run: netclaw approvals trust-verb demo-utilities/calculate --tool demo-utilities/calculate --audience personal
+```
+
+A successful grant prints the label it saved, as in `Trusted 'NonShell exact "demo-utilities/calculate" anywhere' for personal / demo-utilities/calculate.`
 
-This writes an entry with `directory: null` — an "anywhere" grant in `list` output.
+Running it twice for the same phrase prints `No changes: '...' is already trusted for personal / shell_execute.` and exits 0. A grant a saved grant already covers isn't saved twice either.
 
-### tui
+## tui
 
-Open the interactive approvals manager. Same as running `netclaw approvals` with no arguments.
+`netclaw approvals` with no subcommand opens the approvals manager. It lists grants and revokes them. It can't add them, so use `trust-verb` for that.
 
-![Approvals TUI showing entries with revoke option](/screenshots/output/approvals-tui.png)
+![Approvals Manager TUI with a table of six grants by audience, tool, approval and age, and a footer offering Navigate, R/Del Revoke and Ctrl+Q Quit](/screenshots/output/approvals-tui.png)
+
+The same six grants as the list above, one per row, with the footer keys described below.
 
 | Key | Action |
 |-----|--------|
-| Up / Down | Navigate entries |
-| Enter, Delete, or R | Revoke selected entry |
-| Enter | Confirm revoke (in confirmation dialog) |
-| Esc | Cancel revoke confirmation |
+| Up / Down | Move between grants |
+| R or Delete | Start revoking the highlighted grant |
+| Enter | Start revoking the highlighted grant, or confirm in the dialog |
+| Esc | Cancel the confirmation. It never quits |
 | Ctrl+Q | Quit |
 
-The TUI is read-and-revoke only — use `trust-verb` on the command line to add new entries.
-
-![Revoke confirmation dialog in the TUI](/screenshots/output/approvals-tui-revoke-confirm.png)
+![Approvals Manager confirmation asking to revoke the personal shell_execute grant for gh, with Yes, revoke highlighted in red and No, cancel below](/screenshots/output/approvals-tui-revoke-confirm.png)
 
-## Exit codes
-
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 1 | User error or no matching entry for `revoke` |
+The dialog opens on **Yes, revoke**, so press Down first if you're unsure. Esc backs out and nothing is removed.
 
-## File format
+## The grant file
 
-Approvals live in `~/.netclaw/config/tool-approvals.json`:
+Grants live in `~/.netclaw/config/tool-approvals.json`, schema version 3:
 
 ```json
 {
-  "version": 2,
+  "version": 3,
   "audiences": {
     "personal": {
       "shell_execute": [
-        { "verb": "git push", "directory": null },
-        { "verb": "docker compose", "directory": "/home/user/repos/netclaw/" }
-      ]
-    },
-    "team": {
-      "shell_execute": [
-        { "verb": "git pull", "directory": null }
+        {
+          "shell": "Bash",
+          "match": "TokenPrefix",
+          "verbTokens": ["git", "push"],
+          "directory": null,
+          "createdAt": "2026-10-07T15:24:16.7675256+00:00"
+        }
       ]
     }
   }
 }
 ```
 
-Each entry is a verb + optional directory. `directory: null` means the verb is approved in any working directory. A specific directory scopes the approval to that path and its children. The daemon picks up file changes automatically.
-
-## Case sensitivity
-
-Verb and directory matching uses ordinal comparison on Linux/macOS (case-sensitive) and ordinal-ignore-case on Windows. This matches filesystem semantics — `git Push` won't match `git push` on Linux.
+Each entry is a shell, a match kind, the command words, and a scope: `directory: null` for "anywhere", a path for a folder grant (that path and its children, see [what Always here covers](/security/approvals/#what-always-here-covers)), or a Git `repository` for a repository grant. Entries for other tools have a `verb` and no shell. Entries can also carry an `assignmentDigest` when a grant is qualified by bounded shell variable assignments.
 
-## Recovery
+The label `list` prints follows the entry:
 
-If `tool-approvals.json` is malformed, the daemon moves it aside and creates a fresh file:
+| Grant | Label |
+|-------|-------|
+| Anywhere | `Bash token-prefix "git push" anywhere` |
+| Folder | `Bash token-prefix "git push" in /home/me/src/app` |
+| Repository | `Bash token-prefix "git push" in repository <repo>` |
+| Other tool | `NonShell exact "demo-utilities/calculate" anywhere` |
+| Converted from version 2 | `Bash legacy-exact "git push" anywhere` |
 
-| Sibling file | Meaning |
-|---|---|
-| `tool-approvals.json.invalid` | Current file failed to parse — moved aside, fresh file created |
-| `tool-approvals.json.v1.bak` | Legacy v1 format — no auto-migration, kept as backup |
+On Linux and macOS, matching is case-sensitive, so `git Push` doesn't match `git push`. On Windows it ignores case.
 
-To reset completely, delete `tool-approvals.json` and restart the daemon. The next tool invocation that requires approval will recreate the file.
+### Upgrade and repair
 
-## Recipes
+- A **version 2** file gets a byte-identical `tool-approvals.json.v2.bak` and is converted. Old shell entries become `legacy-exact` grants that follow the same coverage rule as new ones: two or more words cover later arguments, one word covers the program alone. While the backup exists, `list`, `revoke`, `trust-verb` and `help` print a `Recovery:` notice. To roll back, stop the daemon, copy the backup over the active file and start the older daemon.
+- A **version 1** file moves to `tool-approvals.json.v1.bak` and an empty version 3 file replaces it.
+- A **malformed or newer-version** file is left untouched. Every subcommand exits 1 with `Error: The approval store is unavailable (InvalidData).` or `(UnsupportedVersion)`, and any tool call that needs a grant is denied with `approval_store_unavailable`. Fix the JSON or restore a copy. A missing file is an empty store, so deleting the file is a way to start over if you don't need the old grants.
 
-Which directories have you granted shell access to?
+`netclaw doctor` reports grants that another grant already covers, and `netclaw doctor --fix` removes them. It reports a folder grant whose directory no longer exists and leaves it alone.
 
-```bash
-netclaw approvals list --json \
-  | jq '.audiences.personal.shell_execute[] | select(.directory != null) | .directory'
-```
+## Exit codes
 
-Wipe all team-level shell approvals and start fresh:
+| Code | Meaning |
+|------|---------|
+| 0 | Success, including `list` with nothing to show |
+| 1 | User error, no matching grant for `revoke`, or an unavailable store |
 
-```bash
-netclaw approvals revoke --tool shell_execute --all --audience team
-```
+An unknown subcommand, as in `netclaw approvals bogus`, prints the usage and exits `0`.
 
-## Related commands
+## Related pages
 
-- [`netclaw init`](/cli/init/) — sets the initial audience disposition and approval policy
-- [`netclaw mcp-tools`](/cli/mcp-tools/) — manage per-tool MCP permissions
-- [`netclaw secrets`](/cli/secrets/) — manage encrypted credentials
+- [How tool approvals work](/security/approvals/) - modes, outcomes and what each prompt answer saves
+- [Reduce or turn off approval prompts](/guides/reduce-approval-prompts/) - pre-approve with `trust-verb` or set a tool to `Auto`
+- [`netclaw mcp`](/cli/mcp-tools/) - per-server and per-tool MCP modes
+- [`netclaw doctor`](/cli/doctor/) - flags redundant grants
+- [Run reminders, webhooks and scripts unattended](/guides/unattended-runs/) - why unattended runs need saved grants
 
 ## Resources
 
-- [Security Model](/architecture/security-model/) — how approvals fit into the four-layer security model
-- [MCP Tool Permissions](/guides/mcp-tool-permissions/) — MCP-specific approval configuration
+- [jq manual](https://jqlang.github.io/jq/manual/) - for filtering `list --json`
+- [Tool approval gates runbook](https://github.com/netclaw-dev/netclaw/blob/dev/docs/runbooks/tool-approval-gates.md) - the product's operator runbook, including the store repair steps
diff --git a/src/content/docs/cli/chat.md b/src/content/docs/cli/chat.md
index ab9bece..839cccc 100644
--- a/src/content/docs/cli/chat.md
+++ b/src/content/docs/cli/chat.md
@@ -1,11 +1,11 @@
 ---
 title: "netclaw chat"
-description: "Interactive chat and headless prompt mode."
+description: "Interactive terminal chat and headless single-prompt mode, with keys, approval prompts and session resume."
 ---
 
-Talk to your agent. `netclaw chat` opens a terminal UI for interactive conversations. `netclaw chat -p` sends a single prompt and exits — the scriptable version.
+Talk to your agent. `netclaw chat` opens a terminal UI for a conversation, and `netclaw chat -p` sends one prompt and exits, which is the version you script.
 
-Both modes require a running daemon. If it's not up, start it with `netclaw daemon start` (or run [`netclaw init`](/cli/init/) which starts it for you). The CLI is a thin [SignalR](https://learn.microsoft.com/en-us/aspnet/core/signalr/introduction) client — rendering only. Inference, tool execution, and session state all live in the daemon.
+Both need a running daemon. If it's down, start it with `netclaw daemon start` (`docker restart <container>` in Docker), or run [`netclaw init`](/cli/init/), which starts it for you. The CLI is a thin [SignalR](https://learn.microsoft.com/en-us/aspnet/core/signalr/introduction) client that only renders. Inference, tool execution and session state all live in the daemon.
 
 ## Usage
 
@@ -17,10 +17,13 @@ netclaw chat [options] [prompt]
 
 | Flag | Alias | Description | Default |
 |------|-------|-------------|---------|
-| `--resume <id>` | `-r` | Resume an existing session by ID or name | New session |
-| `--prompt` | `-p` | Headless mode — send a single prompt, stream output, exit | Interactive TUI |
-| `--json` | — | Output structured JSON envelope (headless only) | Plain text |
-| `--help` | `-h` | Print help and exit | — |
+| `--resume <id>` | `-r` | Resume (or create) a session by ID or name. `--resume=<id>` also works. | New session |
+| `--onboarding` | | Start the guided identity interview. Interactive only: not with `-p` or `--resume`. | Off |
+| `--prompt` | `-p` | Headless mode: send one prompt, print the response, exit | Interactive TUI |
+| `--json` | | Print one JSON envelope instead of prefixed lines (headless only) | Plain text |
+| `--help` | `-h` | Print help | |
+
+The prompt is the first argument that isn't a flag, and it's only used with `-p`. `netclaw chat "hello"` without `-p` opens the TUI and ignores the text. With `-p` and no prompt, you get `netclaw: chat -p requires a prompt argument.` and the usage text, and the exit code is `1`.
 
 ## Interactive TUI
 
@@ -28,57 +31,102 @@ netclaw chat [options] [prompt]
 netclaw chat
 ```
 
-The TUI has three panels:
-
-1. **Chat history** — scrollable, streams responses as they arrive
-2. **Input** — text area that auto-sizes from 3 to 8 rows, keeps 100-message history
-3. **Status bar** — keyboard hints, connection state, active model, token usage
+Three panels: the scrollable chat history, an input box that grows from 3 to 8 rows and remembers your last 100 messages, and a status bar.
 
-### Keyboard shortcuts
+### Keys
 
 | Key | Action |
 |-----|--------|
-| `Enter` | Send message |
-| `Ctrl+Enter` | Insert newline |
-| `PgUp` / `PgDn` / Mouse wheel | Scroll chat history |
-| `Ctrl+Q` | Quit |
-| `Escape` | Quit (ignored while generating) |
+| `Enter` | Send the message |
+| `Ctrl+Enter` | Insert a newline |
+| `PgUp` / `PgDn` / mouse wheel | Scroll the history |
+| `Ctrl+Q` | Quit. This is the only key that quits. |
+| `Esc` | Deny a pending approval prompt. Does nothing when idle, and never quits. |
+| `↑` / `↓` | Pick an option in an approval prompt |
+| `Ctrl+O` | Expand or collapse the full body of a pending approval prompt |
+
+The TUI refuses a message over 512 KB: the text goes back into the input box, an `[error]` line appears and the status bar shows `Message is too large to send (<n> KB; limit 512 KB).`
+
+You can't cancel a running turn. Pressing `Esc` while the agent is generating shows "Cancel generation is not supported yet." in the status bar, and the turn keeps going. Quit with `Ctrl+Q` if you need to leave. The session stays alive in the daemon.
+
+### Quitting
+
+Text you submitted counts as delivered once the daemon has journaled it, and it keeps running after you leave. So `Enter` followed by `Ctrl+Q` is safe. The client waits up to two seconds for the daemon to confirm admission, never for the model's reply, then exits. A chat you never typed in creates no session.
+
+If the daemon doesn't confirm in time, the terminal is restored first and then netclaw prints what it couldn't vouch for:
+
+```
+netclaw: 1 unsent; 0 rejected; 0 delivery unconfirmed. Check session (not created) before you resend.
+```
+
+*Unsent* text never left the client, *rejected* text was refused by the daemon, and *unconfirmed* text was sent but nobody confirmed it arrived. netclaw doesn't resend on its own, because that could run a prompt twice. Look at the named session in [`netclaw sessions`](/cli/sessions/), and only resend if the text isn't there. The guarantee needs a CLI and a daemon that both support text admission, so upgrade them together. A newer CLI talking to an older daemon fails with `unsupported text admission version 0` and sends nothing.
 
 ### Status bar
 
 ```
-[key hints] | [connection status] | [model ID] | [usage]
+[Enter] Send  [Ctrl+Enter] Newline  [PgUp/PgDn/Wheel] Scroll  [Ctrl+Q] Quit | Ready | stub-model
 ```
 
-Status bar color reflects connection state: green = Ready/Connected, yellow = Connecting/Generating, red = Disconnected/Failed.
+The sections are key hints, connection state, the active model and, after the first turn, usage such as `in=10890 out=56 (8 % ctx)`: input tokens, output tokens and the share of the model's context window in use. The hints shorten on narrow terminals. The bar is green when Ready or Connected, yellow while Connecting or Generating, and red when Disconnected or Failed.
+
+### Identity interview
 
-Usage reads like `in=142 out=87 (12% ctx)` — input tokens, output tokens, percentage of the model's [context window](https://platform.openai.com/docs/concepts#context-window) used.
+```bash
+netclaw chat --onboarding
+```
+
+Opens a new chat whose first turn starts the identity interview that `netclaw init` offers at the end of setup, built from the name and communication style already in `netclaw.json`. Use it to redo the interview later. It rejects `-p`, `--resume` and `--onboarding=<value>`. If the daemon is down, the error message repeats the command so you can run it once the daemon is up.
+
+### Slash commands
+
+Start a message with `/` to run a skill as a command, such as `/run-reminder <id>`. An unknown command returns the list of available ones without calling the model. See [Slash commands](/reference/slash-commands/).
 
 ### Tool approval
 
-When a tool needs approval, the input panel swaps the text area for a selection list:
+When a tool call needs your approval, the input box turns into a selection list. The history shows what's being asked:
+
+```
+System: Approval required for shell_execute
+  npm run build
+  Patterns: npm run build
+  Options: Once, This chat, Always here, This repository, Always anywhere, Deny
+```
+
+That's the six-option form, from a chat working inside a Git repository. Outside one, **This repository** drops out and you get five.
 
 | Option | Effect |
 |--------|--------|
-| **Once** | This invocation only |
-| **This chat** | Session-scoped — resets when you quit |
-| **Always here** | The command's verb, scoped to the current directory — persists to [`~/.netclaw/config/tool-approvals.json`](/cli/approvals/) |
-| **Always anywhere** | The command's verb everywhere — a global grant in the same file. The broadest option; use it sparingly. |
-| **Deny** | Block this invocation |
+| **Once** | Allow this call only |
+| **This chat** | Allow it for the rest of this session |
+| **Always here** | Save a grant to [`tool-approvals.json`](/cli/approvals/) for the folder the command's paths point at, and everything under it ([what it covers](/security/approvals/#what-always-here-covers)) |
+| **Always anywhere** | Save a grant for this command in any folder. This is the broadest option, so use it sparingly. |
+| **This repository** | Save a grant for one Git repository and its worktrees. Shown only when the call runs inside a repo. |
+| **Always allow this tool** | Save a grant for an MCP tool |
+| **Deny** | Block the call |
+
+![Netclaw chat TUI with a pending shell_execute approval for npm run build, six numbered options and the Ctrl+O hint in the status bar](/screenshots/output/chat-tui-approval-prompt.png)
+
+The history above the input box says what's being asked, and the status bar reads "Approval required" until you answer.
 
-Arrow keys to select, `Enter` to confirm. netclaw shows fewer options when some don't apply (e.g. just **Once** and **Deny** for a command it can't cleanly parse).
+Use `↑` and `↓` to pick and `Enter` to confirm. Netclaw shows only the options that apply to the call, so a command it can't parse offers just **Once** and **Deny**. `Esc` denies. `Ctrl+O` expands a long command so you can read all of it before you answer.
+
+Approval prompts never time out. A pending prompt waits for you, and a later answer still resumes the call. A background [sub-agent](/skills/custom-subagents/) can raise prompts in the same list. They outlive the parent turn, and the status bar stays on "Approval required" until you answer or the session withdraws the prompt, for example because the child was cancelled, or because the daemon restarted before the child had parked. A child that had already parked keeps its prompt through a restart, and one click resumes it. Only a key press answers one. Typed text doesn't. For how grants are matched and revoked, see [How tool approvals work](/security/approvals/). To get fewer prompts, see [Reduce or turn off approval prompts](/guides/reduce-approval-prompts/).
 
 ### Reconnection
 
-If the daemon disconnects, the status bar turns red and the TUI retries with backoff (1s, 2s, 5s, 10s). Anything you type while disconnected queues up and sends on reconnect.
+If the daemon drops, the status bar turns red and the TUI retries after 1, 2, 5 and then 10 seconds. Text you type while it's down queues up and sends when the connection returns. Text that was already on its way when the connection dropped isn't sent a second time. It shows up in the [quit report](#quitting) as unconfirmed.
 
-### Session resume
+### Resume a session
 
 ```bash
-netclaw chat --resume abc123
+netclaw chat --resume daily-standup
 ```
 
-Recent messages replay as grayed-out history so you have context from where you left off. Find session IDs with [`netclaw sessions`](/cli/sessions/). You can use daemon-assigned IDs or pass your own human-readable name — `--resume daily-standup` creates a named session if it doesn't exist.
+The session's recent messages replay as grayed-out history, between `--- Previous conversation ---` and `--- End of history ---`. Pass a daemon-assigned ID from [`netclaw sessions`](/cli/sessions/), or your own name. If the name doesn't exist yet, netclaw creates the session. You can also resume from the sessions browser, which opens the same view.
+
+![Netclaw chat TUI after resuming a session, with the earlier two-turn conversation about weekly meeting notes shown in grey between Previous conversation and End of history markers](/screenshots/output/chat-tui-idle.png)
+
+The history is context only, and the input box below it is ready for your next message.
 
 ## Headless mode
 
@@ -86,111 +134,173 @@ Recent messages replay as grayed-out history so you have context from where you
 netclaw chat -p "summarize today's alerts"
 ```
 
-Sends one prompt, streams the response to stdout, exits when the turn completes (including any tool calls the agent makes along the way).
+Headless mode sends one prompt, streams the response to stdout and exits when the turn ends, tool calls included. If the agent started a sub-agent with `spawn_agent` and it is still running, the run stays open. See [Sub-agents and open runs](#sub-agents-and-open-runs). A message over 512 KB is refused before a session is created: `[headless:error] Message is too large to send (<n> KB; limit 512 KB).` and exit `1`. [Scripting headless sessions](/guides/scripting-sessions/) has patterns built on it.
+
+![netclaw chat -p run searching for a UUID generator tool, with a tool:call line, a usage line, the tool:result listing demo-utilities__generate_uuid, the answer and a second usage line](/screenshots/output/single-shot-cli-execution.png)
+
+The prefixed lines show the tool call, its result and token usage as they happen, and the unprefixed line is the answer.
 
 ### Output format
 
 | Prefix | Meaning |
 |--------|---------|
-| *(none)* | Streamed assistant text |
-| `[tool:call] name(args)` | Tool invocation |
-| `[tool:result] name → result` | Tool result |
+| none | Streamed assistant text |
+| `[tool:call] name(args)` | A tool call |
+| `[tool:result] name → result` | A tool result |
 | `[usage] in=N out=N total=N cached=N prompt_ms=N tok_s=N` | Token usage and timing |
-| `[file] fileName → filePath` | File written by the agent |
-| `[subagent:start] name (N tools)` | [Sub-agent](/architecture/overview/) spawned |
-| `[subagent:done] name (success/failed, Xs)` | Sub-agent completed |
-| `[compaction] N → M messages (keep=K, context=X/Y tokens)` | [Context compaction](/architecture/overview/) — the daemon summarized older messages to free up token space |
+| `[file] fileName → filePath` | A file the agent produced |
+| `[subagent:start] name (N tools)` | A [subagent](/skills/custom-subagents/) started |
+| `[subagent:done] name (outcome, Xs)` | A subagent finished. The outcome is lower-case, and a `reason=...` can follow the time. |
+| `[compaction] N → M messages (keep=K, context=X/Y tokens)` | The daemon summarized older messages to free context |
+| `[subagent:waiting] N open: <runId>,...` | The turn ended but N sub-agent runs are still open. The run waits for the turn that delivers their result. |
+| `[approval:waiting] tool: text` | A sub-agent asked for an approval that nobody can answer in this run |
+| `[approval:closed] reason` | That prompt was withdrawn |
 
-Errors go to stderr as `[error] message`. Thinking tokens are logged to `~/.netclaw/logs/` but not written to stdout.
+The last three print only in text mode. Errors in the turn go to stderr as `[error] message`, with line breaks turned into spaces, and a failed turn adds a `[turn:failed]` line (see [When the turn fails](#when-the-turn-fails)). Failing to reach the daemon prints `[headless:error]`, the connection error and `[turn:failed] category=infra kind=ChannelFailure`, and exits `1`:
 
-### JSON output
+```
+[headless:error] Connection refused (127.0.0.1:5199)
+[turn:failed] category=infra kind=ChannelFailure
+```
 
-```bash
-netclaw chat -p --json "list running services"
+Startup and connection failures are also appended to `~/.netclaw/logs/headless-errors.log`. Thinking tokens go to the logs, not stdout.
+
+### Sub-agents and open runs
+
+`spawn_agent` returns `accepted` in the first turn, and the child's result arrives in a later turn of the same session. `chat -p` doesn't stop at the end of the first turn. It ends on the first completed turn that reports no open child run. Here's a prompt that asks for a sub-agent, in text mode:
+
+```
+$ netclaw chat -p "Use the spawn_agent tool with the arithmetic-worker agent to compute 19*21. Wait for its result, then tell me the number."
+...
+[subagent:start] arithmetic-worker (25 tools)
+[tool:result] spawn_agent → {"run_id":"35d48023de5d44b8aefe9e2a6c807164","state":"accepted",...}
+[subagent:done] arithmetic-worker (completed, 8.1s)
+...
+[subagent:waiting] 1 open: 35d48023de5d44b8aefe9e2a6c807164
+[tool:call] file_read({"Path":".../subagents/35d48023de5d44b8aefe9e2a6c807164/result.md",...})
+[tool:result] file_read → # Child result ... Result: 399 ...
+**399**
+$ echo $?
+0
 ```
 
-Outputs a single JSON object to stdout. In JSON mode, the prefixed lines above are suppressed — you get one clean object:
+Turn 1 ended with the child still open, so the CLI printed `[subagent:waiting]` and kept going. Turn 2 read the child's `result.md` and answered, and the run exited `0` with stderr empty. The child's text reaches stdout only because the model read that file. The notice turn itself names `result.md` and carries no child output.
+
+With `--json` the same run printed one envelope with two entries in `turnResponses`, and `response` held the second turn's text: `The subagent reported **391**.`
+
+There is no timer. A run lasts as long as its children do, so wrap scripts in `timeout`. If the run is cut short while children are open (a failed turn, a signal, a lost connection), stderr adds `[headless:open-runs] session=<id> runs=<runId>,...`. The CLI doesn't cancel the children. Resume the session with `netclaw chat --resume <id>` to collect their results. The CLI and the daemon must be the same version. An older CLI against a current daemon exits after turn 1 and never sees the child's result, so upgrade them together.
+
+### When the turn fails
+
+A turn can fail after the daemon accepted it: the provider is unreachable, the request times out or the context overflows. `chat -p` then exits `1` and stderr ends with one `[turn:failed]` line:
+
+```
+$ netclaw chat -p "hi"
+[error] LLM provider transport error: Connection refused (llm.example.internal:8080). Check provider configuration and connectivity.
+[turn:failed] category=infra kind=ProviderFailure
+$ echo $?
+1
+```
+
+`kind` names the last error: `ModelBehavior`, `ProviderFailure`, `StreamFailure`, `Timeout`, `ToolFailure`, `InputCompatibility` or `Unknown`. The CLI adds `ChannelFailure` (the daemon is unreachable or the connection dropped) and `Cancelled` (SIGINT or SIGTERM). `category` is `model` only for `ModelBehavior`, where the model broke a rule the runtime enforces, such as returning repeated empty replies. Every other kind is `infra`, so a harness never scores a provider outage as a model failure.
+
+Stdout can still hold the text the model streamed before the failure, so don't treat non-empty output as success. With `--json`, the same failure adds `errorCategory` and `errorKind` to the envelope, and stderr carries the same two lines:
 
 ```json
-{
-  "sessionId": "a1b2c3d4",
-  "response": "Here are the running services...",
-  "toolCalls": [
-    {
-      "callId": "call_01",
-      "toolName": "shell_execute",
-      "argumentsJson": "{\"command\":\"systemctl list-units\"}"
-    }
-  ],
-  "usage": {
-    "inputTokens": 1420,
-    "outputTokens": 387,
-    "totalTokens": 1807,
-    "cachedInputTokens": 980,
-    "reasoningTokens": 0,
-    "promptMs": 142.3,
-    "predictedPerSecond": 48.2
-  },
-  "ttftMs": 342.7,
-  "totalMs": 2841.0
-}
+{"sessionId":"signalr/dc6eccdb721345a59876b82268ab41a2","response":"","turnResponses":[{"turnNumber":1,"text":""}],"totalMs":7409.3,"errorCategory":"infra","errorKind":"ProviderFailure"}
 ```
 
-Null fields are omitted — if there are no tool calls, `toolCalls` won't appear. `ttftMs` is client-side time-to-first-token; `totalMs` is the full round-trip.
+A run that ends on `ChannelFailure` or `Cancelled` prints no envelope. A turn that finishes, or that the daemon skips, exits `0`. A tool call denied for lack of approval doesn't fail the turn either: see [Approvals in headless mode](#approvals-in-headless-mode).
 
-### Named sessions in headless mode
+### JSON output
 
 ```bash
-netclaw chat -p --resume daily-report "what happened since yesterday?"
+netclaw chat -p --resume demo-notes --json "What is the codename?"
 ```
 
-Same `--resume` ID = same conversation, with full history carried forward.
+```json
+{"sessionId":"demo-notes","response":"The codename is **heron**.","turnResponses":[{"turnNumber":1,"text":"The codename is **heron**.","usage":{"inputTokens":10964,"outputTokens":9,"totalTokens":10973,"cachedInputTokens":10409,"promptMs":2020.523,"predictedPerSecond":14.11}}],"usage":{"inputTokens":10964,"outputTokens":9,"totalTokens":10973,"cachedInputTokens":10409,"promptMs":2020.523,"predictedPerSecond":14.11},"ttftMs":19174.9,"totalMs":19533.3}
+```
+
+The prefixed lines are suppressed, so you get one object. `turnResponses` is always there, with one entry per completed turn (`turnNumber`, `text`, `toolCalls`, `usage`). A run with a sub-agent has two or more. The top-level fields summarize all of them:
+
+| Field | Value |
+|-------|-------|
+| `response` | Text of the last turn only |
+| `toolCalls` | Calls from every turn, with `callId`, `toolName` and `argumentsJson`. Left out when there are none. |
+| `usage` | Token counts summed over turns. `promptMs` and `predictedPerSecond` come from the last turn that reported usage. |
+| `ttftMs` | Client-side time to first token, when present |
+| `totalMs` | The full round trip |
+| `errorCategory`, `errorKind` | Only on a failed turn |
+
+Null fields are left out.
+
+### Named sessions
+
+The same `--resume` ID means the same conversation, with history carried forward:
 
 ```bash
-# First turn: set context
 netclaw chat -p --resume deploy-check "I'm about to deploy v2.3 to production"
-
-# Second turn: ask a follow-up (same session, full history)
 netclaw chat -p --resume deploy-check "run the pre-deploy checklist"
 ```
 
-### Tool approval in headless mode
+### Approvals in headless mode
 
-Approval-gated tools are **automatically denied** in headless mode. If your script needs a tool like shell execution, set its approval policy to `Auto` in your [tool configuration](/cli/mcp-tools/) beforehand.
+Nobody can answer a prompt in a headless run, so a call that needs approval is denied and the model sees:
 
-## Examples
+```
+Tool access denied: shell_execute needs approval, and nobody can answer a prompt in an unattended run. Save an "Always" grant for this call in a chat with the same audience (for example with /run-reminder), then run it again.
+```
 
-### Quick question
+Commands that never prompt still run. The fix is a saved grant. Run the same call once in an interactive `netclaw chat` and answer **Always here**, **This repository** or **Always anywhere**. For a reminder, use [`netclaw reminder run`](/cli/reminder/). See [Run reminders, webhooks and scripts unattended](/guides/unattended-runs/).
 
-```bash
-netclaw chat -p "what's the status of the postgres backup job?"
+### When netclaw isn't set up
+
+With no `netclaw.json`, both modes print `daemon not configured - please run netclaw init` and exit `1`. With `--json` the output is:
+
+```json
+{
+  "overall": "not-configured",
+  "message": "daemon not configured - please run netclaw init"
+}
 ```
 
-### Pipe output into other tools
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | The turn finished |
+| `1` | Bad options, netclaw isn't configured, the daemon couldn't be reached, the turn failed, or the run was interrupted (SIGINT, SIGTERM, a lost connection, a daemon restart that deactivated the session, or a prompt over 512 KB) |
+| `124` | An outside `timeout` ended the run. The CLI itself has no timer, and stderr usually also holds `[turn:failed] category=infra kind=Cancelled`. |
+
+Check for `124` before you read stderr. A short network drop after the prompt was sent fails the run with exit `1`, and the daemon may still be running the prompt. Look at the session with `netclaw chat --resume <id>` before you resend.
+
+## Examples
+
+Pipe the response into another tool:
 
 ```bash
-netclaw chat -p --json "list all open incidents" | jq '.response'
+netclaw chat -p --json "list all open incidents" | jq -r '.response'
 ```
 
-### Scripted multi-turn session
+Run a multi-turn script on one session:
 
 ```bash
 SESSION="weekly-review-$(date +%Y%m%d)"
-
 netclaw chat -p --resume "$SESSION" "pull this week's metrics from grafana"
 netclaw chat -p --resume "$SESSION" "compare against last week and flag anomalies"
 netclaw chat -p --resume "$SESSION" --json "write a summary for the team" | jq -r '.response' > report.md
 ```
 
-## Related commands
+## Related pages
 
-- [`netclaw config`](/cli/config/) — Connect Slack/Discord/Mattermost channels, enable web search, set exposure mode, and configure everything `init` doesn't touch
-- [`netclaw sessions`](/cli/sessions/) — Browse and resume previous chat sessions
-- [`netclaw init`](/cli/init/) — First-run setup (configures the daemon that chat connects to)
-- [`netclaw status`](/cli/status/) — Check daemon health before starting a chat
-- [`netclaw mcp`](/cli/mcp-tools/) — Manage MCP tool servers and approval policies
+- [`netclaw sessions`](/cli/sessions/): browse and resume previous chats
+- [Slash commands](/reference/slash-commands/): commands you type inside a chat
+- [`netclaw config`](/cli/config/): connect channels, search and exposure, which `init` doesn't cover
+- [`netclaw status`](/cli/status/): check the daemon before a chat if connections fail
+- [How tool approvals work](/security/approvals/): what the prompt options mean
 
 ## Resources
 
-- [SignalR documentation](https://learn.microsoft.com/en-us/aspnet/core/signalr/introduction) — the real-time protocol between CLI and daemon
-- [jq manual](https://jqlang.github.io/jq/manual/) — handy for wrangling `--json` output in scripts
+- [SignalR documentation](https://learn.microsoft.com/en-us/aspnet/core/signalr/introduction): the real-time protocol between the CLI and the daemon
+- [jq manual](https://jqlang.github.io/jq/manual/): filter `--json` output in scripts
diff --git a/src/content/docs/cli/config.md b/src/content/docs/cli/config.md
index 9d0fd62..36f79c8 100644
--- a/src/content/docs/cli/config.md
+++ b/src/content/docs/cli/config.md
@@ -1,111 +1,211 @@
 ---
 title: "netclaw config"
-description: "Reentrant, menu-driven editor for everything that isn't part of first-run setup — channels, search, exposure, webhooks, skills, and more."
+description: "The settings dashboard for everything first-run setup skips: channels, search, webhooks, skill sources, browser automation, telemetry, security and exposure."
 ---
 
-`netclaw config` is the post-install configuration surface. Where [`netclaw init`](/cli/init/) handles first-run setup (provider, identity, security posture, features), `netclaw config` is where you configure everything else — and it's safe to re-run any time.
+`netclaw config` opens a menu-driven dashboard for every setting that [`netclaw init`](/cli/init/) doesn't ask about. Run it after `init`, and again whenever you add a channel, switch search backends or change who can reach the daemon. It's safe to re-run. Each area saves on its own, and the daemon reloads when `netclaw.json` changes.
+
+## Usage
 
 ```bash
 netclaw config
+netclaw config retention [--logs-days <days>]
 ```
 
-If netclaw hasn't been initialized yet, `netclaw config` exits non-zero and tells you to run `netclaw init` first — no TUI opens.
+`netclaw config` takes no options. `netclaw config --help` prints a short usage note, and any argument it doesn't know prints usage and exits `1`. With no `netclaw.json` both forms print "No configuration found. Run `netclaw init` first.", exit `1` and open nothing. [`netclaw config retention`](#netclaw-config-retention) is the scriptable form of the Data Retention screen.
+
+## Keys
+
+| Key | Action |
+|-----|--------|
+| `↑` / `↓` | Move through rows |
+| `Enter` | Open the selected area, or apply the selected row |
+| `Space` | Toggle a row or save a field, where the footer says so |
+| `←` / `→` | Change a choice row such as Backend or File scope |
+| `Delete` | Remove the selected list entry (skill sources, outbound webhooks) |
+| `Esc` | Back out of an area to the dashboard. Does nothing on the dashboard itself. |
+| `Ctrl+Q` | Quit from anywhere |
 
-It opens a **Settings Areas** menu with a live status summary for each area, so you can see the state of every domain at a glance.
+The footer of each screen lists the keys that apply there.
 
-![Settings Areas dashboard](/screenshots/output/config-dashboard.png)
+## The dashboard
 
-## Dashboard areas
+Run `netclaw config` and you land on the dashboard.
 
-The Settings Areas screen lists each configuration domain with a live status summary. Rows appear in this order:
+![Netclaw Config Settings Areas dashboard listing all thirteen rows from Inference Providers to Quit, each area with a status summary](/screenshots/output/config-dashboard.png)
 
-| Area | Possible status values |
-| --- | --- |
-| Inference Providers | `2 configured` |
-| Models | `claude-sonnet-4-5` |
-| Channels | `Slack · 2 channels` |
-| Inbound Webhooks | `enabled` |
-| Skill Sources | `3 dirs · 2 feeds` |
-| Search | `✓ Brave` |
-| Browser Automation | `– disabled` |
-| Telemetry & Alerting | `OTLP on · 2 webhooks` |
-| Security & Access | `Team · 4/6 enabled` |
-| Workspaces Directory | `~/netclaw-workspaces` |
+It's the demo install the other status screenshots use. In a shorter terminal the list scrolls.
 
-Selecting an area opens its editor. **Changes autosave on completion** — there is no separate save step. Press Esc or Ctrl+Q at the Settings Areas screen to quit without changes. Press Esc inside any area to back out and return to the Settings Areas screen.
+The dashboard lists thirteen rows, each with a live status summary:
 
-**Inference Providers** and **Models** route out to [`netclaw provider`](/cli/provider/) and [`netclaw model`](/cli/model/), which own those surfaces. Backing out of either returns you to the Settings Areas screen.
+| Row | Status shows | Edits |
+|-----|--------------|-------|
+| 1. Inference Providers | `1 configured` | Opens the [provider manager](/cli/provider/) |
+| 2. Models | The Main model ID, `– not set`, or `– config error` | Opens the [model manager](/cli/model/) |
+| 3. Channels | `Slack · 2 channels`, or `– none configured` | Slack, Discord and Mattermost adapters |
+| 4. Inbound Webhooks | `– disabled` or enabled | Global webhook switch and execution timeout |
+| 5. Skill Sources | `0 dirs · 0 feeds`, or `– config error` | Local skill folders and skill servers |
+| 6. Search | `✓ Brave`, `✓ SearXNG`, `✓ DuckDuckGo`, or `– disabled` when `Search.Enabled` is `false` | Search backend and credentials |
+| 7. Browser Automation | `– disabled` or enabled | The browser MCP profile |
+| 8. Telemetry & Alerting | `OTLP off · 0 webhooks` | OTLP export and outbound alert webhooks |
+| 9. Security & Access | `Personal · 6/6 enabled` | Posture, features, audience profiles, exposure mode |
+| 10. Workspaces Directory | The directory path | Project discovery root |
+| 11. Data Retention | `logs 14d` or `logs forever` | How long the daemon keeps [log files](/configuration/data-retention/) |
+| 12. Run Full Doctor | - | Exits the dashboard and runs [`netclaw doctor`](/cli/doctor/) |
+| 13. Quit | - | Exits |
 
-## Validation and save behavior
+## Save behavior
 
-Structurally invalid input (wrong type, out-of-range value) **blocks save with no override**. Failed reachability or runtime probes — such as an unreachable SearXNG endpoint or a skill feed that doesn't respond — surface a warning dialog with a **Save anyway** option, so you can persist the config and fix connectivity later.
+There's no save step for the whole dashboard. An area writes `netclaw.json` (and `secrets.json` for tokens and keys) when you finish editing it, and the screen says so. The Channels screen reads "completed changes are already saved." When `netclaw.json` changes, the running daemon drains its sessions and restarts itself. A change that only touches `secrets.json` or an environment variable needs a manual restart: `netclaw daemon stop` then `netclaw daemon start`, or `docker restart <container>`.
+
+Three outcomes can happen when you apply an area:
+
+- **It saves.** The status line goes green.
+- **A reachability or runtime probe fails.** Examples are a SearXNG endpoint that doesn't answer or a skill server that doesn't respond. A dialog offers **Retry validation**, **Back to edit** or **Save anyway**. Save anyway writes the config so you can fix connectivity later.
+- **The input is invalid.** A wrong type, an out-of-range value or an unresolved channel blocks the save, and there's no override. Fix the field or remove the entry.
 
 ## Channels
 
-Channels (Slack, Discord, Mattermost) are configured here, not in `netclaw init`. Each adapter is independently enabled, has its credentials entered, and has its channel allow-list managed from the Channels area.
+Channels are configured here, not in `init`. Each adapter is enabled on its own, takes its credentials, and keeps its own allow-list.
+
+![The netclaw config Channels area with Slack, Discord and Mattermost unchecked, and a Done adding channels row](/screenshots/output/config-channels-menu.png)
+
+Space toggles an adapter, `Enter` opens it, and **Done adding channels** returns to the dashboard.
+
+Inside an adapter, a Channels & Permissions screen sets each channel's audience and whether it needs an @mention.
+
+![netclaw config Mattermost, Channels & Permissions, with the Assistant and Ops Room channels on Team, Lunch on Public, direct messages on Personal and Require @mention off](/screenshots/output/config-channel-audiences.png)
+
+This one is Mattermost's. Left and right change the audience, Space toggles Require @mention, and `a` adds a channel.
+
+Channel entry resolves before it saves. You type a channel name or ID, and netclaw looks it up through the platform API and stores the canonical ID. The runtime matches incoming messages by ID.
+
+An unresolved channel blocks the save:
 
-Channel entry is **resolve-before-add**: you type a channel name or ID, and netclaw resolves it against the platform API to its **canonical channel ID before saving**. The stored allow-list holds IDs, not display names; display names are shown dynamically in the editor.
+```
+Could not resolve #deploys to a channel the bot can see — fix or remove before saving (an unmatchable channel grants nothing).
+```
+
+A failed lookup, such as a bad token or missing scope, blocks it the same way with `Slack channel lookup failed: <reason>`. Netclaw no longer saves unresolvable names as inert entries.
 
-When saving an adapter, any names or IDs that can't be resolved at save time are kept as inert allow-list entries and flagged with a non-blocking `Could not resolve: #name — flagged below; fix or remove them.` warning. The adapter itself saves successfully.
+Saving the Slack adapter writes these keys to `netclaw.json`: `Slack.Enabled`, `Slack.SocketMode`, `Slack.AllowDirectMessages`, `Slack.AllowedChannelIds`, `Slack.DefaultChannelId`, `Slack.AllowedUserIds`, `Slack.ChannelAudiences` and `Slack.MentionRequiredInThreadByChannel`. The bot and app tokens go to `secrets.json`. Discord and Mattermost write the same shape under their own keys.
 
 :::caution
-**Migrating from a hand-edited `netclaw.json`:** the runtime matches incoming messages by channel **ID**. If you previously placed display names in `AllowedChannelIds` by hand, re-enter those channels through `netclaw config → Channels` so they resolve to canonical IDs — otherwise those channels match nothing and their messages are denied. (`DefaultChannelName` is Slack-only and still resolved to an ID at runtime, so it's unaffected.)
+Saving Slack deletes `Slack.DefaultChannelName` and writes `Slack.DefaultChannelId` from the first allowed channel. If you hand-edited display names into `AllowedChannelIds`, re-enter those channels here so they resolve to IDs. A name left in the list matches nothing, and messages from that channel are denied.
 :::
 
-See the per-platform guides for token setup: [Slack](/channels/slack/), [Discord](/channels/discord/), [Mattermost](/channels/mattermost/).
+Token setup is in the per-platform guides: [Slack](/channels/slack/), [Discord](/channels/discord/) and [Mattermost](/channels/mattermost/).
 
-![The Channels area showing adapter selection — Slack is enabled with 2 channels and 1 user configured](/screenshots/output/config-channels-menu.png)
+## Other areas
 
-The Channels adapter list — Slack is enabled and shows 2 channels, 1 user; Discord and Mattermost are available but not yet configured.
+### Search
 
-## Other areas
+Pick a backend: DuckDuckGo needs no setup but can hit bot detection, Brave needs an API key, and SearXNG needs your instance's endpoint. The SearXNG endpoint gets a reachability probe before the save, which you can override.
+
+
+The active backend is marked `[x]`, and a check mark shows a backend that has saved setup. [Search providers](/configuration/search-providers/) has the screen.
+
+### Inbound webhooks
+
+An **Enabled** toggle (`Webhooks.Enabled`) and an execution timeout in seconds (`Webhooks.ExecutionTimeoutSeconds`, 300 by default). The screen also shows route counts. Create routes with [`netclaw webhooks`](/cli/webhooks/).
+
+
+The editor never creates routes, so a route list stays whatever `netclaw webhooks` made it. The screen is on [Webhooks](/configuration/webhooks/).
+
+### Skill sources
 
-- **Security & Access** — deployment posture, enabled features, audience profiles, and exposure mode.
-- **Search** — backend selection (Brave / SearXNG / DuckDuckGo) with progressive disclosure for the fields each backend needs; the SearXNG endpoint is validated by a reachability probe before saving (overridable).
-- **Telemetry & Alerting** — OTLP toggle and a multi-webhook list editor for outbound operational alerts; each webhook entry carries a name, URL, optional masked Authorization header, and an auto-detected format shown read-only.
-- **Inbound Webhooks** — enable inbound webhooks and set the execution timeout; route authoring is handled by [`netclaw webhooks`](/cli/webhooks/).
-- **Browser Automation** — toggle the Playwright MCP backend.
-- **Skill Sources** — local folders (added via an interactive directory picker with Ctrl+N to create inline) and remote skill feeds.
-- **Workspaces Directory** — the directory netclaw uses for project workspaces, set via an interactive directory picker.
+Add a local folder (a directory picker, `Ctrl+N` creates a folder) or connect a skill server. **Rescan all** refreshes local status and remote skill counts.
 
-![Search backend selection](/screenshots/output/config-search.png)
 
-Search — pick the backend; the active one is marked and SearXNG adds an endpoint field with the reachability probe.
+Both kinds of source are manual adds, and `Delete` removes one. See [Skills](/skills/overview/) for the screen.
 
-![Telemetry and Alerting editor](/screenshots/output/config-telemetry.png)
+### Browser automation
 
-Telemetry & Alerting — toggle OTLP export and manage the outbound alert-webhook list.
+An **Enabled** row that adds or removes the canonical browser MCP profile, and a **Backend** row you change with `←` and `→`. The backends are Playwright and Chrome DevTools. An **MCP permissions** row opens the grant editor, because tool grants for the browser live in [`netclaw mcp permissions`](/cli/mcp-tools/).
 
-![Inbound Webhooks editor](/screenshots/output/config-inbound-webhooks.png)
 
-Inbound Webhooks — global enable plus execution timeout; route files stay owned by [`netclaw webhooks`](/cli/webhooks/).
+The screen lists missing prerequisites, such as Node.js with `npx` or the Playwright browser runtime, with the commands to install them.
 
-![Exposure Mode selection](/screenshots/output/config-exposure.png)
+### Telemetry and alerting
 
-Exposure Mode (under Security & Access) — Local, Reverse Proxy, Tailscale Serve/Funnel, or Cloudflare Tunnel.
+An OTLP toggle and endpoint (`http://127.0.0.1:4317` by default), plus a list of outbound alert webhooks. Each webhook has a name, URL, an optional masked Authorization header and a format that netclaw detects from the URL.
 
-![Skill Sources editor](/screenshots/output/config-skills.png)
 
-Skill Sources — add a local folder or connect a remote skill server; both are manual adds.
+With telemetry off, the endpoint field still shows the default and the webhook list is empty.
 
-![Browser Automation editor](/screenshots/output/config-browser.png)
+### Security and access
 
-Browser Automation — toggle the Playwright MCP backend; it flags missing runtime prerequisites.
+Four sub-screens: **Security Posture**, **Enabled Features**, **Audience Profiles** and **Exposure Mode**. Posture and features are the same choices as `init`. Audience Profiles edit one audience at a time: tool groups, file scope, attachment scope, and a shortcut to MCP grants.
+
+Exposure Mode picks how the daemon is reached.
+
+![The Exposure Mode screen with five options, Local checked and marked recommended, and a warning triangle on Tailscale Funnel and Cloudflare Tunnel](/screenshots/output/config-exposure.png)
+
+The choices are Local (loopback only, the safest), Reverse Proxy, Tailscale Serve, Tailscale Funnel and Cloudflare Tunnel. Funnel and Cloudflare expose the daemon to the internet, so configure authentication first. See [Exposure modes](/deployment/exposure-modes/).
+
+### Workspaces directory
+
+The root netclaw scans for projects, set through a directory picker.
+
+
+On this picker `Esc` cancels and `Ctrl+Q` quits.
+
+### Data retention
+
+How many days the daemon keeps its own log files, including the numbered segments a busy day rolls into (`daemon-<date>.1.log`, `.2.log`, and so on, after the daily file reaches 10 MiB). One row, **Daemon and crash logs**, showing `keep 14 days (default)`, `keep 30 days` or `keep forever`.
+
+Type digits to replace the number (the first digit starts a new value, letters are ignored), `Backspace` to edit, `Enter` to save and `Esc` to go back. `0` keeps the logs forever and the maximum is `36500`. An out-of-range number is rejected with the allowed range and nothing is written. If an environment variable overrides the file, a warning says so. The newest three daemon logs and the newest three crash logs are always kept. [Data retention](/configuration/data-retention/) covers what gets deleted.
+
+![The Data Retention screen with one row, Daemon and crash logs, set to keep 14 days (default)](/screenshots/output/config-retention.png)
+
+The one row at its default. The footer lists the keys: `Enter` saves and `Esc` goes back to the settings areas.
+
+## netclaw config retention
+
+Show or set the same value without the TUI. With no option it prints the current setting.
+
+```bash
+netclaw config retention
+netclaw config retention --logs-days 30
+```
+
+```text
+Daemon and crash logs: keep 30 days
+A running daemon applies the change automatically.
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--logs-days <days>` | Days to keep daemon and crash logs. `0` keeps them forever. | `14` |
+
+Setting the value that's already in effect prints the line and no "applies" message, because nothing was written. A value that isn't a whole number from 0 to 36500, a missing value or an unknown option exits `1` and leaves the file alone:
+
+```text
+$ netclaw config retention --logs-days 36501
+--logs-days: Days must be a whole number from 0 to 36500 (0 keeps the data forever).
+```
 
-![Workspaces Directory picker](/screenshots/output/config-workspaces.png)
+| Situation | Output | Exit |
+|-----------|--------|------|
+| No `netclaw.json` | `No configuration found. Run `netclaw init` first.` | `1` |
+| `--logs-days` with no number | `--logs-days needs a number of days.` | `1` |
+| Unknown option | `Unknown option '--foo'. Run `netclaw config retention --help`.` | `1` |
+| `NETCLAW_Retention__Logs__Days` is set | The write succeeds, then `warning: NETCLAW_Retention__Logs__Days is set and overrides netclaw.json for the daemon.` on stderr | `0` |
+| `Retention` written as `"Retention": { "Logs:Days": 5 }` | `Could not use netclaw.json: Retention:Logs:Days is set in a spelling this command cannot edit. Edit netclaw.json by hand.` | `1` |
 
-Workspaces Directory — an interactive directory picker for the project workspaces root.
+The command edits `Retention.Logs.Days`, and also reads the flat `"Retention:Logs:Days"` spelling if that's what the file already uses. A stored value that isn't an integer shows as the default with a warning, and the next write replaces it.
 
 ## Related pages
 
-- [`netclaw init`](/cli/init/) — first-run setup (provider, identity, posture, features)
-- [`netclaw provider`](/cli/provider/) — inference providers
-- [`netclaw model`](/cli/model/) — model selection
-- [`netclaw webhooks`](/cli/webhooks/) — inbound webhook routes
-- [`netclaw doctor`](/cli/doctor/) — configuration and connectivity diagnostics
+- [`netclaw init`](/cli/init/): first-run setup for provider, identity and posture
+- [`netclaw provider`](/cli/provider/): the provider manager behind row 1
+- [`netclaw model`](/cli/model/): the model manager behind row 2
+- [`netclaw webhooks`](/cli/webhooks/): create the routes that inbound webhooks serve
+- [`netclaw doctor`](/cli/doctor/): validate the config you just saved
+- [Data retention](/configuration/data-retention/): what the Data Retention area deletes
 
 ## Resources
 
-- [Brave Search API](https://brave.com/search/api/) — the managed backend offered in the Search area
-- [SearXNG documentation](https://docs.searxng.org/) — self-hosted search backend and its endpoint requirements
-- [Playwright MCP](https://github.com/microsoft/playwright-mcp) — the browser-automation backend toggled in Browser Automation
+- [Brave Search API](https://brave.com/search/api/): the managed backend in the Search area
+- [SearXNG documentation](https://docs.searxng.org/): the self-hosted backend and its endpoint requirements
+- [Playwright MCP](https://github.com/microsoft/playwright-mcp): one of the two browser-automation backends
diff --git a/src/content/docs/cli/daemon.md b/src/content/docs/cli/daemon.md
new file mode 100644
index 0000000..cdfcc3e
--- /dev/null
+++ b/src/content/docs/cli/daemon.md
@@ -0,0 +1,186 @@
+---
+title: "netclaw daemon"
+description: "Start, stop and inspect the netclaw daemon, install it as a systemd service, and pair or revoke remote devices."
+---
+
+`netclaw daemon` manages the background process (`netclawd`) that runs your sessions, channels and tools. Use it to start and stop a daemon you launched by hand, to install the Linux systemd service, and to pair remote devices.
+
+## Usage
+
+```bash
+netclaw daemon <subcommand>
+```
+
+```text
+Subcommands:
+  start                        Start daemon as a background process
+  stop                         Stop daemon gracefully
+  status                       Show daemon process status (exit 1 if not running or not ready)
+  install                      Install systemd user service (Linux)
+  uninstall                    Remove systemd user service (Linux)
+  pair                         Generate a pairing code for remote device access
+  devices                      List paired devices
+  devices revoke <name>        Revoke a paired device by name
+
+start, stop, and status refuse when the PID in netclaw.pid is not shown to serve this home.
+If no Netclaw daemon of this home runs, delete <home>/netclaw.pid.
+If the process is a wedged daemon of this home, check it, then stop it with 'kill <pid>'.
+```
+
+`netclaw daemon help`, `--help`, `-h` and a bare `netclaw daemon` print the usage and exit `0` without touching the daemon. There is no `netclaw daemon restart`. That and any other unknown subcommand print the usage and exit `1`. To restart, stop and start the daemon, or use the service manager. See [Restart the daemon](#restart-the-daemon).
+
+`start`, `stop`, `status`, `install` and `uninstall` take no arguments. A trailing `--help` prints the usage instead of running the command.
+
+## Subcommands
+
+| Subcommand | What it does |
+|------------|--------------|
+| `start` | Starts the daemon. When the systemd user unit is installed and active or enabled, it runs `systemctl --user start netclaw`. Otherwise it launches `netclawd` as a detached process and waits 1.5 seconds. If that process exits in the window, the command prints the startup error from the crash log. Prints `Daemon already running (PID n).` and exits `1` when one is up. Sets `NETCLAW_HOME` in the process it launches. |
+| `stop` | Sends no signal until it knows the PID belongs to this home (see [Home check](#home-check)). Tells the daemon why it's stopping and waits up to 30 seconds for sessions to drain, then 15 more before it sends SIGKILL. When the systemd unit is running this home's daemon, it runs `systemctl --user stop netclaw` instead, so the unit doesn't bring the daemon back. |
+| `status` | Prints `Daemon running (PID 33, uptime 0m 14s).` plus a tip line pointing at `netclaw status`. Exits `1` with `Daemon is not running.`, with `Daemon process is running but <endpoint>/api/health/ready did not answer.` when the process is up and the readiness probe fails, or with `The local daemon address is unknown. No readiness probe was sent. Repair the local configuration and retry.` when the config can't be read. The probe goes to the endpoint your `netclaw.json` or `NETCLAW_*` variables name. Use [`netclaw status`](/cli/status/) for connector and model health. |
+| `install` | Writes `~/.config/systemd/user/netclaw.service` and `config/daemon.env`, enables the unit, and runs `loginctl enable-linger`. Linux only. It doesn't start the service. It checks that `systemctl --user` works first and exits `1` without writing anything when it doesn't. If `daemon.env` already exists, `install` changes only its `PATH` line and keeps every other line, such as a `NETCLAW_HOME=` you added. |
+| `uninstall` | Stops and disables the unit and removes the unit file and `daemon.env`. Your data stays. Linux only. |
+| `pair` | Prints a pairing code that expires in 5 minutes. Run it on the daemon host. |
+| `devices` | Lists paired devices with name, created and last-used time, or `No paired devices.` |
+| `devices revoke <name>` | Removes a device. Its next request gets `401`. |
+
+`start` finds the daemon binary in `NETCLAW_DAEMON_PATH`, then next to the `netclaw` binary. Both are set up for you by the install script and the Docker image.
+
+## Behavior by platform
+
+| Platform | `start`, `stop`, `status` | `install`, `uninstall` |
+|----------|--------------------------|------------------------|
+| Linux | Work | systemd user unit |
+| macOS (Apple Silicon) | Work | Refused: `Service installation is not yet supported on macOS`. Run `netclaw daemon start` yourself. |
+| Windows | Work. `stop` kills the process, because Windows has no SIGTERM equivalent, so there's no graceful drain. | Refused: `Service installation is currently Linux-only (systemd)` |
+| Docker image | `start` reports the supervisor's PID, `stop` is undone by the supervisor | Don't use. The image has no systemd. |
+
+macOS and Windows have no background service. Start the daemon from a terminal or a login script and stop it with `netclaw daemon stop`. It doesn't come back after a reboot on its own.
+
+### Home check
+
+`stop` doesn't trust `netclaw.pid` on its own. It asks the daemon at the address in this home's `netclaw.json` to confirm the PID and home. If the daemon doesn't answer, `stop` reads `NETCLAW_HOME` from `/proc/<pid>/environ`. `start` and `status` apply the same test. If none of that proves the PID serves this home, they refuse:
+
+```text
+Nothing was stopped. PID 34 is not shown to serve /tmp/h2.
+The daemon at http://127.0.0.1:5199 answered for another daemon or home. If no Netclaw daemon of this home runs, delete /tmp/h2/netclaw.pid. If PID 34 is a daemon of this home, check it, then stop it with 'kill 34' (Task Manager on Windows).
+```
+
+Exit code `1`. `start` opens with `Daemon was not started.` in place of `Nothing was stopped.`, and `status` prints the PID line and the recovery line with no `Nothing was ...` prefix. `/proc` exists only on Linux. On macOS and Windows a daemon that doesn't answer with its home, such as a 0.27.1 daemon, can't be proven, so `stop` always refuses. Stop that daemon yourself, as the refusal says.
+
+### Inside the Docker image
+
+`netclaw daemon start` never launches a second daemon. The entrypoint is PID 1 and owns the daemon, and a second `netclawd` would fight it for the lock file. With the daemon up it prints `Daemon managed by container supervisor (PID 33).` and exits `0`. With it down it says the supervisor owns startup, tells you to check the container, and exits `1`. `netclaw daemon stop` stops the daemon, prints `The container supervisor will restart the daemon.`, and the supervisor starts it again two seconds later. Use `docker restart <container>`. The image's health check is `netclaw daemon status`. See [Run netclaw in Docker](/deployment/docker/).
+
+### Under systemd
+
+With the user unit installed, `netclaw daemon stop` and `start` go through it. A daemon stopped with `netclaw daemon stop` stays stopped, even though the unit has `Restart=always`:
+
+```bash
+netclaw daemon stop     # prints "Stopped systemd user service."
+netclaw daemon status   # "Daemon is not running." (exit 1), and it stays that way
+netclaw daemon start    # prints "Started systemd user service."
+```
+
+The CLI hands the job to the unit only when the unit is running this home's daemon (or, for `start`, when it's the default home and the unit is active or enabled). A `NETCLAW_HOME` other than `~/.netclaw` never touches the unit. If the unit is installed but your shell has no user session bus, `stop` and `start` exit `1` with `Could not determine whether systemd owns the daemon lifecycle` rather than guess. Run them from a login session, or use `systemctl --user`. [`netclaw update`](/cli/update/) makes the same decision before it swaps binaries. See [systemd service](/deployment/systemd/).
+
+## Restart the daemon
+
+| Where it runs | Restart with |
+|---------------|--------------|
+| Started by hand | `netclaw daemon stop`, then `netclaw daemon start` |
+| systemd user unit | `systemctl --user restart netclaw` |
+| Docker | `docker restart <container>` |
+
+Editing `netclaw.json` restarts the daemon for you after it drains active sessions. That includes `Daemon.Host`, `Daemon.Port` and `Daemon.ExposureMode`. Changes to `secrets.json` or to environment variables need a manual restart. If the edit leaves `Models` or a provider invalid, the running daemon refuses it and keeps its previous configuration. [`netclaw status`](/cli/status/) shows `config on disk not applied: <reason>` until you fix the file.
+
+## Pair a remote device
+
+```bash
+netclaw daemon pair
+```
+
+```text
+Pairing code:  NGUL-9SE6
+Expires at:    02:50:31 (local time)
+
+On the remote device, run:
+  netclaw pair http://127.0.0.1:5199
+```
+
+That endpoint line only appears in `local` mode, where `netclaw pair` accepts it. Behind a proxy or tunnel the daemon doesn't know its public address, so it tells you to fill it in:
+
+```text
+On the remote device, run:
+  netclaw pair <https-address>
+
+The daemon does not know its public address. The daemon is exposed through reverse-proxy, and http://127.0.0.1:5199 is reachable only from this machine.
+Replace <https-address> with the HTTPS address this daemon is published at.
+```
+
+The command needs a running daemon and has to run on the daemon host. It proves that with a local key-ring proof, so it works in every [exposure mode](/deployment/exposure-modes/), even where a loopback connection isn't trusted. On the other machine, run `netclaw pair <endpoint>` with the daemon's real HTTPS address and enter the code. [Pairing remote devices](/guides/pairing-remote-devices/) has the full walkthrough. If the daemon is down, `pair` prints `error: Could not connect to daemon at <endpoint>` and exits `1`.
+
+List and revoke devices:
+
+```bash
+netclaw daemon devices
+netclaw daemon devices revoke laptop
+```
+
+```text
+Name                     Created                Last Used
+----------------------------------------------------------------------
+41468926c071-bootstrap   2026-10-07 15:35       2026-10-07 15:36
+```
+
+![Terminal showing netclaw daemon pair printing a pairing code and expiry, then netclaw daemon devices listing one paired device named alice-laptop](/screenshots/output/daemon-pair.png)
+
+The two commands back to back: a fresh code, then the device list with one paired laptop.
+
+The `-bootstrap` device is the one the daemon seeds for itself on the first non-local start.
+
+## Troubleshooting
+
+### `Failed to start daemon` with a crash message
+
+**Cause:** `start` waited 1.5 seconds and the daemon had already exited. The message is the first line of the newest `logs/crash-*.log`, such as an invalid `Daemon` section or an undecryptable secret.
+
+**Fix:** Fix the cause, or read the crash log in the [data directory](/reference/data-directory/#logs).
+
+### `Cannot install the service: systemd user services are not available on this host`
+
+**Cause:** `systemctl --user` can't reach a user session bus, as in a minimal container or an SSH session without `XDG_RUNTIME_DIR`. `install` writes nothing and exits `1`.
+
+**Fix:** Install `dbus-user-session`, log in again, or export `XDG_RUNTIME_DIR=/run/user/$(id -u)`. If you can't run systemd, start the daemon with `netclaw daemon start`. It won't restart after a crash or a reboot. See [systemd service](/deployment/systemd/#before-you-begin).
+
+### `Daemon appears running (lock file held) but PID file is missing`
+
+**Cause:** Another process holds `netclaw.lock`, but `netclaw.pid` is gone.
+
+**Fix:** The daemon ends itself shortly. If it doesn't, the message names the lock file. Find the process that holds it and stop that process with `kill <pid>`.
+
+### `PID <n> is not shown to serve <home>`
+
+**Cause:** `netclaw.pid` is stale, names a process that belongs to another home or another program, or the home can't be proven (macOS and Windows with a daemon that doesn't answer).
+
+**Fix:** If no daemon of this home is running, delete `<home>/netclaw.pid`. Otherwise check the process and stop it with `kill <pid>` (Task Manager on Windows).
+
+### `Service installed but linger failed: Could not enable linger: Access denied`
+
+**Cause:** `loginctl enable-linger` needs permission your session doesn't have. The unit is installed.
+
+**Fix:** Run `sudo loginctl enable-linger $USER`. `install` exits `1` here even though the unit is in place.
+
+## Related pages
+
+- [systemd service](/deployment/systemd/) - the unit file, logs and the upgrade routine
+- [`netclaw update`](/cli/update/) - install a new release
+- [Pairing remote devices](/guides/pairing-remote-devices/) - the full pairing walkthrough
+- [Exposure modes](/deployment/exposure-modes/) - when a daemon needs authentication from remote callers
+- [`netclaw status`](/cli/status/) - runtime health beyond process status
+
+## Resources
+
+- [systemd.service reference](https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html) - `Restart=` and `ExecStop=` semantics
+- [`loginctl enable-linger`](https://www.freedesktop.org/software/systemd/man/latest/loginctl.html) - keep user services running after logout
+- [`tini`](https://github.com/krallin/tini) - the init process the Docker image runs as PID 1
diff --git a/src/content/docs/cli/doctor.md b/src/content/docs/cli/doctor.md
index 1546921..4114e38 100644
--- a/src/content/docs/cli/doctor.md
+++ b/src/content/docs/cli/doctor.md
@@ -1,9 +1,9 @@
 ---
 title: "netclaw doctor"
-description: "Run configuration diagnostics and auto-fix common issues."
+description: "Run 24 configuration and connectivity checks, read what each failure means, and let --fix repair the safe ones."
 ---
 
-`netclaw doctor` runs 16 checks against your config files, secrets, crash logs, memory state, and connectivity. It catches things [`netclaw status`](/cli/status/) won't: broken JSON schemas, unencrypted secrets, misconfigured webhooks, stale crash logs. Doesn't need a running daemon.
+`netclaw doctor` runs 24 checks against your config files, secrets, saved grants, crash logs, memory state and connectivity. It catches what [`netclaw status`](/cli/status/) can't: broken JSON schemas, unencrypted secrets, a Slack token that stopped working, a missing PATH for the shell tool. It doesn't need a running daemon, though a few checks use one when it's there.
 
 ## Usage
 
@@ -15,10 +15,12 @@ netclaw doctor [options]
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `--fix` | Apply safe automatic fixes | Off |
-| `--dry-run` | Show planned fixes without writing (implies `--fix`) | Off |
-| `--yes`, `-y` | Skip confirmation prompt when applying fixes | Off |
-| `--format <text\|json>` | Output format | `text` |
+| `--fix` | Plan the safe automatic fixes, show a diff and apply them after you confirm | Off |
+| `--dry-run` | Show the planned fixes without writing. Implies `--fix`. | Off |
+| `--yes`, `-y` | Apply fixes without the confirmation prompt | Off |
+| `--format <text\|json>` | Output format. `--format=json` also works. | `text` |
+
+An unknown option prints `[FAIL] doctor options: Unknown doctor option: --bogus` with the help text and exits `1`.
 
 ## Output
 
@@ -26,101 +28,183 @@ netclaw doctor [options]
 netclaw doctor
 ```
 
-![netclaw doctor running all 16 diagnostic checks](/screenshots/output/doctor.png)
+![netclaw doctor printing 24 checks, all PASS, then doctor exit code: 0](/screenshots/output/doctor.png)
+
+This is a healthy Personal install, so every check passes and the last line prints exit code 0. The Secrets JSON line passes here because the demo install stores one credential. Without a `secrets.json`, a fresh install shows one `WARN` for it, and a warning alone makes the exit code 2. The lines are long, so click the image to enlarge it.
 
-Checks print as `PASS`, `WARN`, or `FAIL`:
+Each check prints `PASS`, `WARN` or `FAIL`. A failure or warning adds a `fix:` line with the next step:
 
 ```
 [PASS] Config Schema: Config matches schema v1.
-[WARN] Telemetry: Telemetry is enabled without Telemetry:Otlp:Endpoint; default endpoint will be used.
-       fix: Set 'Telemetry:Otlp:Endpoint' (e.g. http://127.0.0.1:4317).
-[WARN] Secrets JSON: secrets.json has 2 unencrypted value(s) (3 encrypted).
-       fix: Re-set secrets via 'netclaw secrets set <key> <value>' to encrypt them.
+[PASS] Tool Audience Profiles: Public and Team tool restrictions remain scoped.
+[PASS] Tool approval grants: No stored grants.
+[PASS] Security Policy: Deployment posture: Personal, Shell: HostAllowed.
+...
+[WARN] Secrets JSON: Secrets file not found at /home/netclaw/.netclaw/config/secrets.json.
+       fix: Create secrets.json if you need provider/slack credentials.
+...
+[PASS] Systemd Unit PATH: No systemd user service installed (skipping).
+
+doctor exit code: 2
 ```
 
-Failures and warnings include a `fix:` line telling you what to do. Pass `--fix` to let doctor handle the ones it can repair automatically.
+Text output ends with `doctor exit code: N`.
+
+### With only environment variables
+
+With no `netclaw.json` but `NETCLAW_*` variables set, doctor skips the checks that read the file. Five checks print `PASS` with a message like `No netclaw.json; NETCLAW_ environment configuration detected`, and the checks that need the base config print `Skipped`. A skip never counts toward the exit code. Chat Client is the exception: it evaluates the configuration the daemon would bind, environment variables included, so a missing provider or model still shows up.
+
+The launcher script in the Docker image drops environment variable names that contain a hyphen before the CLI starts, so a name like `NETCLAW_Models__Definitions__lab-main__Provider` reaches the daemon but not `netclaw doctor`, and Chat Client fails. Use names without hyphens when you want doctor to see them.
+
+### When the config can't be read
+
+If `netclaw.json` or `secrets.json` is empty, cut off, or has a duplicate key, doctor reports one failure, runs only the checks that don't read the config, and exits `1`:
 
-## Exit codes
+```text
+[FAIL] Config Load: Couldn't read netclaw.json: A duplicate key 'configVersion' was found.
+       fix: Fix the JSON in /home/netclaw/.netclaw/config/netclaw.json (a duplicate key, or a file that is empty or cut off), or restore it from a backup.
+[PASS] SQLite Provisioning: No recent daemon crash log indicates SQLite provisioning failure.
+[PASS] Image Processing: Native imaging library loaded; image egress normalization is available.
+[PASS] Systemd Unit PATH: No systemd user service installed (skipping).
+[WARN] Skipped checks: 21 check(s) skipped: the config could not be read.
+
+doctor exit code: 1
+```
+
+`--fix` does nothing here and says why (`Nothing was fixed. Couldn't read netclaw.json: ...`). Repair the file by hand, then run doctor again. See [`Couldn't read netclaw.json`](/troubleshooting/common-problems/#couldnt-read-netclawjson).
+
+### Exit codes
 
 | Code | Meaning |
 |------|---------|
-| `0` | All checks passed |
-| `1` | One or more checks failed |
-| `2` | Warnings only, no failures |
+| `0` | Every check passed |
+| `1` | One or more checks failed, or an option was wrong |
+| `2` | Warnings only |
 
-Note: the [CLI overview](/cli/overview/) documents exit code `2` as "usage/argument error" for most commands. `doctor` is an exception — it uses `2` specifically for warnings-only results.
+`2` isn't an error here, and it's easy to hit: a missing `secrets.json` or an available update is a warning. Skipped checks never count.
 
-Skipped checks (Slack checks when Slack is disabled, etc.) don't affect the exit code.
+:::caution[A hand-written config needs `Tools` and `Security` sections]
+A `netclaw.json` with no `Tools` section fails Tool Audience Profiles (`Tools section is missing; tool trust policy cannot be evaluated`), and one with no `Security` section fails Security Policy (`Security section is missing; strict fallback defaults are active (Public posture, shell disabled)`). Doctor exits `1` either way, and the daemon denies `shell_execute` because the config gets the strict Public posture. Configs written by `netclaw init` have both. If you write the file yourself, add them. For a Personal install that runs shell commands:
 
-Wire it into a script:
+```json
+"Tools": { "ShellMode": "HostAllowed" },
+"Security": { "DeploymentPosture": "Personal", "ShellExecutionMode": "HostAllowed", "StrictDefaults": true }
+```
+
+Or run [`netclaw init`](/cli/init/) to write both for you.
+:::
 
 ```bash
 netclaw doctor > /dev/null 2>&1
-rc=$?
-case $rc in
+case $? in
   0) echo "clean" ;;
-  2) echo "warnings — review with 'netclaw doctor'" ;;
-  *) echo "failures — run 'netclaw doctor --fix'" ;;
+  2) echo "warnings: review with 'netclaw doctor'" ;;
+  *) echo "failures: run 'netclaw doctor --fix'" ;;
 esac
 ```
 
-## Checks
-
-Doctor runs these in order. Checks that don't apply to your config get skipped.
-
-Config files live under `~/.netclaw/config/`: `netclaw.json` for settings, `secrets.json` for credentials.
-
-| Check | What it validates |
-|-------|-------------------|
-| **Config Schema** | `netclaw.json` parses, has valid `configVersion`, matches JSON schema |
-| **Tool Audience Profiles** | Public/team/personal audience profiles don't grant excessive tool access |
-| **Security Policy** | `DeploymentPosture` is set; errors if null with `StrictDefaults` disabled |
-| **Slack ACL** | Warns if no channel allow-list and no default channel are configured; warns if DMs enabled with no `AllowedUserIds` |
-| **Telemetry** | Warns if [OTLP](https://opentelemetry.io/docs/specs/otel/protocol/) endpoint is absent; errors if present but not a valid absolute URI (skipped if telemetry disabled) |
-| **Secrets JSON** | File exists, valid JSON, correct Unix permissions (`600`), values are encrypted |
-| **Slack Auth** | Live API call to verify [bot token](https://api.slack.com/authentication/token-types#bot) works |
-| **SQLite Provisioning** | Inspects the most recent crash log for SQLite-related failures |
-| **Daemon Crash Logs** | Checks for crash files in the last 7 days (in `~/.netclaw/logs/`) |
-| **Memory Checkpoint Health** | Opens memory DB, checks pending checkpoint backlog |
-| **mcp-servers** | Validates MCP server config and live status |
-| **Context Window** | `Models.Main.ContextWindow` is set and valid; warns if absent (defaults to 32,768 tokens) |
-| **Update** | Checks for a newer netclaw version (5s network timeout) |
-| **Webhook Format** | Flags Slack webhooks using Generic format instead of Slack format |
-| **Inbound Webhook Routes** | Validates route JSON files in `~/.netclaw/config/webhooks/` |
-| **exposure-mode** | Validates exposure mode matches running services (`tailscaled`, `cloudflared`, etc.) |
-
-The **mcp-servers** check hits the daemon API for live MCP status but falls back to offline config probes if the daemon isn't running. **Slack Auth** requires network access and will fail in air-gapped environments.
+## The checks
+
+Doctor runs the checks in this order. Config files live under `~/.netclaw/config/`.
+
+| # | Check | Warns or fails when |
+|---|-------|---------------------|
+| 1 | **Config Schema** | `netclaw.json` isn't valid JSON, has a bad `configVersion`, or doesn't match the schema. A missing `configVersion` warns. |
+| 2 | **Tool Audience Profiles** | `netclaw.json` has no `Tools` section. Also fails when a Public or Team profile sets `ToolsMode`, `McpServersMode` or a file mode to `All`. Fails when a `ToolOverrides` or `McpServerDefaults` key contains a colon, such as `file_write:control-plane`. The key is ignored and `--fix` doesn't touch it. Valid forms are `tool_name`, `server/tool` and `server__tool`. In 0.27.1 and earlier a colon key silently bound the tool to Auto. Warns when an override key has no value (`null`, `{}`, `[]`) or can't be a tool name, a profile's `WriteFiles` is wider than its `ReadFiles`, the sessions directory sits under the OS temp directory, an MCP server has no grants or approval default, the Personal allowlist excludes an enabled MCP server, a Public or Team `AllowedTools` list lacks `tool_output_read`, `shell_execute` is set to `Approval` while `ShellMode` is `Off`, or Personal sets `shell_execute` to `Auto`. |
+| 3 | **Tool approval grants** | A saved grant in `tool-approvals.json` is covered by another grant. Warns, and `--fix` removes the redundant ones. |
+| 4 | **Security Policy** | There is no `Security` section (strict fallback defaults, Public posture, shell off), or `DeploymentPosture` is null with `StrictDefaults` off. Warns when the posture is unset and falls back to Public, when an implicit Personal posture allows host shell, or when `Tools.ShellMode` differs from `Security.ShellExecutionMode`. The daemon uses `Tools.ShellMode`. |
+| 5 | **Slack ACL** | Slack is enabled with no channel allow-list and no default channel, so channel traffic is denied. Warns when DMs are on with no `AllowedUserIds`. |
+| 6 | **Telemetry** | OTLP is on with no endpoint (warning) or an endpoint that isn't an absolute URI (failure) |
+| 7 | **Secrets JSON** | The file is missing or has unencrypted values (warning), mode wider than `600` (warning, with a `chmod 600` fix), or won't parse (failure) |
+| 8 | **OAuth Token Expiry** | Never changes the exit code. Passes, and the message names each `Providers.<name>.OAuthTokenExpiry` key still in `netclaw.json` and says to run `netclaw doctor --fix`. |
+| 9 | **Slack Auth** | The bot token is missing, or a live Slack API call rejects it. Needs network access. |
+| 10 | **SQLite Provisioning** | The latest crash log shows the daemon couldn't initialize SQLite |
+| 11 | **Image Processing** | The native imaging library failed to load, so image attachments can't be resized for the model |
+| 12 | **Daemon Crash Logs** | There are crash logs in the last 7 days under `~/.netclaw/logs/` |
+| 13 | **Memory Checkpoint Health** | The memory database can't be opened, or it has a backlog of pending checkpoints |
+| 14 | **Memory Curation LLM** | The curation model (the Main role) is failing or timing out in the last 14 days of logs |
+| 15 | **Memory Embeddings** | The embedding model isn't provisioned or fails its hash check, or some documents lack a current-model embedding |
+| 16 | **Memory Relevance Gate** | The relevance model isn't provisioned or fails its hash check, or the gate is on while embeddings are off |
+| 17 | **mcp-servers** | MCP config is malformed, or live status shows an unreachable or auth-failed server. Falls back to offline probes with no daemon. |
+| 18 | **Chat Client** | The provider or model is missing or invalid. A warning means the daemon will run the No-Op chat client and answer with a configuration banner. A failure (`Invalid model configuration: model '<role>': ... Daemon startup will fail until this is resolved.`) means the daemon won't start. A hand-edited `Thinking` level the provider can't send causes it, including a missing `Providers:<name>:VendorOptions:ThinkingDialect` on an `openai-compatible` provider. The fix line names `netclaw model set <role> <provider> <model> --thinking <level>` or `--clear-thinking`. A daemon that is already running refuses to reload the file and keeps its previous configuration, and [`netclaw status`](/cli/status/#when-the-config-on-disk-isnt-applied) shows `degraded`. |
+| 19 | **Context Window** | The model config is invalid (same `Invalid model configuration:` text as Chat Client), no context window can be resolved, or a pinned `Models.Main.ContextWindow` disagrees with the running daemon |
+| 20 | **Update** | A newer version exists (warning). The check times out after 5 seconds and passes. |
+| 21 | **Webhook Format** | A Slack outbound webhook uses the Generic format, which Slack rejects |
+| 22 | **Inbound Webhook Routes** | Inbound webhooks are enabled with no valid route, or a route file under `config/webhooks/` is invalid |
+| 23 | **exposure-mode** | `Daemon.ExposureMode` is unknown, `TrustedProxies` has a bad entry, or paired devices exist but the local device token doesn't match |
+| 24 | **Systemd Unit PATH** | The systemd user unit doesn't give the daemon's shell tool a PATH that includes its install directory. Skipped off Linux or with no unit. |
+
+Chat Client and Context Window don't need a daemon, but Context Window reads the live value from one when it's running. Without a context window in config, Context Window passes with `Auto-detected N tokens`, taking the value from the running daemon first and the provider second. It only warns when neither answers.
+
+### Reading a failure
+
+Run the fix that the line names:
+
+| Check | Typical fix |
+|-------|-------------|
+| Config Schema | `netclaw doctor --fix --dry-run` to preview repairs, or correct the field it names |
+| Secrets JSON | `chmod 600` the file, or re-enter values with [`netclaw secrets set`](/cli/secrets/) to encrypt them |
+| Slack ACL | Set `Slack:AllowedChannelIds` or a default channel in [`netclaw config`](/cli/config/) |
+| Slack Auth | Check the bot token and scopes in your Slack app |
+| Chat Client | Run [`netclaw init`](/cli/init/), or `netclaw provider add` then `netclaw model set main ...` |
+| Memory Embeddings | Restart the daemon, or run [`netclaw memory backfill-embeddings`](/cli/memory/) |
+| Daemon Crash Logs | Read `~/.netclaw/logs/crash-*.log` and run `netclaw daemon status` |
+| Systemd Unit PATH | Run `netclaw doctor --fix`, then `systemctl --user restart netclaw` |
 
 ## Auto-fix
 
-`--fix` handles these issues in `~/.netclaw/config/netclaw.json`:
-
-- Missing `configVersion` (inserts `1`)
-- Slack enabled with no channel allow-list *and* no default channel (inserts empty `AllowedChannelIds`)
-- Telemetry enabled with no OTLP endpoint (inserts `http://127.0.0.1:4317`)
-- Slack webhooks using Generic format (corrects to `"Slack"`)
-- Schema mismatches: enum int-to-string conversion, removing disallowed properties, inserting missing required properties with schema defaults
-
-Unencrypted secrets, invalid bot tokens, and missing external services need manual work. The `fix:` lines in doctor's output tell you what to do.
+`--fix` plans every repair it can make, prints a diff per file and asks `Apply these fixes? [y/N]:` before writing. Run it with `--dry-run` to see the plan only. With nothing to repair it prints `No safe autofixes available.` After the repairs it prints `Backed up the original to <path>` for each backup it wrote and runs the checks again, so the output shows the result.
 
-Before writing anything, `--fix` shows a diff:
+```bash
+netclaw doctor --fix --dry-run
+```
 
 ```
+Planned fixes (dry-run):
+- /home/netclaw/.netclaw/config/netclaw.json
+  Apply safe configuration autofixes (Removed disallowed property /Daemon/ObsoleteFlag).
+  Original is backed up to /home/netclaw/.netclaw/config/netclaw.json.removed-keys.bak before the change.
   --- before
   +++ after
-  - "configVersion": null,
-  + "configVersion": 1,
+  ...
 ```
 
-Then prompts `Apply these fixes? [y/N]:`.
+`--fix` repairs these in `netclaw.json`:
 
-### Preview without writing
+- A missing `configVersion` (inserts `1`)
+- Inline `Models` roles migrated to named definitions
+- Public or Team `AllowedTools` lists that are exact copies of a shipped default (deleted, so the audience follows the default)
+- Slack enabled with no channel allow-list and no default channel (inserts an empty `AllowedChannelIds`)
+- Telemetry on with no OTLP endpoint (inserts `http://127.0.0.1:4317`)
+- Slack webhooks using the Generic format (set to `Slack`)
+- Retired `Providers.<name>.OAuthTokenExpiry` keys, moved into the provider's entry in `secrets.json` (the date is copied first, then the key is removed). A key whose value isn't null or a date stays.
+- Schema mismatches: enum integers to strings, disallowed properties removed, missing required properties filled with schema defaults
 
-```bash
-netclaw doctor --dry-run
-```
+`--fix` migrates inline `Models` roles to named definitions, but it never removes a key under `Models`, and it never removes a key that holds a credential (a token, password, API key, or a URL with a password or webhook secret in it). Those are reported by Config Schema and left for you to fix by hand, because a removal there could lose a value with no replacement.
+
+It also touches two other files:
+
+- `~/.netclaw/config/daemon.env`, the PATH file for the systemd unit, gets its `PATH` line replaced (or appended) from your current PATH when it's missing or lacks the daemon's install directory. Every other line, such as a `NETCLAW_HOME=` you added, stays as it is. Restart the daemon afterwards with `systemctl --user restart netclaw`.
+- `~/.netclaw/config/tool-approvals.json` loses grants that another saved grant already covers. The other grants stay.
+
+A fix that deletes or rewrites your data copies the original file first. Every backup is written before the first file changes, so a failed backup (doctor exits `1`) leaves everything as it was. Each backup name gets a number when an older one exists, and an older backup is never overwritten:
+
+| Fix | Backup |
+|-----|--------|
+| Models migrated to named definitions | `netclaw.json.legacy-models.bak`, then `.legacy-models.2.bak` and so on |
+| Copied default tool lists removed | `netclaw.json.legacy-tool-defaults.bak`, then `.legacy-tool-defaults.2.bak` and so on |
+| Retired `OAuthTokenExpiry` keys moved | `netclaw.json.retired-oauth-expiry.bak`, then `.retired-oauth-expiry.2.bak` and so on. `secrets.json` gets no backup. |
+| Disallowed properties removed | `netclaw.json.removed-keys.bak`, then `.removed-keys.2.bak` and so on |
+
+The rewritten file keeps the permissions of the original. A `netclaw.json` with comments or trailing commas isn't changed at all: `--fix` prints `Nothing was fixed. Couldn't read netclaw.json: it has comments or trailing commas...` on stderr.
 
-Same diff output, nothing written. Good for CI.
+Other fixes write with no backup, so use `--dry-run` first on a config you care about. Unencrypted secrets, a rejected Slack token and missing external services need manual work, and the `fix:` lines say what to do.
+
+After a failing or warning run without `--fix`, doctor adds a hint when a plan exists:
+
+```
+hint: Some issues may be auto-fixable. Run `netclaw doctor --fix --dry-run` to preview.
+```
 
 ## JSON output
 
@@ -130,13 +214,13 @@ netclaw doctor --format json
 
 ```json
 {
-  "exitCode": 0,
+  "exitCode": 2,
   "checks": [
     {
-      "name": "Config Schema",
-      "severity": "pass",
-      "message": "Config matches schema v1.",
-      "remediation": null
+      "name": "Secrets JSON",
+      "severity": "warning",
+      "message": "Secrets file not found at /home/netclaw/.netclaw/config/secrets.json.",
+      "remediation": "Create secrets.json if you need provider/slack credentials."
     }
   ],
   "fix": {
@@ -148,56 +232,34 @@ netclaw doctor --format json
 }
 ```
 
-Severity values are lowercase: `"pass"`, `"warning"`, `"error"`. Parse with [jq](https://jqlang.github.io/jq/manual/):
+With `--format json`, the `Backed up the original to <path>` line goes to stderr, so stdout holds only the JSON document. Without `--yes`, the `Apply these fixes? [y/N]:` prompt still writes to stdout, so add `--yes` when you pipe a JSON `--fix` run. Severities are lowercase: `pass`, `warning` and `error`. With `--fix`, `fix.files` lists each `path` and `description`.
 
 ```bash
-# List all failures
 netclaw doctor --format json | jq '[.checks[] | select(.severity == "error")]'
-
-# Count warnings
 netclaw doctor --format json | jq '[.checks[] | select(.severity == "warning")] | length'
+netclaw doctor --format json --dry-run | jq -e '.exitCode == 0'
 ```
 
-## Common workflows
-
-### Post-init verification
-
-After running [`netclaw init`](/cli/init/), run doctor right away:
-
-```bash
-netclaw doctor
-```
-
-Doctor checks things that init's built-in health check skips: crash logs, memory state, webhook routes.
-
-### Crash triage
-
-When the daemon crashes or behaves unexpectedly:
-
-```bash
-netclaw doctor
-```
+The last one works as a CI gate. `--dry-run` writes nothing, and the exit code still reflects the real checks.
 
-**Daemon Crash Logs** and **SQLite Provisioning** scan for recent crash files and storage-related failures. Start there before digging through raw logs.
+## Common workflows
 
-### CI health gate
+**After init.** Run `netclaw doctor` right after [`netclaw init`](/cli/init/). It checks things init's health check skips: crash logs, memory state, webhook routes and saved grants.
 
-```bash
-netclaw doctor --format json --dry-run | jq -e '.exitCode == 0'
-```
+**Crash triage.** When the daemon crashes or misbehaves, start with Daemon Crash Logs and SQLite Provisioning before you read raw logs.
 
-`--dry-run` ensures no files are written — safe for read-only CI runners. Exit code still reflects real check results, so unfixed issues cause a non-zero exit.
+**After an upgrade.** If an older release left copied default tool lists or a retired `OAuthTokenExpiry` key in `netclaw.json`, `netclaw doctor --fix` fixes them and keeps a backup. See [Upgrade netclaw](/guides/upgrading/).
 
-## Related commands
+## Related pages
 
-- [`netclaw status`](/cli/status/) — live runtime health (requires the daemon; doctor doesn't)
-- [`netclaw init`](/cli/init/) — first-run wizard. Run doctor right after
-- [`netclaw mcp-tools`](/cli/mcp-tools/) — manage the MCP tool servers doctor validates
-- [`netclaw secrets`](/cli/secrets/) — manage the secrets doctor checks for encryption
+- [`netclaw status`](/cli/status/): live runtime health, which needs the daemon
+- [`netclaw init`](/cli/init/): the first-run wizard, followed by doctor
+- [`netclaw mcp`](/cli/mcp-tools/): manage the MCP servers that doctor validates
+- [`netclaw secrets`](/cli/secrets/): encrypt the values doctor flags
+- [`netclaw approvals`](/cli/approvals/): review the grants doctor reports
 
 ## Resources
 
-- [jq manual](https://jqlang.github.io/jq/manual/) — filter and transform `--format json` output
-- [jq download](https://jqlang.github.io/jq/download/) — install jq if you don't have it
-- [OpenTelemetry collector docs](https://opentelemetry.io/docs/collector/) — if the Telemetry check flags your OTLP endpoint
-- [Slack bot token types](https://api.slack.com/authentication/token-types#bot) — if the Slack Auth check fails
+- [jq manual](https://jqlang.github.io/jq/manual/): filter `--format json` output
+- [Slack bot token types](https://api.slack.com/authentication/token-types#bot): if Slack Auth fails
+- [OpenTelemetry Collector docs](https://opentelemetry.io/docs/collector/): if Telemetry flags your OTLP endpoint
diff --git a/src/content/docs/cli/init.md b/src/content/docs/cli/init.md
index 6c5d875..6bd5fd8 100644
--- a/src/content/docs/cli/init.md
+++ b/src/content/docs/cli/init.md
@@ -3,7 +3,7 @@ title: "netclaw init"
 description: "First-run setup wizard: provider, identity, security posture, enabled features, and health check."
 ---
 
-`netclaw init` runs the bootstrap wizard — four or five steps depending on your security posture — that get netclaw from zero to a working chat session. Run it once on a fresh install. If you need to adjust channels, search, exposure mode, or skills after setup, use [`netclaw config`](/cli/config/) instead.
+`netclaw init` is the first-run wizard. It takes a fresh install to a working chat session in four steps (Personal posture) or five (Team and Public). Run it once. For channels, search, exposure mode and skill sources, use [`netclaw config`](/cli/config/) afterwards.
 
 ## Usage
 
@@ -11,70 +11,86 @@ description: "First-run setup wizard: provider, identity, security posture, enab
 netclaw init
 ```
 
+`init` has no flags and no non-interactive mode. To set up a machine without a terminal, write `netclaw.json` yourself or pass `NETCLAW_*` environment variables, as the [Docker deployment](/deployment/docker/) page does.
+
+:::caution
+Netclaw 0.27.1 and earlier wrote every keystroke typed into `init` and the other full-screen commands, API keys and tokens included, to `netclaw-<command>-trace.log` in the temp directory. 0.28.0 removed it ([GHSA-mh95-h6p6-c9j3](https://github.com/netclaw-dev/netclaw/security/advisories/GHSA-mh95-h6p6-c9j3)). If you ran those commands on an older build, delete the leftover files and rotate the secrets you typed. See [Upgrading](/guides/upgrading/).
+:::
+
 ## Before you begin
 
-- **LLM provider credentials** — an [OpenRouter](https://openrouter.ai/docs) API key (easiest) or [Ollama](https://ollama.com/download) installed locally
-- **Anthropic, OpenAI, or other cloud-provider API key** if not using OpenRouter
+- An LLM provider: an [OpenRouter](https://openrouter.ai/docs) API key is the quickest, or [Ollama](https://ollama.com/download) running locally. Anthropic, OpenAI, DeepSeek, Venice.ai and GitHub Copilot work too.
+- Nothing for channels, search, browser automation or network exposure. All of that is in `netclaw config`.
+
+## Keys
 
-Channel tokens (Slack, Discord, Mattermost), search providers, browser automation, skill sources, and network exposure are all configured in `netclaw config` after init — you don't need them now.
+| Key | Action |
+|-----|--------|
+| `↑` / `↓` | Move through a list |
+| `Enter` | Accept and go to the next screen |
+| `Space` | Toggle a feature (feature step only) |
+| `Esc` | In the wizard, go back one screen. Does nothing on the first screen. On the existing-install menu it quits `init`. See [existing install](#running-init-on-an-existing-install). |
+| `Ctrl+Q` | Quit |
 
 ## Wizard steps
 
-The wizard counts steps dynamically: **4 steps** for Personal posture (the Enabled Features step is skipped), **5 steps** for Team or Public.
+The header counts steps as "of 5" until you pick a posture. Choose Personal and the count drops to 4.
 
-### Step 1 — Provider
+### 1. Provider
 
-Pick an LLM provider, enter credentials, and select a default model.
+Pick a provider, enter credentials, and choose a default model.
 
-![Provider selection list](/screenshots/output/init-01-provider-list.png)
+![Netclaw Setup, Step 1 of 5, LLM Provider, with eight providers listed and Anthropic highlighted](/screenshots/output/init-01-provider-list.png)
 
-Available providers: Anthropic, GitHub Copilot, Ollama, OpenAI, llama.cpp / vLLM, OpenRouter, and Venice.ai. Self-hosted backends (Ollama, llama.cpp / vLLM) prompt for an endpoint URL next.
+The wizard lists Anthropic, DeepSeek, GitHub Copilot, Ollama, OpenAI, OpenAI-compatible (llama.cpp / vLLM / DwarfStar ds4), OpenRouter and Venice.ai. Ollama and OpenAI-compatible ask for an endpoint next.
 
-![Endpoint configuration](/screenshots/output/init-01-endpoint.png)
+The endpoint field arrives pre-filled with `http://localhost:11434` and the cursor sits at the end, so press `Backspace` to clear the default before you type your own. Enter the server address, such as `http://llm.example.internal:8080`, with or without `/v1`. If the connectivity check fails, press `Enter` to retry, `M` to type a model ID by hand, or `Esc` to go back.
 
-After credentials pass a connectivity check, you pick a default model from the discovered list.
+Hosted providers ask for an API key. Self-hosted ones treat the key as optional.
 
-![Model selection](/screenshots/output/init-01-model-select.png)
+Once the connectivity check passes, pick a default model from the discovered list, or choose **Enter model ID manually...**.
 
-Add or swap providers later with [`netclaw provider`](/cli/provider/). Reassign model roles without re-running init with [`netclaw model`](/cli/model/).
+![Model selection step listing one discovered model, qwen2:0.5b, and an Enter model ID manually option](/screenshots/output/init-01-model-select.png)
 
-### Step 2 — Identity
+The discovered models come first and the manual entry is always the last row. Add or swap providers later with [`netclaw provider`](/cli/provider/), and reassign roles with [`netclaw model`](/cli/model/).
 
-Four substeps in order: **agent name → communication style → your name → timezone**.
+### 2. Identity
 
-| Substep | Prompt | Notes |
-|---------|--------|-------|
-| Agent name | `Agent name:` | Defaults to `Netclaw` if left blank |
-| Communication style | `Communication style:` | Choose: Concise & casual, Concise & formal, Detailed & casual, Detailed & formal |
-| Your name | `Your name:` | Optional — used to personalize responses |
-| Timezone | `Your timezone:` | Defaults to local system timezone |
+Four prompts in order:
 
-![Identity step — communication style](/screenshots/output/init-02-identity.png)
+| Prompt | Notes |
+|--------|-------|
+| `Agent name:` | `Netclaw` if you leave it |
+| `Communication style:` | Concise & casual, Concise & formal, Detailed & casual or Detailed & formal |
+| `Your name:` | So the agent knows what to call you |
+| `Your timezone:` | An IANA id such as `America/Chicago`. Starts as `UTC`. Used for time-aware answers and scheduling |
 
-:::note
-Webhook URLs and workspace directories are **not** collected here — they're post-install settings in `netclaw config`.
-:::
+![Netclaw Setup, Step 2 of 5, Identity, asking for a communication style with four options](/screenshots/output/init-02-identity.png)
+
+The communication style is the second of the four identity prompts. A timezone that isn't an IANA id gets an inline message such as `Unknown time zone 'Foo/Bar'. Use an IANA id such as America/Chicago.`, and `Central Standard Time` is refused because it has spaces. On a minimal Linux image without `tzdata`, every zone except `UTC` is refused. Webhook URLs and the workspaces directory aren't asked here. They live in `netclaw config`.
 
-### Step 3 — Security Posture
+### 3. Security posture
 
-![Security posture selection](/screenshots/output/init-02-security-posture.png)
+Pick who will use this instance.
 
-Three postures are listed with a brief annotation; the hint line below explains the shell-access implications of each.
+![Netclaw Setup, Step 3 of 5, Security Posture, listing Personal, Team and Public with a short explanation under the list](/screenshots/output/init-02-security-posture.png)
 
-| Posture | Who uses it | Shell access | Enabled Features step |
-|---------|------------|--------------|----------------------|
-| **Personal** | Single user, high trust | Enabled with approval gates | Skipped (all features on by default) |
-| **Team** | Multiple users, medium trust | Off | Shown (all features on by default) |
-| **Public** | Untrusted users, low trust | Off | Shown (all features off by default) |
+The grey text under the list summarizes what each posture allows.
 
-You can tighten or loosen per-channel behavior later in `netclaw config`.
+| Posture | For | Shell tool | Feature step |
+|---------|-----|------------|--------------|
+| **Personal** | You, on this machine | On, with approval prompts | Skipped, all features on |
+| **Team** | Trusted teammates | Off | Shown, all features on |
+| **Public** | Untrusted users | Off | Shown, all features off |
 
-### Step 4 — Enabled Features *(Team and Public only)*
+The wizard writes the posture, not per-audience tool lists. See [what init writes](#what-init-writes). The hint on this screen points to **Channels** in `netclaw config` for per-channel overrides.
 
-Six toggles that control what's available across all audiences:
+### 4. Enabled features (Team and Public only)
 
-| Feature | Config key |
-|---------|-----------|
+Six toggles that apply to every audience:
+
+| Feature | Key written |
+|---------|-------------|
 | Memory | `Memory.Enabled` |
 | Search | `Search.Enabled` |
 | Skills | `SkillSync.Enabled` |
@@ -82,89 +98,120 @@ Six toggles that control what's available across all audiences:
 | SubAgents | `SubAgents.Enabled` |
 | Webhooks | `Webhooks.Enabled` |
 
-Space to toggle, Enter to continue. Personal posture skips this step entirely — all features are on by default.
+Press `Space` to toggle and `Enter` to continue.
 
-![Feature selection on Team posture](/screenshots/output/init-04-enabled-features.png)
+![Netclaw Setup, Step 4 of 5, Feature Selection, with Memory, Search, Skills, Scheduling, SubAgents and Webhooks all checked](/screenshots/output/init-04-enabled-features.png)
 
-All six features default to enabled on Team posture; Public posture defaults them all off.
+This is the Team posture, which starts with all six on. Public starts with all six off.
 
-### Step 5 — Health Check
+### Health check
 
-Press Enter to run the health checks. The wizard validates config files, tests provider connectivity, and starts the daemon.
+The last step starts by itself when you leave the previous one. There's no extra `Enter`. It ticks off the provider, the model and the memory backend, writes the configuration, applies it to the daemon and validates the result.
 
-![Health check running](/screenshots/output/init-05-health-check.png)
+![Netclaw Setup, Step 4 of 4, Health Check, four green checks and an Applying configuration spinner](/screenshots/output/init-05-health-check.png)
 
-On a clean pass — all probes green — the wizard writes config and launches `netclaw chat` automatically. No extra confirmation needed.
+That's the Personal run, ending at 4 of 4. Team and Public have the extra features step, so their health check reads Step 5 of 5. The checks are identical and only the counter differs.
 
-If any check fails, the wizard stays on the summary screen and shows:
+On a clean pass the wizard opens `netclaw chat` and your agent introduces itself. If anything fails, the failed check shows `✗`, and you stay on the summary with:
 
+```text
+Setup complete with warnings. Run `netclaw daemon start`, then `netclaw chat --onboarding`. Adjust settings with `netclaw config`.
 ```
-Setup complete with warnings. Run `netclaw daemon start`, then `netclaw chat`. Adjust settings with `netclaw config`.
+
+Files written before a failure stay on disk. Fix the cause (on a bare Linux image it's usually a missing `libicu`, see [installation troubleshooting](/getting-started/installation/#failed-to-start-daemon-process-exited-with-code-134)), run `netclaw daemon start`, then `netclaw chat --onboarding`. That command starts the identity interview the wizard would have opened. [`netclaw doctor`](/cli/doctor/) shows what else is wrong.
+
+## What init writes
+
+Here's the Personal config from a real run against an OpenAI-compatible server. The model key is `<provider>-<model id>`, so a model named `demo-model` becomes `openai-compatible-demo-model`:
+
+```json
+{
+  "configVersion": 1,
+  "Providers": {
+    "openai-compatible": { "Type": "openai-compatible", "Endpoint": "http://llm.example.internal:8080" }
+  },
+  "Models": {
+    "Definitions": {
+      "openai-compatible-demo-model": {
+        "Provider": "openai-compatible",
+        "ModelId": "demo-model",
+        "Provenance": "Live"
+      }
+    },
+    "Roles": { "Main": "openai-compatible-demo-model" }
+  },
+  "Security": { "DeploymentPosture": "Personal", "ShellExecutionMode": "HostAllowed", "StrictDefaults": true },
+  "Tools": { "ShellMode": "HostAllowed" },
+  "Identity": { "AgentName": "Netclaw", "CommunicationStyle": "Concise & casual", "UserTimezone": "UTC", "UserName": "Sam" }
+}
 ```
 
-If init fails partway through, the files it already wrote stay on disk. Rerun `netclaw init` or inspect the saved config and run `netclaw doctor` before trying again.
+| File | Contents |
+|------|----------|
+| `~/.netclaw/config/netclaw.json` | The config above. Team and Public add `Memory`, `Search`, `SkillSync`, `Scheduling`, `SubAgents` and `Webhooks` blocks with `Enabled`, and set `ShellExecutionMode` and `Tools.ShellMode` to `Off`. |
+| `~/.netclaw/config/secrets.json` | Only if you entered an API key. Credentials are encrypted. |
+| `~/.netclaw/identity/` | `SOUL.md`, `AGENTS.md` and `TOOLING.md` for the agent's personality and rules |
+| `~/.netclaw/agents/` | Four [sub-agent](/skills/custom-subagents/) profiles: `task-worker`, `research-assistant`, `code-analyst` and `summarizer`. Profiles that already exist are never overwritten. |
 
-## Existing install
+`init` writes the posture, not `Tools.AudienceProfiles`. The daemon computes the per-audience profiles from the posture, so an absent profile is normal.
 
-Running `netclaw init` when `~/.netclaw/config/netclaw.json` already exists opens an action menu instead of the bootstrap wizard.
+## Running init on an existing install
 
-![Existing-install action menu](/screenshots/output/init-existing-menu.png)
+When `~/.netclaw/config/netclaw.json` exists, `init` opens an action menu instead of the wizard. Nothing changes until you confirm an action. The exception is the seed that `install.sh --channel` and `install.ps1` write, a config holding only `configVersion` and `Daemon.UpdateChannel`. That one opens the first-run wizard. A config `init` can't read still opens the menu, so a damaged file is never written over.
+
+![Netclaw Setup menu reading Existing Netclaw install detected, with Redo identity setup, Open configuration editor, Start over from scratch and Cancel](/screenshots/output/init-existing-menu.png)
+
+The menu says your config is untouched until you confirm an action.
 
 | Option | Effect |
 |--------|--------|
-| **Redo identity setup** | Re-runs the four-substep identity flow; provider and all other settings are kept |
-| **Open configuration editor** | Launches `netclaw config` |
-| **Start over from scratch** | Destructive reset — see below |
-| **Cancel** | Exits with config untouched |
+| **Redo identity setup** | Re-runs the four identity prompts with your current answers filled in and saves them to `netclaw.json`. Provider and settings stay. Then `Enter` starts the guided identity chat and `Esc` skips it. |
+| **Open configuration editor** | Hands off to `netclaw config` |
+| **Start over from scratch** | Opens the reset scope chooser |
+| **Cancel** | Exits with everything as it was |
+
+On this menu `Esc` exits `init`, the same as **Cancel**. In the reset screens it steps back one screen: from a confirmation to the scope chooser, then to this menu.
 
 ### Start over from scratch
 
-Selecting "Start over from scratch" opens a scope chooser:
+Choosing **Start over from scratch** opens a scope chooser.
 
-| Scope | What's deleted |
-|-------|---------------|
-| **Reset setup only** | Config, secrets, identity, and personality (`~/.netclaw/config/`, `~/.netclaw/identity/`, `~/.netclaw/soul/`). Memory, sessions, and skills are kept. |
-| **Full reset** | Everything under `~/.netclaw/` |
-| **Cancel** | Returns to the action menu |
+![Start over from scratch scope chooser with Reset setup only, Full reset and Cancel](/screenshots/output/init-start-over-scope.png)
 
-Both destructive scopes require **two confirmations**. The default selection at each confirmation is Cancel — you have to move to the Yes option and confirm twice before anything is deleted.
+Full reset is the destructive row, and its description says it deletes everything.
 
-![Start-over scope chooser](/screenshots/output/init-start-over-scope.png)
+| Scope | What's deleted |
+|-------|----------------|
+| **Reset setup only** | Everything in `~/.netclaw/config/` (`netclaw.json`, `secrets.json`, `tool-approvals.json`, webhook routes, paired devices) and the identity and soul directories. Memory, sessions and skills stay. |
+| **Full reset** | Everything under `~/.netclaw/` except `bin/`, where the installed binaries live |
+| **Cancel** | Back to the menu |
 
-## What init creates
+Both scopes ask you to confirm twice. Each prompt puts **Cancel** first, so you have to move down to **Yes** and press `Enter` twice. The reset stops the daemon, deletes the files, then drops you into the wizard from step 1. If `daemon stop` refuses because the PID in `netclaw.pid` isn't shown to serve this home (see [`netclaw daemon`](/cli/daemon/#pid-n-is-not-shown-to-serve-home)), the reset prints the refusal and `Nothing was deleted.`
 
-| File | Purpose |
-|------|---------|
-| `~/.netclaw/config/netclaw.json` | Main configuration (includes security posture and feature flags) |
-| `~/.netclaw/config/secrets.json` | Encrypted credentials |
-| `~/.netclaw/identity/` | Agent identity and personality |
+:::caution
+**Reset setup only** also deletes `secrets.json` and your saved grants. Copy `~/.netclaw/config/` somewhere first if you want them back. See [Back up, restore and move netclaw](/guides/backup-and-restore/).
+:::
 
 ## After init
 
-After init, netclaw responds to you locally via `netclaw chat` — and nothing else. No channels are connected, search is disabled, and the daemon is loopback-only. To wire up Slack, Discord, or Mattermost, enable web search, or expose the daemon to your team, run `netclaw config` next.
+After init, netclaw answers you locally through `netclaw chat` and nothing else. No channels are connected and the daemon listens on loopback only.
 
 ```bash
-# Connect channels, enable search, set exposure mode, configure skills
-netclaw config
-
-# Verify everything is healthy
-netclaw doctor
-
-# Check daemon status
-netclaw status
+netclaw config    # channels, search, exposure mode, skill sources
+netclaw doctor    # check config and connectivity
+netclaw status    # confirm the daemon is healthy
 ```
 
-## Related commands
+## Related pages
 
-- [`netclaw config`](/cli/config/) — Post-install configuration for channels, search, exposure, skills, and webhooks
-- [`netclaw doctor`](/cli/doctor/) — Diagnose config and connectivity issues
-- [`netclaw status`](/cli/status/) — Check daemon health and connector states
-- [`netclaw provider`](/cli/provider/) — Add or swap providers without re-running init
-- [`netclaw model`](/cli/model/) — Reassign model roles without re-running init
+- [`netclaw config`](/cli/config/): post-install settings for channels, search, exposure and skills
+- [`netclaw doctor`](/cli/doctor/): diagnose config and connectivity problems
+- [`netclaw provider`](/cli/provider/): add or swap providers without re-running init
+- [`netclaw model`](/cli/model/): reassign model roles
+- [Quickstart](/getting-started/quickstart/): the whole path from install to first chat
 
 ## Resources
 
-- [OpenRouter documentation](https://openrouter.ai/docs) — API keys, model catalog, rate limits
-- [Ollama installation](https://ollama.com/download) — Local model runtime setup
-- [Tailscale Funnel documentation](https://tailscale.com/kb/1223/funnel/) — Exposing services to the public internet via Tailscale (configure in `netclaw config` after init)
-- [Cloudflare Tunnel documentation](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) — Exposing services via Cloudflare's network (configure in `netclaw config` after init)
+- [OpenRouter documentation](https://openrouter.ai/docs): API keys, model catalog and rate limits
+- [Ollama installation](https://ollama.com/download): local model runtime setup
+- [llama.cpp server docs](https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md): the OpenAI-compatible server the self-hosted option talks to
diff --git a/src/content/docs/cli/mcp-tools.md b/src/content/docs/cli/mcp-tools.md
index 66de482..9bc6175 100644
--- a/src/content/docs/cli/mcp-tools.md
+++ b/src/content/docs/cli/mcp-tools.md
@@ -1,92 +1,88 @@
 ---
 title: "netclaw mcp"
-description: "Manage MCP servers and tool permissions."
+description: "Add, authorize, list and remove MCP servers, and control which tools each audience can use, with the netclaw mcp command."
 ---
 
-Manage [Model Context Protocol](https://modelcontextprotocol.io/) servers and control which tools each audience can access. Run `netclaw mcp permissions` for an interactive TUI, or use subcommands to script server setup.
+`netclaw mcp` manages [Model Context Protocol](https://modelcontextprotocol.io/) servers: add and remove them, sign in to OAuth servers, and decide which tools Personal, Team and Public sessions can call. The page URL says `mcp-tools` for historical reasons. The command is `netclaw mcp`, and there is no `netclaw mcp-tools`.
 
-Netclaw has three audiences: **Personal**, **Team**, and **Public**. Each has its own tool grants and approval policies. A new server grants all of its tools to Personal with `Auto` approval. Team and Public are **fail-closed**: they get no tools until you grant them.
+New servers are open to Personal (every tool at `Auto`) and closed to Team and Public. Those audiences get no tools until you grant them, with `Approval` (Team) and `Deny` (Public) as the server's default approval mode.
 
 ## Usage
 
 ```bash
-netclaw mcp permissions                   # launch permissions TUI
-netclaw mcp <subcommand> [options]        # CLI mode
+netclaw mcp <subcommand> [options]
 ```
 
-## Permissions TUI
+| Subcommand | What it does | Needs the daemon |
+|------------|--------------|------------------|
+| [`add`](#mcp-add) | Add a server | No |
+| [`auth`](#mcp-auth) | Sign in to an OAuth server | Yes |
+| [`list`](#mcp-list) | List servers with live status | Prints the config without it, shows `status unavailable` and exits `1` |
+| [`get`](#mcp-get) | Show one server's config | No |
+| [`remove`](#mcp-remove) | Remove a server | No |
+| [`enable` / `disable`](#mcp-enable-and-mcp-disable) | Turn a server on or off | No |
+| [`permissions`](#mcp-permissions-and-the-tui) | Edit grants and approvals in a TUI | Yes |
+| [`tools`](#mcp-tools) | Show or script tool grants | Yes |
 
-```bash
-netclaw mcp permissions
-```
-
-Requires a running daemon (`netclaw run` or `netclaw daemon start`).
-
-### Server list
-
-![MCP Permissions server list showing three connected servers: browser_playwright (22 tools), memorizer (21 tools), notion (14 tools)](/screenshots/output/mcp-tools-server-list.png)
+`netclaw mcp` with no subcommand, or an unknown one, prints the help text. `-h` or `--help` after any subcommand prints help too and changes nothing. `netclaw mcp tools --help` prints help specific to that command. The other subcommands print the general `mcp` help.
 
-The TUI probes each configured server and shows connection status and tool count. Select a server to manage its tool grants.
+Config changes made by these commands go to `~/.netclaw/config/netclaw.json`, and the daemon restarts itself to apply them. Credentials go to [`secrets.json`](/cli/secrets/).
 
-### Tool grid
-
-![Tool grid for browser_playwright showing all tools granted for the Personal audience with Auto approval](/screenshots/output/mcp-tools-personal.png)
+## mcp add
 
-The Personal audience with all tools granted and Auto approval. Each row is a discovered tool — `[✓]` means granted, `[ ]` means blocked. The approval column shows whether the tool runs automatically (`Auto`), requires user confirmation (`Approval`), or is hard-blocked (`Deny`).
+```bash
+# stdio (default)
+netclaw mcp add <name> <command> [args...]
+netclaw mcp add <name> -- <command> [args...]
 
-Switch audiences with `←`/`→` on the Audience row. The same server can have completely different permissions per audience:
+# http or sse
+netclaw mcp add --transport http <name> <url>
+```
 
-![Team audience with server disabled and no tools granted](/screenshots/output/mcp-tools-team.png)
+Use `--` before a stdio command so its own flags aren't read as `mcp add` flags. A name can't start with `-` and can't be `help`.
 
-Team audience — server not enabled, no tools granted. This is the default for new servers.
+:::note
+Server names match without regard to case. `netclaw mcp add Git` when `git` exists updates `git` and prints `Updated MCP server 'git' (stdio)`. Its grants and approval modes stay as they were. `get`, `enable`, `disable`, `remove` and `auth` also accept any spelling and print the name as stored.
+:::
 
-![Public audience with server disabled and no tools granted](/screenshots/output/mcp-tools-public.png)
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--transport`, `-t` | `stdio`, `http` or `sse` | `stdio` |
+| `--env KEY=VALUE` | Environment variable for the stdio process. Repeatable. Stored in `secrets.json`. | none |
+| `--header "Key: Value"` | HTTP header. Repeatable. Stored in `secrets.json`. | none |
+| `--client-id <id>` | Pre-registered OAuth client ID | none |
+| `--client-secret <secret>` | Secret for a confidential OAuth client. Stored encrypted in `secrets.json`. Requires `--client-id` and a non-empty value. | none |
+| `--scope <scopes>` | OAuth scopes, space-separated | none |
+| `--grant-all` | Skip the empty Team and Public grant lists, so every tool passes for any audience that allows the server. Approval defaults are still written. Only applies when the server is new. | off |
+| `--auth` | Start the OAuth flow right after adding | off |
 
-Public audience — same default lockdown.
+:::note
+`--auth` doesn't start the flow. `mcp add` runs without a daemon connection, so it adds the server, prints `--auth: daemon API not available. Run `netclaw mcp auth <name>` once the daemon is running.` and exits `0`. It prints that even when the daemon is running. Run `netclaw mcp auth <name>` after the add.
+:::
 
-### Keybindings
+:::caution
+`--client-secret`, `--header` and `--env` put the value on the command line, where shell history and process listings can expose it. Use them on a host you trust.
+:::
 
-| Key | Action |
-|-----|--------|
-| `↑` / `↓` | Navigate rows |
-| `←` / `→` | Change audience or cycle approval mode |
-| `Space` | Toggle tool grant on/off |
-| `A` | Toggle all tools on/off |
-| `E` | Toggle server enabled for current audience |
-| `M` | Cycle server default approval mode |
-| `P` | Cycle per-tool approval override |
-| `Enter` | Done (prompts to save if there are unsaved changes) |
-| `Esc` | Back to server list (quits from server list) |
-| `Ctrl+Q` | Quit (discards unsaved changes) |
+Running `mcp add` on a name that exists updates that server instead of starting over. The command, arguments, URL and OAuth settings come from the new command line. The server's Team and Public grants, allow-list entries, approval defaults and enabled state stay as they were, and `--grant-all` is ignored. The output lists what changed:
 
-Changes are saved to `~/.netclaw/config/netclaw.json`. Restart the daemon to apply.
+```
+Updated MCP server 'echo1' (stdio)
 
-## Subcommands
+Audience grants, approval modes and allow-lists are unchanged.
+Connection settings: replaced arguments; dropped environment variables (pass the option again to keep it).
+```
 
-### `mcp add`
+Environment variables, headers and the client secret are stored as a set with the connection, so a re-add that leaves out `--env`, `--header` or `--client-secret` drops the stored ones. Pass them again to keep them. To change only a secret, use `netclaw secrets set McpServers.<name>.OAuthClientSecret <value>` and restart the daemon.
 
 ```bash
-# stdio transport (default)
-netclaw mcp add <name> [command] [-- args...]
-
-# HTTP or SSE transport
-netclaw mcp add <name> <url> --transport http
+netclaw mcp add --transport stdio --env API_KEY=sk-123 memorizer -- uvx memorizer-mcp
+netclaw mcp add --transport http notion https://mcp.notion.com/mcp
+netclaw mcp add --transport http --header "Authorization: Bearer tok-..." myapi https://api.example.com/mcp
+netclaw mcp add --transport http --client-id CLIENT_ID --client-secret CLIENT_SECRET confidential https://mcp.example.com/mcp
 ```
 
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--transport`, `-t` | `stdio`, `http`, or `sse` | `stdio` |
-| `--env KEY=VALUE` | Environment variable (repeatable) | — |
-| `--header "Key: Value"` | HTTP header (repeatable) | — |
-| `--client-id <id>` | Pre-registered OAuth client ID for HTTP/SSE servers | — |
-| `--client-secret <secret>` | Secret for a pre-registered confidential client. Requires `--client-id` | — |
-| `--scope <scopes>` | OAuth scopes (space-separated) | — |
-| `--auth` | Start `netclaw mcp auth` right after adding (HTTP/SSE only) | — |
-| `--grant-all` | Skip per-tool grants (all tools visible), but still write approval defaults | — |
-
-Server config goes to `~/.netclaw/config/netclaw.json`. Credentials (`--env` values, `--header` values) go to [`secrets.json`](/cli/secrets/).
-
-After adding a server, Personal gets all of its tools with `Auto` approval. Team and Public get no tools, with `Approval` and `Deny` as their approval defaults. Restart the daemon to load the new server, then grant tools to Team or Public:
+The output confirms the security posture, and for http and sse servers without an `Authorization` header it points you at `mcp auth`:
 
 ```
 Added MCP server 'notion' (http)
@@ -100,173 +96,185 @@ Next steps:
   - Then grant tools: netclaw mcp permissions
 ```
 
-The server name you provide here is what appears as `mcp:<name>` in [`netclaw status`](/cli/status/) output.
+The server name is what appears as `mcp:<name>` in [`netclaw status`](/cli/status/).
 
-#### Examples
+## mcp auth
 
 ```bash
-# Add a stdio MCP server
-netclaw mcp add memorizer npx -y @anthropic/memorizer-mcp
+netclaw mcp auth <name>
+```
 
-# Add an HTTP server with OAuth
-netclaw mcp add notion https://mcp.notion.com --transport http \
-  --client-id abc123 --scope "read write"
+Starts the OAuth flow for an http or sse server. The command prints an authorization URL and the `Redirect URI:` it sends, tries to open a browser, and waits up to five minutes for the provider to call back. If the callback can't reach the daemon (a headless host, a container), paste the redirect URL into the waiting terminal. That needs a real terminal, so use `docker exec -it`. Re-run it any time to sign in again.
 
-# Add a server with environment variables
-netclaw mcp add my-server npx my-mcp-server \
-  --env API_KEY=sk-123 --env REGION=us-east-1
+A server with a pre-registered client (`--client-id`) needs that exact URI registered at the provider, which is `http://127.0.0.1:<Daemon.Port>/api/mcp/oauth/callback` (default port `5199`). Use `127.0.0.1`, not `localhost`. See [Redirect URI](/configuration/mcp-servers/#redirect-uri).
 
-# CI/scripting — skip per-tool grant setup
-netclaw mcp add my-server npx my-mcp-server --grant-all
-```
+It fails for stdio servers, for names that aren't configured, and when the daemon isn't running. The full flow, confidential clients and troubleshooting are in [Connect an OAuth MCP server](/guides/oauth-mcp-servers/).
 
-### `mcp list`
+## mcp list
 
 ```bash
 netclaw mcp list
 ```
 
 ```
-Name                 Transport   Enabled   Status
-browser_playwright   stdio       yes       connected (22 tools)
-memorizer            stdio       yes       connected (21 tools)
-notion               http        yes       awaiting auth — run: netclaw mcp auth notion
+Name                 Transport  Enabled  Status
+demo                 http       yes      connected (10 tools)
+anon2                http       yes      connected (2 tools)
 ```
 
-Shows static config plus live status from the daemon. Without a running daemon, all statuses show as unavailable.
+Static config plus live status from the daemon. Without a running daemon the statuses read `status unavailable` and the command exits 1. Status values are listed under [Server status](/configuration/mcp-servers/#server-status).
 
-| Status | Meaning |
-|--------|---------|
-| `connected (N tools)` | Server is up, N tools discovered |
-| `awaiting auth` | OAuth required — run `netclaw mcp auth <name>` |
-| `auth failed` | OAuth token expired or invalid |
-| `unreachable` | Server process crashed or network error — run [`netclaw doctor`](/cli/doctor/) to diagnose |
-| `disabled` | Disabled via `netclaw mcp disable` |
-
-### `mcp get`
+## mcp get
 
 ```bash
 netclaw mcp get <name>
 ```
 
-Shows full server config: transport, command/URL, enabled state, OAuth settings, and environment variables. Credential values are redacted (`***REDACTED***`).
+Shows transport, command or URL, enabled state, client ID, scope, and whether a client secret is configured (`Client secret: configured`). Environment variable and header values are never printed, and show as `***REDACTED***`.
 
-### `mcp remove`
+## mcp remove
 
 ```bash
 netclaw mcp remove <name>
 ```
 
-Removes the server from both `netclaw.json` and `secrets.json`. Tool grant and approval policy entries for this server are not cleaned up automatically — if you re-add a server with the same name, old permission settings will still apply.
+Removes the server and everything netclaw stored for it:
+
+- Its entry in `netclaw.json`, and its `McpServers` entry in `secrets.json`.
+- Stored OAuth tokens (`McpOAuthTokens.<name>` in `secrets.json`). Re-adding the server needs a fresh sign-in.
+- Its Team and Public allow-list entries, tool grants, approval defaults and per-tool overrides under `Tools.AudienceProfiles`.
+- Its saved approvals in `tool-approvals.json`.
+
+Nothing is revoked at the provider. The name matches without regard to case, so `remove Demo` removes a server called `demo`. A name that matches nothing exits 1 with `MCP server '<name>' not found.` Case variants of the server's per-tool approval keys are removed with it.
 
-### `mcp enable` / `mcp disable`
+## mcp enable and mcp disable
 
 ```bash
 netclaw mcp enable <name>
 netclaw mcp disable <name>
 ```
 
-Toggle a server without removing its config. Disabled servers aren't loaded by the daemon — their tools won't appear in `netclaw mcp permissions` or be available in sessions.
+Flips `Enabled` without touching anything else. A disabled server isn't loaded and its tools aren't available in sessions.
 
-### `mcp auth`
+## mcp permissions and the TUI
 
 ```bash
-netclaw mcp auth <name>
+netclaw mcp permissions
 ```
 
-Starts the OAuth flow for an HTTP or SSE server. Opens your browser to the authorization page and prints the URL to the terminal. In headless environments, copy the printed URL manually. Times out after 5 minutes.
+Opens the grants and approvals editor. It needs a TTY and a running daemon, because it probes each server for its tools. Bare `netclaw mcp tools` opens the same TUI.
 
-If netclaw runs on another machine, the browser can't load the callback page after you approve. Copy the URL from the address bar and paste it at the prompt.
+### Server list
 
-A server with a pre-registered client (`--client-id`) needs this redirect URI registered at the provider: `http://127.0.0.1:<Daemon.Port>/api/mcp/oauth/callback` (default port 5199). See [Redirect URI](/configuration/mcp-servers/#redirect-uri).
+The TUI opens on the server list.
 
-Only needed for HTTP and SSE servers that require OAuth.
+![MCP Permissions server list with one connected server, demo-utilities, and its tool count of 10](/screenshots/output/mcp-tools-server-list.png)
 
-### `mcp tools`
+The TUI lists every server the daemon knows with its state and tool count, and Enter opens the selected server's tool grid. This one has a single server, so the list is a single row. `Esc` quits from this screen, unlike the tool grid, where it goes back.
 
-```bash
-netclaw mcp tools <server> [--audience <name>] [--snapshot] [--grant <tools>] [--revoke <tools>]
-```
+### Tool grid
 
-View and script tool grants from the CLI. For interactive editing, use `netclaw mcp permissions`.
+Selecting a server opens its tool grid, shown here for the Personal audience.
 
-| Flag | Description |
-|------|-------------|
-| `--audience <name>` | Filter to `personal`, `team`, or `public` |
-| `--snapshot` | Populate grants from currently discovered tools (requires daemon) |
-| `--grant <tools>` | Comma-separated tool names to grant (requires `--audience`) |
-| `--revoke <tools>` | Comma-separated tool names to revoke (requires `--audience`) |
+![MCP Permissions tool grid for demo-utilities on the personal audience, with the server enabled, default Auto, and ten tools each granted at Auto](/screenshots/output/mcp-tools-personal.png)
 
-Without `--grant`/`--revoke`, displays a table: `✓` = granted, `-` = blocked, `✱` = no per-tool filtering (all tools pass through).
+Personal with every tool granted at `Auto`. The footer reads `[↑↓] Move [Space] Toggle [A] All [E] Disable [Enter] Done [Esc] Back`. On the Team and Public audiences `[E]` reads `Enable all` while the server is off. `[✓]` means granted, `[ ]` means blocked, and the bracketed word is the approval mode: `Auto` runs without asking, `Approval` asks first, `Deny` blocks. `(def)` means the tool inherits the server default.
 
-```bash
-# See what's granted for team
-netclaw mcp tools memorizer --audience team
+`*unsaved*` in the footer appears as soon as the grid opens, before you press anything. A server added with `mcp add` has empty Team and Public grant lists, and the screen counts those as pending edits. Nothing is written until you press `Enter` and confirm.
 
-# Grant specific tools for personal use
-netclaw mcp tools browser_playwright --audience personal \
-  --grant "browser_navigate,browser_click"
+Switch audiences on the Audience row and the same server shows different permissions. Rows for tools that aren't granted render dim, so a screen of grey rows means nothing is granted for that audience.
 
-# Snapshot all discovered tools into the grants config
-netclaw mcp tools memorizer --snapshot
-```
+| Audience | A new server starts as |
+|----------|------------------------|
+| Personal | Server enabled, default `Auto`, every tool granted |
+| Team | Server not enabled, default `Approval`, all tools dim and unchecked ([screenshot](/security/hardening/#mcp-tool-permissions)) |
+| Public | Server not enabled, default `Deny` (shown in red), all tools dim and unchecked |
 
-## How permissions work
+| Key | Action |
+|-----|--------|
+| `↑` / `↓` | Move between rows |
+| `←` / `→` | Change the audience or cycle the approval mode on the current row |
+| `Space` | Toggle the row (tool grant, server access) |
+| `A` | Toggle all tools (asks before granting them all) |
+| `E` | Enable or disable the server for this audience (asks before granting every tool) |
+| `M` | Cycle the server's default approval mode |
+| `P` | Cycle the highlighted tool's approval override |
+| `Enter` | Done. Asks to save if there are unsaved changes (`Y` or `Enter` saves, `N` discards, `Esc` cancels). |
+| `Esc` | Back to the server list. On the server list it quits. |
+| `Ctrl+Q` | Quit |
 
-Tool grants control which tools are visible to each audience. An ungranted tool doesn't exist from the model's perspective — configure grants with `netclaw mcp permissions` or `netclaw mcp tools`.
+Saving writes `netclaw.json`, and the daemon restarts itself to apply it.
 
-Approval policy controls whether granted tools run automatically or need human confirmation:
+Enabling a server for Team or Public grants every discovered tool, and replaces any trimmed grant list. So `E` (or `Space` or an arrow on the **Server enabled** row) and `A` ask first when they would grant everything:
 
-| Mode | Behavior |
-|------|----------|
-| `Auto` | Tool runs without asking |
-| `Approval` | Prompts for confirmation before executing |
-| `Deny` | Hard-blocked even if granted |
+```
+Grant all 10 tools on 'demo' to team?  [Y] Grant  [N/Esc] Cancel
+```
 
-Approval overrides are per-tool: you can set the server default to `Auto` but require `Approval` for destructive tools like `delete` or `drop_table`.
+![MCP Permissions tool grid for the team audience with the prompt "Grant all 10 tools on 'demo-utilities' to team?" at the bottom and Y Grant, N/Esc Cancel](/screenshots/output/mcp-tools-confirm.png)
 
-Default policies for new servers:
+The prompt replaces the footer, and the tool rows stay greyed until you answer.
 
-| Audience | Tool Grants | Approval Default |
-|----------|-------------|------------------|
-| Personal | All tools | Auto |
-| Team | Empty (all blocked) | Approval |
-| Public | Empty (all blocked) | Deny |
+`Y` grants. `N`, `Esc` and `Enter` cancel, so a burst of `Enter` can't grant by accident. Personal in the default `All` mode isn't asked, because it has no grant list. `A` only works once the server is enabled for the audience. Press it again to clear the list when every tool is granted, and it asks before granting them all again. The footer reads `[E] Enable all` when enabling would grant everything, and `[E] Disable` or `[E] Enable` otherwise.
 
-## Examples
+## mcp tools
 
 ```bash
-# Full setup: add a server, grant tools, configure approvals
-netclaw mcp add notion https://mcp.notion.com --transport http
-netclaw mcp permissions    # grant tools in the TUI
+netclaw mcp tools <server> [--audience <name>] [--snapshot] [--grant <tools>] [--revoke <tools>]
+```
 
-# Check what's connected
-netclaw mcp list
+Shows and scripts the same grants from the command line. Without `--grant`, `--revoke` or `--snapshot` it prints a table: `✓` granted, `-` blocked, `✱` no per-tool filtering. `--grant`, `--revoke` and `--snapshot` write `netclaw.json`.
+
+| Flag | Description |
+|------|-------------|
+| `--audience <name>` | `personal`, `team` or `public`. Required for `--grant` and `--revoke`. |
+| `--snapshot` | Write the currently discovered tools as the grant list |
+| `--grant <tools>` | Comma-separated tool names to grant. Also allows the server for that audience. |
+| `--revoke <tools>` | Comma-separated tool names to revoke |
+| `--help`, `-h` | Print help |
 
-# Temporarily disable a server
-netclaw mcp disable notion
+```
+$ netclaw mcp tools pub
+Tools for server 'pub' (2 discovered):
 
-# Re-enable it
-netclaw mcp enable notion
+  Tool           Public   Team     Personal
+  ─────────────────────────────────────────
+  generate_uuid  -        -        ✱
+  whoami         -        -        ✱
 
-# Remove a server you no longer need
-netclaw mcp remove old-server
+Edit interactively: netclaw mcp permissions
 ```
 
-## What's next
+A few behaviors worth knowing:
+
+- Tool names must exist on the server, or the command errors.
+- For a Personal audience in `All` mode, `--revoke` writes a `Deny` override for the tool and `--grant` removes it. Personal doesn't use grant lists.
+- `--grant` adds the server to the audience's `AllowedMcpServers` if it isn't there, and says so (`Also allowed server 'demo' for Team.`). When it does, the grant list becomes exactly the tools you named, and any older entries are dropped with a message. It then prints which tools the audience can call and in which approval mode. If the server's default for that audience is `Deny` (the Public default), it tells you the tool can't be called yet.
+- `--revoke` and `--snapshot` on an audience that doesn't allow the server change nothing and exit `1` (`Server 'demo' is not allowed by the Public audience profile.`). Grant a tool first, or enable the server in the TUI.
+- New tools a server adds later stay hidden from Allowlist audiences until you grant them.
 
-After adding a server and granting permissions, restart the daemon and run [`netclaw status`](/cli/status/) to confirm the MCP connector shows healthy. If a server reports `unreachable` or `auth failed`, run [`netclaw doctor`](/cli/doctor/) to diagnose.
+```bash
+netclaw mcp tools pub --grant whoami --audience team
+netclaw mcp tools pub --revoke whoami --audience personal
+```
+
+```
+Updated Team profile for 'pub': granted 1 tool(s). 1 total granted.
+Also allowed server 'pub' for Team.
+Team can now call: whoami (mode: Approval)
+```
 
-## Related commands
+## Related pages
 
-- [`netclaw init`](/cli/init/) — adds browser automation MCP servers during onboarding
-- [`netclaw status`](/cli/status/) — shows MCP server connectivity at runtime
-- [`netclaw doctor`](/cli/doctor/) — diagnoses MCP server connection issues
-- [`netclaw secrets`](/cli/secrets/) — manage encrypted credentials used by MCP servers
+- [Connect an OAuth MCP server](/guides/oauth-mcp-servers/) - the full `mcp auth` flow, secrets and troubleshooting
+- [MCP servers](/configuration/mcp-servers/) - the config schema behind these commands
+- [MCP tool permissions](/guides/mcp-tool-permissions/) - how audience grants and approvals fit together
+- [`netclaw status`](/cli/status/) - MCP connector health
+- [`netclaw doctor`](/cli/doctor/) - diagnose a server that won't connect
 
 ## Resources
 
-- [Model Context Protocol specification](https://modelcontextprotocol.io/specification) — the protocol netclaw implements for tool servers
-- [MCP server registry](https://github.com/modelcontextprotocol/servers) — community-maintained list of MCP servers
-- [Notion MCP server](https://github.com/makenotion/notion-mcp-server) — Notion's official MCP integration
-- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) — build your own MCP server
+- [Model Context Protocol specification](https://modelcontextprotocol.io/specification) - the protocol netclaw implements
+- [MCP server registry](https://github.com/modelcontextprotocol/servers) - community-maintained list of MCP servers
+- [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization) - the OAuth flow behind `mcp auth`
+- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) - build your own MCP server
diff --git a/src/content/docs/cli/memory.md b/src/content/docs/cli/memory.md
new file mode 100644
index 0000000..f73b877
--- /dev/null
+++ b/src/content/docs/cli/memory.md
@@ -0,0 +1,93 @@
+---
+title: "netclaw memory"
+description: "Embed memories that have no vector yet, after an upgrade to 0.27 or a model change."
+---
+
+`netclaw memory` has one subcommand: `backfill-embeddings`. It makes sure every stored memory has a vector from the current embedding model, so semantic recall can find it. You need it once after upgrading to 0.27 with memories you already had, and again after you change `Memory.Embeddings.ModelId`. It doesn't list, search, edit or delete memories. For that, see [fix a wrong memory](/configuration/memory/#fix-a-wrong-memory).
+
+The command is offline. It reads and writes `~/.netclaw/netclaw.db` and the model files directly, so the daemon doesn't need to be running. It's safe to run next to a live daemon: each write checks the content hash first and skips anything the daemon has already embedded.
+
+## Usage
+
+```bash
+netclaw memory backfill-embeddings [--force]
+netclaw memory help
+```
+
+Running `netclaw memory` with no subcommand, or any unknown one, prints the same help. In Docker, run it through `docker exec <container> netclaw memory ...`.
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--force` | Re-scan every recallable memory, not only those missing a vector for the current model | Off |
+
+`--force` still skips a memory whose stored vector matches its current text, so on an up-to-date store it reports `skipped-hash-unchanged` for everything and writes nothing. Use it when you suspect stale vectors. A change to the memory text or the model id is detected without it.
+
+## Examples
+
+### Backfill after upgrading to 0.27
+
+```bash
+netclaw memory backfill-embeddings
+```
+
+```text
+Provisioning embedding model 'snowflake-arctic-embed-m-int8'...
+Loading embedder 'snowflake-arctic-embed-m-int8' (768 dims)...
+Embedding 1 document(s)...
+  ...1/1
+
+Done: embedded=1 skipped-hash-unchanged=0 failed=0
+```
+
+The command downloads the model first if it isn't on disk (about 110 MB, then loads it), embeds the memories in batches of 16, and prints progress. The exit code is `0` when nothing failed and `1` if any batch or memory failed. Rerunning is safe.
+
+When everything already has a vector:
+
+```text
+Provisioning embedding model 'snowflake-arctic-embed-m-int8'...
+Loading embedder 'snowflake-arctic-embed-m-int8' (768 dims)...
+Nothing to backfill: all recallable documents already have a current-model embedding.
+```
+
+### Fix the doctor warning
+
+`netclaw doctor` shows this when vectors are missing, for example after memories were changed directly in the database:
+
+```text
+[WARN] Memory Embeddings: 1 of 1 recallable documents lack a current-model embedding. queryPrefix=True floor=0.240 (source=manifest).
+       fix: The daemon's gap-repair sweep heals this at next startup, or run `netclaw memory backfill-embeddings` now.
+```
+
+Restarting the daemon fixes the same gap. Run the command when you don't want to restart.
+
+### Offline hosts
+
+With `Memory.Embeddings.AutoDownload` set to `false`, the command doesn't download. It loads the model from `~/.netclaw/models/` or exits `1`:
+
+```text
+[FAIL] unable to provision embedding model 'snowflake-arctic-embed-m-int8': Embedding model 'snowflake-arctic-embed-m-int8' is not provisioned (or fails hash verification) at /home/netclaw/.netclaw/models/snowflake-arctic-embed-m-int8, and Memory.Embeddings.AutoDownload is false. Provision the model manually, or enable AutoDownload and re-run this command.
+```
+
+Copy the model in first. [Run offline](/configuration/memory/#run-offline) has the file list.
+
+### Embeddings turned off
+
+With `Memory.Embeddings.Enabled` set to `false`, the command does nothing, with or without `--force`. It downloads no model, embeds nothing and exits `0`:
+
+```text
+Embeddings are disabled (Memory.Embeddings.Enabled is false); nothing to backfill. Set Memory.Embeddings.Enabled to true to embed memories.
+```
+
+## Related pages
+
+- [Memory and embeddings](/configuration/memory/) - settings, resource cost, offline use, fixing a wrong memory
+- [Memory model](/architecture/memory-model/) - how recall uses the vectors
+- [`netclaw doctor`](/cli/doctor/) - reports missing vectors and model health
+- [Upgrade netclaw](/guides/upgrading/) - when to run the backfill
+
+## Resources
+
+- [snowflake-arctic-embed-m](https://huggingface.co/Snowflake/snowflake-arctic-embed-m) - the default embedding model
+- [ONNX Runtime](https://onnxruntime.ai/) - the runtime that executes it
diff --git a/src/content/docs/cli/model.md b/src/content/docs/cli/model.md
index 41fa58b..26eab78 100644
--- a/src/content/docs/cli/model.md
+++ b/src/content/docs/cli/model.md
@@ -16,12 +16,12 @@ netclaw model <subcommand> [options]   # CLI mode
 
 ## Model roles
 
-Three roles — only Main is required:
+Three roles, and only Main is required:
 
 | Role | Purpose | When unset |
 |------|---------|------------|
-| **Main** | Primary model for all interactions | Required — cannot be cleared |
-| **Fallback** | Automatic failover when Main is unavailable (rate limits, network errors, provider outages) | Falls back to Main |
+| **Main** | Primary model for all interactions | Required, can't be cleared |
+| **Fallback** | Automatic failover for every role when its own model is unavailable (rate limits, network errors, provider outages), Compaction included | Falls back to Main |
 | **Compaction** | Context summarization with a cheaper/faster model | Falls back to Main |
 
 Role names are case-insensitive.
@@ -34,19 +34,36 @@ Role names are case-insensitive.
 netclaw model
 ```
 
-![Model Manager TUI showing role assignments with Main configured and Fallback/Compaction unset](/screenshots/output/model-manager.png)
+![Model Manager listing Main on lab-llama with demo-model, and Fallback and Compaction on my-ollama with qwen2:0.5b, with Max out and Thinking at their defaults and all marked Manual](/screenshots/output/model-manager.png)
 
-Select a role to reassign it, or use the hotkeys:
+All three roles are assigned here, with Main on a different provider from the other two. The Provider column stops at 40 characters, so a long type label such as OpenAI-compatible is cut with an ellipsis.
+
+The manager lists the three roles with the provider, model, output limit (`Max out`) and thinking level behind each one. An unset limit shows `default 32000` and an unset level shows `default`. Select a role to reassign it, or use the hotkeys:
 
 | Key | Action |
 |-----|--------|
 | `↑` / `↓` | Navigate roles |
 | `Enter` | Assign model to selected role |
 | `D` | Discover available models from a provider |
-| `C` | Clear optional role (Fallback or Compaction) |
-| `Esc` | Back / Quit (from role overview) |
+| `P` | Edit the highlighted role's output limit and thinking level |
+| `C` | Clear the highlighted optional role (Fallback or Compaction) at once |
+| `Esc` | Back (does nothing on the role overview) |
 | `Ctrl+Q` | Quit from any screen |
 
+`C` on Main shows `Cannot clear the main model role.` and on an unset role `Fallback role is not set.`
+
+`P` probes the provider for the model's capability, then opens **Model properties** for the role's definition:
+
+- **Max output tokens**: a text box. Blank means the default, 32000.
+- **Thinking level**: `default`, then `off` to `max`. `Tab` switches field and `↑` / `↓` picks a level. Levels the provider or model doesn't offer are greyed with the reason beside them.
+- `Enter` saves and `Esc` cancels. A rejected value shows `Not saved: <reason>`.
+
+When another role shares the definition, the panel says `Also used by: <role>` and the change applies to each of them. On a provider with no thinking dialect, only the output field is editable. See [Output limit and thinking level](#output-limit-and-thinking-level).
+
+![Model properties for Main on lab-llama: Max output tokens blank with default 32000, and thinking levels where only default and off are offered](/screenshots/output/model-properties.png)
+
+This endpoint doesn't report thinking support, so only `default` and `off` are offered, and the `ReasoningEffort` dialect can't send `max` at all.
+
 `Enter` opens the assignment flow: pick a provider, discover its models, confirm. Discovery times out after 45 seconds and shows up to 30 results. If yours isn't listed, pick "Enter model ID manually..." and type it in (e.g., `qwen3:30b`, `llama3.2:latest`).
 
 ## Subcommands
@@ -58,24 +75,24 @@ netclaw model list
 ```
 
 ```
-Role         Provider             Model ID                       Context Window
-Main         remote-gpu           qwen3:30b                      32,768 tokens
-Fallback     remote-gpu           qwen3:8b                       (default)
+Role         Provider             Model ID                       Context Window   Max out        Thinking
+Main         lab-llama            demo-model                     (default)        default 32000  default
+Fallback     (not set)
 Compaction   (not set)
 ```
 
-Context window shows `(default)` unless you've set an explicit `--context-window` value. The table resolves roles to their provider and model — it doesn't show definition names or modality overrides. Read the config file for those.
+Context window shows `(default)` unless you've set an explicit `--context-window` value, in which case it prints it, such as `65,536 tokens`. `Max out` shows the definition's `--max-output-tokens` with thousands separators (`64,000`), or `default 32000` when unset. `Thinking` shows `off`, `low`, `medium`, `high`, `max` or `default`. The table resolves roles to their provider and model. It doesn't show definition names or modality overrides, so read the config file for those.
 
-This reads from config, not from the running daemon. With no models configured, it prompts you to run `model set` or open the TUI.
+This reads `netclaw.json` and applies any `NETCLAW_Models__*` variables set in your shell, the way the daemon does with its own environment. When one applies, a last line names it: `Note: this shell's environment (NETCLAW_Models__Roles__Main) is applied. The daemon uses its own environment.` It doesn't query the running daemon. With no models configured, it prompts you to run `model set` or open the TUI.
 
 If a role points at a definition that doesn't exist, `list` names the bad reference and stops:
 
 ```
-Error: Models:Roles:Main references unknown definition 'does-not-exist'.
+Error: Models:Roles:Main references unknown definition 'does-not-exist'. Defined: lab-llama-demo-model. Fix the name, or run `netclaw model set main <provider> <model>`.
 Fix the Models section in netclaw.json, then rerun `netclaw model list`.
 ```
 
-Open the config, compare `Roles` against `Definitions`, and make the names agree — this usually happens after renaming a definition and forgetting a role. `netclaw doctor` flags the same thing (it won't auto-fix it), and the daemon refuses to start on it, so fix it before restarting.
+Open the config, compare `Roles` against `Definitions`, and make the names agree. This usually happens after you rename a definition and forget a role. `netclaw doctor` flags the same thing (it won't auto-fix it). A running daemon ignores the bad edit and keeps its previous models, and `netclaw status` says `config on disk not applied` until you fix it. A daemon that restarts with the bad file stops at startup with the same one-line message.
 
 ### `model set`
 
@@ -86,12 +103,16 @@ netclaw model set <role> <provider> <model-id> [options]
 | Flag | Description | Default |
 |------|-------------|---------|
 | `--context-window <tokens>` | Override context window size (positive integer) | Provider-detected |
-| `--clear-context-window` | Drop the override and go back to detection | — |
+| `--clear-context-window` | Drop the override and go back to detection | |
 | `--input-modalities <list>` | Comma-separated `Text`, `Image`, `Audio`, `Video` | Detected |
 | `--output-modalities <list>` | Same values, for output | Detected |
-| `--clear-modalities` | Drop both modality overrides | — |
+| `--clear-modalities` | Drop both modality overrides | |
+| `--max-output-tokens <tokens>` | Output limit for every call of this model (positive integer). Thinking tokens count inside it | 32000, clamped per call |
+| `--clear-max-output-tokens` | Drop the limit and go back to the default | |
+| `--thinking <level>` | `off`, `low`, `medium`, `high` or `max` | Model default |
+| `--clear-thinking` | Drop the level | |
 
-Use `--context-window` when a local model doesn't report its window (discovery shows `-`), or to cap usage below the model's actual maximum. Use the modality flags when detection gets a model's capabilities wrong — an Ollama vision model reported as text-only, say.
+Use `--context-window` when a local model doesn't report its window (discovery shows `-`), or to cap usage below the model's actual maximum. Use the modality flags when detection gets a model's capabilities wrong, such as an Ollama vision model reported as text-only.
 
 ```bash
 netclaw model set main remote-gpu qwen3-vl:32b \
@@ -100,21 +121,74 @@ netclaw model set main remote-gpu qwen3-vl:32b \
   --output-modalities "Text"
 ```
 
-`--context-window` and `--clear-context-window` are mutually exclusive:
+Each flag and its `--clear-*` partner are mutually exclusive:
 
 ```
 Error: --context-window and --clear-context-window cannot be combined.
 ```
 
-Modality names are case-insensitive and are stored canonicalized — `text,image` lands on disk as `"Text, Image"`. Only the four names are accepted; anything else, including a raw integer, is rejected:
+The same goes for `--max-output-tokens` with `--clear-max-output-tokens` and `--thinking` with `--clear-thinking`.
+
+Modality names are case-insensitive and are stored canonicalized, so `text,image` lands on disk as `"Text, Image"`. Only the four names are accepted. Anything else, including a raw integer, is rejected:
 
 ```
 Error: invalid modalities '1'. Use a comma-separated list of: Text, Image, Audio, Video (or --clear-modalities to remove the override).
 ```
 
+#### Output limit and thinking level
+
+`--max-output-tokens` caps the reply for every call of the model, and thinking tokens count inside it. With no value, a hosted API gets 32000, capped to the model's known maximum and clamped to its context window. Anthropic replies used to stop at 1024 tokens, so cost per call can rise on upgrade. A self-hosted server gets 32000 clamped to its context window only when the window is known, from `ContextWindow` or the server's own probe. Otherwise netclaw sends no limit field.
+
+`--thinking` sets one provider-neutral level, and netclaw maps it to the switch each provider has. A level the provider or model doesn't offer is rejected, and the error lists the levels that are. netclaw never sends a nearby level instead.
+
+```bash
+netclaw model set main my-anthropic claude-opus-5-5 --max-output-tokens 64000 --thinking high
+```
+
+`set` validates the whole definition before it saves and leaves `netclaw.json` unchanged on an error:
+
+```text
+Error: Models:Definitions:lab-llama-demo-model:MaxOutputTokens (40000) must be below the context window (32768).
+Error: --max-output-tokens must be a positive integer.
+Error: invalid thinking level '3'. Use off, low, medium, high, or max (or --clear-thinking).
+```
+
+A limit above the model's probed maximum is rejected too (`... is above the maximum output of this model (N tokens).`).
+
+An `openai-compatible` provider has no thinking dialect until you set one, so every level is rejected:
+
+```text
+Error: Thinking level 'high' is not offered by provider 'lab-llama': no thinking dialect is set; set VendorOptions:ThinkingDialect on the provider to ChatTemplateKwargs, ReasoningEffort, DeepSeek, or None. Provider 'lab-llama' offers no thinking level. Set Providers:lab-llama:VendorOptions:ThinkingDialect to ChatTemplateKwargs, ReasoningEffort, DeepSeek, or None.
+```
+
+When `set` detects a llama.cpp server, it saves `ReasoningEffort` itself and prints `Detected thinking dialect ReasoningEffort; saved Providers:<name>:VendorOptions:ThinkingDialect.` For any other server, set the dialect yourself on the provider:
+
+```json
+"lab-llama": {
+  "Type": "openai-compatible",
+  "Endpoint": "http://llm.example.internal:8080/v1",
+  "VendorOptions": { "ThinkingDialect": "ReasoningEffort" }
+}
+```
+
+| Dialect | Levels it can send |
+|---------|--------------------|
+| `ReasoningEffort` | `off`, `low`, `medium`, `high` |
+| `DeepSeek` | `off`, `low`, `high`, `max` |
+| `ChatTemplateKwargs` | `off` |
+| `None` | none |
+
+A dialect only says which levels can be sent. The model must offer the level too. On an endpoint that doesn't report thinking support, as most generic `openai-compatible` servers don't, only `off` is accepted, and only with a dialect other than `None`:
+
+```text
+Error: Thinking level 'high' is not offered by provider 'lab-llama': thinking support unknown for this endpoint. Provider 'lab-llama' offers off.
+```
+
+Hand-edited values face the same rules. Four edits fail daemon startup and the `netclaw doctor` Chat Client check: a `Thinking` level the dialect can't send, any level other than `off` on an Ollama provider with `VendorOptions:DisableThinking: true`, a `MaxOutputTokens` at or above `ContextWindow`, and a `VendorOptions:ThinkingDialect` value that isn't a valid dialect. The first two end `Daemon startup will fail until this is resolved.` The other two say `Invalid inference configuration` or `The daemon will not start with this configuration` and tell you to fix the `Models` section or the provider values. A running daemon keeps its previous models until you fix it.
+
 #### What set and clear actually touch
 
-`set` and the `--clear-*` flags edit the **model definition** — the stored facts about a given provider/model pair. Assigning a role only repoints a reference at a definition. That distinction is the whole point: **switch a role away from a model and back, and its overrides are still there.**
+`set` and the `--clear-*` flags edit the **model definition**, the stored facts about a given provider and model pair. Assigning a role only repoints a reference at a definition. The one exception is `--thinking` on a provider with no dialect, where `set` can also write the provider's `VendorOptions:ThinkingDialect`. That's the whole point: **switch a role away from a model and back, and its overrides are still there.**
 
 ```bash
 netclaw model set main remote-gpu qwen3:30b --context-window 65536
@@ -124,24 +198,42 @@ netclaw model set main remote-gpu qwen3:30b    # still 65536
 
 Clearing removes the property outright rather than writing a sentinel, so a cleared value reads as "detect this at runtime".
 
+If another role uses the same definition, `set` says so and the change applies to each of them:
+
+```text
+Note: definition 'lab-llama-demo-model' is also used by: Fallback. The change applies to each of them.
+```
+
+Running `set` again on the model a role already uses keeps that role's own definition. To give two roles different limits on one model, hand-edit a second definition under another name (for example `sonnet-low` and `sonnet-high`) and point the roles at them.
+
 :::note
-`netclaw model set` doesn't check that the model exists. Netclaw probes for metadata only on `openai`-type providers using OAuth device or PKCE auth — for Ollama, Anthropic, OpenRouter, and even API-key OpenAI, no probe runs, and a typo'd model ID is accepted quietly and fails at first use. Passing `--context-window` skips the probe even where it would have run. Use [`netclaw model discover`](#model-discover) to confirm the ID first.
+`netclaw model set` doesn't check that the model exists. Netclaw probes for metadata on `openai`-type providers using OAuth device or PKCE auth. For Ollama, Anthropic, OpenRouter and even API-key OpenAI, no identity probe runs, so a typo'd model ID is accepted quietly and fails at first use. Passing `--context-window` skips the identity probe even where it would have run. Passing `--max-output-tokens` or `--thinking` probes on any provider type, because the offered levels and the model's maximum come only from the probe. On a provider that doesn't use OAuth, that probe never fails the command. On an `openai` provider with OAuth the identity probe is required, so an unreachable provider or an unlisted model prints an `Error:` and exits `1`. Elsewhere, if the model isn't listed, `set` saves anyway and warns:
+
+```text
+Warning: provider 'lab-llama' did not list model 'nonexistent-model', so its thinking capability and maximum output are unknown.
+```
+
+Use [`netclaw model discover`](#model-discover) to confirm the ID first.
 :::
 
+The role must be `main`, `fallback` or `compaction`. Anything else prints `Error: Unknown role 'bogus'. Valid roles: main, fallback, compaction`.
+
+`set` accepts a context window below 4,096 tokens, but the daemon won't. It ignores the edit, `netclaw status` reports `config on disk not applied: ... ContextWindow (2000) is below minimum (4096)`, and `netclaw doctor` fails the Chat Client check. Set it back to 4,096 or more.
+
 The provider must already exist in your config. If it doesn't, the error lists your configured providers:
 
 ```
 Error: Provider 'my-cloud' not found in configuration.
-Configured providers: remote-gpu, my-anthropic
+Configured providers: lab-llama
 ```
 
 Shrinking Main's context window prints a warning because existing sessions with longer histories may fail until compacted.
 
 :::note
-On an older config that still uses inline roles, the first `model set` — or `model clear`, or a TUI assignment — converts the whole `Models` section to definitions and roles. It says nothing while doing it. Netclaw copies `netclaw.json` to `netclaw.json.legacy-models.bak` first, so the change is reversible. See [Migrating model configuration](/guides/migrating-model-config/).
+On an older config that still uses inline roles, the first `model set`, `model clear` or TUI assignment converts the whole `Models` section to definitions and roles. It says nothing while doing it. Netclaw copies `netclaw.json` to `netclaw.json.legacy-models.bak` first (`.legacy-models.2.bak` and up if that name is taken), so the change is reversible. See [Migrating model configuration](/guides/migrating-model-config/).
 :::
 
-Restart the daemon for changes to take effect: `netclaw daemon stop && netclaw daemon start`.
+The daemon restarts itself after a valid edit to `netclaw.json`. After environment-variable changes, restart it yourself: `netclaw daemon stop && netclaw daemon start` (or `docker restart netclaw` in a container).
 
 ### `model discover`
 
@@ -152,16 +244,15 @@ netclaw model discover <provider>
 Discovery hits the provider's API live, so it has to be reachable:
 
 ```
-Model ID                                 Context Window        Cost (in/out per 1M)
-claude-opus-4-1                          200,000               $15.00 / $75.00
-claude-sonnet-4                          200,000               $3.00 / $15.00
-gpt-4-turbo                              128,000               $10.00 / $30.00
-gpt-4o                                   128,000               $5.00 / $15.00
+Discovering models from 'lab-llama' (openai-compatible) at http://llm.example.internal:8080...
+
+Model ID                                 Context Window   Cost (in/out per 1M)
+demo-model                               131,072          -
 
-4 model(s) found.
+1 model(s) found.
 ```
 
-Cost and context window columns show `-` when the provider doesn't report them (common with Ollama and [OpenAI-compatible endpoints](/cli/provider/)).
+Cost shows `-` when the provider doesn't report it, which is common with Ollama and [OpenAI-compatible endpoints](/cli/provider/). An unknown provider prints `Error: Provider '<name>' not found in configuration.` and exits `1`. An unreachable server prints `Error: Connection failed: Connection refused (host:port)` (or `Name or service not known`). A server with no `/v1/models` prints `Error: The openai-compatible models API was not found at <url>/v1/models`. The endpoint may end in `/v1` or not, as [Self-hosted providers](/configuration/self-hosted-providers/#endpoint-url) explains.
 
 ### `model clear`
 
@@ -175,7 +266,7 @@ Clears Fallback or Compaction. Cannot clear Main:
 Error: Cannot clear the main model role. Use `netclaw model set main` to change it instead.
 ```
 
-The role assignment goes away; the definition stays. Re-assign that model later and its overrides are still there.
+The role assignment goes away and the definition stays. Re-assign that model later and its overrides are still there.
 
 ## Examples
 
@@ -189,6 +280,12 @@ netclaw model set fallback remote-gpu qwen3:8b
 # Use a cloud model for compaction
 netclaw model set compaction my-anthropic claude-sonnet-4
 
+# Raise the output limit and think harder
+netclaw model set main my-anthropic claude-opus-5-5 --max-output-tokens 64000 --thinking high
+
+# Back to the defaults for both
+netclaw model set main my-anthropic claude-opus-5-5 --clear-max-output-tokens --clear-thinking
+
 # Tell netclaw a local model can see images when detection says otherwise
 netclaw model set main remote-gpu qwen3-vl:32b --input-modalities "Text, Image"
 
@@ -207,7 +304,7 @@ netclaw model clear fallback
 
 ## Configuration
 
-Assignments live in `~/.netclaw/config/netclaw.json` under the `Models` key. Definitions hold the model facts; roles point at them by name:
+Assignments live in `~/.netclaw/config/netclaw.json` under the `Models` key. Definitions hold the model facts and roles point at them by name:
 
 ```json
 {
@@ -219,7 +316,9 @@ Assignments live in `~/.netclaw/config/netclaw.json` under the `Models` key. Def
         "Provenance": "Manual",
         "ContextWindow": 65536,
         "InputModalities": "Text, Image",
-        "OutputModalities": "Text"
+        "OutputModalities": "Text",
+        "MaxOutputTokens": 16000,
+        "Thinking": "Off"
       },
       "remote-gpu-qwen3-8b": {
         "Provider": "remote-gpu",
@@ -235,33 +334,30 @@ Assignments live in `~/.netclaw/config/netclaw.json` under the `Models` key. Def
 }
 ```
 
-`model set` names new definitions after the provider and model (`remote-gpu-qwen3-30b`), but the names are yours — hand-edit them to anything readable and point the roles at the new name. Definitions stick around after you switch a role away, which is what keeps their overrides intact.
+`Thinking` is stored PascalCase (`Off`, `Low`, `Medium`, `High`, `Max`). `model set` names new definitions after the provider and model (`remote-gpu-qwen3-30b`), but the names are yours. Hand-edit them to anything readable and point the roles at the new name. Definitions stick around after you switch a role away, which is what keeps their overrides intact.
+
+[Models configuration](/configuration/models/) covers the fields in full. Older configs use an inline shape that netclaw still reads. See [Migrating model configuration](/guides/migrating-model-config/).
 
-[Models configuration](/configuration/models/) covers the fields in full. Older configs use an inline shape that netclaw still reads — see [Migrating model configuration](/guides/migrating-model-config/).
+The daemon restarts itself after the config changes.
 
-Restart the daemon afterward.
+After you set your models, run [`netclaw status`](/cli/status/) to confirm the daemon picked them up.
 
 ## Exit codes
 
 `0` on success, `1` on invalid arguments, unknown provider, or validation failure.
 
-## What's next
-
-After setting your models, run [`netclaw status`](/cli/status/) to confirm the daemon picked them up.
-
-## Related commands
+## Related pages
 
-- [`netclaw provider`](/cli/provider/) — add providers before assigning models
-- [Models configuration](/configuration/models/) — the `Models` shape these commands write
-- [Migrating model configuration](/guides/migrating-model-config/) — converting an older inline `Models` section
-- [`netclaw status`](/cli/status/) — see which model the daemon is actually using
-- [`netclaw doctor`](/cli/doctor/) — checks model config validity
-- [`netclaw init`](/cli/init/) — initial model setup during onboarding
+- [`netclaw provider`](/cli/provider/): add providers before assigning models
+- [Models configuration](/configuration/models/): the `Models` shape these commands write
+- [Migrating model configuration](/guides/migrating-model-config/): converting an older inline `Models` section
+- [`netclaw status`](/cli/status/): confirm which model the daemon picked up
+- [`netclaw doctor`](/cli/doctor/): checks model config validity
 
 ## Resources
 
-- [Ollama context length FAQ](https://github.com/ollama/ollama/blob/main/docs/faq.md#how-can-i-specify-the-context-window-size) — Ollama serves at its own `num_ctx` and truncates past it regardless of `--context-window`; set both
-- [Ollama model library](https://ollama.com/library) — browse models for local inference
-- [Anthropic models](https://docs.anthropic.com/en/docs/about-claude/models) — Claude specs, pricing, context windows
-- [OpenRouter catalog](https://openrouter.ai/models) — compare across providers
-- [OpenAI models](https://platform.openai.com/docs/models) — GPT specs, pricing, context windows
+- [Ollama context length FAQ](https://docs.ollama.com/faq#how-can-i-specify-the-context-window-size): Ollama serves at its own `num_ctx` and truncates past it regardless of `--context-window`, so set both
+- [Ollama model library](https://ollama.com/library): browse models for local inference
+- [Anthropic models](https://docs.anthropic.com/en/docs/about-claude/models): Claude specs, pricing and context windows
+- [OpenRouter catalog](https://openrouter.ai/models): compare across providers
+- [OpenAI models](https://platform.openai.com/docs/models): GPT specs, pricing and context windows
diff --git a/src/content/docs/cli/overview.md b/src/content/docs/cli/overview.md
index c4ee0b4..b257447 100644
--- a/src/content/docs/cli/overview.md
+++ b/src/content/docs/cli/overview.md
@@ -1,143 +1,159 @@
 ---
-title: "CLI Overview"
-description: "Netclaw command-line interface reference."
+title: "CLI overview"
+description: "Every netclaw command: what it does, whether it needs the daemon, output formats, exit codes, and the environment variables the CLI reads."
 ---
 
-The `netclaw` CLI controls your agent — configuration, diagnostics, chat, daemon lifecycle.
+The `netclaw` CLI controls your agent: setup, configuration, diagnostics, chat and daemon lifecycle. Pick a command from the map below, or run `netclaw <command> --help` for the built-in help.
 
 ```bash
 netclaw <command> [options]
 ```
 
-The **Daemon** column in each table indicates whether the netclaw daemon (the background process that manages sessions, connectors, and model routing) must be running for that command to work.
+Chat, sessions, status and stats are thin clients. The daemon (`netclawd`, the background process that owns sessions, connectors and model routing) does the work, so those commands fail when it isn't running. `status`, `stats` and `sessions` print `[FAIL] ... unable to reach daemon`. `chat -p` prints `[headless:error] Connection refused (127.0.0.1:5199)` and `[turn:failed] category=infra kind=ChannelFailure` on stderr and exits `1`. The **Daemon** column says which commands need it.
 
-## Commands
+## Command map
 
-### Chat & Sessions
+### Chat and sessions
 
-| Command | Description | Daemon | TUI |
-|---------|-------------|--------|-----|
-| [`chat`](/cli/chat/) | Interactive terminal UI chat | Required | Yes |
-| `chat -p <text>` | Headless single-prompt mode (supports `--resume` / `-r`, `--json`) | Required | No |
+| Command | What it does | Daemon | TUI |
+|---------|--------------|--------|-----|
+| [`chat`](/cli/chat/) | Interactive terminal chat | Required | Yes |
+| [`chat --onboarding`](/cli/chat/#identity-interview) | Interactive chat that starts the guided identity interview | Required | Yes |
+| [`chat -p <text>`](/cli/chat/#headless-mode) | One headless prompt, then exit. Takes `--resume` and `--json`. | Required | No |
 | [`sessions`](/cli/sessions/) | Browse and resume recent sessions | Required | Yes |
-| `sessions --once` | List sessions without the terminal UI | Required | No |
-| `sessions --json` | JSON output (implies `--once`) | Required | No |
+| [`sessions --once`](/cli/sessions/#plain-text-and-json-output) | List sessions without the TUI. `--json` implies it. | Required | No |
+
+### Setup and diagnostics
+
+| Command | What it does | Daemon | TUI |
+|---------|--------------|--------|-----|
+| [`init`](/cli/init/) | First-run wizard: provider, identity, posture, health check | No (starts it) | Yes |
+| [`config`](/cli/config/) | Settings dashboard for everything `init` doesn't cover. `config retention` sets how long logs are kept. | No | Yes |
+| [`doctor`](/cli/doctor/) | 24 configuration and connectivity checks, with `--fix` | Optional | No |
+| [`status`](/cli/status/) | Daemon health, model, connectors | Required | No |
+| [`stats`](/cli/stats/) | Token, session, memory and skill usage | Required | With `--tui` |
+| [`update`](/cli/update/) | Check for and install updates | No | No |
+| `version`, `--version`, `-V` | Print version, commit and build time | No | No |
+
+### Providers, models and tools
+
+| Command | What it does | Daemon | TUI |
+|---------|--------------|--------|-----|
+| [`provider`](/cli/provider/) | Add, rename and remove LLM providers | No | Bare `provider` |
+| [`model`](/cli/model/) | Assign models to the Main, Fallback and Compaction roles | No | Bare `model` |
+| [`mcp`](/cli/mcp-tools/) | MCP server profiles and tool permissions | Optional | `mcp tools`, `mcp permissions` |
+| [`approvals`](/cli/approvals/) | List and revoke saved grants | No | Bare `approvals` |
+| [`secrets`](/cli/secrets/) | Store encrypted credentials with `secrets set` | No | No |
+| [`skill`](/cli/skill/) | List, inspect and sync skills and skill sources | `list` and `sync` need it | No |
+| [`webhooks`](/cli/webhooks/) | Manage inbound webhook routes | `set` and `delete` need it | No |
+| [`reminder`](/cli/reminder/) | Manage scheduled reminders | Required | `ui` or `tui` |
+| [`memory`](/cli/memory/) | Provision the embedding model and backfill memory embeddings | No | No |
+
+### Daemon and devices
+
+| Command | What it does |
+|---------|--------------|
+| [`daemon start`, `stop`, `status`](/cli/daemon/) | Start the daemon in the background, stop it, or show its process state |
+| [`daemon install`, `uninstall`](/cli/daemon/) | Install or remove the systemd user unit (Linux). See [systemd](/deployment/systemd/). |
+| [`daemon pair`](/cli/daemon/) | Print a pairing code on the host machine |
+| [`daemon devices`](/cli/daemon/) | List paired devices. `daemon devices revoke <name>` removes one. |
+| [`pair <endpoint>`](/guides/pairing-remote-devices/) | Pair this machine with a remote daemon, using the code from `daemon pair` |
+
+There is no `daemon restart`. The daemon restarts itself when `netclaw.json` changes. After a change to `secrets.json` or an environment variable, run `netclaw daemon stop` and then `netclaw daemon start`, or `docker restart <container>` in a container.
+
+If you just ran `netclaw init`, run `netclaw config` next. Channels, search, network exposure, webhooks and skill sources live there, not in `init`.
+
+## First run
 
-### First Run & Diagnostics
-
-| Command | Description | Daemon | TUI |
-|---------|-------------|--------|-----|
-| [`init`](/cli/init/) | First-run setup wizard (starts the daemon for you) | Not required | Yes |
-| [`doctor`](/cli/doctor/) | Config and connectivity diagnostics; `--fix` for auto-repair | Optional | No |
-| [`status`](/cli/status/) | Daemon runtime health, connector status, model info | Required | No |
-| [`stats`](/cli/stats/) | Token usage, session counts, memory stats; `--tui` for dashboard | Required | No |
-
-### Daemon Management
-
-| Command | Description |
-|---------|-------------|
-| `daemon start` | Start daemon as a background process |
-| `daemon stop` | Stop daemon gracefully |
-| `daemon status` | Show daemon process status |
-| [`daemon install`](/deployment/systemd/) | Install systemd user service (Linux) |
-| [`daemon uninstall`](/deployment/systemd/#uninstalling) | Remove systemd user service (Linux) |
-| `daemon pair` | Generate a pairing code (run on the host machine) |
-| `daemon devices` | List paired devices |
-| `daemon devices revoke <name>` | Revoke a paired device by name |
-| `pair <endpoint>` | Pair this device with a remote daemon using a pairing code (run on the remote device) |
-
-`daemon install` writes a `systemd --user` unit, so the daemon runs under your own user account at the same privilege you have at the shell. No root, no dedicated service identity. See [systemd Service](/deployment/systemd/) for the security model and operational walkthrough.
-
-See the [Pairing Remote Devices](/guides/pairing-remote-devices/) guide for the full walkthrough.
-
-### Configuration
+```bash
+netclaw init      # provider, identity, posture, health check. Opens chat when it passes.
+netclaw config    # channels, search, exposure, skill sources
+netclaw doctor    # check everything is wired up
+netclaw status    # confirm the daemon is healthy
+```
 
-| Command | Description | Daemon | TUI |
-|---------|-------------|--------|-----|
-| [`config`](/cli/config/) | Post-init setup: channels, search, network exposure, browser automation, telemetry, skill sources | No | Yes |
-| [`provider`](/cli/provider/) | Manage LLM providers | No | Yes (bare invocation) |
-| [`model`](/cli/model/) | Manage model role assignments | No | Yes (bare invocation) |
-| [`mcp`](/cli/mcp-tools/) | Manage [MCP](https://modelcontextprotocol.io/specification) (Model Context Protocol) server profiles and tool permissions | Optional | Partial |
-| [`webhooks`](/cli/webhooks/) | Manage inbound webhook routes | No | No |
-| [`secrets`](/cli/secrets/) | Store encrypted secrets via `secrets set <key> <value>`. See [Secrets](/security/secrets/). | No | No |
-| [`reminder`](/cli/reminder/) | Manage scheduled reminders | Required | Yes (`ui` or `tui` subcommand) |
-| [`skill`](/cli/skill/) | Manage skills and external skill sources. See [Skills](/skills/overview/). | No | No |
+Once you're running, [First conversation](/getting-started/first-conversation/) walks through your first chat.
 
-If you just ran `netclaw init`, `netclaw config` is your next stop — channels (Slack, Discord, Mattermost), search, and network exposure all live there.
+![netclaw status output: overall healthy, version 0.28.2, the active model, and connector lines for Discord, Mattermost, the demo-utilities MCP server, Slack and the TUI](/screenshots/output/status.png)
 
-See [Configuration](/configuration/managed-providers/) for field references and config file details.
+`netclaw status` is the quickest check that the daemon, model and connectors are healthy.
 
-### Housekeeping
+## Global flags
 
-| Command | Description |
-|---------|-------------|
-| `update` | Check for and install CLI updates; `--check` to check only, `--channel <stable\|beta>` to switch release channel |
-| `version` / `--version` / `-V` | Print version, commit hash, and build timestamp |
+| Flag | Effect |
+|------|--------|
+| `--help`, `-h`, `help` | Print the command list. Also works after a command, as in `netclaw doctor --help`. |
+| `--version`, `-V`, `version` | Print the version. |
 
-## First Run
+There are no other global flags. Run bare `netclaw` and it prints the help and exits `2`.
 
-```bash
-# First-time setup (starts the daemon automatically)
-netclaw init
+`--help` works after every command, including `netclaw mcp add --help`, and exits `0`. That includes `netclaw daemon --help`, and a bare `netclaw daemon` prints the same usage and exits `0`. An unknown subcommand such as `netclaw daemon restart` prints the usage and exits `1`.
 
-# Connect channels, enable search, set exposure mode
-netclaw config
+```
+$ netclaw --version
+netclaw 0.28.2 (commit 7419d84, built 2026-10-29T00:09:05Z)
+```
 
-# Check everything is wired up
-netclaw doctor
+## Output formats
 
-# Verify the daemon is healthy
-netclaw status
-```
+| Command | Flag | Shape |
+|---------|------|-------|
+| `status` | `--json` or `--format json` | camelCase object |
+| `stats`, `stats skills` | `--json` or `--format json` | camelCase object |
+| `doctor` | `--format json` | camelCase object with `exitCode`, `checks` and `fix` |
+| `sessions` | `--json` | PascalCase array. Includes `SessionId`. |
+| `chat -p` | `--json` | One camelCase envelope with `sessionId`, `response`, `turnResponses` and `usage`. A failed turn adds `errorCategory` and `errorKind`. The exit code is still the primary signal. |
+| `approvals list`, `webhooks list` | `--json` | See each command's page |
 
-`netclaw init` is intentionally minimal — it doesn't set up Slack, Discord, web search, or network exposure. Run `netclaw config` immediately after to configure those. If `status` shows errors, run `netclaw doctor --fix` to auto-repair common issues.
+The `sessions` output is PascalCase and the others are camelCase. Check the key names before you write a `jq` filter.
 
-```bash
-# Start chatting
-netclaw chat
-```
+## Exit codes
 
-Once you're up and running, head to [First Conversation](/getting-started/first-conversation/) for a walkthrough of your first chat session.
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | The command failed: bad options, validation errors, unreachable daemon or a runtime failure |
+| `2` | Bare `netclaw` or an unknown command (`netclaw: 'bogus' is not a netclaw command. See 'netclaw --help'.`). `doctor` also uses `2` for warnings only, and `status` uses it for a degraded daemon. |
 
-![netclaw status output](/screenshots/output/status.png)
+Each command's page lists the codes scripts should care about.
 
-`netclaw status` shows the daemon's health, active model, and connector states.
+## Where config and data live
 
-## Config Files
+Everything lives under `~/.netclaw`, or `$NETCLAW_HOME` if you set it. See [Data directory layout](/reference/data-directory/) for the full tree.
 
 | File | Purpose |
 |------|---------|
 | `~/.netclaw/config/netclaw.json` | Main configuration |
-| `~/.netclaw/config/secrets.json` | Encrypted credentials overlay |
-| `NETCLAW_*` env vars | Highest-priority overrides |
+| `~/.netclaw/config/secrets.json` | Encrypted credentials, written by `netclaw secrets set` and the provider commands |
+| `~/.netclaw/client/config.json` | The daemon endpoint a paired client uses |
+| `NETCLAW_*` environment variables | Highest priority, overrides both files |
 
-See [Configuration](/configuration/managed-providers/) for field references.
+The CLI and the daemon layer configuration in that order: `netclaw.json`, then `secrets.json`, then `NETCLAW_*` variables.
 
-## Exit Codes
+## Environment variables
 
-| Code | Meaning |
-|------|---------|
-| `0` | Success |
-| `1` | Validation, policy, or runtime failure |
-| `2` | Usage or argument error |
+| Variable | Effect |
+|----------|--------|
+| `NETCLAW_HOME` | Base directory instead of `~/.netclaw` |
+| `NETCLAW_DAEMON_ENDPOINT` | Daemon URL for `chat`, `sessions`, `status` and `stats`. Wins over `client/config.json` and the `Daemon` section of `netclaw.json`. The default is `http://127.0.0.1:5199`. |
+| `NETCLAW_DAEMON_PATH` | Where `netclaw daemon start` finds the `netclawd` binary |
+| `NETCLAW_<Section>__<Key>` | Override any config key. Double underscores separate path segments, as in `NETCLAW_Providers__my-anthropic__ApiKey`. |
+| `CHROME_PATH`, `NETCLAW_PLAYWRIGHT_BROWSER` | Where browser-automation detection looks for a browser |
 
-## Background Update Check
+## Background update check
 
-Non-TUI commands silently check for updates on startup. TUI commands skip this — run `netclaw update --check` to check manually.
+Commands that don't open a full-screen UI check for a new release in the background and print a one-line notice if one exists. `init`, `update`, `secrets`, `daemon`, `chat` (including `chat -p`) and `sessions` never run the check. Run [`netclaw update --check`](/cli/update/) to check by hand.
 
-## Version Output
+## Related pages
 
-```
-netclaw 0.22.1 (commit bc2170d, built 2026-06-01T12:38:11Z)
-```
+- [Quickstart](/getting-started/quickstart/): get netclaw running from scratch
+- [Installation](/getting-started/installation/): platform-specific install instructions
+- [Data directory layout](/reference/data-directory/): what lives under `~/.netclaw`
+- [Slash commands](/reference/slash-commands/): commands you type inside a chat
+- [Docker deployment](/deployment/docker/): run the CLI against a containerized daemon
 
-## Related
+## Resources
 
-- [Quickstart](/getting-started/quickstart/) — Get netclaw running from scratch
-- [Installation](/getting-started/installation/) — Platform-specific install instructions
-- [First Conversation](/getting-started/first-conversation/) — Walk through your first chat session
-- [systemd deployment](/deployment/systemd/) — Run the daemon as a system service
-- [Docker deployment](/deployment/docker/) — Containerized daemon setup
-- [.NET CLI tools documentation](https://learn.microsoft.com/en-us/dotnet/core/tools/) — Background on .NET global tools, which is how netclaw is distributed
-- [systemd user services](https://wiki.archlinux.org/title/Systemd/User) — Reference for `daemon install` / `daemon uninstall` on Linux
-- [Model Context Protocol spec](https://modelcontextprotocol.io/specification) — MCP specification
+- [.NET tools documentation](https://learn.microsoft.com/en-us/dotnet/core/tools/): background on the .NET toolchain netclaw is built on
+- [systemd user services](https://wiki.archlinux.org/title/Systemd/User): reference for `daemon install` and `daemon uninstall` on Linux
+- [Model Context Protocol specification](https://modelcontextprotocol.io/specification): the protocol behind `netclaw mcp`
diff --git a/src/content/docs/cli/provider.md b/src/content/docs/cli/provider.md
index e320bb7..ef6b816 100644
--- a/src/content/docs/cli/provider.md
+++ b/src/content/docs/cli/provider.md
@@ -1,45 +1,72 @@
 ---
 title: "netclaw provider"
-description: "Manage LLM providers."
+description: "Add, rename, validate and remove the LLM providers netclaw talks to, from a TUI or from scripts."
 ---
 
-Manage the LLM providers that netclaw talks to. Run `netclaw provider` for an interactive TUI, or use subcommands to script provider setup.
+`netclaw provider` manages the LLM providers netclaw talks to. Run it bare for an interactive manager, or use subcommands to script provider setup. A provider is a named connection (a type, an endpoint and credentials). [`netclaw model`](/cli/model/) then assigns models from it to roles.
 
-If you haven't run `netclaw init` yet, start there — it configures your first provider.
+If you haven't run [`netclaw init`](/cli/init/) yet, start there. It configures your first provider.
 
 ## Usage
 
 ```bash
-netclaw provider                          # launch TUI
-netclaw provider <subcommand> [options]   # CLI mode
+netclaw provider                          # interactive manager
+netclaw provider <subcommand> [options]   # scriptable
 ```
 
-## Provider Manager TUI
+Most of the manager and every subcommand run without the daemon. The exception is the **ChatGPT Subscription (browser)** sign-in, which needs a running daemon (`Could not reach the daemon. Is it running?`) because the CLI reads the OAuth tokens through a local-control endpoint on it. A CLI and daemon on different versions fail with `The daemon does not support the local-control provider OAuth read. Update the daemon and CLI to the same Netclaw version.` The device-code sign-in and `provider add --auth oauth-device` run in the CLI alone. The daemon restarts itself when `netclaw.json` changes. A credential you change in `secrets.json` needs a manual restart: `netclaw daemon stop` then `netclaw daemon start`, or `docker restart <container>`.
 
-![Provider Manager TUI showing configured providers with health status](/screenshots/output/provider-manager.png)
+## Provider manager
 
-On launch, the TUI probes every configured provider and shows health status:
+```bash
+netclaw provider
+```
+
+![Provider Manager listing lab-llama and my-ollama with a check mark, my-deepseek with a warning triangle, and five unconfigured providers below them](/screenshots/output/provider-manager.png)
+
+The `my-deepseek` row carries the warning because its key is a placeholder, and the Provider column stops at 40 characters, so the long OpenAI-compatible label for `lab-llama` is cut with an ellipsis. Auth shows a dash for providers that need no credential.
+
+On launch the manager probes every configured provider and shows its health. Providers you haven't configured appear as `(not configured)` rows, and **+ Add new provider...** starts the add flow.
 
 | Indicator | Meaning |
 |-----------|---------|
 | `✓` | Healthy, models discovered |
-| `⚠` | Unreachable or auth failure |
+| `⚠` | Unreachable or authentication failed |
 | `…` | Probe in progress |
 
-Select a provider to view details (type, auth, endpoint, model count) or take action:
+Select a provider to see its type, auth method, endpoint, status and model count:
+
+```
+Provider: lab-llama
+  Type:     OpenAI-compatible (llama.cpp / vLLM / DwarfStar ds4)
+  Auth:     -
+  Endpoint: http://llm.example.internal:8080
+  Status:   ✓ Healthy
+  Models:   1 discovered
+```
+
+| Key | Where | Action |
+|-----|-------|--------|
+| `↑` / `↓` | List | Move |
+| `Enter` | List | Open details, or start the add flow on a sentinel row |
+| `Delete` | List | Remove the highlighted provider |
+| `K` | Details | Update the API key |
+| `N` | Details | Rename the provider |
+| `R` | Details | Remove the provider |
+| `V` | Details | Re-validate the connection |
+| `C` / `O` | Device-code sign-in screen | Copy the code, open the verification URL in a browser. On the browser sign-in screen, `C` copies the URL when the browser didn't open. |
+| `Esc` | Details and add flow | Go back. Does nothing on the list. |
+| `Ctrl+Q` | Anywhere | Quit |
+
+The add flow asks for the endpoint next. Here it is for an OpenAI-compatible server, with the default shown as a placeholder.
 
-| Key | Action |
-|-----|--------|
-| `↑` / `↓` | Navigate |
-| `Enter` | Select / open details |
-| `K` | Update API key (details view) |
-| `R` | Remove provider (details view) |
-| `V` | Re-validate connection (details view) |
-| `Esc` | Back / quit |
+![Provider Manager add flow for OpenAI-compatible, naming the provider my-openai-compatible and showing an empty endpoint field with the default http://localhost:11434 as a placeholder](/screenshots/output/provider-add-openai-compatible.png)
 
-The sentinel row `+ Add new provider...` starts an interactive add flow. Netclaw validates connectivity with a 20-second timeout and reports how many models it found.
+The hint under the field says authentication is optional for this type. Type the server address with or without a `/v1` suffix. Both work, and the manager stores what you typed.
 
-OpenAI OAuth is only available through this TUI flow — select Add, choose OpenAI, then pick "ChatGPT Subscription" to authenticate with your existing account.
+The connectivity check during an add gives up after 45 seconds, then reports how many models it found. Individual requests time out after 10 seconds for hosted providers and 30 seconds for self-hosted ones.
+
+OpenAI offers two ChatGPT sign-ins as well as an API key: **ChatGPT Subscription (recommended)**, which uses a device code, and **ChatGPT Subscription (browser)**.
 
 ## Subcommands
 
@@ -51,27 +78,61 @@ netclaw provider list
 
 ```
 Name                 Provider               Auth       Endpoint
-my-anthropic         Anthropic              ApiKey     https://api.anthropic.com
-my-ollama            Ollama                 None       http://localhost:11434
+lab-llama            OpenAI-compatible (llama.cpp / vLLM / DwarfStar ds4) None       http://llm.example.internal:8080
+my-ds                DeepSeek               ApiKey     https://api.deepseek.com/v1
 ```
 
-This shows static config only — no live health probing. Open the TUI to see real-time provider health.
+`list` reads config only. It doesn't probe, so open the manager to see live health. With nothing configured it prints `No providers configured.` and a pointer to `provider add`.
 
 ### `provider add`
 
 ```bash
-netclaw provider add <name> <type> [--api-key <key>] [--endpoint <url>]
+netclaw provider add <name> <type> [options]
 ```
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `--api-key <key>` | API key for the provider | Prompted if required |
-| `--endpoint <url>` | Custom endpoint URL | Provider default |
-| `--auth <method>` | Auth method: `api-key` or `oauth-device` | Inferred from provider |
+| `--api-key <key>` | API key for the provider | Prompted, for providers that only take a key |
+| `--endpoint <url>` | Endpoint URL | The type's default (see [types](#provider-types)) |
+| `--auth <method>` | `api-key` or `oauth-device` | Inferred from the type |
 | `--github-host <url>` | GitHub Enterprise auth host (`github-copilot` only) | `https://github.com` |
 | `--github-api-base <url>` | GitHub Enterprise API base (`github-copilot` only) | `https://api.github.com` |
 
-Provider type and endpoint are stored in `~/.netclaw/config/netclaw.json`. Credentials are encrypted in [`secrets.json`](/cli/secrets/). Restart the daemon after adding a provider so it picks up the new config.
+How the credential is chosen:
+
+- **Key-only providers** (Anthropic, DeepSeek, OpenRouter, Venice.ai) prompt for the key when you leave out `--api-key`.
+- **Self-hosted providers** (Ollama, OpenAI-compatible) need no key. Pass `--api-key` to send a Bearer token to a gateway.
+- **`openai`** with neither `--api-key` nor `--auth` starts the OAuth device flow and waits for you to approve the code it prints. Pass `--api-key` to use a key.
+- **`github-copilot`** only supports `--auth oauth-device`.
+
+An unknown type lists the valid ones:
+
+```
+Error: Unknown provider type 'nosuchtype'.
+Known types: anthropic, deepseek, github-copilot, ollama, openai, openai-compatible, openrouter, veniceai
+```
+
+Type and endpoint land in `~/.netclaw/config/netclaw.json`. Credentials are encrypted in [`secrets.json`](/cli/secrets/). For an OAuth sign-in, the access and refresh tokens are encrypted, but `Providers.<name>.OAuthTokenExpiry` is stored there as plain text because it's a date, not a secret. It never goes in `netclaw.json`, so a token refresh doesn't restart the daemon. If an older `OAuthTokenExpiry` is still in `netclaw.json`, `netclaw doctor --fix` moves it.
+
+An endpoint must be a full `http://` or `https://` URL. A bare host is rejected before anything is written:
+
+```
+Error: Endpoint 'llm.example.internal:8080' is not an absolute http or https URL. Use a form like http://localhost:8080.
+```
+
+Provider names match without regard to case. `netclaw provider add Stub ...` when `stub` exists updates `stub`, and `remove`, `rename` and `model set` accept any spelling too.
+
+### `provider rename`
+
+```bash
+netclaw provider rename <old-name> <new-name>
+```
+
+```
+Renamed provider 'lab-ollama' to 'lab-a100'.
+```
+
+Rename changes the key under `Providers` and repoints every model definition that used the old name, so model roles keep working. If any were repointed, it adds `Reassigned model role(s): ...`. An unknown name prints `Error: Provider '<name>' not found.` and exits `1`.
 
 ### `provider remove`
 
@@ -79,83 +140,100 @@ Provider type and endpoint are stored in `~/.netclaw/config/netclaw.json`. Crede
 netclaw provider remove <name>
 ```
 
-Netclaw blocks removal if any [model role](/cli/model/) (Main, Fallback, or Compaction) references the provider:
+```
+Removed provider 'lab-a100'
+```
+
+An unknown name prints `Provider '<name>' not found.` and exits `1`.
+
+`provider remove` refuses a provider that a model role still uses:
 
 ```
-Error: Cannot remove provider 'my-anthropic' — referenced by model role(s): Main, Fallback
+Error: Cannot remove provider 'lab-a100' ... referenced by model role(s): Main
 Run `netclaw model set` to reassign these roles first, or `netclaw model clear` for optional roles.
 ```
 
-Reassign models first with [`netclaw model`](/cli/model/), then remove.
+It exits `1` and changes nothing. Reassign the role with [`netclaw model set`](/cli/model/#model-set), or drop an optional one with `netclaw model clear`, then remove the provider. If the `Models` section itself can't be resolved (a role names a definition that doesn't exist), `remove` stops with `Cannot remove provider ... the Models section in netclaw.json cannot be resolved` and tells you to repair it first. The Provider Manager's `R` and `Delete` keys apply the same check and show `Referenced by model role(s): ...`.
 
 ## Provider types
 
-Pick Anthropic or OpenAI for hosted models, Ollama for fully local inference, or OpenRouter for access to models from multiple vendors through a single key.
+Pick Anthropic or OpenAI for hosted models, Ollama for local inference, OpenAI-compatible for llama.cpp or vLLM, or OpenRouter for many vendors behind one key.
 
-| Type | Display Name | Default Endpoint | Auth |
-|------|-------------|-----------------|------|
-| `ollama` | Ollama | `http://localhost:11434` | None |
-| `openai-compatible` | llama.cpp / vLLM / DwarfStar ds4 | `http://localhost:11434` | None |
-| `openai` | OpenAI | `https://api.openai.com` | OAuth or API key |
+| Type | Display name | Default endpoint | Auth |
+|------|--------------|------------------|------|
 | `anthropic` | Anthropic | `https://api.anthropic.com` | API key |
+| `deepseek` | DeepSeek | `https://api.deepseek.com/v1` | API key |
+| `github-copilot` | GitHub Copilot | `https://api.githubcopilot.com` | OAuth device flow |
+| `ollama` | Ollama | `http://localhost:11434` | None |
+| `openai` | OpenAI | `https://api.openai.com` | OAuth (device or browser) or API key |
+| `openai-compatible` | OpenAI-compatible (llama.cpp / vLLM / DwarfStar ds4) | `http://localhost:11434` | None, optional key |
 | `openrouter` | OpenRouter | `https://openrouter.ai/api/v1` | API key |
-| `github-copilot` | GitHub Copilot | `https://api.githubcopilot.com` | OAuth (device) |
 | `veniceai` | Venice.ai | `https://api.venice.ai/api/v1` | API key |
 
-For hosted-provider setup details — including GitHub Copilot on GitHub Enterprise — see [Managed Providers](/configuration/managed-providers/).
+`openai-compatible` has no thinking dialect by default, so `netclaw model set ... --thinking` fails until you set `Providers:<name>:VendorOptions:ThinkingDialect` or `model set` detects llama.cpp. See [Output limit and thinking level](/cli/model/#output-limit-and-thinking-level).
+
+For the self-hosted types, give the server address. `http://llm.example.internal:8080` and `http://llm.example.internal:8080/v1` both work ([endpoint rules](/configuration/self-hosted-providers/#endpoint-url)). See [Managed providers](/configuration/managed-providers/) for hosted-provider setup, including GitHub Copilot on GitHub Enterprise, and [Self-hosted providers](/configuration/self-hosted-providers/) for llama.cpp and vLLM.
 
 ## Examples
 
 ```bash
-# Local Ollama on a remote GPU server
+# Ollama on a GPU box
 netclaw provider add my-ollama ollama --endpoint http://my-gpu-server:11434
 
-# Anthropic with an API key
+# Anthropic with a key
 netclaw provider add my-anthropic anthropic --api-key sk-ant-...
 
-# OpenAI with an API key
-netclaw provider add my-openai openai --api-key sk-proj-...
+# OpenAI through your ChatGPT subscription
+netclaw provider add my-openai openai --auth oauth-device
+
+# DeepSeek
+netclaw provider add my-deepseek deepseek --api-key sk-...
 
 # OpenRouter
 netclaw provider add my-openrouter openrouter --api-key sk-or-...
 
-# llama.cpp or vLLM behind an OpenAI-compatible endpoint
-netclaw provider add my-llama openai-compatible --endpoint http://localhost:8080
+# llama.cpp or vLLM
+netclaw provider add my-llama openai-compatible --endpoint http://llm.example.internal:8080
 
 # GitHub Copilot on GitHub Enterprise
 netclaw provider add copilot-ghe github-copilot --auth oauth-device \
   --github-host https://github.example.com \
   --github-api-base https://github.example.com/api/v3
 
-# Remove a provider
-netclaw provider remove my-ollama
+# Give a provider a better name, then drop one you don't use
+netclaw provider rename my-ollama lab-a100
+netclaw provider remove my-openrouter
 ```
 
-After adding a provider, assign it to a model role with [`netclaw model set`](/cli/model/).
+After adding a provider, assign it to a role with [`netclaw model set`](/cli/model/).
 
 ## Override API keys with environment variables
 
-Skip config files entirely by setting an environment variable:
+Set an environment variable instead of writing the key to disk:
 
 ```bash
 export NETCLAW_Providers__my-anthropic__ApiKey="sk-ant-..."
 ```
 
-Double underscores (`__`) separate config path segments. The `NETCLAW_` prefix is required.
+Double underscores separate path segments, and the `NETCLAW_` prefix is required. Restart the daemon after you change one.
+
+## Exit codes
+
+`0` on success. `1` for missing arguments, an unknown type, an unknown provider, a provider a model role still uses, or a failed OAuth flow.
 
-## Related commands
+## Related pages
 
-- [`netclaw init`](/cli/init/) — set up your initial provider during first-run
-- [`netclaw model`](/cli/model/) — assign providers to model roles
-- [`netclaw doctor`](/cli/doctor/) — validate provider connectivity and config health
-- [`netclaw status`](/cli/status/) — check the active provider and model at runtime
-- [`netclaw secrets`](/cli/secrets/) — manage encrypted credentials in `secrets.json`
+- [`netclaw init`](/cli/init/): set up your first provider
+- [`netclaw model`](/cli/model/): assign provider models to roles
+- [`netclaw doctor`](/cli/doctor/): validate provider configuration
+- [`netclaw status`](/cli/status/): see the provider and model the daemon is using
+- [`netclaw secrets`](/cli/secrets/): manage encrypted credentials
 
 ## Resources
 
-- [Anthropic API keys](https://console.anthropic.com/settings/keys) — create and manage Anthropic keys
-- [OpenAI API keys](https://platform.openai.com/api-keys) — create and manage OpenAI keys
-- [OpenRouter keys](https://openrouter.ai/keys) — create and manage OpenRouter keys
-- [OpenRouter model catalog](https://openrouter.ai/models) — browse available models
-- [Ollama](https://ollama.com/) — install and run local models
-- [llama.cpp server docs](https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md) — set up an OpenAI-compatible local server
+- [Anthropic API keys](https://console.anthropic.com/settings/keys): create and manage Anthropic keys
+- [OpenAI API keys](https://platform.openai.com/api-keys): create and manage OpenAI keys
+- [DeepSeek API keys](https://platform.deepseek.com/api_keys): create and manage DeepSeek keys
+- [OpenRouter keys](https://openrouter.ai/keys): create and manage OpenRouter keys
+- [Ollama](https://ollama.com/): install and run local models
+- [llama.cpp server docs](https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md): run an OpenAI-compatible server
diff --git a/src/content/docs/cli/reminder.md b/src/content/docs/cli/reminder.md
index f161f1e..77b61be 100644
--- a/src/content/docs/cli/reminder.md
+++ b/src/content/docs/cli/reminder.md
@@ -1,11 +1,11 @@
 ---
 title: "netclaw reminder"
-description: "Schedule autonomous agent sessions that fire once, on an interval, or via cron."
+description: "Create, inspect and test reminders that run agent sessions once, on an interval, or on a cron schedule."
 ---
 
-`netclaw reminder` schedules autonomous agent sessions. A reminder fires on a schedule (once, on an interval, or via [cron](https://crontab.guru/)), runs a session with your instructions, and optionally delivers results to a Slack channel.
+`netclaw reminder` manages scheduled agent sessions. A reminder fires on a schedule (once, on an interval, or via [cron](https://crontab.guru/)), runs a session with your instructions, and can post the result to a channel. Use `reminder run` to test one before the schedule does, because a scheduled run can't answer approval prompts. The [unattended runs guide](/guides/unattended-runs/) explains why and how to prepare.
 
-All subcommands except `validate` require the daemon to be running. Start it with `netclaw daemon start` or [`netclaw init`](/cli/init/).
+Every subcommand except `validate` needs a running daemon. Without one you get `[FAIL] reminder <subcommand>: requires a running daemon.` and exit code 1. Start it with `netclaw daemon start`, or `docker restart <container>` in Docker.
 
 ## Usage
 
@@ -17,18 +17,19 @@ netclaw reminder <subcommand> [options]
 
 | Subcommand | Description |
 |-----------|-------------|
-| `list` | List all active reminders |
+| `list` | List reminders as a table, enabled or not. `--json` for scripts |
 | `create` | Create or update a reminder |
 | `ui` / `tui` | Interactive reminder builder |
-| `show <id>` | Show reminder details |
+| `show <id>` | Show a reminder's details |
 | `history <id>` | Show execution history |
-| `status <id>` | Show operational status — failures, skipped fires, next fire, recent runs |
+| `status <id>` | Show failures, skipped fires, next fire and recent runs |
+| `run <id>` | Open a chat that tests the reminder now |
 | `enable <id>` | Enable a reminder |
 | `disable <id>` | Disable a reminder |
-| `cancel <id>` | Cancel (soft delete — disables, keeps definition) |
+| `cancel <id>` | Delete a one-shot reminder, or disable a recurring one |
 | `delete <id>` | Permanently delete a reminder and its history |
 | `import <file>` | Import a reminder from a JSON file |
-| `validate <file>` | Validate a reminder file offline (no daemon needed) |
+| `validate <file>` | Validate a reminder file offline, no daemon needed |
 
 ## Interactive TUI
 
@@ -38,17 +39,37 @@ netclaw reminder ui
 
 The Reminder Builder walks you through six steps: title, schedule type, schedule value, instructions, delivery guidance, and review.
 
-![The netclaw reminder TUI builder walking through the creation flow](/screenshots/output/reminder.gif)
+![Recording of the Reminder Builder: typing a title, choosing a cron schedule, entering instructions, reviewing, and the Reminder created screen](/screenshots/output/reminder.gif)
 
-Navigate with arrow keys and Enter. Esc goes back a step (or quits on the first step). Ctrl+Q quits from anywhere. Ctrl+Enter adds newlines in multi-line fields.
+The recording runs about 19 seconds from step 1 to the "Reminder created" screen, which offers Create another or Quit.
+
+Navigate with the arrow keys and Enter. Esc goes back a step and does nothing on the first step. Ctrl+Q quits from anywhere. Ctrl+Enter adds newlines in multi-line fields.
+
+![Reminder Builder step 6 of 6, Review, showing the title daily-uptime-check, type cron, schedule 0 9 * * *, the instructions and delivery guidance, with Create reminder highlighted](/screenshots/output/reminder-builder-review.png)
+
+The review step repeats everything you entered, so this is the last chance to go back with `Esc`.
 
 ## `list`
 
 ```bash
-netclaw reminder list
+netclaw reminder list [--json]
+```
+
+Prints a table with one row per reminder: `id`, `status`, `failures`, `schedule`, `next_fire` and `title`. With none, it prints `No reminders.`
+
+```text
+id                  status    failures  schedule                                    next_fire             title
+---------------------------------------------------------------------------------------------------------------
+daily-uptime-check  enabled   0         runs daily at 09:00 UTC                     2026-10-30 09:00:00Z  daily-uptime-check
+rec-demo            disabled  0         runs every 30m                              -                     rec-demo
+weekly-report       enabled   0         runs every Monday at 09:00 America/Chicago  2026-11-02 15:00:00Z  Weekly report
 ```
 
-![netclaw reminder list showing two reminders — a recurring cron reminder and a one-shot reminder](/screenshots/output/reminder-list.png)
+![netclaw reminder list printing a table with two cron reminders, daily-uptime-check and weekly-report, each with its schedule in words and next fire time](/screenshots/output/reminder-list.png)
+
+The schedule is spelled out in words, and `next_fire` is always UTC, even when the schedule names another zone, as `weekly-report` does with America/Chicago. `status` is `enabled`, `disabled`, or `failed` for a recurring reminder that gave up. A one-shot deletes itself when it ends, so it leaves the list the moment it runs, fails or is cancelled. Use [`status`](#status) or [`history`](#history) to see how it ended. An unknown option exits 1 with a usage line.
+
+`--json` prints a JSON array of `id`, `title`, `enabled`, a readable `schedule`, `nextFire`, `expiresAt`, `audience`, `consecutiveFailures` and `terminalOutcome` for each reminder, which is what `list` printed before 0.28. With none, it prints `No active reminders.`
 
 ## `create`
 
@@ -58,10 +79,10 @@ netclaw reminder create <id> <scheduleType> <schedule> "<prompt>" [options]
 
 | Positional | Description |
 |-----------|-------------|
-| `id` | Stable identifier, kebab-case slug (e.g. `daily-standup`) |
+| `id` | Stable identifier. netclaw lowercases it, turns other characters into dashes and cuts it to 50 characters, so `Daily Standup` becomes `daily-standup` |
 | `scheduleType` | `once`, `interval`, or `cron` |
-| `schedule` | Duration or cron expression (see [Schedule types](#schedule-types)) |
-| `prompt` | Instructions for what netclaw should do when the reminder fires |
+| `schedule` | Duration, timestamp or cron expression (see [Schedule types](#schedule-types)) |
+| `prompt` | What the agent should do when the reminder fires |
 
 ### Options
 
@@ -69,45 +90,55 @@ netclaw reminder create <id> <scheduleType> <schedule> "<prompt>" [options]
 |------|-------------|---------|
 | `--name <title>` | Human-readable title | Same as `id` |
 | `--delivery <kind>` | `none` or `channel` | `none` |
-| `--transport <transport>` | Transport for channel delivery (e.g. `slack`) | — |
-| `--address <target>` | Target for channel delivery (`#channel`, `@user`, or ID) | — |
-| `--expires-in <duration>` | Auto-disable after duration (e.g. `24h`, `7d`) | — |
+| `--transport <transport>` | Channel transport: `slack`, `discord` or `mattermost` | - |
+| `--address <target>` | Where to post: a channel name, `@user` or an ID. [Formats per transport](/configuration/reminders/#reminder-targets) | - |
+| `--expires-in <duration>` | Auto-disable after this long, for recurring reminders (`24h`, `7d`) | - |
 
-If a reminder with the given ID already exists, it gets updated (upsert).
+IDs that start with `restart-resume-` belong to the system, and `create` refuses them with `The reminder ID prefix 'restart-resume-' is reserved for the system.` If a reminder with that ID already exists, `create` updates it. A reminder created here runs with the Personal audience, because the CLI is the operator. To schedule one for a lower audience, ask the agent from a chat in that audience. Under a Team or Public [deployment posture](/security/security-model/#deployment-postures), tool access follows the posture's audience, so a Personal reminder can be refused by `run_reminder`. Create it again from a chat in the narrower audience. See [audience scoping](/configuration/reminders/#audience-scoping).
 
-Channel delivery requires [Slack to be configured](/cli/init/) in netclaw. Without it, the reminder runs but has nowhere to post results.
+`--transport` only works for a channel you've configured. Without the channel, the command fails with `Unknown transport 'slack'. Available transports: [none].` Set the channel up in `netclaw config` first. The CLI can't set a `current_session` target. That one comes from the agent, inside the conversation it should reply in.
 
 ### Schedule types
 
 | Type | What it does | Examples |
 |------|-------------|----------|
-| `once` | Fires one time, then auto-disables | `30m`, `2h`, or an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp like `2026-06-01T18:00:00Z` |
-| `interval` | Repeats on a fixed duration | `15m`, `2h`, `1d` |
-| `cron` | Fires on a [cron schedule](https://crontab.guru/) (5-field, UTC) | `0 */6 * * *`, `0 9 * * MON-FRI` |
+| `once` | Fires one time, then deletes itself | `30m`, `2h`, or an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp like `2030-06-01T18:00:00Z` |
+| `interval` | Repeats on a fixed duration | `2m`, `2h`, `1d` |
+| `cron` | Fires on a [cron schedule](https://crontab.guru/): 5 fields, UTC unless you add a `CRON_TZ=` prefix | `0 */6 * * *`, `CRON_TZ=Europe/Brussels 0 9 * * MON-FRI` |
+
+Intervals under 60 seconds are rejected (`Minimum interval is 60 seconds.`). Anything longer fires on every interval. A `once` reminder still delivers up to seven days late if the daemon was down at its fire time, and a recurring one gets at most one catch-up fire after downtime. The [configuration page](/configuration/reminders/#schedule-types) has the details.
+
+A `CRON_TZ=` prefix takes an IANA zone ID without spaces, like `America/Chicago`. Windows names such as `Eastern Standard Time` and unknown zones are rejected:
+
+```text
+[FAIL] Error: Invalid CRON_TZ prefix. Unknown time zone 'Eastern'. Use an IANA id such as America/Chicago.
+```
 
 ### Examples
 
-#### Recurring cron reminder
+#### Recurring cron reminder in your time zone
 
 ```bash
-netclaw reminder create akka-nuget-daily cron "0 15 * * MON-FRI" \
-  "Check Akka.NET NuGet download counts. Compare to yesterday and flag anything unusual." \
-  --name "Akka NuGet Daily Downloads Report"
+netclaw reminder create weekly-report cron "CRON_TZ=America/Chicago 0 9 * * MON" \
+  "Summarize last week's merged pull requests and open incidents." \
+  --name "Weekly report"
 ```
 
 #### One-shot with Slack delivery
 
 ```bash
-netclaw reminder create stir-trek-talk once "2026-05-01T18:45:00Z" \
+netclaw reminder create stir-trek-talk once 2h \
   "Remind me to head to the Stir Trek talk room" \
   --name "Head to Stir Trek talk room" \
   --delivery channel --transport slack --address "#general"
 ```
 
-#### Interval health check
+A one-shot reminder deletes itself when it ends, whether it ran, failed, was denied, was cancelled or expired. `create` says so in its reply. Re-creating a reminder with the same ID starts a fresh one.
+
+#### Cron health check every six hours
 
 ```bash
-netclaw reminder create infra-check interval "6h" \
+netclaw reminder create infra-check cron "0 */6 * * *" \
   "Run netclaw doctor and summarize any degraded services."
 ```
 
@@ -117,7 +148,13 @@ netclaw reminder create infra-check interval "6h" \
 netclaw reminder show <id>
 ```
 
-Shows the full JSON definition for a reminder — the same format `import` expects.
+Prints a summary of the reminder: schedule in words, next fire, instructions, delivery fields, `audience`, `consecutiveFailures` and `terminalOutcome`. This is a view for reading, not the stored definition, so it's not what `import` expects. The stored file is `~/.netclaw/schedules/reminders/<id>.json`.
+
+For a one-shot that has ended, `show` exits 1, because its definition is gone:
+
+```text
+[FAIL] Reminder 'once-demo' ended (cancelled) at 2026-10-29 15:19:02Z and its definition was deleted. Its history stays readable until 2026-11-10 15:19:02Z: netclaw reminder history once-demo
+```
 
 ## `history`
 
@@ -129,7 +166,16 @@ netclaw reminder history <id> [--last N]
 |------|-------------|---------|
 | `--last <N>` | Number of history records to return | `20` |
 
-Output is a table with columns: `fired_at`, `status` (`ok`/`failed`), `duration_ms`, and `session_id`. Use the session ID to dig into what the agent did with [`netclaw sessions`](/cli/sessions/).
+Output is a table with the columns `fired_at`, `status` (`ok`, `denied` or `failed`), `duration_ms` and `session_id`. Use the session ID to see what the agent did with [`netclaw sessions`](/cli/sessions/).
+
+```text
+fired_at                   status    duration_ms   session_id
+-------------------------------------------------------------------------------
+2026-10-14 04:18:00Z       denied    25847         reminder/disk-note/1791951480000
+2026-10-14 04:24:00Z       ok        25754         reminder/disk-note/1791951840000
+```
+
+A run is `denied` when a tool call was [denied because nobody could approve it](/guides/unattended-runs/#what-an-unattended-run-can-do), or because the audience's policy forbids the tool or path. For a recurring reminder, a denial isn't a failure. netclaw doesn't retry the run or count it toward auto-disable, and it raises a `reminder.tool_denied` alert once per distinct denial until the next `ok` run. Save the grant the call needs, and the next run goes through. A one-shot has no next run, so a denial ends it as `failed`. Its end record keeps the denial text and the prompt, and you set the reminder again once the grant exists. A run is `ok` when the session finished and nothing was denied, even if the agent couldn't do its job otherwise.
 
 ## `status`
 
@@ -137,33 +183,61 @@ Output is a table with columns: `fired_at`, `status` (`ok`/`failed`), `duration_
 netclaw reminder status <id>
 ```
 
-The go-to command when a reminder is misbehaving. Where `history` lists raw runs, `status` answers "is this thing healthy right now?" in one screen — whether it's enabled, whether a run is in flight, when it fires next, how close it is to auto-disabling, and its last five outcomes.
+The first command to run when a reminder misbehaves. Where `history` lists raw runs, `status` shows whether it's enabled, whether a run is in flight, when it fires next, how close it is to auto-disabling, and its last five outcomes.
 
-```
-$ netclaw reminder status gotowebinar-triage
-Reminder:            gotowebinar-triage
+```text
+$ netclaw reminder status disk-note
+Reminder:            disk-note
 Enabled:             True
 Executing now:       False
-Next fire:           2026-06-26 18:00:00Z
-Consecutive fails:   2
-Skipped (duplicate): 14
+Next fire:           Wednesday, October 7 at 3:27 PM Coordinated Universal Time (2026-10-07 15:27:00Z)
+Consecutive fails:   0
+Skipped occurrences: 0
+Terminal outcome:    none
 Recent history (newest first):
-  2026-06-26 17:00:00Z  failed — Reminder execution stalled: no session output for 00:20:00.
-  2026-06-26 15:00:00Z  ok
+  2026-10-07 15:24:00Z  ok
 ```
 
 | Field | Meaning |
 |-------|---------|
-| `Enabled` | Whether the reminder is active. Flips to `False` on its own after 5 consecutive failures. |
+| `Enabled` | Whether the reminder is active. Flips to `False` on its own after 5 consecutive failures, never after `denied` runs. |
 | `Executing now` | A run is in flight right now. |
 | `Next fire` | Next scheduled time, or `not scheduled` when disabled. |
-| `Consecutive fails` | Current failure streak. Auto-disables at 5; a single success resets it to 0. |
-| `Skipped (duplicate)` | Fires skipped because the previous run was still executing. Counted since daemon start — a climbing number means runs regularly outlast their interval. |
-| `Recent history` | The five most recent runs, newest first, each with its outcome and error. |
+| `Consecutive fails` | Current failure streak. Auto-disables at 5, and one success resets it to 0. |
+| `Skipped occurrences` | Fires dropped because the previous run was still going, or because the scheduler delivered one too late to finish. Counted since daemon start. |
+| `Terminal outcome` | `none` while the reminder can still run. `Failed` after a recurring reminder gave up. |
+| `Ended` | For a one-shot that has ended: the outcome (`completed`, `failed`, `cancelled` or `expired`), when, and until when its history stays. Replaces `Terminal outcome`. |
+| `Last error`, `Prompt` | A `failed` one-shot also prints these, so you can set it again. `Prompt` appears only here, not in `show`. |
+| `Occurrence status`, `Occurrence attempts`, `Next retry`, `Last failure` | Shown for a one-shot that has a pending occurrence, including retries after a failure. |
+| `Recent history` | The five most recent runs, newest first, with the error for `failed` and `denied` ones. |
+
+A one-shot deletes itself when it ends, but `status` and `history` keep answering for 12 days. `status` then shows `Enabled: False`, `Next fire: not scheduled` and the `Ended:` line instead of `Terminal outcome:`:
+
+```text
+Ended:               cancelled at 2026-10-29 15:19:02Z (history stays until 2026-11-10 15:19:02Z)
+```
 
-Backed by `GET /api/reminders/{id}/status`. An unknown ID exits non-zero with `Reminder '<id>' not found`.
+An unknown ID exits non-zero with `Reminder '<id>' not found`.
 
-A high `Skipped (duplicate)` count with a short interval is the classic misconfiguration: the reminder is scheduled more often than a run takes to finish, so most fires are dropped. Lengthen the interval or speed up the work.
+A climbing `Skipped occurrences` count means the reminder is scheduled more often than a run takes to finish. See [troubleshooting](/configuration/reminders/#troubleshooting).
+
+## `run`
+
+```bash
+netclaw reminder run <id>
+```
+
+Opens a normal chat with `/run-reminder <id>` as the first message. The agent loads the `run-reminder` skill, warns that the test does real work and asks you to confirm. Answer yes, and it carries out the reminder's exact prompt in that chat and asks you to approve each gated call, so you can save "Always" grants that the scheduled run will use. Nothing is recorded in the reminder's history, and the schedule doesn't change.
+
+The steps are real. A reminder that deletes files deletes them, and one that posts to a channel posts there.
+
+A test only runs in a chat with the reminder's own audience. A CLI chat is Personal, narrowed to your [deployment posture](/security/security-model/#deployment-postures), so on a Personal host `reminder run` tests Personal reminders and on a Team host it tests Team ones. For a reminder at another audience, run `/run-reminder <id>` in a channel with that audience instead. If the reminder is a one-shot that already ended, the agent says so and tells you to set it again. The [unattended runs guide](/guides/unattended-runs/#pre-approve-by-testing-the-reminder) shows the whole flow with real output.
+
+![Netclaw chat TUI during a reminder test run, with an approval prompt for touch /tmp/disk-note.txt and five options with Always here highlighted](/screenshots/output/reminder-run-approval.png)
+
+The prompt has five options because the command doesn't run inside a Git repository, so **This repository** isn't offered.
+
+Any other form (`reminder run` with no ID, or extra arguments) prints `Usage: netclaw reminder run <id>` and exits 1. `run` doesn't print a result block or take `--json`. The result is the chat itself.
 
 ## `enable` / `disable`
 
@@ -172,7 +246,7 @@ netclaw reminder enable <id>
 netclaw reminder disable <id>
 ```
 
-Disabled reminders keep their definition and history — they just stop firing.
+Disabled reminders keep their definition and history and stop firing. Enabling one resets its schedule, so an interval reminder fires one interval after you enable it. An ended one-shot can't be enabled. `enable`, `disable` and `show` fail with the same `ended ... its definition was deleted` message, and you create the reminder again instead.
 
 ## `cancel` vs `delete`
 
@@ -181,7 +255,19 @@ netclaw reminder cancel <id>
 netclaw reminder delete <id>
 ```
 
-`cancel` disables a reminder but leaves the definition and history intact, so you can re-enable it later. `delete` removes everything permanently.
+`cancel` on a recurring reminder disables it and keeps the definition and history, so you can re-enable it later:
+
+```text
+Reminder 'rec-demo' cancelled (disabled).
+```
+
+On a one-shot, `cancel` deletes the reminder and writes an end record with the outcome `cancelled`:
+
+```text
+Reminder 'once-demo' cancelled and deleted.
+```
+
+Cancelling a one-shot that already ended prints `Reminder '<id>' already ended (<outcome> at <time>). Nothing changed.` and exits 0. `delete` removes everything, history included.
 
 ## `import`
 
@@ -189,15 +275,15 @@ netclaw reminder delete <id>
 netclaw reminder import <file> [--replace|--upsert]
 ```
 
-Imports a reminder from a JSON file. The file format matches `show` output — grab a reminder's JSON, edit it, and import it back.
+Imports a reminder from a definition file. The format is the stored file's, documented in [the definition schema](/configuration/reminders/#reminder-definition-schema), so a file copied from `~/.netclaw/schedules/reminders/` on another install imports as it is.
 
 | Mode | Description |
 |------|-------------|
-| _(default)_ | Create only — fails if the reminder already exists |
+| _(default)_ | Create only. Fails if the reminder already exists |
 | `--upsert` | Create or update |
 | `--replace` | Replace the existing reminder entirely |
 
-The file is validated before import. Run `validate` first to check for errors without hitting the daemon.
+A successful import prints `Imported reminder '<id>'.` IDs that start with `restart-resume-` are reserved, so an export that contains one fails with `The reminder ID prefix 'restart-resume-' is reserved for the system.` Remove that entry from the file first. The default mode refuses an existing ID with `[FAIL] Reminder '<id>' already exists.` Use `--upsert` to update it.
 
 ## `validate`
 
@@ -205,32 +291,43 @@ The file is validated before import. Run `validate` first to check for errors wi
 netclaw reminder validate <file>
 ```
 
-Checks a reminder JSON file for schema errors offline. Schedule-type-specific rules:
+Checks a definition file offline, without a daemon:
+
+```text
+$ netclaw reminder validate daily-standup.json
+Reminder definition is valid: daily-standup
+```
+
+It requires `id`, `title`, `instructions`, `delivery`, `audience` and `boundary`, plus the schedule field for the type:
+
+- `OneShot` needs `fireAtMs`
+- `Interval` needs `intervalTicks`
+- `Cron` needs a valid `cronExpression` ([5 fields](https://en.wikipedia.org/wiki/Cron#Cron_expression), optionally with `CRON_TZ=`)
 
-- `once` reminders need a `fireAtMs` timestamp
-- `interval` reminders need `intervalTicks`
-- `cron` reminders need a valid `cronExpression` (standard [5-field format](https://en.wikipedia.org/wiki/Cron#Cron_expression))
+A file without `boundary` fails with `JSON deserialization ... was missing required properties including: 'boundary'`, and an unknown time zone fails with `Invalid CRON_TZ prefix. Unknown time zone 'Nope/Zone'. Use an IANA id such as America/Chicago.` `validate` doesn't check that `boundary` suits the `audience`. The daemon does that when it saves.
 
 ## Exit codes
 
 | Code | Meaning |
 |------|---------|
 | `0` | Success |
-| `1` | Reminder not found, validation error, daemon unreachable, or other failure |
+| `1` | Reminder not found, validation error, daemon unreachable, or another failure |
 
 ## What's next
 
-Run [`netclaw reminder list`](#list) to confirm your reminder appears with the right schedule and next fire time. After it fires, [`netclaw reminder history <id>`](#history) shows whether it succeeded, and [`netclaw reminder status <id>`](#status) tells you at a glance whether it's healthy. Grab the session ID from the history output and pass it to [`netclaw sessions`](/cli/sessions/) to see the full run.
+Run [`netclaw reminder list`](#list) to confirm your reminder appears with the right schedule. After it fires, [`netclaw reminder status <id>`](#status) tells you whether it's healthy, and [`history`](#history) gives you the session ID to pass to [`netclaw sessions`](/cli/sessions/). If the reminder needs shell or file access, [test it with `run`](#run) before the schedule does.
 
-## Related commands
+## Related pages
 
-- [`netclaw status`](/cli/status/) — confirms daemon is running before using reminders
-- [`netclaw sessions`](/cli/sessions/) — inspect what happened during a reminder session
-- [`netclaw stats`](/cli/stats/) — usage statistics including reminder execution counts
-- [`netclaw doctor`](/cli/doctor/) — health checks for the daemon and its subsystems
+- [Run reminders, webhooks and scripts unattended](/guides/unattended-runs/) - why a scheduled run is denied and how to approve it ahead of time
+- [Reminders configuration](/configuration/reminders/) - definition schema, schedules, delivery targets and audience scoping
+- [`netclaw sessions`](/cli/sessions/) - inspect what happened during a reminder session
+- [`netclaw approvals`](/cli/approvals/) - list, add and revoke saved grants
+- [`netclaw status`](/cli/status/) - confirm the daemon is running
 
 ## Resources
 
-- [Crontab.guru](https://crontab.guru/) — visual editor for cron schedule expressions
-- [Cron expression syntax (Wikipedia)](https://en.wikipedia.org/wiki/Cron#Cron_expression) — reference for the standard 5-field cron format
-- [ISO 8601 (Wikipedia)](https://en.wikipedia.org/wiki/ISO_8601) — timestamp format for one-shot reminder schedules
+- [Crontab.guru](https://crontab.guru/) - visual editor for cron schedule expressions
+- [Cron expression syntax (Wikipedia)](https://en.wikipedia.org/wiki/Cron#Cron_expression) - reference for the 5-field cron format
+- [IANA time zone database (Wikipedia)](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) - zone IDs for `CRON_TZ=`
+- [ISO 8601 (Wikipedia)](https://en.wikipedia.org/wiki/ISO_8601) - timestamp format for one-shot schedules
diff --git a/src/content/docs/cli/secrets.md b/src/content/docs/cli/secrets.md
index fda8db0..18dd761 100644
--- a/src/content/docs/cli/secrets.md
+++ b/src/content/docs/cli/secrets.md
@@ -1,78 +1,82 @@
 ---
 title: "netclaw secrets"
-description: "Manage encrypted secrets."
+description: "Store API keys and tokens in netclaw's encrypted vault with netclaw secrets set."
 ---
 
-Store API keys, tokens, and credentials in an encrypted local vault. Values are encrypted at rest using [ASP.NET Data Protection](https://learn.microsoft.com/en-us/aspnet/core/security/data-protection/introduction) — no plaintext ever touches disk.
-
-If you haven't run [`netclaw init`](/cli/init/) yet, start there — the wizard stores your initial credentials automatically. Use `secrets set` afterward to rotate keys, add new providers, or script credential injection without re-running the wizard.
+`netclaw secrets set` writes an API key, token or other credential into an encrypted local vault. Values are encrypted with [ASP.NET Data Protection](https://learn.microsoft.com/en-us/aspnet/core/security/data-protection/introduction) before they reach disk. The one exception is `Providers.<name>.OAuthTokenExpiry`, which is a date and not a secret, so it's stored as plain text. Use it to rotate keys, add a provider or script credential injection after [`netclaw init`](/cli/init/), which stores your first credentials for you.
 
 ## Usage
 
 ```bash
 netclaw secrets set <key> <value>
+netclaw secrets add <key> <value>     # alias for set
 ```
 
-`set` is the only subcommand — there's no `get`, `list`, or `delete`. Secrets are write-only by design. To remove a key, edit `~/.netclaw/config/secrets.json` directly.
-
-## Arguments
+`set` is the only operation. There's no `get`, `list` or `delete`, so secrets are write-only by design. To remove a key, edit `~/.netclaw/config/secrets.json` directly. Any other subcommand, or none, prints the usage text and exits 0. `set` with fewer than two arguments prints examples and exits 1.
 
-| Argument | Description | Required |
-|----------|-------------|----------|
-| `<key>` | Dotted key path (e.g., `Slack.BotToken`) | Yes |
-| `<value>` | The secret value to encrypt and store | Yes |
+| Argument | Description |
+|----------|-------------|
+| `<key>` | A dotted path matching the `netclaw.json` hierarchy, such as `Slack.BotToken`. Colons work too: `Discord:BotToken` |
+| `<value>` | The secret to encrypt and store |
 
-## Key Paths
+The value is a command-line argument, so it lands in your shell history and shows in the process list while the command runs. Prefix the command with a space if your shell skips history for those lines, or clear the history entry afterwards.
 
-Keys use dotted paths matching the `netclaw.json` hierarchy:
+## Key paths
 
-| Key Path | What It Stores |
-|----------|---------------|
-| `Slack.BotToken` | Slack Bot User OAuth Token (`xoxb-...`) |
-| `Slack.AppToken` | Slack App-Level Token (`xapp-...`) |
+| Key path | What it stores |
+|----------|----------------|
+| `Slack.BotToken` | Slack bot user OAuth token (`xoxb-...`) |
+| `Slack.AppToken` | Slack app-level token (`xapp-...`) |
+| `Discord.BotToken` | Discord bot token |
 | `Providers.openrouter.ApiKey` | OpenRouter API key |
-| `Providers.ollama.ApiKey` | Ollama API key (if auth enabled) |
+| `Providers.ollama.ApiKey` | Ollama API key, if auth is on |
 | `Search.BraveApiKey` | Brave Search API key |
+| `Providers.<name>.OAuthTokenExpiry` | OAuth access-token expiry, as an ISO 8601 date. Plain text. OAuth sign-in and token refresh write it, so you rarely set it by hand |
 
-This isn't exhaustive — any dotted path that corresponds to a field in `netclaw.json` works. See [Configuration](/configuration/managed-providers/) for the full schema.
+Any dotted path that matches a field in `netclaw.json` works. See [Managed providers](/configuration/managed-providers/) for provider keys.
 
 ## Examples
 
-### Store a Slack Bot Token
+Store a Slack bot token:
 
 ```bash
 netclaw secrets set Slack.BotToken xoxb-1234567890-abcdef
 ```
 
-```
+```text
 Set Slack.BotToken (encrypted).
 ```
 
-### Store a Provider API Key
+Store a provider key and a colon-style path:
 
 ```bash
 netclaw secrets set Providers.openrouter.ApiKey sk-or-v1-your-key-here
+netclaw secrets set Discord:BotToken your-token-here
 ```
 
-```
+```text
 Set Providers.openrouter.ApiKey (encrypted).
+Set Discord.BotToken (encrypted).
 ```
 
-### Store Multiple Secrets
+`OAuthTokenExpiry` is the exception to the encrypted output. `set` says so and writes the bare date, and it rejects anything that isn't an ISO 8601 date before writing:
 
-```bash
-netclaw secrets set Slack.BotToken xoxb-...
-netclaw secrets set Slack.AppToken xapp-...
-netclaw secrets set Providers.openrouter.ApiKey sk-or-v1-...
+```text
+Set Providers.lab-llama.OAuthTokenExpiry (not encrypted: the token expiry is not a secret).
+Error: Providers.lab-llama.OAuthTokenExpiry must be an ISO 8601 date, for example 2026-06-01T01:00:00+00:00.
 ```
 
-## How Encryption Works
+Secrets are read when the daemon starts, and the daemon only restarts itself when `netclaw.json` changes. After a `secrets set`, restart it yourself:
+
+| Install | Restart |
+|---------|---------|
+| Docker | `docker restart <container>` |
+| systemd user unit | `systemctl --user restart netclaw` |
+| Native | `netclaw daemon stop`, then `netclaw daemon start` |
 
-1. The value is encrypted via ASP.NET Data Protection
-2. The ciphertext is written to `secrets.json` with an `ENC:` prefix
-3. File permissions are set to `600` on Unix
+## What gets written
 
-The raw `secrets.json` looks like this:
+Every value except the token expiry is encrypted, prefixed with `ENC:`, and written to `secrets.json` with mode `600` on Unix:
 
 ```json
 {
@@ -82,44 +86,33 @@ The raw `secrets.json` looks like this:
   "Providers": {
     "openrouter": {
       "ApiKey": "ENC:CfDJ8K9y...long-base64-string..."
+    },
+    "my-openai": {
+      "OAuthTokenExpiry": "2026-06-01T01:00:00+00:00"
     }
   }
 }
 ```
 
-Encryption keys live in `~/.netclaw/keys/`, separate from the secrets file. Both are required to decrypt — one is useless without the other.
-
-## Storage Locations
-
-| Path | Contents |
-|------|----------|
-| `~/.netclaw/config/secrets.json` | Encrypted credential values |
-| `~/.netclaw/keys/` | Data Protection key material |
-
-Both paths are created automatically on first use of `netclaw secrets set` or during `netclaw init`.
-
-## Configuration Layering
-
-Secrets participate in the standard config priority chain (highest priority wins):
-
-```
-NETCLAW_* env vars  →  secrets.json  →  netclaw.json
-       (highest)                          (lowest)
-```
+Encryption keys live in `~/.netclaw/keys/`, separate from the secrets file. Both are created on first use and both are required to decrypt, so back them up together. `netclaw mcp add` also writes MCP server environment variables, headers and OAuth client secrets into `secrets.json` the same way.
 
-Environment variables override secrets, which override `netclaw.json`. Use env vars in CI or containers while keeping `secrets.json` for local development.
+## Configuration layering
 
-## Output Redaction
+Highest priority wins:
 
-Even if a secret leaks into a tool's output at runtime, netclaw's output redactor catches it before it reaches the LLM. It recognizes common secret patterns: API key prefixes (`sk-*`, `xox*-*`, `ghp_*`, `AKIA*`), `Authorization` headers, connection strings with embedded passwords, JWT tokens, and PEM private key blocks.
+| Priority | Source |
+|----------|--------|
+| 1 | `NETCLAW_*` environment variables |
+| 2 | `secrets.json` |
+| 3 | `netclaw.json` |
 
-Secrets are encrypted at rest, decrypted only when needed, and redacted from any tool output before it reaches the LLM.
+An environment variable beats a stored secret with the same path, which is the usual reason a new secret doesn't seem to take effect. Use environment variables in CI and containers, and `secrets.json` for persistent local credentials.
 
 ## Troubleshooting
 
 ### Permission denied writing secrets.json
 
-The file requires `chmod 600`. If permissions drifted:
+**Symptom:** `secrets set` fails to write. **Cause:** permissions on the file or directory drifted. **Fix:**
 
 ```bash
 chmod 600 ~/.netclaw/config/secrets.json
@@ -127,20 +120,21 @@ chmod 600 ~/.netclaw/config/secrets.json
 
 ### Lost encryption keys
 
-If `~/.netclaw/keys/` is deleted, existing encrypted values in `secrets.json` cannot be recovered. You'll need to re-run `netclaw secrets set` for each credential. Always back up `~/.netclaw/keys/` alongside `secrets.json`.
+**Symptom:** the daemon can't decrypt values in `secrets.json`. **Cause:** `~/.netclaw/keys/` was deleted or replaced. **Fix:** the old values are unrecoverable. Re-run `netclaw secrets set` for each credential, and back up `~/.netclaw/keys/` next to `secrets.json` from now on.
 
-### Secrets not taking effect
+### A secret isn't taking effect
 
-An environment variable with the same path will override `secrets.json`. Run [`netclaw doctor`](/cli/doctor/) to diagnose config issues.
+**Symptom:** the daemon still uses an old key. **Cause:** an environment variable with the same path overrides `secrets.json`, or the daemon hasn't restarted since you set the value. **Fix:** unset the variable or restart the daemon, then run [`netclaw doctor`](/cli/doctor/).
 
-## Related Commands
+## Related pages
 
-- [`netclaw init`](/cli/init/) — Stores initial credentials during first-run setup
-- [`netclaw doctor`](/cli/doctor/) — Diagnoses config and connectivity issues
-- [`netclaw provider`](/cli/provider/) — Manages providers that consume API key secrets
+- [Secrets management](/security/secrets/) - how encryption, path denial and output redaction fit together
+- [`netclaw init`](/cli/init/) - stores initial credentials during first-run setup
+- [`netclaw doctor`](/cli/doctor/) - checks secrets file permissions and encryption
+- [`netclaw provider`](/cli/provider/) - manages the providers that consume API key secrets
 
-## Further Reading
+## Resources
 
-- [ASP.NET Data Protection overview](https://learn.microsoft.com/en-us/aspnet/core/security/data-protection/introduction) — The encryption framework netclaw builds on
-- [ASP.NET Data Protection key management](https://learn.microsoft.com/en-us/aspnet/core/security/data-protection/implementation/key-management) — How encryption keys are stored and rotated
-- [OWASP Secrets Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html) — General best practices for credential storage
+- [ASP.NET Data Protection overview](https://learn.microsoft.com/en-us/aspnet/core/security/data-protection/introduction) - the encryption framework netclaw builds on
+- [ASP.NET Data Protection key management](https://learn.microsoft.com/en-us/aspnet/core/security/data-protection/implementation/key-management) - how keys are stored and rotated
+- [OWASP Secrets Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html) - general credential storage practices
diff --git a/src/content/docs/cli/sessions.md b/src/content/docs/cli/sessions.md
index 1ac5644..bfe8421 100644
--- a/src/content/docs/cli/sessions.md
+++ b/src/content/docs/cli/sessions.md
@@ -1,13 +1,11 @@
 ---
 title: "netclaw sessions"
-description: "Browse and resume chat sessions."
+description: "Browse and resume chat sessions, or list them as plain text or JSON for scripts."
 ---
 
-Pick up where you left off. `netclaw sessions` opens a terminal UI (TUI) listing your recent sessions — scroll, hit Enter, and you're back in the conversation. For scripts, `--once` and `--json` dump session data to stdout instead.
+Pick up where you left off. `netclaw sessions` opens a terminal UI of your recent sessions. Select one and press `Enter` to land back in the conversation. `--once` and `--json` print the same list to stdout for scripts.
 
-Requires a running daemon. If it's not up, start it with `netclaw daemon start` (or run [`netclaw init`](/cli/init/) which starts it for you).
-
-This command only lists sessions — there's no delete or cleanup here. Session lifecycle is managed by the daemon's retention policy.
+It needs a running daemon. If it's down, start it with `netclaw daemon start` (`docker restart <container>` in Docker), or run [`netclaw init`](/cli/init/), which starts it for you.
 
 ## Usage
 
@@ -19,146 +17,179 @@ netclaw sessions [options]
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `--once` | List sessions to stdout and exit (no TUI) | TUI mode |
-| `--json` | Output as JSON array (implies `--once`) | Plain text |
+| `--once` | Print the list and exit, with no TUI | TUI |
+| `--json` | Print a JSON array. Implies `--once`. | Plain text |
 
-## TUI mode
+## Browse in the TUI
 
 ```bash
 netclaw sessions
 ```
 
-Full-screen session browser. Each entry shows:
+Each row shows the channel, the title, the turn count and the time since the last activity:
 
 ```
-[cli] Deploy troubleshooting (8 turns, 23m ago)
-[slack] Weekly standup recap (3 turns, 2h ago)
-[cli] Config migration (12 turns, 1d ago)
+1. [headless] Untitled (2 turns, 1m ago)
+2. [headless] Untitled (1 turns, 3m ago)
+3. [tui] First Conversation Setting Up Netclaw Assistant (1 turns, 4m ago)
 ```
 
-The channel tag (`cli`, `slack`, etc.) shows where the session originated. The daemon returns up to 50 of your most recent sessions.
-
-### Keyboard shortcuts
+The channel tag says where the session started: `tui`, `headless`, `slack`, `discord` and so on. Sessions without a title yet show as `Untitled`. The daemon returns 50 sessions at a time, newest first.
 
 | Key | Action |
 |-----|--------|
-| `↑` / `K` | Move selection up |
-| `↓` / `J` | Move selection down |
-| `Enter` | Resume selected session (opens chat) |
-| `N` | Start a new [`netclaw chat`](/cli/chat/) session |
+| `↑` / `K` | Move up |
+| `↓` / `J` | Move down |
+| `Enter` | Resume the selected session in [`netclaw chat`](/cli/chat/) |
+| `N` | Start a new chat |
+| `PgDn` | Next page, older sessions |
+| `PgUp` | Previous page, newer sessions |
 | `Ctrl+Q` | Quit |
-| `Escape` | Quit |
 
-Enter drops you straight into [`netclaw chat`](/cli/chat/) with that session's full history loaded. When no sessions exist, you'll see "No sessions found. Press Enter to start a new chat."
+`Esc` does nothing here. The footer shows the range you're on, such as `Showing sessions 1-3`, plus the `[PgUp]` and `[PgDn]` hints when another page exists. With no sessions, the screen says "No sessions found. Press Enter to start a new chat."
+
+![Netclaw sessions browser listing three [tui] sessions with auto-generated titles and turn counts](/screenshots/output/sessions-tui.png)
 
-## Single-shot mode
+Each row shows where the session started, its generated title, its turn count and how long ago it was active, and the footer carries the range and the keys.
 
-### Plain text output
+Resuming loads the session's history into the chat as grayed-out context. Quitting the chat later doesn't end the session. It stays alive in the daemon, and you can pick it up again from this list.
+
+## Plain text and JSON output
+
+### Plain text
 
 ```bash
 netclaw sessions --once
 ```
 
-Lists all sessions to stdout, one per line:
-
 ```
-a1b2c3d4  Deploy troubleshooting  [active]  turns=8  last=2026-05-03 14:22
-e5f6g7h8  Weekly standup recap    [inactive]  turns=3  last=2026-05-03 11:45
+signalr/467ea8513aa44ea2bc6c8b11a7d28565  Hello from the stub model.  [active]  turns=1  last=2026-10-14 03:33
+newsess  (untitled)  [active]  turns=1  last=2026-10-14 03:32
+signalr/ef858dd055b7421fac18f4671d93facc  (untitled)  [active]  turns=1  last=2026-10-14 03:32
 ```
 
-**Active** means the session is held in memory and responds instantly. **Inactive** means it's persisted to disk — resuming one replays its history, which takes a moment.
+The first column is the session ID you pass to [`netclaw chat --resume`](/cli/chat/#resume-a-session). IDs that you named yourself are short. Daemon-assigned ones look like `signalr/<guid>`. Untitled sessions show `(untitled)`.
 
-The session ID in the first column is what you pass to [`netclaw chat --resume`](/cli/chat/#session-resume):
+**Active** means the session is held in memory and answers at once. **Inactive** means it was saved to disk after sitting idle, and resuming it replays the history first.
 
-```bash
-netclaw sessions --once | head -1 | awk '{print $1}' | xargs netclaw chat --resume
-```
-
-### JSON output
+### JSON
 
 ```bash
 netclaw sessions --json
 ```
 
-Outputs a JSON array of session objects:
-
 ```json
 [
   {
-    "persistenceId": "session-a1b2c3d4",
-    "channel": "cli",
-    "title": "Deploy troubleshooting",
-    "status": "active",
-    "turnCount": 8,
-    "createdAt": 1746268800000,
-    "lastActivity": 1746282120000,
-    "logPath": "/home/user/.netclaw/logs/sessions/a1b2c3d4"
+    "PersistenceId": "session-newsess",
+    "Channel": "headless",
+    "Title": null,
+    "Description": null,
+    "Status": "active",
+    "TurnCount": 1,
+    "CreatedAt": 1791948733854,
+    "LastActivity": 1791948733876,
+    "LogPath": "/home/netclaw/.netclaw/sessions/newsess-1efa2451f878e7b3/logs/session.log",
+    "LastInputTokens": 10,
+    "SessionId": "newsess"
   }
 ]
 ```
 
-#### JSON fields
+The keys are PascalCase. [`netclaw chat -p --json`](/cli/chat/#json-output) and most other commands use camelCase, so check the case before you write a filter.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `persistenceId` | string | Full internal persistence ID (prefixed with `session-`) |
-| `channel` | string | Origin channel (`cli`, `slack`, `discord`, etc.) |
-| `title` | string? | Auto-generated or null for untitled sessions |
-| `description` | string? | Session description, if set |
-| `status` | string | `active` (in memory) or `inactive` (persisted to disk) |
-| `turnCount` | int | Number of completed conversation turns |
-| `createdAt` | long | Creation time (Unix milliseconds) |
-| `lastActivity` | long | Last activity time (Unix milliseconds) |
-| `logPath` | string? | Path to per-session log directory |
-| `lastInputTokens` | long? | Input tokens from the last recorded turn |
-
-Note that `sessionId` is not included in the JSON — it's computed at runtime. To derive the short ID from `persistenceId`, strip the `session-` prefix:
+| `SessionId` | string | The ID to pass to `netclaw chat --resume` |
+| `PersistenceId` | string | The internal ID, which is `session-` plus the session ID |
+| `Channel` | string | Where the session started: `tui`, `headless`, `reminder`, `slack`, `discord`, `mattermost` |
+| `Title` | string or null | Generated after the first turns, null until then |
+| `Description` | string or null | Set only if something wrote one |
+| `Status` | string | `active` (in memory) or `inactive` (saved to disk) |
+| `TurnCount` | int | Completed turns |
+| `CreatedAt` | long | Creation time in Unix milliseconds |
+| `LastActivity` | long | Last activity in Unix milliseconds |
+| `LogPath` | string or null | The session's log file |
+| `LastInputTokens` | long or null | Input tokens in the last recorded turn |
+
+## Examples
+
+These need [jq](https://jqlang.github.io/jq/download/).
+
+Get the ID of the most recent session:
 
 ```bash
-# Requires jq
-netclaw sessions --json | jq -r '.[0].persistenceId | ltrimstr("session-")'
+netclaw sessions --json | jq -r '.[0].SessionId'
 ```
 
-Active sessions have their [actor](https://getakka.net/articles/concepts/actors.html) materialized in memory — they respond without any startup cost. Inactive sessions are persisted to disk and fully recoverable; resuming one replays its history, which takes a moment depending on the number of turns.
+Resume it without opening the TUI picker:
 
-## Exit codes
+```bash
+netclaw chat --resume "$(netclaw sessions --json | jq -r '.[0].SessionId')"
+```
 
-| Code | Meaning |
-|------|---------|
-| `0` | Sessions listed successfully |
-| `1` | Daemon unavailable or request failed |
+List sessions with more than one turn:
 
-In TUI mode, a failed daemon connection shows "Failed to connect to daemon. Is it running?" In `--once` mode, the error looks different:
+```bash
+netclaw sessions --json | jq -r '.[] | select(.TurnCount > 1) | .SessionId'
+```
 
+Sort by last activity, newest first:
+
+```bash
+netclaw sessions --json | jq -r 'sort_by(-.LastActivity) | .[0].SessionId'
 ```
-[FAIL] sessions: unable to reach daemon at <endpoint>: <message>
-run 'netclaw daemon start' and retry.
+
+Print a table with readable timestamps:
+
+```bash
+netclaw sessions --json | jq -r '.[] | [.SessionId, .TurnCount, (.LastActivity/1000 | todate)] | @tsv'
 ```
 
-## Examples
+```
+signalr/4d503455b7d64db483680132c831e3e1	1	2026-10-14T03:41:56Z
+signalr/22f90bcd201845c7861cb5d212dcbc40	1	2026-10-14T03:38:42Z
+```
 
-### Find sessions with many turns
+Count sessions by channel:
 
 ```bash
-# Requires jq
-netclaw sessions --json | jq '[.[] | select(.turnCount > 10)] | sort_by(-.lastActivity)'
+netclaw sessions --json | jq -r '.[].Channel' | sort | uniq -c
 ```
 
-### Resume the most recently active session
+## Deleting sessions
+
+`netclaw sessions` is read-only. It can't delete or archive a session, and netclaw has no command that does. The session list lives in `~/.netclaw/netclaw.db`, and each session's files live in its own directory.
+
+## Where sessions are stored
+
+Since 0.27.0 a new session gets its own directory under `~/.netclaw/sessions/`, named `<session-id>-<hash>` with slashes in the ID turned into underscores. The log is at `logs/session.log` inside it, and `LogPath` in the JSON points there. Sessions created before 0.27.0 keep their old paths. See [Data directory layout](/reference/data-directory/).
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | The list printed (or the TUI closed) |
+| `1` | The daemon was unreachable or the request failed |
+
+In `--once` and `--json` mode a failure prints two lines and exits `1`:
 
-```bash
-# Requires jq — derives session ID by stripping the "session-" prefix
-netclaw chat --resume "$(netclaw sessions --json | jq -r '.[0].persistenceId | ltrimstr("session-")')"
 ```
+[FAIL] sessions: unable to reach daemon at http://127.0.0.1:5199: Connection refused (127.0.0.1:5199)
+       fix: run `netclaw daemon start` and retry.
+```
+
+In the TUI the same failure shows "Failed to connect to daemon. Is it running?"
 
-## Related commands
+## Related pages
 
-- [`netclaw chat`](/cli/chat/) — Pass `--resume <id>` to jump straight into a specific session
-- [`netclaw chat -p`](/cli/chat/#headless-mode) — Headless mode with `--resume` for scripted multi-turn conversations
-- [`netclaw status`](/cli/status/) — Check daemon health if sessions can't connect
-- [`netclaw stats`](/cli/stats/) — Token usage and session count metrics
+- [`netclaw chat`](/cli/chat/): `--resume <id>` jumps into a session, and `-p` scripts it
+- [Scripting headless sessions](/guides/scripting-sessions/): headless multi-turn patterns
+- [`netclaw status`](/cli/status/): check daemon health when sessions can't connect
+- [`netclaw stats`](/cli/stats/): token and session counts
+- [Sessions](/architecture/sessions/): how a session is created, saved and recovered
 
 ## Resources
 
-- [jq manual](https://jqlang.github.io/jq/manual/) — filter and transform `--json` output
-- [Akka.NET persistence](https://getakka.net/articles/persistence/architecture.html) — how session state survives daemon restarts
+- [jq manual](https://jqlang.github.io/jq/manual/): filter and transform `--json` output
+- [Akka.NET persistence](https://getakka.net/articles/persistence/architecture.html): how session state survives daemon restarts
diff --git a/src/content/docs/cli/skill.md b/src/content/docs/cli/skill.md
index 29d8bab..149b256 100644
--- a/src/content/docs/cli/skill.md
+++ b/src/content/docs/cli/skill.md
@@ -1,11 +1,11 @@
 ---
 title: "netclaw skill"
-description: "Manage skills and external skill sources."
+description: "List, sync, inspect and validate skills, and manage external skill sources."
 ---
 
-Manage skills from the CLI — list what's installed, validate new ones, wire up external sources. None of these commands need a running daemon.
+`netclaw skill` shows what skills the agent has loaded, pulls updates from skill servers, checks a skill file before you rely on it, and manages the external directories netclaw reads. `list` and `sync` talk to the running daemon. Every other subcommand reads and writes files and works without it.
 
-Skills are markdown files following the [AgentSkills.io](https://agentskills.io) format: a `SKILL.md` with YAML frontmatter describing what the skill does, what tools it needs, and how to invoke it. At runtime, the agent sees a compressed skill index on every session and reads full skill content on demand — skills inject procedural knowledge into context without bloating the base prompt.
+For what skills are and how netclaw uses them, see [Skills overview](/skills/overview/).
 
 ## Usage
 
@@ -13,269 +13,218 @@ Skills are markdown files following the [AgentSkills.io](https://agentskills.io)
 netclaw skill [subcommand] [options]
 ```
 
-Running `netclaw skill` with no subcommand defaults to `list`.
+With no subcommand, `netclaw skill` runs `list`.
 
 ## Subcommands
 
-| Subcommand | Description |
-|------------|-------------|
-| `list` | List all discovered skills (default) |
-| `show <name>` | Show skill details and full content |
-| `validate <path>` | Validate a SKILL.md file's frontmatter |
-| `remove <name>` | Remove a native skill |
-| `issues` | Show only scanner issues |
-| `search <query>` | Search skills by name or description |
-| `source list` | List configured external sources |
-| `source add <name> --path <dir>` | Add a custom external source |
-| `source add <name> --well-known <alias>` | Add a well-known source |
-| `source remove <name>` | Remove an external source |
-| `source enable <name>` | Enable an external source |
-| `source disable <name>` | Disable an external source |
+| Subcommand | Needs daemon | Description |
+|------------|:------------:|-------------|
+| `list` | Yes | List every skill the daemon has loaded (default) |
+| `sync` | Yes | Run a skill server sync pass now |
+| `show <name>` | No | Show one skill's details and full content |
+| `validate <path>` | No | Check a `SKILL.md` or flat `.md` file |
+| `remove <name>` | No | Delete a native skill |
+| `issues` | No | Show skills with structural problems or shadowed by a higher tier |
+| `search <query>` | No | Find skills by name, display name or description |
+| `source list` | No | List external skill sources |
+| `source add <name> --path <dir>` | No | Add a directory as a source |
+| `source add <name> --well-known <alias>` | No | Add a well-known source (`claude-code` or `open-code`) |
+| `source remove <name>` | No | Remove a source from config |
+| `source enable <name>` | No | Enable a source |
+| `source disable <name>` | No | Disable a source without removing it |
+
+The offline subcommands scan the native directory (`~/.netclaw/skills/`) and your external sources. They don't see skills synced from a skill server or MCP prompt skills, so use `list` to see everything.
 
 ## Skill classifications
 
-Three categories:
+The `SOURCE` column in `list` and `search` takes one of these values:
 
-| Source | Location | Mutable? |
-|--------|----------|----------|
-| `system` | `~/.netclaw/skills/.system/` | No — managed by the daemon |
-| `native` | `~/.netclaw/skills/` | Yes — user-created |
-| `external` | Configured source directories | Manage at source |
+| Source | Where it comes from | Mutable |
+|--------|---------------------|---------|
+| `system` | `~/.netclaw/skills/.system/`, restored from the daemon binary on every start | No |
+| `native` | `~/.netclaw/skills/`, including skills synced from a skill server | Yes for your own skills |
+| `external` | A directory configured with `skill source` | At the source |
+| `mcp` | A prompt from a connected [MCP server](/configuration/mcp-servers/), `list` only | No |
 
-For a deeper look at how skills fit into netclaw's architecture, see [Skills Overview](/skills/overview/).
+Skills synced from a [skill server](/skills/skill-feeds/) live in `~/.netclaw/skills/.server-feeds/<feed>/`, so `list` labels them `native`. They aren't yours to edit. `skill_manage` refuses them, and the next sync restores any file you change. `skill source` doesn't manage them either. Add servers in `netclaw config` or `SkillFeeds` in `netclaw.json`. See [Skill feeds](/skills/skill-feeds/#add-a-feed).
 
-## Listing skills
+## Examples
+
+### List loaded skills
 
 ```bash
 netclaw skill list
 ```
 
+```text
+NAME                                      SOURCE      VERSION     STATUS
+------------------------------------------------------------------------
+flat-note                                 native      -           ok
+hello-greeter                             native      1.0.0       ok
+incident-summary                          native      1.1.0       ok
+k8s-log-triage                            native      0.2.0       ok
+agent-coordination                        system      1.5.3       ok
+netclaw-memory                            system      1.14.3      ok
+netclaw-operations                        system      2.144.0     ok
+netclaw-projects                          system      1.4.0       ok
+run-reminder                              system      1.0.2       ok
+search-citation                           system      1.1.4       ok
+skill-authoring                           system      1.12.0      ok
+subagent-authoring                        system      1.6.2       ok
+web-content-retrieval                     system      1.0.0       ok
+
+13 skill(s)
 ```
-NAME                      SOURCE      VERSION     STATUS
-commit                    native      1.0.0       ok
-review-pr                 native      1.2.0       ok
-akka-net-best-practices   external    -           ok
-modern-csharp-standards   external    -           ok
-session-context           system      -           ok
-my-broken-skill           ?           -           MissingDescription
-
-5 skill(s), 1 issue(s)
-```
 
-Skills with problems show their issue kind in the STATUS column. `netclaw skill issues` gives you the full details.
+![netclaw skill list output with a table of 13 skills, four native and nine system, all with status ok](/screenshots/output/skill-list.png)
+
+The four native rows are two local skills and two from a skill-server feed, and the nine system skills ship with netclaw. MCP prompt skills join the same table when a server provides them.
+
+`list` reads the daemon's live registry, which is the only view that includes MCP prompt skills. It lists accepted skills only, so `STATUS` is always `ok`. Use `netclaw skill issues` for rejected ones. If the daemon isn't reachable, `list` prints `Daemon unavailable: ...` and exits 1. There's no fallback to a disk scan. Start it with `netclaw daemon start`, or `docker restart <container>` in Docker.
 
-## Showing skill details
+### Sync feeds now
 
 ```bash
-netclaw skill show commit
+netclaw skill sync
 ```
 
+```text
+Waiting for the daemon's skill sync pass. Press Ctrl+C to stop this wait.
+Skill sync pass a304191e2ce04fc28782ad22f8385c2d
+corp-skills: ok changed=0 unchanged=2 rejected=0 failed=0 sidecar=complete
+Inventory: ok accepted=13 rejected=0
 ```
-Name:        commit
-Display:     Commit Changes
+
+![netclaw skill sync output reporting one feed, corp-skills, with two unchanged skills, and an inventory of 13 accepted](/screenshots/output/skill-sync.png)
+
+The feed line counts what changed on this pass, and the inventory line is the daemon's total after the refresh.
+
+`sync` starts a pass for every enabled [skill feed](/skills/skill-feeds/) right away instead of waiting for `SkillFeeds.SyncIntervalMinutes`. If a pass is already running, it waits for that one. It takes no flags and saves no config. Ctrl+C stops the wait, not the pass.
+
+It exits 1 when a feed reports `failed` or `rejected` above zero, when the inventory refresh fails, or when the daemon is unreachable. Each feed's `sidecar=` value (`complete`, `absent`, `failed`, `not-run`) reports the subagent pass. See [Skill feeds](/skills/skill-feeds/#when-syncs-run) for what each means.
+
+### Show a skill
+
+```bash
+netclaw skill show hello-greeter
+```
+
+```text
+Name:        hello-greeter
+Display:     Hello Greeter
 Source:      native
 Version:     1.0.0
-Category:    git
-License:     MIT
-Path:        /home/user/.netclaw/skills/commit/SKILL.md
+Category:    -
+License:     -
+Path:        /home/netclaw/.netclaw/skills/hello-greeter/SKILL.md
 Flat file:   False
-Tools:       bash git
-Description: Create well-structured git commits with conventional commit messages.
+Resources:   references/tone.md, scripts/stamp.sh
+Description: Greet the user by name and mention today's weekday.
 
 --- content ---
-(full SKILL.md content follows)
+(full SKILL.md follows)
 ```
 
-## Validating a skill file
+`Resources:` appears when the skill has supporting files. `show` finds skills by name in the native and external directories, so a feed skill answers `[FAIL] skill 'name' not found`.
 
-Catch frontmatter problems before deploying:
+### Validate a skill file
 
 ```bash
 netclaw skill validate ./my-skill/SKILL.md
 ```
 
-```
+```text
 [OK] Valid skill file.
   Name:        my-skill
   Description: Does something useful.
   Version:     1.0.0
-  License:     MIT
+  License:     -
 ```
 
-Once validated, drop the skill into `~/.netclaw/skills/` (directory-based or flat file) and it'll appear on the next `netclaw skill list`.
+A bad file says what's wrong and exits 1:
 
-A failing file tells you exactly what's wrong:
-
-```bash
-netclaw skill validate ./broken-skill.md
+```text
+[FAIL] MissingDescription: Skill frontmatter must include a non-empty description.
 ```
 
-```
-[FAIL] MissingDescription: Skill file missing required 'description' field.
-```
+`validate` applies the native rules: the frontmatter `name` must match the directory (or file) name, and symlinks aren't followed. A skill that loads fine from an external source can still fail here for either reason.
 
-## Searching skills
+Once a skill validates, put it in `~/.netclaw/skills/` as `name/SKILL.md` or `name.md`. The daemon rescans when files change, so `list` shows it without a restart.
 
-```bash
-netclaw skill search "testing"
-```
-
-```
-NAME                      SOURCE      VERSION     DESCRIPTION
-snapshot-testing          external    -           Verify test output using snapshot...
-integration-tests         external    -           Testcontainers patterns for .NET...
-
-2 match(es)
-```
-
-## Removing a skill
+### Check for problems
 
 ```bash
-netclaw skill remove my-old-skill
+netclaw skill issues
 ```
 
-Only native skills can be removed — system and external skills are read-only here.
+```text
+NAME                      KIND                            MESSAGE
+------------------------------------------------------------------
+broken-skill              MissingDescription              Skill frontmatter must include a non-empty description.
 
-## Managing external sources
-
-Point netclaw at skill directories from other tools (Claude Code, Open Code) or shared team paths.
+1 issue(s)
+```
 
-Note: [Skill feeds](/skills/skill-feeds/) are a separate concept — server-based skill repositories synced by the daemon. This section covers local directory sources only.
+`issues` is an offline structural scan of the native and external directories. It reports bad frontmatter, name mismatches, symlinks and skills shadowed by a higher tier. A copy shadowed by a system skill shows as `DuplicateName`. It doesn't report skill server rejections. Those go to the daemon log and the counts in `skill sync`.
 
-### List sources
+### Search skills
 
 ```bash
-netclaw skill source list
+netclaw skill search greeter
 ```
 
-```
-NAME                  ENABLED     TYPE            PATH / WELL-KNOWN
-claude-skills         yes         well-known      claude-code
-team-shared           yes         path            /opt/skills/team
-```
-
-When no sources are configured, netclaw checks for well-known directories and nudges you:
-
-```
-No external skill sources configured.
+```text
+NAME                      SOURCE      VERSION     DESCRIPTION
+----------------------------------------------------------
+hello-greeter             native      1.0.0       Greet the user by name and mention today's weekday.
 
-Detected well-known skill directories on disk:
-  claude-code      /home/user/.claude/skills
-Add one with: netclaw skill source add <name> --well-known <alias>
+1 match(es)
 ```
 
-### Add a well-known source
+### Remove a skill
 
 ```bash
-netclaw skill source add my-claude --well-known claude-code
+netclaw skill remove my-old-skill
 ```
 
-The aliases map to these paths:
-
-| Alias | Scans |
-|-------|-------|
-| `claude-code` | `~/.claude/skills/`, `~/.claude/commands/`, plus installed plugin marketplaces |
-| `open-code` | `~/.open-code/skills/` |
+`remove` deletes native skills only. A system skill fails with `cannot remove system skill`, and an external skill fails with `cannot remove external skill`. Delete the files at the source. Removal is permanent, because native skills have no history.
 
-During `netclaw init`, you're prompted to configure external skill sources:
+## Manage external sources
 
-![External skills configuration during init](/screenshots/output/init-07-external-skills.png)
-
-The init wizard detects well-known directories automatically.
-
-### Add a custom path source
+`skill source` manages local directories. It edits `netclaw.json`, and the running daemon restarts itself to pick up the change. See [External skills](/skills/external-skills/) for the config shape and the plugin scope of the `claude-code` alias.
 
 ```bash
+netclaw skill source list
+netclaw skill source add my-claude --well-known claude-code
 netclaw skill source add team-skills --path /opt/company/skills
-```
-
-The directory must exist. Netclaw scans for both directory-based skills (`skill-name/SKILL.md`) and flat files (`skill-name.md`).
-
-### Enable / disable a source
-
-```bash
 netclaw skill source disable team-skills
 netclaw skill source enable team-skills
-```
-
-Disabled sources stay in config but won't be scanned.
-
-### Remove a source
-
-```bash
 netclaw skill source remove team-skills
 ```
 
-Removes the config entry only — skill files in the directory are untouched.
-
-## Skill file format
-
-Two layouts work:
-
-**Directory-based:**
-
-```
-my-skill/
-  SKILL.md
-  scripts/
-    helper.sh
-  references/
-    api-docs.md
-  assets/
-    diagram.png
-```
-
-**Flat file:**
-
-```
-my-skill.md
-```
-
-The SKILL.md frontmatter:
-
-```yaml
----
-name: my-skill
-description: One-line description of what this skill does.
-metadata:
-  version: 1.0.0
-license: MIT
-compatibility: ["netclaw", "claude-code"]
-allowed-tools: "bash git"
-disable-model-invocation: false
-user-invocable: true
-argument-hint: "<branch-name>"
----
+| Alias | Reads |
+|-------|-------|
+| `claude-code` | `~/.claude/skills/`, `~/.claude/commands/`, and `~/.claude/plugins/marketplaces/*/skills/` |
+| `open-code` | `~/.open-code/skills/` |
 
-# My Skill
+`--path` fails with `[FAIL] directory not found` if the directory doesn't exist. Names have to be unique. `--well-known` sources get `AllowSymlinks: true`, and `--path` sources don't. `remove` deletes the config entry and leaves your skill files alone. With no sources configured, `source list` prints any well-known directories it finds on disk and the command to add them.
 
-Skill instructions go here...
-```
+With no action, `netclaw skill source` lists your sources. An unknown action prints the usage text.
 
-The display name is derived from the first `#` heading in the markdown body, falling back to title-casing the skill name.
+## Frontmatter
 
-| Field | Required | Description |
-|-------|----------|-------------|
-| `name` | Yes | Identifier (must match directory/file name) |
-| `description` | Yes | One-line summary |
-| `metadata.version` | No | Semver version (nested under `metadata:`) |
-| `license` | No | SPDX license identifier |
-| `compatibility` | No | Which agents can use this skill |
-| `allowed-tools` | No | Space-delimited list of tools the skill needs |
-| `disable-model-invocation` | No | When `true`, prevents the model from auto-invoking this skill |
-| `user-invocable` | No | When `true`, users can invoke the skill directly (e.g. `/commit`) |
-| `argument-hint` | No | Hint text shown in command completion |
+The `SKILL.md` format, including the `invocable` key and its default, is in [Skills overview](/skills/overview/#what-a-skill-looks-like). Unknown keys are ignored without a warning. A skill with `user-invocable: false` stays a `/` command, because the key is `invocable`.
 
-## Related commands
+## Related pages
 
-- [`netclaw init`](/cli/init/) — configures external skill sources during onboarding
-- [`netclaw mcp`](/cli/mcp-tools/) — manage tool servers that skills reference in `allowed-tools`
-- [`netclaw status`](/cli/status/) — shows loaded skill count at runtime
+- [Skills overview](/skills/overview/): tiers, precedence, formats and trust
+- [Skill feeds](/skills/skill-feeds/): configure skill servers and read the sync output
+- [External skills](/skills/external-skills/): local directories and the Claude Code alias
+- [`netclaw config`](/cli/config/): the Skill Sources screen
+- [`netclaw stats`](/cli/stats/): `stats skills` shows which skills the agent loads
 
 ## Resources
 
-- [AgentSkills.io](https://agentskills.io) — the SKILL.md format specification
-- [Cloudflare Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc) — discovery protocol for skill feeds
-- [netclaw skill-server](https://github.com/netclaw-dev/skill-server) — self-hosted skill registry for organizations
-- [Skills Overview](/skills/overview/) — how skills work at runtime
-- [Skill Feeds](/skills/skill-feeds/) — server-synced skill repositories
+- [AgentSkills.io](https://agentskills.io): the `SKILL.md` format specification
+- [Cloudflare Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc): the discovery protocol behind skill feeds
+- [netclaw skill-server](https://github.com/netclaw-dev/skill-server): the self-hosted skill registry
diff --git a/src/content/docs/cli/stats.md b/src/content/docs/cli/stats.md
index 93e365c..e90161c 100644
--- a/src/content/docs/cli/stats.md
+++ b/src/content/docs/cli/stats.md
@@ -1,9 +1,9 @@
 ---
 title: "netclaw stats"
-description: "View usage activity statistics."
+description: "See token use, session counts, memory health, skill loads, webhook deliveries and reminder counts from the running daemon."
 ---
 
-`netclaw stats` tells you where your tokens are going, how many sessions are running, and whether memory is healthy. It also covers channel activity, webhook deliveries, and reminders. `--json` for scripts, `--tui` for a live dashboard.
+`netclaw stats` tells you where your tokens are going, how many sessions are running, whether memory is healthy and which skills get loaded. It also covers channel activity, webhook deliveries and reminders. `--json` is for scripts and `--tui` opens a dashboard.
 
 ## Usage
 
@@ -12,88 +12,112 @@ netclaw stats [options]
 netclaw stats skills [options]
 ```
 
-Requires a running daemon. If it's not up, start it with `netclaw daemon start` (or run [`netclaw init`](/cli/init/) which starts it for you).
+It needs a running daemon. If it's down, start it with `netclaw daemon start` (`docker restart <container>` in Docker), or run [`netclaw init`](/cli/init/), which starts it for you.
 
 ## Options
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `--days <N>` | Show trailing N-day daily breakdown | None (omits daily table) |
-| `--all` | Show all-time daily breakdown | Off |
-| `--tui` | Visual TUI dashboard | Off |
-| `--json` | Alias for `--format json` | — |
+| `--days <N>` | Add a daily breakdown for the trailing N days (a positive integer) | No daily table |
+| `--all` | Add an all-time daily breakdown | Off |
+| `--tui` | Open the dashboard | Off |
+| `--json` | Alias for `--format json` | |
 | `--format <text\|json>` | Output format | `text` |
 
+An unknown option, a bad `--days` value or a bad format prints `[FAIL] stats options: ...` with the usage and exits `1`.
+
 ## Output
 
 ```bash
 netclaw stats
 ```
 
-![netclaw stats showing token usage, sessions, memory, channel activity, webhooks, and reminders](/screenshots/output/stats.png)
+```
+netclaw stats — usage since daemon started (8m 40s ago)
 
-Without `--days` or `--all`, you get process-lifetime counters plus current snapshot data. No daily table.
+this process:
+  tokens: in=150 out=90
+  turns: 10    memories: formed=0 recalled=0    skills loaded: 2
 
-| Section | What it shows |
-|---------|---------------|
-| **this process** | Token consumption (in/out), turns completed, [memories](/architecture/overview/) formed/recalled, [skills](/skills/overview/) loaded |
-| **sessions** | Total, active, and all-time turn count |
-| **memory** | Status (`healthy`, `degraded`, `unavailable`), anchor/document/record/edge counts, pending checkpoints |
-| **skills** | Total available skill count |
-| **\<channel\>** | Per-channel events (recv/routed/dropped) and replies (posted/rejected/failed) |
-| **webhooks** | Route counts, delivery stats, rejection breakdown by HTTP status |
-| **reminders** | Scheduled, active, and failed counts |
+sessions:
+  total: 19    active: 11    turns (all-time): 17
 
-The "this process" counters live in the daemon process's memory and reset when the daemon restarts. Everything else (sessions, memory, daily breakdown) is persisted to SQLite and survives restarts.
+memory (healthy):
+  anchors: 0    documents: 0    records: 0    edges: 0
+  pending checkpoints: 0
 
-If memory status shows `degraded` or `unavailable`, run [`netclaw doctor --fix`](/cli/doctor/) to fix common issues automatically.
+skills:
+  available: 8
 
-### Daily breakdown
+webhooks:
+  routes: total=0 enabled=0 disabled=0 invalid=0
+  deliveries: accepted=0 filtered=0 duplicate=0
+  rejected: 404=0 401=0 413=0 400=0 429=0
 
-Add `--days` to see a per-day table of token usage and activity:
+reminders:
+  scheduled: 0    active: 0    failed: 0
+```
 
-```bash
-# Last 14 days
-netclaw stats --days 14
+![netclaw stats output for a daemon that has handled three chat turns, showing token counts, three sessions, memory, skills, webhooks and reminders sections](/screenshots/output/stats.png)
 
-# All time
-netclaw stats --all
-```
+This daemon had been up about three minutes and had handled three short chats, so tokens and sessions are non-zero. It's the same demo install as the other status screenshots, so skills, webhook routes and scheduled reminders match what `netclaw skill list`, `netclaw webhooks list` and `netclaw reminder list` show. Enabling Slack adds a `slack` section.
+
+| Section | What it shows |
+|---------|---------------|
+| **this process** | Tokens in and out, turns, [memories](/architecture/memory-model/) formed and recalled, and skills loaded |
+| **sessions** | Total, active and all-time turn counts |
+| **memory** | `healthy`, `degraded` or `unavailable`, with anchor, document, record and edge counts and pending checkpoints |
+| **skills** | How many skills are available |
+| **\<channel\>** | Per-channel events (`recv`, `routed`, `dropped`) and replies (`posted`, `rejected`, `failed`). Printed for channels with activity. |
+| **webhooks** | Route counts, delivery counts and rejections by HTTP status |
+| **reminders** | Scheduled, active and failed counts. **failed** counts enabled reminders that currently have consecutive failures. A reminder you disable, or one that has since run cleanly, drops out. |
 
-Columns: date, input/output tokens, turns, sessions, memories formed/recalled, skills loaded. When more than one day of data is returned, a totals row appears at the bottom.
+The **this process** counters live in the daemon's memory and reset when it restarts. Sessions, memory and the daily breakdown come from SQLite and survive restarts. If memory reads `degraded` or `unavailable`, run [`netclaw doctor`](/cli/doctor/).
 
-## TUI dashboard
+### Daily breakdown
 
 ```bash
-netclaw stats --tui
+netclaw stats --days 7
+```
+
+```
+date          in tokens    out tokens   turns   sessions   mem formed   mem recalled   skills
+----------   ----------   ----------   -----   --------   ---------   ------------   ------
+2026-10-14          240          144      17         20           0              0        2
 ```
 
-Opens a full-screen dashboard. `--tui` always shows an ASCII bar chart of daily token usage, defaulting to the last 7 days. Pass `--days N` to change the window:
+Use `--all` for all time. With more than one day of data, a totals row closes the table.
+
+## Dashboard
 
 ```bash
+netclaw stats --tui
 netclaw stats --tui --days 30
 ```
 
-The lower half of the dashboard shows the Daily Token Usage bar chart by default. Memory, per-channel, and Webhooks panels take its place when there's no daily breakdown data.
+The dashboard shows token totals, activity and a bar chart of daily token use, defaulting to the last 7 days. When there's no daily data, the memory, per-channel and webhook panels take the chart's place.
 
-`Q`, `Escape`, or `Ctrl+C` to quit.
+Only `Ctrl+Q` quits. `Q`, `Esc` and `Ctrl+C` don't close the view. `--tui` is ignored by `stats skills`, which prints the plain-text report instead of opening a dashboard.
 
-## Skill usage stats
+## Skill usage
 
-`stats skills` shows per-skill load counts broken down by day and invocation method (e.g., `direct`, `auto`, `scheduled`):
+`stats skills` counts skill loads per day, by how they were loaded and by skill:
 
 ```bash
-# Last 7 days (default)
-netclaw stats skills
-
-# Last 30 days
+netclaw stats skills            # last 7 days
 netclaw stats skills --days 30
-
-# All time
 netclaw stats skills --all
 ```
 
-Each day shows total loads, a method breakdown, and per-skill counts (top 15). `--tui` doesn't work with `stats skills`.
+```
+netclaw stats skills — all time
+
+2026-10-14  total=2
+  by method: slash-command=2
+  run-reminder: 2 (slash-command=2)
+```
+
+The three load methods are `slash-command` (you typed `/name`, see [Slash commands](/reference/slash-commands/)), `skill-load` (the model called `skill_load`) and `file-read` (a skill file was read directly). Each day lists the top 15 skills, then a count of the rest. With nothing recorded it prints `No skill loads recorded.`
 
 ## JSON output
 
@@ -101,70 +125,43 @@ Each day shows total loads, a method breakdown, and per-skill counts (top 15). `
 netclaw stats --json
 ```
 
+The keys are camelCase.
+
 ```bash
-# Total input tokens since daemon started
 netclaw stats --json | jq '.tokens.inputTokensTotal'
-
-# Daily token usage for the last 7 days
 netclaw stats --days 7 --json | jq '.dailyBreakdown[] | {date, inputTokens, outputTokens}'
-
-# Active session count
 netclaw stats --json | jq '.sessions.activeSessions'
-
-# Memory health status
 netclaw stats --json | jq -r '.memory.status'
-```
-
-`stats skills --json` returns a separate shape with daily skill load breakdowns:
-
-```bash
 netclaw stats skills --json | jq '.daily[] | {date, totalLoads}'
 ```
 
+The top-level keys are `process`, `tokens`, `sessions`, `memory`, `skills`, `channels`, `webhooks`, `reminders` and `dailyBreakdown`. `stats skills --json` has a single `daily` array whose entries hold `date`, `totalLoads`, `methods` and `skills`.
+
 ## Exit codes
 
 | Code | Meaning |
 |------|---------|
 | `0` | Success |
-| `1` | Daemon unreachable or error response |
-
-## Daemon endpoint
-
-`stats` queries `http://127.0.0.1:5199` by default. Override with:
-
-- `NETCLAW_DAEMON_ENDPOINT` environment variable
-- `~/.netclaw/client/config.json`
-
-See [`netclaw status`](/cli/status/) for more on endpoint configuration.
+| `1` | The daemon is unreachable or answered with an error, or the options were wrong |
 
 ## When the daemon isn't running
 
-You'll see one of two errors:
-
-**Connection refused** — the daemon process isn't running at all:
-
-```
-[FAIL] stats: unable to reach daemon at http://127.0.0.1:5199: Connection refused
-       fix: run `netclaw daemon start` and retry.
-```
-
-**503 response** — the daemon is up but not ready (still starting, or something broke):
-
 ```
-[FAIL] stats: daemon returned 503 from http://127.0.0.1:5199
+[FAIL] stats: unable to reach daemon at http://127.0.0.1:5199: Connection refused (127.0.0.1:5199)
        fix: run `netclaw daemon start` and retry.
 ```
 
-For 503s, [`netclaw doctor --fix`](/cli/doctor/) can often sort out what's wrong without a restart.
+A daemon that answers with an error status, such as `503` while starting, prints `[FAIL] stats: daemon returned 503 from <endpoint>`. `stats` finds the daemon the same way [`netclaw status`](/cli/status/#daemon-endpoint) does: `NETCLAW_DAEMON_ENDPOINT`, then `~/.netclaw/client/config.json`, then `netclaw.json`, then `http://127.0.0.1:5199`.
 
-## Related commands
+## Related pages
 
-- [`netclaw status`](/cli/status/) — live health check for daemon, connectors, and model
-- [`netclaw doctor`](/cli/doctor/) — config diagnostics with `--fix` for auto-repair
-- [`netclaw sessions`](/cli/sessions/) — if stats show unexpected session counts, dig into individual conversations here
-- [`netclaw init`](/cli/init/) — first-run setup (starts the daemon for you)
+- [`netclaw status`](/cli/status/): live health for the daemon, connectors and model
+- [`netclaw doctor`](/cli/doctor/): config diagnostics with `--fix`
+- [`netclaw sessions`](/cli/sessions/): dig into the sessions behind the counts
+- [Memory model](/architecture/memory-model/): what the memory counters measure
+- [OpenTelemetry](/observability/opentelemetry/): export the same signals to a collector
 
 ## Resources
 
-- [jq manual](https://jqlang.github.io/jq/manual/) — for wrangling `--json` output
-- [SQLite documentation](https://www.sqlite.org/docs.html) — daily breakdown data is persisted here
+- [jq manual](https://jqlang.github.io/jq/manual/): work with `--json` output
+- [SQLite documentation](https://www.sqlite.org/docs.html): the daily breakdown is stored in SQLite
diff --git a/src/content/docs/cli/status.md b/src/content/docs/cli/status.md
index 11d2ef8..26c9248 100644
--- a/src/content/docs/cli/status.md
+++ b/src/content/docs/cli/status.md
@@ -1,9 +1,9 @@
 ---
 title: "netclaw status"
-description: "Query daemon runtime status."
+description: "Query the running daemon for health, model, connector states and update availability."
 ---
 
-`netclaw status` queries the running daemon and prints overall health, connector states, the active model, persistence, telemetry counters, and whether an update is available. Run it when something feels off, or wire it into a health check script.
+`netclaw status` asks the running daemon how it's doing and prints overall health, the active model, each connector's state, persistence and memory status, and whether an update is available. Run it when something feels off, or wire it into a health-check script.
 
 ## Usage
 
@@ -11,14 +11,16 @@ description: "Query daemon runtime status."
 netclaw status [options]
 ```
 
-Requires a running daemon. If it's not up, start it with `netclaw daemon start` (or run [`netclaw init`](/cli/init/) which starts it for you).
+It needs a running daemon. If it's down, start it with `netclaw daemon start` (`docker restart <container>` in Docker), or run [`netclaw init`](/cli/init/), which starts it for you.
 
 ## Options
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `--format <text\|json>` | Output format | `text` |
-| `--json` | Alias for `--format json` | — |
+| `--format <text\|json>` | Output format. `--format=json` also works. | `text` |
+| `--json` | Alias for `--format json` | |
+
+An unknown option or format prints `[FAIL] status options: ...` with the usage text and exits `1`.
 
 ## Output
 
@@ -26,120 +28,168 @@ Requires a running daemon. If it's not up, start it with `netclaw daemon start`
 netclaw status
 ```
 
-![netclaw status showing healthy daemon with connectors](/screenshots/output/status.png)
+```
+overall: healthy
+version: 0.28.2 (commit 7419d84, built 2026-10-29T00:10:12Z)
+daemon: PID 32, uptime 1m 22s, endpoint http://127.0.0.1:5199
+persistence: Sqlite
+memory: sqlite (healthy)
+telemetry: disabled
+model: stub-model (provider: stub, context: 32,768 tokens)
+  input: Text
+  output: Text
+connectors:
+- discord: disabled (disabled)
+    Discord connector is disabled in configuration.
+- mattermost: disabled (disabled)
+    Mattermost connector is disabled in configuration.
+- slack: disabled (disabled)
+    Slack connector is disabled in configuration.
+- tui: healthy (enabled)
+
+update: up-to-date (v0.28.2)
+```
 
-| Section | What it tells you |
-|---------|-------------------|
-| **overall** | `healthy` or `degraded` |
-| **version** | Build version, commit hash, build timestamp |
-| **daemon** | PID, uptime, endpoint URL |
-| **persistence** | Storage provider (e.g., SQLite) |
-| **memory** | Memory provider and status — returns `unavailable`, `healthy`, or `degraded` |
-| **telemetry** | Enabled/disabled, [OpenTelemetry Protocol](https://opentelemetry.io/docs/specs/otlp/) (OTLP) endpoint if active |
-| **counters** | Per-channel message stats: `recv`, `routed`, `dropped`, `replied`, `rejected`, `reply_failed` |
-| **model** | Active model name, provider, context window, input/output modalities |
-| **connectors** | Each connector's key, status, and enabled/disabled state |
-| **update** | Whether a newer version is available |
+![netclaw status output: overall healthy, version 0.28.2, the active model, and connector lines for Discord, Mattermost, the demo-utilities MCP server, Slack and the TUI](/screenshots/output/status.png)
 
-### Overall status logic
+The connectors are Discord, Mattermost and Slack (all disabled in this capture), one MCP server and the TUI. A channel with traffic adds a `<channel> counters` line.
 
-`overall` reflects connector health:
+| Line | What it tells you |
+|------|-------------------|
+| `overall` | `healthy` or `degraded` |
+| `config on disk not applied` | Printed under `overall` only when the daemon refused the current `netclaw.json`. See [below](#when-the-config-on-disk-isnt-applied). |
+| `version` | Build version, commit and build time |
+| `daemon` | PID, uptime and the endpoint `status` queried |
+| `persistence` | The storage provider, such as `Sqlite` |
+| `memory` | Memory provider and its status: `healthy`, `degraded` or `unavailable` |
+| `telemetry` | `enabled` with the OTLP endpoint, or `disabled` |
+| `<channel> counters` | Per-channel message counts (`recv`, `routed`, `dropped`, `replied`, `rejected`, `reply_failed`). Only printed for channels with telemetry. |
+| `model` | Active model, the provider (the name you gave it in your config, such as `lab`), context window and input and output modalities |
+| `connectors` | One entry per connector with its status and `enabled` or `disabled`, plus a detail line when there is one |
+| `update` | `up-to-date`, `UPDATE AVAILABLE` with the command to run, or `unknown` |
 
-- **healthy** — all enabled connectors are healthy
-- **degraded** — any enabled connector is `disconnected`, `degraded`, `auth-required`, or `auth-failed`
+### What makes overall degraded
 
-### Connector statuses
+`overall` is `degraded` when any enabled connector is `disconnected`, `degraded`, `auth-required` or `auth-failed`. It's also `degraded` when the daemon has no usable provider or model and is running the No-Op chat client, whatever the connectors say. In that case the `model:` line reads:
+
+```
+model: (none — No-Op chat client active)
+  reason: <why>
+  fix: run `netclaw doctor` for details; use `netclaw init` if no provider is configured.
+```
+
+### When the config on disk isn't applied
+
+The daemon applies a change to `netclaw.json` by itself, but it refuses a file that doesn't validate and keeps running the previous configuration. When that happens `status` is `degraded` and exits `2`:
+
+```
+overall: degraded
+config on disk not applied: Models:Roles:Main references unknown definition 'nope'. Defined: stub-stub-model. Fix the name, or run `netclaw model set main <provider> <model>`.
+  The daemon is still running the previous configuration. No change from netclaw.json is applied until this is fixed.
+version: 0.28.2 (commit 7419d84, built 2026-10-29T00:10:12Z)
+...
+```
+
+The `model:` line below it still shows the model the daemon is running, not the one in the file. Fix the file and the line goes away on its own. [`netclaw doctor`](/cli/doctor/) names the same problem under Chat Client. In `--json` the reason is the `configNotApplied` string, `null` when nothing is wrong.
 
-Channel connectors (Slack, Discord) report: `healthy`, `degraded`, `disconnected`, `disabled`, `unknown`.
+### Connector statuses
 
-MCP connectors — keyed as `mcp:<server-name>` from your configured [MCP tool servers](/cli/mcp-tools/) — add: `auth-required` and `auth-failed`.
+Slack, Discord, Mattermost and the local `tui` connector report `healthy`, `degraded`, `disconnected`, `disabled` or `unknown`. [MCP servers](/cli/mcp-tools/) appear as `mcp:<server-name>` and can also report `auth-required` and `auth-failed`.
 
-Disabled connectors still appear in the list with `(disabled)` so you can tell they're intentionally off, not broken. To enable them, run [`netclaw config`](/cli/config/) — channels, search, exposure mode, and webhooks all live there.
+A provider whose OAuth sign-in was rejected on refresh appears as a connector named `provider:<name>` (`Provider/<name>` in the display name), enabled, with status `auth-failed` and the message `The OAuth credentials need a new sign-in (<reason>). Run `netclaw provider`.` That makes `overall` `degraded` and the exit code `2`.
 
-If any connector shows `degraded` or worse, run [`netclaw doctor --fix`](/cli/doctor/) to auto-repair common issues. If that doesn't resolve it, check the specific connector's configuration in [`netclaw config`](/cli/config/).
+Disabled connectors are listed on purpose, so you can tell they're off and not broken. Turn them on in [`netclaw config`](/cli/config/). If a connector is `degraded` or worse, run [`netclaw doctor`](/cli/doctor/) and then check that connector's settings.
 
 ## Exit codes
 
 | Code | Meaning |
 |------|---------|
 | `0` | Healthy |
-| `2` | Degraded |
-| `1` | Daemon unreachable or error response |
+| `2` | Degraded, including a `netclaw.json` the daemon refused to apply |
+| `1` | The daemon is unreachable, answered with an error, or the options were wrong |
 
-Exit code `2` for degraded (rather than `1`) lets scripts distinguish "something's wrong but running" from "down entirely":
+Exit `2` for degraded lets a script tell "running but unhappy" from "down":
 
 ```bash
 netclaw status > /dev/null 2>&1
-rc=$?
-case $rc in
+case $? in
   0) echo "healthy" ;;
-  2) echo "degraded — check connectors" ;;
+  2) echo "degraded: check connectors and the model" ;;
   *) echo "down or unreachable" ;;
 esac
 ```
 
-Note: the [CLI overview](/cli/overview/) documents exit code `2` as "usage/argument error" for most commands. `status` is an exception — it uses `2` specifically for degraded health.
-
 ## JSON output
 
 ```bash
 netclaw status --json
 ```
 
-Returns the full status response as JSON.
-
-The JSON includes fields not shown in text output — notably `reminders` (with `scheduledCount`, `activeExecutions`, `failedCount`). Also, the `version` text section maps to the `.build` key in JSON, so use `jq '.build'` rather than `jq '.version'`:
+The JSON carries more than the text view: `configNotApplied`, `reminders` (`scheduledCount`, `activeExecutions`, `failedCount`), `memory.embeddings`, and an `update` object that the CLI fills in with `available`, `state`, `currentVersion`, `latestVersion` and `releaseNotesUrl`. The version block is called `build`, not `version`.
 
 ```bash
-# Check overall health
 netclaw status --json | jq -r '.overall'
-
-# Get version info (note: `.build`, not `.version`)
 netclaw status --json | jq '.build'
+netclaw status --json | jq -c '[.connectors[] | select(.enabled and .status != "healthy")]'
+netclaw status --json | jq '.memory.embeddings'
+```
 
-# List unhealthy connectors
-netclaw status --json | jq '[.connectors[] | select(.enabled and .status != "healthy")]'
+```json
+{ "version": "0.28.2", "commitHash": "7419d84", "buildTimestamp": "2026-10-29T00:10:12Z" }
 ```
 
+That's the output of the second command. The third prints `[]` when every enabled connector is healthy.
+
+A file the CLI itself can't parse (empty, cut off, a duplicate key) gets the same `degraded` report, preceded by two lines on stderr that `--json` leaves out of the output you pipe:
+
+```
+Couldn't read netclaw.json: A duplicate key 'configVersion' was found.
+The daemon address could not be read from the config; checking the default port.
+```
+
+`status` then asks the default port, so it works against a local daemon. Other commands stop at the first line and exit `1`. See [`Couldn't read netclaw.json`](/troubleshooting/common-problems/#couldnt-read-netclawjson).
+
 ## When the daemon isn't running
 
-If the daemon is unreachable, you'll see one of:
+An unreachable daemon gives:
 
 ```
-[FAIL] status: unable to reach daemon at http://127.0.0.1:5199: Connection refused
-fix: run 'netclaw daemon start' and retry.
+[FAIL] status: unable to reach daemon at http://127.0.0.1:5199: Connection refused (127.0.0.1:5199)
+       fix: run `netclaw daemon start` and retry.
 ```
 
+A daemon that answers with an error status, such as `503` while starting, gives:
+
 ```
 [FAIL] status: daemon returned 503 from http://127.0.0.1:5199
-fix: run 'netclaw daemon status' and 'netclaw daemon start'.
+       fix: run `netclaw daemon status` and `netclaw daemon start`.
 ```
 
-The distinction:
-
-| Command | What it checks | Daemon required |
-|---------|---------------|-----------------|
-| `netclaw daemon status` | PID file — is the process running? | No |
-| `netclaw status` | Live health query — are connectors, model, persistence all working? | Yes |
+With no `netclaw.json` and no remote endpoint configured, `status` prints `daemon not configured - please run netclaw init` and exits `1`. With `--json` it prints `{"overall": "not-configured", "message": ...}`.
 
-If you're not sure the process is alive, start with `daemon status`. Once it's up, `status` gives the full picture.
+| Command | What it checks | Needs the daemon |
+|---------|----------------|------------------|
+| `netclaw daemon status` | The PID file: is the process alive? | No |
+| `netclaw status` | A live health query: connectors, model, persistence | Yes |
 
 ## Daemon endpoint
 
-`status` queries `http://127.0.0.1:5199/api/health/status` by default. Override with:
+`status` queries `http://127.0.0.1:5199/api/health/status` unless something else is set. netclaw looks in this order and uses the first hit:
 
-- `NETCLAW_DAEMON_ENDPOINT`
-- `~/.netclaw/client/config.json`
+1. `NETCLAW_DAEMON_ENDPOINT`
+2. `~/.netclaw/client/config.json`, written by [`netclaw pair`](/guides/pairing-remote-devices/)
+3. The `Daemon` section of `netclaw.json`
+4. The default above
 
-## Related commands
+## Related pages
 
-- [`netclaw config`](/cli/config/) — Enable and configure connectors, search, exposure mode, and more
-- [`netclaw doctor`](/cli/doctor/) — Diagnostics with auto-repair (`--fix`)
-- [`netclaw stats`](/cli/stats/) — Token usage, session counts, and memory metrics
-- [`netclaw chat`](/cli/chat/) — Start a conversation (check status first if connections fail)
-- [`netclaw init`](/cli/init/) — First-run setup that starts the daemon for you
+- [`netclaw doctor`](/cli/doctor/): offline diagnostics with `--fix`
+- [`netclaw stats`](/cli/stats/): token use, session counts and memory metrics
+- [`netclaw config`](/cli/config/): enable and configure connectors
+- [`netclaw chat`](/cli/chat/): start a conversation
+- [Health checks](/observability/health-checks/): the HTTP endpoints behind `status`
 
 ## Resources
 
-- [jq manual](https://jqlang.github.io/jq/manual/) — for wrangling `--json` output
-- [OpenTelemetry collector docs](https://opentelemetry.io/docs/collector/) — if you're sending telemetry to an OTLP endpoint
+- [jq manual](https://jqlang.github.io/jq/manual/): work with `--json` output
+- [OpenTelemetry Collector docs](https://opentelemetry.io/docs/collector/): if you send telemetry to an OTLP endpoint
diff --git a/src/content/docs/cli/update.md b/src/content/docs/cli/update.md
new file mode 100644
index 0000000..8f62bc4
--- /dev/null
+++ b/src/content/docs/cli/update.md
@@ -0,0 +1,144 @@
+---
+title: "netclaw update"
+description: "Check for a newer netclaw release, install it, and switch between the stable and beta channels."
+---
+
+`netclaw update` downloads the newest release on your channel, verifies it, swaps the `netclaw` and `netclawd` binaries, and restarts the daemon if it was running. Run it on a host install. In Docker you pull a new image instead.
+
+## Usage
+
+```bash
+netclaw update [options]
+```
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--check` | Report whether an update exists and install nothing | Off |
+| `--force` | Skip the `Proceed with update? [y/N]` prompt | Off |
+| `--channel <name>` | Switch the release channel, `stable` or `beta`, and save it to `netclaw.json`. With `--check` it previews the channel and saves nothing. | `stable` |
+
+An unknown channel or flag prints the usage text and exits `1`. `--channel` with no value prints `--channel requires a value: stable or beta.`
+
+## Examples
+
+### Check, then install
+
+```bash
+netclaw update --check
+netclaw update
+```
+
+```text
+Update available: v0.28.0 → v0.28.2
+Release notes: https://github.com/netclaw-dev/netclaw/releases/tag/0.28.2
+
+  netclaw (linux-x64) - 70.2 MB
+  netclawd (linux-x64) - 74.7 MB
+
+Proceed with update? [y/N]: y
+Downloading netclaw... verified.
+Downloading netclawd... verified.
+Stopping daemon... done.
+Installing... done.
+Restarting daemon... done.
+
+Updated to v0.28.2.
+```
+
+![Terminal showing netclaw --version reporting 0.28.1, then netclaw update --check reporting that v0.28.2 is available with a release notes link](/screenshots/output/update-check.png)
+
+The check alone, from a 0.28.1 install. It reports and changes nothing.
+
+Add `--force` for scripts. When the daemon is already current, the command prints `Netclaw is up to date (v0.28.2).` and exits `0`.
+
+### Move to the beta channel
+
+```bash
+netclaw update --channel beta
+```
+
+This saves `Daemon.UpdateChannel` to `netclaw.json`, then installs the newest build on that channel. Later checks follow it. `--channel stable` switches back. Beta resolves to the newest of the latest prerelease and the latest stable, so a stable release that supersedes a beta is still offered.
+
+## What it changes
+
+| Touched | Not touched |
+|---------|-------------|
+| The `netclaw` and `netclawd` binaries, in the directory of the running CLI (`~/.netclaw/bin` by default) | `~/.netclaw` data, `netclaw.json` and `secrets.json` |
+| `Daemon.UpdateChannel` in `netclaw.json`, only when you pass `--channel` without `--check` | The systemd unit file and `daemon.env`. The unit keeps the same `ExecStart` path, which is why updates work in place. |
+
+The command keeps the daemon's owner, using the same rule as [`netclaw daemon stop` and `start`](/cli/daemon/#under-systemd). When the systemd user unit is running this home's daemon, it stops and starts the daemon with `systemctl --user`. A daemon you started by hand, or one that belongs to a different `NETCLAW_HOME`, goes through `netclaw daemon stop` and `start`, which first prove the PID serves this home (see [Home check](/cli/daemon/#home-check)). On Linux that proof reads `/proc/<pid>/environ`. On macOS and Windows a daemon that doesn't answer with its home can't be proven. A 0.27.1 daemon is one, so stop it by hand before you update from 0.27.1. A daemon that wasn't running stays stopped.
+
+It verifies the release manifest's signature and each archive's SHA-256 before it touches a binary. If the signature check fails, the command stops and says the manifest may have been tampered with. If swapping a binary fails, the previous binary is restored. After a successful update the old binaries are deleted, so there's nothing to roll back to. To go back, [install an older release](#pin-or-go-back-to-a-version).
+
+The new daemon migrates `netclaw.db` forward when it starts, and the older one can't read everything the newer one writes. Take a [backup](/guides/backup-and-restore/) first, and read [Upgrade netclaw](/guides/upgrading/) for what changes between versions.
+
+## Pin or go back to a version
+
+`netclaw update` always installs the newest release on the channel. It has no `--version` flag. To pin an exact version or install an older one, run the install script with `NETCLAW_VERSION`. It replaces the binaries and leaves your data alone:
+
+```bash
+systemctl --user stop netclaw
+curl -sSL https://releases.netclaw.dev/install.sh | NETCLAW_VERSION=0.28.0 bash
+systemctl --user start netclaw
+```
+
+Going back past 0.27.0 isn't a supported path. See [Downgrading](/guides/upgrading/#downgrading).
+
+## When the daemon says an update exists
+
+The daemon checks at startup and every 24 hours. It logs a warning, raises an `update.available` [alert](/observability/operational-alerts/), and shows the state in [`netclaw status`](/cli/status/). It never downloads or installs anything. Most other `netclaw` commands also print a one-line `Update available` notice to stderr. [`netclaw doctor`](/cli/doctor/) reports it as a warning.
+
+## Docker
+
+The image sets `Daemon.DisableSelfUpdate=true`, so installing is refused:
+
+```text
+Update available: v0.28.0 → v0.28.2
+Release notes: https://github.com/netclaw-dev/netclaw/releases/tag/0.28.2
+
+Self-update is disabled (Daemon.DisableSelfUpdate=true).
+Pull a newer container image to upgrade.
+```
+
+The command exits `1`. `--check` still works. Change the image tag, as described in [Run netclaw in Docker](/deployment/docker/#upgrading).
+
+## Troubleshooting
+
+### `Could not check for updates`
+
+**Cause:** The release feed at `releases.netclaw.dev` isn't reachable from this machine, or it didn't answer in time. A timeout reads `Timed out after <n>s fetching manifest from <url>` (or `manifest signature`).
+
+**Fix:** Check outbound HTTPS and any proxy. The daemon and the CLI both need it. The daemon's own check logs a warning (`Netclaw update check failed`) and keeps running.
+
+### `Update aborted. Stop the daemon manually, fix service state, and retry.`
+
+**Cause:** The daemon couldn't be stopped, for example because systemd reported an error, or because `netclaw daemon stop` refused with `Nothing was stopped. PID <n> is not shown to serve <home>.` The binaries weren't replaced.
+
+**Fix:** Run `systemctl --user status netclaw` or `netclaw daemon status`, stop the daemon yourself, and run the update again.
+
+### `Could not determine whether systemd owns the daemon lifecycle`
+
+**Cause:** The systemd unit is installed but your shell has no user session bus (no `XDG_RUNTIME_DIR`), so the update can't tell whether the unit would restart the daemon behind its back. It stops before touching a binary.
+
+**Fix:** Run the update from a login session, or export `XDG_RUNTIME_DIR=/run/user/$(id -u)`.
+
+### `Update installed, but daemon restart failed`
+
+**Cause:** The new binaries are in place but the daemon didn't come back up.
+
+**Fix:** Start it with `systemctl --user start netclaw` or `netclaw daemon start`, and read the newest file in `logs/` for the reason. A config the new version rejects is the usual cause.
+
+## Related pages
+
+- [Upgrade netclaw](/guides/upgrading/) - back up, upgrade, verify and roll back, with what changed in each release
+- [Back up, restore and move netclaw](/guides/backup-and-restore/) - what to copy before you update
+- [Installation](/getting-started/installation/) - the install script and its options
+- [`netclaw daemon`](/cli/daemon/) - start, stop and install the daemon
+- [systemd service](/deployment/systemd/) - how a systemd-managed daemon is restarted
+
+## Resources
+
+- [netclaw releases on GitHub](https://github.com/netclaw-dev/netclaw/releases) - release notes for every version
+- [systemctl reference](https://www.freedesktop.org/software/systemd/man/latest/systemctl.html) - `--user` service control
diff --git a/src/content/docs/cli/webhooks.md b/src/content/docs/cli/webhooks.md
index 2002683..b70ca43 100644
--- a/src/content/docs/cli/webhooks.md
+++ b/src/content/docs/cli/webhooks.md
@@ -7,11 +7,11 @@ description: "Configure inbound HTTP endpoints that trigger netclaw sessions fro
 
 This page is the flag reference. For the wire protocol, the route-file schema, and how a request is verified, see [webhook configuration](/configuration/webhooks/).
 
-Routes live as individual JSON files in `~/.netclaw/config/webhooks/`. CLI management (`list`, `set`, `validate`, etc.) doesn't need a running daemon. Actually receiving webhook requests needs three more things:
+Routes live as individual JSON files in `~/.netclaw/config/webhooks/`. `list`, `show`, and `validate` read the route files and don't need a running daemon. `set` and `delete` go through the daemon, so it must be running (`set --dry-run` doesn't). Actually receiving webhook requests needs three more things:
 
-- The daemon running — `netclaw daemon start`.
-- The global endpoint switched on. `Webhooks.Enabled` is `false` by default and every route 404s until it's on, which is **the number one reason a route that looks right never fires**. Flip it in `netclaw config` → **Inbound Webhooks**, then restart the daemon once.
-- A way in from the internet — a [non-local exposure mode](/deployment/exposure-modes/) such as Tailscale Serve or Cloudflare Tunnel. GitHub can't reach your `localhost`.
+- The daemon running: `netclaw daemon start`, or `docker restart <container>` in Docker.
+- The global endpoint switched on. `Webhooks.Enabled` is `false` by default and every route 404s until it's on, which is **the number one reason a route that looks right never fires**. Flip it in `netclaw config` → **Inbound Webhooks**. The daemon restarts itself when the config changes.
+- A way in from the internet: a [non-local exposure mode](/deployment/exposure-modes/) such as Tailscale Serve or Cloudflare Tunnel. GitHub can't reach your `localhost`.
 
 ## Usage
 
@@ -30,9 +30,9 @@ netclaw webhooks list [--json] [--all]
 | `--json` | JSON output | Off |
 | `--all` | Include disabled routes | Off |
 
-![netclaw webhooks list showing no routes configured and the route directory path](/screenshots/output/webhooks-list.png)
+![netclaw webhooks list printing a table of two enabled personal routes, deploy-notify and github-issues, both verified with hmac and delivery required](/screenshots/output/webhooks-list.png)
 
-With no routes configured, you see the storage path. Once routes exist, the table shows status, audience, verification kind, and delivery requirement per route.
+The table has one row per route with its status, audience, verification kind and delivery requirement. With no routes configured, you see the storage path instead.
 
 ## `show`
 
@@ -40,7 +40,7 @@ With no routes configured, you see the storage path. Once routes exist, the tabl
 netclaw webhooks show <route> [--json] [--show-secret]
 ```
 
-Displays full configuration for a single route. Also validates the route file — exits with code 1 if the route has schema errors.
+Displays full configuration for a single route. Also validates the route file and exits with code 1 if the route has schema errors.
 
 | Flag | Description | Default |
 |------|-------------|---------|
@@ -65,12 +65,37 @@ New routes require a prompt (choose one) and a secret (choose one):
 |------|-------------|
 | `--prompt <text>` | Prompt text injected into webhook sessions |
 | `--prompt-file <path>` | Read prompt from a file |
-| `--secret <value>` | Verification secret — **visible in shell history**; prefer `--secret-file` or `--secret-env` |
+| `--secret <value>` | Verification secret, **visible in shell history**. Prefer `--secret-file` or `--secret-env` |
 | `--secret-file <path>` | Read secret from a file |
 | `--secret-env <VAR>` | Read secret from an environment variable |
 
 All three secret flags are read **once, when the command runs**, and the resolved value is written into the route file. `--secret-env` is not a live reference: changing the variable later doesn't rotate the route's secret, and the daemon doesn't need the variable in its environment. Re-run `set` to change it.
 
+Success prints the file and endpoint:
+
+```text
+$ netclaw webhooks set github-issues --prompt "Triage this GitHub issue." --secret-env GITHUB_WEBHOOK_SECRET
+[OK] Created webhook route 'github-issues'.
+     File: /home/netclaw/.netclaw/config/webhooks/github-issues.json
+     Endpoint: /api/webhooks/github-issues
+```
+
+An existing route prints `Updated` instead of `Created`, and `--dry-run` prints `[OK] Webhook route '<name>' is valid (dry run, not saved).` without writing.
+
+#### Rotate a secret
+
+To change only the secret on an existing route, write the new value to a file and pass `--update-only`:
+
+```bash
+netclaw webhooks set github-issues --update-only --secret-file ./new-secret.txt
+```
+
+Every other field stays as it was, and the route picks up the new secret on its next request with no restart. The command fails with `does not exist (--update-only specified)` if the route isn't there. Update the secret at the provider in the same window, because the route and the sender have to agree. The [configuration page](/configuration/webhooks/#secret-rotation) explains how to overlap the two secrets so nothing fails mid-rotation.
+
+:::caution
+The sender has to sign the raw request body with the plaintext secret you give it. If it signs with a hashed or derived key, every delivery fails with a 401, whatever you put in `--secret-file`.
+:::
+
 ### Verification
 
 Three modes. Omit `--verification-kind` and you get `hmac`. The [configuration reference](/configuration/webhooks/#verification) covers the signing protocol behind each one.
@@ -81,13 +106,13 @@ Three modes. Omit `--verification-kind` and you get `hmac`. The [configuration r
 | `hmac-timestamped` | HMAC-SHA256 over `<timestamp><separator><raw body>`, plus a replay window |
 | `header-secret` | A shared secret sent verbatim in a header |
 
-The modes are independent. Netclaw never falls back from one to another, and changing an existing route's mode is a two-sided change — see [migrating a route](#migrating-a-route).
+The modes are independent. Netclaw never falls back from one to another, and changing an existing route's mode is a two-sided change. See [migrating a route](#migrating-a-route).
 
 | Flag | Description | Default |
 |------|-------------|---------|
 | `--verification-kind <kind>` | `hmac`, `hmac-timestamped`, or `header-secret` | `hmac` |
 | `--signature-header <name>` | Header containing the [HMAC](https://en.wikipedia.org/wiki/HMAC) signature | `X-Webhook-Signature` |
-| `--signature-prefix <prefix>` | Prefix on the signature value (e.g. `sha256=`) | — |
+| `--signature-prefix <prefix>` | Prefix on the signature value (e.g. `sha256=`) | - |
 | `--secret-header <name>` | Header containing the secret (header-secret mode) | `X-Webhook-Secret` |
 | `--event-header <name>` | Header with the event type name | `X-Webhook-Event` |
 | `--delivery-header <name>` | Header with the unique delivery ID (for deduplication) | `X-Webhook-Delivery` |
@@ -101,7 +126,7 @@ These four apply only to `hmac-timestamped` routes. The defaults are Stripe's fo
 | `--timestamp-field <name>` | Field in the signature header holding the Unix timestamp | `t` |
 | `--signature-field <name>` | Field holding the signature | `v1` |
 | `--signed-payload-separator <value>` | Joins the timestamp and body before signing | `.` |
-| `--signature-tolerance-seconds <n>` | Replay window in seconds, 1–3600 | `300` |
+| `--signature-tolerance-seconds <n>` | Replay window in seconds, 1-3600 | `300` |
 
 Pass any of them to a route that isn't `hmac-timestamped` and the command fails before writing anything:
 
@@ -109,11 +134,11 @@ Pass any of them to a route that isn't `hmac-timestamped` and the command fails
 [FAIL] Timestamp signature options require '--verification-kind hmac-timestamped'.
 ```
 
-`--signature-prefix` is inert on timestamped routes — the prefix is forced empty, because the signature lives in a header field rather than carrying its own prefix.
+`--signature-prefix` is inert on timestamped routes. The prefix is forced empty, because the signature lives in a header field rather than carrying its own prefix.
 
 ### Behavior
 
-`--audience` controls which [tool audience](/security/security-model/) the webhook session runs under. `public` gets the most restricted tool access, `personal` gets the most permissive.
+`--audience` controls which [tool audience](/security/security-model/) the webhook session runs under. `public` gets the most restricted tool access, `personal` gets the most permissive. Tool access follows the deployment posture's effective audience too, which can be narrower than the route's. A `personal` route under a Team or Public posture doesn't get Personal tools. A webhook session can't answer approval prompts, so a tool call that needs one is denied. [Approve a route's tools ahead of time](/guides/unattended-runs/#webhooks) if its prompt needs shell or file access.
 
 | Flag | Description | Default |
 |------|-------------|---------|
@@ -129,10 +154,10 @@ Set a notification target and the agent posts results to that Slack channel. Con
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `--notify-instructions <text>` | Instructions for agent notification behavior | — |
-| `--notify-instructions-file <path>` | Read notification instructions from a file | — |
+| `--notify-instructions <text>` | Instructions for agent notification behavior | - |
+| `--notify-instructions-file <path>` | Read notification instructions from a file | - |
 | `--delivery-required` / `--no-delivery-required` | Require notification delivery | `true` |
-| `--notification-channel <id>` | Slack channel ID for notifications | — |
+| `--notification-channel <id>` | Slack channel ID for notifications | - |
 
 ### Modifiers
 
@@ -174,7 +199,7 @@ netclaw webhooks set stripe-events \
 ```
 
 :::caution
-**Don't set `--events` on a Stripe route.** Stripe puts the event type in the JSON body, not in a header. An event allow-list on a route whose sender emits no event header rejects *every* delivery — and it does it with a 202, so Stripe's dashboard shows green while nothing runs. `--delivery-header` is the same story: no delivery-ID header means no deduplication.
+**Don't set `--events` on a Stripe route.** Stripe puts the event type in the JSON body, not in a header. An event allow-list on a route whose sender emits no event header rejects *every* delivery, and it does it with a 202, so Stripe's dashboard shows green while nothing runs. `--delivery-header` is the same story: no delivery-ID header means no deduplication.
 :::
 
 `webhooks show` fills in the effective defaults, marking the ones you didn't set:
@@ -211,7 +236,7 @@ Verification:
 ```
 
 :::note
-`show` resolves defaults for display; it doesn't write them. The route file on disk contains no timestamp keys at all until you override one. The `show --json` shape is a view with its own key names (`signatureHeader`, `deliveryIdHeader`) — the file uses `signatureHeaderName` and `deliveryIdHeaderName`. Don't copy one into the other.
+`show` resolves defaults for display. It doesn't write them. The route file on disk contains no timestamp keys at all until you override one. The `show --json` shape is a view with its own key names (`signatureHeader`, `deliveryIdHeader`). The file uses `signatureHeaderName` and `deliveryIdHeaderName`. Don't copy one into the other.
 :::
 
 #### A sender with its own field names
@@ -236,6 +261,35 @@ netclaw webhooks set custom-signed \
 netclaw webhooks set github-issues --rate-limit 10 --dry-run
 ```
 
+#### Smoke-test the signature
+
+Signature verification runs before the event filter. So a correctly signed delivery with an event type outside the route's `--events` list comes back as a `202` that says `event_filtered`, and that proves the secret and headers are right before a real event arrives. A wrong signature comes back `401`.
+
+```bash
+export SMOKE_SECRET=$(openssl rand -hex 16)
+netclaw webhooks set smoke --prompt "Triage this event." --secret-env SMOKE_SECRET --events issues
+```
+
+Sign a body with the route's secret and send it from the daemon host. The route uses the default header names here, `X-Webhook-Signature` and `X-Webhook-Event`:
+
+```bash
+body='{"zen":"Keep it logically awesome."}'
+sig=$(printf '%s' "$body" | openssl dgst -sha256 -hmac "$SMOKE_SECRET" | sed 's/^.* //')
+curl -si -X POST http://127.0.0.1:5199/api/webhooks/smoke \
+  -H 'Content-Type: application/json' \
+  -H "X-Webhook-Event: ping" \
+  -H "X-Webhook-Signature: $sig" \
+  --data "$body"
+```
+
+```text
+HTTP/1.1 202 Accepted
+...
+{"status":"ignored","reason":"event_filtered"}
+```
+
+Swap in a wrong secret and you get `HTTP/1.1 401 Unauthorized` with an empty body, and the daemon log shows `Webhook rejected route=smoke reason=verification_failed`. A sender's own "send test event" button does the same job, since most of them send an event type you haven't allow-listed.
+
 #### Create-only (fail if exists)
 
 ```bash
@@ -261,7 +315,7 @@ netclaw webhooks set github-issues \
   --signature-header X-Hub-Signature-256
 ```
 
-Between those two steps every delivery fails with a 401. Routes hot-reload per request, so the gap lasts however long you take between the two commands — no restart involved.
+Between those two steps every delivery fails with a 401. Routes hot-reload per request, so the gap lasts however long you take between the two commands, with no restart involved.
 
 ## `delete`
 
@@ -284,7 +338,7 @@ Checks the route file for syntax errors and schema violations. These are the sam
 - `verification` section is required with a non-empty `secret`
 - `maxBodyBytes` and `rateLimitPerMinute` must be >= 1
 - `events` list can't contain blank entries
-- If `notifyInstructions` is set, `notificationTarget` is required — regardless of `deliveryRequired`
+- If `notifyInstructions` is set, `notificationTarget` is required, regardless of `deliveryRequired`
 - If `notificationTarget.kind` is `Slack`, `notificationTarget.channelId` is required
 
 On `HmacTimestamped` routes only:
@@ -337,7 +391,7 @@ Three casing conventions meet in that file, and mixing them up is the easiest mi
 | Route file keys | camelCase | `"signatureHeaderName"` |
 | Route file enum values | PascalCase | `"kind": "HmacTimestamped"` |
 
-That's what `netclaw webhooks set` writes, and what [`webhook-route.v1.schema.json`](https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Configuration/Schemas/webhook-route.v1.schema.json) declares. Hand-written PascalCase keys still load — deserialization is case-insensitive — but they won't match what the CLI writes back.
+That's what `netclaw webhooks set` writes, and what [`webhook-route.v1.schema.json`](https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Configuration/Schemas/webhook-route.v1.schema.json) declares. Hand-written PascalCase keys still load, since deserialization is case-insensitive, but they won't match what the CLI writes back.
 
 The CLI's hyphenated spelling doesn't carry into the file: `"kind": "hmac-timestamped"` fails to parse. Use `"HmacTimestamped"`.
 
@@ -349,15 +403,15 @@ Route files contain secrets in plaintext. Keep `~/.netclaw/config/webhooks/` at
 
 When a POST hits `/api/webhooks/{routeName}`:
 
-1. Checks `Webhooks.Enabled`, then loads the route file (hot-reloaded per request — no restart needed after changes)
-2. Rejects bodies over `maxBodyBytes` (413) and non-JSON bodies (400) — both before any signature work
-3. Verifies the request using the route's configured mode — body HMAC, timestamped HMAC, or header secret. Timestamped routes also reject signatures outside the tolerance window.
+1. Checks `Webhooks.Enabled`, then loads the route file (hot-reloaded per request, so no restart is needed after changes)
+2. Rejects bodies over `maxBodyBytes` (413) and non-JSON bodies (400), both before any signature work
+3. Verifies the request using the route's configured mode: body HMAC, timestamped HMAC, or header secret. Timestamped routes also reject signatures outside the tolerance window.
 4. Filters by event type if the route has an allow-list, then drops deliveries it has already seen
 5. Applies the rate limit
 6. Creates a new [`Webhook` session](/architecture/sessions/) with the route's prompt injected as context
-7. If a notification target is configured, the agent posts results to that Slack channel. Without a notification target, the session still runs — output is stored in the session log
+7. If a notification target is configured, the agent posts results to that Slack channel. Without a notification target, the session still runs and its output is stored in the session log
 
-Anything that fails verification — wrong signature, stale or future timestamp, unparseable signature header — returns 401 and never reaches step 6, so no session runs. A 404 means `Webhooks.Enabled` is off, the route doesn't exist, or the route is disabled. The [full status table](/configuration/webhooks/#ingress-pipeline) lists every rejection and its code. To see delivery and rejection counts, run [`netclaw stats`](/cli/stats/).
+Anything that fails verification (wrong signature, stale or future timestamp, unparseable signature header) returns 401 and never reaches step 6, so no session runs. A 404 means `Webhooks.Enabled` is off, the route doesn't exist, or the route is disabled. The [full status table](/configuration/webhooks/#ingress-pipeline) lists every rejection and its code. To see delivery and rejection counts, run [`netclaw stats`](/cli/stats/).
 
 ## Finding your webhook URL
 
@@ -367,7 +421,7 @@ Your route's endpoint is your daemon's external hostname plus the route path:
 <your-external-hostname>/api/webhooks/<route-name>
 ```
 
-Netclaw doesn't store or report that hostname — it comes from whichever ingress you run, [Tailscale Serve](https://tailscale.com/kb/1312/serve) or [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/), and you'll find it in their dashboard. `netclaw status` shows the daemon's *local* endpoint (`http://localhost:PORT`), which external services can't reach — don't paste that into GitHub.
+Netclaw doesn't store or report that hostname. It comes from whichever ingress you run, [Tailscale Serve](https://tailscale.com/kb/1312/serve) or [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/), and you'll find it in their dashboard. `netclaw status` shows the daemon's *local* endpoint (`http://localhost:PORT`), which external services can't reach. Don't paste that into GitHub.
 
 ## Exit codes
 
@@ -378,22 +432,23 @@ Netclaw doesn't store or report that hostname — it comes from whichever ingres
 
 ## What's next
 
-After setting up a route, restart the daemon and run [`netclaw status`](/cli/status/) to confirm the webhook endpoint is healthy. Then paste the full webhook URL into your external service's webhook settings.
+After setting up a route, run [`netclaw status`](/cli/status/) to confirm the webhook endpoint is healthy. Then paste the full webhook URL into your external service's webhook settings. If the handler needs shell or file access, [approve its tools ahead of time](/guides/unattended-runs/#webhooks), because a webhook session can't answer a prompt.
 
-## Related commands
+## Related pages
 
-- [Webhook configuration](/configuration/webhooks/) — wire protocol, route-file schema, and the full ingress pipeline
-- [Exposure modes](/deployment/exposure-modes/) — making the daemon reachable so deliveries arrive at all
-- [`netclaw doctor`](/cli/doctor/) — validates inbound webhook route files
-- [`netclaw stats`](/cli/stats/) — webhook delivery counts and rejection breakdowns
-- [`netclaw config`](/cli/config/) — toggles the global `Webhooks.Enabled` endpoint
-- [`netclaw status`](/cli/status/) — live daemon health including webhook endpoint availability
+- [Run reminders, webhooks and scripts unattended](/guides/unattended-runs/#webhooks) - approve a handler's tool calls ahead of time
+- [Webhook configuration](/configuration/webhooks/) - wire protocol, route-file schema, and the full ingress pipeline
+- [Exposure modes](/deployment/exposure-modes/) - making the daemon reachable so deliveries arrive at all
+- [`netclaw doctor`](/cli/doctor/) - validates inbound webhook route files
+- [`netclaw stats`](/cli/stats/) - webhook delivery counts and rejection breakdowns
+- [`netclaw config`](/cli/config/) - toggles the global `Webhooks.Enabled` endpoint
+- [`netclaw status`](/cli/status/) - live daemon health including webhook endpoint availability
 
 ## Resources
 
-- [GitHub webhook documentation](https://docs.github.com/en/webhooks) — setting up webhooks on the GitHub side
-- [GitLab webhook documentation](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html) — GitLab's webhook configuration
-- [HMAC signature verification](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries) — how GitHub's `X-Hub-Signature-256` works
-- [Stripe webhook signatures](https://docs.stripe.com/webhooks/signature) — the `t=...,v1=...` scheme the timestamped defaults match
-- [Tailscale Serve](https://tailscale.com/kb/1312/serve) — expose your webhook endpoint without a public IP
-- [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) — alternative to Tailscale for public webhook ingress
+- [GitHub webhook documentation](https://docs.github.com/en/webhooks) - setting up webhooks on the GitHub side
+- [GitLab webhook documentation](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html) - GitLab's webhook configuration
+- [HMAC signature verification](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries) - how GitHub's `X-Hub-Signature-256` works
+- [Stripe webhook signatures](https://docs.stripe.com/webhooks/signature) - the `t=...,v1=...` scheme the timestamped defaults match
+- [Tailscale Serve](https://tailscale.com/kb/1312/serve) - expose your webhook endpoint without a public IP
+- [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) - alternative to Tailscale for public webhook ingress
diff --git a/src/content/docs/getting-started/first-assistant.md b/src/content/docs/getting-started/first-assistant.md
new file mode 100644
index 0000000..6603cb8
--- /dev/null
+++ b/src/content/docs/getting-started/first-assistant.md
@@ -0,0 +1,560 @@
+---
+title: "Build your first assistant"
+description: "Go from a fresh machine to an assistant with an identity, a tool it can use, a memory and a reminder that reports back on its own."
+---
+
+By the end of this tutorial you'll have a netclaw assistant that knows who you are, runs commands with your permission, remembers what you tell it across sessions, and checks a website for you on a schedule without being asked. We build it on a Linux box with a single user and no chat account, because that's the shortest path to something real. Connecting Slack, Discord or Mattermost comes last and is optional.
+
+Plan on 30 to 45 minutes. Most of that is waiting for the model, especially a local one. This is the long version. If you only want netclaw running, the [quickstart](/getting-started/quickstart/) takes five minutes, and [Your first conversation](/getting-started/first-conversation/) explains the keys and prompts in the chat without the tutorial around them.
+
+Every output block below comes from a real run. Yours will differ in names, timings and the exact words your model uses.
+
+## Before you begin
+
+| You need | Notes |
+|---|---|
+| A 64-bit Linux machine, an Apple Silicon Mac or Windows x64 | The commands below assume Linux or macOS. See [Installation](/getting-started/installation/) for Windows. |
+| `curl`, `libicu` and `tzdata` on Linux | Minimal images and containers often lack all three. See the callout in step 1. |
+| About 1 GB of free memory | The daemon idles around 480 MB with local memory on. Plan for up to 800 MB. |
+| An LLM provider | A hosted API key, or a server you run such as Ollama, llama.cpp or vLLM. |
+| Outbound access to `releases.netclaw.dev` and `huggingface.co` | The second is for two small memory models on first start. |
+
+## 1. Install and set up
+
+### Install netclaw
+
+If you're on a bare Ubuntu or Debian image, install the three prerequisites first. On a normal desktop or cloud VM you can skip this.
+
+```bash
+sudo apt-get update
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -y curl ca-certificates libicu74 tzdata
+```
+
+`DEBIAN_FRONTEND=noninteractive` stops `tzdata` from stopping to ask for a region. `libicu74` is the Ubuntu 24.04 name. Use your distro's ICU package elsewhere. Without it, the daemon crashes at startup with `Couldn't find a valid ICU package`. Without `tzdata`, `netclaw init` rejects every timezone except `UTC`, and a reminder that names a timezone fails to schedule with `Unknown time zone`.
+
+Run the installer:
+
+```bash
+curl -sSL https://releases.netclaw.dev/install.sh | bash
+```
+
+```text
+Netclaw installer
+  Platform: linux-x64
+  Install dir: /home/sam/.netclaw/bin
+  Channel: stable
+
+  Resolved stable channel from https://releases.netclaw.dev/latest
+  Version: 0.28.2
+
+  Downloading netclaw...
+######################################################################## 100.0%
+  Verifying checksum...
+  Extracting...
+  Installed netclaw to /home/sam/.netclaw/bin/
+  Downloading netclawd...
+######################################################################## 100.0%
+  Verifying checksum...
+  Extracting...
+  Installed netclawd to /home/sam/.netclaw/bin/
+
+Setting up shell integration...
+  Modified '/home/sam/.bashrc' to add netclaw to PATH.
+
+Installation complete! Netclaw will be available in new terminal sessions.
+To use Netclaw in this terminal now, run:
+  . '/home/sam/.netclaw/env'
+Get started:
+  netclaw init             # First-run setup wizard
+  netclaw doctor           # Verify configuration
+  netclaw daemon install   # Enable auto-start on boot (systemd)
+```
+
+The script put the CLI (`netclaw`) and the daemon (`netclawd`) in `~/.netclaw/bin` and added a line to your shell profile. That line only takes effect in new terminals, so load it into this one:
+
+```bash
+. ~/.netclaw/env
+netclaw --version
+```
+
+```text
+netclaw 0.28.2 (commit 7419d84, built 2026-10-29T00:09:05Z)
+```
+
+If you see `netclaw: command not found`, you skipped the first line.
+
+### Run the setup wizard
+
+```bash
+netclaw init
+```
+
+Here's what to answer on each screen. Press a number key to choose from a list, and the choice is taken at once.
+
+| Screen | What to do |
+|---|---|
+| Provider list | Pick your provider. For llama.cpp or vLLM pick **OpenAI-compatible**. |
+| Endpoint (self-hosted only) | Enter the server root, for example `http://llm.example.internal:8080`. |
+| API key | Paste the key. For a keyless local server, press Enter to skip. |
+| Model | Pick your model from the list. |
+| Agent name | Press Enter to keep `Netclaw`, or rename it. |
+| Communication style | Pick one of four. `1. Concise & casual` is a good default. |
+| Your name, timezone | Your first name, and an IANA zone such as `America/Chicago`. |
+| Security posture | `1. Personal`. It's one person on this machine with shell access behind approval prompts. |
+
+Three things trip people up here:
+
+- The endpoint field is pre-filled with `http://localhost:11434` and the cursor sits at the end, so what you type lands after the default. Press Backspace until the default is gone. The timezone field behaves the same way with `UTC`.
+- The endpoint works with or without `/v1`.
+- The step counter says "of 5" until you choose a posture. Personal ends at `Step 4 of 4`.
+
+![Netclaw Setup, Step 1 of 5, LLM Provider, listing eight providers with OpenAI-compatible as number 6](/screenshots/output/init-01-provider-list.png)
+
+OpenAI-compatible is entry 6, the one for llama.cpp and vLLM.
+
+![The OpenAI-compatible endpoint step with http://localhost:11434 pre-filled](/screenshots/output/init-01-endpoint.png)
+
+The field starts with the Ollama default filled in and the cursor at the end of it. Clear it and type your server's address, with or without `/v1`.
+
+The last screen is the health check. It writes your config, starts the daemon and checks the provider:
+
+```text
+Step 4 of 4: Health Check
+✓  LLM provider configured (OpenAI-compatible (llama.cpp / vLLM / DwarfStar ds4))
+✓  Model selected (<your model>)
+✓  Memory backend (SQLite)
+✓  Configuration written
+```
+
+![Netclaw Setup, Step 4 of 4, Health Check, with four green check lines and an Applying configuration spinner](/screenshots/output/init-05-health-check.png)
+
+The capture was taken against an OpenAI-compatible endpoint, so the first line names that. Yours names your provider.
+
+When it ends clean, `init` opens the chat for you. Leave it open for step 2.
+
+:::note
+If a check ends in `Failed to start daemon: process exited with code 134`, the ICU library is missing. Install it, run `netclaw daemon start`, then `netclaw chat --onboarding`. That opens the same conversation `init` would have started. Choosing **Redo identity setup** in `netclaw init` later launches it too.
+:::
+
+### Verify it works
+
+Open a second terminal, or press `Ctrl+Q` to leave the chat and come back to it later.
+
+```bash
+netclaw status
+```
+
+```text
+overall: healthy
+version: 0.28.2 (commit 7419d84, built 2026-10-29T00:10:12Z)
+daemon: PID 3644, uptime 0m 24s, endpoint http://127.0.0.1:5199
+persistence: Sqlite
+memory: sqlite (healthy)
+telemetry: disabled
+model: <your model> (provider: openai-compatible, context: 131,072 tokens)
+  input: Text, Image
+  output: Text
+connectors:
+- discord: disabled (disabled)
+- mattermost: disabled (disabled)
+- slack: disabled (disabled)
+- tui: healthy (enabled)
+
+update: up-to-date (v0.28.2)
+```
+
+The daemon also downloaded two memory models from huggingface.co on its first start. About 129 MB, and a few seconds on a fast link:
+
+```bash
+ls ~/.netclaw/models
+```
+
+```text
+ms-marco-minilm-l-6-v2  snowflake-arctic-embed-m-int8
+```
+
+Run `netclaw doctor` for a fuller check. A fresh install usually shows a `WARN` for a missing `secrets.json`, which is expected when your provider needs no API key.
+
+## 2. Give your assistant an identity
+
+If `init` opened the chat, your assistant has already said hello. If it didn't, run `netclaw chat --onboarding` and the assistant opens the conversation for you. Either way, the conversation goes the same way.
+
+![Netclaw chat TUI right after init, with the assistant greeting Sam and asking what the deployment is for](/screenshots/output/chat-first-greeting.png)
+
+The assistant opens the conversation itself and asks the question the next step answers.
+
+```text
+Netclaw: Hey Sam! I'm Netclaw, your all-purpose assistant. I can dig through code, research stuff online, automate repetitive tasks, manage files, set reminders ... 
+Now let's figure out what you actually need from me.
+What would you primarily like to use me for?
+```
+
+The first reply can take 30 seconds or more on a local model, because every turn carries your identity files and the tool list. The status bar shows `Generating...` meanwhile. You can't cancel a running turn from the TUI today, so wait it out.
+
+Tell it what you want in a couple of sentences. We'll use a homelab:
+
+```text
+I run a small homelab: three Debian boxes, Docker Compose, a Proxmox host. I want you to
+help me keep it healthy: check disk space, summarize logs, and remind me about backups.
+Keep answers short.
+```
+
+It reads its current identity files, proposes a playbook (mission, recurring workflows, delegation, quality checks) and asks a few questions. Answer them, then tell it to write the playbook down:
+
+```text
+Start with just this machine, no SSH to the others yet. The playbook looks right, go ahead
+and write it.
+```
+
+It writes two files and says the playbook applies from your next message. Neither write triggers an approval prompt:
+
+```text
+  ✓ file_write → Successfully wrote 534 bytes to /home/sam/.netclaw/identity/SOUL.md (0.0s)
+  ✓ file_write → Successfully wrote 2608 bytes to /home/sam/.netclaw/identity/AGENTS.md (0.0s)
+Netclaw: Done. Both files are updated:
+- SOUL.md: your name, timezone, homelab context, and "short answers" preference
+- AGENTS.md: mission, three recurring workflows, skill selection, delegation rules, and quality gates
+The new playbook kicks in on your next message.
+```
+
+### Verify it works
+
+Read what it wrote. These files shape every future session, so fix anything wrong now.
+
+```bash
+cat ~/.netclaw/identity/SOUL.md
+```
+
+```text
+# You are Netclaw
+
+When asked your name, who you are, or to introduce yourself, state that you are Netclaw.
+
+## Communication Style
+Be concise and casual. Keep responses short and conversational. Lead with the status; details only when asked.
+
+## User
+- Name: Sam
+- Timezone: America/Chicago
+- Runs a small homelab: three Debian boxes, Docker Compose, one Proxmox host
+- Primary use of this deployment: keeping the homelab healthy (disk checks, log summaries, backup reminders)
+- Prefers short answers; no raw log dumps. Summarize
+```
+
+`~/.netclaw/identity/AGENTS.md` holds the mission and workflows. The model may add detail you didn't ask for, so read it too. See [context structure](/architecture/context-structure/) for how both files are used.
+
+## 3. Let it use a tool
+
+Back in the chat, ask a read-only question:
+
+```text
+How much free disk space does this machine have?
+```
+
+```text
+  ✓ shell_execute → Exit code: 0 Filesystem Size Used Avail Use% Mounted on overlay 3.6T 2.5T 931... (0.2s)
+Netclaw: All clear, 931 GB free on / (74% used). Under your 80% threshold.
+```
+
+It ran `df -h` with no prompt. netclaw keeps a reviewed list of read-only commands that run without asking. Now ask for something that isn't on that list:
+
+```text
+Use curl to download https://example.com and save it as ~/example.html, then tell me how many bytes it is.
+```
+
+This is your first approval prompt:
+
+```text
+System: Approval required for shell_execute
+  curl -sL https://example.com -o ~/example.html && stat -c %s ~/example.html
+  Patterns: curl
+  Options: Once, This chat, Always here, Always anywhere, Deny
+```
+
+![Netclaw chat TUI with an approval prompt for a curl download, listing Once, This chat, Always here, Always anywhere and Deny](/screenshots/output/chat-approval-prompt.png)
+
+Inside a Git repository the prompt adds **This repository** as a sixth option. Here there's no repository, so it has five.
+
+Press `1` for **Once**. A number key takes effect immediately with no Enter. Or move the highlight with the arrow keys and press `Enter`, which confirms the highlighted option (**Once** is highlighted when the prompt opens). Prompts never time out, so you can press `Ctrl+O` to see the full command first. **Once** runs this call and saves nothing. **Deny** doesn't run it, and nothing is banned, but the assistant stops, says what it wanted to do and asks how to continue.
+
+Read the `Patterns:` line before any "Always" answer. `curl` there means the grant would cover every `curl` command, and **Always here** saves the folder the command's paths point at ([what it covers](/security/approvals/#what-always-here-covers)). [Your first conversation](/getting-started/first-conversation/#4-answer-your-first-approval-prompt) walks through the prompt, and [How tool approvals work](/security/approvals/#what-each-answer-does) lists every answer.
+
+```text
+Netclaw: Done. ~/example.html is 577 bytes.
+```
+
+### Verify it works
+
+```bash
+ls -l ~/example.html
+```
+
+You should see a file of the size the assistant reported. Because you chose Once, nothing was saved:
+
+```bash
+netclaw approvals list
+```
+
+```text
+No persistent approvals.
+```
+
+## 4. Teach it something and see it come back
+
+Still in the chat:
+
+```text
+Remember this: my Proxmox host is called pve1 and nightly backups go to a NAS called vault, mounted at /mnt/vault.
+```
+
+```text
+  ✓ search_tools → Found 5 tool(s): ... (0.0s)
+  ✓ load_tool → store_memory (0.2s)
+  ✓ store_memory → Memory save confirmed: "Sam's homelab infrastructure" (checkpoint: cp-a50be59... (0.0s)
+Netclaw: Saved. I'll remember pve1 and the vault NAS at /mnt/vault from now on.
+```
+
+Press `Ctrl+Q` to quit. Quitting leaves the session in the daemon. Start a fresh one:
+
+```bash
+netclaw chat
+```
+
+```text
+Where do my nightly backups go, and what is my Proxmox host called?
+```
+
+```text
+Netclaw: - Nightly backups: NAS vault, mounted at /mnt/vault
+- Proxmox host: pve1
+```
+
+You didn't repeat yourself, and the assistant made no visible tool call. Recall injects relevant memories before the model answers. This relies on the local embedding models. With `Memory.Embeddings.Enabled` set to `false`, recall falls back to keyword search. See [memory model](/architecture/memory-model/).
+
+### Verify it works
+
+```bash
+netclaw sessions --once
+```
+
+```text
+signalr/98f4b55fee1b4eefab96d4a28af39262  Homelab Backup Destination and Proxmox Host  [active]  turns=1  last=2026-10-07 16:01
+signalr/0c27293335d34bc080996e396058e447  First Conversation Setup with Sam  [active]  turns=8  last=2026-10-07 15:56
+```
+
+Two sessions, and the second one knew what the first one was told. You can resume any of them with `netclaw chat --resume <id>`.
+
+## 5. Schedule a reminder that runs a tool
+
+A reminder starts its own session at the scheduled time and works through a prompt. Nobody is at the keyboard, so nobody can answer an approval prompt. A call that would prompt is denied unless a saved "Always" grant already covers it.
+
+:::caution
+A reminder whose tool call gets denied doesn't run its command. The run is recorded as `denied`, and `netclaw reminder status` shows the reason. A denied one-shot ends as failed and deletes itself, and `reminder status` is where its prompt and the denial stay for 12 days. With no delivery target, that status is the only sign, so approve the commands first, as shown below.
+:::
+
+The order matters: create, approve by running it once where you can answer, then watch one fire on its own.
+
+### Create the reminder
+
+Ask the assistant. In the chat, name the ID so the later steps match:
+
+```text
+Every day at 8am Chicago time, use curl to check that https://example.com is up and report the status line in one sentence. Call the reminder daily-uptime-check.
+```
+
+Use your own timezone. The assistant usually tests the `curl` command first, so expect an approval prompt or two. Answer **Once**. Creating the reminder itself (`set_reminder`) doesn't prompt:
+
+```text
+System: Approval required for shell_execute
+  curl -sS -o /dev/null -w "%{http_code}\n" --max-time 15 https://example.com
+  Patterns: curl
+  Options: Once, This chat, Always here, Always anywhere, Deny
+  ✓ set_reminder → Reminder 'Daily uptime check: example.com' scheduled. Runs daily at 08:00 Ame... (0.0s)
+Netclaw: Done - reminder `daily-uptime-check` is scheduled daily at 08:00 America/Chicago (DST-aware).
+```
+
+The wording of the reply, the exact `curl` flags and the title differ from run to run. The ID, the schedule and the timezone are what you check:
+
+```bash
+netclaw reminder list
+```
+
+```text
+id                  status   failures  schedule                             next_fire             title
+-------------------------------------------------------------------------------------------------------
+daily-uptime-check  enabled  0         runs daily at 08:00 America/Chicago  2026-10-08 13:00:00Z  Daily uptime check: example.com
+```
+
+The assistant may also want to run `netclaw approvals trust-verb curl` so the scheduled run can use `curl`. Read that prompt before you answer: approving it, even with **Once**, saves a standing grant for every `curl` command. That's the same decision as **Always anywhere** in the next step. Deny it if you'd rather make that call there.
+
+:::note
+How well this works depends on the model. In five fresh chats against a hosted DeepSeek V4.1 Flash model, all five created the reminder with the right ID, schedule and timezone, and three of them also asked to run `trust-verb curl`. In earlier testing a Qwen3.8 model created it only three times in five, and the other two chats sat on "Generating..." with no error. Check `netclaw reminder list` and fall back to the shell if the reminder isn't there. `netclaw chat -p` can't do this: a one-shot run is headless, and the assistant gets `current_session delivery requires a channel with a gateway`.
+:::
+
+#### From the shell instead
+
+Use the CLI when the assistant doesn't create it, or in a script:
+
+```bash
+netclaw reminder create daily-uptime-check cron "CRON_TZ=America/Chicago 0 8 * * *" \
+  "Use curl -sSfI https://example.com | head -1 to get the HTTP status line of https://example.com and report it in one short sentence." \
+  --name "Daily uptime check: example.com"
+```
+
+```text
+Reminder 'Daily uptime check: example.com' scheduled. Runs daily at 08:00 America/Chicago. Next execution: Thursday, October 8 at 1:00 PM Coordinated Universal Time (2026-10-08 13:00:00Z). Delivery: none (silent execution). ID: daily-uptime-check
+```
+
+Running it again with the same ID replaces the reminder. A cron expression is UTC unless it starts with `CRON_TZ=`. If you're on a minimal image without `tzdata`, this fails with `Invalid CRON_TZ prefix. Unknown time zone 'America/Chicago'`. Install `tzdata` and run it again. `netclaw reminder list` shows it as above. Add `--json` for the same data as a JSON array.
+
+### Approve what it needs, before it runs alone
+
+Run the reminder once, here, where you can answer prompts. `netclaw reminder run` opens a chat that loads the reminder and carries it out. Inside a chat you'd type `/run-reminder daily-uptime-check` instead.
+
+```bash
+netclaw reminder run daily-uptime-check
+```
+
+The steps are real. A reminder that deletes files really deletes them, and one that posts to a channel really posts. This one fetches a web page, so it's safe. Unless the assistant already saved a `curl` grant for you, this is where the `curl` prompt appears again. This time choose **Always anywhere**, because only an "Always" answer carries over to the scheduled run. Once and This chat don't.
+
+```text
+System: Approval required for shell_execute
+  curl -sSfI https://example.com | head -1
+  Patterns: curl
+  Options: Once, This chat, Always anywhere, Deny
+```
+
+```text
+Netclaw: Uptime check passed. example.com is up (HTTP 200, ~70ms).
+```
+
+The command in the prompt is whatever your model chose to run, and any `curl` command matches the saved pattern. There's no **Always here** in this list because the command names no path ([why you sometimes see fewer options](/security/approvals/#why-you-sometimes-see-fewer-options)). Press `Ctrl+Q` to leave, then check that the grant exists:
+
+```bash
+netclaw approvals list
+```
+
+```text
+personal / shell_execute
+  Bash token-prefix "curl" anywhere   added just now
+```
+
+A test run isn't recorded in the reminder's history and doesn't change its schedule. It works only in a chat at the reminder's own audience. On a Personal host, the CLI chat is Personal. Some models describe the reminder instead of running it. If yours does, tell it `Yes, run it now for real, step by step.`
+
+### Watch one fire
+
+Eight in the morning is a long wait, so create a one-time reminder that fires in three minutes. The grant you just saved covers it.
+
+```bash
+netclaw reminder create check-example once 3m \
+  "Use curl to fetch the HTTP status line of https://example.com and report it in one short sentence." \
+  --name "Check example.com once"
+```
+
+```text
+Reminder 'Check example.com once' scheduled. Runs once. Next execution: Wednesday, October 7 at 6:11 PM Coordinated Universal Time (2026-10-07 18:11:36Z). The reminder deletes itself after it runs or after you cancel it. Delivery: none (silent execution). ID: check-example
+```
+
+With no delivery target, nothing appears in a chat. The reminder runs in a session of its own. Wait the three minutes, then list sessions:
+
+```bash
+netclaw sessions --once
+```
+
+```text
+reminder/check-example/1791396696026  (untitled)  [active]  turns=1  last=2026-10-07 18:12
+signalr/4074b0a5cbd84a198a86ba4df5337a0a  Daily Uptime Check for Example Com  [active]  turns=1  last=2026-10-07 18:08
+```
+
+`turns=0` means it hasn't finished yet, so wait a few seconds more. Open the reminder's session to read what the run did:
+
+```bash
+netclaw chat --resume reminder/check-example/1791396696026
+```
+
+```text
+System: Session started. Title: Checking Example Com HTTP Status
+--- Previous conversation ---
+You: Use curl to fetch the HTTP status line of https://example.com and report it in one short sentence.
+Netclaw: https://example.com is up, HTTP 200 OK.
+--- End of history ---
+```
+
+A finished one-shot deletes its own definition, so `netclaw reminder list` prints `No reminders.` A small end record and the run history stay for 12 days. Read them with `netclaw reminder status`:
+
+```bash
+netclaw reminder status check-example
+```
+
+```text
+Reminder:            check-example
+Enabled:             False
+Executing now:       False
+Next fire:           not scheduled
+Consecutive fails:   0
+Skipped occurrences: 0
+Ended:               completed at 2026-10-29 15:33:21Z (history stays until 2026-11-10 15:33:21Z)
+Occurrence status:   Delivered
+Occurrence attempts: 0
+Recent history (newest first):
+  2026-10-29 15:33:06Z  ok
+```
+
+That session is also where you'd look after a reminder fails. To have results land in Slack, Discord or Mattermost, add `--delivery channel --transport <name> --address <target>` once a channel is set up. See [`netclaw reminder`](/cli/reminder/#create).
+
+### Verify it works
+
+```bash
+netclaw reminder status daily-uptime-check
+```
+
+```text
+Reminder:            daily-uptime-check
+Enabled:             True
+Executing now:       False
+Next fire:           Thursday, October 8 at 1:00 PM Coordinated Universal Time (2026-10-08 13:00:00Z)
+Consecutive fails:   0
+Skipped occurrences: 0
+Terminal outcome:    none
+Recent history:      none
+```
+
+The daily reminder fires tomorrow at 8am, so its history is empty for now. `Skipped occurrences` should stay at `0`.
+
+## 6. Connect it to where you work (optional)
+
+Everything so far ran in the terminal. To reach the assistant from chat, add a channel in [`netclaw config`](/cli/config/) under **Channels**:
+
+```bash
+netclaw config
+```
+
+| Channel | Guide |
+|---|---|
+| Slack | [Slack setup](/channels/slack/) |
+| Discord | [Discord setup](/channels/discord/) |
+| Mattermost | [Mattermost setup](/channels/mattermost/), or [run netclaw with Mattermost on Docker Compose](/guides/mattermost-docker-compose/) to try it on one machine |
+
+The same approval rules apply in a channel, and only the person who started the request can answer its prompt. Channels also set an audience, Personal, Team or Public, that decides which tools are available, and the reminders you built here belong to Personal. See the [security model](/security/security-model/) before you open a channel to other people.
+
+## What's next
+
+- [Reduce or turn off approval prompts](/guides/reduce-approval-prompts/): tune the prompts you've now seen
+- [Run reminders, webhooks and scripts unattended](/guides/unattended-runs/): what unattended runs can and can't do
+- [`netclaw mcp`](/cli/mcp-tools/): give the assistant more tools through MCP servers
+- [Skills](/skills/overview/): teach it repeatable procedures
+- [Back up, restore and move netclaw](/guides/backup-and-restore/): protect the identity files, memory and secrets you just created
+
+## Related pages
+
+- [Quickstart](/getting-started/quickstart/): the five-minute version of steps 1 and 2
+- [Your first conversation](/getting-started/first-conversation/): keys, slash commands and the approval prompt in detail
+- [Installation](/getting-started/installation/): every platform, update and uninstall
+- [Reminders](/configuration/reminders/): schedule types, delivery modes and failure handling
+- [`netclaw reminder`](/cli/reminder/): create, test and inspect reminders from the shell
+
+## Resources
+
+- [Ollama](https://ollama.com/): run a local model in minutes if you don't have a provider yet
+- [Crontab guru](https://crontab.guru/): decode the cron expressions reminders use
+- [IANA time zone database](https://www.iana.org/time-zones): valid timezone names for `init` and reminders
diff --git a/src/content/docs/getting-started/first-conversation.md b/src/content/docs/getting-started/first-conversation.md
index 4663bfd..965b255 100644
--- a/src/content/docs/getting-started/first-conversation.md
+++ b/src/content/docs/getting-started/first-conversation.md
@@ -1,14 +1,14 @@
 ---
-title: "Your First Conversation"
-description: "Start your first chat session with Netclaw."
+title: "Your first conversation"
+description: "What to try in your first chat session, how to answer the first approval prompt, and the keys and slash commands that matter."
 ---
 
-You've installed Netclaw, run `netclaw init`, and the daemon is up. Open a chat.
+Your first session is where your assistant learns who you are, and where you find out what a tool call and an approval prompt look like. This page explains what you're looking at: the opening conversation, a tool call, the approval prompt, and the keys that matter. If you haven't installed yet, the [quickstart](/getting-started/quickstart/) is the five-minute path. If you'd rather build something start to finish, including memory and a scheduled reminder, follow [Build your first assistant](/getting-started/first-assistant/).
 
-## Prerequisites
+## Before you begin
 
-- Netclaw [installed](/getting-started/installation/) with a running daemon
-- At least one [provider configured](/cli/provider/) (done during `netclaw init`)
+- netclaw is [installed](/getting-started/installation/) and `netclaw init` finished. `netclaw status` should say `overall: healthy`.
+- You have a provider and model configured. `init` does that, and [`netclaw provider`](/cli/provider/) adds more later.
 
 ## 1. Open a chat
 
@@ -16,81 +16,161 @@ You've installed Netclaw, run `netclaw init`, and the daemon is up. Open a chat.
 netclaw chat
 ```
 
-<!-- TODO(screenshots): chat-session-start.png — first-run chat TUI; needs a live model. Tracked in netclaw-dev/netclaw-website#71 -->
+If `init` just finished cleanly, you're already in a chat and your assistant has started talking. Otherwise you get an empty chat with a message box and a key hint line:
 
-The TUI launches into a new session. The status bar shows your active model and "Generating..." because Netclaw is already composing its opening message.
+```text
+[Enter] Send  [Ctrl+Enter] Newline  [PgUp/PgDn/Wheel] Scroll  [Ctrl+Q] Quit  |  Ready  |  <your model>
+```
+
+The session doesn't exist until you send your first message. At that point `System: Session started. New session.` appears. An empty chat you quit without typing leaves nothing behind.
+
+Only the `init` handoff starts the greeting on its own. To get the same opening conversation from a plain terminal, run `netclaw chat --onboarding` instead. Or run `netclaw chat` and say what you want to use it for, and the conversation begins from your message.
+
+## 2. Tell it what you want
 
-## 2. Meet your agent
+The opening conversation does three things. The assistant introduces itself, asks what you'll use it for and what good work looks like, and then proposes a short playbook. Answer in plain language. When the proposal looks right, tell it to go ahead and write it.
 
-Netclaw introduces itself without any prompt from you. It reads your identity file (created during `netclaw init`) and greets you by name.
+![Netclaw chat TUI right after init, with the assistant greeting Sam and asking what the deployment is for](/screenshots/output/chat-first-greeting.png)
 
-![Netclaw greeting and profile check](/screenshots/output/chat-intro-greeting.png)
+The greeting arrives before you type anything, and the status bar already shows `Ready` and the model name.
 
-The `file_read` tool call in the output means Netclaw pulled your identity from `~/.netclaw/identity/SOUL.md` to check what it already knows about you. Then it asks what you want to use it for.
+After you confirm, it writes two files and tells you the new playbook applies from your next message:
 
-## 3. Teach it about you
+| File | Holds |
+|---|---|
+| `~/.netclaw/identity/SOUL.md` | Who it is and who you are: name, style, timezone, preferences |
+| `~/.netclaw/identity/AGENTS.md` | What this deployment is for: mission, recurring workflows, delegation, quality checks |
 
-Tell Netclaw about your work. It asks follow-up questions to build your profile.
+Neither write triggers an approval prompt. They're plain Markdown that every future session loads, so read them and fix anything the assistant got wrong. See [context structure](/architecture/context-structure/).
 
-![Multi-turn profile conversation](/screenshots/output/chat-profile-questions.png)
+Each model call sends your identity files, tool list and history, so the first turn is already about 11,000 input tokens. A local model can take 30 seconds or more to start replying. The status bar shows `Generating...` and then token counts such as `in=11345`. That's prompt processing, not a hang.
 
-In this example, the conversation went:
+## 3. Ask for something that needs a tool
 
-1. "I need help with administrative tasks for NetclawCorp."
-2. Netclaw asks about team size and role
-3. "5 people" / "COO. We use Google Workspace, Slack, Xero, and Invoicely."
+Tools show inline as they run. Start with a read-only question:
 
-Give it as much context as you want. Your role, team, tools, workflows. It remembers everything across sessions.
+```text
+How much free disk space does this machine have?
+```
+
+The assistant runs `df -h` through `shell_execute` and answers. You won't see an approval prompt, because netclaw ships a reviewed list of read-only commands that run without one.
 
-## 4. Profile saved
+Now ask for something that changes a file:
 
-Netclaw writes your profile to `SOUL.md`, the identity file that persists across sessions.
+```text
+Use curl to download https://example.com and save it as ~/example.html, then tell me how many bytes it is.
+```
 
-![Profile written to SOUL.md](/screenshots/output/chat-profile-update-soul.md.png)
+## 4. Answer your first approval prompt
 
-The `file_write` line confirms your profile landed at `~/.netclaw/identity/SOUL.md`. Every future session loads this file automatically, so you never re-introduce yourself.
+This one does prompt, because `curl` isn't on the reviewed list:
 
-`SOUL.md` grows over time. As you work with Netclaw, it updates the file with new preferences and context it picks up from your conversations.
+```text
+System: Approval required for shell_execute
+  curl -sL https://example.com -o ~/example.html && stat -c %s ~/example.html
+  Patterns: curl
+  Options: Once, This chat, Always here, Always anywhere, Deny
+```
+
+![Netclaw chat TUI with an approval prompt for a curl download, listing Once, This chat, Always here, Always anywhere and Deny](/screenshots/output/chat-approval-prompt.png)
+
+The same prompt as it looks in the TUI. Your download doesn't run inside a repository, so you get five options. Inside a Git repository there's a sixth, **This repository**.
+
+The input box turns into a list. Press a number key to pick an option and it takes effect immediately, with no Enter. Or use the arrow keys and Enter, which confirms the highlighted option (Once, until you move). The assistant carries on once you answer. **Once** runs this one call and saves nothing, **Deny** skips it and bans nothing, though the assistant then stops, says what it wanted to do and asks how to continue, and the "Always" options save a grant.
+
+The `Patterns:` line shows what an "Always" answer would save. Here that's the prefix `curl`, so it would cover any `curl` command. **Always here** saves the folder the command's paths point at, not the one you're standing in ([what it covers](/security/approvals/#what-always-here-covers)). Pick **Once** while you're learning. Prompts don't expire, so you can read the command, press `Ctrl+O` to expand it in full, and take your time. Only the person who started the request can answer.
+
+You can see and undo saved grants any time:
+
+```bash
+netclaw approvals list
+netclaw approvals revoke 'Bash token-prefix "curl" anywhere'
+```
 
-## 5. Do something real
+The full list of answers, why some prompts offer fewer of them, and how the gates work are in [how tool approvals work](/security/approvals/). If you're tired of the prompts, see [reduce or turn off approval prompts](/guides/reduce-approval-prompts/).
 
-Profile bootstrapping done. Try a tool-assisted task.
+## 5. Teach it something
 
-### Ask a live question
+Tell it a fact and ask it to remember it:
 
+```text
+Remember this: my Proxmox host is called pve1 and nightly backups go to a NAS called vault, mounted at /mnt/vault.
 ```
-what is the current temperature in Chicago?
+
+The assistant finds its memory tool, saves the note and confirms. Quit, start a new chat and ask for it back, and the answer comes from memory. [Build your first assistant](/getting-started/first-assistant/#4-teach-it-something-and-see-it-come-back) walks through that round trip, and the [memory model](/architecture/memory-model/) explains how recall works.
+
+## Keys that matter
+
+| Key | What it does |
+|---|---|
+| `Enter` | Send the message |
+| `Ctrl+Enter` | Insert a newline |
+| `PgUp` / `PgDn`, mouse wheel | Scroll the history |
+| `Ctrl+Q` | Quit the TUI. It's the only key that quits. It waits up to two seconds for the daemon to confirm your last message, and doesn't wait for the model. |
+| `Esc` | With an approval prompt open, denies it. While the assistant is generating, shows `Cancel generation is not supported yet.` Otherwise does nothing. |
+| `Ctrl+O` | Expand or collapse the full body of a pending approval prompt |
+| `1` to `5`, `Up` / `Down`, `Enter` | Choose an option in an approval prompt |
+
+A running turn can't be cancelled from the TUI today. If a reply is heading the wrong way, wait for it to finish and correct it in the next message.
+
+## Slash commands
+
+Type `/` followed by a skill name to run that skill directly. Type an unknown command and netclaw lists what's available:
+
+```text
+Netclaw: Unknown command: /help
+
+Available commands:
+  /agent-coordination
+  /netclaw-memory
+  /netclaw-operations
+  /netclaw-projects
+  /run-reminder <reminder id>
+  /search-citation
+  /skill-authoring
+  /subagent-authoring
+  /web-content-retrieval
 ```
 
-![Web fetch tool in action](/screenshots/output/single-shot-chat-web-fetch.png)
+There are no built-in `/new`, `/clear` or `/model` commands. See [slash commands](/reference/slash-commands/) for what each one does.
+
+## Come back later
 
-Netclaw calls `web_fetch`, pulls weather data, and returns a plain-language answer. Tool calls appear inline so you can see exactly what happened behind the scenes.
+`Ctrl+Q` closes the TUI and leaves the session alive in the daemon. A reply that was still generating keeps going there. Pick it up from the session list, or by ID:
 
-### Headless mode
+```bash
+netclaw sessions                       # TUI: Enter resumes, N starts a new chat
+netclaw sessions --once                # plain list, then exit
+netclaw chat --resume signalr/0c27293335d34bc080996e396058e447
+```
 
-Skip the TUI for quick one-offs. The `-p` flag sends a single prompt and exits:
+History replays when you resume. Sessions also survive a daemon restart, and they come back marked `[inactive]`.
+
+## One-shot prompts
+
+`netclaw chat -p` sends one prompt and prints the reply:
 
 ```bash
-netclaw chat -p "can you tell me if there's an MCP server for Xero?"
+netclaw chat -p "What's the status line of https://example.com?"
 ```
 
-![Headless mode with tool call output](/screenshots/output/single-shot-cli-execution.png)
+Nobody is there to answer an approval prompt in headless mode, so a call that would prompt is denied:
 
-Tool calls and results stream to stdout, then the process exits. Good for scripting and quick terminal lookups.
+```text
+Tool access denied: shell_execute needs approval, and nobody can answer a prompt in an unattended run. Save an "Always" grant for this call in a chat with the same audience ...
+```
 
-## Where to go from here
+If the reply starts a sub-agent, `-p` stays open and prints `[subagent:waiting] N open: <run ids>` until the child's result has been handled. A failed turn exits 1 with `[turn:failed] category=<model|infra> kind=<Kind>` on stderr. Answer an "Always" option for that call in an interactive chat and headless runs can use it. The same rule applies to reminders and webhooks. See [unattended runs](/guides/unattended-runs/).
 
-At this point, netclaw has your profile and a working tool stack. A few directions worth exploring:
+## Related pages
 
-- **Connect channels, enable search, set exposure mode** — run [`netclaw config`](/cli/config/) to reach any of these. It's a re-entrant menu-driven TUI; everything `netclaw init` didn't set up lives here.
-- Wire it into Slack or Discord: create your Slack app, then run `netclaw config` → Channels to enter the tokens ([Channels guide](/channels/slack/))
-- Give netclaw more tools via [`netclaw mcp`](/cli/mcp-tools/) — MCP servers for databases, APIs, file systems, whatever you need
-- Resume this session later: `Ctrl+Q` to close, [`netclaw sessions`](/cli/sessions/) to pick it back up
-- [`netclaw chat`](/cli/chat/) has the full reference: keyboard shortcuts, JSON output, named sessions, scripted multi-turn workflows
+- [Build your first assistant](/getting-started/first-assistant/): the longer tutorial, ending with a reminder that runs a tool on its own
+- [`netclaw chat`](/cli/chat/): every flag, JSON output and named sessions
+- [How tool approvals work](/security/approvals/): the model behind the prompt
+- [Slash commands](/reference/slash-commands/): what each command does
+- [`netclaw config`](/cli/config/): connect Slack, Discord or Mattermost when you're ready
 
 ## Resources
 
-- [`netclaw chat` reference](/cli/chat/) — flags, modes, keyboard shortcuts
-- [Security Model](/security/security-model/) — how tool access and permissions work
-- [MCP Tools](https://modelcontextprotocol.io/specification/2025-03-26/server/tools) — the protocol behind tool execution
-- [SignalR documentation](https://learn.microsoft.com/en-us/aspnet/core/signalr/introduction) — real-time protocol between CLI and daemon
+- [Model Context Protocol](https://modelcontextprotocol.io/): the protocol behind MCP tool servers
+- [SignalR documentation](https://learn.microsoft.com/en-us/aspnet/core/signalr/introduction): the real-time protocol between the CLI and the daemon
diff --git a/src/content/docs/getting-started/installation.md b/src/content/docs/getting-started/installation.md
index bf5e6d8..2a63f32 100644
--- a/src/content/docs/getting-started/installation.md
+++ b/src/content/docs/getting-started/installation.md
@@ -1,69 +1,94 @@
 ---
 title: "Installation"
-description: "Install Netclaw on your system."
+description: "Requirements, install commands for Linux, macOS, Windows and Docker, plus how to update and uninstall netclaw."
 ---
 
-Netclaw has two components: a **CLI** (`netclaw`) and a **daemon** (`netclawd`). The CLI is a thin client — all inference, tool execution, and session state live in the daemon. Install both on the same machine to get started; for remote setups, see [Pairing Remote Devices](/guides/pairing-remote-devices/).
+Netclaw is two binaries: the CLI (`netclaw`) and the daemon (`netclawd`). The CLI is a thin client. Inference, tool execution and session state all live in the daemon, so install both on the machine that will run your assistant. For a remote setup, see [pairing remote devices](/guides/pairing-remote-devices/). If you just want it running, the [quickstart](/getting-started/quickstart/) is shorter.
 
-## Linux (recommended)
+## Requirements
 
-```bash
-curl -sSL https://releases.netclaw.dev/install.sh | bash
+| | Linux | macOS | Windows |
+|---|---|---|---|
+| Architecture | x86_64, ARM64 | Apple Silicon (M1 or later). Intel Macs are rejected. | x64 only |
+| Tools the installer needs | `curl`, `tar`, `sha256sum` or `shasum` | `curl`, `tar`, `shasum` (all ship with macOS) | PowerShell |
+| Extra packages | ICU runtime (`libicu`) for the daemon, `tzdata` for timezone-aware reminders | - | - |
+| .NET runtime | Not needed | Not needed | Not needed |
+| Runs as a service | systemd user unit | No, start it by hand | No, start it by hand |
+
+The binaries are self-contained, so there's no .NET to install. There are no Homebrew, winget, apt or other package-manager packages. The install script, the PowerShell script and the Docker image are the supported routes.
+
+:::caution
+On a minimal Linux image the daemon crashes at startup with `Couldn't find a valid ICU package installed on the system` and `netclaw init` ends with `Failed to start daemon: process exited with code 134`. Install your distro's ICU runtime first, for example `sudo apt-get install libicu74` on Ubuntu 24.04. Most desktop installs and cloud VMs have it already. Minimal containers and some slim images don't. The same images often lack `tzdata` too. Without it the `init` identity step answers `Unknown time zone 'America/Chicago'` for every zone except `UTC`, and a reminder with a `CRON_TZ=` prefix fails with `Invalid CRON_TZ prefix. Unknown time zone`. `sudo apt-get install curl ca-certificates libicu74 tzdata` covers everything on Ubuntu 24.04.
+:::
+
+### Machine and network
+
+| Resource | What to expect |
+|---|---|
+| Memory | Budget about 800 MB for `netclawd` with local embeddings on, the figure from the 0.27.0 release notes. Measured on 0.27.1: about 480 MB idle and 560 MB after a few memory writes, or about 235 MB with embeddings off. |
+| Disk | About 160 MB for the two binaries, about 129 MB for the two embedding models, then session history and memory as you use it. |
+| Network | `releases.netclaw.dev` for installs and updates, `huggingface.co` on the daemon's first start to fetch the embedding models, and your LLM provider. |
+| LLM provider | An API key for a hosted provider, or the address of a server you run (Ollama, llama.cpp, vLLM). The [quickstart](/getting-started/quickstart/) covers choosing one. |
+
+Semantic memory is on by default since 0.27.0. To skip the model download and cut memory use, turn embeddings off in `~/.netclaw/config/netclaw.json`:
+
+```json
+{
+  "Memory": { "Embeddings": { "Enabled": false } }
+}
 ```
 
-Installs both CLI and daemon to `~/.netclaw/bin` and puts `netclaw` on your PATH automatically — see [PATH and shell integration](#path-and-shell-integration). The same script serves macOS on Apple Silicon. Supports x86_64 and ARM64 on Linux; Intel Macs are not supported.
+The daemon restarts itself when that file changes. Memory recall falls back to keyword search. See [memory and embeddings](/configuration/memory/).
+
+## Install on Linux or macOS
 
 ```bash
-# CLI only
-curl -sSL https://releases.netclaw.dev/install.sh | bash -s -- cli
+curl -sSL https://releases.netclaw.dev/install.sh | bash
+```
 
-# Daemon only
-curl -sSL https://releases.netclaw.dev/install.sh | bash -s -- daemon
+The script detects your platform, downloads both binaries, checks them against the published SHA-256 checksums and puts them in `~/.netclaw/bin`. It ends by printing the next three commands.
 
-# Pin a version
-NETCLAW_VERSION=0.1.0 curl -sSL https://releases.netclaw.dev/install.sh | bash
+| Goal | Command |
+|---|---|
+| CLI only | `curl -sSL https://releases.netclaw.dev/install.sh \| bash -s -- cli` |
+| Daemon only | `curl -sSL https://releases.netclaw.dev/install.sh \| bash -s -- daemon` |
+| Pin a version | `curl -sSL https://releases.netclaw.dev/install.sh \| NETCLAW_VERSION=0.28.2 bash` |
+| Custom directory | `curl -sSL https://releases.netclaw.dev/install.sh \| INSTALL_DIR=$HOME/tools/netclaw bash` |
+| Install into another home | `curl -sSL https://releases.netclaw.dev/install.sh \| NETCLAW_HOME=/srv/netclaw bash` |
+| Preview only | `curl -sSL https://releases.netclaw.dev/install.sh \| bash -s -- --dry-run` |
+| Leave my shell profile alone | `curl -sSL https://releases.netclaw.dev/install.sh \| bash -s -- --skip-shell` |
 
-# Custom install directory
-INSTALL_DIR=/opt/netclaw curl -sSL https://releases.netclaw.dev/install.sh | bash
-```
+The environment variable goes on `bash`, after the pipe. Put it before `curl` and the script never sees it. `NETCLAW_HOME` moves the config, `bin/` and the `env` script together. `INSTALL_DIR` moves only the binaries. An existing install is upgraded where it sits, in `$NETCLAW_HOME/bin` first, then in a legacy `~/.netclaw/bin` (its `env` script stays at `~/.netclaw/env`). `CONFIG_DIR` and `NETCLAW_CONFIG_DIR` have no effect.
 
-## Windows
+## Install on Windows
 
 ```powershell
 iwr -useb https://releases.netclaw.dev/install.ps1 | iex
 ```
 
-Installs to `%LOCALAPPDATA%\Programs\netclaw` and prepends it to your User PATH — see [PATH and shell integration](#path-and-shell-integration). To install a specific component or version:
+This installs to `%LOCALAPPDATA%\Programs\netclaw` and prepends that folder to your User PATH. For options, download the script and run it with parameters:
 
 ```powershell
 $script = Join-Path $env:TEMP "netclaw-install.ps1"
 iwr -useb https://releases.netclaw.dev/install.ps1 -OutFile $script
-& $script -Component cli           # CLI only
-& $script -Component daemon        # Daemon only
-& $script -Version 0.1.0           # Pinned version
+& $script -Component cli                     # CLI only
+& $script -Component daemon                  # daemon only
+& $script -Version 0.28.2                    # pinned version
+& $script -InstallDir C:\tools\netclaw       # custom directory
+& $script -DryRun                            # preview only
+& $script -SkipShell                         # leave PATH alone
 ```
 
 ## PATH and shell integration
 
-The native installers put `netclaw` on your PATH for you. The catch is the terminal you ran the installer in — a piped install can't change the PATH of a shell that's already running, so `netclaw` resolves in new terminals but not the current one until you reload it.
-
-**Linux and macOS.** The installer writes `~/.netclaw/env` and sources it from your shell's startup file — `.bashrc` or `.bash_profile` for bash, `.zshrc` for zsh, or a native `~/.config/fish/conf.d/netclaw.fish` for fish. New shells pick it up. For the shell you installed from, load it now instead of opening a new one:
-
-```bash
-. ~/.netclaw/env
-```
-
-**Windows.** The installer prepends the install directory to your User PATH and updates the current session. Any other terminal that's already open needs a restart before it inherits the change.
+A piped install can't change the PATH of the shell it ran in, so `netclaw` works in new terminals but not the current one.
 
-**Opting out.** Pass `--skip-shell` (Linux/macOS) or `-SkipShell` (Windows) and the installer leaves your PATH alone, printing the directory to add yourself.
-
-```bash
-curl -sSL https://releases.netclaw.dev/install.sh | bash -s -- --skip-shell
-```
+- On Linux and macOS the installer writes `~/.netclaw/env` and sources it from `.bashrc` (`.bash_profile` or `.profile` on macOS), `.zshrc`, or `~/.config/fish/conf.d/netclaw.fish`. In the shell you installed from, load it now with `. ~/.netclaw/env` (`<home>/env` if you set `NETCLAW_HOME`).
+- On Windows the installer updates your User PATH and the current session. Other terminals that are already open need a restart.
 
 ## Docker
 
-Run the daemon as a container — useful for servers, homelab setups, or if you don't want to install anything on the host.
+The image runs the daemon only, as the non-root user `netclaw` (UID 1654), on port 5199 inside the container. Keep state in a named volume:
 
 ```bash
 docker run -d \
@@ -72,35 +97,11 @@ docker run -d \
   ghcr.io/netclaw-dev/netclaw
 ```
 
-| Setting | Value |
-|---------|-------|
-| Image | `ghcr.io/netclaw-dev/netclaw` |
-| Architectures | `linux/amd64`, `linux/arm64` |
-| Runs as | non-root user `netclaw` (UID 1654) |
-| Port | 5199 (loopback inside the container) |
-| Volume | `/home/netclaw/.netclaw` (config, identity, sessions, logs) |
-
-The image runs as the non-root `netclaw` user, so persist state in a named volume (a host bind mount has to be `chown`ed to UID 1654 first). The container runs the daemon only, bound to loopback — drive it with `docker exec netclaw netclaw <command>`. To reach it from a host CLI or another machine (including [pairing](/guides/pairing-remote-devices/)), configure a non-local [exposure mode](/deployment/exposure-modes/). See [Docker Deployment](/deployment/docker/) for the full setup.
-
-Pass provider credentials as environment variables:
-
-```bash
-docker run -d \
-  --name netclaw \
-  -v netclaw-home:/home/netclaw/.netclaw \
-  -e NETCLAW_Providers__openrouter__Type=openrouter \
-  -e NETCLAW_Providers__openrouter__ApiKey=sk-or-v1-... \
-  -e NETCLAW_Models__Definitions__claude__Provider=openrouter \
-  -e NETCLAW_Models__Definitions__claude__ModelId=anthropic/claude-sonnet-4 \
-  -e NETCLAW_Models__Roles__Main=claude \
-  ghcr.io/netclaw-dev/netclaw
-```
-
-For Docker Compose setups (including bundling Ollama), see [Docker Deployment](/deployment/docker/).
+Drive it with `docker exec -it netclaw netclaw <command>`. Give the container at least 768 MiB if you set a memory limit. With embeddings on, 512 MiB gets the daemon killed and restarted over and over. The image is multi-arch (`linux/amd64`, `linux/arm64`), and the entrypoint chowns the data directory for you, so a bind mount works too. To reach the daemon from another machine, configure an [exposure mode](/deployment/exposure-modes/). Compose files, Ollama sidecars and environment-variable configuration live in [Docker deployment](/deployment/docker/).
 
 ## Build from source
 
-Requires [.NET 10 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/10.0).
+You need the [.NET 10 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/10.0).
 
 ```bash
 git clone https://github.com/netclaw-dev/netclaw.git
@@ -110,92 +111,170 @@ dotnet publish src/Netclaw.Daemon/Netclaw.Daemon.csproj -c Release -o ./out
 export PATH="$PWD/out:$PATH"
 ```
 
+## What gets installed where
+
+| Path | What it is |
+|---|---|
+| `~/.netclaw/bin/netclaw`, `netclawd` | The CLI (81 MB) and the daemon (86 MB). On Windows, `%LOCALAPPDATA%\Programs\netclaw`. |
+| `~/.netclaw/env` | PATH snippet that your shell profile sources. |
+| `~/.bashrc`, `~/.zshrc` or fish `conf.d/netclaw.fish` | Two lines that source `~/.netclaw/env`. |
+| `~/.netclaw/` | The data directory, created on first run: `config/`, `identity/`, `sessions/`, `skills/`, `models/`, `logs/`, `schedules/`, `keys/` and `netclaw.db`. On Windows, `%USERPROFILE%\.netclaw`. Set `NETCLAW_HOME` to move it. |
+
+See the [data directory reference](/reference/data-directory/) for every file.
+
 ## Verify the install
 
 ```bash
 netclaw --version
 ```
 
-You should see the version, commit hash, and build timestamp.
+```text
+netclaw 0.28.2 (commit 7419d84, built 2026-10-29T00:09:05Z)
+```
+
+Then run [`netclaw init`](/cli/init/). After that, `netclaw status` should report `overall: healthy`.
 
-## Next steps
+## Keep the daemon running
 
-**1. Run `netclaw init`**
+On Linux, install the daemon as a systemd user service so it starts at boot. See [systemd deployment](/deployment/systemd/).
 
 ```bash
-netclaw init
+netclaw daemon install
 ```
 
-The [`init` wizard](/cli/init/) covers provider setup, identity, security posture, and feature selection — then runs a health check and drops you into chat. It is intentionally minimal: channels, search, and network exposure are not configured here.
-
-**2. Run `netclaw config`**
+On macOS and Windows there's no service yet. Start the daemon yourself after each reboot:
 
 ```bash
-netclaw config
+netclaw daemon start
 ```
 
-[`netclaw config`](/cli/config/) is the menu-driven dashboard for everything else. Connect Slack, Discord, or Mattermost; enable web search; set your exposure mode; configure inbound webhooks and skill sources. Run it right after `init` — nothing beyond a basic chat session works until you do.
+In a container or on any host without `systemctl`, `netclaw daemon install` refuses and writes nothing:
 
-See the [Quickstart](/getting-started/quickstart/) for a guided walkthrough of both steps.
+```text
+Cannot install the service: systemd user services are not available on this host (...). Run the daemon under a container supervisor, or start it with `netclaw daemon start` (it will not restart after a crash or reboot).
+```
 
-## Switching release channels
+Use `netclaw daemon start` or the Docker image there. A daemon started by hand doesn't come back after a reboot or a crash.
 
-By default, the install script and daemon pull from the **stable** channel — release builds only.
+## Update
 
-If Netclaw is already installed, switch channels with the CLI:
+```bash
+netclaw update                 # check, then ask before installing
+netclaw update --check         # check only
+netclaw update --force         # install without the confirmation prompt
+```
+
+`netclaw update` downloads and checksums the new binaries, stops the daemon, swaps the binaries, and starts the daemon again if it was running. The daemon only checks for updates in the background and reports them in `netclaw status`. It never applies one. Self-update is disabled in the Docker image, so pull a newer image tag instead. See [upgrading](/guides/upgrading/) and [`netclaw update`](/cli/update/).
+
+`netclaw daemon stop` and `netclaw update` signal a process only after proving the PID serves this home. Linux reads the proof from `/proc`. On macOS and Windows the CLI can't prove the home of a 0.27.1 daemon, so updating from 0.27.1 refuses with `Nothing was stopped. PID <pid> is not shown to serve <home>.` Run the `kill <pid>` command it prints (Task Manager on Windows) once, then update again.
+
+Re-running the install script also works and keeps your configuration. A running daemon keeps the old version until you restart it, so stop it first and start it after:
 
 ```bash
-netclaw update --channel beta
+netclaw daemon stop
+curl -sSL https://releases.netclaw.dev/install.sh | bash
+netclaw daemon start
 ```
 
-This installs the newest build on that channel right away and saves to your config, so later update checks and self-updates follow the beta feed. Pass `--channel stable` to switch back.
+### Release channels
 
-To choose a channel at first install instead, pass `--channel` to the install script:
+`stable` is the default and carries release builds only. `beta` resolves to the newest prerelease, or to a newer stable release if one supersedes it.
 
-**Linux:**
+```bash
+netclaw update --channel beta     # switch, save to config, and install now
+netclaw update --channel stable   # switch back
+```
+
+To pick a channel at first install, pass it to the script. The script saves the channel to `netclaw.json` itself, using `jq` when a config already exists. Without `jq` it prints the line to add. A `netclaw.json` that holds only the channel doesn't count as an existing install, so `netclaw init` still runs the full setup wizard.
 
 ```bash
 curl -sSL https://releases.netclaw.dev/install.sh | bash -s -- --channel beta
 ```
 
-**Windows:**
-
 ```powershell
-.\install.ps1 -Channel beta
+& $script -Channel beta
 ```
 
-**Docker:**
+For Docker, use the `ghcr.io/netclaw-dev/netclaw:beta` tag.
 
-Use the `ghcr.io/netclaw-dev/netclaw:beta` image tag instead of the default `ghcr.io/netclaw-dev/netclaw` (which resolves to the latest stable).
+## Uninstall
 
-The install script only swaps which binaries it pulls. Also set `Daemon.UpdateChannel` to `"beta"` in `netclaw.json` so the daemon checks the beta feed for self-updates. (Switching with `netclaw update --channel` does this for you.)
+There's no uninstall command. Remove the pieces in this order:
 
-> **Note:** The install script is idempotent — running it on an existing install will update the binaries without breaking your configuration. If the daemon is running, stop it first:
->
-> ```bash
-> sudo systemctl stop netclawd
-> curl -sSL https://releases.netclaw.dev/install.sh | bash -s -- --channel beta
-> sudo systemctl start netclawd
-> ```
+1. Stop the daemon, and remove the service if you installed one.
 
-## Updating
+   ```bash
+   netclaw daemon stop
+   netclaw daemon uninstall
+   ```
 
-```bash
-netclaw update                 # check for and install updates
-netclaw update --check         # check only, don't install
-netclaw update --channel beta  # switch channel (saved to config), then update
-```
+2. Delete the binaries and the PATH hook.
+
+   ```bash
+   rm -rf ~/.netclaw/bin ~/.netclaw/env
+   ```
+
+   Then delete the `# netclaw shell setup` comment and the `. '.../.netclaw/env'` line from your `~/.bashrc` or `~/.zshrc`. For fish, delete `~/.config/fish/conf.d/netclaw.fish`.
+
+3. Optional: delete your data.
+
+   ```bash
+   rm -rf ~/.netclaw
+   ```
+
+   :::caution
+   This removes your config, secrets, encryption keys, sessions, memory and reminders for good. [Back them up first](/guides/backup-and-restore/) if you might want them again.
+   :::
+
+On Windows, run `netclaw daemon stop`, delete `%LOCALAPPDATA%\Programs\netclaw`, remove that folder from your User PATH in Environment Variables, and delete `%USERPROFILE%\.netclaw` if you want the data gone too. For Docker, `docker rm -f netclaw` and `docker volume rm netclaw-home`.
+
+## Troubleshooting
+
+### `netclaw: command not found`
+
+**Symptom:** the install finished but `netclaw --version` fails.
+**Cause:** your current shell started before the installer changed the PATH.
+**Fix:** run `. ~/.netclaw/env`, or open a new terminal. On Windows, restart the terminal.
+
+### `Error: Required command 'curl' not found`
+
+**Symptom:** the script stops straight away, or the shell says `curl: command not found`.
+**Cause:** minimal images and containers ship without `curl`.
+**Fix:** `sudo apt-get install curl ca-certificates` (or your distro's equivalent), then run the script again.
+
+### `Failed to start daemon: process exited with code 134`
+
+**Symptom:** `netclaw init` ends with that line and `Setup complete with warnings`, followed by a .NET stack trace that begins `Couldn't find a valid ICU package`.
+**Cause:** the ICU runtime library is missing. The CLI runs without it and the daemon doesn't.
+**Fix:** install it (`sudo apt-get install libicu74` on Ubuntu 24.04, or the `libicu` or `icu-libs` package on other distros), run `netclaw daemon start`, then `netclaw chat --onboarding` to get the opening conversation `init` would have started. If you can't install packages, `DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 netclaw daemon start` also works.
+
+### `Unknown time zone 'America/Chicago'`
+
+**Symptom:** the `init` identity step or `netclaw reminder create` rejects a valid IANA zone.
+**Cause:** the machine has no timezone database. Minimal images ship without `tzdata`. `UTC` still works.
+**Fix:** install it (`sudo apt-get install tzdata`) and retry.
+
+### `Error: Intel Macs are not supported`
+
+**Cause:** the installer only ships Apple Silicon builds.
+**Fix:** run netclaw on an Apple Silicon Mac, a Linux machine or in Docker.
+
+### `Failed to fetch checksum file`
+
+**Cause:** the version you pinned isn't on the release feed.
+**Fix:** check the spelling against the [release list](https://github.com/netclaw-dev/netclaw/releases), or drop `NETCLAW_VERSION` to install the latest stable.
 
-Self-update is disabled in the Docker image — update by pulling a new image tag instead.
+## Related pages
 
-| Channel | Description |
-|---------|-------------|
-| `stable` | Official releases only. The default. |
-| `beta` | Prereleases. Resolves to the newest of {stable, prerelease}, so a stable release that supersedes a beta is still offered. |
+- [Quickstart](/getting-started/quickstart/): install, `netclaw init` and a first message in five minutes
+- [Build your first assistant](/getting-started/first-assistant/): the full path from a fresh machine to an assistant that works unprompted
+- [Docker deployment](/deployment/docker/): Compose, sidecars and environment-variable configuration
+- [systemd deployment](/deployment/systemd/): run the daemon as a user service on Linux
+- [Upgrading](/guides/upgrading/): what to check before and after an update
 
 ## Resources
 
-- [.NET 10 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) — required for building from source
-- [Docker Engine](https://docs.docker.com/engine/install/) — container runtime for the Docker install method
-- [Docker Deployment](/deployment/docker/) — Docker Compose, Ollama sidecar, and production container configuration
-- [Automatic PATH integration (netclaw#1687)](https://github.com/netclaw-dev/netclaw/pull/1687) — the installer behavior this section documents
+- [netclaw releases on GitHub](https://github.com/netclaw-dev/netclaw/releases): release notes for every version
+- [.NET globalization and ICU](https://learn.microsoft.com/en-us/dotnet/core/extensions/globalization-icu): why the daemon needs ICU and the invariant-mode switch
+- [Docker Engine install guide](https://docs.docker.com/engine/install/): container runtime for the Docker route
+- [.NET 10 SDK downloads](https://dotnet.microsoft.com/en-us/download/dotnet/10.0): required only to build from source
diff --git a/src/content/docs/getting-started/quickstart.md b/src/content/docs/getting-started/quickstart.md
index bfdbc21..befa5eb 100644
--- a/src/content/docs/getting-started/quickstart.md
+++ b/src/content/docs/getting-started/quickstart.md
@@ -1,9 +1,15 @@
 ---
 title: "Quickstart"
-description: "Get Netclaw running in minutes with the init wizard."
+description: "Install netclaw, run the setup wizard and send your first message in about five minutes."
 ---
 
-Install netclaw, run the setup wizard, and start chatting. Takes about 5 minutes.
+Install netclaw, answer a few setup questions, and talk to your assistant. Allow about five minutes, plus a minute or two on first start while the daemon fetches its memory models. This is the short path with no detours. [Your first conversation](/getting-started/first-conversation/) explains what you see in the chat, and [Build your first assistant](/getting-started/first-assistant/) is the long tutorial that adds tools, memory and a reminder.
+
+## Before you begin
+
+- A 64-bit Linux, an Apple Silicon Mac or Windows x64. On Linux you also need `curl`, the ICU library (`libicu`) and `tzdata`. Without ICU the daemon won't start, and without `tzdata` the identity step rejects every timezone but UTC. See [requirements](/getting-started/installation/#requirements).
+- About 1 GB of free memory and outbound access to `releases.netclaw.dev` and `huggingface.co`.
+- An LLM: an API key for one of the eight providers `init` lists (Anthropic, OpenAI, OpenRouter and DeepSeek among them), or the address of a server you run, such as Ollama or llama.cpp.
 
 ## 1. Install
 
@@ -11,13 +17,21 @@ Install netclaw, run the setup wizard, and start chatting. Takes about 5 minutes
 curl -sSL https://releases.netclaw.dev/install.sh | bash
 ```
 
-The installer adds `netclaw` to your PATH in new shells. To use it in this one, load it now:
+The installer adds `netclaw` to your PATH for new shells. Load it into this one:
 
 ```bash
 . ~/.netclaw/env
 ```
 
-Or just open a new terminal — on Windows, restart your terminal so it picks up the updated PATH. See [Installation](/getting-started/installation/) for Windows, Docker, build-from-source, and the `--skip-shell` opt-out.
+On Windows, use the [PowerShell installer](/getting-started/installation/#install-on-windows) and restart your terminal. Check it worked:
+
+```bash
+netclaw --version
+```
+
+```text
+netclaw 0.28.2 (commit 7419d84, built 2026-10-29T00:09:05Z)
+```
 
 ## 2. Run the setup wizard
 
@@ -25,78 +39,98 @@ Or just open a new terminal — on Windows, restart your terminal so it picks up
 netclaw init
 ```
 
-The wizard covers four steps for Personal posture (five for Team/Public — more on that below).
-
-### Pick a provider
+The wizard asks for four things:
 
-![Provider selection](/screenshots/output/init-01-provider-list.png)
+| Step | You choose |
+|---|---|
+| Provider | An LLM provider, its credentials or endpoint, and a default model |
+| Identity | Agent name, communication style, your name, timezone |
+| Security posture | Personal, Team or Public |
+| Health check | Nothing. It writes config, starts the daemon and opens chat. |
 
-![Model selection](/screenshots/output/init-01-model-select.png)
+Team and Public add a fifth step, enabled features. The header says "Step 1 of 5" until you pick a posture, then drops to "of 4" if you chose Personal.
 
-Choose an LLM provider and enter credentials. Self-hosted providers like Ollama need an endpoint URL. Once credentials pass a connectivity check, you pick a default model.
+### Provider
 
-Use [`netclaw provider`](/cli/provider/) to add more providers later.
+Press a number to pick a provider, then enter its credentials. For llama.cpp or vLLM, pick **OpenAI-compatible** and give the server address, with or without `/v1`: `http://llm.example.internal:8080`. The endpoint field starts with `http://localhost:11434` already in it and your cursor sits at the end, so press Backspace until the default is gone before you type. After a connectivity check you pick a default model.
 
-### Set your identity
+![Netclaw Setup, Step 1 of 5, LLM Provider, listing eight providers from Anthropic to Venice.ai with Anthropic highlighted](/screenshots/output/init-01-provider-list.png)
 
-![Identity step — communication style substep](/screenshots/output/init-02-identity.png)
+The first screen lists all eight providers, and the counter reads "of 5" until you choose a posture.
 
-The identity step has four substeps in order: agent name → communication style → your name → timezone. The screenshot above shows the communication style substep. All four fields pre-fill when you re-run `netclaw init` on an existing install.
+### Identity and posture
 
-### Set your security posture
+Answer the four identity prompts, then pick **Personal** for a single-user machine. The timezone must be an IANA id such as `America/Chicago`. `UTC` is already filled in. See the [security model](/security/security-model/) for Team and Public.
 
-![Security posture selection](/screenshots/output/init-02-security-posture.png)
+![Netclaw Setup, Step 2 of 5, Identity, with four communication styles from Concise & casual to Detailed & formal](/screenshots/output/init-02-identity.png)
 
-Pick how much you trust the environment. **Personal** is single-user with full tool access. **Team** and **Public** are progressively more restrictive. See [Security Model](/security/security-model/) for details.
+The style you pick here shapes the assistant's first greeting, and you can redo this step later from `netclaw init`.
 
-### Enabled features (Team / Public only)
+![Netclaw Setup, Step 3 of 5, Security Posture, offering Personal, Team and Public with Personal highlighted](/screenshots/output/init-02-security-posture.png)
 
-If you chose Team or Public posture, the wizard adds a step to select which feature sets are active. Personal posture skips this step and goes straight to the health check.
+The grey text under the options summarizes what each posture allows. Channels are set up later in `netclaw config`.
 
 ### Health check
 
-![Health check](/screenshots/output/init-05-health-check.png)
-
-The wizard validates provider connectivity, writes config, and starts the daemon. When all checks pass, netclaw launches chat automatically — you land in the chat TUI without running anything else.
-
-If the health check finishes with warnings, the wizard displays: "Setup complete with warnings. Run `netclaw daemon start`, then `netclaw chat`. Adjust settings with `netclaw config`." Fix the flagged issue and retry.
+The wizard writes `~/.netclaw/config/netclaw.json`, starts the daemon and checks the provider. A clean run looks like this:
 
-## 3. Connect channels and features
-
-```bash
-netclaw config
+```text
+✓  LLM provider configured (OpenAI-compatible (llama.cpp / vLLM / DwarfStar ds4))
+✓  Model selected (<your model>)
+✓  Memory backend (SQLite)
+✓  Configuration written
 ```
 
-![The netclaw config Settings Areas menu](/screenshots/output/config-dashboard.png)
-
-Each row is a configuration area with its live status — select one to set it up.
+![Netclaw Setup, Step 4 of 4, Health Check, with four green check lines and an Applying configuration spinner](/screenshots/output/init-05-health-check.png)
 
-Channels (Slack, Discord, Mattermost), web search, network exposure, skill sources, webhooks, and browser automation are all configured here — none of them are set during `netclaw init`. Run [`netclaw config`](/cli/config/) now to connect your first channel or enable search before you do anything else. Changes save as you make them; re-run it any time.
+The four checks go green while the daemon applies the new configuration, and the step counter ends at 4 of 4 because this was a Personal setup. This capture used an OpenAI-compatible endpoint serving `qwen2:0.5b`, so that's what the first two lines name. Yours name your provider and model. The spinner is the last frame `init` shows before it opens the chat.
 
-## 4. First chat session
+If the daemon fails to start, the last line reads "Setup complete with warnings" and tells you to run `netclaw daemon start`, then `netclaw chat --onboarding`. On a bare Linux image the cause is usually a missing `libicu`. See [troubleshooting](/getting-started/installation/#failed-to-start-daemon-process-exited-with-code-134).
 
-<!-- TODO(screenshots): chat-session-start.png — capture after release; epic #55 -->
+## 3. Send your first message
 
-On a clean health check, `netclaw init` drops you straight into the chat TUI. The agent introduces itself and kicks off a personality-bootstrapping conversation — it asks about your work, your tools, and what you need help with. This builds your profile so future conversations have context.
+After a clean health check, `init` opens the chat and your assistant greets you by name and asks what you want to use it for. Answer in plain language. The first reply can take 30 seconds or more on a local model. Press `Ctrl+Q` to leave.
 
-See [Your First Conversation](/getting-started/first-conversation/) for the full walkthrough of what happens next.
+If `init` ended with warnings, there's no greeting. Fix the warning, run `netclaw daemon start`, then `netclaw chat --onboarding`. It opens the same conversation.
 
-### Headless mode
-
-Don't need the TUI? Send a one-shot prompt from your terminal:
+## Verify it works
 
 ```bash
-netclaw chat -p "what's the weather in Chicago?"
+netclaw status
 ```
 
-Pipe output to other tools with `--json`. See [`netclaw chat`](/cli/chat/) for the full reference.
+```text
+overall: healthy
+version: 0.28.2 (commit 7419d84, built 2026-10-29T00:10:12Z)
+daemon: PID 3644, uptime 0m 24s, endpoint http://127.0.0.1:5199
+persistence: Sqlite
+memory: sqlite (healthy)
+telemetry: disabled
+model: <your model> (provider: openai-compatible, context: 131,072 tokens)
+connectors:
+- discord: disabled (disabled)
+- mattermost: disabled (disabled)
+- slack: disabled (disabled)
+- tui: healthy (enabled)
+```
+
+`overall: healthy` and a reply in the chat mean you're done. If something looks off, run `netclaw doctor`. A `WARN` about a missing `secrets.json` is normal when your provider needs no API key.
 
 ## What's next
 
-Init gets you to chat. To make netclaw actually useful — connecting it to Slack, enabling web search, or exposing it to your team — run `netclaw config` next.
+- [Your first conversation](/getting-started/first-conversation/): what to try, the keys that matter and your first approval prompt
+- [Build your first assistant](/getting-started/first-assistant/): identity, tools, memory and a reminder that reports back
+- [`netclaw config`](/cli/config/): connect Slack, Discord or Mattermost, enable web search, set exposure
+
+## Related pages
+
+- [Installation](/getting-started/installation/): every platform, update and uninstall
+- [`netclaw init`](/cli/init/): the wizard in full, including re-running it
+- [Self-hosted providers](/configuration/self-hosted-providers/): Ollama, llama.cpp and vLLM settings
+- [`netclaw status`](/cli/status/) and [`netclaw doctor`](/cli/doctor/): check health when something is wrong
+
+## Resources
 
-- [`netclaw config`](/cli/config/) — connect channels, enable web search, set network exposure and skills
-- [Your First Conversation](/getting-started/first-conversation/) — personality bootstrapping and your first real interaction
-- [Slack](/channels/slack/) / [Discord](/channels/discord/) / [Mattermost](/channels/mattermost/) — full channel setup guides
-- [`netclaw doctor`](/cli/doctor/) — diagnose issues if something didn't work
-- [`netclaw status`](/cli/status/) — check daemon health and connector states
+- [Ollama](https://ollama.com/): run models locally with one command
+- [llama.cpp server](https://github.com/ggml-org/llama.cpp/tree/master/tools/server): an OpenAI-compatible server for GGUF models
+- [OpenRouter](https://openrouter.ai/): one API key for many hosted models