docs: auto-sync with merged PRs (through 2026-08-28)

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

@@ -155,6 +155,7 @@ Layer review in before asking a teammate:
 - **`/review`** — slash command, AI review of staged, unstaged, and untracked changes in the worktree when run without arguments. Good as a last pass before committing.
 - **`/review uncommitted [guidance]`** — explicitly review uncommitted changes, optionally focusing the review with guidance.
 - **`/review branch [base] [guidance]`** — review the whole branch vs. its detected or specified base, with optional guidance.
+- **`/review worktree [guidance]`** — review every committed, staged, unstaged, and untracked change in the worktree against its recorded parent branch. This scope is offered only in Agent Manager worktree sessions.
 - **`/review <commit-hash>` or `/review <PR URL or number>`** — review a specific commit or pull request.
 - **`kilo review` in CI** — automated PR review. See [Code Reviews](/docs/automate/code-reviews/overview) for the setup.
 - **Human review** — push the branch from the session terminal and `gh pr create`. The PR badge appears on the worktree and stays in sync with CI and reviews.

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

@@ -189,7 +189,8 @@ Imported work stays associated with its branch or worktree and can be continued
 
 - Create a worktree session to start a new agent in an isolated branch
 - Press `Cmd+T` (macOS) / `Ctrl+T` (Windows/Linux) to start another session in the selected worktree
-- Use session history to reopen local sessions or preview cloud sessions
+- Use session history to reopen local sessions or preview cloud sessions. Open it with the history button in the **WORKTREES** header; in multi-project mode, each project row has its own history button, including collapsed projects. Opening a project's button activates that project and filters the Local history tab to that project's sessions.
+- Hover a session in the history list for direct actions: open the session in a newly created worktree, or move it to the project root and open it in the project's local tabs.
 - When a worktree is selected, open session history to use the **Worktree** source, which is selected by default and lists only sessions assigned to that worktree. Opening a worktree session returns to its owning worktree.
 - Continue a cloud session locally from Agent Manager using the same extension sign-in and provider settings
 
@@ -218,9 +219,11 @@ Each request can include 1-20 tasks. Each task must include at least one of `pro
 
 The companion `agent_manager_models` tool searches models and their supported reasoning variants on demand. Results are grouped by model name (with the offering providers listed for reference) and limited to 20 per call, so the full catalog is never added to the conversation context.
 
-The same tool also manages existing sessions. It can return an overview of sections, worktrees, and local sessions, send a prompt to one managed session, stop a managed session, or move a session's worktree into a section. The overview includes section IDs, each section's assigned worktrees, worktree IDs, and session IDs. Use those exact IDs for a subsequent move. Moving accepts a section ID from the overview, or `null` to ungroup the worktree. Moving a session moves its whole worktree, including multi-version siblings. Local sessions cannot be assigned to a section. Stopping aborts the session's active work and removes it from the panel, just like closing the session tab.
+The same tool also manages existing sessions. It can return an overview of sections, worktrees, and local sessions, send a prompt to one managed session, stop a managed session, move a session's worktree into a section, or answer a managed session's pending question. The overview includes section IDs, each section's assigned worktrees, worktree IDs, and session IDs. Use those exact IDs for a subsequent move. Moving accepts a section ID from the overview, or `null` to ungroup the worktree. Moving a session moves its whole worktree, including multi-version siblings. Local sessions cannot be assigned to a section. Stopping aborts the session's active work and removes it from the panel, just like closing the session tab.
 
-The tool uses the `agent_manager` permission. Approval prompts are scoped to the requested capability, so approving `worktree` does not automatically approve `local`, an overview, or a targeted prompt. Prompting an existing managed session requires an explicit `prompt` approval the first time, even if Agent Manager session creation was previously approved broadly. Stopping a session likewise requires an explicit `stop` approval, and moving a worktree requires an explicit `move` approval.
+A session waiting on a question refuses prompts. The failed prompt names the session ID, the pending question's ID and text, and its option labels, so a follow-up `answer` call can resolve the question with the exact labels shown. Answering resolves questions only — a session blocked on a permission request must be approved in the Agent Manager UI instead.
+
+The tool uses the `agent_manager` permission. Approval prompts are scoped to the requested capability, so approving `worktree` does not automatically approve `local`, an overview, or a targeted prompt. Prompting an existing managed session requires an explicit `prompt` approval the first time, even if Agent Manager session creation was previously approved broadly. Stopping a session likewise requires an explicit `stop` approval, moving a worktree requires an explicit `move` approval, and answering a pending question requires an explicit `answer` approval.
 
 ## Sections
 

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

@@ -124,6 +124,7 @@ Use `/review` for all local code reviews:
 - **`/review`** — Review uncommitted changes (staged, unstaged, and untracked) when run without arguments
 - **`/review uncommitted [guidance]`** — Review uncommitted changes with optional guidance
 - **`/review branch [base] [guidance]`** — Review your current branch vs. its detected or specified base, with optional guidance
+- **`/review worktree [guidance]`** — Review every committed, staged, unstaged, and untracked change in an Agent Manager worktree against its recorded parent branch (offered only in Agent Manager worktree sessions)
 - **`/review <commit-hash>`** — Review a specific commit
 - **`/review <PR URL or number>`** — Review a pull request
 

packages/kilo-docs/pages/automate/integrations.md

@@ -40,6 +40,10 @@ Before connecting:
 
 Go to your **Personal** or **Organization Dashboard**, and navigate to the [Integrations](https://app.kilo.ai/integrations) tab.
 
+{% callout type="note" %}
+For organizations, only Owners and Admins can add a GitHub integration. If you have another role, ask an Owner or Admin to complete the installation.
+{% /callout %}
+
 ### 2. Start the Connection Flow
 
 1. Click **Configure** on the GitHub panel.
@@ -163,14 +167,18 @@ Once your integrations are connected, the following features are enabled in Kilo
 
 ### Upcoming:
 
-- **Bitbucket Integration**
+- **Bitbucket Integration** — currently available only for organizations when starting [Cloud Agent](/docs/code-with-ai/platforms/cloud-agent) sessions; full integration support is upcoming
 
 ---
 
 ## Managing or Removing the Integration
 
 ### GitHub
 
+For organizations, the GitHub integration page lists each installation with its connection health, repository scope (all or only selected repositories), the selected repositories, and per-installation actions. Personal accounts keep the single GitHub identity connection.
+
+An organization can connect more than one GitHub organization. Click **Add organization** on the GitHub panel and repeat the installation flow for each GitHub organization; each one appears as a separate installation with its own repository scope and actions. Adding installations requires the Owner or Admin role.
+
 From the **Integrations** page, click "Manage on GitHub" to:
 
 - View the GitHub account you connected

packages/kilo-docs/pages/code-with-ai/agents/context-mentions.md

@@ -26,6 +26,7 @@ Type `@` in the chat input to get autocomplete suggestions. You can mention:
 | **Terminal** | In the sidebar, include the active VS Code terminal output. In Agent Manager, include the focused terminal for the selected session or worktree, including embedded **Run** and **Setup** tabs. | `@terminal` |
 | **Git Changes** | Attach uncommitted working-tree diffs and new files | `@git-changes` |
 | **Past chats** | Add a previous session's chat history as context | `@` → **Past chats** → pick a session |
+| **Worktrees** | In Agent Manager, reference another worktree — inserts its path with its branch, base branch, and session IDs as context | `@` → **Worktrees** → pick a worktree |
 
 Selecting a suggestion inserts the mention and highlights it in the input. File contents, terminal output, and git changes are attached as context when you send the message.
 
@@ -37,6 +38,12 @@ Choosing **Past chats** from the `@` menu opens a searchable picker of sessions
 
 Very long chat histories are truncated, keeping the beginning and end, so a single mention cannot fill the context window.
 
+### Referencing Agent Manager worktrees
+
+In Agent Manager, choosing **Worktrees** from the `@` menu opens a searchable picker of the project's worktrees. Search matches worktree names, branches, and session titles. Recently opened worktrees sort first, then worktrees with the most recent activity.
+
+Selecting a worktree inserts an `@` mention of its absolute path and attaches a small text record with the worktree's branch, base branch, and session IDs and titles. The mention is metadata only — it does not attach the worktree's files, diffs, or chat history, and it does not change the agent's working directory. The worktree you are currently working in is not offered as a reference.
+
 ### Drag and Drop
 
 You can also add file mentions by dragging and dropping:

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

@@ -670,6 +670,11 @@ Add to `~/.config/kilo/config.json`:
 
 Once enabled, start a CLI session and open [Cloud Agents](https://app.kilo.ai/cloud). Your local session appears in the dashboard. See [Cloud Agent Remote Connections](/docs/code-with-ai/platforms/cloud-agent#remote-connections) for details.
 
+A connected client can also start new sessions on your CLI. When it does, it can:
+
+- **Choose a child folder** of the CLI's launch directory as the session workspace. The CLI resolves the requested folder under the launch directory and rejects absolute paths and paths that escape it.
+- **Continue one of your existing cloud sessions locally.** The CLI downloads the cloud session and opens it instead of starting a new empty session.
+
 ### Requirements
 
 - Connection to Kilo Gateway

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

@@ -5,7 +5,7 @@ description: "Using Kilo Code in the browser"
 
 # {% $markdoc.frontmatter.title %}
 
-Cloud Agents let you run Kilo Code in the cloud from any device, without relying on your local machine. They provide a remote development environment that can read and modify your GitHub and GitLab repositories, run commands, and auto-commit changes as work progresses.
+Cloud Agents let you run Kilo Code in the cloud from any device, without relying on your local machine. They provide a remote development environment that can read and modify your GitHub, GitLab, or Bitbucket repositories, run commands, and auto-commit changes as work progresses. Bitbucket repositories are available for organizations only, not personal accounts.
 
 ## What Cloud Agents Enable
 
@@ -18,8 +18,8 @@ Cloud Agents let you run Kilo Code in the cloud from any device, without relying
 
 Before using Cloud Agents:
 
-- **GitHub or GitLab Integration must be configured**
-  Connect your account via the [Integrations tab](https://app.kilo.ai/integrations) so that Cloud Agents can access your repositories.
+- **A GitHub, GitLab, or Bitbucket integration must be configured**
+  Connect your account via the [Integrations tab](https://app.kilo.ai/integrations) so that Cloud Agents can access your repositories. Bitbucket is available for organizations only.
 
 ## Cost
 
@@ -35,14 +35,23 @@ Usage is measured in whole seconds, with no rounding up to a longer billing inte
 
 See [Kilo Code pricing](https://kilo.ai/pricing) for current rates and pricing for other cloud products.
 
+### Session cost display
+
+The session header shows two separate entries:
+
+- **Token Usage** — the session's inference spend (model usage), paid in Kilo credits.
+- **Compute** — the estimated cost of the cloud environment, which may be shared with other sessions. The display shows an hourly rate while idle or an estimate for the active period. **Not currently charged** means compute charges are not being applied.
+
+If a compute billing check fails — for example, when the paying account has insufficient credits — the error appears next to the composer with recovery actions appropriate to the paying account (personal or organization) and your role in it. Your prompt text is preserved so you can retry after resolving the billing issue.
+
 ## How to Use
 
-1. **Connect your GitHub or GitLab account** in the [Integrations](https://app.kilo.ai/integrations) tab of your personal or organization dashboard.
-2. **Select a repository** to use as your workspace.
+1. **Connect your GitHub, GitLab, or Bitbucket account** in the [Integrations](https://app.kilo.ai/integrations) tab of your personal or organization dashboard. Bitbucket is available for organizations only.
+2. **Select a repository** to use as your workspace. The repository picker groups your repositories into Recently used and per-provider sections.
 3. **Add environment variables** (secrets supported) and set optional startup commands.
 4. **Start chatting with Kilo Code.**
 
-Your work is always pushed to GitHub, ensuring nothing is lost.
+Automatic commit and push depends on your session settings. If it is disabled, review, commit, and push the changes you want to keep.
 
 ## Starting Tasks from the CLI
 
@@ -185,6 +194,8 @@ When creating a trigger, you choose an **activation mode** that cannot be change
 
 Triggers utilize [agent environment profiles](#agent-environment-profiles) to configure the execution environment for triggered sessions. The agent resolves the profile at runtime, so profile updates apply automatically to future executions. Profiles referenced by triggers cannot be deleted until those triggers are updated or removed.
 
+Both webhook and scheduled triggers can optionally set a **reasoning effort** for models that support it. The effort picker sits next to the model selector and starts at **Default**, which leaves the model's own behavior unchanged. Choosing a specific effort stores it on the trigger and applies it to every session the trigger starts; existing triggers keep working without one.
+
 Triggers do not support manual env var or setup command overrides at this time.
 
 ### Scheduled Triggers

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

@@ -17,6 +17,41 @@ Open **Settings → Tools → Kilo Code** to configure the plugin. The JetBrains
 - **Context** — toggle auto-compaction, set the auto-compaction limit (the percentage of the model window that triggers compaction), enable pruning of old tool outputs, and manage file watcher ignore patterns. See [Context Condensing](/docs/customize/context/context-condensing) and [.kilocodeignore](/docs/customize/context/kilocodeignore) for what these settings control.
 - **Agent Behavior → Skills** — inspect loaded skills, add extra skill sources (local paths or remote URLs), edit or remove custom skills, and open skill files in the editor. See [Skills](/docs/customize/skills) for the skill format and discovery rules.
 
+## Chat and Agents tabs
+
+The Kilo Code tool window is split into two tabs:
+
+- **Chat** — the conversation with the agent in the current workspace.
+- **Agents** — the Agent Manager, a control panel for running and orchestrating multiple agents in parallel, each in its own git worktree. A notification dot appears on the tab when a worktree session needs attention.
+
+The tool window toolbar has labeled create actions: **+ Session** starts a new session in the Chat tab, and **+ Worktree** opens the New Worktree dialog in the Agents tab.
+
+When a chat has no session yet, the empty state reflects where you are working. On a plain branch it suggests keeping changes isolated and offers a **run it in a worktree** link that opens the New Worktree flow; in a worktree it confirms that your main checkout stays untouched.
+
+### Working with worktrees
+
+- The worktree list shows each session's activity state with compact status icons and badges, including a running indicator for active sessions.
+- Drag worktrees to reorder them; the order is persisted and selection stays stable across refreshes.
+- Session history is scoped to the current worktree, so sessions from the main checkout or sibling worktrees are not mixed in. Sessions started from a worktree's separate IDE frame also appear in Agent Manager.
+- In a worktree editor tab, the session-list toggle hides or shows the session list. The choice is remembered per worktree. While the list is hidden, the toggle shows the session count or flags a background session that needs your attention, so a pending question stays visible.
+
+### Chat branch dock
+
+When the workspace is a git repository, the chat header shows a branch dock with the current branch, a file-change summary, and worktree actions:
+
+- **New Worktree** — open the New Worktree dialog, which has three tabs: **New** creates a worktree on a new branch with an optional initial prompt, **From PR** imports a GitHub pull request by URL, and **From Branch** imports an existing local branch that no worktree is using yet. Imported PR branches get git tracking set up, so `git push` and `git pull` work in the new worktree.
+- **Move to Worktree** — move the conversation and your current local changes into a dedicated worktree for isolated follow-up work. Available whenever the repository has local changes, even before the chat has a session.
+
+When the branch has an associated pull request, the dock shows the PR badge and title with access to the diff. Worktree actions appear only while the session is idle.
+
+## Mermaid diagrams in chat
+
+Chat renders `mermaid` and `mmd` code fences as inline diagrams. While a reply is still streaming, or if a diagram fails to render, the fence shows its source instead.
+
+- **Viewer window** — click a rendered diagram to open it in a resizable viewer with zoom controls, trackpad pinch zoom, Cmd/Ctrl+wheel zoom, drag to pan, and double-click to fit.
+- **Editor tab** — use the open action on a diagram's toolbar to open it in its own editor tab with a rendered **Diagram** view and a read-only **Source** view.
+- **Copy** — copying a rendered diagram puts the picture (PNG) on the clipboard. While streaming or after a render error, copy falls back to the Mermaid source.
+
 ## Reviewing session changes
 
 - **Modified files per turn** — each assistant turn that changed files shows a **Modified** card with the affected files and their diff stats. Expand a file to see its diff inline, or open all of the turn's changes in the **Changed files** diff viewer.
@@ -26,3 +61,9 @@ Open **Settings → Tools → Kilo Code** to configure the plugin. The JetBrains
 ## Permission requests
 
 When the agent asks for several approvals at once, permission requests queue up instead of replacing each other. Resolve the current request to advance to the next one in the queue.
+
+## Turn failures and retries
+
+When a turn fails — for example from a provider error or missing provider credentials — the transcript ends with an error card showing the failure details and a **Retry** action. Retry replays the failed turn using the model and agent selected at that moment, so you can switch away from an unavailable provider and press **Retry** to continue the conversation.
+
+Pressing **Stop** is not treated as a failure. The transcript shows a short "Stopped" note, and the session does not get an error badge in the history, recents, or Agent Manager worktree rows.