kiki-agent-lite 0.3.1 → 0.3.2

package/README.md

@@ -2,9 +2,9 @@
 
 > A local agent workspace for Kiki
 
-[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE) [![Docs](https://img.shields.io/badge/docs-online-blue)](https://x-t-e-r.github.io/kiki/) [Releases](https://github.com/X-T-E-R/kiki/releases)
+[![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/X-T-E-R/kiki/blob/kiki/LICENSE) [![Docs](https://img.shields.io/badge/docs-online-blue)](https://x-t-e-r.github.io/kiki/) [Releases](https://github.com/X-T-E-R/kiki/releases)
 
-## What is Kiki CLI
+## About
 
 Kiki is a local agent workspace with a desktop GUI, a CLI/TUI, and a browser UI available through `kiki web`. It can read and edit code, run shell commands, search files, fetch web pages, and choose the next step from the feedback it receives. It works out of the box with Moonshot AI's Kimi models and can also be configured to use other compatible providers.
 
@@ -14,19 +14,22 @@ Kiki began as a fork of Kimi Code (Moonshot AI) and is now developed independent
 
 Download the appropriate build from [GitHub Releases](https://github.com/X-T-E-R/kiki/releases).
 
-> On Windows, install [Git for Windows](https://gitforwindows.org/) before first launch because Kiki CLI uses the bundled Git Bash as its shell environment. If Git Bash is installed in a custom location, set `KIKI_SHELL_PATH` to the absolute path of `bash.exe`.
+> **Windows:** install [Git for Windows](https://gitforwindows.org/) before first launch — Kiki CLI uses the bundled Git Bash as its shell environment. If Git Bash is in a custom location, set `KIKI_SHELL_PATH` to the absolute path of `bash.exe`.
 
-Then run it with a new terminal session:
+Then open a new terminal session and confirm the install:
 
 ```sh
 kiki --version
 ```
 
-### A note on npm
+### Installing from npm
 
-With Node.js 24.15.0 or later, the CLI is also published on npm as `kiki-agent` (CLI/TUI plus a checksum-verified desktop download) and `kiki-agent-lite` (CLI/TUI only). Install one, not both — they supply the same `kiki` command. GitHub Releases remain the way to fetch a standalone executable.
+With Node.js 24.15.0 or later you can also install from npm. Pick **one** of these — they both provide the same `kiki` command, and installing both leaves you with a conflict:
 
-For checksums, update channels, and uninstall steps, see the [installation guide](https://x-t-e-r.github.io/kiki/en/getting-started/installation).
+- `kiki-agent` — CLI/TUI plus a checksum-verified desktop download
+- `kiki-agent-lite` — CLI/TUI only
+
+GitHub Releases remain the way to get a standalone executable. For checksums, update channels, and uninstall steps, see the [installation guide](https://x-t-e-r.github.io/kiki/en/getting-started/installation).
 
 ## Quick Start
 
@@ -43,7 +46,7 @@ On first launch, run `/login` inside Kiki CLI and choose either Kimi Code OAuth
 Take a look at this project and explain the main directories.
 ```
 
-To use the browser UI, run:
+To use the browser UI instead, run:
 
 ```sh
 kiki web
@@ -70,8 +73,8 @@ kiki web
 
 - Source: https://github.com/X-T-E-R/kiki
 - Issues: https://github.com/X-T-E-R/kiki/issues
-- Security: see [SECURITY.md](../../SECURITY.md) in the main repository
+- Security: report privately per https://github.com/X-T-E-R/kiki/blob/kiki/SECURITY.md
 
 ## License
 
-MIT
+[MIT](https://github.com/X-T-E-R/kiki/blob/kiki/LICENSE)

package/dist/docs/en/configuration/config-files.md

@@ -1,20 +1,24 @@
 # Configuration files
 
-Kiki writes all long-term preferences — which model to use, which API key to fill in, how many steps an Agent can run per turn — into TOML (a plain-text configuration format with a clear structure) files. Saved preferences persist across starts; `config.toml` and provider credentials also reload while Kiki is running. Ordinary agent and runtime settings live in `config.toml`; provider credentials live in a separate `credentials.toml`; terminal-UI and client preferences (theme, editor, notifications, auto-update) live in a companion `tui.toml`.
+Kiki keeps its long-term preferences in TOML (plain text with a clear structure) files. Settings live in three places, and the split is worth knowing before you edit anything:
 
-Default location: `~/.kiki/config.toml`, created automatically on first run. Provider credentials live in `~/.kiki/credentials/credentials.toml`; see [Provider credentials](#provider-credentials).
+| File | Holds |
+| --- | --- |
+| `~/.kiki/config.toml` | Agent and runtime settings, plus your model and provider definitions |
+| `~/.kiki/credentials/credentials.toml` | API keys, OAuth tokens and MCP credentials |
+| `~/.kiki/tui.toml` | Terminal-side preferences: theme, editor, notifications, auto-update |
+
+`config.toml` is created on first run. Saved preferences persist across starts, and both `config.toml` and the credential file are watched while Kiki runs.
 
 ## Config file location
 
-The CLI reads configuration from `~/.kiki/config.toml`. To relocate the data directory, override it with the `KIKI_HOME` environment variable:
+To move the whole data directory, set the `KIKI_HOME` environment variable:
 
 ```sh
 export KIKI_HOME=/path/to/kiki-home
 ```
 
-The config file path then becomes `$KIKI_HOME/config.toml`. Regardless of where the directory lives, the file name is always `config.toml`.
-
-Provider credentials live at `$KIKI_HOME/credentials/credentials.toml` when you override the data directory. The `credentials/` directory also holds OAuth and MCP credentials.
+The config file then lives at `$KIKI_HOME/config.toml` — the name is always `config.toml`, wherever the directory is — and credentials at `$KIKI_HOME/credentials/credentials.toml`.
 
 ::: tip
 TOML field names always use snake_case, for example `default_model` and `max_context_size`. If a key contains `.`, you must quote it — for example `[models."gpt-4.1"]` — otherwise TOML treats `.` as a nested table separator.
@@ -105,6 +109,26 @@ command = "node ~/.kiki/hooks/check-bash.mjs"
 timeout = 5
 ```
 
+## External harness defaults
+
+An external harness (the program running the agent) can use its own configuration without a Kiki profile. For the main-agent `execution` selection, set reusable Kiki overrides under `[agent_executor_overrides.<id>.defaults]`; a session override wins over an explicitly declared profile value, which wins over these settings. Anything left unset stays with the harness's own default. Native execution keeps Kiki's existing model and profile defaults.
+
+```toml
+[agent_executor_overrides."claude-acp".defaults]
+# Optional: use the harness's model ID, not a native Kiki model alias.
+model_alias = "YOUR_HARNESS_MODEL"
+thinking_effort = "high"
+permission_mode = "auto"
+kiki_context = []
+allow_kiki_subagents = false
+```
+
+Omit model, effort and permission fields to let the harness choose them. `kiki_context` accepts `memory`, `board`, `cron`, `threads`, `history` and `hooks`; `[]` explicitly disables all groups, and `allow_kiki_subagents = false` explicitly disables delegation. An omitted profile field inherits the harness settings in this execution path. Changing settings does not rewrite an existing binding: select the execution again or explicitly rebuild its context to adopt them.
+
+`defaults.executor_prompt` accepts `delivery` (`append`, `replace` or `preamble`), `body`, `append`, `include`, and `per_engine.<id>` overrides. These fields merge individually with the selected profile, so setting only `delivery` does not erase the default body. Omitted `include` inherits; `include = []` turns off the additional sections. A profile body is used when no effective `executor_prompt.body` is set. External execution does not automatically add Kiki cognition or shared prompt fields; request the desired fields explicitly in `include`.
+
+Through [the REST API](../server/rest-api.md#sessions), update these settings with `POST /api/config` and an `agent_executor_overrides` object. A defaults field set to JSON `null` removes that saved setting; `defaults: null` removes the whole defaults block. TOML has no `null`, so remove the corresponding key when editing the file. Launch settings such as `bin_path`, `home_dir`, `env` and `args` remain separate from defaults.
+
 ## Continuity reminder cues
 
 Kiki can remind the agent to record standing instructions, find earlier decisions, update unfinished todos, and preserve working notes before or after context compaction. Reminders are appended to conversation history; they do not automatically save memories or change the system prompt. Progress reminders require `TodoList`; instruction and history reminders can also operate with approved memory access when `TodoList` is unavailable.
@@ -127,7 +151,7 @@ The field-level priority between `api_key` and the `[providers.<name>.env]` fall
 
 ### Migrating existing keys
 
-If an older root-level `credentials.toml` exists, startup moves its contents unchanged to `credentials/credentials.toml`; reads also support the old location until the move succeeds. If both locations contain different bytes, Kiki stops rather than choosing one: inspect both files before retrying. If an older `config.toml` still holds provider credentials, startup moves them into `credentials/credentials.toml` and rewrites `config.toml` without them. The previous `config.toml` is kept as a unique backup named `config.toml.bak-<YYYY-MM-DD>-<uuid>` so you can review or restore it. The backup still contains the original plaintext keys; remove it after checking the migration if you no longer need it. Repeated loads after a successful migration do not create another backup or change already-moved credentials. If the same key path exists in both files with different values, migration stops for manual review rather than choosing one; a failed or interrupted migration may leave a backup for inspection.
+An older root-level `credentials.toml` is moved unchanged into `credentials/credentials.toml` at startup, and the old location stays readable until that succeeds; if the two hold different bytes, Kiki stops rather than choosing — check both and retry. Credentials still sitting in an older `config.toml` are moved into `credentials/credentials.toml`, and the old `config.toml` is kept as a unique `config.toml.bak-<YYYY-MM-DD>-<uuid>`. That backup still holds the original plaintext keys, so delete it once you have checked the migration and no longer need it. Loading again after a successful migration creates no second backup and changes nothing already moved; the same key path holding different values in the two files stops the migration for you to resolve, and an interrupted one may leave a backup to inspect.
 
 ### File permissions
 
@@ -159,6 +183,7 @@ Fields in the config file fall into two categories: **top-level scalars** that d
 | `retry` | `table` | — | Error-specific step retry policies → [`retry`](#retry) |
 | `request_governance` | `table` | No rules | Native model-request concurrency and waiting budgets → [`request_governance`](#request-governance) |
 | `token_counting` | `table` | — | Which context token count is reported externally → [`token_counting`](#token-counting) |
+| `transcript_memory` | `table` | — | Server-side transcript history memory budgets → [`transcript_memory`](#transcript-memory) |
 | `background` | `table` | — | Background task runtime parameters → [`background`](#background) |
 | `subagent` | `table` | — | Subagent run defaults and limits → [`subagent`](#subagent) |
 | `agents` | `table` | — | Delegation-notice defaults → [`agents`](#agents) |
@@ -176,7 +201,7 @@ Fields in the config file fall into two categories: **top-level scalars** that d
 | `identity` | `table` | — | Custom agent identity → [`identity`](#identity) |
 | `prompt` | `table` | `{}` | Prompt field overrides and custom variables → [`prompt`](#prompt) |
 
-The following sections cover each of the nested tables in turn: `providers`, `models`, `thinking`, `loop_control`, `retry`, `token_counting`, `background`, `subagent`, `agents`, `thread_communication`, `mcp`, `tools`, `image`, `session_title`, `experimental`, `nb_search`, `permission`, `interaction`, and `prompt`.
+The following sections cover each of the nested tables in turn: `providers`, `models`, `thinking`, `loop_control`, `retry`, `token_counting`, `transcript_memory`, `background`, `subagent`, `agents`, `thread_communication`, `mcp`, `tools`, `image`, `session_title`, `experimental`, `nb_search`, `permission`, `interaction`, and `prompt`.
 
 ## `providers`
 
@@ -241,11 +266,15 @@ model = "gpt-4.1"
 max_context_size = 1048576
 ```
 
-### Explicit legacy model parameter migration
+### Legacy model parameter migration
+
+Older configurations put `temperature` / `top_p` and `max_completion_tokens` / `service_tier` in different places. **Settings → Models & providers → Available models → Legacy model parameter migration** can copy them into a model's `parameters` table.
 
-In **Settings → Models & providers → Available models → Legacy model parameter migration**, select **Preview migration** to inspect proposed copies without writing a file. The preview lists only model aliases, parameter names, review reasons, a revision, and backup identifiers; it does not return config text, credential values, or backup contents. No model-parameter migration runs automatically at startup. Where unambiguous, the operation copies older `request_params.temperature`/`top_p` and `max_completion_tokens`/`service_tier` into a model's `parameters` table. Ambiguous values and conflicts remain for manual review; existing older fields are **not removed**, so inspect the preview rather than assuming their behavior has changed.
+**Preview migration** first, which lists the model aliases, parameter names, review reasons, a revision and the backup name it would use, and writes nothing. Unambiguous values are copied; ambiguous or conflicting ones are left for you to decide. Your existing fields are not removed, so read the preview instead of assuming anything changed.
 
-Choose **Apply previewed changes**, then confirm to write. The server first stores a byte-exact backup next to `config.toml` under a unique `config.toml.generation-backup-<uuid>` name, then conditionally writes the proposed config. A changed config or stale preview is rejected, not overwritten. Backups may contain the original secrets: protect them like `config.toml` and `credentials.toml`. The server config store requests owner-only file permissions where supported; do not assume identical permission guarantees on every platform. The backup identifier is listed in the same panel; **Restore backup** asks for separate confirmation and restores only if the current config still exactly matches that backup's migrated output and the preview revision remains current. Edits that leave different bytes block restoration, but the current byte-only revision cannot detect a sequence that returns the config to exactly the same bytes; an older backup may then undo a newer identical migration. Do not restore an older backup after subsequent changes. Backup and config are separate files, not one crash-atomic multi-file transaction. A config CAS that definitely rejects a stale revision deletes its new backup only if the backup still matches; if the write outcome is uncertain, the backup and observed config remain for inspection instead of automatically rolling back another writer. On Windows, the underlying atomic writer first tries to replace by rename, but under `EPERM` contention it can fall back to unlinking the destination before renaming: readers may briefly see a missing config, and a crash in that window can leave it missing. Inspect both files and the backup before retrying after any uncertain failure.
+**Apply previewed changes** then writes a byte-exact backup next to `config.toml` as `config.toml.generation-backup-<uuid>` before touching the config, and refuses to write if the config changed since the preview. That backup contains your original secrets — protect it like `config.toml` and `credentials.toml`, and delete it once you no longer need it.
+
+**Restore backup** asks for its own confirmation, and only restores while the current config is still exactly what that backup produced. Any other edit blocks it. Restore soon after a migration: the revision is a byte comparison, so a later edit that happens to return the config to identical bytes is not detected, and an old backup can undo newer work.
 
 ### Model alias resolution
 
@@ -293,7 +322,9 @@ max_context_size = 131072
 display_name = "Kimi for Coding (custom)"
 ```
 
-`[models."<alias>".overrides]` accepts ordinary model fields such as `max_context_size`, `max_input_size`, `max_output_size`, `capabilities`, `display_name`, `reasoning_key`, `adaptive_thinking`, `support_efforts`, `default_effort`, `off_effort`, `service_tier`, `request_params`, `context_budget`, `auto_compact`, and `max_completion_tokens`. It does not accept identity / routing fields: `provider`, `model`, `protocol`, `beta_api`, and `base_url`. For these added fields, resolve the model alias configuration, including its `overrides`, first; then apply model alias → top-level profile → matching `model_profiles` entry. Merge `request_params` by key and use the last explicit `service_tier`; `context_budget` and `max_completion_tokens` are limits, so take the smallest declared value across layers within the model's capacity and output cap. Omitting a limit adds no restriction.
+`[models."<alias>".overrides]` accepts ordinary model fields such as `max_context_size`, `max_input_size`, `max_output_size`, `capabilities`, `display_name`, `reasoning_key`, `adaptive_thinking`, `support_efforts`, `default_effort`, `off_effort`, `service_tier`, `request_params`, `context_budget`, `auto_compact`, and `max_completion_tokens`. It does not accept identity or routing fields: `provider`, `model`, `protocol`, `beta_api` and `base_url`.
+
+Layering works in this order: resolve the alias configuration including its `overrides`, then apply model alias → top-level profile → matching `model_profiles` entry. `request_params` merge by key and the last explicit `service_tier` wins. `context_budget` and `max_completion_tokens` are limits, so the smallest value across layers applies, within the model's capacity and output cap; omitting one adds no restriction.
 
 You can also switch models temporarily without touching the config file — by setting `KIKI_MODEL_*` environment variables, the CLI synthesizes a temporary provider in memory that does not persist after restart. See [Define a model from environment variables](./env-vars.md#define-a-model-from-environment-variables-kiki-model).
 
@@ -341,13 +372,13 @@ steering = "cognition/flash-steering.md"
 
 `~/.kiki/cognition/flash-anchor.md`:
 
-```
+```text
 You are a helpful software engineer assistant.
 ```
 
 `~/.kiki/cognition/flash-steering.md`:
 
-```
+```text
 Router: classify this task (build or fix) now, then adopt the matching style — build: direct production; fix: inspect-first. Let's first understand the problem and devise a plan; then let's carry out the plan and act.
 ```
 
@@ -405,7 +436,7 @@ the bound model's `overrides.default_effort` → its `default_effort` → global
 | `compaction_soft_context_size` | `integer` | `0` | Legacy absolute token ceiling, used only when no `auto_compact` is set at any layer |
 | `compaction_max_attempts` | `integer` | `3` | Maximum total requests for a failing compaction, including the initial attempt; all recovery paths share this budget |
 
-A session's per-model token override takes priority over a matching `model_profiles` entry, profile top level, model alias, then this global percentage. Without any new `auto_compact`, Kiki preserves the previous threshold: `min(0.85 × usable context, usable context − 50000, positive compaction_soft_context_size)`, with an explicit legacy ratio in place of 0.85. Saving a new global value converts the current model's token point to a percentage and removes the old ratio and soft-ceiling keys; a legacy absolute ceiling cannot retain the same value across differently sized models after that conversion. Changing the threshold takes effect before the next model step, not immediately. Run `/autocompact` to inspect the current session value.
+The compaction point resolves in this order: the session's per-model token override, a matching `model_profiles` entry, the profile's top-level value, the model alias, then this global percentage. With no `auto_compact` set anywhere, the previous threshold applies: `min(0.85 × usable context, usable context − 50000, positive compaction_soft_context_size)`, using your explicit legacy ratio in place of 0.85. Saving a new global value converts the current model's token point to a percentage and drops the old ratio and soft-ceiling keys — after which a legacy absolute ceiling no longer means the same thing on models of different sizes. The change applies before the next model step, and `/autocompact` shows the current session value.
 
 `max_steps_per_turn` can be overridden by the `KIKI_LOOP_MAX_STEPS_PER_TURN` environment variable, and `max_attempts_per_step` by `KIKI_LOOP_MAX_ATTEMPTS_PER_STEP`; both take higher priority than the config file.
 
@@ -422,7 +453,7 @@ cooldown_human_turns = 8
 long_task_steps = 24
 ```
 
-Regular progress reminders require new successful work, at least six human turns since the relevant content changed, and eight since that domain's previous reminder (or session start). After its first reminder, spacing doubles to 16 human turns; each unchanged domain receives at most two progress reminders. Todo reminders need unfinished items. Notes reminders additionally require uncovered work of at least 8,000 tokens or 10% of the compaction threshold, whichever is larger. Long-task notes checkpoints can occur without another human turn: they require 24 successful work steps since both the last notes change and last notes reminder, plus at least 16,000 uncovered tokens or 10% of the threshold, whichever is larger. Polling alone does not count as successful work.
+A regular progress reminder needs new successful work, at least six human turns since that content last changed, and eight since that domain's previous reminder or the session start. After the first one, spacing doubles to 16 human turns, and each unchanged domain gets at most two. Todo reminders require unfinished items; notes reminders also require at least 8,000 uncovered tokens or 10% of the compaction threshold, whichever is larger. A long-task notes checkpoint needs no new human turn — 24 successful work steps since both the last notes change and the last notes reminder, plus 16,000 uncovered tokens or 10% of the threshold. Polling alone is not successful work.
 
 Todos and notes keep separate ages, work watermarks, reminder clocks, and two-reminder budgets. An actual content change resets only that domain's age, work watermark, and reminder budget, returning its spacing to the base cooldown. Changing the list does not reset notes state, and changing notes does not reset the list's. Rewriting identical content resets neither.
 
@@ -435,7 +466,7 @@ memory_maintenance = false
 
 `memory_maintenance` is a boolean, defaulting to `true` when omitted. A valid configuration reload takes effect at the next reminder evaluation; it does not remove reminders already in the conversation. It controls only periodic maintenance prompts during active work (M3), at most once per context window. Setting it to `false` keeps reminders for new human standing instructions (M1) and the pre-compaction check for an identified, still-unhandled instruction (M2). It does not disable memory tools, change approval policy, or turn off TodoList notes.
 
-Memory reminders are available to the main agent in non-ephemeral sessions when memory is enabled, memory approval is not `off`, and `MemoryWrite` is registered and permitted by tool policy. Periodic reminders stay silent while idle or only polling. They ask the agent to retain instructions, stable decisions, or evidenced knowledge useful to future tasks: if nothing worth keeping has changed, it should not write. Task progress stays in working notes; pending memory proposals are not active guidance and should not be duplicated.
+Memory reminders reach the main agent in non-ephemeral sessions when memory is on, approval is not `off`, and `MemoryWrite` is registered and permitted. They stay silent while idle or merely polling, and they ask the agent to keep instructions, stable decisions or evidenced knowledge that will matter later — with nothing worth keeping changed, it should not write. Task progress belongs in working notes, and a pending memory proposal is not active guidance.
 
 Instruction and history reminders use configurable Chinese/English cues followed by a local structural gate, not a separate model call:
 
@@ -445,7 +476,7 @@ instructions = ["always", "never", "以后", "不要"]
 history = ["as I said", "earlier", "之前", "我说过"]
 ```
 
-Each supplied list replaces its defaults; an empty list disables that category. English cues match case-insensitively at word boundaries; Chinese cues use substring matching. Matching a cue alone is insufficient: quoted examples and product discussions do not establish standing rules, and a steer correction must pass the same gate. A delivered instruction/history reminder is deduplicated for that accepted input or steer revision, rather than limited to one per entire turn. Already covered references are skipped; repeated references to the same identified topic have a three-human-turn cooldown while todo and notes state is unchanged. New rule modifications and revocations bypass that history cooldown and the progress cooldown.
+Each list replaces its defaults, and an empty list disables that category. English cues match case-insensitively at word boundaries, Chinese cues by substring. A cue alone is not enough — a quoted example or a passing mention does not establish a rule, and a steer correction has to pass the same gate. A delivered reminder is deduplicated per accepted input or steer revision rather than once per turn, already-covered references are skipped, and repeated references to the same topic cool down for three human turns while todo and notes state is unchanged. Changing or revoking a rule skips both that cooldown and the progress one.
 
 Configuration decisions belong in task notes unless their broader scope is explicit; cross-session memory still requires its existing approval policy. Context-window preservation and handoff-rebuild reminders follow compaction state, not the progress cadence.
 
@@ -485,6 +516,18 @@ match = '^provider\.'
 retry = false
 ```
 
+## `transcript_memory`
+
+`transcript_memory` controls how much transcript history the server keeps in memory. All three fields are optional: an omitted field uses its default.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `tail_turns` | positive integer | `20` | How many finished turns stay resident per agent |
+| `max_agent_bytes` | positive integer | `16777216` (16 MiB) | Per-agent resident byte budget — what stays in memory. Older turns are read from disk on demand |
+| `max_detail_cache_bytes` | non-negative safe integer | `268435456` (256 MiB) | Largest single full-detail read cached at once. `0` turns that extra slot off, leaving the content to be read without being held in that cache. A changed value takes effect at the next cache admission or eviction; lowering it evicts what no longer fits, and does not cancel a read already in progress |
+
+These are server-side memory budgets, not read limits. Lowering them reduces memory use and may mean reading the same content from disk again.
+
 ## `token_counting`
 
 `token_counting` selects which context token count is reported externally — the value behind the context-size display. Internal logic (automatic compaction triggers, budgets, and overflow backoff) always uses both provider-reported usage and estimates, regardless of this setting.
@@ -680,14 +723,14 @@ Each entry describes one connection through its `type` (`agent-browser-profile`
 
 `nb_search` configures Kiki's built-in search and retrieval module — the capability behind the `WebSearch` and `FetchURL` tools. The module is part of the product: it ships with Kiki and needs no separate installation, and its provider instances, credential slots, lanes, and default fetch chain are built in.
 
-No credentials or configuration are required for the default `WebSearch` lane, `github.repositories`, but it searches GitHub repositories only. For library documentation, choose `context7.docs` explicitly; it returns typed context and cannot be combined with result lanes. `duckduckgo.search` is an optional keyless general-web lane, but its public HTML endpoint may return a CAPTCHA; for reliable broader coverage, configure a provider credential and override `defaults.search_lane`. Field names and merge behavior follow the module's canonical configuration contract, shared with the standalone nb-search CLI, so an existing nb-search configuration file applies without translation.
+The default `WebSearch` lane is `duckduckgo.search`, which searches the general web without registration, credentials or configuration. Its public HTML endpoint may issue a challenge or rate limit; wait before retrying, or explicitly choose another configured source. These failures are errors, not empty results, and never trigger a silent switch to a paid provider. Configured defaults and explicit lane selections take precedence. For repository search or library documentation, choose `github.repositories` or `context7.docs` explicitly; the latter returns typed context and cannot be combined with result lanes. Field names and merge behavior follow the module's canonical configuration contract, shared with the standalone nb-search CLI, so an existing nb-search configuration file applies without translation.
 
 | Field | Type | Required | Description |
 | --- | --- | --- | --- |
 | `provider_instances` | `table` | No | Named provider instances with `provider_id`, `enabled`, optional `credential_slot_id` / `base_url`, `key_strategy` (`round-robin` or `priority`), `balance_ttl_ms` (60,000–86,400,000), and provider-specific `options` |
 | `credential_slots` | `table` | No | Named credential slots containing only `provider_id` and the environment-variable name in `env` |
 | `lanes` | `table` | No | Named operation lanes with `provider_instance_id`, `operation_id`, `latency`, `cost`, and optional `evidence_groups` |
-| `defaults.search_lane` | `string` | No | Built-in default is `github.repositories` (repositories only); override for general-web search. Explicitly removing the default without selecting a lane makes `WebSearch` fail closed |
+| `defaults.search_lane` | `string` | No | Built-in default is keyless `duckduckgo.search` (general web); configured defaults take precedence. Explicitly removing the default without selecting a lane makes `WebSearch` fail closed |
 | `defaults.fetch_chain` | `array<table>` | No | URL default tries `direct.fetch` first and keyless `jina.reader` on failure; a successful but unusable direct response needs explicit `execution.fetch.quality` rules to trigger fallback |
 | `execution` | `table` | No | Provider-call, concurrency, retry, timeout, inline-output, response-size, redirect, content-size, and quality budgets |
 

package/dist/docs/en/configuration/data-locations.md

@@ -54,6 +54,8 @@ $KIKI_HOME  (default: ~/.kiki)
 │       └── <key>-<suffix>.json
 ├── sessions/               # Session data (see below)
 │   └── <workDirKey>/<sessionId>/
+├── server/
+│   └── events/             # Bounded client event replay journals
 ├── bin/
 │   ├── rg                  # managed ripgrep binary for Grep (rg.exe on Windows)
 │   └── fd                  # managed fd binary for file references (fd.exe on Windows)
@@ -68,7 +70,7 @@ $KIKI_HOME  (default: ~/.kiki)
 Each file under the data root serves a specific purpose; most are managed automatically by the CLI:
 
 - **`config.toml`**: the main runtime configuration file, storing user-level settings such as providers, models, and loop control. Provider API keys live in `credentials/credentials.toml`. See [Configuration files](./config-files.md).
-- **`credentials/credentials.toml`**: holds provider credentials such as each provider's `api_key`. On a shared TOML path a value here overrides `config.toml`, and credentials left in an older `config.toml` are migrated here on first load, with the previous file kept as `config.toml.bak-<date>`. An older root-level `credentials.toml` is moved here without changing its contents; a mismatch between the two files stops migration for inspection. Kiki requests owner-only permissions (`0o600`) where supported. See [Provider credentials](./config-files.md#provider-credentials).
+- **`credentials/credentials.toml`**: holds provider credentials such as each provider's `api_key`. On a shared TOML path a value here overrides `config.toml`, and credentials left in an older `config.toml` are migrated here on first load, with the previous file kept as `config.toml.bak-<date>` — that backup still contains your keys in plaintext, so delete it once you have checked the migration. Kiki requests owner-only permissions (`0o600`) where supported. See [Provider credentials](./config-files.md#provider-credentials).
 - **`tui.toml`**: terminal UI client preferences such as theme, editor, notifications, and status line.
 - **`AGENTS.md`**: user-level agent instructions. This file moves with `KIKI_HOME` and is combined with workspace-root instructions unless `.kiki/AGENTS.md` overrides it.
 - **`mcp.json`**: user-level MCP server declarations, merged with the project-local `.kiki/mcp.json` on startup. See [MCP](../server/mcp.md).
@@ -76,7 +78,7 @@ Each file under the data root serves a specific purpose; most are managed automa
 - **`cognition/`**: prompt files referenced by `[models."<alias>".cognition]`; paths are relative to the data root. See [Model cognition](./config-files.md#model-cognition).
 - **`hooks/`**: script files referenced by `[[hooks]]` command paths (for example `node ~/.kiki/hooks/check-bash.mjs`). See [Hooks](../customization/hooks.md).
 - **`plugins/installed.json`**: records installed plugins, each plugin's enabled state, and MCP server capability state changes made via `/plugins` or `/plugins mcp disable|enable`. Files installed from local paths or zip URLs are copied to `plugins/managed/<id>/`. See [Plugins](../customization/plugins.md).
-- **`credentials/`**: restricted credential directory, with requested permissions `0o700` (directory) / `0o600` (files). OAuth logins for managed providers are stored as `credentials/<name>.json`; MCP server credentials are stored under `credentials/mcp/`. OAuth credentials are written using an atomic flow (tmp → fsync → rename) to prevent corruption.
+- **`credentials/`**: restricted credential directory, with requested permissions `0o700` (directory) / `0o600` (files). OAuth logins for managed providers are stored as `credentials/<name>.json`; MCP server credentials are stored under `credentials/mcp/`. On Windows, check the file and parent-directory ACLs yourself before relying on the file to stay private.
 - **`workspaces.json` and `workspaces/`**: the registered workspace catalog and the project directories Kiki creates when a new session has no selected workspace. Each automatically created session receives a distinct directory; these are working files, separate from the session history under `sessions/`.
 
 ## Session data
@@ -94,14 +96,20 @@ Inside each session directory:
 - **`tasks/`**: background task persistence — `tasks/<task_id>.json` stores status/pid/exit code; `tasks/<task_id>/output.log` stores output.
 - **`cron/`**: scheduled task persistence; reloaded into the scheduler when the session is resumed with `kiki --session`. See [Scheduled tasks](../reference/tools.md#scheduled-tasks).
 
+## Server event replay
+
+`server/events/<sessionId>.jsonl` stores durable events for reconnecting clients, not the complete conversation history. Kiki automatically retains the session's replay window (1000 events by default). Active writers compact after growing beyond two windows and retain one window when closing; this limits event count, not bytes, and keeps oversized events intact.
+
+Older journals shrink when the new writer first appends to them. Browsing a cold session only reads its watermark and does not rewrite the journal; journals for inactive or deleted sessions therefore remain until written again or explicitly cleared. Failed replacement leaves the durable source intact and logs a warning, with reclamation retried on later writes or writer close.
+
+This retention does not remove `sessions/`, agent `wire.jsonl` files, or saved media. Clients whose cursor is no longer covered recover through a snapshot/reset rather than replaying the old event sequence; see [Reconnect and recovery](../server/rest-api.md#reconnect-and-recovery). If you need to clear old journals manually, first stop every Kiki server using this data root, then clear only `server/events/` and restart. Never delete or truncate these journals while a writer is running.
+
 ## Built-in tool cache
 
 The first time the `Grep` tool needs ripgrep, the CLI can automatically download `rg` and cache it at `bin/rg` (`bin/rg.exe` on Windows). File-reference completion in the terminal UI uses `fd`; the CLI downloads and caches it at `bin/fd` (`bin/fd.exe` on Windows) in the background when needed. Subsequent runs reuse the cached binaries. `rg` prefers the system `PATH` before the cache, while `fd` checks the managed cache before falling back to system `fd` / `fdfind`. Deleting the `bin/` directory triggers a fresh download on the next use.
 
 ## Logs
 
-The log filename `kimi-code.log` is a historical name inherited from Kiki's upstream project and is kept as is.
-
 - **`logs/kimi-code.log`** (global): records startup, login, export, and other cross-session events.
 - **`<sessionDir>/logs/kimi-code.log`** (session-level): records diagnostic events within a single session.
 

package/dist/docs/en/configuration/env-vars.md

@@ -24,9 +24,9 @@ export KIKI_HOME="/path/to/custom/kiki"
 
 > Make sure the directory is writable. Multiple `kiki` instances sharing the same `KIKI_HOME` will share config and credential files.
 
-On macOS and Linux, the shared runtime keeps its local endpoint inside this directory, and the resulting path has a length limit that varies by platform. A home directory that is still too long is reported as a configuration problem that names the actual length, the platform's limit, and the fix — use a shorter `KIKI_HOME`. This is a diagnostic, not a silent move: Kiki does not relocate your data or pick a different directory for you, and a short symlink does not shorten the real path that the limit measures.
+On macOS and Linux, the shared runtime keeps its local endpoint inside this directory, and the resulting path has a length limit that varies by platform. If the path is still too long, Kiki reports a configuration problem naming the actual length, the platform's limit, and the fix: use a shorter `KIKI_HOME`. Kiki does not move your data for you, and a short symlink does not shorten the real path the limit measures.
 
-After upgrading on macOS or Linux, quit every process still using the same `KIKI_HOME` and start the new build. Old and new builds do not share a running runtime, and Kiki does not migrate the previous one for you. Windows is unaffected — the runtime uses a named pipe there and needs no such step.
+After upgrading on macOS or Linux, quit every process still using the same `KIKI_HOME` before starting the new build — the old and new builds do not share a running runtime. Windows is unaffected: the runtime uses a named pipe there.
 
 For the complete data directory structure, see [Data locations](./data-locations.md).
 
@@ -36,9 +36,7 @@ Switch models temporarily without modifying `config.toml` — when `KIKI_MODEL_N
 
 ## Provider credential key names
 
-The key names below are not read directly from the shell — they are key names written inside the `[providers.<name>.env]` sub-table, serving as fallback values for `api_key` / `base_url`. The CLI reads only from the config files, not from `process.env`.
-
-This design lets you keep familiar key name conventions while keeping secrets out of `config.toml`: the secret keys go to the companion `credentials.toml`, and the non-secret `*_BASE_URL` keys stay in `config.toml`.
+The key names below are not read from the shell. They are keys written inside the `[providers.<name>.env]` sub-table, used as fallback values for `api_key` / `base_url`. Secret keys go in the companion `credentials.toml`; the non-secret `*_BASE_URL` keys stay in `config.toml`.
 
 ```toml
 # ~/.kiki/credentials/credentials.toml
@@ -170,7 +168,7 @@ Switches that control the behavior of subsystems such as background tasks, the b
 
 Subagent concurrency has no environment-variable override. Configure [`[subagent]`](./config-files.md#subagent) with `max_direct_children` and `max_total_subagents`; their defaults are `16` and `0` (unlimited), respectively.
 
-`[subagent].default_model` explicitly supplies a model only when dispatch parameters and effective pins do not. It does not inherit the caller or bypass hard model rules. `[subagent].default_effort` remains removed: use an effort pin or the selected model's defaults (see [`subagent`](./config-files.md#subagent)). Forced environment values likewise cannot bypass profile hard lists.
+`[subagent].default_model` supplies a model only when dispatch parameters and effective pins do not. It never inherits the caller's model, and neither it nor a forced environment value can bypass a profile's hard model rules. `[subagent].default_effort` was removed and is no longer read — startup warns about it; set an effort pin on the profile, route, or caller lease, or let the selected model use its own default.
 
 ## Diagnostic logs
 

package/dist/docs/en/configuration/overrides.md

@@ -77,28 +77,27 @@ Mutual exclusion rules (startup fails if violated):
 
 ## Model and effort resolution
 
-For native executor agents, determine the model for this dispatch first, then resolve that model's thinking effort. Route and caller-lease pins supply soft defaults; deviations and explicit `preferred_*` / `discouraged_models` advice produce binding advisories only for hard-permitted executable bindings. `allowed_models`, `deny_models`, and `allowed_efforts` are hard at every profile, lease, tree, and matching model-profile scope. Machine deny rules and provider/executor capability checks also remain hard.
+Resolve the model first, then that model's thinking effort. Route and caller-lease pins are defaults you can override; `allowed_models`, `deny_models`, and `allowed_efforts` are hard limits at every profile, lease, tree, and matching `model_profiles` scope — for a subagent they reject binding, manual changes, and resume, while in a main session your own selection wins and going outside one only warns. A value the model itself does not support is still an error either way.
 
-Thinking effort resolves in this order, then must satisfy all hard effort lists:
+When a profile binds — a new main session, a new subagent, a model switch, or a native `AgentRun` dispatch — the requested effort is collected from the role's own sources and then resolved against the bound model:
 
-1. An explicit `effort` wins over defaults, not hard constraints. Pin or preference mismatches produce advisories; an out-of-list or unsupported effort is rejected.
-2. When `effort` is omitted, route or caller-lease defaults take precedence.
-3. A matching `model_profiles` entry.
-4. The profile's top-level `thinking_effort`, only when the selected model matches the profile's default `model_alias`.
-5. `[models."<alias>"].overrides.default_effort`.
-6. The selected model's `default_effort`, including `[models."<alias>"].default_effort`.
-7. The global `[thinking].effort`.
-8. If neither default effort is set, the model's supported-effort midpoint or capability fallback.
+1. An explicit `effort` on the call.
+2. For a main session, a persona's or route's locked effort. For a subagent, the route's locked effort, or the caller lease's when the route pins none. Then, in both cases, a matching `model_profiles` entry and the profile's top-level `thinking_effort`.
+3. The bound model's preferred effort.
+4. `[models."<alias>"].overrides.default_effort`.
+5. The model's own `default_effort`.
 
-When `[thinking].enabled` is `false`, an unpinned effort resolves to Off unless a model override is set. Models with `always_thinking` cannot be turned Off; their fallback follows the model-default-then-global order.
+If none of those produces a value, or the resulting effort is not one the model supports, the bind fails as a configuration error rather than silently picking something. With no model configured at all, the bind asks for both a model and an effort. You do not have to pass an effort when a route, lease, profile pin, or model default already supplies one; you need one only when nothing else does, in which case configure that pin or pass `effort` for this call.
 
-A profile without `model_alias` skips only the top-level effort layer; it does not fail closed, and resolution continues with the next default layer. On a plain resume, omitting model parameters keeps the current binding. An alias resolving to the same canonical model is a no-op. Changing only `effort` keeps the saved model. Changing to a different canonical model without `effort` re-resolves effort for the new model; on resume, that model change still requires `allow_model_change: true`. Existing parameter validation and the external executor's own validation remain in force.
+This applies to profile binding only. A plain resume that keeps an existing valid binding is not recomputed, so an effort saved earlier keeps working. Changing only `effort` keeps the saved model, and changing model on resume still requires `allow_model_change: true`.
+
+Paths that do not bind a profile are unchanged: the global `[thinking]` section still supplies its fallback, and `[thinking].enabled = false` still resolves an unpinned effort to Off there.
 
 ## Prompt field precedence
 
-Prompt text fields use a separate chain rather than the ordinary CLI/config priority. From low to high, the order is global `[prompt.overrides]`, model `[models."<alias>".prompt_overrides]`, agent or `SYSTEM.md` frontmatter `prompt_overrides`, and the matching `model_profiles[].prompt_overrides` — four precedence levels. Agent files and `SYSTEM.md` are two separate configuration surfaces sharing the same position in that chain, which brings the total to five supported surfaces.
+Prompt text fields use a separate chain. From low to high: global `[prompt.overrides]`, model `[models."<alias>".prompt_overrides]`, agent or `SYSTEM.md` frontmatter `prompt_overrides`, then the matching `model_profiles[].prompt_overrides`. Agent files and `SYSTEM.md` sit at the same level, so there are five surfaces across four levels.
 
-Every surface accepts `files` and `fields`. Files are loaded from the Kiki home directory in listed order, then inline fields win within that surface. A field missing at a higher level inherits the lower value; values are never concatenated. See [`prompt`](./config-files.md#prompt) for the external-file schema, available field examples, turn snapshots, and migration from the removed `prompt.shared` / `prompt.tools` keys.
+Every surface accepts `files` and `fields`. Files load from the Kiki home directory in listed order, then inline fields win within that surface. A field missing at a higher level inherits the lower value; values are never concatenated. See [`prompt`](./config-files.md#prompt) for the external-file schema, field examples, and how to move off the removed `prompt.shared` / `prompt.tools` keys.
 
 ## Common scenarios
 

package/dist/docs/en/configuration/providers.md

@@ -31,7 +31,7 @@ The manager displays providers as a list of entries grouped by source. Navigatio
 
 Two paths when adding:
 
-- **Known third-party provider**: fetches the model catalog from [models.dev](https://models.dev/), select a provider → enter an API key → select a default model. Vendors whose protocol the catalog does not declare (e.g. xai, openrouter, and other vendor-specific SDKs) are imported as OpenAI-compatible with a "guessed" note; when the catalog provides no usable endpoint, a base URL prompt appears first; proprietary protocols (Amazon Bedrock, Cohere) and unrecognized explicit protocols are refused. Deprecated and alpha-status models are excluded from the import list. If the public catalog is unreachable, the CLI falls back to a built-in snapshot of the catalog, so the import still works offline or in blocked networks
+- **Known third-party provider**: pick a provider from the [models.dev](https://models.dev/) catalog → enter an API key → pick a default model. Vendors the catalog does not describe with a protocol (xai, openrouter, and other vendor-specific SDKs) are imported as OpenAI-compatible and marked as guessed; if the catalog has no usable endpoint for them, you are asked for a base URL first. Proprietary protocols (Amazon Bedrock, Cohere) cannot be imported. Deprecated and alpha models are left out of the list. If the public catalog is unreachable, Kiki falls back to a built-in snapshot of it, so the import still works offline.
 - **Custom registry (api.json)**: paste a custom registry URL and Bearer token; this explicit import creates the `providers` / `models` entries. Later startup does not synchronize upstream additions, removals, or model metadata changes.
 
 ### Fetching model suggestions
@@ -42,7 +42,7 @@ Suggestions are kept in server memory and disappear when the server restarts. Ch
 
 In the GUI, open **Settings → Models & providers → Connections**. Under **Connect with an API key**, choose one of five protocol entries (`openai`, `openai_responses`, `anthropic`, `google-genai`, `vertexai`) or search for a service by name. A matching service, including DeepSeek, GLM, Kimi, Ollama, LM Studio, or OpenRouter, fills in its protocol and base URL. If there is no match, choose a protocol and enter the base URL yourself. Then enter the key if required and add a model.
 
-Ollama and LM Studio use the same API-key path as other OpenAI-compatible services; their local servers may not require a key. The five quick starts are OpenAI, Anthropic, Google Gemini, DeepSeek, and Moonshot (Kimi). The Kimi shortcut retains the existing `kimi` wire adapter described below, rather than adding a sixth protocol entry.
+Ollama and LM Studio use the same API-key path as other OpenAI-compatible services; their local servers may not require a key. The five quick starts are OpenAI, Anthropic, Google Gemini, DeepSeek, and Moonshot (Kimi) — the Kimi shortcut configures the `kimi` provider described below.
 
 **Available models** lists configured models across providers: search by name or ID, inspect context size and capabilities, and star a model to set the global default. The provider and model also retain their own per-provider default and remote ID. A manually entered Kimi API key uses the same suggestion-only flow as other API-key connections; account sign-in provisions its own models.
 
@@ -107,6 +107,8 @@ For connecting to the OpenAI Chat Completions protocol, as well as any third-par
 
 Third-party reasoning models (DeepSeek, Qwen, One API, etc.) work out of the box: the CLI automatically handles the `reasoning_content` field and `reasoning_effort` injection. If your gateway returns reasoning content under a non-standard field name, set `reasoning_key` on the model alias to override.
 
+For both `openai` and `openai_responses`, Kiki does not send an output-length limit of its own when you have not set one and the model's capability is unknown — the request carries no `max_tokens`, `max_completion_tokens` or `max_output_tokens`, and the server's own default applies. A limit you set yourself, a known model output capability, a tighter session or profile limit, and a remaining-window budget are all still honored; the context window size on its own is not treated as an output limit. That maximum is a ceiling, not a promise about answer length — what the model returns still depends on the task and on when it stops — and you are billed for the response you actually get.
+
 - Default `base_url`: `https://api.openai.com/v1`
 - Credential key names: `OPENAI_API_KEY`, `OPENAI_BASE_URL`
 
@@ -180,7 +182,7 @@ Shares the same implementation as `google-genai`; setting `type = "vertexai"` sw
 
 - Credential key name: `VERTEXAI_API_KEY` — written in the `[providers.vertexai.env]` sub-table, and stored in `credentials.toml` like every other provider API key; the API-key alternative to the ADC flow below
 
-Authentication follows the standard Google Cloud ADC flow (`gcloud auth application-default login` or a `GOOGLE_APPLICATION_CREDENTIALS` service account JSON) — this part is unrelated to Kimi Code. **The project ID and region must be written in the `[providers.vertexai.env]` sub-table** — simply `export GOOGLE_CLOUD_PROJECT` in the shell will not be read by the CLI.
+Authentication follows the standard Google Cloud ADC flow (`gcloud auth application-default login`, or a `GOOGLE_APPLICATION_CREDENTIALS` service account JSON file). **The project ID and region must be written in the `[providers.vertexai.env]` sub-table** — exporting `GOOGLE_CLOUD_PROJECT` in your shell has no effect.
 
 ```toml
 [providers.vertexai]
@@ -204,9 +206,9 @@ In the GUI **Connections** tab, **Sign in with an account** offers Kimi Code, Gi
 
 ## Request identity
 
-The sections above decide which endpoint Kiki connects to and with which key; **request identity** decides which client each request presents itself as. It writes the `User-Agent` and extra headers sent to the provider endpoint, so the server treats that traffic as Codex CLI, Claude Code, Grok Build, OpenCode, or Kiki's own client. It is a different setting from [`[identity]`](./config-files.md#identity), the runtime display name and slug.
+The sections above decide which endpoint Kiki connects to and with which key. **Request identity** decides which client each request claims to be: it writes the `User-Agent` and extra headers, so the provider treats the traffic as Codex CLI, Claude Code, Grok Build, OpenCode, or Kiki's own client. It is a different setting from [`[identity]`](./config-files.md#identity), the runtime display name and slug.
 
-Identity only supplies those client-identity fields: `base_url`, the API key, and the authentication method still come from your provider configuration and `credentials.toml`, and identity never carries or rewrites them. Credential and transport headers such as `Authorization`, `x-api-key`, `Cookie`, and `Content-Type` are not accepted as identity fields.
+Identity only supplies those client-identity fields. `base_url`, the API key, and the authentication method still come from your provider configuration and `credentials.toml`. Credential and transport headers such as `Authorization`, `x-api-key`, `Cookie`, and `Content-Type` are not accepted as identity fields.
 
 ### Built-in identities
 
@@ -242,7 +244,7 @@ GUI **Settings → Request identity** is the central page: the left column lists
 | Provider | Settings → Models & providers → provider editor → Request identity | `[providers.<name>.request_identity]` |
 | Model | Settings → Models & providers → model editor → Request identity | `[models."<alias>".request_identity]` |
 
-Later layers override earlier ones (global → provider → model). With no layer set, an ordinary API-key connection keeps the built-in Kimi Code identity, while a provider authenticated through the Codex or Grok Build OAuth flows keeps that provider's default identity. A layer you set explicitly — global, provider, or model — still overrides that default. Choosing a compatible preset resets the lower layers first and then applies that layer's optional sparse `overrides` (for example `lineage.format`, `client.user_agent`, `request.logical_id`). Sending one provider's traffic as OpenCode takes only:
+Later layers override earlier ones (global → provider → model). With no layer set, an ordinary API-key connection uses the built-in Kimi Code identity, and a provider authenticated through the Codex or Grok Build OAuth flows uses that provider's default identity. Choosing a compatible preset clears the lower layers first, then applies that layer's optional sparse `overrides` (for example `lineage.format`, `client.user_agent`, `request.logical_id`). Sending one provider's traffic as OpenCode takes only:
 
 ```toml
 [providers.my-gateway.request_identity]