kiki-agent-lite 0.3.1 → 0.3.2

package/dist/docs/en/customization/prompt-fields.md

@@ -1,12 +1,12 @@
 # Prompt field overrides
 
-Prompt field overrides replace named text units in the built-in prompt — the system sections, tool descriptions, and delegation notices — without forking an agent profile. Field values replace; they do not append, prepend, or wrap.
+Prompt field overrides replace named pieces of the built-in prompt — system sections, tool descriptions, delegation notices — without forking a profile. A field value replaces; it does not append, prepend or wrap.
 
-Kiki ships a read-only surface for discovering and validating these fields: `kiki prompt-fields`. The full field registry, override format, precedence, and validation rules are owned by the [Configuration files: `prompt`](../configuration/config-files.md#prompt) reference — this page shows how the pieces fit together.
+`kiki prompt-fields` is a read-only way to discover and check these fields. The registry, format, precedence and validation rules live in [Configuration files: `prompt`](../configuration/config-files.md#prompt); this page shows how the pieces fit together.
 
 ## What you can override
 
-Useful built-in field ids include `system.language`, `system.reply_style`, `system.coding`, `system.shared`, `tool.web-search.description`, `tool.web-search.guidance`, `delegation.sub.notice`, and `delegation.independent.notice`. System fields replace sections of the built-in prompt; `system.shared` is the only shared outer addition and is appended once when non-empty. A tool `description` replaces its static description; a tool `guidance` is appended under the existing `User-configured guidance:` label.
+Useful built-in field ids include `system.language`, `system.reply_style`, `system.coding`, `system.shared`, `tool.web-search.description`, `tool.web-search.guidance`, `delegation.sub.notice` and `delegation.independent.notice`. System fields replace sections of the built-in prompt, except `system.shared`, which is the one shared outer addition and is appended once when non-empty. A tool `description` replaces its static description; a tool `guidance` is appended under the existing `User-configured guidance:` label.
 
 ## Where overrides live
 
@@ -21,6 +21,10 @@ Every override surface uses the same format — optional `files` (strict TOML fi
 
 Precedence from low to high follows the table order; a missing key inherits the lower value. The complete format, `${name}` variable substitution rules, and validation failures are documented in [`prompt`](../configuration/config-files.md#prompt).
 
+An existing agent keeps its bound prompt fields, custom variables and cognition text when it resumes, even if their source files have changed or been deleted. Edits apply to new bindings; choose [Rebuild context](./agents.md#rebuilding-a-session-context) to adopt them in an existing session. An explicit model change selects the target model's prompt inputs; `new_window` alone does not reload prompt sources. Current tool permissions and hard model constraints still apply.
+
+Older records reuse their saved system prompt and recover inline fields from the saved profile where possible. If a record never saved a required shared field, tool override, steering cue or anchor and its original inputs cannot be reconstructed, recovery names the missing inputs. Rebuild the context to use current sources rather than rolling back your installed prompts.
+
 ## Discover and validate with `kiki prompt-fields`
 
 `kiki prompt-fields` is read-only; it does not modify `config.toml`, `SYSTEM.md`, agent profiles, or override files.
@@ -32,13 +36,13 @@ kiki prompt-fields validate --config ./candidate.toml --home ~/.kiki   # validat
 kiki prompt-fields explain delegation.sub.notice --agent reviewer --model fast --delegation-position sub
 ```
 
-`explain` prints a field's `effective`, `shadowed`, or `inactive` status, its effective value, and the complete source chain for the selected context. Select the context with `--agent`, `--model`, `--executor`, and `--delegation-position <main|sub|independent>`; `--config <path>` inspects another config file and `--home <dir>` selects the Kiki home used for `SYSTEM.md`, agent discovery, and relative override files.
+`explain` prints a field's `effective`, `shadowed` or `inactive` status, its effective value, and the whole source chain for the context you select with `--agent`, `--model`, `--executor` and `--delegation-position <main|sub|independent>`. `--config <path>` inspects another config file, and `--home <dir>` picks the Kiki home used for `SYSTEM.md`, agent discovery and relative override files.
 
-The removed `prompt.shared` and `prompt.tools` keys have moved into fields under `[prompt.overrides]`; migrate old entries instead of restoring those keys — see [prompt field precedence](../configuration/overrides.md#prompt-field-precedence).
+If your config still carries the old `prompt.shared` and `prompt.tools` keys, move those entries into fields under `[prompt.overrides]` rather than restoring the keys — see [prompt field precedence](../configuration/overrides.md#prompt-field-precedence).
 
 ## Desktop settings entry point
 
-In the desktop GUI, open **Settings → Agents → Prompt** to edit this section — see [Settings pages](../guides/settings.md#agents). The card is collapsed by default.
+In the desktop app, **Settings → Agents → Prompt** edits this section — see [Settings pages](../guides/settings.md#agents). The card starts collapsed.
 
 ## Next steps
 

package/dist/docs/en/customization/skills.md

@@ -1,12 +1,10 @@
 # Agent Skills
 
-Agent Skills are a lightweight mechanism for extending model capabilities in Kiki. A Skill is a Markdown document with YAML frontmatter that describes a specialized area of knowledge or a workflow — for example, a project's code style guidelines, a PR review process, or a commit message format.
-
-Compared to pasting the same instructions into a prompt every time, Skills offer the advantage of keeping content in a file, enabling reuse across projects and teams, allowing instant loading via a slash command, and letting the model invoke them automatically when needed.
+A Skill is a Markdown document with YAML frontmatter that describes a piece of knowledge or a workflow — a project's code style, a PR review process, a commit message format. Keeping it in a file rather than pasting it into every prompt means it can be shared across projects and teams, loaded with a slash command, or picked up by the model automatically when it is relevant.
 
 ## Custom prompt commands
 
-Use a Markdown command when you want `/name arguments` to load your own prompt only after you explicitly send it. Commands reuse the Skill catalog and parameter expansion, but their descriptions are not offered to the model for automatic Skill invocation.
+A command is the same kind of file, loaded only when you explicitly send `/name arguments`. Commands reuse the Skill catalog and parameter expansion, but the model is never offered their descriptions for automatic invocation.
 
 Create `.kiki/commands/brainstorm.md` in your project root:
 
@@ -20,13 +18,13 @@ Ask about important missing requirements. Keep this a discussion; do not
 create documents or modify files unless I ask you to.
 ```
 
-In the GUI or terminal, type `/`, select `brainstorm`, add a topic, then send `/brainstorm a simpler settings menu`. Selecting the entry only fills the draft; sending loads the body once with your arguments and attachments. This is an example, not an installed or mandatory brainstorming workflow.
+In the GUI or terminal, type `/`, pick `brainstorm`, add a topic and send `/brainstorm a simpler settings menu`. Picking the entry only fills the draft; sending loads the body once with your arguments and attachments.
 
-The YAML frontmatter is optional. Without it, the filename supplies the name and the first non-empty body line supplies the menu description. Optional `name`, `description`, and `argument-hint` customize those fields; names cannot contain whitespace, `/`, `\\`, or `:`. The [body placeholders](#body-placeholders) also work in commands. If there is no argument placeholder, arguments are appended to the body. Values inserted as arguments are not expanded again.
+The frontmatter is optional. Without it, the filename supplies the name and the first non-empty body line becomes the menu description. Optional `name`, `description` and `argument-hint` override those; a name cannot contain whitespace, `/`, `\` or `:`. The [body placeholders](#body-placeholders) work here too, and if the body has no argument placeholder the arguments are appended to it. Values inserted as arguments are not expanded again.
 
-Command locations are the active application data directory's `commands/*.md` for user-wide commands and `.kiki/commands/*.md` at the project root. Only direct Markdown children are commands. Project commands take precedence over user commands of the same name. The legacy `.kimi-code/commands/` tree is not read. Explicit Skill-directory overrides retain their existing replacement behavior. Edits are watched; reopen the GUI slash menu or run `/reload` in the terminal to refresh the menu.
+Commands live in `commands/*.md` under the active application data directory (user-wide) and `.kiki/commands/*.md` at the project root. Only direct Markdown children count, and a project command wins over a user command of the same name. The legacy `.kimi-code/commands/` tree is not read. Edits are watched — reopen the GUI slash menu or run `/reload` in the terminal to see them.
 
-Built-in shortcuts keep their bare names: `/plan` still controls Plan mode. A colliding catalog entry is shown as `/skill:plan`; a command colliding with an existing Skill is shown as `/command:name`. Use the name shown in the menu. Commands are user prompts, not system prompts or executable scripts: they do not grant permissions, switch modes, or turn a flowchart into a workflow engine. Review command files from unfamiliar repositories before sending them.
+Built-in shortcuts keep their bare names, so `/plan` still controls Plan mode. A Skill that collides with one is shown as `/skill:plan`, and a command that collides with a Skill as `/command:name`; use the name the menu shows. A command is a user prompt, not a system prompt or a script: it grants no permissions, switches no modes, and cannot run anything. Review command files from an unfamiliar repository before sending them.
 
 ## Creating a Skill
 
@@ -93,7 +91,7 @@ Kiki scans four tiers by scope; more specific scopes take higher priority: **Pro
 - `$KIKI_HOME/skills/` (default: `~/.kiki/skills/`)
 - `~/.agents/skills/`
 
-The Kiki-specific user Skill directory moves with `KIKI_HOME`, so isolated data roots also get isolated Kiki-specific Skills. The generic `~/.agents/skills/` directory stays under the real OS home so it can be shared across tools.
+The Kiki-specific user Skill directory moves with `KIKI_HOME`, so a relocated data root gets its own copy; the generic `~/.agents/skills/` stays under the real OS home so other tools can share it.
 
 **Project level** (project root = the nearest directory containing `.git`, searching upward from the working directory):
 - `.kiki/skills/`
@@ -105,18 +103,18 @@ The Kiki-specific user Skill directory moves with `KIKI_HOME`, so isolated data
 extra_skill_dirs = ["~/team-skills", ".agents/team-skills"]
 ```
 
-**Built-in Skills** are distributed with the CLI and have the lowest priority. They provide out-of-the-box workflows for common tasks — for example, configuring MCP servers, customizing the TUI theme, and editing config files. See [Built-in skill commands](../reference/slash-commands.md#built-in-skill-commands) for the full list. Every Skill Kiki ships today describes Kiki itself, so the top-level [`builtin_product_skills`](../configuration/config-files.md#top-level-fields) field turns all of them off at once — including `/kiki-ops`, the guided path for configuring and troubleshooting Kiki. Set it back to `true` to restore them.
+**Built-in Skills** ship with the CLI and have the lowest priority. They cover common setup tasks — configuring MCP servers, customizing the TUI theme, editing config files; [Built-in skill commands](../reference/slash-commands.md#built-in-skill-commands) lists them. Every Skill Kiki ships describes Kiki itself, so the top-level [`builtin_product_skills`](../configuration/config-files.md#top-level-fields) field turns all of them off at once, including `/kiki-ops`. Set it back to `true` to restore them.
 
 ## Invoking a Skill
 
 Users can invoke a Skill manually with a slash command:
 
-```
+```text
 /skill:code-style
 /skill:git-commits fix concurrency issue in login endpoint
 ```
 
-The model can also invoke a Skill automatically based on `description` and `whenToUse` (unless `disableModelInvocation` is `true` or `type` is `flow`). Skill invocations allow up to 3 levels of nesting; beyond that they are terminated.
+The model can also invoke a Skill on its own from `description` and `whenToUse`, unless `disableModelInvocation` is `true` or `type` is `flow`. A Skill can invoke another Skill, up to three levels deep.
 
 ## Complete Example
 
@@ -146,7 +144,7 @@ Please review the PR the user specified: $pr_ref
    - Noteworthy positives
 ```
 
-Save this as `$KIKI_HOME/skills/review-pr/SKILL.md` (or `~/.kiki/skills/review-pr/SKILL.md` when `KIKI_HOME` is unset), place the checklist at `references/checklist.md` in the same directory, and after starting a new session you can invoke it with `/skill:review-pr #1234`, where `#1234` is expanded into `$pr_ref`.
+Save this as `$KIKI_HOME/skills/review-pr/SKILL.md` (`~/.kiki/skills/review-pr/SKILL.md` when `KIKI_HOME` is unset), put the checklist at `references/checklist.md` in the same directory, and start a new session. `/skill:review-pr #1234` then expands `#1234` into `$pr_ref`.
 
 ## Next steps
 

package/dist/docs/en/customization/skins.md

@@ -1,10 +1,8 @@
 # GUI Skins
 
-A skin changes how the Kiki GUI looks: its palette, its fonts, its corner radius and its density. Kiki ships six light–dark skin families, and you can add your own as a JSON file. You can also put a picture or video behind the window, or install an appearance pack that bundles colors with art.
+A skin sets the Kiki GUI's colors, fonts, corner radius and density. Kiki comes with six light–dark skin families, and you can add your own as a JSON file. A skin only sets design tokens — it carries no CSS and no code, so nothing you install can restyle an approval prompt or run anything on your machine.
 
-Skins are declarative only. A skin sets design tokens — it cannot add CSS rules or scripts, so it cannot hide an approval prompt, break a layout on upgrade, or run code.
-
-Light and dark stay a separate choice. A skin supplies a light variant, a dark variant, or both; the theme switch above the skin picker still decides which one you see.
+Light and dark remain a separate choice. A skin can supply a light variant, a dark variant, or both; the theme switch above the skin picker decides which one you actually see.
 
 ## Built-in skins
 
@@ -17,8 +15,6 @@ Light and dark stay a separate choice. A skin supplies a light variant, a dark v
 | **Iris × Starveil** | light, dark | Violet-white paper and iris ink; indigo-violet layers and silver-lilac controls at night. |
 | **High contrast × Obsidian** | light, dark | Visible borders and AAA main text; layered charcoal, ice-cyan focus and near-white controls at night. |
 
-Inkstone replaces the previous default dark palette within the Paper family. Linen, Graphite, Forest, Claret, Heather, Nocturne, Sand and Slate are retired. Stored built-in selections fall back to Paper in light mode and Inkstone in dark mode, including desktop space preferences. Your light / dark / system choice and accent, font, radius and density overrides stay intact. User skin files with the same names are not retired.
-
 ## Pick and adjust a skin
 
 Settings → Appearance:
@@ -34,15 +30,15 @@ The first page of the first-run setup (**Language and look**) has the same light
 Settings → Appearance → Background puts a picture or a short video behind the window.
 
 - **Choose picture or video**: PNG, JPEG, WebP, AVIF, GIF, MP4 or WebM, up to 25 MB for a picture or 100 MB for a video. The file stays on this device (in the browser's storage) and is never uploaded, so it works for a browser tab connected to a remote server too.
-- **Or paste a link**: an `https` link to a picture or video. The server fetches it once, following the media policy below, and the copy is kept on this device. The link is not loaded again, so it cannot track you and still works offline.
+- **Or paste a link**: an `https` link to a picture or video. The server fetches it once, under the policy in [Linked pictures](#linked-pictures), and keeps the copy on this device. Nothing is loaded from that link again, so it cannot track you and the background still shows offline.
 - **Show behind**: the whole window, only the conversation, or only the sidebar (tablet width and up).
 - **Fit** (fill, fit, tile, center), **Anchor** (nine points), **Picture strength**, **Blur**, **Brightness** and **Soften** (a wash of the window color over the picture).
 - **Panel opacity** and **Panel blur**: how much the sidebar and the conversation let the picture through.
 - **Separate for light and dark**: off by default. Turn it on to pick a different background for each theme.
 
-Text stays readable whatever you pick. Kiki measures the picture and raises **Panel opacity** just enough that the faintest text keeps WCAG AA (4.5:1) against the darkest and lightest parts of the picture. The setting says when it did. Menus, dialogs, approval prompts and the composer card always keep a solid background.
+Text stays readable whatever you pick. Kiki measures the picture and raises **Panel opacity** as far as it needs to keep the faintest text at WCAG AA (4.5:1) against the picture's lightest and darkest areas, and the setting tells you when it did that. Menus, dialogs, approval prompts and the composer card always keep a solid background.
 
-Video always plays muted and looped. It pauses on its first frame, or on the pack's poster, while the window is hidden or not focused, when reduced motion is on, and when the battery is low and unplugged. Kiki warns about videos larger than 1440p or 40 MB, which use a lot of memory for no visible gain behind the panels.
+Video plays muted and on a loop. It holds on its first frame — or the pack's poster — while the window is hidden or not focused, when reduced motion is on, and when the battery is low and you are unplugged. Kiki warns about videos above 1440p or 40 MB: they cost a lot of memory and you cannot see the difference behind the panels.
 
 ## The themes folder
 
@@ -56,13 +52,13 @@ Create it if it does not exist. **The filename is the skin id**: `ocean.json` ap
 After adding a file, press **Reload skins** in Appearance. No restart needed.
 
 ::: warning Which machine's folder?
-Kiki reads this folder **on the machine running kap-server**, because that is the only filesystem the server can see.
+The themes folder is read on the machine running the Kiki server, since that is the only filesystem it can see.
 
-- **Desktop app** — your own `~/.kiki/themes/`, as you would expect.
-- **Browser connected to a remote server** — the folder belongs to that server, not to the device you are browsing from. The built-in skins still work everywhere, since they ship in the app itself.
+- **Desktop app** — your own `~/.kiki/themes/`.
+- **Browser connected to a remote server** — the folder belongs to that server, not to the device you are browsing from. Built-in skins work either way, because they ship inside the app.
 :::
 
-Kiki never writes skin files here: exporting a skin hands you a file to place yourself. The one exception is appearance packs. **Import pack** and **Delete** create and remove pack folders in this directory, and nothing else.
+Kiki does not write skin files into this folder. **Export as skin file** hands you the file and you place it where you want it. Appearance packs are the exception: **Import pack** and **Delete** create and remove pack folders here, and do nothing else.
 
 ## Write a skin
 
@@ -129,7 +125,7 @@ Every value is `#rgb` or `#rrggbb`.
 | `shadowInk` | The color shadows and modal scrims are mixed from |
 
 ::: tip Keep text readable
-Kiki's untweaked built-in palettes hold WCAG AA (4.5:1) for body, secondary, faint and semantic text against `canvas`, `paper` and `panel`, and for `onAccent` against `accent`. Use `accentInk` for text rather than the button fill `accent`, especially in Paper. A skin that drops below that is still loaded — Kiki will not override your choice — but text gets hard to read. Check your `ink`, `inkSoft` and `inkFaint` against all three surfaces.
+Kiki's built-in palettes hold WCAG AA (4.5:1) for body, secondary, faint and semantic text against `canvas`, `paper` and `panel`, and for `onAccent` against `accent`. Set `accentInk` for text rather than reusing the button fill `accent`, especially in Paper. A skin below that contrast still loads, and Kiki will not correct it for you, so check your `ink`, `inkSoft` and `inkFaint` against all three surfaces before you ship it.
 :::
 
 ### Fonts
@@ -158,13 +154,13 @@ Always end a stack with a CJK-capable family or a generic (`sans-serif`, `serif`
 
 ## What happens on errors
 
-Skins are designed to never lock you out of your own interface:
+A bad skin never leaves you without an interface. Appearance reports what it did with each file:
 
-- **An invalid color or font value**: that one token is dropped and keeps its default; the rest of the skin applies. Appearance lists what was dropped.
-- **An unknown token**: ignored, reported in the same place.
-- **An unexpected top-level key** (for instance a `css` field): the whole file is rejected, because a skin carrying something other than tokens is not a skin. It appears under the skipped files list with the reason.
-- **Malformed JSON, or a TUI theme file**: skipped, listed with a reason, and the other files still load.
-- **A selected skin file that disappears**: the GUI falls back to the default palette and says the skin is missing, rather than silently applying a different one.
+- **An invalid color or font value**: that one token is dropped and keeps its default; the rest of the skin applies.
+- **An unknown token**: ignored.
+- **An unexpected top-level key** (for instance a `css` field): the whole file is rejected and listed with the reason, because a skin that carries anything besides tokens is not a skin.
+- **Malformed JSON, or a TUI theme file**: skipped with a reason, and the other files still load.
+- **A selected skin file that disappears**: the GUI falls back to the default palette and says the skin is missing, rather than quietly applying a different one.
 
 ## Appearance packs
 
@@ -203,22 +199,22 @@ Settings → Appearance → Appearance packs lists installed packs with their pr
 - `background.media` names 1–12 files; with more than one, `interval` (seconds) turns them into a carousel. `poster` is the still shown while a video is paused.
 - The background dials are `fit` (`cover` `contain` `tile` `center`), `alignment` (`center` `top` `bottom` `left` `right` `topLeft` `topRight` `bottomLeft` `bottomRight`), `opacity` (0–1), `blur` (0–40), `brightness` (0.4–1.4), `scrim` (0–0.9), `scope` (`window` `main` `sidebar`), `surfaceOpacity` (0.3–1) and `surfaceBlur` (0–32). The names follow Windows Terminal's background settings.
 
-`surfaceOpacity` controls the sheet wash on every GUI page and the inspector within the chosen background scope. Readability assist keeps local text washes in the conversation and settings, and frosts other page sheets and the inspector without raising their opacity. At low opacity, text over a busy picture can be harder to read even with assist on; raise `surfaceOpacity` for stronger separation. Dialogs, popovers and the composer card keep solid fills.
+`surfaceOpacity` sets how far the sheet washes on each GUI page — and the inspector — let the background through, within the scope you chose. Readability assist keeps the local text wash in the conversation and settings, and frosts the other page sheets and the inspector instead of raising their opacity. Text over a busy picture can still be hard to read at low opacity even with assist on; raise `surfaceOpacity` when you need more separation. Dialogs, popovers and the composer card keep solid fills.
 
 The built-in `kiki-appearance` skill walks an agent through making a pack: the format, the contrast rules for each color, media sizes and encoding, packaging, and the usual mistakes.
 
 ### What a pack can and cannot contain
 
-- **Only** the manifest and picture or video files it names: PNG, JPEG, WebP, AVIF, GIF, MP4, WebM. Anything else in the archive, whether a script, a stylesheet, SVG, HTML, a font, or a file the manifest does not name, refuses the whole pack.
-- Every file's first bytes must match its extension, so a renamed page cannot pass as a picture. Files are served with their true type, `nosniff`, and a sandboxing content policy.
+- **Only** the manifest and picture or video files it names: PNG, JPEG, WebP, AVIF, GIF, MP4, WebM. Anything else in the archive — a script, a stylesheet, SVG, HTML, a font, or a file the manifest does not name — refuses the whole pack.
+- Every file's first bytes must match its extension, so a renamed web page cannot pass as a picture. Files are served with their true type, `nosniff`, and a sandboxing content policy.
 - Limits: 25 MB per picture, 100 MB per video, 100 MB and 64 files per pack. Archive entries are checked against these before anything is decompressed.
-- **No custom CSS.** Tokens already reach every color, face and shape the app exposes. A stylesheet could also hide or restyle approval prompts, draw fake controls, or load tracking URLs, and a "safe subset" would be a permanent attack surface for little visual gain. A later format version can add a declarative slot without breaking version 1 packs.
-- Any unknown key fails the whole pack, unlike a skin file, which drops a bad token and keeps the rest. A pack is installed as a unit, and a half-accepted pack would pair media with colors the author never tested together.
+- **No custom CSS.** Tokens already reach every color, face and shape the app exposes, and a stylesheet could hide approval prompts, draw fake controls, or load tracking URLs.
+- A pack is installed as a unit, so any unknown key fails the whole pack — unlike a skin file, which drops a bad token and keeps the rest. Half-accepting a pack would pair media with colors the author never tested together.
 
 ### Linked pictures
 
-**Or paste a link** fetches through the server with a fixed policy: `https` only, no credentials in the URL, every redirect hop resolved and refused unless it points to a public internet address (no loopback, private, link-local or carrier-grade NAT ranges), at most three redirects, the same size limits, and the type checked from the bytes rather than the headers.
+**Or paste a link** fetches through the server, which allows `https` only, no credentials in the URL, at most three redirects, and the same size limits as an uploaded file. Every redirect hop is resolved and refused unless it points at a public internet address — loopback, private, link-local and carrier-grade NAT ranges are all out. The type is checked from the bytes, not from the response headers.
 
 ## Distribution
 
-The skin format is deliberately shaped so a skin can ship inside a plugin as a declarative contribution: the server lists an enabled plugin's `x-kiki.themes` entries beside your own skin files, marked with the plugin that contributed them. Share a standalone skin as a `.json` file, bundle it with a plugin, or ship colors with art as an appearance pack.
+An enabled plugin can ship skins. Anything it declares under `x-kiki.themes` appears in the picker beside your own skin files, marked with the plugin that contributed it. To share a skin of your own, send the `.json` file, bundle it into a plugin, or ship colors with art as an [appearance pack](#appearance-packs).

package/dist/docs/en/customization/themes.md

@@ -1,16 +1,16 @@
 # Custom Themes
 
-Kiki can use a built-in color scheme or a custom JSON theme file. Custom files live in the themes directory and appear in `/theme` alongside the built-in choices.
+Kiki can use a built-in color scheme or your own JSON theme file. Custom files live in the themes directory and show up in `/theme` next to the built-in choices.
 
 ::: tip Terminal themes and GUI skins
-This page describes **terminal (TUI) themes**. The GUI has its own file format, called a **skin**, which covers colors, fonts and shape rather than only terminal colors — see [GUI Skins](./skins.md).
+This page covers **terminal (TUI) themes**. The GUI uses its own format called a **skin**, which covers colors, fonts and shape as well — see [GUI Skins](./skins.md).
 
-Both live in the **same directory** (`~/.kiki/themes/`) and are told apart by content: a file with `"kind": "kiki-skin"` is a GUI skin, anything else is a TUI theme. Each loader ignores the other's files, so you can keep both side by side. A TUI theme does not restyle the GUI, and a skin does not restyle the terminal.
+Both live in the **same directory** (`~/.kiki/themes/`) and are told apart by content: a file with `"kind": "kiki-skin"` is a GUI skin, anything else is a TUI theme, and each loader ignores the other's files. A TUI theme does not restyle the GUI, and a skin does not restyle the terminal.
 :::
 
 ## Built-in color tokens
 
-Custom themes can override the tokens below. The `dark` and `light` columns show the built-in values; `auto` resolves to one of those palettes at startup, and falls back to `dark` when terminal background detection is unavailable.
+A custom theme can override any token below. The `dark` and `light` columns are the built-in values; `auto` resolves to one of them at startup and falls back to `dark` when terminal background detection is unavailable.
 
 | Token | `dark` | `light` | What it controls |
 | --- | --- | --- | --- |
@@ -34,17 +34,15 @@ Custom themes can override the tokens below. The `dark` and `light` columns show
 | `roleUser` | `#FFCB6B` | `#9A4A00` | User message bullet and text, skill-activation name |
 | `shellMode` | `#BD93F9` | `#7C3AED` | Shell mode (`!`) prompt, editor border, and the echoed `$ command` line |
 
-## Use the theme skill
+## Let the skill write it
 
-You do not need to write the JSON by hand. Run the built-in `/kiki-ops [request]` skill command and describe the theme you want; the skill can choose colors, write the file under `~/.kiki/themes/`, validate the hex values, and tell you how to apply it.
-
-Example invocations:
+You do not have to write the JSON by hand. Run `/kiki-ops` and describe the theme you want — the skill picks the colors, writes the file under `~/.kiki/themes/`, checks the hex values, and tells you how to apply it.
 
 - `/kiki-ops Create a warm dark theme with amber accents.`
 - `/kiki-ops Make a light theme based on Solarized, but keep errors easy to see.`
 - `/kiki-ops Tweak my ember theme so diffs have higher contrast.`
 
-After activation, the skill usually asks whether you want a light or dark base, what mood or palette you prefer, and whether you have exact colors to include. If you use it to edit an existing theme, make sure it reads and backs up the file before overwriting it.
+It will usually ask whether you want a light or dark base, what mood or palette you prefer, and whether you have specific colors to include. When you ask it to edit an existing theme, it reads and backs the file up before overwriting.
 
 ## Create a theme
 
@@ -90,8 +88,8 @@ Use the token names from [Built-in color tokens](#built-in-color-tokens). Any to
 
 Two ways:
 
-1. **The `/theme` command** (recommended): opens the theme picker, where custom themes appear as `Custom: <filename>`. The picker **re-scans the themes directory every time it opens**, so a theme file you just added shows up **without a restart**.
-2. **`tui.toml`**: set `theme` to your theme name:
+1. **The `/theme` command** — opens the picker, where your themes appear as `Custom: <filename>`. The picker re-scans the directory each time it opens, so a file you just added shows up without a restart.
+2. **`tui.toml`** — set `theme` to the theme's name:
 
    ```toml
    # ~/.kiki/tui.toml
@@ -100,11 +98,13 @@ Two ways:
 
 ## What happens on errors
 
-Custom themes are designed to never get in your way:
+A bad value never stops the theme from loading:
 
-- **An invalid color value** (not `#` followed by 6 hex digits): that one entry is silently skipped and falls back to the selected base palette; the rest of the colors still apply.
+- **An invalid color value** (not `#` followed by 6 hex digits): that one entry is skipped and falls back to the selected base palette; the rest still apply.
 - **An unrecognized token**: ignored, with no effect on other colors.
-- **A missing custom theme file or malformed JSON**: silently falls back to the built-in `dark` palette. It does not retry `auto`.
+- **A missing theme file or malformed JSON**: falls back to the built-in `dark` palette, not to `auto`.
+
+If your changes do not appear at all, check that the filename matches `name` in the file — that mismatch is the usual cause, and it fails silently.
 
 ## Editing the active theme
 
@@ -114,5 +114,5 @@ If you edit the theme file that is **currently active**, the change is not reloa
 - switch to another theme in `/theme` and back.
 
 ::: warning Note
-Re-selecting the **same** theme in `/theme` does not reload it (you get a "Theme unchanged" message). To reload changes to the active theme, use one of the two methods above.
+Picking the **same** theme again in `/theme` does not reload it — you get "Theme unchanged". Use `/reload-tui`, or switch to another theme and back.
 :::

package/dist/docs/en/features/agents.md

@@ -0,0 +1,85 @@
+---
+title: Agent Profiles
+---
+
+# Agent Profiles
+
+An **agent** is the thing that actually does the work: it reads files, runs commands, calls tools, and answers. Every agent in Kiki is defined by a **profile** — one Markdown file that says which model and thinking effort it runs on, how it is instructed, which tools it may call, and which agents it can hand work to. Write a profile once and every dispatch of that kind of agent reuses it.
+
+This page explains what an agent is, how the main agent and subagents differ, and how to choose and combine profiles. The full field reference lives in [Agents and Sub-Agents](/en/customization/agents) and [Agent profiles: concepts and design](/en/customization/agent-profiles).
+
+## The main agent and its subagents
+
+You talk to one agent per session: the **main agent**. It receives your messages, plans, calls tools, and produces the replies you see. When a piece of work is worth isolating, the main agent dispatches a **subagent** to handle it — a coding change that needs exploring first, several implementations to review in parallel, a large refactor to plan without loading the main context.
+
+A subagent is given a task description and works in its own isolated context. It reports back with its conclusions and a note when it finishes; its full reasoning and tool records are not poured into the main agent's conversation, which is what lets several lines of work run at once without the main context filling with detail. That is context isolation, not a sealed box: you can open any subagent to read its own transcript, and message it yourself from its composer — see [A subagent keeps its own record](/en/features/workbench#a-subagent-keeps-its-own-record).
+
+A dispatch tree in which a lead session has spawned several subagents, each with its own model bound\.
+
+Each subagent spends model tokens of its own, so handing over a task the main agent could finish in one step is pure extra cost. Whether the remaining work is separable enough to hand off is the main agent's own judgment, and naming a role yourself overrides it.
+
+### How a profile becomes a main agent
+
+A profile is not a main agent or a subagent by itself. Which one it is depends on how it is bound:
+
+- **Selected as the session's main agent** — with `--agent` in the terminal, or from the profile selector when you start a session. This is the agent you talk to.
+- **Dispatched as a subagent** — when the main agent hands it a task. This is the normal case for every other role.
+- **Run independently** — an external host such as an MCP client, an SDK caller, or an external executor invokes the agent on its own. It is not a subagent of this session, so Kiki gives it the standalone handoff notice instead of the subagent one, but the host is still the side that receives its result.
+
+The profile picker on the New session page, listing the profiles that can drive a session and the one currently checked\.
+
+The `main: true` frontmatter flag marks a profile as a *candidate* for the session's main agent, which is what puts it in the selector. It is not an authorization gate: naming such a profile explicitly in a dispatch still runs it as a subagent, and it never becomes the session's main agent that way. The actual binding is what you select, and the flag only decides what you can select from.
+
+The session's main agent runs on the model you pick for the session, which overrides whatever its profile pins. A subagent resolves its own model separately, in order: an explicit `model_alias` on the dispatch, then the pin or model menu of the profile it runs as, then `[subagent].default_model`. A profile left without a pin and no default configured fails the dispatch with `model.not_configured` rather than silently inheriting the caller's model — except for the templates that set `model_alias: inherit` on purpose. So the model you choose in the menu governs the agent you are talking to, and what a profile pins governs every agent dispatched as that role.
+
+### One model, shared settings, differences only where you want them
+
+When the same model serves both roles, you do not define it twice. A model is defined once — its alias, provider, credentials, context window, and supported efforts — and the roles share the usual operating settings such as default effort, service tier, when the context compresses, and the context budget. The main agent can override just the ones that should differ, and anything it leaves unset is inherited; a subagent simply uses the shared values.
+
+So a single model can be set to a high effort for the agent you talk to and the default elsewhere, or compress at a tighter point for the main agent while subagents keep the shared trigger. Everything not named stays shared, and an explicitly chosen model or effort in a session still wins. Prompt fields follow the same split between shared, main, and independent: parameters are inherited field by field, while the old prompt identity blocks still replace as a whole. See [`models` in the config reference](/en/configuration/config-files#models) and [Model menus and hard boundaries](/en/customization/agent-profiles#model-menus-and-hard-boundaries) for the exact rules.
+
+## One file describes the role
+
+The **frontmatter** carries the configuration — the name, the description the dispatcher reads, the model and thinking effort, the tool allowlist, and which subagents the role may itself dispatch. The **body** is the system prompt the agent starts from. Nothing else is required: a profile is plain text you can read, diff, and keep in version control.
+
+Fresh installs ship three roles you can use immediately: the main `agent` that drives sessions, `general`, a general-purpose subagent that can read, write, run commands, and search, and `explore`, a read-only explorer for mapping unfamiliar code.
+
+**Settings → Agents** is where they all live. One list, main agents and subagents side by side, each row showing its model, effort, and which child agents it may create — with the file each one comes from when you need to edit it.
+
+The Settings \> Agents list, with main agents and subagents grouped and each role's model, effort, and permitted child agents on its row\.
+
+## The roles worth writing
+
+Two more ship as templates, because most work divides into the same two shapes:
+
+- **`implementer`** owns one technical objective end to end — investigate, implement when authorized, verify, and hand off with evidence. It may use `explore` for read-only groundwork but keeps the final engineering judgment.
+- **`reviewer`** judges a decision, a candidate, or a repair independently and read-only, reporting findings without changing the work. Its tools are restricted so it cannot edit or dispatch.
+
+Both templates set `model_alias: inherit`, so the role follows whatever model dispatched it unless you pin one. You can add them from first-run setup, the `/kiki-profile` skill, or **Settings → Agents**.
+
+Editing one opens its own page. The form covers the fields that matter — the instructions it starts from, the description the dispatcher reads, when to use it, model, effort, engine, whether it can drive a session, and which child agents it may create — with a **Raw file** tab beside it when you would rather read or write the Markdown directly.
+
+The agent editor: instructions, description, when to use it, model, effort, engine, the main-agent switch, and the child agents this role may create\.
+
+Writing your own pays off when a kind of work recurs and has house rules: a reviewer that must cite file and line, a tester that always runs the suite before reporting, an implementer that must not touch generated files. Starting from a copy of a role that already works, or from a shipped template, beats starting blank.
+
+## Deciding which one runs
+
+You rarely pick a profile by hand. The main agent dispatches on the `description` and `whenToUse` each profile declares, so those two lines decide the work — write them for the dispatcher, not for yourself. You can still steer: ask for a role by name ("use `explore` to map the files first"). Whether a dispatch stops for your approval depends on the session's [permission mode](/en/guides/interaction#permission-modes) — under `manual` each one is a request you read and accept or reject, while `auto` and `yolo` let routine dispatches proceed.
+
+Where a role runs is also yours to fix. Bind the main agent, each subagent, and the reviewer to different models or vendors so a strong model plans while cheaper ones do routine work. Set a hard allowlist when a role must not run an expensive model, and a model menu with `restrict_models_to_menu: true` when the profile already maintains a complete permitted set. See [Providers and models](/en/configuration/providers) and [Model menus and hard boundaries](/en/customization/agent-profiles#model-menus-and-hard-boundaries).
+
+Edits reload in about 200 ms and newly dispatched agents pick them up immediately. A session already in flight keeps the profile snapshot it started with, so use **Rebuild context** in that session to apply the change without losing the conversation. See [Profile reloads and live sessions](/en/customization/agents#profile-reloads-and-live-sessions).
+
+## A profile is not a persona
+
+A profile is execution configuration: tools, permissions, model, effort, and the prompt the role starts from. A [persona](/en/features/people) is identity: who someone is, what they are for, and what they remember across conversations. A persona card names the profile it rides on, and you can rebind that profile without losing the identity.
+
+## Next steps
+
+- [Agents and Sub-Agents](/en/customization/agents) — the field reference and dispatch contract
+- [Agent profiles: concepts and design](/en/customization/agent-profiles) — where profiles live and when changes take effect
+- [One workbench, many lines](/en/features/workbench) — what the main session does with a dispatched tree
+- [Every layer is yours](/en/features/freedom) — prompt overrides, connections, permission modes, and hooks
+
+[Online version with images](https://x-t-e-r.github.io/kiki/en/features/agents.html)

package/dist/docs/en/features/daily.md

@@ -4,7 +4,7 @@ title: The daily driver
 
 # The daily driver
 
-The workbench is one window, but the work is not: a turn runs, a subagent finishes, something needs your approval, and the cost adds up. This page is about the parts of that window you look at every day — the timeline that stays readable, annotations you can leave on a message, the tray that collects what needs you, the right rail that follows whichever agent you are focused on, and the usage page that tells you what it cost.
+The workbench is one window, but the work is not: a turn runs, a subagent finishes, something needs your approval, and the cost adds up. This page is about the parts of that window you look at every day — the timeline that stays readable, annotations you can leave on a message, the tray that collects what needs you, the right rail that follows whichever agent you are focused on, and the usage page that tells you what it cost, what is holding a request up, and where those numbers can go.
 
 ## A timeline that stays readable
 
@@ -12,7 +12,7 @@ A long agent turn is mostly tool calls, thinking, and shell output. The conversa
 
 Resolved questions, approvals, markers, and completion notices stay inline at their original position as compact one-line entries. Consecutive entries fold into an expandable "Activity history" row, and consecutive identical marker dividers (such as goal updates) show only the latest one with a repeat count, for example "Goal updated ×12", when nothing separates them. Reopening a session shows model changes as dividers naming the previous and new model; changing only thinking effort does not add one.
 
-Long tool output loads in stages — **Continue loading** pulls in the rest, and if that fails on a field that has an original to fetch, the same place offers **Download original** to save the field's full content to your machine. See [Interface overview](/en/guides/interface#conversation-view).
+Long tool output loads by itself as you scroll: Kiki keeps reading the next segment in the background and the row under the body shows the progress. If a segment fails, it stops there and offers **Retry**, and where the server keeps an original for that field the same row offers **Download original** to save the field's full content to your machine. See [Interface overview](/en/guides/interface#conversation-view).
 
 ## Annotations: say something about a message
 
@@ -34,15 +34,45 @@ It shows the agent's head over what it is doing now, "needs you" items as plain
 
 See [Interface overview](/en/guides/interface#right-rail) and [Session controls](/en/guides/settings#session-controls).
 
-## The usage page tells you what it cost
+## The usage page answers three different questions
 
-**Usage** in the sidebar opens **History** by default: token usage and estimated cost for a date range, defaulting to today. Token usage and cost carry separate completeness indicators — when a provider does not return usage, Kiki marks it as unknown rather than a real zero — and the **Data reliability** section distinguishes unknown providers and incomplete accounting from an empty range or a failed request.
+**Usage** in the sidebar is one page with three tabs. **History** answers what a date range cost, **Live** answers why nothing is moving, and **External sync** answers where you want the numbers to go.
 
-**Live** shows running and queued requests for this service, with a per-model, provider, and role breakdown, waiting rows naming the blocking rule, and **Concurrency limits** for adding or editing rules. **External sync** sends content-free usage (model, UTC half-hour, four token counts, quality, cost) to vibecafe.ai, a Kiki webhook, or your own script — never a prompt, answer, title, workspace name, or path. It stays off until the server enables the `usage_export` flag, and a saved destination sends nothing until you preview the exact payload and agree once.
+### History: what the range cost
 
-See [Usage](/en/guides/settings#usage) and [`kiki usage-export`](/en/reference/command#kiki-usage-export).
+**History** opens by default: token usage and estimated cost for a date range, starting at today. The filter bar drives it — range first, then workspace, bucket size, and what the chart is broken down by — and every choice rides the URL, so a view you settled on is a link you can paste. Under the four totals, the trend chart stacks by the breakdown axis, a bucket opens into the sessions and turns behind it, and the tabs below rank sessions by cost so the expensive one is the first row.
 
-The usage page in History, with token and cost per session and a note on how complete the data is\.
+The number it will not give you is a confident wrong one. Token usage and cost carry **separate** completeness indicators: when a provider does not return usage for a call, Kiki marks it unknown rather than recording a real zero, and a figure with unknowns in it is shown as partially unknown instead of a total. **Data reliability** then separates the cases a reader must not confuse — a provider that never reported, accounting that is incomplete, a range with nothing in it, and a request that failed. The cost itself is a local estimate from your own price table; **Model prices** in the header is where an unpriced model gets one, and the page names the models it could not price rather than quietly pricing them at zero.
+
+The usage page on its History tab: cost, token, and cache-hit totals for the range, a seven-day trend, and the per-session breakdown below\.
+
+### Live: who is running, who is waiting, and which rule is holding them
+
+**Live** is the other half of the same page, and it answers the question a spending page raises the moment something feels slow. It counts what this Kiki service is running and what it is holding, and **Request details** breaks those counts down by model, provider, or role.
+
+The part that makes it useful is the **Waiting now** list. Each waiting row names the model, how long it has been waiting, and which concurrency rule is holding it back, by rule id. That id is the same one in the **Concurrency limits** editor directly below, so the row tells you which rule to change.
+
+A rule picks a target (specific models, specific providers, or everything), a scope (**All sessions** shares one budget across the service; **Each session** gives every session its own), a cap, and what happens past it: **Queue** waits for a slot, **Reject** fails the request immediately. A rule can also carry a wait budget, and a rule targeting only subagents is a switch away. The toggle beside a rule pauses it without deleting it or dropping its wait budget, and saving applies to new and queued requests without killing anything already streaming — which is why raising a cap can release a queue while lowering one can leave running requests briefly above the new limit.
+
+Two boundaries worth knowing before you tune this. The cap counts **requests**, not tokens, money, or agents — it is not a spending budget. And it governs model requests this Kiki service sends itself: when you hand a turn to Codex, Claude Code, or Grok Build as the engine, those requests are the engine's own and do not pass through these rules. An external tool that calls back into Kiki to run a native request does count, as Kiki's own.
+
+The usage page on its Live tab: running and queued counts by model, a waiting request naming the kimi-cap rule that holds it, and the concurrency rules below with one enabled and one paused\.
+
+### External sync: send the numbers somewhere you chose
+
+**External sync** sends this server's own usage to a destination you pick, on a schedule you pick. It is the tab for a person who wants their token counts somewhere other than this app: a team warehouse, a personal script, or a hosted service. Three kinds of destination are available:
+
+- **Kiki webhook** — your own HTTPS endpoint, receiving a documented JSON batch. Bearer or HMAC authentication, optional gzip, and a secret you can keep in the system keyring or, if you prefer, in a private file on the server; you may narrow the range, exclude workspaces, and keep temporary sessions out.
+- **VibeCafe** — signs in from the page itself with a device code, against the official service. A custom address, or a key you supply yourself, is a separate advanced path. The sign-in is part of the experimental `usage_export` feature: the device-code flow is implemented, but it has not yet been verified end to end against the live service.
+- **Script** — a command you approve. Kiki writes the batch to its stdin and reads a receipt from its output. It runs as your own OS user with your ordinary permissions, so it can read files and reach the network on its own; **this is not a sandbox**, and approval is per command, not per batch.
+
+What crosses the wire is deliberately small: the model, a UTC half-hour bucket, four token counts, a quality flag, and a local cost estimate. Prompts, answers, titles, workspace names, and paths are not part of the payload — though the receiving end can still see your address and when you work, and the model name it sees may be an opaque id rather than your local alias. Every destination shows its own state: active, paused, waiting to be sent, refused credential, or a service that already holds a different value. A pause keeps the queue; removing a destination asks separately whether to discard what is still pending.
+
+The whole feature is off by default until the server enables the `usage_export` flag, and a saved destination stays **disabled until you preview the exact payload and agree once**. Widening the range, changing the endpoint, or pointing the destination at a different credential asks again; narrowing the range or changing the interval does not.
+
+The usage page on its External sync tab: three destinations — a webhook that is active, a VibeCafe connection whose credential was refused with its queue intact, and a script that is paused — each with its endpoint, state, and pending count\.
+
+The same destinations can be managed from the terminal with [`kiki usage-export`](/en/reference/command#kiki-usage-export), and every control on this page has a documented field, error code, and limit behind it: see [Usage](/en/guides/settings#usage) for where each control lives and [`request_governance`](/en/configuration/config-files#request-governance) for the rules' full field reference.
 
 ## Next steps
 

package/dist/docs/en/features/ecosystem.md

@@ -36,7 +36,9 @@ See [Using Kiki in IDEs](/en/server/ide), [`kiki acp`](/en/server/acp), and [`ki
 
 The direction reverses: another agent harness runs *your* subagent. An agent profile can carry an `executor` and run on Claude Code, Codex, Cursor, Gemini CLI, Kimi CLI, OpenCode, or Grok Build over ACP or the Codex app-server. Settings → External engines checks whether each one is installed and shows the setup steps that remain.
 
-This is not the same as a seat. A seat is a fixed place external tools call into; an external executor is a place Kiki dispatches out to. When the external harness is the main agent instead, `allow_kiki_subagents: true` lets it dispatch Kiki subagents back, and `kiki_context` can expose Kiki's own native context — memory, board, cron, threads, history, hooks — to it over the same bridge, with child completions queued back to the main agent. The profile's tool policy, dispatch policy, model constraints, and notification policy still apply across that bridge; it is a call path, not a bypass.
+The external engines list, with each engine's install state, what Kiki can set on it, and any check details that remain\.
+
+A seat is a fixed place external tools call into; an external executor is a place Kiki dispatches out to. When the external harness is the main agent instead, `allow_kiki_subagents: true` lets it dispatch Kiki subagents back, and `kiki_context` can expose Kiki's own native context — memory, board, cron, threads, history, hooks — to it over the same bridge, with child completions queued back to the main agent. The profile's tool policy, dispatch policy, model constraints, and notification policy still apply across that bridge.
 
 See [External main-agent delegation](/en/customization/agents#external-main-agent-delegation) and [Kiki context in external main agents](/en/customization/agents#kiki-context-in-external-main-agents).
 

package/dist/docs/en/features/extend.md

@@ -10,7 +10,7 @@ Beyond the model, the prompt, and the tools an agent already has, Kiki has four
 
 A plugin is the packaging unit. One plugin can contribute skills, agents, MCP servers, hooks, commands, tools, and sandboxed panels, and you can browse, install, and configure plugins on the **Capabilities** page. Claude Code plugins with a `.claude-plugin/plugin.json` manifest install too, and you can point Kiki at your own marketplace JSON.
 
-The official marketplace is maintained by Kimi and currently has three plugins: **Kimi Datasource** (query market data, macro indicators, company registrations, academic literature, and laws in natural language), **Kimi Browser Extension** (let AI drive your own browser), and **Kimi Computer Use** (let AI operate your desktop apps). Two more capabilities are separate plugins, not part of that trio: **Kiki Documents**, which converts a local PDF, Office, HTML, or text file into Markdown that `Read` and `Grep` can use, and **Kiki Notion**, a configuration and workflow for Notion's hosted MCP service. Installing a plugin never runs its hooks by itself — they fire only when their matching event occurs while the plugin is enabled. See [Plugins](/en/customization/plugins).
+The official marketplace is maintained by Kimi and currently has three plugins: **Kimi Datasource** (query market data, macro indicators, company registrations, academic literature, and laws in natural language), **Kimi Browser Extension** (let AI drive your own browser), and **Kimi Computer Use** (let AI operate your desktop apps). Two more capabilities are separate plugins, not part of that trio: **Kiki Extract**, which converts a local PDF, Office, HTML, or text file into Markdown that `Read` and `Grep` can use, and **Kiki Notion**, a configuration and workflow for Notion's hosted MCP service. Extracting a file is a reading step — it makes an existing document searchable, and it neither creates nor edits Office documents. Installing a plugin never runs its hooks by itself — they fire only when their matching event occurs while the plugin is enabled. See [Plugins](/en/customization/plugins).
 
 Media generation is a separate, experimental capability: a media plugin contributes one or more *sources* for images, video, or speech, which you configure under **Capabilities → Plugins → Media sources**. Generation is **off by default** and has to be turned on explicitly; it is a capability to enable on purpose, not a default.
 
@@ -30,8 +30,14 @@ MCP tools reach the agent exactly like built-in tools, with the same approval mo
 
 `WebSearch` and `FetchURL` are backed by an inspectable search and retrieval module. **Settings → Search & retrieval → Overview & source** shows which configuration source is in effect and whether the server reuses your local search configuration; `/mcp`-style status and the readiness of each named lane are visible there too. Search runs on named lanes you can inspect — some, like GitHub repository search, work without a key, and multiple keys for one provider rotate across calls. A fetch runs a chain with visible fallbacks, so you can see which extractor produced the text. The equivalent configuration lives in `config.toml` under `nb_search`. See [Search and retrieval](/en/guides/settings#search-retrieval) and [Config files: `nb_search`](/en/configuration/config-files#nb-search).
 
+The search lanes tab: the default lane, the pinned ones, and every other lane with where its results and credentials come from\.
+
+The fetch chain tab, with the pipelines a web address is read through in order and what each one falls back to\.
+
 ## Next steps
 
 - [Plugins](/en/customization/plugins) — the full plugin reference
 - [Agent Skills](/en/customization/skills) — writing a skill
 - [Model Context Protocol](/en/server/mcp) — connecting MCP servers
+
+[Online version with images](https://x-t-e-r.github.io/kiki/en/features/extend.html)

package/dist/docs/en/features/freedom.md

@@ -36,12 +36,16 @@ Prompt field overrides, down to one tools description, beside a live preview of
 
 Account connections use **OAuth**. The device flow shows you a code, an **Open verification page** link, how long it stays valid, and **Cancel sign-in**, and the row's status is a word meant for a person: **Connected** (Kiki renews it on its own), **Sign-in expired** (the provider no longer accepts it), **Sign-in didn't finish** (you declined it, the code expired, or it failed), or **Waiting for you**. Signing out ends that sign-in in Kiki and removes the models it provisioned; it does not sign you out at the provider.
 
+A device sign-in in progress: the code to enter on the verification page, how long it stays valid, and the cancel action\.
+
 **Reusing a sign-in this machine already has** is one way to get an OAuth credential, not a rival to it. For ChatGPT (Codex) and Grok Build, a connection can use the sign-in their own app already holds on this machine. Kiki reuses it and renews it; it does not copy the credential, does not start the other app, and signing in or out here does not change anything there. The order is deliberate: **Check this machine** first reports which account is on the other side and where it is kept, and only then is **Use this sign-in** offered — carrying the account it just showed you, so a credential replaced in between is refused rather than adopted silently. When the machine cannot be used, the page says why in terms you can act on.
 
 A sign-in that completes adds that account's models to the catalog. **Available models** is the authority on what you can actually use right now. See [Connections](/en/guides/settings#connections).
 
 The connections list: each connection is one row, and its authentication is part of that row\.
 
+Reusing a sign-in this machine already holds: what was found and where it is kept, with the action that adopts it\.
+
 ## Permission modes: how often it asks
 
 `/permission` switches among Manual, Auto, Approve for me, and YOLO. In the default Auto mode, routine tool calls run without asking, but sensitive-file and external-link access still request approval. Manual asks before shell commands and workspace-external writes, while trusted-workspace `Write` / `Edit` calls run without per-file approval. YOLO skips sensitive-file prompts unless a rule explicitly denies them. An explicit deny always wins, and the agent can still ask you questions in any mode.