docs: auto-sync cli with merged PRs (through 2026-10-31)

packages/kilo-docs/pages/automate/agent-manager.md

@@ -369,6 +369,8 @@ The tool supports two modes:
 | `worktree` | Creates one Agent Manager git worktree and session per task. Each task gets an isolated checkout, branch, directory, and terminal. |
 | `local` | Creates Agent Manager sessions in the current workspace without git worktree isolation. You can also target an existing managed worktree with its `worktreeID`. |
 
+In `worktree` mode, set a task's `baseBranch` to start its new worktree from a specific existing branch, like the base branch in the New Worktree dialog. Use the branch name without a remote prefix, such as `main` or `release/1.0`. When omitted, the worktree starts from the configured default base branch, or the repository default branch when no default is configured. A task `baseBranch` cannot be combined with `local` mode or `worktreeID`.
+
 Starting another session in an existing worktree reuses its files and branch without rerunning setup. Coordinate edits between sessions sharing that checkout.
 
 Each request can start up to 20 tasks. Sessions started with a prompt inherit the current turn's model and reasoning effort unless you explicitly request a different selection. Sessions created without a prompt use the normal defaults. Ask for independent sessions for separate tasks, or alternate versions of the same task to compare approaches.

packages/kilo-docs/pages/automate/code-reviews/github.md

@@ -97,6 +97,7 @@ Turn automated reviews on or off for an individual repository to override the in
 
 - Check the Code Reviews page for error details on specific reviews
 - Ensure you have sufficient Kilo Code credits
+- A review on a paid model does not start when your balance is below the Cloud Agent minimum. Add credits or select a free or BYOK model, then push a new commit to run the review again.
 - Very large PRs may time out — consider splitting the change into smaller PRs
 
 ### The GitHub App is missing permissions

packages/kilo-docs/pages/automate/code-reviews/gitlab.md

@@ -119,6 +119,7 @@ You need **Maintainer role** on the GitLab project. Both webhook creation and bo
 
 - Check the Code Reviews page for error details
 - Ensure you have sufficient Kilo Code credits
+- A review on a paid model does not start when your balance is below the Cloud Agent minimum. Add credits or select a free or BYOK model, then push a new commit to run the review again.
 - Large MRs may time out — consider splitting the change into smaller MRs
 
 ### No projects listed after connecting

packages/kilo-docs/pages/automate/code-reviews/overview.md

@@ -37,6 +37,12 @@ Before enabling Code Reviews:
     - [Kilo Discord](https://discord.gg/hZnd57qN)
 - **Kilo Code credits are still used** when the agent performs model reasoning during a review.
 
+### Credit requirement for paid models
+
+A review on a paid model starts only when the owning account's available balance covers the Cloud Agent minimum balance, so a review is never dispatched when its model usage cannot be paid for. If the balance is too low, the review fails before any model runs: Kilo posts a billing notice on the pull or merge request, leaves the review without comments, and marks the platform check as action required (GitHub) or the commit status as failed (GitLab).
+
+Reviews on free models, on models you connect with your own key (BYOK), and on organizations sponsored through Kilo's OSS program skip this check. Every model the review runs is evaluated.
+
 ## Concurrent reviews
 
 Cloud Code Reviews limit how many reviews one owner can run at the same time. Reviews past that limit wait, then start when a slot opens. Local `/review` commands do not count toward this limit.

packages/kilo-docs/pages/code-with-ai/agents/auto-model.md

@@ -41,35 +41,30 @@ The underlying models behind each Auto Model tier are updated server-side as bet
 
 You get lean costs on routine work and stronger models when the work demands it — with no manual switching.
 
-### Custom Efficient pools
+### Platform pools
 
-You can constrain `kilo-auto/efficient` to the exact models you trust by configuring an **Efficient model pool** on the **Auto routing** card:
+Kilo selects the model pool for `kilo-auto/efficient` and `kilo-auto/frontier`; they are not configurable per owner. You can still choose your account's platform routing mode, and organization model policy continues to filter which models its members can route to.
 
-- **Personal** — your [profile page](https://app.kilo.ai/profile)
-- **Organization** — your organization's **Providers & Models** page. Owners and billing managers can edit; members see a read-only view.
+To route across the exact models you trust — including client models the gateway cannot reach — create a [custom auto router](#custom-auto-routers).
 
-A pool holds 1–10 exact model and thinking-variant pairs. Variants stay distinct, so the same model with different thinking variants (for example `max` and `xhigh`) counts as separate entries. Leave the pool empty to inherit: an organization without a pool uses each member's personal pool, and a member without a personal pool uses the platform pool.
+{% callout type="warning" title="Data handling for Auto Free" %}
+Auto Free may route your requests to providers that log prompts and outputs and use them to improve their services. Do not submit personal or confidential data when using Auto Free. In particular, it may route to NVIDIA's free endpoints.
 
-New entries are benchmarked on demand before they can serve traffic. Each entry shows a status:
+For NVIDIA free endpoints (Super/Ultra/etc): Trial use only - do not submit personal or confidential data. Your use is logged for security purposes and to improve NVIDIA products and services. The logged session data for improvement purposes is not linked to your identity or any persistent identifier. For more information about our data processing practices, see our [Privacy Policy](https://www.nvidia.com/en-us/about-nvidia/privacy-policy/). By interacting with this endpoint, you consent to our collection, recording, and use of such information and the [NVIDIA API Trial Terms of Service](https://assets.ngc.nvidia.com/products/api-catalog/legal/NVIDIA%20API%20Trial%20Terms%20of%20Service.pdf).
+{% /callout %}
 
-| Status | Meaning |
-|---|---|
-| Benchmarking | The pair is being measured and is not used for routing yet |
-| Ready | Proven accurate enough and eligible for routing |
-| Failed | Benchmarking failed — retry the entry |
-| Unavailable | The model or variant is no longer in your catalog — remove the entry |
+### Custom auto routers
 
-Routing decides only among ready entries. If no pool entry can serve a request, the request falls back to a fixed, cost-effective baseline model, so quality never drops below that baseline.
+A custom auto router is your own routing pool under a `kilo-auto/custom/<slug>` model id. Create the router in the Kilo web editor, then register the models this machine can run so the CLI can serve it locally instead of always forwarding to the gateway:
 
-{% callout type="note" %}
-You can benchmark up to 10 new or retried pairs per owner per rolling 24 hours. Entries that are already ready or benchmarking don't count against this limit.
-{% /callout %}
+- `kilo auto router list` — list your custom routers, their entries, and each entry's eval status
+- `kilo auto router add <router> <model>` — register a model configured in this CLI as a router entry
+- `kilo auto router remove <router> <model>` — remove a client model entry
+- `kilo auto eval <router>` — run the router's missing client evals locally in Docker
 
-{% callout type="warning" title="Data handling for Auto Free" %}
-Auto Free may route your requests to providers that log prompts and outputs and use them to improve their services. Do not submit personal or confidential data when using Auto Free. In particular, it may route to NVIDIA's free endpoints.
+When you select a custom router, Kilo ranks the entries this machine can serve, asks the routing service for a decision, and runs the chosen model through its local provider. See the [CLI command reference](/docs/code-with-ai/platforms/cli-reference#kilo-auto) for every command and option.
 
-For NVIDIA free endpoints (Super/Ultra/etc): Trial use only - do not submit personal or confidential data. Your use is logged for security purposes and to improve NVIDIA products and services. The logged session data for improvement purposes is not linked to your identity or any persistent identifier. For more information about our data processing practices, see our [Privacy Policy](https://www.nvidia.com/en-us/about-nvidia/privacy-policy/). By interacting with this endpoint, you consent to our collection, recording, and use of such information and the [NVIDIA API Trial Terms of Service](https://assets.ngc.nvidia.com/products/api-catalog/legal/NVIDIA%20API%20Trial%20Terms%20of%20Service.pdf).
-{% /callout %}
+An entry can link to a platform model so it reuses that model's platform benchmark instead of running a local client eval. Pass `--measured-as <model>` to `kilo auto router add`, accept the link the CLI suggests when it finds a matching platform model, or set it in the web editor, which suggests a link for each entry and lets you pick another model or clear it. The link applies to each variant whose name matches a measured platform variant; other variants still need a client eval, and linked variants are skipped by `kilo auto eval`. A linked entry serves the newest platform measurement for that model and is flagged stale when the measurement is older than the current benchmark engine or the model has left the catalog. Once stored, a link stays until you clear it in the web editor.
 
 ## Benefits
 

packages/kilo-docs/pages/code-with-ai/platforms/cli.md

@@ -39,6 +39,8 @@ kilo --help
 
 After installation, run `kilo` and use the `/connect` command to add your first provider credentials. This is the interactive way to configure API keys for model providers.
 
+The dialog lists each provider with a short description — Kilo Gateway is marked **Recommended**. When the Kilo Gateway model list cannot load, its row shows a red `!` with the reason, such as credentials rejected, not signed in, no connection, or a provider error, so you can fix the connection before starting a session.
+
 ## Opening Links
 
 Links in agent responses use terminal hyperlink metadata when the terminal supports it. Kilo also handles links inside the TUI, so mouse capture does not make supported HTTP(S) links inactive. Move the pointer over a link to see the hover underline, then click it to open the default browser.
@@ -122,9 +124,12 @@ The `kilo console` command and its browser interface are deprecated and will be
 
 #### Provider Commands
 
-| Command | Description |
-|---|---|
-| `/connect` | Connect/add a provider - entry point for new users to add API credentials |
+| Command | Aliases | Description |
+|---|---|---|
+| `/connect` | - | Connect/add a provider - entry point for new users to add API credentials |
+| `/usage` | `/plans`, `/quota` | Show plan and quota usage for your connected providers |
+
+`/usage` opens a **Plans & usage** dialog with one card per detected source: Kilo coding plan quotas, ChatGPT (Codex) rate limits, and MiniMax Token Plan quotas. Each card shows the plan, the usage windows with their percentage used, any reset time, and a **Manage** link when the provider offers one. Press `ctrl+r` to refresh.
 
 #### System Commands
 
@@ -262,6 +267,26 @@ The `diff_open` and `session_move` TUI keybindings run the same actions and are
 }
 ```
 
+## Home Screen and Session Sidebar
+
+### Home screen news
+
+When you are signed in to Kilo Gateway, the CLI home screen shows the most recent unread Kilo news item, with a `(N new)` count when more than one item is unread. Select the banner to open the **News** dialog, which lists every unread item and its action links. Opening the dialog marks those items as read, and they stay hidden after a restart. Items that are not intended for the CLI are not shown.
+
+The command palette has **Hide news** and **Show news** on the home screen, and the choice persists. Kilo fetches news only while you are signed in, and refetches after you sign in, sign out, or switch teams.
+
+### Session sidebar
+
+The session sidebar shows Kilo panels alongside the built-in ones:
+
+- **Branch PR** — the pull request for the current branch, when `gh` is installed and the branch has one.
+- **Token Usage** — input, output, reasoning, cache read, and cache write tokens, cache hit rate, generation speed, and cost for the whole session, including subagents.
+- **Models** — one row per provider and model, with its step count and cost. Expand a row for its token breakdown.
+- **Terminal Bench 2.0** — the completion score and cost per attempt for the current Kilo model.
+- **Footer** — your Kilo balance, Kilo Pass usage (personal accounts), and the Kilo version.
+
+Select a panel heading to collapse or expand it.
+
 ## Permissions
 
 Kilo Code uses the permission config to decide whether a given action should run automatically, prompt you, or be blocked.
@@ -707,6 +732,21 @@ The CLI supports overriding config values with environment variables. The suppor
 - For `kilocode` provider: `KILOCODE_<FIELD_NAME>` (e.g., `KILOCODE_MODEL` → `kilocodeModel`)
 - For other providers: `KILO_<FIELD_NAME>` (e.g., `KILO_API_KEY` → `apiKey`)
 
+## Self-Hosted Backends
+
+By default the CLI sends Kilo API traffic (sign-in, profile, defaults) to `https://api.kilo.ai` and [AI gateway](/docs/gateway) traffic (chat, model listing, embeddings, autocomplete, transcription) to `https://ai-gateway.kilo.ai/api/v1`. Point either at a different server with these environment variables — for example, to route gateway traffic through a self-hosted gateway for compliance, or a local backend during development.
+
+| Variable | Default | Controls |
+|---|---|---|
+| `KILO_API_URL` | `https://api.kilo.ai` | Kilo API traffic. When set on its own (without `KILO_AI_GATEWAY_URL`), gateway traffic also goes here, under `/api/gateway/v1`. |
+| `KILO_AI_GATEWAY_URL` | `https://ai-gateway.kilo.ai/api/v1` | AI gateway traffic only. |
+
+Set `KILO_AI_GATEWAY_URL` to send only gateway traffic to another server while leaving sign-in and profile requests on the default:
+
+```bash
+KILO_AI_GATEWAY_URL=https://gateway.example.com/api/v1 kilo
+```
+
 ## Using the CLI in an Organization
 
 If you belong to a Kilo organization (Team or Enterprise), you can route CLI requests through that organization. The process differs slightly between interactive and non-interactive usage.

packages/kilo-docs/pages/code-with-ai/platforms/slack.md

@@ -140,6 +140,12 @@ To make proper use of all of the Kilo Slack bot's capabilities, it's important t
 
 ---
 
+## Organization Slack integrations
+
+When Slack is connected to an organization, the integration is managed by the organization. Only organization owners and admins can connect, re-install, or disconnect Slack, and only they can change its model. Members see the connection state, can test the connection, and see a note explaining who manages the integration.
+
+---
+
 ## Changing the Model
 
 You can customize which AI model Kilo uses for generating responses.

packages/kilo-docs/pages/getting-started/adding-credits.md

@@ -15,6 +15,12 @@ These options are available to purchase from your [personal profile page](https:
 
 You can also use subscriptions or credits you may have purchased directly with an AI provider by adding your keys on the [Bring your own Key (BYOK)](https://app.kilo.ai/byok) settings screen. For setup details and supported providers, see [AI Providers documentation](/docs/ai-providers). If your provider is not yet supported, you can also [directly connect your provider](/docs/getting-started/setup-authentication) in the extension and CLI.
 
+## Changing your Kilo Pass plan
+
+If you already have a Kilo Pass, you can change plans, including upgrading to a higher tier such as Expert, from the Kilo Pass subscription settings on your [profile page](https://app.kilo.ai/profile). A plan change takes effect when your next billing period starts, and your current pass stays active until then. You can cancel a pending change before it takes effect.
+
+If your subscription is set to cancel at the end of the current period, resume it before changing plans. Plan selection is disabled while cancellation is pending, because the subscription would end instead of switching plans. Canceling a Kilo Pass also releases any scheduled plan change.
+
 ## Transparent Pricing
 
 At Kilo Code, we believe in complete pricing transparency:

packages/kilo-docs/pages/getting-started/byok.md

@@ -29,6 +29,7 @@ Use your provider API key to route matching models through your account:
 - Azure Foundry (experimental)
 - DeepSeek
 - Fireworks
+- GMI Cloud
 - Google AI Studio
 - Inception
 - Minimax
@@ -61,6 +62,15 @@ These providers offer coding-focused subscriptions or dedicated endpoints. Bring
 - Xiaomi Token Plan (Singapore)
 - Z.ai Coding Plan
 
+### Gateway keys
+
+These keys route through a gateway that already serves the regular Kilo catalog models, so no separate model entries are needed. Save the gateway's own API key:
+
+- OpenRouter
+- Vercel AI Gateway
+
+A gateway key serves the catalog models its gateway provides. If you save both keys, the Vercel AI Gateway key is used for the models it serves, and the OpenRouter key covers requests that Vercel cannot serve.
+
 ## Connect a ChatGPT subscription
 
 Connect **OpenAI (ChatGPT subscription)** on the [BYOK page](https://app.kilo.ai/byok) to use your subscription allowance for supported OpenAI models through the Kilo Gateway. No OpenAI API key is needed.
@@ -143,6 +153,22 @@ These rules apply to saved API keys. Eligible requests use a connected ChatGPT s
 - If the key is invalid, the request fails. It does not fall back to using Kilo's keys.
 - Subscription-based providers (such as the Z.ai Coding Plan or Kimi Code) only expose the models included in that plan. Select one of those models to route traffic through your subscription.
 
+## Serve Kilo catalog model IDs (catalog mode)
+
+By default, a provider key serves models under that provider's own IDs. You can switch a key to serve Kilo catalog model IDs instead by turning on **Use Kilo catalog model IDs** when you add or edit the key.
+
+Catalog mode is off by default for new and existing keys. It is offered only for providers that map at least one model to a catalog ID, and it is not available for Vercel BYOK keys or for the OpenRouter and Vercel AI Gateway keys.
+
+With catalog mode on:
+
+- The key serves catalog model IDs such as `moonshotai/kimi-k2.6`, and its supported models list shows those IDs. The provider-prefixed IDs are no longer served by the key.
+- [Auto Model](/docs/code-with-ai/agents/auto-model) and custom routers can route matching catalog models through the key. For the catalog models it serves, the key is used ahead of a ChatGPT connection and your other BYOK keys.
+- Organization model restrictions apply to requests that use the key. Keys without catalog mode keep their provider-prefixed IDs and stay exempt from those restrictions.
+
+Saved favorites are not rewritten when you switch a key to catalog mode. A saved model that used the provider-prefixed ID fails with a message naming the catalog ID to use; select the catalog model instead.
+
+Personal key owners can change catalog mode. For organization keys, only organization owners and admins can.
+
 ## Using BYOK in the Extensions and CLI
 
 - BYOK works with the Kilo Gateway provider. Users should ensure that is set as the active [provider](/docs/ai-providers).

packages/kilo-docs/pages/getting-started/rate-limits-and-costs.md

@@ -77,7 +77,7 @@ Kilo automatically applies prompt caching on supported providers. Repeated conte
 - Kilo calculates an estimated cost for each request based on configured pricing. This estimate is shown per-request in the chat history.
 - Cache hits are billed at a discounted rate compared to regular input tokens.
 - Requests using **Auto Free** models are billed at $0 on Kilo's side.
-- **BYOK (Bring Your Own Key)** requests are billed at $0 on Kilo's side — you pay the provider directly.
+- **BYOK (Bring Your Own Key)** requests are not charged for inference on Kilo's side — you pay the provider directly. Kilo still charges for the gateway-side costs it incurs on the request, such as server tools, plugins, and PDF parsing.
 
 For current pricing, visit [kilo.ai/models](https://kilo.ai/models).