@cerebriline/core 4.100.255 → 4.100.256

package/assets/prompt-templates/deepseek.md

@@ -7,18 +7,28 @@ match:
 
 <!-- PROVENANCE -- written by scripts/review-prompt-templates.mts, not by the model.
 
-     Sections `read_files`, `editor`, `ask_question`, `check_file`, `spawn_agent` written by deepseek-v4.1-flash:cloud (Ollama family `deepseek_v41`) on 2026-09-23.
+     Sections `run_commands` written by deepseek-v4.1-flash:cloud (Ollama family `deepseek_v41`) on 2026-10-22.
      Every other section is as it was. Before this run:
 
-       Sections `grep`, `sed`, `awk`, `run_commands` written by deepseek-v4.1-flash:cloud (Ollama family `deepseek_v41`) on 2026-09-12.
+       Sections `apply_patch`, `awk`, `editor`, `fetch_web_content`, `grep`, `read_files`, `search_codebase`, `sed`, `check_file`, `run_commands` written by deepseek-v4.1-flash:cloud (Ollama family `deepseek_v41`) on 2026-10-22.
+       Every other section is as it was. Before this run:
 
-       Every other section is unchanged. Written by deepseek-v4.1-flash:cloud (Ollama family `deepseek_v41`) on 2026-09-12.
-       Run, with its log: prompt-reviews/regen/20260912-2324-deepseek-v4.1-flash-cloud
+         Sections `read_files`, `editor`, `ask_question`, `check_file`, `spawn_agent` written by deepseek-v4.1-flash:cloud (Ollama family `deepseek_v41`) on 2026-09-23.
+         Every other section is as it was. Before this run:
 
-     Run, with its log: prompt-reviews/regen/20260923-1647-deepseek-v4.1-flash-cloud
+           Sections `grep`, `sed`, `awk`, `run_commands` written by deepseek-v4.1-flash:cloud (Ollama family `deepseek_v41`) on 2026-09-12.
+
+           Every other section is unchanged. Written by deepseek-v4.1-flash:cloud (Ollama family `deepseek_v41`) on 2026-09-12.
+           Run, with its log: prompt-reviews/regen/20260912-2324-deepseek-v4.1-flash-cloud
+
+         Run, with its log: prompt-reviews/regen/20260923-1647-deepseek-v4.1-flash-cloud
+
+       Run, with its log: prompt-reviews/regen/20261022-0646-deepseek-v4.1-flash-cloud
+
+     Run, with its log: prompt-reviews/regen/20261022-0710-deepseek-v4.1-flash-cloud
 
      Sampler asked for by the generator, overriding the model's own:
-       temperature 0.7
+       temperature 0.2
 
      Sampler the tag sources (`/api/show`), which applies to every key
      the request above does not set:
@@ -102,35 +112,62 @@ Read the content of text or image files at the provided absolute paths, or retur
 
 Each read returns at most 2000 lines / ~47k characters; longer files report their total line count, so page through them with `start_line`/`end_line` on that file's entry. Reading a range is the normal case; reading a file whole is the exception. Locate first, then read: a diagnostic or a stack trace already names the line, `search_codebase` reports the line every match is on, and `ask_lsp` resolves a symbol to where it is defined. Any of those hands you a line number to read around — take roughly 30 lines either side of it, and widen only if what you needed turned out to fall outside that. Read a file entire only when you have no line to start from and it is genuinely small. The cost of reading more than you need is not the tool call: every line returned stays in the conversation for the rest of the task, crowding out the room left to reason about it. Binary files that are not images and very large files are not supported.
 
-Output: one object per requested file, in the order requested — `{query, result, success, error?}`, where a failed entry has `success: false` and the reason in `error`. `query` echoes the path you asked for (as `path:start-end` when you gave a range), and `result` is that file's content, with every line prefixed by its number as `  92 | text`. Those numbers are how you address an edit, and they are not in the file. Never paste them into another tool: text carrying a `92 | ` prefix will not match anything. When you are reading in order to copy text into `editor`, set `line_numbers: false` on that file's entry and get it clean.
+Output: one entry per requested file, in the order requested, each named by the path you asked for — as `path:start-end` when you gave a range — and holding that file's content with every line prefixed by its number as `  92 | text`. An entry that could not be read says it failed and gives the reason. Those numbers are how you address an edit, and they are not in the file. Never paste them into another tool: text carrying a `92 | ` prefix will not match anything. When you are reading in order to copy text into `editor`, set `line_numbers: false` on that file's entry and get it clean.
 
 # tool: search_codebase
-Regex search across the codebase. Pass an array of pattern strings. When several independent patterns are useful, send them together in one call. Use for finding code patterns, function definitions, class names, imports, etc. It reports one match per file by default; raise `max_per_file` to find every occurrence inside a file. `context_lines` sets lines shown either side of a match (default 2). Output beyond ~48k chars per query is middle-truncated; narrow patterns beat broad ones. Output: one object per pattern — `{query, result, success, error?}`. Failed entries have `success: false` with reason in `error`. `query` is the pattern, `result` is matching lines with file paths. A pattern that matched nothing has `success: true` with empty `result` — that is a definite answer, not a failure.
+
+Regex search across the codebase. Pass an array of pattern strings. When several independent patterns are useful, send them together in one call. Use for finding code patterns, function definitions, class names, imports, etc. It reports one match per file by default; raise `max_per_file` to find every occurrence inside a file. `context_lines` sets lines shown either side of a match (default 2). Output beyond ~48k chars per query is middle-truncated; narrow patterns beat broad ones.
+
+Output: one entry per pattern, named by the pattern you sent and holding the matching lines with their file paths. An entry that could not run says it failed and gives the reason. A pattern that matched nothing comes back empty rather than failed — that is a definite answer, and re-running it will not change it.
 
 # tool: fetch_web_content
-Fetch and analyze web content from URLs. Pass an array of `{url, prompt}` objects. Each request includes a URL and a prompt describing what information to extract. Fetch independent URLs together in one call. Use for documentation, API references, or any web content. Output: one object per request — `{query, result, success, error?}`. Failed entries have `success: false` with reason in `error`. `query` is the URL, `result` is extracted text.
+
+Fetch and analyze web content from URLs. Pass an array of `{url, prompt}` objects. Each request includes a URL and a prompt describing what information to extract. Fetch independent URLs together in one call. Use for documentation, API references, or any web content.
+
+Output: one entry per request, named by the URL you asked for, holding the text extracted from that page for your prompt. An entry that could not be fetched says it failed and gives the reason.
 
 # tool: editor
 
-An editor for controlled filesystem edits on the text file at the provided path. Which of the six operations you get is decided by which arguments you send:
+An editor for controlled filesystem edits on the text file at `file_path`. Which of the six operations you get is decided by which arguments you send:
 
 - Replace text: `old_text` plus `new_text`. When `old_text` occurs more than once, add `occurrence` (one-based, in file order) to pick one, or `replace_all: true` to change every one.
 - Replace lines: `start_line` plus `new_text`, with optional `end_line` (inclusive, defaults to `start_line`). No `old_text` needed. Prefer this when the text is long, minified or repeated: a diagnostic already gives you the line number, and a line number cannot be ambiguous. An empty `new_text` deletes the range.
-- Replace characters: `start_line` and `start_column` plus `new_text`, with optional `end_line`/`end_column` (both inclusive; each defaults to its start). This is the unit a diagnostic speaks in — `Line 108, column 385` — and on a long or minified line it is the only edit that leaves the other 400 characters untouched. `start_column` on its own replaces exactly one character.
+- Replace characters: `start_line` and `start_column` plus `new_text`, with optional `end_line`/`end_column` (both inclusive; each defaults to its start). This is the unit a diagnostic speaks in — `Line 12, column 640` — and on a long or minified line it is the only edit that leaves the other 400 characters untouched. `start_column` on its own replaces exactly one character.
 - Insert: `insert_line` plus `new_text`, which adds text before that line without replacing anything. Use `line_count + 1` to append at EOF. Add `insert_column` to insert *within* that line instead, before the character at that column — this is how you add one missing bracket. Use `line_length + 1` to append at the end of the line.
 - Create, or replace a file whole: `new_text` alone. When the file does not exist this creates it; when it exists this replaces every line, which is allowed once you have read the file, since reading it is what tells you what you are overwriting. `start_line: 1` with `end_line: <line count>` is the same write by another name. Neither has a size limit, because a file written whole cannot be split — but reach for a whole-file write only once a targeted edit has failed, since a rewrite that is slightly wrong quietly loses the parts you did not mean to touch. Never delete a file to get a clean slate: this call already is one, and a deleted file is simply gone if the turn ends before you write it back.
 
-Write the arguments in this order: `path` and every other short argument first — line and column numbers, `intent`, `task_progress`, `old_text` — and `new_text` last. The text you are writing is the long part of the call, and whatever is written after a long text is the part most easily left out.
+Write the arguments in this order: `file_path` and every other short argument first — line and column numbers, `intent`, `task_progress`, `old_text` — and `new_text` last. The text you are writing is the long part of the call, and whatever is written after a long text is the part most easily left out.
 Use this rather than a shell command for anything that changes a file. Make one edit at a time and check it before starting the next: reads and searches cost nothing if one turns out to be unnecessary, but several edits made together and checked once leave several things to undo and no way to tell which one was wrong.
 
 Read the lines you are about to change before you change them: an edit aimed at a range you have not read in its current state is refused. Your own edits count — one that changes the file's length moves every line below it, so read that region again before editing it a second time. Line numbers taken from an earlier turn, from a task summary, or from a diagnostic issued before your last edit are the ones that go stale.
 
 Repeating the lines already in the range and then continuing is how you insert after them, and it is allowed — the range says which lines you mean, so repeating them is your own choice. What is refused is a `new_text` that goes on to repeat lines from *outside* the range: that appends a second copy of text already elsewhere in the file rather than replacing anything, and the refusal names the lines it matched so you can aim the next call at them.
 
-Output: a single `{query, result, success, error?}` object for this one edit, where `query` is `edit:<path>` or `insert:<path>` and `result` describes what changed. A failed edit changes nothing: `success` is false, `error` says why, and the file is exactly as it was. Do not resend the same call — `error` names the fix. In particular, text copied out of a `read_files` result must have its `123 | ` line-number gutter removed first.
+Output: one entry for this one edit, named `edit:<path>` or `insert:<path>`, describing what changed. A failed edit changes nothing: the entry says it failed and why, and the file is exactly as it was. Do not resend the same call — the reason names the fix. In particular, text copied out of a `read_files` result must have its `123 | ` line-number gutter removed first.
 
 # tool: apply_patch
-Edit files using a canonical freeform patch grammar. Pass the patch text as the `input` string. Supported actions: `*** Add File: <path>`, `*** Update File: <path>`, `*** Delete File: <path>`, with optional `*** Move to: <new path>` after an Update header. In Add sections, every content line starts with `+`. In Update sections, use context lines plus `-` and `+` lines. Use `@@` markers for disambiguation. No line numbers — context-based. Prefer direct patch body; legacy `%%bash` and `apply_patch <<"EOF"` wrappers accepted but not preferred. Output: a single `{query, result, success, error?}` object covering the whole patch. `result` says which files were added, updated, moved or deleted. A patch that did not apply sets `success: false` with reason in `error` — re-read the file and rebuild from what is actually there.
+
+Edit files with the canonical freeform patch grammar. Pass the patch text as the `input` string — the patch body itself, not a shell command that would run it.
+
+```
+*** Begin Patch
+*** Update File: src/page.tsx
+@@
+   return (
+     <div>
+       <button onClick={() => console.log("clicked")}>Click me</button>
++      <button onClick={() => console.log("cancel clicked")}>Cancel</button>
+     </div>
+   );
+ }
+*** End Patch
+```
+
+The actions are `*** Add File: <path>`, `*** Update File: <path>` and `*** Delete File: <path>`, and an Update header may be followed immediately by `*** Move to: <new path>`. In an Add section every content line starts with `+`. In an Update section you describe the change with context lines plus `-` and `+` lines, and add `@@` markers when repeated code needs more context to tell one block from another. There are no line numbers anywhere: the format is context-based, so the context lines are what place the change.
+
+Send the patch body directly. The legacy wrappers — `%%bash`, `apply_patch <<"EOF"` — are accepted for compatibility, but they are not the preferred form.
+
+Output: one result covering the whole patch, saying which files were added, updated, moved or deleted. A patch that did not apply — usually because its context lines no longer match the file — comes back failed and says why. Do not resend it: re-read the file and rebuild the patch from what is actually there.
 
 # tool: ask_question
 
@@ -141,11 +178,16 @@ Mark the option you would pick: end it with ` (recommended)` and say why in one
 Output: the user's answer, as plain text — one of the options you offered, or whatever they wrote instead. Act on it in the same turn; the answer arriving is not a reason to stop.
 
 # tool: submit_and_exit
-Submit the final answer and exit the conversation. Call only when all necessary steps are completed. Verify output matches expected format, data types, and file locations. Provide a summary of what was done and confirm the issue is resolved. Output: a short confirmation as plain text. This call ends the run — nothing planned after it will execute.
+Submit the final answer and exit the conversation. Call only when all necessary steps are completed. Verify output matches expected format, data types, and file locations. Send `summary` — what was done and where it stands — and `verified`: `true` only when tool output from this session shows every requirement met, `false` when you have done what you can and it is not. Output: a short confirmation as plain text. This call ends the run — nothing planned after it will execute.
 
 # tool: run_commands
 
-Run shell commands in the working directory. Use for building, testing, running linters, installing dependencies, or any operation that needs a shell. Do not use for reading files (use read_files), searching code (use search_codebase, or grep when you want grep's own flags), or editing files (use editor, apply_patch, or sed when one mechanical change applies across many files). When several independent commands that do not depend on each other's output are needed, pass them all in one call as an array of strings — they run in order but you do not need to wait for one result before sending the next. Each command runs in its own shell; use `&&` or `;` to chain steps within one string. Output: one object per command — `{command, exitCode, stdout, stderr, success}`, where `success` is true when exitCode is 0. A non-zero exitCode is not a tool failure; it is the command's answer — read stdout and stderr to understand what happened. Long output is truncated; redirect to a file and read it with read_files if you need the full output.
+Run shell commands in the working directory. Use for building, testing, running linters, installing dependencies, or any operation that needs a shell. Do not use for reading files (use read_files), searching code (use search_codebase, or grep when you want grep's own flags), or editing files (use editor, apply_patch, or sed when one mechanical change applies across many files). When several independent commands that do not depend on each other's output are needed, pass them all in one call as an array of strings — they run in order but you do not need to wait for one result before sending the next. Each command runs in its own shell; use `&&` or `;` to chain steps within one string.
+
+`credentials` is an optional array of names of stored credentials to make available to the commands in this call, for commands that need a secret to run. Leave it out when nothing needs one.
+
+Output: one entry per command, named by the command string, holding its exit code, its stdout and its stderr. A command that exited non-zero is a failed entry: it comes back marked failed, with the exit code in its reason, and a text session sees it marked failed above the output. The output is still there to read — stdout and stderr are what the command printed before it exited, and they are usually the whole answer to why it failed. Long output is truncated; redirect to a file and read it with read_files if you need the full output.
+
 {{DEFAULT}}
 
 # tool: skills
@@ -167,7 +209,7 @@ Pass every file you want checked in one call.
 
 Read a clean result carefully. "No problems reported by the editor" is conclusive only where a language server covers that file, and it does not for every language on every machine. If this reports nothing where you have reason to expect a problem, or the project has a checker the language servers do not run, run that checker with `run_commands`. Tests and builds are always `run_commands`; this tool does not run them.
 
-Output: plain text, one section per file you named, each problem on its own line as `file:line:column` with its severity and message. A file with nothing wrong says so in one line. There is no object to unpack and no `success` field — problems being listed is this tool working, not failing.
+Output: plain text, one section per file you named, each problem on its own line as `file:line:column` with its severity and message. A file with nothing wrong says so in one line. There is no object to unpack and no success field — problems being listed is this tool working, not failing.
 
 When a file's brackets do not match, a `Delimiter scan` section names the line to edit and how many brackets that line is out by, one line per place the trouble starts — a file can be broken in several spots at once, so work through every line it lists before re-checking rather than re-checking after each one. A parse error is always reported where the parser gave up, which is the closing bracket; the line named here is the one the error cannot name. Trust those lines over counting brackets yourself — the scan skips strings, comments and regex literals, which counting characters does not. It runs whether or not the editor reported anything, so it can appear beneath a file the editor called clean — no language server checks the script inside an `.html` file, and there this is the only report you will get.
 
@@ -317,7 +359,7 @@ Other flags: `ignore_case`, `invert` (the lines that do *not* match), `word` (wh
 
 Reach for this to find where something is before you read or edit it: it is cheaper than reading whole files, and a match counts as having read those lines. It runs in-process rather than through the shell, so it needs no binary installed and behaves the same on every platform.
 
-Output: a single `{query, result, success, error?}`. `query` is `grep:<pattern>`; `result` holds the matching lines, each prefixed with its path and line number. A failed entry has `success: false` with the reason in `error`. A pattern that matched nothing is still `success: true`, with `result` saying so in words — that is an answer, and running the same search again will not change it.
+Output: one entry for the search, named `grep:<pattern>`, holding the matching lines each prefixed with its path and line number. An entry that could not run says it failed and gives the reason. A pattern that matched nothing has not failed — the entry says so in words, and that is an answer; running the same search again will not change it.
 
 # tool: sed
 
@@ -327,7 +369,7 @@ Without `in_place` it only prints the result, which is how you check a script be
 
 Choose this over `editor` when one mechanical change applies in many places or across many files — renaming an identifier everywhere, stripping a prefix from every line of a block. For a single considered change in one place, `editor` is the better tool: it can anchor on text you quote back, and it tells you when the file has moved under you. An in-place run is refused on a file you have not read, exactly as an `editor` call is, and a script addressed by line number is refused unless you have read those lines. Read first. It runs in-process rather than through the shell, so it needs no binary installed and behaves the same on every platform.
 
-Output: one object per file — `{query, result, success, error?}`. `query` is `sed:<file>`; `result` is that file's output, or a sentence saying what was written. A failed entry has `success: false` with the reason in `error`. The files do not share a fate: one may be written while the next is refused, so read every entry. `success: false` means that file was NOT touched, and `error` says why. A script that matched nothing is `success: true` — it ran, and that is its answer; running it again unchanged will not change it.
+Output: one entry per file, named `sed:<file>`, holding that file's output or a sentence saying what was written. An entry that could not run says it failed and gives the reason. The files do not share a fate: one may be written while the next is refused, so read every entry. A failed entry means that file was NOT touched, and it says why. A script that matched nothing has not failed — it ran, and that is its answer; running it again unchanged will not change it.
 
 # tool: awk
 
@@ -335,7 +377,7 @@ Run an `awk` program over one or more files. Send a `program` — `{print $1}`,
 
 This is the tool for questions about columns and totals, where grep would only hand you the lines and leave you to count them yourself: summing a column, pulling fields out of a delimited file, counting occurrences per key. It is read-only, and deliberately so — output redirection, pipes, `system()` and `getline` are refused rather than quietly ignored. Use `sed` or `editor` to change a file. It runs in-process rather than through the shell, so it needs no binary installed and behaves the same on every platform.
 
-Output: a single `{query, result, success, error?}`. `query` is `awk:<program>`; `result` is everything the program printed. A failed entry has `success: false` with the reason in `error`. A program that printed nothing is still `success: true` — that is the program's answer, not a failure.
+Output: one entry for the run, named by the program you sent as `awk:<program>`, holding everything the program printed. An entry that could not run says it failed and gives the reason. A program that printed nothing has not failed — silence is the program's answer, not an error.
 
 # tool: extract_document
 {{DEFAULT}}

package/assets/prompt-templates/default.md

@@ -49,35 +49,35 @@ If user asked a simple question without any coding context, answer it directly w
 {{CLINE_METADATA}}
 
 # tool: read_files
-Read the content of text or image files at the provided absolute paths, or return only an inclusive one-based line range when start_line/end_line are provided on the same file entry as its path. When you already know multiple files you need, read them together in one call, and call this tool in the same response as other independent tool calls. Each read returns at most 2000 lines / ~47k characters; longer files report their total line count, page through them with start_line/end_line on that file's entry. Reading a range is the normal case; reading a file whole is the exception. Locate first, then read: a diagnostic or a stack trace already names the line, `search_codebase` reports the line every match is on, and `ask_lsp` resolves a symbol to where it is defined. Any of those hands you a line number to read around — take roughly 30 lines either side of it, and widen only if what you needed turned out to fall outside that. Read a file entire only when you have no line to start from and it is genuinely small. The cost of reading more than you need is not the tool call: every line returned stays in the conversation for the rest of the task, crowding out the room left to reason about it. Binary files that are not image and large files are not supported. Output: one object per requested file, in the order requested — `{query, result, success, error?}`, where a failed entry has `success: false` and the reason in `error`. `query` echoes the path you asked for (as `path:start-end` when you gave a range), and `result` is that file's content, with every line prefixed by its number as `  92 | text`. Those numbers are how you address an edit, and they are not in the file. Never paste them into another tool: text carrying a `92 | ` prefix will not match anything. When you are reading in order to copy text into `editor`, set `line_numbers: false` on that file's entry and get it clean.
+Read the content of text or image files at the provided absolute paths, or return only an inclusive one-based line range when start_line/end_line are provided on the same file entry as its path. When you already know multiple files you need, read them together in one call, and call this tool in the same response as other independent tool calls. Each read returns at most 2000 lines / ~47k characters; longer files report their total line count, page through them with start_line/end_line on that file's entry. Reading a range is the normal case; reading a file whole is the exception. Locate first, then read: a diagnostic or a stack trace already names the line, `search_codebase` reports the line every match is on, and `ask_lsp` resolves a symbol to where it is defined. Any of those hands you a line number to read around — take roughly 30 lines either side of it, and widen only if what you needed turned out to fall outside that. Read a file entire only when you have no line to start from and it is genuinely small. The cost of reading more than you need is not the tool call: every line returned stays in the conversation for the rest of the task, crowding out the room left to reason about it. Binary files that are not image and large files are not supported. Output: one entry per requested file, in the order requested — each entry names what it answers, then what came back, and a failed entry says that it failed and why. An entry is named by the path you asked for (as `path:start-end` when you gave a range), and what came back is that file's content, with every line prefixed by its number as `  92 | text`. Those numbers are how you address an edit, and they are not in the file. Never paste them into another tool: text carrying a `92 | ` prefix will not match anything. When you are reading in order to copy text into `editor`, set `line_numbers: false` on that file's entry and get it clean.
 
 # tool: search_codebase
-Perform regex pattern searches across the codebase. Supports multiple parallel searches. When several search patterns could be useful and do not depend on each other, run them together in one call, and call this tool in the same response as other independent tool calls. Use for finding code patterns, function definitions, class names, imports, etc. It reports one match per file by default, which answers which files mention something. To find every occurrence inside a file — how many times a name appears and where each one is — raise `max_per_file`. `context_lines` sets how many lines are shown either side of a match, 2 by default. Output beyond ~48k characters per query is middle-truncated; narrow patterns beat broad ones. Output: one object per pattern — `{query, result, success, error?}`, where a failed entry has `success: false` and the reason in `error`. `query` is the pattern you sent and `result` is the matching lines with their file paths. A pattern that matched nothing still has `success: true` with an empty `result`; that is an answer, not a failure, and re-running it will not change it.
+Perform regex pattern searches across the codebase. Supports multiple parallel searches. When several search patterns could be useful and do not depend on each other, run them together in one call, and call this tool in the same response as other independent tool calls. Use for finding code patterns, function definitions, class names, imports, etc. It reports one match per file by default, which answers which files mention something. To find every occurrence inside a file — how many times a name appears and where each one is — raise `max_per_file`. `context_lines` sets how many lines are shown either side of a match, 2 by default. Output beyond ~48k characters per query is middle-truncated; narrow patterns beat broad ones. Output: one entry per pattern — each entry names what it answers, then what came back, and a failed entry says that it failed and why. An entry is named by the pattern you sent and holds the matching lines with their file paths. A pattern that matched nothing comes back empty, not failed; that is an answer, and re-running it will not change it.
 
 # tool: grep
-Search files for lines matching a pattern, as POSIX `grep` does. Give it a `pattern` and, optionally, `paths` — files or directories, defaulting to the workspace root searched recursively, skipping `node_modules`, `.git`, `dist` and the like. The pattern is a BASIC regular expression by default, exactly as grep reads one: `+ ? ( ) { } |` are literal characters there, and `\(a\|b\)` is how you group and alternate. Pass `extended: true` for the syntax you are probably thinking of, or `fixed: true` to search for the text itself with no syntax at all. Flags: `ignore_case`, `invert` (the lines that do not match), `word` (whole words), `count` (how many per file), `files_with_matches` (names only), `context` (lines either side), `max_count` (stop after N per file). Line numbers are included unless you set `line_numbers: false`. Use it to find where something is before you read or edit it — it is cheaper than reading whole files, and a match records that you have read those lines. This runs in-process, not through the shell: it needs no binary installed and behaves identically on every platform. Output: a single `{query, result, success, error?}`, where a failed entry has `success: false` and the reason in `error`. `query` is `grep:<pattern>` and `result` holds the matching lines prefixed with their path and line number. A pattern that matched nothing still has `success: true`, and `result` says so in words: that is an answer, and re-running the same search will not change it.
+Search files for lines matching a pattern, as POSIX `grep` does. Give it a `pattern` and, optionally, `paths` — files or directories, defaulting to the workspace root searched recursively, skipping `node_modules`, `.git`, `dist` and the like. The pattern is a BASIC regular expression by default, exactly as grep reads one: `+ ? ( ) { } |` are literal characters there, and `\(a\|b\)` is how you group and alternate. Pass `extended: true` for the syntax you are probably thinking of, or `fixed: true` to search for the text itself with no syntax at all. Flags: `ignore_case`, `invert` (the lines that do not match), `word` (whole words), `count` (how many per file), `files_with_matches` (names only), `context` (lines either side), `max_count` (stop after N per file). Line numbers are included unless you set `line_numbers: false`. Use it to find where something is before you read or edit it — it is cheaper than reading whole files, and a match records that you have read those lines. This runs in-process, not through the shell: it needs no binary installed and behaves identically on every platform. Output: one result, named `grep:<pattern>`, holding the matching lines prefixed with their path and line number; a search that could not run says that it failed and why. A pattern that matched nothing is not a failure, and the result says so in words: that is an answer, and re-running the same search will not change it.
 
 # tool: awk
-Run an `awk` program over one or more files. Send a `program` — `{print $1}`, `NR>1 {sum+=$2} END {print sum}`, `$3 ~ /error/ {print FILENAME, NR, $0}` — and the `files` to run it over. `field_separator` is `-F`; `variables` is `-v`. A program with only a BEGIN block needs no files. This is the tool for questions about columns and totals, where grep would only find the lines and you would still have to count them yourself: summing a column, picking fields out of a delimited file, counting occurrences per key. It is read-only, and deliberately so: output redirection, pipes, `system()` and `getline` are all refused rather than quietly ignored. Use `sed` or `editor` to change a file. This runs in-process, not through the shell: it needs no binary installed and behaves identically on every platform. Output: a single `{query, result, success, error?}`, where a failed entry has `success: false` and the reason in `error`. `query` is `awk:<program>` and `result` is everything the program printed. A program that printed nothing still has `success: true` — that is the program's answer, not a failure.
+Run an `awk` program over one or more files. Send a `program` — `{print $1}`, `NR>1 {sum+=$2} END {print sum}`, `$3 ~ /error/ {print FILENAME, NR, $0}` — and the `files` to run it over. `field_separator` is `-F`; `variables` is `-v`. A program with only a BEGIN block needs no files. This is the tool for questions about columns and totals, where grep would only find the lines and you would still have to count them yourself: summing a column, picking fields out of a delimited file, counting occurrences per key. It is read-only, and deliberately so: output redirection, pipes, `system()` and `getline` are all refused rather than quietly ignored. Use `sed` or `editor` to change a file. This runs in-process, not through the shell: it needs no binary installed and behaves identically on every platform. Output: one result, named `awk:<program>`, holding everything the program printed; a program that could not run says that it failed and why. A program that printed nothing has not failed — that is the program's answer.
 
 # tool: extract_document
-Read a document that is not plain text: PDF, Word (DOCX and 97-2003 DOC), PowerPoint (PPTX, PPT), Excel (XLSX, XLS), OpenDocument (ODT, ODP, ODS, ODG), RTF, CSV, HTML, and ebooks (EPUB, MOBI, AZW, AZW3, FB2). `read_files` cannot read these: it returns their bytes as garbage text. It returns the document as markdown (or plain text with `format: "text"`) and writes the whole text to a file, with the pictures inside the document saved beside it in an `images` folder and linked from the text. The output goes to `.cline/extracted/<document name>/` in the workspace; pass `output_dir` only when the user asks for it somewhere else in the workspace. Use `range` to read part of a long document: pages of a PDF, slides, sheets, or chapters of an ebook. `images: "inline"` also attaches the first few pictures to the result, when you can see images; `images: "none"` skips them. The first lines of the result say what the document is: its format, title and author, how many pages, slides, sheets or chapters it has, the table of contents of an ebook, and which PDF pages are scanned images of text. Their text is recognized (OCR) and marked as such, or the result says why it was not; `ocr` picks how. Output: a single `{query, result, success, error?}`, where a failed entry has `success: false` and the reason in `error`. `query` is `extract_document:<path>` and `result` holds that summary, then the text. A long text is cut at `max_chars` and says where the rest is. A document with no text still has `success: true`, and the result says so.
+Read a document that is not plain text: PDF, Word (DOCX and 97-2003 DOC), PowerPoint (PPTX, PPT), Excel (XLSX, XLS), OpenDocument (ODT, ODP, ODS, ODG), RTF, CSV, HTML, and ebooks (EPUB, MOBI, AZW, AZW3, FB2), each of them also gzipped (`book.fb2.gz`). `read_files` cannot read these: it returns their bytes as garbage text. It returns the document as markdown (or plain text with `format: "text"`) and writes the whole text to a file, with the pictures inside the document saved beside it in an `images` folder and linked from the text. The output goes to `.cline/extracted/<document name>/` in the workspace; pass `output_dir` only when the user asks for it somewhere else in the workspace. Use `range` to read part of a long document: pages of a PDF, slides, sheets, or chapters of an ebook. `images: "inline"` also attaches the first few pictures to the result, when you can see images; `images: "none"` skips them. The first lines of the result say what the document is: its format, title and author, how many pages, slides, sheets or chapters it has, the table of contents of an ebook, and which PDF pages are scanned images of text. Their text is recognized (OCR) and marked as such, or the result says why it was not; `ocr` picks how. Output: one result, named `extract_document:<path>`, holding that summary, then the text; a document that could not be read says that it failed and why. A long text is cut at `max_chars` and says where the rest is. A document with no text is not a failure, and the result says so.
 
 # tool: fetch_web_content
-Fetch content from URLs and analyze them using the provided prompts. Use for retrieving documentation, API references, or any web content. Each request includes a URL and a prompt describing what information to extract. Fetch independent URLs together in one call, and call this tool in the same response as other independent tool calls. Output: one object per request — `{query, result, success, error?}`, where a failed entry has `success: false` and the reason in `error`. `query` is the URL and `result` is what was extracted from that page for your prompt, as text.
+Fetch content from URLs and analyze them using the provided prompts. Use for retrieving documentation, API references, or any web content. Each request includes a URL and a prompt describing what information to extract. Fetch independent URLs together in one call, and call this tool in the same response as other independent tool calls. Output: one entry per request — each entry names what it answers, then what came back, and a failed entry says that it failed and why. An entry is named by the URL and holds what was extracted from that page for your prompt, as text.
 
 # tool: editor
-An editor for controlled filesystem edits on the text file at the provided path. It does six things, chosen by which arguments you send:
+An editor for controlled filesystem edits on the text file at `file_path`. It does six things, chosen by which arguments you send:
 - Replace text: `old_text` plus `new_text`. When `old_text` occurs more than once, add `occurrence` (one-based, in file order) to pick one, or `replace_all: true` to change every one.
 - Replace lines: `start_line` plus `new_text`, with optional `end_line` (inclusive, defaults to `start_line`). No `old_text` needed. Prefer this when the text is long, minified or repeated: a diagnostic already gives you the line number, and a line number cannot be ambiguous. An empty `new_text` deletes the range.
-- Replace characters: `start_line` and `start_column` plus `new_text`, with optional `end_line`/`end_column` (both inclusive; each defaults to its start). This is the unit a diagnostic speaks in — `Line 108, column 385` — and on a long or minified line it is the only edit that leaves the other 400 characters untouched. `start_column` on its own replaces exactly one character.
+- Replace characters: `start_line` and `start_column` plus `new_text`, with optional `end_line`/`end_column` (both inclusive; each defaults to its start). This is the unit a diagnostic speaks in — `Line 12, column 640` — and on a long or minified line it is the only edit that leaves the other 400 characters untouched. `start_column` on its own replaces exactly one character.
 - Insert: `insert_line` plus `new_text`, which adds text before that line without replacing anything. Use `line_count + 1` to append at EOF. Add `insert_column` to insert *within* that line instead, before the character at that column — this is how you add one missing bracket. Use `line_length + 1` to append at the end of the line.
 - Create, or replace a file whole: `new_text` alone. When the file does not exist this creates it; when it exists this replaces every line, which is allowed once you have read the file, since reading it is what tells you what you are overwriting. `start_line: 1` with `end_line: <line count>` is the same write by another name. Neither has a size limit, because a file written whole cannot be split — but reach for a whole-file write only once a targeted edit has failed, since a rewrite that is slightly wrong quietly loses the parts you did not mean to touch. Never delete a file to get a clean slate: this call already is one, and a deleted file is simply gone if the turn ends before you write it back.
-Write the arguments in this order: `path` and every other short argument first — line and column numbers, `intent`, `task_progress`, `old_text` — and `new_text` last. The text you are writing is the long part of the call, and whatever is written after a long text is the part most easily left out.
-Use this rather than a shell command for anything that changes a file. Make one edit at a time and check it before starting the next: reads and searches cost nothing if one turns out to be unnecessary, but several edits made together and checked once leave several things to undo and no way to tell which one was wrong. Read the lines you are about to change before you change them: an edit aimed at a range you have not read in its current state is refused. Your own edits count — one that changes the file's length moves every line below it, so read that region again before editing it a second time. Line numbers taken from an earlier turn, from a task summary, or from a diagnostic issued before your last edit are the ones that go stale. Repeating the lines already in the range and then continuing is how you insert after them, and it is allowed — the range says which lines you mean, so repeating them is your own choice. What is refused is a `new_text` that goes on to repeat lines from *outside* the range: that appends a second copy of text already elsewhere in the file rather than replacing anything, and the refusal names the lines it matched so you can aim the next call at them. Output: a single `{query, result, success, error?}` object for this one edit, where `query` is `edit:<path>` or `insert:<path>` and `result` describes what changed. A failed edit changes nothing: `success` is false, `error` says why, and the file is exactly as it was. Do not resend the same call — `error` names the fix. In particular, text copied out of a `read_files` result must have its `123 | ` line-number gutter removed first.
+Write the arguments in this order: `file_path` and every other short argument first — line and column numbers, `intent`, `task_progress`, `old_text` — and `new_text` last. The text you are writing is the long part of the call, and whatever is written after a long text is the part most easily left out.
+Use this rather than a shell command for anything that changes a file. Make one edit at a time and check it before starting the next: reads and searches cost nothing if one turns out to be unnecessary, but several edits made together and checked once leave several things to undo and no way to tell which one was wrong. Read the lines you are about to change before you change them: an edit aimed at a range you have not read in its current state is refused. Your own edits count — one that changes the file's length moves every line below it, so read that region again before editing it a second time. Line numbers taken from an earlier turn, from a task summary, or from a diagnostic issued before your last edit are the ones that go stale. Repeating the lines already in the range and then continuing is how you insert after them, and it is allowed — the range says which lines you mean, so repeating them is your own choice. What is refused is a `new_text` that goes on to repeat lines from *outside* the range: that appends a second copy of text already elsewhere in the file rather than replacing anything, and the refusal names the lines it matched so you can aim the next call at them. Output: one result for this one edit, named `edit:<path>` or `insert:<path>`, describing what changed. A failed edit changes nothing: the result says it failed and why, and the file is exactly as it was. Do not resend the same call — the reason names the fix. In particular, text copied out of a `read_files` result must have its `123 | ` line-number gutter removed first.
 
 # tool: sed
-Apply a `sed` script to one or more files. Send a `script` — `s/foo/bar/g`, `/^debug/d`, `2,5s/^/# /`, several separated by newlines or `;` — and the `files` to run it over. Without `in_place` it only prints the result, which is how you check a script before trusting it; with `in_place: true` it rewrites each file. Addresses and `s///` patterns are BASIC regular expressions, as sed reads them, unless you pass `extended: true`. `quiet: true` prints only what the script prints, as `sed -n` does. Reach for this over `editor` when one mechanical change applies in many places or across many files — renaming an identifier everywhere, stripping a prefix from every line of a block. For a single considered change to one place, `editor` is the better tool: it can anchor on text you quote back, and it tells you when the file has moved under you. An in-place run is refused on a file you have not read, the same way an `editor` call is — and a script addressed by line number is refused unless you have read those lines. Read first. This runs in-process, not through the shell: it needs no binary installed and behaves identically on every platform. Output: one object per file — `{query, result, success, error?}`, where a failed entry has `success: false` and the reason in `error`. `query` is `sed:<file>` and `result` is that file's output, or a sentence saying what was written. The files do not share a fate: one may be written while the next is refused, so read every entry. `success: false` means that file was NOT touched and `error` says why. A script that matched nothing is `success: true` — it ran, and that is its answer; running it again unchanged will not change it.
+Apply a `sed` script to one or more files. Send a `script` — `s/foo/bar/g`, `/^debug/d`, `2,5s/^/# /`, several separated by newlines or `;` — and the `files` to run it over. Without `in_place` it only prints the result, which is how you check a script before trusting it; with `in_place: true` it rewrites each file. Addresses and `s///` patterns are BASIC regular expressions, as sed reads them, unless you pass `extended: true`. `quiet: true` prints only what the script prints, as `sed -n` does. Reach for this over `editor` when one mechanical change applies in many places or across many files — renaming an identifier everywhere, stripping a prefix from every line of a block. For a single considered change to one place, `editor` is the better tool: it can anchor on text you quote back, and it tells you when the file has moved under you. An in-place run is refused on a file you have not read, the same way an `editor` call is — and a script addressed by line number is refused unless you have read those lines. Read first. This runs in-process, not through the shell: it needs no binary installed and behaves identically on every platform. Output: one entry per file — each entry names what it answers, then what came back, and a failed entry says that it failed and why. An entry is named `sed:<file>` and holds that file's output, or a sentence saying what was written. The files do not share a fate: one may be written while the next is refused, so read every entry. A failed entry means that file was NOT touched, and it says why. A script that matched nothing has not failed — it ran, and that is its answer; running it again unchanged will not change it.
 
 # tool: apply_patch
 Use `apply_patch` to edit files with the canonical freeform patch grammar. Pass the patch text directly as the `input` string. Prefer the exact format below:
@@ -118,7 +118,7 @@ Example:
  }
 *** End Patch
 
-Output: a single `{query, result, success, error?}` object covering the whole patch, where `result` says which files were added, updated, moved or deleted. A patch that did not apply — usually because its context lines no longer match the file — sets `success: false` and says so in `error`; re-read the file and rebuild the patch from what is actually there rather than resending it.
+Output: one result covering the whole patch, saying which files were added, updated, moved or deleted. A patch that did not apply — usually because its context lines no longer match the file — comes back failed and says why; re-read the file and rebuild the patch from what is actually there rather than resending it.
 
 # tool: ask_question
 Ask user a question for clarifying or gathering information needed to complete the task. For example, ask the user clarifying questions about a key implementation decision. You should only ask one question. Provide an array of 2-5 options for the user to choose from. Never include an option to toggle to Act mode. Mark the option you would pick: end it with ' (recommended)' and say why in one sentence in the question. Mark exactly one. Leave every option unmarked only when the choice turns on the user's taste or on something only they know. Output: the user's answer, as plain text — one of the options you offered, or whatever they wrote instead. Act on it in the same turn; the answer arriving is not a reason to stop.
@@ -147,7 +147,7 @@ Pass every file you want checked in one call.
 
 Read a clean result carefully. "No problems reported by the editor" is conclusive only where a language server covers that file, and it does not for every language on every machine. If this reports nothing and you have reason to expect a problem, or the project has a checker the language servers do not run, run that checker with `run_commands`. Tests and builds are always `run_commands`; this tool does not run them.
 
-Output: plain text, one section per file you named, each problem on its own line as `file:line:column` with its severity and message. A file with nothing wrong says so in one line. There is no object to unpack and no `success` field — problems being listed is this tool working, not failing.
+Output: plain text, one section per file you named, each problem on its own line as `file:line:column` with its severity and message. A file with nothing wrong says so in one line. Problems being listed is this tool working, not failing.
 
 When a file's brackets do not match, a `Delimiter scan` section names the line to edit and how many brackets that line is out by, one line per place the trouble starts — a file can be broken in several spots at once, so work through every line it lists before re-checking rather than re-checking after each one. A parse error is always reported where the parser gave up, which is the closing bracket; the line named here is the one the error cannot name. Trust those lines over counting brackets yourself — the scan skips strings, comments and regex literals, which counting characters does not. It runs whether or not the editor reported anything, so it can appear beneath a file the editor called clean — no language server checks the script inside an `.html` file, and there this is the only report you will get.
 
@@ -156,7 +156,7 @@ List the files in the workspace. Use this to find out what exists — do not run
 
 Two ways to ask:
 - `path` — list what is directly inside one directory. Omit it to list the workspace root.
-- `pattern` — a glob searched across the whole workspace, e.g. `**/*.html`, `src/**/*.ts`, `**/manic_miner.*`. Use this when you know part of a name but not where it lives.
+- `pattern` — a glob searched across the whole workspace, e.g. `**/*.html`, `src/**/*.ts`, `**/config.*`. Use this when you know part of a name but not where it lives.
 
 Results are limited to the workspace folders the user opened, and directories the user's settings exclude from search — `node_modules`, `.git`, build output — are left out. A path outside the workspace is refused rather than listed.
 

package/assets/prompt-templates/gemma.md

@@ -7,10 +7,15 @@ match:
 
 <!-- PROVENANCE -- written by scripts/review-prompt-templates.mts, not by the model.
 
-     Sections `grep`, `sed`, `awk`, `run_commands` written by gemma4:31b-cloud (Ollama family `gemma4`) on 2026-09-12.
+     Sections `apply_patch`, `awk`, `editor`, `fetch_web_content`, `grep`, `read_files`, `search_codebase`, `sed` written by gemma4:31b-cloud (Ollama family `gemma4`) on 2026-10-22.
+     Every other section is as it was. Before this run:
 
-     Every other section is unchanged. Written by gemma4:31b-cloud (Ollama family `gemma4`) on 2026-09-12.
-     Run, with its log: prompt-reviews/regen/20260912-2324-gemma4-31b-cloud
+       Sections `grep`, `sed`, `awk`, `run_commands` written by gemma4:31b-cloud (Ollama family `gemma4`) on 2026-09-12.
+
+       Every other section is unchanged. Written by gemma4:31b-cloud (Ollama family `gemma4`) on 2026-09-12.
+       Run, with its log: prompt-reviews/regen/20260912-2324-gemma4-31b-cloud
+
+     Run, with its log: prompt-reviews/regen/20261022-0646-gemma4-31b-cloud
 
      Sampler asked for by the generator, overriding the model's own:
        temperature 0.2
@@ -84,47 +89,70 @@ Environment:
 {{CLINE_METADATA}}
 
 # tool: read_files
+
 Read text or image files. Use this instead of shell commands like `cat` or `type`.
 - **Arguments:** `files`: An array of objects. Each object must have a `path`. Optionally include `start_line` and `end_line` (1-based) to read a specific range. Set `line_numbers: false` when reading text to be copied into `editor`.
 - **When to use:** When you need to see the contents of one or more files. Batch all known required files into one call.
-- **Output:** An array of objects `{query, result, success, error?}`. `result` contains the file content with line numbers (unless disabled). If `success` is false, `error` explains why.
+- **Constraints:** Each read returns at most 2000 lines. Use ranges to page through larger files. Avoid reading entire files unless they are genuinely small to save context space.
+- **Output:** One entry per requested file, named by the path (or `path:start-end` for ranges). It holds the file content with line numbers (unless disabled). If a read fails, the entry explains why.
 {{DEFAULT}}
 
 # tool: search_codebase
+
 Regex search across the codebase. Use this instead of `grep` or `rg`.
 - **Arguments:** `queries`: An array of regex strings. `context_lines` (integer) for surrounding lines. `max_per_file` (integer) to find all occurrences in a file.
 - **When to use:** To find patterns, names, or imports. Use narrow patterns to avoid middle-truncation. Batch multiple independent queries into one call.
-- **Output:** An array of objects `{query, result, success, error?}`. `result` contains matching lines and their file paths.
+- **Output:** One entry per pattern, named by the regex used. It holds the matching lines and their file paths. If a search fails, the entry explains why.
 {{DEFAULT}}
 
 # tool: fetch_web_content
+
 Retrieve and analyze web pages.
 - **Arguments:** `requests`: An array of objects, each containing a `url` and a `prompt` describing what to extract.
 - **When to use:** For documentation or API references. Batch multiple URLs into one call.
-- **Output:** An array of objects `{query, result, success, error?}`. `result` is the extracted text.
+- **Output:** One entry per request, named by the URL. It holds the text extracted from the page based on your prompt. If a request fails, the entry explains why.
 {{DEFAULT}}
 
 # tool: editor
+
 Precise text edits or file creation. This is the primary tool for writing files. Never use shell redirects (`>`) or `sed`.
 - **Arguments:** 
-    - `path`: Absolute path to the file.
+    - `file_path`: Absolute path to the file.
     - `new_text`: The text to insert or replace.
     - `old_text` (Optional): The exact text to be replaced. Must match indentation perfectly.
     - `insert_line` (Optional): 1-based line number to insert `new_text` before.
     - `start_line`/`end_line` (Optional): Line range to replace (inclusive).
-    - `start_column`/`end_column` (Optional): Character range on those lines (inclusive, each defaults to its start). Diagnostics report a column; this replaces only those characters, which is what a long or minified line needs.
-    - `insert_column` (Optional): With `insert_line`, inserts inside that line before this character instead of adding a new line. Use it to add a single missing bracket; `line_length + 1` appends at the end of the line.
+    - `start_column`/`end_column` (Optional): Character range on those lines (inclusive). Used for precise edits on long or minified lines.
+    - `insert_column` (Optional): With `insert_line`, inserts within that line before this character.
     - `occurrence` (Optional): 1-based index if `old_text` appears multiple times.
     - `replace_all` (Optional): Boolean to replace all occurrences of `old_text`.
-- **When to use:** For small, precise changes or creating new files. Emit multiple `editor` calls in one response for different files or non-overlapping regions.
-- **Output:** A single `{query, result, success, error?}` object. If `old_text` is not found, `success` is false.
+- **When to use:** For small, precise changes or creating new files.
+- **Constraints:** 
+    - Make one edit at a time and verify it before proceeding.
+    - You must read the lines you are about to change in their current state; edits to unread ranges are refused.
+    - Text copied from `read_files` must have the line-number gutter (`123 | `) removed.
+- **Output:** A single result named `edit:<path>` or `insert:<path>` describing what changed. If the edit fails (e.g., `old_text` not found or range unread), the result explains why.
 {{DEFAULT}}
 
 # tool: apply_patch
-Apply complex changes using a patch grammar.
-- **Arguments:** `input`: A string containing the patch. Use `*** Begin Patch`, `*** Update File: path`, and `+`/`-` markers.
-- **When to use:** For larger structural changes across multiple files.
-- **Output:** A single `{query, result, success, error?}` object. If context lines do not match, `success` is false.
+
+Apply complex changes using a patch grammar. Use this for larger structural changes across multiple files.
+- **Arguments:** `input`: A string containing the patch. Use the following format:
+    *** Begin Patch
+    *** Update File: path/to/file.ts
+    @@ optional section marker
+       [context before]
+    -[old line]
+    +[new line]
+       [context after]
+    *** End Patch
+- **Supported Actions:**
+    - `*** Add File: <path>`: Every line of content must start with `+`.
+    - `*** Update File: <path>`: Use context lines with `-` and `+` markers.
+    - `*** Delete File: <path>`
+    - `*** Move to: <new path>`: Must immediately follow an Update File header.
+- **Constraints:** Do not use line numbers; the format is context-based. Use `@@` markers to disambiguate repeated code blocks. Avoid legacy shell wrappers like `%%bash`.
+- **Output:** A single result listing which files were added, updated, moved, or deleted. If the patch fails to apply (usually due to context mismatch), the result explains why.
 {{DEFAULT}}
 
 # tool: ask_question
@@ -327,7 +355,7 @@ Search files for lines matching a pattern, as POSIX `grep` does. This runs in-pr
     - `ignore_case`, `invert` (non-matching lines), `word` (whole words), `count` (matches per file), `files_with_matches` (names only), `line_numbers` (defaults to true), `max_count` (stop after N per file).
     - `context` (Optional): Integer for lines of surrounding context.
 - **When to use:** To find where a string or pattern exists before reading or editing. It is cheaper than reading whole files.
-- **Output:** A single `{query, result, success, error?}` object. `result` contains matching lines prefixed with path and line number. A pattern that matches nothing is still `success: true`.
+- **Output:** A single result named `grep:<pattern>` containing matching lines prefixed with path and line number. If the search fails, the result explains why.
 {{DEFAULT}}
 
 # tool: sed
@@ -341,7 +369,7 @@ Apply a `sed` script to one or more files. This runs in-process and behaves iden
     - `extended` (Optional): Boolean. Use for extended regex syntax.
 - **When to use:** For mechanical changes applying in many places or across many files (e.g., renaming an identifier everywhere). For single, considered changes, use `editor`.
 - **Constraints:** In-place runs are refused on files you have not read. Scripts addressed by line number are refused unless those lines have been read.
-- **Output:** One `{query, result, success, error?}` object per file. `result` is the output or a confirmation of the write. If `success` is false, that specific file was NOT touched.
+- **Output:** One entry per file, named `sed:<file>`. It holds the resulting text or a confirmation that the file was written. If a specific file was not touched, the entry explains why.
 {{DEFAULT}}
 
 # tool: awk
@@ -354,7 +382,7 @@ Run an `awk` program over one or more files. This runs in-process and behaves id
     - `variables` (Optional): Object of variables to pass to the program (like `-v`).
 - **When to use:** For questions about columns, totals, or delimited data (e.g., summing a column, counting occurrences per key) where `grep` is insufficient.
 - **Constraints:** Read-only. Output redirection, pipes, `system()`, and `getline` are refused.
-- **Output:** A single `{query, result, success, error?}` object. `result` contains everything the program printed. A program that prints nothing is still `success: true`.
+- **Output:** A single result named `awk:<program>` containing everything the program printed. If the program fails to run, the result explains why.
 {{DEFAULT}}
 
 # tool: extract_document