@oh-my-pi/pi-coding-agent 14.2.1 → 14.4.0

package/src/prompts/tools/ast-edit.md

@@ -2,12 +2,12 @@ Performs structural AST-aware rewrites via native ast-grep.
 
 <instruction>
 - Use for codemods and structural rewrites where plain text replace is unsafe
-- `path` accepts a comma-separated list in addition to file/dir/glob
-- Set `lang` explicitly in mixed-language trees for deterministic rewrites
+- `path` is required and accepts a file, directory, glob, comma-separated path list, or internal URL
+- Language is inferred from `path`; narrow `path` to one language for deterministic rewrites
 - Metavariables captured in `pat` (`$A`, `$$$ARGS`) are substituted into that entry's `out` template
 - **Patterns match AST structure, not text.** `$NAME` = one node (captured); `$_` = one without binding; `$$$NAME` = zero-or-more (lazy — stops at next matchable element); `$$$` = zero-or-more without binding. Use `$$$NAME`, **NOT** `$$NAME` — the two-dollar form is invalid. Metavariable names are UPPERCASE and **MUST** be the whole AST node — partial text like `prefix$VAR` or `"hello $NAME"` does NOT work
 - When the same metavariable appears twice, both occurrences **MUST** match identical code (`$A == $A` matches `x == x`, not `x == y`)
-- Rewrite patterns **MUST** parse as a single valid AST node. For method fragments or body snippets that don't parse standalone, wrap in context (e.g. `class $_ { … }`) and set `sel` to target the inner node — match and replacement target the selected node, not the wrapper. If ast-grep reports `Multiple AST nodes are detected`, wrap and use `sel`
+- Rewrite patterns **MUST** parse as a single valid AST node. For method fragments or body snippets that don't parse standalone, wrap in context (e.g. `class $_ { … }`)
 - For TS declarations/methods, tolerate unknown annotations: `async function $NAME($$$ARGS): $_ { $$$BODY }` or `class $_ { method($ARG: $_): $_ { $$$BODY } }`
 - Delete matched code with empty `out`: `{"pat":"console.log($$$)","out":""}`
 - Each rewrite is a 1:1 structural substitution — cannot split one capture across multiple nodes or merge multiple captures into one
@@ -19,22 +19,18 @@ Performs structural AST-aware rewrites via native ast-grep.
 </output>
 
 <examples>
-- Rename a call site across a directory:
-  `{"ops":[{"pat":"oldApi($$$ARGS)","out":"newApi($$$ARGS)"}],"lang":"typescript","path":"src/"}`
-- Delete matching calls (empty `out` removes the node):
-  `{"ops":[{"pat":"console.log($$$ARGS)","out":""}],"lang":"typescript","path":"src/"}`
-- Rewrite import source path:
-  `{"ops":[{"pat":"import { $$$IMPORTS } from \"old-package\"","out":"import { $$$IMPORTS } from \"new-package\""}],"lang":"typescript","path":"src/"}`
-- Modernize to optional chaining (same metavariable enforces identity):
-  `{"ops":[{"pat":"$A && $A()","out":"$A?.()"}],"lang":"typescript","path":"src/"}`
-- Swap two arguments using captures:
-  `{"ops":[{"pat":"assertEqual($A, $B)","out":"assertEqual($B, $A)"}],"lang":"typescript","path":"tests/"}`
-- Rename a function declaration while tolerating any return type annotation:
-  `{"ops":[{"pat":"async function fetchData($$$ARGS): $_ { $$$BODY }","out":"async function loadData($$$ARGS): $_ { $$$BODY }"}],"sel":"function_declaration","lang":"typescript","path":"src/api.ts"}`
-- Rewrite a method body fragment by wrapping in parseable context and selecting the method:
-  `{"ops":[{"pat":"class $_ { async execute($INPUT: $_) { $$$BEFORE; const $PARSED = $_.parse($INPUT); $$$AFTER } }","out":"class $_ { async execute($INPUT: $_) { $$$BEFORE; const $PARSED = $SCHEMA.parse($INPUT); $$$AFTER } }"}],"sel":"method_definition","lang":"typescript","path":"src/tools/todo.ts"}`
-- Python — convert print calls to logging:
-  `{"ops":[{"pat":"print($$$ARGS)","out":"logger.info($$$ARGS)"}],"lang":"python","path":"src/"}`
+# Rename a call site across TypeScript files
+`{"ops":[{"pat":"oldApi($$$ARGS)","out":"newApi($$$ARGS)"}],"path":"src/**/*.ts"}`
+# Delete matching calls
+`{"ops":[{"pat":"console.log($$$ARGS)","out":""}],"path":"src/**/*.ts"}`
+# Rewrite import source path
+`{"ops":[{"pat":"import { $$$IMPORTS } from \"old-package\"","out":"import { $$$IMPORTS } from \"new-package\""}],"path":"src/**/*.ts"}`
+# Modernize to optional chaining (same metavariable enforces identity)
+`{"ops":[{"pat":"$A && $A()","out":"$A?.()"}],"path":"src/**/*.ts"}`
+# Swap two arguments using captures
+`{"ops":[{"pat":"assertEqual($A, $B)","out":"assertEqual($B, $A)"}],"path":"tests/**/*.ts"}`
+# Python — convert print calls to logging
+`{"ops":[{"pat":"print($$$ARGS)","out":"logger.info($$$ARGS)"}],"path":"src/**/*.py"}`
 </examples>
 
 <critical>

package/src/prompts/tools/ast-grep.md

@@ -2,18 +2,18 @@ Performs structural code search using AST matching via native ast-grep.
 
 <instruction>
 - Use when syntax shape matters more than raw text (calls, declarations, specific language constructs)
-- `path` accepts a comma-separated list in addition to file/dir/glob
-- Set `lang` explicitly in mixed-language trees to avoid parse noise from non-source files
-- Multiple patterns in `pat` run in one native pass, merged, then `offset`/`limit` applied
+- `path` is required and accepts a file, directory, glob, comma-separated path list, or internal URL
+- Language is inferred from `path`; narrow `path` to one language when mixed-language trees could cause parse noise
+- `pat` is a single AST pattern. Run separate calls for distinct unrelated patterns
 - **Patterns match AST structure, not text** — whitespace/formatting is ignored
 - `$NAME` captures one node; `$_` matches one without binding; `$$$NAME` captures zero-or-more (lazy — stops at next matchable element); `$$$` matches zero-or-more without binding. Use `$$$NAME`, **NOT** `$$NAME` — the two-dollar form is invalid and produces a parse error
 - Metavariable names are UPPERCASE and must be the whole AST node — partial-text like `prefix$VAR`, `"hello $NAME"`, or `a $OP b` does NOT work; match the whole node instead
 - When the same metavariable appears twice, both occurrences **MUST** match identical code (`$A == $A` matches `x == x`, not `x == y`)
-- Patterns **MUST** parse as a single valid AST node for the target language. For method fragments or body snippets that don't parse standalone, wrap in valid context (e.g. `class $_ { … }`) and set `sel` to target the inner node — results return for the selected node, not the outer wrapper. If ast-grep reports `Multiple AST nodes are detected`, the pattern isn't a single parseable node — wrap and use `sel`
-- C++ qualified calls used as expression statements need the statement semicolon in the pattern: use `ns::doThing($ARG);`, `$CALLEE($ARG)`, or wrap a statement snippet and select `call_expression`. Without `;`, tree-sitter-cpp may parse `ns::doThing($ARG)` as declaration-like syntax and return no matches
+- Patterns **MUST** parse as a single valid AST node for the inferred target language. For method fragments or body snippets that don't parse standalone, wrap in valid context (e.g. `class $_ { … }`)
+- C++ qualified calls used as expression statements need the statement semicolon in the pattern: use `ns::doThing($ARG);`, `$CALLEE($ARG);`, or wrap a statement snippet. Without `;`, tree-sitter-cpp may parse `ns::doThing($ARG)` as declaration-like syntax and return no matches
 - For TS declarations/methods, tolerate unknown annotations: `async function $NAME($$$ARGS): $_ { $$$BODY }` or `class $_ { method($ARG: $_): $_ { $$$BODY } }`
 - Declaration forms are structurally distinct — top-level `function foo`, class method `foo()`, and `const foo = () => {}` are different AST shapes; search the right form before concluding absence
-- Loosest existence check: `pat: ["executeBash"]` with `sel: "identifier"`
+- Loosest existence check: `pat: "executeBash"` with a narrow `path`
 </instruction>
 
 <output>
@@ -22,26 +22,20 @@ Performs structural code search using AST matching via native ast-grep.
 </output>
 
 <examples>
-- Multi-pattern scoped search:
-  `{"pat":["console.log($$$)","console.error($$$)"],"lang":"typescript","path":"src/"}`
-- Named imports from a specific package (quoted string inside pattern):
-  `{"pat":["import { $$$IMPORTS } from \"react\""],"lang":"typescript","path":"src/"}`
-- Arrow functions assigned to a const (distinct AST from function declarations):
-  `{"pat":["const $NAME = ($$$ARGS) => $BODY"],"lang":"typescript","path":"src/utils/"}`
-- Method call on any object, ignoring method name with `$_`:
-  `{"pat":["logger.$_($$$ARGS)"],"lang":"typescript","path":"src/"}`
-- Contextual pattern with selector — match the identifier `foo`, not the whole call:
-  `{"pat":["foo()"],"sel":"identifier","lang":"typescript","path":"src/utils.ts"}`
-- Match a function declaration while tolerating any return type annotation (`sel` targets the inner node):
-  `{"pat":["async function processItems($$$ARGS): $_ { $$$BODY }"],"sel":"function_declaration","lang":"typescript","path":"src/worker.ts"}`
-- Match a method body fragment by wrapping in parseable context and selecting the method:
-  `{"pat":["class $_ { async execute($INPUT: $_) { $$$BEFORE; const $PARSED = $_.parse($INPUT); $$$AFTER } }"],"sel":"method_definition","lang":"typescript","path":"src/tools/todo.ts"}`
-- Loosest existence check for a symbol in one file:
-  `{"pat":["processItems"],"sel":"identifier","lang":"typescript","path":"src/worker.ts"}`
+# Search TypeScript files under src
+`{"pat":"console.log($$$)","path":"src/**/*.ts"}`
+# Named imports from a specific package
+`{"pat":"import { $$$IMPORTS } from \"react\"","path":"src/**/*.ts"}`
+# Arrow functions assigned to a const
+`{"pat":"const $NAME = ($$$ARGS) => $BODY","path":"src/utils/**/*.ts"}`
+# Method call on any object, ignoring method name with `$_`
+`{"pat":"logger.$_($$$ARGS)","path":"src/**/*.ts"}`
+# Loosest existence check for a symbol in one file
+`{"pat":"processItems","path":"src/worker.ts"}`
 </examples>
 
 <critical>
-- Avoid repo-root AST scans when the target is language-specific — narrow `path` first
-- Parse issues are query failure, not evidence of absence: repair the pattern or tighten `path`/`glob`/`lang` before concluding "no matches"
+- Avoid repo-root scans — narrow `path` first
+- Parse issues are query failure, not evidence of absence: repair the pattern or tighten `path` before concluding "no matches"
 - For broad/open-ended exploration across subsystems, use Task tool with explore subagent first
 </critical>

package/src/prompts/tools/atom.md

@@ -0,0 +1,96 @@
+Applies precise file edits using full anchors from `read` output (for example `160sr`).
+
+Read the file first. Copy the full anchors exactly as shown by `read`.
+
+<operations>
+**Top level**: `{ path, edits: […] }` — `path` is shared by all entries. You may still override the file inside `loc` with forms like `other.ts:160sr`.
+
+Each entry has one shared locator plus one or more verbs:
+- `loc: "160sr"` — single anchored line
+- `loc: "^"` — beginning of file (only valid with `pre`)
+- `loc: "$"` — end of file (only valid with `post`)
+- `loc: "a.ts:160sr"` — cross-file override inside the locator
+
+Verbs:
+- `set: ["…"]` — replace the anchor line
+- `pre: ["…"]` — insert before the anchor line (or at BOF when `loc:"^"`)
+- `post: ["…"]` — insert after the anchor line (or at EOF when `loc:"$"`)
+
+Combination rules:
+- On a single-anchor `loc`, you may combine `pre`, `set`, and `post` in the same entry.
+- `set: []` on a single-anchor `loc` deletes that line.
+- `set:[""]` is **not** delete — it replaces the line with a blank line.
+</operations>
+
+<examples>
+All examples below reference the same file:
+
+```ts title="a.ts"
+{{hline  1 "// @ts-ignore"}}
+{{hline  2 "const timeout = 5000;"}}
+{{hline  3 "const tag = \"DO NOT SHIP\";"}}
+{{hline  4 "const fallback = group.targetFramework || 'All Frameworks';"}}
+{{hline  5 "function alpha() {"}}
+{{hline  6 "\tlog();"}}
+{{hline  7 "}"}}
+{{hline  8 ""}}
+{{hline  9 "function beta(x) {"}}
+{{hline 10 "\tif (x) {"}}
+{{hline 11 "\t\treturn parse(data);"}}
+{{hline 12 "\t}"}}
+{{hline 13 "\treturn null;"}}
+{{hline 14 "}"}}
+```
+
+# Swap an operator by replacing the line
+Original line 4: `const fallback = group.targetFramework || 'All Frameworks';`
+`{path:"a.ts",edits:[{loc:{{href 4 "const fallback = group.targetFramework || 'All Frameworks';"}},set:["const fallback = group.targetFramework ?? 'All Frameworks';"]}]}`
+
+# Flip a literal by replacing the line
+Original line 2: `const timeout = 5000;`
+`{path:"a.ts",edits:[{loc:{{href 2 "const timeout = 5000;"}},set:["const timeout = 30_000;"]}]}`
+
+# Negate a condition by replacing the line
+Original line 10: `\tif (x) {`
+`{path:"a.ts",edits:[{loc:{{href 10 "\tif (x) {"}},set:["\tif (!x) {"]}]}`
+
+# Combine `pre` + `set` + `post` in one entry
+`{path:"a.ts",edits:[{loc:{{href 6 "\tlog();"}},pre:["\tvalidate();"],set:["\tlog();"],post:["\tcleanup();"]}]}`
+
+# Replace one whole line with `set`
+Use `set` to replace the full anchored line, preserving any unchanged surrounding lines yourself.
+`{path:"a.ts",edits:[{loc:{{href 3 "const tag = \"DO NOT SHIP\";"}},set:["const tag = \"OK\";"]}]}`
+
+# Replace multiple non-adjacent lines
+`{path:"a.ts",edits:[{loc:{{href 11 "\t\treturn parse(data);"}},set:["\t\treturn parse(data) ?? fallback;"]},{loc:{{href 13 "\treturn null;"}},set:["\treturn fallback;"]}]}`
+
+# Delete a line with `set: []`
+`{path:"a.ts",edits:[{loc:{{href 11 "\t\treturn parse(data);"}},set:[]}]}`
+
+# Preserve a blank line with `set:[""]`
+`{path:"a.ts",edits:[{loc:{{href 8 ""}},set:[""]}]}`
+
+# Insert before / after a line
+`{path:"a.ts",edits:[{loc:{{href 9 "function beta(x) {"}},pre:["function gamma() {","\tvalidate();","}",""]}]}`
+`{path:"a.ts",edits:[{loc:{{href 6 "\tlog();"}},post:["\tvalidate();"]}]}`
+
+# Prepend / append at file edges
+`{path:"a.ts",edits:[{loc:"^",pre:["// Copyright (c) 2026",""]}]}`
+`{path:"a.ts",edits:[{loc:"$",post:["","export const VERSION = \"1.0.0\";"]}]}`
+
+# Cross-file override inside `loc`
+`{path:"a.ts",edits:[{loc:"b.ts:{{href 2 "const timeout = 5000;"}}",set:["const timeout = 30_000;"]}]}`
+</examples>
+
+<critical>
+- Make the minimum exact edit.
+- Copy the full anchors exactly as shown by `read/grep` (for example `160sr`, not just `sr`).
+- `loc` chooses the target. Verbs describe what to do there.
+- On a single-anchor `loc`, you may combine `pre`, `set`, and `post`.
+- `loc:"^"` only supports `pre`. `loc:"$"` only supports `post`.
+- `set: []` deletes the anchored line. `set:[""]` preserves a blank line.
+- Within a single request you may submit edits in any order — the runtime applies them bottom-up so they don't shift each other. After any request that mutates a file, anchors below the mutation are stale on disk; re-read before issuing more edits to that file.
+- `set` operations target the current file content only. Do not try to reference old line text after the file has changed.
+- Text content must be literal file content with matching indentation. If the file uses tabs, use real tabs.
+- You **MUST NOT** use this tool to reformat or clean up unrelated code.
+</critical>

package/src/prompts/tools/browser.md

@@ -1,6 +1,7 @@
 Navigates, clicks, types, scrolls, drags, queries DOM content, and captures screenshots.
 
 <instruction>
+- For fetching static web content (articles, docs, issues/PRs, JSON, PDFs, feeds), prefer the `read` tool with a URL — it returns clean reader-mode text without spinning up a browser. Use this tool only when you need JS execution, authentication, or interactive actions.
 - `"open"` starts a headless session (or implicitly on first action); `"goto"` navigates to `url`; `"close"` releases the browser
 - `"observe"` captures a numbered accessibility snapshot — prefer `click_id`/`type_id`/`fill_id` using returned `element_id` values; flags: `include_all`, `viewport_only`
 - `"click"`, `"type"`, `"fill"`, `"press"`, `"scroll"`, `"drag"` for selector-based interactions — prefer ARIA/text selectors (`p-aria/[name="Sign in"]`, `p-text/Continue`) over brittle CSS

package/src/prompts/tools/chunk-edit.md

@@ -1,13 +1,14 @@
-Edits files via syntax-aware chunks. Run `read(path="file.ts")` first.
+Edits files via syntax-aware chunks. Use `read(path="file.ts")` to read and discover chunks before editing.
+- `read` is the canonical read path for chunk source and `sel="?"` tree listings.
 - `write` rewrites the entire targeted region — best for most edits.
-- `replace` does surgical find-and-replace within a chunk — use when making small changes to a large chunk, or batching multiple substitutions.
 - `insert` adds content before/after a chunk.
+- `delete` deletes a targeted chunk and must be explicit.
 
 Call format: `{"edits": [{"path": "file:chunk#ID~", "write": "new body"}, …]}`
 
 <rules>
-- **MUST** `read` first. Never invent chunk paths or IDs. Copy them from the latest `read` output or edit response.
-- `path` format: `file:selector` — e.g. `src/app.ts:fn_foo#ABCD~`. Append `~` for body, `^` for head, or nothing for the whole chunk. Include `#ID` for `put`/`find`+`replace`/`delete`.
+- **MUST** inspect first with `read`. Never invent chunk paths or IDs. Copy them from the latest `read` output or edit response.
+- `path` format: `file:selector` — e.g. `src/app.ts:fn_foo#thth~`. Append `~` for body, `^` for head, or nothing for the whole chunk. Include `#ID` for `write`/`delete`.
 - If the exact chunk path is unclear, run `read(path="file", sel="?")` and copy a selector from that listing.
 {{#if chunkAutoIndent}}
 - Use `\t` for indentation in `content`. Write content at indent-level 0 — the tool re-indents it to match the chunk's position in the file. For example, to replace `~` of a method, write the body starting at column 0:
@@ -16,6 +17,8 @@ Call format: `{"edits": [{"path": "file:chunk#ID~", "write": "new body"}, …]}`
   ```
   The tool adds the correct base indent automatically. Never manually pad with the chunk's own indentation.
   Multiple sibling body lines at the same level all start at column 0: `"print(a)\nprint(b)\nprint(c)\n"`. Only use `\t` when nesting deeper (e.g. `"if cond:\n\tinner\nouter\n"`).
+  Before applying the target's base indent, the tool strips any common leading whitespace shared by all non-empty `write` lines as a safety net. Do not rely on that cleanup for mixed indentation; write `~` bodies at column 0 and use one `\t` per relative nesting level.
+  Multi-line replacements use the same relative-indentation model: the replacement text is dedented, then re-indented to the matched source line. Do not include the chunk's base indentation in replacement text.
   **Common mistake** when replacing `~` of a function body: do NOT include the function's own indentation.
   Wrong: `"if b == 0:\n\t\treturn None\n\treturn a / b\n"` — adds the function's base `\t` to every line.
   Correct: `"if b == 0:\n\treturn None\nreturn a / b\n"` — `if` and `return a / b` at column 0, only `return None` gets `\t` for nesting.
@@ -26,10 +29,15 @@ Call format: `{"edits": [{"path": "file:chunk#ID~", "write": "new body"}, …]}`
   content: "if (x) {\n  return true;\n}"
   ```
   The tool adds the correct base indent automatically, then preserves the tabs/spaces you used inside the snippet. Never manually pad with the chunk's own indentation.
+  Before applying the target's base indent, the tool strips any common leading whitespace shared by all non-empty `write` lines as a safety net. Do not rely on that cleanup for mixed indentation; write `~` bodies at column 0.
+  Multi-line replacements use the same relative-indentation model: the replacement text is dedented, then re-indented to the matched source line. Do not include the chunk's base indentation in replacement text.
 {{/if}}
-- Region suffixes only apply to container chunks (classes, functions, impl blocks, sections). On leaf chunks (enum variants, fields, single statements, and compound statements like `if`/`for`/`while`/`match`/`try`), `~` and `^` silently fall back to whole-chunk replacement — prefer the unsuffixed form and always supply the complete replacement (condition + body, not just the body) to avoid dropping structural parts.
-- `put`, `find`+`replace`, and `delete` require the current ID. `prepend`/`append` do not.
+- Region suffixes only apply to chunks with a real head/body boundary (classes, functions, impl blocks, and similar containers). On code leaf chunks (enum variants, fields, single statements, and compound statements like `if`/`for`/`while`/`match`/`try`), `~` and `^` are rejected. Use the unsuffixed selector and supply the complete replacement content, or edit the parent container's `~` body.
+- Unsuffixed `write` on a leaf chunk uses your content verbatim after normal replacement; it is not a body-region rewrite. Include the exact indentation and punctuation the leaf needs in the file.
+- `^` head writes and `~` body writes use the same base-indent model: write content at column 0 relative to the target region, and the tool applies the chunk's file indentation.
+- `write` and `delete` require the current ID. `prepend`/`append` do not.
 - **IDs change after every edit.** The edit response always carries the new IDs — use those for the next call or run `read(path="file", sel="?")` to refresh. Never reuse an ID from before the latest edit.
+- Same-file edit batches are transactional: if any operation in that file fails, no changes from that file's batch are saved. Multi-file edit calls run per file, so a later file error does not roll back earlier files that already succeeded.
 </rules>
 
 <critical>
@@ -42,56 +50,57 @@ You **MUST** use the narrowest region that covers your change. Putting without a
 
 <regions>
 In `read` output, lines marked `^` between the line number and `|` are **head** lines (doc comments, attributes/decorators, signature). Lines without `^` are **body** lines. Use this to decide which region to target:
-- `fn_foo#ID~` — **body only (the default choice for most edits).** Head lines (`^`) are preserved automatically — doc comments, attributes, and signature stay untouched. On leaf chunks, falls back to whole chunk.
+- `fn_foo#ID~` — **body only (the default choice for most edits).** Head lines (`^`) are preserved automatically — doc comments, attributes, and signature stay untouched. On code leaf chunks, this is rejected because there is no safe body boundary.
 - `fn_foo#ID^` — head only (decorators, attributes, doc comments, signature, opening delimiter). Body stays untouched.
 - `fn_foo#ID` — entire chunk including leading trivia. **You must include doc comments and attributes in `content`; omitting them deletes them.**
-- `chunk~` + `append`/`prepend` inserts *inside* the container. `chunk` + `append`/`prepend` inserts *outside*.
+- `chunk~` + `append`/`prepend` inserts *inside* the container. `chunk` + `append`/`prepend` inserts *outside*. Appending to a container without `~` emits a warning because it lands after the closing delimiter, not before it.
 
-**Note on leading trivia:** whether a decorator/doc comment belongs to `^` depends on the parser. In Rust and Python, attributes and decorators are attached to the function chunk, so `^` covers them. In TypeScript/JavaScript, a `@decorator` + `/** jsdoc */` block immediately above a method often surfaces as a **separate sibling chunk** (shown as `chunk#ID` in the `?` listing) rather than as part of the function's `^`. If you need to rewrite a decorator, check the `?` listing for a sibling `chunk#ID` directly above your target.
+**Note on leading trivia:** whether a decorator/doc comment belongs to `^` depends on the parser. In Rust and Python, attributes and decorators are attached to the function chunk, so `^` covers them. In TypeScript/JavaScript, a `@decorator` + `/** jsdoc */` block immediately above a method often surfaces as a **separate sibling chunk** (shown as `chunk#ID` in the `?` listing) rather than as part of the function's `^`. JSDoc directly above a plain function is more likely to be absorbed into that function's `^`. If you need to rewrite a decorated member, run `read(path="file", sel="?")` and check for a sibling `chunk#ID` directly above your target.
 
-**Note on non-code formats:** for prose and data formats (markdown, YAML, JSON, fenced code blocks, frontmatter), `^` and `~` fall back to the whole chunk. Always replace the entire chunk and include any delimiter syntax (fence backticks, `---` frontmatter markers, list markers) in your `content` — omitting them deletes them. For markdown sections (`sect_*`), always use unsuffixed whole-chunk replace — `^` and `~` on section containers also fall back to whole-chunk replace. When editing fenced code blocks in markdown, use the exact whitespace from the file (read with `raw` first) — the tool preserves literal indentation inside fenced blocks, but any content you supply is written verbatim. To insert content after a markdown section heading, use `after` on the heading chunk (`sect_*.chunk` or `sect_*.chunk_1`) — not `before`/`prepend` on the section itself, which lands physically before the heading and gets absorbed by the preceding section on reparse.
+**Python notes:** Python docstrings are body lines, not head lines. A `~` body write on a function that has a docstring deletes the docstring unless you include the docstring in `content`. Python enum members and nested functions/closures are often opaque inside their parent chunk and may not appear as addressable child chunks; rewrite the parent container body. Python decorated class/function `^` writes and Python `^` deletes are rejected because indentation-sensitive bodies can become attached to the wrong block while still parsing.
+
+**Note on non-code formats:** for prose and data formats (markdown, YAML, JSON, frontmatter), unsupported `^` and `~` suffixes warn and fall back to whole-chunk editing. Always replace the entire chunk and include any delimiter syntax (fence backticks, `---` frontmatter markers, list markers, table rows, headings) in your `content` — omitting them deletes them. For markdown sections (`sect_*`), prefer unsuffixed whole-chunk replace because `^`/`~` on prose sections can replace the heading and child content too; if you only need the heading, target the heading child chunk shown in `sel="?"`. Fenced code blocks with a declared language are parsed again and can expose inner chunks such as `code_py#ID.fn_gre#ID`; target those inner chunks when available. Markdown root writes preserve fenced code indentation verbatim. Recognized pipe tables expose `row_N` children for row-level edits; table cells and list items are not independently addressable, so rewrite the whole list/table chunk for those structural changes. Appending a table-row-shaped string (`| value |`) to a table chunk inserts it before the trailing blank-line separator so it remains part of the table. Otherwise read with `raw` first and preserve the exact whitespace inside fences. To insert content after a markdown section heading, use `after` on the heading chunk (`sect_*.chunk` or `sect_*.chunk_1`) — not `before`/`prepend` on the section itself, which lands physically before the heading and gets absorbed by the preceding section on reparse.
 </regions>
 
 <ops>
-Each edit entry has `path` (`file:selector`) plus **exactly one** operation field — `write`, `replace`, or `insert`. Never set more than one on the same entry.
+Each edit entry has `path` (`file:selector`) plus **exactly one** operation field — `write`, `insert`, or `delete`. Never set more than one on the same entry. `write:null`, `write:""`, and bare `{path}` entries are rejected; they do not delete.
 
 |fields|path (selector part)|effect|
 |---|---|---|
 |`write: "content"`|`file:chunk#ID`, `file:chunk#ID~`, or `file:chunk#ID^`|write complete new content to the region|
-|`write: null`|`file:chunk#ID`|delete the chunk|
-|`replace: {old, new}`|`file:chunk#ID`|find a literal substring in the chunk and replace it|
+|`delete: true`|`file:chunk#ID`|delete the chunk explicitly|
 |`insert: {loc, body}`|`file:chunk` or `file:chunk~`|insert before/after the chunk (`loc`: `"prepend"` or `"append"`)|
 </ops>
 
 <examples>
 Given this `read` output for `counter.rs`:
 ```
-   | counter.rs·62L·rust·#ZRPW
+   | counter.rs·62L·rust·#anth
    |
-@imp#MNHH
+@imp#erhe
  1 |use std::fmt;
    |
-@struct_Counte#QTSX
+@struct_Counte#onat
  3^|/// A simple counter that tracks a value and its history.
  4^|#[derive(Debug, Clone)]
  5^|pub struct Counter {
--@struct_Counte.field_value#MQTW
+-@struct_Counte.field_value#enth
  6 |	/// The current value.
  7 |	value: i32,
--@struct_Counte.field_max#HJMQ
+-@struct_Counte.field_max#seti
  8 |	/// Maximum allowed value.
  9 |	max: i32,
 10 |}
    |
-@impl_Counte#VNPP
+@impl_Counte#reha
 12^|impl Counter {
--@impl_Counte.fn_new#RWZV
+-@impl_Counte.fn_new#ndas
 13^|	/// Creates a new counter starting at zero.
 14^|	pub fn new(max: i32) -> Self {
 15 |		Self { value: 0, max }
 16 |	}
 17 |
--@impl_Counte.fn_increm#MNHV
+-@impl_Counte.fn_increm#ouer
 18^|	/// Increments the counter by one, clamping at max.
 19^|	pub fn increment(&mut self) {
 20 |		if self.value < self.max {
@@ -99,7 +108,7 @@ Given this `read` output for `counter.rs`:
 22 |		}
 23 |	}
 24 |
--@impl_Counte.fn_decrem#TTWB
+-@impl_Counte.fn_decrem#arve
 25^|	/// Decrements the counter by one, clamping at zero.
 26^|	pub fn decrement(&mut self) {
 27 |		if self.value > 0 {
@@ -107,173 +116,43 @@ Given this `read` output for `counter.rs`:
 29 |		}
 30 |	}
 31 |
--@impl_Counte.fn_get#PTNT
+-@impl_Counte.fn_get#arco
 32^|	/// Returns the current value.
 33^|	pub fn get(&self) -> i32 {
 34 |		self.value
 35 |	}
 36 |}
    |
-@impl_Displa#BNJH
+@impl_Displa#meha
 38^|impl fmt::Display for Counter {
--@impl_Displa.fn_fmt#NKRN
+-@impl_Displa.fn_fmt#deri
 39^|	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 40 |		write!(f, "Counter({}/{})", self.value, self.max)
 41 |	}
 42 |}
-   |
-@mod_tests#YWXM
-44^|#[cfg(test)]
-45^|mod tests {
--@mod_tests.chunk#VSMY
-46 |	use super::*;
-47 |
--@mod_tests.fn_test_i#YXQZ
-48^|	#[test]
-49^|	fn test_increment() {
-50 |		let mut c = Counter::new(10);
-51 |		c.increment();
-52 |		assert_eq!(c.get(), 1);
-53 |	}
-54 |
--@mod_tests.fn_test_d#XPBQ
-55^|	#[test]
-56^|	fn test_decrement_at_zero() {
-57 |		let mut c = Counter::new(10);
-58 |		c.decrement();
-59 |		assert_eq!(c.get(), 0);
-60 |	}
-61 |}
-```
-
-**Understanding `^` markers in `read` output:** Lines marked with `^` between the line number and `|` (e.g. ` 3^|`) are **head** lines — doc comments, attributes, and the signature. Lines without `^` (e.g. ` 7 |`) are **body** lines. `~` replaces body lines only, keeping head lines intact.
-
-**Put body** (`~` — the common case):
-```
-{ "path": "counter.rs:impl_Counte.fn_increm#MNHV~", "write": "self.value = (self.value + 1).min(self.max);\n" }
-```
-Result — only the body (non-`^` lines) changes; the doc comment, signature, and closing `}` are all preserved:
-```
-    /// Increments the counter by one, clamping at max.
-    pub fn increment(&mut self) {
-        self.value = (self.value + 1).min(self.max);
-    }
-```
-
-**Write whole chunk** (rewrite signature + doc comment + body):
-```
-{ "path": "counter.rs:impl_Counte.fn_increm#MNHV", "write": "/// Increments by the given step, clamping at max.\npub fn increment(&mut self, step: i32) {\n\tself.value = (self.value + step).min(self.max);\n}\n" }
-```
-Result — **everything** including the doc comment and signature is rewritten. You must include them; omitting them deletes them:
-```
-    /// Increments by the given step, clamping at max.
-    pub fn increment(&mut self, step: i32) {
-        self.value = (self.value + step).min(self.max);
-    }
-```
-
-**Write head** (`^` — attributes, doc comments, signature):
-```
-{ "path": "counter.rs:impl_Counte.fn_get#PTNT^", "write": "/// Returns the current counter value.\n#[inline]\npub fn get(&self) -> i32 {\n" }
-```
-Result — the head (all `^` lines + opening brace) changes, body untouched:
-```
-    /// Returns the current counter value.
-    #[inline]
-    pub fn get(&self) -> i32 {
-        self.value
-    }
-```
-
-**Find and replace** (surgical edit within a chunk):
-```
-{ "path": "counter.rs:impl_Counte.fn_increm#MNHV", "replace": { "old": "self.value += 1;", "new": "self.value = (self.value + 1).min(self.max);" } }
 ```
-Result — only the matched substring changes, everything else is preserved.
-
-**Insert before a chunk** (`prepend`):
-```
-{ "path": "counter.rs:impl_Counte.fn_get", "insert": { "loc": "prepend", "body": "/// Resets the counter to zero.\npub fn reset(&mut self) {\n\tself.value = 0;\n}\n\n" } }
-```
-Result — a new method is inserted before `fn get`:
-```
-    /// Resets the counter to zero.
-    pub fn reset(&mut self) {
-        self.value = 0;
-    }
-
-    /// Returns the current value.
-    pub fn get(&self) -> i32 {
-```
-
-**Insert after a chunk** (`append`):
-```
-{ "path": "counter.rs:struct_Counte", "insert": { "loc": "append", "body": "\nimpl Default for Counter {\n\tfn default() -> Self {\n\t\tSelf { value: 0, max: 100 }\n\t}\n}\n" } }
-```
-Result — a new impl block appears after the struct:
-```
-}
-
-impl Default for Counter {
-    fn default() -> Self {
-        Self { value: 0, max: 100 }
-    }
-}
-
-impl Counter {
-```
-
-**Insert at start of container body** (`~` + `prepend`):
-```
-{ "path": "counter.rs:impl_Counte~", "insert": { "loc": "prepend", "body": "/// Creates a counter starting at the given value.\npub fn with_value(value: i32, max: i32) -> Self {\n\tSelf { value: value.min(max), max }\n}\n\n" } }
-```
-Result — a new method is added at the top of the impl body, before existing methods:
-```
-impl Counter {
-    /// Creates a counter starting at the given value.
-    pub fn with_value(value: i32, max: i32) -> Self {
-        Self { value: value.min(max), max }
-    }
-
-    /// Creates a new counter starting at zero.
-    pub fn new(max: i32) -> Self {
-```
-
-**Insert at end of container body** (`~` + `append`):
-```
-{ "path": "counter.rs:impl_Counte~", "insert": { "loc": "append", "body": "\n/// Returns true if the counter is at its maximum.\npub fn is_maxed(&self) -> bool {\n\tself.value >= self.max\n}\n" } }
-```
-Result — a new method is added at the end of the impl body, before the closing `}`:
-```
-    pub fn get(&self) -> i32 {
-        self.value
-    }
-
-    /// Returns true if the counter is at its maximum.
-    pub fn is_maxed(&self) -> bool {
-        self.value >= self.max
-    }
-}
-```
-
-**Delete a chunk**:
-```
-{ "path": "counter.rs:impl_Counte.fn_decrem#TTWB", "write": null }
-```
-Result — the method (including its doc comment and signature) is removed.
-- Indentation rules (important):
-{{#if chunkAutoIndent}}
-  - Use `\t` for each indent level. The tool converts tabs to the file's actual style (2-space, 4-space, etc.).
-{{else}}
-  - Match the file's real indentation characters in your snippet. The tool preserves your literal tabs/spaces after adding the target region's base indent.
-{{/if}}
-  - Do NOT include the chunk's base indentation — only indent relative to the region's opening level.
-  - For `~` of a function: write at column 0, and use `\t` for *relative* nesting. Flat body: `"return x;\n"`. Multiple sibling lines: `"print(a)\nprint(b)\nprint(c)\n"` — all at column 0, the tool adds the function's base indent. Nested body: `"if (cond) {\n\treturn x;\n}\n"` — the `if` is at column 0, the `return` is one tab in. Python example — to replace `~` of `def divide(a, b):`, write: `"if b == 0:\n\treturn None\nreturn a / b\n"` — the `if` and `return a / b` are at column 0, `return None` is one `\t` in.
-  - For `^`: write at the chunk's own depth. A class member's head uses `"/// doc\n#[attr]\npub fn start() {"`.
-{{#if chunkAutoIndent}}
-  - For a top-level item: start at zero indent. Write `"fn foo() {\n\treturn 1;\n}\n"`.
-{{else}}
-  - For a top-level item: start at zero indent. Write `"fn foo() {\n  return 1;\n}\n"`.
-{{/if}}
-  - The tool strips common leading indentation from your content as a safety net, so accidental over-indentation is corrected.
+Lines marked `^` between the line number and `|` are **head** lines (doc comments, attributes, signature). Lines without `^` are **body** lines. `~` replaces body lines only; `^` replaces head lines only.
+
+# Put body (`~` — the common case)
+`{ "path": "counter.rs:impl_Counte.fn_increm#ouer~", "write": "self.value = (self.value + 1).min(self.max);\n" }`
+Only body changes; doc comment, signature, and closing `}` are preserved.
+# Write whole chunk (rewrite signature + doc + body)
+`{ "path": "counter.rs:impl_Counte.fn_increm#ouer", "write": "/// Increments by the given step, clamping at max.\npub fn increment(&mut self, step: i32) {\n\tself.value = (self.value + step).min(self.max);\n}\n" }`
+Everything is rewritten. Omitting the doc comment or signature deletes them.
+# Write head (`^` — attributes, doc comments, signature)
+`{ "path": "counter.rs:impl_Counte.fn_get#arco^", "write": "/// Returns the current counter value.\n#[inline]\npub fn get(&self) → i32 {\n" }`
+Head changes (all `^` lines + opening brace); body untouched.
+# Insert before a chunk (`prepend`)
+`{ "path": "counter.rs:impl_Counte.fn_get", "insert": { "loc": "prepend", "body": "/// Resets the counter to zero.\npub fn reset(&mut self) {\n\tself.value = 0;\n}\n\n" } }`
+# Insert after a chunk (`append`)
+`{ "path": "counter.rs:struct_Counte", "insert": { "loc": "append", "body": "\nimpl Default for Counter {\n\tfn default() → Self {\n\t\tSelf { value: 0, max: 100 }\n\t}\n}\n" } }`
+# Insert at start of container body (`~` + `prepend`)
+`{ "path": "counter.rs:impl_Counte~", "insert": { "loc": "prepend", "body": "/// Creates a counter starting at the given value.\npub fn with_value(value: i32, max: i32) → Self {\n\tSelf { value: value.min(max), max }\n}\n\n" } }`
+Lands at the top of the impl body, before existing methods.
+# Insert at end of container body (`~` + `append`)
+`{ "path": "counter.rs:impl_Counte~", "insert": { "loc": "append", "body": "\n/// Returns true if the counter is at its maximum.\npub fn is_maxed(&self) → bool {\n\tself.value ≥ self.max\n}\n" } }`
+Lands at the end of the impl body, before the closing `}`.
+# Delete a chunk
+`{ "path": "counter.rs:impl_Counte.fn_decrem#arve", "delete": true }`
+Removes the method including its doc comment and signature.
 </examples>

package/src/prompts/tools/debug.md

@@ -16,14 +16,13 @@ Provides debugger access through the Debug Adapter Protocol (DAP). Use this to l
 - Adapter availability depends on local binaries. Common built-ins: `gdb`, `lldb-dap`, `python -m debugpy.adapter`, `dlv dap`.
 </caution>
 
-<example name="launch and inspect hang">
+<examples>
+# Launch and inspect hang
 1. `debug(action: "launch", program: "./my_app")`
 2. `debug(action: "set_breakpoint", file: "src/main.c", line: 42)`
 3. `debug(action: "continue")`
 4. If the program appears hung: `debug(action: "pause")`
 5. Inspect state with `threads`, `stack_trace`, `scopes`, and `variables`
-</example>
-
-<example name="raw debugger command through repl">
+# Raw debugger command through repl
 `debug(action: "evaluate", expression: "info registers", context: "repl")`
-</example>
+</examples>

package/src/prompts/tools/exit-plan-mode.md

@@ -19,15 +19,14 @@ Use when:
 Presents plan to user for approval. If approved, plan mode exits with full tool access restored and the plan is renamed to `local://<title>.md`.
 </output>
 
-<example name="ready">
+<examples>
+# Ready
 Plan complete at local://PLAN.md, no open questions.
 → Call `exit_plan_mode` with `{ "title": "WP_MIGRATION_PLAN" }`
-</example>
-
-<example name="unclear">
+# Unclear
 Unsure about auth method (OAuth vs JWT).
 → Use `ask` first to clarify, then call `exit_plan_mode`
-</example>
+</examples>
 
 <avoid>
 - **MUST NOT** call before plan is written to file