opencode-readseek 0.10.6 → 0.11.0

package/README.md

@@ -13,12 +13,28 @@ For OpenCode with the legacy server plugin API, add the plugin to `opencode.json
 }
 ```
 
-OpenCode V2 can load the same package using `"plugins": ["opencode-readseek"]`.
-The V2 entrypoint supplies a ReadSeek skill and agent guidance, but OpenCode V2
-currently has no plugin API for registering custom tools. The `readseek_*` tools
-listed below require the legacy server plugin API. To use the V2 skill without
-those tools, install `@jarkkojs/readseek` globally so `readseek` is on PATH;
-otherwise use OpenCode's built-in tools.
+For OpenCode V2, install the package locally:
+
+```sh
+npm install --save-dev opencode-readseek
+```
+
+Then select the isolated entrypoint in your project's `opencode.json`:
+
+```json
+{
+  "plugins": ["./node_modules/opencode-readseek/dist/v2.js"]
+}
+```
+
+Local plugin modules can also import the default export from `opencode-readseek/v2`.
+This entrypoint does not load the legacy tool implementation. The existing
+`opencode-readseek` and `opencode-readseek/server` entrypoints remain unchanged.
+
+The V2 entrypoint supplies a ReadSeek skill and agent guidance only; it does not
+register custom tools. The `readseek_*` tools listed below require the legacy
+server plugin API. To use the V2 skill, install `@jarkkojs/readseek` globally so
+`readseek` is on PATH; otherwise use OpenCode's built-in tools.
 
 The plugin uses the AppImage on Linux (without FUSE) and native executables on
 macOS/Windows supplied by `@jarkkojs/readseek`. Set
@@ -26,9 +42,46 @@ macOS/Windows supplied by `@jarkkojs/readseek`. Set
 
 ## Tools
 
-`readseek_inspect`, `readseek_extract`, `readseek_edit`, `readseek_write`,
-`readseek_grep`, `readseek_search`, `readseek_def`, `readseek_refs`, and
-`readseek_rename`.
+- Read without inference: `readseek_show_content`, `readseek_show_structure`,
+  `readseek_show_metadata`, `readseek_show_assets`.
+- Check: `readseek_check_syntax`, `readseek_check_rules`.
+- Explicit inference: `readseek_generate_caption`, `readseek_detect_objects`,
+  `readseek_recognize_text`.
+- Find: `readseek_find_text`, `readseek_find_nodes`, `readseek_find_definitions`,
+  `readseek_find_references`.
+- Mutate: `readseek_edit_text`, `readseek_rename_symbol`, `readseek_write_file`.
+
+Tool names mirror native verb-object commands, such as `show content`,
+`find nodes`, and `edit text`. Paths resolve against the project directory.
+Use `at` selectors (`line:N[:COLUMN]`, `hash:H[:COLUMN]`, `symbol:NAME`,
+`page:N`, `node:ID`, or `asset:ID`) where supported. Structure defaults to
+`depth: 1`. Use separate structure, metadata, and syntax tools rather than
+combining facets in a content request.
+
+`readseek_find_nodes` accepts `pattern`, `context` with `selector`, or `rule`.
+`readseek_find_references` requires exactly one of `name` or `at`; binding
+references and renames use line or hash cursors. KDL selection/check rules
+may be inline or `@path`; tool calls cannot supply standard input.
+
+`readseek_find_text` accepts exactly one of literal `text` or regex `pattern`.
+The adapter also supports `literal`, `ignoreCase`, `glob`, `context`, `limit`,
+and per-file `summary`. Native `find text --text` searches literally.
+
+Read fresh `LINE:HASH` anchors before editing. Each edit item contains exactly
+one nested `set_line`, `replace_lines`, `insert_after`, `replace_symbol`, or
+`replace` object. Edits and renames default to applying after a verified plan
+and edit permission; use `apply: false` to preview and `planHash` to require
+that plan when applying. `write_file` replaces complete text files.
+
+Syntax and rule checks treat exit 1 as findings, not transport failure;
+exit 0 is clean and exit 2 is failure. Syntax checks do not typecheck.
+
+Assets auto-materialize into the cache. Content and asset tools return usable
+cached paths and attach images according to `imageMode`; there is no extract
+command or asset output-path parameter. Inference is only requested through
+the explicit inference tools (`level: low|medium|high`, default `low`). Caption
+`include` may request `text` and/or `objects`. Models must already be installed;
+reading never silently invokes OCR or downloads a model.
 
 To control image handling:
 
@@ -43,12 +96,15 @@ To control image handling:
 ## Development
 
 ```sh
-bun install
 bun test
-bun run typecheck
+npm run build
+npm run typecheck
 ```
 
 
+For real-binary checks, set `READSEEK_BINARY` to the built native executable,
+for example `/absolute/path/to/packages/readseek/build/readseek`.
+
 ## Licensing
 
 `opencode-readseek` is licensed under the Apache 2.0 license. See [LICENSE](LICENSE)