kiki-agent-lite 0.3.1 → 0.3.2

package/dist/docs/en/reference/command.md

@@ -1,15 +1,15 @@
 # `kiki` Command
 
-`kiki` is the product's unified CLI entry — the terminal form of the three-form product (desktop app, CLI/TUI, and server) — covering the daemon-backed interactive TUI, non-interactive `-p` mode, and shared-daemon controls. Running it without arguments attaches to an existing healthy daemon or starts one after workspace trust; `kiki -p` keeps the SDK-backed non-interactive path separate. Use `kiki serve` to control the daemon explicitly, and `kiki web` for the compatible foreground server/UI command. Its seat and MCP subcommands let external callers such as Cursor, Claude Code, and Codex call Kiki (inbound); they do not configure the external executors that Kiki uses to run subagents (outbound).
+`kiki` is the command-line entry to Kiki. It covers the interactive TUI, non-interactive `-p` mode, and shared-daemon controls. Running it with no arguments attaches to an existing healthy daemon or starts one after workspace trust; `kiki -p` runs a single prompt and exits. Use `kiki serve` to control the daemon explicitly and `kiki web` for the foreground server and browser UI. The seat and MCP subcommands let external callers such as Cursor, Claude Code, and Codex call Kiki.
 
 ```sh
 kiki [options]
 kiki <subcommand> [options]
 ```
 
-Interactive sessions always use the shared background daemon. After workspace trust is confirmed, the CLI attaches to an existing daemon or starts one automatically; no separate installation or experimental flag is required. If connection or startup fails, the error is shown instead of falling back to an independent local session. Correct the reported error and run the command again. Non-interactive `--prompt` execution is separate from this terminal startup path.
+Interactive sessions always use the shared background daemon. After workspace trust is confirmed, the CLI attaches to an existing daemon or starts one automatically. If that fails, Kiki shows the error rather than falling back to a separate local session — fix what the error names and run the command again.
 
-Interactive mode needs a terminal on both stdin and stdout. A pipe or a redirect on either one ends the run before workspace trust and the daemon are involved — Kiki does not switch to non-interactive mode for you. To supply a prompt from a pipe, run `kiki -p -` and let Kiki read the prompt from stdin.
+Interactive mode needs a terminal on both stdin and stdout. A pipe or a redirect on either one ends the run before workspace trust and the daemon are involved, and Kiki does not switch to non-interactive mode for you. To supply a prompt from a pipe, run `kiki -p -` and let Kiki read the prompt from stdin.
 
 ## Main Command Options
 
@@ -265,7 +265,11 @@ Recovery and removal have different meanings:
 - `clear-queue <id> --agree` explicitly discards pending data and disables that destination. `remove <id>` removes local configuration and its secret; add `--discard-pending` only when you want to discard an existing queue. Neither deletes remote history, and delivery identity/revision evidence is retained.
 - `withdraw <id> --agree` sends versioned deletion tombstones only where the receiver supports deletion. It does not delete local usage; vibe does not support this operation.
 
-For an existing vibe collector, use `handoff plan <id>` on a new native draft, prepare the collector's `kiki-handoff.json` for the returned namespace and future UTC cutoff **T**, then run native `preview` and `test`. `handoff arm <id> --collector-file <file> --fingerprint <preview_fingerprint> --agree` verifies the marker against the saved native credential, activates only that home's collector cutoff, and enables native delivery from the fixed T. It does not read the collector's key or stop its daemon. Different keys are not treated as proof of the same remote account. The collector remains responsible for `<T`, native for `>=T`; offline catch-up keeps T rather than using ACK time. `handoff refresh <id>` reads the collector's safe final receipt; completion requires both the old receipt and a real native ACK. `handoff rollback <id> --cutoff <new_future_R> --agree` keeps native responsible for `[T,R)` and resumes the collector at `>=R`, not an unbounded old scan.
+To hand a home over from an existing vibe collector, use `handoff plan <id>` on a new native draft, prepare the collector's `kiki-handoff.json` for the returned namespace and future UTC cutoff **T**, then run native `preview` and `test`.
+
+`handoff arm <id> --collector-file <file> --fingerprint <preview_fingerprint> --agree` verifies the marker against the saved native credential, activates only that home's collector cutoff, and enables native delivery from the fixed T. It does not read the collector's key or stop its daemon, and different keys are not treated as proof of the same remote account.
+
+The collector stays responsible for `<T` and native for `>=T`; offline catch-up keeps T rather than using ACK time. `handoff refresh <id>` reads the collector's safe final receipt, and completion requires both that receipt and a real native ACK. `handoff rollback <id> --cutoff <new_future_R> --agree` keeps native responsible for `[T,R)` and resumes the collector at `>=R`, never an unbounded old scan.
 
 Receiver developers can run the repository's local example with `pnpm exec tsx packages/kap-server/examples/usage-export-receiver.ts` (Node 24). It binds only `127.0.0.1:9080`, persists replacements and deletion tombstones in `usage-receiver.sqlite`, and exposes `POST /usage`. Approve the exact loopback HTTP grant when testing it. A production receiver needs TLS, durable storage, and authentication; the example is not a hosted dashboard.
 

package/dist/docs/en/reference/keyboard.md

@@ -1,6 +1,16 @@
 # Keyboard Shortcuts
 
-Kiki's TUI shortcuts are grouped by context: general input, mode switching, editing, streaming, tool output, approval panels, and help navigation. Type `/help` to browse command usage, descriptions, support status, and input shortcuts.
+This page covers GUI thread navigation, followed by TUI shortcuts grouped by context: general input, mode switching, editing, streaming, tool output, approval panels, and help navigation. In the TUI, type `/help` to browse command usage, descriptions, support status, and input shortcuts.
+
+## Desktop and web thread navigation
+
+In the GUI, open Settings → Shortcuts to rebind **Next running thread** and **Previous running thread**. The defaults are `Ctrl-Tab` and `Ctrl-Shift-Tab`, respectively. Browsers own these tab-switching chords; choose different bindings to use the actions on the web. Existing custom bindings remain unchanged. If a custom binding already uses `Ctrl-Shift-Tab`, the new previous-thread action stays unbound until you assign a free chord.
+
+These actions cycle through running sessions already loaded in the current window's session list, within its connection and fetched workspace/archive scope. They use creation time, newest first, rather than pin order or recent updates. From a thread outside that set, Next enters the first running thread and Previous enters the last. With no running threads they do nothing; with one, they stay on it.
+
+A running session has an active main or subagent turn, or background work. A pending approval/question alone, unread output, or a pinned session does not make it running. A session that still has running work remains eligible even if it also needs your input.
+
+Switching conversations through these shortcuts, the sidebar, or the quick switcher focuses the current editable composer once it is ready. Drafts and unchanged draft selections are retained without scrolling the transcript to the composer. Open dialogs and terminal input keep their focus; ordinary Tab, Shift-Tab and IME text input keep their usual behavior.
 
 ## General Shortcuts
 
@@ -29,7 +39,7 @@ During streaming, `Ctrl-C` clears a nonempty draft first. With the input box emp
 
 Press `Shift-Tab` to enable or disable Plan mode. When enabled, the Agent prioritizes read-only tools for research and planning and can write to the current plan file; `Bash` is subject to the current permission mode and regular rules, without any additional separate approval triggered by Plan mode. Simply toggling does not create an empty plan file. Press `Shift-Tab` again to exit Plan mode.
 
-Type `!` in an empty input box to enter shell mode and run terminal commands directly. The active-turn backgrounding shortcut `Ctrl-B` is disabled in the daemon TUI. See [Interaction and input](../guides/interaction.md#shell-mode).
+Type `!` in an empty input box to enter shell mode and run terminal commands directly. See [Interaction and input](../guides/interaction.md#shell-mode).
 
 ## Input & Editing
 
@@ -60,8 +70,12 @@ While streaming output is active, the input box can still receive input and supp
 | --- | --- |
 | `Esc` | Interrupt the current streaming output |
 | `Ctrl-C` | Clear a nonempty draft first; interrupt the active turn when the input is empty |
-| `Ctrl-S` | Disabled: the prompt-steering shortcut does not inject input into the active turn |
-| `Ctrl-B` | Disabled: the active turn cannot be moved to the background with this shortcut |
+| `Ctrl-S` | Steer the running turn: send the queued messages and the current draft into it now instead of waiting for the turn to end |
+| `Ctrl-B` | Move the running turn to the background, leaving you free to queue the next instruction |
+
+`Ctrl-S` steers in queue order. Shell commands (`! …`) and inline Skill invocations are never steered in — they stay queued and run after the current turn, and everything queued behind such an item waits with them.
+
+Both shortcuts are unavailable in the daemon TUI (`kiki web`), which reports them as disabled.
 
 ## Tool Output
 

package/dist/docs/en/reference/model-vocabulary.md

@@ -23,15 +23,15 @@ A newly spawned subagent selects its model in this order:
 2. The `model_alias` pin on the effective profile, route, or caller lease (constraints an external delegating host pre-sets for the caller).
 3. Explicitly configured `[subagent].default_model`.
 
-With none of these sources, the spawn fails with `model.not_configured`; neither the caller's model nor the main-agent `default_model` is a silent fallback. Explicit `model_alias: inherit` on the profile, route, or caller lease binds the caller's current resolved model and effective thinking effort unless explicit tool `effort` or an applicable profile, route, lease, or matching `model_profiles` effort pin wins. `AgentRun` rejects `model_alias: "inherit"`: specify a concrete configured model name, or omit the parameter to use the target default. Unknown concrete aliases and machine-denied models fail before the child starts. A model outside explicit preferences or different from a route/caller-lease pin continues with an advisory only when executable and inside every hard model and effort boundary.
+With none of these sources, the spawn fails with `model.not_configured`; neither the caller's model nor the main-agent `default_model` is a silent fallback. `model_alias: inherit` on a profile, route, or caller lease binds the caller's current model and thinking effort unless an explicit tool `effort` or an applicable effort pin overrides them. `AgentRun` itself rejects `model_alias: "inherit"` — pass a concrete configured model name, or omit the parameter to use the target default. An unknown alias or a model on a denylist fails before the child starts. Choosing a model outside `preferred_models` / `discouraged_models` is allowed as long as it is inside every hard model and effort limit.
 
 A resumed or retried subagent keeps its persisted binding unless the `AgentRun` `resume` explicitly requests a change. Omitting both `model_alias` and `effort` keeps the current binding; an explicit effort applies to the next idle run. `AgentRun` rejects `model_alias: "inherit"` on resume as well; specify a concrete model name for an explicit change, or omit it to keep the saved model. Switching to a different canonical model requires `allow_model_change: true`; an alias resolving to the same canonical model is a no-op.
 
 ## Agent files and routes
 
-Agent files and profile route sidecars pin models with `model_alias`; a main-agent profile cannot use `inherit` because it has no caller. The legacy `model_preference` field is explicitly rejected with a migration diagnostic; unknown `model` metadata written by other tools also fails closed. Remove unsupported fields instead of relying on them being ignored.
+Agent files and profile route sidecars pin models with `model_alias`; a main-agent profile cannot use `inherit` because it has no caller. A legacy `model_preference` field is rejected with a migration message, as is unknown `model` metadata left behind by other tools — remove fields that are not supported rather than expecting them to be ignored.
 
-A route-declared `model_alias` is a soft default. For subagents, an executable, hard-permitted override stays tied to the route, is marked detached, and carries an advisory. `allowed_models`, `deny_models`, and `allowed_efforts` are hard in profiles, leases, `spawn_constraints`, and matching `model_profiles`; a violation rejects subagent binding, manual changes, and resume. In a main session, user selections override profile model / effort rules: hard violations only warn, and recommendation or pin deviations do not warn or block sending. Only `preferred_models`, `discouraged_models`, and `preferred_efforts` are recommendations. Machine `[subagent].deny_models` adds another hard boundary. Native model lists compare canonical identities; external executors compare actual effective model IDs.
+A route-declared `model_alias` is a soft default, and `preferred_models`, `discouraged_models`, and `preferred_efforts` are recommendations. `allowed_models`, `deny_models`, and `allowed_efforts` are hard limits: in a subagent, going outside them rejects the binding, a manual change, or a resume. In a main session your own selection wins, and a violation only warns. `[subagent].deny_models` adds a further hard limit. Native model lists compare canonical identities; external executors compare the effective model IDs they actually call.
 
 ## Settings by identity
 
@@ -41,13 +41,11 @@ A model carries one set of shared settings: its default thinking effort, service
 - **Main agent**: applies when the model is used as the main agent, whichever profile happens to hold it. An unset field inherits.
 - **Externally delegated agent**: applies to agents delegated in from an external host. An unset field inherits.
 
-Identity is who the model is serving, not which profile is selected, so switching profiles does not drop this layer. Overriding a prompt or cognition field is a different mechanism: those replace a whole group of values, while a setting above merges one field at a time. The two do not change each other.
+Identity is who the model is serving, not which profile is selected, so switching profiles does not drop this layer. Overriding a prompt or cognition field is a different mechanism: those replace a whole group of values, while a setting here changes one field at a time. Clearing an override returns the field to the shared value. `usage_effective` and `usage_sources` report the value each identity resolves to and where it was read from; they describe the model's own resolution, and do not include a profile pin or a session override.
 
-A cleared override goes straight back to the shared value. `usage_effective` and `usage_sources` report the value each identity resolves to and where it was read from; they describe the model's own resolution, and do not include a profile pin or a session override.
+The context budget and the generated-token ceiling are caps, not preferences: the effective value is the lower of the shared cap and any identity value, so an identity can tighten them but never raise them past what the model allows.
 
-The context budget and the generated-token ceiling are caps, not preferences: the effective value is the lower of the shared cap and any identity difference, so an identity can tighten them but never raise them past what the model allows.
-
-In Settings › Models, the model editor opens on the shared values; switch to Main agent to see and edit only that identity's differences, and the editor shows what each field inherits and what it resolves to. A model on a server without this layer simply has no difference to edit.
+In Settings › Models, the model editor opens on the shared values; switch to Main agent to see and edit only that identity's differences, and the editor shows what each field inherits and what it resolves to.
 
 ## Model ID resolution
 

package/dist/docs/en/reference/slash-commands.md

@@ -14,7 +14,7 @@ Some commands are only available in the idle state. Executing these commands whi
 | --- | --- | --- | --- |
 | `/login` | — | Select an account or platform and log in: Kimi Code uses OAuth device-code flow; Kimi Platform uses API key login | No |
 | `/logout` | — | Clear credentials for the currently selected account | No |
-| `/provider` | — | Open the interactive provider manager to view, add, and remove configured providers. See [Platforms & Models — `/provider` and provider management](../configuration/providers.md#provider-—-interactive-provider-management) | Yes |
+| `/provider` | — | Open the interactive provider manager to view, add, and remove configured providers. See [Providers and models — `/provider`](../configuration/providers.md#provider-—-interactive-provider-management) | Yes |
 | `/model` | — | Switch the LLM model used in the current session | Yes |
 | `/settings` | `/config` | Open the settings panel inside the TUI | Yes |
 | `/experiments` | `/experimental` | Open the experimental feature panel | Yes |
@@ -130,7 +130,7 @@ All built-in Skill commands are only available in the idle state.
 
 Activated external Skills are automatically registered as slash commands. Ordinary external Skills use the `skill:` namespace prefix:
 
-```
+```text
 /skill:<name> [extra text]
 ```
 
@@ -138,7 +138,7 @@ For example, `/skill:code-style` loads the Skill named `code-style` and sends it
 
 External sub-skills appear directly in the slash command panel with dotted names:
 
-```
+```text
 /<parent-skill>.<sub-skill> [extra text]
 ```
 
@@ -146,7 +146,7 @@ For example, a child Skill named `review` inside a parent Skill named `code-styl
 
 For convenience, external Skill commands also support a shorthand form that omits the `skill:` prefix — `/<name>` — as long as the name is not taken by a system slash command. That is, `/code-style` falls back to matching `/skill:code-style`.
 
-::: info
+::: tip
 All Skill commands are only available in the idle state. `flow`-type Skills are also exposed via `/skill:<name>` — there is no separate `/flow:` namespace.
 :::
 

package/dist/docs/en/reference/tools.md

@@ -17,7 +17,11 @@ File tools handle reading, writing, and searching the local filesystem — the f
 | `Glob` | Auto-allow | Find files by glob pattern |
 | `ReadMediaFile` | Auto-allow | Read an image or video file |
 
-**`Read`** accepts a file path (`path`) plus optional `line_offset` (starting line number; negative values count from the end) and `n_lines` (maximum number of lines to read). Returns at most 1000 lines or 100 KB per call; content beyond that limit is accompanied by a truncation notice. UTF-8 and UTF-16 text are supported; UTF-16 is converted for display. The result shows line numbers and reports original line endings; a pure CRLF file appears as LF in `Read`, and `Edit` preserves CRLF when using that view. Mixed line endings require matching the visible `\r` characters exactly. If the file is an image or video, the tool suggests using `ReadMediaFile` instead. An explicit absolute path can read outside the workspace, subject to sensitive-file approval. Registered user skill and agent definition roots (including linked installations) are readable by default; ordinary workspace links to external files require approval. Only `~/.kiki/agents`, `skills`, `commands`, and `docs` under `~/.kiki` are treated as definition or documentation roots; other paths there require explicit paths and remain subject to sensitive-file rules.
+**`Read`** accepts a file path (`path`) plus optional `line_offset` (starting line number; negative values count from the end) and `n_lines` (maximum number of lines to read). Returns at most 1000 lines or 100 KB per call; content beyond that limit comes with a truncation notice. UTF-8 and UTF-16 text are supported, with UTF-16 converted for display. If the file is an image or video, the tool suggests using `ReadMediaFile` instead.
+
+The result shows line numbers and reports the original line endings. A pure CRLF file appears as LF in `Read`, and `Edit` preserves CRLF when you edit that view; a file with mixed line endings needs the visible `\r` characters matched exactly.
+
+An explicit absolute path can read outside the workspace, subject to sensitive-file approval. Registered user Skill and agent definition roots (including linked installations) are readable by default, while an ordinary workspace link to an external file requires approval. Under `~/.kiki`, only `agents`, `skills`, `commands`, and `docs` count as definition or documentation roots; other paths there still need an explicit path and remain subject to the sensitive-file rules.
 
 **`Write`** accepts `path`, `content`, and an optional `mode` (`overwrite` or `append`; defaults to overwrite). Missing parent directories are created automatically; `append` mode appends content to the end of the file without automatically adding a newline.
 
@@ -48,7 +52,11 @@ Use `offset` (default 0) and `head_limit` (default 100) to page through matching
 
 When a command is only a file read, search, or text-file write, `Bash` still runs it but may append a one-line hint pointing to `Read`, `Grep`/`Glob`, or `Write`/`Edit`. Each hint category appears at most three times per session. Set `bash_file_tool_hints = false` under [`[background]`](../configuration/config-files.md#background) to suppress these hints; execution and approval behavior are unchanged.
 
-Foreground mode blocks the current turn until the command completes or times out, and the TUI streams stdout and stderr into the running `Bash` tool card while the command is still active. By default, a foreground command that hits its timeout is not killed — it keeps running as a background task (bounded by the 600s default background timeout, i.e. a command auto-backgrounded on timeout gets a fresh 600-second budget); to restore kill-on-timeout, set [`bash_auto_background_on_timeout`](../configuration/config-files.md#background) to `false` under `[background]`. The 600s background default is configurable via [`bash_task_timeout_s`](../configuration/config-files.md#background) (`0` = no timeout) and defaults to no timeout in print mode (`kiki -p`). Background mode returns a task ID immediately and automatically notifies the Agent when the task finishes. stdin is always closed — interactive commands receive EOF immediately. A two-phase termination strategy (SIGTERM → 5-second grace period → SIGKILL) ensures reliable process cleanup when a task is stopped or hits its background timeout. On Windows, Git Bash is used by default.
+**Foreground** mode blocks the current turn until the command completes or times out, and the TUI streams stdout and stderr into the running `Bash` tool card while the command is still active. **Background** mode returns a task ID immediately and automatically notifies the Agent when the task finishes.
+
+A foreground command that hits its timeout is not killed by default: it keeps running as a background task, with a fresh copy of the 600s background budget. Set [`bash_auto_background_on_timeout`](../configuration/config-files.md#background) to `false` under `[background]` to kill timed-out foreground commands instead, and change the background budget itself with [`bash_task_timeout_s`](../configuration/config-files.md#background) (`0` = no timeout; print mode defaults to no timeout).
+
+stdin is always closed, so an interactive command receives EOF immediately. A stopped or timed-out task is terminated with SIGTERM, then SIGKILL after the 5-second grace period. On Windows, Git Bash is used by default.
 
 ## Dynamic tools
 
@@ -60,23 +68,33 @@ If no deferred MCP or plugin tools are active, neither `SelectTools` nor `CallTo
 
 `HistorySearch`, `HistoryRead`, and `HistoryList` are resident built-in tools in the `history` group. When enabled, they are included directly in the tool list and can be called without `SelectTools`. They read transcript history under the existing workspace access policy; a source `ref` identifies evidence, not a permission grant.
 
-**Migration from the earlier Search default:** `HistorySearch({"query":"distinctive words"})` now searches the current session and current agent with `mode: "auto"` (complete phrase matching). It previously defaulted to workspace-wide token-AND search. Existing windows holding the older tool description use the new default as well; tool execution is not pinned to the schema version the model saw. Every Search result echoes `scope_used`, `mode_used`, and `target`. When a session-scoped page has fewer hits than its limit, `expand_hint.next_call` shows a ready-to-use `scope: "workspace"` retry; for auto/all/any it explicitly selects indexed `mode: "terms"` (token-AND), so the response echoes that changed matching mode. To preserve the old search deliberately, pass `{"scope":"workspace","mode":"terms"}`; `scope: "this_session"` remains a locked-current-session alias. Choose another `session_id` explicitly for a known older session, and name an `agent_id` or `include_subagents` when expanding the agent range. Check `coverage` and `next_cursor`: a partial empty page means the scanned or indexed domain is incomplete. A scan cursor resumes a bounded segment; if it expires, restart the original query.
+`HistorySearch({"query":"distinctive words"})` searches the current session and current agent with `mode: "auto"` (complete phrase matching). Every result echoes `scope_used`, `mode_used`, and `target` — read them instead of assuming a default. To search the way earlier Kiki versions did, pass `{"scope":"workspace","mode":"terms"}`; `scope: "this_session"` remains a locked-current-session alias, and another `session_id` selects a known older session.
+
+When a session-scoped page has fewer hits than its limit, `expand_hint.next_call` gives you a ready-to-use `scope: "workspace"` retry; for `auto` / `all` / `any` it explicitly switches to indexed `mode: "terms"` (token-AND), and the response echoes that changed matching mode. Name an `agent_id` or set `include_subagents` to widen the agent range. Check `coverage` and `next_cursor`: a partial empty page means the scanned or indexed domain is incomplete. A scan cursor resumes a bounded segment, and if it has expired, restart the original query.
 
 For server transcript fallback, `sort: "newest"` and `"oldest"` order matching text by timestamp, with stable source-ID ties across pages; missing timestamps sort as zero. Navigation first prepares the current visibility through a fixed source watermark, so a cold large session may return empty `navigation_building` preparation pages before any hits. Continue with `next_cursor`; preparation and text reads share the same per-call budget. Once navigation is ready, newest-first search reads recent text spans directly rather than scanning the wire prefix.
 
-The default `sort: "relevance"` ranks lexical match scores only among the hits collected on the current bounded page: full-query matches and additional matching clauses raise the score, then newer timestamps and stable IDs break ties. Pages are scanned newest-first, not globally ordered by relevance; a later page may contain a stronger match. Partial pages disclose `page_local_relevance` in coverage. New scan cursors bind the request, source fingerprint, and navigation generation; appending, undoing, clearing, or rewriting the source invalidates them. Restart the query after an invalidation. Older scan cursors can still continue source-order scans and carry a warning to restart for sorted navigation.
+The default `sort: "relevance"` ranks lexical match scores only among the hits collected on the current bounded page: full-query matches and additional matching clauses raise the score, then newer timestamps and stable IDs break ties. Pages are scanned newest-first, not globally ordered by relevance; a later page may contain a stronger match. Partial pages disclose `page_local_relevance` in coverage.
+
+A new scan cursor pins the historical range this query started over. Normal appends to the source still allow paging, but the newly added content is not in this result set — re-run the query to see it. If the pinned source content changes, the query conditions change, or the shared navigation advances past this range, restart the query as the response instructs. Older scan cursors continue to read under their original compatibility rules.
+
+`HistorySearch` returns `source_changed` when it finds the source changing while a read is running; restart the query once its writer settles. That is distinct from a cursor you passed that no longer matches its source or query, which asks you to restart without it.
 
 Calls that omit the newer scope and mode arguments use the current session and `auto` matching. Read `scope_used` and `mode_used` in the response rather than assuming a historical default; when the result is too narrow, follow `expand_hint.next_call` and retry with `scope: "workspace"`.
 
-Use `HistoryList` to browse short turn excerpts or archived agents when you lack search words. A turn entry's `ref` opens the whole turn as source blocks with `HistoryRead`; `turn` and `step_id` also select bounded turn/step blocks. While the navigation directory is still being built, coverage reports the scanned portion. Use `HistoryRead({"step_id":"t42.3"})` for a known step. For a Search hit on a text block, `HistoryRead({"ref":"<hit.ref>"})` starts near the match. Each block includes its own `ref` and UTF-16 `range`; continue with `cursor`, or reopen a block with its `ref` and `start_char` set to the previous `range.end` if the cursor expires. A stale or removed source returns an error instead of another turn's content. Existing v1 Read cursors continue their legacy JSON paging; restart with a ref, turn, or step_id for blocks.
+Use `HistoryList` to browse short turn excerpts or archived agents when you lack search words. A turn entry's `ref` opens the whole turn as source blocks with `HistoryRead`; `turn` and `step_id` also select bounded turn/step blocks. While the navigation directory is still being built, the response is a `partial` preparation page that reports the scanned portion and carries a cursor — continue with it instead of assuming the list is complete. Use `HistoryRead({"step_id":"t42.3"})` for a known step. For a Search hit on a text block, `HistoryRead({"ref":"<hit.ref>"})` starts near the match. Each block includes its own `ref` and UTF-16 `range`; continue with `cursor`, or reopen a block with its `ref` and `start_char` set to the previous `range.end` if the cursor expires. A stale or removed source returns an error instead of another turn's content. Existing v1 Read cursors continue their legacy JSON paging; restart with a ref, turn, or step_id for blocks.
+
+`HistoryRead` reports a normal `partial` read with the blocks it scanned and a cursor to continue. `no_match` means the scan finished and the selector has nothing there. `source_pending` means the persisted transcript ends in an unfinished record, so the lookup cannot yet say whether the selector matches; retry it once the writer settles. When the navigation directory is still being prepared, the same `partial` status comes back with a preparation cursor and progress, and an empty block list there means not scanned yet, not absent — continue with that cursor before reading it as `no_match`. If the agent's persisted transcript is unavailable altogether, the error points you at `HistoryList` with `kind: "agents"` to check the agent id. A source that has changed returns an error rather than another turn's content.
 
-To search only cross-thread messages, use `HistorySearch({"query":"handoff","scope":"peer"})`. This searches both directions within the current workspace, or the explicitly approved `workspace_id`; optional `session_id` narrows to one session. Peer search reuses the lexical matching modes but is newest-first: omit `sort` or use `"newest"`. It excludes subagents and ordinary user input, does not accept `source: "transcript"`, and accepts only `agent_id: "main"` when an agent is specified. The response has `source: "mailbox"`; hits carry `communication` metadata with message identity, endpoints, and delivery state, without fabricated transcript turn numbers or HistoryRead refs. Use the [communication-history REST read](../server/rest-api.md#communication-history) for the full message and navigation identity. Continue a partial or empty page using `next_cursor`; the view covers retained mailbox records, not older messages already evicted by previous versions.
+To search only cross-thread messages, use `HistorySearch({"query":"handoff","scope":"peer"})`. It searches both directions within the current workspace, or the explicitly approved `workspace_id`; an optional `session_id` narrows to one session. Peer search reuses the lexical matching modes but is newest-first, so omit `sort` or use `"newest"`. It excludes subagents and ordinary user input, does not accept `source: "transcript"`, and accepts only `agent_id: "main"`.
+
+The response has `source: "mailbox"`; hits carry `communication` metadata with message identity, endpoints, and delivery state. Use the [communication-history REST read](../server/rest-api.md#communication-history) for the full message and navigation identity. Continue a partial or empty page using `next_cursor`; the view covers retained mailbox records, not older messages already evicted by previous versions.
 
 In non-interactive prompt runs (`kiki -p`), `HistoryList` reads a bounded prefix of the persisted transcript without starting a server or search worker: at most 2 MiB, 10,000 records and 256 KiB per record; agent rosters inspect at most 256 directory entries. Results explicitly report `partial` coverage and do not contain navigation `ref` values. You can list the current session or specify another persisted `session_id`. `HistorySearch` and `HistoryRead` remain unavailable in this print host; use an interactive session or the server for indexed search and full history reads.
 
 ## Web Tools
 
-Both web tools are backed by Kiki's built-in search and retrieval module, which ships with the product — there is nothing to install. A keyless repository-search lane and the URL fetch chain work without configuration; for broader web search, choose another lane. See [`nb_search`](../configuration/config-files.md#nb-search) for configuration.
+Both web tools are backed by Kiki's built-in search and retrieval module, which ships with the product — there is nothing to install. General-web search and URL fetching work without configuration or an API key. See [`nb_search`](../configuration/config-files.md#nb-search) for configuration.
 
 | Tool | Default Approval | Description |
 | --- | --- | --- |
@@ -87,7 +105,7 @@ Both web tools are backed by Kiki's built-in search and retrieval module, which
 
 Search the web through Kiki's built-in search and retrieval module (`nb-search`). The minimal call is `{ "query": "search terms" }`, which selects `action: "run"` and lets everything else fall back to your `[nb_search]` defaults. `query` may be a single string or an array of strings.
 
-Without configuration, this call uses `github.repositories`: results cover GitHub repositories, not the general web. Choose `context7.docs` for library documentation (a typed result), or explicitly select `duckduckgo.search` for keyless general-web results; the public HTML endpoint may issue a CAPTCHA. A configured provider such as `exa.search` is preferable when reliable broad coverage matters. If the default lane is explicitly removed, the tool still fails closed unless a `lane`, `lanes`, or `preset` is named. Explicit selections override the default and never silently switch providers when invalid or unavailable.
+Without configuration, this call uses `duckduckgo.search` for general-web results, with no registration, API key or lane selection. The public HTML endpoint may issue a challenge or rate limit; wait before retrying, or explicitly choose another configured source. These failures are errors, not empty results. Choose `github.repositories` for repository search or `context7.docs` for library documentation (a typed result). If the default lane is explicitly removed, the tool still fails closed unless a `lane`, `lanes`, or `preset` is named. Explicit selections override the default and never silently switch providers when invalid or unavailable.
 
 `run` accepts these parameter groups that actually change behavior:
 
@@ -192,7 +210,7 @@ The parent Agent's `Bash` calls still follow the current permission rules. Enter
 
 `notes` accepts only the changed sections: `goal`, `directives`, `decided`, `rejected`, `evidence`, `files`, `next`, and `open`. Each supplied string replaces its entire section, so include its still-valid conditions and exceptions. Omitted sections remain unchanged; `""` deletes one section, `notes: null` clears all notes, and `notes: {}` changes no content. Each section is limited to 1,500 characters and the whole notebook to 7,500; an over-limit mixed call changes neither domain. Writes return a compact receipt with changed and cleared fields, revision, character counts, and todo status counts, not the full notebook. Use `{}` when you need the current contents.
 
-Main and child agents have separate lists and notes; the tool cannot read or update another agent's state. Both are restored with their owning agent and follow conversation undo. Context renewal preserves existing notes; a summary's candidate instructions are kept for review rather than written automatically. `review_handoff: true` explicitly acknowledges that the handoff and human input have been checked against current notes and original sources, through the current tool call. An ordinary section update does not acknowledge that review. Oversized candidates remain complete in the handoff with a visible notice, and unreviewed input is carried forward. In the GUI, unknown text sections retain their field names; unreadable updates show a warning and the last readable notes rather than an empty notebook. Historical shared lists remain with the main agent; earlier child lists are not reconstructed from tool messages.
+Main and child agents have separate lists and notes; the tool cannot read or update another agent's state. Both are restored with their owning agent and follow conversation undo, and context renewal preserves existing notes. `review_handoff: true` explicitly acknowledges that the handoff and human input have been checked against current notes and original sources; an ordinary section update does not acknowledge that review. Oversized candidates stay complete in the handoff with a visible notice, and unreviewed input is carried forward. Historical shared lists remain with the main agent.
 
 The task board is the persistent record of requirements that survives sessions. `BoardRead` supports `preview`, `list`, `show`, and `overview` for cards in the current workspace or other authorized workspaces. `BoardWrite` `create` always starts at `active`, so do not pass `status`; for `update`, include `status` only when changing the state. Valid states are `active`, `in_progress`, `paused`, `done`, `cancelled`, and `superseded`. `done`, `cancelled`, and `superseded` are terminal; reopen a terminal card by setting `status` back to `active`, `in_progress`, or `paused`, which clears its `completedAt`. Updates must use the card's current `revision`; after a conflict, reread the card before retrying.
 
@@ -206,7 +224,43 @@ Memory stores what a session does not keep. Agents save durable facts with `Memo
 
 When a proposed update or archive is held for review, the original entry keeps its current content and stays in effect until you decide. Accepting the proposal applies the update or archive to that original entry; discarding it removes only the proposal and leaves the original untouched. If the original entry has changed since the proposal was made, the decision is refused, the proposal is kept, and you are asked to read the entry again.
 
-For the three-scope model, the review inbox, the undoable change history, and the `/memory` page, see [Memory](../guides/memory.md).
+### Writing an entry
+
+`MemoryWrite` takes one `action` per call:
+
+- **`create`** — a genuinely new subject. Requires `type`, `title`, `body` and `reason`; omits `id` and `expected_revision`. Without an explicit `scope` it lands in the bound persona, otherwise the workspace.
+- **`update`** — revise the entry in place, keeping its id and the conditions that still hold. `body` is the complete new content, not a patch.
+- **`supersede`** — write a replacement with its own id and retire the predecessor only once the replacement is active. This is the right choice for a rule that genuinely changed, and it keeps both versions readable.
+- **`archive`** — retire an entry, preserving its stored content. Send only the target and `reason`; the type, title and body fields are ignored.
+
+`update`, `supersede` and `archive` need `id` **and** `expected_revision` — the revision from a read result, a search item, or an earlier receipt. Without it the call is refused rather than applied to a version you have not seen. The same id can exist in more than one visible scope; an explicit `scope` limits the lookup, and an omitted one must resolve to exactly one target or the call reports the candidates instead of choosing.
+
+Two optional fields record what the content is resting on, and both are omitted or preserved rather than defaulted:
+
+- **`basis`** — `{ kind, note, refs? }` where `kind` is `human`, `observed`, `derived` or `unknown`. It records the evidence for the content, separately from the writer that the system records automatically; a write that runs in your turn is not automatically attributed to you. Omitting it on an `update` keeps the current basis only if the type, title and body are unchanged. Rewrite any of those without supplying a new basis and the entry is downgraded to `{ kind: 'unknown' }` with a `content changed without refreshed attribution` warning, so a stale attribution cannot survive the text it described.
+- **`validity`** — `{ check, until? }`, for content that changes. Omitting it on an `update` keeps the existing value; sending `null` clears it deliberately. A missing `validity` does not mean the content is permanently true.
+
+`covered_by` applies to `archive` only, and takes `{ id, expected_revision }` of a retained active entry in the same scope whose content fully covers the target's. The dependency is re-checked inside the write when the retirement is applied, so retiring an entry against a replacement that has since changed fails with `covered_target_changed` instead of losing the rule.
+
+A successful call returns the full stored (or proposed) entry together with an `outcome`:
+
+| Outcome | What it means |
+| --- | --- |
+| `applied` | The write took effect. The returned entry is the current read — do not re-read it just to confirm. |
+| `pending` | The write is a proposal awaiting your decision. The entry it targets is unchanged and still in effect. |
+| `unchanged` | Nothing in the submitted write differed from what is stored. No new revision and nothing to undo were created. |
+
+`operation_id` is `null` for `unchanged`, and for a repeated identical pending request, which is how a duplicate proposal is recognized rather than stacked.
+
+Failures come back as structured errors with a `code`, a message and recovery guidance — `missing_revision`, `revision_conflict`, `not_found`, `ambiguous_target`, `scope_mismatch`, `covered_target_changed`, `duplicate_title` and others. The intended response is to follow the recovery, re-read if needed, and make one corrected attempt; creating a second entry to get around a refused write is what these codes exist to prevent. A target you cannot see is reported as unavailable rather than written on someone else's behalf.
+
+### Searching and reading
+
+`MemorySearch` takes `mode: "search"` (the default, requires `query`) or `mode: "list"` (no query, browses the inventory). `page_size` is 1–20 and defaults to 8 for search and 20 for list; continue with `cursor` alone, and changing any filter invalidates it. Each item carries the full title, type, status, revision, owning scope, a `target` whose fields can be copied straight into `MemoryWrite`, `basis_kind` and an `applicability` of `expired`, `recheck` or `unrecorded`. The response's `coverage` states which scopes and statuses were inspected and whether anything was skipped. Continue empty preparation pages while `exhausted` is false; scan budgets do not cut off the remaining source. Search ranking is local to each bounded source chunk. Search also returns a `snippet` of at most 200 characters and a `score`; list returns neither. A snippet omits conditions, so read before you rely on, merge, or replace an entry.
+
+`MemoryRead` takes exactly one of `id` or `ids` (up to 10), reads active, archived and replaced entries by default, and includes pending proposals only with `include_pending: true`. The result is the complete entry — not a summary — with its owning scope, target fields and applicability, so a read can be the source for an `update`.
+
+For the three-scope model, the review inbox, the undoable change history, and the `/memory` page, see [Memory](../guides/memory.md). For the same data over HTTP, see [Server API](../server/rest-api.md#memory).
 
 ## Collaboration Tools
 
@@ -214,7 +268,7 @@ Main agents receive five thread tools by default: `ThreadCreate`, `ThreadList`,
 
 Omitting `host_id`, leaving it empty, or using `"local"` addresses the executing agent's home, not the space currently open in the GUI. Same-home communication can cross workspaces. Another local or remote space requires an owner-approved one-way [thread bridge](./command.md#kiki-bridges); use its returned host-qualified reference and `bridge_id` or `connection_id`. Identical session IDs in different homes remain different threads. GUI browsing permission does not grant bridge permission.
 
-- `ThreadCreate` is for an explicit user request to create a new thread or session, not for routine delegation. Optional `cwd` must be an absolute path to an existing directory, including a directory outside the current workspace; omitted `cwd` uses the current session's workspace root. Optional `profile` must name an enabled main-agent profile; omitted `profile` uses the default. Optional `prompt` (at most 100,000 characters) becomes the new thread's first user message and starts its turn immediately; without it, the thread stays empty until the user sends a message. Optional `title` overrides the default: if omitted with a prompt, the first line (up to 80 characters) becomes the title; without a prompt, the session uses its default name. The result returns `id`, `title`, `cwd`, `profile`, and `prompt_started`. The new thread appears in the left session list within a few seconds; use `ThreadSend` and `ThreadWait` to continue interacting with it.
+- `ThreadCreate` is for an explicit user request to create a new thread or session, not for routine delegation. Optional `cwd` must be an absolute path to an existing directory, including one outside the current workspace; omitted `cwd` uses the current session's workspace root. Optional `profile` must name an enabled main-agent profile; omitted `profile` uses the default. Optional `prompt` (at most 100,000 characters) becomes the new thread's first user message and starts its turn immediately; without it, the thread stays empty until the user sends a message. Optional `title` overrides the default: with a prompt and no title, the first line (up to 80 characters) becomes the title. The result returns `id`, `title`, `cwd`, `profile`, and `prompt_started`; the thread then appears in the left session list within a few seconds, and `ThreadSend` and `ThreadWait` continue the conversation.
 - `ThreadList` lists enabled, unarchived sessions, optionally filtered by `workspace_id`. With no bridge selector it lists the executing home; with a selector it lists only the approved target scope and requires `read`. Local results are newest first. `limit` defaults to 50 and accepts 1–100; use the returned opaque cursor for another page.
 - `ThreadRead` reads completed main-agent turns locally without resuming a cold session. Across a bridge it requires `read` and returns a bounded `view.transcript` page with coverage and cursors; omitted text or frames carry `contentRefs`. Pass a returned reference as `content_ref` to read its next bounded `view.segment`. `limit` defaults to 20 and accepts 1–100.
 - `ThreadSend` durably saves an explicit message and records the executing main-agent session as its verified source. Supply the target, non-empty `content` of at most 100,000 characters, and `idempotency_key` of at most 256 characters. There is no source parameter; reuse a key only for the same message. A bridge needs `send`, plus `wake` to deliver into a model prompt or resume a cold thread; without wake it stays pending. `delivered` confirms prompt delivery, not a reply. Pending records retry with the original key for up to 15 minutes; use bridge receipts to inspect rejection reasons. Ordinary assistant text is never forwarded automatically.
@@ -227,7 +281,7 @@ Only `ThreadSend`, called by the source thread's main Agent, records peer attrib
 
 On Kiki desktop and the `kiki` CLI/TUI, the main `agent` profile always receives `AgentRun`, `AgentList`, and `AgentSend`. These tools address only the caller's direct children — by the optional `name` passed to `AgentRun`, or by agent id. They are not behind an experiment. The built-in [`coder` and `explore` profiles](../customization/agents.md) do not receive them.
 
-`AgentList` returns those direct children and never lists grandchildren. `AgentSend` queues a mailbox message that is delivered as early as possible: when the child is running, the message is steered into its active turn at the next step boundary; when the child is idle (or a race just ended its turn), it stays queued and is read at the beginning of the child's next step.
+`AgentList` returns those direct children and never lists grandchildren. `AgentSend` queues a mailbox message for a direct child, and what happens to it depends on the child's state — the `AgentSend` entry further down this page has the detail.
 Collaboration tools handle inter-Agent coordination, user interaction, and Skill invocation.
 
 | Tool | Default Approval | Description |
@@ -238,7 +292,30 @@ Collaboration tools handle inter-Agent coordination, user interaction, and Skill
 | `AskUserQuestion` | Auto-allow | Ask the user a question to gather structured input |
 | `Skill` | Auto-allow | Invoke a registered inline Skill |
 
-**`AgentRun`** delegates a subtask to a sub-Agent. Required parameters are `prompt` and `description` (a short 3-5 word task description for UI display). Optional launch parameters include `profile` (when omitted, an explicitly configured `[subagent].default_profile` selects that profile; with no such key, the built-in general-purpose subagent prompt is used; an explicit blank value requires a target), `profile_file` (an explicit role Markdown file, absolute or workspace-relative; it is not a shared prompt template and is mutually exclusive with `profile`, `route`, and `resume`), `background` (omitted: background for main, foreground for subagents; explicit `false` waits synchronously), `name` (a session-unique handle of lowercase letters, digits, and underscores; `root` is reserved), `route`, `model_alias`, `effort`, and `allow_model_change` for an explicit model change on `resume`. Two optional parameters override this child's tools for one binding: `tools` replaces the resolved tool selection (a lone `*`, or `["*", ThreadRead]`, keeps the ordinary tools and adds that opt-in, while a finite list stays finite), and `disallowed_tools` adds a call-level deny. Omit both and a new child uses the configured default while a `resume` keeps its saved overrides; an explicit value replaces that layer, and `disallowed_tools: []` clears only the call-level deny, never a profile, ancestor, or route deny. Both need the native executor: an external executor that does not support them fails before the child starts. A new spawn selects its model in order: concrete `model_alias` parameter → effective profile, route, or caller-lease pin → explicitly configured `[subagent].default_model`. With none of these sources it fails with `model.not_configured` and no child is created. The caller's model and main-agent `default_model` are not silent fallbacks. `AgentRun` rejects `model_alias: "inherit"`: specify a concrete configured model name, or omit the parameter to use the target default. A subagent profile, route, or caller lease may still set `model_alias: inherit` to bind the caller's current resolved model and effective thinking effort unless tool `effort` or an applicable profile, route, lease, or matching `model_profiles` effort pin takes priority. Otherwise, effort resolves through tool `effort` → matching `model_profiles` effort → profile `thinking_effort` when the bound model matches its pin → the bound model's own default. An unknown concrete `model_alias` is an error; a main-agent profile cannot use `inherit` because it has no caller. `resume` continues an existing direct child by name or agent id, is mutually exclusive with `name`, `profile`, `profile_file`, and `route`. Omit both `model_alias` and `effort` to keep the saved binding, or pass `effort` to apply it on the next idle run. `AgentRun` also rejects `model_alias: "inherit"` on resume; use a concrete model name for an explicit change. Omit `model_alias` to keep the saved model; changing it to a different canonical model requires `allow_model_change: true`, while an alias resolving to the same canonical model is a no-op. `preferred_models`, `discouraged_models`, `preferred_efforts`, and route/caller-lease pins produce advisories for hard-permitted executable bindings. `allowed_models`, `deny_models`, and `allowed_efforts` are hard in profile, lease, tree, and matching model-profile scopes; binding, manual changes, and resume reject violations. Machine deny, unavailable capabilities, model-change confirmation, and executor/thread restrictions also remain hard. An external executor that does not support changing a resumed thread binding returns an error instead of recreating the thread or executor. Agent tasks time out after 2 hours by default; configure the global limit through `[subagent] timeout_ms` or `KIKI_SUBAGENT_TIMEOUT_MS` (`0` disables it), and print mode defaults to no timeout. There is no per-call timeout or arbitrary provider-parameter passthrough. In foreground mode the parent waits; in background mode a task ID returns immediately and the result is delivered automatically through a later synthetic User message. The TUI groups several foreground calls from one step and shows their status and elapsed time. See [Agents and Sub-Agents](../customization/agents.md) for the complete profile and lifecycle contract.
+**`AgentRun`** delegates a subtask to a sub-Agent. Required parameters are `prompt` and `description` (a short 3-5 word task description for UI display).
+
+| Parameter | Effect |
+| --- | --- |
+| `profile` | Which agent profile runs the subtask. Omitted, an explicitly configured `[subagent].default_profile` selects it; with no such key, the built-in general-purpose subagent prompt is used; an explicit blank value requires a target |
+| `profile_file` | A role Markdown file, absolute or workspace-relative. It is a role definition rather than a shared prompt template, and is mutually exclusive with `profile`, `route`, and `resume` |
+| `background` | Omitted: background for a main-agent call, foreground for a subagent call. An explicit `false` waits synchronously |
+| `name` | A session-unique handle of lowercase letters, digits, and underscores; `root` is reserved |
+| `route` | A profile route to run instead of a named profile |
+| `model_alias` | The model the child uses. See [model selection](./model-vocabulary.md#binding-rules) for the full resolution order |
+| `effort` | Thinking effort for this child |
+| `allow_model_change` | Required on `resume` to switch an existing child to a different model |
+| `tools` | Replaces the resolved tool selection for this binding only. A lone `*`, or `["*", ThreadRead]`, keeps the ordinary tools and adds that opt-in; a finite list stays finite |
+| `disallowed_tools` | Adds a call-level deny. `[]` clears only that layer, never a profile, ancestor, or route deny |
+
+Omit both `tools` and `disallowed_tools` and a new child uses the configured default, while a `resume` keeps its saved overrides. Both parameters need the native executor; an external executor that does not support them fails before the child starts.
+
+**Model and effort.** A new spawn picks its model in this order: the `model_alias` parameter → the pin on the effective profile, route, or caller lease → an explicitly configured `[subagent].default_model`. With none of these sources the call fails with `model.not_configured` and no child is created — the caller's model and the main-agent `default_model` are not silent fallbacks. `AgentRun` rejects `model_alias: "inherit"`, so pass a concrete configured model name or omit the parameter; a subagent profile, route, or caller lease can still set `model_alias: inherit` to follow the caller. Thinking effort otherwise resolves through the tool `effort` → the route's locked effort, or the caller lease's when the route pins none → a matching `model_profiles` effort → the profile's `thinking_effort` when the bound model matches its pin → the bound model's own default. With no declared effort, a model known not to support thinking uses `off`; a thinking model without a resolvable default still requires an explicit effort. Unknown capabilities do not imply `off`. See the [full binding rules](../customization/agents.md#named-profile-routes-experimental).
+
+`preferred_models`, `discouraged_models`, and `preferred_efforts` are recommendations, so a model outside them still runs. `allowed_models`, `deny_models`, and `allowed_efforts` are hard: binding, manual changes, and resume all reject a violation, as do machine-level deny rules and unavailable capabilities.
+
+**Resume.** `resume` continues an existing direct child by name or agent id, and is mutually exclusive with `name`, `profile`, `profile_file`, and `route`. Omit both `model_alias` and `effort` to keep the saved binding, or pass `effort` to apply it on the next idle run. `model_alias: "inherit"` is rejected here too — use a concrete model name to change models, and add `allow_model_change: true` when the change resolves to a different model. An external executor that cannot change a resumed thread's binding returns an error rather than recreating the thread.
+
+**Timeouts and modes.** Agent tasks time out after 2 hours by default; set the global limit with `[subagent] timeout_ms` or `KIKI_SUBAGENT_TIMEOUT_MS` (`0` disables it), and print mode defaults to no timeout. There is no per-call timeout. In foreground mode the parent waits; in background mode a task ID returns immediately and the result arrives later as a synthetic User message. The TUI groups several foreground calls from one step and shows their status and elapsed time. See [Agents and Sub-Agents](../customization/agents.md) for the complete profile and lifecycle contract.
 
 The `AgentRun` default follows the caller's runtime identity, not the target profile, and applies again on `resume`; goal mode does not change it. Main calls with omitted `background` or explicit `true` require `TaskList`, `TaskOutput`, and `TaskStop`; if they are unavailable, launch fails with guidance to enable them or retry with explicit `background:false`. No synchronous fallback is attempted. For a main foreground call, steer / Send now releases the wait into background without stopping the child. The next safe step reads the new input, and the child still delivers its completion notification. Ordinary queued input does not detach the wait. Stopping the current main turn is not the same as stopping detached children; use `TaskStop` to stop a tracked child explicitly.
 
@@ -248,9 +325,9 @@ A completion still reaches you automatically while a [goal](../guides/goals.md)
 
 **`AgentList`** lists direct children of the current agent. Optional `include_finished` defaults to false. A live child that is starting, running, or cancelling stays visible as `running`, even after its previous background task has completed or timed out. A broken live executor is `errored`; otherwise status follows the latest background task, or is `untracked` when there is no task record. Pass `true` to also include finished or errored children. At most 50 entries are returned, running first; `omitted` is the count that did not fit. Each entry includes `agent_id`, optional `name` and `profile`, and `status`. A `running` child does not necessarily have a tracked background task or a pending completion notification; use `TaskList` to inspect tracked work.
 
-**`AgentSend`** queues a non-empty `message` for a direct child identified by `target` (a `name` from `AgentRun`, or an agent id). A running child receives the message as soon as possible: it is steered into the child's active turn at the next step boundary. An idle resumable child starts a new run with the message, and that run's completion notifies the parent like any other agent task. If more than one direct child matches, or none do, the call fails — use `AgentList` and retry with an unambiguous value. A full mailbox means the child has too many unread queued messages; wait until it consumes some, then retry.
+**`AgentSend`** queues a non-empty `message` for a direct child identified by `target` (a `name` from `AgentRun`, or an agent id). A child that is running natively receives the message at the next step boundary, steered into its active turn. A child running on an external executor is not steerable, so the message waits and is picked up when its next run starts. An idle resumable child starts a new run with the message, and that run's completion notifies the parent like any other agent task. If more than one direct child matches, or none do, the call fails — use `AgentList` and retry with an unambiguous value. A full mailbox means the child has too many unread queued messages; wait until it consumes some, then retry.
 
-The result includes a `message_id` and a `queued` or `delivered` status. `queued` means accepted by the mailbox, not yet added to the recipient's context. Once the recipient's context is persisted and the mailbox acknowledges delivery, the sender's transcript records a delivery receipt and clears the GUI's pending-delivery label, even if the child's transcript is not open. The receipt survives reload and history replay; it confirms delivery, not that the child has acted on the message.
+The result includes a `message_id` and a `queued` or `delivered` status. `queued` means the mailbox accepted the message; delivery can complete concurrently, so it does not say the message is definitely still unread. `delivered` means the message reached the recipient's context and nothing more — not that the child has acted on it. `resumed: true` reports that a new run was actually observed starting; the field is omitted when no run start was observed, so its absence is not a negative answer. Once the recipient's context is persisted and the mailbox acknowledges delivery, the sender's transcript records a delivery receipt and clears the GUI's pending-delivery label, even if the child's transcript is not open. The receipt survives reload and history replay.
 
 **`AskUserQuestion`** asks the user a structured multiple-choice question — useful for disambiguation or option selection. The `questions` parameter accepts 1–4 questions; each question requires `question` (ending with `?`), `options` (2–4 choices, each with a `label` and `description`), and optional `header` (max 12 characters) and `multi_select` (defaults to false). An "Other" option is appended automatically. Setting `background` to true starts a background question task and returns a task ID immediately. When the host does not support interactive questioning, a failure message is returned and the Agent should ask the user directly in a text reply instead.
 

package/dist/docs/en/release-notes/changelog.md

@@ -6,7 +6,7 @@ outline: 2
 
 This page documents the changes in each Kiki release.
 
-::: info Note
+::: tip Note
 Early entries on this page originate from the upstream Kimi Code project and use the naming of their time. The command's current name is `kiki`; for environment variables, the exact names in [Environment variables](../configuration/env-vars.md) are authoritative.
 :::
 
@@ -15,7 +15,6 @@ Early entries on this page originate from the upstream Kimi Code project and use
 ### Polish
 
 - web: Settings gains a Lab tab with a new multi-tab sidebar toggle; when enabled, the sidebar shows the Open / Done / Workspaces tabs.
-- Make several refinements and internal improvements. See the [changelog on GitHub](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/CHANGELOG.md) for more technical entries.
 
 ## 0.37.1 (2026-08-18)
 
@@ -47,7 +46,6 @@ Early entries on this page originate from the upstream Kimi Code project and use
 - web: Fix Ctrl+K in the composer opening session search on macOS — session search now only answers to Cmd+K.
 - web: Fix the Background Agent panel showing incorrect task counts and statuses.
 - web: Fix pasting a copied folder into the composer failing the upload with a connection error — folders are now skipped instead.
-- Fix several known issues and make various refinements. See the [changelog on GitHub](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/CHANGELOG.md) for more technical entries.
 
 ## 0.36.1 (2026-08-14)
 
@@ -59,10 +57,6 @@ Early entries on this page originate from the upstream Kimi Code project and use
 
 - web: Polish the Plan, Goal, and Swarm toggles in the composer, which now live in the + menu next to the input box.
 
-### Bug Fixes
-
-- Fix several known issues and make various refinements. See the [changelog on GitHub](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/CHANGELOG.md) for more technical entries.
-
 ## 0.36.0 (2026-08-13)
 
 ### Features
@@ -93,7 +87,6 @@ Early entries on this page originate from the upstream Kimi Code project and use
 - Show project MCP launch targets in the workspace trust prompt, default to declining trust, and resolve `fd` and `stty` binaries to absolute paths so untrusted workspaces cannot plant bare-name executables before confirmation.
 - Fix sessions failing with a provider 400 error on every follow-up request after a turn is interrupted while the model is still thinking, on strict OpenAI-compatible providers (e.g. DeepSeek).
 - Fix Ctrl+C being ignored during automatic retries of failed API requests.
-- Fix several known issues and make various refinements. See the [changelog on GitHub](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/CHANGELOG.md) for more technical entries.
 
 ## 0.35.0 (2026-08-12)
 
@@ -107,7 +100,6 @@ Early entries on this page originate from the upstream Kimi Code project and use
 - Fix coder subagents spawning further subagents by default.
 - Fix the token counts reported after compaction reading far below the real context size; they now match the numbers shown while the session runs.
 - Fix two binary-planting risks on Windows.
-- Fix several known issues and make various refinements. See the [changelog on GitHub](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/CHANGELOG.md) for more technical entries.
 
 ## 0.34.0 (2026-08-06)
 

package/dist/docs/en/server/acp.md

@@ -28,7 +28,7 @@ The table below lists the capabilities declared by the current ACP adapter layer
 
 ## ACP Method Coverage
 
-The spec divides methods into a **stable** surface and an evolving **unstable** surface. The two have entirely different stability guarantees — the stable surface covers methods every production ACP client uses, while the unstable surface covers experimental extensions (inline-edit prediction, document buffer sync, provider management, elicitation, etc.) — so they are listed separately. All methods needed for a normal agent flow (initialize → auth → new/load/resume → prompt → cancel + file I/O + tool approval) are implemented.
+The spec splits methods into a **stable** surface and an evolving **unstable** surface, so they are listed separately. Everything a normal agent flow needs — initialize → auth → new/load/resume → prompt → cancel, plus file I/O and tool approval — is implemented.
 
 ### Stable agent-side — IDE → agent
 

package/dist/docs/en/server/ide.md

@@ -92,7 +92,7 @@ Paseo's generic ACP adapter does not drive the login flow, so complete the termi
 
 - **Session disconnects immediately / IDE shows "agent exited"**: usually a wrong `command` path or a missing login. Run `kiki acp` in a terminal first to verify — if it blocks waiting for stdin, the CLI itself is fine and the problem is in the IDE configuration; if it exits immediately with an error, follow the error message (most commonly you need to run `/login`).
 - **IDE shows "auth required"**: the CLI has no usable authentication token. Exit the IDE, run `kiki` in a terminal to complete login, then restart the IDE.
-- **MCP tools not visible**: check the [`kiki acp` reference](./acp.md) capability table to confirm that the MCP transport type configured in your IDE is supported. The Kiki ACP adapter currently supports `http`, `stdio`, and `sse` transports; `acp` transport MCP servers are silently dropped and a warning is written to the log.
+- **MCP tools not visible**: the `kiki acp` adapter accepts `http` and `sse` transports, and `stdio` only when the IDE is started with `--allow-client-stdio-mcp`. An `acp`-transport server is discarded with a warning in the log. See [MCP Forwarding](./acp.md#mcp-forwarding).
 
 ## Next steps
 

package/dist/docs/en/server/local-server.md

@@ -18,7 +18,7 @@ kiki serve --ensure --workspace . --json
 kiki serve --stop
 ```
 
-With no mode, `serve` runs the daemon in the foreground. `--query --json` only inspects the current instance; `--ensure` attaches to an existing healthy instance or starts one; `--stop` shuts down the reachable instance for the selected home. A live instance with unverifiable identity must be stopped or upgraded before Kiki will start another. `--idle-exit` defaults to `30m`; active client leases (periodically renewed indications that a client is still using the daemon) and running dispatches keep it alive. Explicit `--idle-exit 0ms` keeps a newly started daemon running until explicitly stopped. The TUI performs the same attach-or-start behavior after workspace trust.
+With no mode, `serve` runs the daemon in the foreground. `--query --json` only inspects the current instance; `--ensure` attaches to an existing healthy instance or starts one; `--stop` shuts down the reachable instance for the selected home. If a live instance's identity cannot be verified, stop or upgrade it before Kiki will start another. `--idle-exit` defaults to `30m`; active client leases (periodically renewed indications that a client is still using the daemon) and running dispatches keep it alive. Explicit `--idle-exit 0ms` keeps a newly started daemon running until you stop it. The TUI attaches or starts the same way after workspace trust.
 
 ## Run the compatible foreground server
 
@@ -50,14 +50,14 @@ For a trusted local client, carry the local-owner capability as follows:
 
 - **REST**: the `Authorization: Bearer <token>` request header.
 - **Kiki GUI**: the URL in the startup banner carries a `#token=` fragment, so opening it in a browser completes sign-in automatically. The fragment is never sent to the server.
-- **WebSocket**: clients that can set headers use `Authorization: Bearer`; clients that cannot (such as browsers) pass the subprotocol (a protocol name declared during the WebSocket handshake) `kimi-code.bearer.<token>` (a historical protocol name kept from the upstream Kimi Code era for compatibility).
+- **WebSocket**: clients that can set headers use `Authorization: Bearer`; clients that cannot (such as browsers) pass the token in the handshake subprotocol as `kimi-code.bearer.<token>`.
 
-If the remote owner token leaks, run `kiki web rotate-token`: it replaces `server.token`, invalidates the old remote credential and stops affected peer streams without a restart. This does not rotate `server.local-owner`; treat exposure of that local administrative capability as a compromise of local access, not as something fixed by remote-token rotation.
+If the remote owner token leaks, run `kiki web rotate-token`: it replaces `server.token`, invalidates the old remote credential and stops affected peer streams without a restart. It does not rotate `server.local-owner`, so treat exposure of that file as a compromise of local access.
 
 The desktop GUI first checks the instance registry and attaches to an existing server with its local-owner capability; only when none is found does it start its own sidecar. Supported local clients in the same home therefore share the same sessions, regardless of which launcher started the server.
 
 ::: warning Note
-This warning targets independently provisioned, mutually untrusted runtimes (for example, two services with distinct host identities and separate authority domains): do not point such runtimes at the same writable home, do not copy session directories between their homes, and do not copy `device_id` to make two homes impersonate the same host — session indexes, thread attribution, and permission boundaries all rely on the uniqueness of a home identity. The shared daemon, TUI, desktop GUI, and coexisting server instances within one home are supported ways of collaborating and are unaffected.
+Two independently provisioned runtimes that do not trust each other — separate services with their own host identity and authority domain — must not share a writable `KIKI_HOME`, must not copy session directories between their homes, and must not copy `device_id` to impersonate the same host. Session indexes, thread attribution, and permission boundaries all depend on a home having a unique identity. The shared daemon, TUI, desktop GUI, and coexisting server instances inside one home are supported and unaffected.
 :::
 
 Binding a non-loopback address (`--host`, including bare `--host`, which targets `0.0.0.0`) requires either a TLS-terminating reverse proxy in front of the server or `--insecure-no-tls`; without one of those the server refuses to start. Once it is running on a non-loopback address, you may set `KIKI_PASSWORD` as an additional owner credential; it does not replace the local-owner capability or the per-source grant. The server rate-limits authentication failures automatically.
@@ -84,7 +84,7 @@ kiki web --insecure-no-tls      # allow plain LAN HTTP (see the warning below)
 
 In the TUI the same operations are `/web temporary|persistent|status|off|link|revoke [id]`, with `--host`, `--port`, `--public-url`, `--insecure-no-tls`, and `--no-open`.
 
-Each run prints a single-use link that signs a browser in. Kiki redeems it for a session cookie held by the browser itself (HttpOnly, `SameSite=Strict`, host-only, `Secure` over HTTPS); no session or root token is ever placed in JavaScript, `localStorage`, or a URL query string. The link is shown once — the server keeps only a digest, so a lost link is replaced by a new one rather than looked up. An already-authorized browser keeps working across service restarts; a new device needs a new link.
+Each run prints a single-use link that signs a browser in. Kiki redeems it for a session cookie held by the browser itself (HttpOnly, `SameSite=Strict`, host-only, `Secure` over HTTPS); no session or root token is ever placed in JavaScript, `localStorage`, or a URL query string. The server keeps only a digest, so a lost link is replaced by a new one rather than looked up. An already-authorized browser keeps working across service restarts; a new device needs a new link.
 
 Turning Web access off revokes every link and every browser session, and closes the open streams. It does not stop the daemon, the desktop app, or the TUI, and it does not cancel work already started. `kiki serve` and the desktop app are unaffected either way.
 

package/dist/docs/en/server/mcp.md

@@ -2,7 +2,7 @@
 
 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open protocol that lets models safely call tools exposed by external processes or services — for example, reading GitHub issues, querying databases, or operating the local file system. Kiki acts as an MCP client to connect these external tools and exposes them to the Agent alongside built-in tools (`Read`, `Bash`, `Grep`, etc.) with no behavioral difference.
 
-MCP tool results can carry embedded media. When the current model cannot take an embedded image — because of its format or because the part is over the per-part size cap — the result keeps a text notice *and* saves the original into the session's media storage, so nothing is lost. The notice carries the saved file's absolute path and a `kimi-file://` reference; pass the path to `Read` or `ReadMediaFile` to inspect the original. A resource blob in a format Kiki does not deliver is preserved the same way. When the accumulated list of saved attachments would crowd the tool output, it is written to a text file and the output keeps a short pointer to it.
+MCP tool results can carry embedded media. When the current model cannot take an embedded image — because of its format or because the part is over the per-part size cap — Kiki keeps a text notice *and* saves the original into the session's media storage, so nothing is lost. The notice carries the saved file's absolute path and a `kimi-file://` reference; pass the path to `Read` or `ReadMediaFile` to inspect the original. A resource blob in a format Kiki does not deliver is preserved the same way. When the list of saved attachments would crowd the tool output, it is written to a text file and the output keeps a short pointer to it.
 
 ## Connection Methods
 
@@ -67,7 +67,7 @@ Optional fields:
 
 You do not have to set the connection timeout or the single tool-call timeout per server: `[mcp] startup_timeout_ms` / `[mcp] tool_timeout_ms` in `config.toml` or the `KIKI_MCP_STARTUP_TIMEOUT_MS` / `KIKI_MCP_TOOL_TIMEOUT_MS` environment variables change the global defaults. Precedence is: per-server field > environment variable > `config.toml` > built-in default. See [Configuration files](../configuration/config-files.md#mcp).
 
-HTTP and SSE servers support providing static credentials via `headers` or `bearerTokenEnvVar`. When OAuth is needed, run `/kiki-ops help me log in to MCP <server-name>` to complete browser-based authorization.
+HTTP and SSE servers support providing static credentials via `headers` or `bearerTokenEnvVar`. When OAuth is needed, run `/kiki-ops help me log in to MCP <server-name>` to complete browser-based authorization. If the server's authorization metadata says it supports `offline_access`, Kiki asks for that scope during login so the authorization can be refreshed later without a new sign-in; otherwise your original scopes are used as they are. A server that advertises the scope may still show an extra consent page, and does not guarantee it issues a refresh token. An already-signed-in server keeps its existing grant and goes on refreshing it — a new scope does not sign you out.
 
 Plugins can also declare MCP servers in their manifest. Servers declared by a plugin are enabled by default and can be disabled or re-enabled in `/plugins`: disabling or removing stops the tools in open sessions — calls fail with a removal notice — while re-enabling reconnects the server in open sessions immediately and restores its tools, as long as the server already existed when the session was created (this includes re-enabling an `enabled: false` entry in `mcp.json`). A brand-new server still follows the rule above: it only joins sessions created later. See [Plugins](../customization/plugins.md#mcp-servers-in-plugins) for details.