@jarkkojs/readseek-api 0.9.15 → 0.10.0

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/contract.ts
-var DIGEST_FACETS = [
+var INSPECT_FACETS = [
   "metadata",
   "content",
   "map",
@@ -9,18 +9,6 @@ var DIGEST_FACETS = [
 var VISION_MODES = ["none", "all", "ocr", "caption", "objects"];
 var VISION_ANALYSIS_MODES = ["all", "ocr", "caption", "objects"];
 var VISION_LEVELS = ["low", "medium", "high"];
-var DOCUMENT_NODE_KINDS = [
-  "artifact",
-  "footer",
-  "header",
-  "heading",
-  "marginal_label",
-  "page",
-  "page_number",
-  "paragraph",
-  "section",
-  "structural_section"
-];
 var EDIT_VARIANTS = [
   "set_line",
   "replace_lines",
@@ -28,13 +16,13 @@ var EDIT_VARIANTS = [
   "replace",
   "replace_symbol"
 ];
-var GIT_SELECTION_FLAGS = ["cached", "others", "ignored"];
+var GIT_SCOPES = ["tracked", "untracked", "ignored", "all"];
 var TOOL_NAMES = [
-  "digest",
+  "inspect",
   "edit",
   "write",
   "grep",
-  "view",
+  "extract",
   "search",
   "def",
   "refs",
@@ -56,27 +44,24 @@ var PARAM_DESCRIPTIONS = {
   line: "One-based cursor line; required with scope",
   renameLine: "One-based cursor line of the symbol to rename",
   column: "One-based cursor byte column for disambiguation",
-  cached: "In a Git repository, search tracked/indexed files",
-  others: "In a Git repository, search untracked files",
-  ignored: "With others=true, include ignored untracked files",
+  gitScope: "In a Git repository, which files to search: tracked, untracked, ignored (untracked plus ignored), or all. Defaults to tracked plus untracked.",
   select: "Facets: metadata, content, map, diagnostics, identity (default content)",
   selectComma: "Comma-separated facets: metadata, content, map, diagnostics, identity",
-  at: "Location: line:N[:COLUMN], hash:HASH[:COLUMN], or symbol:NAME",
+  selector: "Positional selector: line:N[:COLUMN], hash:H[:COLUMN], symbol:NAME, page:N, node:ID, or asset:ID. Columns require the identity facet, which in turn rejects symbol selectors",
+  assetSelector: "Document asset selector in the form asset:ID",
+  query: "KDL selection query, @path, or '-' for standard input",
+  stdinName: "File name hint when the target is '-'",
   end: "Last line to include",
   limit: "Maximum number of lines to include",
+  inspectDepth: "Maximum structural depth for map output; defaults to 1 in agent tools",
   offset: "One-based starting line",
   readLimit: "Maximum lines to return",
   symbolRead: "Symbol name to read",
   bundle: "Include related symbols from the same file; requires symbol",
   image: "Standalone image mode: none, all, ocr, caption, objects. Required for standalone images.",
-  visionModeDigest: "Standalone image mode: none, all, caption, objects, or ocr",
-  visionModeView: "Analyze selected assets: all, ocr, caption, or objects",
+  visionModeInspect: "Standalone image mode: none, all, caption, objects, or ocr",
   visionLevel: "Vision inference level: low (default), medium, or high",
-  node: "Node ID to use as the view root",
-  page: "One-based source page",
-  kind: "Node kind filter",
-  depth: "Maximum depth below selected roots",
-  outline: "Return outline nodes only",
+  output: "Destination file for extracted binary data; stdout is not supported",
   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":"..."}}',
@@ -113,11 +98,11 @@ var PARAM_DESCRIPTIONS = {
   scopeContext: "Context lines within each symbol"
 };
 var TOOL_DESCRIPTIONS = {
-  digest: "Digest source content and images into the native CLI envelope. Returns metadata plus requested facets unchanged from `readseek digest`. Use it before edits to obtain fresh `LINE:HASH` anchors; use for structural maps, diagnostics, and cursor identity.",
+  inspect: "Inspect source content, images, and documents through the native CLI envelope. Use it before edits to obtain fresh `LINE:HASH` anchors; use shallow maps for structural overviews, diagnostics for syntax checks, and identity for cursor context.",
   edit: 'Edit existing text files with fresh `LINE:HASH` anchors. Read or search 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":"..."}}`.',
   write: "Create or replace a complete text file and return `LINE:HASH` anchors. Use `edit` for small changes to an existing file.",
   grep: "Search text or regex in files and return edit-ready `LINE:HASH` anchors. Use for identifiers, strings, configuration, errors, comments, and documentation.",
-  view: "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.",
+  extract: "Extract a selected document asset into a destination file. Use an `asset:ID` selector discovered through `inspect`; extracted binary data is never returned on stdout.",
   search: "Search code by AST structure using ast-grep-style patterns. Results include line hashes usable as `LINE:HASH` anchors. Use `grep` for identifiers, strings, comments, configuration, documentation, or other plain text and regex.",
   def: "Go to a symbol definition or declaration by name. Accepts qualified or unqualified names; use this instead of text search for functions, methods, classes, types, and other declarations.",
   refs: "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 literals, and use this before renaming or deleting a symbol.",
@@ -129,18 +114,11 @@ function renderToolDescription(name, aliases = {}) {
     throw new Error(`Missing TOOL_DESCRIPTIONS for ${name}`);
   return TOOL_NAMES.reduce((description, toolName) => description.replaceAll(`\`${toolName}\``, `\`${aliases[toolName] ?? toolName}\``), desc);
 }
-var gitFlagsSchema = {
-  cached: {
-    type: "boolean",
-    description: PARAM_DESCRIPTIONS.cached
-  },
-  others: {
-    type: "boolean",
-    description: PARAM_DESCRIPTIONS.others
-  },
-  ignored: {
-    type: "boolean",
-    description: PARAM_DESCRIPTIONS.ignored
+var gitScopeSchema = {
+  gitScope: {
+    type: "string",
+    enum: GIT_SCOPES,
+    description: PARAM_DESCRIPTIONS.gitScope
   }
 };
 var editItemSchema = {
@@ -206,28 +184,31 @@ var editItemSchema = {
 };
 var TOOL_CONTRACTS = [
   {
-    name: "digest",
-    title: "Digest source",
-    description: TOOL_DESCRIPTIONS.digest,
+    name: "inspect",
+    title: "Inspect input",
+    description: TOOL_DESCRIPTIONS.inspect,
     inputSchema: {
       type: "object",
       properties: {
         path: { type: "string", description: PARAM_DESCRIPTIONS.path },
+        selector: { type: "string", description: PARAM_DESCRIPTIONS.selector },
         select: { type: "string", description: PARAM_DESCRIPTIONS.select },
-        at: { type: "string", description: PARAM_DESCRIPTIONS.at },
+        query: { type: "string", description: PARAM_DESCRIPTIONS.query },
         end: { type: "integer", minimum: 1, description: PARAM_DESCRIPTIONS.end },
         limit: { type: "integer", minimum: 1, description: PARAM_DESCRIPTIONS.limit },
+        depth: { type: "integer", minimum: 0, description: PARAM_DESCRIPTIONS.inspectDepth },
         language: { type: "string", description: PARAM_DESCRIPTIONS.languageOverride },
         visionMode: {
           type: "string",
           enum: [...VISION_MODES],
-          description: PARAM_DESCRIPTIONS.visionModeDigest
+          description: PARAM_DESCRIPTIONS.visionModeInspect
         },
         visionLevel: {
           type: "string",
           enum: [...VISION_LEVELS],
           description: PARAM_DESCRIPTIONS.visionLevel
-        }
+        },
+        stdinName: { type: "string", description: PARAM_DESCRIPTIONS.stdinName }
       },
       required: ["path"],
       additionalProperties: false
@@ -301,34 +282,27 @@ var TOOL_CONTRACTS = [
     }
   },
   {
-    name: "view",
-    title: "View document",
-    description: TOOL_DESCRIPTIONS.view,
+    name: "extract",
+    title: "Extract asset",
+    description: TOOL_DESCRIPTIONS.extract,
     inputSchema: {
       type: "object",
       properties: {
         path: { type: "string", description: PARAM_DESCRIPTIONS.path },
-        node: { type: "string", description: PARAM_DESCRIPTIONS.node },
-        page: { type: "integer", minimum: 1, description: PARAM_DESCRIPTIONS.page },
-        kind: {
+        selector: {
           type: "string",
-          enum: [...DOCUMENT_NODE_KINDS],
-          description: PARAM_DESCRIPTIONS.kind
+          pattern: "^asset:.+",
+          description: PARAM_DESCRIPTIONS.assetSelector
         },
-        depth: { type: "integer", minimum: 0, description: PARAM_DESCRIPTIONS.depth },
-        outline: { type: "boolean", description: PARAM_DESCRIPTIONS.outline },
-        visionMode: {
+        output: {
           type: "string",
-          enum: [...VISION_ANALYSIS_MODES],
-          description: PARAM_DESCRIPTIONS.visionModeView
+          minLength: 1,
+          pattern: "^(?!-$).+",
+          description: PARAM_DESCRIPTIONS.output
         },
-        visionLevel: {
-          type: "string",
-          enum: [...VISION_LEVELS],
-          description: PARAM_DESCRIPTIONS.visionLevel
-        }
+        stdinName: { type: "string", description: PARAM_DESCRIPTIONS.stdinName }
       },
-      required: ["path"],
+      required: ["path", "selector", "output"],
       additionalProperties: false
     }
   },
@@ -342,7 +316,8 @@ var TOOL_CONTRACTS = [
         pattern: { type: "string", description: PARAM_DESCRIPTIONS.pattern },
         path: { type: "string", description: PARAM_DESCRIPTIONS.searchPath },
         language: { type: "string", description: PARAM_DESCRIPTIONS.language },
-        ...gitFlagsSchema
+        limit: { type: "integer", minimum: 1, description: PARAM_DESCRIPTIONS.matchLimit },
+        ...gitScopeSchema
       },
       required: ["pattern"],
       additionalProperties: false
@@ -358,7 +333,7 @@ var TOOL_CONTRACTS = [
         name: { type: "string", description: PARAM_DESCRIPTIONS.name },
         path: { type: "string", description: PARAM_DESCRIPTIONS.searchPath },
         language: { type: "string", description: PARAM_DESCRIPTIONS.language },
-        ...gitFlagsSchema
+        ...gitScopeSchema
       },
       required: ["name"],
       additionalProperties: false
@@ -377,7 +352,7 @@ var TOOL_CONTRACTS = [
         scope: { type: "boolean", description: PARAM_DESCRIPTIONS.scope },
         line: { type: "integer", minimum: 1, description: PARAM_DESCRIPTIONS.line },
         column: { type: "integer", minimum: 1, description: PARAM_DESCRIPTIONS.column },
-        ...gitFlagsSchema
+        ...gitScopeSchema
       },
       additionalProperties: false
     }
@@ -395,7 +370,9 @@ var TOOL_CONTRACTS = [
         to: { type: "string", description: PARAM_DESCRIPTIONS.to },
         workspace: { type: "boolean", description: PARAM_DESCRIPTIONS.workspace },
         apply: { type: "boolean", description: PARAM_DESCRIPTIONS.apply },
-        planHash: { type: "string", description: PARAM_DESCRIPTIONS.planHash }
+        planHash: { type: "string", description: PARAM_DESCRIPTIONS.planHash },
+        language: { type: "string", description: PARAM_DESCRIPTIONS.language },
+        ...gitScopeSchema
       },
       required: ["path", "line", "to"],
       additionalProperties: false
@@ -411,7 +388,7 @@ function getToolContract(name) {
 // src/policy.ts
 var REPLACEABLE_TOOLS = [
   {
-    tool: "digest",
+    tool: "inspect",
     builtIn: "read",
     benefit: "it returns LINE:HASH anchors for safe edits."
   },
@@ -432,8 +409,8 @@ var REPLACEABLE_TOOLS = [
   }
 ];
 var TOOL_COMPACT_GUIDELINES = {
-  digest: [
-    "Use `digest` for map, diagnostics, and identity facets instead of separate tools."
+  inspect: [
+    "Use `inspect` for shallow maps, diagnostics, and identity; use `def`, `refs`, or `search` for targeted symbol questions."
   ],
   edit: [
     "Prefer set_line, replace_lines, and insert_after; use replace only when anchors are impractical."
@@ -452,14 +429,14 @@ var TOOL_COMPACT_GUIDELINES = {
   ]
 };
 var BUILTIN_FALLBACKS = {
-  read: "digest",
+  read: "inspect",
   edit: "edit",
   write: "write",
   grep: "grep",
   apply_patch: "edit"
 };
 var PREFERENCE_LEADS = {
-  digest: "Preferred for reading source with anchors and facets.",
+  inspect: "Preferred for reading source with anchors and facets.",
   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.",
@@ -467,10 +444,10 @@ var PREFERENCE_LEADS = {
   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.",
-  view: "Preferred for digesting document structure or selected content."
+  extract: "Preferred for saving a selected document asset to a file."
 };
 var FALLBACK_TEMPLATES = {
-  read: "Prefer `digest` with fresh LINE:HASH anchors.",
+  read: "Prefer `inspect` 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.",
@@ -496,7 +473,7 @@ function renderFallbackToolDescription(builtIn, aliases = {}) {
 }
 function renderToolRoutingPolicy(options = {}) {
   const aliases = options.aliases ?? {};
-  const digest = resolveToolName("digest", aliases);
+  const inspect = resolveToolName("inspect", aliases);
   const edit = resolveToolName("edit", aliases);
   const write = resolveToolName("write", aliases);
   const grep = resolveToolName("grep", aliases);
@@ -504,11 +481,11 @@ function renderToolRoutingPolicy(options = {}) {
   const def = resolveToolName("def", aliases);
   const refs = resolveToolName("refs", aliases);
   const rename = resolveToolName("rename", aliases);
-  const view = resolveToolName("view", aliases);
+  const extract = resolveToolName("extract", aliases);
   if (options.style === "server") {
     return [
-      "Structural code navigation, document viewing, and hash-verified edits with readseek.",
-      "For structural questions, prefer these tools to text Grep/Bash: definitions, references, AST search, multi-facet digest (content/map/diagnostics/identity), and document views.",
+      "Structural code navigation, document inspection, and hash-verified edits with readseek.",
+      "For structural questions, prefer these tools to text Grep/Bash: targeted definitions, references, and AST search; shallow inspect maps; diagnostics and identity; and document inspection.",
       `Use ${edit} for LINE:HASH-anchored mutations (preview with apply=false; apply defaults to true and re-checks plan_hash).`,
       "Paths resolve against CLAUDE_PROJECT_DIR. Native Read/Grep/Edit hooks provide passive context;",
       "call MCP tools for active navigation, document questions, or anchored edits."
@@ -519,7 +496,7 @@ function renderToolRoutingPolicy(options = {}) {
   if (options.preferOverBuiltIns) {
     bullets.push("- Prefer ReadSeek tools over built-ins when they can do the job.");
   }
-  bullets.push(`- Read with ${digest} first; ${edit} needs fresh LINE:HASH anchors.`, `- Use ${grep} for text/regex, ${search} for AST patterns, and ${digest}/${def}/${refs} for symbol navigation.`, `- Use ${edit} for existing files, ${write} for whole-file creation or replacement, and ${rename} for symbol renames.`, `- Use ${view} for document structure; run ${digest} with select diagnostics after source edits for a quick syntax check.`);
+  bullets.push(`- Read with ${inspect} first; ${edit} needs fresh LINE:HASH anchors.`, `- Use ${grep} for text/regex, ${search} for AST patterns, ${def}/${refs} for targeted symbols, and shallow ${inspect} maps only for file overviews.`, `- Use ${edit} for existing files, ${write} for whole-file creation or replacement, and ${rename} for symbol renames.`, `- Use ${inspect} for document structure; run ${inspect} with select diagnostics after source edits for a quick syntax check.`, `- Use ${extract} to save a selected document asset.`);
   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.`);
   }
@@ -561,12 +538,6 @@ function parseLineAnchor(anchor) {
 }
 
 // src/validation.ts
-function validateGitSelection(input) {
-  if (input.ignored && !input.others) {
-    return { ok: false, error: "ignored requires others=true" };
-  }
-  return { ok: true };
-}
 function validateRefsNameVsScope(input) {
   if (input.scope) {
     if (input.line === undefined) {
@@ -583,11 +554,8 @@ function validateRefsNameVsScope(input) {
   return { ok: true };
 }
 function validateVisionLevelVsMode(input) {
-  if (input.outline && (input.visionMode !== undefined || input.visionLevel !== undefined)) {
-    return { ok: false, error: "Cannot combine outline with visionMode or visionLevel" };
-  }
-  if (input.visionLevel !== undefined && input.visionMode === undefined) {
-    return { ok: false, error: "visionLevel requires visionMode" };
+  if (input.visionLevel !== undefined && !["all", "ocr", "caption", "objects"].includes(input.visionMode ?? "")) {
+    return { ok: false, error: "visionLevel requires an analysis visionMode" };
   }
   return { ok: true };
 }
@@ -714,21 +682,54 @@ function coerceNonNegativeInt(value) {
   }
   return;
 }
+// src/edit-plan.ts
+import { Document, Node, format } from "@bgotink/kdl";
+function node(name, properties, children = []) {
+  const result = Node.create(name);
+  for (const [key, value] of Object.entries(properties))
+    result.setProperty(key, value);
+  if (children.length > 0)
+    result.children = new Document(children);
+  return result;
+}
+function editNode(edit) {
+  if ("set_line" in edit) {
+    const value = edit.set_line;
+    return node("set-line", { anchor: value.anchor, text: value.new_text });
+  }
+  if ("replace_lines" in edit) {
+    const value = edit.replace_lines;
+    return node("replace-lines", { start: value.start_anchor, end: value.end_anchor, text: value.new_text });
+  }
+  if ("insert_after" in edit) {
+    const value = edit.insert_after;
+    return node("insert-after", { anchor: value.anchor, text: value.new_text });
+  }
+  if ("replace_symbol" in edit) {
+    const value = edit.replace_symbol;
+    return node("replace-symbol", { symbol: value.symbol, body: value.new_body });
+  }
+  const value = edit.replace;
+  return node("replace", {
+    old: value.old_text,
+    new: value.new_text,
+    ...value.all === undefined ? {} : { all: value.all }
+  });
+}
+function serializeEditPlan(edits) {
+  const validation = validateExactlyOneEditVariant(edits);
+  if (!validation.ok)
+    throw new Error(validation.error);
+  return format(new Document([node("plan", {}, validation.edits.map(editNode))]));
+}
 // src/argv.ts
+var DEFAULT_INSPECT_MAP_DEPTH = 1;
 function buildLineLocation(line, column) {
   return column === undefined ? `line:${line}` : `line:${line}:${column}`;
 }
-function appendGitSelectionArgs(args, input) {
-  const validated = validateGitSelection(input);
-  if (!validated.ok) {
-    throw new Error(validated.error);
-  }
-  if (input.cached)
-    args.push("--cached");
-  if (input.others)
-    args.push("--others");
-  if (input.ignored)
-    args.push("--ignored");
+function appendGitScopeArgs(args, input) {
+  if (input.gitScope !== undefined)
+    args.push("--git-scope", input.gitScope);
   return args;
 }
 function pushOptionalString(args, flag, value) {
@@ -757,51 +758,163 @@ function selectArg(select) {
     return;
   return Array.isArray(select) ? select.join(",") : select;
 }
-function buildDigestArgs(input) {
+function selectedInspectFacets(select) {
+  const facets = (selectArg(select) ?? "content").split(",").map((facet) => facet.trim());
+  for (const facet of facets) {
+    if (!INSPECT_FACETS.includes(facet)) {
+      throw new Error(`unknown inspect facet: ${facet}`);
+    }
+  }
+  return facets;
+}
+function hasInspectFacet(facets, facet) {
+  return facets.includes(facet);
+}
+function validateTarget(command, target, stdinName) {
+  if (target.length === 0)
+    throw new Error(`${command} requires a target file path or '-'`);
+  if (stdinName !== undefined && stdinName.length > 0 && target !== "-") {
+    throw new Error("stdinName requires '-' as the target");
+  }
+}
+function validatePositiveInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+}
+var SELECTOR_KINDS = ["line", "hash", "symbol", "page", "node", "asset"];
+function isSelectorKind(value) {
+  return SELECTOR_KINDS.includes(value);
+}
+function parseSelector(text) {
+  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)) {
+    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 (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");
+  }
+  return { kind, value };
+}
+function buildInspectArgs(input) {
+  validateTarget("inspect", input.path, input.stdinName);
+  if (input.selector !== undefined && input.selector.length === 0) {
+    throw new Error("selector must not be empty");
+  }
   const vision = validateVisionLevelVsMode({
     visionMode: input.visionMode,
     visionLevel: input.visionLevel
   });
   if (!vision.ok)
     throw new Error(vision.error);
+  const facets = selectedInspectFacets(input.select);
+  const hasContent = hasInspectFacet(facets, "content");
+  const hasIdentity = hasInspectFacet(facets, "identity");
+  const hasMap = hasInspectFacet(facets, "map");
+  const hasSourceFacet = hasMap || hasInspectFacet(facets, "diagnostics") || hasIdentity;
+  if (input.end !== undefined)
+    validatePositiveInteger(input.end, "end");
+  if (input.limit !== undefined)
+    validatePositiveInteger(input.limit, "limit");
+  if (input.end !== undefined && input.limit !== undefined) {
+    throw new Error("cannot combine end with limit");
+  }
+  if (input.depth !== undefined) {
+    if (!Number.isSafeInteger(input.depth) || input.depth < 0) {
+      throw new Error("depth must be a non-negative integer");
+    }
+    if (!hasMap)
+      throw new Error("depth requires the map facet");
+  }
+  if (input.selector !== undefined && input.query !== undefined) {
+    throw new Error("cannot combine selector with query");
+  }
+  if (!hasContent && (input.end !== undefined || input.limit !== undefined || input.query !== undefined)) {
+    throw new Error("ranges and queries require the content facet");
+  }
+  if (hasIdentity && input.selector === undefined) {
+    throw new Error("the identity facet requires a selector");
+  }
+  if (input.selector !== undefined && !hasContent && !hasIdentity) {
+    throw new Error("selectors require the content or identity facet");
+  }
+  if (input.selector !== undefined) {
+    const selector = parseSelector(input.selector);
+    if (selector.kind === "symbol" && hasIdentity) {
+      throw new Error("the identity facet does not accept symbol selectors");
+    }
+    if (selector.column !== undefined && !hasIdentity) {
+      throw new Error("selector columns require the identity facet");
+    }
+  }
+  const hasVision = input.visionMode !== undefined || input.visionLevel !== undefined;
+  if (hasVision && !hasContent) {
+    throw new Error("vision options require the content facet");
+  }
+  if (hasVision && hasSourceFacet) {
+    throw new Error("vision options cannot be combined with source facets");
+  }
   const args = [];
   if (input.readseekDir !== undefined)
     args.push("--readseek-dir", input.readseekDir);
-  args.push("digest", input.path);
+  args.push("inspect", input.path);
+  if (input.selector !== undefined)
+    args.push(input.selector);
   const select = selectArg(input.select);
   if (select !== undefined)
     args.push("--select", select);
-  pushOptionalString(args, "--at", input.at);
+  pushOptionalString(args, "--query", input.query);
   pushOptionalNumber(args, "--end", input.end);
   pushOptionalNumber(args, "--limit", input.limit);
+  pushOptionalNumber(args, "--depth", input.depth);
   pushOptionalString(args, "--language", input.language);
   pushOptionalString(args, "--vision-mode", input.visionMode);
   pushOptionalString(args, "--vision-level", input.visionLevel);
   pushOptionalString(args, "--stdin-name", input.stdinName);
+  args.push("--kdl");
   return args;
 }
-function buildViewArgs(input) {
-  const vision = validateVisionLevelVsMode({
-    visionMode: input.visionMode,
-    visionLevel: input.visionLevel,
-    outline: input.outline
-  });
-  if (!vision.ok)
-    throw new Error(vision.error);
+function buildExtractArgs(input) {
+  validateTarget("extract", input.path, input.stdinName);
+  if (input.selector.length === 0)
+    throw new Error("extract requires an asset selector");
+  if (!input.selector.startsWith("asset:") || input.selector === "asset:") {
+    throw new Error("extract requires an asset: selector");
+  }
+  if (input.output.length === 0 || input.output === "-") {
+    throw new Error("extract output must be a file path");
+  }
   const args = [];
   if (input.readseekDir !== undefined)
     args.push("--readseek-dir", input.readseekDir);
-  args.push("view", input.path);
-  if (input.format !== undefined)
-    args.push("--format", input.format);
-  pushOptionalString(args, "--node", input.node);
-  pushOptionalNumber(args, "--page", input.page);
-  pushOptionalString(args, "--kind", input.kind);
-  pushOptionalNumber(args, "--depth", input.depth);
-  if (input.outline)
-    args.push("--outline");
-  pushOptionalString(args, "--vision-mode", input.visionMode);
-  pushOptionalString(args, "--vision-level", input.visionLevel);
+  args.push("--output", input.output, "extract", input.path, input.selector);
+  pushOptionalString(args, "--stdin-name", input.stdinName);
   return args;
 }
 function buildSearchArgs(input) {
@@ -809,15 +922,17 @@ function buildSearchArgs(input) {
   pushOptionalString(args, "--path", input.path);
   pushOptionalString(args, "--language", input.language);
   pushOptionalNumber(args, "--limit", input.limit);
-  return appendGitSelectionArgs(args, input);
+  appendGitScopeArgs(args, input);
+  args.push("--kdl");
+  return args;
 }
 function buildDefArgs(input) {
   const args = ["def", input.name];
   pushOptionalString(args, "--path", input.path);
-  if (input.format !== undefined)
-    args.push("--format", input.format);
   pushOptionalString(args, "--language", input.language);
-  return appendGitSelectionArgs(args, input);
+  appendGitScopeArgs(args, input);
+  args.push("--kdl");
+  return args;
 }
 function buildRefsArgs(input) {
   const validated = validateRefsNameVsScope(input);
@@ -832,10 +947,10 @@ function buildRefsArgs(input) {
     pushOptionalNumber(args, "--line", input.line);
     pushOptionalNumber(args, "--column", input.column);
   }
-  if (input.format !== undefined)
-    args.push("--format", input.format);
   pushOptionalString(args, "--language", input.language);
-  return appendGitSelectionArgs(args, input);
+  appendGitScopeArgs(args, input);
+  args.push("--kdl");
+  return args;
 }
 function buildEditArgs(input) {
   const args = ["edit", input.path];
@@ -847,6 +962,7 @@ function buildEditArgs(input) {
   pushOptionalString(args, "--language", input.language);
   if (input.requestFromStdin)
     args.push("--edits", "-");
+  args.push("--kdl");
   return args;
 }
 function buildRenameArgs(input) {
@@ -859,7 +975,9 @@ function buildRenameArgs(input) {
     flagOrder: input.flagOrder ?? "plan-hash-first"
   });
   pushOptionalString(args, "--language", input.language);
-  return appendGitSelectionArgs(args, input);
+  appendGitScopeArgs(args, input);
+  args.push("--kdl");
+  return args;
 }
 // src/platform.ts
 import { accessSync, constants as fsConstants, existsSync, statSync } from "node:fs";
@@ -875,6 +993,8 @@ var READSEEK_PLATFORM_PACKAGES = {
 };
 var resolveFromPackage = createRequire(import.meta.url).resolve;
 function readSeekBinaryName(platform = process.platform) {
+  if (platform === "linux")
+    return "readseek.AppImage";
   return platform === "win32" ? "readseek.exe" : "readseek";
 }
 function readSeekPlatformKey(platform = process.platform, arch = process.arch) {
@@ -906,9 +1026,9 @@ function resolveReadSeekBinaryFromPackages(resolver = resolveFromPackage, option
   const platformPackage = READSEEK_PLATFORM_PACKAGES[key];
   if (!platformPackage) {
     const supported = Object.keys(READSEEK_PLATFORM_PACKAGES).join(", ");
-    throw new Error(`@jarkkojs/readseek ships no binary for ${key}; it supports ${supported}`);
+    throw new Error(`@jarkkojs/readseek-api ships no binary for ${key}; it supports ${supported}`);
   }
-  const metaPackage = options.metaPackage ?? "@jarkkojs/readseek";
+  const metaPackage = options.metaPackage ?? "@jarkkojs/readseek-api";
   const metaPackageJson = resolve(`${metaPackage}/package.json`);
   const metaPackageDir = path.dirname(metaPackageJson);
   let packageJsonPath;
@@ -949,7 +1069,7 @@ function resolveReadSeekCacheDir(subPath, options = {}) {
   return pathModule.join(base, ...parts);
 }
 // src/path.ts
-import { realpathSync } from "node:fs";
+import { lstatSync, realpathSync } from "node:fs";
 import { homedir as homedir2 } from "node:os";
 import path2 from "node:path";
 var UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
@@ -978,30 +1098,338 @@ function isSubPath(parent, candidate) {
   const relative = path2.relative(parent, candidate);
   return relative === "" || !relative.startsWith(`..${path2.sep}`) && relative !== ".." && !path2.isAbsolute(relative);
 }
+function resolvePathWithMissingTail(filePath) {
+  let ancestor = filePath;
+  const missing = [];
+  while (true) {
+    try {
+      lstatSync(ancestor);
+    } catch (error) {
+      if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT")
+        throw error;
+      const parent = path2.dirname(ancestor);
+      if (parent === ancestor)
+        throw error;
+      missing.push(path2.basename(ancestor));
+      ancestor = parent;
+      continue;
+    }
+    return path2.join(realpathSync.native(ancestor), ...missing.reverse());
+  }
+}
 function resolveScopedPath(root, rawPath, fallback = ".") {
-  const canonicalRoot = canonicalPathKey(root, ".");
-  const candidate = canonicalPathKey(canonicalRoot, rawPath ?? fallback);
+  let canonicalRoot;
+  let candidate;
+  try {
+    canonicalRoot = realpathSync.native(path2.resolve(root));
+    candidate = resolvePathWithMissingTail(path2.resolve(canonicalRoot, rawPath ?? fallback));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { ok: false, error: `cannot resolve project path (${root}): ${rawPath ?? fallback}: ${message}` };
+  }
   if (!isSubPath(canonicalRoot, candidate)) {
     return { ok: false, error: `path escapes project root (${canonicalRoot}): ${rawPath ?? fallback}` };
   }
   return { ok: true, path: candidate };
 }
-// src/json.ts
-var READSEEK_USAGE_HINT = /\n\s*Run readseek(?: [\w-]+)* --help for more information\.?\s*$/;
+// src/error.ts
+var READSEEK_USAGE_HINT = /(?:^|\n)\s*Run readseek(?: [\w-]+)* --help for more information\.?\s*$/;
 function cleanReadSeekErrorText(stderr) {
   return stderr.replace(READSEEK_USAGE_HINT, "").replace(/^error:\s*/i, "").replace(/\s*\n\s*/g, " ").trim();
 }
-function parseReadSeekJson(stdout) {
-  try {
-    return JSON.parse(stdout);
-  } catch {
-    const preview = stdout.trim().slice(0, 200);
-    throw new Error(`readseek returned invalid JSON: ${preview}`);
+// src/kdl.ts
+import { parse } from "@bgotink/kdl";
+function convertNode(node) {
+  if (node.getTag() !== null)
+    throw new Error("KDL node annotations are not supported");
+  const properties = new Map;
+  for (const entry of node.entries) {
+    const name = entry.getName();
+    if (name === null)
+      throw new Error("KDL positional arguments are not supported");
+    if (properties.has(name))
+      throw new Error(`KDL duplicate property '${name}'`);
+    if (entry.getTag() !== null)
+      throw new Error("KDL value annotations are not supported");
+    const value = entry.getValue();
+    if (value === null)
+      throw new Error("KDL null values are not supported");
+    if (typeof value === "number" && !Number.isFinite(value)) {
+      throw new Error("KDL number out of range");
+    }
+    properties.set(name, value);
+  }
+  return {
+    name: node.getName(),
+    properties,
+    children: node.children?.nodes.map(convertNode) ?? []
+  };
+}
+function parseKdlDocument(text) {
+  const document = parse(text);
+  if (document.nodes.length !== 1)
+    throw new Error("KDL document must contain exactly one root node");
+  return convertNode(document.nodes[0]);
+}
+
+// src/output-kdl.ts
+function properties(node) {
+  return Object.fromEntries(node.properties);
+}
+function children(node, name) {
+  return node.children.filter((child) => child.name === name);
+}
+function child(node, name) {
+  return node.children.find((candidate) => candidate.name === name);
+}
+function requireProperty(node, name) {
+  const value = node.properties.get(name);
+  if (value === undefined)
+    throw new Error(`invalid readseek KDL: ${node.name} is missing '${name}'`);
+  return value;
+}
+function line(node) {
+  const anchor = requireProperty(node, "anchor");
+  const content = requireProperty(node, "content");
+  if (typeof anchor !== "string" || typeof content !== "string") {
+    throw new Error("invalid readseek KDL line");
+  }
+  const match = /^(\d+):([0-9a-f]+)$/.exec(anchor);
+  if (!match)
+    throw new Error(`invalid readseek KDL line anchor: ${anchor}`);
+  return {
+    line: Number(match[1]),
+    hash: match[2],
+    text: content
+  };
+}
+function mapNode(node) {
+  return {
+    ...properties(node),
+    children: children(node, "node").map(mapNode)
+  };
+}
+function sourceContent(node) {
+  const result = properties(node);
+  result.hashlines = children(node, "line").map(line);
+  const objects = children(node, "object");
+  if (objects.length > 0) {
+    result.objects = objects.map((object) => ({
+      label: requireProperty(object, "label"),
+      bbox: [
+        requireProperty(object, "xmin"),
+        requireProperty(object, "ymin"),
+        requireProperty(object, "xmax"),
+        requireProperty(object, "ymax")
+      ]
+    }));
+  }
+  return result;
+}
+function sourceMap(node) {
+  const root = child(node, "node");
+  return {
+    ...properties(node),
+    ...root ? { root: mapNode(root) } : {},
+    symbols: children(node, "symbol").map(properties)
+  };
+}
+function diagnostics(node) {
+  return {
+    ...properties(node),
+    diagnostics: children(node, "diagnostic").map(properties)
+  };
+}
+function identity(node) {
+  const result = properties(node);
+  const identifier = child(node, "identifier");
+  const symbol = child(node, "symbol");
+  if (identifier)
+    result.identifier = properties(identifier);
+  if (symbol)
+    result.symbol = properties(symbol);
+  return result;
+}
+function sourceDocument(root) {
+  const result = {};
+  const metadata = child(root, "metadata");
+  const cache = child(root, "cache");
+  const content = child(root, "content");
+  const map = child(root, "map");
+  const diagnosticOutput = child(root, "diagnostics");
+  const identityOutput = child(root, "identity");
+  if (metadata)
+    result.metadata = properties(metadata);
+  if (cache)
+    result.cache = properties(cache);
+  if (content)
+    result.content = sourceContent(content);
+  if (map)
+    result.map = sourceMap(map);
+  if (diagnosticOutput)
+    result.diagnostics = diagnostics(diagnosticOutput);
+  if (identityOutput)
+    result.identity = identity(identityOutput);
+  return result;
+}
+function hit(node) {
+  return {
+    ...properties(node),
+    hashlines: children(node, "line").map(line),
+    captures: children(node, "capture").map((capture) => ({
+      ...properties(capture),
+      hashlines: children(capture, "line").map(line)
+    }))
+  };
+}
+function search(root) {
+  return {
+    ...properties(root),
+    results: children(root, "match").map((match) => ({
+      ...properties(match),
+      matches: children(match, "hit").map(hit)
+    })),
+    documents: children(root, "document").map((documentNode) => ({
+      ...properties(documentNode),
+      hits: children(documentNode, "hit").map(properties)
+    }))
+  };
+}
+function references(root) {
+  const parsed = children(root, "reference").map((reference) => {
+    const sourceLine = child(reference, "line");
+    if (!sourceLine)
+      throw new Error("invalid readseek KDL reference: missing line");
+    const parsedLine = line(sourceLine);
+    const symbol = child(reference, "symbol");
+    return {
+      ...properties(reference),
+      line_hash: parsedLine.hash,
+      text: parsedLine.text,
+      ...symbol ? { symbol: properties(symbol) } : {}
+    };
+  });
+  return {
+    references: parsed,
+    locations: parsed.map((reference) => {
+      const { symbol, ...location } = reference;
+      return symbol && typeof symbol === "object" ? { ...location, ...symbol } : location;
+    })
+  };
+}
+function definitions(root) {
+  return {
+    locations: children(root, "definition").map((definition) => {
+      const symbol = child(definition, "symbol");
+      const sourceLine = child(definition, "line");
+      if (!symbol || !sourceLine) {
+        throw new Error("invalid readseek KDL definition: missing symbol or line");
+      }
+      const symbolProperties = properties(symbol);
+      const parsedLine = line(sourceLine);
+      const definitionColumn = definition.properties.get("column");
+      const nameByte = symbol.properties.get("name_byte");
+      const startByte = symbol.properties.get("start_byte");
+      let column = 1;
+      if (typeof definitionColumn === "number") {
+        column = definitionColumn;
+      } else if (typeof nameByte === "number" && typeof startByte === "number") {
+        column = nameByte - startByte + 1;
+      }
+      return {
+        file: requireProperty(definition, "file"),
+        line: parsedLine.line,
+        column,
+        line_hash: parsedLine.hash,
+        text: parsedLine.text,
+        kind: symbolProperties.kind,
+        name: symbolProperties.name,
+        qualified_name: symbolProperties.qualified_name
+      };
+    })
+  };
+}
+function edit(root) {
+  const result = properties(root);
+  for (const name of ["before_content", "content"]) {
+    const contentNode = child(root, name);
+    if (contentNode)
+      result[name] = requireProperty(contentNode, "content");
+  }
+  return result;
+}
+function renameEdit(node) {
+  const sourceLine = child(node, "line");
+  if (!sourceLine)
+    throw new Error("invalid readseek KDL rename edit: missing line");
+  return {
+    ...properties(node),
+    text: requireProperty(sourceLine, "content")
+  };
+}
+function renameFile(node) {
+  return {
+    ...properties(node),
+    edits: children(node, "edit").map(renameEdit),
+    conflicts: children(node, "conflict").map(properties)
+  };
+}
+function rename(root) {
+  return {
+    ...renameFile(root),
+    others: children(root, "other").map(renameFile)
+  };
+}
+function genericNode(node) {
+  const result = properties(node);
+  const textNode = child(node, "text");
+  const bbox = child(node, "bbox");
+  if (textNode)
+    result.text = requireProperty(textNode, "content");
+  if (bbox)
+    result.bbox = properties(bbox);
+  const objects = children(node, "object");
+  if (objects.length > 0)
+    result.objects = objects.map(genericNode);
+  return result;
+}
+function pdfDocument(root) {
+  return {
+    ...properties(root),
+    nodes: children(root, "node").map(genericNode),
+    assets: children(root, "asset").map(genericNode),
+    vision: children(root, "vision").map(genericNode)
+  };
+}
+function parseReadSeekKdl(text) {
+  const root = parseKdlDocument(text);
+  switch (root.name) {
+    case "document":
+      return root.properties.has("format") ? pdfDocument(root) : sourceDocument(root);
+    case "search":
+      return search(root);
+    case "check":
+      return diagnostics(root);
+    case "refs":
+      return references(root);
+    case "def":
+      return definitions(root);
+    case "edit":
+      return edit(root);
+    case "edit-batch":
+      return { ...properties(root), files: children(root, "file").map(edit) };
+    case "rename":
+      return rename(root);
+    default:
+      throw new Error(`unsupported readseek KDL root: ${root.name}`);
   }
 }
 // src/process.ts
 var DEFAULT_READSEEK_TIMEOUT_MS = 120000;
 var DEFAULT_MAX_OUTPUT_BYTES = 32 * 1024 * 1024;
+function readSeekProcessEnvironment() {
+  return process.platform === "linux" ? { ...process.env, APPIMAGE_EXTRACT_AND_RUN: "1" } : process.env;
+}
 function resolveProcessLimits(options = {}) {
   return {
     timeoutMs: options.timeoutMs ?? DEFAULT_READSEEK_TIMEOUT_MS,
@@ -1032,8 +1460,8 @@ function ensureSuccessfulStdout(result) {
     return result.stdout;
   throw failureFromProcessResult(result);
 }
-function parseSuccessfulJson(result) {
-  return parseReadSeekJson(ensureSuccessfulStdout(result));
+function parseSuccessfulKdl(result) {
+  return parseReadSeekKdl(ensureSuccessfulStdout(result));
 }
 // src/process-node.ts
 import { spawn } from "node:child_process";
@@ -1100,7 +1528,7 @@ async function runReadSeekNode(binaryPath, args, options = {}) {
     try {
       child = spawn(binaryPath, [...args], {
         cwd: options.cwd,
-        env: process.env,
+        env: readSeekProcessEnvironment(),
         shell: false,
         stdio: [options.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
         windowsHide: true
@@ -1143,17 +1571,17 @@ async function runReadSeekNode(binaryPath, args, options = {}) {
 async function runReadSeekNodeText(binaryPath, args, options = {}) {
   return ensureSuccessfulStdout(await runReadSeekNode(binaryPath, args, options));
 }
-async function runReadSeekNodeJson(binaryPath, args, options = {}) {
-  return parseSuccessfulJson(await runReadSeekNode(binaryPath, args, options));
+async function runReadSeekNodeKdl(binaryPath, args, options = {}) {
+  return parseSuccessfulKdl(await runReadSeekNode(binaryPath, args, options));
 }
 // src/process-bun.ts
 function getBunSpawn() {
   const bunGlobal = globalThis;
-  const spawn2 = bunGlobal.Bun?.spawn;
-  if (typeof spawn2 !== "function") {
+  const spawn = bunGlobal.Bun?.spawn;
+  if (typeof spawn !== "function") {
     throw new Error("Bun.spawn is unavailable in this runtime");
   }
-  return spawn2;
+  return spawn;
 }
 async function readBoundedText(stream, streamName, maxOutputBytes, onOverflow) {
   const reader = stream.getReader();
@@ -1190,16 +1618,16 @@ async function runReadSeekBun(binaryPath, args, options = {}) {
   if (limits.cancelable && options.signal?.aborted) {
     throw readSeekCancellationError(options.signal);
   }
-  const spawn2 = getBunSpawn();
+  const spawn = getBunSpawn();
   const stdin = options.stdin === undefined ? undefined : new TextEncoder().encode(options.stdin);
   const spawnOptions = {
     cwd: options.cwd,
-    env: process.env,
+    env: readSeekProcessEnvironment(),
     stderr: "pipe",
     stdin,
     stdout: "pipe"
   };
-  const child = spawn2([binaryPath, ...args], limits.cancelable && options.signal ? { ...spawnOptions, killSignal: "SIGKILL", signal: options.signal } : spawnOptions);
+  const child = spawn([binaryPath, ...args], limits.cancelable && options.signal ? { ...spawnOptions, killSignal: "SIGKILL", signal: options.signal } : spawnOptions);
   const killForOverflow = () => {
     try {
       child.kill("SIGKILL");
@@ -1228,351 +1656,368 @@ async function runReadSeekBun(binaryPath, args, options = {}) {
   } finally {
     if (timeout !== undefined)
       clearTimeout(timeout);
+    pending.catch(() => {
+      return;
+    });
   }
 }
 async function runReadSeekBunText(binaryPath, args, options = {}) {
   return ensureSuccessfulStdout(await runReadSeekBun(binaryPath, args, options));
 }
-async function runReadSeekBunJson(binaryPath, args, options = {}) {
-  return parseSuccessfulJson(await runReadSeekBun(binaryPath, args, options));
+async function runReadSeekBunKdl(binaryPath, args, options = {}) {
+  return parseSuccessfulKdl(await runReadSeekBun(binaryPath, args, options));
 }
-// src/client.ts
-function classifyReadSeekFailure(err) {
-  const failure = err;
-  const message = String(failure?.message ?? err);
-  const missing = failure?.code === "ENOENT" || /Cannot find package|Cannot find module|no such file/i.test(message);
-  if (missing) {
-    return { code: "readseek-not-installed", message, hint: "Run npm install to install @jarkkojs/readseek." };
+// src/client-output.ts
+import { Type } from "@sinclair/typebox";
+import { AssertError, Value } from "@sinclair/typebox/value";
+var OPERATIONS = ["Clone", "Clean", "Default", "Assert"];
+function parse2(schema, value, what) {
+  try {
+    return Value.Parse(OPERATIONS, schema, value);
+  } catch (error) {
+    if (!(error instanceof AssertError))
+      throw error;
+    const detail = error.error;
+    throw new Error(`invalid readseek ${what}${detail?.path ?? ""}: ${detail?.message ?? "invalid value"}`);
   }
-  return { code: "readseek-execution-error", message };
-}
-function requireNumber(value, field) {
-  if (typeof value !== "number" || !Number.isSafeInteger(value))
-    throw new Error(`invalid readseek ${field}: expected safe integer`);
-  return value;
-}
-function requireString(value, field) {
-  if (typeof value !== "string")
-    throw new Error(`invalid readseek ${field}`);
-  return value;
-}
-function requireBoolean(value, field) {
-  if (typeof value !== "boolean")
-    throw new Error(`invalid readseek ${field}: expected boolean`);
-  return value;
-}
-function optionalString(value, field) {
-  if (value === undefined || value === null)
-    return;
-  return requireString(value, field);
-}
-function parseHashline(value, field) {
-  if (!value || typeof value !== "object")
-    throw new Error(`invalid readseek ${field}`);
-  const item = value;
-  return {
-    line: requireNumber(item.line, `${field}.line`),
-    hash: requireString(item.hash, `${field}.hash`),
-    text: requireString(item.text, `${field}.text`)
-  };
-}
-function parseSearchHashlines(value, field) {
-  if (!Array.isArray(value))
-    throw new Error(`invalid readseek ${field}`);
-  return value.map((line) => parseHashline(line, field));
 }
+var Int = Type.Integer({ minimum: Number.MIN_SAFE_INTEGER, maximum: Number.MAX_SAFE_INTEGER });
+var Str = Type.String();
+var Bool = Type.Boolean();
+var OptStr = Type.Optional(Str);
+var OptInt = Type.Optional(Int);
+var Hashline = Type.Object({ line: Int, hash: Str, text: Str });
+var Hashlines = Type.Array(Hashline);
+var ReadOutput = Type.Object({
+  file: Str,
+  language: Str,
+  line_count: Int,
+  file_hash: Str,
+  start_line: Int,
+  end_line: Int,
+  hashlines: Hashlines
+});
+var SymbolOutput = Type.Object({
+  kind: Str,
+  name: Str,
+  qualified_name: OptStr,
+  start_line: Int,
+  end_line: Int,
+  start_hash: OptStr,
+  end_hash: OptStr,
+  start_anchor: OptStr,
+  end_anchor: OptStr
+});
+var MapNode = Type.Recursive((Self) => Type.Object({
+  kind: Str,
+  name: Str,
+  start_line: Int,
+  end_line: Int,
+  start_anchor: Str,
+  end_anchor: Str,
+  children: Type.Array(Self)
+}));
+var MapOutput = Type.Object({
+  file: Str,
+  language: Str,
+  line_count: Int,
+  file_hash: Str,
+  root: Type.Optional(MapNode),
+  symbols: Type.Array(SymbolOutput)
+});
+var SearchSpan = {
+  start_byte: OptInt,
+  end_byte: OptInt,
+  text: OptStr,
+  start_line: Int,
+  end_line: Int,
+  start_hash: Str,
+  end_hash: Str,
+  hashlines: Hashlines
+};
+var SearchCapture = Type.Object({ name: Str, ...SearchSpan });
+var SearchMatch = Type.Object({
+  pattern_index: Type.Integer({ default: 0 }),
+  ...SearchSpan,
+  captures: Type.Array(SearchCapture)
+});
+var SearchFileOutput = Type.Object({
+  file: Str,
+  language: Str,
+  file_hash: Str,
+  matches: Type.Array(SearchMatch)
+});
+var SearchEnvelope = Type.Object({
+  results: Type.Array(SearchFileOutput),
+  returned_matches: OptInt,
+  truncated: Type.Optional(Bool),
+  byte_basis: OptStr
+});
+var RefsEnvelope = Type.Object({
+  references: Type.Array(Type.Object({
+    file: Str,
+    line: Int,
+    column: Int,
+    line_hash: Str,
+    text: Str,
+    symbol: Type.Optional(Type.Object({ qualified_name: OptStr }))
+  }))
+});
+var Diagnostic = Type.Object({
+  kind: Type.Union([Type.Literal("error"), Type.Literal("missing")]),
+  start_line: Int,
+  end_line: Int
+});
+var CheckEnvelope = Type.Object({
+  file_hash: OptStr,
+  error_count: Int,
+  missing_count: Int,
+  diagnostics: Type.Array(Diagnostic)
+});
+var DetectedObject = Type.Object({
+  label: Str,
+  bbox: Type.Tuple([Int, Int, Int, Int])
+});
+var PreparedImage = Type.Object({
+  mime: Str,
+  encoding: Type.Literal("base64"),
+  data: Str
+});
+var SourceDetection = Type.Object({
+  kind: Type.Literal("source"),
+  type: Str,
+  file: Str,
+  language: Str,
+  engine: OptStr,
+  supported: Bool,
+  mime: OptStr,
+  syntax: OptStr
+});
+var ImageDetection = Type.Object({
+  kind: Type.Literal("image"),
+  type: Str,
+  file: Str,
+  mime: OptStr,
+  format: Str,
+  width: Int,
+  height: Int,
+  animated: Bool,
+  encoding: Type.Optional(Type.Literal("base64")),
+  data: OptStr,
+  ocr: OptStr,
+  caption: OptStr,
+  objects: Type.Optional(Type.Array(DetectedObject))
+});
+var TextDetection = Type.Object({
+  kind: Type.Literal("text"),
+  type: Str,
+  file: Str,
+  mime: OptStr
+});
+var PdfDetection = Type.Object({
+  kind: Type.Literal("pdf"),
+  type: Type.Literal("application/pdf"),
+  file: Str,
+  mime: OptStr,
+  format: Type.Literal("pdf"),
+  pages: Int
+});
+var Detection = Type.Union([SourceDetection, ImageDetection, TextDetection, PdfDetection]);
+var SourceDetectionInput = Type.Omit(SourceDetection, ["kind"]);
+var ImageDetectionInput = Type.Omit(ImageDetection, ["kind"]);
+var TextDetectionInput = Type.Omit(TextDetection, ["kind"]);
+var PdfDetectionInput = Type.Omit(PdfDetection, ["kind"]);
+var UnspannedContent = Type.Omit(ReadOutput, ["start_line", "end_line"]);
+var PdfInspectMetadata = Type.Object({ source: Str, format: Type.Literal("pdf"), pages: Int });
+var DocumentCache = Type.Object({
+  content_hash: Str,
+  state: Type.Union([Type.Literal("built"), Type.Literal("reused")])
+});
+var Identifier = Type.Object({
+  text: Str,
+  start_column: Int,
+  end_column: Int,
+  start_byte: Int,
+  end_byte: Int
+});
+var IdentifyEnvelope = Type.Object({
+  file: Str,
+  language: Str,
+  engine: OptStr,
+  line_count: Int,
+  file_hash: Str,
+  line: Int,
+  column: Int,
+  line_hash: Str,
+  identifier: Type.Optional(Identifier),
+  symbol: Type.Optional(Type.Object({
+    name: Str,
+    kind: Str,
+    qualified_name: Str,
+    start_line: Int,
+    end_line: Int
+  }))
+});
+var EditOutputSchema = Type.Object({
+  file: Str,
+  before_hash: Str,
+  file_hash: Str,
+  plan_hash: Str,
+  applied: Bool,
+  changed: Bool,
+  edit_count: Int,
+  before_content: OptStr,
+  content: OptStr
+});
+var RenameConflictSchema = Type.Object({ line: Int, column: Int, reason: Str });
+var RenameEditSchema = Type.Object({
+  line: Int,
+  start_column: Int,
+  end_column: Int,
+  start_byte: Int,
+  end_byte: Int,
+  occurrence: Str,
+  line_hash: Str,
+  text: Str
+});
+var Conflicts = Type.Array(RenameConflictSchema, { default: [] });
+var Edits = Type.Array(RenameEditSchema, { default: [] });
+var RenameFileOutputSchema = Type.Object({
+  file: Str,
+  language: Str,
+  engine: OptStr,
+  file_hash: Str,
+  conflicts: Conflicts,
+  edits: Edits
+});
+var RenameOutputSchema = Type.Object({
+  file: Str,
+  language: Str,
+  engine: OptStr,
+  file_hash: Str,
+  old_name: Str,
+  new_name: Str,
+  plan_hash: Str,
+  applied: Bool,
+  conflicts: Conflicts,
+  edits: Edits,
+  others: Type.Array(RenameFileOutputSchema, { default: [] })
+});
+var DefEnvelope = Type.Object({
+  locations: Type.Array(Type.Object({
+    file: Str,
+    line: Int,
+    column: Int,
+    line_hash: Str,
+    text: Str,
+    kind: OptStr,
+    name: OptStr,
+    qualified_name: OptStr
+  }))
+});
 function parseReadOutput(value) {
-  if (!value || typeof value !== "object")
-    throw new Error("invalid readseek read output");
-  const output = value;
-  const hashlines = output.hashlines;
-  if (!Array.isArray(hashlines))
-    throw new Error("invalid readseek hashlines");
-  return {
-    file: requireString(output.file, "file"),
-    language: requireString(output.language, "language"),
-    line_count: requireNumber(output.line_count, "line_count"),
-    file_hash: requireString(output.file_hash, "file_hash"),
-    start_line: requireNumber(output.start_line, "start_line"),
-    end_line: requireNumber(output.end_line, "end_line"),
-    hashlines: hashlines.map((line) => parseHashline(line, "hashline"))
-  };
+  return parse2(ReadOutput, value, "read output");
 }
 function parseMapOutput(value) {
-  if (!value || typeof value !== "object")
-    throw new Error("invalid readseek map output");
-  const output = value;
-  const symbols = output.symbols;
-  if (!Array.isArray(symbols))
-    throw new Error("invalid readseek symbols");
-  return {
-    file: requireString(output.file, "file"),
-    language: requireString(output.language, "language"),
-    line_count: requireNumber(output.line_count, "line_count"),
-    file_hash: requireString(output.file_hash, "file_hash"),
-    symbols: symbols.map((symbol) => {
-      if (!symbol || typeof symbol !== "object")
-        throw new Error("invalid readseek symbol");
-      const item = symbol;
-      return {
-        kind: requireString(item.kind, "symbol.kind"),
-        name: requireString(item.name, "symbol.name"),
-        qualified_name: requireString(item.qualified_name, "symbol.qualified_name"),
-        start_line: requireNumber(item.start_line, "symbol.start_line"),
-        end_line: requireNumber(item.end_line, "symbol.end_line"),
-        start_hash: requireString(item.start_hash, "symbol.start_hash"),
-        end_hash: requireString(item.end_hash, "symbol.end_hash")
-      };
-    })
-  };
+  return parse2(MapOutput, value, "map output");
 }
 function parseSearchOutput(value) {
-  if (!value || typeof value !== "object")
-    throw new Error("invalid readseek search output");
-  const output = value;
-  if (!Array.isArray(output.results))
-    throw new Error("invalid readseek search results");
-  return output.results.map((result) => {
-    if (!result || typeof result !== "object")
-      throw new Error("invalid readseek search result");
-    const file = result;
-    if (!Array.isArray(file.matches))
-      throw new Error("invalid readseek search matches");
-    return {
-      file: requireString(file.file, "search.file"),
-      language: requireString(file.language, "search.language"),
-      file_hash: requireString(file.file_hash, "search.file_hash"),
-      matches: file.matches.map((match) => {
-        if (!match || typeof match !== "object")
-          throw new Error("invalid readseek search match");
-        const item = match;
-        if (!Array.isArray(item.captures))
-          throw new Error("invalid readseek search captures");
-        return {
-          pattern_index: item.pattern_index === undefined ? 0 : requireNumber(item.pattern_index, "search.match.pattern_index"),
-          start_line: requireNumber(item.start_line, "search.match.start_line"),
-          end_line: requireNumber(item.end_line, "search.match.end_line"),
-          start_hash: requireString(item.start_hash, "search.match.start_hash"),
-          end_hash: requireString(item.end_hash, "search.match.end_hash"),
-          hashlines: parseSearchHashlines(item.hashlines, "search.match.hashlines"),
-          captures: item.captures.map((capture) => {
-            if (!capture || typeof capture !== "object")
-              throw new Error("invalid readseek search capture");
-            const captureItem = capture;
-            return {
-              name: requireString(captureItem.name, "search.capture.name"),
-              start_line: requireNumber(captureItem.start_line, "search.capture.start_line"),
-              end_line: requireNumber(captureItem.end_line, "search.capture.end_line"),
-              start_hash: requireString(captureItem.start_hash, "search.capture.start_hash"),
-              end_hash: requireString(captureItem.end_hash, "search.capture.end_hash"),
-              hashlines: parseSearchHashlines(captureItem.hashlines, "search.capture.hashlines")
-            };
-          })
-        };
-      })
-    };
-  });
+  const envelope = parse2(SearchEnvelope, value, "search output");
+  const results = envelope.results;
+  if (envelope.returned_matches !== undefined)
+    results.returned_matches = envelope.returned_matches;
+  if (envelope.truncated !== undefined)
+    results.truncated = envelope.truncated;
+  if (envelope.byte_basis !== undefined)
+    results.byte_basis = envelope.byte_basis;
+  return results;
 }
 function parseRefsOutput(value) {
-  if (!value || typeof value !== "object")
-    throw new Error("invalid readseek refs output");
-  const output = value;
-  if (!Array.isArray(output.references))
-    throw new Error("invalid readseek references");
-  return output.references.map((reference) => {
-    if (!reference || typeof reference !== "object")
-      throw new Error("invalid readseek reference");
-    const item = reference;
-    const symbol = item.symbol;
-    const enclosing = symbol && typeof symbol === "object" ? optionalString(symbol.qualified_name, "reference.symbol.qualified_name") : undefined;
-    return {
-      file: requireString(item.file, "reference.file"),
-      line: requireNumber(item.line, "reference.line"),
-      column: requireNumber(item.column, "reference.column"),
-      line_hash: requireString(item.line_hash, "reference.line_hash"),
-      text: requireString(item.text, "reference.text"),
-      enclosingSymbol: enclosing
-    };
-  });
-}
-function parseDiagnosticKind(value) {
-  if (value === "error" || value === "missing")
-    return value;
-  throw new Error("invalid readseek diagnostic.kind");
+  return parse2(RefsEnvelope, value, "refs output").references.map(({ symbol, ...reference }) => ({
+    ...reference,
+    enclosingSymbol: symbol?.qualified_name
+  }));
 }
 function parseCheckOutput(value) {
-  if (!value || typeof value !== "object")
-    throw new Error("invalid readseek check output");
-  const output = value;
-  if (!Array.isArray(output.diagnostics))
-    throw new Error("invalid readseek diagnostics");
+  const output = parse2(CheckEnvelope, value, "check output");
   return {
-    file_hash: optionalString(output.file_hash, "file_hash"),
-    errorCount: requireNumber(output.error_count, "error_count"),
-    missingCount: requireNumber(output.missing_count, "missing_count"),
-    diagnostics: output.diagnostics.map((diagnostic) => {
-      if (!diagnostic || typeof diagnostic !== "object")
-        throw new Error("invalid readseek diagnostic");
-      const item = diagnostic;
-      return {
-        kind: parseDiagnosticKind(item.kind),
-        start_line: requireNumber(item.start_line, "diagnostic.start_line"),
-        end_line: requireNumber(item.end_line, "diagnostic.end_line")
-      };
-    })
+    file_hash: output.file_hash,
+    errorCount: output.error_count,
+    missingCount: output.missing_count,
+    diagnostics: output.diagnostics
   };
 }
-function parseDetectedObjects(value) {
-  if (value === undefined || value === null)
-    return;
-  if (!Array.isArray(value))
-    throw new Error("invalid readseek detect objects");
-  return value.map((object) => {
-    if (!object || typeof object !== "object")
-      throw new Error("invalid readseek detect object");
-    const item = object;
-    const bbox = item.bbox;
-    if (!Array.isArray(bbox) || bbox.length !== 4)
-      throw new Error("invalid readseek detect object.bbox");
-    return {
-      label: requireString(item.label, "object.label"),
-      bbox: bbox.map((n, i) => requireNumber(n, `object.bbox[${i}]`))
-    };
-  });
-}
-function parseImageEncoding(value) {
-  if (value === "base64")
-    return value;
-  throw new Error("invalid image encoding");
-}
 function parseDetectOutput(value) {
-  if (!value || typeof value !== "object")
-    throw new Error("invalid readseek detect output");
-  const output = value;
-  const type = requireString(output.type, "type");
-  const file = requireString(output.file, "file");
-  const mime = optionalString(output.mime, "mime");
-  if (type === "application/pdf") {
-    if (output.format !== "pdf")
-      throw new Error("invalid readseek PDF format");
-    return {
-      kind: "pdf",
-      type,
-      file,
-      mime,
-      format: output.format,
-      pages: requireNumber(output.pages, "pages")
-    };
+  const output = value ?? {};
+  if (output.type === "application/pdf") {
+    return { kind: "pdf", ...parse2(PdfDetectionInput, value, "detect output") };
   }
   if (output.width !== undefined || output.height !== undefined) {
-    return {
-      kind: "image",
-      type,
-      file,
-      mime,
-      format: requireString(output.format, "format"),
-      width: requireNumber(output.width, "width"),
-      height: requireNumber(output.height, "height"),
-      animated: requireBoolean(output.animated, "animated"),
-      encoding: output.encoding === undefined ? undefined : parseImageEncoding(output.encoding),
-      data: output.data === undefined ? undefined : requireString(output.data, "data"),
-      ocr: optionalString(output.ocr, "ocr"),
-      caption: optionalString(output.caption, "caption"),
-      objects: parseDetectedObjects(output.objects)
-    };
+    return { kind: "image", ...parse2(ImageDetectionInput, value, "detect output") };
   }
   if (output.language !== undefined) {
-    return {
-      kind: "source",
-      type,
-      file,
-      language: requireString(output.language, "language"),
-      engine: optionalString(output.engine, "engine"),
-      supported: requireBoolean(output.supported, "supported"),
-      mime,
-      syntax: optionalString(output.syntax, "syntax")
-    };
+    return { kind: "source", ...parse2(SourceDetectionInput, value, "detect output") };
   }
-  return { kind: "text", type, file, mime };
-}
-function parseDocumentCache(value) {
-  if (!value || typeof value !== "object")
-    throw new Error("invalid readseek document cache");
-  const cache = value;
-  const state = requireString(cache.state, "cache.state");
-  if (state !== "built" && state !== "reused")
-    throw new Error("invalid readseek cache.state");
-  return {
-    content_hash: requireString(cache.content_hash, "cache.content_hash"),
-    state
-  };
-}
-function parseIdentifyOutput(value) {
-  if (!value || typeof value !== "object")
-    throw new Error("invalid readseek identify output");
-  const output = value;
-  const identifier = output.identifier;
-  const symbol = output.symbol;
-  return {
-    file: requireString(output.file, "file"),
-    language: requireString(output.language, "language"),
-    engine: optionalString(output.engine, "engine"),
-    line_count: requireNumber(output.line_count, "line_count"),
-    file_hash: requireString(output.file_hash, "file_hash"),
-    line: requireNumber(output.line, "line"),
-    column: requireNumber(output.column, "column"),
-    line_hash: requireString(output.line_hash, "line_hash"),
-    identifier: identifier && typeof identifier === "object" ? {
-      text: requireString(identifier.text, "identifier.text"),
-      start_column: requireNumber(identifier.start_column, "identifier.start_column"),
-      end_column: requireNumber(identifier.end_column, "identifier.end_column"),
-      start_byte: requireNumber(identifier.start_byte, "identifier.start_byte"),
-      end_byte: requireNumber(identifier.end_byte, "identifier.end_byte")
-    } : undefined,
-    symbol: symbol && typeof symbol === "object" ? {
-      name: requireString(symbol.name, "symbol.name"),
-      kind: requireString(symbol.kind, "symbol.kind"),
-      qualified_name: requireString(symbol.qualified_name, "symbol.qualified_name"),
-      start_line: requireNumber(symbol.start_line, "symbol.start_line"),
-      end_line: requireNumber(symbol.end_line, "symbol.end_line")
-    } : undefined
-  };
+  return { kind: "text", ...parse2(TextDetectionInput, value, "detect output") };
 }
 function parseImageContent(value) {
   const detection = parseDetectOutput(value);
   if (detection.kind !== "image")
-    throw new Error("invalid readseek image content");
+    throw new Error("invalid readseek image content: expected an image");
   return detection;
 }
 function parseTextContent(value) {
+  const output = value ?? {};
+  if (output.hashlines === undefined || output.start_line !== undefined)
+    return parseReadOutput(value);
+  const spanned = parse2(UnspannedContent, value, "content");
+  return {
+    ...spanned,
+    start_line: spanned.hashlines[0]?.line ?? 1,
+    end_line: spanned.hashlines[spanned.hashlines.length - 1]?.line ?? 0
+  };
+}
+function parseDocumentCache(value) {
+  return parse2(DocumentCache, value, "document cache");
+}
+function parseIdentifyOutput(value) {
+  return parse2(IdentifyEnvelope, value, "identify output");
+}
+function parsePdfInspectMetadata(value) {
   if (!value || typeof value !== "object")
-    throw new Error("invalid readseek content");
-  const output = value;
-  if (output.hashlines !== undefined && output.start_line === undefined) {
-    const hashlines = parseSearchHashlines(output.hashlines, "content.hashlines");
-    const first = hashlines[0];
-    const last = hashlines[hashlines.length - 1];
-    return {
-      file: requireString(output.file, "file"),
-      language: requireString(output.language, "language"),
-      line_count: requireNumber(output.line_count, "line_count"),
-      file_hash: requireString(output.file_hash, "file_hash"),
-      start_line: first?.line ?? 1,
-      end_line: last?.line ?? 0,
-      hashlines
-    };
+    return;
+  if (value.format !== "pdf")
+    return;
+  const document = parse2(PdfInspectMetadata, value, "inspect metadata");
+  return { kind: "pdf", type: "application/pdf", file: document.source, format: "pdf", pages: document.pages };
+}
+function parseEditOutput(value) {
+  return parse2(EditOutputSchema, value, "edit output");
+}
+function parseRenameOutput(value) {
+  return parse2(RenameOutputSchema, value, "rename output");
+}
+function parseDefOutput(value) {
+  return parse2(DefEnvelope, value, "def output").locations;
+}
+
+// src/client.ts
+function classifyReadSeekFailure(err) {
+  const failure = err;
+  const message = String(failure?.message ?? err);
+  const missing = failure?.code === "ENOENT" || /Cannot find package|Cannot find module|no such file/i.test(message);
+  if (missing) {
+    return { code: "readseek-not-installed", message, hint: "Run npm install to install @jarkkojs/readseek." };
   }
-  return parseReadOutput(value);
+  return { code: "readseek-execution-error", message };
 }
-function parseDigestEnvelope(value) {
+function parseSourceInspectEnvelope(value) {
   if (!value || typeof value !== "object")
-    throw new Error("invalid readseek digest output");
+    throw new Error("invalid readseek inspect output");
   const output = value;
-  if (output.metadata === undefined)
-    throw new Error("invalid readseek digest metadata");
-  const result = {
-    metadata: parseDetectOutput(output.metadata)
-  };
+  const result = {};
+  if (output.metadata !== undefined)
+    result.metadata = parseDetectOutput(output.metadata);
   if (output.cache !== undefined)
     result.cache = parseDocumentCache(output.cache);
   if (output.content !== undefined)
@@ -1585,223 +2030,104 @@ function parseDigestEnvelope(value) {
     result.identity = parseIdentifyOutput(output.identity);
   return result;
 }
-function parseEditOutput(value) {
-  if (!value || typeof value !== "object")
-    throw new Error("invalid readseek edit output");
-  const output = value;
-  return {
-    file: requireString(output.file, "file"),
-    before_hash: requireString(output.before_hash, "before_hash"),
-    file_hash: requireString(output.file_hash, "file_hash"),
-    plan_hash: requireString(output.plan_hash, "plan_hash"),
-    applied: requireBoolean(output.applied, "applied"),
-    changed: requireBoolean(output.changed, "changed"),
-    edit_count: requireNumber(output.edit_count, "edit_count"),
-    before_content: optionalString(output.before_content, "before_content"),
-    content: optionalString(output.content, "content")
-  };
-}
-function parseRenameConflicts(value, field) {
-  if (value === undefined)
-    return [];
-  if (!Array.isArray(value))
-    throw new Error(`invalid readseek ${field}`);
-  return value.map((item) => {
-    if (!item || typeof item !== "object")
-      throw new Error(`invalid readseek ${field} entry`);
-    const c = item;
-    return {
-      line: requireNumber(c.line, `${field}.line`),
-      column: requireNumber(c.column, `${field}.column`),
-      reason: requireString(c.reason, `${field}.reason`)
-    };
-  });
-}
-function parseRenameEdits(value, field) {
-  if (value === undefined)
-    return [];
-  if (!Array.isArray(value))
-    throw new Error(`invalid readseek ${field} entry`);
-  return value.map((item) => {
-    if (!item || typeof item !== "object")
-      throw new Error(`invalid readseek ${field} entry`);
-    const e = item;
-    return {
-      line: requireNumber(e.line, `${field}.line`),
-      start_column: requireNumber(e.start_column, `${field}.start_column`),
-      end_column: requireNumber(e.end_column, `${field}.end_column`),
-      start_byte: requireNumber(e.start_byte, `${field}.start_byte`),
-      end_byte: requireNumber(e.end_byte, `${field}.end_byte`),
-      occurrence: requireString(e.occurrence, `${field}.occurrence`),
-      line_hash: requireString(e.line_hash, `${field}.line_hash`),
-      text: requireString(e.text, `${field}.text`)
-    };
-  });
-}
-function parseRenameOutput(value) {
-  if (!value || typeof value !== "object")
-    throw new Error("invalid readseek rename output");
-  const output = value;
-  const others = output.others;
-  if (others !== undefined && !Array.isArray(others))
-    throw new Error("invalid readseek others");
-  return {
-    file: requireString(output.file, "file"),
-    language: requireString(output.language, "language"),
-    engine: optionalString(output.engine, "engine"),
-    file_hash: requireString(output.file_hash, "file_hash"),
-    old_name: requireString(output.old_name, "old_name"),
-    new_name: requireString(output.new_name, "new_name"),
-    applied: requireBoolean(output.applied, "applied"),
-    conflicts: parseRenameConflicts(output.conflicts, "conflicts"),
-    edits: parseRenameEdits(output.edits, "edits"),
-    others: others?.map((entry) => {
-      if (!entry || typeof entry !== "object")
-        throw new Error("invalid readseek other");
-      const o = entry;
-      return {
-        file: requireString(o.file, "other.file"),
-        language: requireString(o.language, "other.language"),
-        engine: optionalString(o.engine, "other.engine"),
-        file_hash: requireString(o.file_hash, "other.file_hash"),
-        conflicts: parseRenameConflicts(o.conflicts, "other.conflicts"),
-        edits: parseRenameEdits(o.edits, "other.edits")
-      };
-    }) ?? []
-  };
-}
-function parseDefCompact(value) {
-  if (!value || typeof value !== "object")
-    throw new Error("invalid readseek def output");
-  const output = value;
-  const locations = output.locations;
-  if (!Array.isArray(locations))
-    throw new Error("invalid readseek def locations");
-  return locations.map((loc) => {
-    if (!loc || typeof loc !== "object")
-      throw new Error("invalid readseek def location");
-    const item = loc;
-    return {
-      file: requireString(item.file, "location.file"),
-      line: requireNumber(item.line, "location.line"),
-      column: requireNumber(item.column, "location.column"),
-      line_hash: requireString(item.line_hash, "location.line_hash"),
-      text: requireString(item.text, "location.text"),
-      kind: optionalString(item.kind, "location.kind"),
-      name: optionalString(item.name, "location.name"),
-      qualified_name: optionalString(item.qualified_name, "location.qualified_name")
-    };
-  });
-}
 function createReadSeekClient(runner) {
-  function digestArgs(target, options) {
-    return buildDigestArgs({
+  function inspectArgs(target, options) {
+    return buildInspectArgs({
       path: target,
+      selector: options.selector,
       select: options.select ?? "content",
-      at: options.at,
+      query: options.query,
       end: options.end,
       limit: options.limit,
+      depth: options.depth,
       language: options.language,
       visionMode: options.visionMode,
       visionLevel: options.visionLevel,
-      stdinName: options.stdin !== undefined && target === "-" ? options.stdinName ?? target : undefined
+      stdinName: options.stdinName
     });
   }
-  async function runDigestRaw(target, options = {}) {
-    const args = digestArgs(target, options);
-    const runOptions = {
+  function inspectRunOptions(options) {
+    return {
       signal: options.signal,
       stdin: options.stdin,
       timeoutMs: options.timeoutMs,
       vision: options.vision
     };
-    return runner.json(args, runOptions);
   }
-  async function digest(target, options = {}) {
-    return parseDigestEnvelope(await runDigestRaw(target, options));
+  async function inspect(target, options = {}) {
+    return runner.kdl(inspectArgs(target, options), inspectRunOptions(options));
+  }
+  async function inspectText(target, options = {}) {
+    return runner.text(inspectArgs(target, options), inspectRunOptions(options));
   }
-  function requireDigestContent(envelope, field) {
+  async function inspectSource(target, options = {}) {
+    return parseSourceInspectEnvelope(await inspect(target, options));
+  }
+  function requireInspectMetadata(envelope, field) {
+    if (envelope.metadata === undefined)
+      throw new Error(`invalid readseek ${field}: missing metadata`);
+    return envelope.metadata;
+  }
+  function requireInspectContent(envelope, field) {
     if (envelope.content === undefined)
       throw new Error(`invalid readseek ${field}: missing content`);
     return envelope.content;
   }
-  async function digestContent(filePath, options = {}) {
-    const envelope = await digest(filePath, {
-      select: "content",
-      at: options.startLine !== undefined ? buildLineLocation(options.startLine) : undefined,
+  async function inspectContent(filePath, options = {}) {
+    const inspected = await inspect(filePath, {
+      select: ["metadata", "content"],
+      selector: options.startLine !== undefined ? buildLineLocation(options.startLine) : undefined,
       end: options.endLine,
       visionMode: options.visionMode,
       signal: options.signal,
       vision: options.vision
     });
-    if (envelope.metadata.kind === "pdf") {
-      return { metadata: envelope.metadata, cache: envelope.cache };
+    const pdf = parsePdfInspectMetadata(inspected);
+    if (pdf)
+      return { metadata: pdf };
+    const envelope = parseSourceInspectEnvelope(inspected);
+    const metadata = requireInspectMetadata(envelope, "content");
+    const content = requireInspectContent(envelope, "content");
+    if (metadata.kind === "image") {
+      return { metadata, image: parseImageContent(content) };
     }
-    const content = requireDigestContent(envelope, "content");
-    if (envelope.metadata.kind === "image") {
-      return { metadata: envelope.metadata, image: parseImageContent(content) };
-    }
-    return { metadata: envelope.metadata, text: parseTextContent(content) };
+    return { metadata, text: parseTextContent(content) };
   }
   return {
-    async view(filePath, options = {}) {
-      const args = buildViewArgs({
-        path: filePath,
-        node: options.node,
-        page: options.page,
-        kind: options.kind,
-        depth: options.depth,
-        outline: options.outline,
-        visionMode: options.visionMode,
-        visionLevel: options.visionLevel
-      });
-      return runner.text(args, {
+    inspect,
+    inspectText,
+    inspectContent,
+    async extract(target, selector, output, options = {}) {
+      await runner.text(buildExtractArgs({
+        path: target,
+        selector,
+        output,
+        stdinName: options.stdinName
+      }), {
         signal: options.signal,
-        vision: options.visionMode !== undefined
+        stdin: options.stdin,
+        timeoutMs: options.timeoutMs,
+        cancelable: options.cancelable
       });
     },
-    digestRaw(target, options = {}) {
-      return runDigestRaw(target, options);
-    },
-    digest,
-    digestContent,
     async image(filePath, modes, options = {}) {
-      const requestedModes = modes.length > 1 ? ["all"] : modes;
-      const results = await Promise.allSettled(requestedModes.map(async (mode) => {
-        const digested = await digestContent(filePath, {
-          visionMode: mode,
-          signal: options.signal,
-          vision: true
-        });
-        if (!digested.image)
-          throw new Error(`readseek returned no image analysis for ${filePath}`);
-        return digested.image;
-      }));
-      let merged;
-      for (const result of results) {
-        if (result.status !== "fulfilled")
-          continue;
-        const detection = result.value;
-        merged = merged === undefined ? detection : {
-          ...merged,
-          ocr: detection.ocr ?? merged.ocr,
-          caption: detection.caption ?? merged.caption,
-          objects: detection.objects ?? merged.objects
-        };
-      }
-      if (merged !== undefined)
-        return merged;
-      const failure = results.find((result) => result.status === "rejected");
-      if (failure?.status === "rejected")
-        throw failure.reason;
-      throw new Error(`readseek returned no image analysis for ${filePath}`);
+      if (modes.length === 0)
+        throw new Error(`readseek returned no image analysis for ${filePath}`);
+      const inspected = await inspectContent(filePath, {
+        visionMode: modes.length > 1 ? "all" : modes[0],
+        signal: options.signal,
+        vision: true
+      });
+      if (!inspected.image)
+        throw new Error(`readseek returned no image analysis for ${filePath}`);
+      return inspected.image;
     },
     async preparedImage(filePath, options = {}) {
-      const digested = await digestContent(filePath, {
+      const inspected = await inspectContent(filePath, {
         visionMode: "none",
         signal: options.signal
       });
-      const output = digested.image;
+      const output = inspected.image;
       if (!output || output.encoding !== "base64" || output.data === undefined || output.mime === undefined) {
         throw new Error(`readseek returned no prepared image for ${filePath}`);
       }
@@ -1813,11 +2139,9 @@ function createReadSeekClient(runner) {
         pattern,
         language: options.language,
         limit: options.limit,
-        cached: options.cached,
-        others: options.others,
-        ignored: options.ignored
+        gitScope: options.gitScope
       });
-      return parseSearchOutput(await runner.json(args, { signal: options.signal }));
+      return parseSearchOutput(await runner.kdl(args, { signal: options.signal }));
     },
     async refs(target, options = {}) {
       const args = buildRefsArgs({
@@ -1827,26 +2151,21 @@ function createReadSeekClient(runner) {
         line: options.line,
         column: options.column,
         language: options.language,
-        cached: options.cached,
-        others: options.others,
-        ignored: options.ignored
+        gitScope: options.gitScope
       });
-      return parseRefsOutput(await runner.json(args, { signal: options.signal }));
+      return parseRefsOutput(await runner.kdl(args, { signal: options.signal }));
     },
     async def(target, options) {
       const args = buildDefArgs({
         path: target,
         name: options.name,
-        format: "plain",
         language: options.language,
-        cached: options.cached,
-        others: options.others,
-        ignored: options.ignored
+        gitScope: options.gitScope
       });
-      return parseDefCompact(await runner.json(args, { signal: options.signal }));
+      return parseDefOutput(await runner.kdl(args, { signal: options.signal }));
     },
     async check(filePath, content, options = {}) {
-      const envelope = await digest("-", {
+      const envelope = await inspectSource("-", {
         select: "diagnostics",
         stdin: content,
         stdinName: filePath,
@@ -1856,12 +2175,12 @@ function createReadSeekClient(runner) {
         throw new Error("invalid readseek diagnostics: missing diagnostics facet");
       return envelope.diagnostics;
     },
-    async identify(filePath, content, options = {}) {
-      const envelope = await digest("-", {
+    async identify(filePath, content, options) {
+      const envelope = await inspectSource("-", {
         select: "identity",
         stdin: content,
         stdinName: filePath,
-        at: options.line !== undefined ? buildLineLocation(options.line, options.column) : undefined,
+        selector: buildLineLocation(options.line, options.column),
         language: options.language,
         signal: options.signal
       });
@@ -1870,8 +2189,11 @@ function createReadSeekClient(runner) {
       return envelope.identity;
     },
     async detect(filePath, options = {}) {
-      const envelope = await digest(filePath, { select: "metadata", signal: options.signal });
-      return envelope.metadata;
+      const inspected = await inspect(filePath, { select: "metadata", signal: options.signal });
+      const pdf = parsePdfInspectMetadata(inspected);
+      if (pdf)
+        return pdf;
+      return requireInspectMetadata(parseSourceInspectEnvelope(inspected), "metadata");
     },
     async edit(filePath, edits, options = {}) {
       const args = buildEditArgs({
@@ -1881,9 +2203,9 @@ function createReadSeekClient(runner) {
         language: options.language,
         requestFromStdin: true
       });
-      return parseEditOutput(await runner.json(args, {
+      return parseEditOutput(await runner.kdl(args, {
         signal: options.signal,
-        stdin: JSON.stringify({ edits }),
+        stdin: serializeEditPlan(edits),
         timeoutMs: options.timeoutMs,
         cancelable: options.cancelable
       }));
@@ -1896,88 +2218,88 @@ function createReadSeekClient(runner) {
         column: options.column,
         workspace: options.workspace,
         apply: options.apply,
+        planHash: options.planHash,
         language: options.language,
-        cached: options.cached,
-        others: options.others,
-        ignored: options.ignored
+        gitScope: options.gitScope
       });
-      return parseRenameOutput(await runner.json(args, { signal: options.signal }));
+      return parseRenameOutput(await runner.kdl(args, { signal: options.signal }));
     }
   };
 }
 export {
-  validateVisionLevelVsMode,
-  validateRefsNameVsScope,
-  validateGitSelection,
-  validateExactlyOneEditVariant,
-  tryParseLineAnchor,
-  runReadSeekNodeText,
-  runReadSeekNodeJson,
-  runReadSeekNode,
-  runReadSeekBunText,
-  runReadSeekBunJson,
-  runReadSeekBun,
-  rewriteBacktickedToolNames,
-  resolveToolName,
-  resolveToCwd,
-  resolveScopedPath,
-  resolveReadSeekCacheDir,
-  resolveReadSeekBinaryOverride,
-  resolveReadSeekBinaryFromPackages,
-  resolveProcessLimits,
-  renderToolRoutingPolicy,
-  renderToolDescription,
-  renderPreferredToolDescription,
-  renderFallbackToolDescription,
-  renderCompactGuidelines,
-  readSeekPlatformKey,
-  readSeekBinaryName,
-  preferredToolDescriptionMap,
-  parseSuccessfulJson,
-  parseReadSeekJson,
-  parseLineAnchor,
-  isSubPath,
-  getToolContract,
-  fallbackToolDescriptionMap,
-  failureFromProcessResult,
-  expandUserPath,
-  ensureSuccessfulStdout,
-  createReadSeekClient,
-  coercePositiveInt,
-  coerceOptionalString,
-  coerceObviousBase10Int,
-  coerceNonNegativeInt,
-  coerceBoolean,
-  cleanReadSeekErrorText,
-  classifyReadSeekFailure,
-  canonicalPathKey,
-  buildViewArgs,
-  buildSearchArgs,
-  buildRenameArgs,
-  buildRefsArgs,
-  buildLineLocation,
-  buildEditArgs,
-  buildDigestArgs,
-  buildDefArgs,
-  appendGitSelectionArgs,
-  appendApplyAndPlanHash,
-  VISION_MODES,
-  VISION_LEVELS,
-  VISION_ANALYSIS_MODES,
-  TOOL_NAMES,
-  TOOL_DESCRIPTIONS,
-  TOOL_CONTRACTS,
-  TOOL_COMPACT_GUIDELINES,
-  REPLACEABLE_TOOLS,
-  READSEEK_PLATFORM_PACKAGES,
-  READSEEK_BINARY_ENV,
-  PARAM_DESCRIPTIONS,
-  HASH_LEN,
-  GIT_SELECTION_FLAGS,
-  EDIT_VARIANTS,
-  DOCUMENT_NODE_KINDS,
-  DIGEST_FACETS,
-  DEFAULT_READSEEK_TIMEOUT_MS,
+  BUILTIN_FALLBACKS,
+  DEFAULT_INSPECT_MAP_DEPTH,
   DEFAULT_MAX_OUTPUT_BYTES,
-  BUILTIN_FALLBACKS
+  DEFAULT_READSEEK_TIMEOUT_MS,
+  EDIT_VARIANTS,
+  GIT_SCOPES,
+  HASH_LEN,
+  INSPECT_FACETS,
+  PARAM_DESCRIPTIONS,
+  READSEEK_BINARY_ENV,
+  READSEEK_PLATFORM_PACKAGES,
+  REPLACEABLE_TOOLS,
+  TOOL_COMPACT_GUIDELINES,
+  TOOL_CONTRACTS,
+  TOOL_DESCRIPTIONS,
+  TOOL_NAMES,
+  VISION_ANALYSIS_MODES,
+  VISION_LEVELS,
+  VISION_MODES,
+  appendApplyAndPlanHash,
+  appendGitScopeArgs,
+  buildDefArgs,
+  buildEditArgs,
+  buildExtractArgs,
+  buildInspectArgs,
+  buildLineLocation,
+  buildRefsArgs,
+  buildRenameArgs,
+  buildSearchArgs,
+  canonicalPathKey,
+  classifyReadSeekFailure,
+  cleanReadSeekErrorText,
+  coerceBoolean,
+  coerceNonNegativeInt,
+  coerceObviousBase10Int,
+  coerceOptionalString,
+  coercePositiveInt,
+  createReadSeekClient,
+  ensureSuccessfulStdout,
+  expandUserPath,
+  failureFromProcessResult,
+  fallbackToolDescriptionMap,
+  getToolContract,
+  isSubPath,
+  parseLineAnchor,
+  parseReadSeekKdl,
+  parseSuccessfulKdl,
+  preferredToolDescriptionMap,
+  readSeekBinaryName,
+  readSeekPlatformKey,
+  readSeekProcessEnvironment,
+  renderCompactGuidelines,
+  renderFallbackToolDescription,
+  renderPreferredToolDescription,
+  renderToolDescription,
+  renderToolRoutingPolicy,
+  resolveProcessLimits,
+  resolveReadSeekBinaryFromPackages,
+  resolveReadSeekBinaryOverride,
+  resolveReadSeekCacheDir,
+  resolveScopedPath,
+  resolveToCwd,
+  resolveToolName,
+  rewriteBacktickedToolNames,
+  runReadSeekBun,
+  runReadSeekBunKdl,
+  runReadSeekBunText,
+  runReadSeekNode,
+  runReadSeekNodeKdl,
+  runReadSeekNodeText,
+  serializeEditPlan,
+  tryParseLineAnchor,
+  validateExactlyOneEditVariant,
+  validateRefsNameVsScope,
+  validateVisionLevelVsMode
 };