pi-readseek 0.2.0 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readseek",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "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.2.2",
+    "@jarkkojs/readseek": "0.2.6",
     "diff": "^8.0.3",
     "ignore": "^7.0.5",
     "picomatch": "^4.0.4",

package/prompts/edit.md

@@ -1,4 +1,4 @@
-Surgically edit existing text files. Prefer hash-verified anchored edits from fresh `read`, `grep`, `search`, or `write` output; copy `LINE:HASH` anchors exactly.
+Surgically edit existing text files. Prefer hash-verified anchors from fresh `read`, `grep`, `search`, or `write` output; copy `LINE:HASH` anchors exactly.
 
 `edit` requires the target file to have been anchored earlier in the current session. If you get `file-not-read`, run `read`, `grep`, `search`, or `write` first.
 
@@ -6,16 +6,15 @@ Surgically edit existing text files. Prefer hash-verified anchored edits from fr
 
 | Variant | Use | Anchors |
 |---|---|---|
-| `set_line` | Replace/delete one line | 1 |
-| `replace_lines` | Replace/delete a contiguous range | 2 |
+| `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 function/class/method/etc. | 0 (`symbol`) |
-| `replace` | String replacement escape hatch; one match by default, all with `all: true` | 0 |
+| `replace_symbol` | Replace one function/class/method/interface/type/enum/etc. | 0 (`symbol`) |
+| `replace` | Exact string replacement escape hatch; one match by default, all with `all: true` | 0 |
 
-Set `new_text` (or `replace_lines` `new_text`) to `""` to delete the anchored line(s). For an intentionally blank line, use `"\n"` or whitespace content, not `""`.
-Prefer `set_line`, `replace_lines`, and `insert_after`: they verify the file still matches the anchored content. Use `replace` only when anchors are impractical, such as repeated text across many unrelated lines.
+Set `new_text` (or `replace_lines.new_text`) to `""` to delete anchored line(s). For an intentionally blank line, use `"\n"` or whitespace content, not `""`.
 
-`replace` is exact-only by default: missing `old_text` fails with `text-not-found`. Wrap old_text/new_text in {replace: ...} — a bare top-level `{old_text, new_text}` inside `edits[]` is rejected with guidance. `fuzzy: true` is a narrow fallback that only normalizes whitespace and confusable Unicode (e.g. smart hyphens) after exact matching fails; it is **not approximate or Levenshtein/semantic matching** and will not find renamed or reworded text. When fuzzy matching is used, the response warns that exact text was not found.
+Prefer `set_line`, `replace_lines`, and `insert_after`: they verify that the file still matches the anchored content. Use `replace` only when anchors are impractical, such as repeated text across many unrelated lines.
 
 ## Input shape
 
@@ -32,29 +31,32 @@ Prefer `set_line`, `replace_lines`, and `insert_after`: they verify the file sti
 }
 ```
 
-Use only the variant(s) needed for the task; the example shows all shapes together for reference. Each `edits[]` entry must contain exactly one variant key. `new_text` / `new_body` is plain file content — no hash prefixes or diff markers.
+Use only the needed variant(s); the example shows all shapes for reference. Each `edits[]` entry must contain exactly one variant key. `new_text` / `new_body` is plain file content — no hash prefixes or diff markers.
 
-## Optional post-edit verification
+## Exact and fuzzy replacement
+
+`replace` is exact-only by default. Missing `old_text` fails with `text-not-found`.
 
-`postEditVerify: true` opts into post-write persisted-content verification for this one call. It is default off: when omitted or false, successful edits use the normal fast path and do not perform an extra read-back check.
+Wrap string replacements as `{ "replace": { "old_text": "...", "new_text": "..." } }`; a bare top-level `{ old_text, new_text }` inside `edits[]` is rejected with guidance.
 
-When enabled, `edit` first runs the normal validation and write path. Only after the write succeeds, it reads the file back from disk and compares the persisted content to the exact intended content, including BOM restoration and original line-ending restoration. This is not syntax validation; syntax validation is the separate pre-write `syntaxValidate` / `PI_HASHLINE_SYNTAX_VALIDATE` guard described below.
+`fuzzy: true` is a narrow fallback after exact matching fails. It normalizes whitespace and confusable Unicode such as smart hyphens; it is **not** approximate, Levenshtein, or semantic matching. Fuzzy successes return a warning.
 
 ## `replace_symbol`
 
-Use `replace_symbol` to replace one function, class, method, interface, type, enum, or similar symbol. Query symbols like `read symbol:`: `Name`, `Class.method`, or `Name@<line>`.
+Use `replace_symbol` when you want to replace one whole mapped symbol without line anchors. Query symbols like `read({ symbol })`: `Name`, `Class.method`, or `Name@<line>`.
 
 Rules:
-- Use an exact name, dotted path, or `@<line>`. If `read({symbol})` returned a fuzzy match, confirm the exact symbol before editing.
+
+- Use an exact name, dotted path, or `@<line>`. If `read({ symbol })` returned a fuzzy match, confirm the exact symbol first.
 - Supported for TypeScript, JavaScript, Rust, and Java. For other languages, use anchored edits.
 - `new_body` must not be empty or whitespace-only.
 - Write `new_body` without extra leading indentation; `edit` re-indents it to match the original symbol.
 - If `new_body` appears to declare a different symbol name, the edit still applies but returns a `name-mismatch` warning.
-- Do not combine `replace_symbol` with anchored edits that touch the same lines. Duplicate/overlapping `replace_symbol` ranges are rejected.
+- Do not combine `replace_symbol` with anchored edits that touch the same lines. Duplicate or overlapping `replace_symbol` ranges are rejected.
 
 ## Stale anchors
 
-If anchors no longer match, `edit` fails with a hash mismatch (`hash-mismatch`) and shows nearby current lines. Lines marked `>>>` include updated anchors:
+If anchors no longer match, `edit` fails with `hash-mismatch` and shows nearby current lines. Lines marked `>>>` include updated anchors:
 
 ```text
 >>> 41:b34|  const renamed = 3;
@@ -62,32 +64,39 @@ If anchors no longer match, `edit` fails with a hash mismatch (`hash-mismatch`)
 
 Copy the updated `LINE:HASH` and retry. If the target moved farther away, re-run `read`, `grep`, `search`, or `write` for fresh anchors.
 
-If `edit` auto-relocates an anchor, check the warning and verify the edit landed in the intended place.
+If `edit` auto-relocates an anchor, read the warning and verify that the edit landed in the intended place.
 
 ## Validation and warnings
 
 - All edits are checked before writing; if a hard validation fails, nothing is written.
 - Anchored edits are applied bottom-up so line numbers stay stable.
 - `no-op` means the requested edit matched the current file already or produced identical content.
-- A whitespace-only warning means formatting changed but behavior probably did not.
-- A `replace`-only success may include a reminder to prefer anchored edits next time.
+- Whitespace-only warnings mean formatting changed but behavior probably did not.
+- A `replace`-only success may remind you to prefer anchored edits next time.
 
 Syntax validation runs before writing when supported:
+
 - Supported: Rust, C++, C headers, Java.
 - Default `warn`: write succeeds, but warnings include `syntax-regression: lines X-Y`.
 - `block`: aborts without writing.
 - `off`: skips validation.
 - `PI_HASHLINE_SYNTAX_VALIDATE` can set the default mode.
 
-Existing syntax errors are tolerated; the warning is for newly introduced parser errors.
+Existing syntax errors are tolerated; warnings are for newly introduced parser errors.
+
+## Optional post-edit verification
+
+`postEditVerify: true` opts into read-back verification for this call. It is off by default. When enabled, `edit` writes normally, then reads the file back and compares persisted content to the intended content, including BOM and original line endings. This is not syntax validation.
 
 ## Diff data contract
 
-Successful `edit` results include `details.diffData` and `details.readseekValue.diffData` in addition to the existing `details.diff` / `readseekValue.diff` string fields. The string fields remain the backward-compatible human-readable fallback.
+Successful `edit` results include:
 
-Successful `edit` results also include `details.patch`: a standard unified diff (`---`/`+++` file headers and `@@` hunk headers) generated from the pre-/post-edit file contents. Use `details.patch` when you need a portable, tool-agnostic patch (e.g. to apply elsewhere); use the compact `details.diff` hashline string for human-readable in-session display. `details.patch` is additive and does not change `details.diff`.
+- `details.diff` and `details.readseekValue.diff`: compact human-readable hashline diff strings.
+- `details.patch`: standard unified diff with file and hunk headers.
+- `details.diffData` and `details.readseekValue.diffData`: stable structured diff data.
 
-`diffData` is a stable versioned contract:
+`diffData` shape:
 
 ```ts
 type DiffData = {
@@ -110,4 +119,4 @@ type DiffData = {
 };
 ```
 
-For compact one-line hashline diffs, `details.diff` remains compact, while `diffData.entries` uses expanded remove/add rows so renderers can show inline word changes without breaking hashline output.
+For compact one-line hashline diffs, `details.diff` remains compact while `diffData.entries` uses expanded remove/add rows so renderers can show inline word changes without breaking hashline output.

package/prompts/find.md

@@ -1,4 +1,4 @@
-Find files recursively by name. Uses glob patterns by default, respects nested `.gitignore`, includes hidden files, and returns relative paths.
+Find files or directories recursively by basename. Uses glob patterns by default, respects nested `.gitignore`, includes hidden entries, and returns relative paths.
 
 ## Parameters
 
@@ -9,11 +9,10 @@ Find files recursively by name. Uses glob patterns by default, respects nested `
 - `maxDepth` — non-negative directory depth limit.
 - `sortBy` — `"name"` default, `"mtime"`, or `"size"`; use `reverse: true` for descending/newest/largest first.
 - `modifiedSince` — keep entries modified strictly after an ISO date/time or relative age like `30m`, `1h`, `24h`, `7d`.
-- `minSize` / `maxSize` — file-size filters, inclusive; numbers are bytes, strings accept 1024-based `KB`, `MB`, `GB`, etc. Directories are not removed by size filters.
+- `minSize` / `maxSize` — inclusive file-size filters; numbers are bytes, strings accept 1024-based `KB`, `MB`, `GB`, etc. Directories are not removed by size filters.
 
 ## Output and usage
 
-One relative path per line. Directories end with `/`. If results exceed `limit` or 50 KB, output says it was truncated.
-Filtering and sorting happen before `limit`, so queries like largest/newest files work as expected.
+Output is one relative path per line. Directories end with `/`. Filtering and sorting happen before `limit`, so newest/largest queries work as expected.
 
-Use `find` for recursive file-name discovery, `ls` for one directory, and `grep` for file contents. Remember: `pattern` matches basenames, not full paths.
+Use `find` for recursive name discovery, `ls` for one directory, `grep` or `search` for contents, and `read` for file content. Remember: `pattern` matches basenames, not full paths.

package/prompts/grep.md

@@ -1,26 +1,28 @@
-Search file contents. Non-summary results return `LINE:HASH` anchors usable directly by `edit`; no follow-up `read` is needed.
+Search file contents. Non-summary results include edit-ready `LINE:HASH` anchors, so you usually do not need a follow-up `read` before `edit`.
 
 ## Modes
 
-- Default: matching lines only. Output lines are `path:>>LINE:HASH|content`; `>>` marks matches.
-- `context: N`: include N lines before/after each match. Context lines use `path:  LINE:HASH|content`; nearby ranges are merged/deduped.
-- `summary: true`: return per-file match counts only — no line content or anchors. Use first for broad searches, then narrow with `path`/`glob`.
-- `scope: "symbol"`: group matches by enclosing symbol. By default returns the full symbol block. `scopeContext: N` windows to ±N lines around each match, clipped to the symbol; `0` returns only match lines. Ignored when `summary: true`.
+- 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`.
 
 ## Parameters
 
-- `pattern` — regex by default; use `literal: true` for exact strings or regex metacharacters.
+- `pattern` — regular expression by default; set `literal: true` for exact text or regex metacharacters.
 - `path` — file or directory, default cwd.
-- `glob` — file filter, e.g. `'*.ts'` or `'**/*.test.ts'`.
+- `glob` — file-name filter such as `*.ts` or `**/*.test.ts`.
 - `ignoreCase` — case-insensitive search.
 - `context` — surrounding lines for normal grep.
-- `limit` — max matches, default 100.
+- `limit` — maximum matches, default 100.
 - `summary` — counts only, no anchors.
 - `scope` — only `"symbol"` is supported.
 - `scopeContext` — non-negative context within symbol scope; requires `scope: "symbol"`.
 
-## Truncation and guidance
+## Use well
 
-If matches hit `limit`, output appends `[Results truncated at N matches — refine pattern or increase limit]`. Large non-summary results may cap displayed matches per file and/or head-truncate by output budget; narrow with `summary`, `path`, `glob`, or a more specific pattern.
+Use `grep` for text: identifiers, strings, config keys, error messages, comments, or docs. Use `literal: true` unless you want regex behavior.
 
-Use `grep` for text search. For structural code patterns such as calls, imports, or JSX, prefer `search`.
+For code shape — calls, imports, declarations, JSX, object literals, control flow — prefer `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/ls.md

@@ -1,11 +1,11 @@
-List one directory. Shows directories first with `/`, then files, sorted alphabetically; dotfiles are included.
+List one directory. Output is directories first (with `/`), then files, sorted alphabetically; dotfiles are included.
 
 ## Parameters
 
 - `path` — directory to list, default cwd.
 - `limit` — max entries, default 500; must be positive.
-- `glob` — optional entry-name filter such as `*.ts` or `.env*`.
+- `glob` — optional entry-name filter such as `*.ts`, `.env*`, or `test-*`.
 
 ## Usage
 
-Output is one entry per line. Use `ls` to inspect a single directory, `find` for recursive discovery, and `read` for file contents. If output exceeds `limit` or 50 KB, it says so.
+Use `ls` to inspect one known directory. Use `find` for recursive discovery, `grep` or `search` for contents, and `read` for file content. If output exceeds `limit` or 50 KB, narrow with `glob` or switch to `find`.

package/prompts/read.md

@@ -1,13 +1,21 @@
-Read text files with `LINE:HASH|content` anchors usable by `edit`. Default cap: {{DEFAULT_MAX_LINES}} lines or {{DEFAULT_MAX_BYTES}}. Images return attachments, not edit anchors.
+Read files through readseek. Text output uses `LINE:HASH|content` anchors that can be copied directly into `edit`; supported images return attachments instead of anchors. Default cap: {{DEFAULT_MAX_LINES}} lines or {{DEFAULT_MAX_BYTES}}.
+
+## Choose the right read
+
+- Normal read: inspect a whole small file or a targeted `offset` / `limit` range.
+- `map: true`: append a structural map for navigation before reading more code.
+- `symbol: "Name"`: read one function, class, method, interface, type, enum, or similar symbol.
+- `bundle: "local"`: with `symbol`, include direct same-file local support when readseek can identify it.
 
 ## Parameters
 
-- `offset` / `limit` — positive line numbers for targeted reads; `offset` is 1-indexed.
-- `map: true` — append a full-file structural map even for small files. May combine with `offset` / `limit`; cannot combine with `symbol` or `bundle`.
-- `symbol: "Name"` — read one symbol range by name, with hash anchors. Supports `ClassName.method`, Java package-relative names, and `Name@<line>` disambiguation. Cannot combine with `offset` / `limit`.
-- `bundle: "local"` — with `symbol`, also include direct same-file local support when available. Cannot combine with `map`.
+- `path` — file path.
+- `offset` / `limit` — positive line numbers; `offset` is 1-indexed.
+- `map` — append the full-file structural map; cannot combine with `symbol` or `bundle`.
+- `symbol` — symbol query; supports `Class.method`, package-relative Java names, and `Name@<line>` disambiguation; cannot combine with `offset` / `limit`.
+- `bundle` — only `"local"`; requires `symbol` and cannot combine with `map`.
 
-When a full-file read is truncated, a readseek structural map is appended automatically when available. Use that map's line ranges for follow-up `read({ offset, limit })`. Map and symbol coverage depends on readseek language support.
+When a full-file read is truncated, readseek appends a structural map automatically when available. Use map line ranges for follow-up `read({ offset, limit })` calls.
 
 ## Symbol examples
 
@@ -16,18 +24,18 @@ When a full-file read is truncated, a readseek structural map is appended automa
 | `{ "symbol": "processEvent" }` | function or top-level symbol |
 | `{ "symbol": "EventEmitter" }` | class/interface/type/enum/etc. |
 | `{ "symbol": "EventEmitter.emit" }` | child method/member |
-| `{ "symbol": "Foo.bar@42" }` | specific overload/definition near line 42 |
-| `{ "symbol": "handleRequest", "bundle": "local" }` | symbol plus direct local support |
+| `{ "symbol": "Foo.bar@42" }` | overload/definition near line 42 |
+| `{ "symbol": "handleRequest", "bundle": "local" }` | symbol plus direct same-file support |
 
 ## Symbol resolution
 
-`@<line>` only applies as a trailing suffix like `Foo.bar@42`; names such as `foo@bar` are ordinary queries. Resolution order: containing range → nearest symbol starting at/after the requested line → nearest symbol above it. If unresolved but same-name candidates exist, the response lists retry hints like `name@<startLine>`.
+`@<line>` only applies as a trailing suffix like `Foo.bar@42`; names such as `foo@bar` are ordinary queries. Resolution order: containing range → nearest symbol starting at/after the requested line → nearest symbol above it.
 
 Result behavior:
+
 - **Found**: returns only the symbol range with `[Symbol: name (kind), lines X-Y of Z]`.
-- **Ambiguous**: returns candidate names/kinds/ranges; retry with dot notation or `@<line>`.
-- **Fuzzy**: returns the best camelCase/substring match with a warning banner and confirmation hint. Verify before editing from fuzzy-match anchors.
-- **Not found**: falls back to normal read with a warning listing available symbols.
-- **Unmappable**: falls back to normal read with a warning.
+- **Ambiguous**: lists candidates and retry hints such as `name@<startLine>`.
+- **Fuzzy**: returns the best camelCase/substring match with a warning; verify before editing from those anchors.
+- **Not found** or **unmappable**: falls back to normal read with a warning and, when available, symbol suggestions.
 
-Hash anchors from symbol and bundled reads are valid for `edit`.
+Hash anchors from normal, symbol, and bundled reads are valid for `edit` until the file changes.

package/prompts/sg.md

@@ -1,9 +1,9 @@
-AST-aware structural code search. Use when text search is too broad or brittle and you need code shape, such as calls, imports, declarations, or JSX. Returns matches grouped by file with edit-ready hashline anchors.
+Search code with readseek AST patterns. Use it when text search is too broad or brittle and the query depends on syntax: calls, imports, declarations, JSX, object fields, control flow, and similar code shapes. Results are grouped by file with edit-ready hashline anchors.
 
 ## Parameters
 
 - `pattern` — ast-grep-style pattern to match.
-- `lang` — language hint such as `typescript`, `tsx`, `javascript`, `jsx`, `rust`, `python`, `dockerfile`, `lua`, `nix`, `perl`, or `zig`; set it when syntax is ambiguous.
+- `lang` — language hint; set it when syntax is ambiguous, extensionless, generated, or TSX/JSX-like.
 - `path` — file or directory, default cwd.
 - `cached` — in a Git repository, search tracked/indexed files.
 - `others` — in a Git repository, search untracked files.
@@ -12,9 +12,11 @@ AST-aware structural code search. Use when text search is too broad or brittle a
 ## Pattern syntax
 
 - `$NAME` matches one AST node.
-- `$_` matches any one node.
-- `$$$ARGS` matches zero or more nodes; use `$$$` for variable-length args, body statements, object fields, JSX children, etc.
-- Reusing the same metavariable name requires each occurrence to match the same source text.
+- `$_` 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 parsed as code, not text. Formatting is mostly ignored, but syntax must be valid for the selected language. Include punctuation that the language grammar requires.
 
 ## Examples
 
@@ -23,9 +25,16 @@ AST-aware structural code search. Use when text search is too broad or brittle a
 - `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.
+
+## Languages
+
+Useful `lang` values include `assembly`, `bash`, `c`, `cpp`, `csharp`, `css`, `dockerfile`, `gdscript`, `go`, `html`, `java`, `javascript`, `json`, `jsx`, `just`, `kconfig`, `latex`, `lua`, `make`, `markdown`, `meson`, `nix`, `perl`, `php`, `puppet`, `python`, `riscv`, `ruby`, `rust`, `sql`, `swift`, `toml`, `tsx`, `typescript`, `typst`, `xml`, `yaml`, `zig`, and `unknown`.
+
+`unknown` forces text-only handling and is not useful for parser-backed search.
 
-## Tips
+## Git selection
 
-Patterns are parsed as code, not text: formatting is mostly ignored, but syntax must be valid for `lang`. Include semicolons in languages that require them. Use `grep` for plain text and `search` for structure.
+When searching a directory inside a Git repository, readseek defaults to tracked/indexed files plus untracked non-ignored files. Use `cached`, `others`, and `ignored` to narrow or expand that selection. `ignored` requires `others`.
 
-When searching a directory inside a Git repository, readseek 0.2.x defaults to tracked/indexed files plus untracked non-ignored files. Use `cached`, `others`, and `ignored` to narrow or expand that Git selection.
+Use `grep` for plain text and `search` for structure.

package/prompts/write.md

@@ -1,24 +1,24 @@
-Write full file content. Creates new files and parent directories, overwrites existing files, and returns `LINE:HASH` anchors for immediate `edit` use.
+Create or overwrite a whole file and return `LINE:HASH` anchors for immediate follow-up `edit` calls.
 
 ## Use / avoid
 
-Use `write` to create a file or intentionally replace a whole file. For small changes or appends, `read` first and use `edit` (`insert_after` for appends).
+Use `write` for new files, generated files, or intentional full-file replacement. For small changes or appends to an existing file, read or search first and use `edit` (`insert_after` for appends).
 
-Existing files are overwritten without confirmation. Binary-looking content is written, but hashlines are not generated, so there are no anchors to feed into `edit`.
+Existing files are overwritten without confirmation. Binary-looking content can be written, but hashlines are not generated, so there are no anchors for `edit`.
 
 ## Parameters
 
 - `path` — relative or absolute file path.
 - `content` — complete file contents.
-- `map` — optional; append a structural map when possible. Map append is best-effort and write still succeeds if map generation fails.
+- `map` — optional; append a structural map when possible. Map generation is best-effort and does not make the write fail.
 
 ## Output
 
-Successful text writes return `LINE:HASH|content`; display hashlines escape control characters for safe rendering. Visible output is capped at 2000 lines or 50 KB, but full anchors remain available in `readseekValue`.
+Successful text writes return `LINE:HASH|content`. Display hashlines escape control characters for safe rendering. Visible output is capped at 2000 lines or 50 KB, but full anchors remain available in `readseekValue`.
 
 ## Diff data contract
 
-Successful text `write` results include additive final `details.diff`, `details.readseekValue.diff`, `details.diffData`, and `details.readseekValue.diffData` fields. The string fields remain the backward-compatible human-readable fallback.
+Successful text `write` results include additive final `details.diff`, `details.readseekValue.diff`, `details.diffData`, and `details.readseekValue.diffData` fields. String diff fields remain the backward-compatible human-readable fallback.
 
 `diffData` is a stable versioned contract:
 
@@ -43,4 +43,4 @@ type DiffData = {
 };
 ```
 
-For compact one-line hashline diffs, `details.diff` remains compact, while `diffData.entries` uses expanded remove/add rows so renderers can show inline word changes without breaking hashline output.
+For compact one-line hashline diffs, `details.diff` remains compact while `diffData.entries` uses expanded remove/add rows so renderers can show inline word changes without breaking hashline output.

package/src/readseek/mapper.ts

@@ -5,7 +5,7 @@ import { THRESHOLDS } from "./constants.js";
 import type { FileMap, MapOptions } from "./types.js";
 
 export const READSEEK_MAPPER_NAME = "readseek";
-export const READSEEK_MAPPER_VERSION = 1;
+export const READSEEK_MAPPER_VERSION = 2;
 
 export interface MapperIdentity {
   mapperName: string;
@@ -38,7 +38,7 @@ export async function generateMapWithIdentity(
   throwIfAborted(options.signal);
   const fileStat = await stat(filePath);
   throwIfAborted(options.signal);
-  const map = await readseekMap(filePath, fileStat.size);
+  const map = await readseekMap(filePath, fileStat.size, { signal: options.signal });
   throwIfAborted(options.signal);
   return { map, ...READSEEK_MAPPER_IDENTITY };
 }
@@ -56,7 +56,7 @@ export async function generateMapFromContent(
   options: MapOptions = {},
 ): Promise<FileMap | null> {
   throwIfAborted(options.signal);
-  const map = await readseekMapContent(filePath, content);
+  const map = await readseekMapContent(filePath, content, { signal: options.signal });
   throwIfAborted(options.signal);
   return map;
 }

package/src/readseek-client.ts

@@ -1,7 +1,5 @@
-import { spawn } from "node:child_process";
+import { spawn, type StdioOptions } from "node:child_process";
 import { createRequire } from "node:module";
-import { mkdtemp, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
 import path from "node:path";
 
 import { DetailLevel } from "./readseek/enums.js";
@@ -27,7 +25,7 @@ export interface ReadseekReadOutput {
 interface ReadseekSymbol {
 	kind: string;
 	name: string;
-	address: string;
+	qualified_name: string;
 	start_line: number;
 	end_line: number;
 	start_hash: string;
@@ -90,34 +88,41 @@ function normalizeKind(kind: string): FileSymbol["kind"] {
 	return SymbolKind.Unknown;
 }
 
+function parentQualifiedNameFor(qualifiedName: string): string {
+	const lastDot = qualifiedName.lastIndexOf(".");
+	return lastDot === -1 ? "" : qualifiedName.slice(0, lastDot);
+}
+
 function symbolsFromReadseek(symbols: ReadseekSymbol[]): FileSymbol[] {
-	const byAddress = new Map<string, FileSymbol[]>();
-	const entries: Array<{ address: string; parentAddress: string; symbol: FileSymbol }> = [];
+	const symbolsByQualifiedName = new Map<string, FileSymbol[]>();
+	const entries: Array<{ parentQualifiedName: string; symbol: FileSymbol }> = [];
 
 	for (const symbol of symbols) {
-		const address = symbol.address || symbol.name;
-		const parentAddress = address.includes(".") ? address.slice(0, address.lastIndexOf(".")) : "";
+		const parentQualifiedName = parentQualifiedNameFor(symbol.qualified_name);
 		const fileSymbol: FileSymbol = {
 			name: symbol.name,
 			kind: normalizeKind(symbol.kind),
 			startLine: symbol.start_line,
 			endLine: symbol.end_line,
 		};
-		const bucket = byAddress.get(address);
+		const bucket = symbolsByQualifiedName.get(symbol.qualified_name);
 		if (bucket) bucket.push(fileSymbol);
-		else byAddress.set(address, [fileSymbol]);
-		entries.push({ address, parentAddress, symbol: fileSymbol });
+		else symbolsByQualifiedName.set(symbol.qualified_name, [fileSymbol]);
+		entries.push({ parentQualifiedName, symbol: fileSymbol });
 	}
 
 	const roots: FileSymbol[] = [];
 	for (const entry of entries) {
-		const parent = entry.parentAddress ? byAddress.get(entry.parentAddress)?.[0] : undefined;
-		if (parent) {
-			parent.children ??= [];
-			parent.children.push(entry.symbol);
-		} else {
+		const parent = entry.parentQualifiedName
+			? symbolsByQualifiedName.get(entry.parentQualifiedName)?.[0]
+			: undefined;
+		if (!parent) {
 			roots.push(entry.symbol);
+			continue;
 		}
+
+		parent.children ??= [];
+		parent.children.push(entry.symbol);
 	}
 
 	return roots;
@@ -156,14 +161,29 @@ export function isReadseekAvailable(): boolean {
 	}
 }
 
-async function runReadseek(args: string[], options: { signal?: AbortSignal } = {}): Promise<unknown> {
-	const { stdout, stderr } = await new Promise<{ stdout: string; stderr: string }>((resolve, reject) => {
-		const child = spawn(readseekBinaryPath(), args, { stdio: ["ignore", "pipe", "pipe"], signal: options.signal });
+interface RunReadseekOptions {
+	signal?: AbortSignal;
+	stdin?: string;
+}
+
+async function runReadseek(args: string[], options: RunReadseekOptions = {}): Promise<unknown> {
+	const stdout = await new Promise<string>((resolve, reject) => {
+		const stdin = options.stdin;
+		const stdio: StdioOptions = [stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"];
+		const child = spawn(readseekBinaryPath(), args, { stdio, signal: options.signal });
+		const childStdout = child.stdout;
+		const childStderr = child.stderr;
+		const childStdin = child.stdin;
+		if (!childStdout || !childStderr) {
+			child.kill();
+			reject(new Error("readseek stdio streams are unavailable"));
+			return;
+		}
 		const stdoutChunks: Buffer[] = [];
 		const stderrChunks: Buffer[] = [];
 		let stdoutBytes = 0;
 
-		child.stdout.on("data", (chunk: Buffer) => {
+		childStdout.on("data", (chunk: Buffer) => {
 			stdoutBytes += chunk.length;
 			if (stdoutBytes > 32 * 1024 * 1024) {
 				child.kill();
@@ -172,16 +192,26 @@ async function runReadseek(args: string[], options: { signal?: AbortSignal } = {
 			}
 			stdoutChunks.push(chunk);
 		});
-		child.stderr.on("data", (chunk: Buffer) => stderrChunks.push(chunk));
+		childStderr.on("data", (chunk: Buffer) => stderrChunks.push(chunk));
 		child.on("error", (error: any) => reject(error));
+		if (stdin !== undefined) {
+			if (!childStdin) {
+				child.kill();
+				reject(new Error("readseek stdin stream is unavailable"));
+				return;
+			}
+			childStdin.on("error", (error: any) => {
+				if (error?.code !== "EPIPE") reject(error);
+			});
+			childStdin.end(stdin, "utf-8");
+		}
 		child.on("close", (code) => {
 			const stdout = Buffer.concat(stdoutChunks).toString("utf-8");
 			const stderr = Buffer.concat(stderrChunks).toString("utf-8").trim();
-			if (code === 0) resolve({ stdout, stderr });
+			if (code === 0) resolve(stdout);
 			else reject(new Error((stderr || `readseek exited with status ${code}`).replace(/^error:\s*/i, "")));
 		});
 	});
-	void stderr;
 	return JSON.parse(stdout) as unknown;
 }
 
@@ -235,7 +265,7 @@ function parseMapOutput(value: unknown): ReadseekMapOutput {
 			return {
 				kind: requireString(item.kind, "symbol.kind"),
 				name: requireString(item.name, "symbol.name"),
-				address: requireString(item.address, "symbol.address"),
+				qualified_name: requireString(item.qualified_name, "symbol.qualified_name"),
 				start_line: requireNumber(item.start_line, "symbol.start_line"),
 				end_line: requireNumber(item.end_line, "symbol.end_line"),
 				start_hash: requireString(item.start_hash, "symbol.start_hash"),
@@ -308,8 +338,7 @@ export async function readseekRead(filePath: string, startLine?: number, endLine
 	return parseReadOutput(await runReadseek(args));
 }
 
-export async function readseekMap(filePath: string, totalBytes: number): Promise<FileMap | null> {
-	const output = parseMapOutput(await runReadseek(["map", filePath]));
+function fileMapFromReadseekOutput(output: ReadseekMapOutput, filePath: string, totalBytes: number): FileMap | null {
 	if (output.language === "unknown" && output.symbols.length === 0) return null;
 	return {
 		path: filePath,
@@ -322,6 +351,15 @@ export async function readseekMap(filePath: string, totalBytes: number): Promise
 	};
 }
 
+export async function readseekMap(
+	filePath: string,
+	totalBytes: number,
+	options: { signal?: AbortSignal } = {},
+): Promise<FileMap | null> {
+	const output = parseMapOutput(await runReadseek(["map", filePath], { signal: options.signal }));
+	return fileMapFromReadseekOutput(output, filePath, totalBytes);
+}
+
 export async function readseekSearch(
 	target: string,
 	pattern: string,
@@ -335,15 +373,13 @@ export async function readseekSearch(
 	return parseSearchOutput(await runReadseek(args, { signal: options.signal })).results;
 }
 
-export async function readseekMapContent(filePath: string, content: string): Promise<FileMap | null> {
-	const tempDir = await mkdtemp(path.join(tmpdir(), "readseek-map-"));
-	const tempPath = path.join(tempDir, path.basename(filePath) || `content${path.extname(filePath)}` || "content");
-	try {
-		await writeFile(tempPath, content, "utf8");
-		const map = await readseekMap(tempPath, Buffer.byteLength(content, "utf8"));
-		if (!map) return null;
-		return { ...map, path: filePath };
-	} finally {
-		await rm(tempDir, { recursive: true, force: true });
-	}
+export async function readseekMapContent(
+	filePath: string,
+	content: string,
+	options: { signal?: AbortSignal } = {},
+): Promise<FileMap | null> {
+	const output = parseMapOutput(
+		await runReadseek(["map", "--stdin", "--path", filePath], { signal: options.signal, stdin: content }),
+	);
+	return fileMapFromReadseekOutput(output, filePath, Buffer.byteLength(content, "utf8"));
 }

package/src/tool-prompt-metadata.ts

@@ -5,37 +5,39 @@ const COMPACT_DESCRIPTIONS: Record<string, string> = {
   "read.md": "Read text files/images by path; text has LINE:HASH anchors, images return attachments.",
   "edit.md": "Edit existing text files using fresh LINE:HASH anchors from read, grep, search, or write.",
   "grep.md": "Search file contents; non-summary results include LINE:HASH anchors for edits.",
-  "find.md": "Find files by glob, respecting .gitignore.",
-  "ls.md": "List one directory.",
-  "write.md": "Create or overwrite a file and return anchors.",
+  "find.md": "Find files recursively by basename glob, respecting .gitignore.",
+  "ls.md": "List one directory with directories first and dotfiles included.",
+  "write.md": "Create or overwrite a complete file and return anchors.",
   "sg.md": "Search code by AST pattern and return anchored matches.",
 };
 
 const COMPACT_GUIDELINES: Record<string, string[]> = {
   "read.md": [
     "Use read for file contents, images/screenshots, ranges, symbols, and edit anchors.",
+    "Use map or symbol mode before pulling large code files into context.",
     "Use read for images; it returns attachments, so avoid OCR tools unless explicitly needed.",
   ],
   "edit.md": [
     "Use edit with fresh LINE:HASH anchors for existing files.",
-    "Use edit replace only when anchored edits are impractical.",
+    "Prefer set_line, replace_lines, and insert_after; use replace only when anchors are impractical.",
   ],
   "grep.md": [
     "Use grep for text search and edit-ready matching anchors.",
-    "Use grep summary mode when only file counts are needed.",
+    "Use grep summary mode for broad count/file discovery before narrowing.",
   ],
   "find.md": [
-    "Use find for recursive file discovery by glob.",
+    "Use find for recursive file discovery by basename glob.",
   ],
   "ls.md": [
-    "Use ls to list one directory, optionally with a glob filter.",
+    "Use ls to inspect one directory; use find for recursion.",
   ],
   "write.md": [
     "Use write to create files or intentionally overwrite whole files.",
-    "Use edit rather than write for small changes to existing files.",
+    "Use edit rather than write for small changes or appends to existing files.",
   ],
   "sg.md": [
     "Use search for AST-shaped code patterns.",
+    "Use grep instead of search for plain text.",
   ],
 };