mandrel 2.30.0 → 2.32.0

package/.agents/scripts/generate-config-docs.js

@@ -1,31 +1,54 @@
 #!/usr/bin/env node
 /**
- * .agents/scripts/generate-config-docs.js — Schema-backed `.agentrc` reference
+ * .agents/scripts/generate-config-docs.js — the `.agentrc` config surface
+ * generator (Story #5007).
  *
- * Renders a bounded region inside `.agents/docs/configuration.md` from
- * `.agents/schemas/agentrc.schema.json`. The region is delimited by:
+ * **One annotated source, three generated artifacts.** The runtime AJV schema
+ * (`AGENTRC_SCHEMA`, composed from `lib/config-settings-schema*.js` and
+ * `lib/config/gates/*`) is the single hand-authored enumeration of the
+ * `.agentrc.json` surface. `description` and `default` annotations live on
+ * those literals — AJV ignores both — and this generator emits everything
+ * downstream of them:
  *
- *     <!-- BEGIN GENERATED:agentrc -->
- *     ...generated tables...
- *     <!-- END GENERATED:agentrc -->
+ *   1. `.agents/schemas/agentrc.schema.json` — the JSON-Schema mirror every
+ *      consumer `.agentrc.json` points `$schema` at. Serialized 2020-12,
+ *      fully inlined (no `$defs`): it IS the runtime schema, so the class of
+ *      bug where a key exists in the mirror but not in the runtime AJV — and
+ *      a consumer's whole config is therefore dead on arrival (Epic #4131) —
+ *      cannot be expressed any more.
+ *   2. `.agents/docs/agentrc-reference.json` — the defaults inventory
+ *      `lib/config/defaults.js` reads for `mandrel explain` and the
+ *      sync-agentrc redundancy advisory. Built from the `default`
+ *      annotations: a node carrying one contributes its value verbatim and is
+ *      not descended into; a node carrying none contributes nothing.
+ *   3. The bounded key-table region inside `.agents/docs/configuration.md`,
+ *      delimited by:
  *
- * One Markdown section is emitted per top-level schema key (`project`,
- * `github`, `planning`, `delivery`). Each section's table has columns:
+ *          <!-- BEGIN GENERATED:agentrc -->
+ *          ...generated tables...
+ *          <!-- END GENERATED:agentrc -->
  *
- *     | Key | Required | Type | Default | Description |
+ *      One Markdown section per top-level schema key, each table columned
+ *      `| Key | Required | Type | Default | Description |`, with nested
+ *      properties flattened into dot-paths (`paths.agentRoot`,
+ *      `branchProtection.requiredChecks[]`).
  *
- * Nested properties are flattened into dot-paths (e.g. `paths.agentRoot`,
- * `branchProtection.requiredChecks[]`). Defaults, descriptions, and types
- * are sourced from the schema directly; rows without a `default` declaration
- * render `—`.
+ * Until this Story the first two were hand-maintained alongside the runtime
+ * schema and reconciled by two parity suites; those suites are now
+ * generator-fidelity checks.
  *
  * Modes:
- *   (default)  — rewrites the bounded region in place. If the region markers
- *                are absent from `.agents/docs/configuration.md`, they are inserted
- *                just after the "Top-level shape" section header before the
- *                hand-authored per-section docs.
- *   --check    — exits 0 when the on-disk region matches the freshly
- *                generated content, exits 1 with a diff hint otherwise.
+ *   (default)  — rewrite any artifact whose content is stale.
+ *   --check    — exit 0 when all three are current, exit 1 naming the stale
+ *                ones. Wired into `npm run docs:check`, hence `npm run lint`.
+ *
+ * **Whitespace is not content.** The two JSON artifacts are re-formatted by
+ * Biome via lint-staged after they are written, so comparing raw bytes would
+ * make the check fail on formatting alone. Both comparison and write go
+ * through {@link canonicalJson}: parse, re-serialize, compare. That is
+ * insensitive to whitespace and *sensitive* to key order, which is what
+ * actually matters — key order drives the doc-table order and the ordering a
+ * consumer's editor offers completions in.
  *
  * Per `.agents/rules/orchestration-error-handling.md`, unrecoverable
  * failures surface via `throw new Error(...)` so `runAsCli` can map the
@@ -37,6 +60,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
+import { AGENTRC_SCHEMA } from './lib/config-settings-schema.js';
 import { Logger } from './lib/Logger.js';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -48,103 +72,139 @@ const SCHEMA_PATH = path.join(
   'schemas',
   'agentrc.schema.json',
 );
+const REFERENCE_PATH = path.join(
+  PROJECT_ROOT,
+  '.agents',
+  'docs',
+  'agentrc-reference.json',
+);
 const DOC_PATH = path.join(PROJECT_ROOT, '.agents', 'docs', 'configuration.md');
 const REGION_BEGIN = '<!-- BEGIN GENERATED:agentrc -->';
 const REGION_END = '<!-- END GENERATED:agentrc -->';
 
+/** Envelope keys prepended to the serialized runtime schema. */
+const MIRROR_ENVELOPE = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  $id: 'https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/agentrc.schema.json',
+  title: 'Mandrel .agentrc',
+  description:
+    'GENERATED — do not edit. Emitted by `node .agents/scripts/generate-config-docs.js` from the runtime AJV schema in `.agents/scripts/lib/config-settings-schema.js` (plus its `-delivery` / `-quality` / `config/gates/*` modules), which is the single source of truth for the `.agentrc.json` surface. This file exists for editor tooling and human readers; because it is a serialization of the runtime schema rather than a hand-kept mirror, the two cannot disagree. Edit the annotated schema literals and re-run `npm run docs:gen`.',
+};
+
+/** `$schema` pointer written into the generated defaults inventory. */
+const REFERENCE_SCHEMA_POINTER = '../schemas/agentrc.schema.json';
+
 // Order matters — drives the per-section emission sequence.
-const TOP_LEVEL_KEYS = ['project', 'github', 'planning', 'delivery'];
+const TOP_LEVEL_KEYS = ['project', 'github', 'planning', 'delivery', 'qa'];
 
 /**
- * Read and parse the agentrc JSON Schema.
+ * Canonical JSON text for comparison and for writing. Key order is preserved
+ * (and therefore compared); whitespace is normalized away.
  *
- * @param {string} file Absolute path to the schema file.
- * @returns {object}
+ * @param {unknown} value
+ * @returns {string}
  */
-function readSchema(file) {
-  if (!fs.existsSync(file)) {
-    throw new Error(`Schema file not found: ${file}`);
-  }
-  let raw;
-  try {
-    raw = fs.readFileSync(file, 'utf8');
-  } catch (err) {
-    throw new Error(`Failed to read schema ${file}: ${err.message}`);
-  }
+function canonicalJson(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+/**
+ * Read a JSON artifact and return its canonical text, or `null` when the file
+ * is absent (first generation) or unparseable (a hand-mangled artifact is
+ * treated as stale, not as a crash).
+ *
+ * @param {string} file
+ * @returns {string | null}
+ */
+function readCanonicalJson(file) {
+  if (!fs.existsSync(file)) return null;
   try {
-    return JSON.parse(raw);
-  } catch (err) {
-    throw new Error(`Failed to parse schema ${file}: ${err.message}`);
+    return canonicalJson(JSON.parse(fs.readFileSync(file, 'utf8')));
+  } catch {
+    return null;
   }
 }
 
 /**
- * Resolve a `$ref` pointing into `#/$defs/<name>`. Throws on unknown refs
- * because every ref in the agentrc schema is a local one.
+ * Build the shipped JSON-Schema mirror: the 2020-12 envelope followed by the
+ * runtime schema verbatim.
+ *
+ * The runtime schema is a plain, cycle-free object literal (no RegExp or
+ * function values), so `structuredClone` is a faithful serialization. Shared
+ * sub-schema objects — `TOLERANCE_SCHEMA` and friends, referenced by several
+ * gates — are inlined at each use rather than hoisted into `$defs`. The
+ * inlined document is smaller than the hand-maintained `$defs` mirror it
+ * replaces, and it removes the naming heuristic a hoisting pass would need.
  *
- * @param {object} schema The root schema object.
- * @param {string} ref    The `$ref` value.
+ * @param {object} schema
  * @returns {object}
  */
-function resolveRef(schema, ref) {
-  if (typeof ref !== 'string' || !ref.startsWith('#/$defs/')) {
-    throw new Error(`Unsupported $ref shape: ${ref}`);
-  }
-  const name = ref.slice('#/$defs/'.length);
-  const target = schema.$defs?.[name];
-  if (!target) {
-    throw new Error(`Unresolved $ref: ${ref}`);
+function buildMirrorSchema(schema) {
+  return { ...MIRROR_ENVELOPE, ...structuredClone(schema) };
+}
+
+/**
+ * Collect the `default` annotations under `node` into a nested plain object.
+ *
+ * A node carrying `default` contributes that value verbatim and is NOT
+ * descended into — that is what lets an object-shaped or array-shaped default
+ * (`github.branchProtection.requiredChecks`, `qa.environments`) be declared in
+ * one place. A properties-bearing node with no `default` contributes an object
+ * built from whichever children contributed something, or nothing at all when
+ * none did.
+ *
+ * @param {object} node
+ * @returns {unknown} The built value, or `undefined` for "contributes nothing".
+ */
+function collectDefaults(node) {
+  if (!node || typeof node !== 'object') return undefined;
+  if (Object.hasOwn(node, 'default')) return structuredClone(node.default);
+  if (!node.properties) return undefined;
+  const out = {};
+  for (const [key, child] of Object.entries(node.properties)) {
+    const built = collectDefaults(child);
+    if (built !== undefined) out[key] = built;
   }
-  return target;
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/**
+ * Build the defaults inventory shipped as `.agents/docs/agentrc-reference.json`.
+ *
+ * @param {object} schema
+ * @returns {object}
+ */
+function buildReferenceInventory(schema) {
+  return {
+    $schema: REFERENCE_SCHEMA_POINTER,
+    ...(collectDefaults(schema) ?? {}),
+  };
 }
 
 /**
- * Collapse an `allOf` envelope down to its first concrete sub-schema. The
- * agentrc schema uses `allOf` exclusively to apply guard constraints
- * (`safeString`, `minLength`) on top of a base type — the first member
- * carries the type for documentation purposes.
+ * Collapse an `allOf` envelope down onto its base node. The schema uses
+ * `allOf` only to hang a conditional (`if`/`then`) constraint off a block, so
+ * the merged view carries the base type for documentation purposes.
  *
- * @param {object} schema The root schema (needed for ref resolution).
- * @param {object} node   The schema node to flatten.
+ * @param {object} node The schema node to flatten.
  * @returns {object}
  */
-function flattenAllOf(schema, node) {
+function flattenAllOf(node) {
   if (!node || typeof node !== 'object') return node;
   if (!Array.isArray(node.allOf)) return node;
   const merged = { ...node };
   delete merged.allOf;
   for (const member of node.allOf) {
-    const resolved = member.$ref ? resolveRef(schema, member.$ref) : member;
-    for (const [key, value] of Object.entries(resolved)) {
+    for (const [key, value] of Object.entries(member)) {
       if (merged[key] === undefined) merged[key] = value;
     }
   }
   return merged;
 }
 
-/**
- * Resolve a property node down to its first non-ref form. Returns the
- * resolved node alongside the original ref name (if any) so callers can
- * detect when to recurse into a referenced object def.
- *
- * @param {object} schema
- * @param {object} node
- * @returns {{ node: object, refName: string | null }}
- */
-function resolveNode(schema, node) {
-  if (node && typeof node === 'object' && typeof node.$ref === 'string') {
-    const refName = node.$ref.startsWith('#/$defs/')
-      ? node.$ref.slice('#/$defs/'.length)
-      : null;
-    return { node: resolveRef(schema, node.$ref), refName };
-  }
-  return { node, refName: null };
-}
-
 /**
  * Render the "Type" cell for an `array`-typed node by inspecting its `items`
- * schema. Mirrors the original inline ladder exactly: a `$ref` item renders
- * `array<RefName>`, an enum item renders `array<enum>`, a typed item renders
+ * schema: an enum item renders `array<enum>`, a typed item renders
  * `array<type>`, and anything else collapses to a bare `array`.
  *
  * @param {object} flat Flattened array node.
@@ -153,12 +213,6 @@ function resolveNode(schema, node) {
 function renderArrayType(flat) {
   const items = flat.items;
   if (items && typeof items === 'object') {
-    if (items.$ref) {
-      const refName = items.$ref.startsWith('#/$defs/')
-        ? items.$ref.slice('#/$defs/'.length)
-        : items.$ref;
-      return `\`array<${refName}>\``;
-    }
     if (Array.isArray(items.enum)) {
       return `\`array<enum>\``;
     }
@@ -194,16 +248,24 @@ function renderObjectType(flat) {
  * row here rather than another nested branch.
  *
  * Order is load-bearing — `oneOf` and `enum` are matched before the plain
- * `type` rules, exactly as the original ladder short-circuited.
+ * `type` rules.
  *
  * @type {Array<{ when: (flat: object) => boolean, render: (flat: object) => string }>}
  */
 const TYPE_RULES = [
-  // The only oneOf in the schema is `listOrExtenderOfStrings`.
   {
-    when: (flat) => Array.isArray(flat.oneOf),
+    // The list-or-extender union: a plain `string[]` (replace) or an
+    // `{ append?, prepend? }` object that deep-merges with the framework list.
+    when: (flat) =>
+      Array.isArray(flat.oneOf) &&
+      flat.oneOf.some((m) => m?.properties?.append || m?.properties?.prepend),
     render: () => '`string[]` or `{ append?, prepend? }`',
   },
+  {
+    when: (flat) => Array.isArray(flat.oneOf),
+    render: (flat) =>
+      `one of: ${flat.oneOf.map((m) => `\`${m?.type ?? '?'}\``).join(', ')}`,
+  },
   {
     when: (flat) => Array.isArray(flat.enum),
     render: (flat) =>
@@ -228,32 +290,31 @@ const TYPE_RULES = [
 ];
 
 /**
- * Render the "Type" cell for a schema node. The agentrc schema uses a few
- * recurring shapes — string, integer, number, boolean, array, object,
- * `oneOf` (the `listOrExtenderOfStrings` extender form), enum, and nullable
- * variants. Anything else falls through to a `?` so missing coverage is
- * visible rather than silently wrong.
+ * Render the "Type" cell for a schema node. Anything the table does not match
+ * falls through to a `?` so missing coverage is visible rather than silently
+ * wrong.
  *
- * @param {object} schema
  * @param {object} node
  * @returns {string}
  */
-function renderType(schema, node) {
+function renderType(node) {
   if (!node || typeof node !== 'object') return '?';
-  const flat = flattenAllOf(schema, node);
+  const flat = flattenAllOf(node);
   const rule = TYPE_RULES.find((r) => r.when(flat));
   return rule ? rule.render(flat) : '?';
 }
 
 /**
- * Render the "Default" cell. Schemas without an explicit `default` get an
- * em dash — the value is documented prose-side in `.agents/docs/configuration.md`.
+ * Render the "Default" cell. Nodes without an explicit `default` annotation
+ * get an em dash — see the annotation contract in `config-settings-schema.js`
+ * for why a key can have a runtime default and no annotation.
  *
- * @param {unknown} value
+ * @param {object} node
  * @returns {string}
  */
-function renderDefault(value) {
-  if (value === undefined) return '—';
+function renderDefault(node) {
+  if (!node || !Object.hasOwn(node, 'default')) return '—';
+  const value = node.default;
   if (value === null) return '`null`';
   if (typeof value === 'string') return `\`"${value}"\``;
   if (typeof value === 'boolean' || typeof value === 'number') {
@@ -282,11 +343,10 @@ function escapeCell(text) {
  * Returns `null` when `flat` is not a properties-bearing object, so the
  * caller can fall through to the next row shape.
  *
- * @param {object} schema
  * @param {{flat: object, keyPath: string, pathParts: string[], propName: string, isRequired: boolean, description: string}} ctx
  * @returns {Array<object> | null}
  */
-function nestedObjectRows(schema, ctx) {
+function nestedObjectRows(ctx) {
   const { flat, keyPath, pathParts, propName, isRequired, description } = ctx;
   if (flat.type !== 'object' || !flat.properties) return null;
   const childRequired = new Set(
@@ -297,10 +357,10 @@ function nestedObjectRows(schema, ctx) {
       key: keyPath,
       required: isRequired ? 'Yes' : 'No',
       type: '`object`',
-      def: renderDefault(flat.default),
+      def: renderDefault(flat),
       description: description || 'Nested configuration block.',
     },
-    ...flattenObject(schema, flat, [...pathParts, propName], childRequired),
+    ...flattenObject(flat, [...pathParts, propName], childRequired),
   ];
 }
 
@@ -309,28 +369,24 @@ function nestedObjectRows(schema, ctx) {
  * describing the item shape in the Description cell. Returns `null` when the
  * property is not an array whose items are a properties-bearing object.
  *
- * @param {object} schema
  * @param {{flat: object, keyPath: string, isRequired: boolean, description: string}} ctx
  * @returns {Array<object> | null}
  */
-function arrayOfObjectsRows(schema, ctx) {
+function arrayOfObjectsRows(ctx) {
   const { flat, keyPath, isRequired, description } = ctx;
   if (flat.type !== 'array' || !flat.items) return null;
-  const { node: itemNode, refName } = resolveNode(schema, flat.items);
+  const itemNode = flat.items;
   if (!itemNode || itemNode.type !== 'object' || !itemNode.properties) {
     return null;
   }
   const itemKeys = Object.keys(itemNode.properties).join(', ');
-  const suffix = refName ? ` (\`${refName}\`)` : '';
-  const desc =
-    (description ? `${description} ` : '') +
-    `Each item${suffix} has: ${itemKeys}.`;
+  const desc = `${description ? `${description} ` : ''}Each item has: ${itemKeys}.`;
   return [
     {
       key: `${keyPath}[]`,
       required: isRequired ? 'Yes' : 'No',
-      type: renderType(schema, flat),
-      def: renderDefault(flat.default),
+      type: renderType(flat),
+      def: renderDefault(flat),
       description: desc,
     },
   ];
@@ -341,66 +397,61 @@ function arrayOfObjectsRows(schema, ctx) {
  * it is the fallthrough shape when neither the nested-object nor the
  * array-of-objects builder applied.
  *
- * @param {object} schema
  * @param {{flat: object, keyPath: string, isRequired: boolean, description: string}} ctx
  * @returns {Array<object>}
  */
-function leafRow(schema, ctx) {
+function leafRow(ctx) {
   const { flat, keyPath, isRequired, description } = ctx;
   return [
     {
       key: keyPath,
       required: isRequired ? 'Yes' : 'No',
-      type: renderType(schema, flat),
-      def: renderDefault(flat.default),
+      type: renderType(flat),
+      def: renderDefault(flat),
       description: description || '—',
     },
   ];
 }
 
 // Ordered row-shape builders for one property. The loop in flattenObject
-// returns the first builder that yields rows (non-null), matching the
-// original if/continue ladder: nested-object first, array-of-objects next,
-// scalar leaf as the always-matching fallthrough.
+// returns the first builder that yields rows (non-null): nested-object first,
+// array-of-objects next, scalar leaf as the always-matching fallthrough.
 const ROW_BUILDERS = [nestedObjectRows, arrayOfObjectsRows, leafRow];
 
 /**
- * Flatten one object-typed schema node into table rows. Recurses into
- * nested `object` properties (resolving `$ref`s along the way) so dot-paths
- * like `paths.agentRoot` and `branchProtection.requiredChecks` show up as
- * individual rows.
+ * Flatten one object-typed schema node into table rows. Recurses into nested
+ * `object` properties so dot-paths like `paths.agentRoot` and
+ * `branchProtection.requiredChecks` show up as individual rows.
  *
- * Arrays of objects (`requiredChecks[]`, `routes[]`, `bundles[]`) are
- * emitted as a single row whose Key column carries a `[]` suffix; the row's
- * item shape is captured in the Description cell. This keeps the output
- * legible without exploding into per-item-property rows.
+ * Arrays of objects (`requiredChecks[]`, `routes[]`, `bundles[]`) are emitted
+ * as a single row whose Key column carries a `[]` suffix; the item shape is
+ * captured in the Description cell. This keeps the output legible without
+ * exploding into per-item-property rows.
  *
- * @param {object} schema     Root schema (for ref resolution).
  * @param {object} node       Schema node to flatten.
  * @param {string[]} pathParts Dot-path accumulator.
  * @param {Set<string>} required Required-property names on the parent.
  * @returns {Array<{key:string, required:string, type:string, def:string, description:string}>}
  */
-function flattenObject(schema, node, pathParts, required) {
+function flattenObject(node, pathParts, required) {
   const rows = [];
   const properties = node.properties || {};
   const localRequired = new Set(
     Array.isArray(node.required) ? node.required : [],
   );
 
-  for (const [propName, rawChild] of Object.entries(properties)) {
-    const { node: child } = resolveNode(schema, rawChild);
-    const flat = flattenAllOf(schema, child);
+  for (const [propName, child] of Object.entries(properties)) {
+    const flat = flattenAllOf(child);
     const ctx = {
       flat,
       keyPath: [...pathParts, propName].join('.'),
       pathParts,
       propName,
       isRequired: required.has(propName) || localRequired.has(propName),
-      description: flat.description || rawChild.description || '',
+      description: flat.description || '',
     };
     for (const build of ROW_BUILDERS) {
-      const built = build(schema, ctx);
+      const built = build(ctx);
       if (built !== null) {
         rows.push(...built);
         break;
@@ -419,13 +470,11 @@ function flattenObject(schema, node, pathParts, required) {
  * @returns {string}
  */
 function renderSection(schema, topKey) {
-  const rootProps = schema.properties || {};
-  const rawNode = rootProps[topKey];
-  if (!rawNode) {
+  const node = (schema.properties || {})[topKey];
+  if (!node) {
     throw new Error(`Top-level key "${topKey}" missing from schema.properties`);
   }
-  const { node } = resolveNode(schema, rawNode);
-  const flat = flattenAllOf(schema, node);
+  const flat = flattenAllOf(node);
 
   if (flat.type !== 'object' || !flat.properties) {
     throw new Error(
@@ -441,7 +490,7 @@ function renderSection(schema, topKey) {
     Array.isArray(flat.required) ? flat.required : [],
   );
 
-  const rows = flattenObject(schema, flat, [], childRequired);
+  const rows = flattenObject(flat, [], childRequired);
   const header = `### \`${topKey}\` ${sectionRequired ? '(required)' : '(optional)'}`;
   const tableHeader = '| Key | Required | Type | Default | Description |';
   const tableSep = '| --- | --- | --- | --- | --- |';
@@ -467,10 +516,13 @@ function renderSection(schema, topKey) {
 function renderRegion(schema) {
   const blocks = [
     '',
-    '> Generated by `node .agents/scripts/generate-config-docs.js` from',
-    `> [\`.agents/schemas/agentrc.schema.json\`](../schemas/agentrc.schema.json).`,
-    '> Edit the schema (and its AJV mirror under `.agents/scripts/lib/`),',
-    '> then re-run the generator — do not hand-edit this region.',
+    '> Generated by `node .agents/scripts/generate-config-docs.js` from the',
+    '> runtime AJV schema in',
+    '> [`.agents/scripts/lib/config-settings-schema.js`](../scripts/lib/config-settings-schema.js).',
+    '> Edit the `description` / `default` annotations on those schema literals',
+    '> and re-run `npm run docs:gen` — do not hand-edit this region, and do not',
+    '> hand-edit `agentrc.schema.json` or `agentrc-reference.json` either: both',
+    '> are emitted by the same generator.',
     '',
   ];
   for (const key of TOP_LEVEL_KEYS) {
@@ -541,21 +593,53 @@ function spliceRegion(original, body) {
 }
 
 /**
- * Build the canonical post-generation file content.
+ * Build every generated artifact from `schema` and pair each with what is on
+ * disk today.
+ *
+ * The JSON artifacts compare canonically (see the module header); the
+ * Markdown artifact compares raw, because its region is spliced into
+ * hand-authored prose that must survive byte-for-byte.
  *
- * @param {string} schemaPath
- * @param {string} docPath
- * @returns {{ generated: string, original: string }}
+ * @param {{ schema?: object, schemaPath?: string, referencePath?: string,
+ *   docPath?: string }} [opts]
+ * @returns {Array<{ name: string, file: string, generated: string,
+ *   current: string | null, stale: boolean }>}
  */
-function buildExpected(schemaPath, docPath) {
+function buildArtifacts(opts = {}) {
+  const {
+    schema = AGENTRC_SCHEMA,
+    schemaPath = SCHEMA_PATH,
+    referencePath = REFERENCE_PATH,
+    docPath = DOC_PATH,
+  } = opts;
+
   if (!fs.existsSync(docPath)) {
     throw new Error(`Target doc not found: ${docPath}`);
   }
-  const original = fs.readFileSync(docPath, 'utf8');
-  const schema = readSchema(schemaPath);
-  const body = renderRegion(schema);
-  const generated = spliceRegion(original, body);
-  return { generated, original };
+  const docOriginal = fs.readFileSync(docPath, 'utf8');
+
+  const artifacts = [
+    {
+      name: 'mirror schema',
+      file: schemaPath,
+      generated: canonicalJson(buildMirrorSchema(schema)),
+      current: readCanonicalJson(schemaPath),
+    },
+    {
+      name: 'defaults inventory',
+      file: referencePath,
+      generated: canonicalJson(buildReferenceInventory(schema)),
+      current: readCanonicalJson(referencePath),
+    },
+    {
+      name: 'configuration.md key table',
+      file: docPath,
+      generated: spliceRegion(docOriginal, renderRegion(schema)),
+      current: docOriginal,
+    },
+  ];
+  for (const a of artifacts) a.stale = a.generated !== a.current;
+  return artifacts;
 }
 
 /**
@@ -570,39 +654,47 @@ async function main(argv = process.argv.slice(2)) {
     allowPositionals: false,
   });
 
-  const { generated, original } = buildExpected(SCHEMA_PATH, DOC_PATH);
+  const artifacts = buildArtifacts();
+  const stale = artifacts.filter((a) => a.stale);
+  const rel = (f) => path.relative(PROJECT_ROOT, f);
 
   if (values.check) {
-    if (generated === original) {
+    if (stale.length === 0) {
       Logger.info(
-        `generate-config-docs: ${path.relative(PROJECT_ROOT, DOC_PATH)} is up to date.`,
+        `generate-config-docs: all ${artifacts.length} generated config artifacts are up to date.`,
       );
       return;
     }
-    const hint =
-      `${path.relative(PROJECT_ROOT, DOC_PATH)} is out of date. ` +
-      'Run `node .agents/scripts/generate-config-docs.js` to regenerate the bounded region.';
-    throw new Error(hint);
+    throw new Error(
+      `${stale.length} generated config artifact(s) drifted from the runtime schema: ` +
+        `${stale.map((a) => `${a.name} (${rel(a.file)})`).join(', ')}. ` +
+        'Run `node .agents/scripts/generate-config-docs.js` to regenerate.',
+    );
   }
 
-  if (generated === original) {
+  if (stale.length === 0) {
     Logger.info(
-      `generate-config-docs: ${path.relative(PROJECT_ROOT, DOC_PATH)} already current — no write.`,
+      'generate-config-docs: every generated config artifact already current — no write.',
     );
     return;
   }
-  fs.writeFileSync(DOC_PATH, generated, 'utf8');
+  for (const a of stale) {
+    fs.writeFileSync(a.file, a.generated, 'utf8');
+  }
   Logger.info(
-    `generate-config-docs: wrote bounded region into ${path.relative(PROJECT_ROOT, DOC_PATH)}.`,
+    `generate-config-docs: rewrote ${stale.map((a) => rel(a.file)).join(', ')}.`,
   );
 }
 
 export {
-  buildExpected,
+  buildArtifacts,
+  buildMirrorSchema,
+  buildReferenceInventory,
+  canonicalJson,
+  collectDefaults,
   flattenObject,
   REGION_BEGIN,
   REGION_END,
-  readSchema,
   renderRegion,
   renderSection,
   spliceRegion,
@@ -613,11 +705,11 @@ runAsCli(import.meta.url, main, {
   usage: {
     invocation: 'node .agents/scripts/generate-config-docs.js [--check]',
     summary:
-      'Regenerate the configuration reference from the .agentrc schema. Writes only when the generated content differs.',
+      'Regenerate the three .agentrc config artifacts (JSON-Schema mirror, defaults inventory, configuration.md key table) from the runtime AJV schema. Writes only what drifted.',
     flags: [
       [
         '--check',
-        'Verify the doc is current and fail if stale; write nothing.',
+        'Verify every artifact is current and fail naming the stale ones; write nothing.',
       ],
     ],
   },