@jarkkojs/readseek-api 0.11.3 → 0.12.0

package/README.md

@@ -21,7 +21,7 @@ platform binary; plugins declare both packages directly.
 
 ```ts
 import {
-  buildShowStructureArgs,
+  buildTreeArgs,
   resolveReadSeekBinaryFromPackages,
   resolveReadSeekBinaryOverride,
   runReadSeekNodeKdl,
@@ -29,14 +29,13 @@ import {
 
 const binary =
   resolveReadSeekBinaryOverride() ?? resolveReadSeekBinaryFromPackages();
-const args = buildShowStructureArgs({ path: "src/index.ts", depth: 2 });
+const args = buildTreeArgs({ path: "src/index.ts", depth: 2 });
 const result = await runReadSeekNodeKdl(binary, args);
 ```
 
-The API follows the CLI's verb–object grammar: `showContent`, `showStructure`,
-`showMetadata`, `showAssets`, `findNodes`, `findText`, `findDefinitions`,
-`findReferences`, `checkSyntax`, `checkRules`, `generateCaption`, `detectObjects`,
-`recognizeText`, `editText`, and `renameSymbol`. Selection uses `at`.
+The API follows the CLI's single-word command grammar: `show`, `tree`,
+`meta`, `assets`, `search`, `grep`, `def`, `refs`, `syntax`, `check`,
+`caption`, `objects`, `ocr`, `edit`, and `rename`. Selection uses `at`.
 
 Document content and asset results include usable cached image paths. There is no
 separate extraction step or destination argument. Cache population is an internal
@@ -44,14 +43,13 @@ write; reading never invokes inference. Syntax checks return diagnostics even
 when the native process exits 1 (findings); exit 2 is a failure.
 
 `presentShowResult()` and `formatShowResult()` provide shared readable output for
-`show_content`, `show_structure`, `show_metadata`, and `show_assets`. Summaries
+`show`, `tree`, `meta`, and `assets`. Summaries
 identify selections and counts; bodies contain anchored lines, document sections,
 structure trees, fields, or asset paths. Notices identify omitted source ranges
 and how to continue. Formatting never mutates the decoded result.
 
-This is a breaking contract: legacy `inspect`/`extract` methods, selectable facets,
-and old command names are removed, not aliased.
-
+This is a breaking contract: two-word verb-object methods, legacy `inspect`/`extract`
+methods, and old command names are removed, not aliased.
 ## Licensing
 
 `@jarkkojs/readseek-api` is licensed under the Apache 2.0 license. See

package/dist/argv.d.ts

@@ -18,6 +18,8 @@ type ParsedSelector = {
     kind: SelectorKind;
     value: string;
     column?: number;
+    endLine?: number;
+    explicitKind: boolean;
 };
 /** Mirrors core::ParseSelector so wrappers reject the same selectors natively. */
 export declare function parseSelector(text: string): ParsedSelector;
@@ -26,39 +28,39 @@ export type AccessArgsInput = {
     stdinName?: string;
     readseekDir?: string;
 };
-export type ShowContentArgsInput = AccessArgsInput & {
+export type ShowArgsInput = AccessArgsInput & {
     at?: string;
     end?: number;
     limit?: number;
     language?: string;
     noAnchors?: boolean;
 };
-export type ShowStructureArgsInput = AccessArgsInput & {
+export type TreeArgsInput = AccessArgsInput & {
     at?: string;
     depth?: number;
     kind?: string;
     outline?: boolean;
     language?: string;
 };
-export type ShowMetadataArgsInput = AccessArgsInput & {
+export type MetaArgsInput = AccessArgsInput & {
     language?: string;
 };
-export type ShowAssetsArgsInput = AccessArgsInput & {
+export type AssetsArgsInput = AccessArgsInput & {
     at?: string;
 };
-export type CheckSyntaxArgsInput = AccessArgsInput & {
+export type SyntaxArgsInput = AccessArgsInput & {
     language?: string;
 };
 export type VisionArgsInput = AccessArgsInput & {
     at?: string;
     level?: VisionLevel;
 };
-export type GenerateCaptionArgsInput = VisionArgsInput & {
+export type CaptionArgsInput = VisionArgsInput & {
     include?: ("text" | "objects")[];
 };
-export type DetectObjectsArgsInput = VisionArgsInput;
-export type RecognizeTextArgsInput = VisionArgsInput;
-export type FindNodesArgsInput = AccessArgsInput & GitScopeInput & {
+export type ObjectsArgsInput = VisionArgsInput;
+export type OcrArgsInput = VisionArgsInput;
+export type SearchArgsInput = AccessArgsInput & GitScopeInput & {
     pattern?: string;
     context?: string;
     selector?: string;
@@ -67,29 +69,29 @@ export type FindNodesArgsInput = AccessArgsInput & GitScopeInput & {
     limit?: number;
     noAnchors?: boolean;
 };
-export type FindTextArgsInput = {
+export type GrepArgsInput = {
     path: string;
     text: string;
     limit?: number;
 } & GitScopeInput;
-export type FindDefinitionsArgsInput = {
+export type DefArgsInput = {
     path: string;
     name: string;
     language?: string;
     noAnchors?: boolean;
 } & GitScopeInput;
-export type FindReferencesArgsInput = {
+export type RefsArgsInput = {
     path: string;
     name?: string;
     at?: string;
     language?: string;
     noAnchors?: boolean;
 } & GitScopeInput;
-export type CheckRulesArgsInput = {
+export type CheckArgsInput = {
     path: string;
     rules: string;
 } & GitScopeInput;
-export type EditTextArgsInput = {
+export type EditArgsInput = {
     path: string;
     apply?: boolean;
     planHash?: string;
@@ -97,7 +99,7 @@ export type EditTextArgsInput = {
     requestFromStdin?: boolean;
     flagOrder?: ApplyPlanHashOrder;
 } & GitScopeInput;
-export type RenameSymbolArgsInput = {
+export type RenameArgsInput = {
     path: string;
     to: string;
     at: string;
@@ -107,19 +109,19 @@ export type RenameSymbolArgsInput = {
     language?: string;
     flagOrder?: ApplyPlanHashOrder;
 } & GitScopeInput;
-export declare function buildShowContentArgs(input: ShowContentArgsInput): string[];
-export declare function buildShowStructureArgs(input: ShowStructureArgsInput): string[];
-export declare function buildShowMetadataArgs(input: ShowMetadataArgsInput): string[];
-export declare function buildShowAssetsArgs(input: ShowAssetsArgsInput): string[];
-export declare function buildCheckSyntaxArgs(input: CheckSyntaxArgsInput): string[];
-export declare function buildGenerateCaptionArgs(input: GenerateCaptionArgsInput): string[];
-export declare function buildDetectObjectsArgs(input: DetectObjectsArgsInput): string[];
-export declare function buildRecognizeTextArgs(input: RecognizeTextArgsInput): string[];
-export declare function buildFindNodesArgs(input: FindNodesArgsInput): string[];
-export declare function buildFindTextArgs(input: FindTextArgsInput): string[];
-export declare function buildFindDefinitionsArgs(input: FindDefinitionsArgsInput): string[];
-export declare function buildFindReferencesArgs(input: FindReferencesArgsInput): string[];
-export declare function buildCheckRulesArgs(input: CheckRulesArgsInput): string[];
-export declare function buildEditTextArgs(input: EditTextArgsInput): string[];
-export declare function buildRenameSymbolArgs(input: RenameSymbolArgsInput): string[];
+export declare function buildShowArgs(input: ShowArgsInput): string[];
+export declare function buildTreeArgs(input: TreeArgsInput): string[];
+export declare function buildMetaArgs(input: MetaArgsInput): string[];
+export declare function buildAssetsArgs(input: AssetsArgsInput): string[];
+export declare function buildSyntaxArgs(input: SyntaxArgsInput): string[];
+export declare function buildCaptionArgs(input: CaptionArgsInput): string[];
+export declare function buildObjectsArgs(input: ObjectsArgsInput): string[];
+export declare function buildOcrArgs(input: OcrArgsInput): string[];
+export declare function buildSearchArgs(input: SearchArgsInput): string[];
+export declare function buildGrepArgs(input: GrepArgsInput): string[];
+export declare function buildDefArgs(input: DefArgsInput): string[];
+export declare function buildRefsArgs(input: RefsArgsInput): string[];
+export declare function buildCheckArgs(input: CheckArgsInput): string[];
+export declare function buildEditArgs(input: EditArgsInput): string[];
+export declare function buildRenameArgs(input: RenameArgsInput): string[];
 export {};

package/dist/client.d.ts

@@ -13,20 +13,20 @@ export interface ReadSeekRunner {
     kdl(args: readonly string[], options?: ReadSeekRunOptions): Promise<unknown>;
 }
 type Options<T> = Omit<T, "path" | "requestFromStdin" | "flagOrder"> & Omit<ReadSeekRunOptions, "vision">;
-export type ReadSeekContentOptions = Options<argv.ShowContentArgsInput>;
-export type ReadSeekStructureOptions = Options<argv.ShowStructureArgsInput>;
-export type ReadSeekMetadataOptions = Options<argv.ShowMetadataArgsInput>;
-export type ReadSeekAssetsOptions = Options<argv.ShowAssetsArgsInput>;
-export type ReadSeekSyntaxOptions = Options<argv.CheckSyntaxArgsInput>;
-export type ReadSeekRulesOptions = Options<argv.CheckRulesArgsInput>;
-export type ReadSeekCaptionOptions = Options<argv.GenerateCaptionArgsInput>;
-export type ReadSeekVisionOptions = Options<argv.DetectObjectsArgsInput>;
-export type ReadSeekNodesOptions = Options<argv.FindNodesArgsInput>;
-export type ReadSeekTextOptions = Options<argv.FindTextArgsInput>;
-export type ReadSeekDefinitionsOptions = Options<argv.FindDefinitionsArgsInput>;
-export type ReadSeekReferencesOptions = Options<argv.FindReferencesArgsInput>;
-export type ReadSeekEditOptions = Options<argv.EditTextArgsInput>;
-export type ReadSeekRenameOptions = Options<argv.RenameSymbolArgsInput>;
+export type ReadSeekShowOptions = Options<argv.ShowArgsInput>;
+export type ReadSeekTreeOptions = Options<argv.TreeArgsInput>;
+export type ReadSeekMetaOptions = Options<argv.MetaArgsInput>;
+export type ReadSeekAssetsOptions = Options<argv.AssetsArgsInput>;
+export type ReadSeekSyntaxOptions = Options<argv.SyntaxArgsInput>;
+export type ReadSeekCheckOptions = Options<argv.CheckArgsInput>;
+export type ReadSeekCaptionOptions = Options<argv.CaptionArgsInput>;
+export type ReadSeekVisionOptions = Options<argv.ObjectsArgsInput>;
+export type ReadSeekSearchOptions = Options<argv.SearchArgsInput>;
+export type ReadSeekGrepOptions = Options<argv.GrepArgsInput>;
+export type ReadSeekDefOptions = Options<argv.DefArgsInput>;
+export type ReadSeekRefsOptions = Options<argv.RefsArgsInput>;
+export type ReadSeekEditOptions = Options<argv.EditArgsInput>;
+export type ReadSeekRenameOptions = Options<argv.RenameArgsInput>;
 export interface ReadSeekFailure {
     code: "readseek-not-installed" | "readseek-execution-error";
     message: string;
@@ -39,20 +39,20 @@ export interface ReadSeekFailure {
  */
 export declare function classifyReadSeekFailure(err: unknown): ReadSeekFailure;
 export interface ReadSeekClient {
-    showContent(path: string, options?: ReadSeekContentOptions): Promise<output.ReadSeekContentOutput>;
-    showStructure(path: string, options?: ReadSeekStructureOptions): Promise<output.ReadSeekStructureOutputEnvelope>;
-    showMetadata(path: string, options?: ReadSeekMetadataOptions): Promise<output.ReadSeekDetection>;
-    showAssets(path: string, options?: ReadSeekAssetsOptions): Promise<output.ReadSeekAssetsOutput>;
-    checkSyntax(path: string, options?: ReadSeekSyntaxOptions): Promise<output.ReadSeekCheckOutput>;
-    checkRules(path: string, options: ReadSeekRulesOptions): Promise<output.ReadSeekRulesOutput>;
-    generateCaption(path: string, options?: ReadSeekCaptionOptions): Promise<output.ReadSeekContentOutput>;
-    detectObjects(path: string, options?: ReadSeekVisionOptions): Promise<output.ReadSeekContentOutput>;
-    recognizeText(path: string, options?: ReadSeekVisionOptions): Promise<output.ReadSeekContentOutput>;
-    findNodes(path: string, options: ReadSeekNodesOptions): Promise<output.ReadSeekSearchOutput>;
-    findText(path: string, options: ReadSeekTextOptions): Promise<output.ReadSeekTextSearchOutput>;
-    findDefinitions(path: string, options: ReadSeekDefinitionsOptions): Promise<output.DefLocation[]>;
-    findReferences(path: string, options: ReadSeekReferencesOptions): Promise<output.ReadSeekReference[]>;
-    editText(path: string, edits: unknown[], options?: ReadSeekEditOptions): Promise<output.EditOutput>;
-    renameSymbol(path: string, options: ReadSeekRenameOptions): Promise<output.RenameOutput>;
+    show(path: string, options?: ReadSeekShowOptions): Promise<output.ReadSeekContentOutput>;
+    tree(path: string, options?: ReadSeekTreeOptions): Promise<output.ReadSeekStructureOutputEnvelope>;
+    meta(path: string, options?: ReadSeekMetaOptions): Promise<output.ReadSeekDetection>;
+    assets(path: string, options?: ReadSeekAssetsOptions): Promise<output.ReadSeekAssetsOutput>;
+    syntax(path: string, options?: ReadSeekSyntaxOptions): Promise<output.ReadSeekCheckOutput>;
+    check(path: string, options: ReadSeekCheckOptions): Promise<output.ReadSeekRulesOutput>;
+    caption(path: string, options?: ReadSeekCaptionOptions): Promise<output.ReadSeekContentOutput>;
+    objects(path: string, options?: ReadSeekVisionOptions): Promise<output.ReadSeekContentOutput>;
+    ocr(path: string, options?: ReadSeekVisionOptions): Promise<output.ReadSeekContentOutput>;
+    search(path: string, options: ReadSeekSearchOptions): Promise<output.ReadSeekSearchOutput>;
+    grep(path: string, options: ReadSeekGrepOptions): Promise<output.ReadSeekTextSearchOutput>;
+    def(path: string, options: ReadSeekDefOptions): Promise<output.DefLocation[]>;
+    refs(path: string, options: ReadSeekRefsOptions): Promise<output.ReadSeekReference[]>;
+    edit(path: string, edits: unknown[], options?: ReadSeekEditOptions): Promise<output.EditOutput>;
+    rename(path: string, options: ReadSeekRenameOptions): Promise<output.RenameOutput>;
 }
 export declare function createReadSeekClient(runner: ReadSeekRunner): ReadSeekClient;

package/dist/contract.d.ts

@@ -4,7 +4,7 @@ export declare const EDIT_VARIANTS: readonly ["set_line", "replace_lines", "inse
 export type EditVariant = (typeof EDIT_VARIANTS)[number];
 export declare const GIT_SCOPES: readonly ["tracked", "untracked", "ignored", "all"];
 export type GitScope = (typeof GIT_SCOPES)[number];
-export declare const TOOL_NAMES: readonly ["show_content", "show_structure", "show_metadata", "show_assets", "check_syntax", "check_rules", "generate_caption", "detect_objects", "recognize_text", "find_nodes", "find_text", "find_definitions", "find_references", "edit_text", "rename_symbol", "write_file"];
+export declare const TOOL_NAMES: readonly ["show", "tree", "meta", "assets", "syntax", "check", "caption", "objects", "ocr", "search", "grep", "def", "refs", "edit", "rename", "write"];
 export type ToolName = (typeof TOOL_NAMES)[number];
 export declare const PARAM_DESCRIPTIONS: {
     readonly path: "Absolute or relative file path";
@@ -20,8 +20,8 @@ export declare const PARAM_DESCRIPTIONS: {
     readonly name: "Qualified or unqualified symbol name";
     readonly refsName: "Identifier to find references for";
     readonly gitScope: "In a Git repository, which files to search: tracked, untracked, ignored (untracked plus ignored), or all. Defaults to tracked plus untracked.";
-    readonly at: "Location selector: line:N[:COLUMN], hash:H[:COLUMN], symbol:NAME, page:N, node:ID, or asset:ID";
-    readonly assetAt: "Document selector: page:N, node:ID, or asset:ID";
+    readonly at: "Location selector: N[:COLUMN], START-END, H[:COLUMN], NAME, line:N[:COLUMN], hash:H[:COLUMN], symbol:NAME, page:N, node:ID, or asset:ID";
+    readonly assetAt: "Document selector: N, page:N, node:ID, or asset:ID";
     readonly rule: "KDL node selection rule, @path, or '-' for standard input";
     readonly rules: "KDL structural checks, @path, or '-' for standard input";
     readonly stdinName: "File name hint when the target is '-'";
@@ -33,7 +33,7 @@ export declare const PARAM_DESCRIPTIONS: {
     readonly kind: "Restrict structure to this node kind";
     readonly outline: "Show outline of document hierarchy or source symbols";
     readonly noAnchors: "Omit source line anchors";
-    readonly text: "Literal native text query; adapter find_text also supports regex via pattern";
+    readonly text: "Literal native text query; adapter grep also supports regex via pattern";
     readonly edits: "Use set_line, replace_lines, insert_after, replace_symbol, or replace";
     readonly editVariant: "Exactly one nested edit variant";
     readonly setLine: "Replace one line: {\"set_line\":{\"anchor\":\"LINE:HASH\",\"new_text\":\"...\"}}";
@@ -70,22 +70,22 @@ export declare const PARAM_DESCRIPTIONS: {
     readonly scopeContext: "Context lines within each symbol";
 };
 export declare const TOOL_DESCRIPTIONS: {
-    readonly show_content: "Read source, document content, or image descriptors without inference. Obtain fresh `LINE:HASH` anchors before edits; use at with a column for cursor context. Document results include typed nodes and cached asset paths.";
-    readonly show_structure: "Show parsed source or document hierarchy. Use shallow depth for file overviews.";
-    readonly show_metadata: "Show format, source identity, language, dimensions, or page count without decoding image content or inference.";
-    readonly show_assets: "Return selected document asset descriptors with usable cached paths. Adapters attach images from those paths.";
-    readonly check_syntax: "Check parser syntax diagnostics. Exit 0 is clean, 1 has findings, 2 is failure; this is not type checking.";
-    readonly check_rules: "Evaluate KDL structural assertions. Exit 0 is clean, 1 has findings, 2 is failure.";
-    readonly generate_caption: "Explicitly infer a caption using an installed model. Include text and objects to request OCR and detection too; never downloads models automatically.";
-    readonly detect_objects: "Explicitly infer object labels and bounding boxes using an installed model.";
-    readonly recognize_text: "Explicitly recognize text from pixels using an installed model; reading never silently invokes OCR.";
-    readonly find_nodes: "Find AST nodes by pattern or KDL selection rule. Returns edit-ready anchors. Use `find_text` for text and regex.";
-    readonly find_text: "Search text or regex and return edit-ready `LINE:HASH` anchors. Native CLI text is literal; adapters preserve regex, glob, context, summary, and symbol grouping.";
-    readonly find_definitions: "Find a symbol definition or declaration by qualified or unqualified name.";
-    readonly find_references: "Find identifier-name matches with name, or binding-scoped references with at. Use before renaming or deleting a symbol.";
-    readonly edit_text: "Edit existing files with fresh `LINE:HASH` anchors. Each edits item contains exactly one set_line, replace_lines, insert_after, replace_symbol, or replace object. Preview before applying a verified plan.";
-    readonly rename_symbol: "Rename a symbol at a line or hash cursor with binding-aware edits and stale-plan protection.";
-    readonly write_file: "Create or replace a complete text file and return `LINE:HASH` anchors. Use `edit_text` for small changes.";
+    readonly show: "Read source, document content, or image descriptors without inference. Obtain fresh `LINE:HASH` anchors before edits; use at with a column for cursor context. Document results include typed nodes and cached asset paths.";
+    readonly tree: "Show parsed source or document hierarchy. Use shallow depth for file overviews.";
+    readonly meta: "Show format, source identity, language, dimensions, or page count without decoding image content or inference.";
+    readonly assets: "Return selected document asset descriptors with usable cached paths. Adapters attach images from those paths.";
+    readonly syntax: "Check parser syntax diagnostics. Exit 0 is clean, 1 has findings, 2 is failure; this is not type checking.";
+    readonly check: "Evaluate KDL structural assertions. Exit 0 is clean, 1 has findings, 2 is failure.";
+    readonly caption: "Explicitly infer a caption using an installed model. Include text and objects to request OCR and detection too; never downloads models automatically.";
+    readonly objects: "Explicitly infer object labels and bounding boxes using an installed model.";
+    readonly ocr: "Explicitly recognize text from pixels using an installed model; reading never silently invokes OCR.";
+    readonly search: "Find AST nodes by pattern or KDL selection rule. Returns edit-ready anchors. Use `grep` for text and regex.";
+    readonly grep: "Search text or regex and return edit-ready `LINE:HASH` anchors. Native CLI text is literal; adapters preserve regex, glob, context, summary, and symbol grouping.";
+    readonly def: "Find a symbol definition or declaration by qualified or unqualified name.";
+    readonly refs: "Find identifier-name matches with name, or binding-scoped references with at. Use before renaming or deleting a symbol.";
+    readonly edit: "Edit existing files with fresh `LINE:HASH` anchors. Each edits item contains exactly one set_line, replace_lines, insert_after, replace_symbol, or replace object. Preview before applying a verified plan.";
+    readonly rename: "Rename a symbol at a line or hash cursor with binding-aware edits and stale-plan protection.";
+    readonly write: "Create or replace a complete text file and return `LINE:HASH` anchors. Use `edit` for small changes.";
 };
 export declare function rewriteBacktickedToolNames(text: string, aliases?: Readonly<Partial<Record<ToolName, string>>>): string;
 export declare function renderToolDescription(name: ToolName, aliases?: Readonly<Partial<Record<ToolName, string>>>): string;

package/dist/index.js

@@ -9,22 +9,22 @@ var EDIT_VARIANTS = [
 ];
 var GIT_SCOPES = ["tracked", "untracked", "ignored", "all"];
 var TOOL_NAMES = [
-  "show_content",
-  "show_structure",
-  "show_metadata",
-  "show_assets",
-  "check_syntax",
-  "check_rules",
-  "generate_caption",
-  "detect_objects",
-  "recognize_text",
-  "find_nodes",
-  "find_text",
-  "find_definitions",
-  "find_references",
-  "edit_text",
-  "rename_symbol",
-  "write_file"
+  "show",
+  "tree",
+  "meta",
+  "assets",
+  "syntax",
+  "check",
+  "caption",
+  "objects",
+  "ocr",
+  "search",
+  "grep",
+  "def",
+  "refs",
+  "edit",
+  "rename",
+  "write"
 ];
 var PARAM_DESCRIPTIONS = {
   path: "Absolute or relative file path",
@@ -40,8 +40,8 @@ var PARAM_DESCRIPTIONS = {
   name: "Qualified or unqualified symbol name",
   refsName: "Identifier to find references for",
   gitScope: "In a Git repository, which files to search: tracked, untracked, ignored (untracked plus ignored), or all. Defaults to tracked plus untracked.",
-  at: "Location selector: line:N[:COLUMN], hash:H[:COLUMN], symbol:NAME, page:N, node:ID, or asset:ID",
-  assetAt: "Document selector: page:N, node:ID, or asset:ID",
+  at: "Location selector: N[:COLUMN], START-END, H[:COLUMN], NAME, line:N[:COLUMN], hash:H[:COLUMN], symbol:NAME, page:N, node:ID, or asset:ID",
+  assetAt: "Document selector: N, page:N, node:ID, or asset:ID",
   rule: "KDL node selection rule, @path, or '-' for standard input",
   rules: "KDL structural checks, @path, or '-' for standard input",
   stdinName: "File name hint when the target is '-'",
@@ -53,7 +53,7 @@ var PARAM_DESCRIPTIONS = {
   kind: "Restrict structure to this node kind",
   outline: "Show outline of document hierarchy or source symbols",
   noAnchors: "Omit source line anchors",
-  text: "Literal native text query; adapter find_text also supports regex via pattern",
+  text: "Literal native text query; adapter grep also supports regex via pattern",
   edits: "Use set_line, replace_lines, insert_after, replace_symbol, or replace",
   editVariant: "Exactly one nested edit variant",
   setLine: 'Replace one line: {"set_line":{"anchor":"LINE:HASH","new_text":"..."}}',
@@ -90,22 +90,22 @@ var PARAM_DESCRIPTIONS = {
   scopeContext: "Context lines within each symbol"
 };
 var TOOL_DESCRIPTIONS = {
-  show_content: "Read source, document content, or image descriptors without inference. Obtain fresh `LINE:HASH` anchors before edits; use at with a column for cursor context. Document results include typed nodes and cached asset paths.",
-  show_structure: "Show parsed source or document hierarchy. Use shallow depth for file overviews.",
-  show_metadata: "Show format, source identity, language, dimensions, or page count without decoding image content or inference.",
-  show_assets: "Return selected document asset descriptors with usable cached paths. Adapters attach images from those paths.",
-  check_syntax: "Check parser syntax diagnostics. Exit 0 is clean, 1 has findings, 2 is failure; this is not type checking.",
-  check_rules: "Evaluate KDL structural assertions. Exit 0 is clean, 1 has findings, 2 is failure.",
-  generate_caption: "Explicitly infer a caption using an installed model. Include text and objects to request OCR and detection too; never downloads models automatically.",
-  detect_objects: "Explicitly infer object labels and bounding boxes using an installed model.",
-  recognize_text: "Explicitly recognize text from pixels using an installed model; reading never silently invokes OCR.",
-  find_nodes: "Find AST nodes by pattern or KDL selection rule. Returns edit-ready anchors. Use `find_text` for text and regex.",
-  find_text: "Search text or regex and return edit-ready `LINE:HASH` anchors. Native CLI text is literal; adapters preserve regex, glob, context, summary, and symbol grouping.",
-  find_definitions: "Find a symbol definition or declaration by qualified or unqualified name.",
-  find_references: "Find identifier-name matches with name, or binding-scoped references with at. Use before renaming or deleting a symbol.",
-  edit_text: "Edit existing files with fresh `LINE:HASH` anchors. Each edits item contains exactly one set_line, replace_lines, insert_after, replace_symbol, or replace object. Preview before applying a verified plan.",
-  rename_symbol: "Rename a symbol at a line or hash cursor with binding-aware edits and stale-plan protection.",
-  write_file: "Create or replace a complete text file and return `LINE:HASH` anchors. Use `edit_text` for small changes."
+  show: "Read source, document content, or image descriptors without inference. Obtain fresh `LINE:HASH` anchors before edits; use at with a column for cursor context. Document results include typed nodes and cached asset paths.",
+  tree: "Show parsed source or document hierarchy. Use shallow depth for file overviews.",
+  meta: "Show format, source identity, language, dimensions, or page count without decoding image content or inference.",
+  assets: "Return selected document asset descriptors with usable cached paths. Adapters attach images from those paths.",
+  syntax: "Check parser syntax diagnostics. Exit 0 is clean, 1 has findings, 2 is failure; this is not type checking.",
+  check: "Evaluate KDL structural assertions. Exit 0 is clean, 1 has findings, 2 is failure.",
+  caption: "Explicitly infer a caption using an installed model. Include text and objects to request OCR and detection too; never downloads models automatically.",
+  objects: "Explicitly infer object labels and bounding boxes using an installed model.",
+  ocr: "Explicitly recognize text from pixels using an installed model; reading never silently invokes OCR.",
+  search: "Find AST nodes by pattern or KDL selection rule. Returns edit-ready anchors. Use `grep` for text and regex.",
+  grep: "Search text or regex and return edit-ready `LINE:HASH` anchors. Native CLI text is literal; adapters preserve regex, glob, context, summary, and symbol grouping.",
+  def: "Find a symbol definition or declaration by qualified or unqualified name.",
+  refs: "Find identifier-name matches with name, or binding-scoped references with at. Use before renaming or deleting a symbol.",
+  edit: "Edit existing files with fresh `LINE:HASH` anchors. Each edits item contains exactly one set_line, replace_lines, insert_after, replace_symbol, or replace object. Preview before applying a verified plan.",
+  rename: "Rename a symbol at a line or hash cursor with binding-aware edits and stale-plan protection.",
+  write: "Create or replace a complete text file and return `LINE:HASH` anchors. Use `edit` for small changes."
 };
 function rewriteBacktickedToolNames(text, aliases = {}) {
   return TOOL_NAMES.reduce((rewritten, toolName) => rewritten.replaceAll(`\`${toolName}\``, `\`${aliases[toolName] ?? toolName}\``), text);
@@ -198,22 +198,22 @@ function tool(name, title, properties, required) {
   return { name, title, description: TOOL_DESCRIPTIONS[name], inputSchema: { type: "object", properties, required, additionalProperties: false } };
 }
 var TOOL_CONTRACTS = [
-  tool("show_content", "Show content", { ...path, ...at, ...lang, ...stdin, ...noAnchors, end: integer(PARAM_DESCRIPTIONS.end), limit: integer(PARAM_DESCRIPTIONS.limit) }, ["path"]),
-  tool("show_structure", "Show structure", { ...path, ...at, ...lang, ...stdin, depth: integer(PARAM_DESCRIPTIONS.depth, 0), kind: string(PARAM_DESCRIPTIONS.kind), outline: { type: "boolean", description: PARAM_DESCRIPTIONS.outline } }, ["path"]),
-  tool("show_metadata", "Show metadata", { ...path, ...lang, ...stdin }, ["path"]),
-  tool("show_assets", "Show assets", { ...path, at: string(PARAM_DESCRIPTIONS.assetAt), ...stdin }, ["path"]),
-  tool("check_syntax", "Check syntax", { ...path, ...lang, ...stdin }, ["path"]),
-  tool("check_rules", "Check rules", { path: string(PARAM_DESCRIPTIONS.searchPath), ...gitScopeSchema, rules: string(PARAM_DESCRIPTIONS.rules) }, ["rules"]),
-  tool("generate_caption", "Generate caption", { ...path, ...at, ...stdin, ...level, include: { type: "array", items: { type: "string", enum: ["text", "objects"] }, minItems: 1, uniqueItems: true, description: PARAM_DESCRIPTIONS.include } }, ["path"]),
-  tool("detect_objects", "Detect objects", { ...path, ...at, ...stdin, ...level }, ["path"]),
-  tool("recognize_text", "Recognize text", { ...path, ...at, ...stdin, ...level }, ["path"]),
-  tool("find_nodes", "Find nodes", { ...path, ...lang, ...stdin, ...limit, ...gitScopeSchema, ...noAnchors, pattern: string(PARAM_DESCRIPTIONS.pattern), context: string(PARAM_DESCRIPTIONS.patternContext), selector: string(PARAM_DESCRIPTIONS.selector), rule: string(PARAM_DESCRIPTIONS.rule) }, []),
-  tool("find_text", "Find text", { ...path, ...limit, ...gitScopeSchema, text: string(PARAM_DESCRIPTIONS.text), pattern: string(PARAM_DESCRIPTIONS.grepPattern), glob: string(PARAM_DESCRIPTIONS.glob), ignoreCase: { type: "boolean", description: PARAM_DESCRIPTIONS.ignoreCase }, literal: { type: "boolean", description: PARAM_DESCRIPTIONS.literal }, context: integer(PARAM_DESCRIPTIONS.context, 0), summary: { type: "boolean", description: PARAM_DESCRIPTIONS.summary }, scope: { type: "string", enum: ["symbol"], description: PARAM_DESCRIPTIONS.grepScope }, scopeContext: integer(PARAM_DESCRIPTIONS.scopeContext, 0) }, []),
-  tool("find_definitions", "Find definitions", { ...path, ...lang, ...gitScopeSchema, ...noAnchors, name: string(PARAM_DESCRIPTIONS.name) }, ["name"]),
-  tool("find_references", "Find references", { ...path, ...at, ...lang, ...gitScopeSchema, ...noAnchors, name: string(PARAM_DESCRIPTIONS.refsName) }, []),
-  tool("edit_text", "Hash-verified edit", { ...path, ...lang, ...gitScopeSchema, ...apply, edits: { type: "array", minItems: 1, items: editItemSchema, description: PARAM_DESCRIPTIONS.edits }, postEditVerify: { type: "boolean", description: PARAM_DESCRIPTIONS.postEditVerify } }, ["path", "edits"]),
-  tool("rename_symbol", "Rename symbol", { ...path, ...at, ...lang, ...gitScopeSchema, ...apply, to: string(PARAM_DESCRIPTIONS.to), workspace: { type: "boolean", description: PARAM_DESCRIPTIONS.workspace } }, ["path", "at", "to"]),
-  tool("write_file", "Write file", { ...path, content: string(PARAM_DESCRIPTIONS.content) }, ["path", "content"])
+  tool("show", "Show content", { ...path, ...at, ...lang, ...stdin, ...noAnchors, end: integer(PARAM_DESCRIPTIONS.end), limit: integer(PARAM_DESCRIPTIONS.limit) }, ["path"]),
+  tool("tree", "Show structure", { ...path, ...at, ...lang, ...stdin, depth: integer(PARAM_DESCRIPTIONS.depth, 0), kind: string(PARAM_DESCRIPTIONS.kind), outline: { type: "boolean", description: PARAM_DESCRIPTIONS.outline } }, ["path"]),
+  tool("meta", "Show metadata", { ...path, ...lang, ...stdin }, ["path"]),
+  tool("assets", "Show assets", { ...path, at: string(PARAM_DESCRIPTIONS.assetAt), ...stdin }, ["path"]),
+  tool("syntax", "Check syntax", { ...path, ...lang, ...stdin }, ["path"]),
+  tool("check", "Check rules", { path: string(PARAM_DESCRIPTIONS.searchPath), ...gitScopeSchema, rules: string(PARAM_DESCRIPTIONS.rules) }, ["rules"]),
+  tool("caption", "Generate caption", { ...path, ...at, ...stdin, ...level, include: { type: "array", items: { type: "string", enum: ["text", "objects"] }, minItems: 1, uniqueItems: true, description: PARAM_DESCRIPTIONS.include } }, ["path"]),
+  tool("objects", "Detect objects", { ...path, ...at, ...stdin, ...level }, ["path"]),
+  tool("ocr", "Recognize text", { ...path, ...at, ...stdin, ...level }, ["path"]),
+  tool("search", "Search AST nodes", { ...path, ...lang, ...stdin, ...limit, ...gitScopeSchema, ...noAnchors, pattern: string(PARAM_DESCRIPTIONS.pattern), context: string(PARAM_DESCRIPTIONS.patternContext), selector: string(PARAM_DESCRIPTIONS.selector), rule: string(PARAM_DESCRIPTIONS.rule) }, []),
+  tool("grep", "Search text", { ...path, ...limit, ...gitScopeSchema, text: string(PARAM_DESCRIPTIONS.text), pattern: string(PARAM_DESCRIPTIONS.grepPattern), glob: string(PARAM_DESCRIPTIONS.glob), ignoreCase: { type: "boolean", description: PARAM_DESCRIPTIONS.ignoreCase }, literal: { type: "boolean", description: PARAM_DESCRIPTIONS.literal }, context: integer(PARAM_DESCRIPTIONS.context, 0), summary: { type: "boolean", description: PARAM_DESCRIPTIONS.summary }, scope: { type: "string", enum: ["symbol"], description: PARAM_DESCRIPTIONS.grepScope }, scopeContext: integer(PARAM_DESCRIPTIONS.scopeContext, 0) }, []),
+  tool("def", "Find definitions", { ...path, ...lang, ...gitScopeSchema, ...noAnchors, name: string(PARAM_DESCRIPTIONS.name) }, ["name"]),
+  tool("refs", "Find references", { ...path, ...at, ...lang, ...gitScopeSchema, ...noAnchors, name: string(PARAM_DESCRIPTIONS.refsName) }, []),
+  tool("edit", "Hash-verified edit", { ...path, ...lang, ...gitScopeSchema, ...apply, edits: { type: "array", minItems: 1, items: editItemSchema, description: PARAM_DESCRIPTIONS.edits }, postEditVerify: { type: "boolean", description: PARAM_DESCRIPTIONS.postEditVerify } }, ["path", "edits"]),
+  tool("rename", "Rename symbol", { ...path, ...at, ...lang, ...gitScopeSchema, ...apply, to: string(PARAM_DESCRIPTIONS.to), workspace: { type: "boolean", description: PARAM_DESCRIPTIONS.workspace } }, ["path", "at", "to"]),
+  tool("write", "Write file", { ...path, content: string(PARAM_DESCRIPTIONS.content) }, ["path", "content"])
 ];
 function getToolContract(name) {
   const contract = TOOL_CONTRACTS.find((entry) => entry.name === name);
@@ -224,70 +224,70 @@ function getToolContract(name) {
 // src/policy.ts
 var REPLACEABLE_TOOLS = [
   {
-    tool: "show_content",
+    tool: "show",
     builtIn: "read",
     benefit: "it returns LINE:HASH anchors for safe edits."
   },
   {
-    tool: "edit_text",
+    tool: "edit",
     builtIn: "edit",
     benefit: "it verifies fresh LINE:HASH anchors."
   },
   {
-    tool: "find_text",
+    tool: "grep",
     builtIn: "grep",
     benefit: "it returns LINE:HASH anchors."
   },
   {
-    tool: "write_file",
+    tool: "write",
     builtIn: "write",
     benefit: "it returns LINE:HASH anchors."
   }
 ];
 var TOOL_COMPACT_GUIDELINES = {
-  show_content: [
-    "Use `show_structure` for shallow overviews and `check_syntax` for diagnostics; use `find_definitions`, `find_references`, or `find_nodes` for targeted symbol questions."
+  show: [
+    "Use `tree` for shallow overviews and `syntax` for diagnostics; use `def`, `refs`, or `search` for targeted symbol questions."
   ],
-  edit_text: [
+  edit: [
     "Prefer set_line, replace_lines, and insert_after; use replace only when anchors are impractical."
   ],
-  find_text: [
-    "Use `find_text` with summary first for broad searches, then narrow by path, glob, or pattern."
+  grep: [
+    "Use `grep` with summary first for broad searches, then narrow by path, glob, or pattern."
   ],
-  write_file: [
-    "Use anchored edits rather than `write_file` for small changes or appends."
+  write: [
+    "Use anchored edits rather than `write` for small changes or appends."
   ],
-  find_nodes: [
-    "Use `find_nodes` for AST patterns; use `find_text` for plain text."
+  search: [
+    "Use `search` for AST patterns; use `grep` for plain text."
   ],
-  find_references: [
-    "Use `find_references` before changing a symbol; use at with line:N:C to follow one binding."
+  refs: [
+    "Use `refs` before changing a symbol; use at with line:N:C to follow one binding."
   ]
 };
 var BUILTIN_FALLBACKS = {
-  read: "show_content",
-  edit: "edit_text",
-  write: "write_file",
-  grep: "find_text",
-  apply_patch: "edit_text"
+  read: "show",
+  edit: "edit",
+  write: "write",
+  grep: "grep",
+  apply_patch: "edit"
 };
 var PREFERENCE_LEADS = {
-  show_content: "Preferred for reading source with anchors.",
-  edit_text: "Preferred for editing existing text files with fresh LINE:HASH anchors.",
-  write_file: "Preferred for creating or replacing a complete text file; returns LINE:HASH anchors.",
-  find_text: "Preferred text/regex search; returns edit-ready LINE:HASH anchors.",
-  find_nodes: "Preferred for AST or structural code search with ast-grep-style patterns.",
-  find_definitions: "Preferred for go-to-definition or declaration lookup by name.",
-  find_references: "Preferred for finding identifier-name matches or binding-specific references before rename_symbol or delete.",
-  rename_symbol: "Preferred for renaming a symbol with binding-aware, verified edits.",
-  show_assets: "Preferred for materializing selected document assets with usable cached paths."
+  show: "Preferred for reading source with anchors.",
+  edit: "Preferred for editing existing text files with fresh LINE:HASH anchors.",
+  write: "Preferred for creating or replacing a complete text file; returns LINE:HASH anchors.",
+  grep: "Preferred text/regex search; returns edit-ready LINE:HASH anchors.",
+  search: "Preferred for AST or structural code search with ast-grep-style patterns.",
+  def: "Preferred for go-to-definition or declaration lookup by name.",
+  refs: "Preferred for finding identifier-name matches or binding-specific references before `rename` or delete.",
+  rename: "Preferred for renaming a symbol with binding-aware, verified edits.",
+  assets: "Preferred for materializing selected document assets with usable cached paths."
 };
 var FALLBACK_TEMPLATES = {
-  read: "Prefer `show_content` with fresh LINE:HASH anchors.",
-  edit: "Prefer `edit_text` with fresh LINE:HASH anchors.",
-  write: "Prefer `write_file` so the result returns LINE:HASH anchors.",
-  grep: "Prefer `find_text` for text/regex search with edit-ready anchors.",
-  apply_patch: "Prefer `edit_text` for existing text files."
+  read: "Prefer `show` with fresh LINE:HASH anchors.",
+  edit: "Prefer `edit` with fresh LINE:HASH anchors.",
+  write: "Prefer `write` so the result returns LINE:HASH anchors.",
+  grep: "Prefer `grep` for text/regex search with edit-ready anchors.",
+  apply_patch: "Prefer `edit` for existing text files."
 };
 function resolveToolName(name, aliases = {}) {
   return aliases[name] ?? name;
@@ -306,21 +306,21 @@ function renderFallbackToolDescription(builtIn, aliases = {}) {
 }
 function renderToolRoutingPolicy(options = {}) {
   const aliases = options.aliases ?? {};
-  const show_content = resolveToolName("show_content", aliases);
-  const edit_text = resolveToolName("edit_text", aliases);
-  const write_file = resolveToolName("write_file", aliases);
-  const find_text = resolveToolName("find_text", aliases);
-  const find_nodes = resolveToolName("find_nodes", aliases);
-  const find_definitions = resolveToolName("find_definitions", aliases);
-  const find_references = resolveToolName("find_references", aliases);
-  const rename_symbol = resolveToolName("rename_symbol", aliases);
-  const show_assets = resolveToolName("show_assets", aliases);
+  const show = resolveToolName("show", aliases);
+  const edit = resolveToolName("edit", aliases);
+  const write = resolveToolName("write", aliases);
+  const grep = resolveToolName("grep", aliases);
+  const search = resolveToolName("search", aliases);
+  const def = resolveToolName("def", aliases);
+  const refs = resolveToolName("refs", aliases);
+  const rename = resolveToolName("rename", aliases);
+  const assets = resolveToolName("assets", aliases);
   const title = options.title ?? "ReadSeek tool policy:";
   const bullets = [];
   if (options.preferOverBuiltIns) {
     bullets.push("- Prefer ReadSeek tools over built-ins when they can do the job.");
   }
-  bullets.push(`- Read with ${show_content} first; ${edit_text} needs fresh LINE:HASH anchors.`, `- Use ${find_text} for text/regex, ${find_nodes} for AST patterns, ${find_definitions}/${find_references} for targeted symbols, and shallow ${resolveToolName("show_structure", aliases)} structures only for file overviews.`, `- Use ${edit_text} for existing files, ${write_file} for whole-file creation or replacement, and ${rename_symbol} for symbol renames.`, `- Use ${resolveToolName("show_structure", aliases)} for document structure; run ${resolveToolName("check_syntax", aliases)} after source edits for a quick syntax check.`, `- Use ${show_assets} to materialize selected document assets and read their returned paths.`);
+  bullets.push(`- Read with ${show} first; ${edit} needs fresh LINE:HASH anchors.`, `- Use ${grep} for text/regex, ${search} for AST patterns, ${def}/${refs} for targeted symbols, and shallow ${resolveToolName("tree", aliases)} structures only for file overviews.`, `- Use ${edit} for existing files, ${write} for whole-file creation or replacement, and ${rename} for symbol renames.`, `- Use ${resolveToolName("tree", aliases)} for document structure; run ${resolveToolName("syntax", aliases)} after source edits for a quick syntax check.`, `- Use ${assets} to materialize selected document assets and read their returned paths.`);
   if (options.demoteBuiltIns && options.demoteBuiltIns.length > 0) {
     bullets.push(`- Do not use built-in ${options.demoteBuiltIns.join(", ")} when a ReadSeek tool can do the job.`);
   }
@@ -530,50 +530,111 @@ var SELECTOR_KINDS = ["line", "hash", "symbol", "page", "node", "asset"];
 function isSelectorKind(value) {
   return SELECTOR_KINDS.includes(value);
 }
+function parsePositiveSelectorInt(raw, name) {
+  if (!/^-?\d+$/.test(raw))
+    throw new Error(`invalid ${name} \`${raw}\``);
+  const parsed = Number(raw);
+  if (!Number.isSafeInteger(parsed))
+    throw new Error(`invalid ${name} \`${raw}\``);
+  if (parsed < 1)
+    throw new Error(`${name} must be greater than zero`);
+  return parsed;
+}
+function parseLineSelector(value, explicitKind) {
+  const parts = value.split(":");
+  if (parts.length > 2)
+    throw new Error("selector has too many components");
+  const head = parts[0];
+  if (parts.length === 2) {
+    if (head.slice(1).includes("-"))
+      throw new Error("line range cannot include a column");
+    const line = parsePositiveSelectorInt(head, "line");
+    const column = parsePositiveSelectorInt(parts[1], "column");
+    return { kind: "line", value: String(line), column, explicitKind };
+  }
+  const dash = head.indexOf("-", 1);
+  if (dash > 0) {
+    const start = parsePositiveSelectorInt(head.slice(0, dash), "line");
+    const endLine = parsePositiveSelectorInt(head.slice(dash + 1), "end line");
+    if (endLine < start)
+      throw new Error(`end line ${endLine} precedes start line ${start}`);
+    return { kind: "line", value: String(start), endLine, explicitKind };
+  }
+  const line = parsePositiveSelectorInt(head, "line");
+  return { kind: "line", value: String(line), explicitKind };
+}
+function parseHashSelector(value, explicitKind) {
+  const parts = value.split(":");
+  if (parts.length > 2)
+    throw new Error("selector has too many components");
+  const head = parts[0];
+  if (!/^[0-9a-fA-F]{6}$/.test(head))
+    throw new Error(`invalid line hash \`${head}\``);
+  if (parts.length === 2) {
+    const column = parsePositiveSelectorInt(parts[1], "column");
+    return { kind: "hash", value: head, column, explicitKind };
+  }
+  return { kind: "hash", value: head, explicitKind };
+}
+function isDocumentSelector(parsed) {
+  return ["page", "node", "asset"].includes(parsed.kind) || parsed.kind === "line" && !parsed.explicitKind && parsed.column === undefined && parsed.endLine === undefined;
+}
+function isBindingSelector(parsed) {
+  if (parsed.endLine !== undefined)
+    return false;
+  if (parsed.kind === "line" || parsed.kind === "hash")
+    return true;
+  return parsed.kind === "symbol" && !parsed.explicitKind && /^[0-9a-fA-F]{6}$/.test(parsed.value);
+}
 function parseSelector(text) {
+  if (text.length === 0)
+    throw new Error("selector must not be empty");
   const separator = text.indexOf(":");
-  if (separator < 0) {
-    throw new Error("selector must start with line:, hash:, symbol:, page:, node:, or asset:");
-  }
-  const kind = text.slice(0, separator);
-  const value = text.slice(separator + 1);
-  if (value.length === 0)
-    throw new Error(`${kind} selector must not be empty`);
-  if (!isSelectorKind(kind)) {
+  const hasSingleColon = separator >= 0 && text[separator + 1] !== ":";
+  if (hasSingleColon) {
+    const kind = text.slice(0, separator);
+    const value = text.slice(separator + 1);
+    if (isSelectorKind(kind)) {
+      if (value.length === 0)
+        throw new Error(`${kind} selector must not be empty`);
+      if (kind === "line")
+        return parseLineSelector(value, true);
+      if (kind === "hash")
+        return parseHashSelector(value, true);
+      if (kind === "page") {
+        if (value.includes(":"))
+          throw new Error("page selector has too many components");
+        parsePositiveSelectorInt(value, "page");
+      }
+      return { kind, value, explicitKind: true };
+    }
+    if (/^\d+$/.test(kind))
+      return parseLineSelector(text, false);
+    if (/^[0-9a-fA-F]{6}$/.test(kind) && /^\d+$/.test(value))
+      return parseHashSelector(text, false);
     throw new Error(`unknown selector kind \`${kind}\`; expected line, hash, symbol, page, node, or asset`);
   }
-  if (kind === "line" || kind === "hash") {
-    const parts = value.split(":");
-    if (parts.length > 2)
-      throw new Error("selector has too many components");
-    if (parts.length === 2) {
-      const column = Number(parts[1]);
-      if (!Number.isSafeInteger(column))
-        throw new Error(`invalid column \`${parts[1]}\``);
-      if (column < 1)
-        throw new Error("column must be greater than zero");
-      return { kind, value: parts[0], column };
+  if (/^[0-9-]/.test(text)) {
+    if (/^[0-9a-fA-F]{6}$/.test(text) && /[a-fA-F]/.test(text)) {
+      return parseHashSelector(text, false);
     }
+    return parseLineSelector(text, false);
   }
-  if (kind === "page") {
-    if (value.includes(":"))
-      throw new Error("page selector has too many components");
-    const page = Number(value);
-    if (!Number.isSafeInteger(page))
-      throw new Error(`invalid page \`${value}\``);
-    if (page < 1)
-      throw new Error("page must be greater than zero");
+  if (/^[0-9a-fA-F]{6}$/.test(text) && /\d/.test(text)) {
+    return parseHashSelector(text, false);
   }
-  return { kind, value };
+  if (/\s/.test(text))
+    throw new Error(`invalid selector \`${text}\``);
+  return { kind: "symbol", value: text, explicitKind: false };
 }
-function start(verb, object, input) {
+function start(command, input) {
   if (!input.path)
-    throw new Error(`${verb} ${object} requires a path`);
+    throw new Error(`${command} requires a path`);
   if (input.stdinName !== undefined && input.path !== "-")
     throw new Error("stdinName requires '-' as the target");
   const args = [];
   pushOptionalString(args, "--readseek-dir", input.readseekDir);
-  args.push(verb, object, input.path);
+  args.push(command, input.path);
   pushOptionalString(args, "--stdin-name", input.stdinName);
   return args;
 }
@@ -599,12 +660,12 @@ function anchors(args, input) {
   if (input.noAnchors)
     args.push("--no-anchors");
 }
-function buildShowContentArgs(input) {
+function buildShowArgs(input) {
   if (input.end !== undefined)
     validatePositiveInteger(input.end, "end");
   if (input.end !== undefined && input.limit !== undefined)
     throw new Error("cannot combine end with limit");
-  const args = start("show", "content", input);
+  const args = start("show", input);
   at2(args, input.at);
   pushOptionalNumber(args, "--end", input.end);
   limit2(args, input.limit);
@@ -612,10 +673,10 @@ function buildShowContentArgs(input) {
   anchors(args, input);
   return finish(args);
 }
-function buildShowStructureArgs(input) {
+function buildTreeArgs(input) {
   if (input.depth !== undefined && (!Number.isSafeInteger(input.depth) || input.depth < 0))
     throw new Error("depth must be a non-negative integer");
-  const args = start("show", "structure", input);
+  const args = start("tree", input);
   at2(args, input.at);
   pushOptionalNumber(args, "--depth", input.depth);
   pushOptionalString(args, "--kind", input.kind);
@@ -624,35 +685,35 @@ function buildShowStructureArgs(input) {
     args.push("--outline");
   return finish(args);
 }
-function buildShowMetadataArgs(input) {
-  const args = start("show", "metadata", input);
+function buildMetaArgs(input) {
+  const args = start("meta", input);
   language(args, input);
   return finish(args);
 }
-function buildShowAssetsArgs(input) {
-  if (input.at !== undefined && !["page", "node", "asset"].includes(parseSelector(input.at).kind))
+function buildAssetsArgs(input) {
+  if (input.at !== undefined && !isDocumentSelector(parseSelector(input.at)))
     throw new Error("assets requires a page, node, or asset selector");
-  const args = start("show", "assets", input);
+  const args = start("assets", input);
   at2(args, input.at);
   return finish(args);
 }
-function buildCheckSyntaxArgs(input) {
-  const args = start("check", "syntax", input);
+function buildSyntaxArgs(input) {
+  const args = start("syntax", input);
   language(args, input);
   return finish(args);
 }
-function visionArgs(verb, object, input) {
+function visionArgs(command, input) {
   if (input.level !== undefined && !VISION_LEVELS.includes(input.level))
     throw new Error("invalid vision level");
-  if (input.at !== undefined && !["page", "node", "asset"].includes(parseSelector(input.at).kind))
+  if (input.at !== undefined && !isDocumentSelector(parseSelector(input.at)))
     throw new Error("vision requires a document selector");
-  const args = start(verb, object, input);
+  const args = start(command, input);
   at2(args, input.at);
   pushOptionalString(args, "--level", input.level);
   return args;
 }
-function buildGenerateCaptionArgs(input) {
-  const args = visionArgs("generate", "caption", input);
+function buildCaptionArgs(input) {
+  const args = visionArgs("caption", input);
   if (input.include !== undefined) {
     if (input.include.length === 0 || input.include.some((task) => task !== "text" && task !== "objects"))
       throw new Error("include requires text or objects");
@@ -660,13 +721,13 @@ function buildGenerateCaptionArgs(input) {
   }
   return finish(args);
 }
-function buildDetectObjectsArgs(input) {
-  return finish(visionArgs("detect", "objects", input));
+function buildObjectsArgs(input) {
+  return finish(visionArgs("objects", input));
 }
-function buildRecognizeTextArgs(input) {
-  return finish(visionArgs("recognize", "text", input));
+function buildOcrArgs(input) {
+  return finish(visionArgs("ocr", input));
 }
-function buildFindNodesArgs(input) {
+function buildSearchArgs(input) {
   const hasPattern = Boolean(input.pattern);
   const hasRule = Boolean(input.rule);
   const hasContext = Boolean(input.context);
@@ -674,7 +735,7 @@ function buildFindNodesArgs(input) {
     if (hasPattern || hasContext || input.selector)
       throw new Error("rule cannot be combined with pattern, context, or selector");
   } else if (!hasPattern && !hasContext) {
-    throw new Error("find nodes requires pattern, context, or rule");
+    throw new Error("search requires pattern, context, or rule");
   }
   if (hasContext && !input.selector) {
     throw new Error("context requires selector");
@@ -682,7 +743,7 @@ function buildFindNodesArgs(input) {
   if (hasPattern && hasContext) {
     throw new Error("pattern and context cannot be combined");
   }
-  const args = start("find", "nodes", input);
+  const args = start("search", input);
   pushOptionalString(args, "--pattern", input.pattern);
   pushOptionalString(args, "--context", input.context);
   pushOptionalString(args, "--selector", input.selector);
@@ -693,28 +754,28 @@ function buildFindNodesArgs(input) {
   anchors(args, input);
   return finish(args);
 }
-function buildFindTextArgs(input) {
-  const args = start("find", "text", input);
+function buildGrepArgs(input) {
+  const args = start("grep", input);
   args.push("--text", input.text);
   limit2(args, input.limit);
   appendGitScopeArgs(args, input);
   return finish(args);
 }
-function buildFindDefinitionsArgs(input) {
-  const args = start("find", "definitions", input);
+function buildDefArgs(input) {
+  const args = start("def", input);
   args.push("--name", input.name);
   language(args, input);
   appendGitScopeArgs(args, input);
   anchors(args, input);
   return finish(args);
 }
-function buildFindReferencesArgs(input) {
+function buildRefsArgs(input) {
   const validated = validateReferencesSelection(input);
   if (!validated.ok)
     throw new Error(validated.error);
-  if (input.at !== undefined && !["line", "hash"].includes(parseSelector(input.at).kind))
+  if (input.at !== undefined && !isBindingSelector(parseSelector(input.at)))
     throw new Error("references requires a line or hash selector");
-  const args = start("find", "references", input);
+  const args = start("refs", input);
   pushOptionalString(args, "--name", input.name);
   at2(args, input.at);
   language(args, input);
@@ -722,14 +783,14 @@ function buildFindReferencesArgs(input) {
   anchors(args, input);
   return finish(args);
 }
-function buildCheckRulesArgs(input) {
-  const args = start("check", "rules", input);
+function buildCheckArgs(input) {
+  const args = start("check", input);
   args.push("--rules", input.rules);
   appendGitScopeArgs(args, input);
   return finish(args);
 }
-function buildEditTextArgs(input) {
-  const args = start("edit", "text", input);
+function buildEditArgs(input) {
+  const args = start("edit", input);
   appendApplyAndPlanHash(args, input);
   language(args, input);
   appendGitScopeArgs(args, input);
@@ -737,10 +798,10 @@ function buildEditTextArgs(input) {
     args.push("--edits", "-");
   return finish(args);
 }
-function buildRenameSymbolArgs(input) {
-  if (!["line", "hash"].includes(parseSelector(input.at).kind))
+function buildRenameArgs(input) {
+  if (!isBindingSelector(parseSelector(input.at)))
     throw new Error("rename requires a line or hash selector");
-  const args = start("rename", "symbol", input);
+  const args = start("rename", input);
   at2(args, input.at);
   args.push("--to", input.to);
   if (input.workspace !== undefined)
@@ -1271,71 +1332,71 @@ function runOptions(options, vision = false) {
 }
 function createReadSeekClient(runner) {
   return {
-    async showContent(path, options = {}) {
-      const value = await runner.kdl(buildShowContentArgs({ ...options, path }), runOptions(options));
+    async show(path, options = {}) {
+      const value = await runner.kdl(buildShowArgs({ ...options, path }), runOptions(options));
       return parseContentOutput(value);
     },
-    async showStructure(path, options = {}) {
-      const value = await runner.kdl(buildShowStructureArgs({ ...options, path }), runOptions(options));
+    async tree(path, options = {}) {
+      const value = await runner.kdl(buildTreeArgs({ ...options, path }), runOptions(options));
       return parseStructureEnvelope(value);
     },
-    async showMetadata(path, options = {}) {
-      const value = await runner.kdl(buildShowMetadataArgs({ ...options, path }), runOptions(options));
+    async meta(path, options = {}) {
+      const value = await runner.kdl(buildMetaArgs({ ...options, path }), runOptions(options));
       return parsePdfMetadata(value) ?? parseDetectOutput(value?.metadata);
     },
-    async showAssets(path, options = {}) {
-      const value = await runner.kdl(buildShowAssetsArgs({ ...options, path }), runOptions(options));
+    async assets(path, options = {}) {
+      const value = await runner.kdl(buildAssetsArgs({ ...options, path }), runOptions(options));
       return parseAssetsOutput(value);
     },
-    async checkSyntax(path, options = {}) {
-      const value = await runner.kdl(buildCheckSyntaxArgs({ ...options, path }), runOptions(options));
+    async syntax(path, options = {}) {
+      const value = await runner.kdl(buildSyntaxArgs({ ...options, path }), runOptions(options));
       return parseCheckOutput(value?.diagnostics ?? value);
     },
-    async checkRules(path, options) {
-      const value = await runner.kdl(buildCheckRulesArgs({ ...options, path }), runOptions(options));
+    async check(path, options) {
+      const value = await runner.kdl(buildCheckArgs({ ...options, path }), runOptions(options));
       return parseRulesOutput(value);
     },
-    async generateCaption(path, options = {}) {
-      const value = await runner.kdl(buildGenerateCaptionArgs({ ...options, path }), runOptions(options, true));
+    async caption(path, options = {}) {
+      const value = await runner.kdl(buildCaptionArgs({ ...options, path }), runOptions(options, true));
       return parseContentOutput(value);
     },
-    async detectObjects(path, options = {}) {
-      const value = await runner.kdl(buildDetectObjectsArgs({ ...options, path }), runOptions(options, true));
+    async objects(path, options = {}) {
+      const value = await runner.kdl(buildObjectsArgs({ ...options, path }), runOptions(options, true));
       return parseContentOutput(value);
     },
-    async recognizeText(path, options = {}) {
-      const value = await runner.kdl(buildRecognizeTextArgs({ ...options, path }), runOptions(options, true));
+    async ocr(path, options = {}) {
+      const value = await runner.kdl(buildOcrArgs({ ...options, path }), runOptions(options, true));
       return parseContentOutput(value);
     },
-    async findNodes(path, options) {
-      const value = await runner.kdl(buildFindNodesArgs({ ...options, path }), runOptions(options));
+    async search(path, options) {
+      const value = await runner.kdl(buildSearchArgs({ ...options, path }), runOptions(options));
       return parseSearchOutput(value);
     },
-    async findText(path, options) {
-      const value = await runner.kdl(buildFindTextArgs({ ...options, path }), runOptions(options));
+    async grep(path, options) {
+      const value = await runner.kdl(buildGrepArgs({ ...options, path }), runOptions(options));
       return parseTextSearchOutput(value);
     },
-    async findDefinitions(path, options) {
-      const value = await runner.kdl(buildFindDefinitionsArgs({ ...options, path }), runOptions(options));
+    async def(path, options) {
+      const value = await runner.kdl(buildDefArgs({ ...options, path }), runOptions(options));
       return parseDefOutput(value);
     },
-    async findReferences(path, options) {
-      const value = await runner.kdl(buildFindReferencesArgs({ ...options, path }), runOptions(options));
+    async refs(path, options) {
+      const value = await runner.kdl(buildRefsArgs({ ...options, path }), runOptions(options));
       return parseRefsOutput(value);
     },
-    async editText(path, edits, options = {}) {
+    async edit(path, edits, options = {}) {
       const stdin = serializeEditPlan(edits);
-      return parseEditOutput(await runner.kdl(buildEditTextArgs({ ...options, path, requestFromStdin: true }), runOptions({ ...options, stdin })));
+      return parseEditOutput(await runner.kdl(buildEditArgs({ ...options, path, requestFromStdin: true }), runOptions({ ...options, stdin })));
     },
-    async renameSymbol(path, options) {
-      const value = await runner.kdl(buildRenameSymbolArgs({ ...options, path }), runOptions(options));
+    async rename(path, options) {
+      const value = await runner.kdl(buildRenameArgs({ ...options, path }), runOptions(options));
       return parseRenameOutput(value);
     }
   };
 }
 // src/show-presentation.ts
 function isShowTool(name) {
-  return name === "show_content" || name === "show_structure" || name === "show_metadata" || name === "show_assets";
+  return name === "show" || name === "tree" || name === "meta" || name === "assets";
 }
 function record(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
@@ -1450,7 +1511,7 @@ function presentShowResult(tool, value, options = {}) {
   const path = inline(options.path || output.source || output.file || content.file || structure.file || metadata.file || cursor.file) || "(unknown path)";
   const summary = [];
   const result = { summary: "", body: "", notices: [], metadata: {} };
-  if (tool === "show_metadata") {
+  if (tool === "meta") {
     const data = Object.keys(metadata).length > 0 ? metadata : output;
     if (text(data.format || data.language || data.type))
       summary.push(inline(data.format || data.language || data.type));
@@ -1459,7 +1520,7 @@ function presentShowResult(tool, value, options = {}) {
       summary.push(plural(result.metadata.pages, "page"));
     }
     result.body = fields(data) || "No metadata available.";
-  } else if (tool === "show_assets") {
+  } else if (tool === "assets") {
     const assets = records(output.assets);
     result.metadata.assets = assets.length;
     summary.push(plural(assets.length, "asset"));
@@ -1473,7 +1534,7 @@ function presentShowResult(tool, value, options = {}) {
     summary.push(plural(nodes.length, "node"));
     if (result.metadata.pages !== undefined)
       summary.push(plural(result.metadata.pages, "page"));
-    const sections = [text(output.title) ? safe(text(output.title)) : "", documentNodes(nodes, tool === "show_content")];
+    const sections = [text(output.title) ? safe(text(output.title)) : "", documentNodes(nodes, tool === "show")];
     if (assets.length > 0) {
       result.metadata.assets = assets.length;
       sections.push(`Assets
@@ -1482,7 +1543,7 @@ ${assetList(assets)}`);
     result.body = sections.filter(Boolean).join(`
 
 `) || "No content in this selection.";
-  } else if (tool === "show_structure") {
+  } else if (tool === "tree") {
     const symbols = records(structure.symbols);
     result.metadata.symbols = symbols.length;
     summary.push(plural(symbols.length, "symbol"));
@@ -1536,7 +1597,7 @@ ${assetList(assets)}`);
     const description = Object.keys(content).length > 0 ? content : output;
     result.body = fields(description) || "No content in this selection.";
   }
-  if (tool === "show_structure")
+  if (tool === "tree")
     result.notices.push("Structure is limited to the requested depth, kind, and outline. Use a deeper depth or focus with at to inspect further.");
   if (text(output.warning))
     result.notices.push(safe(text(output.warning)));
@@ -2049,7 +2110,7 @@ function acceptsReadSeekExitCode(args, exitCode) {
       index++;
       continue;
     }
-    return arg === "find" || arg === "check";
+    return arg === "grep" || arg === "search" || arg === "def" || arg === "refs" || arg === "syntax" || arg === "check";
   }
   return false;
 }
@@ -2285,22 +2346,22 @@ export {
   acceptsReadSeekExitCode,
   appendApplyAndPlanHash,
   appendGitScopeArgs,
-  buildCheckRulesArgs,
-  buildCheckSyntaxArgs,
-  buildDetectObjectsArgs,
-  buildEditTextArgs,
-  buildFindDefinitionsArgs,
-  buildFindNodesArgs,
-  buildFindReferencesArgs,
-  buildFindTextArgs,
-  buildGenerateCaptionArgs,
+  buildAssetsArgs,
+  buildCaptionArgs,
+  buildCheckArgs,
+  buildDefArgs,
+  buildEditArgs,
+  buildGrepArgs,
   buildLineLocation,
-  buildRecognizeTextArgs,
-  buildRenameSymbolArgs,
-  buildShowAssetsArgs,
-  buildShowContentArgs,
-  buildShowMetadataArgs,
-  buildShowStructureArgs,
+  buildMetaArgs,
+  buildObjectsArgs,
+  buildOcrArgs,
+  buildRefsArgs,
+  buildRenameArgs,
+  buildSearchArgs,
+  buildShowArgs,
+  buildSyntaxArgs,
+  buildTreeArgs,
   canonicalPathKey,
   classifyReadSeekFailure,
   cleanReadSeekErrorText,

package/dist/show-presentation.d.ts

@@ -1,4 +1,4 @@
-export type ShowTool = "show_content" | "show_structure" | "show_metadata" | "show_assets";
+export type ShowTool = "show" | "tree" | "meta" | "assets";
 export interface ShowPresentation {
     summary: string;
     body: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jarkkojs/readseek-api",
-  "version": "0.11.3",
+  "version": "0.12.0",
   "description": "Shared ReadSeek CLI contract, validation, argv builders, and bounded process runners",
   "type": "module",
   "license": "Apache-2.0",
@@ -51,7 +51,7 @@
     "vitest": "^4.1.0"
   },
   "dependencies": {
-    "@jarkkojs/readseek": "^0.11.3",
+    "@jarkkojs/readseek": "^0.12.0",
     "@bgotink/kdl": "0.4.0",
     "@sinclair/typebox": "0.34.52"
   }