pi-readseek 0.6.3 → 0.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readseek",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Pi extension for readseek-backed hash-anchored read/edit/grep, structural code maps, structural search, and file exploration",
   "type": "module",
   "exports": {
@@ -39,7 +39,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@jarkkojs/readseek": "^0.6.3",
+    "@jarkkojs/readseek": "^0.6.4",
     "diff": "^8.0.3",
     "xxhash-wasm": "^1.1.0"
   },

package/prompts/def.md

@@ -1,5 +1,4 @@
-Find structural definitions by qualified or unqualified name across a file or
-directory.
+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.
 
 ## Parameters
 
@@ -8,7 +7,4 @@ directory.
 - `lang` — language override.
 - `cached`, `others`, `ignored` — Git file selection; `ignored` requires `others`.
 
-## When to use
-
-- After `readSeek_hover`, use its qualified symbol name.
-- When asked where a function, class, or type is defined.
+After `readSeek_hover`, use its qualified symbol name.

package/prompts/edit.md

@@ -1,6 +1,6 @@
-Edit existing text files with fresh `LINE:HASH` anchors from `readSeek_read`,
-`readSeek_grep`, `readSeek_search`, or `readSeek_write`. The file must have
-been anchored in this session; on `file-not-read`, read or search it first.
+Edit existing text files safely with fresh `LINE:HASH` anchors; on `file-not-read`, read or search the file first.
+
+Anchors come from `readSeek_read`, `readSeek_grep`, `readSeek_search`, or `readSeek_write`.
 
 ## Variants
 

package/prompts/grep.md

@@ -1,4 +1,4 @@
-Search file contents. Non-summary results include edit-ready `LINE:HASH` anchors, so you usually do not need a follow-up `readSeek_read` before `readSeek_edit`.
+Search plain text or regex in files and return edit-ready `LINE:HASH` anchors. Use for identifiers, strings, configuration, errors, comments, or documentation.
 
 ## Modes
 
@@ -19,10 +19,4 @@ Search file contents. Non-summary results include edit-ready `LINE:HASH` anchors
 - `scope` — only `"symbol"` is supported.
 - `scopeContext` — non-negative context within symbol scope; requires `scope: "symbol"`.
 
-## Use well
-
-Use `readSeek_grep` for text: identifiers, strings, config keys, error messages, comments, or docs. Use `literal: true` unless you want regex behavior.
-
-For code shape — calls, imports, declarations, JSX, object literals, control flow — prefer `readSeek_search`, which parses AST patterns.
-
 If output says results were truncated at `limit` or by display budget, narrow before editing. Good narrowing order: `summary` → `path`/`glob` → stricter pattern → `scope: "symbol"` or `context`.

package/prompts/hover.md

@@ -1,11 +1,6 @@
-Identify the identifier and enclosing symbol at a cursor. Unsaved editor content
-is included.
+Identify the token and enclosing symbol at a cursor. Use before rename or definition lookup, or to identify a line's enclosing symbol; unsaved editor content is included.
 
 ## Parameters
 
 - `path`, `line` — required file path and one-based cursor line.
 - `column` — optional one-based cursor byte column.
-
-## When to use
-
-- Before rename or go-to-definition, or to identify a line's enclosing symbol.

package/prompts/read.md

@@ -1,4 +1,4 @@
-Read files through readseek. Text results use `LINE:HASH|content` anchors for `readSeek_edit`. Images and PDFs require an explicit available `image` mode; omitting it skips them. Default cap: {{DEFAULT_MAX_LINES}} lines or {{DEFAULT_MAX_BYTES}}.
+Read anchored text by range, map, or symbol, and process images or PDFs with an explicit mode.
 
 ## Choose the right read
 
@@ -16,6 +16,8 @@ Read files through readseek. Text results use `LINE:HASH|content` anchors for `r
 - `bundle` — only `"local"`; requires `symbol` and excludes `map`.
 - `image` — an exposed image/PDF mode.
 
+Default cap: {{DEFAULT_MAX_LINES}} lines or {{DEFAULT_MAX_BYTES}}. Omitting `image` skips images and PDFs.
+
 Truncated full-file reads append a map when available. Use its ranges for follow-up reads.
 
 ## Symbol examples

package/prompts/refs.md

@@ -1,5 +1,4 @@
-Find identifier references before renaming, deleting, or changing a symbol when
-text search is too broad. Results include edit-ready anchors and enclosing symbols.
+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.
 
 ## Parameters
 
@@ -23,5 +22,3 @@ shadows.
 
 In Git repositories, directory search includes tracked/indexed and untracked
 non-ignored files. `ignored` requires `others`.
-
-Use `readSeek_grep` for plain text, `readSeek_search` for code shape, and `readSeek_refs` for identifier usage.

package/prompts/rename.md

@@ -1,5 +1,4 @@
-Rename an identifier with binding accuracy. The cursor binding is resolved and
-only occurrences of that declaration are changed.
+Rename the symbol at a cursor without changing same-named bindings. Use for symbol renames; use search and edit for broader refactors.
 
 ## Parameters
 
@@ -7,12 +6,3 @@ only occurrences of that declaration are changed.
 - `column` — optional one-based cursor byte column.
 - `workspace` — expand across the project; local shadows in other files are excluded.
 - `apply` — default `true`; set `false` to return only the verified plan.
-
-## When to use
-
-- Use when the user requests a symbol rename and the cursor is known.
-
-## When not to use
-
-- Use `readSeek_grep`/`readSeek_search` for broad replacement and
-  `readSeek_edit` for other refactors.

package/prompts/sg.md

@@ -1,6 +1,4 @@
-Search code with AST patterns when text search is too broad. Use it for calls,
-imports, declarations, JSX, object fields, and control flow. Results include
-edit-ready anchors.
+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.
 
 ## Parameters
 
@@ -35,5 +33,3 @@ punctuation must be valid for the selected language.
 In Git repositories, directory search includes tracked/indexed and untracked
 non-ignored files. Use `cached`, `others`, and `ignored` to choose; `ignored`
 requires `others`.
-
-Use `readSeek_grep` for plain text and `readSeek_search` for structure.

package/prompts/write.md

@@ -1,10 +1,7 @@
-Create or replace a whole file and return `LINE:HASH` anchors for follow-up edits.
+Create or replace a complete file and return `LINE:HASH` anchors. Use for new or fully generated files; use anchored edits for small changes.
 
 ## Use / avoid
 
-Use it for new, generated, or intentionally replaced files. For small changes or
-appends, read/search first and use `readSeek_edit`.
-
 Existing files are overwritten without confirmation. Binary-looking content gets
 no anchors.
 

package/src/def.ts

@@ -15,7 +15,7 @@ import type { FileAnchoredCallback } from "./tool-types.js";
 
 const DEF_PROMPT_METADATA = defineToolPromptMetadata({
 	promptUrl: new URL("../prompts/def.md", import.meta.url),
-	promptSnippet: "Find structural definitions for a symbol",
+	promptSnippet: "Find where a symbol is defined",
 });
 
 type DefParams = {

package/src/edit.ts

@@ -59,7 +59,9 @@ const hashlineEditItemSchema = Type.Union([
 const hashlineEditSchema = Type.Object(
 	{
 		path: filePathParam(),
-		edits: Type.Optional(Type.Array(hashlineEditItemSchema, { description: "Edit operations" })),
+		edits: Type.Optional(Type.Array(hashlineEditItemSchema, {
+			description: "Edits: set_line, replace_lines, insert_after, replace_symbol, or replace",
+		})),
 		postEditVerify: Type.Optional(Type.Boolean({
 			description: "Verify persisted content after write",
 		})),
@@ -565,7 +567,7 @@ export function registerEditTool(pi: ExtensionAPI, options: EditToolOptions = {}
 	const name = options.name ?? "readSeek_edit";
 	const promptMetadata = defineToolPromptMetadata({
 		promptUrl: new URL("../prompts/edit.md", import.meta.url),
-		promptSnippet: "Edit with fresh hash-verified anchors",
+		promptSnippet: "Safely edit with fresh LINE:HASH anchors",
 		registeredName: name,
 		toolAliases: options.toolAliases,
 	});

package/src/grep.ts

@@ -26,20 +26,20 @@ import { searchPathParam } from "./readseek-params.js";
 
 
 const grepSchema = Type.Object({
-	pattern: Type.String({ description: "Pattern to search" }),
+	pattern: Type.String({ description: "Regex pattern; use literal for exact text" }),
 	path: searchPathParam(),
-	glob: Type.Optional(Type.String({ description: "Glob filter" })),
+	glob: Type.Optional(Type.String({ description: "File-name glob, such as *.ts" })),
 	ignoreCase: Type.Optional(Type.Boolean({ description: "Ignore case" })),
 	literal: Type.Optional(Type.Boolean({ description: "Treat pattern literally" })),
-	context: optionalIntOrString("Context lines"),
-	limit: optionalIntOrString("Max matches"),
+	context: optionalIntOrString("Surrounding lines for each match"),
+	limit: optionalIntOrString("Maximum matches to return"),
 	summary: Type.Optional(Type.Boolean({ description: "Return per-file counts" })),
 	scope: Type.Optional(
 		Type.Literal("symbol", {
-			description: "Scope matches to symbols",
+			description: "Group matches by enclosing symbol",
 		}),
 	),
-	scopeContext: optionalIntOrString("Symbol context lines"),
+	scopeContext: optionalIntOrString("Context lines within each symbol"),
 });
 
 interface GrepParams {
@@ -513,7 +513,7 @@ export function registerGrepTool(pi: ExtensionAPI, options: GrepToolOptions = {}
 	const name = options.name ?? "readSeek_grep";
 	const promptMetadata = defineToolPromptMetadata({
 		promptUrl: new URL("../prompts/grep.md", import.meta.url),
-		promptSnippet: "Search file text with edit-ready anchors",
+		promptSnippet: "Search plain text or regex with edit-ready anchors",
 		registeredName: name,
 	});
 	const tool = registerReadSeekTool(pi, {

package/src/hover.ts

@@ -15,7 +15,7 @@ import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderErrorResult, r
 
 const HOVER_PROMPT_METADATA = defineToolPromptMetadata({
 	promptUrl: new URL("../prompts/hover.md", import.meta.url),
-	promptSnippet: "Identify a cursor token and enclosing symbol",
+	promptSnippet: "Identify the token and enclosing symbol at a cursor",
 });
 
 const hoverSchema = Type.Object({

package/src/read.ts

@@ -524,7 +524,7 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 	const imageModes = imageMode === "auto" ? ["none", "ocr", "caption", "objects"] as const : ["ocr", "caption", "objects"] as const;
 	const promptMetadata = defineToolPromptMetadata({
 		promptUrl: new URL("../prompts/read.md", import.meta.url),
-		promptSnippet: "Read files or images with anchors, maps, symbols, and OCR",
+		promptSnippet: "Read anchored text, symbols, maps, images, or PDFs",
 		registeredName: name,
 	});
 	const tool = registerReadSeekTool(pi, {
@@ -541,12 +541,12 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 		parameters: Type.Object({
 			path: filePathParam(),
 			offset: optionalIntOrString("Start line (1-indexed)"),
-			limit: optionalIntOrString("Max lines"),
+			limit: optionalIntOrString("Maximum lines to return"),
 			symbol: Type.Optional(Type.String({ description: "Symbol name to read" })),
 			map: mapParam(),
 			bundle: Type.Optional(
 				Type.Literal("local", {
-					description: "Include same-file local support",
+					description: "Include related symbols from the same file; requires symbol",
 				}),
 			),
 			...(imageMode === "off"

package/src/readseek-params.ts

@@ -4,12 +4,12 @@ import { buildToolErrorResult, type ToolErrorResult } from "./readseek-value.js"
 
 /** Optional search path shared by the readseek search tools. */
 export function searchPathParam() {
-  return Type.Optional(Type.String({ description: "Search path" }));
+  return Type.Optional(Type.String({ description: "File or directory to search" }));
 }
 
 /** Optional language hint shared by the readseek search tools. */
 export function langParam() {
-  return Type.Optional(Type.String({ description: "Language hint" }));
+  return Type.Optional(Type.String({ description: "Language override when auto-detection is ambiguous" }));
 }
 
 /**

package/src/refs.ts

@@ -27,7 +27,7 @@ type RefsParams = {
 
 const REFS_PROMPT_METADATA = defineToolPromptMetadata({
   promptUrl: new URL("../prompts/refs.md", import.meta.url),
-  promptSnippet: "Find identifier references with enclosing symbols",
+  promptSnippet: "Find usages of an identifier or cursor binding",
 });
 
 interface RefsToolOptions {
@@ -133,9 +133,9 @@ export function registerRefsTool(pi: ExtensionAPI, options: RefsToolOptions = {}
       name: Type.String({ description: "Identifier to find references for" }),
       path: searchPathParam(),
       lang: langParam(),
-      scope: Type.Optional(Type.Boolean({ description: "Restrict to the binding under line/column (single file)" })),
-      line: Type.Optional(Type.Number({ description: "One-based cursor line, used with scope" })),
-      column: Type.Optional(Type.Number({ description: "One-based cursor byte column, used with scope" })),
+      scope: Type.Optional(Type.Boolean({ description: "Restrict results to the binding at the cursor" })),
+      line: Type.Optional(Type.Number({ description: "Cursor line (1-indexed), required with scope" })),
+      column: Type.Optional(Type.Number({ description: "Cursor byte column (1-indexed) for disambiguation" })),
       ...readSeekGitSearchParams(),
     }),
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {

package/src/register-tool.ts

@@ -12,7 +12,7 @@ export function optionalIntOrString(description: string) {
 
 /** Required file-path parameter shared by the read, edit, and write tools. */
 export function filePathParam() {
-  return Type.String({ description: "File path" });
+  return Type.String({ description: "Absolute or relative file path" });
 }
 
 /** Optional structural-map toggle shared by the read and write tools. */

package/src/rename.ts

@@ -13,16 +13,16 @@ import { clampLineToWidth, clampLinesToWidth, linkedPathLine, linkToolPath, rend
 
 const RENAME_PROMPT_METADATA = defineToolPromptMetadata({
 	promptUrl: new URL("../prompts/rename.md", import.meta.url),
-	promptSnippet: "Rename a binding accurately from its cursor",
+	promptSnippet: "Rename the symbol at a cursor without touching shadows",
 });
 
 const renameSchema = Type.Object({
 	path: filePathParam(),
-	line: Type.Number({ description: "One-based cursor line of the binding to rename" }),
-	column: Type.Optional(Type.Number({ description: "One-based cursor byte column of the binding to rename" })),
-	to: Type.String({ description: "New name for the binding" }),
-	workspace: Type.Optional(Type.Boolean({ description: "Expand rename across project root (name-based outside cursor file)" })),
-	apply: Type.Optional(Type.Boolean({ description: "Write the planned edits to disk after verifying line hashes" })),
+	line: Type.Number({ description: "One-based line of the symbol to rename" }),
+	column: Type.Optional(Type.Number({ description: "One-based byte column for disambiguation" })),
+	to: Type.String({ description: "New symbol name" }),
+	workspace: Type.Optional(Type.Boolean({ description: "Rename across the project" })),
+	apply: Type.Optional(Type.Boolean({ description: "Apply the verified edits; default true" })),
 });
 
 interface RenameParams {

package/src/sg.ts

@@ -49,7 +49,7 @@ export function mergeRanges(ranges: SgRange[]): SgRange[] {
 
 const SG_PROMPT_METADATA = defineToolPromptMetadata({
   promptUrl: new URL("../prompts/sg.md", import.meta.url),
-  promptSnippet: "Search code by AST pattern with edit-ready anchors",
+  promptSnippet: "Search syntax-aware code shapes with AST patterns",
 });
 
 interface SgToolOptions {
@@ -190,7 +190,7 @@ export function registerSgTool(pi: ExtensionAPI, options: SgToolOptions = {}) {
     promptSnippet: SG_PROMPT_METADATA.promptSnippet,
     promptGuidelines: SG_PROMPT_METADATA.promptGuidelines,
     parameters: Type.Object({
-      pattern: Type.String({ description: "AST pattern" }),
+      pattern: Type.String({ description: "ast-grep pattern, such as console.log($$$ARGS)" }),
       lang: langParam(),
       path: searchPathParam(),
       ...readSeekGitSearchParams(),

package/src/tool-prompt-metadata.ts

@@ -2,16 +2,6 @@ import { readFileSync } from "node:fs";
 
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize } from "@earendil-works/pi-coding-agent";
 
-const COMPACT_DESCRIPTIONS: Record<string, string> = {
-  "read.md": "Read text files, images, or PDFs by path; text has LINE:HASH anchors and visual files require an explicit image mode.",
-  "edit.md": "Edit existing text files using fresh LINE:HASH anchors from readSeek_read, readSeek_grep, readSeek_search, or readSeek_write.",
-  "grep.md": "Search file contents; non-summary results include LINE:HASH anchors for edits.",
-
-  "write.md": "Create or overwrite a complete file and return anchors.",
-  "sg.md": "Search code by AST pattern and return anchored matches.",
-  "refs.md": "Find references to an identifier and return anchored usages with enclosing symbols.",
-};
-
 const REPLACEABLE_TOOL_GUIDELINES: Record<string, { readSeekName: string; builtInName: string; benefit: string }> = {
   "read.md": {
     readSeekName: "readSeek_read",
@@ -37,8 +27,7 @@ const REPLACEABLE_TOOL_GUIDELINES: Record<string, { readSeekName: string; builtI
 
 const COMPACT_GUIDELINES: Record<string, string[]> = {
   "read.md": [
-    "Use readSeek_read map or symbol mode before pulling large code files into context.",
-    "For images and PDFs, explicitly choose one of the image modes exposed by readSeek_read.",
+    "Use readSeek_read map or symbol mode to inspect large code 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.",
@@ -50,8 +39,7 @@ const COMPACT_GUIDELINES: Record<string, string[]> = {
     "Use anchored edits rather than readSeek_write for small changes or appends to existing files.",
   ],
   "sg.md": [
-    "Use readSeek_search for AST-shaped code patterns.",
-    "Use readSeek_grep instead of readSeek_search for plain text.",
+    "Use readSeek_search for syntax-aware code shapes; use readSeek_grep for plain text.",
   ],
   "refs.md": [
     "Use readSeek_refs to find every usage of an identifier before renaming or deleting it.",
@@ -96,7 +84,6 @@ export function defineToolPromptMetadata(options: {
 }): ToolPromptMetadata {
   const prompt = loadPrompt(options.promptUrl);
   const fileName = promptFileName(options.promptUrl);
-  const compactDescription = COMPACT_DESCRIPTIONS[fileName];
   const replaceable = REPLACEABLE_TOOL_GUIDELINES[fileName];
   const registeredName = options.registeredName ?? replaceable?.readSeekName;
   const preferenceGuideline = replaceable && registeredName
@@ -105,7 +92,7 @@ export function defineToolPromptMetadata(options: {
       : `Use ${registeredName}; ${replaceable.benefit}`
     : undefined;
   return {
-    description: rewriteToolAliases(compactDescription ?? firstPromptParagraph(prompt), options.toolAliases),
+    description: rewriteToolAliases(firstPromptParagraph(prompt), options.toolAliases),
     promptSnippet: rewriteToolAliases(options.promptSnippet, options.toolAliases),
     promptGuidelines: [
       ...(preferenceGuideline ? [preferenceGuideline] : []),

package/src/write.ts

@@ -241,7 +241,7 @@ export function registerWriteTool(pi: ExtensionAPI, options: WriteToolOptions =
   const name = options.name ?? "readSeek_write";
   const promptMetadata = defineToolPromptMetadata({
     promptUrl: new URL("../prompts/write.md", import.meta.url),
-    promptSnippet: "Create or overwrite a file with edit anchors",
+    promptSnippet: "Create or replace a complete file with edit anchors",
     registeredName: name,
   });
   const tool = registerReadSeekTool(pi, {
@@ -252,7 +252,7 @@ export function registerWriteTool(pi: ExtensionAPI, options: WriteToolOptions =
     promptGuidelines: promptMetadata.promptGuidelines,
     parameters: Type.Object({
       path: filePathParam(),
-      content: Type.String({ description: "File content" }),
+      content: Type.String({ description: "Complete file content" }),
       map: mapParam(),
     }),
     async execute(_toolCallId: string, params: { path: string; content: string; map?: boolean }, _signal: AbortSignal | undefined, _onUpdate: any, ctx: any): Promise<any> {