kiki-agent-lite 0.3.1 → 0.3.2

package/dist/docs/en/guides/memory.md

@@ -1,16 +1,32 @@
 # Memory
 
-Memory is what a session does not keep. Kiki saves your preferences, feedback, verified project facts, and reference pointers, and finds them again in a later conversation. It is on by default, it is stored only on the machine running Kiki, and every write is one line in the conversation. This page covers the choices the **/memory** page offers, the review inbox that can sit between an agent and a write, and how to turn memory off.
+Kiki remembers the things you would otherwise re-explain every session: how you like your code reviewed, which project fact you confirmed last week, where a reference lives. It is on by default, everything stays on the machine running Kiki, and every write shows up as one line in the conversation.
 
-If you are looking for what the agent can *do* in a single session — compression, the queue, the task board — see [Work that runs long](/en/features/long-work) instead.
+This page covers the scope choices on the **/memory** page, the review inbox that can sit between an agent and a write, and how to turn memory off. For what the agent does inside one session — compression, the message queue, the task board — see [Work that runs long](/en/features/long-work).
+
+::: warning Shared memory homes
+A Kiki older than 0.3.2 does not know the **Basis** and **Validity** fields below, and a write from that version can drop them from an entry. If two Kiki installations share one memory home — a desktop app and a CLI on the same `KIKI_HOME`, or a rollback to an earlier build — upgrade each of them to 0.3.2 or later. A field that has already been dropped is not restored for you: an entry that has lost one reads **Not recorded**, and putting it back means recording the basis or the check again from the original instruction or source material.
+:::
 
 ## What the agent remembers
 
-Memory is not a transcript and not a cache. It is the small set of durable facts you would otherwise have to re-explain: how you like your code reviewed, which project fact was verified last week, where the reference lives. Task progress belongs in the agent's working notes, not here.
+Memory is not a transcript and not a cache. It is the small set of durable facts that would otherwise be lost when a session ends; task progress belongs in the agent's working notes instead. An entry is one subject, held in one place: a short title you can recognize later and the **complete** current content, including the conditions that decide when it applies. The agent replaces content in full rather than appending to it, and keeps correction history and retired values in the change reason, not in the rule itself. The entry body is limited to 1,500 characters and a scope holds 300 active entries at a time; past either, the agent merges into existing entries instead of starting a new one. Replacing an active entry is still allowed at capacity when the final active count does not increase; a proposal is checked again when you approve it.
+
+Agents write with `MemoryWrite` and read back with `MemorySearch` and `MemoryRead`. Search matches partial terms, including Chinese phrases without spaces. Native subagents get the two read-only tools by default; `MemoryWrite` stays with the main agent.
+
+Search comes in two modes. The default searches for a subject, title or alias and returns a ranked page of 8; `mode: "list"` browses the inventory a page at a time, 20 entries per page, with no query. Both report which scopes and statuses were actually inspected, whether the result set is complete, and whether anything was skipped or unreadable. A cursor continues beyond each scan budget; even an empty preparation page must be continued while `exhausted` is false. Ranking is local to each bounded source chunk, not a global relevance ranking across all remaining entries. A search snippet is at most 200 characters and **omits the conditions** — before relying on an entry, merging it, or replacing it, the agent reads it in full, and a search that finds nothing only means no entry uses those words.
+
+In the main agent's `TodoList` notes, `directives` and `decided` can point at an entry by id, like `[m_id]`. At compaction the handoff carries each referenced entry's current title, follows replacements, and marks archived entries as withdrawn.
+
+## Where an entry came from, and when to check it
+
+An entry can record two things about itself, and both change how you should read it.
+
+**Basis** is the content's evidence: `human` (something you asked for or accepted), `observed` (checkable material or an observation), `derived` (Kiki's own inference or a relay of what someone else said), or `unknown`. The detail view spells each one out and shows the note and any source locators behind it. An older entry that has no basis recorded reads **Not recorded** — a gap in the record, not a judgment about the content. Once you have material you can check it against, ask Kiki to record the basis and the check for that entry; the fields are written through the memory tools, not by the editor on the **/memory** page. Kiki will not invent one, and it does not treat a line as yours just because the write happened in your turn.
 
-Agents write memory with `MemoryWrite` and read it back with `MemorySearch` and `MemoryRead`. Search accepts partial term matches, including Chinese phrases without spaces. Native subagents get the read-only `MemorySearch` and `MemoryRead` by default; `MemoryWrite` stays main-only.
+**Validity** is the check to run before trusting a changing fact. It carries a `check` describing what must be verified, and optionally an `until` timestamp. An entry with a check reads **Before relying on it: Check again**; one past its `until` reads **Past its endpoint** and stays on disk as a historical lead rather than a current premise; one with no recorded validity reads **No check was recorded**. Passing `until` never deletes or archives anything on its own.
 
-In the main agent's `TodoList` notes, `directives` and `decided` can reference an entry by its id, like `[m_id]`. At compaction the handoff carries the current title of each referenced entry, follows replacements, and marks archived entries as withdrawn. Resolving those references does not rewrite the saved notes or the frozen system prompt.
+Changing an entry's title, type or content on the page keeps its recorded basis and check. When the basis or the check needs to change, ask Kiki to update them at the same time. See [Built-in Tools](/en/reference/tools#memory-tools) for the tool-level contract.
 
 ## What the page lets you choose
 
@@ -20,40 +36,53 @@ On the `/memory` page you pick which body of memory you are looking at, and the
 - **Workspace** — one project's store.
 - **Persona** — one persona's own store, following that persona across profiles and models.
 
-Persona-specific entries are isolated from other personas. By default a persona can also read the shared global and workspace memory; set `memory.shared: []` on the persona card to exclude those. A workspace has its own switch that can follow the global setting, turn on, or turn off. Turning memory off in a workspace leaves saved entries in place — agents simply do not read or write them there.
+Persona entries are isolated from each other. By default a persona can also read the shared global and workspace memory; set `memory.shared: []` on the persona card to cut that off. A workspace has its own switch that can follow the global setting, turn on, or turn off — turning it off leaves the saved entries in place, agents just stop reading and writing them there.
 
-These are the choices the page offers, not a claim about how everything is stored: behind them a persona also has memory scoped to one workspace, so a persona working across projects can keep project-specific notes of its own.
+A persona can also keep notes scoped to a single workspace, which is how one persona working across several projects keeps project-specific detail of its own.
+
+A new entry without an explicit scope goes to the bound persona when there is one, otherwise to the workspace — and choosing a scope never moves an existing entry or widens access to another workspace or persona.
 
 ### Personas
 
-A persona's memory follows the identity rather than the project. It keeps following that persona when the profile or model changes, so switching models does not lose what it knows. Deleting a persona also removes its persona memory; if that cleanup fails, the deletion reports the error and keeps the card so you can retry. See [Personas, Bots, and rooms](/en/customization/personas#memory-and-character-cards).
+A persona's memory follows the persona, not the project, so it survives a change of profile or model. Deleting a persona deletes its memory too; if that cleanup fails, the deletion reports the error and keeps the card so you can retry. See [Personas, Bots, and rooms](/en/customization/personas#memory-and-character-cards).
 
 Entries are typed, and the type is what you filter by: **About you**, **Feedback**, **Project**, and **Reference**. An entry is also **pinned** (kept at the top), **active**, **replaced** by a newer entry, or **archived**.
 
+### Archived, replaced, and merged
+
+Retiring an entry is a state change, not a deletion: the text stays, and **Undo** still reaches it. An agent **replaces** an entry when a rule has genuinely changed, which writes a new entry with its own id and marks the old one **Replaced**, so the history of both remains readable. When the new entry fully covers the old one's content, the agent can retire the old one as **Merged into** the retained entry instead, and the detail view links straight to it; that link is re-checked at the moment the retirement is applied, so a merge cannot silently hide a rule whose replacement has since changed.
+
 ## The /memory page
 
-**/memory** is a permanent entry in the sidebar, whether memory is on or off — with it off, the page is the turn-on guide; with it on, it is the management console. You can search entries, filter by type, show or hide archived ones, and open an entry to read it, edit it, pin it, or delete it.
+**/memory** is always in the sidebar. With memory off it is the guide for turning it on; with memory on it is where you manage entries — search them, filter by type, show or hide archived ones, and open one to read, edit, pin or delete it.
 
-Workspace and Persona are searchable picks, because either list can run to hundreds; choosing one clears the other, and the choice rides a `?workspace=` or `?persona=` parameter so a link to a particular scope keeps working.
+Workspace and Persona are searchable pickers, since either list can run to hundreds of entries. Picking one clears the other, and the choice rides a `?workspace=` or `?persona=` parameter, so a link to a particular scope keeps working.
+
+The list and Inbox show available entries as they arrive and keep reading automatically until the namespace is covered. If a record cannot be read, the page keeps the readable entries and shows the diagnostic rather than claiming the list is empty. If continuation fails or the source changes, use **Retry** to reload. List previews stay short; opening an entry or **View** in Inbox loads its full content.
 
 ### Change history and undo
 
-Every change to an entry is recorded, and each history row opens the change with the before and after and an **Undo** for that one operation — including a delete. That is why the delete confirmation says you can undo it rather than that it is permanent.
+Every change to an entry is recorded. Each history row shows the before and after and offers **Undo** for that one operation, deletes included — which is why the delete confirmation says you can undo it.
+
+If the entry changed while you had it open, saving is refused and you are asked to reload first, so your edit cannot overwrite the newer version. Reload and re-apply what you meant to change.
 
-If an entry changed while you had it open, saving is refused with a notice to reload first, so your edit does not overwrite the newer version. Reload the entry and re-apply what you meant to change.
+Saving an entry that changes nothing — the same title, content, pin state and recorded attributes — produces no new version and nothing to undo, and the page says **No change**. Re-submitting an edit you already saved is the normal way to land here. Changing only the basis or the check is still a change, and does get its own version.
 
 ## The review inbox
 
 Memory approval has three settings. The default, **auto**, applies a write the agent proposes right away. Set it to **review** and a proposed update or archive waits for you. With `auto` there is nothing pending, so no **Inbox** tab appears at all.
 
-While a proposal waits, the original entry keeps its current content and stays in effect. **Keep** applies the proposal — an update replaces the text of the entry it supersedes, an archive archives that entry. **Discard** drops only the proposal and leaves the original untouched.
+While a proposal waits, the original entry keeps its current content and stays in effect. **Keep** applies the proposal — an update replaces the text of the entry it supersedes, an archive archives that entry. **Discard** drops only the proposal and leaves the original untouched. A proposal is not active guidance: it is not used as a premise, and an agent's own write cannot approve it, only you can.
 
 ## Turning memory off
 
-The **/memory** page has a single **Use memory** switch, and the same setting is available in the desktop app's settings. Turning it off stops agents from reading or writing memory. The periodic long-term-memory reminders are a separate thing: to stop only those while keeping the new-instruction and pre-compaction checks, set `memory_maintenance = false` in `config.toml`. That does not disable memory tools, approval, or task notes — see [Continuity reminder settings](/en/configuration/config-files#continuity-reminder-settings).
+The **/memory** page has a single **Use memory** switch, and the same setting lives in the desktop app's settings. Turning it off stops agents from reading or writing memory.
+
+The periodic long-term-memory reminders are separate. To stop just those while keeping the new-instruction and pre-compaction checks, set `memory_maintenance = false` in `config.toml` — the memory tools, approval and task notes stay available. See [Continuity reminder settings](/en/configuration/config-files#continuity-reminder-settings).
 
 ## Next steps
 
 - [Personas, Bots, and rooms](/en/customization/personas#memory-and-character-cards) — how persona memory follows a persona
 - [Work that runs long](/en/features/long-work#memory-keeps-the-facts-across-sessions) — the other long-work features
 - [Built-in Tools](/en/reference/tools#memory-tools) — the memory tools in full
+- [Server API](/en/server/rest-api#memory) — the same memory over HTTP

package/dist/docs/en/guides/sessions.md

@@ -1,10 +1,10 @@
 # Workspaces and sessions
 
-Kiki persists every conversation as a "session" — storing message history and metadata so you can close the terminal or the browser and pick up right where you left off. The desktop app, browser GUI, and CLI/TUI all read and write the same session data. This page covers how to manage workspaces and sessions, use the task board, resume and fork sessions, and export or compress context.
+Every conversation is saved as a session — its message history and metadata — so you can close the terminal or the browser and pick the work up later. The desktop app, the browser UI and the CLI/TUI all read and write the same sessions. This page covers workspaces, resuming and forking, the task board, compression and export.
 
 ## Session storage
 
-All sessions are saved under `$KIKI_HOME/sessions/` (default: `~/.kiki/sessions/`), grouped by working directory. You do not need to touch these files in daily use — they matter when you need to debug, troubleshoot, or back up sessions:
+Sessions are saved under `$KIKI_HOME/sessions/` (default: `~/.kiki/sessions/`), grouped by working directory. You never need to touch these files to use Kiki; they are here to read when you are debugging or backing up:
 
 ```text
 ~/.kiki/
@@ -28,27 +28,27 @@ All sessions are saved under `$KIKI_HOME/sessions/` (default: `~/.kiki/sessions/
 Do not manually edit files inside the `sessions/` directory — doing so may prevent sessions from being restored correctly.
 :::
 
-The desktop and browser GUI store new-session choices separately from this CLI directory. When draft persistence is enabled, the GUI remembers the selected model and effort, plus the workspace, working directory, and profile (the agent's configuration file), across navigation and browser refresh. A session's inherited model and a local override are distinct: changing the local effort does not silently replace the model inherited from the current session. The **Composer → Persist composer drafts** toggle in Settings controls whether these selections and the per-session draft text are written to this browser; turning it off clears the saved store. Drafts in the currently open page are unaffected by turning the toggle off; a refresh or restart starts with no restored selection.
-
-> The two GUI paragraphs above do not apply to CLI users — feel free to skip them.
+In the desktop and browser GUI, the model, effort, workspace, working directory and profile (the agent's configuration file) you pick for a new session can be remembered across navigation and refresh. Turn that on with **Composer → Persist composer drafts** in Settings; turning it off clears what was saved. Drafts in the page you currently have open survive the switch, but the next refresh starts with nothing restored. This is separate from the session files above, which is why the two behave differently.
 
 ## Task board
 
-Open the task board from the fixed button at the bottom of the main agent's right panel. The board is fully built into Kiki — no additional installation is needed. Cards organize requirements and their links to sessions, not running agents. Todo lists remain separate and local to each agent.
+The task board lives behind the fixed button at the bottom of the main agent's right panel. Cards hold requirements and the sessions linked to them; an agent's own todo list stays separate and local to that agent.
 
-Cards appear a page at a time; counts and search results cover the cards loaded so far while syncing continues. Switching workspace scope or closing the board cancels further page loading. In a new-card form, card details, or a confirmation, `Tab` stays inside the topmost dialog and `Esc` closes only that dialog, returning focus to its opener. Dialogs cannot be dismissed while their save or delete request is pending.
+Cards load a page at a time, so counts and search results cover what has loaded so far while syncing continues. Changing the workspace scope or closing the board stops further loading. In a card form, card detail, or confirmation, `Tab` stays in the topmost dialog and `Esc` closes only that dialog and returns focus to whatever opened it. A dialog cannot be dismissed while its save or delete is still in flight.
 
-Trust the workspace before creating or editing cards. Storage is controlled by the `taskBoard.storage` setting: `auto` reuses a compatible workspace store first, or uses `sessions/<workspaceId>/.board`; `global` uses the `boards` directory under the Kiki home; `fixed` uses an absolute path or a path relative to the workspace that you provide. Paths are not executed as scripts. Previewing a location does not create it or grant write access; save the configuration before creating there. Nonempty incompatible directories are rejected.
+Trust the workspace before you create or edit cards there. Where they are stored is set by `taskBoard.storage`: `auto` reuses a compatible workspace store if it finds one and otherwise uses `sessions/<workspaceId>/.board`; `global` uses the `boards` directory under the Kiki home; `fixed` uses an absolute path, or one relative to the workspace, that you provide. Previewing a path does not create it or give Kiki write access — save the setting first. A directory that exists but cannot hold a board is rejected.
 
-Changing the storage setting does not migrate cards; existing cards keep referencing their original store. If another edit wins, reload the card before retrying; failed edits retain the draft. The main agent can read and write the board with the `BoardRead` and `BoardWrite` tools under normal tool policy and approval rules. Subagents keep their own `TodoList`; board tools require [explicit permission](../configuration/config-files.md#subagent). Plan mode cannot use `BoardWrite`.
+Changing the setting does not move existing cards; they keep pointing at the store they were created in. If someone else saved a change first, reload the card and try again — a failed edit keeps your draft. The main agent reads and writes the board with `BoardRead` and `BoardWrite` under the normal tool policy and approval rules; subagents need [explicit permission](../configuration/config-files.md#subagent) for those, keep their own `TodoList`, and Plan mode cannot use `BoardWrite` at all.
 
-When context is compacted, the handoff lists up to five cards linked to the current session, with their IDs, titles, and statuses. This read-only list requires the board feature and `BoardRead` to be enabled; it is omitted if the read fails or takes longer than 500 ms. Card status never updates automatically from Todo lists or completed agent runs.
+After a compaction, the handoff can list up to five cards linked to the session, with ids, titles and statuses. That list needs the board feature and `BoardRead` enabled, and is simply absent if the read fails or takes more than 500 ms. Card status is never updated from todo lists or finished agent runs.
 
 ## Starting and resuming sessions
 
-On the desktop or browser **New session** page, you can use an existing workspace, enter an absolute project directory, or select **Automatically create a workspace**. When no workspaces are registered, the automatic option is selected by default. On your first send, Kiki creates a new directory under `$KIKI_HOME/workspaces/` (default: `~/.kiki/workspaces/`), registers it as a workspace, and opens the session there. An explicitly selected workspace that was later deleted stays invalid until you choose another workspace or the automatic option; Kiki will not silently use a different existing one. See [Data locations](../configuration/data-locations.md#directory-layout) for the directory layout and cleanup implications.
+On the **New session** page in the desktop app or browser you can pick an existing workspace, type an absolute project directory, or choose **Automatically create a workspace** (the default when nothing is registered yet). With the automatic option, your first send creates a directory under `$KIKI_HOME/workspaces/` (default: `~/.kiki/workspaces/`), registers it, and opens the session there. If you picked a workspace explicitly and it was deleted since, it stays invalid until you choose another one or switch to automatic — Kiki will not quietly open a different workspace. [Data locations](../configuration/data-locations.md#directory-layout) has the layout and what cleanup touches.
+
+Opening a saved session reads its history without waking an inactive session's agents, and selecting a subagent reads that subagent's history without the main agent's conversation. The session activates when you send, edit or regenerate a message, answer an approval or question, or steer a prompt. If activation fails, nothing is sent and the history stays readable. Reading a session never stops work already running in it.
 
-Opening a saved session in the desktop or browser GUI reads its history without starting an inactive session's agents. Selecting a subagent reads that subagent's history without loading the main agent's conversation. Sending, editing or regenerating a message, answering an approval or question, or steering a prompt activates the session first. If activation fails, the action is not sent and the history remains readable. Browsing does not stop work that is already running.
+The GUI opens with a small window of the latest messages. Scrolling up loads the next earlier page automatically; staying in the conversation does not load its entire history in the background. Visible messages and expanded entries load the details they need. Jumping to an older message or returning to a saved reading position continues loading until that place is found; scrolling yourself cancels the old jump. Older message previews may be fetched again as you scroll to keep the reading cache small. Leaving the conversation cancels its pending reads, not the agent's work. A real read failure keeps the messages already loaded and offers a retry; [Reading timeout](./settings.md#timeouts) controls how long a read may wait.
 
 Every time you run `kiki` directly it creates a new session. To resume a previous session, use one of the following:
 
@@ -74,7 +74,7 @@ kiki --session
 `--continue` and `--session` are mutually exclusive.
 :::
 
-In the GUI, a saved model, profile, or effort that is no longer available remains visible with a diagnostic. Select a valid value before sending; the GUI does not silently substitute another model or profile. An error shown while the list is still loading or when the catalog request fails does not mean your saved choice is invalid.
+In the GUI, a saved model, profile or effort that is no longer available stays visible with a diagnostic. Pick a valid value before sending — the GUI will not quietly swap in a different model or profile. An error while the list is still loading, or a failed catalog request, does not mean your saved choice is bad.
 
 ## Switching sessions inside the TUI
 
@@ -87,19 +87,25 @@ You can manage sessions without leaving the terminal. The following slash comman
 
 ## GUI session recovery and activity
 
-In the sidebar, a thread created by another thread normally nests under its creator. To display it as a separate top-level row, open its row menu and choose **Show at top level**; choose **Show nested** to return it. This changes only the display, not the creator relationship. The choice survives a refresh or restart in the same browser or desktop space and server connection. When sorting by recent activity, each thread uses its own activity time; activity in a child thread does not move its parent ahead of other threads.
+A thread created by another thread nests under its creator by default. **Show at top level** in the row's menu lifts it into its own top-level row, and **Show nested** puts it back. This is display only — the creator relationship stays as it is, and the choice survives a refresh or restart in the same browser or desktop space. The same menu also offers **Copy thread link** for a link to that thread, and **Add to conversation** to drop a reference to it into the conversation you currently have open.
+
+The sidebar sorts threads by their own update time. A thread shown at top level keeps its own position and time group: activity in it does not move its parent, and activity in the parent does not carry it along. Nested threads still follow their creator's row.
+
+If session recovery fails, the GUI keeps whatever history it had already loaded and shows the error, with a request ID when there is one. **Retry now** next to it reruns the recovery.
 
-When session recovery fails, the GUI keeps the history that was already loaded and shows the error together with a request ID when one is available. A **Retry now** button in the same area calls the recovery action directly.
+Editing a queued prompt's text or delivery timing through Kiki keeps its identity on recovery; you do not need to restore the original text or send a duplicate. If a completed turn cannot be saved because storage is temporarily unavailable, Kiki briefly retries saving the same result without running the turn again. A longer outage keeps the turn waiting for persistence; after storage is writable again, submitting the next prompt retries that save before continuing. A pending save is not confirmation that the result is on disk.
 
-Resolved questions, approvals, markers, and background-task completion notices stay in the timeline as compact entries. Completed work can be grouped under **Worked**; expand it to see the individual entries. Expand an answered question to read the full question and its saved answer. Dismissed and expired questions also expand to show the original question and choices. Completed task output remains available in task history. File references can be previewed, opened, or shown in their containing folder from the relevant session view; a preview is generated on demand and is not the original file, which stays available to open or download.
+Resolved questions, approvals, markers and finished background tasks stay in the timeline as compact entries. Finished work can be grouped under **Worked**; expand it to see the individual entries. Expanding a question shows the full question and, for an answered one, the saved answer — dismissed and expired questions show their original choices too. Output from completed tasks stays in task history. File references can be previewed, opened or revealed in their folder; a preview is generated on demand, and the original file is still there to open or download.
 
-In the file preview, Markdown opens in the rendered view; switch to **Source** to inspect the text or edit it in the desktop app when a write channel is available. The rendered view supports tables, math, diagrams, and images linked relative to the Markdown file. For files larger than about 512 KB, the initial view shows only the beginning and is read-only. Select **Load full file** in either the rendered or Source view to display the rest; loading the full file does not enable editing.
+Images in sent attachments and in tool results appear as soon as they scroll into view — you do not click to load them. Clicking one opens it full size, and a real failure offers a retry. The viewer keeps its own **Download**; there is no second download link under each image.
+
+Markdown previews open rendered. **Source** shows the text, and in the desktop app you can edit it there when a write channel is available. The rendered view handles tables, math, diagrams and images linked relative to the Markdown file. A file above roughly 512 KB starts as its opening portion and keeps loading the rest in the background; it stays read-only at that size, so use **Source** to read it but edit smaller files. If the background read fails, the view says so and offers a retry.
 
 ## GUI usage statistics
 
-Opening **Usage** without filters starts with today in the browser's local time. An explicit range in the URL takes precedence; a previously saved all-history view does not replace this default. The page refreshes its date boundary across midnight and when the browser's timezone offset changes.
+**Usage** opens on today in the browser's local time. A range in the URL overrides that, and a saved all-history view does not replace it. The page keeps its date boundary correct across midnight and when the browser's timezone offset changes.
 
-Token usage and estimated cost have separate completeness indicators. When a provider does not return usage, Kiki marks it as unknown rather than a real zero. Mixed results show the recorded subtotal with an incomplete-accounting notice. Older zero records without accounting provenance remain ambiguous; Kiki does not reconstruct missing tokens from them. Missing model prices affect cost estimates, not recorded token counts. The **Data reliability** section distinguishes these cases from an empty range or a failed request.
+Token usage and estimated cost each carry their own completeness marker. If a provider returned no usage, Kiki shows that as unknown rather than as a real zero, and mixed results show the recorded subtotal with an incomplete-accounting notice. A missing model price affects the cost estimate only, never the recorded token count. **Data reliability** tells these cases apart from an empty range or a failed request.
 
 ## Context compression
 
@@ -115,19 +121,19 @@ You can pass a hint to tell the model what to prioritize when compressing:
 /compact Keep the discussion about database migrations
 ```
 
-The context meter below the composer shows the same numbers and lets you set the compaction point, and its detail card also carries the renewal strategy — summarize (the default), fresh (restart from the agent's working notes), or auto. `/autocompact` shows or changes the compaction point from the terminal. Facts you want to survive compression are better kept in [memory](./memory.md), which outlives the session entirely.
+You can ask for a compaction while the agent is already working. Kiki queues the request and runs it once the current response and the tools it called have finished, without waiting for the rest of the turn. Asking again while a manual compaction is queued or running does nothing — there is only ever one. The line above the context meter says which one you are watching and how far along it is: **Manual compaction queued**, then **running**, then **complete**. A run that cannot compact ends as **failed**. The automatic one from the context limit reads the same way, with *Automatic* in place of *Manual*.
+
+The context meter under the composer shows the same numbers, lets you set the compaction point, and carries the renewal strategy: **summarize**, **fresh** (restart from the agent's working notes), or **auto** (the built-in main-agent default: restart when the notes safely cover the work, otherwise summarize). `/autocompact` shows or moves the compaction point from the terminal. Facts that must survive compression belong in [memory](./memory.md), which outlives the session.
 
 ## Forking a session
 
-To explore a new direction without disrupting the current conversation, use `/fork`:
+`/fork` copies the current session so you can try a different direction without disturbing this one:
 
 ```sh
 /fork
 ```
 
-Forking does not switch you away: you stay in the original session and the conversation continues untouched. The fork is an independent copy you can switch to at any time using `/sessions`. A saved `/goal` is not copied to the fork. Start a new goal there if you want autonomous goal work.
-
-After forking, the CLI prints a ready-to-run `kiki --resume` command (also copied to the clipboard) so you can enter the fork directly from a new terminal process.
+You stay in the original session; the fork is an independent copy you can switch to whenever you like with `/sessions`. A `/goal` you saved does not come along — set one in the fork if you want goal-driven work there. New forks do not inherit scheduled tasks, whether you copy the full session, fork at a turn boundary, or create a child session. Schedules in the original session and existing copies stay unchanged; create a new task explicitly in the new session if needed. The CLI prints a ready-to-run `kiki --resume` command, also on your clipboard, so you can open the fork from a fresh terminal.
 
 ## Exporting a session
 
@@ -143,14 +149,14 @@ Omitting `sessionId` exports the most recent session in the current directory (w
 kiki export <sessionId> -o ~/Desktop/my-session.zip
 ```
 
-The export includes all files in the session directory, including diagnostic logs. The global diagnostic log (`~/.kiki/logs/kimi-code.log` — the file name follows the project's early naming; it is Kiki's global log) is also bundled by default; add `--no-include-global-log` to exclude it.
+The export includes everything in the session directory, diagnostic logs included, plus the global log at `~/.kiki/logs/kimi-code.log` (the name is inherited from the project's earlier naming). Add `--no-include-global-log` to leave that one out.
 
 You can also export from inside the TUI without leaving the interactive session:
 
 - **`/export-debug-zip`**: produces the same debug ZIP as `kiki export`.
 - **`/export-md`** (alias `/export`): exports the conversation as a human-readable Markdown file, suitable for sharing or archiving. Accepts an optional path argument; without one, it writes to `kimi-export-<short-id>-<timestamp>.md` in the current working directory.
 
-In the web UI, `/export` downloads the current session as a diagnostic ZIP. It includes the persisted session data, diagnostic logs, and a bounded metadata-only `logs/kimi-web.jsonl` record of key browser events. Prompt text, WebSocket payloads, and console arguments are not copied into this browser log. This web command differs from the TUI `/export` alias above.
+In the web UI, `/export` downloads the current session as a diagnostic ZIP: the persisted session data, diagnostic logs, and a bounded metadata-only `logs/kimi-web.jsonl` record of key browser events. Prompt text, WebSocket payloads and console arguments are not copied into that browser log. This is a different command from the TUI `/export` alias above.
 
 ::: tip
 Exported files may contain code, command output, and file paths that are sensitive. Review the content before sharing.

package/dist/docs/en/guides/settings.md

@@ -26,7 +26,7 @@ The Kiki desktop app exposes preferences in the **Settings** dialog and activity
 
 ## Connections
 
-**Settings → Models & providers → Connections** (`/settings/ai?tab=providers`) is one list. Every way Kiki reaches a model is a **connection** — an account you sign in to, a hosted API you hold a key for, or a server on this machine — and each is one row that says how it is reached, what it carries, and whether it works. How a connection authenticates is part of the connection, not a separate list to keep in step with it.
+**Settings → Models & providers → Connections** (`/settings/ai?tab=providers`) is one list. Every way Kiki reaches a model is a **connection** — an account you sign in to, a hosted API you hold a key for, or a server on this machine — and each row says how it is reached, what it carries, and whether it works. How it authenticates is part of the connection, not a separate list to keep in step.
 
 **Add connection** is the single way in, and it asks one question — which service, by what means:
 
@@ -36,12 +36,12 @@ The Kiki desktop app exposes preferences in the **Settings** dialog and activity
 
 An account connection is written by the sign-in, so its row has no protocol, address or key to fill in. Expand it to see which account is behind it, what the vendor says it has left, and the action that changes the sign-in:
 
-- **Connected** — the credential works. Kiki renews it on its own. **Sign out** ends that sign-in in Kiki and removes the models it provisioned; it does not sign you out at the provider, and it does not touch the provider's own record of your account.
+- **Connected** — the credential works, and Kiki renews it on its own. **Sign out** ends that sign-in inside Kiki and removes the models it added; at the provider you stay signed in.
 - **Sign-in expired** — the provider no longer accepts it. **Sign in again** replaces it on this same connection; nothing is added to the list.
-- **Sign-in didn't finish** — the flow ended without a credential: you declined it, the code expired, or it failed. One line says which, and the connection is left as the server reports it rather than as a half-made one.
+- **Sign-in didn't finish** — the flow ended without a credential: you declined it, the code expired, or it failed. One line says which, and the row is left as the server reports it.
 - **Waiting for you** — a sign-in is running, with the code, **Open verification page**, how long it stays valid, and **Cancel sign-in**.
 
-A sign-in that completes adds that account's models to the catalog on the server. **Available models** is the authority on what you can use — a row here reports the connection and its sign-in, not a promise about which models are selectable right now.
+A completed sign-in adds that account's models to the catalog on the server. **Available models** is where you check what you can actually use — a row here reports the connection and its sign-in state.
 
 Signing out here affects Kiki only. The provider keeps its own record of your subscription, and signing in again reconnects the same account.
 
@@ -49,52 +49,81 @@ Signing out here affects Kiki only. The provider keeps its own record of your su
 
 For ChatGPT (Codex) and Grok Build, a connection can use the sign-in their own app already holds on this machine instead of a new one. Kiki reuses it and renews it when it runs out; it does not copy the credential, does not start the other app, and signing in or out here does not change anything there.
 
-"This machine" is the machine Kiki's **server** runs on. That is usually the one you are looking at, and when it is not, **Look somewhere else on the server** takes a directory to read from instead.
+"This machine" is the machine Kiki's **server** runs on. That is usually the one you are looking at; when it is not, **Look somewhere else on the server** takes a directory to read from instead.
 
-The order is deliberate. **Check this machine** reports which account is on the other side and where it is kept — a file, the system keyring, or an encrypted store. Only then is **Use this sign-in** offered, and it carries the account it just showed you, so a credential that was replaced in between is refused rather than adopted silently. A credential due for renewal is not a problem: it is offered, and Kiki renews it.
+**Check this machine** reports which account is on the other side and where it is kept — a file, the system keyring, or an encrypted store — and **Use this sign-in** then attaches that exact account. A credential that was replaced in between is refused rather than adopted, and one that is due for renewal is used and renewed.
 
-When the machine cannot be used, the page says why in terms you can act on — no account for that service, signed out, stored somewhere unreadable, or belonging to a different account — and offers nothing to attach.
+If the machine cannot be used, the page says why in terms you can act on — no account for that service, signed out, stored somewhere unreadable, or belonging to a different account — and offers nothing to attach.
 
 **Stop using it** lets go of the machine's sign-in for this connection. It removes Kiki's reference and the models it provisioned; the sign-in itself is still there, and the other app is unaffected.
 
+### Timeouts
+
+**Settings → Models & providers → Connections** carries two separate timeouts, and they govern different requests:
+
+- **Request timeout** — the default deadline for ordinary requests this interface makes to the Kiki server.
+- **Reading timeout** — how long a history or content read may wait before Kiki gives up on it. The default is `0`, meaning no deadline: a large or slow conversation loads as long as it takes. Set a number of seconds if you would rather a stalled read fail quickly.
+
+A reading timeout only bounds waiting; it never limits how much can be read. A changed value applies to the **next** read — it does not interrupt one already running, and it does not reconnect anything. Leave it at `0` unless you specifically want a ceiling. These are GUI settings, not keys in `config.toml`; the server-side memory budgets that govern how much history is kept in memory are separate — see [`transcript_memory`](../configuration/config-files.md#transcript-memory).
+
 ## About
 
-**Settings → About** shows the current version and the update channel. Choose Stable or Beta and run a manual update check; when an update is available, Kiki shows its version and release notes before asking for confirmation. See [Kiki desktop](../getting-started/desktop-app.md#update).
+**Settings → About** shows the current version and owns the update settings. **Update channel** picks Stable or Beta, and every check — automatic or manual — reads the channel from here. **Check for updates automatically** turns the daily check on or off; with it off, only **Check for updates** checks. The **When an update is found** setting applies: **Notify me** shows a dialog with the version and a short summary and waits for you, while **Download and install** starts the install without that dialog. Either way, Kiki asks before closing spaces that still have running work.
+
+The dialog's three choices are saved rather than repeated each time: **Remind me tomorrow** comes back 24 hours later, **Skip this version** silences that version on that channel only, and a newer version still comes either way. Before installing, Kiki re-checks the channel and the version and refuses an offer that has changed underneath you. If a choice cannot be saved, the dialog stays open and asks you to try again. See [Kiki desktop](../getting-started/desktop-app.md#update).
 
 ## Agents
 
-**Settings → Agents** selects a workspace to inspect its default main profile (the agent's configuration file), effective source, and subagent capabilities. File-backed profiles can be edited at their displayed source. **Settings → Agents → Prompt** edits the `[prompt]` prompt-field overrides section in `config.toml`; the card is collapsed by default — expand it before editing. See [Agents and subagents](../customization/agents.md#capability-visibility) and [Prompt field overrides](../customization/prompt-fields.md).
+**Settings → Agents** picks a workspace and shows its default main profile (the agent's configuration file), the source in effect, and the subagent capabilities. File-backed profiles can be edited at the source shown. **Settings → Agents → Prompt** edits the `[prompt]` prompt-field overrides section in `config.toml`; expand the card first. See [Agents and subagents](../customization/agents.md#capability-visibility) and [Prompt field overrides](../customization/prompt-fields.md).
+
+The periodic long-term memory reminders run on their own schedule. To stop just those while keeping the new standing-instruction and pre-compaction checks, set `memory_maintenance = false` in `config.toml`; memory tools, approval and task notes stay available. See [Continuity reminder settings](../configuration/config-files.md#continuity-reminder-settings).
+
+## Notifications & messages
+
+Under **Settings → Notifications & messages → System notifications**, **Allow system notifications** controls session notifications and pending-input reminders from other spaces on this device. The default-on **Notify when the conversation finishes** switch uses the existing notification path while Kiki is hidden or unfocused. Completion means the assigned work has settled: the main agent has finished, finite background tasks and subagents have settled, and their results and any automatic continuation have been handled. A turn ending alone does not notify. Resident servers, watchers and future schedules do not keep work unfinished; approvals, questions, failures and user stops are not completion notices. In a browser, allow this site to send notifications; if you previously denied permission, restore it in the address bar’s site permissions.
 
-Long-term memory maintenance reminders help retain changes useful to future tasks; no meaningful change calls for no write. To disable only the periodic reminders while keeping new standing-instruction and pre-compaction checks, set `memory_maintenance = false` in `config.toml`. This does not disable memory tools, approval, or task notes. See [Continuity reminder settings](../configuration/config-files.md#continuity-reminder-settings) for the section and prerequisites.
+For configured phone or team-chat channels, enable **The conversation finishes** on each channel; it uses the same work-completion decision. **Send notifications** remains their separate master switch; previously disabled masters, connections and channels stay disabled. New configurations default to on with **Skip short work** at `0` seconds, so short replies qualify too. Raising it filters short-work notices for those channels, without changing what completion means. System-notification switches are saved on this device; channel rules are saved by the connected server. Launching or reconnecting does not replay old completion notices.
 
 ## Search & retrieval
 
 **Settings → Search & retrieval → Overview & source** inspects the built-in search and retrieval module — the capability behind the `WebSearch` and `FetchURL` tools — showing which configuration source is in effect and whether the server reuses the local search configuration. The equivalent configuration lives in `config.toml` — see [Configuration files](../configuration/config-files.md#nb-search).
 
+The same section's **Advanced & diagnostics** tab carries a **Full-text index** card for searching your own session history. The first index is built in the background, newest sessions first, and the card counts what is done so far. If the index stops for a reason you can fix, that card is where **Restart the indexer** appears; when indexing is off or unavailable by configuration, there is nothing to restart and the reason is stated instead.
+
 ## Browser control
 
-**Settings → Browser control** (`/settings/browser-control`) manages saved browser connections. One connection is one controllable browser location; opening the page reads and edits them and starts no browser.
+**Settings → Browser control** (`/settings/browser-control`) opens on three named routes. Pick one, set it up, connect it — usually two actions.
+
+- **Kimi Browser Extension**: drives the browser you already use, with your own sign-ins. Kiki installs the plugin and the local bridge; the extension is added once from your browser's store, and only you can click through that approval.
+- **Independent browser**: Kiki starts and keeps a browser of its own, with its own sign-ins that never touch your everyday browser. **Set up** downloads and verifies the components it needs; **Connect** then starts it.
+- **Codex / ChatGPT browser extension**: driven by the Codex / ChatGPT desktop app. Kiki neither installs nor controls this one, so the row carries its official instructions and nothing else.
+
+Each row states its own status and **what it still needs**, and puts the next action on that same line: **Set up** while a component is missing, the store link while only the approval is left, and **Turn on browser control** while only the switch is. Once everything Kiki can install is in place, the row stops asking you to install and tells you it is ready to connect. The detector's own sentences — which parts are merely reported rather than verified — sit in the **What this server checked** fold, off the first screen.
+
+**Turn on browser control** is the same consented action, on this page. When the switch is the only thing missing, that one confirmation installs whatever is still missing — nothing at all when the components are already in place — enables the plugin, and turns browser control on for the server. The confirmation says all three before you accept. Browser control is off by default, so this is the step that switches it on; there is no separate switch to find on another page.
 
-A connection has a fixed id, a display name, and one of two styles, which point at different targets:
+If something outside this page holds browser control off — an environment variable, or a runtime override on that host — no action here can change it. The row says exactly that instead of offering a button, and **See what holds it off** names the override responsible.
 
-- **Profile (Independent agent browser):** Kiki starts and manages a browser of its own on the server, with a profile (sign-in state) of its own — your everyday browser cookies are not copied. Optional extras: an installed Chrome or Edge instead of the bundled one, and **Show the browser window** (off by default, so it starts headless).
-- **CDP (Existing or remote browser):** attaches to a browser that already exposes a CDP address and starts nothing new. That address names the machine the browser runs on, which may be a different machine.
+The **Advanced: edit connections, or connect a browser you already run** fold holds what you type rather than pick. A connection has a fixed id, a display name, an enable switch, and one of two styles that point at different targets:
 
-The driver, and any browser Kiki starts, run on the Kiki server — not on the device showing this window. **Check components** starts the managed driver and reads its session and tab state; **Check connection** handshakes with the CDP endpoint and lists its targets. Neither opens a page. **Start browser** and **Attach browser** are the separate actions that connect. Saving writes configuration only and ends that connection's current running session first. **Disconnect** releases the connection, and what happens to the browser depends on who started it: a borrowed CDP browser stays, an instance Kiki started is closed.
+- **Profile (Independent agent browser)**: Kiki starts and manages a browser of its own on the server, with a profile (sign-in state) of its own — your everyday browser cookies are not copied. Optional extras: an installed Chrome or Edge instead of the bundled one, and **Show the browser window** (off by default, so it starts headless).
+- **CDP (Existing or remote browser)**: attaches to a browser that already exposes a CDP address and starts nothing new. That address names the machine the browser runs on, which may be a different machine.
 
-Agents use these connections through the [browser tools](../reference/tools.md#browser-tools), naming a connection by its id — never by display name. **Default connection** applies to sessions created afterwards; turning a connection off never swaps in another one.
+Each connection can be checked, connected and disconnected on its own. A check starts the managed driver and reads its session and tab state; a CDP connection handshakes with the endpoint and lists its targets. Neither opens a page. Saving writes configuration only and ends that connection's current running session first. **Disconnect** releases the connection: a borrowed CDP browser stays, an instance Kiki started is closed. **Default connection** applies to sessions created afterwards; turning a connection off never swaps in another one.
 
-Running a browser is a development-candidate feature and is off by default. Turn on `native_browser` under **Settings → Developer → Experimental**, or set it under [`[experimental]`](../configuration/config-files.md#experimental), before connecting. With it off, the page still reads and edits saved connections, but connecting is refused and agents get no browser tools. The connections themselves are stored in [`[browser_control]`](../configuration/config-files.md#browser-control).
+The driver, and any browser Kiki starts, run on the Kiki server — not on the device showing this window; the components live under `<Kiki home>/browser/resources` on the machine that runs them.
+
+Agents use these connections through the [browser tools](../reference/tools.md#browser-tools), naming a connection by its id — never by display name. The switch and the connections themselves live under [`[experimental]`](../configuration/config-files.md#experimental) and [`[browser_control]`](../configuration/config-files.md#browser-control) respectively.
 
 ## Computer control
 
 **Settings → Computer control** drives the desktop of the machine running the Kiki server, through a pinned open-source executor. Nothing is installed or configured by default, so the page starts empty.
 
-**Install executor** downloads and verifies that pinned release, then registers a global MCP connection named `kiki-computer` (the driver's path plus `mcp` arguments). **Installed** means the executor files verified — not that anything is being controlled; desktop access is a separate check that the install does not run. The page names the machine that would be driven: **Kiki server** is the connected server, so with a remote or SSH connection the desktop belongs to that host's own graphical session.
+**Install executor** downloads and verifies that release, then registers a global MCP connection named `kiki-computer` (the driver's path plus `mcp` arguments). **Installed** means the files verified — it does not check that anything can actually be controlled, and it does not touch the desktop. The page names the machine that would be driven: **Kiki server** is the connected server, so over a remote or SSH connection the desktop is that host's own graphical session.
 
-The agent drives it with the executor's own tools through the existing MCP mechanism and permissions; Kiki adds no second desktop tool set — see [MCP](../server/mcp.md). The pinned Windows executor observes the primary display and has no display selection of its own. On macOS the direct connection carries desktop permissions in the calling process, so grant them where the driver reports them missing.
+The agent drives it with the executor's own tools, through the existing MCP mechanism and permissions — see [MCP](../server/mcp.md). The pinned Windows executor watches the primary display and cannot pick a different one. On macOS the desktop permission travels in the calling process, so grant it where the driver reports it missing.
 
-**Stop control** ends the cua processes this service started, and disables an editable connection's configuration at the same time. It does not mean nobody controls that desktop: another client or another Kiki instance may still be driving it.
+**Stop control** ends the cua processes this service started and disables an editable connection's configuration. Another client or another Kiki instance may still be driving that desktop.
 
 ## Composer
 
@@ -108,15 +137,13 @@ Open **Dispatch capabilities** — next to the new-session workspace selector, o
 
 ### Effective prompts
 
-In a session, open the header's **⋯ → Effective prompts**. The drawer opens independently of the right rail, including on narrow screens. It shows the current agent identity, profile, model and executor, prompt channels and source order, field override states and reasons, file locations, and cognition-anchor scope. The latest actual request is separate evidence: before any request exists, the details do not claim that the displayed composition has been sent.
+In a session, open the header's **⋯ → Effective prompts**. The drawer opens independently of the right rail, including on narrow screens, and shows the current agent identity, profile, model and executor, the prompt channels and their source order, field overrides with the reason for each, file locations, and the cognition-anchor scope.
 
-The binding and disk revisions help identify changed source files. When you want to reload the session's prompt sources, use [Rebuild context](../customization/agents.md#rebuilding-a-session-context) after the session becomes idle. Ordinary details read the current identity; **Check all branches** is a separate, explicit action to inspect configured common, main-agent and independent-agent prompt files. It does not activate those other branches or switch the current identity.
+The binding and disk revisions help you spot which source files changed. To actually reload the session's prompt sources, use [Rebuild context](../customization/agents.md#rebuilding-a-session-context) once the session is idle. **Check all branches** is a separate action that inspects the configured common, main-agent and independent-agent prompt files without switching the current identity.
 
 ### Cockpit
 
-On desktop-width screens, use **Standard / Cockpit** in the right-panel header. Cockpit temporarily widens that panel and takes over the preview space, while the conversation and composer stay in the main column.
-
-Choose **Standard** or **Exit cockpit** to restore the previous preview content, tabs, draft and width. Exiting cockpit leaves the standard right panel open; hiding that panel is a separate action. Opening a file, agent detail or skill preview also exits cockpit and restores the preview workspace. The temporary cockpit width does not replace your saved standard-panel width.
+On desktop-width screens, **Standard / Cockpit** in the right-panel header switches the panel between its normal width and a wide one that takes over the preview space. The conversation and composer stay in the main column either way, and **Standard** or **Exit cockpit** puts the previous preview content, tabs, draft and width back. Opening a file, an agent detail or a skill preview also leaves cockpit.
 
 ## Usage
 
@@ -126,14 +153,18 @@ Open **Usage** in the sidebar (`/usage`). It has three tabs and opens **History*
 - **Live:** running and queued native-request counts across this service. Expand **Request details** for the breakdown by model, provider, and role, and waiting rows with blocking rule IDs and elapsed queue time. If the connection fails, the last counts are marked stale. On the same tab, **Concurrency limits** lets you add or edit rules, choose a model or provider target, and set a shared or per-session cap. The switch pauses a rule without deleting it. Saving applies the rule to new and queued requests without stopping active streams.
 - **External sync:** destinations that receive this server's own usage. Three kinds are available: **vibecafe.ai**, **Kiki webhook**, and **Script**. Only the model, the UTC half-hour, the four token counts, quality and cost go out — never a prompt, answer, title, workspace name or path.
 
+  A **vibecafe.ai** destination signs in from the page itself: press **Sign in to VibeCafe**, approve it in your browser with the code it shows, and the page reports the result. There is no authorization code to copy, and no address, client id, or key to fill in — the destination is `https://vibecafe.ai`. A custom address, or a key you supply yourself, is the advanced path instead. The sign-in is part of the experimental `usage_export` feature, and the flow has not been exercised against the live service: if it does not complete, the destination stays as the page left it and nothing has been sent.
+
+A **Kiki webhook** destination takes your own HTTPS endpoint, with `none`, `bearer`, or `hmac` authentication and optional gzip. A secret is stored either in the system keyring or, if you choose that explicitly, in a private file on the server — the keyring is not silently substituted if it fails, and the file is protected by filesystem permissions rather than encrypted at rest.
+
 Existing `/usage?panel=limits` links open Live and focus the concurrency-rule section; there is no separate Limits tab.
 
-External sync stays off until the server enables the `usage_export` flag. A saved destination sends nothing until you preview the exact payload and agree once; widening the range, changing the endpoint, or a credential change that cannot be shown to be the same identity asks for consent again, while shrinking the range or changing the interval does not. Pausing a destination keeps its queue; removing it is a separate action that asks whether to discard the queued buckets; asking the service to delete the usage it already holds is a third one. See [`kiki usage-export`](../reference/command.md#kiki-usage-export) for the command-side equivalent.
+External sync stays off until the server enables the `usage_export` flag. Signing in does not change that: an approved credential is stored, the destination stays **disabled**, and no consent has been given — so the order still holds, choose a destination, preview the exact payload, agree once, then enable. A destination that has not been agreed to sends nothing. Widening the range, changing the endpoint, or changing a credential to a different identity asks again, while shrinking the range or changing the interval does not. Pausing keeps the queue, removing asks whether to discard the queued batches, and asking the service to delete what it already holds is a separate action. See [`kiki usage-export`](../reference/command.md#kiki-usage-export) for the command-side equivalent.
 
-A **Script** destination runs your command as your own OS user with your ordinary permissions — it can read files and use the network on its own, and this is not a sandbox. Kiki writes only the content-free batch to its stdin and reads a receipt from its output. When a local vibecafe collector already reports this home to the same account, the destination offers a handoff: one future UTC boundary splits the timeline, the collector keeps everything before it and Kiki everything from it onward, and a single agreement covers both. Kiki does not rewrite the collector's state file, read its key, or stop its service.
+A **Script** destination runs your command as your own OS user with your ordinary permissions — it can read files and reach the network on its own, and this is not a sandbox. Kiki writes only the content-free batch to its stdin and reads a receipt from its output.
 
-For a request that appears stuck, open **Live → Request details** before changing a limit. A queued row names the local blocking rule; a provider HTTP 429 is diagnosed from the provider error instead. Local queue-full, timeout, and rejection errors need different adjustments. See [`request_governance`](../configuration/config-files.md#request-governance) for the fields, copyable examples, and error codes. External executors are unmanaged; these counts are not their activity or the provider account's total usage.
+For a request that looks stuck, open **Live → Request details** before changing a limit. A queued row names the local rule blocking it, and a provider HTTP 429 is diagnosed from the provider's own error — a full local queue, a timeout and a rejection each need a different fix. [`request_governance`](../configuration/config-files.md#request-governance) has the fields, examples and error codes. The rules cover the model requests this service sends itself: when you run a turn on Codex, Claude Code, or Grok Build as the engine, those requests are the engine's own and are not counted here, while an external tool calling back into Kiki for a native request is.
 
 ## CLI counterpart
 
-The TUI does not use the **Settings** dialog: client preferences in the terminal (theme, editor, and so on) are configured through `tui.toml` and the interactive commands `/config`, `/theme`, and `/editor`; see [`tui.toml`](../configuration/config-files.md#tui-toml). Agent and runtime settings live in `config.toml`.
+The TUI has no **Settings** dialog. Terminal-side preferences (theme, editor, and the rest) are configured in `tui.toml` or with the interactive `/config`, `/theme` and `/editor` commands — see [`tui.toml`](../configuration/config-files.md#tui-toml). Agent and runtime settings live in `config.toml`.

package/dist/docs/en/index.md

@@ -18,17 +18,23 @@ features:
   - title: "One workbench, many lines"
     details: The lead session dispatches subagents that each run a model you chose for that role, sends long commands to the background, and hears back when they finish.
     link: ./features/workbench
+  - title: "Agent Profiles"
+    details: "One Markdown file describes a kind of agent: the model it runs on, how it is instructed, which tools it may call, and what it can dispatch."
+    link: ./features/agents
   - title: "Work that runs long"
     details: Goals that carry across turns, a queue for what you type while it is busy, scheduled prompts, a per-workspace task board, and memory that outlives the session.
     link: ./features/long-work
   - title: "Roles you can talk to"
-    details: A persona is a persistent identity with its own memory, a fixed daily conversation, and a seat in a room where several of them discuss one topic.
+    details: A persona is a long-term identity with its own memory, a fixed daily conversation, and a seat in a room where several of them discuss one topic.
     link: ./features/people
+  - title: "Know what it costs"
+    details: "The usage page answers three questions: what a date range cost, which concurrency rule is holding a request back, and where the content-free numbers can be sent."
+    link: ./features/daily
   - title: "Your data, your machines"
     details: Spaces with their own credentials, directed remote connections, one-way thread bridges, Web access, and in-session SSH.
     link: ./features/spaces
   - title: "Every layer is yours"
-    details: Agents are Markdown files you own, prompts are overridable down to one tool description, connections and OAuth are one list, and hooks run your scripts.
+    details: Prompts are overridable down to one tool description, connections and OAuth are one list, permission modes are yours to pick, and hooks run your scripts.
     link: ./features/freedom
   - title: "Bring your history, meet other tools"
     details: Import another tool's conversations and keep working in them, use Kiki inside your editor over ACP, or let Kiki run other agent harnesses as its engines.