@vibe-agent-toolkit/cli 0.1.42 → 0.2.0-rc.10

package/dist/utils/corpus-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"corpus-target.js","sourceRoot":"","sources":["../../src/utils/corpus-target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE1E;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,OAA2B,EAC3B,WAAmB;IAEnB,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,IAAI,GAAG,CAAC,CAAC,CAAC;IAC1F,IAAI,mBAAmB,CAAC,QAAQ,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CACb,GAAG,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,qCAAqC,IAAI,GAAG;cACrE,IAAI,WAAW,yDAAyD;cACxE,wDAAwD,CAC3D,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/utils/edge-lens-evaluation.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Evaluating the authored-link lens over a populated projection, so SQL can ask
+ * about edges.
+ *
+ * ## Why the CLI does this rather than the population
+ *
+ * `edges` and `edge_resolutions` are derived per lens, and the set of lenses is
+ * not known at population time — zones.md §2: *"A lens may be declared in config
+ * **or invented on demand** to answer a question nobody anticipated."* So a
+ * population cannot produce them without first inventing the lens, which is a
+ * question, not a fact. Inventing one here costs a definition and a pass over
+ * rows already in memory; it commits the data model to nothing, and the rows go
+ * into the per-run in-memory database that `projection-query.ts` guarantees
+ * holds this tree and nothing else.
+ *
+ * ## One lens per extent, and the extent is the thing worth naming
+ *
+ * A corpus has more than one extent — this repository has two, `filesystem`
+ * (the tracked tree) and `agentic-convention` (the CLAUDE.md closure) — and an
+ * edge relation over one is a different relation from an edge relation over the
+ * other. Evaluating every extent and keying the rows on the lens's own
+ * `contextId` means a caller SELECTs the population they meant, rather than
+ * silently getting whichever one happened to be evaluated. `lens_contexts` says
+ * which lenses exist and which extent each reads over, so the join is
+ * discoverable from SQL alone.
+ *
+ * ⚠️ **Only `species: 'extent'` rows are read over.** A lens over a lens is not
+ * a thing this evaluation models, and `resolution_contexts` holds no lens rows
+ * anyway — nothing in the population mints one. The filter is there so that
+ * stops being true loudly rather than silently if something ever does.
+ */
+import { type Projection, type ResolutionContextRow } from '@vibe-agent-toolkit/resources';
+/**
+ * The rows one sweep of the corpus produced, ready for `writeDerived`.
+ *
+ * 🪤 **The three field names must be `DERIVED_TABLES`' own keys, and nothing
+ * used to check that.** `writeDerived` looks each relation up by
+ * `bundle[spec.key]`, and every member of `DerivedRows` is optional — so
+ * renaming a derived relation left this interface spelling the OLD name, which
+ * type-checked cleanly as a tolerated excess property while the renamed
+ * relation was silently never written. Verified: the rename compiled with zero
+ * errors under `--strict`.
+ *
+ * The `satisfies` below is what makes the correspondence real rather than a
+ * coincidence of spelling — a renamed relation now fails to compile here.
+ */
+export interface EvaluatedLenses {
+    readonly lensContexts: readonly ResolutionContextRow[];
+    readonly edges: readonly Record<string, unknown>[];
+    readonly edgeResolutions: readonly Record<string, unknown>[];
+}
+/**
+ * Every key of {@link EvaluatedLenses} names a real derived relation.
+ *
+ * A compile-time assertion with no runtime cost beyond one frozen object: it
+ * pins the field names of `EvaluatedLenses` to `DerivedTableName`, which is
+ * the correspondence `writeDerived` depends on and cannot express itself.
+ */
+export declare const EVALUATED_LENS_RELATIONS: {
+    readonly lensContexts: true;
+    readonly edges: true;
+    readonly edgeResolutions: true;
+};
+/**
+ * Evaluate the authored-link lens over every extent in a projection.
+ *
+ * @param projection - A populated projection
+ * @returns The lens rows and the two relations, in step with each other
+ */
+export declare function evaluateAuthoredLenses(projection: Projection): EvaluatedLenses;
+/**
+ * The lens id for one extent's authored-link view.
+ *
+ * Derived from the extent's own id rather than minted fresh, so the same tree
+ * produces the same lens id on every run and a reader can predict it. It is
+ * NOT a digest: nothing here needs collision resistance, and a readable id is
+ * what makes `WHERE contextId = …` writable by hand.
+ *
+ * @param extentContextId - The extent this lens reads over
+ * @returns The lens's `contextId`
+ */
+export declare function authoredLensId(extentContextId: string): string;
+//# sourceMappingURL=edge-lens-evaluation.d.ts.map

package/dist/utils/edge-lens-evaluation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-lens-evaluation.d.ts","sourceRoot":"","sources":["../../src/utils/edge-lens-evaluation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAKL,KAAK,UAAU,EACf,KAAK,oBAAoB,EAC1B,MAAM,+BAA+B,CAAC;AAavC;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,YAAY,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACvD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACnD,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;CAC9D;AAED;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB;;;;CAEqE,CAAC;AAE3G;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,UAAU,GAAG,eAAe,CAsC9E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAE9D"}

package/dist/utils/edge-lens-evaluation.js

@@ -0,0 +1,110 @@
+/**
+ * Evaluating the authored-link lens over a populated projection, so SQL can ask
+ * about edges.
+ *
+ * ## Why the CLI does this rather than the population
+ *
+ * `edges` and `edge_resolutions` are derived per lens, and the set of lenses is
+ * not known at population time — zones.md §2: *"A lens may be declared in config
+ * **or invented on demand** to answer a question nobody anticipated."* So a
+ * population cannot produce them without first inventing the lens, which is a
+ * question, not a fact. Inventing one here costs a definition and a pass over
+ * rows already in memory; it commits the data model to nothing, and the rows go
+ * into the per-run in-memory database that `projection-query.ts` guarantees
+ * holds this tree and nothing else.
+ *
+ * ## One lens per extent, and the extent is the thing worth naming
+ *
+ * A corpus has more than one extent — this repository has two, `filesystem`
+ * (the tracked tree) and `agentic-convention` (the CLAUDE.md closure) — and an
+ * edge relation over one is a different relation from an edge relation over the
+ * other. Evaluating every extent and keying the rows on the lens's own
+ * `contextId` means a caller SELECTs the population they meant, rather than
+ * silently getting whichever one happened to be evaluated. `lens_contexts` says
+ * which lenses exist and which extent each reads over, so the join is
+ * discoverable from SQL alone.
+ *
+ * ⚠️ **Only `species: 'extent'` rows are read over.** A lens over a lens is not
+ * a thing this evaluation models, and `resolution_contexts` holds no lens rows
+ * anyway — nothing in the population mints one. The filter is there so that
+ * stops being true loudly rather than silently if something ever does.
+ */
+import { AUTHORED_EDGE_FORMS, buildReferenceIndex, resolveEdges, } from '@vibe-agent-toolkit/resources';
+/**
+ * The lens kind these evaluations declare.
+ *
+ * `ZoneKindSchema` is an open vocabulary, so this names the POLICY rather than
+ * the mechanism: what makes two of these lenses the same is that both admit the
+ * authored forms and nothing else. A lens that promoted bare tokens would be a
+ * different kind, not a variant of this one, because the two answer differently
+ * by an order of magnitude and a reader comparing them must be able to tell.
+ */
+const AUTHORED_LENS_KIND = 'authored-link';
+/**
+ * Every key of {@link EvaluatedLenses} names a real derived relation.
+ *
+ * A compile-time assertion with no runtime cost beyond one frozen object: it
+ * pins the field names of `EvaluatedLenses` to `DerivedTableName`, which is
+ * the correspondence `writeDerived` depends on and cannot express itself.
+ */
+export const EVALUATED_LENS_RELATIONS = {
+    lensContexts: true, edges: true, edgeResolutions: true,
+};
+/**
+ * Evaluate the authored-link lens over every extent in a projection.
+ *
+ * @param projection - A populated projection
+ * @returns The lens rows and the two relations, in step with each other
+ */
+export function evaluateAuthoredLenses(projection) {
+    const lensContexts = [];
+    const edges = [];
+    const edgeResolutions = [];
+    // Built ONCE for every lens. It is a pure function of `blob_references` and
+    // reads nothing from a lens, so rebuilding it per extent is duplicated work a
+    // one-member extent would pay in full — 43 ms at one extent against 713 ms at
+    // ten, measured on this repository.
+    const referencesByBlob = buildReferenceIndex(projection);
+    for (const context of projection.resolutionContexts) {
+        if (context.species !== 'extent')
+            continue;
+        const contextId = authoredLensId(context.contextId);
+        lensContexts.push({
+            contextId,
+            species: 'lens',
+            kind: AUTHORED_LENS_KIND,
+            rootId: context.rootId,
+            extentContextId: context.contextId,
+            // Null because this lens's kind is not `tree`; the schema refuses a role
+            // on any other kind, which is that check doing its job rather than a
+            // field being forgotten.
+            role: null,
+        });
+        const relation = resolveEdges(projection, {
+            contextId,
+            extentContextId: context.contextId,
+            forms: AUTHORED_EDGE_FORMS,
+            // Ordinary markdown. `claude-import` is the other dialect and belongs to
+            // the `@`-import forms, which the authored-only policy does not admit.
+            dialect: 'href',
+        }, { referencesByBlob });
+        edges.push(...relation.edges);
+        edgeResolutions.push(...relation.edgeResolutions);
+    }
+    return { lensContexts, edges, edgeResolutions };
+}
+/**
+ * The lens id for one extent's authored-link view.
+ *
+ * Derived from the extent's own id rather than minted fresh, so the same tree
+ * produces the same lens id on every run and a reader can predict it. It is
+ * NOT a digest: nothing here needs collision resistance, and a readable id is
+ * what makes `WHERE contextId = …` writable by hand.
+ *
+ * @param extentContextId - The extent this lens reads over
+ * @returns The lens's `contextId`
+ */
+export function authoredLensId(extentContextId) {
+    return `lens-${AUTHORED_LENS_KIND}-${extentContextId}`;
+}
+//# sourceMappingURL=edge-lens-evaluation.js.map

package/dist/utils/edge-lens-evaluation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-lens-evaluation.js","sourceRoot":"","sources":["../../src/utils/edge-lens-evaluation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,YAAY,GAIb,MAAM,+BAA+B,CAAC;AAEvC;;;;;;;;GAQG;AACH,MAAM,kBAAkB,GAAG,eAAe,CAAC;AAsB3C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,YAAY,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI;CACkD,CAAC;AAE3G;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,UAAsB;IAC3D,MAAM,YAAY,GAA2B,EAAE,CAAC;IAChD,MAAM,KAAK,GAA8B,EAAE,CAAC;IAC5C,MAAM,eAAe,GAA8B,EAAE,CAAC;IAEtD,4EAA4E;IAC5E,8EAA8E;IAC9E,8EAA8E;IAC9E,oCAAoC;IACpC,MAAM,gBAAgB,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAC;IAEzD,KAAK,MAAM,OAAO,IAAI,UAAU,CAAC,kBAAkB,EAAE,CAAC;QACpD,IAAI,OAAO,CAAC,OAAO,KAAK,QAAQ;YAAE,SAAS;QAC3C,MAAM,SAAS,GAAG,cAAc,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACpD,YAAY,CAAC,IAAI,CAAC;YAChB,SAAS;YACT,OAAO,EAAE,MAAM;YACf,IAAI,EAAE,kBAAkB;YACxB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,eAAe,EAAE,OAAO,CAAC,SAAS;YAClC,yEAAyE;YACzE,qEAAqE;YACrE,yBAAyB;YACzB,IAAI,EAAE,IAAI;SACX,CAAC,CAAC;QACH,MAAM,QAAQ,GAAG,YAAY,CAAC,UAAU,EAAE;YACxC,SAAS;YACT,eAAe,EAAE,OAAO,CAAC,SAAS;YAClC,KAAK,EAAE,mBAAmB;YAC1B,yEAAyE;YACzE,uEAAuE;YACvE,OAAO,EAAE,MAAM;SAChB,EAAE,EAAE,gBAAgB,EAAE,CAAC,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC9B,eAAe,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,eAAe,CAAC,CAAC;IACpD,CAAC;IAED,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC;AAClD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,eAAuB;IACpD,OAAO,QAAQ,kBAAkB,IAAI,eAAe,EAAE,CAAC;AACzD,CAAC"}

package/dist/utils/help-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help-loader.d.ts","sourceRoot":"","sources":["../../src/utils/help-loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAyBxD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEnD"}
+{"version":3,"file":"help-loader.d.ts","sourceRoot":"","sources":["../../src/utils/help-loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAwBxD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEnD"}

package/dist/utils/help-loader.js

@@ -21,7 +21,6 @@ export function loadVerboseHelp(section) {
     const filename = section ? `${section}.md` : 'index.md';
     const helpPath = safePath.join(packageRoot, 'docs', filename);
     try {
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- path is constructed from known safe components
         const content = readFileSync(helpPath, 'utf-8');
         return content;
     }

package/dist/utils/help-loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"help-loader.js","sourceRoot":"","sources":["../../src/utils/help-loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAErD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,mCAAmC;IACnC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,MAAM,WAAW,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAEtD,wCAAwC;IACxC,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC;IACxD,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;IAE9D,IAAI,CAAC;QACH,qHAAqH;QACrH,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAChD,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,sCAAsC;QACtC,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5E,OAAO;;0BAEe,QAAQ;;EAEhC,YAAY;;;CAGb,CAAC;IACA,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,eAAe,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;AACrE,CAAC"}
+{"version":3,"file":"help-loader.js","sourceRoot":"","sources":["../../src/utils/help-loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAErD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,mCAAmC;IACnC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,MAAM,WAAW,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAEtD,wCAAwC;IACxC,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC;IACxD,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;IAE9D,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAChD,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,sCAAsC;QACtC,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5E,OAAO;;0BAEe,QAAQ;;EAEhC,YAAY;;;CAGb,CAAC;IACA,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,eAAe,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;AACrE,CAAC"}

package/dist/utils/issue-anchor.d.ts

@@ -2,13 +2,13 @@
  * Rendering for the four `ValidationIssue` anchors.
  *
  * `location` / `line` / `field` are independent fields on the issue (see the
- * anchor contract on `ValidationIssue` in `@vibe-agent-toolkit/agent-schema`).
+ * anchor contract on `ValidationIssue` in `@vibe-agent-toolkit/schema`).
  * Splitting them apart in the producers only pays off if the renderers put
  * them back together — a `line` that no output surface prints is a `line` that,
  * from the user's side, was deleted. This is the one place that join happens,
  * so every command spells an anchor the same way.
  */
-import type { ValidationIssue } from '@vibe-agent-toolkit/agent-schema';
+import type { ValidationIssue } from '@vibe-agent-toolkit/schema';
 /**
  * Render an issue's anchor as a single human/tool-readable string.
  *

package/dist/utils/issue-anchor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"issue-anchor.d.ts","sourceRoot":"","sources":["../../src/utils/issue-anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAExE;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAe5E"}
+{"version":3,"file":"issue-anchor.d.ts","sourceRoot":"","sources":["../../src/utils/issue-anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAe5E"}

package/dist/utils/issue-anchor.js

@@ -2,7 +2,7 @@
  * Rendering for the four `ValidationIssue` anchors.
  *
  * `location` / `line` / `field` are independent fields on the issue (see the
- * anchor contract on `ValidationIssue` in `@vibe-agent-toolkit/agent-schema`).
+ * anchor contract on `ValidationIssue` in `@vibe-agent-toolkit/schema`).
  * Splitting them apart in the producers only pays off if the renderers put
  * them back together — a `line` that no output surface prints is a `line` that,
  * from the user's side, was deleted. This is the one place that join happens,

package/dist/utils/issue-rendering.d.ts

@@ -15,8 +15,8 @@
  * passed"). That is why none of it was ever reported — it produces silence, not
  * a false alarm.
  */
-import { type SeverityCounts, type ValidationIssue } from '@vibe-agent-toolkit/agent-schema';
 import type { PackageSkillResult } from '@vibe-agent-toolkit/agent-skills';
+import { type SeverityCounts, type ValidationIssue } from '@vibe-agent-toolkit/schema';
 /** Render an issue's own severity as itself. */
 export declare function severityLabel(severity: ValidationIssue['severity']): string;
 /**
@@ -177,8 +177,8 @@ export declare function formatCollapsedFindingsHint(collapsed: number, report: s
  * is not: `files.dependencies` carries only what the link-graph walk discovered, so
  * every file `files:` copied in — each glob match, plus any explicit entry the walk
  * had not already bundled — is absent from the total. A bundle holding SKILL.md, one
- * linked doc and one declared artifact prints `2 files`. That undercount is issue
- * #177 and is deliberately NOT patched here; this wording is only the part that can
+ * linked doc and one declared artifact prints `2 files`. That undercount is a
+ * report-shape defect and is deliberately NOT patched here; this wording is only the part that can
  * be made true today, so nobody reads the number as an inventory of the output.
  *
  * The `+ 1` is the bundle's root `SKILL.md`, which `files.dependencies` does not

package/dist/utils/issue-rendering.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"issue-rendering.d.ts","sourceRoot":"","sources":["../../src/utils/issue-rendering.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAiB3E,gDAAgD;AAChD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,eAAe,CAAC,UAAU,CAAC,GAAG,MAAM,CAE3E;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAYtE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,IAAI,CAAC,EAAE,MAAM,GACZ,MAAM,CAKR;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,SAAK,GAAG,MAAM,EAAE,CAY9E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,GAAG,MAAM,EAAE,CAUnF;AAcD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,kBAAkB,GAAG,eAAe,EAAE,CAapF;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,GAAG,mBAAmB,CAuBzF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,OAAO,EAAE,OAAO,GACf,SAAS,eAAe,EAAE,CAI5B;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,OAAO,EAAE,OAAO,GACf,MAAM,CAKR;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,MAAM,GAAG,SAAS,CAMpB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAG1E;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,GAAG,cAAc,CASnF"}
+{"version":3,"file":"issue-rendering.d.ts","sourceRoot":"","sources":["../../src/utils/issue-rendering.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AAiBpC,gDAAgD;AAChD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,eAAe,CAAC,UAAU,CAAC,GAAG,MAAM,CAE3E;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAYtE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,IAAI,CAAC,EAAE,MAAM,GACZ,MAAM,CAKR;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,SAAK,GAAG,MAAM,EAAE,CAY9E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,GAAG,MAAM,EAAE,CAUnF;AAcD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,kBAAkB,GAAG,eAAe,EAAE,CAapF;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,GAAG,mBAAmB,CAuBzF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,OAAO,EAAE,OAAO,GACf,SAAS,eAAe,EAAE,CAI5B;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,OAAO,EAAE,OAAO,GACf,MAAM,CAKR;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,MAAM,GAAG,SAAS,CAMpB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAG1E;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,GAAG,cAAc,CASnF"}

package/dist/utils/issue-rendering.js

@@ -15,7 +15,7 @@
  * passed"). That is why none of it was ever reported — it produces silence, not
  * a false alarm.
  */
-import { countBySeverity, } from '@vibe-agent-toolkit/agent-schema';
+import { countBySeverity, } from '@vibe-agent-toolkit/schema';
 import { formatIssueAnchor } from './issue-anchor.js';
 /**
  * Uppercase label for a resolved severity.
@@ -259,8 +259,8 @@ export function formatCollapsedFindingsHint(collapsed, report) {
  * is not: `files.dependencies` carries only what the link-graph walk discovered, so
  * every file `files:` copied in — each glob match, plus any explicit entry the walk
  * had not already bundled — is absent from the total. A bundle holding SKILL.md, one
- * linked doc and one declared artifact prints `2 files`. That undercount is issue
- * #177 and is deliberately NOT patched here; this wording is only the part that can
+ * linked doc and one declared artifact prints `2 files`. That undercount is a
+ * report-shape defect and is deliberately NOT patched here; this wording is only the part that can
  * be made true today, so nobody reads the number as an inventory of the output.
  *
  * The `+ 1` is the bundle's root `SKILL.md`, which `files.dependencies` does not

package/dist/utils/issue-rendering.js.map

@@ -1 +1 @@
-{"version":3,"file":"issue-rendering.js","sourceRoot":"","sources":["../../src/utils/issue-rendering.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"issue-rendering.js","sourceRoot":"","sources":["../../src/utils/issue-rendering.ts"],"names":[],"mappings":"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"}

package/dist/utils/issue-severity.d.ts

@@ -18,11 +18,18 @@
  * findings imports this; nobody writes a fourth copy. Same rule as
  * `resolveAssetReference` and `resolveSkillReference` in CLAUDE.md.
  */
-import { type ValidationIssue } from '@vibe-agent-toolkit/agent-schema';
-/** A `validation.severity` map as it appears in config, or nothing. */
-export interface SeverityOverrides {
-    severity?: Record<string, string> | undefined;
-}
+import { type SeverityConfig, type ValidationIssue } from '@vibe-agent-toolkit/schema';
+/**
+ * A `validation.severity` map as it appears in config, or nothing.
+ *
+ * ⚠️ **Do not re-hand-roll this as `Record<string, string>`.** It was that, and
+ * the key space is now the registry enum PLUS `CUSTOM:<name>` — a `Partial`
+ * mapped type whose values are `SeverityLevel | undefined`. A
+ * `Record<string, string>` is not assignable to it and broke every consumer the
+ * moment the custom key space landed. `SeverityConfig` is the schema's own
+ * `Pick<ValidationConfig, 'severity'>`, so the two cannot drift again.
+ */
+export type SeverityOverrides = SeverityConfig;
 /**
  * Re-severity findings against a `validation.severity` map, dropping the codes
  * resolved to `ignore`.

package/dist/utils/issue-severity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"issue-severity.d.ts","sourceRoot":"","sources":["../../src/utils/issue-severity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAmC,KAAK,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAEzG,uEAAuE;AACvE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;CAC/C;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,UAAU,EAAE,iBAAiB,GAAG,SAAS,GACxC,eAAe,EAAE,CAenB"}
+{"version":3,"file":"issue-severity.d.ts","sourceRoot":"","sources":["../../src/utils/issue-severity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AAEpC;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GAAG,cAAc,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,UAAU,EAAE,iBAAiB,GAAG,SAAS,GACxC,eAAe,EAAE,CAenB"}

package/dist/utils/issue-severity.js

@@ -18,7 +18,7 @@
  * findings imports this; nobody writes a fourth copy. Same rule as
  * `resolveAssetReference` and `resolveSkillReference` in CLAUDE.md.
  */
-import { resolveSeverity } from '@vibe-agent-toolkit/agent-schema';
+import { resolveSeverity, } from '@vibe-agent-toolkit/schema';
 /**
  * Re-severity findings against a `validation.severity` map, dropping the codes
  * resolved to `ignore`.

package/dist/utils/issue-severity.js.map

@@ -1 +1 @@
-{"version":3,"file":"issue-severity.js","sourceRoot":"","sources":["../../src/utils/issue-severity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAkB,eAAe,EAAwB,MAAM,kCAAkC,CAAC;AAOzG;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAkC,EAClC,UAAyC;IAEzC,MAAM,SAAS,GAAG,UAAU,EAAE,QAAQ,CAAC;IACvC,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC;IAEhD,MAAM,QAAQ,GAAsB,EAAE,CAAC;IACvC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,IAAI,SAAS,CAAC,EAAE,CAAC;YAC/B,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACrB,SAAS;QACX,CAAC;QACD,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,CAAC,IAAiB,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC;QACnF,IAAI,QAAQ,KAAK,QAAQ;YAAE,SAAS;QACpC,QAAQ,CAAC,IAAI,CAAC,QAAQ,KAAK,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}
+{"version":3,"file":"issue-severity.js","sourceRoot":"","sources":["../../src/utils/issue-severity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAEL,eAAe,GAGhB,MAAM,4BAA4B,CAAC;AAcpC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAkC,EAClC,UAAyC;IAEzC,MAAM,SAAS,GAAG,UAAU,EAAE,QAAQ,CAAC;IACvC,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC;IAEhD,MAAM,QAAQ,GAAsB,EAAE,CAAC;IACvC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,IAAI,SAAS,CAAC,EAAE,CAAC;YAC/B,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACrB,SAAS;QACX,CAAC;QACD,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,CAAC,IAAiB,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC;QACnF,IAAI,QAAQ,KAAK,QAAQ;YAAE,SAAS;QACpC,QAAQ,CAAC,IAAI,CAAC,QAAQ,KAAK,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/utils/optional-backend.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Lazy loading for **optional heavy backends** — the seam that keeps a
+ * multi-hundred-megabyte dependency out of every other command's cost.
+ *
+ * ## Why this exists rather than four `await import()` calls
+ *
+ * `@vibe-agent-toolkit/rag-lancedb` pulls a platform-native LanceDB binary
+ * (97.8 MB unpacked on `darwin-arm64`, and larger still on `win32-x64`, where
+ * it measured 119.6 MiB) plus `onnxruntime-web` (137.5 MB) and `gpt-tokenizer`
+ * (42.2 MB). Summed over the RAG lane's third-party closure against this
+ * release's pins, on `darwin-arm64`: **~287 MB unpacked**, and a static import
+ * chain from `bin.ts` meant
+ * `import('@lancedb/lancedb')` — **1,350 ms cold** — ran before `vat --version`
+ * could print a string. It is a named seam rather than a one-off fix because
+ * "optional backend" is a shape VAT keeps growing — a projection store is
+ * loaded through it too — not because any one dependency is special.
+ *
+ * ## What it does NOT do
+ *
+ * It does not fall back, retry, or degrade. An absent backend is a legible
+ * error naming the package to install, and nothing more — the point is that
+ * the failure is readable, not that it is survivable.
+ */
+/**
+ * Whether a thrown value is Node's "module not installed" error.
+ *
+ * Exported because every optional backend asks it, and a second copy would be
+ * free to drift onto the message.
+ *
+ * @param error - The thrown value
+ * @returns True when the module could not be resolved at all
+ */
+export declare function isModuleMissing(error: unknown): boolean;
+/**
+ * Report an uninstalled backend and exit, in the shape every other command
+ * failure takes.
+ *
+ * Exit code **2** — a system error, not a validation failure. An absent
+ * optional package is a fact about the installation rather than about the
+ * user's corpus, and a caller scripting `vat` must be able to tell those apart
+ * from the exit code alone.
+ *
+ * Exported for the backends that are not selected by a Commander action —
+ * {@link lazyAction} is the shape most take, but a store chosen by an
+ * environment variable is loaded from inside a command rather than in place of
+ * one, and it must fail the same way.
+ *
+ * @param backend - What to name and how to install it
+ * @returns Never; the process exits
+ */
+export declare function reportMissingBackend(backend: OptionalBackend): never;
+/** One optional backend, as a user is told to install it. */
+export interface OptionalBackend {
+    /** Human name used in the error message, e.g. `RAG`. */
+    readonly feature: string;
+    /** The npm package to install, e.g. `@vibe-agent-toolkit/rag-lancedb`. */
+    readonly packageName: string;
+}
+/**
+ * Bind a Commander action that loads its implementation on first invocation.
+ *
+ * The returned function has the same shape Commander expects, so a command
+ * declaration keeps every option, description and help block it had — only the
+ * *implementation* moves behind the `await`. Help text is static data and must
+ * stay eagerly available, which is exactly why the split is at the action
+ * rather than at the command.
+ *
+ * @param backend - What to name in the error when the import fails to resolve
+ * @param load - Imports the module and returns the handler out of it
+ * @returns A Commander action that loads, then delegates
+ *
+ * @example
+ * ```typescript
+ * .action(lazyAction(RAG_BACKEND, async () => (await import('./index-command.js')).indexCommand))
+ * ```
+ */
+export declare function lazyAction<Args extends readonly unknown[]>(backend: OptionalBackend, load: () => Promise<(...args: Args) => unknown>): (...args: Args) => Promise<void>;
+//# sourceMappingURL=optional-backend.d.ts.map

package/dist/utils/optional-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-backend.d.ts","sourceRoot":"","sources":["../../src/utils/optional-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAoBH;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAOvD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,eAAe,GAAG,KAAK,CAcpE;AAED,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,IAAI,SAAS,SAAS,OAAO,EAAE,EACxD,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,GAC9C,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAalC"}

package/dist/utils/optional-backend.js

@@ -0,0 +1,117 @@
+/**
+ * Lazy loading for **optional heavy backends** — the seam that keeps a
+ * multi-hundred-megabyte dependency out of every other command's cost.
+ *
+ * ## Why this exists rather than four `await import()` calls
+ *
+ * `@vibe-agent-toolkit/rag-lancedb` pulls a platform-native LanceDB binary
+ * (97.8 MB unpacked on `darwin-arm64`, and larger still on `win32-x64`, where
+ * it measured 119.6 MiB) plus `onnxruntime-web` (137.5 MB) and `gpt-tokenizer`
+ * (42.2 MB). Summed over the RAG lane's third-party closure against this
+ * release's pins, on `darwin-arm64`: **~287 MB unpacked**, and a static import
+ * chain from `bin.ts` meant
+ * `import('@lancedb/lancedb')` — **1,350 ms cold** — ran before `vat --version`
+ * could print a string. It is a named seam rather than a one-off fix because
+ * "optional backend" is a shape VAT keeps growing — a projection store is
+ * loaded through it too — not because any one dependency is special.
+ *
+ * ## What it does NOT do
+ *
+ * It does not fall back, retry, or degrade. An absent backend is a legible
+ * error naming the package to install, and nothing more — the point is that
+ * the failure is readable, not that it is survivable.
+ */
+// Deliberately NOT `commands/rag/command-helpers.js`, which is where the rest
+// of the rag lane's shared helpers live: that module statically imports
+// `@vibe-agent-toolkit/rag-lancedb`, so reaching for its `handleCommandError`
+// here would load the very backend this file exists to defer.
+import { ExitCode } from '@vibe-agent-toolkit/schema';
+import { writeYamlOutput } from './output.js';
+/**
+ * Node's code for "the module is genuinely not installed".
+ *
+ * Matched on `code`, never on the message: the message embeds the specifier and
+ * the importing file and is not a stable contract, while the code is. A miss
+ * here would be reported as a missing backend when the real cause was a syntax
+ * error *inside* the backend, which is the worst possible diagnosis.
+ */
+const MODULE_NOT_FOUND = 'ERR_MODULE_NOT_FOUND';
+/**
+ * Whether a thrown value is Node's "module not installed" error.
+ *
+ * Exported because every optional backend asks it, and a second copy would be
+ * free to drift onto the message.
+ *
+ * @param error - The thrown value
+ * @returns True when the module could not be resolved at all
+ */
+export function isModuleMissing(error) {
+    return (typeof error === 'object'
+        && error !== null
+        && 'code' in error
+        && error.code === MODULE_NOT_FOUND);
+}
+/**
+ * Report an uninstalled backend and exit, in the shape every other command
+ * failure takes.
+ *
+ * Exit code **2** — a system error, not a validation failure. An absent
+ * optional package is a fact about the installation rather than about the
+ * user's corpus, and a caller scripting `vat` must be able to tell those apart
+ * from the exit code alone.
+ *
+ * Exported for the backends that are not selected by a Commander action —
+ * {@link lazyAction} is the shape most take, but a store chosen by an
+ * environment variable is loaded from inside a command rather than in place of
+ * one, and it must fail the same way.
+ *
+ * @param backend - What to name and how to install it
+ * @returns Never; the process exits
+ */
+export function reportMissingBackend(backend) {
+    const install = `npm install ${backend.packageName}`;
+    process.stderr.write(`${backend.feature} is an optional feature and its backend is not installed.\n`
+        + `\nInstall it with:  ${install}\n`
+        + '\nIt ships separately because it carries a platform-native binary that every\n'
+        + 'other vat command would otherwise download and load.\n');
+    writeYamlOutput({
+        status: 'error',
+        error: `${backend.feature} backend not installed: ${backend.packageName}`,
+        fix: install,
+    });
+    process.exit(ExitCode.ERROR);
+}
+/**
+ * Bind a Commander action that loads its implementation on first invocation.
+ *
+ * The returned function has the same shape Commander expects, so a command
+ * declaration keeps every option, description and help block it had — only the
+ * *implementation* moves behind the `await`. Help text is static data and must
+ * stay eagerly available, which is exactly why the split is at the action
+ * rather than at the command.
+ *
+ * @param backend - What to name in the error when the import fails to resolve
+ * @param load - Imports the module and returns the handler out of it
+ * @returns A Commander action that loads, then delegates
+ *
+ * @example
+ * ```typescript
+ * .action(lazyAction(RAG_BACKEND, async () => (await import('./index-command.js')).indexCommand))
+ * ```
+ */
+export function lazyAction(backend, load) {
+    return async (...args) => {
+        let handler;
+        try {
+            handler = await load();
+        }
+        catch (error) {
+            if (!isModuleMissing(error)) {
+                throw error;
+            }
+            reportMissingBackend(backend);
+        }
+        await handler(...args);
+    };
+}
+//# sourceMappingURL=optional-backend.js.map

package/dist/utils/optional-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-backend.js","sourceRoot":"","sources":["../../src/utils/optional-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,8EAA8E;AAC9E,wEAAwE;AACxE,8EAA8E;AAC9E,8DAA8D;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAEtD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,gBAAgB,GAAG,sBAAsB,CAAC;AAEhD;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;WACtB,KAAK,KAAK,IAAI;WACd,MAAM,IAAI,KAAK;WACd,KAA4B,CAAC,IAAI,KAAK,gBAAgB,CAC3D,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAwB;IAC3D,MAAM,OAAO,GAAG,eAAe,OAAO,CAAC,WAAW,EAAE,CAAC;IACrD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,GAAG,OAAO,CAAC,OAAO,6DAA6D;UAC7E,uBAAuB,OAAO,IAAI;UAClC,gFAAgF;UAChF,wDAAwD,CAC3D,CAAC;IACF,eAAe,CAAC;QACd,MAAM,EAAE,OAAO;QACf,KAAK,EAAE,GAAG,OAAO,CAAC,OAAO,2BAA2B,OAAO,CAAC,WAAW,EAAE;QACzE,GAAG,EAAE,OAAO;KACb,CAAC,CAAC;IACH,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;AAUD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,UAAU,CACxB,OAAwB,EACxB,IAA+C;IAE/C,OAAO,KAAK,EAAE,GAAG,IAAU,EAAiB,EAAE;QAC5C,IAAI,OAA0C,CAAC;QAC/C,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,IAAI,EAAE,CAAC;QACzB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC5B,MAAM,KAAK,CAAC;YACd,CAAC;YACD,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAChC,CAAC;QACD,MAAM,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IACzB,CAAC,CAAC;AACJ,CAAC"}

package/dist/utils/output.d.ts

@@ -76,6 +76,32 @@ export declare function writeAllSync(write: SyncWriter, buffer: Buffer, options?
  * @param data - Data to serialize as YAML
  */
 export declare function writeYamlOutput(data: unknown): void;
+/**
+ * Write a single JSON document to stdout.
+ *
+ * The sibling of {@link writeYamlOutput}, for the same payloads, and it exists
+ * because a consumer that has to parse YAML needs a YAML parser: JSON is the
+ * format every language reads without one. `vat resources validate` already
+ * offers `--format json` for exactly this reason; a scan document that could
+ * only be had as YAML made the population it reports the harder of the two to
+ * consume programmatically, which is backwards.
+ *
+ * Written the same way as its YAML sibling, and the comment there applies
+ * verbatim: the ordinary stream write keeps this summary behind any
+ * human-readable progress already buffered on the same channel.
+ *
+ * @param data - Data to serialize as JSON
+ */
+export declare function writeJsonOutput(data: unknown): void;
+/**
+ * Write one structured document in the format a `--format` option selected:
+ * `json` → {@link writeJsonOutput}; anything else (including an absent option)
+ * → {@link writeYamlOutput}, the CLI's default document format.
+ *
+ * @param data - The document
+ * @param format - The selected format (`json`, or anything else for YAML)
+ */
+export declare function writeStructuredOutput(data: unknown, format: string | undefined): void;
 /**
  * Write a test-format finding to stderr.
  *