Merge pull request #13386 from Kilo-Org/docs-agent-manager-base-branch

docs(agent-manager): clarify worktree base branch selection

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

@@ -76,7 +76,7 @@ A related pattern: use the sidebar as an investigation surface. Start two or thr
 
 ### 5. A worktree per bug
 
-For a day of small fixes: one worktree per bug. Use `Cmd+N` to configure each worktree or `Cmd+Shift+N` to create one immediately from the default branch, merge each quickly so none drift. Close the worktree when the fix lands.
+For a day of small fixes: one worktree per bug. Use `Cmd+N` to configure each worktree or `Cmd+Shift+N` to create one immediately from the configured default base branch, merge each quickly so none drift. Close the worktree when the fix lands.
 
 ### 6. Multiple sessions on one branch
 

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

@@ -110,9 +110,9 @@ PR badges update automatically in the background. The active worktree refreshes
 2. Enter a branch name (or let Kilo generate one)
 3. Type your first message, then create the worktree
 
-A new git worktree is created from your current branch. The agent works in isolation — your main branch is unaffected.
+Kilo creates the worktree from the selected project's configured default base branch. In a multi-project workspace, the selected project determines this setting. An explicit base branch selected in the dialog takes precedence. If no default is configured, Kilo falls back to automatic detection of the repository's remote default branch. The agent works in isolation, so your main branch is unaffected.
 
-To create a worktree immediately from the default base branch, press `Cmd+Shift+N` (macOS) / `Ctrl+Shift+N` (Windows/Linux).
+To create a worktree immediately from the default base branch, press `Cmd+Shift+N` (macOS) / `Ctrl+Shift+N` (Windows/Linux). This uses the selected project's configured default, or the automatic remote-default fallback when no configured default exists.
 
 ### Slash Commands in the Worktree Prompt
 
@@ -232,6 +232,8 @@ Previewing only displays the proposed changes. It does not approve or deny the p
 
 Press `Cmd+D` (macOS) / `Ctrl+D` (Windows/Linux) to toggle the diff panel. It shows a live-updating diff between the worktree and its parent branch.
 
+The worktree creation base and the diff comparison base are separate. The Branch scope starts with the worktree's recorded parent branch, and its base-branch picker changes only the comparison target. It does not change the branch from which the worktree was created.
+
 - Select files and click **Apply to local** to copy the worktree's changes onto your local checkout of the base branch
 - Conflicts are surfaced with a resolution dialog
 - Supports unified and split diff views
@@ -442,6 +444,7 @@ Closing a managed worktree removes it from Agent Manager, deletes its `.kilo/wor
 
 - **"Please open a folder…" error** — the Agent Manager requires a VS Code workspace folder
 - **Worktree creation fails** — ensure Git is installed and the workspace is a valid git repository. Open the main repository (where `.git` is a directory), not an existing worktree checkout.
+- **A configured base branch is missing** — Kilo clears the stale project setting and uses automatic remote-default detection for the new worktree. Select the project and configure a new default if needed.
 - **Provider or authentication errors** — open extension Settings and verify your sign-in, provider, model, or BYOK configuration. Agent Manager uses the same settings as the sidebar.
 - **Session history missing cloud sessions** — sign in through the extension and confirm the repository remote matches the sessions you expect to see.
 - **PR badges or PR import missing** — install and authenticate the GitHub CLI (`gh`). This is only required for GitHub PR features.