pi-readseek 0.11.4 → 0.12.1

package/package.json

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

package/prompts/assets.md

@@ -0,0 +1,6 @@
+Return selected document asset descriptors with usable cached paths and attach images from those paths.
+
+## Parameters
+
+- `path` — document file.
+- `at` — optional document selector: `N`, `page:N`, `node:ID`, or `asset:ID`.

package/prompts/{find_definitions.md → def.md}

@@ -8,7 +8,7 @@ Go to a symbol definition or declaration by name. Accepts qualified or unqualifi
 - `gitScope` — in a Git repository, which files to search: `tracked`, `untracked`,
   `ignored` (untracked plus ignored), or `all`. Defaults to tracked plus untracked.
 
-After `readSeek_show_content` with `select: "identity"`, use
-`identity.identifier.text` for the token under the cursor. Use
-`identity.symbol.qualified_name` only when intentionally navigating to the
+After `readSeek_show` with `at: "N:COLUMN"` (or `"line:N:COLUMN"`), use
+`cursor.identifier.text` for the token under the cursor. Use
+`cursor.symbol.qualified_name` only when intentionally navigating to the
 enclosing declaration.

package/prompts/{edit_text.md → edit.md}

@@ -1,7 +1,7 @@
 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_show_content`, `readSeek_find_text`, `readSeek_find_nodes`,
-`readSeek_find_references`, `readSeek_find_definitions`, or `readSeek_write_file`.
+Anchors come from `readSeek_show`, `readSeek_grep`, `readSeek_search`,
+`readSeek_refs`, `readSeek_def`, or `readSeek_write`.
 
 ## Variants
 

package/prompts/{find_text.md → grep.md}

@@ -1,4 +1,4 @@
-Search text or regex in files and return edit-ready `LINE:HASH` anchors. Use for identifiers, strings, configuration, errors, comments, and documentation.
+Search text or regex with native ReadSeek. Source results return edit-ready `LINE:HASH` anchors; document results return `node:`/`page:` selectors, not editable anchors.
 
 ## Modes
 
@@ -13,15 +13,16 @@ Search text or regex in files and return edit-ready `LINE:HASH` anchors. Use for
 
 ## Parameters
 
-- `pattern` — regular expression by default; set `literal: true` for exact text.
+- `pattern` — UTF-8 RE2 regular expression by default; set `literal: true` for exact text. Lookaround and backreferences are not supported.
 - `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 in normal mode.
-- `limit` — maximum matches; defaults to 100.
+- `limit` — maximum matching lines (not occurrences); positive, defaults to 100.
 - `summary` — return counts without anchors.
 - `scope` — only `"symbol"` is supported.
-- `scopeContext` — non-negative context inside symbol scope.
+- `scopeContext` — non-negative context inside symbol scope; requires `scope: "symbol"`.
+- `gitScope` — `tracked`, `untracked`, `ignored`, or `all`; defaults to tracked plus untracked files.
 
 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/refs.md

@@ -0,0 +1,10 @@
+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 `at`, results are identifier-name matches; with `at`, 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
+
+- `name` — identifier to find; required unless `at` is set.
+- `at` — cursor binding selector (`N[:COLUMN]`, `H[:COLUMN]`, `line:N[:COLUMN]`, or `hash:H[:COLUMN]`); mutually exclusive with `name`.
+- `path` — file or directory; defaults to the current directory.
+- `language` — language override for ambiguous, extensionless, or generated source.
+- `gitScope` — in a Git repository, which files to search: `tracked`, `untracked`,
+  `ignored` (untracked plus ignored), or `all`. Defaults to tracked plus untracked.

package/prompts/{rename_symbol.md → rename.md}

@@ -3,8 +3,7 @@ Rename a symbol at a source location. Resolvable same-named bindings are preserv
 ## Parameters
 
 - `path` — source file containing the cursor.
-- `line` — one-based cursor line.
-- `column` — optional one-based cursor byte column for disambiguation.
+- `at` — cursor location selector (`N[:COLUMN]`, `H[:COLUMN]`, `line:N[:COLUMN]`, or `hash:H[:COLUMN]`).
 - `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/{find_nodes.md → search.md}

@@ -1,10 +1,12 @@
-Search code by AST structure using ast-grep-style patterns. Results include line hashes usable as `LINE:HASH` anchors. Use `readSeek_find_text` for identifiers, strings, comments, configuration, documentation, or other plain text and regex.
+Search code by AST structure using ast-grep-style patterns or KDL selection rules. 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
 
 - `pattern` — AST pattern to match.
 - `context` — surrounding code context for sub-statement patterns (used with `selector`).
 - `selector` — target AST node kind to extract from pattern context.
+- `rule` — KDL node selection rule, `@path`, or `'-'` for standard input.
+- `limit` — maximum matches to return.
 - `path` — file or directory; defaults to the current directory.
 - `language` — language override for ambiguous, extensionless, generated, or
   JSX-like source.

package/prompts/show.md

@@ -0,0 +1,16 @@
+Read source content, document content, or image descriptors without inference.
+
+Obtain fresh `LINE:HASH` anchors before edits; pass `at` with a column (`N:COLUMN` or `line:N:COLUMN`) for cursor context. Document results include typed nodes and cached asset paths.
+
+## Parameters
+
+- `path` — source, image, or document path.
+- `at` — optional selector: `N[:COLUMN]`, `START-END`, `H[:COLUMN]`, `NAME`, `line:N[:COLUMN]`, `hash:H[:COLUMN]`, `symbol:NAME`, `page:N`, `node:ID`, or `asset:ID`.
+- `end` — last source line to include.
+- `limit` — maximum source lines to include; cannot be combined with `end`.
+- `language` — source-language override when detection is ambiguous.
+- `noAnchors` — omit source line anchors.
+
+## PDF workflow
+
+Read a PDF with `readSeek_tree` or `readSeek_show`, then narrow with `at: "page:N"` (or `"N"`), `at: "node:ID"`, or `at: "asset:ID"`. Selected assets are cached automatically with local paths.

package/prompts/find_references.md

@@ -1,14 +0,0 @@
-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
-
-- `name` — identifier to find; required unless `scope` is set with `line`.
-- `path` — file or directory; defaults to the current directory.
-- `language` — language override for ambiguous, extensionless, or generated source.
-- `scope` — restrict results to the binding at `line` / `column` in one file;
-  requires `line`. `name` is optional when scoped.
-- `line` — one-based cursor line used with `scope`.
-- `column` — optional one-based cursor byte column for disambiguation; used with
-  `scope`. Cursor fields require `scope`.
-- `gitScope` — in a Git repository, which files to search: `tracked`, `untracked`,
-  `ignored` (untracked plus ignored), or `all`. Defaults to tracked plus untracked.

package/prompts/show_assets.md

@@ -1,11 +0,0 @@
-Extract one document asset selected by a stable `asset:ID` into a destination file.
-
-Call `readSeek_show_content` on the document first to discover asset IDs. This tool writes binary data directly to disk and never returns those bytes through tool output.
-
-## Parameters
-
-- `path` — document file.
-- `selector` — required asset selector in the form `asset:ID`.
-- `output` — destination file path. `-` and stdout are not supported.
-
-The result is a short receipt containing the resolved source, selector, and destination paths.

package/prompts/show_content.md

@@ -1,34 +0,0 @@
-Inspect source content, standalone images, and documents through the native CLI envelope.
-
-Use this for anchored source content, diagnostics, cursor identity, shallow structural maps, and document structure. Prefer `def`, `refs`, or `search` when the question targets a source symbol.
-
-## Parameters
-
-- `path` — source, image, or document path.
-- `selector` — one positional selector: `line:N[:COLUMN]`, `hash:HASH[:COLUMN]`, `symbol:NAME`, `page:N`, `node:ID`, or `asset:ID`.
-- `select` — source facets: `metadata`, `content`, `map`, `diagnostics`, `identity`. Accepts one facet, an array, or comma-separated facets. Default `content`.
-- `query` — document KDL selection query, such as `select selector="page:2" kind="heading" depth=2`; cannot be combined with `selector`.
-- `end` — last source line to include.
-- `limit` — maximum source lines to include; cannot be combined with `end`.
-- `depth` — maximum structural depth for a source `map`; agent tools default to `1`.
-- `language` — source-language override when detection is ambiguous.
-- `visionMode` — standalone image analysis: `none`, `all`, `ocr`, `caption`, or `objects`.
-- `visionLevel` — vision inference level: `low` (default), `medium`, or `high`; requires an analysis `visionMode`.
-
-## Source facets
-
-| select | Purpose |
-| --- | --- |
-| `metadata` | File kind, language, and engine |
-| `content` | Anchored text or prepared/analyzed image payload |
-| `map` | Structural outline; start shallow and deepen as needed |
-| `diagnostics` | Parser errors and missing syntax nodes |
-| `identity` | Token and enclosing symbol at `selector` |
-
-## PDF workflow
-
-Inspect a PDF without a selector first. The result contains stable page, node, and asset IDs. Narrow with `page:N`, `node:ID`, or a KDL `query`. Use `readSeek_show_assets` only when the binary bytes of an `asset:ID` must be saved.
-
-## Output
-
-The decoded native KDL envelope is rendered as JSON and retained in `details.readSeekValue.envelope`. Source facets appear only when requested; PDF output contains document properties, nodes, assets, and optional vision results.