kiki-agent-lite 0.3.1 → 0.3.2

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

@@ -4,22 +4,23 @@ title: Features
 
 # Features
 
-Kiki is an open-source AI agent workbench that runs on your machine. These pages walk through what it does, in the order you are most likely to need it: what the workbench is, how long work keeps going, what you do every day, who you can talk to, where your data lives, which layers you control, how other tools plug in, and how it looks and extends.
+Kiki is an open-source AI agent workbench that runs on your machine. These pages follow the order you are likely to need them: what the workbench is, how to describe an agent you can reuse, which model and control layer it runs under, how long work keeps going, who you can talk to, what your daily window looks like, where your data and machines are, how you extend it, how other tools plug in, and how it looks.
 
 The Kiki workbench: the subagents a lead session dispatched, an active goal, and a queued message, all on one screen\.
 
-If you are new to Kiki, start with [Installation](/en/getting-started/installation), then come back here. If you already run it, jump to the page that matches what you are trying to do — each one links back to the guide that has the full steps.
+New to Kiki? Start with [Installation](/en/getting-started/installation), then come back here. Already running it? Jump to the page that matches what you are trying to do — each one links back to the guide that has the full steps.
 
 | Page | What it covers |
 | --- | --- |
 | [One workbench, many lines](/en/features/workbench) | The lead session, its dispatched subagents, per-role models, and background tasks |
+| [Agent Profiles](/en/features/agents) | Profiles as reusable roles: model and effort, instructions, tools, and dispatch |
+| [Every layer is yours](/en/features/freedom) | Prompt overrides, connections and OAuth, permission modes, and hooks |
 | [Work that runs long](/en/features/long-work) | Goals, the message queue, scheduled tasks, the task board, the context window, and memory |
-| [The daily driver](/en/features/daily) | The timeline, annotations, the "needs you" tray, the right rail, and the usage page |
 | [Roles you can talk to](/en/features/people) | Personas, their daily conversation entry, their memory, and rooms |
+| [The daily driver](/en/features/daily) | The timeline, annotations, the "needs you" tray, the right rail, and the usage page: cost, concurrency rules, and external sync |
 | [Your data, your machines](/en/features/spaces) | Spaces, remote connections, thread bridges, Web access, and in-session SSH |
-| [Every layer is yours](/en/features/freedom) | Agent files, prompt overrides, connections and OAuth, permission modes, and hooks |
+| [Make it yours to extend](/en/features/extend) | Plugins, skills, MCP servers, and search and retrieval |
 | [Bring your history, meet other tools](/en/features/ecosystem) | Importing another tool's history, using Kiki in an editor, and Kiki as a service |
 | [Look and feel](/en/features/look) | Skins, backgrounds, appearance packs, and fine tuning |
-| [Make it yours to extend](/en/features/extend) | Plugins, skills, MCP servers, and search and retrieval |
 
 [Online version with images](https://x-t-e-r.github.io/kiki/en/features/)

package/dist/docs/en/features/long-work.md

@@ -22,14 +22,30 @@ The full behavior is described in [Interface overview](/en/guides/interface#inpu
 
 An active goal with two queued messages, each with its own send timing\.
 
+The queue expanded under a running goal, with each queued message's own send timing and its edit, send-now, and remove actions\.
+
 ## Work that outlives the session
 
 Two features carry work beyond a single conversation. Both are listed globally rather than per-session, but what they hold is scoped differently.
 
 **Scheduled tasks.** The agent can schedule a prompt to fire at a future time, either once or on a cron expression in your local timezone, and a global panel lists every schedule. A schedule is ticked by a Kiki that has its session open — the interactive daemon or server, or a print run for the sessions that run already has open. It does not scan the rest of the home or wake a closed session, so a schedule only fires while some Kiki is holding that session. Recurring tasks are shifted forward by deterministic jitter so everyone does not fire on the hour, and one that missed fire times fires once with the missed count. Schedules are bound to their session and do not carry into a brand-new session, and a session holds at most 50 active ones. See [Scheduled tasks](/en/reference/tools#scheduled-tasks).
 
+The scheduled tasks panel, with enabled one-shot and recurring entries above a paused one, and run-now, pause, resume, and delete per entry\.
+
+### Managing a schedule by hand
+
+The scheduled-tasks page is also where you change a schedule yourself. Every entry leads with when it runs, in words rather than a cron expression: "every hour on the hour", "every day at 09:00", "every Monday at 08:30". The expression is still there, one click away in the entry's detail panel, along with the prompt in full, the owning conversation, and the moment the server computed for the next run.
+
+**New scheduled task** creates one, and **Edit** changes one. The form asks whether the task runs once or on a schedule, then for the repeat: every N hours, a time each day, days of the week, or a day of the month. You pick the conversation it belongs to, searchable by title and grouped by workspace, because that is where its output arrives.
+
+A schedule more specific than those controls — several times a day, a day of the month pinned to a weekday — opens on the cron expression itself and is saved exactly as written. Editing such a task never quietly turns it into a simpler rule. A save the server refuses leaves everything you typed in the form, so a rejected change costs you nothing to retry.
+
+**Run now** sits on its own line at the bottom left of an entry, away from pause and delete: it runs the prompt once without touching the schedule. Rebinding an existing task to another conversation stays inside the task's own workspace.
+
 **The task board.** Each workspace has a board where requirements are cards, and each card links to the sessions working on it. Cards are persistent requirements, not agent runs — reading a card does not change it, and the board does not update from todo lists. The main agent reads and writes the board itself with `BoardRead` and `BoardWrite`, under the normal approval rules. Open it from the fixed button at the bottom of the main agent's right panel. See [Task board](/en/guides/sessions#task-board).
 
+The task board, with requirement cards in To do, In progress, Paused, and Done columns, each linked to the sessions working on it\.
+
 ## The context window: when it fills up
 
 As a conversation grows, Kiki compresses the history when the context approaches the window limit. You decide where that point is, and what happens when it is reached.
@@ -38,11 +54,11 @@ The context meter sits below the composer. Opening it gives you a detail card wi
 
 The card also holds the **renewal strategy** — a three-way choice for what happens at the compaction point:
 
-- **Summarize** (the default) — compress the history into a summary and keep going.
+- **Summarize** — compress the history into a summary and keep going.
 - **Fresh** — do not carry the history. Restart from the agent's working notes alone.
-- **Auto** — let the agent decide per run.
+- **Auto** (the built-in main-agent default) — restart when the working notes safely cover the work; otherwise summarize.
 
-The source label next to it says which layer the current value came from (session, profile, global, or inherited) and doubles as the control that saves it more broadly or resets it. Subagents and external executors read this value but do not set it.
+The source label next to it says which layer the current value came from (session, profile, global, or inherited) and doubles as the control that saves it more broadly or resets it. A session choice takes precedence over its profile, then the global setting, then the built-in default. Subagents have a separate default, and external executors manage their own context; both are read-only here.
 
 **Fresh has real conditions.** Restarting from notes throws away the conversation, so Kiki only does it when nothing would be lost — the history is available, the working notes exist and have been reviewed in the current window, and the restart will fit. When something arrived after the last handoff, or a result cannot be recovered from notes, Kiki compacts instead of clearing. Treat Fresh as "restart from notes when that is safe", not "clear the history at any moment".
 
@@ -50,11 +66,13 @@ For the manual side, `/compact` compresses on demand and accepts a hint about wh
 
 The context meter detail card, with the context window track and Fresh selected as the renewal strategy\.
 
+The context details card opened over a running session, with Fresh start selected and this session's cumulative token counts below it\.
+
 ## Memory keeps the facts across sessions
 
 A session ends. Memory is what does not. The agent saves user preferences, feedback, verified project facts, and reference pointers, and finds them again later. On the `/memory` page you choose which body of memory you are looking at — **Global**, one **Workspace**, or one **Persona**. Persona-specific entries are isolated from other personas; by default a persona can also read the shared global and workspace memory.
 
-Memory is on by default, and the `/memory` page in the sidebar is its permanent home either way — with memory off it is the turn-on guide, with memory on it is the management console. You can search entries, filter by type, edit, pin, and delete them, and every change can be undone one operation at a time — including a delete, which is why the confirmation says so rather than claiming anything is permanent. When memory approval is set to `review`, proposed changes wait in an Inbox tab for you to accept or discard instead of taking effect on their own.
+Memory is on by default, and the `/memory` page in the sidebar is its permanent home either way — with memory off it is the turn-on guide, with memory on it is the management console. You can search entries, filter by type, edit, pin, and delete them, and every change can be undone one operation at a time, including a delete. When memory approval is set to `review`, proposed changes wait in an Inbox tab for you to accept or discard instead of taking effect on their own.
 
 Agents write memory with `MemoryWrite` and read it with `MemorySearch` and `MemoryRead`. See [Memory](/en/guides/memory) for the full page, the review inbox, and how to turn memory off.
 
@@ -62,7 +80,7 @@ The memory page in the persona scope, listing entries across the global, workspa
 
 ## Next steps
 
-- [Memory](/en/guides/memory) — the three scopes, the review inbox, and undoable history
+- [Memory](/en/guides/memory) — choosing between scopes, the review inbox, and undoable history
 - [Using goals](/en/guides/goals) — writing and managing goals
 - [Task board](/en/guides/sessions#task-board) — persistent requirement cards per workspace
 - [The daily driver](/en/features/daily) — the window you use while all of this runs

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

@@ -19,7 +19,7 @@ Each skin ships a light and a dark variant; the light / dark switch above the pi
 | **Iris × Starveil** | Violet-white paper and iris ink; indigo-violet layers and silver-lilac controls at night. |
 | **High contrast × Obsidian** | Visible borders and AAA main text; layered charcoal, ice-cyan focus and near-white controls at night. |
 
-See [Built-in skins](/en/customization/skins#built-in-skins) for the full table and the retired palettes.
+See [Built-in skins](/en/customization/skins#built-in-skins) for the full table.
 
 The appearance settings, with the skin picker, the background, and the fine-tuning controls\.
 

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

@@ -28,6 +28,8 @@ confirmed facts from open questions.
 
 `model_alias` and `thinking_effort` are optional: they select a configured model and effort for this persona, and they do not grant permissions. A `tools` field is rejected, because tools belong to the profile.
 
+The **Personas** page is the form view of that file. One persona's settings in a single column: which profile it rides on, its model and effort, the working directory its conversations start in, whether it is pinned to the sidebar, and which memory bodies it can read.
+
 Two behaviors are worth knowing before you edit. Each session freezes its own persona snapshot, so changing the card does not silently alter a conversation already in flight — start a new session, or rebuild its context, to apply the edit. And the opening greeting is local presentation until you explicitly reply to it; simply opening the conversation does not put it into the model's history.
 
 The Personas page also imports and exports Character Card V3 in JSON, PNG, and CHARX, and the avatar picker takes PNG, JPEG, or WebP. **Remove avatar** restores the initials without deleting the persona or its memories; a duplicate creates a new identity without copying conversation state or private memory; archive hides a persona from ordinary selection without erasing it.
@@ -36,6 +38,8 @@ See [Personas, Bots, and rooms](/en/customization/personas) for the full card re
 
 The persona card: name, avatar, responsibility, and the standing rules it works by\.
 
+One persona's settings: the profile it rides on, its model and effort, the working directory, how it is delivered, whether it is pinned or hidden from the sidebar, and which memory it can read\.
+
 ## A fixed daily conversation
 
 Every persona has a stable address for its daily conversation — the same entry the sidebar row, the switcher, the header, and the persona page all point at. Clicking a persona's name lands you in that one conversation, so "ask Xiaolan" means the same thing every time. If it does not exist yet, the entry opens a fresh daily draft and adopts it once it exists.
@@ -56,20 +60,24 @@ The **/memory** page exposes the persona scope alongside global and workspace, i
 
 A room gives two to six members a shared conversation with a host, a budget, and pause and continue. Persona members get their own message-mode sessions inside the room; existing threads can join as themselves, keeping their own sessions, workspaces, and permissions. In the GUI, Ctrl/⌘-click threads in the sidebar and choose **Pull into a new room**, use **Add to room…** on a thread, add them from the **Threads** tab under **Add member**, or pick **Open a room with these threads** on a thread link.
 
-Members run in order, so a later speaker sees earlier speakers' results rather than talking past them. Scheduling follows three rules and nothing else:
+Persona turns run in order; existing threads each have their own queue. A member catches up on room messages when it wakes. Older queued notifications already covered by a successfully completed catch-up do not start another turn. Scheduling follows three rules:
 
 1. A user mention wakes the named members; `@everyone` selects all of them.
 2. A user message with no mention goes to the host, whether the host is a persona or a thread.
-3. A persona or Bot message wakes only the members it mentions. A message with no mentions does not continue the discussion.
+3. A persona or thread room message wakes only the members it mentions. A message with no mentions is logged but wakes no one.
 
 The budget limits member messages after each user message — 12 by default. When it runs out the discussion pauses, and **Continue** resets the budget and resumes the retained work. **Pause** cancels queued wakes but lets the active turn finish.
 
+A room whose member budget is spent: the discussion paused at 12 of 12 messages, with Continue and Adjust limit offered, and the member list beside it\.
+
 Renaming, changing the host, muting, and reassigning the classification workspace never rewrite a member's system prompt or permissions. A member that cannot wake shows the failure and a recovery action rather than a promise of an automatic retry: for a model login failure, sign in under **Settings → Models & providers → Connections**, or open the member's conversation and pick an available model, then send another room message and mention it if it is not the host.
 
 See [Discuss in a room](/en/customization/personas#discuss-in-a-room) and [Collaboration tools](/en/reference/tools#collaboration-tools).
 
 A room where three personas discuss a release, each message attributed to its speaker\.
 
+A room that also holds threads, listed under their own tab when you go to add a member\.
+
 ## Next steps
 
 - [Personas, Bots, and rooms](/en/customization/personas) — the full reference for personas, home conversations, and rooms

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

@@ -18,18 +18,26 @@ Change the credential scope on the subspace's own card in **Settings → Spaces*
 
 The spaces list: the main space beside two registered spaces, one sharing accounts and one isolated\.
 
+One space's own settings sheet, where each row says whether it follows the main space or is set here, with a Change action per row\.
+
+Choosing a space's credential scope: share the main space's accounts and keys, or keep this space's separate\.
+
 ## Remote connections: one Kiki, pointed at another
 
 A remote connection is a directed link from this Kiki's home to another Kiki home on another machine. It is not a shared login: the target has its own identity, and it must approve the source before anything flows.
 
 Receiving is off by default. Enabling the gate on the target does not approve anyone by itself — you then create an invitation, hand it to the source, and the source registers a connection against it. Every connection is one row with its own state, its last-known measurements, and actions that affect only that link: enable, disable, retry, or remove. `inbound revoke <grantId>` stops one source's reads and streams without touching the others, and `inbound disable` closes all peer access while keeping the allow list. Removing a connection releases local credentials and owned tunnels; it does not stop the target daemon or undo work already started there. An offline target keeps its last-known measurements and their timestamp rather than reporting invented zeros.
 
-The command side plans before it acts. `kiki connections ... ssh plan` only queries; `ssh execute PLAN_ID` attaches; only an explicit `--ensure` may start a remote daemon, and that daemon keeps running until you stop it. Neither opens inbound access on its own. Both hosts need a compatible Kiki and working SSH authentication with known-host verification, and Kiki does not install remote software for you.
+The command side plans before it acts. `kiki connections ... ssh plan` only queries; `ssh execute PLAN_ID` attaches; only an explicit `--ensure` may start a remote daemon, and that daemon keeps running until you stop it. Neither opens inbound access on its own. The GUI also rechecks an already-running target before attaching, without starting it or asking for another confirmation. Both hosts need a compatible connection protocol and working SSH authentication with known-host verification; their Kiki version strings do not have to match. Kiki does not install remote software for you.
+
+If the target temporarily closes inbound access, wait for its owner to reopen it, then try your operation again. A refusal for one operation does not sign you out of the connection, and Kiki never automatically repeats a refused write. An invalid token or revoked grant still rejects access; replace the connection's credentials or authorization before trying again.
 
 See [`kiki connections`](/en/reference/command#kiki-connections) and [`kiki bridges`](/en/reference/command#kiki-bridges) for the command reference behind these settings.
 
 The remote connections list: one row per peer Kiki, each with its own state and the moment its last reading was taken\.
 
+This Kiki's identity string, and the gate deciding which other Kikis may connect to it — off by default, with each allowed one listed and revocable\.
+
 ## Thread bridges: talk without browsing
 
 A thread bridge is a one-way channel for thread messages between two homes. It is deliberately narrower than a remote connection: the target home approves the exact source and target scopes, the operations — `read`, `send`, `wait`, and `wake` only if you ask for it — and an expiry, and the bridge carries nothing else. Without `wake`, sends stay pending rather than starting a model turn on the other side.
@@ -54,11 +62,15 @@ Web access turned on for this Kiki, with the browsers already signed in listed b
 
 ## In-session SSH
 
-A session can hold SSH hosts. Use the input box's **+** menu to add one, and the **Session SSH** control above the input box lists the joined hosts, takes a host away on **X**, and reopens the same list to add more. A joined host is a resource of that session, not something each message carries — so the timeline does not fill with host bubbles, and removing a host removes it from the session rather than from your machine.
+A session can hold SSH hosts. Use the input box's **+** menu to add one, and the **SSH** control above the input box lists the joined hosts, takes a host away on **X**, and reopens the same list to add more. A joined host is a resource of that session, not something each message carries — so the timeline does not fill with host bubbles, and removing a host removes it from the session rather than from your machine.
+
+The control appears only once the session holds a host. A session that has joined none has no SSH line above its input box, and the **+** menu is still the way to add the first one. It stays on screen for as long as the host is joined, including between turns, because "joined" is the session's own state rather than whether a request happens to be running.
+
+Adding a host makes it available to the session; it does not connect to it. In a new session, picking a host in the **+** menu shows the same **SSH** control before the first message, and the hosts you selected are joined to the created session before that message is sent.
 
-Adding a host makes it available to the session; it does not connect to it. In a new session the control reads **SSH to join**, and the hosts you selected are joined to the created session before its first message is sent.
+The SSH panel above the input box, listing the hosts joined to this session and the ones still available to add\.
 
-See [Interface overview](/en/guides/interface#input-box) for the Session SSH control and the send-timing menu beside it.
+See [Interface overview](/en/guides/interface#input-box) for the SSH control and the send-timing menu beside it.
 
 ## Next steps
 

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

@@ -18,15 +18,15 @@ The desktop app, the terminal UI (`kiki`), and the browser UI (`kiki web`) are t
 
 You hand the main agent a task — a coding change, a research question, a bug to track down. It plans, calls tools, and when the work divides cleanly it dispatches subagents to handle the focused pieces: exploring an unfamiliar codebase, reviewing several implementations in parallel, or planning a large refactor without touching the main context.
 
-A subagent receives a task description, works in its own isolated context, and returns its conclusions. It does not talk to you directly, and its intermediate reasoning and tool call records stay out of the main agent's history. The lead only keeps the result. This is why you can run four or five lines at once without the main context drowning in details.
+A subagent receives a task description and works in its own isolated context, then hands back its conclusions and reports when it finishes. Its full reasoning and tool call records are not poured into the main agent's history, which is what lets you run four or five lines at once without the main context drowning in details. You can still open any of them and read every step for yourself.
 
-Fresh installs ship two subagent profiles: `general`, a general-purpose assistant, and `explore`, a read-only explorer. Dispatch is scheduled by the main agent, based on task complexity, context consumption, and whether the sub-tasks are independent — you do not have to name one. You can, though: tell the main agent directly, or approve each dispatch as it appears.
+Fresh installs ship two subagent profiles: `general`, a general-purpose assistant, and `explore`, a read-only explorer. Dispatch is scheduled by the main agent, based on task complexity, context consumption, and whether the sub-tasks are independent — you do not have to name one. You can, though: tell the main agent directly, and under the `manual` permission mode each dispatch also stops for your approval.
 
 See [Agents and Sub-Agents](/en/customization/agents) for the full dispatch contract, context isolation, and permission inheritance.
 
 ## Each role can run a different model
 
-Different lines of work do not have to share a model. Bind the main agent, each subagent, and the reviewer to different models — or different vendors — and one session runs all of them at once. A strong reasoning model can plan while cheaper models do the routine work; a different vendor can review without the review being anchored to the same blind spots as the implementation.
+Different lines of work do not have to share a model. Bind the main agent, each subagent, and the reviewer to different models — or different vendors — and one session runs all of them at once. A strong reasoning model can plan while cheaper models do the routine work, and a reviewer running on a different model family brings an outside perspective to the decision the implementer already made.
 
 The main `agent` profile always receives three child-agent tools (`AgentRun`, `AgentList`, `AgentSend`) with no experiment flag, and each can name the model its child should run. If no model is pinned anywhere, a dispatch fails with `model.not_configured` rather than silently guessing. Kimi works out of the box; Anthropic, OpenAI-compatible services, the OpenAI Responses API, Gemini, and Vertex AI can be added, and you can sign in with a GitHub Copilot or ChatGPT account.
 
@@ -34,12 +34,18 @@ Model selection, hard model boundaries, and the model menu are covered in [Provi
 
 The dispatch tree of one session, with each role bound to its own model\.
 
+One session running several roles at once: the right rail lists the main agent's state, its todos, and each child agent with the model it is bound to\.
+
 ## A subagent keeps its own record
 
 Open any dispatched subagent to read its own transcript: what it was asked, what it did, and what it concluded — next to the main session, without loading the main agent's conversation. The same right rail follows you into the subagent, so you can inspect its context and cost the same way.
 
 You can also message a running subagent from its own composer, and pick it back up later with `AgentRun` to continue the same task instead of starting over. See [Agents and Sub-Agents](/en/customization/agents#named-child-agents) and the [right rail](/en/guides/interface#right-rail).
 
+A subagent's own session: its separate transcript, its own composer, and a composer row that shows which agent a message is replying to\.
+
+The right rail of a subagent, showing the same state, todos, working notes, and session overview the main agent gets\.
+
 ## Background tasks report back on their own
 
 Long shell commands and subagents do not have to hold the foreground. Send them to the background and Kiki notifies the main agent automatically when they finish, with the result inline and the full-output path retained — so neither you nor the agent has to keep checking. You can inspect a running task's status and output, and stop one at any time. Stopping an agent task also reports any direct subagents still running under it.
@@ -48,6 +54,8 @@ The main `agent` profile uses `TaskList`, `TaskOutput`, and `TaskStop` for backg
 
 The tasks page: one background task running with its stop control, one finished, and one failed\.
 
+The tasks page filtered to all tasks, one running, one completed, and one failed, each with the command it ran and a filter row across the top\.
+
 ## Next steps
 
 - [Work that runs long](/en/features/long-work) — goals, the queue, scheduled tasks, the board, and memory

package/dist/docs/en/getting-started/desktop-app.md

@@ -1,74 +1,89 @@
 # Kiki desktop
 
-Kiki desktop is available for Windows x64 (a per-user NSIS installer), Linux x64 (AppImage and deb), and macOS Apple Silicon or Intel (dmg). The Windows installer includes the CLI/TUI and adds `kiki` to your user `PATH`; Linux deb includes it too. This page explains the Windows-specific signed updater; Linux/macOS bundles use manual updates and their installation steps are in [Installation](./installation.md#install-the-desktop-app). Windows installers, updater signatures, SHA256 checksums, and versioned updater manifests are retained on [GitHub Releases](https://github.com/X-T-E-R/kiki/releases).
+The Windows build has a signed in-app updater. macOS and Linux builds do not — updating them means downloading the newer bundle yourself. This page covers both, plus what happens to your data during an update and how to roll back. Installation steps are in [Installation](./installation.md#install-the-desktop-app).
+
+| Platform | Bundle | How you update it |
+| --- | --- | --- |
+| Windows x64 | `Kiki_*_x64-setup.exe` (per-user NSIS installer, includes the CLI) | In-app updater, or run the newer installer |
+| Linux x64 | `Kiki_*_amd64.deb` / `Kiki_*_amd64.AppImage` | Download and install the newer bundle |
+| macOS Apple Silicon | `Kiki_*_aarch64.dmg` | Download the newer dmg |
+| macOS Intel | `Kiki_*_x64.dmg` | Download the newer dmg |
+
+Windows installers, updater signatures, SHA256 checksums, and updater manifests for every version stay on [GitHub Releases](https://github.com/X-T-E-R/kiki/releases).
 
 ::: warning Note
-Kiki Windows installers are not Authenticode-signed (Windows' official code signing for verifying the publisher) in the first public release. Windows SmartScreen may therefore identify the publisher as unknown even when the file came from the official Release.
+The Windows installer carries no Authenticode signature (Windows' official code signing, which is what displays a verified publisher name). SmartScreen may therefore show an unknown publisher for a file you downloaded from the official Release. See [SmartScreen and updater signing](#smartscreen-and-updater-signing).
 :::
 
 ## Requirements and release channels
 
-The desktop build supports Windows x64 and installs for the current Windows account without administrator access in the normal case. Windows may download the Microsoft Edge WebView2 bootstrapper (the Microsoft web component the desktop UI depends on) during installation if the required runtime is missing.
+The Windows build installs for the current Windows account without administrator access. If the machine lacks the required runtime, the installer downloads the Microsoft Edge WebView2 bootstrapper (the Microsoft web component the desktop UI renders in).
 
-On macOS the desktop app needs **13.5 or later**, because that is the bundled runtime's own floor. Intel and Apple Silicon are separate downloads, not one universal app. On Linux the desktop app is x64 (deb or AppImage); the CLI/TUI also builds for arm64. Terminal chat and other headless use need no desktop or display of any kind.
+macOS needs **13.5 or later**, which is the floor of the runtime bundled inside the app. Intel and Apple Silicon are separate downloads, not one universal app. Linux desktop builds are x64 (deb or AppImage); the CLI/TUI also builds for arm64. Nothing in Kiki requires a desktop — the CLI/TUI runs on a machine with no display.
 
-| Channel | Intended use | Public feed (the metadata URL for each update channel — not an RSS feed) |
+| Channel | What it offers | Update feed |
 | --- | --- | --- |
-| Stable | Normal daily use | `https://x-t-e-r.github.io/kiki/updater/stable/latest.json` |
-| Beta | Early access to a newer tested build | `https://x-t-e-r.github.io/kiki/updater/beta/latest.json` |
+| Stable | The current stable build | `https://x-t-e-r.github.io/kiki/updater/stable/latest.json` |
+| Beta | Newer builds that have been tested but are not stable yet | `https://x-t-e-r.github.io/kiki/updater/beta/latest.json` |
 
-The stable feed points to the highest published stable version and is absent until the first stable release. The beta feed is available during the public beta period; after stable exists, it compares the highest stable and beta versions using SemVer (Semantic Versioning — the rule that compares major, minor, and patch numbers) and points to whichever is newer.
+Each feed is a JSON file the updater reads; you never need to open it. The stable feed names the highest published stable version, and it stays empty until the first stable release. While only beta builds exist, the beta feed is the one that has content. Once both exist, the beta feed names whichever of the two is higher by SemVer (Semantic Versioning — the rule that compares major, minor, and patch numbers), so selecting Beta can also hand you the current stable build.
 
 ## Install and verify
 
-Installation starts from a versioned Release rather than an unversioned download link. This keeps the installer, checksum, and updater metadata tied to the same `kiki-v<version>` tag.
+Download from a versioned Release, not from a "latest download" link, so the installer, checksum, and updater metadata all come from the same `kiki-v<version>` tag.
 
-1. Open the [Kiki Releases page](https://github.com/X-T-E-R/kiki/releases) and select the required stable or beta version.
-2. Download the `Kiki_*_x64-setup.exe` installer and its adjacent `.sha256` file.
-3. In PowerShell, paste and run the following commands from the download directory, replacing the file name with the downloaded installer (the first command shows the checksum the release published, the second computes the checksum of your download — the two outputs must match):
+1. Open the [Kiki Releases page](https://github.com/X-T-E-R/kiki/releases) and select the stable or beta version you want.
+2. Download the `Kiki_*_x64-setup.exe` installer and the `.sha256` file next to it.
+3. In the download directory, open PowerShell and run these two commands, replacing the file name with the one you downloaded. The first prints the checksum the release published, the second computes the checksum of your copy:
 
    ```powershell
    Get-Content .\Kiki_1.0.0_x64-setup.exe.sha256
    (Get-FileHash .\Kiki_1.0.0_x64-setup.exe -Algorithm SHA256).Hash.ToLower()
    ```
 
-4. Confirm that the two hexadecimal hashes are identical.
-5. Run the installer and start Kiki from the Windows Start menu.
+4. Check that the two hexadecimal strings match.
+5. Run the installer, then start Kiki from the Windows Start menu.
 
-The `.sig` asset contains the complete Tauri updater signature (Tauri is the app framework behind the Kiki desktop app; this signature is consumed by its built-in updater). It is separate from the SHA256 checksum used for a manual download check.
+The `.sig` asset holds the Tauri updater signature (Tauri is the app framework behind the desktop app) that the in-app updater checks. You do not need it for a manual install — the `.sha256` file above is the manual check.
 
 ## Update
 
-Kiki checks the selected update channel once after desktop startup. You can also choose Stable or Beta and run a manual check from **Settings → About**. When an update is available, Kiki shows its version and release notes before asking for confirmation.
+**Settings → About** is where updates live. It shows the current version, lets you pick the **Update channel** (Stable or Beta), and turns automatic checks on or off. With automatic checks on, Kiki looks for a new version once a day, and the **When an update is found** setting below the switch decides what happens then: **Notify me** shows an update dialog, while **Download and install** goes straight into the install. Either way, a space with running work is never closed without asking you first. **Check for updates** always checks the channel you have selected, whether or not the automatic check is on.
+
+In **Notify me** mode the dialog shows the version and a short summary of what changed, then waits for you. The three buttons are not the same kind of decision:
 
-Installing an update exits the Kiki desktop process and its bundled sidecar (the background service process that runs alongside the desktop UI), verifies the signed installer, and runs the NSIS update. Running work is interrupted, so finish or stop important tasks before confirming. Kiki does not automatically downgrade when you switch channels.
+- **Remind me tomorrow** — the same offer comes back 24 hours later.
+- **Skip this version** — Kiki stops asking about that version on that channel, and remembers it. A newer version still comes, and a skip recorded on Stable does not silence Beta.
+- **Update now** — install it.
 
-If the in-app update fails, close Kiki, download the newer installer from its exact Release, verify its SHA256 file, and run it manually. Installing a newer version over the existing per-user installation keeps the normal application data location intact.
+Closing the dialog with the window button or `Esc` dismisses this reminder only; nothing is stored, so the same offer can come back later.
 
-The in-app update above is the Windows updater. On macOS and Linux, updating the desktop app means downloading the newer bundle yourself, so quit Kiki first, install the new bundle over the old one, and start it again. After replacing the app on macOS or Linux, quit any older Kiki process still using the same data home before starting the new build — see [`KIKI_HOME`](../configuration/env-vars.md#kiki-home).
+Before installing, Kiki looks the version up on your channel again. If the channel or the version changed since the offer appeared, it refreshes the offer instead of installing something you did not agree to. If any space still has a running session or waiting input, Kiki names those spaces and asks you to confirm before closing anything; declining leaves your sessions running. Once you confirm, Kiki closes the backends it manages, then downloads, verifies and installs. Switching channels never downgrades an install.
 
-The public `latest.json` files provide signed updater metadata for stable and beta clients. Each manifest points to an installer under a specific `kiki-v<version>` tag rather than a mutable latest-download URL, and its `signature` field is the content of that installer's `.sig` asset.
+If the download or install step fails, Kiki says so and the install button becomes a retry. Whether your sessions need restarting depends on how far it got: retry directly while the update screen is still usable, and restart Kiki only if you need those sessions back. If the automatic check or a channel change cannot be saved, the dialog stays open and tells you to try again.
+
+If the in-app update keeps failing, close Kiki, download the newer installer from the exact Release you were trying to update to, verify its `.sha256` file, and run it. Installing over the existing per-user installation keeps your application data where it is.
+
+On macOS and Linux, quit Kiki, install the newer bundle over the old one, and start it again. If an older Kiki process is still running against the same data home, quit it first — see [`KIKI_HOME`](../configuration/env-vars.md#kiki-home).
 
 ## Backend logs
 
-When desktop starts its own backend, it records diagnostic stderr (the process's error-output stream) in `desktop-backend.log` inside the active space's `logs` directory (the home's log folder, beside the server's own `kimi-code.log`). The current file rotates at 5 MiB and keeps three numbered backups (`.1` is the newest). Rotation also runs when opening an oversized existing log; that older file is retained as a backup. A single oversized new line is truncated to its UTF-8 tail. Logging failures do not stop the backend; startup diagnostics still retain the last 100 nonempty lines in memory.
+When the desktop app starts its own backend, that backend's error output goes to `desktop-backend.log` in the active space's `logs` directory, beside the server's own `kimi-code.log`. The file rotates at 5 MiB and keeps three numbered backups, where `.1` is the newest.
 
-The backend defaults to `warn`. To change it before the settings control is connected, quit desktop and set `"logLevel": "debug"` in the active space's `desktop.json`, preserving its other fields. Supported values are `fatal`, `error`, `warn`, `info`, `debug`, `trace`, and `silent`. A space inherits the main home's level unless it has its own override. The change applies on the next desktop-owned backend launch, not to an already running or externally managed server. Log-directory and path commands are available to desktop integrations; a browser connected to a remote server cannot open its host directory.
+The backend logs at `warn` by default. To change that, quit the desktop app and set `"logLevel"` in the active space's `desktop.json`, leaving its other fields alone. Accepted values are `fatal`, `error`, `warn`, `info`, `debug`, `trace`, and `silent`. A space without its own `desktop.json` follows the main home. The new level applies the next time the desktop app launches the backend.
 
 ## SmartScreen and updater signing
 
-SmartScreen reputation and updater signing answer two different questions: SmartScreen asks "who published this installer?", while the updater signature asks "was this file tampered with?". Because the installer has no Authenticode signature, Windows cannot display a verified publisher identity; the Tauri `.sig` allows the built-in updater to verify that the downloaded installer was signed with the Kiki updater key. The two facts are complementary, not contradictory.
-
-If SmartScreen appears, first confirm that the URL is under `github.com/X-T-E-R/kiki/releases/` and that the SHA256 value matches. Only then use **More info** and **Run anyway** if you accept the unknown-publisher warning. Do not install a copy received through chat, email, or a third-party mirror.
+When SmartScreen appears, check the URL and the hash before you go any further: the URL should be under `github.com/X-T-E-R/kiki/releases/`, and the SHA256 value should match the published one. If both check out, use **More info** → **Run anyway**. A copy that arrived through chat, email, or a third-party mirror fails that check by definition — do not install it.
 
 ## Windows, tray, and opening files
 
-Closing the window hides it to the tray on Windows and macOS; use **Quit** from the tray menu, or the usual exit command, to actually exit. If the tray icon cannot be created, Kiki still opens normally and closing the window asks you to confirm the exit instead. On Linux, when a tray is available the same close minimizes the window so your window manager can bring it back; where there is no tray, closing asks you to confirm the exit. Global shortcuts are a convenience — if one cannot be registered, the app still starts.
+On Windows and macOS, closing the window hides it to the tray — **Quit** in the tray menu is what actually exits. On Linux with a tray available, the same close minimizes the window so your window manager can bring it back. Where no tray is available, closing the window asks you to confirm the exit instead.
 
-Opening a file from the file menu hands it to the system application associated with that file type. The menu refuses a list of known launch targets rather than opening them: `.app` and `.command` on macOS, `.desktop` on Linux, and executables and scripts on Windows — including a link whose real target is one of those. Ordinary text files open normally, and *Reveal in file manager* and saving are unaffected. Treat the refusal list as covering those named types, not as a general promise about every file association.
+Opening a file from the file menu hands it to the app your system associates with that file type. The menu does not launch these types, because starting them would run code outside the app: `.app` and `.command` on macOS, `.desktop` on Linux, and executables and scripts on Windows. A shortcut pointing at one of those is refused too. Other files, including ordinary text files, open normally, and **Reveal in file manager** is unaffected.
 
 ## Roll back
 
-Rollback uses the immutable assets retained on the Releases page. Back up any important workspace data first, close Kiki, download the previous installer and `.sha256` file from its exact tag, verify the hash, and run that installer.
+To go back a version, back up any workspace data you care about, close Kiki, then download the previous installer and its `.sha256` file from that exact tag, verify the hash, and run the installer.
 
-If Windows refuses to install an older version over a newer one, uninstall Kiki from **Installed apps** and then run the older installer. Do not delete Kiki's application data while uninstalling unless you also intend to reset local settings and sessions. After rollback, use the stable feed or continue updating manually from stable Releases to avoid immediately selecting a newer beta again.
+If Windows refuses to install the older version over the newer one, uninstall Kiki from **Installed apps** first, then run the older installer. Keep Kiki's application data through that uninstall unless you want to reset your local settings and sessions. After rolling back, stay on the stable channel — otherwise the next update check offers you the beta again.

package/dist/docs/en/getting-started/first-launch.md

@@ -1,6 +1,6 @@
 # First launch
 
-This page picks up after installation: start Kiki, configure an API source, and run your first conversation.
+You have Kiki installed. This page walks through the first ten minutes: starting it in your project, connecting a model, and getting a useful answer out of it.
 
 ## Start Kiki
 
@@ -11,54 +11,65 @@ cd your-project
 kiki
 ```
 
-When developing from source, run `pnpm dev:cli` from the repository root instead. To run a single instruction without entering the interactive UI, use `-p` (prompt mode):
+If you are working from a source checkout, run `pnpm dev:cli` from the repository root instead. To send a single instruction without entering the interactive UI, use `-p` (prompt mode):
 
 ```sh
 kiki -p "Take a look at this project's directory structure"
 ```
 
-To resume the previous session, add `-c` (short for `--continue`; how it differs from `--session` is covered in [Workspaces and sessions](../guides/sessions.md#starting-and-resuming-sessions)):
+Add `-c` (short for `--continue`) to pick up the previous session; [Workspaces and sessions](../guides/sessions.md#starting-and-resuming-sessions) covers how that differs from `--session`:
 
 ```sh
 kiki -c
 ```
 
-## Configure an API source
+## Connect a model
 
-On first launch you need to configure an API source. In the interactive UI, enter `/login` to begin the login flow:
+Kiki needs a model before it can answer anything. In the interactive UI, type `/login`:
 
 ```sh
 /login
 ```
 
-`/login` opens a platform selector supporting two options:
+That opens a picker with four options:
 
-- **Kimi Code (OAuth)** — device-code flow; open the link on any device, sign in, and enter the code to authorize
-- **Kimi Platform API key** — enter an API key from `platform.kimi.com` or `platform.kimi.ai`
+- **Kimi Code (kimi.com/code)** — the managed subscription, via a device-code flow: open the link on any device, sign in, and enter the code
+- **Kimi Code (kimi.ai/code)** — the same flow against the global endpoint
+- **Kimi Platform (API key · platform.kimi.com)** — an API key from the mainland platform console
+- **Kimi Platform (API key · platform.kimi.ai)** — an API key from the global platform console
 
-To sign out, enter `/logout` to clear the current credentials.
+`/logout` clears the current credentials.
 
-::: tip Using other AI providers
-If you want to connect Anthropic, OpenAI, Google, or other providers, edit `~/.kiki/config.toml` directly to configure the API key. See [Providers and models](../configuration/providers.md) for details. For the full reference of all config options, see [Configuration files](../configuration/config-files.md), [Environment variables](../configuration/env-vars.md), and [Configuration overrides](../configuration/overrides.md).
+::: tip Other providers
+Anthropic, OpenAI, Google, and other providers are configured in `~/.kiki/config.toml` — see [Providers and models](../configuration/providers.md). The full option reference is split across [Configuration files](../configuration/config-files.md), [Environment variables](../configuration/env-vars.md), and [Configuration overrides](../configuration/overrides.md).
 :::
 
-In the desktop app and browser UI, an optional setup wizard opens on first run. It has four pages: pick your language and look; connect a model using an API key (the most general option) or sign in with Kimi Code, GitHub Copilot, or ChatGPT (Codex); choose the default permission mode for new sessions (Auto is recommended); and an optional last page about web search, SSH, external engines, plugins and MCP, scheduled tasks and more, where each item opens its settings or, with **Let Kiki set it up**, a new session with a `/kiki-ops` request pre-filled (not sent). The wizard does not ask for a folder: a new session uses the most recent workspace, or a new folder in Kiki Home when there is none. The model step groups API-key templates by vendor, gateway, and local server. After connecting, use **Settings → Models & providers → Available models** to search and star the model new sessions should use. Any step can be skipped and finished later in Settings, and **Replay setup wizard** runs it again. Finishing opens a new session with an empty input box; starter suggestions below it fill in a first prompt, and nothing is sent until you send it. To set up search, MCP, or your own agent roles later, ask Kiki with `/kiki-ops`; see [Agents and Sub-Agents](../customization/agents.md#built-in-sub-agents) for how profiles select models.
+Instead of the terminal, the desktop app and the browser UI open a setup wizard on first run with the same four choices:
+
+1. **Language and look** — the window behind the dialog previews each choice.
+2. **Connect a model** — an API key works with the widest range of services, and you can instead sign in with a Kimi Code, GitHub Copilot, or ChatGPT (Codex) account. Templates are grouped by vendor, gateway, and local server. **Test connection** checks the values in the form without saving anything.
+3. **Permissions** — the default permission mode for new sessions. Auto is the recommended choice: it works on its own inside the workspace and asks before sensitive or external actions.
+4. **What else Kiki can do** — web search and history, memory, SSH hosts, external engines, plugins, skills and MCP, scheduled tasks, the task board, and bots. Each row either opens its settings or, with **Let Kiki set it up**, opens a new session with a `/kiki-ops` request typed in for you to review and send.
+
+Skip any page and finish it later — **Settings → Models & providers** holds the model connection, and **Replay setup wizard** in Settings starts the wizard over. After connecting a provider, star the model you want in **Settings → Models & providers → Available models**; new sessions use starred models.
+
+The wizard does not ask which folder to work in. **Set up with Kiki** opens a new session in a new folder under Kiki Home, with a setup request already typed into the composer: Kiki asks what you mainly use it for, offers to create your first agent, and helps you choose a default model and thinking effort for the read-only Explore subagent — or leaves it alone, or turns that role off. **Set up later** skips all of that and simply closes the dialog. Nothing is sent in either case until you send it, and the starter chips on the new session offer a few opening prompts. For the workspace itself, the new session page still defaults to your most recent workspace, or a new folder under Kiki Home if you have none. You can also ask for any of that later setup with `/kiki-ops`, and [Agents and sub-agents](../customization/agents.md#built-in-sub-agents) covers how agent profiles pick their model.
 
 ## Your first conversation
 
-Once logged in, describe a task in natural language. A good starting point is to let Kiki familiarize itself with the project:
+Once logged in, describe what you want in natural language. Letting Kiki look around first is a good way to start:
 
-```
+```text
 Take a look at this project's directory structure and briefly describe what each directory is for.
 ```
 
-Kiki automatically calls file-reading, search, and other tools (tools are built-in capabilities the agent can invoke — reading files, searching code, running commands) to browse the relevant content before responding. Read-only operations are executed automatically by default without requiring confirmation.
+Kiki answers using tools (built-in capabilities it can call — reading files, searching code, running commands), so it looks at your project before it replies instead of guessing. Read-only calls run without stopping to ask.
 
-New sessions default to Auto mode: ordinary tool calls, including shell commands, run without asking. Access to sensitive files such as `.env` files and private keys requires approval, as do dangerous Bash commands by default. In manual mode, `Write` / `Edit` inside a trusted working directory run without per-file approval; shell commands and workspace-external writes ask first. Use `/permission` to pick one of the four modes: `manual`, `auto`, `review` ("Approve for me", where a reviewer you configure decides first and anything uncertain comes back to you), or `yolo`. See [Permission modes](../guides/interaction.md#permission-modes) for the differences.
+New sessions start in Auto mode, so Kiki runs ordinary tool calls — including shell commands — without stopping to ask, and pauses for your approval before touching sensitive files such as `.env` or private keys. Use `/permission` to switch to `manual`, `auto`, `review` ("Approve for me", where a reviewer you configure decides first), or `yolo`; [Permission modes](../guides/interaction.md#permission-modes) explains what each one asks for.
 
-You can also describe a more concrete task directly:
+You can also skip the tour and describe a concrete task:
 
-```
+```text
 Add a function in src/utils that converts any string to kebab-case, and add a unit test for it.
 ```
 
@@ -68,9 +79,9 @@ Kiki plans the steps, modifies the code, runs the tests, and tells you what it d
 Type `/help` at any time to open the built-in command and keyboard shortcut panel. Use `↑`/`↓` to browse and `Esc` to close. To exit, type `/exit`, press `Ctrl-C` twice, or press `Ctrl-D` with the input box empty.
 :::
 
-## Common commands and keyboard shortcuts
+## Commands and shortcuts worth knowing now
 
-For a first-time user, the following is all you need to know:
+If you remember nothing else from this page, remember these:
 
 **Session commands**
 
@@ -96,7 +107,7 @@ For the full list, type `/help` or visit [Slash commands](../reference/slash-com
 
 ## Where data is stored
 
-Kiki stores its local data under `~/.kiki/` by default — config files, session records, logs, and the update cache. To move it elsewhere, point to a new path via the `KIKI_HOME` environment variable. Note that the desktop app's OAuth credentials default to the compatibility home `~/.kimi-code/` when `KIKI_HOME` is unset; see [Data locations](../configuration/data-locations.md) for the full picture.
+Kiki keeps its local data under `~/.kiki/` — config files, session records, logs, and the update cache. Set the `KIKI_HOME` environment variable to move all of it somewhere else. One exception: unless `KIKI_HOME` is set, the desktop app reads OAuth credentials from the compatibility home `~/.kimi-code/`. [Data locations](../configuration/data-locations.md) lists every path and what it holds.
 
 ## Next steps