@maincode-ai/matilda-code 0.21.13 → 0.22.0-nightly.20261101.b0ad315a4

package/bundled/mainy/docs/features/tips.md

@@ -1,54 +0,0 @@
-# Contextual Tips
-
-Matilda Code includes a contextual tips system that helps you discover features and stay aware of session state.
-
-## Startup Tips
-
-Each time you launch Matilda Code, a tip is shown in the header area. Tips are selected by priority first, then rotated across sessions using LRU (least-recently-used) scheduling among tips of the same priority, so you see a different tip each time.
-
-New users see onboarding-focused tips during their first sessions:
-
-| Sessions | Example tips                                            |
-| -------- | ------------------------------------------------------- |
-| < 5      | Slash commands (`/`), Tab autocomplete                  |
-| < 10     | `MATILDA.md` project context, `--continue` / `--resume` |
-| < 15     | Shell commands with `!` prefix                          |
-
-After that, tips rotate through general features like `/compress`, `/approval-mode`, `/insight`, `/btw`, and more.
-
-## Post-Response Tips
-
-During a conversation, Matilda Code monitors your context window usage and shows tips when action may be needed:
-
-| Context usage | Condition                      | Tip                                               |
-| ------------- | ------------------------------ | ------------------------------------------------- |
-| 50-80%        | After a few prompts in session | Suggests `/compress` to free up context           |
-| 80-95%        | —                              | Warns context is getting full                     |
-| >= 95%        | —                              | Urgent: run `/compress` now or `/new` to continue |
-
-Post-response tips have per-tip cooldowns to avoid being repetitive.
-
-## Tip History
-
-Tip display history is persisted at `~/.matilda/tip_history.json`. This file tracks:
-
-- Session count (used for new-user tip selection)
-- Which tips have been shown and when (used for LRU rotation and cooldown)
-
-You can safely delete this file to reset tip history.
-
-## Disabling Tips
-
-To hide all tips (both startup and post-response), set `ui.hideTips` to `true` in `~/.matilda/settings.json`:
-
-```json
-{
-  "ui": {
-    "hideTips": true
-  }
-}
-```
-
-You can also toggle this in the settings dialog via the `/settings` command.
-
-Tips are also automatically hidden when screen reader mode is enabled.

package/bundled/mainy/docs/features/token-caching.md

@@ -1,29 +0,0 @@
-# Token Caching and Cost Optimization
-
-Matilda Code automatically optimizes API costs through token caching when using API key authentication. This feature stores frequently used content like system instructions and conversation history to reduce the number of tokens processed in subsequent requests.
-
-## How It Benefits You
-
-- **Cost reduction**: Less tokens mean lower API costs
-- **Faster responses**: Cached content is retrieved more quickly
-- **Automatic optimization**: No configuration needed - it works behind the scenes
-
-## Token caching is available for
-
-- API key users (Matilda API key, OpenAI-compatible providers)
-
-## Monitoring Your Savings
-
-Use the `/stats` command to see your cached token savings:
-
-- When active, the stats display shows how many tokens were served from cache
-- You'll see both the absolute number and percentage of cached tokens
-- Example: "10,500 (90.4%) of input tokens were served from the cache, reducing costs."
-
-This information is only displayed when cached tokens are being used, which occurs with API key authentication but not with OAuth authentication.
-
-## Example Stats Display
-
-![Matilda Code Stats Display](https://img.alicdn.com/imgextra/i3/O1CN01F1yzRs1juyZu63jdS_!!6000000004609-2-tps-1038-738.png)
-
-The above image shows an example of the `/stats` command output, highlighting the cached token savings information.

package/bundled/mainy/docs/features/tool-use-summaries.md

@@ -1,178 +0,0 @@
-# Tool-Use Summaries
-
-Matilda Code can generate a short, git-commit-subject-style label after each tool batch completes, summarizing what the batch accomplished. The label appears inline in the transcript and replaces the generic `Tool × N` header in compact mode.
-
-This is a UX aid for parallel tool calls: when the model fans out into several `Read` + `Grep` + `Bash` calls at once, the summary tells you the intent at a glance instead of forcing you to scan the tool list.
-
-The feature is enabled by default and runs silently in the background. It requires a configured [fast model](./followup-suggestions#fast-model).
-
-## What You See
-
-### Full mode (default)
-
-The summary appears as a dim badge line directly below the tool group:
-
-```
-╭──────────────────────────────────────────────╮
-│ ✓  ReadFile a.txt                            │
-│ ✓  ReadFile b.txt                            │
-│ ✓  ReadFile c.txt                            │
-│ ✓  ReadFile d.txt                            │
-╰──────────────────────────────────────────────╯
-
- ● Read 4 text files
-```
-
-### Compact mode (`Ctrl+O` or `ui.compactMode: true`)
-
-The label replaces the generic `Tool × N` header in the compact one-liner:
-
-```
-╭──────────────────────────────────────────────╮
-│✓  Read txt files  · 4 tools                  │
-│Press Ctrl+O to show full tool output         │
-╰──────────────────────────────────────────────╯
-```
-
-The individual tool calls are still a keystroke away (`Ctrl+O` to toggle to full mode).
-
-## How It Works
-
-After a tool batch finalizes, Matilda Code fires a fire-and-forget call to the configured fast model with:
-
-- The tool names, truncated arguments, and truncated results (each capped at 300 characters).
-- The assistant's most recent text output (first 200 characters) as an intent prefix.
-- A system prompt instructing the model to return a past-tense, 30-character label in git-commit-subject style.
-
-The call runs in parallel with the next turn's API streaming, so its ~1s latency is hidden behind the main model's response. When the label resolves, it is appended to the transcript as a `tool_use_summary` entry.
-
-Example labels: `Searched in auth/`, `Fixed NPE in UserService`, `Created signup endpoint`, `Read config.json`, `Ran failing tests`.
-
-## When It Appears
-
-The summary is generated when **all** of the following are true:
-
-- `experimental.emitToolUseSummaries` is `true` (default).
-- A `fastModel` is configured (via settings or `/model --fast`).
-- At least one tool completed in the batch.
-- The turn was not aborted before tool completion.
-- The fast model returned a non-empty, non-error response.
-
-Subagent tool calls do not trigger summary generation — only the main session's tool batches do.
-
-## When It Doesn't Appear
-
-The summary is silently skipped (no error, no UI change) when:
-
-- No fast model is configured.
-- The fast model call fails, times out, or returns empty.
-- The model returned an obvious error-message-like string (e.g., `Error: ...`, `I cannot ...`) — filtered out by the client so the UI does not show misleading labels.
-- The turn was aborted (`Ctrl+C`) before the model finished.
-
-In all these cases, the tool group renders as it always has.
-
-## Fast Model
-
-The label is generated using the [fast model](./followup-suggestions#fast-model) — the same model you configure for prompt suggestions and speculative execution. Configure it via:
-
-### Via command
-
-```
-/model --fast matilda3-coder-flash
-```
-
-### Via `settings.json`
-
-```json
-{
-  "fastModel": "matilda3-coder-flash"
-}
-```
-
-When no fast model is configured, summary generation is skipped entirely — the feature has no effect until you set one up.
-
-## Configuration
-
-These settings can be configured in `settings.json`:
-
-| Setting                             | Type    | Default | Description                                                                                        |
-| ----------------------------------- | ------- | ------- | -------------------------------------------------------------------------------------------------- |
-| `experimental.emitToolUseSummaries` | boolean | `true`  | Master switch for summary generation. Turn off to disable the extra fast-model call.               |
-| `fastModel`                         | string  | `""`    | Fast model used for summary generation (shared with prompt suggestions). Required; no-op if empty. |
-
-### Environment override
-
-`MATILDA_CODE_EMIT_TOOL_USE_SUMMARIES` overrides the `experimental.emitToolUseSummaries` setting for the current session:
-
-- `MATILDA_CODE_EMIT_TOOL_USE_SUMMARIES=0` or `=false` — force off.
-- `MATILDA_CODE_EMIT_TOOL_USE_SUMMARIES=1` or `=true` — force on.
-- Unset — use the `experimental.emitToolUseSummaries` setting.
-
-### Example
-
-```json
-{
-  "fastModel": "matilda3-coder-flash",
-  "experimental": {
-    "emitToolUseSummaries": true
-  }
-}
-```
-
-## Scope & lifecycle
-
-Three points that tend to trip up a first read of this feature:
-
-1. **One generation per batch, shared by both display modes.** The fast-model call happens exactly once in `handleCompletedTools` when a tool batch finalizes. Toggling `Ctrl+O` afterwards does **not** trigger a new call — both modes read from the same `tool_use_summary` history entry that was captured the first time. You can flip compact mode on and off freely without extra cost.
-2. **No backfill on toggle or on session resume.** A `tool_group` that completed before the feature was enabled (or before you flipped the setting on, or in a resumed session — `ChatRecordingService` does not persist summary entries) will never get a label. There is no "sweep existing history" pass. If you turn this setting on mid-session, only _future_ batches will show a label; older groups keep the default rendering with no indicator that a label is missing.
-3. **Main-agent batches only.** The trigger lives in the main session's turn loop (`useGeminiStream`), so:
-   - ✅ Shell, MCP, file operations, and the `Task` / subagent tool _call itself_ (as it appears in the main batch) are summarized.
-   - ❌ A subagent's **internal** tool batches (run through `packages/core/src/agents/runtime/`) are not summarized.
-
-   An outer batch that _contains_ a `Task` tool will still be labeled, but the fast model sees only the subagent tool call and its aggregated output — not the individual tool calls inside the subagent. Expect labels like `Ran research-agent` or `Delegated file search` rather than `Searched 14 files`. This is intentional — summarizing subagent internals would multiply the fast-model cost and surface noise that never shows up in the primary UI.
-
-## Recommended pairing: enable compact mode
-
-For batches of 3+ parallel tool calls, pairing this feature with `ui.compactMode: true` produces the cleanest transcript. The compact view folds the whole batch into a single labeled row (`✓  Read txt files  · 4 tools`) instead of showing every tool line plus the trailing summary. Details remain one keystroke away via `Ctrl+O`.
-
-```json
-{
-  "fastModel": "matilda3-coder-flash",
-  "ui": {
-    "compactMode": true
-  },
-  "experimental": {
-    "emitToolUseSummaries": true
-  }
-}
-```
-
-In full mode (the default), the summary renders as a trailing `● <label>` line below the tool group — useful for large or heterogeneous batches, but for small same-type batches (e.g. `Read × 3`) the label can read as a restatement of the visible tool lines. If that matches your usual workflow, either turn compact mode on as above, or turn the summary off entirely via `experimental.emitToolUseSummaries: false`.
-
-## Monitoring
-
-Summary model usage appears in `/stats` output under the fast-model token totals, with the `prompt_id` `tool_use_summary_generation` so it can be distinguished from prompt suggestions and other background tasks.
-
-## Data flow & privacy
-
-The summary call sends each successful tool's name, truncated `args`, and truncated result (each field capped at 300 characters) to the **fast model**, plus the first 200 characters of the assistant's most recent text as an intent prefix.
-
-If your fast model is configured for the same provider/auth as your main session model, the data flows along the same boundary your main session already uses — no change in trust scope. If you have configured a fast model from a **different provider**, tool inputs and outputs (potentially including file contents read by `read_file`, command output from shell calls, or values surfaced through MCP tools) will be sent to that other provider as part of the summarization prompt. That is a strictly larger data-sharing scope than the main session alone.
-
-If this matters for your workflow, you have two clean options:
-
-- Configure `fastModel` to a model under the same provider as your main session, so the summary call doesn't cross any new auth/data boundary.
-- Disable the feature entirely with `experimental.emitToolUseSummaries: false` (or `MATILDA_CODE_EMIT_TOOL_USE_SUMMARIES=0`).
-
-The 300-character per-field cap limits exposure but does not eliminate it — secrets discovered in tool output during the cap window can still be sent. Treat the fast model's data boundary the same way you treat the main model's.
-
-## Cost
-
-One fast-model call per qualifying tool batch. Input is a small fixed system prompt plus the truncated tool inputs/outputs (each capped at 300 characters per field). Output is a single short line (capped at 100 characters, typically 20 tokens or fewer). On a typical fast model this is roughly $0.001 per batch.
-
-If you do not want the extra cost, turn the feature off via `experimental.emitToolUseSummaries: false` or `MATILDA_CODE_EMIT_TOOL_USE_SUMMARIES=0`.
-
-## Related
-
-- [Compact Mode](../configuration/settings#ui.compactMode) — toggle with `Ctrl+O`; the summary replaces the generic tool-group header when compact mode is on.
-- [Followup Suggestions](./followup-suggestions) — another fast-model-driven UX enhancement that shares the same `fastModel` setting.

package/bundled/mainy/docs/features/worktree.md

@@ -1,343 +0,0 @@
-# Worktrees
-
-> Isolate experimental work in a temporary [git worktree](https://git-scm.com/docs/git-worktree) without leaving your current session. Useful when the model is about to make wide-ranging edits you want to keep separate from your main checkout, or when you want a subagent to work in a sandbox of its own.
-
-## Quick Start
-
-### Start the session inside a worktree (`--worktree` flag)
-
-If you know up front that the entire session should run inside a worktree, pass `--worktree` at launch:
-
-```bash
-# Auto-generated slug (e.g. tender-jemison-037f0a)
-matilda --worktree
-
-# Explicit name
-matilda --worktree my-feature
-
-# `=` form (recommended when also passing a positional prompt — see tip below)
-matilda --worktree=my-feature
-
-# PR reference — fetches refs/pull/<N>/head from `origin`
-matilda --worktree=#4174
-matilda --worktree https://github.com/MaincodeHQ/matilda-code/pull/4174
-
-# Continue a previous --worktree session — re-attaches to the existing dir
-matilda --resume <session-id> --worktree=my-feature
-```
-
-> **Tip — bare `--worktree` followed by a positional prompt is ambiguous.** Because `--worktree` takes an optional value, `matilda --worktree "say hi"` makes yargs consume `"say hi"` as the slug (and reject it because of the space). Use one of:
->
-> - `matilda --worktree=my-feature "say hi"` (always works — explicit slug via `=`)
-> - `matilda "say hi" --worktree` (positional first, flag at the end → auto slug)
-> - `matilda --worktree --approval-mode yolo "say hi"` (any flag between them anchors the bare form)
-
-> **Tip — `matilda --resume --worktree foo` (no session ID) shows an empty picker on first use.** The picker scopes to the chosen worktree's session storage; sessions started outside that worktree are not listed. To resume a session that was started inside `foo`, use `matilda --resume <id> --worktree foo` directly — the CLI re-attaches to the existing `foo/` directory rather than re-creating it.
-
-`process.cwd()` and the model's workspace are switched to the worktree before the first turn runs. Exit with `Ctrl+C` twice and the [Exit Dialog](#exit-dialog-ctrlc--ctrld) prompts to keep or remove the worktree.
-
-The `--worktree` flag cannot be combined with `--acp`/`--experimental-acp` — for ACP hosts (like Zed), pass the worktree path as the `cwd` of the `loadSession`/`newSession` request instead.
-
-### Or ask mid-session
-
-Alternatively, ask Matilda Code in plain language to create a worktree from inside an existing session:
-
-```text
-> start a worktree called experiment-a
-Worktree experiment-a created on branch worktree-experiment-a
-.matilda/worktrees/experiment-a
-```
-
-From this point on, the model routes every file edit and shell command through `.matilda/worktrees/experiment-a/`. Your original working directory is untouched.
-
-When you are done:
-
-```text
-> exit the worktree and remove it
-Removed worktree experiment-a (branch worktree-experiment-a)
-```
-
-If you want to come back later, ask to exit with the worktree kept on disk instead:
-
-```text
-> exit the worktree but keep it
-Kept worktree experiment-a at .matilda/worktrees/experiment-a
-```
-
-## When Worktrees Are Used
-
-Worktrees are activated in four independent paths:
-
-| Trigger                                         | What happens                                                                                                                   |
-| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| You launch with `--worktree`                    | The CLI creates the worktree before any model turn runs and chdirs the session into it. PR forms (`#N`, full URL) fetch first. |
-| You explicitly ask for a worktree mid-session   | Model calls `enter_worktree`; subsequent file edits go inside it.                                                              |
-| You explicitly ask to leave                     | Model calls `exit_worktree` with `keep` or `remove`.                                                                           |
-| Model spawns a sub-agent with isolation enabled | A throwaway worktree (`agent-<hex>`) is created automatically and cleaned up if the agent has no diffs.                        |
-
-The two mid-session tools (`enter_worktree` / `exit_worktree`) are deliberately gated behind explicit phrasing — saying "fix this bug" or "create a branch" will **not** trigger them. You must say something like "use a worktree", "start a worktree", or "in a worktree". The `--worktree` CLI flag has no such guard; it always creates one when present.
-
-## What Gets Created
-
-Every Matilda-managed worktree is placed under your project's `.matilda` directory:
-
-```
-<repoRoot>/.matilda/worktrees/<slug>/         # Working directory
-                          ↳ branch worktree-<slug>   # Created off your current branch
-```
-
-- **Slug** — letters, digits, dot, underscore, hyphen; max 64 chars. If you don't specify a name, an `<adjective>-<noun>-<6hex>` slug is auto-generated (e.g. `tender-jemison-037f0a`). PR references produce `pr-<N>`.
-- **Branch** — always `worktree-<slug>`, branched from whichever branch you have checked out when you ask for the worktree (not necessarily the main working tree's `HEAD`). For PR worktrees the branch is `worktree-pr-<N>` and is based on `FETCH_HEAD` (the PR's tip on the GitHub side) rather than your local branch.
-- **Hooks** — the worktree's `core.hooksPath` is automatically pointed at the main repo's `.husky/` (preferred) or `.git/hooks/` so commits inside the worktree still trigger your existing pre-commit / commit-msg hooks.
-- **Optional symlinks** — directories listed in `worktree.symlinkDirectories` (see [Settings](#settings)) are symlinked from the main repo into the new worktree so heavy dirs like `node_modules` can be reused without reinstalling.
-
-The general-purpose worktree path is **not configurable** — it must live under `<repoRoot>/.matilda/worktrees/` so the CLI can find it on restart and on stale-cleanup sweeps. (The unrelated `agents.arena.worktreeBaseDir` setting controls only [Agent Arena](./arena.md) worktrees, which use a separate path tree under `~/.matilda/arena/`.)
-
-## Footer and Status Line
-
-When a worktree is active, the Footer shows a dim indicator on its own row:
-
-```
-⎇ worktree-experiment-a (experiment-a)
-```
-
-If you use a [custom status line script](./status-line.md), it also receives a `worktree` object in the JSON payload piped to stdin:
-
-```json
-{
-  "worktree": {
-    "name": "experiment-a",
-    "path": "/path/to/repo/.matilda/worktrees/experiment-a",
-    "branch": "worktree-experiment-a",
-    "original_cwd": "/path/to/repo",
-    "original_branch": "main"
-  }
-}
-```
-
-The payload field is present **only** when a worktree is active, so a `null`-check (`input.worktree?.name`) is enough.
-
-If your custom status line already renders worktree info, you can hide the built-in Footer row to avoid duplication — see [Settings](#settings) below.
-
-## Exit Dialog (Ctrl+C / Ctrl+D)
-
-Pressing the quit shortcut twice while a worktree is active opens the **Worktree Exit Dialog** instead of closing the CLI:
-
-```
-⎇ Active worktree: "experiment-a" (worktree-experiment-a)
-
-  • 2 new commit(s) on worktree-experiment-a
-  • 3 uncommitted file(s)
-  Removing the worktree will discard everything above.
-
-What would you like to do?
-  ○ Keep worktree (exit without deleting)
-  ○ Remove worktree and branch (discards 2 commit(s), 3 file(s))
-  ○ Cancel (stay in session)
-```
-
-The dialog inspects the worktree on open (`git status --porcelain` + `git rev-list <baseHEAD>..HEAD`) and surfaces both counts so you know exactly what you'd be discarding. `ESC` cancels.
-
-If `git status` itself fails (e.g. corrupt index, worktree directory was removed under the CLI), the dialog shows a `⚠ Could not measure worktree state` warning and the counts may be unreliable — choose **Keep** or **Cancel** until you've diagnosed the underlying repo problem.
-
-## `--resume` Restore
-
-The active worktree binding is persisted to a sidecar file alongside your session transcript:
-
-```
-<chatsDir>/<sessionId>.worktree.json
-```
-
-When you launch the CLI with `--resume <sessionId>` (or pick the session from `/resume`), three things happen consistently across **interactive TUI**, **headless `-p`**, and **ACP/Zed** modes:
-
-1. The sidecar is loaded and the worktree directory is verified to still exist on disk.
-2. If alive, the model receives a one-shot reminder on its very next prompt:
-   ```
-   [Resumed] Active worktree: "<slug>" at <path> (branch: <branch>). Continue using this path for all file operations.
-   ```
-3. If the worktree directory was deleted between sessions, the stale sidecar is cleaned up automatically — no error, the resume just continues without worktree context.
-
-Each mode chooses its own injection mechanism, but the user-visible behavior is identical:
-
-| Mode              | Mechanism                                                                                              |
-| ----------------- | ------------------------------------------------------------------------------------------------------ |
-| Interactive (TUI) | `INFO` history item + system-reminder prefix on the next user prompt.                                  |
-| Headless (`-p`)   | `<system-reminder>` prefix on the prompt + `worktree_restored` JSON system event in the output stream. |
-| ACP (e.g. Zed)    | Pending notice attached to the next `prompt()` call.                                                   |
-
-The model is **not** automatically `chdir`'d into the worktree — the reminder is what keeps it routing edits through the worktree path.
-
-## Sub-Agent Isolation
-
-The `agent` tool accepts an optional `isolation: "worktree"` parameter. When set, Matilda Code creates an ephemeral worktree at `<repoRoot>/.matilda/worktrees/agent-<7hex>/` before the sub-agent starts, and:
-
-- **No changes** → the worktree is automatically removed when the agent finishes.
-- **Has changes** → the worktree is preserved; its path and branch are appended to the agent's result, e.g.
-  ```
-  …agent output…
-  [worktree preserved: /path/to/.matilda/worktrees/agent-3f2a1b9 (branch worktree-agent-3f2a1b9)]
-  ```
-  Review the diff and merge or delete it manually.
-
-Two constraints:
-
-- `isolation: "worktree"` requires a `subagent_type` — forked sub-agents (no `subagent_type`) reuse the parent's full conversation context, so isolating them would split intent from working tree.
-- Background agents (`run_in_background: true`) work fine with isolation; the cleanup runs when the agent reports completion.
-
-### Automatic Stale Cleanup
-
-Ephemeral agent worktrees that survived a crash or `--no-cleanup` shutdown are reaped on every CLI startup, with conservative fail-closed rules:
-
-| Guard                                  | Behavior                                       |
-| -------------------------------------- | ---------------------------------------------- |
-| Slug must match `agent-<7hex>` pattern | Named worktrees you created are never touched. |
-| Directory `mtime` > 30 days            | Newer entries are skipped.                     |
-| Any uncommitted tracked change         | Skip the entry (don't delete).                 |
-| Any commit not reachable from a remote | Skip the entry (don't delete).                 |
-| Any error reading git state            | Skip the entry (don't delete).                 |
-
-Named user worktrees (`enter_worktree` slugs) are **never** auto-cleaned — you keep them around until you ask to remove them.
-
-## Safety Guards on `exit_worktree action="remove"`
-
-Three independent guards trigger before the directory and branch are deleted:
-
-1. **Session ownership** — each worktree carries a sidecar marker with the session ID that created it. A different session trying to remove it is refused with a clear error pointing at `git worktree remove` for the manual escape hatch.
-2. **Dirty working tree** — uncommitted tracked or untracked changes block removal. Pass `discard_changes: true` to override. (Bypass requires explicit user confirmation — `action: "remove"` is never auto-approved in AUTO_EDIT mode.)
-3. **Unmerged commits** — commits on `worktree-<slug>` that no other local branch or remote ref points at block removal unconditionally; there is no "discard commits" flag because losing committed work is rarely what users mean. Merge, push, or rename the branch elsewhere first.
-
-The same three guards apply to the `WorktreeExitDialog → Remove` button.
-
-## Settings
-
-Two settings shape the general-purpose worktree experience:
-
-| Key                               | Type       | Default     | Effect                                                                                                                                                                                                                                                                     |
-| --------------------------------- | ---------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ui.hideBuiltinWorktreeIndicator` | boolean    | `false`     | Hides the built-in `⎇ worktree-… (…)` Footer row. The `worktree` field is still delivered to custom status line scripts. Set to `true` only if your status line already renders the worktree — otherwise you lose all UI affordance.                                       |
-| `worktree.symlinkDirectories`     | `string[]` | `undefined` | Directories under the main repo to symlink into every general-purpose worktree on creation. Paths are relative to the repo root; absolute paths and any entry containing `..` are rejected. Missing sources and existing destinations are silently skipped (no overwrite). |
-
-Example:
-
-```jsonc
-// ~/.matilda/settings.json or <repo>/.matilda/settings.json
-{
-  "worktree": {
-    "symlinkDirectories": ["node_modules", ".turbo", "dist"],
-  },
-}
-```
-
-Applies to ALL worktree-creation paths: `--worktree` flag, `enter_worktree` tool, and `agent isolation: "worktree"`.
-
-Settings unrelated to general worktrees but worth knowing about:
-
-- `agents.arena.worktreeBaseDir` — controls **Agent Arena** worktree placement (default `~/.matilda/arena`). Does not affect general-purpose worktrees, which always live under `<repoRoot>/.matilda/worktrees/`.
-
-There is no schema for `worktree.sparsePaths` yet — that's a roadmap item (see [Limitations](#limitations)).
-
-## Tool Reference
-
-### `enter_worktree`
-
-```json
-{ "name": "experiment-a" }
-```
-
-| Field  | Type   | Required | Notes                                                                                      |
-| ------ | ------ | -------- | ------------------------------------------------------------------------------------------ |
-| `name` | string | no       | Slug. Letters, digits, dot, underscore, hyphen; max 64 chars. Auto-generated when omitted. |
-
-Refuses to run when:
-
-- The CLI is not in a git repository.
-- The current working directory is already inside `.matilda/worktrees/` (no nested worktrees).
-
-### `exit_worktree`
-
-```json
-{ "name": "experiment-a", "action": "remove", "discard_changes": false }
-```
-
-| Field             | Type                   | Required                              | Notes                                                              |
-| ----------------- | ---------------------- | ------------------------------------- | ------------------------------------------------------------------ |
-| `name`            | string                 | yes                                   | Must match the slug used in `enter_worktree`.                      |
-| `action`          | `"keep"` \| `"remove"` | yes                                   | `keep` preserves dir + branch; `remove` deletes both.              |
-| `discard_changes` | boolean                | only when `action="remove"` and dirty | Overrides the dirty-tree guard. Has no effect for `action="keep"`. |
-
-`action: "remove"` always prompts for confirmation, including under `AUTO_EDIT` approval mode — it is treated as a destructive shell operation, not an info-only tool.
-
-### `agent` — `isolation` parameter
-
-```json
-{
-  "subagent_type": "my-agent",
-  "description": "…",
-  "prompt": "…",
-  "isolation": "worktree"
-}
-```
-
-| Field       | Type         | Required | Notes                                                                                             |
-| ----------- | ------------ | -------- | ------------------------------------------------------------------------------------------------- |
-| `isolation` | `"worktree"` | no       | Runs the agent in a fresh `agent-<7hex>` worktree. Requires `subagent_type` to be set (no forks). |
-
-See [Sub-Agents](./sub-agents.md) for the rest of the agent tool reference.
-
-## CLI Reference
-
-### `--worktree [name | #N | url]`
-
-```bash
-matilda --worktree                                               # auto-generate slug
-matilda --worktree my-feature                                    # explicit slug
-matilda --worktree=my-feature                                    # = form
-matilda --worktree=#123                                          # PR reference
-matilda --worktree https://github.com/owner/repo/pull/123        # PR URL
-```
-
-| Input                         | Result                                                                                                                |
-| ----------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| Bare flag (no value)          | Auto slug `<adjective>-<noun>-<6hex>`, branch `worktree-<slug>`, base = current branch.                               |
-| Plain slug                    | Branch `worktree-<slug>`, base = current branch. Slug validation: letters/digits/dot/underscore/hyphen, max 64 chars. |
-| `#N` or `<github-url>/pull/N` | Slug `pr-<N>`, branch `worktree-pr-<N>`, base = `FETCH_HEAD` after `git fetch origin pull/<N>/head` (30s timeout).    |
-
-`--worktree` cannot be combined with `--acp` / `--experimental-acp`.
-
-When `--worktree` is combined with `--resume <session-id>`, the worktree wins: the resumed session's saved worktree (if any) is overridden and a stderr line + first-prompt reminder report the override.
-
-For interactive (TUI) and headless (`-p`) modes the worktree is automatically created and the session chdirs into it before the first turn.
-
-PR-fetch failure modes (exit code != 0, no worktree created):
-
-| Cause                         | Message excerpt                                            |
-| ----------------------------- | ---------------------------------------------------------- |
-| Missing `origin` remote       | `requires an "origin" remote that points at GitHub`        |
-| PR doesn't exist on origin    | `Failed to fetch PR #<N>: the PR does not exist on origin` |
-| 30s network timeout           | `Failed to fetch PR #<N>: timed out after 30s`             |
-| PR number out of range / zero | `Invalid PR number`                                        |
-
-## Limitations
-
-The following items are intentionally not implemented in the current phase:
-
-- **No sparse checkout.** Large monorepos check out the full tree. (`worktree.sparsePaths` is a roadmap item.)
-- **No tmux integration.** The CLI does not spawn worktree sessions in new tmux windows.
-- **Worktrees are separate "projects" for session storage.** Sessions started with `--worktree foo` are saved under that worktree's chats dir; to resume them later you must pass `--worktree foo` again. Sessions started without `--worktree` are saved under the main checkout and won't appear in the worktree's resume picker.
-- **No cross-slug session override.** `matilda --resume <sid> --worktree second` where `<sid>` was created with `--worktree first` will fail to find the session — sessions and worktrees are tightly bound by `projectHash(cwd)`. To switch worktrees on an existing session you must exit, then re-launch with the new `--worktree` and a fresh prompt. A future architectural change (anchoring storage at the repo root instead of `cwd`) would lift this constraint.
-- **Mid-session `enter_worktree` does NOT switch `process.cwd()` or `Config.targetDir`.** That tool uses the model-context-only convention (see [Sub-Agents](./sub-agents.md)). Only the startup `--worktree` flag actually switches the process working directory.
-- **Relative paths in other arg fields are resolved BEFORE the worktree chdir.** Path-taking flags (`--mcp-config`, `--openai-logging-dir`, `--json-file`, `--input-file`, `--telemetry-outfile`, `--include-directories`) are normalized to absolute paths against the launch cwd when `--worktree` is set. Other path-shaped argv fields not in this list still resolve against the worktree cwd — use absolute paths to be safe.
-
-## Troubleshooting
-
-**The Footer shows no worktree indicator even though I just created one.**
-Check that `ui.hideBuiltinWorktreeIndicator` is not set to `true`. Also confirm the slug is non-empty in the tool's success message.
-
-**`--resume` does not restore my worktree.**
-Check `<chatsDir>/<sessionId>.worktree.json` exists. The CLI deletes the sidecar automatically when the worktree directory is gone, so a missing sidecar plus a missing directory is the normal "no worktree to restore" state — not a bug. Run with `--debug` and grep for `restoreWorktreeContext` to see the reason.
-
-**`exit_worktree` says "created by a different session".**
-This is the session-ownership guard. Resume the original session and exit from there, or run the suggested `git worktree remove …` command manually.
-
-**Stale `agent-<hex>` worktrees keep piling up.**
-The 30-day cutoff is conservative; sweep manually with `git worktree list && git worktree remove <path>`, or wait — the next CLI startup after the 30-day mark will reap them as long as they are clean and pushed.

package/bundled/mainy/docs/ide-integration/_meta.ts

@@ -1,4 +0,0 @@
-export default {
-  'ide-integration': 'Introduction',
-  'ide-companion-spec': 'IDE Companion Spec',
-};