pi-readseek 0.8.18 → 0.8.20

package/README.md

@@ -1,37 +1,43 @@
 # pi-readseek
 
-`pi-readseek` adds ReadSeek's anchored file tools, structural search, and symbol
-navigation to Pi. Built-in tools remain unchanged unless `replacedTools` maps
-`read`, `edit`, `write`, or `grep` to the ReadSeek implementation.
+`pi-readseek` adds ReadSeek's anchored file operations, structural search,
+symbol navigation, and PDF tools to Pi. Built-ins remain available unless
+`replacedTools` maps `read`, `edit`, `write`, or `grep` to a ReadSeek-backed
+implementation.
 
-## Installation
+## Install
 
 ```sh
 pi install npm:pi-readseek
 ```
 
-The extension depends on `@jarkkojs/readseek`, which installs the native binary on
+The package depends on `@jarkkojs/readseek`, which supplies the native binary on
 supported platforms.
 
 ## Tools
 
-- `readSeek_read`: reads anchored text by range, symbol, or structural map; it can
-  also read or analyze images and PDFs.
-- `readSeek_edit`: applies hash-verified edits to existing text files.
-- `readSeek_write`: creates or replaces complete files and returns anchors.
-- `readSeek_grep`: searches text and returns edit-ready anchors.
-- `readSeek_search`: searches code with structural AST patterns.
-- `readSeek_def`, `readSeek_refs`, `readSeek_hover`: navigate symbols.
-- `readSeek_rename`: applies binding-aware renames by default. Set `apply: false`
-  for a dry run; workspace matches are name-based where binding support is unavailable.
-- `readSeek_check`: reports parser errors and missing syntax.
-- `readSeek_view`: indexes a PDF or narrows an existing index by page, node, kind,
-  or depth.
+| Tool | Purpose |
+| --- | --- |
+| `readSeek_read` | Read anchored text by range, symbol, or map; read images and PDFs |
+| `readSeek_edit` | Apply hash-verified edits to an existing text file |
+| `readSeek_write` | Create or replace a complete text file and return anchors |
+| `readSeek_grep` | Search text or regex and return edit-ready anchors |
+| `readSeek_search` | Search AST patterns |
+| `readSeek_def` | Find symbol definitions |
+| `readSeek_refs` | Find identifier usages, optionally scoped to a cursor binding |
+| `readSeek_hover` | Identify the token and enclosing symbol at a cursor |
+| `readSeek_rename` | Rename a cursor symbol; set `apply: false` to preview the plan |
+| `readSeek_check` | Report parser errors and missing syntax |
+| `readSeek_view` | View or narrow a structural PDF index |
+
+The extension also tells Pi to get fresh anchors before editing and to run a
+syntax check after source edits.
 
 ## Settings
 
-Add an optional `readseek` section to `~/.pi/agent/settings.json` (global) or
-`.pi/settings.json` (project). Project settings take precedence. Defaults:
+Add a `readseek` object to `~/.pi/agent/settings.json` (global) or
+`.pi/settings.json` (project). Project settings override matching global values.
+Defaults:
 
 ```json
 {
@@ -54,24 +60,32 @@ Add an optional `readseek` section to `~/.pi/agent/settings.json` (global) or
 }
 ```
 
-- `replacedTools`: built-in tools backed by ReadSeek. Valid values are `"read"`,
-  `"edit"`, `"write"`, and `"grep"`.
-- `imageMode`: controls standalone images and images embedded in PDFs. `"auto"`
-  exposes `none`, `all`, `ocr`, `caption`, and `objects`. When the active model
-  accepts images, `"auto"` silently passes prepared images to the model instead
-  of running local analysis. `"on"` always runs the selected local analysis and
-  omits `none`; `"off"` skips standalone and embedded images. PDF text is always
-  read regardless of `imageMode`. Omitting `image` skips standalone images and,
-  unless native vision is available in `"auto"` mode, PDF embedded images.
-- `syntaxValidation`: syntax-regression handling for `readSeek_edit`. `"warn"`
-  writes with a warning, `"block"` aborts, and `"off"` disables the check.
-- `timeoutMs`: ReadSeek command timeout in milliseconds.
-- `grep.maxLines` and `grep.maxBytes`: output limits for `readSeek_grep`. Values
-  above the defaults are clamped.
-- `display`: default display state (`"compact"` or `"expanded"`) per tool for `read`, `grep`, `edit`, and `write`.
+- `replacedTools`: any of `"read"`, `"edit"`, `"write"`, and `"grep"`.
+- `imageMode`: `"auto"` uses Pi's native image input when available, `"on"`
+  always runs local analysis, and `"off"` skips images while still reading PDF
+  text. Standalone images require `image`; values are `all`, `ocr`, `caption`, and
+  `objects`. In `"auto"`, `none` returns a prepared standalone image without local
+  analysis. Local analysis uses
+  [Qwen3-VL-2B-Instruct](../../docs/models/qwen3-vl-2b-instruct.md).
+- `syntaxValidation`: `"warn"` (write and warn), `"block"` (abort), or `"off"`.
+  Validation triggers only when an edit increases parser error or missing-node
+  counts.
+- `timeoutMs`: native command timeout in milliseconds.
+- `grep.maxLines` and `grep.maxBytes`: output limits; larger values are clamped
+  to the defaults.
+- `display`: initial `"compact"` or `"expanded"` state for `read`, `grep`,
+  `edit`, and `write` results.
+
+## Development
+
+```sh
+npm install
+npm test
+npm run typecheck
+```
 
-## Licensing
+## License
 
-`pi-readseek` is licensed under `Apache-2.0`; see [LICENSE](LICENSE).
+`pi-readseek` is Apache-2.0; see [LICENSE](LICENSE).
 `@jarkkojs/readseek` is licensed separately under
-`Apache-2.0 AND LGPL-2.1-or-later`.
+Apache-2.0 AND LGPL-2.1-or-later.

package/dist/index.ts

@@ -15,7 +15,7 @@ var REPLACEABLE_TOOL_GUIDELINES = {
   "read.md": {
     readSeekName: "readSeek_read",
     builtInName: "read",
-    benefit: "it provides LINE:HASH anchors for safe edits."
+    benefit: "it returns LINE:HASH anchors for safe edits."
   },
   "edit.md": {
     readSeekName: "readSeek_edit",
@@ -25,7 +25,7 @@ var REPLACEABLE_TOOL_GUIDELINES = {
   "grep.md": {
     readSeekName: "readSeek_grep",
     builtInName: "grep",
-    benefit: "it returns edit-ready anchors."
+    benefit: "it returns LINE:HASH anchors."
   },
   "write.md": {
     readSeekName: "readSeek_write",
@@ -35,23 +35,22 @@ var REPLACEABLE_TOOL_GUIDELINES = {
 };
 var COMPACT_GUIDELINES = {
   "read.md": [
-    "Use readSeek_read map or symbol mode to inspect large code files without reading them in full."
+    "Use readSeek_read with map or symbol to inspect large files without reading them in full."
   ],
   "edit.md": [
-    "With readSeek_edit, prefer set_line, replace_lines, and insert_after; use replace only when anchors are impractical."
+    "Prefer set_line, replace_lines, and insert_after; use replace only when anchors are impractical."
   ],
   "grep.md": [
-    "Use readSeek_grep summary mode for broad count/file discovery before narrowing."
+    "Use readSeek_grep with summary first for broad searches, then narrow by path, glob, or pattern."
   ],
   "write.md": [
-    "Use anchored edits rather than readSeek_write for small changes or appends to existing files."
+    "Use anchored edits rather than readSeek_write for small changes or appends."
   ],
   "search.md": [
-    "Use readSeek_search for syntax-aware code shapes; use readSeek_grep for plain text."
+    "Use readSeek_search for AST patterns; use readSeek_grep for plain text."
   ],
   "refs.md": [
-    "Use readSeek_refs to find every usage of an identifier before renaming or deleting it.",
-    "Use readSeek_refs with scope plus line/column to follow a specific binding instead of every same-named identifier."
+    "Use readSeek_refs before changing a symbol; add scope plus line/column to follow one binding."
   ]
 };
 function loadPrompt(promptUrl) {
@@ -3661,21 +3660,21 @@ function registerReadTool(pi, options = {}) {
   const imageModes = imageMode === "auto" ? ["none", "all", "ocr", "caption", "objects"] : ["all", "ocr", "caption", "objects"];
   const promptMetadata = defineToolPromptMetadata({
     promptUrl: new URL("../prompts/read.md", import.meta.url),
-    promptSnippet: "Read anchored text, symbols, maps, images, or PDFs",
+    promptSnippet: imageMode === "off" ? "Read anchored text, symbols, maps, or PDF text" : "Read anchored text, symbols, maps, images, or PDFs",
     registeredName: name
   });
   const tool = registerReadSeekTool(pi, {
     name,
     label: "Read",
-    description: imageMode === "off" ? 'Read anchored text by range, map, or symbol; standalone images are skipped because imageMode is "off", while PDFs are read as text.' : promptMetadata.description,
+    description: imageMode === "off" ? "Read anchored text by range, symbol, or map. Images are disabled; PDFs still return text." : promptMetadata.description,
     promptSnippet: promptMetadata.promptSnippet,
     promptGuidelines: [
       ...promptMetadata.promptGuidelines,
-      imageMode === "off" ? "The image parameter is unavailable; standalone images and PDF embedded images are skipped, while PDFs are read as text." : `For an image, explicitly choose image: ${imageModes.join(", ")}; omitting image skips standalone images. PDFs are always read as text, and image controls embedded images.${imageMode === "auto" ? " Native image-capable models bypass local analysis and receive standalone and PDF embedded images directly." : ""}`
+      ...imageMode === "auto" ? ["Image-capable Pi models receive prepared images directly. For standalone images, image=none skips local analysis; other modes use ReadSeek when native vision is unavailable."] : []
     ],
     parameters: Type2.Object({
       path: filePathParam(),
-      offset: optionalIntOrString("Start line (1-indexed)"),
+      offset: optionalIntOrString("One-based starting line"),
       limit: optionalIntOrString("Maximum lines to return"),
       page: optionalIntOrString("One-based PDF page; defaults to 1"),
       symbol: Type2.Optional(Type2.String({ description: "Symbol name to read" })),
@@ -3685,7 +3684,7 @@ function registerReadTool(pi, options = {}) {
       })),
       ...imageMode === "off" ? {} : {
         image: Type2.Optional(Type2.Union(imageModes.map((mode) => Type2.Literal(mode)), {
-          description: `Standalone image/PDF embedded-image mode: ${imageModes.join(", ")}. Must be selected explicitly for standalone images.`
+          description: `Standalone/PDF-embedded image mode: ${imageModes.join(", ")}. Required for standalone images.${imageMode === "auto" ? " For standalone images, none skips local analysis." : ""}`
         }))
       }
     }),
@@ -4793,20 +4792,43 @@ function pendingPreviewLines(summary, preview, expanded) {
   const headerLine = summaryLine(preview.data.headerLabel, { hidden: !expanded });
   return { lines: [summary, headerLine], diffData: expanded ? diffData : undefined, headerLabel: preview.data.headerLabel };
 }
-var hashlineEditItemSchema = Type3.Union([
-  Type3.Object({ set_line: Type3.Object({ anchor: Type3.String(), new_text: Type3.String() }) }, { additionalProperties: false }),
-  Type3.Object({ replace_lines: Type3.Object({ start_anchor: Type3.String(), end_anchor: Type3.String(), new_text: Type3.String() }) }, { additionalProperties: false }),
-  Type3.Object({ insert_after: Type3.Object({ anchor: Type3.String(), new_text: Type3.String() }) }, { additionalProperties: false }),
-  Type3.Object({ replace: Type3.Object({ old_text: Type3.String(), new_text: Type3.String(), all: Type3.Optional(Type3.Boolean()), fuzzy: Type3.Optional(Type3.Boolean()) }) }, { additionalProperties: false }),
-  Type3.Object({ replace_symbol: Type3.Object({ symbol: Type3.String(), new_body: Type3.String() }) }, { additionalProperties: false })
-]);
+var hashlineEditItemSchema = Type3.Object({
+  set_line: Type3.Optional(Type3.Object({
+    anchor: Type3.String({ description: "Fresh LINE:HASH anchor for the line to replace" }),
+    new_text: Type3.String({ description: "Replacement text; use an empty string to delete the line" })
+  }, { description: 'Replace one line: {"set_line":{"anchor":"LINE:HASH","new_text":"..."}}' })),
+  replace_lines: Type3.Optional(Type3.Object({
+    start_anchor: Type3.String({ description: "Fresh LINE:HASH anchor for the first line in the range" }),
+    end_anchor: Type3.String({ description: "Fresh LINE:HASH anchor for the last line in the range" }),
+    new_text: Type3.String({ description: "Replacement text; use an empty string to delete the range" })
+  }, { description: 'Replace a range: {"replace_lines":{"start_anchor":"LINE:HASH","end_anchor":"LINE:HASH","new_text":"..."}}' })),
+  insert_after: Type3.Optional(Type3.Object({
+    anchor: Type3.String({ description: "Fresh LINE:HASH anchor for the line after which to insert" }),
+    new_text: Type3.String({ description: "Text to insert after the anchored line" })
+  }, { description: 'Insert text: {"insert_after":{"anchor":"LINE:HASH","new_text":"..."}}' })),
+  replace: Type3.Optional(Type3.Object({
+    old_text: Type3.String({ description: "Exact text to find" }),
+    new_text: Type3.String({ description: "Replacement text" }),
+    all: Type3.Optional(Type3.Boolean({ description: "Replace every exact match" })),
+    fuzzy: Type3.Optional(Type3.Boolean({ description: "Allow unverified fuzzy matching when exact text is absent" }))
+  }, { description: 'Replace text: {"replace":{"old_text":"...","new_text":"..."}}' })),
+  replace_symbol: Type3.Optional(Type3.Object({
+    symbol: Type3.String({ description: "Mapped symbol name" }),
+    new_body: Type3.String({ description: "Complete replacement body for the symbol" })
+  }, { description: 'Replace a symbol: {"replace_symbol":{"symbol":"name","new_body":"..."}}' }))
+}, {
+  additionalProperties: false,
+  minProperties: 1,
+  maxProperties: 1,
+  description: "Exactly one nested edit variant"
+});
 var hashlineEditSchema = Type3.Object({
   path: filePathParam(),
   edits: Type3.Optional(Type3.Array(hashlineEditItemSchema, {
-    description: "Edits: set_line, replace_lines, insert_after, replace_symbol, or replace"
+    description: "Use set_line, replace_lines, insert_after, replace_symbol, or replace"
   })),
   postEditVerify: Type3.Optional(Type3.Boolean({
-    description: "Verify persisted content after write"
+    description: "Read back and verify persisted content"
   }))
 }, { additionalProperties: true });
 function buildEditError(path2, code, message, hint, errorDetails) {
@@ -4860,7 +4882,12 @@ async function executeEdit(opts) {
       }
       for (let i = 0;i < edits.length; i++) {
         throwIfAborted(signal);
-        const e = edits[i];
+        const edit = edits[i];
+        if (!edit || typeof edit !== "object" || Array.isArray(edit)) {
+          const message = `edits[${i}] must be an object containing exactly one edit variant.`;
+          return buildEditError(absolutePath, "invalid-edit-variant", message);
+        }
+        const e = edit;
         if ((("old_text" in e) || ("new_text" in e)) && !("replace" in e)) {
           const message = `edits[${i}] has top-level 'old_text'/'new_text'. Use {replace: {old_text, new_text}} or {set_line}, {replace_lines}, {insert_after}.`;
           return buildEditError(absolutePath, "invalid-edit-variant", message);
@@ -4870,7 +4897,7 @@ async function executeEdit(opts) {
           return buildEditError(absolutePath, "invalid-edit-variant", message);
         }
         const variantCount = Number("set_line" in e) + Number("replace_lines" in e) + Number("insert_after" in e) + Number("replace" in e) + Number("replace_symbol" in e);
-        if (variantCount !== 1) {
+        if (variantCount !== 1 || Object.keys(e).length !== 1) {
           const message = `edits[${i}] must contain exactly one of: 'set_line', 'replace_lines', 'insert_after', 'replace', 'replace_symbol'. Got: [${Object.keys(e).join(", ")}].`;
           return buildEditError(absolutePath, "invalid-edit-variant", message);
         }
@@ -5202,7 +5229,7 @@ function registerEditTool(pi, options = {}) {
   const name = options.name ?? "readSeek_edit";
   const promptMetadata = defineToolPromptMetadata({
     promptUrl: new URL("../prompts/edit.md", import.meta.url),
-    promptSnippet: "Safely edit with fresh LINE:HASH anchors",
+    promptSnippet: "Edit existing files with fresh LINE:HASH anchors",
     registeredName: name,
     toolAliases: options.toolAliases
   });
@@ -5669,7 +5696,7 @@ function validateIgnoredRequiresOthers(tool, params) {
 
 // src/grep.ts
 var grepSchema = Type5.Object({
-  pattern: Type5.String({ description: "Regex pattern; use literal for exact text" }),
+  pattern: Type5.String({ description: "Regex pattern; set literal for exact text" }),
   path: searchPathParam(),
   glob: Type5.Optional(Type5.String({ description: "File-name glob, such as *.ts" })),
   ignoreCase: Type5.Optional(Type5.Boolean({ description: "Ignore case" })),
@@ -6040,7 +6067,7 @@ function registerGrepTool(pi, options = {}) {
   const name = options.name ?? "readSeek_grep";
   const promptMetadata = defineToolPromptMetadata({
     promptUrl: new URL("../prompts/grep.md", import.meta.url),
-    promptSnippet: "Search plain text or regex with edit-ready anchors",
+    promptSnippet: "Search text or regex with edit-ready LINE:HASH anchors",
     registeredName: name
   });
   const tool = registerReadSeekTool(pi, {
@@ -6186,7 +6213,7 @@ function mergeRanges(ranges) {
 }
 var SEARCH_PROMPT_METADATA = defineToolPromptMetadata({
   promptUrl: new URL("../prompts/search.md", import.meta.url),
-  promptSnippet: "Search syntax-aware code shapes with AST patterns"
+  promptSnippet: "Search source code with AST patterns"
 });
 function linesFromSearchResult(result, ranges) {
   const lineMap = new Map;
@@ -6295,7 +6322,7 @@ function registerSearchTool(pi, options = {}) {
     promptSnippet: SEARCH_PROMPT_METADATA.promptSnippet,
     promptGuidelines: SEARCH_PROMPT_METADATA.promptGuidelines,
     parameters: Type6.Object({
-      pattern: Type6.String({ description: "ast-grep pattern, such as console.log($$$ARGS)" }),
+      pattern: Type6.String({ description: "AST pattern (ast-grep style), such as console.log($$$ARGS)" }),
       lang: langParam(),
       path: searchPathParam(),
       ...readSeekGitSearchParams()
@@ -6349,7 +6376,7 @@ function buildRefsOutput(input) {
 // src/refs.ts
 var REFS_PROMPT_METADATA = defineToolPromptMetadata({
   promptUrl: new URL("../prompts/refs.md", import.meta.url),
-  promptSnippet: "Find usages of an identifier or cursor binding"
+  promptSnippet: "Find identifier usages or a cursor binding"
 });
 function refsLine(reference) {
   return {
@@ -6431,8 +6458,8 @@ function registerRefsTool(pi, options = {}) {
       path: searchPathParam(),
       lang: langParam(),
       scope: Type7.Optional(Type7.Boolean({ description: "Restrict results to the binding at the cursor" })),
-      line: Type7.Optional(Type7.Number({ description: "Cursor line (1-indexed), required with scope" })),
-      column: Type7.Optional(Type7.Number({ description: "Cursor byte column (1-indexed) for disambiguation" })),
+      line: Type7.Optional(Type7.Number({ description: "One-based cursor line; required with scope" })),
+      column: Type7.Optional(Type7.Number({ description: "One-based cursor byte column for disambiguation" })),
       ...readSeekGitSearchParams()
     }),
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
@@ -6463,15 +6490,15 @@ import path5 from "node:path";
 import { Text as Text6 } from "@earendil-works/pi-tui";
 var RENAME_PROMPT_METADATA = defineToolPromptMetadata({
   promptUrl: new URL("../prompts/rename.md", import.meta.url),
-  promptSnippet: "Rename the symbol at a cursor without touching shadows"
+  promptSnippet: "Rename a cursor symbol with verified edits"
 });
 var renameSchema = Type8.Object({
   path: filePathParam(),
-  line: Type8.Integer({ minimum: 1, description: "One-based line of the symbol to rename" }),
-  column: Type8.Optional(Type8.Integer({ minimum: 1, description: "One-based byte column for disambiguation" })),
+  line: Type8.Integer({ minimum: 1, description: "One-based cursor line of the symbol to rename" }),
+  column: Type8.Optional(Type8.Integer({ minimum: 1, description: "One-based cursor byte column for disambiguation" })),
   to: Type8.String({ description: "New symbol name" }),
   workspace: Type8.Optional(Type8.Boolean({ description: "Rename across the project" })),
-  apply: Type8.Optional(Type8.Boolean({ description: "Apply the verified edits; default true" }))
+  apply: Type8.Optional(Type8.Boolean({ description: "Apply the verified edits; defaults to true" }))
 });
 async function executeRename(opts) {
   const { params, signal, cwd, onFileMutated } = opts;
@@ -6886,7 +6913,7 @@ function registerWriteTool(pi, options = {}) {
   const name = options.name ?? "readSeek_write";
   const promptMetadata = defineToolPromptMetadata({
     promptUrl: new URL("../prompts/write.md", import.meta.url),
-    promptSnippet: "Create or replace a complete file with edit anchors",
+    promptSnippet: "Create or replace a complete file with LINE:HASH anchors",
     registeredName: name
   });
   const tool = registerReadSeekTool(pi, {
@@ -6897,7 +6924,7 @@ function registerWriteTool(pi, options = {}) {
     promptGuidelines: promptMetadata.promptGuidelines,
     parameters: Type10.Object({
       path: filePathParam(),
-      content: Type10.String({ description: "Complete file content" }),
+      content: Type10.String({ description: "Complete text file content" }),
       map: mapParam()
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -7002,7 +7029,7 @@ import { Type as Type11 } from "@sinclair/typebox";
 import path6 from "node:path";
 var DEF_PROMPT_METADATA = defineToolPromptMetadata({
   promptUrl: new URL("../prompts/def.md", import.meta.url),
-  promptSnippet: "Find where a symbol is defined"
+  promptSnippet: "Find symbol declarations by name"
 });
 async function executeDef(opts) {
   const { params, signal, cwd, onFileAnchored } = opts;
@@ -7107,7 +7134,7 @@ import { Text as Text9 } from "@earendil-works/pi-tui";
 import { Type as Type12 } from "@sinclair/typebox";
 var CHECK_PROMPT_METADATA = defineToolPromptMetadata({
   promptUrl: new URL("../prompts/check.md", import.meta.url),
-  promptSnippet: "Check a source file for parser errors and missing syntax"
+  promptSnippet: "Run a quick syntax check on a source file"
 });
 async function executeCheck(opts) {
   const { params, signal, cwd } = opts;
@@ -7200,7 +7227,7 @@ var NODE_KINDS = [
 ];
 var VIEW_PROMPT_METADATA = defineToolPromptMetadata({
   promptUrl: new URL("../prompts/view.md", import.meta.url),
-  promptSnippet: "View the structure or selected content of an indexed PDF"
+  promptSnippet: "View PDF structure or selected content"
 });
 async function executeView(opts) {
   const { params, signal, cwd } = opts;
@@ -7262,11 +7289,11 @@ function registerViewTool(pi) {
     parameters: Type13.Object({
       path: filePathParam(),
       node: Type13.Optional(Type13.String({ description: "Node ID to use as the view root" })),
-      page: optionalIntOrString("One-based source page"),
+      page: optionalIntOrString("One-based PDF page"),
       kind: Type13.Optional(Type13.Union(NODE_KINDS.map((kind) => Type13.Literal(kind)), {
         description: "Node kind filter"
       })),
-      depth: optionalIntOrString("Maximum depth below the selected roots"),
+      depth: optionalIntOrString("Maximum depth below selected roots"),
       outline: Type13.Optional(Type13.Boolean({ description: "Return outline nodes only" }))
     }),
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
@@ -7341,10 +7368,9 @@ function formatSettingsWarning(warning) {
 function editingPolicy(readName, editName, writeName) {
   return [
     "ReadSeek editing policy:",
-    `- Prefer ${readName} when preparing to edit existing text; its LINE:HASH anchors are required by ${editName}.`,
-    `- Prefer ${editName} for existing text files, ${writeName} for whole-file creation or replacement, and readSeek_rename for symbol renames.`,
-    "- Do not use Pi's built-in edit or write when the corresponding ReadSeek tool is available.",
-    "- Use readSeek_check after source edits for a quick syntax check."
+    `- Read first with ${readName} when preparing to edit; ${editName} needs fresh LINE:HASH anchors.`,
+    `- Use ${editName} for existing files, ${writeName} for whole-file creation or replacement, and readSeek_rename for symbol renames.`,
+    "- Run readSeek_check after source edits for a quick syntax check."
   ].join(`
 `);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-readseek",
-  "version": "0.8.18",
-  "description": "Pi extension for readseek-backed hash-anchored read/edit/grep, structural code maps, structural search, and file exploration",
+  "version": "0.8.20",
+  "description": "Pi extension for LINE:HASH-anchored file operations and structural code navigation",
   "type": "module",
   "exports": {
     ".": "./dist/index.ts"
@@ -40,7 +40,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@jarkkojs/readseek": "^0.8.18",
+    "@jarkkojs/readseek": "^0.8.20",
     "diff": "^9.0.0",
     "xxhash-wasm": "^1.1.0"
   },

package/prompts/check.md

@@ -1,8 +1,8 @@
-Check a source file for parser errors and missing syntax. Use after edits for quick syntax validation, not as a compiler or linter.
+Run a quick syntax check on a source file. Use after edits to find parser errors and missing syntax; this is not a compiler or linter.
 
 ## Parameters
 
-- `path` — source file to check.
+- `path` — source file.
 
 ## Output
 

package/prompts/def.md

@@ -1,10 +1,11 @@
-Find symbol declarations by qualified or unqualified name. Use instead of text search when locating where a function, class, type, or other symbol is defined.
+Find symbol declarations by qualified or unqualified name. Use this instead of text search when locating a function, class, type, or other definition.
 
 ## Parameters
 
-- `path` — file or directory, default `.`.
 - `name` — qualified or unqualified symbol name.
-- `lang` — language override.
-- `cached`, `others`, `ignored` — Git file selection; `ignored` requires `others`.
+- `path` — file or directory; defaults to the current directory.
+- `lang` — language override when detection is ambiguous.
+- `cached`, `others`, `ignored` — Git file selection; `ignored` requires
+  `others`.
 
-After `readSeek_hover`, use its qualified symbol name.
+After `readSeek_hover`, prefer its qualified symbol name.

package/prompts/edit.md

@@ -1,71 +1,68 @@
-Edit existing text files safely with fresh `LINE:HASH` anchors; on `file-not-read`, read or search the file first.
+Edit existing text files with fresh `LINE:HASH` anchors. Read or search the file first when no fresh anchors are available. Each `edits[]` item must use exactly one nested object: `{"set_line":{"anchor":"LINE:HASH","new_text":"..."}}`, `{"replace_lines":{"start_anchor":"LINE:HASH","end_anchor":"LINE:HASH","new_text":"..."}}`, `{"insert_after":{"anchor":"LINE:HASH","new_text":"..."}}`, `{"replace_symbol":{"symbol":"name","new_body":"..."}}`, or `{"replace":{"old_text":"...","new_text":"..."}}`.
 
-Anchors come from `readSeek_read`, `readSeek_grep`, `readSeek_search`, or `readSeek_write`.
+Anchors come from `readSeek_read`, `readSeek_grep`, `readSeek_search`, or
+`readSeek_write`.
 
 ## Variants
 
-| Variant | Use | Anchors |
-|---|---|---|
-| `set_line` | Replace or delete one line | 1 |
-| `replace_lines` | Replace or delete one contiguous range | 2 |
-| `insert_after` | Insert after an existing line | 1 |
-| `replace_symbol` | Replace one mapped symbol | 0 (`symbol`) |
-| `replace` | Exact string replacement; one match unless `all: true` | 0 |
+| Variant | Use | Required anchor |
+| --- | --- | --- |
+| `set_line` | Replace or delete one line | `anchor` |
+| `replace_lines` | Replace or delete one contiguous range | `start_anchor`, `end_anchor` |
+| `insert_after` | Insert after one line | `anchor` |
+| `replace_symbol` | Replace one mapped symbol | `symbol` instead of an anchor |
+| `replace` | Replace exact text; one match unless `all: true` | None |
 
-Set `new_text` to `""` to delete lines; use `"\n"` for a blank line. Prefer
-anchored variants. Use `replace` only when anchors are impractical.
+Use `new_text: ""` to delete lines and `new_text: "\n"` for a blank line.
+Prefer anchored variants. Use `replace_symbol` for a whole symbol and `replace`
+only when anchors are impractical.
 
-## Input shape
+Each `edits[]` item contains exactly one variant. `new_text` and `new_body` are
+plain file content, not a diff or hashline output.
 
 ```json
 {
   "path": "src/foo.ts",
   "edits": [
     { "set_line": { "anchor": "42:ab1", "new_text": "const x = 2;" } },
-    { "replace_lines": { "start_anchor": "50:c3d", "end_anchor": "55:e4f", "new_text": "const y = 3;\nreturn y;" } },
-    { "insert_after": { "anchor": "60:f5a", "new_text": "// TODO\n" } },
-    { "replace_symbol": { "symbol": "add", "new_body": "export function add(a, b) {\n  return a + b;\n}" } },
-    { "replace": { "old_text": "value", "new_text": "result", "all": true } }
+    {
+      "replace_lines": {
+        "start_anchor": "50:c3d",
+        "end_anchor": "55:e4f",
+        "new_text": "const y = 3;\nreturn y;"
+      }
+    },
+    { "insert_after": { "anchor": "60:f5a", "new_text": "// TODO\n" } }
   ]
 }
 ```
 
-Use only needed variants. Each `edits[]` entry has exactly one key. `new_text`
-and `new_body` are plain file content, not diffs or hashlines.
+## Exact, fuzzy, and symbol replacement
 
-## Exact and fuzzy replacement
+`replace` is exact by default and fails when its text is absent. `fuzzy: true`
+retries only after exact matching fails and normalizes whitespace plus
+confusable Unicode. Verify any warned fuzzy match.
 
-`replace` is exact by default; missing text fails. `fuzzy: true` only normalizes
-whitespace and confusable Unicode after exact matching fails. Verify warned fuzzy
-matches before continuing.
+`replace_symbol` accepts `Name`, `Class.method`, or `Name@<line>` in a mappable
+source file. `new_body` must be non-empty and unindented. Do not overlap a
+symbol replacement with anchored edits.
 
-## `replace_symbol`
+## Stale anchors and validation
 
-Use `replace_symbol` for one whole mapped `Name`, `Class.method`, or
-`Name@<line>` in any mappable source file. `new_body` must be non-empty and
-unindented. Confirm fuzzy symbol matches first; do not overlap them with anchored
-edits.
-
-## Stale anchors
-
-On `hash-mismatch`, nearby lines marked `>>>` include fresh anchors:
+A `hash-mismatch` response marks nearby current lines with `>>>`, for example:
 
 ```text
 >>> 41:b34|  const renamed = 3;
 ```
 
-Retry with those anchors, or read/search again. Verify any auto-relocation warning.
-
-## Validation and warnings
-
-All edits validate before writing; hard failures write nothing. Anchored edits run
-bottom-up. `no-op` means no change. Syntax validation for every language with a
-tree-sitter parser follows `readseek.syntaxValidation`: `warn` (default), `block`,
-or `off`. It triggers when error or missing-node counts increase and reports the
-post-edit diagnostic ranges.
+Retry with those anchors or read/search again. Verify any automatic relocation
+warning.
 
-## Optional post-edit verification
+All edits validate before writing; a hard failure writes nothing. Anchored edits
+run bottom-up. `no-op` means no content changed. For languages with a tree-sitter
+parser, `readseek.syntaxValidation` controls newly introduced parse errors:
+`warn` (default), `block`, or `off`.
 
-`postEditVerify: true` reads back the written file and compares the persisted
-content, including BOM and line endings. Results provide a compact hashline diff,
-a unified patch, and structured `details.diffData`.
+Set `postEditVerify: true` to read back the file and compare persisted content,
+including its BOM and line endings. Verification returns a compact anchored
+diff, unified patch, and structured `details.diffData`.

package/prompts/grep.md

@@ -1,24 +1,27 @@
-Search plain text or regex in files and return edit-ready `LINE:HASH` anchors. Use for identifiers, strings, configuration, errors, comments, or documentation.
+Search text or regex in files and return edit-ready `LINE:HASH` anchors. Use for identifiers, strings, configuration, errors, comments, and documentation.
 
 ## Modes
 
-- Default: matching lines only. Match rows look like `path:>>LINE:HASH|content`.
-- `context: N`: include N lines before and after each match. Context rows use `path:  LINE:HASH|content`; nearby ranges are merged and deduped.
-- `summary: true`: return per-file match counts only. Use this first for broad searches, then narrow with `path`, `glob`, or a stricter pattern.
-- `scope: "symbol"`: group matches by enclosing symbol. By default returns full symbol blocks. `scopeContext: N` clips each match to ±N lines inside the symbol; `0` returns only match lines. Ignored with `summary: true`.
+- Default: return matching lines as `path:>>LINE:HASH|content`.
+- `context: N`: include N surrounding lines. Context rows use
+  `path:  LINE:HASH|content`; overlapping ranges are merged.
+- `summary: true`: return per-file counts only. Use this first for a broad
+  search, then narrow by `path`, `glob`, or pattern.
+- `scope: "symbol"`: group matches by their enclosing symbol. By default the
+  full symbol is returned; `scopeContext: N` clips each match to ±N lines inside
+  it, and `0` returns only matching lines. `summary` ignores symbol scope.
 
 ## Parameters
 
-- `pattern` — regular expression by default; set `literal: true` for exact text or regex metacharacters.
-- `path` — file or directory, default cwd.
+- `pattern` — regular expression by default; set `literal: true` for exact text.
+- `path` — file or directory; defaults to the current directory.
 - `glob` — file-name filter such as `*.ts` or `**/*.test.ts`.
 - `ignoreCase` — case-insensitive search.
-- `context` — surrounding lines for normal grep.
-- `limit` — maximum matches, default 100.
-- `summary` — counts only, no anchors.
+- `context` — surrounding lines in normal mode.
+- `limit` — maximum matches; defaults to 100.
+- `summary` — return counts without anchors.
 - `scope` — only `"symbol"` is supported.
-- `scopeContext` — non-negative context within symbol scope; requires `scope: "symbol"`.
+- `scopeContext` — non-negative context inside symbol scope.
 
-If output is truncated at `limit` or by the display budget, narrow with `summary`,
-then `path`/`glob`, then a stricter pattern. Request context or symbol blocks only
-after narrowing.
+If `limit` or the display budget truncates output, start with `summary`, narrow
+the file set and pattern, then request context or symbol blocks.

package/prompts/hover.md

@@ -1,6 +1,7 @@
-Identify the token and enclosing symbol at a cursor. Use before rename or definition lookup, or to identify a line's enclosing symbol. The file is read from disk.
+Identify the token and enclosing symbol at a cursor. Use before definition lookup or rename, or to identify a line's enclosing symbol.
 
 ## Parameters
 
-- `path`, `line` — required file path and one-based cursor line.
+- `path` — source file.
+- `line` — one-based cursor line.
 - `column` — optional one-based cursor byte column.

package/prompts/read.md

@@ -1,45 +1,50 @@
-Read anchored text by range, map, or symbol, process images with an explicit mode, and always read PDF text.
+Read anchored text by range, symbol, or map. Standalone images require an explicit mode; PDF text is always returned.
 
-## Choose the right read
+## Choose a read
 
-- Normal read: a small file or an `offset` / `limit` range.
-- `map: true`: append a structural map.
+- Default: read a small file or an `offset` / `limit` range.
+- `map: true`: append the file's structural map.
 - `symbol: "Name"`: read one mapped symbol.
-- `bundle: "local"`: include direct same-file support for a symbol.
+- `bundle: "local"`: include directly related symbols from the same file.
 
 ## Parameters
 
 - `path` — file path.
-- `offset` / `limit` — positive lines; `offset` is 1-indexed.
-- `map` — full-file map; incompatible with `symbol` or `bundle`.
-- `symbol` — `Name`, `Class.method`, or `Name@<line>`; incompatible with `offset` / `limit`.
+- `offset` / `limit` — positive line numbers; `offset` is one-based.
+- `map` — append a full-file map; incompatible with `symbol` and `bundle`.
+- `symbol` — `Name`, `Class.method`, or `Name@<line>`; incompatible with
+  `offset` and `limit`.
 - `bundle` — only `"local"`; requires `symbol` and excludes `map`.
-- `image` — an exposed standalone-image/PDF embedded-image mode; unavailable when `imageMode` is `"off"`.
-- `page` — one-based PDF page; defaults to page 1 and cannot be combined with `offset` / `limit`.
-
-Default cap: {{DEFAULT_MAX_LINES}} lines or {{DEFAULT_MAX_BYTES}}. PDF reads always return text for one page by default. Omitting `image` skips standalone images and PDF embedded images unless native vision is available in `"auto"` mode. With native vision, prepared standalone and PDF embedded images are passed directly instead of using local analysis.
-
-Truncated full-file reads append a map when available. Use its ranges for follow-up reads.
-
-## Symbol examples
-
-| Query | Reads |
-|---|---|
-| `{ "symbol": "processEvent" }` | function or unqualified symbol |
-| `{ "symbol": "EventEmitter" }` | class/interface/type/enum/etc. |
-| `{ "symbol": "EventEmitter.emit" }` | child method/member |
-| `{ "symbol": "Foo.bar@42" }` | overload/definition near line 42 |
-| `{ "symbol": "handleRequest", "bundle": "local" }` | symbol plus direct same-file support |
-
-## Symbol resolution
-
-`@<line>` is only a trailing suffix, as in `Foo.bar@42`; `foo@bar` is an ordinary name. Resolution prefers the containing range, then the nearest symbol at or after the line, then one above it.
-
-Result behavior:
-
-- **Found:** the symbol range.
-- **Ambiguous:** candidates and `name@<startLine>` retry hints.
-- **Fuzzy:** a warned best match; verify before editing.
-- **Not found/unmappable:** normal read with a warning and suggestions when available.
-
-Hash anchors from normal, symbol, and bundled reads are valid for `readSeek_edit` until the file changes.
+- `image` — standalone-image/PDF embedded-image mode; unavailable when
+  `imageMode` is `"off"`.
+- `page` — one-based PDF page; defaults to 1 and excludes `offset` / `limit`.
+
+Text output is capped at {{DEFAULT_MAX_LINES}} lines or {{DEFAULT_MAX_BYTES}}.
+A truncated full-file read appends a map when available; use its ranges for
+follow-up reads.
+
+Standalone images require `image`. In `"auto"`, `image: "none"` returns a
+prepared standalone image without local analysis. PDF text is always read;
+without `image`, embedded images are skipped unless an image-capable Pi model is
+active in `"auto"` mode. That model receives prepared images directly.
+
+## Symbol lookup
+
+| Query | Result |
+| --- | --- |
+| `{"symbol":"processEvent"}` | Function or other unqualified symbol |
+| `{"symbol":"EventEmitter"}` | Class, interface, type, enum, or similar symbol |
+| `{"symbol":"EventEmitter.emit"}` | Qualified child method or member |
+| `{"symbol":"Foo.bar@42"}` | Definition or overload near line 42 |
+| `{"symbol":"handleRequest","bundle":"local"}` | Symbol plus direct same-file support |
+
+`@<line>` is a trailing disambiguator; `foo@bar` remains an ordinary name.
+Resolution prefers a containing range, then the nearest symbol at or after the
+line, then one above it.
+
+A successful lookup returns the symbol range. Ambiguous results include
+`name@<startLine>` retry hints. Verify fuzzy matches before editing. A missing or
+unmappable symbol falls back to a normal read with a warning.
+
+Anchors from text, symbol, and bundled reads remain valid for `readSeek_edit`
+until the file changes.

package/prompts/refs.md

@@ -1,25 +1,21 @@
-Find identifier usages with enclosing symbols and edit-ready anchors. Use before renaming, deleting, or changing a symbol; add a cursor scope to exclude same-named bindings.
+Find identifier usages with enclosing symbols and edit-ready `LINE:HASH` anchors. Add cursor scope to follow one binding and exclude shadows.
 
 ## Parameters
 
-- `name` — identifier to find references for.
-- `path` — file or directory, default cwd.
-- `lang` — language hint for ambiguous, extensionless, or generated code.
-- `scope` — restrict results to the binding under `line`/`column` in a single file. Requires `line`.
-- `line` — one-based cursor line, used with `scope`.
-- `column` — one-based cursor byte column, used with `scope`.
-- `cached` — in a Git repository, search tracked/indexed files.
-- `others` — in a Git repository, search untracked files.
-- `ignored` — with `others`, include ignored untracked files.
+- `name` — identifier to find.
+- `path` — file or directory; defaults to the current directory.
+- `lang` — language override for ambiguous, extensionless, or generated source.
+- `scope` — restrict results to the binding at `line` / `column` in one file;
+  requires `line`.
+- `line` — one-based cursor line used with `scope`.
+- `column` — optional one-based cursor byte column used with `scope`.
+- `cached` — search tracked/indexed files in a Git repository.
+- `others` — search untracked files in a Git repository.
+- `ignored` — include ignored untracked files; requires `others`.
 
-## Scope
+Without `scope`, results match by name. With `scope`, results follow the cursor
+binding and exclude shadows.
 
-Without `scope`, references match by name. With `scope` and `line` (optionally
-`column`), results are limited to the cursor binding in one file and exclude
-shadows.
-
-## Git selection
-
-In Git repositories, directory search includes tracked/indexed and untracked,
-non-ignored files by default. `cached` or `others` restricts the search to that
-group; `ignored` requires `others`.
+In a Git work tree, directory search includes tracked/indexed and untracked
+non-ignored files by default. Setting `cached` or `others` restricts the set;
+`ignored` requires `others`.

package/prompts/rename.md

@@ -1,9 +1,11 @@
-Rename the symbol at a cursor without changing resolvable same-named bindings. Use for symbol renames; use search and edit for broader refactors.
+Rename the symbol at a cursor while preserving resolvable same-named bindings. Set `apply: false` to preview the verified plan.
 
 ## Parameters
 
-- `path`, `line`, `to` — required file, one-based cursor line, and plain new name.
+- `path` — source file containing the cursor.
+- `line` — one-based cursor line.
 - `column` — optional one-based cursor byte column.
-- `workspace` — expand across the project; local shadows are excluded where binding
-  support is available, and other files are otherwise matched by name.
-- `apply` — default `true`; set `false` to return only the verified plan.
+- `to` — new plain identifier.
+- `workspace` — expand across the project. The cursor file remains binding-aware;
+  other files use name matching where binding resolution is unavailable.
+- `apply` — defaults to `true`; set `false` to return only the verified plan.

package/prompts/search.md

@@ -1,35 +1,35 @@
-Search syntax-aware code shapes with AST patterns and return edit-ready anchors. Use for calls, imports, declarations, JSX, object fields, or control flow; use `readSeek_grep` for plain text.
+Search AST patterns (ast-grep style) and return edit-ready `LINE:HASH` anchors. Use `readSeek_grep` for plain text or regex.
 
 ## Parameters
 
-- `pattern` — ast-grep-style pattern to match.
-- `lang` — language hint for ambiguous, extensionless, generated, or JSX-like code.
-- `path` — file or directory, default cwd.
-- `cached` — in a Git repository, search tracked/indexed files.
-- `others` — in a Git repository, search untracked files.
-- `ignored` — with `others`, include ignored untracked files.
+- `pattern` — AST pattern to match.
+- `path` — file or directory; defaults to the current directory.
+- `lang` — language override for ambiguous, extensionless, generated, or
+  JSX-like source.
+- `cached` — search tracked/indexed files in a Git repository.
+- `others` — search untracked files in a Git repository.
+- `ignored` — include ignored untracked files; requires `others`.
 
 ## Pattern syntax
 
 - `$NAME` matches one AST node.
-- `$_` matches any one AST node when you do not need to reuse it.
-- `$$$ARGS` matches zero or more sibling nodes. Use it for function args, body statements, object fields, JSX children, etc.
-- Reusing a metavariable name requires every occurrence to match the same source text.
-
-Patterns are code, not text: formatting is mostly ignored, but syntax and required
-punctuation must be valid for the selected language.
-
-## Examples
-
-- `console.log($$$ARGS)` — calls.
-- `import $NAME from '$SOURCE'` — default imports.
-- `export function $NAME($$$PARAMS) { $$$BODY }` — exported functions.
-- `$OBJ.$METHOD($$$ARGS)` — method calls.
-- `<$TAG $$$ATTRS>$$$CHILDREN</$TAG>` — JSX/TSX elements.
-- `if ($COND) { $$$BODY }` — control-flow blocks.
-
-## Git selection
-
-In Git repositories, directory search includes tracked/indexed and untracked,
-non-ignored files by default. `cached` or `others` restricts the search to that
-group; `ignored` requires `others`.
+- `$_` matches one node without capturing a reusable value.
+- `$$$ARGS` matches zero or more sibling nodes, such as arguments, statements,
+  object fields, or JSX children.
+- Reusing a metavariable requires every occurrence to match the same source text.
+
+Patterns are code, not text. Formatting is mostly ignored, but syntax and
+required punctuation must be valid for the selected language.
+
+```text
+console.log($$$ARGS)
+import $NAME from '$SOURCE'
+export function $NAME($$$PARAMS) { $$$BODY }
+$OBJ.$METHOD($$$ARGS)
+<$TAG $$$ATTRS>$$$CHILDREN</$TAG>
+if ($COND) { $$$BODY }
+```
+
+In a Git work tree, directory search includes tracked/indexed and untracked
+non-ignored files by default. Setting `cached` or `others` restricts the set;
+`ignored` requires `others`.

package/prompts/view.md

@@ -1,14 +1,14 @@
-View the structure or selected content of an indexed PDF. Start with the default overview, then narrow by page or node instead of reading the whole document.
+View the structure or selected content of a PDF. Start with the overview, then narrow by page or node instead of reading the whole document.
 
 ## Parameters
 
-- `path` — PDF document to view.
-- `node` — optional node ID to use as the view root.
-- `page` — optional one-based source page.
-- `kind` — optional node kind filter.
-- `depth` — optional maximum depth below selected roots.
+- `path` — PDF file.
+- `node` — node ID to use as the view root.
+- `page` — one-based PDF page.
+- `kind` — node kind filter.
+- `depth` — maximum depth below selected roots.
 - `outline` — return outline nodes only.
 
-## Output
-
-Returns a bounded text projection with stable node IDs and source page references.
+A `.readseek/` directory must already exist; run `readseek init` if needed. The
+first call then creates a reusable structural index. Output is a bounded text
+projection with stable node IDs and source-page references.

package/prompts/write.md

@@ -1,19 +1,16 @@
-Create or replace a complete file and return `LINE:HASH` anchors. Use for new or fully generated files; use anchored edits for small changes.
+Create or replace a complete text file and return `LINE:HASH` anchors. Use anchored edits for small changes to an existing file.
 
-## Usage
-
-Existing files are overwritten without confirmation. Binary-looking content is
-rejected without writing.
+Existing files are replaced without confirmation. Binary-looking content is
+rejected before writing.
 
 ## Parameters
 
 - `path` — file path.
-- `content` — complete file contents.
+- `content` — complete file content.
 - `map` — append a best-effort structural map.
 
 ## Output
 
-Text writes return `LINE:HASH|content`. Visible output is capped at
-{{DEFAULT_MAX_LINES}} lines or {{DEFAULT_MAX_BYTES}}; full anchors remain in
-`readSeekValue`. Results also include a compact
-diff, unified patch, and structured `details.diffData`.
+Text output uses `LINE:HASH|content` and is capped at {{DEFAULT_MAX_LINES}} lines
+or {{DEFAULT_MAX_BYTES}}. Complete anchors remain in `readSeekValue`. Results
+also include a compact diff and structured `details.diffData`.