@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/gen-api-docs.js

@@ -0,0 +1,1111 @@
+#!/usr/bin/env node
+'use strict';
+// gen-api-docs.js — generate a standards-compliant OpenAPI 3.1 spec + a human/AI
+// Markdown reference DIRECTLY FROM the live route files (task 1918, BONGOS-V1).
+//
+// WHY: the GDS API had no machine-readable contract — the only endpoint doc was a
+// hand-maintained mirror (docs/routes-permissions.md) that drifted from the code.
+// An AI agent hitting the API had nothing standard to read. This generator emits
+// OpenAPI 3.1 — the format every tool (Postman, Swagger, Redoc, LLM tool-callers)
+// already understands — from the SAME route-introspection engine the ship-time
+// rank gate uses (src/bongos/route-rank-check.js). So the docs enumerate EXACTLY the
+// routes the server mounts and cannot silently drift.
+//
+// DESIGN (mirrors gen-repo-map.js / ADR 0063):
+//   - Deterministic: no timestamps, stable sort — so `--check` is a clean CI gate.
+//   - Zero runtime deps: a line+regex extractor over the route source, plus a
+//     built-in structural OpenAPI validator (no @redocly/cli in the critical path;
+//     run `npm run docs:api:lint` for the full standard lint on demand).
+//   - Two-root aware (ADR 0108): route discovery + doc writes route through
+//     resolveCoreRoot(); never hardcode path.resolve(__dirname,'..','..').
+//
+// Writes (all deterministic):
+//   docs/api/openapi.json      — OpenAPI 3.1, the machine-readable contract
+//   docs/api-reference.md       — grouped Markdown reference (for humans + AI)
+//   docs/routes-permissions.md  — generated pointer stub (the retired hand-mirror)
+//
+// Usage:
+//   node scripts/bongos/gen-api-docs.js            # regenerate the three files
+//   node scripts/bongos/gen-api-docs.js --check     # write nothing; exit 1 if the spec is not valid
+//                                                   # OpenAPI 3.1, exit 2 if the committed stub drifted.
+//                                                   # openapi.json + api-reference.md are gitignored
+//                                                   # (task 1004866) and never compared.
+//   node scripts/bongos/gen-api-docs.js --json      # print the extracted model as JSON (debug)
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { resolveCoreRoot, resolveDocsRoot } = require('../../src/instance-config');
+const rrc = require('../../src/bongos/route-rank-check');
+// Destructured, not reached through `rrc.` — knip tracks a destructured CJS require but
+// not namespace member access, so `rrc.canonicalRoutePath(...)` read as an unused export
+// and tripped the dead-code ratchet (knip_issue_count 224 > baseline 223) even though the
+// call site below is real. The named import is how a new helper on this module gets
+// counted as used (task 1003747).
+const { canonicalRoutePath } = require('../../src/bongos/route-rank-check');
+const { API_PREFIX, API_VERSION, VERSIONED_API_PREFIX } = require('../../src/bongos/api-prefix');
+// Task 2050 (ADR 0118): the enriched extractor resolves named constants used in
+// validate() rules. Both requires are pure (no side effects / no DB / no express):
+// _helpers exports the LIMITS caps; api-errors is the kernel error registry whose
+// category taxonomy the spec advertises (ADR 0116). Keep them pure — the generator
+// must never execute a route file or open a connection.
+const { LIMITS } = require('../../src/bongos/routes/_helpers');
+const { sameContent } = require('./gen-freshness'); // eol-insensitive freshness (CRLF checkouts)
+const apiErrors = require('../../src/bongos/api-errors');
+
+const CORE_ROOT = resolveCoreRoot();
+// Routes are READ from the core (CORE_ROOT, via route-rank-check); the generated
+// spec + reference are WRITTEN to the DOCS root — the instance repo when a consumer
+// points at it (`bongos upgrade`), the same coreRoot in a single checkout (ADR 0108,
+// task 2051). So `bongos upgrade` refreshes the CONSUMER's docs, not node_modules.
+const DOCS_ROOT = resolveDocsRoot();
+const OPENAPI_PATH = path.join(DOCS_ROOT, 'docs', 'api', 'openapi.json');
+const REFERENCE_PATH = path.join(DOCS_ROOT, 'docs', 'api-reference.md');
+const PERMISSIONS_PATH = path.join(DOCS_ROOT, 'docs', 'routes-permissions.md');
+
+// Spec version tracks the core package version — deterministic (no build clock).
+function specVersion() {
+  try {
+    return require(path.join(CORE_ROOT, 'package.json')).version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+// Human-facing product name for the spec title, from the branding pack. Best-effort:
+// a branding hiccup must not break doc generation (falls back to a neutral name).
+function productName() {
+  try {
+    const { branding } = require('../../src/branding');
+    const b = branding();
+    return (b.identity && (b.identity.productName || b.identity.worldName)) || 'Cloud Bongos';
+  } catch {
+    return 'Cloud Bongos';
+  }
+}
+
+const METHOD_ORDER = ['get', 'post', 'put', 'patch', 'delete'];
+
+const RANK_BLURB = {
+  public: 'No authentication — any caller.',
+  'any-builder': 'Any authenticated builder (row-level ownership enforced in-handler).',
+  'metic+archon': 'Metic or Archon rank (review/triage powers).',
+  archon: 'Archon only (rank and identity management + the escalation keys — the trust boundary).',
+  'bfg-principal': 'The BFG cross-builder memory service principal (not a human rank).',
+  unknown: 'Gate could not be classified from source — treat as privileged.',
+};
+
+// ---------------------------------------------------------------------------
+// Extraction (per route file)
+// ---------------------------------------------------------------------------
+
+// The contiguous `//` comment block immediately above line i, `//` stripped and
+// joined. A leading "rank: <val> — " token is dropped so the prose that remains is
+// the human rationale (the rank itself is captured structurally). Blank lines and
+// code end the block.
+// Route-comment descriptions carry bare "#NNN" GDS task refs (e.g. "V3.R91 / #401").
+// Emitted verbatim they mis-render as GitHub *issue* links in the committed
+// docs/api-reference.md AND trip the doc-ref-linkify CI gate — while gen-api-docs
+// --check demands the committed file match this generator's output, so the two
+// checks would fight over the generated file forever. Neutralize the refs at their
+// single origin to plain "task NNN" (brand-neutral, deterministic, and what
+// linkify-refs treats as clean — it never rewrites a hostname). Only a #-prefixed
+// run of digits is touched; "V3.R91", anchors like "#/task", and "# heading" are left
+// alone. (task 1918 follow-up; surfaced landing task 1915.)
+function neutralizeTaskRefs(text) {
+  return String(text || '').replace(/#(\d{1,6})\b/g, 'task $1');
+}
+
+function commentBlockAbove(lines, i) {
+  const buf = [];
+  for (let j = i - 1; j >= 0; j--) {
+    const line = lines[j];
+    if (/^\s*\/\//.test(line)) {
+      buf.unshift(line.replace(/^\s*\/\/\s?/, ''));
+      continue;
+    }
+    break; // blank or code — stop
+  }
+  let text = buf.join(' ').replace(/\s+/g, ' ').trim();
+  text = text.replace(/^rank:\s*[a-z+-]+\s*(?:—|-|:)?\s*/i, '').trim();
+  return neutralizeTaskRefs(text);
+}
+
+// An Express inline param constraint — `:id(\d+)` (task 1003747). It is a ROUTING
+// detail, never part of the URL a caller types, so it is stripped everywhere a
+// route string reaches a reader or the spec. Without this, `/inbox/:id(\d+)`
+// generated the path template `/inbox/{id}(\\d+)` (malformed — it would break the
+// generated client), renamed the operationId `get_inbox_id` → `get_inbox_id_d`
+// (a silent breaking change for every client consumer), and printed the regex in
+// the public API reference.
+// The canonicaliser itself lives in route-rank-check, next to scanDeclarations — the
+// scanner this generator already shares with the auditor — so there is ONE definition
+// rather than a copy per consumer. Declarations therefore arrive canonical already;
+// this wrapper stays because pathParams/routeForDisplay are pure exported helpers that
+// callers (and tests/api_docs.mjs) hand raw strings to directly.
+function routeForDisplay(route) {
+  return canonicalRoutePath(String(route || ''));
+}
+
+// :param → {param}; also return the ordered param name list. Inline constraints
+// are dropped first so the template stays a valid OpenAPI path.
+function pathParams(route) {
+  const names = [];
+  const openapiPath = routeForDisplay(route).replace(/:([A-Za-z0-9_]+)/g, (_, n) => {
+    names.push(n);
+    return `{${n}}`;
+  });
+  return { openapiPath, names };
+}
+
+// Strip // line comments and /* */ block comments, honoring string literals — so
+// a schema literal's inline comments (`parallel_safe: {}, // note`) don't derail
+// the brace/key scan below.
+function stripComments(str) {
+  let out = '';
+  let quote = null;
+  for (let k = 0; k < str.length; k++) {
+    const c = str[k];
+    const n = str[k + 1];
+    if (quote) {
+      out += c;
+      if (c === '\\') { out += n == null ? '' : n; k++; continue; }
+      if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === '`') { quote = c; out += c; continue; }
+    if (c === '/' && n === '/') { while (k < str.length && str[k] !== '\n') k++; out += '\n'; continue; }
+    if (c === '/' && n === '*') { k += 2; while (k < str.length && !(str[k] === '*' && str[k + 1] === '/')) k++; k++; continue; }
+    out += c;
+  }
+  return out;
+}
+
+// Capture the balanced {...} literal starting at the first '{' at or after `from`.
+// Returns the substring (incl. braces) or null. String/char literals are skipped
+// so a brace inside a quoted default doesn't unbalance the scan.
+function captureBalanced(str, from) {
+  const open = str.indexOf('{', from);
+  if (open === -1) return null;
+  let depth = 0;
+  let quote = null;
+  for (let k = open; k < str.length; k++) {
+    const c = str[k];
+    if (quote) {
+      if (c === '\\') { k++; continue; }
+      if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === '`') { quote = c; continue; }
+    if (c === '{') depth++;
+    else if (c === '}') { depth--; if (depth === 0) return str.slice(open, k + 1); }
+  }
+  return null;
+}
+
+// Top-level `identifier:` keys of an object-literal string (depth-1 only).
+// Strips comments first so it is robust regardless of caller (idempotent on
+// already-stripped input).
+function topLevelKeys(objLiteral) {
+  const inner = stripComments(objLiteral).slice(1, -1);
+  const keys = [];
+  let depth = 0;
+  let quote = null;
+  let atFieldStart = true;
+  let ident = '';
+  for (let k = 0; k < inner.length; k++) {
+    const c = inner[k];
+    if (quote) {
+      if (c === '\\') { k++; continue; }
+      if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === '`') { quote = c; ident = ''; atFieldStart = false; continue; }
+    if (c === '{' || c === '[' || c === '(') { depth++; atFieldStart = false; ident = ''; continue; }
+    if (c === '}' || c === ']' || c === ')') { depth--; continue; }
+    if (depth === 0) {
+      if (c === ',') { atFieldStart = true; ident = ''; continue; }
+      if (c === ':' && ident) { keys.push(ident); ident = ''; atFieldStart = false; continue; }
+      if (atFieldStart && /[A-Za-z0-9_$]/.test(c)) { ident += c; continue; }
+      if (!/\s/.test(c)) { ident = ''; atFieldStart = false; }
+    }
+  }
+  return keys;
+}
+
+// ---------------------------------------------------------------------------
+// Rule-set extraction (task 2050 / ADR 0118 §1 "enrich the generator")
+// ---------------------------------------------------------------------------
+//
+// The per-route validate() schema object is already structured data (_helpers.js):
+// each field's rule carries type/required/enum/min/max/minLength/maxLength/
+// itemsType/maxItems. We parse that rule set (not just field names) so the spec can
+// emit typed request schemas + named components.schemas. Values are resolved
+// STATICALLY — the generator NEVER executes a route file (the stripComments/
+// captureBalanced philosophy). Literals resolve directly; a named constant
+// (LIMITS.TITLE, a file-local `const CAP = 64`) resolves via a per-file constants
+// map; an unresolvable expression (e.g. a computed bound) is simply omitted from
+// that ONE annotation — the field's type still emits, so a schema degrades
+// gracefully and never emits a wrong constraint.
+
+const KNOWN_TYPES = new Set(['string', 'number', 'integer', 'boolean', 'array', 'object']);
+const RULE_NUM_KEYS = ['maxLength', 'minLength', 'min', 'max', 'maxItems'];
+// Only digits, numeric separators, and arithmetic operators — no identifiers. A
+// string matching this is safe to evaluate (it cannot reference anything).
+const NUMERIC_ARITH_RE = /^[-+*/()\s\d._]+$/;
+
+// Split an object/array INNER (braces/brackets already stripped) on depth-0 commas,
+// honoring string literals and nesting. Returns the raw segments (untrimmed).
+function splitTopLevel(inner) {
+  const parts = [];
+  let depth = 0;
+  let quote = null;
+  let start = 0;
+  for (let k = 0; k < inner.length; k++) {
+    const c = inner[k];
+    if (quote) {
+      if (c === '\\') { k++; continue; }
+      if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === '`') { quote = c; continue; }
+    if (c === '{' || c === '[' || c === '(') depth++;
+    else if (c === '}' || c === ']' || c === ')') depth--;
+    else if (c === ',' && depth === 0) { parts.push(inner.slice(start, k)); start = k + 1; }
+  }
+  if (inner.slice(start).trim() !== '') parts.push(inner.slice(start));
+  return parts;
+}
+
+// Split "key: value" on the FIRST depth-0 colon. Returns { key, value } (both
+// trimmed; key unquoted) or null for a shorthand / non-key-value segment.
+function splitKeyValue(segment) {
+  let depth = 0;
+  let quote = null;
+  for (let k = 0; k < segment.length; k++) {
+    const c = segment[k];
+    if (quote) {
+      if (c === '\\') { k++; continue; }
+      if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === '`') { quote = c; continue; }
+    if (c === '{' || c === '[' || c === '(') depth++;
+    else if (c === '}' || c === ']' || c === ')') depth--;
+    else if (c === ':' && depth === 0) {
+      const key = segment.slice(0, k).trim().replace(/^['"`]|['"`]$/g, '');
+      return { key, value: segment.slice(k + 1).trim() };
+    }
+  }
+  return null;
+}
+
+// Top-level `key: value` entries of an object literal (depth-1), value kept as its
+// raw source substring. Comments are stripped first (idempotent).
+function topLevelEntries(objLiteral) {
+  const inner = stripComments(String(objLiteral)).trim().replace(/^\{/, '').replace(/\}$/, '');
+  const entries = [];
+  for (const seg of splitTopLevel(inner)) {
+    const kv = splitKeyValue(seg);
+    if (kv && /^[A-Za-z_$][\w$]*$/.test(kv.key)) entries.push(kv);
+  }
+  return entries;
+}
+
+// Walk a dotted path (LIMITS.TITLE, TASK_FIELD_BOUNDS.priority.min) against the
+// constants map. Returns the primitive/array value or undefined.
+function resolveConst(pathExpr, constants) {
+  let cur = constants;
+  for (const p of pathExpr.split('.')) {
+    if (cur == null || typeof cur !== 'object' || !(p in cur)) return undefined;
+    cur = cur[p];
+  }
+  return (cur !== null && (typeof cur !== 'object' || Array.isArray(cur))) ? cur : undefined;
+}
+
+// Resolve a scalar rule value: boolean/number/string literal, pure numeric
+// arithmetic (30 * 1024 * 1024, 2_000_000), or a named constant. Undefined if
+// unresolvable (a computed/dynamic expression).
+function resolveScalar(expr, constants = {}) {
+  const s = String(expr).trim();
+  if (s === 'true') return true;
+  if (s === 'false') return false;
+  const str = /^(['"`])([\s\S]*)\1$/.exec(s);
+  if (str) return str[2];
+  if (NUMERIC_ARITH_RE.test(s) && /\d/.test(s)) {
+    try {
+      // Safe: charset-restricted to digits/separators/operators/parens — no identifiers.
+      const v = Function('"use strict"; return (' + s.replace(/_/g, '') + ');')();
+      if (typeof v === 'number' && Number.isFinite(v)) return v;
+    } catch { /* not a number after all */ }
+    return undefined;
+  }
+  if (/^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)*$/.test(s)) return resolveConst(s, constants);
+  return undefined;
+}
+
+// Resolve an array rule value (enum): a literal array of literals, or a named
+// constant that resolves to such an array. All-or-nothing — if any element is
+// unresolvable the enum is dropped (never emit a partial/wrong enum).
+function resolveArray(expr, constants = {}) {
+  const s = String(expr).trim();
+  if (s.startsWith('[') && s.endsWith(']')) {
+    const out = [];
+    for (const seg of splitTopLevel(s.slice(1, -1))) {
+      if (seg.trim() === '') continue;
+      const v = resolveScalar(seg, constants);
+      if (v === undefined) return undefined;
+      out.push(v);
+    }
+    return out;
+  }
+  const c = resolveConst(s, constants);
+  return Array.isArray(c) ? c : undefined;
+}
+
+// Parse one field's rule object → the recognized, resolved constraint keys.
+function parseRule(ruleLiteral, constants = {}) {
+  const rule = {};
+  if (!/^\s*\{/.test(String(ruleLiteral))) return rule; // `field: SOMETHING` non-object → unconstrained
+  for (const { key, value } of topLevelEntries(ruleLiteral)) {
+    if (key === 'required') {
+      if (resolveScalar(value, constants) === true) rule.required = true;
+    } else if (key === 'type' || key === 'itemsType') {
+      const v = resolveScalar(value, constants);
+      if (typeof v === 'string' && KNOWN_TYPES.has(v)) rule[key] = v;
+    } else if (key === 'enum') {
+      const v = resolveArray(value, constants);
+      if (Array.isArray(v) && v.length) rule.enum = v;
+    } else if (RULE_NUM_KEYS.includes(key)) {
+      const v = resolveScalar(value, constants);
+      if (typeof v === 'number' && Number.isFinite(v)) rule[key] = v;
+    }
+  }
+  return rule;
+}
+
+// Per-file constants map: top-level single-line `const NAME = <literal>` decls
+// (numbers, arithmetic, strings, arrays of literals). Catches the file-local caps
+// + enum arrays (CLAIM_OUTCOMES, INBOX_STATUS_VALUES, SECURITY_DOC_CONTENT_MAX,
+// PUBLISH_BUNDLE_B64_MAX). Merged over the global constants (LIMITS).
+function scanFileConstants(source) {
+  const out = {};
+  const re = /^\s*const\s+([A-Za-z_$][\w$]*)\s*=\s*([^;\n]+);?\s*$/gm;
+  let m;
+  while ((m = re.exec(source))) {
+    const name = m[1];
+    const rhs = m[2].trim();
+    const v = rhs.startsWith('[') ? resolveArray(rhs, out) : resolveScalar(rhs, out);
+    if (v !== undefined) out[name] = v;
+  }
+  return out;
+}
+
+// Global constants available to every route file: the LIMITS caps (the dominant
+// referenced constant). TASK_FIELD_BOUNDS is imported (not file-local) so its
+// bounds are omitted — the affected fields still emit their integer type.
+function globalConstants() {
+  return { LIMITS: LIMITS || {} };
+}
+
+// The source line where THIS route's handler ends — the next router.<verb>(
+// declaration, or +200 lines, whichever comes first. Bounds the window both the
+// request- and response-shape extractors scan so they never bleed into the next
+// handler.
+function routeEndLine(lines, i) {
+  for (let j = i + 1; j < lines.length && j < i + 200; j++) {
+    if (/^\s*router\.(get|post|patch|put|delete)\s*\(/.test(lines[j])) return j;
+    if (j === i + 199) return j;
+  }
+  return lines.length;
+}
+
+// Request-body shape for a write route: does it read req.body, is it validated, and
+// (best-effort) the top-level field names from its validateOrRespond/validate schema.
+function extractBody(lines, i, method, constants = {}) {
+  if (!['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) return null;
+  // Window: from this route to the next route declaration (or +200 lines).
+  const end = routeEndLine(lines, i);
+  const window = stripComments(lines.slice(i, end).join('\n'));
+  const readsBody = /\breq\.body\b/.test(window);
+  const orRespond = /validateOrRespond\s*\(\s*req\s*,\s*res\s*,/.exec(window);
+  const lowLevel = /\bvalidate\s*\(\s*req\.body/.exec(window);
+  const validateCall = orRespond || lowLevel;
+  const fields = [];
+  const rules = {};
+  // validateOrRespond REJECTS unknown fields by default (R11/#1998); the low-level
+  // validate() defaults lenient. `strict` drives additionalProperties in the spec.
+  let strict = false;
+  if (validateCall) {
+    const after = validateCall.index + validateCall[0].length;
+    let lit = captureBalanced(window, after);
+    // captureBalanced seeks the NEXT '{' anywhere — when the third argument is
+    // an identifier, that grabs some unrelated later block. Only trust the
+    // capture when the brace directly follows the call.
+    if (lit && !/^\s*\{/.test(window.slice(after))) lit = null;
+    if (!lit) {
+      // Schema hoisted to a module-scope const (the boot-loud enum-spread
+      // pattern, task 1003057): resolve `validateOrRespond(req, res, IDENT)`
+      // against `const IDENT = [Object.freeze(] { … }` anywhere in the file,
+      // so hoisting a schema never silently drops a route from the API docs.
+      const ident = /^\s*([A-Za-z_$][\w$]*)\s*[,)]/.exec(window.slice(after));
+      if (ident) {
+        const whole = stripComments(lines.join('\n'));
+        const decl = new RegExp(`const\\s+${ident[1]}\\s*=\\s*(?:Object\\.freeze\\s*\\(\\s*)?`).exec(whole);
+        if (decl) lit = captureBalanced(whole, decl.index + decl[0].length);
+      }
+    }
+    if (lit) {
+      for (const { key, value } of topLevelEntries(lit)) {
+        if (/^\d/.test(key)) continue; // defensive: no numeric-leading field names
+        fields.push(key);
+        rules[key] = parseRule(value, constants);
+      }
+      if (orRespond) {
+        // The opts arg follows the schema literal; strict unless it passes
+        // strict:false. When the schema was resolved from a module-scope const,
+        // the literal is not in the window — read the call tail instead.
+        const litAt = window.indexOf(lit, after);
+        const optsWindow = litAt >= 0 ? window.slice(litAt + lit.length) : window.slice(after);
+        strict = !/\bstrict\s*:\s*false\b/.test(optsWindow);
+      }
+    }
+  }
+  if (!readsBody && !validateCall) return null;
+  return { readsBody, validated: Boolean(validateCall), fields, rules, strict };
+}
+
+// ---------------------------------------------------------------------------
+// Response-shape extraction (task 2061 / ADR 0124 — type the success RESPONSE)
+// ---------------------------------------------------------------------------
+//
+// Task 2050 typed the REQUEST body from validate(); the SUCCESS response stayed
+// `any`. Routes declare no response schema, but they DO build the body inline —
+// `res.json({ … })` — and that object literal IS the shape. We read it statically
+// (the same captureBalanced/splitTopLevel machinery the request extractor uses),
+// never executing a route. Only the KEYS are provable (a value is usually a
+// variable, so it types as `unknown`); two values type safely — a boolean literal,
+// and the ADR-0119 `pageMeta()` `page` block (→ the shared PageInfo component).
+//
+// DEGRADE-GRACEFULLY CONTRACT — never emit a shape we cannot prove:
+//   - a bare-value response (`res.json(row)`), a top-level spread (`{ …rest }`),
+//     a computed/quoted key, or an empty `{}` → the route keeps the `ApiResponse`
+//     alias (extractResponse returns null). We only ever NARROW `any`, never lie.
+
+// The value expression of one response property → a JSON Schema fragment. Only two
+// shapes are typed with confidence; everything else is `{}` (renders as `unknown`).
+function responseValueSchema(expr) {
+  const v = String(expr).trim();
+  if (v === 'true' || v === 'false') return { type: 'boolean' };
+  // `!!x` and `Boolean(x)` are boolean whatever x is — the two idioms routes use
+  // to coerce a truthy value before returning it (task 1002430). Without this a
+  // handler returning `{ ok: true }` in one branch and `{ ok: !!v }` in another
+  // documents `ok` as untyped, which is strictly worse than the truth.
+  if (/^!!/.test(v) || /^Boolean\s*\(/.test(v)) return { type: 'boolean' };
+  if (/^pageMeta\s*\(/.test(v)) return { $ref: '#/components/schemas/PageInfo' };
+  return {}; // a variable / call / ternary — the KEY is the win; leave the value open
+}
+
+// Parse one `res.json({ … })` object literal → { key: valueSchema } (depth-1), or
+// null if the shape can't be fully trusted (spread / non-identifier key / empty).
+function parseResponseObject(objLiteral) {
+  const inner = stripComments(String(objLiteral)).trim().replace(/^\{/, '').replace(/\}$/, '');
+  const props = {};
+  let count = 0;
+  for (const seg of splitTopLevel(inner)) {
+    const s = seg.trim();
+    if (s === '') continue;
+    if (s.startsWith('...')) return null;            // spread → unknown extra keys
+    const kv = splitKeyValue(s);
+    let key; let value;
+    if (kv) { key = kv.key; value = kv.value; }
+    else if (/^[A-Za-z_$][\w$]*$/.test(s)) { key = s; value = s; } // { foo } shorthand
+    else return null;                                 // method / unparseable segment
+    if (!/^[A-Za-z_$][\w$]*$/.test(key)) return null; // computed/quoted key → give up
+    props[key] = responseValueSchema(value);
+    count++;
+  }
+  return count ? props : null;
+}
+
+// Merge the shapes of every success `res.json({ … })` in one handler (branches):
+// union the keys; a key present in EVERY branch is required, others optional; a
+// value schema is kept only where all branches agree (else it opens to `unknown`).
+function mergeResponseShapes(shapes) {
+  const order = [];
+  const byKey = {};
+  for (const shape of shapes) {
+    for (const [key, schema] of Object.entries(shape)) {
+      if (!byKey[key]) { byKey[key] = []; order.push(key); }
+      byKey[key].push(schema);
+    }
+  }
+  const properties = {};
+  const required = [];
+  for (const key of order) {
+    const variants = byKey[key];
+    const first = JSON.stringify(variants[0]);
+    properties[key] = variants.every((s) => JSON.stringify(s) === first) ? variants[0] : {};
+    if (variants.length === shapes.length) required.push(key);
+  }
+  return { properties, required };
+}
+
+// The success-response shape for a route: scan its handler window for success
+// `res.json(…)` / `res.status(2xx).json(…)` calls. Returns { properties, required }
+// when EVERY success body is a provable object literal, else null (degrade).
+function extractResponse(lines, i) {
+  const window = stripComments(lines.slice(i, routeEndLine(lines, i)).join('\n'));
+  const re = /\bres\s*\.\s*(?:status\s*\(\s*(\d+)\s*\)\s*\.\s*)?json\s*\(/g;
+  const shapes = [];
+  let m;
+  let sawSuccessJson = false;
+  while ((m = re.exec(window))) {
+    const status = m[1] ? Number(m[1]) : 200;
+    if (status < 200 || status > 299) continue;       // error body — the envelope covers it
+    sawSuccessJson = true;
+    let k = m.index + m[0].length;                    // first char after '('
+    while (k < window.length && /\s/.test(window[k])) k++;
+    if (window[k] !== '{') return null;               // bare value → shape unknowable
+    const lit = captureBalanced(window, k);
+    const shape = lit && parseResponseObject(lit);
+    if (!shape) return null;                           // couldn't prove the shape
+    shapes.push(shape);
+  }
+  if (!sawSuccessJson || !shapes.length) return null;
+  return mergeResponseShapes(shapes);
+}
+
+// First path segment → resource tag (tasks, me, public, …). '' → 'root'.
+function tagFor(route) {
+  const seg = route.split('/').filter(Boolean)[0] || 'root';
+  return seg.replace(/[^A-Za-z0-9_-]/g, '');
+}
+
+// The full extracted model: [{ method, route, openapiPath, params, rank, tag,
+// description, body, file }], stable-sorted.
+// `routeFiles` is injectable so a test can drive the model over a fixture route file
+// (the default is the live core + module route set).
+function extractModel({ routeFiles = rrc.discoverRouteFiles() } = {}) {
+  const routes = [];
+  const globals = globalConstants();
+  for (const { abs, rel } of routeFiles) {
+    const text = fs.readFileSync(abs, 'utf8');
+    const lines = text.split('\n');
+    // Constants a validate() rule in THIS file may reference (LIMITS + file-local consts).
+    const constants = Object.assign({}, globals, scanFileConstants(text));
+    // rrc.scanDeclarations, not a second regex: the spec must enumerate EXACTLY the
+    // routes the ship-time gate enforces. Its own regex missed multi-line declarations,
+    // so 10 real endpoints (6 writes) were absent from the published contract entirely
+    // (BV1.R109b). An unresolvable path is skipped here and reported by checkRouteRanks.
+    for (const decl of rrc.scanDeclarations(text)) {
+      if (decl.route === null) continue;
+      const i = decl.line;
+      const method = decl.method;
+      const route = decl.route;
+      const { openapiPath, names } = pathParams(route);
+      // classifyGate, not classifyRank: a route migrated to requirePermission(...)
+      // (BV1.R104-R107) resolves through the governance catalog to its real rank
+      // floor, and names the authority atoms it gates on. Before BV1.R109 those
+      // routes documented as 'any-builder' — enforcement was correct, the LABEL lied.
+      const { rank, perms } = rrc.classifyGate(lines, i);
+      routes.push({
+        method,
+        route,
+        openapiPath,
+        params: names,
+        rank,
+        perms,
+        tag: tagFor(route),
+        description: commentBlockAbove(lines, i),
+        body: extractBody(lines, i, method, constants),
+        response: extractResponse(lines, i),
+        file: rel,
+      });
+    }
+  }
+  routes.sort((a, b) =>
+    a.openapiPath.localeCompare(b.openapiPath)
+    || METHOD_ORDER.indexOf(a.method.toLowerCase()) - METHOD_ORDER.indexOf(b.method.toLowerCase())
+    || a.file.localeCompare(b.file));
+  return routes;
+}
+
+// ---------------------------------------------------------------------------
+// OpenAPI 3.1 assembly
+// ---------------------------------------------------------------------------
+
+function operationId(method, openapiPath) {
+  const slug = openapiPath.replace(/[{}]/g, '').replace(/[^A-Za-z0-9]+/g, '_').replace(/^_|_$/g, '');
+  return `${method.toLowerCase()}_${slug || 'root'}`;
+}
+
+function pascalCase(s) {
+  return String(s).split(/[^A-Za-z0-9]+/).filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join('');
+}
+
+// A body field whose validate() rule declared NO type but whose name is a resource
+// id: task_id/builder_id/parent_task_id/… These are Postgres bigint PKs left untyped
+// on purpose (R11/#1998 — they arrive as a JSON number OR a stringified integer).
+// Give them the shared StringifiableId schema instead of degrading to `{}`.
+// version_id is excluded (it is a text slug and always declares type:'string', so it
+// never reaches the untyped branch — the guard is belt-and-braces).
+function isIdField(field) {
+  return field !== 'version_id' && (field === 'id' || /_id$/.test(field));
+}
+
+// ruleToSchema(field, rule) — one field's parsed rule → a JSON Schema fragment.
+function ruleToSchema(field, rule) {
+  if (!rule.type) {
+    if (isIdField(field)) return { $ref: '#/components/schemas/StringifiableId' };
+    return rule.enum ? { enum: rule.enum } : {}; // untyped, non-id → unconstrained
+  }
+  const s = {};
+  if (rule.type === 'integer' || rule.type === 'number') {
+    s.type = rule.type;
+    if (rule.min != null) s.minimum = rule.min;
+    if (rule.max != null) s.maximum = rule.max;
+  } else if (rule.type === 'string') {
+    s.type = 'string';
+    if (rule.minLength != null) s.minLength = rule.minLength;
+    if (rule.maxLength != null) s.maxLength = rule.maxLength;
+  } else if (rule.type === 'array') {
+    s.type = 'array';
+    if (rule.itemsType) s.items = { type: rule.itemsType };
+    if (rule.maxItems != null) s.maxItems = rule.maxItems;
+  } else {
+    s.type = rule.type; // boolean | object
+  }
+  if (rule.enum) s.enum = rule.enum;
+  return s;
+}
+
+// requestSchemaFor(r) — the JSON Schema for a write route's body, plus a component
+// name when it carries declared fields (so it lands in components.schemas and the
+// operation references it by $ref). A body with no declared fields (an undocumented
+// or schema-less body) stays an inline open object with no named component.
+function requestSchemaFor(r) {
+  const rules = r.body.rules || {};
+  const fields = r.body.fields || [];
+  if (!fields.length) return { schema: { type: 'object', additionalProperties: true } };
+  const properties = {};
+  const required = [];
+  for (const f of fields) {
+    const rule = rules[f] || {};
+    properties[f] = ruleToSchema(f, rule);
+    if (rule.required) required.push(f);
+  }
+  const schema = { type: 'object', properties };
+  if (required.length) schema.required = required;
+  // A validated strict route rejects unknown fields; a lenient/undeclared one allows them.
+  schema.additionalProperties = r.body.validated ? !r.body.strict : true;
+  return { schema, componentName: pascalCase(operationId(r.method, r.openapiPath)) + 'Request', required };
+}
+
+// The reusable component schemas every spec carries (task 2050): the ADR-0116 error
+// envelope + its inner object, and the pg-bigint id convention.
+function baseComponentSchemas() {
+  return {
+    ApiErrorObject: {
+      type: 'object',
+      required: ['code', 'message'],
+      properties: {
+        code: { type: 'string', description: 'Stable machine-readable slug the caller may switch on (e.g. `task_not_found`). Classified into a category (`x-error-categories`); the specific slug is preserved (ADR 0116).' },
+        message: { type: 'string', description: 'Human-readable, safe to surface. Never leaks internals unless a handler opts in.' },
+        details: { description: 'Optional structured payload — e.g. the validator\'s `[{ field, reason }]` list.' },
+      },
+      description: 'The inner error object carried by every non-2xx response.',
+    },
+    ErrorEnvelope: {
+      type: 'object',
+      required: ['error'],
+      properties: { error: { $ref: '#/components/schemas/ApiErrorObject' } },
+      description: 'The single error shape returned by EVERY non-2xx response (ADR 0116). A caller reads `error.code`.',
+    },
+    StringifiableId: {
+      type: ['integer', 'string'],
+      description: 'A resource id — an integer, or its stringified form (a Postgres bigint serializes as a JSON string, so ids may arrive either way). Accept both.',
+    },
+    PageInfo: {
+      type: 'object',
+      required: ['limit', 'offset'],
+      properties: {
+        limit: { type: 'integer', description: 'Page size actually applied (clamped to the endpoint cap, ADR 0119).' },
+        offset: { type: 'integer', description: 'Zero-based row offset of this page.' },
+        total: { type: 'integer', description: 'Total matching rows, when cheaply countable; derive "more pages" via `offset + items.length < total`.' },
+      },
+      description: 'The `page` block of a paginated list response (ADR 0119), built by `pageMeta()`.',
+    },
+  };
+}
+
+// The reusable error responses (ADR 0116) — the envelope, referenced by every
+// non-2xx. Defined ONCE in components.responses; each operation $refs the right one
+// (keeps the committed spec lean instead of inlining the body on 200+ routes).
+function baseComponentResponses() {
+  const body = { content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } } };
+  return {
+    BadRequest: { description: 'Malformed or invalid request (the ADR-0116 error envelope).', ...body },
+    ValidationFailed: { description: 'Request body failed schema validation; `error.details` lists the field errors.', ...body },
+    Unauthorized: { description: 'No or invalid session.', ...body },
+    Forbidden: { description: 'Authenticated but rank/ownership too low for this route.', ...body },
+    NotFound: { description: 'The referenced resource does not exist.', ...body },
+  };
+}
+
+function buildOperation(r, stats, schemas) {
+  const op = {
+    operationId: operationId(r.method, r.openapiPath),
+    tags: [r.tag],
+    summary: `${r.method} ${routeForDisplay(r.route)}`,
+    description: (r.description ? r.description + '\n\n' : '')
+      + `**Rank:** \`${r.rank}\` — ${RANK_BLURB[r.rank] || RANK_BLURB.unknown}`
+      + (r.perms && r.perms.length ? `\n\n**Permissions:** \`${r.perms.join('`, `')}\` (all required).` : ''),
+    'x-rank': r.rank,
+    'x-source': r.file,
+  };
+  // The authority ATOMS a migrated route gates on (ADR 0151). Absent on a route still
+  // gated by rank, so today's spec is byte-identical until BV1.R104-R107 land.
+  if (r.perms && r.perms.length) op['x-permissions'] = r.perms;
+  if (r.params.length) {
+    op.parameters = r.params.map((name) => ({
+      name, in: 'path', required: true, schema: { type: 'string' },
+      description: `Path parameter \`${name}\`.`,
+    }));
+  }
+  if (r.body) {
+    const { schema, componentName, required } = requestSchemaFor(r);
+    let bodySchema = schema;
+    if (componentName) {
+      schemas[componentName] = schema; // land it in components.schemas
+      bodySchema = { $ref: '#/components/schemas/' + componentName };
+    }
+    op.requestBody = {
+      // A body is REQUIRED when the schema declares at least one required field.
+      required: Boolean(required && required.length),
+      content: { 'application/json': { schema: bodySchema } },
+      'x-validated': r.body.validated,
+    };
+    if (!r.body.validated) {
+      op.requestBody['x-body-undocumented'] = true;
+      stats.undocumentedBodies++;
+    }
+  }
+  const responses = { 200: { description: 'Success.' } };
+  // task 2061: attach the statically-proven success shape (from res.json({…})) to
+  // 200 as a named component, so the generated client types the return concretely.
+  if (r.response && Object.keys(r.response.properties).length) {
+    const componentName = pascalCase(operationId(r.method, r.openapiPath)) + 'Response';
+    const schema = { type: 'object', properties: r.response.properties };
+    if (r.response.required.length) schema.required = r.response.required;
+    schemas[componentName] = schema;
+    responses[200] = { description: 'Success.', content: { 'application/json': { schema: { $ref: '#/components/schemas/' + componentName } } } };
+    stats.responseSchemas++;
+  }
+  responses[400] = { $ref: (r.body && r.body.validated) ? '#/components/responses/ValidationFailed' : '#/components/responses/BadRequest' };
+  if (r.rank !== 'public') {
+    responses[401] = { $ref: '#/components/responses/Unauthorized' };
+    responses[403] = { $ref: '#/components/responses/Forbidden' };
+  }
+  if (r.params.length) responses[404] = { $ref: '#/components/responses/NotFound' };
+  op.responses = responses;
+  op.security = r.rank === 'public' ? [] : [{ builderSession: [] }];
+  return op;
+}
+
+function buildOpenapi(model) {
+  const stats = { undocumentedBodies: 0, responseSchemas: 0 };
+  const schemas = baseComponentSchemas();
+  const paths = {};
+  for (const r of model) {
+    if (!paths[r.openapiPath]) paths[r.openapiPath] = {};
+    paths[r.openapiPath][r.method.toLowerCase()] = buildOperation(r, stats, schemas);
+  }
+  // Deterministic key order for components.schemas (base + per-operation request schemas).
+  const sortedSchemas = {};
+  for (const k of Object.keys(schemas).sort()) sortedSchemas[k] = schemas[k];
+  // Stable key order for paths (already sorted in model, but rebuild explicitly).
+  const sortedPaths = {};
+  for (const p of Object.keys(paths).sort()) sortedPaths[p] = paths[p];
+
+  const tags = [...new Set(model.map((r) => r.tag))].sort()
+    .map((name) => ({ name, description: `Endpoints under \`${API_PREFIX}/${name}\`.` }));
+
+  const spec = {
+    openapi: '3.1.0',
+    info: {
+      title: `${productName()} — Bongos API`,
+      version: specVersion(),
+      license: { name: 'AGPL-3.0-or-later', url: 'https://www.gnu.org/licenses/agpl-3.0.html' },
+      description: [
+        `The Bongos API — the build-methodology backend`,
+        `(builders, tasks, claims, credits, grading, memory).`,
+        ``,
+        `**API version:** \`${API_VERSION}\` — served at \`${VERSIONED_API_PREFIX}\`. The`,
+        `unversioned \`${API_PREFIX}\` and legacy \`/api/gds\` are permanent aliases`,
+        `pinned to this version; pin to \`${VERSIONED_API_PREFIX}\` for a stable`,
+        `contract (breaking changes ship a new \`/vN\`, ADR 0117). This is the`,
+        `CONTRACT version, distinct from the package build in \`info.version\`.`,
+        ``,
+        `**Base path:** \`${API_PREFIX}\` (every path below is relative to it).`,
+        ``,
+        `**Auth:** a builder session — the \`gds_session\` cookie (web) or`,
+        `\`Authorization: Bearer <token>\` (CLI). **Ranks** gate writes and are`,
+        `enforced server-side per request, never cached (ADR 0016):`,
+        `\`public\` < \`any-builder\` < \`metic+archon\` < \`archon\`.`,
+        `Each operation carries its required rank in \`x-rank\`.`,
+        ``,
+        `Generated from the live route files by \`scripts/bongos/gen-api-docs.js\` —`,
+        `do not hand-edit; it regenerates on every ship.`,
+      ].join('\n'),
+    },
+    'x-api-version': API_VERSION, // the explicit contract version (ADR 0117)
+    servers: [
+      { url: VERSIONED_API_PREFIX, description: 'Versioned API base (same-origin) — pin here for a stable contract.' },
+      { url: API_PREFIX, description: 'Unversioned alias (permanent) — resolves to the current version.' },
+    ],
+    tags,
+    paths: sortedPaths,
+    components: {
+      securitySchemes: {
+        builderSession: {
+          type: 'apiKey',
+          in: 'cookie',
+          name: 'gds_session',
+          description: 'Builder session. Web clients send the `gds_session` cookie; '
+            + 'CLI clients send `Authorization: Bearer <token>`. Rank is resolved from '
+            + 'the live builder record on every request (ADR 0016).',
+        },
+      },
+      schemas: sortedSchemas,
+      responses: baseComponentResponses(),
+    },
+    // The error-code taxonomy (ADR 0116): every non-2xx `error.code` classifies onto
+    // one of these categories, each with a default status + retriable flag. Sourced
+    // from the kernel registry (src/bongos/api-errors.js) so docs can't drift from it.
+    'x-error-categories': apiErrors.CATEGORIES,
+    'x-endpoint-count': model.length,
+    'x-schema-count': Object.keys(sortedSchemas).length,
+    'x-undocumented-bodies': stats.undocumentedBodies,
+    'x-response-schemas': stats.responseSchemas,
+    'x-generated-by': 'scripts/bongos/gen-api-docs.js',
+  };
+  return spec;
+}
+
+// ---------------------------------------------------------------------------
+// Markdown reference
+// ---------------------------------------------------------------------------
+
+const MD_BANNER = '<!-- GENERATED by scripts/bongos/gen-api-docs.js — do not hand-edit. Run `node scripts/bongos/gen-api-docs.js`. -->';
+
+function shortDesc(d) {
+  if (!d) return '';
+  const first = d.split(/(?<=\.)\s/)[0];
+  return (first.length > 140 ? first.slice(0, 137) + '…' : first).replace(/\|/g, '\\|');
+}
+
+function buildReferenceMd(model, spec) {
+  const L = [];
+  L.push(MD_BANNER);
+  L.push('');
+  L.push('# Bongos API reference');
+  L.push('');
+  L.push(`> **Generated from the live route files** — the route file is authoritative. ${model.length} endpoints across ${new Set(model.map((r) => r.file)).size} route files.`);
+  L.push('> Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).');
+  L.push('');
+  L.push(`Base path: \`${API_PREFIX}\`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust-boundary-server-enforced-permissions.md)): \`public\` < \`any-builder\` < \`metic+archon\` < \`archon\`.`);
+  L.push('');
+  const byTag = new Map();
+  for (const r of model) {
+    if (!byTag.has(r.tag)) byTag.set(r.tag, []);
+    byTag.get(r.tag).push(r);
+  }
+  for (const tag of [...byTag.keys()].sort()) {
+    const rows = byTag.get(tag);
+    L.push(`## \`${tag}\` (${rows.length})`);
+    L.push('');
+    L.push('| Method | Path | Rank | Body | Description |');
+    L.push('|---|---|---|---|---|');
+    for (const r of rows) {
+      const body = r.body
+        ? (r.body.validated
+          ? (r.body.fields.length ? '`' + r.body.fields.join('`, `') + '`' : 'validated')
+          : '_undocumented_')
+        : '—';
+      L.push(`| ${r.method} | \`${API_PREFIX}${routeForDisplay(r.route)}\` | \`${r.rank}\` | ${body} | ${shortDesc(r.description)} |`);
+    }
+    L.push('');
+  }
+  if (spec['x-undocumented-bodies'] > 0) {
+    L.push('---');
+    L.push('');
+    L.push(`> ${spec['x-undocumented-bodies']} write endpoint(s) take a JSON body with no declared validator schema — their fields are not yet machine-documented. Adding a \`validateOrRespond\` schema (\`src/bongos/routes/_helpers.js\`) surfaces them here automatically.`);
+    L.push('');
+  }
+  return L.join('\n') + '\n';
+}
+
+function buildPermissionsStub() {
+  return [
+    MD_BANNER,
+    '',
+    '# Routes & permissions — moved',
+    '',
+    '> This hand-maintained mirror has been **retired**. Every endpoint and its rank gate',
+    '> is now generated from the live route files.',
+    '',
+    // task 1004866: the two generated files are gitignored in the core, so they are named
+    // as paths, not linked — a link to an absent file is a stale link in a fresh clone.
+    '- **Full endpoint + permission reference:** `docs/api-reference.md` (generated, not committed)',
+    '- **Machine-readable spec (OpenAPI 3.1):** `docs/api/openapi.json` (generated, not committed)',
+    '- **Rendered docs site:** **`/docs`** (e.g. `cloudbongos.com/docs`)',
+    '- **Rank-ladder model:** [`docs/canonical-permissions.md`](canonical-permissions.md) · [ADR 0016](adr/0016-trust-boundary-server-enforced-permissions.md)',
+    '',
+    'Build both, and the typed client, with `node scripts/bongos/api-artifacts.js`.',
+    '',
+  ].join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Built-in structural OpenAPI 3.1 validator (no external dep)
+// ---------------------------------------------------------------------------
+
+function validateOpenapi(spec) {
+  const problems = [];
+  if (spec.openapi !== '3.1.0') problems.push(`openapi must be '3.1.0' (got ${JSON.stringify(spec.openapi)})`);
+  if (!spec.info || typeof spec.info.title !== 'string' || !spec.info.title) problems.push('info.title missing');
+  if (!spec.info || typeof spec.info.version !== 'string' || !spec.info.version) problems.push('info.version missing');
+  if (!spec.paths || typeof spec.paths !== 'object') problems.push('paths missing');
+  const schemes = (spec.components && spec.components.securitySchemes) || {};
+  for (const [p, item] of Object.entries(spec.paths || {})) {
+    if (!p.startsWith('/')) problems.push(`path ${p} must start with '/'`);
+    for (const [method, op] of Object.entries(item)) {
+      if (!METHOD_ORDER.includes(method)) problems.push(`${p}: unexpected method ${method}`);
+      if (!op.responses || Object.keys(op.responses).length === 0) problems.push(`${method.toUpperCase()} ${p}: no responses`);
+      for (const param of op.parameters || []) {
+        if (!param.name || !param.in) problems.push(`${method.toUpperCase()} ${p}: malformed parameter`);
+      }
+      for (const req of op.security || []) {
+        for (const name of Object.keys(req)) {
+          if (!schemes[name]) problems.push(`${method.toUpperCase()} ${p}: security scheme '${name}' not defined in components`);
+        }
+      }
+    }
+  }
+  // Every local $ref under paths/components must resolve to a defined component
+  // (schema or response) — a dangling $ref is a broken contract (task 2050).
+  const definedSchemas = new Set(Object.keys((spec.components && spec.components.schemas) || {}));
+  const definedResponses = new Set(Object.keys((spec.components && spec.components.responses) || {}));
+  const seen = [];
+  (function collectRefs(node) {
+    if (!node || typeof node !== 'object') return;
+    if (typeof node.$ref === 'string') seen.push(node.$ref);
+    for (const v of Object.values(node)) collectRefs(v);
+  })({ paths: spec.paths, components: spec.components });
+  for (const ref of seen) {
+    const sm = /^#\/components\/schemas\/(.+)$/.exec(ref);
+    const rm = /^#\/components\/responses\/(.+)$/.exec(ref);
+    if (sm) { if (!definedSchemas.has(sm[1])) problems.push(`$ref '${ref}' does not resolve to a defined component schema`); }
+    else if (rm) { if (!definedResponses.has(rm[1])) problems.push(`$ref '${ref}' does not resolve to a defined component response`); }
+    else problems.push(`unsupported $ref (only #/components/{schemas,responses}/* is emitted): ${ref}`);
+  }
+  return problems;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function build() {
+  const model = extractModel();
+  const spec = buildOpenapi(model);
+  return {
+    model,
+    spec,
+    files: [
+      // committed:false (task 1004866) — gitignored, rebuilt by every consumer from the
+      // routes (scripts/bongos/api-artifacts.js), so --check has no committed copy to compare.
+      { full: OPENAPI_PATH, rel: 'docs/api/openapi.json', content: JSON.stringify(spec, null, 2) + '\n', committed: false },
+      { full: REFERENCE_PATH, rel: 'docs/api-reference.md', content: buildReferenceMd(model, spec), committed: false },
+      { full: PERMISSIONS_PATH, rel: 'docs/routes-permissions.md', content: buildPermissionsStub(), committed: true },
+    ],
+  };
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const checkOnly = args.includes('--check');
+  const jsonOnly = args.includes('--json');
+
+  const { model, spec, files } = build();
+
+  if (jsonOnly) {
+    console.log(JSON.stringify({ endpoints: model.length, undocumentedBodies: spec['x-undocumented-bodies'], model }, null, 2));
+    return;
+  }
+
+  // Always structurally validate — a malformed spec is a hard failure in both modes.
+  const problems = validateOpenapi(spec);
+  if (problems.length) {
+    console.error('gen-api-docs: generated spec is NOT valid OpenAPI 3.1:');
+    for (const p of problems) console.error('  - ' + p);
+    process.exit(1);
+  }
+
+  if (checkOnly) {
+    // Generation succeeded and the spec validated above. The spec + reference are not
+    // committed (task 1004866), so only the committed pointer stub is compared on disk.
+    const stale = files.filter((f) => f.committed).filter((f) => {
+      let cur = null;
+      try { cur = fs.readFileSync(f.full, 'utf8'); } catch { return true; /* missing → stale */ }
+      return !sameContent(cur, f.content);
+    });
+    if (stale.length) {
+      console.error(`gen-api-docs --check: STALE — would update ${stale.map((f) => f.rel).join(', ')}. Run \`node scripts/bongos/gen-api-docs.js\` and commit.`);
+      process.exit(2);
+    }
+    console.log(`gen-api-docs --check: generation OK (${model.length} endpoints, ${spec['x-undocumented-bodies']} undocumented bodies).`);
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(OPENAPI_PATH), { recursive: true });
+  for (const f of files) fs.writeFileSync(f.full, f.content);
+  console.log(`gen-api-docs: wrote ${files.length} files — ${model.length} endpoints, ${spec['x-undocumented-bodies']} undocumented bodies.`);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  extractModel,
+  buildOpenapi,
+  buildReferenceMd,
+  buildPermissionsStub,
+  validateOpenapi,
+  commentBlockAbove,
+  pathParams,
+  routeForDisplay,
+  captureBalanced,
+  topLevelKeys,
+  topLevelEntries,
+  splitTopLevel,
+  splitKeyValue,
+  resolveScalar,
+  resolveArray,
+  resolveConst,
+  parseRule,
+  scanFileConstants,
+  ruleToSchema,
+  requestSchemaFor,
+  isIdField,
+  pascalCase,
+  extractBody,
+  routeEndLine,
+  responseValueSchema,
+  parseResponseObject,
+  mergeResponseShapes,
+  extractResponse,
+  build,
+  API_PREFIX,
+};