@vibe-agent-toolkit/cli 0.2.0-rc.11 → 0.2.0-rc.12

package/dist/report-schemas.js

@@ -1,100 +1,658 @@
 /**
- * Every structured document a `vat` command publishes, and what shape it has.
+ * Every shape VAT publishes — on stdout, in a file, as an exported library
+ * type, as a committed JSON Schema — and what each one is.
  *
- * 🔑 **Zero committed schemas described any CLI output document** — 31 schema
- * artifacts shipped and none was a report — so an adopter's `jq` recipe, CI
- * adapter or SARIF exporter was written against an example in a doc, or
- * against a run. This registry is the one list; `scripts/generate-json-schemas.ts`
- * writes `schemas/<name>.json` from it, `test/report-schemas.test.ts` pins the
- * emitted files against a fresh render and walks the Commander tree to prove
- * every command that offers `--format json` (or `--yaml`) is listed here.
+ * 🔑 **One list, asserted both ways.** `test/published-shapes.test.ts` holds
+ * every claim here against the tree: each writer call in `commands/` names an
+ * entry and each entry has its writer call; each Commander leaf with an action
+ * is covered by exactly one entry; each `packages/<pkg>/schemas/*.json` is
+ * registered and each registered file exists; each `*Result` / `*Report` /
+ * `*Document` type a published barrel exports is registered and each
+ * registered one is exported. A registry asserted only one way is a hand-kept
+ * list, and hand-kept lists are how a shape shipped with nothing describing it.
  *
- * ## Three kinds of entry, and the ratchet between them
+ * ## Kinds and channels
  *
- * - `report` — the document IS the shared envelope (`Report<T>` from
- *   `@vibe-agent-toolkit/schema`): `status`, a REQUIRED `examined`,
- *   `findings`, `summary`, `data`. The schema is emitted and pinned.
- * - `external` — the document's shape is owned by someone else (an Anthropic
- *   Admin API object passed through, a specification's own artifact). Never
- *   renamed to the envelope; listed so the walk knows it was considered.
- * - `legacy` — a VAT-owned shape not yet migrated to the envelope. Each carries
- *   the reason. ⛔ **This list may only SHRINK.** An entry leaves when its
- *   command publishes the envelope (and gains a `report` entry with a schema);
- *   a new command is never added here — it publishes the envelope from day one.
+ * - `report` / `stdout` — the document IS the union envelope (`Report<T>`).
+ *   The writer (`utils/document-writer.ts`) validates it against `schema`
+ *   before a byte leaves, derives the run-integrity refusal from `examined`
+ *   (the verb's declared denominator — what `examined` counts, and what to
+ *   check when it is zero), and ends on the code the written document derives.
+ *   `scripts/generate-json-schemas.ts` emits `schemas/<name>.json` from it.
+ * - `external` / `stdout` — a payload whose shape someone else owns (the
+ *   Anthropic Admin API), passed through; `exitCodes` maps each outcome to the
+ *   exit contract, since there is no envelope to derive one from.
+ * - `artifact` — a VAT-owned shape that is not a run report: a stdout
+ *   artifact (a config to paste), a file a verb writes, or a type a package
+ *   barrel exports. `schemaFile` names the committed JSON Schema describing it
+ *   (rendered from `schema`), or is `null` when none is published; `writer`
+ *   says who puts a file artifact's bytes on disk.
+ * - `input` / `schema-file` — a committed JSON Schema describing what an
+ *   ADOPTER writes (config, manifests, frontmatter). Registered so the
+ *   both-ways file check can tell "describes an input" from "unregistered".
+ * - `legacy` / `stdout` — exactly `claude context`, the one verb not on the
+ *   envelope through wave A (wave C replaces it). Its type admits no other verb.
+ *
+ * ## Why the report schemas live in sibling `*-schema.ts` modules
+ *
+ * The writer imports this registry, and every report verb imports the
+ * writer. A schema declared in the verb's own module would make this file
+ * import the verb that imports it — an ESM cycle whose binding is read here
+ * before the verb has initialised it. So each verb's `<VERB>_REPORT_SCHEMA`
+ * lives beside it in a module that imports nothing from the writer.
+ *
+ * ## The one lint exception
+ *
+ * `local/no-stdout-outside-writer` makes the writer the only stdout under
+ * `commands/`. Its `allowFiles` is exactly `commands/agent/run.ts` — whose
+ * stdout is the agent's reply, not a document.
  */
-import { ARD_EMIT_REPORT_SCHEMA } from './commands/ard/emit.js';
-import { OKF_VALIDATE_REPORT_SCHEMA } from './commands/okf/validate.js';
-import { CHECK_REPORT_SCHEMA } from './commands/resources/check.js';
-import { SKILL_REVIEW_REPORT_SCHEMA } from './commands/skill/review.js';
-export const REPORT_SCHEMAS = [
-    { kind: 'report', command: 'okf validate', name: 'okf-validate', schema: OKF_VALIDATE_REPORT_SCHEMA },
-    { kind: 'report', command: 'skill review', name: 'skill-review', schema: SKILL_REVIEW_REPORT_SCHEMA },
-    { kind: 'report', command: 'resources check', name: 'resources-check', schema: CHECK_REPORT_SCHEMA },
-    { kind: 'report', command: 'ard emit', name: 'ard-emit', schema: ARD_EMIT_REPORT_SCHEMA },
+import { FrictionReportSchema } from '@vibe-agent-toolkit/agent-skills';
+import { ClaudeContextChainRowSchema, ClaudeContextLoadRowSchema, EdgeResolutionRowSchema, EdgeRowSchema, LensEntryPointRowSchema, PROJECTION_TABLES, } from '@vibe-agent-toolkit/resources';
+import { ExitCode } from '@vibe-agent-toolkit/schema';
+import { AGENT_BUILD_EXAMINED, AGENT_BUILD_REPORT_SCHEMA } from './commands/agent/build-schema.js';
+import { AGENT_IMPORT_EXAMINED, AGENT_IMPORT_REPORT_SCHEMA } from './commands/agent/import-schema.js';
+import { AGENT_INSTALL_EXAMINED, AGENT_INSTALL_REPORT_SCHEMA } from './commands/agent/install-schema.js';
+import { AGENT_INSTALLED_EXAMINED, AGENT_INSTALLED_REPORT_SCHEMA } from './commands/agent/installed-schema.js';
+import { AGENT_LIST_EXAMINED, AGENT_LIST_REPORT_SCHEMA } from './commands/agent/list-schema.js';
+import { AGENT_UNINSTALL_EXAMINED, AGENT_UNINSTALL_REPORT_SCHEMA } from './commands/agent/uninstall-schema.js';
+import { AGENT_VALIDATE_EXAMINED, AGENT_VALIDATE_REPORT_SCHEMA } from './commands/agent/validate-schema.js';
+import { ARD_EMIT_REPORT_SCHEMA } from './commands/ard/emit-schema.js';
+import { AUDIT_EXAMINED, AUDIT_REPORT_SCHEMA } from './commands/audit-schema.js';
+import { AUDIT_SETTINGS_EXAMINED, AUDIT_SETTINGS_REPORT_SCHEMA } from './commands/audit-settings-schema.js';
+import { CACHE_CLEAR_EXAMINED, CACHE_CLEAR_REPORT_SCHEMA } from './commands/cache/clear-schema.js';
+import { MARKETPLACE_PUBLISH_EXAMINED, MARKETPLACE_PUBLISH_REPORT_SCHEMA } from './commands/claude/marketplace/publish-schema.js';
+import { MARKETPLACE_VALIDATE_EXAMINED, MARKETPLACE_VALIDATE_REPORT_SCHEMA } from './commands/claude/marketplace/validate-schema.js';
+import { ORG_NOT_IMPLEMENTED_EXAMINED, ORG_NOT_IMPLEMENTED_REPORT_SCHEMA } from './commands/claude/org/stubs-schema.js';
+import { PLUGIN_BUILD_EXAMINED, PLUGIN_BUILD_REPORT_SCHEMA } from './commands/claude/plugin/build-schema.js';
+import { PLUGIN_INSTALL_EXAMINED, PLUGIN_INSTALL_REPORT_SCHEMA } from './commands/claude/plugin/install-schema.js';
+import { PLUGIN_LIST_EXAMINED, PLUGIN_LIST_REPORT_SCHEMA } from './commands/claude/plugin/list-schema.js';
+import { PLUGIN_UNINSTALL_EXAMINED, PLUGIN_UNINSTALL_REPORT_SCHEMA } from './commands/claude/plugin/uninstall-schema.js';
+import { CORPUS_SCAN_EXAMINED, CORPUS_SCAN_REPORT_SCHEMA } from './commands/corpus/scan-schema.js';
+import { renderDoctorText } from './commands/doctor-render.js';
+import { DOCTOR_EXAMINED, DOCTOR_REPORT_SCHEMA } from './commands/doctor-schema.js';
+import { INVENTORY_EXAMINED, INVENTORY_REPORT_SCHEMA } from './commands/inventory-schema.js';
+import { MCP_LIST_COLLECTIONS_EXAMINED, MCP_LIST_COLLECTIONS_REPORT_SCHEMA } from './commands/mcp/list-collections-schema.js';
+import { OKF_VALIDATE_REPORT_SCHEMA } from './commands/okf/validate-schema.js';
+import { ORCHESTRATOR_EXAMINED, ORCHESTRATOR_REPORT_SCHEMA } from './commands/orchestrator-schema.js';
+import { RAG_CLEAR_REPORT_SCHEMA, RAG_DATABASE_EXAMINED, RAG_STATS_REPORT_SCHEMA } from './commands/rag/admin-schema.js';
+import { RAG_INDEX_EXAMINED, RAG_INDEX_REPORT_SCHEMA } from './commands/rag/index-schema.js';
+import { RAG_QUERY_EXAMINED, RAG_QUERY_REPORT_SCHEMA } from './commands/rag/query-schema.js';
+import { CHECK_REPORT_SCHEMA, RESOURCES_CHECK_EXAMINED } from './commands/resources/check-schema.js';
+import { RESOURCES_QUERY_EXAMINED, RESOURCES_QUERY_REPORT_SCHEMA } from './commands/resources/query-schema.js';
+import { RESOURCES_SCAN_EXAMINED, RESOURCES_SCAN_REPORT_SCHEMA } from './commands/resources/scan-schema.js';
+import { RESOURCES_VALIDATE_EXAMINED, RESOURCES_VALIDATE_REPORT_SCHEMA } from './commands/resources/validate-schema.js';
+import { SKILL_REVIEW_REPORT_SCHEMA } from './commands/skill/review-schema.js';
+import { SKILL_TEST_CONFIGURE_EXAMINED, SKILL_TEST_CONFIGURE_REPORT_SCHEMA } from './commands/skill/test/configure-schema.js';
+import { SKILL_TEST_RUN_EXAMINED, SKILL_TEST_RUN_REPORT_SCHEMA } from './commands/skill/test/run-schema.js';
+import { SKILLS_BUILD_EXAMINED, SKILLS_BUILD_REPORT_SCHEMA } from './commands/skills/build-schema.js';
+import { SKILLS_INSTALL_EXAMINED, SKILLS_INSTALL_REPORT_SCHEMA } from './commands/skills/install-schema.js';
+import { SKILLS_LIST_EXAMINED, SKILLS_LIST_REPORT_SCHEMA } from './commands/skills/list-schema.js';
+import { SKILLS_PACKAGE_EXAMINED, SKILLS_PACKAGE_REPORT_SCHEMA } from './commands/skills/package-schema.js';
+import { SKILLS_VALIDATE_EXAMINED, SKILLS_VALIDATE_REPORT_SCHEMA } from './commands/skills/validate-schema.js';
+/** Who puts an artifact's bytes out, named once. */
+const DOCUMENT_WRITER = 'document-writer';
+/** The verb publishing the corpus scan's file artifacts, named once. */
+const CORPUS_SCAN = 'corpus scan';
+/** The Admin API adapter: only a write that fully landed is `OK`; a partial or failed one is `ERROR`. */
+const ADMIN_API_EXIT_CODES = { ok: ExitCode.OK, partial: ExitCode.ERROR, failed: ExitCode.ERROR };
+/** `ard emit --format text`: the one summary line it has always printed; its findings go to stderr. */
+function renderArdEmitText(report) {
+    const data = report.data;
+    if (data?.outputPath === undefined || data.outputPath === null)
+        return '';
+    return `Wrote ${data.entryCount} ARD entr${data.entryCount === 1 ? 'y' : 'ies'} to ${data.outputPath}\n`;
+}
+const REPORTS = [
     {
-        kind: 'external',
-        command: 'claude org *',
-        reason: 'Anthropic Admin API objects passed through as the API returns them (`has_more`, `data[]`, snake_case). Renaming them would make VAT a second schema for a document Anthropic owns.',
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['okf validate'],
+        name: 'okf-validate',
+        schema: OKF_VALIDATE_REPORT_SCHEMA,
+        examined: {
+            unit: 'bundle documents',
+            whenZero: 'Declare a bundle under okf.bundles in vibe-agent-toolkit.config.yaml, or check that each bundle root holds its markdown documents.',
+        },
     },
     {
-        kind: 'external',
-        command: 'inventory',
-        reason: 'The structural inventory `@vibe-agent-toolkit/agent-skills` serializes (`serializeInventory`) — a description of a plugin, marketplace, skill or install root, not a run over one. It carries no findings and no denominator to publish.',
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['skill review'],
+        name: 'skill-review',
+        schema: SKILL_REVIEW_REPORT_SCHEMA,
+        examined: {
+            unit: 'skills',
+            whenZero: 'Point the command at a SKILL.md file or a directory containing one.',
+        },
+        // The human report goes to stderr; without --yaml stdout carries nothing.
+        renderText: () => '',
     },
     {
-        kind: 'legacy',
-        command: 'resources validate',
-        reason: 'The lab measures this document (`filesScanned`, per-file rows) through `packages/lab` and the qa-snapshot harness; the instrument and the subject move together, and the lab is outside this migration.',
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['resources check'],
+        name: 'resources-check',
+        schema: CHECK_REPORT_SCHEMA,
+        examined: RESOURCES_CHECK_EXAMINED,
     },
     {
-        kind: 'legacy',
-        command: 'resources scan',
-        reason: 'A population listing (which files, which collections), not findings; the envelope fits once `data` carries the listing and `examined` the file count — a small migration, not yet made.',
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['ard emit'],
+        name: 'ard-emit',
+        schema: ARD_EMIT_REPORT_SCHEMA,
+        examined: {
+            unit: 'configured surfaces',
+            whenZero: 'The ard: block declares no surface this project has — declare skills, marketplaces or OKF bundles to advertise, or do not run vat ard emit for this project.',
+        },
+        renderText: renderArdEmitText,
     },
     {
-        kind: 'legacy',
-        command: 'resources query',
-        reason: 'SQL rows the operator selected — the shape is the query\'s, and a `findings` list over arbitrary rows would be a fiction.',
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['audit'],
+        name: 'audit',
+        schema: AUDIT_REPORT_SCHEMA,
+        examined: AUDIT_EXAMINED,
     },
     {
-        kind: 'legacy',
-        command: 'claude context',
-        reason: 'Two document kinds (`answer` / `unknown`) plus the `--all` cost map, each a query answer with conditions per path; the severity vocabulary is now the shared one, the envelope migration is a design change for the query lane.',
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['inventory'],
+        name: 'inventory',
+        schema: INVENTORY_REPORT_SCHEMA,
+        examined: INVENTORY_EXAMINED,
     },
     {
-        kind: 'legacy',
-        command: 'audit',
-        reason: 'The largest document in the CLI, consumed by the corpus runner, the lab and fifteen integration tests; its walker was under concurrent edit when the envelope landed.',
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['audit settings'],
+        name: 'audit-settings',
+        schema: AUDIT_SETTINGS_REPORT_SCHEMA,
+        examined: AUDIT_SETTINGS_EXAMINED,
     },
     {
-        kind: 'legacy',
-        command: 'skills validate',
-        reason: 'Publishes per-skill COUNT rows by design (a clean skill is omitted; `skillsValidated` is the denominator) — a flat `findings` list is a design change for the maintainer, not a rename.',
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['resources validate'],
+        name: 'resources-validate',
+        schema: RESOURCES_VALIDATE_REPORT_SCHEMA,
+        examined: RESOURCES_VALIDATE_EXAMINED,
     },
     {
-        kind: 'legacy',
-        command: 'validate',
-        reason: 'A phase orchestrator over `phase-utils`; its document nests each phase\'s own, so it migrates after every phase does.',
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['resources scan'],
+        name: 'resources-scan',
+        schema: RESOURCES_SCAN_REPORT_SCHEMA,
+        examined: RESOURCES_SCAN_EXAMINED,
     },
     {
-        kind: 'legacy',
-        command: 'verify',
-        reason: 'The second phase orchestrator over `phase-utils` (it publishes no `issueCounts` at all); migrates with `validate`.',
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['resources query'],
+        name: 'resources-query',
+        schema: RESOURCES_QUERY_REPORT_SCHEMA,
+        examined: RESOURCES_QUERY_EXAMINED,
     },
     {
-        kind: 'legacy',
-        command: 'audit settings',
-        reason: 'Publishes `SettingsFinding[]` under `findings` with `path`; the envelope fits once `path` becomes `location`.',
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['skills validate'],
+        name: 'skills-validate',
+        schema: SKILLS_VALIDATE_REPORT_SCHEMA,
+        examined: SKILLS_VALIDATE_EXAMINED,
     },
     {
-        kind: 'legacy',
-        command: 'claude marketplace validate',
-        reason: 'A `vat verify` phase and a standalone command sharing one document; migrates with the orchestrators.',
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['skills build'],
+        name: 'skills-build',
+        schema: SKILLS_BUILD_REPORT_SCHEMA,
+        examined: SKILLS_BUILD_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['skills package'],
+        name: 'skills-package',
+        schema: SKILLS_PACKAGE_REPORT_SCHEMA,
+        examined: SKILLS_PACKAGE_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['skills list'],
+        name: 'skills-list',
+        schema: SKILLS_LIST_REPORT_SCHEMA,
+        examined: SKILLS_LIST_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['skills install'],
+        name: 'skills-install',
+        schema: SKILLS_INSTALL_REPORT_SCHEMA,
+        examined: SKILLS_INSTALL_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['skill test run'],
+        name: 'skill-test-run',
+        schema: SKILL_TEST_RUN_REPORT_SCHEMA,
+        examined: SKILL_TEST_RUN_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['skill test configure'],
+        name: 'skill-test-configure',
+        schema: SKILL_TEST_CONFIGURE_REPORT_SCHEMA,
+        examined: SKILL_TEST_CONFIGURE_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['doctor'],
+        name: 'doctor',
+        schema: DOCTOR_REPORT_SCHEMA,
+        examined: DOCTOR_EXAMINED,
+        // The human check block, every check listed; under yaml/json it goes to stderr instead.
+        renderText: renderDoctorText,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['cache clear'],
+        name: 'cache-clear',
+        schema: CACHE_CLEAR_REPORT_SCHEMA,
+        examined: CACHE_CLEAR_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['rag index'],
+        name: 'rag-index',
+        schema: RAG_INDEX_REPORT_SCHEMA,
+        examined: RAG_INDEX_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['rag query'],
+        name: 'rag-query',
+        schema: RAG_QUERY_REPORT_SCHEMA,
+        examined: RAG_QUERY_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['rag stats'],
+        name: 'rag-stats',
+        schema: RAG_STATS_REPORT_SCHEMA,
+        examined: RAG_DATABASE_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['rag clear'],
+        name: 'rag-clear',
+        schema: RAG_CLEAR_REPORT_SCHEMA,
+        examined: RAG_DATABASE_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['mcp list-collections'],
+        name: 'mcp-list-collections',
+        schema: MCP_LIST_COLLECTIONS_REPORT_SCHEMA,
+        examined: MCP_LIST_COLLECTIONS_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: [CORPUS_SCAN],
+        name: 'corpus-scan',
+        schema: CORPUS_SCAN_REPORT_SCHEMA,
+        examined: CORPUS_SCAN_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['claude marketplace validate'],
+        name: 'claude-marketplace-validate',
+        schema: MARKETPLACE_VALIDATE_REPORT_SCHEMA,
+        examined: MARKETPLACE_VALIDATE_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['agent validate'],
+        name: 'agent-validate',
+        schema: AGENT_VALIDATE_REPORT_SCHEMA,
+        examined: AGENT_VALIDATE_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['agent build'],
+        name: 'agent-build',
+        schema: AGENT_BUILD_REPORT_SCHEMA,
+        examined: AGENT_BUILD_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['agent import'],
+        name: 'agent-import',
+        schema: AGENT_IMPORT_REPORT_SCHEMA,
+        examined: AGENT_IMPORT_EXAMINED,
     },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['agent installed'],
+        name: 'agent-installed',
+        schema: AGENT_INSTALLED_REPORT_SCHEMA,
+        examined: AGENT_INSTALLED_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['agent list'],
+        name: 'agent-list',
+        schema: AGENT_LIST_REPORT_SCHEMA,
+        examined: AGENT_LIST_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['agent install'],
+        name: 'agent-install',
+        schema: AGENT_INSTALL_REPORT_SCHEMA,
+        examined: AGENT_INSTALL_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['agent uninstall'],
+        name: 'agent-uninstall',
+        schema: AGENT_UNINSTALL_REPORT_SCHEMA,
+        examined: AGENT_UNINSTALL_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['claude plugin list'],
+        name: 'claude-plugin-list',
+        schema: PLUGIN_LIST_REPORT_SCHEMA,
+        examined: PLUGIN_LIST_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['claude plugin install'],
+        name: 'claude-plugin-install',
+        schema: PLUGIN_INSTALL_REPORT_SCHEMA,
+        examined: PLUGIN_INSTALL_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['claude plugin uninstall'],
+        name: 'claude-plugin-uninstall',
+        schema: PLUGIN_UNINSTALL_REPORT_SCHEMA,
+        examined: PLUGIN_UNINSTALL_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['claude plugin build'],
+        name: 'claude-plugin-build',
+        schema: PLUGIN_BUILD_REPORT_SCHEMA,
+        examined: PLUGIN_BUILD_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        verbs: ['claude marketplace publish'],
+        name: 'claude-marketplace-publish',
+        schema: MARKETPLACE_PUBLISH_REPORT_SCHEMA,
+        examined: MARKETPLACE_PUBLISH_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        // The not-implemented stubs: each only ever publishes the error branch (NOT_IMPLEMENTED).
+        verbs: [
+            'claude org api-keys update',
+            'claude org invites create',
+            'claude org invites delete',
+            'claude org users update',
+            'claude org users remove',
+            'claude org workspaces create',
+            'claude org workspaces archive',
+            'claude org workspaces members add',
+            'claude org workspaces members update',
+            'claude org workspaces members remove',
+        ],
+        name: 'claude-org-not-implemented',
+        schema: ORG_NOT_IMPLEMENTED_REPORT_SCHEMA,
+        examined: ORG_NOT_IMPLEMENTED_EXAMINED,
+    },
+    {
+        kind: 'report',
+        channel: 'stdout',
+        // ONE shape for the three: each folds its phases' reports the same way.
+        verbs: ['build', 'validate', 'verify'],
+        name: 'orchestrator',
+        schema: ORCHESTRATOR_REPORT_SCHEMA,
+        examined: ORCHESTRATOR_EXAMINED,
+    },
+];
+const CLAUDE_ORG_EXTERNAL = {
+    kind: 'external',
+    channel: 'stdout',
+    verbs: [
+        'claude org info',
+        'claude org users list',
+        'claude org users get',
+        'claude org invites list',
+        'claude org workspaces list',
+        'claude org workspaces get',
+        'claude org workspaces members list',
+        'claude org api-keys list',
+        'claude org usage',
+        'claude org cost',
+        'claude org code-analytics',
+        'claude org skills list',
+        'claude org skills install',
+        'claude org skills delete',
+        'claude org skills versions list',
+        'claude org skills versions add',
+        'claude org skills versions delete',
+    ],
+    reason: 'Anthropic Admin API objects passed through as the API returns them (`has_more`, `data[]`, snake_case). Renaming them would make VAT a second schema for a document Anthropic owns. A run that threw publishes `{ error: { code, message } }` instead (endWithExternalRefusal).',
+    exitCodes: ADMIN_API_EXIT_CODES,
+};
+const EXTERNALS = [CLAUDE_ORG_EXTERNAL];
+const LEGACY = [
     {
         kind: 'legacy',
-        command: 'agent validate',
-        reason: 'Publishes the agent-config validator\'s result verbatim; the envelope fits once `examined` is the manifest count.',
+        channel: 'stdout',
+        verbs: ['claude context'],
+        reason: 'The one legacy document through wave A, published through writeLegacyDocument; wave C replaces the verb.',
     },
 ];
+/** Relations VAT publishes to adopter SQL that no projection table materialises (the per-lens derived rows). */
+const DERIVED_RELATION_SCHEMAS = [
+    ['projection-edges', EdgeRowSchema],
+    ['projection-edge-resolutions', EdgeResolutionRowSchema],
+    ['projection-lens-entry-points', LensEntryPointRowSchema],
+    ['projection-claude-context-chains', ClaudeContextChainRowSchema],
+    ['projection-claude-context-loads', ClaudeContextLoadRowSchema],
+];
+/** Every relation `vat resources query` / `check` expose to an adopter's SQL, as a file artifact. */
+const PROJECTION_RELATIONS = [
+    ...Object.values(PROJECTION_TABLES).map((spec) => [`projection-${spec.name.replaceAll('_', '-')}`, spec.schema]),
+    ...DERIVED_RELATION_SCHEMAS,
+].map(([name, schema]) => ({
+    kind: 'artifact',
+    channel: 'file',
+    name,
+    publishers: ['resources query', 'resources check'],
+    schema,
+    schemaFile: `packages/resources/schemas/${name}.json`,
+    writer: 'projection-store',
+    reason: 'A relation VAT publishes to adopter SQL; its row shape is what a check or query statement reads.',
+}));
+const ARTIFACTS = [
+    {
+        kind: 'artifact',
+        channel: 'stdout',
+        name: 'claude-desktop-config',
+        publishers: ['mcp serve'],
+        schema: null,
+        schemaFile: null,
+        writer: DOCUMENT_WRITER,
+        reason: '`mcp serve --print-config`: the Claude Desktop config snippet an operator pastes; its shape is the MCP client config.',
+    },
+    {
+        kind: 'artifact',
+        channel: 'stdout',
+        name: 'skill-test-config',
+        publishers: ['skill test configure'],
+        schema: null,
+        schemaFile: null,
+        writer: DOCUMENT_WRITER,
+        reason: '`skill test configure --print`: the updated vibe-agent-toolkit.config.yaml text, verbatim, for redirecting over the file; its shape is the project config.',
+    },
+    {
+        kind: 'artifact',
+        channel: 'file',
+        name: 'friction-report',
+        publishers: ['skill test run'],
+        schema: FrictionReportSchema,
+        schemaFile: 'packages/agent-skills/schemas/friction-report.json',
+        writer: 'skill-test-harness',
+        reason: 'The graded friction report a skill test run writes into its results/ directory (`data.artifacts.frictionReport`), validated against its schema before the run reports.',
+    },
+    {
+        kind: 'artifact',
+        channel: 'file',
+        name: 'corpus-summary',
+        publishers: [CORPUS_SCAN],
+        schema: null,
+        schemaFile: null,
+        writer: DOCUMENT_WRITER,
+        reason: 'corpus scan `summary.yaml`: the per-plugin index of one scan run.',
+    },
+    {
+        kind: 'artifact',
+        channel: 'file',
+        name: 'corpus-audit',
+        publishers: [CORPUS_SCAN],
+        schema: AUDIT_REPORT_SCHEMA,
+        schemaFile: 'packages/cli/schemas/corpus-audit.json',
+        writer: DOCUMENT_WRITER,
+        reason: 'corpus scan `<name>-audit.yaml`: the `vat audit` report for one plugin, the same envelope and schema the verb publishes.',
+    },
+    ...PROJECTION_RELATIONS,
+];
+/** A library result type an adopter's code receives. */
+function exported(pkg, typeNames, reason) {
+    return typeNames.map((typeName) => ({ kind: 'artifact', channel: 'export', package: `@vibe-agent-toolkit/${pkg}`, typeName, reason }));
+}
+const AGENT_SKILLS = 'agent-skills';
+const SCHEMA_PACKAGE = 'schema';
+const LIBRARY_RESULT = 'A result type the package barrel exports; its shape is the library API contract.';
+const EXPORTS = [
+    ...exported('agent-config', ['ValidationResult'], LIBRARY_RESULT),
+    ...exported('agent-runtime', ['AgentResult', 'StatefulAgentResult'], 'The agent result envelope every runtime adapter returns.'),
+    ...exported(AGENT_SKILLS, [
+        'BuildResult', 'FrontmatterResult', 'GitCloneResult', 'ImportResult', 'LinkGraphResult',
+        'PackageSkillResult', 'PackagingValidationResult', 'ValidationResult',
+        'PreflightResult', 'RunHarnessResult', 'StageHarnessResult',
+    ], LIBRARY_RESULT),
+    ...exported(AGENT_SKILLS, ['FrictionReport', 'GradingReport', 'ToolEvalReport'], 'A skill-test report the harness writes and a caller reads back.'),
+    ...exported('claude-marketplace', [
+        'CompatibilityResult', 'MultipartResult', 'PluginListResult', 'SettingsAuditResult',
+        'SettingsPathCandidatesResult', 'SettingsPathsResult', 'SettingsValidateResult', 'UninstallPluginResult',
+    ], LIBRARY_RESULT),
+    ...exported('discovery', ['ScanResult'], LIBRARY_RESULT),
+    ...exported('gateway-mcp', ['MCPToolResult'], 'The MCP tool result the gateway returns to a client.'),
+    ...exported('rag', ['ChunkingResult', 'DocumentResult', 'IndexResult', 'RAGResult'], LIBRARY_RESULT),
+    ...exported('resource-compiler', ['CompileResult', 'ParseResult'], LIBRARY_RESULT),
+    ...exported('resources', [
+        'BlobPopulationResult', 'ContentFetchResult', 'OkfBundleReport',
+        'ParseResult', 'PopulateResult', 'ProjectionDocument', 'ResolveLocalHrefResult', 'ValidationResult',
+    ], LIBRARY_RESULT),
+    ...exported('runtime-claude-agent-sdk', ['AgentConversionResult', 'BatchConversionResult'], LIBRARY_RESULT),
+    ...exported('runtime-langchain', ['ConversationalResult'], LIBRARY_RESULT),
+    ...exported('runtime-vercel-ai-sdk', ['ConversionResult'], LIBRARY_RESULT),
+    ...exported('utils', ['ApplyResult'], 'What `applyTreePlan` returns: the warnings of a tree change that is done.'),
+    ...exported(SCHEMA_PACKAGE, ['Report', 'OkReport', 'FindingsReport', 'ErrorReport'], 'The union report envelope every report verb publishes; its JSON Schemas are the `report` entries above.'),
+    ...exported(SCHEMA_PACKAGE, ['ExitDeterminingDocument'], 'The envelope fields an exit code derives from.'),
+    ...exported(SCHEMA_PACKAGE, ['AgentResult', 'StatefulAgentResult', 'FrameworkResult'], 'The agent result envelope every runtime adapter returns.'),
+    ...exported(SCHEMA_PACKAGE, ['AllowFilterResult'], LIBRARY_RESULT),
+    ...exported('vat-example-cat-agents', [
+        'ApprovalResult', 'ChoiceResult', 'CustomApprovalResult', 'HaikuValidationResult', 'NameValidationResult',
+    ], 'An example agent\'s result type, published as part of the example package.'),
+];
+/** An adopter-written shape's committed JSON Schema. */
+function inputs(pkg, names, reason) {
+    return names.map((name) => ({ kind: 'input', channel: 'schema-file', file: `packages/${pkg}/schemas/${name}.json`, reason }));
+}
+const INPUTS = [
+    ...inputs('agent-skills', ['skill-frontmatter', 'vat-skill-frontmatter', 'marketplace-manifest'], 'The SKILL.md frontmatter or marketplace.json an author writes.'),
+    ...inputs('resources', ['project-config'], 'vibe-agent-toolkit.config.yaml, the adopter\'s project config.'),
+    ...inputs('resources', ['okf-concept-frontmatter'], 'The OKF concept-document frontmatter a bundle author writes.'),
+    ...inputs('schema', ['agent-manifest', 'agent-metadata', 'agent-interface', 'llm-config', 'tool', 'resource-registry'], 'A part of the agent.yaml manifest an agent author writes.'),
+    ...inputs('schema', ['vat-package-metadata'], 'The `vat` block an adopter writes in package.json.'),
+    ...inputs('schema', ['validation-config'], 'The `validation` block (`severity` / `allow`) an adopter writes.'),
+];
+/** Every shape VAT publishes. See the module docstring for the kinds and the both-ways test. */
+export const PUBLISHED_SHAPES = [
+    ...REPORTS,
+    ...EXTERNALS,
+    ...ARTIFACTS,
+    ...EXPORTS,
+    ...INPUTS,
+    ...LEGACY,
+];
+/**
+ * The registry entry a report verb publishes through.
+ *
+ * @throws When `verb` has no report entry — a defect in the caller, never a user mistake
+ */
+export function reportShapeFor(verb) {
+    const entry = REPORTS.find((shape) => shape.verbs.includes(verb));
+    if (entry === undefined)
+        throw new Error(`No report entry in PUBLISHED_SHAPES for verb '${verb}'`);
+    return entry;
+}
+/**
+ * The published artifact named `name` on `channel`.
+ *
+ * @throws When no such artifact is registered
+ */
+export function artifactShapeFor(name, channel) {
+    const entry = ARTIFACTS.find((shape) => shape.name === name && shape.channel === channel);
+    if (entry === undefined)
+        throw new Error(`No ${channel} artifact in PUBLISHED_SHAPES named '${name}'`);
+    return entry;
+}
+/**
+ * The exit code an external verb's outcome maps to — the adapter its entry declares.
+ *
+ * @throws When `verb` has no external entry
+ */
+export function exitCodeForExternal(verb, outcome) {
+    const entry = EXTERNALS.find((shape) => shape.verbs.includes(verb));
+    if (entry === undefined)
+        throw new Error(`No external entry in PUBLISHED_SHAPES for verb '${verb}'`);
+    return entry.exitCodes[outcome.kind];
+}
 //# sourceMappingURL=report-schemas.js.map