command-code 1.46.0 → 1.47.1

package/dist/bundled/command-code-knowledge/reference/sessions.md

@@ -8,9 +8,9 @@ Every conversation you have with Command Code is a **session**: a durable transc
 
 ## What is a session?
 
-A session is a single append-only **JSONL file** — one JSON record per line. The first line is a header (session id, creation time, working directory); every line after it is an entry: your messages, the model's replies (with token usage and cost), model and effort changes, compaction summaries, and more.
+A session is a single append-only **JSONL file**, one JSON record per line. The first line is a header (session id, creation time, working directory); every line after it is an entry: your messages, the model's replies (with token usage and cost), model and effort changes, compaction summaries, and more.
 
-Entries form a **tree**, not just a list. Each entry points at its parent, so a session can hold multiple branches of the same conversation — this is what powers `/rewind`, `/tree`, and forking. The file itself is never rewritten in place: navigating history just moves a pointer, and new entries are appended.
+Entries form a **tree** rather than a flat list. Each entry points at its parent, so a session can hold multiple branches of the same conversation. This is what powers `/rewind`, `/tree`, and forking. The file itself is never rewritten in place: navigating history just moves a pointer, and new entries are appended.
 
 ### Where session files live
 
@@ -39,7 +39,7 @@ Alongside the transcript, a session can have sidecar files:
 /session-file
 ```
 
-`/session-file` prints the current session id and the absolute path of its transcript. In terminals that support hyperlinks the path is clickable. If you haven't sent a message yet you'll see a `(not created yet)` note — the transcript is created on the first save.
+`/session-file` prints the current session id and the absolute path of its transcript. In terminals that support hyperlinks the path is clickable. If you haven't sent a message yet you'll see a `(not created yet)` note; the transcript is created on the first save.
 
 ---
 
@@ -47,9 +47,9 @@ Alongside the transcript, a session can have sidecar files:
 
 Sessions are designed so you never lose committed work:
 
-- **Per-turn commit:** Every completed turn is appended to the transcript as it commits — not on exit. Kill the process mid-run and everything up to the last committed turn is on disk.
+- **Per-turn commit:** Every completed turn is appended to the transcript as it commits, not on exit. Kill the process mid-run and everything up to the last committed turn is on disk.
 - **A turn either commits or is lost:** There is no torn state: an interrupted turn simply doesn't make it into the file, and the session resumes cleanly from the previous commit.
-- **User messages survive failed turns:** If a turn dies on a model/API error, your message that opened it is still written to disk — so a session that errored on its very first turn still shows up in `/resume`.
+- **User messages survive failed turns:** If a turn dies on a model/API error, your message that opened it is still written to disk, so a session that errored on its very first turn still shows up in `/resume`.
 - **Empty sessions leave no file:** A brand-new session buffers in memory until the first assistant reply, so opening Command Code and quitting without a real exchange doesn't litter your session catalog.
 - **Torn files never block startup:** If a transcript is damaged, corrupted lines are skipped and the session still loads.
 
@@ -64,7 +64,7 @@ Sessions are designed so you never lose committed work:
 /clear
 ```
 
-`/clear` starts a new session with empty context. The previous session stays on disk, fully resumable with `/resume`. `/new` is an alias — same command, same menu row.
+`/clear` starts a new session with empty context. The previous session stays on disk, fully resumable with `/resume`. `/new` is an alias: same command, same menu row.
 
 ### At launch
 
@@ -91,12 +91,12 @@ cmd --no-session              # throwaway session, nothing written to disk
 /resume
 ```
 
-`/resume` (alias `/sessions`) opens the session picker — the same picker you get from `cmd -r` with no argument. It supports search, renaming (without leaving the picker), deleting sessions, and filtering by the git branch a session was started on. Forked sessions show their provenance (`fork of <parent>`), and the session you're currently in is highlighted and can't be deleted.
+`/resume` (alias `/sessions`) opens the session picker, the same picker you get from `cmd -r` with no argument. It supports search, renaming (without leaving the picker), deleting sessions, and filtering by the git branch a session was started on. Forked sessions show their provenance (`fork of <parent>`), and the session you're currently in is highlighted and can't be deleted.
 
 Two kinds of sessions are hidden from the picker:
 
-- **Headless (`cmd -p`) sessions** — they carry no title and stay out of the picker and `--continue`, but an exact session id still resumes them.
-- **In-memory (`--no-session`) sessions** — they were never written to disk.
+- **Headless (`cmd -p`) sessions** carry no title and stay out of the picker and `--continue`, but an exact session id still resumes them.
+- **In-memory (`--no-session`) sessions** were never written to disk.
 
 ### At launch
 
@@ -149,7 +149,7 @@ Three commands let one conversation become many. They differ in **what comes wit
              in the tree you already have
 ```
 
-### `/fork [name]` — copy everything
+### `/fork [name]`: copy everything
 
 ```bash
 # In Command Code session
@@ -157,27 +157,27 @@ Three commands let one conversation become many. They differ in **what comes wit
 /fork payments-experiment
 ```
 
-`/fork` copies the **entire session** — the full tree with every branch, plus checkpoints and file backup history, so `/rewind` keeps working in the fork — into a new session and switches to it. The original is left untouched and resumable.
+`/fork` copies the **entire session** into a new session and switches to it. That means the full tree with every branch, plus checkpoints and file backup history, so `/rewind` keeps working in the fork. The original is left untouched and resumable.
 
 Lineage is recorded on the fork's meta: `parentSessionId` (the source session) and `branchPoint` (the stable message id of the last source message at the fork point), so the picker can render `fork of <parent>` provenance. Names are optional (up to 200 characters) and must be unique.
 
-### `/clone` — copy the current branch only
+### `/clone`: copy the current branch only
 
 ```bash
 # In Command Code session
 /clone
 ```
 
-`/clone` duplicates just the **active branch** of the conversation (from the current point back to the root) into a brand-new session file and switches into it. Unlike `/fork`, checkpoints and file history are deliberately not copied — a clone is "duplicate the conversation", and `/rewind` in the clone legitimately starts empty. The new file's header records the source transcript as its `parentSession`.
+`/clone` duplicates just the **active branch** of the conversation (from the current point back to the root) into a brand-new session file and switches into it. Unlike `/fork`, checkpoints and file history are deliberately not copied. A clone is "duplicate the conversation", and `/rewind` in the clone legitimately starts empty. The new file's header records the source transcript as its `parentSession`.
 
-### `/tree` — browse the whole tree
+### `/tree`: browse the whole tree
 
 ```bash
 # In Command Code session
 /tree
 ```
 
-`/tree` opens the session-tree navigator: every branch of the session, not just the active one. From there you can jump to **any point** in the tree, fold segments, search, attach labels to entries, and cycle display filters (`default`, `no-tools`, `user-only`, `labeled-only`). When you navigate away from a branch, Command Code can generate a **branch summary** so the work you're leaving behind stays findable — you can confirm, customize, or skip the summary (and set a default in `/config`).
+`/tree` opens the session-tree navigator: every branch of the session, including inactive ones. From there you can jump to **any point** in the tree, fold segments, search, attach labels to entries, and cycle display filters (`default`, `no-tools`, `user-only`, `labeled-only`). When you navigate away from a branch, Command Code can generate a **branch summary** so the work you're leaving behind stays findable. You can confirm, customize, or skip the summary (and set a default in `/config`).
 
 ---
 
@@ -191,7 +191,7 @@ Lineage is recorded on the fork's meta: `parentSessionId` (the source session) a
 | `/status` | Show comprehensive environment status |
 | `/trace` | Copy the current OpenTelemetry trace id (for support); works mid-turn, and persisted trace ids survive resume |
 
-Names must be unique within a project — renaming to a taken name is rejected. The name also becomes your terminal tab title, and it's what `-r <name>` resolves.
+Names must be unique within a project; renaming to a taken name is rejected. The name also becomes your terminal tab title, and it's what `-r <name>` resolves.
 
 ---
 
@@ -219,39 +219,39 @@ Each row in the selector shows when the checkpoint was taken, a preview of the m
 
 Checkpoints with no file changes only offer **Conversation only**.
 
-Rewinding removes the messages after the checkpoint **and the checkpoint itself** — you land *before* the message that opened it. The context token count updates to reflect the shorter conversation.
+Rewinding removes the messages after the checkpoint **and the checkpoint itself**. You land *before* the message that opened it. The context token count updates to reflect the shorter conversation.
 
-Rewinds persist. If you rewind and then quit, the rewound state is what you'll see when you resume the session later — it isn't a preview.
+Rewinds persist. If you rewind and then quit, the rewound state is what you'll see when you resume the session later. It isn't a preview.
 
 ### What a file rewind does to your working tree
 
-A **Code only** or **Both** rewind doesn't just undo edits — it puts the tree back the way it was:
+A **Code only** or **Both** rewind does more than undo edits. It puts the tree back the way it was:
 
 | If a file was… | After the rewind |
 | -------------- | ---------------- |
 | **Modified** after the checkpoint | Restored to its contents at the checkpoint |
-| **Created** after the checkpoint | **Deleted** — it didn't exist at the checkpoint |
+| **Created** after the checkpoint | **Deleted**, since it didn't exist at the checkpoint |
 | **Deleted** after the checkpoint | Restored |
 
-Backups are taken before each `write_file` or `edit_file` call and replayed newest-first, so a run of edits to the same file lands back on its oldest state. Backups are byte-faithful, so binary files (images, compiled artifacts) survive a backup–restore round-trip unchanged — no special handling needed.
+Backups are taken before each `write_file` or `edit_file` call and replayed newest-first, so a run of edits to the same file lands back on its oldest state. Backups are byte-faithful, so binary files (images, compiled artifacts) survive a backup–restore round-trip unchanged, with no special handling needed.
 
 ### Restores are verified before they run
 
-Command Code checks every backup in the set can actually be restored *before* writing anything, so a rewind either applies in full or not at all — it won't leave you half-restored. If a file can't be restored, you're told which one and why.
+Command Code checks every backup in the set can actually be restored *before* writing anything, so a rewind either applies in full or not at all; it won't leave you half-restored. If a file can't be restored, you're told which one and why.
 
 ### Limits and pausing
 
 Checkpoints are kept for **30 days**, capped at **200 backups per session**. Backups live in `~/.commandcode/file-history/<session-id>/`, and identical content is stored once no matter how many checkpoints reference it.
 
-File backups are capped at **10MB per file**. An oversized file is never read or backed up — and because it was never captured, a rewind **leaves it exactly as it is** rather than deleting it. Once a session hits the 200-backup cap, or 30 days pass, older checkpoints age out.
+File backups are capped at **10MB per file**. An oversized file is never read or backed up, and because it was never captured, a rewind **leaves it exactly as it is** rather than deleting it. Once a session hits the 200-backup cap, or 30 days pass, older checkpoints age out.
 
-If the disk runs low, checkpointing **pauses for the whole session** rather than silently degrading file by file, and you'll see a notice. Checkpoints already taken stay usable, and checkpointing resumes on its own — with a second notice — once enough space is free.
+If the disk runs low, checkpointing **pauses for the whole session** rather than silently degrading file by file, and you'll see a notice. Checkpoints already taken stay usable, and checkpointing resumes on its own, with a second notice, once enough space is free.
 
 ---
 
 ## Session scratchpad
 
-Each session gets a **scratchpad**: a per-session temporary workspace for intermediate files — analysis notes, throwaway scripts, generated data — that don't belong in your project.
+Each session gets a **scratchpad**, a per-session temporary workspace for intermediate files that don't belong in your project: analysis notes, throwaway scripts, generated data.
 
 ```text  theme={null}
 /tmp/commandcode-<uid>/<sanitized-cwd>/<session-id>/scratchpad
@@ -261,7 +261,7 @@ Each session gets a **scratchpad**: a per-session temporary workspace for interm
 - **Shared with sub-agents:** Every sub-agent in the session sees the same directory, so agents can hand intermediate results to each other by file name.
 - **Survives compaction:** After history compaction, a bounded metadata-only **manifest** of the scratchpad is re-injected, so the model remembers which working files still exist on disk without re-reading them.
 - **Follows launch-time forks:** Forking at launch with `--fork-session` copies the source session's scratchpad into the fork, so the branched conversation keeps its working files.
-- **Cleaned up with retention:** Scratchpads older than 30 days are swept, and deleting a session deletes its scratchpad. It's temp space — keep durable deliverables in the project itself.
+- **Cleaned up with retention:** Scratchpads older than 30 days are swept, and deleting a session deletes its scratchpad. It's temp space; keep durable deliverables in the project itself.
 
 The whole tree can be relocated with the `COMMANDCODE_SCRATCHPAD_BASE` environment variable. Provisioning is fail-open: if the scratchpad can't be created safely, the feature silently disables and the session runs normally without it.
 
@@ -277,14 +277,14 @@ Disable it entirely in `settings.json`:
 
 ## Sharing and exporting
 
-### `/share` — live share link
+### `/share`: live share link
 
 ```bash
 # In Command Code session
 /share
 ```
 
-`/share` uploads the conversation, copies a share URL to your clipboard, and — this is the key part — keeps the shared page **live**: every turn committed after sharing is streamed to the link automatically. Resuming a previously shared session re-arms the live updates. Run `/share` again to re-copy the existing link.
+`/share` uploads the conversation, copies a share URL to your clipboard, and keeps the shared page **live**: every turn committed after sharing is streamed to the link automatically. Resuming a previously shared session re-arms the live updates. Run `/share` again to re-copy the existing link.
 
 ```bash
 # In Command Code session
@@ -293,7 +293,7 @@ Disable it entirely in `settings.json`:
 
 `/unshare` deletes the share and stops the live updates.
 
-### `/share gist` — GitHub gist
+### `/share gist`: GitHub gist
 
 ```bash
 # In Command Code session
@@ -304,7 +304,7 @@ Disable it entirely in `settings.json`:
 
 `/share gist [html|jsonl|md]` renders the session and posts it as a **secret GitHub gist** via the `gh` CLI, then copies the gist URL. The default format comes from `/config`'s "Default share gist format" setting.
 
-### `/export` — write a file
+### `/export`: write a file
 
 ```bash
 # In Command Code session
@@ -315,7 +315,7 @@ Disable it entirely in `settings.json`:
 
 With no path, the file is written as `command-code-session-<first 8 chars of id>.<format>` using `/config`'s "Default export format" (`html` when unset). `jsonl` exports the raw transcript.
 
-### `/copy` — clipboard
+### `/copy`: clipboard
 
 ```bash
 # In Command Code session
@@ -330,7 +330,7 @@ With no path, the file is written as `command-code-session-<first 8 chars of id>
 
 When the conversation approaches the context limit, Command Code compacts history (automatically, or on `/compact`). Two guarantees matter for sessions:
 
-- **The on-disk log is never rewritten:** Compaction appends a compaction entry (the summary plus a pointer to the first entry kept verbatim) to the transcript tree. Your full history stays in the file — context building just reads through the compaction entry, and `/tree` can still reach everything.
+- **The on-disk log is never rewritten:** Compaction appends a compaction entry (the summary plus a pointer to the first entry kept verbatim) to the transcript tree. Your full history stays in the file; context building just reads through the compaction entry, and `/tree` can still reach everything.
 - **Savings persist across resumes:** Cumulative compaction stats (event count, total tokens saved, last event) are written to the session's meta on every compaction, so the "total this session" figure `/compact` reports survives `--resume`.
 
 ---
@@ -343,7 +343,7 @@ When the conversation approaches the context limit, Command Code compacts histor
 
 - **One picker, not two.** `/resume` and `/sessions` open the same unified picker rather than separate interactive/print views, so there's one mental model for "where are my sessions."
 - **Rewind is destructive on purpose, but reversible.** Restoring is instant and irreversible in the moment, but because it's just moving between checkpoints, you can rewind forward again if you change your mind.
-- **Print sessions are real sessions.** They're saved and resumable, just hidden from the picker by default — automation output doesn't have to mean throwaway state.
+- **Print sessions are real sessions.** They're saved and resumable, just hidden from the picker by default. Automation output doesn't have to mean throwaway state.
 
 ---
 
@@ -353,7 +353,7 @@ When the conversation approaches the context limit, Command Code compacts histor
 
 1. Ensure you've sent at least one message in the session
 2. Check if checkpointing is paused (you'll have seen a disk-space notice)
-3. Verify the session has file modifications — a checkpoint with no file changes only offers a conversation restore
+3. Verify the session has file modifications; a checkpoint with no file changes only offers a conversation restore
 
 ### Restore failed
 
@@ -371,11 +371,11 @@ When the conversation approaches the context limit, Command Code compacts histor
 
 ## Tips
 
-- **Name sessions you'll come back to:** `/rename auth-refactor` (or launch with `-n`) makes `cmd -r auth-refactor` a one-liner later — and a bare `/rename` will generate a decent title for you.
-- **Fork before risky experiments:** `cmd -c --fork-session` or `/fork` gives you a full copy — checkpoints included — while the original stays pristine.
+- **Name sessions you'll come back to:** `/rename auth-refactor` (or launch with `-n`) makes `cmd -r auth-refactor` a one-liner later, and a bare `/rename` will generate a decent title for you.
+- **Fork before risky experiments:** `cmd -c --fork-session` or `/fork` gives you a full copy, checkpoints included, while the original stays pristine.
 - **Use `/clone` to tidy up:** After heavy rewinding, `/clone` extracts just the branch you kept into a clean new session.
 - **Label important points in `/tree`:** Labels survive forks and make long trees navigable.
-- **Let the scratchpad absorb clutter:** Ask for throwaway scripts and intermediate outputs in the scratchpad — no permission prompts, no files polluting your repo, and it's cleaned up automatically.
+- **Let the scratchpad absorb clutter:** Ask for throwaway scripts and intermediate outputs in the scratchpad: no permission prompts, no files polluting your repo, and it's cleaned up automatically.
 - **`/share` before pairing:** The link updates live as the session continues, so a teammate can follow along in real time.
 - **Grab `/trace` when something breaks:** The trace id is what support needs, it's copyable mid-turn, and past ids survive a resume.
 
@@ -383,7 +383,7 @@ When the conversation approaches the context limit, Command Code compacts histor
 
 ## See also
 
-- [Headless Mode](./headless.md) — resuming and naming sessions from scripts and CI.
-- [Interactive Mode](https://commandcode.ai/docs/interactive-mode) — the full session experience.
-- [Context & Compaction](https://commandcode.ai/docs/context) — how history is summarized as it grows.
-- [Permissions](./permissions.md) — how permission decisions apply as you resume or fork a session.
+- [Headless Mode](./headless.md): resuming and naming sessions from scripts and CI.
+- [Interactive Mode](https://commandcode.ai/docs/interactive-mode): the full session experience.
+- [Context & Compaction](https://commandcode.ai/docs/context): how history is summarized as it grows.
+- [Permissions](./permissions.md): how permission decisions apply as you resume or fork a session.

package/dist/bundled/command-code-knowledge/reference/skills.md

@@ -20,7 +20,7 @@ Skills use **progressive disclosure** to manage context efficiently:
 
 1. **Discovery**: Command Code loads only the name, description, and file path of each skill at startup.
 2. **Activation**: When a task matches a skill or invoked directly with `/skill-name`, Command Code reads its full `SKILL.md` instructions.
-3. **Execution**: Command Code follows the instructions, optionally loading referenced files as needed
+3. **Execution**: Command Code follows the instructions, optionally loading referenced files as needed.
 
 This keeps Command Code fast while giving access to more context on demand.
 
@@ -622,7 +622,7 @@ allowed-tools: Read Bash(python:*)
 | `metadata`      | No       | Arbitrary key-value mapping for additional metadata (author, version, etc.).                                      |
 | `allowed-tools` | No       | Space-delimited list (or YAML array) of pre-approved tools the skill may use. (Experimental)                      |
 
-Command Code additionally honors these extension fields. Several mirror the Agent Skills / Claude Code frontmatter so a skill authored for another agent loads unchanged; tools that don't recognize a field ignore it safely:
+Command Code also honors these extension fields. Several mirror the Agent Skills / Claude Code frontmatter so a skill authored for another agent loads unchanged; tools that don't recognize a field ignore it safely:
 
 |            Field           | Required |                                                                Behavior                                                                 |
 | -------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |

package/dist/bundled/command-code-knowledge/reference/tools.md

@@ -40,12 +40,29 @@ Read a file as a bounded, line-numbered window. Read-only; never prompts.
 
 What it does beyond "read a file":
 
-- **Format-aware**: images (png/jpg/gif/webp/bmp/tiff) come back as real image blocks the model can see; Jupyter notebooks render as tagged cells with outputs; SVG reads as text; PDFs get a shell-extraction hint.
+- **Format-aware**: images come back as real image blocks the model can see; Jupyter notebooks render as tagged cells with outputs; Word, PowerPoint, Excel, OpenDocument, RTF, EPUB and PDF files are extracted to Markdown; SVG reads as text. The full list is below.
 - **Bounded by design**: 128 KB byte cap, 2000-line window, 2000-char per-line clamp - with truncation notes that embed the exact `offset` to continue from.
 - **Typo-tolerant**: on a miss it retries macOS filename variants (curly apostrophes, NFD normalization) and then suggests siblings ("Did you mean…?") using substring and edit-distance matching.
 - **Efficient**: memory-capped streaming reads, and re-reading an unchanged file returns a dedup stub instead of burning context.
 - **Honest about safety**: device and stream paths (`/dev/zero`, `/dev/stdin`, `/proc/<pid>/fd/*`, …) are blocked; every read is recorded in the session's read ledger, which the write tools check later.
 
+#### What it reads
+
+| Kind | Extensions | What comes back |
+| --- | --- | --- |
+| Text and code | anything not listed below, plus `.svg` and `.rtf` | Line-numbered text window (`offset`/`limit`, negative `offset` reads the tail). |
+| Images | `.png` `.jpg` `.jpeg` `.gif` `.webp` `.bmp` `.tiff` | The image itself, attached for vision-capable models (compressed, with the scale factor disclosed when downscaled). |
+| Jupyter notebooks | `.ipynb` | Tagged cells with their outputs; plots attached as images; oversized outputs replaced by a `jq` pointer. |
+| Word | `.docx` `.docm` `.doc` | Markdown: headings, lists, tables, windowed by `offset`/`limit` like text. |
+| PowerPoint | `.pptx` `.pptm` `.ppsx` `.ppsm` `.ppt` `.pps` `.pot` | Markdown per slide, speaker notes included. |
+| Excel | `.xlsx` `.xlsm` `.xlsb` `.xls` | Markdown tables per sheet. |
+| OpenDocument | `.odt` `.ods` `.odp` | Markdown, as for the Office equivalents. |
+| RTF, EPUB | `.rtf` `.epub` | Markdown. `.rtf` reads as plain text when no converter is available. |
+| PDF | `.pdf` | Markdown from the text layer. A scanned or image-only PDF says which pages have no text and gives the `pdftoppm` command to render them; reading the rendered pages attaches them as images. |
+| Other binary | `.zip` `.tar` `.gz` `.exe` `.dll` `.so` `.dylib` `.wasm` and other known binary types | A one-line note with the MIME type and size. Bytes are never loaded. |
+
+Document extraction runs through a native converter that is not shipped with the CLI. The first document read on a machine installs it (needs network, a second or two); every later read and every later session reuses it, and a new release upgrades it on the next read. Where it cannot be installed (offline, unsupported platform) the read falls back to the binary note above, and `.rtf` to plain text. Documents are read as a rendering, never as bytes, so `write_file` will not overwrite a `.docx` with the Markdown that came out of it.
+
 #### Multi-file reads
 
 Pass `paths` (or a single glob pattern in `file_path`) and the contents come back concatenated under `// File: <path> (<type>)` headers, preceded by a `Read X/Y files` summary:
@@ -54,11 +71,11 @@ Pass `paths` (or a single glob pattern in `file_path`) and the contents come bac
 {"paths": ["/repo/src/index.ts", "/repo/src/**/*.test.ts"]}
 ```
 
-`file_path` and `paths` are two separate fields on purpose rather than one union-typed field: providers translate JSON-Schema unions inconsistently — Gemini rejects a function declaration whose parameter sets `any_of` alongside `description`/`items`, failing the whole request. `paths` satisfies the schema's `file_path` requirement through the tool's `requiredAlternatives`, so a multi-file call needs no placeholder.
+`file_path` and `paths` are two separate fields on purpose rather than one union-typed field: providers translate JSON-Schema unions inconsistently: Gemini rejects a function declaration whose parameter sets `any_of` alongside `description`/`items`, failing the whole request. `paths` satisfies the schema's `file_path` requirement through the tool's `requiredAlternatives`, so a multi-file call needs no placeholder.
 
-Literal paths are read as named; glob patterns are filtered by `exclude`, the default exclusions and `.gitignore`. Binary files are noted with their type and size instead of being inlined. Per-file errors are reported inline and never fail the whole call; every match is boundary-checked individually (symlink and `..` escapes are dropped); and an aggregate ~100 KB cap (one tool-output budget) reports exactly which files were skipped, so a wide glob narrows instead of flooding the context.
+Literal paths are read as named; glob patterns are filtered by `exclude`, the default exclusions and `.gitignore`. Documents are extracted to Markdown (capped per file at 128 KB, with a hint to read the file alone for the rest); other binary files are noted with their type and size instead of being inlined. Per-file errors are reported inline and never fail the whole call; every match is boundary-checked individually (symlink and `..` escapes are dropped); and an aggregate ~100 KB cap (one tool-output budget) reports exactly which files were skipped, so a wide glob narrows instead of flooding the context.
 
-This absorbed the former `read_multiple_files` tool — one tool schema instead of two keeps roughly 540 tokens out of every request (~1,685 → ~1,147), and models no longer have to choose between two near-identical read tools. Calls that still arrive under the old name are rewritten to `read_file` (its `include` renames onto `paths`, and `targetDirectory` / `gitIgnore` / `defaultExclude` onto the merged schema's snake_case options), so nothing breaks mid-conversation.
+This absorbed the former `read_multiple_files` tool; one tool schema instead of two keeps roughly 540 tokens out of every request (~1,685 → ~1,147), and models no longer have to choose between two near-identical read tools. Calls that still arrive under the old name are rewritten to `read_file` (its `include` renames onto `paths`, and `targetDirectory` / `gitIgnore` / `defaultExclude` onto the merged schema's snake_case options), so nothing breaks mid-conversation.
 
 ### `read_directory`
 

package/dist/bundled/config/SKILL.md

@@ -13,6 +13,6 @@ Use the deterministic CLI instead of editing settings files by hand.
 4. For writes, choose the explicit `user` or `project` scope supported by the setting — the `scope` column in [settings.md](references/settings.md) says which one each takes. Never guess a scope.
 5. Report the previous value, new value, and written scope.
 
-A running session adopts the change at the start of its next round, so report the write as applied without claiming the live session already reloaded it.
+A running session adopts most changes at the start of its next round, so report the write as applied without claiming the live session already reloaded it. The exception is `model`: a running session keeps its current model, so a `model` write is the default for new sessions and takes effect in the running session only after a `/model` switch or a restart. For a live model change in the current session, use `/model <id>` instead.
 
 Never hand-edit invalid JSON or invent a setting key.

package/dist/bundled/config/references/settings.md

@@ -6,7 +6,7 @@ The executable registry is authoritative. Run `cmd config list --scope effective
 
 | Key | Scope | Type | Values | Description |
 | --- | --- | --- | --- | --- |
-| `model` | user | string | known model id | The default main-loop model. A long-lived host may also apply the change to its current session. |
+| `model` | user | string | known model id | The default main-loop model for new sessions. A running session keeps its current model. Use /model to change the running session. |
 | `permissions.defaultMode` | user | enum | `default`, `plan`, `auto-accept`, `dont-ask` | Default permission mode for tool usage. A long-lived host may also apply the change to its current session. "bypass" cannot be set here. |
 | `theme` | user | enum | `dark`, `light`, `auto` | Terminal color theme (same setting as /theme). Auto automatically detects your terminal background and uses light or dark to match. |
 | `compact-mode` | user | enum | `default`, `fast` | Auto-compact aggressiveness when context fills up (same setting as /compact-mode). |

package/dist/bundled/mod-builder/reference/overview.md

@@ -236,8 +236,8 @@ Embedders wire the same machinery directly: `createModHost` + `loadMods` + `crea
 
 The rest of this page is the complete reference, in order:
 
-- [ModApi reference](./api.md#mod-api-reference) — every field, registration verb, and live method.
-- [Hooks and events](./hooks-and-events.md#hooks-and-events) — the mutating lifecycle, the `AgentEvent` catalog.
-- [UI surface](./ui.md#ui-surface) — dialogs, footer status, editor widgets, custom feed rendering.
-- [Packaging and install](./packaging.md#packaging-and-install) — `cmd mods add`, manifests, filtering, scopes.
-- [Verify a mod](./verify.md#verify-a-mod) — load it, list it, test it, ship it.
+- [ModApi reference](./api.md#mod-api-reference): every field, registration verb, and live method.
+- [Hooks and events](./hooks-and-events.md#hooks-and-events): the mutating lifecycle, the `AgentEvent` catalog.
+- [UI surface](./ui.md#ui-surface): dialogs, footer status, editor widgets, custom feed rendering.
+- [Packaging and install](./packaging.md#packaging-and-install): `cmd mods add`, manifests, filtering, scopes.
+- [Verify a mod](./verify.md#verify-a-mod): load it, list it, test it, ship it.

package/dist/bundled/mod-builder/reference/verify.md

@@ -38,9 +38,9 @@ Run rm -rf /tmp/scratch-dir
 
 Expected result:
 
-- ✅ The mod's confirm dialog appears before the shell command runs
-- ✅ Declining blocks the tool - the model sees the block reason and adapts
-- ❌ No `tool_running` fires for the blocked call
+-  The mod's confirm dialog appears before the shell command runs
+-  Declining blocks the tool - the model sees the block reason and adapts
+-  No `tool_running` fires for the blocked call
 
 ## 4. Iterate with /reload