kiki-agent-lite 0.3.1 → 0.3.2

package/dist/docs/en/getting-started/installation.md

@@ -1,11 +1,13 @@
 # Installation
 
-Kiki ships in three forms that share one daemon (the background process Kiki keeps running so all forms share session data) and one session store: the **Kiki desktop app** for Windows, Linux, and macOS, the **CLI/TUI** (TUI — the text-based interface inside the terminal) for the terminal, and a local **server** for browser and API clients. This page covers how to install and update each form; see [First launch](./first-launch.md) for what to do after installation.
+Kiki ships as three forms — the **Kiki desktop app** for Windows, Linux, and macOS, the **CLI/TUI** (TUI — the text interface you type into inside a terminal), and a local **server** for browser and API clients. They share one background daemon (the process Kiki keeps running so every form sees the same session data) and one session store, so you can start a task in the terminal and pick it up in the desktop app.
+
+This page covers installing and updating each form. [First launch](./first-launch.md) covers what to do next.
 
 ::: tip Before you install
-Kiki's terminal form runs fine in any modern terminal — Windows Terminal and your system's built-in terminal need no adjustments.
+Kiki's terminal form runs in any modern terminal. Windows Terminal and your system's built-in terminal need no changes.
 
-For the best visual experience (sharper font rendering and icon display), use a terminal with true-color and ligature support, such as [Kitty](https://sw.kovidgoyal.net/kitty/) or [Ghostty](https://ghostty.org/). This is optional; everything works without it.
+A terminal with true-color and font ligatures renders the interface more crisply — [Kitty](https://sw.kovidgoyal.net/kitty/) and [Ghostty](https://ghostty.org/) are two good choices. Any terminal works if you skip this.
 :::
 
 ## Install the desktop app
@@ -25,20 +27,29 @@ macOS needs **13.5 or later**; that floor comes from the bundled runtime, so it
 2. Download the desktop bundle for your system and its adjacent `.sha256` file. Compare the published hash with your downloaded file (`shasum -a 256 <file>` on macOS, `sha256sum <file>` on Linux, or `Get-FileHash <file> -Algorithm SHA256` in Windows PowerShell).
 3. Install it: run the Windows installer or `sudo apt install ./Kiki_*.deb`; on Linux AppImage, run `chmod +x Kiki_*.AppImage` then `./Kiki_*.AppImage`; on macOS, mount the dmg and drag Kiki to Applications.
 
-The macOS dmg is **not Apple-signed or notarized**. After verifying it, Control-click the app in Applications and choose **Open** on first launch, then confirm **Open** in the dialog. If macOS still blocks it and you trust the verified download, remove quarantine with `xattr -dr com.apple.quarantine /Applications/Kiki.app`; this disables Gatekeeper's quarantine check for that app copy. To run its CLI from a terminal, first check that `/usr/local/bin/kiki` does not already exist, then run `sudo mkdir -p /usr/local/bin` followed by `sudo ln -s /Applications/Kiki.app/Contents/MacOS/kiki-server /usr/local/bin/kiki`. The Windows SmartScreen note and updater details are in [Kiki desktop](./desktop-app.md).
+The macOS dmg is **not Apple-signed or notarized**. After verifying the hash, Control-click the app in Applications and choose **Open** on first launch, then confirm **Open** in the dialog. If macOS still blocks it, remove the quarantine flag from that copy with `xattr -dr com.apple.quarantine /Applications/Kiki.app`.
+
+The dmg puts no `kiki` command on your `PATH`. To use the bundled CLI from a terminal, first check that `/usr/local/bin/kiki` does not already exist, then run:
+
+```sh
+sudo mkdir -p /usr/local/bin
+sudo ln -s /Applications/Kiki.app/Contents/MacOS/kiki-server /usr/local/bin/kiki
+```
+
+For the Windows SmartScreen prompt and updater details, see [Kiki desktop](./desktop-app.md).
 
 ## Install the CLI
 
-For a terminal-only install, choose a standalone executable on [GitHub Releases](https://github.com/X-T-E-R/kiki/releases) under `kiki-v<version>`. There is no separate Windows CLI download; the Windows desktop installer provides `kiki`.
+For a terminal-only install, pick the standalone executable for your platform from a `kiki-v<version>` tag on [GitHub Releases](https://github.com/X-T-E-R/kiki/releases). Windows has no standalone CLI file; the desktop installer provides `kiki` there.
 
 | Platform | Standalone file |
 | --- | --- |
 | Linux x64 / ARM64 | `kiki-linux-x64` / `kiki-linux-arm64` |
 | macOS Intel / Apple Silicon | `kiki-darwin-x64` / `kiki-darwin-arm64` |
 
-Download its `<filename>.sha256` file, compare its hash, rename the downloaded executable to `kiki`, set executable permission with `chmod +x kiki`, and put it on your `PATH`. A standalone SEA executable does not require Node.js. `kiki desktop` launches the desktop app when installed, or shows an installation link when absent.
+Download the file together with its `<filename>.sha256` companion, compare the two hashes, rename the executable to `kiki`, run `chmod +x kiki`, and put it somewhere on your `PATH`. A standalone executable needs no Node.js. Once the desktop app is installed, `kiki desktop` opens it; without an installation it prints a download link.
 
-With Node.js 24.15.0 or later, npm offers two alternatives:
+With Node.js 24.15.0 or later you can install from npm instead:
 
 ```sh
 npm install -g kiki-agent       # CLI/TUI and the matching desktop build
@@ -46,11 +57,13 @@ npm install -g kiki-agent-lite  # CLI/TUI only
 kiki --version
 ```
 
-Choose one npm package, not both at the same time: each supplies the same `kiki` command. The full package downloads and SHA-256-verifies the platform desktop asset during installation, so it needs network access and supports Windows/Linux x64 and macOS Intel/Apple Silicon; the lite package does not download a desktop bundle. On Windows, [Git for Windows](https://gitforwindows.org/) is a required shell dependency for both install routes. Install it before first launch; if Git Bash is installed in a custom location, set `KIKI_SHELL_PATH` to the absolute path of `bash.exe`.
+Install one of the two, not both — each one provides the same `kiki` command. `kiki-agent` also downloads the desktop build for your platform and verifies its SHA-256, so it needs network access during install and covers Windows and Linux x64 plus macOS Intel and Apple Silicon. `kiki-agent-lite` ships the CLI only.
+
+On Windows, both packages need [Git for Windows](https://gitforwindows.org/) for their shell dependency — install it before your first run. If you installed Git Bash somewhere other than the default location, set `KIKI_SHELL_PATH` to the absolute path of `bash.exe`.
 
 ### Development from source
 
-Kiki's source repository is a pnpm (a Node.js package manager) workspace. Developing from source is for users who want to hack on or debug the CLI itself. It requires Node.js `24.15.0` or later and pnpm `10.33.0`. From the repository root:
+Working on the CLI itself needs Node.js `24.15.0` or later and pnpm `10.33.0`. The repository is a pnpm (Node.js package manager) workspace; from its root:
 
 ```sh
 node --version
@@ -59,7 +72,7 @@ pnpm install
 pnpm dev:cli -- --help
 ```
 
-The root `dev:cli` script starts the local development environment and forwards `--help` to the CLI entry point; no published package or global install is required.
+`dev:cli` starts the local development build and forwards `--help` to the CLI entry point, so nothing needs to be published or installed globally.
 
 ## Update and uninstall
 
@@ -69,9 +82,11 @@ For a release build, verify the installed version before upgrading:
 kiki --version
 ```
 
-**Update**: replace a standalone `kiki` executable with the matching newer Release asset, or run `npm install -g kiki-agent@latest` / `npm install -g kiki-agent-lite@latest` for an npm installation. On Windows, the desktop app can also check and install signed NSIS updates from **Settings → About** — see [Kiki desktop](./desktop-app.md#update). Linux and macOS desktop bundles require a new manual download; they do not use that Windows updater feed.
+**Update**: replace a standalone `kiki` executable with the newer file from the matching Release asset, or run `npm install -g kiki-agent@latest` / `npm install -g kiki-agent-lite@latest` for an npm install. On Windows the desktop app can also check for and install signed NSIS updates from **Settings → About**; see [Kiki desktop](./desktop-app.md#update). Linux and macOS desktop bundles have no in-app updater, so download the newer bundle yourself.
+
+**Uninstall**: delete a standalone `kiki` executable from your `PATH`, or run `npm uninstall -g kiki-agent` / `npm uninstall -g kiki-agent-lite`. That removes the CLI only — remove the desktop app through the system: **Installed apps** in Windows Settings, your package manager for a Linux deb, or dragging Kiki.app out of Applications on macOS. To stop working on the source, delete your checkout.
 
-**Uninstall**: remove a standalone `kiki` executable from your `PATH`, or run `npm uninstall -g kiki-agent` / `npm uninstall -g kiki-agent-lite`. npm uninstall does not remove an app copied to Applications or a Windows installer it ran; uninstall those through the OS. Source development is removed by deleting the checkout. For the desktop bundles, use **Installed apps** in Windows Settings, your package manager for a Linux deb, or delete Kiki.app from Applications on macOS. Removing the executable does not delete your data — session history and configuration live under `~/.kiki/` and stay available to the next installation; see [Data locations](../configuration/data-locations.md) if you want to remove it as well.
+None of these steps touch your data. Session history and configuration live under `~/.kiki/` and are still there after you reinstall; [Data locations](../configuration/data-locations.md) explains how to remove them deliberately.
 
 ## Next steps
 

package/dist/docs/en/getting-started/use-cases.md

@@ -1,12 +1,12 @@
 # Common use cases
 
-This page collects typical Kiki scenarios along with ready-to-use prompt examples — copy them as-is or adapt them to your needs.
+Each section below is a situation you will actually hit, with prompts you can send as they are. Adapt the wording to your project.
 
 ## Understanding an unfamiliar project
 
-When taking over an unfamiliar repository, a good first step is to enter Plan mode (the mode where the agent outputs an action plan and waits for your confirmation before touching anything), so the agent outputs a research plan before modifying files. Start the CLI with the `--plan` flag, press `Shift-Tab`, or type `/plan` in a session — all three do the same:
+Plan mode (the agent writes out what it intends to do and waits for your go-ahead before touching files) is worth turning on before you ask for changes in code you have not read yet. Start the CLI with `--plan`, press `Shift-Tab`, or type `/plan` in a session:
 
-```
+```text
 Give me an overview of this repository's architecture. Specifically:
 1. Where is the entry point and what happens at startup?
 2. How do the main modules depend on each other?
@@ -16,21 +16,21 @@ Finally, draw a simple module dependency diagram.
 
 You can also focus on a specific question:
 
-```
+```text
 How does the event loop in src/runtime work? Where do events originate, and what consumes them?
 ```
 
-```
+```text
 How is "permission approval" implemented in this project? Which files are involved, and what are the key types?
 ```
 
-For large-scale investigations, you can have the main agent (the agent you talk to directly) dispatch **sub-agents** (lower-level agents spawned by the main agent that handle sub-tasks in parallel). See [Agents and sub-agents](../customization/agents.md).
+For a large investigation, ask the main agent (the one you are talking to) to split the work across sub-agents, which work in parallel on pieces of it. [Agents and sub-agents](../customization/agents.md) covers how to prompt for that.
 
 ## Implementing a new feature
 
-Describe the requirement and acceptance criteria clearly. For complex changes, use Plan mode to confirm the approach before execution:
+State the requirement and what "done" looks like. For a change that touches several files, confirm the approach in Plan mode before it runs:
 
-```
+```text
 Add a retry utility under src/utils:
 - Signature: retry<T>(fn: () => Promise<T>, options): Promise<T>
 - Options: maxAttempts, initialDelayMs, backoffFactor
@@ -40,15 +40,15 @@ Add a retry utility under src/utils:
 
 If the result isn't right, just describe what you want changed — no need to edit manually:
 
-```
+```text
 The backoff calculation used a fixed value. I'd like to add some jitter to avoid the thundering-herd effect. Update the implementation and the tests.
 ```
 
 ## Fixing a bug
 
-Give the symptom, reproduction steps, and expected behavior all at once to avoid back-and-forth clarification:
+Give the symptom, how to reproduce it, and what you expected — all in one message, so the agent does not have to ask you back:
 
-```
+```text
 Running npm test occasionally produces this error:
 
   TypeError: Cannot read properties of undefined (reading 'id')
@@ -57,89 +57,89 @@ Running npm test occasionally produces this error:
 It only appears in test cases that concurrently trigger multiple updates. Please locate the cause and fix it, then run the full test suite to confirm.
 ```
 
-When the root cause is unclear, ask the agent to investigate before making changes:
+When you do not know the cause yet, ask for investigation before any edits:
 
-```
+```text
 User feedback: after a successful login, the first page refresh sends you back to the login page; a second refresh works fine. Please find the most likely causes first and list the most suspicious locations. I'll confirm the direction before you start making changes.
 ```
 
-For purely mechanical tasks, you can let the agent run freely:
+When the fix is mechanical, you can hand it over as-is:
 
-```
+```text
 Run the test suite, fix every failing test case, then run it again to confirm everything is green.
 ```
 
 ## Writing tests and refactoring
 
-Tasks with clear boundaries and explicit acceptance criteria are particularly well-suited for the agent:
+Work with a clear boundary and a checkable result is the easiest kind to hand over:
 
-```
+```text
 src/parser/markdown.ts currently has almost no tests. Please add a unit test suite covering: normal paragraphs, nested lists, code blocks, tables, blockquotes, and mixed content. Follow the testing style already used in the project.
 ```
 
-```
+```text
 Extract the repeated "read body → validate → log → respond" pattern in src/handlers into a middleware. Run the tests afterwards to make sure existing behavior is unchanged.
 ```
 
-For multi-file refactors, use Plan mode first to confirm the approach. You can also `/fork` the session into an experimental branch and switch to it from `/sessions` — forking itself never disrupts the original session, so you can simply switch back if you don't like the result.
+For a refactor that spans several files, confirm the approach in Plan mode first. Another option is to `/fork` the session, try the refactor in the copy, and switch between them from `/sessions` — the original session keeps running either way.
 
 ## One-off scripts and automation
 
-Batch file edits, statistics collection, and research comparisons can all be done with a single prompt:
+Batch file edits, statistics, and research comparisons each fit in a single prompt:
 
-```
+```text
 Change all var declarations in .js files under src to const or let, preferring const where possible. Run lint once you're done to confirm.
 ```
 
-```
+```text
 Analyze the access logs in logs/ from the past 7 days. For each API path, compute the call count, p50, and p99 response times, and output the results as a Markdown table.
 ```
 
-```
+```text
 Research the main dependency injection options for TypeScript (tsyringe, inversify, awilix). Compare them across three dimensions: API style, decorator requirements, and runtime overhead. Give me a recommendation that fits on one page.
 ```
 
-For batch tasks you know are safe, skip the per-call approval prompts: start the CLI with `--yolo` (the whole session runs in YOLO mode, including approval-free access to sensitive files unless explicitly denied; Plan mode exit review still applies), or type `/yolo` in a session to toggle it — both turn on the same YOLO mode. Alternatively, add pre-approved allowlist rules for specific tools in [Configuration files](../configuration/config-files.md#permission).
+For a batch of work you already trust, you can stop approving each call. Start the CLI with `--yolo` or type `/yolo` in a session — both switch the session to YOLO mode, where tool calls including reads of sensitive files run without asking, unless a permission rule denies them. Exiting Plan mode is still reviewed. For a narrower option, pre-approve specific tools in the `[permission]` section of [Configuration files](../configuration/config-files.md#permission).
 
 ## Scheduled tasks and reminders
 
-Inside an interactive session, you can ask the agent to set one-time reminders or recurring tasks. The agent generates a cron expression (a standard format for describing "when to run") in your local timezone and re-injects the prompt into the same session when it fires:
+In an interactive session, ask the agent for a one-time reminder or a recurring task. It writes a cron expression (the standard way to express "when to run") in your local timezone and re-sends the prompt into the same session each time it fires:
 
-```
+```text
 Remind me at 2:30 PM to check the deployment.
 ```
 
-```
+```text
 Every weekday at 9 AM, summarize recent CI failures for me.
 ```
 
-```
+```text
 Check the production health endpoint every hour and let me know if anything looks wrong.
 ```
 
-```
+```text
 Come back in about 10 minutes and check whether the build has finished.
 ```
 
-Scheduled tasks are bound to their session — closing the terminal is fine, and they are reloaded and continue firing when you resume the same session with `kiki --session`. They are not carried into brand-new sessions. Recurring tasks expire after 7 days — on the final trigger the agent receives a "stale" signal and decides whether to stop or renew based on your original instructions.
+A schedule belongs to the session that created it. Closing the terminal is fine — resume that same session with `kiki --session` and the schedule reloads and keeps firing. A brand-new session starts with no schedules. Recurring schedules stop after 7 days; on the last run the agent is told the schedule has expired and renews it only if your original instructions asked for that.
 
-To see what tasks are currently pending, just ask the agent (it calls `Cron` with the read-only `list` action). To cancel a task, tell the agent to remove it or reference its 8-character ID. For the full tool reference, see [Scheduled tasks](../reference/tools.md#scheduled-tasks). The global kill switch is `KIKI_DISABLE_CRON=1`.
+To see what is pending, just ask — the agent reads the schedule list. To cancel one, tell the agent to remove it or give its 8-character ID. [Scheduled tasks](../reference/tools.md#scheduled-tasks) documents the tool, and `KIKI_DISABLE_CRON=1` turns scheduled tasks off entirely.
 
 ## Generating and maintaining documentation
 
-```
+```text
 I just changed the interface signature in src/auth/login.ts. Please update the corresponding JSDoc, the example code in README, and any paragraphs in docs/en/guides that mention this interface.
 ```
 
-```
+```text
 For every public function under src/api that is missing a docstring, add a documentation comment following the style of the existing ones.
 ```
 
-```
+```text
 Based on the command implementations in src/cli, generate a draft command reference listing each subcommand, its arguments, and default values. Put it in docs/en/reference for me to review later.
 ```
 
-When you need a record or a retrospective, use `kiki export <sessionId>` to package the session as a ZIP, or use `/export-md` inside the TUI to export a readable Markdown transcript.
+To keep a record or do a retrospective, `kiki export <sessionId>` packages a session as a ZIP; `/export-md` inside the TUI writes a readable Markdown transcript.
 
 ## Next steps
 

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

@@ -1,6 +1,6 @@
 # Goals
 
-Goals keep Kiki working toward a defined outcome across turns (a turn is one full pass of the agent handling one message). Unlike a normal prompt that says what to do next, a goal says what must become true. Use `/goal` to enter goal mode when the task has a clear finish line, but the next useful step depends on what the agent learns while it works — for example, fixing a batch of failing tests or tracking down the root cause of a broken build.
+A goal keeps Kiki working toward an outcome across turns (one turn is a full pass of the agent handling one message). A prompt says what to do next; a goal says what must become true. Use `/goal` when there is a finish line but the next useful step depends on what the agent finds along the way — a batch of failing tests, or the root cause of a broken build.
 
 ## Start a goal
 
@@ -24,7 +24,7 @@ Avoid goals that only name a broad direction:
 /goal Find all bugs in this codebase.
 ```
 
-That goal does not say what counts as success, what to inspect, or when to stop. The agent may block immediately, or keep working far longer than you expected.
+That goal says nothing about what success looks like, what to inspect, or when to stop, so the agent may block immediately or work far longer than you expected.
 
 ### When to use goals
 
@@ -78,9 +78,9 @@ A goal can stop in three ways:
 - **paused**: you paused it, interrupted the turn, resumed a session that had an active goal, or hit a model, provider, or runtime error
 - **blocked**: Kiki needs input, cannot complete the goal as stated, or reached a budget limit. When the agent blocks a goal, it writes a short message explaining why.
 
-Write stop conditions into the objective. `/goal` does not have a separate stop-limit flag.
+Put your stop conditions in the objective itself — there is no separate stop-limit flag.
 
-A blocked goal does not freeze work it already started. When a task launched for a blocked goal finishes, its result wakes the main agent to process that one completion; the goal itself stays blocked and does not resume on its own. Pausing or cancelling the goal, and an exhausted budget, still apply as before and hold the result for your next message.
+A blocked goal does not cancel work it already started. When a task launched for it finishes, the result wakes the main agent to process that one completion; the goal itself stays blocked until you resume it. The same result is held for your next message if you pause or cancel the goal, or if the budget runs out.
 
 ## Manage goals in the web UI
 
@@ -90,13 +90,13 @@ Use the strip actions to pause an active goal, resume a paused or blocked goal,
 
 ## Queue upcoming goals
 
-Agents sometimes complete a goal quickly while the next piece of work is already on your mind — previously you had to wait for the goal to finish, return to the TUI, and submit the next one manually. Use `/goal next` to queue upcoming goals without interrupting the current one:
+When a goal finishes quickly and you already know what comes next, queue it instead of waiting:
 
 ```sh
 /goal next Update the release notes after the tests pass
 ```
 
-Upcoming goals are not visible to the agent while the current goal is running. When the current goal completes, Kiki starts the first upcoming goal in the same way as users enter `/goal <objective>`.
+The agent does not see queued goals while the current one runs. Once the current goal completes, Kiki starts the first queued goal exactly as if you had typed `/goal <objective>`.
 
 If no goal is active, `/goal next <objective>` starts that objective immediately. It behaves like `/goal <objective>` and shows a status message before the goal starts.
 
@@ -114,7 +114,9 @@ If the current goal is paused, canceled, or blocked, Kiki does not start the nex
 
 Goal mode is useful for work that can be checked with files, tests, command output, generated artifacts, or a clear written report. It is less useful for a one-off edit or a question that only needs one answer.
 
-The permission mode decides whether tool calls need your approval. In `manual` mode, goal work may pause for tool call approval. For unattended work (no one present to approve or answer questions), use a permission mode that matches the risk of the repository and the commands the agent may run.
+Goal mode suits work you can check — files, tests, command output, generated artifacts, a written report. It is overkill for a one-off edit or a question with one answer.
+
+Your permission mode decides whether tool calls wait for you. In `manual` mode, goal work pauses for approval on tool calls; for unattended work, pick a mode that matches the risk of the repository and the commands the agent will run.
 
 In non-interactive prompt mode (`kiki -p`, which runs one prompt and exits), only goal creation is supported:
 

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

@@ -1,49 +1,47 @@
 # Interaction and input
 
-The Kiki CLI and TUI run as an interactive terminal user interface built around three components: the input box, the conversation view, and the status bar. This page covers how to enter text, paste media, navigate the approval flow, and switch between modes.
+The CLI and TUI are a terminal interface built from the input box, the conversation view, and the status bar. This page covers typing and pasting, the approval flow, and the modes you can switch between.
 
 ## Input box basics
 
-The input box accepts free-form text. Press `Enter` to send, or `Shift-Enter` / `Ctrl-J` to insert a newline. When the input box is empty, press `↑` / `↓` to browse the input history for the current working directory, including previous shell commands.
+The input box accepts free-form text. `Enter` sends; `Shift-Enter` / `Ctrl-J` insert a newline. When it is empty, `↑` / `↓` browse what you have typed before in this working directory, shell commands included.
 
-**Exiting the CLI**: press `Ctrl-D` with the input box empty, press `Ctrl-C` twice while idle, or type `/exit`. All three require the agent to be idle — pressing `Ctrl-C` or `Esc` during streaming output only interrupts the current turn, it does not exit the program.
+**Leaving the CLI**: `Ctrl-D` with an empty input box, `Ctrl-C` twice while idle, or `/exit`. All three need the agent to be idle — during streaming output, `Ctrl-C` and `Esc` only interrupt the current turn.
 
 ## Pasting images and video
 
-Kiki supports pasting images and video directly into the input box, so you can discuss screenshots, UI mockups, architecture diagrams, or code demos without uploading or converting files first.
-
-**Video input is a distinctive Kiki capability** — you can paste a video clip and have the model analyze its content, UI flow, or code walkthrough.
+You can paste images and video straight into the input box, so a screenshot, UI mockup, architecture diagram or code demo can go into the conversation without uploading or converting anything first.
 
 How to paste:
 
 - **macOS / Linux**: `Ctrl-V`
 - **Windows**: `Alt-V`
 
-After pasting, the input box shows a placeholder that you can edit like normal text; on submit, the placeholder is replaced with the actual content. A plain-text clipboard falls back to ordinary paste. Media support depends on whether the current model accepts image / video input (the model capability fields `image_in` / `video_in`); it is enabled by default when you are logged in to a Kimi Code account.
+The pasted media shows up as an editable placeholder; on send, the real content replaces it. A plain-text clipboard just pastes as text. Whether media works at all depends on the current model accepting image / video input (the `image_in` / `video_in` capability fields); it is enabled by default on a Kimi Code account.
 
 ## Slash commands
 
 Anything starting with `/` is treated as a slash command. Typing `/` opens a completion menu that filters in real time as you keep typing; press `Esc` to close the menu. If nothing matches, the input is sent to the agent as a regular message.
 
-Active [Agent Skills](../customization/skills.md) (skill packages that extend what the agent can do) are automatically registered as slash commands: ordinary external Skills are invoked with `/skill:<name>`, external sub-skills appear as dotted commands such as `/parent.child`, and built-in Skills appear directly as `/<name>` in the slash command panel. If an external skill name does not conflict with a system slash command, you can also drop the `skill:` prefix and type `/<name>` directly.
+Active [Agent Skills](../customization/skills.md) (skill packages that extend what the agent can do) are registered as slash commands. Ordinary external skills are invoked with `/skill:<name>`, external sub-skills appear as dotted commands such as `/parent.child`, and built-in skills appear directly as `/<name>`. When an external skill name does not clash with a system command, you can drop the `skill:` prefix and type `/<name>`.
 
-Inside a longer prompt, typing `/` after whitespace — including at the start of a later line — opens a skill-only completion menu. You can reference several Skills in one prompt this way: Kiki activates them together and runs them with the prompt as a single turn (one `/undo`, which reverts the previous turn's output, undoes the whole submission), and the prompt text is sent unchanged. A Skill mention in a prompt never carries arguments — activation is by name only; arguments remain a standalone `/skill:<name> args` concept. Built-in and plugin commands still only work at the very start of the input.
+Inside a longer prompt, typing `/` after whitespace — including at the start of a later line — opens a skill-only completion menu. Reference several skills in one prompt that way: Kiki activates them together and runs them as a single turn, and one `/undo` reverts the whole submission. A skill mentioned inside a prompt is activated by name only and cannot carry arguments; arguments still need a standalone `/skill:<name> args`. Built-in and plugin commands only work at the very start of the input.
 
-Some commands are only available when the agent is idle — you need to press `Esc` to interrupt streaming output or context compression before using them. Mode-toggle and query commands like `/yolo`, `/plan`, `/help`, and `/btw` are always available. For the full list, see [Slash commands reference](../reference/slash-commands.md).
+Some commands need the agent to be idle — press `Esc` to interrupt streaming output or context compression first. Mode toggles and queries like `/yolo`, `/plan`, `/help` and `/btw` are always available. [Slash commands reference](../reference/slash-commands.md) has the full list.
 
 ## File references
 
-Type `@` to trigger file-path completion. Selecting a path inserts its relative form into your message; the agent loads the file content directly when it reads the message. File references work in both git and non-git directories, and folder suggestions end with `/` so you can keep completing paths inside them. While Kiki's fast file-search component is still downloading in the background, Kiki falls back to a basic filesystem scan. Hidden paths are available, but `.git` is excluded from suggestions.
+Type `@` to get file-path completion. Picking a path inserts its relative form into your message, and the agent reads the file when it picks up that message. It works in git and non-git directories alike, and folder suggestions end with `/` so you can keep completing paths inside them. While Kiki's fast file-search component is still downloading in the background, completion falls back to a plain filesystem scan. Hidden paths are suggested; `.git` is not.
 
 > `@` references and slash commands are two separate mechanisms: `@` gives the agent file context, while `/` invokes built-in features or Skills. After whitespace, `/` offers Skill completions only; use a leading `/` for built-in and plugin commands.
 
 ## Approval flow
 
-When the agent calls a tool with side effects — running commands, modifying files outside the workspace trust boundary — the TUI displays an approval panel for your confirmation. In a trusted working directory, `Write` / `Edit` inside that directory run without per-file approval; shell commands, workspace-external writes, workspace links to external targets, and sensitive-file access prompt in manual mode. Approvals are not triggered for regular tool calls in YOLO mode, nor for writes to plan files in Plan mode.
+When a tool call has side effects — running a command, writing outside the workspace trust boundary — the TUI shows an approval panel. In a trusted working directory, `Write` / `Edit` inside it run without a per-file prompt; in manual mode, shell commands, writes outside the workspace, links to external targets and sensitive files all ask first. YOLO mode does not prompt for ordinary tool calls, and neither does Plan mode for writes to plan files.
 
-Use the arrow keys to select an option and press `Enter` to confirm, or press `1` / `2` / `3` to select by number directly. `Esc`, `Ctrl-C`, and `Ctrl-D` are all equivalent to rejecting.
+Use the arrow keys and `Enter`, or press `1` / `2` / `3` to pick by number. `Esc`, `Ctrl-C`, and `Ctrl-D` all mean reject.
 
-The panel typically includes an **Approve for this session** option; selecting it auto-approves the same kind of call for the rest of the session. For permanent rules, add allow / deny entries in [Configuration files](../configuration/config-files.md#permission).
+The panel usually offers **Approve for this session**, which approves that kind of call for the rest of the session. For rules that outlive a session, add allow / deny entries in [Configuration files](../configuration/config-files.md#permission).
 
 ## Mode switching
 
@@ -54,17 +52,19 @@ In Plan mode the agent first outputs an action plan and waits for your approval
 - Toggle: `Shift-Tab` or `/plan`
 - Clear the current plan: `/plan clear` (only while idle)
 
-After producing a plan the agent pauses for your review — you can approve it, reject it, or ask for revisions. Exiting Plan mode requires your confirmation even if YOLO mode is also active. Auto and Approve for me are the exceptions: plan exits are approved automatically and marked as "Auto-approved" in the transcript.
+After writing the plan the agent pauses for you: approve it, reject it, or ask for changes. Leaving Plan mode asks for confirmation even when YOLO mode is on — except in Auto and Approve for me, where the exit is approved for you and marked "Auto-approved" in the transcript.
 
 ### Permission modes
 
-Select among Manual, Auto, Approve for me, and YOLO with `/permission`. **YOLO mode** (`/yolo`) auto-approves agent file access, including sensitive targets such as `.env` or SSH keys; an explicit deny rule still wins. Git-control paths may still prompt. Exiting Plan mode still requires review, and the agent can still ask you questions.
+`/permission` switches between Manual, Auto, Approve for me, and YOLO.
+
+**YOLO mode** (`/yolo`) approves agent file access without asking, including sensitive targets such as `.env` or SSH keys. An explicit deny rule still wins, and Git-control paths may still prompt. Leaving Plan mode still asks, and the agent can still put questions to you.
 
-**Auto mode** (`/auto`) approves ordinary tool actions and plan exits without prompting. It asks you before accessing sensitive files or workspace links to external targets, and the agent can still ask you questions. Explicit deny rules still block matching calls; dangerous Bash commands also request approval unless that guard is disabled.
+**Auto mode** (`/auto`) approves ordinary tool actions and plan exits without prompting, and asks before sensitive files and workspace links to external targets. Explicit deny rules still block matching calls, and dangerous Bash commands still request approval unless that guard is turned off.
 
-**Approve for me** (`review`) behaves like Auto but routes policy-generated approval requests to a [configured reviewer](../configuration/config-files.md#reviewer-approval) first. An explicit `ask` rule always goes to you instead. A confident reviewer approval or denial is recorded with reviewer attribution. Uncertain or unavailable review goes to your ordinary approval panel; after three consecutive reviewer denials in a turn, later requests in that turn come directly to you. Agent questions remain separate from reviewer decisions; [the interaction setting](../configuration/config-files.md#interaction) controls whether questions block the turn.
+**Approve for me** (`review`) works like Auto but sends policy-generated approval requests to a [configured reviewer](../configuration/config-files.md#reviewer-approval) first. An explicit `ask` rule always comes to you instead. A confident reviewer decision is recorded with the reviewer's attribution; an uncertain or unavailable one falls back to your approval panel, and after three reviewer denials in a turn the rest of that turn's requests come straight to you. Agent questions are separate from reviewer decisions, and [the interaction setting](../configuration/config-files.md#interaction) decides whether a question blocks the turn.
 
-If no approval client is attached (for example, during an unattended scheduled run), a request needing your approval is cancelled instead of granting access. Questions without an attached client are dismissed rather than waiting indefinitely.
+With no approval client attached — an unattended scheduled run, for instance — a request that would need you is cancelled rather than granted, and a question is dismissed rather than left hanging.
 
 ::: warning
 YOLO mode skips confirmation for file writes and command execution. Only use it in working directories you trust.
@@ -72,13 +72,13 @@ YOLO mode skips confirmation for file writes and command execution. Only use it
 
 ### Shell mode
 
-Shell mode lets you run terminal commands without leaving the conversation. The command output is written into the conversation context, so the agent can see the results in later turns.
+Shell mode runs terminal commands without leaving the conversation. Their output goes into the conversation context, so the agent can see the results in later turns.
 
-- Enter: type `!` in an empty input box, or paste a command that starts with `!`.
-- Exit: press `Backspace` or `Esc` in an empty input box; submitting a command also returns you to normal mode automatically.
-- Recall previous commands: with the input box empty in shell mode, press `↑` to browse earlier shell commands; recalling one keeps you in shell mode so it runs as a command again.
+- Enter: type `!` in an empty input box, or paste a command starting with `!`.
+- Exit: press `Backspace` or `Esc` in an empty input box. Submitting a command also returns you to normal mode.
+- Recall previous commands: with the input box empty in shell mode, press `↑`; recalling one keeps you in shell mode so it runs again as a command.
 
-In shell mode the input box shows a `!` prompt on the left (in the desktop GUI the border also turns violet). For example, you can run `!git status` to check the repository state without opening a new terminal — the output goes straight into the conversation context.
+The input box shows a `!` prompt on the left in shell mode (in the desktop GUI the border turns violet too). `!git status` checks the repository without opening another terminal, and its output lands in the conversation.
 
 ## During streaming output
 
@@ -90,9 +90,9 @@ The input box remains usable while the agent is thinking or calling tools, and s
 
 ## External editor
 
-Press `Ctrl-G` to send the current input content to an external editor. When you save and close, the text is written back into the input box; if you close without saving, the original content is preserved. This is handy when you need to enter large blocks of text or content with complex formatting.
+`Ctrl-G` sends the current input to an external editor. Save and close to write the text back into the input box; close without saving and the original stays. This is the easy way to enter long or heavily formatted text.
 
-Editor priority: `/editor` config → `$VISUAL` environment variable → `$EDITOR` environment variable. If none are set, run `/editor` first to choose a default.
+Kiki picks the editor in this order: the `/editor` config, then `$VISUAL`, then `$EDITOR`. With none of them set, run `/editor` to choose one.
 
 ## Next steps
 

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

@@ -1,42 +1,46 @@
 # Interface overview
 
-The Kiki desktop app and the browser GUI (the same interface used in a browser) share the same interface. A session is built around three areas: the conversation view, the input box, and the right rail. This page orients you in the interface; see [Workspace and session management](/en/guides/sessions) for boards, drafts, and recovery, and [Interaction and input](/en/guides/interaction) for the TUI counterpart.
+The desktop app and the browser UI are the same interface, and a session in either is built from three areas: the conversation view, the input box, and the right rail. This page is a tour of those three. For sessions, boards and drafts see [Workspace and session management](/en/guides/sessions); for the terminal version of the same concepts see [Interaction and input](/en/guides/interaction).
 
 ## Conversation view
 
-The conversation view shows the session timeline: assistant messages, tool calls, approvals, questions, and background-task notices. 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, while failed or cancelled entries always remain individually visible. Consecutive identical marker dividers, such as goal updates, show only the latest entry with a repeat count (for example, "Goal updated ×12") when no message or tool call separates them. File references can be previewed, opened, or shown in their containing folder. Reopening a session or loading an agent's saved history shows model changes as dividers naming the previous and new model; changing only thinking effort does not add a divider.
+This is the session timeline: assistant messages, tool calls, approvals, questions, and background-task notices.
 
-Long tool output and other large fields load in stages. Choose **Continue loading** to pull in the rest of a field that was cut short, with the row reporting how much is loaded. When that loading fails on a field that has an original to fetch — a tool's input or output, or a background task's own output, for example — the same place offers **Download original**, which saves the field's complete original content to your machine and reports its own saving, saved, and retry states. Retrying stays available, and not every field can be downloaded.
+Anything that has been resolved — a question you answered, an approval you granted, a marker — collapses into a compact one-line entry that stays where it happened. Several in a row fold into an **Activity history** row you can expand. Failed and cancelled entries always stay visible on their own. Repeating markers such as goal updates show the latest one with a count ("Goal updated ×12") when nothing else separates them.
+
+File references can be previewed, opened, or revealed in their folder. Reopening a session, or loading an agent's saved history, shows each model change as a divider naming the old and new model; a thinking-effort change on its own does not add one.
+
+Long tool output and other large fields arrive in stages. **Continue loading** pulls in the rest of a truncated field, and the row tells you how much is loaded so far. If that fails on a field that has an original behind it — a tool's input or output, a background task's own output — the same row offers **Download original**, which writes the complete content to your machine and reports its own saving, saved, and retry states. Retrying stays available, and not every field can be downloaded.
 
 ## Input box
 
-The input box accepts free-form text. `Enter` sends; `Shift-Enter` / `Ctrl-J` insert a newline. When it is empty, `↑` / `↓` browse the input history for the current working directory. Images and videos can be pasted from the clipboard, subject to the current model's multimodal capabilities — see [Interaction and input](/en/guides/interaction) for the full behavior, which the GUI input box shares.
+The input box accepts free-form text. `Enter` sends; `Shift-Enter` / `Ctrl-J` insert a newline. When it is empty, `↑` / `↓` browse what you have typed before in this working directory. You can paste images and video from the clipboard, as long as the current model accepts them — [Interaction and input](/en/guides/interaction) covers the details.
 
-Use the input box's **+** menu to add SSH hosts to the session. A host joined to a session is a resource of that session, not something each message carries, so the **Session SSH** control above the input box stays in place for as long as the host is joined: it lists the joined hosts, takes a host away on **X**, and opens the same host list from its own row to add or remove more. Adding a host makes it available to the session; it does not connect to it. In a new session (`/new`) the control reads **SSH to join**, and the selected hosts are joined to the created session before its first message is sent.
+The **+** menu in the input box adds SSH hosts to the session. A joined host belongs to the session rather than to each message, so **Session SSH** stays above the input box for as long as one is joined: it lists them, removes one on **X**, and reopens the host list from its own row. Adding a host makes it available to the session; it does not connect to it. In a brand-new session the control reads **SSH to join**, and the hosts you pick are joined before the first message goes out.
 
-While the agent is busy, new messages join a queue above the input box by default instead of interrupting. Each queued message has its own send timing: **when idle** (as soon as the agent finishes its turn), **after subagents** (once the running subagents finish), or **after tasks** (once all background tasks finish). Change a message's timing, edit, reorder, or send it now from its row in the queue.
+While the agent is busy, a new message joins the queue above the input box instead of interrupting. Each queued message carries its own timing — **when idle**, **after subagents**, or **after tasks** — and you can change it, edit the text, reorder, or send it right away from its row in the queue.
 
-While the agent is busy, hover over the send button, or focus it and press `↓`, to open the send-timing menu. Alongside the default send action, you can choose to send the message into the current turn for reading at the next safe step boundary (the same behavior as `Ctrl-Enter`), start it after subagents finish, or start it after all background tasks finish. If the main agent is waiting for a foreground `AgentRun`, Send now releases that wait into background without stopping the child; the child still reports completion automatically. Ordinary queueing does not release the wait. The choice applies only to this message and does not change the default timing. The menu does not appear while the agent is idle.
+To pick that timing, hover the send button or focus it and press `↓`. Besides the default, you can send the message into the current turn so the agent reads it at its next safe step (the same as `Ctrl-Enter`), start it after the running subagents finish, or start it after all background tasks finish. When the main agent is blocked waiting on a foreground `AgentRun`, **Send now** moves that wait to the background without stopping the child, which still reports back when it completes; plain queueing does not. The timing you choose applies to that one message. The menu only appears while the agent is busy.
 
-Stopping the main agent before it has replied or called a tool restores the interrupted prompt and its attachments to the session draft, alongside any unsent edits. Already answered or steered prompts are not restored. Attachment recovery requires the complete prompt content to be available in the loaded transcript; recovered attachments stay in memory for the current app run.
+Stop the main agent before it has replied or called a tool and the interrupted prompt goes back into the session draft with its attachments, next to any edits you had not sent. A prompt the agent already answered or was steered by is not restored, and recovered attachments need the full prompt in the loaded transcript and stay in memory until you restart the app.
 
-After a restart, restored queued messages wait for confirmation. Choose **Send now** on one message to send just that message, or **Resume queue** to release the queue. **Later** only collapses the explanation: the resume button stays visible while messages are held, and newly submitted messages may continue to queue until you resume.
+After a restart, queued messages come back held until you decide. **Send now** on one message sends only that one; **Resume queue** releases the rest. **Later** just hides the explanation — the resume button remains, and anything you submit meanwhile keeps queuing until you resume.
 
-In a subagent's input box, the stop button is disabled while its stop request is pending. If the request fails, an error notice explains why and the button becomes available to retry. Stopping one run does not clear unrelated messages waiting in that subagent's queue.
+In a subagent's input box the stop button is disabled while the stop request is in flight. If it fails, the notice says why and the button comes back so you can retry. Stopping one run leaves the subagent's other queued messages alone.
 
 ## Approvals
 
-Approvals appear in the timeline before a protected operation runs, with options to approve once or for the session. In the default Auto mode, routine tool calls run without asking; sensitive-file and external-link access still request approval. Manual mode asks before shell commands and workspace-external writes, while trusted-workspace `Write` / `Edit` calls run without per-file approval. YOLO mode skips sensitive-file prompts unless explicitly denied. Tool calls interrupted by `Esc` stop before execution.
+An approval appears in the timeline before a protected operation runs, with the option to allow it once or for the session. Auto mode (the default) runs routine tool calls without asking and still asks for sensitive files and external links. Manual mode asks before shell commands and writes outside the workspace, while `Write` / `Edit` inside a trusted directory run without a per-file prompt. YOLO mode skips the sensitive-file prompt unless a deny rule covers it. Pressing `Esc` stops a tool call before it executes.
 
 ## Right rail
 
-The right panel describes one agent at a time: whichever you last clicked into or focused. The main agent and every subagent get the same page, and the same rail follows you into a subagent's transcript. It shows the agent's head over what it is doing now, the items waiting on you as rows you can decide from, the activity feed, and a folded capabilities block. From **Dispatch capabilities** (the panel showing how the agent dispatches subagents) you can inspect a subagent's profile (configuration file), route, and executor, plus where the default model and thinking effort (how much reasoning the model invests) come from; see [Agents and subagents](../customization/agents.md#rebuilding-a-session-context).
+The rail describes one agent at a time — whichever you last clicked into or focused. The main agent and every subagent get the same page, and the rail follows you into a subagent's transcript. It shows what that agent is doing now, the items waiting on you as rows you can decide from, the activity feed, and a folded capabilities block. **Dispatch capabilities** opens the panel showing how the agent hands work to subagents, and from there you can inspect a subagent's profile (its configuration file), route and executor, plus where its default model and thinking effort (how much reasoning the model invests) come from — see [Agents and subagents](../customization/agents.md#rebuilding-a-session-context).
 
-On desktop-width screens the panel is open by default, and **Standard / Cockpit** in its header temporarily widens it over the preview space while the conversation and composer stay in the main column. **Standard** or **Exit cockpit** restores the previous preview content, tabs, draft, and width.
+On desktop-width screens the rail is open by default. **Standard / Cockpit** in its header widens it over the preview space while the conversation and composer stay in the main column; **Standard** or **Exit cockpit** puts the previous preview content, tabs, draft and width back.
 
 ## Sessions and workspaces
 
-The session list groups sessions by workspace; pick one to resume or start a new draft. Saved model, profile (the agent's configuration file), and effort choices that are no longer available stay visible with a diagnostic so you can select a valid value — the GUI does not silently substitute another model. Details are covered in [Workspace and session management](/en/guides/sessions).
+The session list groups sessions by workspace; pick one to resume, or start a new draft there. If a saved model, profile (the agent's configuration file) or effort is no longer available, the entry stays visible with a diagnostic instead of quietly switching you to a different model. [Workspace and session management](/en/guides/sessions) covers the rest.
 
 ## Next steps