pi-readseek 0.8.23 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readseek",
-  "version": "0.8.23",
+  "version": "0.9.0",
   "description": "Pi extension for LINE:HASH-anchored file operations and structural code navigation",
   "type": "module",
   "exports": {
@@ -40,7 +40,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@jarkkojs/readseek": "^0.8.23",
+    "@jarkkojs/readseek": "^0.9.0",
     "diff": "^9.0.0",
     "xxhash-wasm": "^1.1.0"
   },

package/prompts/def.md

@@ -8,4 +8,7 @@ Go to a symbol definition or declaration by name. Accepts qualified or unqualifi
 - `cached`, `others`, `ignored` — Git file selection; `ignored` requires
   `others`.
 
-After `readSeek_hover`, use `identifier.text` for the token under the cursor. Use `symbol.qualified_name` only when intentionally navigating to the enclosing declaration.
+After `readSeek_digest` with `select: "identity"`, use
+`identity.identifier.text` for the token under the cursor. Use
+`identity.symbol.qualified_name` only when intentionally navigating to the
+enclosing declaration.

package/prompts/digest.md

@@ -0,0 +1,37 @@
+Digest source content and images into the native CLI envelope. Returns `metadata` plus requested facets unchanged from `readseek digest`.
+
+Use this instead of separate hover/check/map tools: identity at a cursor,
+diagnostics after edits, or a structural map.
+
+## Parameters
+
+- `path` — file path.
+- `select` — facets: `metadata`, `content`, `map`, `diagnostics`, `identity`.
+  Accepts one facet, an array, or a comma-separated string. Default `content`.
+- `at` — location: `line:N[:COLUMN]`, `hash:HASH[:COLUMN]`, or `symbol:NAME`.
+- `end` — last line to include (with content).
+- `limit` — maximum lines to include (with content).
+- `language` — language override when detection is ambiguous.
+- `visionMode` — standalone image mode: `none`, `all`, `ocr`, `caption`, or
+  `objects`.
+- `visionLevel` — vision inference level: `low` (default), `medium`, or `high`;
+  requires `visionMode`.
+
+## Facets
+
+| select         | Purpose                                              |
+| -------------- | ---------------------------------------------------- |
+| `metadata`     | File kind, language, and engine                      |
+| `content`      | Anchored text or prepared/analyzed image payload     |
+| `map`          | Structural symbol outline                            |
+| `diagnostics`  | Parser errors and missing syntax nodes               |
+| `identity`     | Token and enclosing symbol at `at`                   |
+
+Combine facets with a comma or array, e.g. `map,diagnostics` or
+`["identity"]` with `at: "line:12:4"`.
+
+## Output
+
+Text content is the native JSON envelope. `details.readSeekValue.envelope`
+holds the same object. `metadata` is always present; other keys appear only
+when selected.

package/prompts/edit.md

@@ -5,13 +5,13 @@ Anchors come from `readSeek_read`, `readSeek_grep`, `readSeek_search`,
 
 ## Variants
 
-| 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 |
+| 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                          |
 
 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`
@@ -37,26 +37,19 @@ plain file content, not a diff or hashline output.
 }
 ```
 
-## Exact, fuzzy, and symbol replacement
+## Exact and symbol 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` requires exact text. It fails when the text is absent or appears more
+than once unless `all: true` is set.
 
-`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` accepts `Name`, a qualified name such as `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.
 
 ## Stale anchors and validation
 
-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 automatic relocation
-warning.
+A stale-anchor response reports the current hash for the requested line. Read or
+search again before retrying.
 
 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

package/prompts/read.md

@@ -1,9 +1,8 @@
-Read anchored text by range, symbol, or map. Standalone images require an explicit mode; PDF text is always returned.
+Read anchored text by range or symbol. Standalone images require an explicit mode. Use `readSeek_view` for documents (PDF first). Use `readSeek_digest` with `select: "map"` for a structural outline.
 
 ## Choose a read
 
 - 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 directly related symbols from the same file.
 
@@ -11,32 +10,29 @@ Read anchored text by range, symbol, or map. Standalone images require an explic
 
 - `path` — file path.
 - `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` — standalone-image/PDF embedded-image mode; unavailable when
-  `imageMode` is `"off"`.
-- `page` — one-based PDF page; defaults to 1 and excludes `offset` / `limit`.
+- `bundle` — only `"local"`; requires `symbol`.
+- `image` — standalone-image mode; unavailable when `imageMode` is `"off"`.
 
 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.
+prepared standalone image without local analysis. Documents (PDF first) are not
+readable through this tool — use `readSeek_view` for structure, content, and
+optional asset vision.
 
 ## 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 |
+| 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

package/prompts/refs.md

@@ -1,4 +1,4 @@
-Find references or usages of an identifier by name or cursor binding. Results include enclosing symbols and edit-ready `LINE:HASH` anchors. Without cursor scope, results are identifier-name matches; with scope, they follow one binding and exclude shadows. Use text search for literal occurrences in strings or comments, and use this tool before renaming or deleting a symbol.
+Find references or usages of an identifier by name or cursor binding. Results include enclosing symbols and line hashes usable as `LINE:HASH` anchors. Without cursor scope, results are identifier-name matches; with scope, they follow one binding and exclude shadows. Use text search for literal occurrences in strings or comments, and use this tool before renaming or deleting a symbol.
 
 ## Parameters
 
@@ -8,13 +8,12 @@ Find references or usages of an identifier by name or cursor binding. Results in
 - `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`.
+- `column` — optional one-based cursor byte column for disambiguation; 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`.
 
-Without `scope`, results match by name. With `scope`, results follow the cursor
-binding and exclude shadows.
 
 In a Git work tree, directory search includes tracked/indexed and untracked
 non-ignored files by default. Setting `cached` or `others` restricts the set;

package/prompts/rename.md

@@ -4,7 +4,7 @@ Rename a symbol at a source location. Resolvable same-named bindings are preserv
 
 - `path` — source file containing the cursor.
 - `line` — one-based cursor line.
-- `column` — optional one-based cursor byte column.
+- `column` — optional one-based cursor byte column for disambiguation.
 - `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.

package/prompts/search.md

@@ -1,4 +1,4 @@
-Search code by AST structure using ast-grep-style patterns. Results include edit-ready `LINE:HASH` anchors. Use `readSeek_grep` for identifiers, strings, comments, configuration, documentation, or other plain text and regex.
+Search code by AST structure using ast-grep-style patterns. Results include line hashes usable as `LINE:HASH` anchors. Use `readSeek_grep` for identifiers, strings, comments, configuration, documentation, or other plain text and regex.
 
 ## Parameters
 

package/prompts/view.md

@@ -1,14 +1,18 @@
-Inspect a PDF's structure or selected content. Start with the overview, then narrow by page, node, kind, or depth instead of reading the whole document.
+Digest a document's structure or selected content. Start with the overview, then narrow by page, node, kind, or depth instead of reading the whole document. PDF is the first supported document format.
 
 ## Parameters
 
-- `path` — PDF file.
+- `path` — document file (PDF first).
 - `node` — node ID to use as the view root.
-- `page` — one-based PDF page.
+- `page` — one-based source page.
 - `kind` — node kind filter.
 - `depth` — maximum depth below selected roots.
 - `outline` — return outline nodes only.
+- `visionMode` — analyze selected assets: `all`, `ocr`, `caption`, or `objects`.
+- `visionLevel` — vision inference level: `low` (default), `medium`, or `high`;
+  requires `visionMode`.
 
-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.
+The Pi integration creates and reuses its document cache automatically. The
+first call builds a structural index. Output is a bounded text projection with
+stable node IDs and source-page references. Optional vision analysis is appended
+for selected assets.

package/prompts/write.md

@@ -7,7 +7,6 @@ rejected before writing.
 
 - `path` — file path.
 - `content` — complete file content.
-- `map` — append a best-effort structural map.
 
 ## Output
 

package/prompts/check.md

@@ -1,10 +0,0 @@
-Check a source file for parser errors or missing syntax after edits. Validation requires a supported tree-sitter language; files without a supported parser are not checked. This is not a compiler, type checker, test runner, or linter.
-
-## Parameters
-
-- `path` — source file.
-
-## Output
-
-Returns parser error and missing-node counts with affected line ranges.
-Files without a supported parser are not validated.

package/prompts/hover.md

@@ -1,7 +0,0 @@
-Inspect the symbol at a source location. This identifies the token and enclosing symbol; use it before definition lookup or binding-specific references.
-
-## Parameters
-
-- `path` — source file.
-- `line` — one-based cursor line.
-- `column` — optional one-based cursor byte column.