Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

docs: update user guides for subscription runtimes (#109)

Leo2bc79431310f
diff --git a/docs/README.md b/docs/README.md
index 55150eef7..89535c258 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -3,6 +3,8 @@
## Using Akeru Bot
- [Install and first run](./user/install.md)
+- [Configure bots](./user/bots.md)
+- Providers: [Codex](./user/providers-codex.md) · [Claude](./user/providers-claude.md)
- [Permission modes](./user/permission-modes.md)
- [Configure sandboxes](./user/sandboxes.md)
- [Keyboard shortcuts](./user/keybindings.md)
@@ -17,8 +19,7 @@
- [Remote access](./user/remote-access.md)
- [Keeping app and server in sync](./user/updating.md)
- [Source control integrations](./user/source-control.md)
-- [Background service (Linux)](./user/background-service.md)
-- Providers: [Codex](./user/providers-codex.md) · [Claude](./user/providers-claude.md)
+- [Background service](./user/background-service.md)
Mobile app: [apps/mobile/README.md](../apps/mobile/README.md)
diff --git a/docs/user/analytics.md b/docs/user/analytics.md
index 2d66fd240..646df55a3 100644
--- a/docs/user/analytics.md
+++ b/docs/user/analytics.md
@@ -1,30 +1,41 @@
# Anonymous usage analytics
-Akeru Bot sends anonymous usage totals from packaged production builds. Development
-and CI runs do not send analytics unless a maintainer enables them.
-
-Each report covers one three-hour UTC period. It contains counts for bots, messages,
-bot replies, failed turns, groups, approval decisions, provider turns, sandbox turns,
-completed tool categories, and provider-native web searches. It also records which
-public catalog plugins are enabled. Custom plugin names and MCP server details never
-leave the installation.
-
-The first report with activity marks the analytics installation as new. This supports
-an anonymous new-active-install trend. It does not identify a person or count a
-download that never runs.
-Reserved counters for external messages, voice, browser tasks, routines, and
-connectors stay at zero until those features have a durable local count source.
-
-Akeru Bot uses a random UUID only for analytics. It does not read provider sign-in
-files or use an account ID. Reports do not contain personal information, user
-content, connector data, IP addresses, prompts, replies, model output, personal IDs,
-URLs, paths, recipients, memory, payloads, tokens, credentials, screenshots, stack
-traces, error text, files, or custom properties.
-
-Turn off **Analytics** in **Settings → General** to stop collection. Akeru Bot then
-deletes the analytics UUID, the current period, all reports waiting to send, and the
-legacy analytics ID file. The setting stays off.
+Packaged production builds send anonymous aggregate usage by default. Development and CI builds do
+not send it unless a maintainer enables it.
+
+## What a report contains
+
+Each report covers one three-hour UTC period. It contains fixed counters for:
+
+- created, deleted, and active bots
+- user messages, bot replies, group messages, and failed turns
+- approval decisions and provider turns
+- local and remote sandbox turns
+- completed tool categories and provider-native web searches
+- supported external messages, voice calls, browser work, routines, and connectors
+- public catalog plugins that are enabled
+
+Counters with no durable local source stay at zero. Custom plugin names and Custom MCP server details
+never leave the environment.
+
+The first report with activity marks the installation as new. This measures active installations. It
+does not count a download that never runs.
+
+## What a report excludes
+
+Reports do not contain prompts, replies, model output, files, paths, URLs, recipients, memory,
+screenshots, stack traces, error text, tokens, credentials, or provider account identifiers.
+
+Akeru uses a random analytics UUID. It disables PostHog person profiles and geolocation for these
+events. It also supplies a fixed empty IP value instead of the client address.
+
+## Turn analytics off
+
+Open **Settings > Privacy** and turn off **Anonymous analytics**. Mobile uses the same path.
+
+Turning analytics off deletes the analytics UUID, the current period, queued reports, and the legacy
+analytics ID file. The setting stays off.
Resource diagnostics are separate. [Local resource telemetry](../internals/resource-telemetry.md)
-measures processes and host resources for the diagnostics interface. It does not
-send those measurements as anonymous usage analytics.
+measures the environment for the diagnostics interface and does not send those measurements as
+anonymous analytics.
diff --git a/docs/user/background-service.md b/docs/user/background-service.md
index 09d690ba7..d93244b94 100644
--- a/docs/user/background-service.md
+++ b/docs/user/background-service.md
@@ -1,65 +1,63 @@
-# Running Akeru Bot in the background
+# Run Akeru in the background
-On Linux and macOS, Akeru Bot can run as a background service for your user, so it is ready without
-keeping a terminal open.
+Linux and macOS can run the command-line server as a service for the current user.
## Manage the service
-Install it with the latest Akeru Bot release:
+Install the latest release:
-```sh
+```bash
npx akeru-bot@latest service install
```
-Check whether it is installed:
+Check its state:
-```sh
+```bash
npx akeru-bot@latest service status
```
Update or repair it:
-```sh
+```bash
npx akeru-bot@latest service update
```
Stop it and remove it from startup:
-```sh
+```bash
npx akeru-bot@latest service uninstall
```
-Updating restarts Akeru Bot briefly. Let active agent work and terminal commands finish first.
-If a remote update is already in progress, wait for it to finish before retrying a local update.
+An update restarts Akeru. Let active agent work and terminal commands finish first. Wait when another
+local or remote update is already running.
-The service runs a small stable launcher. Exact Akeru Bot versions are installed separately, so a
-failed remote candidate can return to the previous version without rewriting the service
-definition. The launcher snapshots the database before a remote candidate starts, so database
-updates roll back with the server version. An older launcher may require one local
-`service update` before this is available.
+## Updates and rollback
-## Platform support
+The service uses a stable launcher and installs exact Akeru versions separately. Before a remote
+candidate starts, the launcher snapshots the database. A failed candidate can return to the previous
+server and database without rewriting the service definition.
-**Linux** uses a systemd user unit at `~/.config/systemd/user/t3code.service`. The service starts
-when the machine boots and keeps running after you log out (lingering is enabled during install).
+An older launcher can require one local `service update` before remote rollback is available.
-**macOS** uses a launch agent at `~/Library/LaunchAgents/com.t3tools.t3code.service.plist`. It
-starts when you log in, not when the Mac boots, and it stops when you log out; macOS has no
-equivalent of Linux lingering for user agents. For a Mac that should stay reachable unattended,
-turn on automatic login (System Settings → Users & Groups; unavailable while FileVault is on) and
-keep the Mac from sleeping.
+## Linux
-A few more macOS notes:
+Linux installs a systemd user unit at `~/.config/systemd/user/t3code.service`. Installation enables
+lingering, so the service starts at boot and remains available after you log out.
-- Installing over SSH needs someone logged in at the Mac's screen to start the agent right away.
- Without that, the install command reports an error at the final start step, but the agent is
- fully installed and starts at the next login.
-- macOS may show privacy prompts for protected folders such as Desktop, Documents, or Downloads,
- attributed to a bare `node` process, or deny access without a prompt. If agent work fails to
- read those folders, grant Full Disk Access to the node binary listed in the launch agent's
- `ProgramArguments`.
-- The agent appears under System Settings → General → Login Items. If it was switched off there,
- or disabled with `launchctl disable`, macOS will not start it at login until you switch it back
- on.
+## macOS
-**Windows** is not supported yet.
+macOS installs a launch agent at
+`~/Library/LaunchAgents/com.t3tools.t3code.service.plist`. It starts when you log in and stops when
+you log out.
+
+For an unattended Mac, keep the Mac awake and configure an account to log in after restart. FileVault
+can prevent automatic login.
+
+An install over SSH needs a user logged in at the Mac to start the launch agent immediately. Without
+that session, installation can finish but the agent starts at the next login.
+
+If agent work cannot read Desktop, Documents, or Downloads, grant Full Disk Access to the Node.js
+binary listed in the launch agent's `ProgramArguments`. Also check **System Settings > General >
+Login Items** if the launch agent does not start.
+
+Windows does not support the background service yet.
diff --git a/docs/user/bots.md b/docs/user/bots.md
index ddd8dd5e5..b302ccfb0 100644
--- a/docs/user/bots.md
+++ b/docs/user/bots.md
@@ -1,44 +1,65 @@
# Configure bots
-Open a bot to edit its profile in the panel beside the conversation.
+Open a bot, then use the panel beside the conversation to edit it.
-- Select the avatar to change its shape, color, generated image, or uploaded image.
-- Set the bot name.
-- Add an optional label and description.
-- Choose the model that the bot uses.
-- Set an optional **Token hard stop**. Akeru Bot interrupts the current step at the limit.
-- Turn on **Voice calls** to show the phone button in that bot's chat header.
-- Open **Tools** to choose which installed plugins and MCP servers the bot can use. New tools are enabled for every bot by default.
-- Select **Save** to apply profile, model, voice, and tool changes.
+## Profile
-Akeru Bot stores the profile in the connected environment. Other clients connected to the same environment see the same bot configuration. Workspace-disabled tools stay unavailable to all bots.
+You can change the bot's avatar, name, label, description, model, voice access, and enabled tools.
+Select **Save** to apply the changes.
-Each settled bot reply shows its engine, step tokens, and estimated USD cost when the provider reports enough usage data.
+Set **Token hard stop** to interrupt the current step when it reaches the selected limit. A settled
+reply shows its engine, step tokens, and estimated USD cost when the provider reports enough usage
+data.
-Settings controls whether bots share their workspace and browser. **Separate** is the default and gives each bot its own workspace identity and browser profile. **Shared** lets bots share files and cookies. Bots can use Local, E2B, Daytona, Vercel Sandbox, or Upstash Box workspaces. Connect remote providers in **Settings > Sandbox**. Remote workspaces use the provider credentials available to the environment and fail if those credentials are missing. A bot's explicit sandbox overrides the default.
+Akeru stores bot profiles on the connected environment. Every client connected to that environment
+sees the same profile.
-Local bots ask before file changes and shell commands by default. Select **Settings > General > Local execution > Full access** to skip those local prompts. Actions that send, pay, delete, change production, or use secrets still ask. Bots that run in a cloud sandbox do not show the local computer prompt.
+## Workspaces and browsers
+
+**Separate** is the default. Each bot gets its own workspace identity and browser profile. **Shared**
+lets bots share files and browser cookies.
+
+Bots can use Local, E2B, Daytona, Vercel Sandbox, or Upstash Box. Connect remote services under
+**Settings > Sandbox**. A bot-specific sandbox overrides the environment default.
+
+Local bots ask before file changes and shell commands by default. Set **Settings > General > Local
+execution** to **Full access** to skip routine local prompts. Protected actions still ask. Cloud
+sandboxes do not show the local-computer prompt.
## Run a routine
-Open **Routines** in a bot's panel. Add a job, procedure, schedule, timezone, required skills, and connectors. Run a dry run and approve the procedure before you enable its schedule.
+Open **Routines** in the bot panel. Add a job, procedure, schedule, timezone, required skills, and
+connectors. Run a dry run and approve the procedure before you enable its schedule.
-The panel shows the next and last run, latest result or failure, and the five latest attempts. You can run, pause, resume, edit, or delete the routine. A procedure change requires approval again.
+The panel shows the next and last run, latest result or failure, and five recent attempts. You can
+run, pause, resume, edit, or delete the routine. A procedure change needs approval again.
-If a required connector, provider, bot, or workspace is unavailable, Akeru pauses the routine and adds one item to the bot inbox. Fix the dependency, then resume the routine. Restoring an archived bot does not resume its routines.
+If a required connector, provider, bot, or workspace is unavailable, Akeru pauses the routine and
+adds one item to the bot inbox. Fix the dependency, then resume the routine. Restoring an archived
+bot does not resume its routines.
-Use the panel button to collapse or reopen the editor. The default shortcut is **Mod+Alt+B**, and you can change `Right Panel: Toggle` in the keybinding settings. On a narrow screen, the same button opens a sheet.
+## Tools
-When a request needs tools, the bot first replies in plain language. During longer work, it adds short status notes after meaningful progress. When work resumes automatically, it continues without a repeated opening note.
+Open **Tools** in the bot editor to enable or disable installed plugins and MCP servers. New tools
+start enabled for every bot. A workspace-disabled tool stays unavailable to every bot.
-Bot replies support headings, links, tables, task lists, code blocks, math, and Mermaid diagrams.
+Changing the provider starts a fresh provider session with the same enabled tool set.
+
+## Conversation panel
-On web and desktop, a bot can link to an app setting with a chip such as `[Error inbox](grokbot://app/v1/settings?id=bot-inbox)`. The chip opens the matching Settings section and shows the destination on hover.
+Use the panel button to collapse or reopen the bot editor. The default shortcut is `Mod+Alt+B`. You
+can change **Right Panel: Toggle** in keybinding settings. Narrow screens open the editor as a sheet.
-## Call a bot
+Bot replies support headings, links, tables, task lists, code blocks, math, and Mermaid diagrams.
+During longer work, the bot posts short status notes after meaningful progress.
-Open **Settings → Voice** to enable voice, choose the ChatGPT subscription provider, and select a voice. Turning voice off there removes calling for every bot.
+## Voice calls
-Turn on **Voice calls** for the bot, then select the phone button in its chat header. Akeru Bot uses the microphone and speaker on this computer with the connected ChatGPT subscription. New calls use the voice selected in Settings.
+1. Open **Settings > Voice**.
+2. Enable voice and choose the connected ChatGPT subscription and voice.
+3. Turn on **Voice calls** for the bot.
+4. Select the phone button in the bot's chat header.
-Only one call can run at a time. The call bar stays visible when you open another bot. Select the bar to return to the call, or select the hang-up button to end it.
+Akeru uses the microphone and speaker on the current computer. Only one call can run at a time. The
+call bar stays visible when you open another bot. Select it to return to the call, or select hang up
+to end the call.
diff --git a/docs/user/composer.md b/docs/user/composer.md
index bd758c84e..86d091823 100644
--- a/docs/user/composer.md
+++ b/docs/user/composer.md
@@ -1,27 +1,31 @@
# Message composer
-Messages can contain up to 120,000 characters. If a draft is longer, Akeru Bot keeps it in the
-composer and shows how many characters need to be removed. Shorten the draft or split it into
-multiple messages, then send again in the same thread.
+Messages can contain up to 120,000 characters. Akeru keeps an oversized draft in the composer and
+shows how many characters you must remove. Shorten the draft or send it as several messages.
-On servers that support direct uploads, images upload as soon as you add them. The send button
-becomes available after every upload finishes. Failed uploads can be retried or removed.
+## Attach images
-On web and desktop, HEIC and HEIF photos are automatically converted to JPEG when you drag them into
-the composer or paste them into a message.
+On servers with direct uploads, an image starts uploading when you add it. Akeru enables **Send**
+after every upload finishes. Retry or remove a failed upload.
+
+Web and desktop convert HEIC and HEIF photos to JPEG when you drag or paste them into the composer.
## Commands and skills
-Type `/` to open the command menu. Type `$` to find and add a skill. Skill rows show their source,
-such as System, Personal, Project, or App.
+Type `/` to open the command menu. Type `$` to search for a skill and add its token to the message.
+
+Skill results identify their source as App, Repo, Project, Personal, System, or Provider. A selected
+skill appears as a badge in the composer.
+
+The slash menu includes skills by default. Turn off **Show skills in slash menu** under
+**Settings > General** to keep it command-only. Slash-menu skill results use the
+`/skill:Skill Name` label and insert the same `$name` token. Akeru hides duplicate native provider
+commands when the same skill is already available.
+
+## Start work in the background
-By default, the `/` menu includes skills. To keep this menu command-only, turn off **Show skills in
-slash menu** in **Settings → General**. Skill results use the `/skill:Skill Name` label and add the
-same `$name` skill token to your message. The original skill name remains searchable. If the provider
-also reports that skill as a native slash command, Akeru Bot hides the duplicate native entry and keeps
-the `/skill:Skill Name` label.
+From a new thread on desktop, press `Cmd+Enter` on macOS or `Ctrl+Enter` on Windows and Linux. Akeru
+starts the thread, opens another new thread, and shows an **Open** action for the work in progress.
-On desktop, press `Cmd+Enter` on macOS or `Ctrl+Enter` on Windows and Linux from a new thread to
-start it in the background. Akeru Bot opens another new thread and shows an **Open** action for the
-thread that started. The new thread keeps the selected workspace mode and base branch. If **New
-worktree** is selected, each background thread creates its own worktree.
+The background thread keeps the selected workspace mode and base branch. If **New worktree** is
+selected, each background thread creates a separate worktree.
diff --git a/docs/user/data-portability.md b/docs/user/data-portability.md
index 7d9134b58..a4217c1a9 100644
--- a/docs/user/data-portability.md
+++ b/docs/user/data-portability.md
@@ -1,17 +1,28 @@
-# Data portability
+# Move Akeru data
-Open **Settings > General**, then find **Data portability**.
+Open **Settings > General** and find **Data portability**.
-Choose **Export** to download an `akeru.archive` file. The archive includes safe server settings, MCP recipes, bots, groups, mapped project references, thread metadata, conversation text, plans, and approval history.
+## Export
-The archive removes credentials, local paths, project scripts, attachments, image files, Git state, provider sessions, receipts, tool arguments, raw approval payloads, and deleted threads and projects. It replaces image avatars with generated avatars. MCP recipes do not include secrets.
+Select **Export** to download an `akeru.archive` file. The archive can contain safe server settings,
+MCP recipes, bots, groups, mapped project references, thread metadata, conversation text, proposed
+plans, and approval history.
-Imported approval rows are history only. An import does not reopen a request or approve an action. Imported MCP servers stay disabled until you reconnect their credentials.
+The export excludes secrets, provider credentials, jobs, durable memory, routines, skill
+assignments, usage history, files, Git repositories, terminals, attachments, and checkpoints.
-Choose **Import** and select an archive to see a restore preview. The preview lists additions, changes, conflicts, missing providers, and data that stays on the source device. Review this list before you restore the archive.
+## Import
-Akeru Bot updates a project when its existing workspace reference matches the archive. For each missing workspace, choose an existing local folder in the preview. Akeru Bot links the restored project to that folder without copying its files, then restores its threads. Import skips unmapped projects and their threads without blocking independent records.
+1. Select **Import** and choose an archive.
+2. Review the bots, groups, projects, threads, settings, and skipped items in **Restore preview**.
+3. Map project paths to directories on the destination environment.
+4. Select **Restore**.
-Import skips records that need a missing provider. It also skips conflicts when the target has a newer record. If the environment changes after the preview, Akeru Bot stops the import and requires a new preview.
+The archive limit is 20 MiB. Akeru validates the complete archive before it writes any restored data.
+Unsupported or unsafe entries appear in the preview and remain skipped.
-The restore result lists failed records. A partly restored record means at least one write succeeded before another write failed. Review the archive again after any failed or partly restored result.
+Desktop can use its native project-folder picker. Browser and mobile clients cannot browse the
+server's filesystem through that picker, so map paths from a desktop client when needed.
+
+Keep the archive private. It can contain conversation text, project paths, bot instructions, and
+approval history even though it excludes credentials.
diff --git a/docs/user/install.md b/docs/user/install.md
index fc1c60621..2751bfa2e 100644
--- a/docs/user/install.md
+++ b/docs/user/install.md
@@ -1,64 +1,72 @@
# Install Akeru Bot
-Akeru Bot is a web and desktop GUI for running coding agents on your machine.
+Akeru Bot runs on your machine. The desktop app includes the server. The command-line package runs
+the same server for web and remote clients.
-## Requirements
+## Desktop app
-Node.js `^22.16 || ^23.11 || >=24.10` on the machine that runs the Akeru Bot server.
+Download the current installer from
+[GitHub Releases](https://github.com/opencoredev/akeru-bot/releases).
+
+- macOS: Apple silicon DMG
+- Windows: Windows 10 or 11 x64 installer
+- Linux: x86_64 AppImage
+
+Open the app, add a project, then open **Settings > Providers** to connect an account. The desktop
+app manages the local server.
+
+## Command-line server
-At least one provider CLI, installed and authenticated. See [Providers](#providers) below.
+The command-line server requires Node.js `^22.16 || ^23.11 || >=24.10`.
-## Run Without Installing
+Run the latest release without installing it globally:
```bash
npx akeru-bot@latest
```
-This starts the Akeru Bot server on your machine and opens the local web app. Use
-`npx akeru-bot@latest --help` for the full CLI reference.
+The command starts the server and opens the local web app. Run this for the complete command list:
-## Desktop App
-
-Download the latest installer for your platform from
-[GitHub Releases](https://github.com/opencoredev/akeru-bot/releases).
+```bash
+npx akeru-bot@latest --help
+```
-## Providers
+Use the [background service](./background-service.md) when the server must stay available after you
+close the terminal.
-Akeru Bot drives provider CLIs; it does not ship them. Install the CLI for each provider you want
-to use, then authenticate it.
+## Connect a subscription
-| Provider | CLI | Default binary | Log in with |
-| ---------- | ----------------------------------------------------- | -------------- | --------------------- |
-| Codex | [Codex CLI](https://developers.openai.com/codex/cli) | `codex` | `codex login` |
-| Claude | [Claude Code](https://claude.com/product/claude-code) | `claude` | `claude auth login` |
-| Grok Build | [Grok Build CLI](https://x.ai/cli) | `grok` | `grok login` |
-| OpenCode | [OpenCode](https://opencode.ai) | `opencode` | `opencode auth login` |
+Open **Settings > Providers** on any connected client. The **Subscriptions** section supports:
-Codex and Claude are on by default. Grok Build and OpenCode are off by default; turn
-them on in **Settings** → the provider's card when you want to use them.
+| Account | Supported access |
+| --------------- | --------------------------------------- |
+| ChatGPT | Plus, Pro, Business, Enterprise, or Edu |
+| Claude | Pro or Max |
+| Grok | Shared xAI login |
+| Kimi For Coding | Kimi For Coding plan |
-Run the login command on the machine running the Akeru Bot server, not on the device you browse
-from.
+Select **Connect** and finish the provider's sign-in flow. ChatGPT, Grok, and Kimi use a device code.
+Claude asks you to paste the returned authorization code into Akeru.
-### Binary Discovery
+The environment server owns the connection, so you sign in once per environment. It stores access
+and refresh tokens outside the workspace. Web, desktop, and mobile clients only receive connection
+status and sign-in progress.
-Each provider CLI must be on the server's `PATH`, or have an explicit binary path set in
-**Settings** → the provider instance → **Binary path**. Use the explicit path when a version
-manager or a non-standard install location keeps the CLI off the `PATH` of the shell that
-started Akeru Bot.
+After sign-in, select **Check OAuth** to test the stored login. Use **Reconnect** after a revoked or
+expired login. Akeru cannot verify whether an xAI login includes SuperGrok or X Premium+.
-### When Auth Is Needed
+## What Akeru runs
-Provider auth is required before you start a session with that provider, not before you start
-Akeru Bot. You can install Akeru Bot, open it, and add providers afterwards. A provider that is not
-authenticated shows its status in **Settings** and fails at session start with the login command
-to run.
+Codex and Kimi use Akeru's custom Mastra-based runtime. Akeru supplies the workspace, memory,
+plugins, approval rules, and subscription access for each thread.
-For multi-account setups, see [Codex](./providers-codex.md) and [Claude](./providers-claude.md).
+Claude, Grok, and OpenCode use their provider adapters. These adapters keep provider-specific
+session and permission behavior behind the same Akeru thread interface.
-## Next Steps
+## Next steps
-- [Permission modes](./permission-modes.md): how much Akeru Bot asks before acting
-- [Remote access](./remote-access.md): connect from a phone, tablet, or another desktop
-- [Keeping Akeru Bot in sync](./updating.md): client and server version skew
-- [Running in the background](./background-service.md): Linux background service
+- [Configure bots](./bots.md)
+- [Choose a permission mode](./permission-modes.md)
+- [Connect another device](./remote-access.md)
+- [Use Codex](./providers-codex.md)
+- [Use Claude](./providers-claude.md)
diff --git a/docs/user/keybindings.md b/docs/user/keybindings.md
index eae9d6237..b22d0568c 100644
--- a/docs/user/keybindings.md
+++ b/docs/user/keybindings.md
@@ -1,12 +1,11 @@
-# Keybindings
+# Keyboard shortcuts
-Edit keybindings from **Settings** → **Keybindings**. That page lists every command, its current
+Edit shortcuts from **Settings > Keybindings**. The page lists every command, its current
shortcut, whether it is a default or your own, and warns about conflicts.
The same configuration lives in `~/.akeru/userdata/keybindings.json` on the machine running the
-server, if you prefer editing it directly. Akeru Bot writes the built-in defaults into that file on
-first run, and adds any new defaults on later startups unless a rule of yours already claims the
-command or the shortcut.
+server. Akeru merges your rules with the built-in defaults. It keeps a default when no custom rule
+claims that command. An absent or empty file therefore still resolves to the built-in shortcuts.
The file is a JSON array of rules.
@@ -19,13 +18,13 @@ The file is a JSON array of rules.
Invalid rules are ignored. An invalid file is ignored entirely, and the server logs a warning.
-## Rule Shape
+## Rule shape
- `key` (required): shortcut string, like `mod+j`, `ctrl+k`, `cmd+shift+d`
- `command` (required): the command ID to run
- `when` (optional): boolean expression controlling when the shortcut is active
-## Key Syntax
+## Key syntax
Modifiers: `mod` (`cmd` on macOS, `ctrl` elsewhere), `cmd` / `meta`, `ctrl` / `control`, `shift`,
`alt` / `option`.
@@ -50,7 +49,7 @@ successful pick; its hover glow and badge preview the element and color family t
**Cancel** or `Escape` exits Inspect and clears its selection and spotlight.
`rightPanel.toggleMaximized` maximizes or restores the open right panel. It has no default shortcut,
-so add one in **Settings** → **Keybindings** if you want to use it.
+so add one in **Settings > Keybindings** if you want to use it.
`thread.settle` settles the active thread or restores it when it is already settled. Its default
shortcut is `mod+shift+s`, and it does not run while the terminal has focus.
@@ -60,7 +59,7 @@ agent responses across connected environments. Message matches show one labeled
keeping the thread's project, branch, and machine context visible. Message search begins after two
characters and uses SQLite's ASCII case-insensitive matching.
-The full command list and the current defaults are shown in **Settings** → **Keybindings**, which
+The full command list and the current defaults are shown in **Settings > Keybindings**, which
always matches the build you are running. Use that rather than a copied list.
Note that `chat.new` and `chat.newLocal` both create a thread through the same path. A new thread
@@ -74,7 +73,7 @@ Background submission from a new thread is the exception. `mod+enter` starts tha
another new thread with the same workspace mode and base branch. **New worktree** remains selected,
but the new thread does not reuse the worktree created for the thread that just started.
-## `when` Conditions
+## `when` conditions
A `when` expression is evaluated against context keys describing the current UI state. The keys
the app supplies today are `terminalFocus`, `terminalOpen`, `previewFocus`, `previewOpen`, and
diff --git a/docs/user/mobile-appearance.md b/docs/user/mobile-appearance.md
index 60bed54c3..a357378c6 100644
--- a/docs/user/mobile-appearance.md
+++ b/docs/user/mobile-appearance.md
@@ -1,15 +1,17 @@
# Mobile appearance
-Akeru Bot Mobile includes the Akeru Bot, Akeru Paper, Akeru Chat, Grove, Ocean, Ember, and Iris themes.
-Each theme has light and dark colors that apply throughout the app, including code reviews, file
-previews, the terminal, native headers, and sheets.
+Akeru Mobile includes these themes:
-To change themes:
+- Akeru Classic
+- Akeru Paper
+- Akeru Chat
+- Grove
+- Ocean
+- Ember
+- Iris
-1. Open **Settings**.
-2. Select **Appearance**.
-3. Choose a theme.
-4. Select **System**, **Light**, or **Dark**.
+Open **Settings > Appearance**. Choose separate themes for light and dark appearance, or apply one
+theme to both. Then select **System**, **Light**, or **Dark** for the device mode.
-**System** follows the device appearance automatically. Theme, text, code, and terminal appearance
-preferences are stored on the device.
+**System** follows the device appearance. Theme, text, code, and terminal preferences stay on that
+device.
diff --git a/docs/user/permission-modes.md b/docs/user/permission-modes.md
index f131bda7b..b3399ac04 100644
--- a/docs/user/permission-modes.md
+++ b/docs/user/permission-modes.md
@@ -1,50 +1,39 @@
-# Permission Modes
+# Permission modes
-A permission mode controls how much the agent does on its own and when it stops to ask you.
+A permission mode controls which actions an agent can take before it must ask you.
-The mode is set per thread, from the mode control in the message composer. Changing it in one
-thread does not change any other thread. A thread created from inside another thread keeps that
-thread's mode. Otherwise, new threads use **Settings > General > Local execution** and ask before
-local file changes and shell commands by default.
+Set the mode per thread from the message composer. A child thread keeps its parent thread's mode.
+Other new threads use **Settings > General > Local execution** and ask before local file changes and
+shell commands by default.
-## The Modes
+## The modes
-**Supervised**: ask before commands and file changes. The agent pauses and shows you what it
-wants to run or edit, and waits for approval. Work outside the workspace is restricted.
+**Supervised** asks before commands and file changes. Work outside the workspace stays restricted.
-**Auto-accept edits**: auto-approve edits, ask before other actions. File changes go through
-without prompting; commands and anything else still stop for approval.
+**Auto-accept edits** allows file edits and asks before commands and other actions.
-**Auto**: routine actions proceed without you; risky ones still ask. How this is enforced depends
-on the provider: Codex delegates routine approvals to an AI reviewer, Claude uses its own auto
-permission mode, and providers without an equivalent (such as OpenCode) fall back to asking, like
-Supervised.
+**Auto** allows routine actions and asks before risky ones. Each provider maps this mode to its own
+permission system. A provider without an equivalent can fall back to supervised behavior.
-**Full access**: allow commands and edits without local prompts. The agent runs unattended until
-it finishes or asks a question of its own. Actions that send, pay, delete, change production, or
-use secrets still ask.
+**Full access** allows routine commands and edits without local prompts. The agent still asks its own
+questions and still stops at protected actions.
-Approvals appear inline in the conversation. Approve or reject one and the agent continues from
-there. The Codex runtime still asks before every MCP tool call and actions that send, pay, delete,
-deploy, publish, expose secrets, sign, refund, or change an account. This applies in every mode.
-Each approval applies only to the pending action.
+## Protected actions
-## Choosing a Mode
+Akeru's Codex and Kimi runtime always asks before an action that sends data, pays, deletes, changes
+production, publishes, exposes secrets, signs, refunds, or changes an account. Unknown mutating
+actions also ask. Each approval applies only to the pending action.
-Use **Full access** for work in a worktree or a sandbox you can throw away.
+Installed MCP tools ask unless the server marks the tool read-only. Provider adapters can add their
+own approval rules.
-Use **Supervised** on a repository where an unwanted command is expensive, or the first time you
-run an unfamiliar task.
+## Choose a mode
-**Auto-accept edits** suits refactors where the edits are the point and you only care about the
-shell commands.
+Use **Supervised** for an unfamiliar task or a repository where an unwanted command is expensive.
-## Provider Behavior
+Use **Auto-accept edits** when you want the refactor but still want to inspect shell commands.
-Each provider maps these modes onto its own approval and sandbox settings. Codex, for example,
-translates the mode into its approval policy and sandbox level, so **Supervised** runs the CLI
-with prompting enabled and a restricted workspace while **Full access** disables both. The
-protected-action gate still applies after this provider mapping. The exact per-provider translation
-is internal and may change.
+Use **Full access** for a worktree or sandbox that you can restore. Check the workspace and Git diff
+after the agent finishes.
-Mobile offers the same four modes with the same labels and descriptions.
+Web, desktop, and mobile use the same four labels.
diff --git a/docs/user/plugins.md b/docs/user/plugins.md
index 929db040b..2e900a03e 100644
--- a/docs/user/plugins.md
+++ b/docs/user/plugins.md
@@ -1,22 +1,47 @@
# Plugins
-Open **Plugins** from the sidebar or command palette. Use **All**, **Featured**, **Installed**, or one of the eight categories. Search checks the plugin name, title, description, category, tags, capabilities, and publisher name.
+Open **Plugins** from the sidebar or command palette. Filter by **All**, **Featured**, **Installed**,
+or category. Search checks the plugin name, title, description, category, tags, capabilities, and
+publisher.
-Select a plugin to review its publisher, authentication, hosted or local execution, transport, platform support, permissions, approval classes, setup, documentation, source, and active dependent bots. A routine can require an enabled connector. Health shows **Not checked** until Akeru completes a real request. An enabled plugin does not imply a healthy connection.
+## Review a plugin
-The available action matches the current state:
+Select a plugin to inspect its publisher, authentication, execution location, transport, supported
+platforms, permissions, approval classes, setup, documentation, source, and dependent bots.
+
+Health stays **Not checked** until a real request succeeds. An enabled plugin is not proof that its
+connection works. A routine can require an enabled connector.
+
+## Plugin actions
- **Add** installs a public or local plugin.
-- **Connect** starts an OAuth connection.
-- **Add key** installs a plugin whose key stays in the host environment.
-- **Disable** stops an enabled plugin without deleting its registration.
-- **Reconnect** refreshes and enables a disabled plugin.
-- **Remove** deletes the plugin registration.
+- **Connect** starts OAuth.
+- **Add key** stores a required key in the host environment.
+- **Disable** stops the plugin without deleting it.
+- **Reconnect** repairs and enables a disabled plugin.
+- **Remove** deletes the registration.
+
+A plugin waiting for publisher approval stays visible, but **Connect** remains disabled. A plugin
+removed from the public directory stays under **Installed** until you remove it.
+
+## Enable tools for a bot
+
+Akeru enables a new plugin for every bot by default. Open the bot's **Tools** setting to disable it
+for that bot. Changing the bot's provider starts a fresh provider session with the same enabled tools.
+
+## Custom MCP servers
+
+Use **Add server** under **Custom MCP servers** when a connector is not in the directory. Installed
+servers can be edited, disabled, or removed from the same section.
-Approval-pending plugins remain visible, but Akeru disables **Connect** and shows the vendor blocker. Plugins removed from the directory remain under **Installed** until you remove them.
+Akeru does not store plugin credentials in the public directory or MCP registry. Keep credentials in
+the environment server or the service's sign-in flow.
-Codex Computer Use runs only on the local Mac. It does not use a hosted desktop or remote-control service. When a Codex bot starts control, macOS requests Screen Recording and Accessibility access if the helper does not have them. Akeru allows one controlling bot at a time and shows its name in the sidebar. **Stop** ends that session. **Revoke** ends it and disables Computer Use for every bot. Akeru keeps screenshots, typed text, window titles, and application content out of stored runtime events.
+## Codex Computer Use
-Akeru enables each installed plugin for every bot by default. Use a bot's **Plugins** setting to disable it for that bot. A provider change starts a fresh provider session with the same enabled plugins.
+Codex Computer Use runs only on the local Mac. It does not use a hosted desktop. macOS requests
+Screen Recording and Accessibility access when the helper needs them.
-Ask the agent to add a Custom MCP server when a connector is not in the directory. Existing Custom MCP servers remain under **Installed**, where you can edit, disable, or delete them. Akeru stores no plugin credentials in the directory or MCP registry. Keep credentials in the host environment or the service sign-in flow.
+Only one bot can control the Mac at a time. **Stop** ends the current session. **Revoke** ends it and
+disables Computer Use for every bot. Akeru excludes screenshots, typed text, window titles, and app
+content from stored runtime events.
diff --git a/docs/user/privacy.md b/docs/user/privacy.md
index dd7066991..d00f8ea71 100644
--- a/docs/user/privacy.md
+++ b/docs/user/privacy.md
@@ -1,26 +1,32 @@
# Privacy and outbound data
-Akeru Bot stores threads, settings, secrets, and logs on your device under `~/.akeru`. It does not
-require a hosted Akeru account.
-
-Some features send data to services outside your device:
-
-- Provider runs send prompts, selected files, tool results, screenshots, computer frames, and
- conversation context to the provider CLI or service you choose. The provider controls its own
- processing and retention.
-- Product feedback goes to `feedback.akeru.bot`. The service may keep submissions for up to 90
- days.
-- Voice calls send microphone audio and session data to the ChatGPT Realtime service while a call
- is active.
-- Provider update checks contact the release sources for your configured providers. Signed desktop
- builds contact the configured release host for Akeru Bot updates.
-- Anonymous analytics use PostHog only when you turn analytics on and the distributor configures a
- PostHog key. Events include the app version, platform, architecture, client type, feature use,
- and a random installation identifier. They do not use a provider account identifier.
-
-Open Settings, then Privacy, to control analytics, product feedback, voice calls, and provider
-update checks. Analytics starts off. Mobile shows the same controls in the Privacy section for the
-connected environment.
-
-The published Terms of Use and Privacy Policy pages are drafts. Akeru Bot must not ship a signed
-release until qualified legal counsel approves them.
+Akeru stores environment data under `~/.akeru` by default. This includes projects, threads, bot
+profiles, settings, secrets, logs, local memory, and cached provider data. A worktree development
+server uses that worktree's `.akeru` directory instead.
+
+## Data that can leave the environment
+
+- Agent requests send the prompt, selected files, tool results, and conversation context to the
+ provider that you select. That provider controls its processing and retention.
+- Product feedback sends the text and an optional safe interface descriptor to
+ `feedback.akeru.bot`. The service can retain accepted feedback for up to 90 days.
+- Voice calls send microphone audio and call state to the ChatGPT Realtime service while a call is
+ active.
+- Provider update checks contact the release source for configured providers. Signed desktop builds
+ contact the configured Akeru release host.
+- Anonymous analytics send fixed aggregate counters and app, platform, architecture, and client
+ dimensions when analytics is on.
+
+## Subscription credentials
+
+The environment server stores subscription credentials in its private secrets directory. OAuth
+tokens do not pass through the WebSocket contract and do not enter projects, checkpoints, sandboxes,
+or client storage. A run receives only the short-lived access that it needs.
+
+## Privacy controls
+
+Open **Settings > Privacy** to control anonymous analytics, product feedback, voice calls, and
+provider update checks. Mobile exposes the same controls for the connected environment.
+
+Turning a control off stops new transfers for that feature. Provider requests still leave the
+environment when you run a connected online model.
diff --git a/docs/user/product-feedback.md b/docs/user/product-feedback.md
index 32d4c5a09..dbb14f2d3 100644
--- a/docs/user/product-feedback.md
+++ b/docs/user/product-feedback.md
@@ -1,16 +1,28 @@
# Product feedback
-Open **Feedback** from the sidebar or command palette. You can also select **Send feedback** in **Settings → About**. Desktop builds include **Help → Send Feedback**.
+Open **Feedback** from the sidebar or command palette. You can also select **Send feedback** under
+**Settings > About**. Desktop builds include **Help > Send Feedback**.
-Write the feedback and select **Send**. Select **Choose an element** to attach a privacy-safe reference to part of the Akeru Bot interface. The picker does not collect form values, page HTML, screenshots, files, workspace paths, or full URLs.
+Write up to 4,000 characters and select **Send**. Select **Choose an element** to attach a safe
+description of one interface element.
-A submission contains:
+## What Akeru sends
-- Feedback text, up to 4,000 characters.
-- An optional interface element descriptor.
+A submission contains the feedback text and, when selected, one interface element descriptor. It
+does not contain a screenshot, raw page content, input value, credential, tool result, workspace
+path, full URL, thread, or conversation.
-It does not contain screenshots, raw DOM, input values, credentials, tool results, a thread, or a full conversation. No account is required. A failed send keeps the draft. A confirmed send clears it.
+A failed send keeps the draft. A confirmed send clears it. No account is required. The service can
+keep accepted feedback for up to 90 days.
-Akeru Bot keeps accepted feedback for 90 days. Turn off **Product feedback** in **Settings → Privacy** to disable sending. Self-hosted environments can set an HTTPS endpoint in **Settings → About**. Loopback HTTP endpoints are allowed for local testing.
+Turn off **Product feedback** under **Settings > Privacy** to disable sending. A self-hosted
+environment can set an HTTPS endpoint under **Settings > About**. Loopback HTTP is allowed for local
+testing.
-Codex-backed Akeru bots can propose feedback text. A proposal can only add bounded text to the same editable draft after one-time approval. The bot cannot send it. You must select **Send** for each submission. Review agent proposals on web or desktop. Mobile can cancel them but cannot open the draft in this version.
+## Bot-proposed feedback
+
+A Codex-backed Akeru bot can propose text for the same feedback draft after one-time approval. The
+bot cannot submit it. Review the draft and select **Send** yourself.
+
+Web and desktop can open the proposed draft. Mobile can decline the approval but cannot open the
+draft in this version.
diff --git a/docs/user/project-settings.md b/docs/user/project-settings.md
index 1a9d03afe..d4ffbcdcc 100644
--- a/docs/user/project-settings.md
+++ b/docs/user/project-settings.md
@@ -1,16 +1,17 @@
# Customize a project icon
-Akeru Bot selects a project icon automatically. It checks `t3.json`, common favicon and app icon
-paths, and icon links in project HTML files.
+Akeru finds a project icon from `t3.json`, common favicon and app-icon paths, and icon links in HTML
+files.
-To choose a different icon:
+To choose another file:
-1. Open **Settings** and select **Projects**.
+1. Open **Settings > Projects**.
2. Select the project.
-3. Under **Appearance**, select **Choose a project file**.
-4. Search for an image file and select it.
+3. Open the **Project** section.
+4. Select **Choose file**.
+5. Search for an image and select it.
-Akeru Bot supports SVG, PNG, ICO, JPEG, GIF, AVIF, and WebP files. The selected path applies to
-each checkout in the project group and appears on your connected clients.
+Akeru supports SVG, PNG, ICO, JPEG, GIF, AVIF, and WebP. The selected path applies to every checkout
+in the project group and appears on connected clients.
-To use automatic detection again, select **Automatic**.
+Use the reset button beside the icon to return to automatic detection.
diff --git a/docs/user/providers-claude.md b/docs/user/providers-claude.md
index 3fae09757..260db29f0 100644
--- a/docs/user/providers-claude.md
+++ b/docs/user/providers-claude.md
@@ -1,229 +1,44 @@
# Claude
-This guide is for people who want to use more than one Claude setup in Akeru Bot. For Codex, see
-[Codex](./providers-codex.md). For first-time setup, see [Install Akeru Bot](./install.md).
+Connect a Claude Pro or Max subscription from Akeru. Claude threads run through Akeru's Claude
+adapter, which keeps Claude-specific session behavior behind the same thread controls as other
+providers.
-Common reasons:
+## Connect Claude
-- use separate work and personal Claude accounts
-- try a different Claude Code configuration without disturbing your main setup
-- run Claude through a router such as Claude Code Router
-- use external providers exposed through a Claude-compatible workflow
+1. Open **Settings > Providers**.
+2. Find **Claude** and select **Connect**.
+3. Finish the Anthropic sign-in flow in the browser.
+4. Copy the authorization code from Anthropic.
+5. Paste the code into Akeru and select **Connect**.
-## I Only Use One Claude Account
+The environment server completes the exchange and stores the credential. No inbound callback to the
+Akeru server is required, so this flow also works from a remote browser or mobile client.
-Use the default provider.
+## Check the connection
-Log in with Claude Code normally:
+The provider card reports the current state. A connected account can still show **Detected** until a
+real provider request succeeds.
-```bash
-claude auth login
-```
+- Select **Check OAuth** to test the stored login.
+- Select **Reconnect** after an expired or revoked login.
+- Disconnect the account to remove its stored credential from this environment.
-In Akeru Bot Settings, your Claude provider can stay like this:
+Sign-in state belongs to one environment. Connect Claude again on each separate Akeru server that
+should use the account.
-```text
-Display name: Claude
-Binary path: claude
-CLAUDE_CONFIG_DIR path: empty
-```
+## Continue a Claude thread
-An empty `CLAUDE_CONFIG_DIR path` means Akeru Bot uses Claude Code's normal config directory.
+Akeru keeps Claude's provider-specific session identity when a thread continues. Changing to an
+incompatible provider starts a new provider session instead of reusing Claude's resume state.
-When you set this field, Akeru Bot points Claude Code at that directory with the
-`CLAUDE_CONFIG_DIR` environment variable. It does not change `HOME`, so your system keychain and
-the rest of your environment stay as they are.
+Installed plugins and MCP servers stay attached to the Akeru thread. A provider change restarts the
+provider session with the same enabled plugin set.
-## Reduce Context Usage
+## Permissions
-In Settings, open your Claude provider and set **Auto-compact after** to a token count between
-`100000` and `1000000`. For example, `300000` compacts the conversation into a summary once it
-reaches about 300,000 tokens, without changing the model's context window. Leave the field
-empty to keep Claude Code's default behavior.
+Claude maps Akeru's thread mode to its own permission behavior. Protected actions still ask even when
+the thread uses **Full access**.
-On web and desktop, when you return to an older Claude thread with a large context, Akeru Bot
-offers to compact the conversation before you continue. You can also select **Compact context**
-from the context meter. On every client, you can enter `/compact` in the message composer, and
-Claude can show its own resume prompt when you continue an old session.
-
-## Where Claude Skills Are Loaded
-
-Akeru Bot looks for Claude skills in the Claude config directory's `skills` folder, then
-`<workspace>/.agents/skills`, then `<workspace>/.claude/skills`.
-
-If the same skill name exists in more than one folder, the later folder wins.
-
-## I Want Work And Personal Claude Accounts
-
-Use a different Claude config directory for each account.
-
-Example:
-
-```text
-default config dir work account
-~/.claude_personal_home personal account
-```
-
-### Set Up The First Account
-
-Log in normally:
-
-```bash
-claude auth login
-```
-
-In Akeru Bot Settings:
-
-```text
-Display name: Claude Work
-Binary path: claude
-CLAUDE_CONFIG_DIR path: empty
-```
-
-### Set Up The Second Account
-
-Log in with a separate config directory:
-
-```bash
-mkdir -p ~/.claude_personal_home
-CLAUDE_CONFIG_DIR=~/.claude_personal_home claude auth login
-```
-
-Use `CLAUDE_CONFIG_DIR`, not `HOME`. Setting `HOME` writes the login to
-`~/.claude_personal_home/.claude`, which is not where Akeru Bot looks.
-
-Then add another Claude provider in Akeru Bot:
-
-```text
-Display name: Claude Personal
-Binary path: claude
-CLAUDE_CONFIG_DIR path: ~/.claude_personal_home
-```
-
-Use the email shown in Settings to confirm each provider is using the intended account. Emails are
-blurred by default; click the blurred email to reveal it.
-
-## Can I Switch Claude Accounts In An Existing Thread?
-
-Usually, no.
-
-Akeru Bot only offers Claude providers that use the same config directory for an existing thread. A
-different config directory is treated as a different Claude environment.
-
-This is different from the recommended Codex setup. Claude Code keeps account and local state across
-multiple files under its config directory, so Akeru Bot keeps separate config directories isolated
-instead of trying to share part of the state.
-
-## I Want To Use OpenRouter
-
-Use this when you want Claude Code to talk to OpenRouter directly, without running a local router.
-This is the simplest external-provider setup.
-
-OpenRouter provides a Claude Code integration through Claude's Anthropic-compatible environment
-variables.
-
-### Configure A Claude OpenRouter Provider
-
-Add or edit a Claude provider in Akeru Bot Settings:
-
-```text
-Display name: Claude OpenRouter
-Binary path: claude
-CLAUDE_CONFIG_DIR path: ~/.claude_openrouter_home
-```
-
-In that provider's Environment variables section, add:
-
-```text
-ANTHROPIC_BASE_URL https://openrouter.ai/api
-ANTHROPIC_AUTH_TOKEN sk-or-... Sensitive
-ANTHROPIC_API_KEY Empty value
-```
-
-Mark `ANTHROPIC_AUTH_TOKEN` as sensitive. Akeru Bot stores the value as a server secret and does not
-send it back to the app after saving.
-
-If you want this setup isolated from your normal Claude account, create that home first:
-
-```bash
-mkdir -p ~/.claude_openrouter_home
-```
-
-If you previously used the same Claude home with a normal Anthropic login, run `/logout` in a Claude
-Code session for that home before using OpenRouter. Otherwise Claude Code may keep using cached
-Anthropic credentials instead of the OpenRouter token.
-
-### Pick OpenRouter Models
-
-OpenRouter can route Claude Code's default model roles to OpenRouter model IDs.
-
-Example:
-
-```text
-ANTHROPIC_DEFAULT_OPUS_MODEL anthropic/claude-opus-4.6
-ANTHROPIC_DEFAULT_SONNET_MODEL anthropic/claude-sonnet-4.6
-ANTHROPIC_DEFAULT_HAIKU_MODEL anthropic/claude-haiku-4.5
-CLAUDE_CODE_SUBAGENT_MODEL anthropic/claude-sonnet-4.6
-```
-
-Add those to the same provider's Environment variables section if you want stable model choices.
-
-### Verify OpenRouter Is Being Used
-
-Open a Claude session and run:
-
-```text
-/status
-```
-
-You should see the Anthropic base URL set to:
-
-```text
-https://openrouter.ai/api
-```
-
-You can also check the OpenRouter activity dashboard for requests from your API key.
-
-### Common OpenRouter Mistakes
-
-- Use `https://openrouter.ai/api`, not `https://openrouter.ai/api/v1`, for Claude Code.
-- Set `ANTHROPIC_AUTH_TOKEN` to your OpenRouter API key.
-- Set `ANTHROPIC_API_KEY` to an empty string so Claude Code does not try to use an Anthropic login.
-- Put these variables on the Claude provider instance, not in global shell startup files.
-
-OpenRouter's setup can change over time. Use its upstream Claude Code guide for the current details:
-<https://openrouter.ai/docs/guides/guides/claude-code-integration>.
-
-## I Want To Use Claude Code Router
-
-Claude Code Router is useful when you want a local routing layer with more control than a direct
-OpenRouter setup.
-
-Akeru Bot does not need a special Claude Code Router provider. Treat the router as a Claude
-environment: give a Claude provider its own `CLAUDE_CONFIG_DIR path`, and put whatever variables
-the router tells you to export into that provider's Environment variables section. Mark tokens
-and API keys as sensitive.
-
-```text
-Display name: Claude Router
-Binary path: claude
-CLAUDE_CONFIG_DIR path: ~/.claude_router_home
-```
-
-Follow the upstream project's README for the router's own install, startup, and configuration
-steps: <https://github.com/musistudio/claude-code-router>.
-
-## I Want Different Claude Settings, Not A Different Account
-
-Create another Claude provider with the same account if you want a named preset.
-
-Examples:
-
-- "Claude Default"
-- "Claude Router"
-- "Claude Experimental"
-
-If the preset needs different Claude files, give it a different `CLAUDE_CONFIG_DIR path`. If it needs
-different API keys, base URLs, or router settings, use Environment variables.
-
-Do not put environment variable assignments in `Launch arguments`.
+See [Permission modes](./permission-modes.md) for the four modes and the actions that always need
+approval.
diff --git a/docs/user/providers-codex.md b/docs/user/providers-codex.md
index 3755c1ea4..7b2bbdffa 100644
--- a/docs/user/providers-codex.md
+++ b/docs/user/providers-codex.md
@@ -1,153 +1,53 @@
# Codex
-This guide is for people who want to use more than one Codex account in Akeru Bot. For Claude, see
-[Claude](./providers-claude.md). For first-time setup, see [Install Akeru Bot](./install.md).
+Akeru runs Codex models through its built-in Mastra-based runtime. Connect a ChatGPT subscription in
+Akeru. You do not need the Codex CLI for Akeru bot turns.
-Common reasons:
+## Connect ChatGPT
-- use a work account for work projects
-- use a personal account for personal projects
-- switch to another account when one account hits limits
-- keep one shared Codex history instead of maintaining two separate Codex setups
+1. Open **Settings > Providers**.
+2. Find **ChatGPT** and select **Connect**.
+3. Open the sign-in page and enter the displayed device code.
+4. Approve access with the ChatGPT account that this environment should use.
+5. Return to Akeru and wait for the account status to update.
-## I Only Use One Codex Account
+Akeru supports ChatGPT Plus, Pro, Business, Enterprise, and Edu. Select **Check OAuth** to test the
+stored login. Use **Reconnect** after an expired or revoked login.
-Use the default provider.
+## How Codex runs
-In Settings, your Codex provider can stay like this:
+Akeru creates and controls the Codex session. The runtime supplies:
-```text
-Display name: Codex
-CODEX_HOME path: ~/.codex
-Shadow home path: empty
-```
+- the bot's local or remote workspace
+- installed plugins and MCP tools
+- Akeru memory and bot tools
+- the selected permission mode
+- the selected ChatGPT subscription model
-Log in with Codex normally:
+Akeru normalizes tool calls, approvals, usage, messages, and errors before it sends them to the
+client. This keeps the same thread controls available on web, desktop, and mobile.
-```bash
-codex login
-```
+The environment server stores the subscription credential under its private secrets directory. It
+passes short-lived access to the runtime when needed. The credential does not enter the project,
+thread history, checkpoints, or client storage.
-## Send feedback to OpenAI
+## Protected actions
-In an existing Codex thread, send `/feedback` or `/feedback` followed by a description of the
-issue. Akeru Bot uploads the thread and Codex logs to OpenAI and shows a thread ID that you can copy
-and share with OpenAI employees.
+The runtime can allow routine reads and edits based on the thread's permission mode. It still asks
+before an action that sends data, pays, deletes, changes production, publishes, exposes secrets,
+signs, refunds, or changes an account. An approval applies only to the pending action.
-## Approve access to other apps
+See [Permission modes](./permission-modes.md) for the complete mode behavior.
-When a Codex tool needs access to an app such as Safari, Akeru Bot shows the app name and asks for
-approval. You can approve, decline, or cancel the request from the desktop app, web app, or mobile
-app. Some tools also offer approval for the current session or permanent approval.
+## Fix sign-in problems
-## I Want Work And Personal Codex Accounts
+If Codex cannot start:
-Use one real Codex home and one shadow home.
+1. Open **Settings > Providers**.
+2. Check the ChatGPT status.
+3. Select **Check OAuth**.
+4. Select **Reconnect** if the check fails.
+5. Confirm that the account has a supported ChatGPT plan.
-Recommended setup:
-
-```text
-~/.codex shared Codex home
-~/.codex_p second account auth
-```
-
-The idea is:
-
-- both accounts can see the same Akeru Bot/Codex sessions
-- each account keeps its own login
-- existing threads can continue with either account
-
-### Set Up The First Account
-
-Log in normally:
-
-```bash
-codex login
-```
-
-This is the account used by `~/.codex`.
-
-In Akeru Bot Settings, name it something obvious:
-
-```text
-Display name: Codex Work
-CODEX_HOME path: ~/.codex
-Shadow home path: empty
-```
-
-### Set Up The Second Account
-
-Log in with a separate Codex home:
-
-```bash
-mkdir -p ~/.codex_p
-CODEX_HOME=~/.codex_p codex login
-```
-
-In Akeru Bot Settings, add another Codex provider:
-
-```text
-Display name: Codex Personal
-CODEX_HOME path: ~/.codex
-Shadow home path: ~/.codex_p
-```
-
-The important part is that both providers use the same `CODEX_HOME path`, but only the second one
-has a `Shadow home path`.
-
-## Which Account Am I Using?
-
-Open Settings and look at the provider row.
-
-Akeru Bot shows the authenticated email for providers that report one. Emails are blurred by default;
-click the blurred email to reveal it.
-
-Use display names and accent colors to make accounts easy to tell apart in the model picker.
-
-## I Need A Different API Key Or Endpoint
-
-Use the provider's Environment variables section in Settings.
-
-This is useful when a Codex-compatible setup needs account-specific variables. Add the variables to
-the provider instance that should receive them, and mark API keys or tokens as sensitive. Sensitive
-values are stored as server secrets and are not sent back to the app after saving.
-
-## Can I Switch Accounts In An Existing Thread?
-
-Yes, when both Codex providers share the same `CODEX_HOME path`.
-
-For example:
-
-```text
-Codex Work CODEX_HOME path: ~/.codex
-Codex Personal CODEX_HOME path: ~/.codex, Shadow home path: ~/.codex_p
-```
-
-Those two providers are considered compatible for continuation, so the locked model picker can show
-both.
-
-If you add a third Codex provider with a completely different `CODEX_HOME path`, Akeru Bot treats it
-as a different workspace. It will not be offered for existing threads created under `~/.codex`.
-
-## If Both Accounts Look The Same
-
-If two Codex providers show the same account or the same unexpected model list:
-
-1. Check the email in Settings.
-2. Refresh provider status.
-3. Confirm the second provider has `Shadow home path` set.
-4. Confirm the shadow directory has its own `auth.json`.
-5. If you copied `~/.codex` into the shadow directory, remove everything except `auth.json`.
-
-Example cleanup:
-
-```bash
-find ~/.codex_p -mindepth 1 ! -name auth.json -exec rm -rf {} +
-```
-
-## When To Use A Separate CODEX_HOME
-
-Use a totally separate `CODEX_HOME path` only when you want a separate Codex workspace.
-
-That means separate sessions and less account switching inside old threads. Most dual-account users
-should use the shared-home plus shadow-home setup instead.
+Repeat these steps on the environment that owns the project. Signing in on another Akeru server does
+not connect this one.
diff --git a/docs/user/remote-access.md b/docs/user/remote-access.md
index b9b091fc7..5329d3ede 100644
--- a/docs/user/remote-access.md
+++ b/docs/user/remote-access.md
@@ -1,7 +1,6 @@
# Remote access
-Use remote access to connect a phone, tablet, browser, or desktop app to an Akeru Bot server that you
-control.
+Connect a phone, tablet, browser, or desktop app directly to an Akeru server that you control.
## Pair with a running server
@@ -11,8 +10,8 @@ Run this on the server machine:
npx akeru-bot pair
```
-The command finds the running server, creates a one-time pairing credential, and prints a URL and QR
-code. The other device must be able to reach the address in that URL.
+The command finds the server and prints a one-time pairing URL and QR code. The other device must be
+able to reach the address in that URL.
For Tailscale HTTPS, run:
@@ -20,93 +19,83 @@ For Tailscale HTTPS, run:
npx akeru-bot pair --tailscale
```
-This configures Tailscale Serve when needed and prints a pairing URL for the machine's HTTPS
-MagicDNS address.
+Akeru configures Tailscale Serve when needed and prints a link for the machine's HTTPS MagicDNS
+address.
-Treat a pairing URL like a password. The credential expires and ordinary pairing links work once.
+Treat a pairing link like a password. The default command creates a link that expires and works once.
-## Desktop network access
+## Create a link from the desktop app
-1. Open **Settings** and select **Connections**.
-2. Enable **Network access** under **This environment**.
-3. Select a reachable LAN, Tailscale, or custom HTTPS endpoint.
-4. Select **Create Link**.
+1. Open **Settings > Connections**.
+2. Under **This environment**, choose a reachable LAN, Tailscale, or custom HTTPS endpoint.
+3. Set the endpoint as the default when needed.
+4. Select **Create link**.
5. Open the link on the other device.
-A loopback address works only on the same machine. A LAN address requires both devices to reach the
-same network. A browser loaded over HTTPS can connect only to an HTTPS and WSS server.
+A loopback address works only on the server machine. A LAN address requires both devices to reach
+the same network. A browser loaded over HTTPS can connect only to an HTTPS and WSS endpoint.
-The client connects directly to the address in the link. Akeru Bot does not proxy the connection
-through a hosted service.
+The client connects to the selected endpoint. Akeru does not proxy the session through a hosted
+service.
-## Headless server
+## Run a headless server
-Run a server without the desktop app:
+Bind the server to the machine's Tailscale address:
```bash
npx akeru-bot serve --host "$(tailscale ip -4)"
```
-The command prints the server address, pairing credential, URL, and QR code.
-
-To let Akeru Bot configure Tailscale Serve, run:
+Or let Akeru configure Tailscale Serve:
```bash
npx akeru-bot serve --tailscale-serve
```
-Use `--tailscale-serve-port` to choose another HTTPS port. Use `akeru serve --help` for the full
-flag list.
+Use `--tailscale-serve-port` to select another HTTPS port. Run this for all server flags:
+
+```bash
+npx akeru-bot serve --help
+```
-## Desktop-managed SSH
+## Connect through SSH
-The desktop app can start or reuse a server on an SSH host.
+The desktop app can start or reuse an Akeru server on an SSH host.
-1. Open **Settings** and select **Connections**.
+1. Open **Settings > Connections**.
2. Select **Add environment**.
-3. Select the SSH flow.
+3. Select the SSH connection.
4. Enter a target such as `[email protected]`.
5. Confirm the launch.
The desktop app starts the remote server and opens a local port forward. The remote machine owns its
-projects, threads, files, terminals, git state, and provider sessions.
+projects, threads, files, terminals, Git state, subscriptions, and provider sessions.
-The SSH launcher requires a compatible Node.js version on the remote host:
-
-```text
-^22.16 || ^23.11 || >=24.10
-```
-
-Check the non-interactive shell if launch fails:
+The remote host needs Node.js `^22.16 || ^23.11 || >=24.10`. Check the non-interactive shell when
+startup fails:
```bash
ssh [email protected] 'sh -lc "command -v node && node --version"'
```
-Configure the remote version manager so that command prints a compatible Node.js version.
+Configure the remote version manager until that command prints a supported Node.js version.
-## Saved environments
+## Manage saved access
-After pairing, the client stores a bearer credential for that environment. It reconnects without
-reusing the original pairing URL.
+After pairing, the client stores a bearer credential for the environment. It reconnects without the
+original pairing link.
-Use `akeru auth` to inspect sessions, create another pairing link, or revoke access:
+Inspect sessions, create links, and revoke access from the command line:
```bash
npx akeru-bot auth --help
```
-Remove a saved environment from **Connections** on web or desktop, or **Environments** on mobile.
-This removes the local saved connection. Revoke the server session when the device should no longer
-have access.
-
-## Security notes
+Web and desktop show saved connections under **Connections**. Mobile shows them under
+**Environments**. Removing a saved connection deletes it from that client. Revoke the server session
+when the device must lose access.
-- Prefer a private network such as Tailscale.
-- Do not expose an HTTP server directly to the public internet.
-- Use HTTPS and WSS across untrusted networks.
-- Revoke links or sessions that you no longer trust.
-- Finish active work before updating a remote server because the server restarts.
+Prefer a private network such as Tailscale. Do not expose an HTTP server directly to the public
+internet. Use HTTPS and WSS across untrusted networks.
-See [background service](./background-service.md) for a Linux server that must remain available
-after logout.
+See [Running Akeru Bot in the background](./background-service.md) for an unattended server.
diff --git a/docs/user/sandboxes.md b/docs/user/sandboxes.md
index 3232bc228..7c5287420 100644
--- a/docs/user/sandboxes.md
+++ b/docs/user/sandboxes.md
@@ -1,11 +1,23 @@
# Configure sandboxes
-Open **Settings > Sandbox** to connect a remote sandbox provider. Akeru Bot supports E2B, Daytona, Vercel Sandbox, and Upstash Box. Local needs no credential and is always available.
+Open **Settings > Sandbox** to connect E2B, Daytona, Vercel Sandbox, or Upstash Box. Local workspaces
+need no credential and are always available.
-Select **Connect** and enter the provider credentials. The server stores secret values outside `settings.json`. A client receives only a redacted marker for each saved secret.
+Select **Connect** and enter the provider credentials. The environment stores secret values outside
+`settings.json`. Clients receive only a redacted marker after a secret is saved.
-Only connected providers appear in the default sandbox selector. Disconnecting the default provider changes the default to Local. Akeru pauses remote sandboxes when bots are idle and reconnects to the saved provider workspace when work resumes.
+## Choose the default
-The default applies when a bot has no sandbox override. A bot with an explicit sandbox keeps that choice. Connect that provider before you start the bot.
+Only connected services appear in the default sandbox selector. Disconnecting the current default
+changes the default to Local.
-Changing a provider credential replaces active sessions that use that connection. This prevents an existing session from continuing with an old account credential.
+The default applies to a bot without its own sandbox choice. A bot-specific choice stays in place,
+so connect that service before you start the bot.
+
+## Session behavior
+
+Akeru pauses remote sandboxes while bots are idle and reconnects to the saved provider workspace when
+work resumes.
+
+Changing a provider credential replaces active sessions that use the connection. A running session
+cannot continue with the old credential.
diff --git a/docs/user/source-control.md b/docs/user/source-control.md
index fd2cf3c28..9941d11c4 100644
--- a/docs/user/source-control.md
+++ b/docs/user/source-control.md
@@ -1,151 +1,117 @@
-# Source Control Integrations
+# Source control integrations
-Akeru Bot connects to your Git hosting provider so you can create pull requests, review code, and manage repositories without leaving the app.
+Akeru can clone and publish repositories, create and inspect change requests, and show review state
+beside the thread that owns the work.
-## Supported Providers
+## Supported hosts
-Akeru Bot works with the platforms your team already uses:
+| Host | Authentication | Change request name |
+| ------------ | ----------------------------------- | ------------------- |
+| GitHub | GitHub CLI | Pull request |
+| GitLab | GitLab CLI | Merge request |
+| Bitbucket | Access token or account API token | Pull request |
+| Azure DevOps | Azure CLI with the DevOps extension | Pull request |
-- **GitHub** – Pull requests, repository creation, and clone integration
-- **GitLab** – Merge requests, repository publishing, and hosted clones
-- **Bitbucket** – Pull request workflows (via API token authentication)
-- **Azure DevOps** – Pull request support for Microsoft-hosted repositories
+Git is required on the environment server for every local repository operation.
-## What You Can Do
+## Add a project from a remote
-### Start Projects from Anywhere
+1. Open the command palette with `Cmd/Ctrl+K`.
+2. Select **Add Project**.
+3. Choose a listed host or **Git URL**.
+4. Enter the repository name or full URL.
+5. Choose the destination directory.
-**Clone repositories directly**
+Akeru accepts host-specific names such as `owner/repo`, `group/project`,
+`workspace/repository`, or `project/repository`.
-- Open the Command Palette (`Cmd/Ctrl + K`) → **Add Project**
-- Choose **GitHub repository**, **GitLab repository**, **Bitbucket repository**, **Azure DevOps repository**, or paste any **Git URL**
-- Enter the repository path (`owner/repo`, `group/project`, `workspace/repository`, or `project/repository`) or a full Git URL, pick a destination, and start coding
+## Publish a local repository
-**Publish local projects to the cloud**
+Use **Publish Repository** on a local Git repository without a remote. Akeru creates the hosted
+repository, adds it as `origin`, and pushes the current branch.
-- Have a local Git repository without a remote?
-- Use the **Publish Repository** action to create a new hosted repository (GitHub, GitLab, Bitbucket, or Azure DevOps), add it as your origin remote, and push, in one flow
-- If the local repository has no commits yet, publishing creates the remote and wires it up but does not push. Make a commit, then push normally.
+If the repository has no commits, Akeru creates the remote and adds `origin` but does not push. Make
+the first commit, then push it.
-### Manage Code Reviews Without Context Switching
+## Work with change requests
-**Create pull requests while you work**
+Use the Git controls in the thread toolbar to push a branch and create a pull request or merge
+request. Akeru can draft a title and description from the branch commits.
-- Push a branch and create a pull request from the Git actions controls in the toolbar
-- Akeru Bot can suggest titles and descriptions based on your commits
-- Supports GitHub Pull Requests, GitLab Merge Requests, Bitbucket Pull Requests, and Azure DevOps Pull Requests
+The **Pull requests** page opens reviews in right-panel tabs. From a thread, you can open a linked
+review in the panel or in the system browser. Command-click on macOS, or Control-click on Windows and
+Linux, opens a sidebar change-request number in the browser.
-**Stay on top of open reviews**
+Akeru can check out another branch for local review. GitHub, GitLab, and Bitbucket also support
+editing change-request text and your own comments in place. Azure DevOps supports title and
+description edits, but its comments stay read-only in Akeru.
-- See if your current branch already has an open PR/MR
-- Open several reviews from the **Pull requests** page as tabs in the right panel
-- While working in a thread, open linked reviews in the same compact right-panel tabs without
- leaving the conversation
-- Open the review directly in your browser with one click
-- Command-click (Control-click on Windows and Linux) a pull request number in the sidebar to open it in your browser instead of in Akeru Bot
-- Check out a teammate's branch to review code locally
+## Configure authentication
-**Fix what you wrote, in place**
+Open **Settings > Source Control**. The page shows **Version Control** and **Source Control
+Providers**. Use the rescan icon after you install a CLI or change credentials. Its tooltip reads
+**Rescan Git and hosting integrations**.
-- Rewrite a pull request's title and description from the review itself, in Markdown, with a
- preview before you save
-- Rewrite your own comments the same way, wherever they are shown
-- Works on GitHub, GitLab, and Bitbucket. Azure DevOps takes a new title and description; its
- comments stay read-only here, as they already were
+Authentication belongs to the environment server. Run these commands on that machine.
-### Know Your Setup at a Glance
+### GitHub
-The **Source Control settings** page shows you exactly what's connected:
+Install GitHub CLI 2.81.0 or newer, then sign in:
-- ✅ Which providers are authenticated and ready
-- ⚠️ What's missing and how to fix it
-- 👤 Which account is signed in (when available)
-
-Run a quick **Rescan** after setting up a new machine or changing credentials.
-
-## Getting Started
-
-### For GitHub (Recommended for most users)
-
-1. Install the GitHub CLI (version 2.81.0 or newer) on the machine running Akeru Bot:
- ```bash
- brew install gh
- ```
-2. Sign in:
- ```bash
- gh auth login
- ```
-3. Open **Settings → Source Control** in Akeru Bot and verify GitHub shows as authenticated
-
-You can now clone, publish, and create pull requests.
+```bash
+brew install gh
+gh auth login
+```
-### For GitLab
+### GitLab
-1. Install the GitLab CLI:
- ```bash
- brew install glab
- ```
-2. Authenticate:
- ```bash
- glab auth login
- ```
-3. Check **Settings → Source Control** to confirm the connection
+Install and authenticate GitLab CLI:
-### For Bitbucket
+```bash
+brew install glab
+glab auth login
+```
-Bitbucket uses tokens instead of a CLI tool. Two options, both set as environment variables on the
-machine running Akeru Bot.
+### Bitbucket
-Recommended, a Bitbucket access token:
+Set a Bitbucket access token:
```bash
export T3CODE_BITBUCKET_ACCESS_TOKEN="your-access-token"
```
-Or an Atlassian account email plus API token, with read/write access to pull requests and
-repositories, plus read access to your user account (`read:user:bitbucket`, used to verify the
-connection):
+Or set an Atlassian account email and API token:
```bash
export T3CODE_BITBUCKET_EMAIL="[email protected]"
export T3CODE_BITBUCKET_API_TOKEN="your-token"
```
-If both are set, the access token wins. Restart Akeru Bot and verify the connection in **Source
-Control settings**.
-
-### For Azure DevOps
+The API token needs repository and pull-request read/write access plus `read:user:bitbucket`. The
+access token wins when both methods are set. Restart Akeru after you change these environment
+variables.
-1. Install Azure CLI:
- ```bash
- brew install azure-cli
- ```
-2. Add the DevOps extension:
- ```bash
- az extension add --name azure-devops
- ```
-3. Sign in:
- ```bash
- az login
- ```
+### Azure DevOps
----
+Install Azure CLI and its DevOps extension:
-## Requirements & Troubleshooting
-
-**Git is required** – Akeru Bot uses Git for all local operations. Ensure `git` is installed on your server.
+```bash
+brew install azure-cli
+az extension add --name azure-devops
+az login
+```
-**Server-side setup** – Authentication happens on the machine running Akeru Bot (the server), not your local browser. If you're using a hosted or team instance, your administrator may have already configured providers.
+If Akeru reports that Azure DevOps still needs authentication, run:
-**Common issues:**
+```bash
+az devops login
+```
-- **Provider shows "Not authenticated"** – Run the login command for that provider (e.g., `gh auth login`) in a terminal on the server, then rescan in Settings
-- **GitHub says it could not verify sign-in status** – Akeru Bot needs GitHub CLI 2.81.0 or newer to check sign-in status. Update `gh` (e.g., `brew upgrade gh`), then rescan
-- **Bitbucket not connecting** – Double-check your environment variables are set in the correct shell profile and the server was restarted
-- **Can't push to a remote** – Verify your Git remote URL matches the provider you've authenticated with (SSH vs HTTPS remotes may need different credentials)
+Rescan after authentication succeeds.
-**Need more help?** Check your provider's CLI documentation:
+## Fix connection problems
-- [GitHub CLI](https://cli.github.com/)
-- [GitLab CLI](https://gitlab.com/gitlab-org/cli)
-- [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/)
+- Update GitHub CLI when Akeru cannot verify its sign-in state.
+- Confirm that authentication and Git remotes use compatible SSH or HTTPS credentials.
+- Restart the server after changing Bitbucket environment variables.
+- Run the provider's login command on the server, not on a remote client.
diff --git a/docs/user/thread-sidebar.md b/docs/user/thread-sidebar.md
index b42dc54db..57a346e16 100644
--- a/docs/user/thread-sidebar.md
+++ b/docs/user/thread-sidebar.md
@@ -1,34 +1,39 @@
-# Organizing threads
+# Organize threads
-Pin a thread from its context menu to keep it in the pinned section above your active work.
-Pinned threads are shown independently of their project, including when you connect to more than
-one environment.
+Use a thread's menu to settle, snooze, wake, archive, delete, pin, or unpin it.
-Pinned threads still move to **Settled** when they become inactive. They also move when their pull
-request merges if **Auto-settle merged threads** is enabled.
+## Active and settled threads
-When you un-settle a thread, it returns to the top of the active list so you can find it right
-away. Its timestamps do not change. Other threads keep their positions.
+Akeru settles inactive threads after three days by default. An open pull request blocks inactivity
+settlement. Closed pull requests settle their threads, and merged pull requests settle them when
+**Auto-settle merged threads** is on.
-Right-click a pull request link in a thread and choose **Link to thread** to show that pull request
-in the sidebar. The thread settles when the linked pull request merges if **Auto-settle merged
-threads** is enabled. Right-click the same link and choose **Unlink from thread** to remove it.
+Settling a pinned thread also removes its pin. **Un-settle thread** returns the thread to the top of
+the active list without changing its timestamps.
-On web and desktop, drag a pinned thread to change its position. On mobile, open the thread's menu
-and choose **Move up** or **Move down**. The order is stored by the server and appears on your
-other connected devices.
+Use **Snooze** to hide a thread until its wake time. Use **Wake thread** to return it early.
-If reordering is unavailable for one environment, update the Akeru Bot server running in that
-environment. Older servers can still pin and unpin threads, but do not understand synced ordering;
-their pinned threads keep the default newest-first order below the ones you have arranged.
+## Pinned order
-## Environment artwork
+Pinned threads appear above active work across projects and environments. On web and desktop, drag a
+pinned thread to reorder it. On mobile, open its menu and select **Move up** or **Move down**.
-Dev environments can identify themselves with artwork at the top of the sidebar and in
-the send button. Choose **Artwork**, **Version pill**, or **None** in Settings under environment
-identification. Artwork is recolored to match each built-in theme. Custom themes use the **Version
-pill** fallback because their colors are not controlled by Akeru Bot.
+The environment server stores the order. An older server can still pin a thread but keeps its default
+newest-first order until it is updated.
-To generate a fresh title from the conversation, open a thread's context menu and choose
-**Regenerate title**. While Akeru Bot is generating it, the action reads **Regenerating…** and cannot
-be selected again. The option is hidden when the connected environment needs a server update.
+## Link a pull request
+
+Right-click a pull-request link and select **Link to thread**. Select **Unlink from thread** from the
+same menu to remove it. Linked review state appears with the thread and can trigger automatic
+settlement.
+
+## Regenerate a title
+
+Open the thread menu and select **Regenerate title**. The action changes to **Regenerating…** until
+the new title is ready. Akeru hides this action when the environment server is too old to support it.
+
+## Environment identification
+
+Development environments can show **Artwork**, a **Version pill**, or **None** at the top of the
+sidebar and in the send button. Artwork follows built-in theme colors. Custom themes use the version
+pill because Akeru does not control their color palette.
diff --git a/docs/user/updating.md b/docs/user/updating.md
index 55a0a6000..b05063791 100644
--- a/docs/user/updating.md
+++ b/docs/user/updating.md
@@ -1,81 +1,68 @@
-# Keeping Akeru Bot in Sync
+# Keep the app and server in sync
-The Akeru Bot web or desktop app and the server it connects to work best when they use the same
-version. If they do not match, Akeru Bot shows a warning with the right update option for that server.
+Akeru works best when a client and its connected environment server use the same version. A version
+mismatch appears above the composer and under **Settings > Connections**.
-## Where to Find the Update
+Dismissing the composer notice hides that reminder for the two current versions. It does not update
+the server. Connections still shows the mismatch.
-You may see the warning in either of these places:
+## Before an update
-- above the message box in the current conversation
-- **Settings** → **Connections**, beside the affected connection
+Let active agent work and terminal commands finish. A server update interrupts the connection and
+can stop work that is still running. It does not remove threads, settings, or project files.
-Dismissing the conversation warning only hides that reminder for those two versions. It does not
-update the server, and the version difference remains visible in Connections.
+## Update the environment
-## Before You Update
+The available action depends on how the environment started.
-Let active agent work and terminal commands finish first. Updating restarts the server, so the
-connection will disappear briefly and work that is still running may be interrupted.
+- A supported background service can offer an update action in Akeru. Keep the client open while it
+ downloads, verifies, restarts, and reconnects.
+- A desktop-managed environment tells you to update the desktop app on the machine that owns the
+ server.
+- A command-line environment offers **Copy update command**. Run the copied command on the server
+ machine with its normal startup flags.
-The update does not remove saved threads, settings, or project files.
+The manual command pins the server to the client version:
-## Choose the Action You See
-
-| Action | What to do |
-| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Update server** | Available for the Akeru Bot Linux background service. Select the button and leave Akeru Bot open while it prepares, tests, restarts, and reconnects. |
-| **Update the desktop app** | Open the Akeru Bot desktop app on the machine that runs the server and install the app update there. Reopen it if needed. |
-| **Copy update command** | Copy the command, open a terminal on the server machine, stop the current Akeru Bot server, and relaunch it with the copied command and any startup options you normally use. |
-
-The available action depends on how that server was started. Akeru Bot does not update connected
-servers silently in the background.
-
-An older background-service launcher may ask you to run the exact
-`npx akeru-bot@<version> service update` command on the server machine. That one local update installs the
-rollback support needed for later remote updates, including versions that change the database.
-
-After selecting **Update**, the notice becomes a live status line: **Downloading…** while the new
-version is fetched and verified, then **Restarting…** while the server restarts into it. The same
-status appears in the conversation and in Connections, so navigating between them does not lose the
-update. A failure remains visible with its error and an option to retry.
-
-**Copy update command** gives you `npx akeru-bot@<client-version>`, which relaunches the server directly
-at the matching version. Add whatever startup options you normally use.
+```bash
+npx akeru-bot@<client-version>
+```
-If the server instead runs as the Akeru Bot background service, update the service on the host and
-pin the same version:
+For the background service, pin the same version like this:
-```sh
+```bash
npx akeru-bot@<client-version> service update
```
-`service update` installs the version of the CLI that invoked it, so `npx akeru-bot@latest service update`
-only resolves the skew when your client happens to be on the latest release. The exact version from
-the warning always works.
+`service update` installs the version of the package that invoked it. `@latest` only resolves a
+mismatch when the client already uses the latest release.
+
+An older launcher can ask for one exact local service update before Akeru can perform future remote
+updates safely.
-See [Running Akeru Bot in the Background](./background-service.md) for install, status, and removal
-commands.
+## Follow progress
-## After the Update
+The notice shows **Downloading…** while Akeru fetches and verifies the candidate. It shows
+**Restarting…** while the replacement server starts. The same state appears in the composer and
+Connections.
-Keep the web or desktop app open while the server restarts. The update completes only after the
-service launcher reports that exact update committed and the replacement server is ready to accept
-commands. A rollback is reported immediately instead of waiting for a generic reconnect timeout.
+A failed update stays visible with its error and retry action. A rollback appears as soon as the
+launcher returns to the previous version.
-If a step fails:
+If an update fails:
1. Retry the offered action once.
-2. Make sure you updated the machine named in the warning, not only the device you are using.
-3. For a command-line server, relaunch it with `npx akeru-bot@<client-version>`, replacing
- `<client-version>` with the client version shown in the warning.
+2. Confirm that you updated the machine named in the notice.
+3. Relaunch a command-line server with `npx akeru-bot@<client-version>`.
+
+See [Run Akeru in the background](./background-service.md) for service commands.
+
+## Mobile updates
-## The Mobile App
+The mobile app downloads its own update in the background and installs it after you leave the app.
+It saves unsent drafts and queued messages before restart.
-The mobile app keeps itself current on its own. When it finds a new version, it downloads it in the
-background and installs it automatically the next time you leave the app. Unsent drafts and queued
-messages are saved before the restart. Only if the app stays open long enough that the update never
-gets that chance does it ask whether to install right away; choosing **Later** is safe and keeps the
-automatic install armed.
+If the app stays open for too long to install the update, it asks whether to install now. **Later**
+keeps the pending automatic install.
-For remote connection setup and access troubleshooting, see [Remote Access](./remote-access.md).
+See [Remote access](./remote-access.md) for connection setup.
diff --git a/docs/user/usage.md b/docs/user/usage.md
index 75981f6e2..cb7675f42 100644
--- a/docs/user/usage.md
+++ b/docs/user/usage.md
@@ -1,9 +1,29 @@
# Review usage
-Open Usage from the sidebar to see how much of each connected subscription is
-left. It uses the accounts from Settings → Providers: ChatGPT, Claude, Grok,
-and Kimi For Coding. Disconnected accounts are hidden.
+Open **Usage** from the sidebar to review subscription limits and recent model activity across your
+connected environments.
-Each row is a cap (5-hour, weekly, or plan) with percent left and when it
-resets. Usage reloads every five minutes. Change that interval in
-Settings → General. The refresh button reloads immediately.
+## Plan limits
+
+The plan section shows available limits for ChatGPT, Claude, Cursor, Grok, and Kimi For Coding.
+Disconnected accounts and limits that a provider does not report stay hidden.
+
+Each meter shows the percentage used or left and the next reset time. Provider plans expose different
+windows, such as five-hour, weekly, or plan-wide limits.
+
+## Activity
+
+The **Activity** section summarizes the last 30 days of local Codex and Claude transcript usage. It
+shows processed tokens, cached input, output, estimated cache savings, and totals by model when that
+data exists.
+
+Akeru reads transcripts from each environment. It deduplicates shared transcript directories so the
+same usage is not counted twice. A notice identifies environments that are still loading, stale, or
+unavailable.
+
+## Refresh usage
+
+Akeru refreshes usage every five minutes by default. Select **Refresh usage** to reload it now.
+
+Change **Usage refresh** in **Settings > General** to a value from 1 to 60 minutes. Mobile also shows
+Usage under General settings and supports pull-to-refresh.