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

package/src/prompts/tools/find.md

@@ -8,14 +8,10 @@ Finds files using fast pattern matching that works with any codebase size.
 Matching file paths sorted by modification time (most recent first). Truncated at 1000 entries or 50KB (configurable via `limit`).
 </output>
 
-<example name="find files">
-```
-{
-  "pattern": "src/**/*.ts",
-  "limit": 1000
-}
-```
-</example>
+<examples>
+# Find files
+`{"pattern": "src/**/*.ts", "limit": 1000}`
+</examples>
 
 <avoid>
 For open-ended searches requiring multiple rounds of globbing and grepping, you **MUST** use Task tool instead.

package/src/prompts/tools/github.md

@@ -0,0 +1,18 @@
+GitHub CLI tool with a single op-based dispatch. Wraps `gh` for repository, issue, pull request, search, checkout, push, and Actions watch workflows.
+
+<instruction>
+Pick the operation via `op`. Each op uses a subset of the parameters:
+- `repo_view` — Read repository metadata. Optional `repo` (owner/repo) and `branch`. Falls back to the current checkout or default `gh` repo.
+- `issue_view` — Read an issue. Required `issue` (number or URL). Optional `repo`. Set `comments: false` to skip discussion.
+- `pr_view` — Read a pull request, including reviews and inline review comments. Optional `pr` (number, URL, or branch); omitting it targets the current branch's PR. Optional `repo`. Set `comments: false` for a lighter summary.
+- `pr_diff` — Read a pull request diff. Optional `pr`, `repo`. Set `nameOnly: true` for changed file names. Use `exclude` to drop generated paths from the diff.
+- `pr_checkout` — Check a pull request out into a dedicated git worktree. Optional `pr`, `repo`, `branch` (local), `worktree` (path), `force` (reset existing local branch).
+- `pr_push` — Push a checked-out PR branch back to its source branch. Requires the branch to have been checked out via `op: pr_checkout` (carries push metadata). Optional `branch`; defaults to the current checked-out git branch. Optional `forceWithLease`.
+- `search_issues` — Search issues using normal GitHub issue search syntax. Required `query`. Optional `repo`, `limit`.
+- `search_prs` — Search pull requests using normal GitHub PR search syntax. Required `query`. Optional `repo`, `limit`.
+- `run_watch` — Watch a GitHub Actions workflow run. Optional `run` (id or URL). Omitting `run` watches all workflow runs for the current HEAD commit; `branch` falls back to the current branch. Optional `tail` (log lines per failed job). Streams snapshots, fast-fails on the first detected job failure (with a brief grace period to capture concurrent failures), then fetches tailed logs for the failed jobs. The full failed-job logs are saved as a session artifact for on-demand reads.
+</instruction>
+
+<output>
+Returns a concise readable summary tailored to the chosen op (repo/issue/PR metadata, diff text, search results, checkout info, push target, or workflow run snapshot). For `run_watch`, the full failed-job logs are saved as a session artifact when failures occur.
+</output>

package/src/prompts/tools/grep.md

@@ -2,26 +2,26 @@ Searches files using powerful regex matching.
 
 <instruction>
 - Supports full regex syntax (e.g., `log.*Error`, `function\\s+\\w+`); literal braces need escaping (`interface\\{\\}` for `interface{}` in Go)
-- `path` also accepts comma-separated path lists; pair with `glob` when you need a relative file filter in addition to `type`
-- For cross-line patterns like `struct \\{[\\s\\S]*?field`, set `multiline: true`
-- If the pattern contains a literal `\n`, `multiline` defaults to true automatically
+- `path` is required and accepts a file, directory, glob, comma-separated path list, or internal URL
+- Cross-line patterns are detected from literal `\n` or escaped `\\n` in `pattern`
 </instruction>
 
 <output>
 {{#if IS_HASHLINE_MODE}}
-- Text output is CID prefixed: `LINE#ID:content`
+- Text output is anchor-prefixed: `123th:content` (match) or `123th-content` (context). The 2-letter ID is a content fingerprint.
 {{else}}
 {{#if IS_LINE_NUMBER_MODE}}
 - Text output is line-number-prefixed
 {{/if}}
 {{/if}}
 {{#if IS_CHUNK_MODE}}
-- Text output is chunk-path-prefixed: `path:selector>LINE|content`
+- Text output is chunk-path-prefixed: `path:sel>123th:content`
 {{/if}}
 </output>
 
 <critical>
-- You **MUST** use Grep when searching for content.
-- You **MUST NOT** invoke `grep` or `rg` via Bash.
-- If the search is open-ended, requiring multiple rounds, you **MUST** use Task tool with explore subagent instead.
+- You **MUST** use the built-in Grep tool for any content search. Do **NOT** shell out to `grep`, `rg`, `ripgrep`, `ag`, `ack`, `git grep`, `awk`, `sed`-for-search, or any other CLI search via Bash — even for a single match, even "just to check quickly", even piped through other commands.
+- Bash `grep`/`rg` returns raw text without chunk paths, loses `.gitignore` semantics, bypasses result limits, and wastes tokens. The Grep tool is faster, structured, and already wired into the workspace — there is no scenario where Bash search is preferable.
+- If you catch yourself typing `grep`, `rg`, or `| grep` in a Bash command, stop and re-issue the search through the Grep tool instead.
+- If the search is open-ended, requiring multiple rounds, you **MUST** use the Task tool with the explore subagent instead of chaining Grep calls yourself.
 </critical>

package/src/prompts/tools/hashline.md

@@ -1,22 +1,21 @@
-Applies precise file edits using `LINE#ID` anchors from `read` output.
+Applies precise file edits using full anchors from `read` output (for example `160sr`).
 
-Read the file first. Copy anchors exactly from the latest `read` output. After any successful edit, re-read before editing that file again.
+Read the file first. Copy the full anchors exactly as shown by `read`.
 
 <operations>
 **Top level**
 - `edits` — array of edit entries
+- `path` (optional) — default file path used when an entry omits its own `path`. Lets you share the path across many edits in one request.
 
-**Edit entry**: `{ path, loc, content }` or `{ path, delete: true }` or `{ path, move: "new/path" }`
-- `path` — file path
+**Edit entry**: `{ path?, loc, content }`
+- `path` — file path (omit to fall back to the request-level `path`)
 - `loc` — where to apply the edit (see below)
-- `content` — replacement/inserted lines (array of strings preferred, `null` to delete)
-- `delete` — delete the file
-- `move` — move/rename the file
+- `content` — replacement/inserted lines (`string[]`, one element per line; `null` to delete)
 
 **`loc` values**
 - `"append"` / `"prepend"` — insert at end/start of file
-- `{ append: "N#ID" }` / `{ prepend: "N#ID" }` — insert after/before anchored line
-- `{ range: { pos: "N#ID", end: "N#ID" } }` — replace inclusive range `pos..end` with new content (set `pos == end` for single-line replace)
+- `{ append: "123th" }` / `{ prepend: "123th" }` — insert after/before anchored line
+- `{ range: { pos: "123th", end: "123th" } }` — replace inclusive range `pos..end` with new content (set `pos == end` for single-line replace)
 </operations>
 
 <examples>
@@ -43,92 +42,26 @@ All examples below reference the same file:
 {{hline 18 "}"}}
 ```
 
-<example name="replace a block body">
+# Replace a block body
 Replace only the catch body. Do not target the shared boundary line `} catch (err) {`.
-
-```
-{
-  edits: [{
-    path: "a.ts",
-    loc: { range: { pos: {{href 15 "\t\tconsole.error(err);"}}, end: {{href 16 "\t\treturn null;"}} } },
-    content: [
-      "\t\tif (isEnoent(err)) return null;",
-      "\t\tthrow err;"
-    ]
-  }]
-}
-```
-</example>
-
-<example name="replace whole block including closing brace">
-Replace the entire body of `alpha`, including its closing `}`. `end` **MUST** be {{href 7 "}"}} because `content` includes `}`.
-
-```
-{
-  edits: [{
-    path: "a.ts",
-    loc: { range: { pos: {{href 6 "\tlog();"}}, end: {{href 7 "}"}} } },
-    content: [
-      "\tvalidate();",
-      "\tlog();",
-      "}"
-    ]
-  }]
-}
-```
-
-**Wrong**: `end: {{href 6 "\tlog();"}}` with the same content — line 7 (`}`) survives AND content emits `}`, producing two closing braces.
-</example>
-
-<example name="replace one line">
+`{edits:[{path:"a.ts",loc:{range:{pos:{{href 15 "\t\tconsole.error(err);"}},end:{{href 16 "\t\treturn null;"}}}},content:["\t\tif (isEnoent(err)) return null;","\t\tthrow err;"]}]}`
+# Replace whole block including closing brace
+Replace `alpha`'s entire body including the closing `}`. `end` **MUST** be {{href 7 "}"}} because `content` includes `}`.
+`{edits:[{path:"a.ts",loc:{range:{pos:{{href 6 "\tlog();"}},end:{{href 7 "}"}}}},content:["\tvalidate();","\tlog();","}"]}]}`
+**Wrong**: `end: {{href 6 "\tlog();"}}` — line 7 (`}`) survives AND content emits `}`, producing two closing braces.
+# Replace one line
 Single-line replace uses `pos == end`.
-
-```
-{
-  edits: [{
-    path: "a.ts",
-    loc: { range: { pos: {{href 2 "const timeout = 5000;"}}, end: {{href 2 "const timeout = 5000;"}} } },
-    content: ["const timeout = 30_000;"]
-  }]
-}
-```
-</example>
-
-<example name="delete a range">
-```
-{
-  edits: [{
-    path: "a.ts",
-    loc: { range: { pos: {{href 10 "\t// TODO: remove after migration"}}, end: {{href 11 "\tlegacy();"}} } },
-    content: null
-  }]
-}
-```
-</example>
-
-<example name="insert before sibling">
+`{edits:[{path:"a.ts",loc:{range:{pos:{{href 2 "const timeout = 5000;"}},end:{{href 2 "const timeout = 5000;"}}}},content:["const timeout = 30_000;"]}]}`
+# Delete a range
+`{edits:[{path:"a.ts",loc:{range:{pos:{{href 10 "\t// TODO: remove after migration"}},end:{{href 11 "\tlegacy();"}}}},content:null}]}`
+# Insert before a sibling
 When adding a sibling declaration, prefer `prepend` on the next declaration.
-
-```
-{
-  edits: [{
-    path: "a.ts",
-    loc: { prepend: {{href 9 "function beta() {"}} },
-    content: [
-      "function gamma() {",
-      "\tvalidate();",
-      "}",
-      ""
-    ]
-  }]
-}
-```
-</example>
+`{edits:[{path:"a.ts",loc:{prepend:{{href 9 "function beta() {"}}},content:["function gamma() {","\tvalidate();","}",""]}]}`
 </examples>
 
 <critical>
-- Make the minimum exact edit. Do not rewrite nearby code unless the range requires it.
-- Copy anchors exactly as `N#ID` from the latest `read` output.
+- Make the minimum exact edit.
+- Copy the full anchors exactly as shown by `read/grep` (for example `160sr`, not just `sr`).
 - `range` requires both `pos` and `end`.
 - **Closing-delimiter check**: when your replacement `content` ends with a closing delimiter (`}`, `*/`, `)`, `]`), compare it against the line immediately after `end` in the file. If they match, extend `end` to include that line — otherwise the original delimiter survives and `content` adds a second copy.
 - For a range, replace only the body or the whole range — don't split range boundaries.

package/src/prompts/tools/{gemini-image.md → image-gen.md}

@@ -1,4 +1,4 @@
-Generates or edits images using Gemini image models.
+Generates or edits images using the configured image provider.
 
 <instructions>
 - You **MUST** provide a single detailed `subject` prompt for image generation or editing.

package/src/prompts/tools/inspect-image.md

@@ -12,12 +12,12 @@ Inspects an image file with a vision-capable model and returns compact text anal
 </instruction>
 
 <examples>
-- OCR with strict formatting:
-  - `{"path":"screenshots/error.png","question":"Extract all visible text verbatim. Return as bullet list in reading order."}`
-- Screenshot debugging:
-  - `{"path":"screenshots/settings.png","question":"Identify the likely cause of the disabled Save button. Return: (1) observations, (2) likely cause, (3) confidence."}`
-- Scene/object question:
-  - `{"path":"photos/shelf.jpg","question":"List all clearly visible product labels and their shelf positions (top/middle/bottom). If unreadable, say unreadable."}`
+# OCR with strict formatting
+`{"path":"screenshots/error.png","question":"Extract all visible text verbatim. Return as bullet list in reading order."}`
+# Screenshot debugging
+`{"path":"screenshots/settings.png","question":"Identify the likely cause of the disabled Save button. Return: (1) observations, (2) likely cause, (3) confidence."}`
+# Scene/object question
+`{"path":"photos/shelf.jpg","question":"List all clearly visible product labels and their shelf positions (top/middle/bottom). If unreadable, say unreadable."}`
 </examples>
 
 <output>

package/src/prompts/tools/lsp.md

@@ -31,3 +31,9 @@ Interacts with Language Server Protocol servers for code intelligence.
 - Glob expansion samples up to 20 files per request; use `file: "*"` for broader coverage
 - When `symbol` is provided for position-based actions, missing symbols or out-of-bounds `occurrence` values return an explicit error instead of silently falling back
 </caution>
+
+<critical>
+- You **MUST** use `lsp` for symbol-aware operations (rename, find references, go to definition/implementation, code actions) whenever a language server is available — it is safer and more accurate than text-based alternatives.
+- You **MUST NOT** perform cross-file renames with `ast_edit`, `sed`, `rsed`, or manual edits when `lsp` `rename` can do it. Text-based renames miss shadowing, re-exports, and usages in other files.
+- Prefer `lsp` `code_actions` for imports, quick-fixes, and refactors the language server already knows how to apply.
+</critical>

package/src/prompts/tools/patch.md

@@ -50,25 +50,18 @@ Returns success/failure; on failure, error message indicates:
 - **NEVER** use edit to fix indentation, whitespace, or reformat code. Formatting is a single command run once at the end (`bun fmt`, `cargo fmt`, `prettier —write`, etc.)—not N individual edits. If you see inconsistent indentation after an edit, leave it; the formatter will fix all of it in one pass.
 </critical>
 
-<example name="create">
-edit {"edits":[{"path":"hello.txt","op":"create","diff":"Hello\n"}]}
-</example>
-
-<example name="update">
-edit {"edits":[{"path":"src/app.py","op":"update","diff":"@@ def greet():\n def greet():\n-print('Hi')\n+print('Hello')\n"}]}
-</example>
-
-<example name="rename">
-edit {"edits":[{"path":"src/app.py","op":"update","rename":"src/main.py","diff":"@@\n …\n"}]}
-</example>
-
-<example name="delete">
-edit {"edits":[{"path":"obsolete.txt","op":"delete"}]}
-</example>
-
-<example name="multi-file">
-edit {"edits":[{"path":"src/types.ts","op":"update","diff":"@@\n-old\n+new\n"},{"path":"src/index.ts","op":"update","diff":"@@\n-old\n+new\n"}]}
-</example>
+<examples>
+# Create
+`edit {"edits":[{"path":"hello.txt","op":"create","diff":"Hello\n"}]}`
+# Update
+`edit {"edits":[{"path":"src/app.py","op":"update","diff":"@@ def greet():\n def greet():\n-print('Hi')\n+print('Hello')\n"}]}`
+# Rename
+`edit {"edits":[{"path":"src/app.py","op":"update","rename":"src/main.py","diff":"@@\n …\n"}]}`
+# Delete
+`edit {"edits":[{"path":"obsolete.txt","op":"delete"}]}`
+# Multi-file
+`edit {"edits":[{"path":"src/types.ts","op":"update","diff":"@@\n-old\n+new\n"},{"path":"src/index.ts","op":"update","diff":"@@\n-old\n+new\n"}]}`
+</examples>
 
 <avoid>
 - Generic anchors: `import`, `export`, `describe`, `function`, `const`

package/src/prompts/tools/python.md

@@ -44,7 +44,8 @@ User sees output like Jupyter notebook; rich displays render fully:
 - You **MUST** use `run()` for shell commands; you **MUST NOT** use raw `subprocess`
 </critical>
 
-<example name="multiple small cells">
+<examples>
+# Multiple small cells
 ```python
 cells: [
     {"title": "imports", "code": "import json\nfrom pathlib import Path"},
@@ -53,4 +54,4 @@ cells: [
     {"title": "use helper", "code": "configs = [parse_config(p) for p in Path('.').glob('*.json')]"}
 ]
 ```
-</example>
+</examples>

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

@@ -1,23 +1,53 @@
-Reads files using syntax-aware chunks.
+Reads files using syntax-aware chunks. Also inspects directories, archives, SQLite databases, images, documents (PDF/DOCX/PPTX/XLSX/RTF/EPUB/ipynb), **and URLs**.
 
 <instruction>
-- `path` — file path or URL; may include `:selector` suffix
-- `sel` — optional selector: `class_Foo`, `class_Foo.fn_bar#ABCD~`, `?`, `L50`, `L50-L120`, or `raw`
+The chunk-aware `read` variant returns AST-scoped chunks with current checksum IDs for structural editing, and otherwise behaves like `open` for non-code content.
+- You **MUST** parallelize calls when exploring related files
+- For URLs, `read` fetches the page and returns clean extracted text/markdown by default (reader-mode). It handles HTML pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom, JSON endpoints, PDFs, etc. You **SHOULD** reach for `read` — not a browser/puppeteer tool — for fetching and inspecting web content.
+
+## Parameters
+- `path` — file path or URL; may include `:selector` suffix (required)
+- `sel` — optional selector for chunks, line ranges, listing, or raw mode
 - `timeout` — seconds, for URLs only
 
-Each anchor `@full.chunk.path#CCCC` (with `-` prefixes for nesting depth) in the output identifies a chunk. Use `full.chunk.path#CCCC` as-is to read truncated chunks.
-If you need a canonical target list, run `read(path="file", sel="?")`. That listing shows chunk paths with IDs.
-Line numbers in the gutter are absolute file line numbers.
+## Selectors
+
+|`sel` value|Behavior|
+|---|---|
+|*(omitted)*|Read full file as chunks (up to {{DEFAULT_LIMIT}} lines)|
+|`class_Foo`|Read a specific chunk|
+|`class_Foo.fn_bar#thth~`|Read a chunk region (body `~` / head `^`) by ID|
+|`?`|List all chunk paths with IDs|
+|`L50`|Read from line 50 onward (shorthand for L50 to EOF)|
+|`L50-L120`|Read lines 50 through 120|
+|`L20-L20`|Read exactly one line|
+|`raw`|Raw content without transformations (for URLs: untouched HTML)|
 
-`L20` (single line, no explicit end) is shorthand for `L20` to end-of-file. Use `L20-L20` for a one-line window.
+Max {{DEFAULT_MAX_LINES}} lines per call.
+
+# Chunks
+Each anchor `@full.chunk.path#thth` (with `-` prefixes for nesting depth) in the output identifies a chunk. Use `full.chunk.path#thth` as-is to read truncated chunks.
+If you need a canonical target list, run `read(path="file", sel="?")`. That listing shows chunk paths with IDs and is the safest structural discovery mode. Summary lines in this listing are orientation hints; follow a selector with `read(path="file", sel="chunk#ID")` or use `raw` when you need exact source.
+Line numbers in the gutter are absolute file line numbers.
 
 {{#if chunkAutoIndent}}
 Chunk reads normalize leading indentation so copied content round-trips cleanly into chunk edits.
 {{else}}
 Chunk reads preserve literal leading tabs/spaces from the file. When editing, keep the same whitespace characters you see here.
 {{/if}}
+`raw` shows the file's literal whitespace. Structured chunk views may normalize or display indentation for edit round-tripping, so use `raw` when exact tabs/spaces matter, especially inside markdown fenced code blocks.
+
+IDs change after every edit. Use the new IDs from the edit response or refresh with `sel="?"` before the next `write`/`delete`. `insert` selectors may omit IDs, but still prefer fresh paths after structural edits.
+
+Parser boundaries vary by language: TypeScript/JavaScript decorators and JSDoc above decorated methods may appear as sibling `chunk#ID` entries, Python decorators are part of the function/class head, Python docstrings are body lines, and Python enum members or nested closures may remain opaque inside their parent chunk. Decorated Python `^` writes and Python `^` deletes are rejected for safety.
+Markdown sections, lists, and tables are structural chunks. Recognized pipe tables expose `row_N` children for row-level edits; list items and table cells are not independently addressable. Fenced code blocks with a declared language are parsed again when possible, so functions inside a markdown fence can appear as addressable nested chunks.
 
 Chunk trees: JS, TS, TSX, Python, Rust, Go. Others use blank-line fallback.
+# Inspection
+Extracts text from PDF, Word, PowerPoint, Excel, RTF, EPUB, and Jupyter notebook files. Can inspect images.
+
+# Directories & Archives
+Directories and archive roots return a list of entries. Supports `.tar`, `.tar.gz`, `.tgz`, `.zip`. Use `archive.ext:path/inside/archive` to read contents.
 
 # SQLite Databases
 When used against a SQLite database (`.sqlite`, `.sqlite3`, `.db`, `.db3`), returns structured database content.
@@ -27,9 +57,17 @@ When used against a SQLite database (`.sqlite`, `.sqlite3`, `.db`, `.db3`), retu
 - `file.db:table?limit=50&offset=100` — paginated rows
 - `file.db:table?where=status='active'&order=created:desc` — filtered rows
 - `file.db?q=SELECT …` — read-only SELECT query
+
+# URLs
+Extracts content from web pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom feeds, JSON endpoints, PDFs at URLs, and similar text-based resources. Returns clean reader-mode text/markdown — no browser required. Use `sel="raw"` for untouched HTML; `timeout` to override the default request timeout. You **SHOULD** prefer `read` over a browser/puppeteer tool for fetching URL content; only use a browser when the page requires JS execution, authentication, or interactive actions (clicks, forms, scrolling).
 </instruction>
 
 <critical>
-- **MUST** `read` before editing — never invent chunk names or IDs.
+- You **MUST** `read` before editing — never invent chunk names or IDs.
     - Chunk names are truncated (e.g., `handleRequest` becomes `fn_handleRequ`). Always copy chunk paths from `read` or `?` output — never construct them from source identifiers.
+- You **MUST** use `read` (never bash `cat`/`head`/`tail`/`less`/`more`/`ls`/`tar`/`unzip`/`curl`/`wget`) for all file, directory, archive, and URL reads.
+- You **MUST NOT** reach for a browser/puppeteer tool to fetch static web content — `read` handles HTML, PDFs, JSON, feeds, and docs directly. Reserve browser tools for JS-heavy pages or interactive flows.
+- You **MUST** always include the `path` parameter; never call with `{}`.
+- For specific line ranges, use `sel`: `read(path="file", sel="L50-L150")` — not `cat -n file | sed`.
+- You **MAY** use `sel` with URL reads; the tool paginates cached fetched output.
 </critical>

package/src/prompts/tools/read.md

@@ -1,8 +1,9 @@
 Reads the content at the specified path or URL.
 
 <instruction>
-The `read` tool is multi-purpose — inspects files, directories, archives, SQLite databases, and URLs.
+The `read` tool is multi-purpose and more capable than it looks — inspects files, directories, archives, SQLite databases, images, documents (PDF/DOCX/PPTX/XLSX/RTF/EPUB/ipynb), **and URLs**.
 - You **MUST** parallelize reads when exploring related files
+- For URLs, `read` fetches the page and returns clean extracted text/markdown by default (reader-mode). It handles HTML pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom, JSON endpoints, PDFs, etc. You **SHOULD** reach for `read` — not a browser/puppeteer tool — for fetching and inspecting web content.
 
 ## Parameters
 - `path` — file path or URL (required)
@@ -14,15 +15,16 @@ The `read` tool is multi-purpose — inspects files, directories, archives, SQLi
 |`sel` value|Behavior|
 |---|---|
 |*(omitted)*|Read full file (up to {{DEFAULT_LIMIT}} lines)|
-|`L50`|Read from line 50 onward|
+|`L50`|Read from line 50 onward (shorthand for L50 to EOF)|
 |`L50-L120`|Read lines 50 through 120|
-|`raw`|Raw content without transformations (for URLs: untouched HTML)|
+|`L20-L20`|Read exactly one line|
+|`raw`|Skip line-numbering / hashline / chunking; return file content as plain text. For URLs: untouched HTML.|
 
 Max {{DEFAULT_MAX_LINES}} lines per call.
 
 # Filesystem
 {{#if IS_HASHLINE_MODE}}
-- Reading from FS returns lines prefixed with anchors: `41#ZZ:def alpha():`
+- Reading from FS returns lines prefixed with anchors: `41th:def alpha():` (line number, 2-letter ID, colon, then content)
 {{else}}
 {{#if IS_LINE_NUMBER_MODE}}
 - Reading from FS returns lines prefixed with line numbers: `41:def alpha():`
@@ -45,11 +47,12 @@ For `.sqlite`, `.sqlite3`, `.db`, `.db3`:
 - `file.db?q=SELECT …` — read-only SELECT query
 
 # URLs
-Extracts content from web pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom feeds, JSON endpoints, and similar text-based resources. Use `sel="raw"` for untouched HTML; `timeout` to override the default request timeout.
+Extracts content from web pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom feeds, JSON endpoints, PDFs at URLs, and similar text-based resources. Returns clean reader-mode text/markdown — no browser required. Use `sel="raw"` for untouched HTML; `timeout` to override the default request timeout. You **SHOULD** prefer `read` over a browser/puppeteer tool for fetching URL content; only use a browser when the page requires JS execution, authentication, or interactive actions (clicks, forms, scrolling).
 </instruction>
 
 <critical>
-- You **MUST** use `read` (never bash `cat`/`head`/`tail`/`less`/`more`/`ls`/`tar`/`unzip`) for all file, directory, and archive reads.
+- You **MUST** use `read` (never bash `cat`/`head`/`tail`/`less`/`more`/`ls`/`tar`/`unzip`/`curl`/`wget`) for all file, directory, archive, and URL reads.
+- You **MUST NOT** reach for a browser/puppeteer tool to fetch static web content — `read` handles HTML, PDFs, JSON, feeds, and docs directly. Reserve browser tools for JS-heavy pages or interactive flows.
 - You **MUST** always include the `path` parameter; never call with `{}`.
 - For specific line ranges, use `sel`: `read(path="file", sel="L50-L150")` — not `cat -n file | sed`.
 - You **MAY** use `sel` with URL reads; the tool paginates cached fetched output.

package/src/prompts/tools/ssh.md

@@ -25,20 +25,11 @@ You **MUST** build commands from the reference below
 You **MUST** verify the shell type from "Available hosts" and use matching commands.
 </critical>
 
-<example name="linux">
-Task: List /home/user files on "server1"
-Host: server1 (10.0.0.1) | linux/bash
-Command: `ls -la /home/user`
-</example>
-
-<example name="windows-cmd">
-Task: Show running processes on "winbox"
-Host: winbox (192.168.1.5) | windows/cmd
-Command: `tasklist /v`
-</example>
-
-<example name="macos">
-Task: Get system info on "macbook"
-Host: macbook (10.0.0.20) | macos/zsh
-Command: `uname -a && sw_vers`
-</example>
+<examples>
+# List files: Linux
+Host: server1 (10.0.0.1) | linux/bash. Command: `ls -la /home/user`
+# Show running processes: Windows cmd
+Host: winbox (192.168.1.5) | windows/cmd. Command: `tasklist /v`
+# Get system info: macOS
+Host: macbook (10.0.0.20) | macos/zsh. Command: `uname -a && sw_vers`
+</examples>

package/src/prompts/tools/todo-write.md

@@ -1,28 +1,53 @@
-Manages a phased task list. Each field is a verb — set the ones you need in a single call.
+Manages a phased task list through an `ops` array of flat operations.
 The next pending task is auto-promoted to `in_progress` after completing the current one.
 
 <protocol>
-## Fields
+## Shape
+
+Pass an object with an `ops` array:
+
+```ts
+{
+  ops: [
+    { op: "replace", phases: [...] },
+    { op: "start", task: "task-3" },
+    { op: "done", phase: "Implementation" },
+    { op: "rm" },
+    { op: "drop", task: "task-9" },
+    { op: "append", phase: "Implementation", items: [{ id: "task-10", label: "Run tests" }] },
+  ],
+}
+```
+
+## Operation fields
 
 |Field|Type|When to use|
 |---|---|---|
-|`phases`|Phase[]|Initial setup, or full restructure when the plan changes significantly|
-|`complete`|string[]|Mark tasks done|
-|`start`|string|Jump to a specific task out of order|
-|`abandon`|string[]|Drop tasks intentionally|
-|`remove`|string[]|Remove tasks that are no longer relevant|
-|`add_notes`|{id, notes}[]|Append runtime observations to tasks|
-|`add_tasks`|{phase, content, details?}[]|Add tasks to a phase (by name or ID)|
-|`add_phase`|{name, tasks?}|Add a new phase of work discovered mid-task|
+|`op`|string|Required. One of `replace`, `start`, `done`, `rm`, `drop`, `append`|
+|`task`|string|Task id for `start`, or a task target for `done` / `rm` / `drop`|
+|`phase`|string|Phase target for `done` / `rm` / `drop`, or append destination for `append`|
+|`items`|{id, label}[]|Required for `append`. If the phase does not exist, it is created at the end|
+|`phases`|Phase[]|Only for `replace`. Keeps initial phased setup available for harness bootstrap and full restructures|
+
+## Semantics
+- `start`: requires `task`; sets that task to `in_progress`
+- `done`: marks one task, one phase, or all tasks completed
+- `rm`: removes one task, one phase's tasks, or all tasks
+- `drop`: marks one task, one phase, or all tasks abandoned
+- `append`: appends `items` to `phase`; creates the phase if missing
+- `replace`: replaces the full todo list
+
+If `done`, `rm`, or `drop` omits both `task` and `phase`, it applies to all tasks.
 
 ## Task Anatomy
-- `content`: Short label (5-10 words). What is being done, not how.
-- `details`: File paths, implementation steps, edge cases. Shown only when the task is active.
+- `label`: Short label (5-10 words). What is being done, not how.
+- `replace` task `content` should stay short and specific.
 
 ## Rules
-- Mark tasks completed immediately after finishing — never defer
-- Complete phases in order — do not skip ahead while earlier ones are pending
-- On blockers: add a new task describing the blocker
+- Mark tasks done immediately after finishing — never defer.
+- Complete phases in order — do not skip ahead while earlier ones are pending.
+- On blockers, append a new task to the active phase.
+- Keep ids stable once introduced.
 </protocol>
 
 <conditions>
@@ -33,32 +58,20 @@ Create a todo list when:
 4. New instructions arrive mid-task — capture before proceeding
 </conditions>
 
-<example name="initial-setup">
-{phases: [
-  {name: "Investigation", tasks: [{content: "Read source"}, {content: "Map callsites"}]},
-  {name: "Implementation", tasks: [{content: "Apply fix", details: "Update parser.ts to handle edge case in line 42"}, {content: "Run tests"}]}
-]}
-</example>
-
-<example name="complete">
-{complete: ["task-2", "task-3"]}
-</example>
-
-<example name="add-notes">
-{add_notes: [{id: "task-3", notes: "Found edge case in parser — needs null check"}]}
-</example>
-
-<example name="add-task">
-{add_tasks: [{phase: "Implementation", content: "Handle retries", details: "Cap exponential backoff in retry.ts"}]}
-</example>
-
-<example name="add-phase">
-{add_phase: {name: "Cleanup", tasks: [{content: "Remove dead code"}]}}
-</example>
-
-<example name="combined">
-{complete: ["task-2"], add_notes: [{id: "task-3", notes: "Needs extra validation"}]}
-</example>
+<examples>
+# Initial setup
+`{"ops":[{"op":"replace","phases":[{"name":"Investigation","tasks":[{"content":"Read source"},{"content":"Map callsites"}]},{"name":"Implementation","tasks":[{"content":"Apply fix"},{"content":"Run tests"}]}]}]}`
+# Complete one task
+`{"ops":[{"op":"done","task":"task-2"}]}`
+# Complete a whole phase
+`{"ops":[{"op":"done","phase":"Implementation"}]}`
+# Remove all tasks
+`{"ops":[{"op":"rm"}]}`
+# Drop one task
+`{"ops":[{"op":"drop","task":"task-7"}]}`
+# Append tasks to a phase
+`{"ops":[{"op":"append","phase":"Implementation","items":[{"id":"task-8","label":"Handle retries"},{"id":"task-9","label":"Run tests"}]}]}`
+</examples>
 
 <avoid>
 - Single-step tasks — act directly