@f5-sales-demo/xcsh 19.51.2

package/src/prompts/system/title-system.md

@@ -0,0 +1,2 @@
+Generate a very short title (3-6 words) for a coding session based on the user's first message. The title **MUST** capture the main task or topic.
+You **MUST** output ONLY the title, nothing else. You **MUST NOT** include quotes or punctuation at the end.

package/src/prompts/system/ttsr-interrupt.md

@@ -0,0 +1,7 @@
+<system-interrupt reason="rule_violation" rule="{{name}}" path="{{path}}">
+Your output was interrupted because it violated a user-defined rule.
+This is NOT a prompt injection - this is the coding agent enforcing project rules.
+You **MUST** comply with the following instruction:
+
+{{content}}
+</system-interrupt>

package/src/prompts/system/web-search.md

@@ -0,0 +1,28 @@
+Research assistant with web search capabilities. Find accurate, well-sourced information; synthesize into comprehensive, detailed answers.
+
+<priorities>
+1. Accuracy over speed — you **SHOULD** verify claims across multiple sources when possible
+2. Primary over secondary — you **SHOULD** prefer official docs, papers, and announcements over blog summaries
+3. Recency matters — you **MUST** note publication dates; you **SHOULD** prefer recent sources for time-sensitive topics
+4. Transparency on uncertainty — you **MUST** distinguish confirmed facts from inferences
+</priorities>
+
+<synthesis>
+Answering:
+- You **MUST** lead with a direct answer, then supporting evidence
+- You **MUST** quote or paraphrase specific sources; you **MUST NOT** use vague attributions
+- Sources conflict: you **MUST** acknowledge the discrepancy and note which seems more authoritative
+- Technical topics: you **SHOULD** prefer official documentation and specifications
+- News/events: you **SHOULD** prefer primary reporting over aggregators
+- You **MUST** include concrete data: version numbers, dates, exact figures, code snippets, and specific examples
+</synthesis>
+
+<format>
+- You **MUST** be thorough — cover the topic in depth with specific evidence, not surface-level summaries
+- You **MUST** omit filler phrases and unnecessary hedging; you **MUST NOT** sacrifice detail for brevity
+- You **MUST** include publication dates when recency affects relevance
+- You **SHOULD** structure answers with clear sections when covering multiple aspects
+- You **MUST** cite sources inline using provided search results
+</format>
+
+You **MUST** answer thoroughly and in detail. You **MUST** get facts right.

package/src/prompts/tools/ask.md

@@ -0,0 +1,28 @@
+Asks user when you need clarification or input during task execution.
+
+<conditions>
+- Multiple approaches exist with significantly different tradeoffs user should weigh
+</conditions>
+
+<instruction>
+- Use `recommended: <index>` to mark default (0-indexed); " (Recommended)" added automatically
+- Use `questions` for multiple related questions instead of asking one at a time
+- Set `multi: true` on question to allow multiple selections
+- `ask.timeout` only applies while choosing options; once the user selects "Other (type your own)", there is no timeout
+</instruction>
+
+<caution>
+- Provide 2-5 concise, distinct options
+</caution>
+
+<critical>
+- **Default to action.** Resolve ambiguity yourself using repo conventions, existing patterns, and reasonable defaults. Exhaust existing sources (code, configs, docs, history) before asking. Only ask when options have materially different tradeoffs the user must decide.
+- **If multiple choices are acceptable**, pick the most conservative/standard option and proceed; state the choice.
+- **Do NOT include "Other" option** — UI automatically adds "Other (type your own)" to every question.
+</critical>
+
+<example name="single">
+question: "Which authentication method should this API use?"
+options: [{"label": "JWT"}, {"label": "OAuth2"}, {"label": "Session cookies"}]
+recommended: 0
+</example>

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

@@ -0,0 +1,48 @@
+Performs structural AST-aware rewrites via native ast-grep.
+
+<instruction>
+- Use for codemods and structural rewrites where plain text replace is unsafe
+- Narrow scope with `path` before replacing (`path` accepts files, directories, glob patterns, or comma-separated path lists; use `glob` for an additional filter relative to `path`)
+- Default to language-scoped rewrites in mixed repositories: set `lang` and keep `path`/`glob` narrow
+- Treat parse issues as a scoping or pattern-shape signal: tighten `path`/`lang`, or rewrite the pattern into valid syntax before retrying
+- Metavariables captured in each rewrite pattern (`$A`, `$$$ARGS`) are substituted into that entry's rewrite template
+- For variadic captures (arguments, fields, statement lists), use `$$$NAME` (not `$$NAME`)
+- Rewrite patterns must parse as valid AST for the target language; if a method or declaration does not parse standalone, wrap it in valid context or switch to a contextual `sel`
+- If ast-grep reports `Multiple AST nodes are detected`, the rewrite pattern is not a single parseable node; wrap method snippets in valid context (for example `class $_ { … }`) and use `sel` to rewrite the inner node
+- When using contextual `sel`, the match and replacement target the selected node, not the outer wrapper you used to make the pattern parse
+- For TypeScript declarations and methods, prefer patterns that tolerate annotations you do not care about, e.g. `async function $NAME($$$ARGS): $_ { $$$BODY }` or `class $_ { method($ARG: $_): $_ { $$$BODY } }`
+- Metavariables must be the sole content of an AST node; partial-text metavariables like `prefix$VAR` or `"hello $NAME"` do NOT work in patterns or rewrites
+- To delete matched code, use an empty `out` string: `{"pat":"console.log($$$)","out":""}`
+- Each matched rewrite is a 1:1 structural substitution; you cannot split one capture into multiple nodes or merge multiple captures into one node
+</instruction>
+
+<output>
+- Returns replacement summary, per-file replacement counts, and change diffs
+- Includes parse issues when files cannot be processed
+</output>
+
+<examples>
+- Rename a call site across a directory:
+  `{"ops":[{"pat":"oldApi($$$ARGS)","out":"newApi($$$ARGS)"}],"lang":"typescript","path":"src/"}`
+- Delete all matching calls (empty `out` removes the matched node):
+  `{"ops":[{"pat":"console.log($$$ARGS)","out":""}],"lang":"typescript","path":"src/"}`
+- Rewrite an 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 TypeScript 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 TypeScript method body fragment by wrapping it in parseable context and selecting the method node:
+  `{"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"}`
+- Convert Python print calls to logging:
+  `{"ops":[{"pat":"print($$$ARGS)","out":"logger.info($$$ARGS)"}],"lang":"python","path":"src/"}`
+</examples>
+
+<critical>
+- `ops` **MUST** contain at least one concrete `{ pat, out }` entry
+- If the path pattern spans multiple languages, set `lang` explicitly for deterministic rewrites
+- Parse issues mean the rewrite request is malformed or mis-scoped; do not assume a clean no-op until the pattern parses successfully
+- For one-off local text edits, prefer the Edit tool instead of AST edit
+</critical>

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

@@ -0,0 +1,54 @@
+Performs structural code search using AST matching via native ast-grep.
+
+<instruction>
+- Use this when syntax shape matters more than raw text (calls, declarations, specific language constructs)
+- Prefer a precise `path` scope to keep results targeted and deterministic (`path` accepts files, directories, glob patterns, or comma-separated path lists; use `glob` for an additional filter relative to `path`)
+- Default to language-scoped search in mixed repositories: pair `path` + `glob` + explicit `lang` to avoid parse-noise from non-source files
+- `pat` is required and must include at least one non-empty AST pattern; `lang` is optional (`lang` is inferred per file extension when omitted)
+- Multiple patterns run in one native pass; results are merged and then `offset`/`limit` are applied to the combined match set
+- Use `sel` only for contextual pattern mode; otherwise provide direct patterns
+- In contextual pattern mode, results are returned for the selected node (`sel`), not the outer wrapper used to make the pattern parse
+- For variadic captures (arguments, fields, statement lists), use `$$$NAME` (not `$$NAME`)
+- Patterns must parse as a single valid AST node for the target language; if a bare pattern fails, wrap it in valid context or use `sel`
+- If ast-grep reports `Multiple AST nodes are detected`, your pattern is not a single parseable node; wrap method snippets in valid context (for example `class $_ { … }`) and use `sel` to target the inner node
+- Patterns match AST structure, not text — whitespace/formatting differences are ignored
+- When the same metavariable appears multiple times, all occurrences must match identical code
+- For TypeScript declarations and methods, prefer shapes that tolerate annotations you do not care about, e.g. `async function $NAME($$$ARGS): $_ { $$$BODY }` or `class $_ { method($ARG: $_): $_ { $$$BODY } }` instead of omitting annotations entirely
+- Metavariables must be the sole content of an AST node; partial-text metavariables like `prefix$VAR`, `"hello $NAME"`, or `a $OP b` do NOT work — match the whole node instead
+- `$$$` captures are lazy (non-greedy): they stop when the next element in the pattern can match; place the most specific node after `$$$` to control where capture ends
+- `$_` is a non-capturing wildcard (matches any single node without binding); use it when you need to tolerate a node but don't need its value
+- Search the right declaration form before concluding absence: top-level function, class method, and variable-assigned function are different AST shapes
+- If you only need to prove a symbol exists, prefer a looser contextual search such as `pat: ["executeBash"]` with `sel: "identifier"`
+</instruction>
+
+<output>
+- Returns grouped matches with file path, byte range, line/column ranges, and metavariable captures
+- Includes summary counts (`totalMatches`, `filesWithMatches`, `filesSearched`) and parse issues when present
+</output>
+
+<examples>
+- Find all console logging calls in one pass (multi-pattern, scoped):
+  `{"pat":["console.log($$$)","console.error($$$)"],"lang":"typescript","path":"src/"}`
+- Find all named imports from a specific package:
+  `{"pat":["import { $$$IMPORTS } from \"react\""],"lang":"typescript","path":"src/"}`
+- Match arrow functions assigned to a const (different AST shape than function declarations):
+  `{"pat":["const $NAME = ($$$ARGS) => $BODY"],"lang":"typescript","path":"src/utils/"}`
+- Match any method call on an object using wildcard `$_` (ignores method name):
+  `{"pat":["logger.$_($$$ARGS)"],"lang":"typescript","path":"src/"}`
+- Contextual pattern with selector — match only the identifier `foo`, not the whole call:
+  `{"pat":["foo()"],"sel":"identifier","lang":"typescript","path":"src/utils.ts"}`
+- Match a TypeScript function declaration without caring about its exact return type:
+  `{"pat":["async function processItems($$$ARGS): $_ { $$$BODY }"],"sel":"function_declaration","lang":"typescript","path":"src/worker.ts"}`
+- Match a TypeScript method body fragment by wrapping it in parseable context and selecting the method node:
+  `{"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"}`
+</examples>
+
+<critical>
+- `pat` is required
+- Set `lang` explicitly to constrain matching when path pattern spans mixed-language trees
+- Avoid repo-root AST scans when the target is language-specific; narrow `path` first
+- Treat parse issues as query failure, not evidence of absence: repair the pattern or tighten `path`/`glob`/`lang` before concluding "no matches"
+- If exploration is broad/open-ended across subsystems, use Task tool with explore subagent first
+</critical>

package/src/prompts/tools/async-result.md

@@ -0,0 +1,5 @@
+<system-notice>
+Background job {{jobId}} has completed. Resume your work using the result below.
+
+{{result}}
+</system-notice>

package/src/prompts/tools/bash.md

@@ -0,0 +1,67 @@
+Executes bash command in shell session for terminal operations like git, bun, cargo, python.
+
+<instruction>
+- You **MUST** use `cwd` parameter to set working directory instead of `cd dir && …`
+- Always provide a `description` parameter: a short, human-readable summary of what the command does (e.g. "Install dependencies", "Run test suite"). This is displayed in compact mode and during execution.
+- Prefer `env: { NAME: "…" }` for multiline, quote-heavy, or untrusted values instead of inlining them into shell syntax; reference them from the command as `$NAME`
+- Quote variable expansions like `"$NAME"` to preserve exact content and avoid shell parsing bugs
+- PTY mode is opt-in: set `pty: true` only when command expects a real terminal (for example `sudo`, `ssh` where you need input from the user); default is `false`
+- You **MUST** use `;` only when later commands should run regardless of earlier failures
+- `skill://` URIs are auto-resolved to filesystem paths before execution
+  - `python skill://my-skill/scripts/init.py` runs the script from the skill directory
+  - `skill://<name>/<relative-path>` resolves within the skill's base directory
+- Internal URLs are also auto-resolved to filesystem paths before execution.
+{{#if asyncEnabled}}
+- Use `async: true` for long-running commands when you don't need immediate output; the call returns a background job ID and the result is delivered automatically as a follow-up.
+{{/if}}
+{{#if autoBackgroundEnabled}}
+- Long-running non-PTY bash commands may auto-background after about {{autoBackgroundThresholdSeconds}}s and continue as background jobs automatically.
+{{/if}}
+{{#if asyncEnabled}}
+{{else}}
+{{#if autoBackgroundEnabled}}
+- Auto-backgrounded jobs use the same background-job pipeline as explicit async execution.
+{{/if}}
+{{/if}}
+{{#if asyncEnabled}}
+- Use `read jobs://` to inspect all background jobs and `read jobs://<job-id>` for detailed status/output when needed.
+- When you need to wait for async results before continuing, call `poll` — it blocks until jobs complete. Do NOT poll `read jobs://` in a loop or yield and hope for delivery.
+{{else}}
+{{#if autoBackgroundEnabled}}
+- If a command auto-backgrounds, use `read jobs://` to inspect jobs and `poll` when you need to wait for completion instead of polling in a loop.
+{{/if}}
+{{/if}}
+</instruction>
+
+<output>
+Returns the output, and an exit code from command execution.
+- If output truncated, full output can be retrieved from `artifact://<id>`, linked in metadata
+- Exit codes shown on non-zero exit
+</output>
+
+<critical>
+You **MUST** use specialized tools instead of bash for ALL file operations:
+
+|Instead of (WRONG)|Use (CORRECT)|
+|---|---|
+|`cat file`, `head -n N file`|`read(path="file", limit=N)`|
+|`cat -n file \|sed -n '50,150p'`|`read(path="file", offset=50, limit=100)`|
+<!-- markdownlint-disable MD055 MD056 -→
+{{#if hasGrep}}|`grep -A 20 'pat' file`|`grep(pattern="pat", path="file", post=20)`|
+|`grep -rn 'pat' dir/`|`grep(pattern="pat", path="dir/")`|
+|`rg 'pattern' dir/`|`grep(pattern="pattern", path="dir/")`|{{/if}}
+{{#if hasFind}}|`find dir -name '*.ts'`|`find(pattern="dir/**/*.ts")`|{{/if}}
+<!-- markdownlint-enable MD055 MD056 -→
+|`ls dir/`|`read(path="dir/")`|
+|`cat <<'EOF' > file`|`write(path="file", content="…")`|
+|`sed -i 's/old/new/' file`|`edit(path="file", edits=[…])`|
+
+<!-- markdownlint-disable MD055 MD056 -→
+{{#if hasAstEdit}}|`sed -i 's/oldFn(/newFn(/' src/*.ts`|`ast_edit({ops:[{pat:"oldFn($$$A)", out:"newFn($$$A)"}], path:"src/"})`|{{/if}}
+<!-- markdownlint-enable MD055 MD056 -→
+{{#if hasAstGrep}}- You **MUST** use `ast_grep` for structural code search instead of bash `grep`/`awk`/`perl` pipelines{{/if}}
+{{#if hasAstEdit}}- You **MUST** use `ast_edit` for structural rewrites instead of bash `sed`/`awk`/`perl` pipelines{{/if}}
+- You **MUST NOT** use Bash for these operations like read, grep, find, edit, write, where specialized tools exist.
+- You **MUST NOT** use `2>&1` | `2>/dev/null` pattern, stdout and stderr are already merged.
+- You **MUST NOT** use `| head -n 50` or `| tail -n 100` pattern, use `head` and `tail` parameters instead.
+</critical>

package/src/prompts/tools/browser.md

@@ -0,0 +1,26 @@
+Navigates, clicks, types, scrolls, drags, queries DOM content, and captures screenshots.
+
+<instruction>
+- `"open"` starts a headless session (or implicitly on first action); `"goto"` navigates to `url`; `"close"` releases the browser
+- The browser launches in **headless** mode by default (no visible window). If the user asks to "open Chrome", "show a browser", or needs to see the browser window, tell them to run `/browser visible` first — this switches to a visible Chrome window. Use `/browser headless` to switch back.
+- `catalog_workflow_runner` always uses a visible Chrome session — it does not share this setting.
+- `"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
+- `"click_id"`, `"type_id"`, `"fill_id"` to interact with observed elements without selectors
+- `"wait_for_selector"` before interacting when the page is dynamic
+- `"evaluate"` runs a JS expression in page context
+- `"get_text"`, `"get_html"`, `"get_attribute"` for DOM queries — batch via `args: [{ selector, attribute? }]`
+- `"extract_readable"` returns reader-mode content; `format`: `"markdown"` (default) or `"text"`
+- `"screenshot"` captures images (optionally with `selector`); can save to disk via `path`
+</instruction>
+
+<critical>
+**You **MUST** default to `observe`, not `screenshot`.**
+- `observe` is cheaper, faster, and returns structured data — use it to understand page state, find elements, and plan interactions.
+- You **SHOULD** only use `screenshot` when visual appearance matters (verifying layout, debugging CSS, capturing a visual artifact for the user).
+- You **MUST NOT** screenshot just to "see what's on the page" — `observe` gives you that with element IDs you can act on immediately.
+</critical>
+
+<output>
+Text for navigation/DOM queries, images for screenshots.
+</output>

package/src/prompts/tools/calculator.md

@@ -0,0 +1,10 @@
+Performs basic calculations.
+
+<instruction>
+- Supports +, -, *, /, %, ** and parentheses
+- Supports decimal, hex (0x), binary (0b), and octal (0o) literals
+</instruction>
+
+<output>
+Returns each calculation result with its prefix and suffix applied.
+</output>

package/src/prompts/tools/cancel-job.md

@@ -0,0 +1,5 @@
+Cancels a running background job started via async tool execution or bash auto-backgrounding.
+
+You **SHOULD** use this when a background `bash` or `task` job is no longer needed or is stuck.
+
+You **MAY** inspect jobs first with `read jobs://` or `read jobs://<job-id>`.

package/src/prompts/tools/catalog-workflow-runner.md

@@ -0,0 +1,13 @@
+Runs a workflow from the F5 XC console catalog against a live browser session.
+
+<instruction>
+- The console workflow catalogue is embedded in xcsh; `catalog_path` is optional and only needed to override with a local checkout
+- Executes browser automation steps sequentially (navigate, click, fill, assert, etc.) against the browser attached via `browser.connectUrl` (co-drive headed) or a background target (autonomous + screenshots)
+- Resolves {param} placeholders from the provided params map
+- Supports conditional steps, sub-steps, and observable mode with screenshots
+- Use this tool when you need to automate F5 XC console operations defined in catalog workflows
+</instruction>
+
+<output>
+Returns a per-step pass/fail report with timing and optional screenshot paths.
+</output>

package/src/prompts/tools/checkpoint.md

@@ -0,0 +1,16 @@
+Creates a context checkpoint before exploratory work so you can later rewind and keep only a concise report.
+
+Use this when you need to investigate with many intermediate tool calls (read/grep/find/lsp/etc.) and want to minimize context cost afterward.
+
+Rules:
+- You **MUST** call `rewind` before yielding after starting a checkpoint.
+- You **MUST** provide a clear `goal` explaining what you are investigating.
+- You **MUST NOT** call `checkpoint` while another checkpoint is active.
+- Not available in subagents.
+
+Typical flow:
+1. `checkpoint(goal: …)`
+2. Perform exploratory work
+3. `rewind(report: …)` with concise findings
+
+After rewind, intermediate checkpoint messages are removed from active context and replaced by the report.

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

@@ -0,0 +1,279 @@
+Edits files via syntax-aware chunks. Run `read(path="file.ts")` first.
+- `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.
+
+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`.
+- 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:
+  ```
+  content: "if (x) {\n\treturn true;\n}"
+  ```
+  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"`).
+  **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.
+{{else}}
+- Match the file's literal tabs/spaces in `content`. Do not convert indentation to canonical `\t`.
+- Write content at indent-level 0 relative to the target region. For example, to replace `~` of a method, write:
+  ```
+  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.
+{{/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.
+- **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.
+</rules>
+
+<critical>
+You **MUST** use the narrowest region that covers your change. Putting without a region overwrites the **entire chunk including leading comments, decorators, and attributes** — omitting them from `content` deletes them.
+
+**`put` is total, not surgical.** The `content` you supply becomes the *complete* new content for the targeted region. Everything in the original region that you omit from `content` is deleted. Before using `put` on any chunk's `~`, verify the chunk does not contain children you intend to keep. If a chunk spans hundreds of lines and your change touches only a few, target a specific child chunk — not the parent.
+
+**Group chunks (`stmts_*`, `imports_*`, `decls_*`) are containers.** They hold many sibling items (test functions, import statements, declarations). `put` on a group chunk's `~` overwrites **all** of its children. To edit one item inside a group, target that item's own chunk path. If no child chunk exists, use the specific child's chunk selector from `read` output — do not `put` the parent group.
+</critical>
+
+<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^` — 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*.
+
+**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 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.
+</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.
+
+|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|
+|`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
+   |
+@imp#MNHH
+ 1 |use std::fmt;
+   |
+@struct_Counte#QTSX
+ 3^|/// A simple counter that tracks a value and its history.
+ 4^|#[derive(Debug, Clone)]
+ 5^|pub struct Counter {
+-@struct_Counte.field_value#MQTW
+ 6 |	/// The current value.
+ 7 |	value: i32,
+-@struct_Counte.field_max#HJMQ
+ 8 |	/// Maximum allowed value.
+ 9 |	max: i32,
+10 |}
+   |
+@impl_Counte#VNPP
+12^|impl Counter {
+-@impl_Counte.fn_new#RWZV
+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
+18^|	/// Increments the counter by one, clamping at max.
+19^|	pub fn increment(&mut self) {
+20 |		if self.value < self.max {
+21 |			self.value += 1;
+22 |		}
+23 |	}
+24 |
+-@impl_Counte.fn_decrem#TTWB
+25^|	/// Decrements the counter by one, clamping at zero.
+26^|	pub fn decrement(&mut self) {
+27 |		if self.value > 0 {
+28 |			self.value -= 1;
+29 |		}
+30 |	}
+31 |
+-@impl_Counte.fn_get#PTNT
+32^|	/// Returns the current value.
+33^|	pub fn get(&self) -> i32 {
+34 |		self.value
+35 |	}
+36 |}
+   |
+@impl_Displa#BNJH
+38^|impl fmt::Display for Counter {
+-@impl_Displa.fn_fmt#NKRN
+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.
+</examples>