@geraldmaron/construct 1.1.0 → 1.2.0

package/lib/cli-commands.mjs

@@ -13,6 +13,7 @@
  */
 
 import { resolveColors } from './term-format.mjs';
+import { surfaceForCommand } from './registry/surface-map.mjs';
 
 export const CLI_COMMANDS = [
   // ── Core (shown by default) ───────────────────────────────────────────
@@ -23,6 +24,10 @@ export const CLI_COMMANDS = [
     core: true,
     description: 'Start services for development',
     usage: 'construct dev [--select] [--only=postgres,dashboard,...]',
+    examples: [
+      { cmd: 'construct dev', desc: 'Start the default service set' },
+      { cmd: 'construct dev --only=dashboard', desc: 'Start just the dashboard' },
+    ],
     options: [
       { flag: '--select', desc: 'Pick which services to start from an interactive checklist' },
       { flag: '--only=<a,b,c>', desc: 'Start only the named services (postgres, dashboard, telemetry, memory, opencode)' },
@@ -35,6 +40,10 @@ export const CLI_COMMANDS = [
     core: true,
     description: 'Start the local dashboard/orchestration daemon (or --token to mint a dashboard token)',
     usage: 'construct dashboard [--token]',
+    examples: [
+      { cmd: 'construct dashboard', desc: 'Launch the local dashboard daemon' },
+      { cmd: 'construct dashboard --token', desc: 'Mint a dashboard access token' },
+    ],
   },
   {
     name: 'stop',
@@ -43,6 +52,9 @@ export const CLI_COMMANDS = [
     core: true,
     description: 'Stop all running services',
     usage: 'construct stop',
+    examples: [
+      { cmd: 'construct stop', desc: 'Stop every running service' },
+    ],
   },
   {
     name: 'status',
@@ -51,6 +63,11 @@ export const CLI_COMMANDS = [
     core: true,
     description: 'Show system health and credentials',
     usage: 'construct status',
+    strictFlags: true,
+    examples: [
+      { cmd: 'construct status', desc: 'Human-readable health summary' },
+      { cmd: 'construct status --json', desc: 'Full payload for scripting' },
+    ],
     options: [
       { flag: '--json', desc: 'Output full status payload as JSON' },
     ],
@@ -61,10 +78,15 @@ export const CLI_COMMANDS = [
     category: 'Core',
     core: true,
     description: 'Machine setup (scoped per ADR-0029): --scope=project|user|both, default project',
-    usage: 'construct install [--scope=project|user|both] [--yes] [--no-docker] [--no-launch-agent] [--reconfigure] [--with-docling]',
+    usage: 'construct install [--scope=project|user|both] [--yes] [--dry-run] [--no-docker] [--no-launch-agent] [--reconfigure] [--with-docling]',
+    examples: [
+      { cmd: 'construct install --dry-run', desc: 'Preview the plan before writing anything' },
+      { cmd: 'construct install --scope=user --yes', desc: 'Non-interactive user-scope install' },
+    ],
     options: [
       { flag: '--scope=<s>',      desc: 'project (default, no-op + guidance) | user (writes ~/.construct/, MCP, ~/.claude/* via consent) | both' },
       { flag: '--yes',            desc: 'Apply defaults without prompts (only meaningful with --scope=user|both)' },
+      { flag: '--dry-run',        desc: 'Preview the install plan (scopes, files, services) without writing anything' },
       { flag: '--no-docker',      desc: 'Skip Docker-based service setup (local Postgres)' },
       { flag: '--no-launch-agent', desc: 'Skip background macOS LaunchAgent registration' },
       { flag: '--reconfigure',    desc: 'Re-prompt for service consent, ignoring cached answers' },
@@ -78,6 +100,10 @@ export const CLI_COMMANDS = [
     core: true,
     description: 'Project setup (once per repo): scaffold .cx/, AGENTS.md, plan.md, adapters',
     usage: 'construct init [path] [options]',
+    examples: [
+      { cmd: 'construct init', desc: 'Scaffold the current repo interactively' },
+      { cmd: 'construct init --yes --with-adrs', desc: 'Non-interactive init with the ADR doc lane' },
+    ],
     options: [
       { flag: '--yes', desc: 'Accept all defaults (non-interactive)' },
       { flag: '--no-start', desc: 'Do not start services after init' },
@@ -103,6 +129,10 @@ export const CLI_COMMANDS = [
     core: true,
     description: 'Sync agent adapters to AI tools',
     usage: 'construct sync [--project] [--dry-run] [--no-docs] [--compress-personas]',
+    examples: [
+      { cmd: 'construct sync', desc: 'Sync adapters to detected AI tools' },
+      { cmd: 'construct sync --dry-run', desc: 'Preview adapter changes without writing' },
+    ],
     options: [
       { flag: '--project', desc: 'Write project-local Claude adapters into the current repo only' },
       { flag: '--dry-run', desc: 'Preview adapter changes without writing files' },
@@ -117,6 +147,10 @@ export const CLI_COMMANDS = [
     core: true,
     description: 'View and process the active profile\'s intake queue (queue label varies by profile)',
     usage: 'construct intake list|show|done|skip|reopen|integrate|classify',
+    examples: [
+      { cmd: 'construct intake list', desc: 'See pending packets' },
+      { cmd: 'construct intake done <id> --output=path', desc: 'Mark processed and stamp the artifact' },
+    ],
     subcommands: [
       { name: 'list', desc: 'List pending packets' },
       { name: 'show <id>', desc: 'Show one packet (triage, related docs, excerpt, tag suggestions)' },
@@ -134,6 +168,10 @@ export const CLI_COMMANDS = [
     core: true,
     description: 'View and manage artifact recommendations',
     usage: 'construct recommendations list|show|dismiss|stats',
+    examples: [
+      { cmd: 'construct recommendations list', desc: 'See open recommendations' },
+      { cmd: 'construct recommendations dismiss <id>', desc: 'Dismiss one by id' },
+    ],
   },
   {
     name: 'integrations',
@@ -180,6 +218,10 @@ export const CLI_COMMANDS = [
     core: true,
     description: 'Isolated tmpdir-based environment for QA / specialist dry-runs',
     usage: 'construct sandbox create|list|delete|prune [--profile=<id>]',
+    examples: [
+      { cmd: 'construct sandbox create --profile=<id>', desc: 'Spin up an isolated sandbox' },
+      { cmd: 'construct sandbox prune --days=7', desc: 'Remove sandboxes older than a week' },
+    ],
     subcommands: [
       { name: 'create [--profile=<id>]', desc: 'Create a new sandbox under ~/.cx/sandboxes/' },
       { name: 'list', desc: 'List existing sandboxes, newest first' },
@@ -194,6 +236,10 @@ export const CLI_COMMANDS = [
     core: true,
     description: 'Manage the active org profile and its lifecycle (draft, promote, archive, health)',
     usage: 'construct profile show|list|set|create|drafts|archive|health',
+    examples: [
+      { cmd: 'construct profile list', desc: 'List curated profiles' },
+      { cmd: 'construct profile set <id>', desc: 'Switch the active profile' },
+    ],
     subcommands: [
       { name: 'show', desc: 'Show the active profile' },
       { name: 'list', desc: 'List curated profiles' },
@@ -225,6 +271,10 @@ export const CLI_COMMANDS = [
     core: true,
     description: 'Documentation commands',
     usage: 'construct docs check|verify|update',
+    examples: [
+      { cmd: 'construct docs verify', desc: 'Validate the docs tree' },
+      { cmd: 'construct docs update', desc: 'Regenerate AUTO-managed regions' },
+    ],
     subcommands: [
       { name: 'check', desc: 'Check for missing how-to guides' },
       { name: 'verify', desc: 'Validate documentation quality' },
@@ -238,6 +288,10 @@ export const CLI_COMMANDS = [
     core: true,
     description: 'Check installation health',
     usage: 'construct doctor [<status|logs|tick|report|consistency|watch|stop|credentials>] [--fix-legacy-agents]',
+    examples: [
+      { cmd: 'construct doctor', desc: 'Run all health checks once' },
+      { cmd: 'construct doctor report', desc: 'Print the latest health report' },
+    ],
     subcommands: [
       { name: 'status', desc: 'Doctor daemon status' },
       { name: 'logs', desc: 'Tail doctor daemon logs' },
@@ -268,15 +322,61 @@ export const CLI_COMMANDS = [
     category: 'Work',
     core: false,
     description: 'Convert documents to indexed markdown',
-    usage: 'construct ingest <file> [--strategy=adapter|provider] [--orchestration=prompt-only|orchestrated] [--strict] [--legacy-extractor]',
+    usage: 'construct ingest <file> [--strategy=adapter|provider] [--orchestration=prompt-only|orchestrated] [--strict] [--fidelity=fast|high]',
   },
   {
     name: 'export',
     emoji: '📤',
     category: 'Work',
     core: false,
-    description: 'Export markdown to PDF/DOCX/HTML via Pandoc + Typst (optional system binaries; ADR-0024)',
-    usage: 'construct export <markdown-file> --to=<pdf|docx|html> [--output=<path>]',
+    description: 'Export markdown to PDF, DOCX, HTML, and other Pandoc formats via Pandoc + Typst (optional system binaries; ADR-0024)',
+    usage: 'construct export <markdown-file> --to=<pdf|docx|deck|pptx|html|rtf|odt|epub|tex|txt|md|mdx> [--output=<path>] [--figures] [--detect]',
+    strictFlags: true,
+    options: [
+      { flag: '--to=<format>', desc: 'pdf, docx, deck, pptx, html, rtf, odt, epub, tex, txt, md, mdx' },
+      { flag: '--output=<path>', desc: 'Output path' },
+      { flag: '--figures', desc: 'Render d2/mermaid via pandoc-ext/diagram filter' },
+      { flag: '--detect', desc: 'Report binary availability (JSON)' },
+    ],
+  },
+  {
+    name: 'publish',
+    emoji: '📰',
+    category: 'Work',
+    core: false,
+    description: 'Publish typed artifacts: release gate + export PDF with figures + optional demos',
+    usage: 'construct publish <markdown> [--to=pdf] [--type=DOC] [--demo=NAME] [--strict]',
+    strictFlags: true,
+    options: [
+      { flag: '--to=<format>', desc: 'pdf (default), docx, deck, pptx, html, rtf, odt, epub, tex, txt, md, mdx' },
+      { flag: '--output=<path>', desc: 'Output path (default: .cx/publish/<name>.<format>)' },
+      { flag: '--type=<doc-type>', desc: 'Manifest doc type for release gate (inferred when omitted)' },
+      { flag: '--demo=<name>', desc: 'Terminal VHS tape to record (repeatable)' },
+      { flag: '--dashboard-demo=<name>', desc: 'Playwright demo spec basename (repeatable)' },
+      { flag: '--figures', desc: 'Render d2/mermaid via diagram filter (default on)' },
+      { flag: '--no-figures', desc: 'Skip diagram filter' },
+      { flag: '--no-gate', desc: 'Skip artifact release gate (escape hatch only)' },
+      { flag: '--source-only', desc: 'Write sources only' },
+      { flag: '--strict', desc: 'Exit 2 when toolchain or release gate fails (default)' },
+      { flag: '--no-strict', desc: 'Do not exit 2 on toolchain/gate failure' },
+      { flag: '--detect', desc: 'Print tooling JSON and exit' },
+    ],
+  },
+  {
+    name: 'tools',
+    emoji: '🧰',
+    category: 'Work',
+    core: false,
+    description: 'Detect optional publish pipeline binaries (Pandoc, D2, VHS, Playwright)',
+    usage: 'construct tools detect [--json] [--figures] [--demo=NAME]',
+    strictFlags: true,
+    options: [
+      { flag: '--json', desc: 'JSON output' },
+      { flag: '--figures', desc: 'Include figure tooling (default on)' },
+      { flag: '--no-figures', desc: 'Skip figure binaries' },
+      { flag: '--demo=<name>', desc: 'Include terminal demo recorder check' },
+      { flag: '--dashboard-demo=<name>', desc: 'Include dashboard Playwright check' },
+    ],
   },
   {
     name: 'infer',
@@ -380,6 +480,14 @@ export const CLI_COMMANDS = [
     description: 'Run Construct as an Agent Client Protocol (ACP) server over stdio for Zed/JetBrains/VS Code ACP clients',
     usage: 'construct acp',
   },
+  {
+    name: 'chat',
+    emoji: '💬',
+    category: 'Models & Integrations',
+    core: false,
+    description: "Interactive terminal chat on Construct's owned agent loop, with a multi-pane transparency surface (live token/cost/context usage, reasoning, tool timeline, and the planned specialist route); switch models, change settings, and see a token/cost breakdown in-session. Use --accessible or --plain for the linear, screen-reader-friendly renderer",
+    usage: 'construct chat [--model <id>] [--free] [--web] [--list] [--resume[=file]] [--ascii] [--plain] [--accessible] [--no-thinking] [--no-path] [--no-specialists] [--no-tools] [--no-observability] [--quiet]',
+  },
   {
     name: 'mcp',
     emoji: '🔌',
@@ -481,6 +589,15 @@ export const CLI_COMMANDS = [
     description: 'Show evaluator catalog for prompt and agent experiments',
     usage: 'construct evals <list|run>',
   },
+  {
+    name: 'improvement',
+    emoji: '🔁',
+    category: 'Observability',
+    core: false,
+    surface: 'dashboard',
+    description: 'Governed improvement loop — review, approve, and record apply/rollback for proposals',
+    usage: 'construct improvement submit|review|pending|show|approve|apply|rollback|list',
+  },
   {
     name: 'cleanup',
     emoji: '🧹',
@@ -488,10 +605,11 @@ export const CLI_COMMANDS = [
     core: false,
     description: 'Release dev-agent memory pressure by cleaning stale helper and bridge processes',
     usage: 'construct cleanup [--dry-run] [--quiet] [--pressure-release] [--pressure-only] [--disk-only]',
+    strictFlags: true,
     options: [
       { flag: '--dry-run',          desc: 'Show what would be cleaned without changing anything' },
       { flag: '--quiet',            desc: 'Minimal output' },
-      { flag: '--pressure-release', desc: 'Also kill stale dev-agent processes' },
+      { flag: '--pressure-release', desc: 'Also kill stale dev-agent and leaked VHS demo-recorder processes' },
       { flag: '--pressure-only',    desc: 'Pressure release only — skip disk cleanup' },
       { flag: '--disk-only',        desc: 'Disk cleanup only — skip pressure release' },
     ],
@@ -510,7 +628,41 @@ export const CLI_COMMANDS = [
     category: 'Diagnostics',
     core: false,
     description: 'Audit Construct internals and review the mutation trail',
-    usage: 'construct audit <events|trail>',
+    usage: 'construct audit <skills|specialists|tests|trail>',
+    subcommands: [
+      { name: 'skills', desc: 'Audit skill corpus coverage and metadata (`--inventory` checks certification skill inventory freshness)' },
+      { name: 'specialists', desc: 'Audit specialist/skill matrix and cross-checks' },
+      { name: 'tests', desc: 'Validate behavior-to-test capability traceability (`--corpus` checks test-file inventory)' },
+      { name: 'trail', desc: 'Review mutation audit trail' },
+    ],
+  },
+  {
+    name: 'certify',
+    emoji: '✅',
+    category: 'Diagnostics',
+    core: false,
+    description: 'Inspect and run scenario-based certification under .cx/certification/',
+    usage: 'construct certify list|show|scenarios|models|demos|status|gate|run <scenario-id>',
+    subcommands: [
+      { name: 'list', desc: 'List recorded certification run ids' },
+      { name: 'show', desc: 'Show one certification run record as JSON' },
+      { name: 'scenarios', desc: 'List available certification scenarios with model tier' },
+      { name: 'models', desc: 'List routable certification models (free by default)' },
+      { name: 'status', desc: 'Roll up certification posture across capabilities and surfaces' },
+      { name: 'gate', desc: 'Release candidate gate — stale or failing release-critical certification evidence blocks' },
+      { name: 'run', desc: 'Execute a scenario (live requires CONSTRUCT_CERTIFY_LIVE=1; paid requires CONSTRUCT_CERTIFY_ALLOW_PAID=1)' },
+    ],
+  },
+  {
+    name: 'artifact',
+    emoji: '📋',
+    category: 'Work',
+    core: false,
+    description: 'Validate typed document artifacts against the release gate',
+    usage: 'construct artifact validate <path> --type=<doc-type> [--json]',
+    subcommands: [
+      { name: 'validate', desc: 'Run manifest structure, citation, and reviewer checks' },
+    ],
   },
   {
     name: 'doc',
@@ -560,6 +712,42 @@ export const CLI_COMMANDS = [
     description: 'Generate wireframes from description',
     usage: 'construct wireframe <description>',
   },
+  {
+    name: 'diagram',
+    emoji: '📊',
+    category: 'Work',
+    core: false,
+    description: 'Render code-driven diagrams via D2/Graphviz (optional system binaries; ADR-0001)',
+    usage: 'construct diagram <description> [--type=architecture|flow|sequence|state|er|class] [--format=svg|png] [--theme=<name>] [--out=<path>] [--source-only]',
+    strictFlags: true,
+    options: [
+      { flag: '--type=<t>',     desc: 'architecture (default) | flow | sequence | state | er | class' },
+      { flag: '--format=<f>',   desc: 'svg (default) | png' },
+      { flag: '--theme=<name>', desc: 'D2 theme name (e.g. neutral, sketch, cool-classics)' },
+      { flag: '--out=<path>',   desc: 'Output path (default: .cx/diagrams/<slug>-<ts>.<ext>)' },
+      { flag: '--source-only',  desc: 'Always write the source file; skip rendering' },
+    ],
+  },
+  {
+    name: 'demo',
+    emoji: '🎬',
+    category: 'Work',
+    core: false,
+    description: 'Run guided demos via construct chat (default) or record VHS/asciinema tapes',
+    usage: 'construct demo <list|init|record|name> [--surface=chat|web|tape|dashboard] [--format=gif|mp4|webm] [--out=<path>] [--source-only]',
+    strictFlags: true,
+    options: [
+      { flag: '--surface=<s>', desc: 'chat (default) | web | tape | dashboard' },
+      { flag: '--model=<id>', desc: 'Pin model for chat demo' },
+      { flag: '--web', desc: 'Open web chat (/chat/) instead of terminal Ink' },
+      { flag: '--plain', desc: 'Linear chat renderer (accessibility / non-TTY)' },
+      { flag: '--free', desc: 'OpenRouter free-router mode for chat demo' },
+      { flag: '--format=<f>',  desc: 'gif (default) | mp4 | webm (tape surface only)' },
+      { flag: '--out=<path>',  desc: 'Output path (tape recording)' },
+      { flag: '--from=<t>',    desc: 'Template for init: quickstart | diagram' },
+      { flag: '--source-only', desc: 'Tape: write .tape only; skip recording' },
+    ],
+  },
   {
     name: 'ollama',
     emoji: '🦙',
@@ -792,8 +980,8 @@ export const CLI_COMMANDS = [
     emoji: '🔑',
     category: 'Integrations',
     core: false,
-    description: 'Manage provider credentials (set, rotate, revoke, list)',
-    usage: 'construct creds <list|set|rotate|revoke|test>',
+    description: 'Manage provider credentials (login, set, rotate, revoke, list, test)',
+    usage: 'construct creds <list|login|set|rotate|revoke|test>',
   },
   {
     name: 'providers',
@@ -907,8 +1095,8 @@ export const CLI_COMMANDS = [
     emoji: '📄',
     category: 'Diagnostics',
     core: false,
-    description: 'Manage the docs static site build',
-    usage: 'construct docs:site <build|serve>',
+    description: 'Regenerate generated reference pages under docs/reference/',
+    usage: 'construct docs:site [--check]',
   },
   {
     name: 'beads:stats',
@@ -939,7 +1127,13 @@ export const CLI_COMMANDS = [
   { name: 'lint:templates',    category: 'Internal', core: false, internal: true, description: 'Internal lint: shipped templates', usage: 'construct lint:templates' },
   { name: 'lint:prompts',      category: 'Internal', core: false, internal: true, description: 'Internal lint: specialist prompt frontmatter + sections', usage: 'construct lint:prompts' },
   { name: 'specialist',        category: 'Internal', core: false, internal: true, description: 'Maintainer tool: scaffold, edit, and lint specialist prompts', usage: 'construct specialist <create|edit|lint>' },
-  { name: 'registry:status',   category: 'Internal', core: false, internal: true, description: 'Dev: capability-matrix registry inspector', usage: 'construct registry:status' },
+  { name: 'registry:status',   category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Dev: capability registry inspector', usage: 'construct registry:status [--json]' },
+  { name: 'registry:validate', category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Validate registry/capabilities.json against repo reality', usage: 'construct registry:validate [--json]' },
+  { name: 'registry:generate-docs', category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Generate docs/reference/capabilities.md from registry', usage: 'construct registry:generate-docs' },
+  { name: 'oracle', category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Oracle meta-controller — fleet health review and bounded-auto maintenance', usage: 'construct oracle start|status|review|pending|approve|gaps|reconcile' },
+  { name: 'matrix', category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Living dependency matrix — build/inspect the typed file↔capability↔workflow↔test graph', usage: 'construct matrix build|stat|query <node-id> [--json]' },
+  { name: 'impact', category: 'Diagnostics', core: false, internal: false, surface: 'thin-cli', description: 'Change-impact analysis — map changed files to affected tests, capabilities, and workflows', usage: 'construct impact [files…] [--stdin] [--run] [--json]' },
+  { name: 'rules', category: 'Diagnostics', core: false, internal: false, surface: 'thin-cli', description: 'Rule and hook reference telemetry rollup', usage: 'construct rules usage [--since=30d]' },
   { name: 'evaluator:rubrics', category: 'Internal', core: false, internal: true, description: 'Internal: list registered evaluator rubrics', usage: 'construct evaluator:rubrics' },
   { name: 'activation:status', category: 'Internal', core: false, internal: true, description: 'Internal: agent activation telemetry', usage: 'construct activation:status' },
   { name: 'prune',             category: 'Internal', core: false, internal: true, description: 'Internal: prune ephemeral storage entries', usage: 'construct prune' },
@@ -947,6 +1141,10 @@ export const CLI_COMMANDS = [
   { name: 'resources',         category: 'Internal', core: false, internal: true, description: 'Internal: resource probe', usage: 'construct resources' },
 ];
 
+for (const cmd of CLI_COMMANDS) {
+  if (!cmd.surface) cmd.surface = surfaceForCommand(cmd.name);
+}
+
 /** Flat list of all top-level command names (for completions). */
 export const COMMAND_NAMES = CLI_COMMANDS.filter((c) => !c.internal).map((c) => c.name);
 
@@ -1035,5 +1233,28 @@ export function formatCommandHelp(name, { colors = false } = {}) {
     }
     lines.push('');
   }
+
+  if (spec.examples && spec.examples.length > 0) {
+    lines.push(`${c.bold}Examples${c.reset}`);
+    for (const ex of spec.examples) {
+      lines.push(`  ${ex.cmd}`);
+      if (ex.desc) lines.push(`    ${c.dim}${ex.desc}${c.reset}`);
+    }
+    lines.push('');
+  }
+
+  // Every help block closes with the obvious next action: an explicit `next`,
+  // else "run a subcommand" for grouped commands, plus a See also pointer to the
+  // full reference — so no surface is a dead end.
+
+  const firstSub = spec.subcommands?.[0]?.name.split(/\s+/)[0];
+  const next = spec.next
+    || (firstSub ? `Run \`construct ${spec.name} ${firstSub}\` to start; add --help to any subcommand for details.` : null);
+  if (next) {
+    lines.push(`${c.dim}Next:${c.reset} ${next}`);
+    lines.push('');
+  }
+  lines.push(`${c.dim}See also:${c.reset} run \`construct --help\` for all commands; full reference in docs/reference/cli/.`);
+  lines.push('');
   return lines.join('\n');
 }

package/lib/comment-lint.mjs

@@ -94,7 +94,9 @@ function requiresHeader(rel) {
     return { required: false, type: null };
   }
   // Exclude test fixture data files — these are project artifacts, not source files.
-  if (rel.startsWith('tests/fixtures/projects/')) {
+  if (rel.startsWith('tests/fixtures/projects/')
+    || rel.startsWith('tests/fixtures/artifacts/')
+    || rel.startsWith('tests/fixtures/document-io/')) {
     return { required: false, type: null };
   }
   // Markdown files always get markdown-style headers, even if the directory
@@ -158,7 +160,7 @@ const BANNED = [
   { pattern: /<!--.*\b(?:added for|added recently|just added|new:)\b.*-->/i, label: 'point-in-time in markdown comment' },
   { pattern: /<!--.*\b(?:used by|called from|only consumer)\b.*-->/i, label: 'caller reference in markdown comment' },
   // TODO without owner
-  { pattern: new RegExp(`${CMT}\\s*TODO(?:\\((\\w+)\\))?:?(?!\\s*\\(\\w+\\):)`, 'i'), label: 'TODO without owner — use: TODO(owner): what and why' }, // construct-lint-ignore
+  { pattern: new RegExp(`${CMT}\\s*TODO(?!\\s*\\(\\w+\\)\\s*:)`, 'i'), label: 'TODO without owner — use: TODO(owner): what and why' }, // construct-lint-ignore
 ];
 
 // Files whose content is authored precisely to demonstrate banned patterns
@@ -319,7 +321,7 @@ function checkArtifactBanned(content, rel) {
 // Internal specialist role ids (cx-business-strategist, cx-product-manager, …) are
 // implementation detail; in a consuming project's deliverable they read as a tool-identity
 // leak. The set is anchored to the real role ids from specialists/registry.json — an
-// open-ended /cx-[a-z-]+/ also matches unrelated npm packages (cx-oracle, cx-ray, cx-pro)
+// open-ended /cx-[a-z-]+/ also matches unrelated npm packages (cx-ray, cx-pro, cx-widget)
 // and would fail the release gate on legitimate user content. Drift from the registry is
 // caught by tests/tool-invisibility.test.mjs, not at runtime: this module sits on the hook
 // path and must never throw on a missing or malformed registry file.
@@ -327,7 +329,7 @@ function checkArtifactBanned(content, rel) {
 export const KNOWN_CX_ROLE_IDS = [
   'accessibility', 'ai-engineer', 'architect', 'business-strategist', 'data-analyst',
   'data-engineer', 'debugger', 'designer', 'devil-advocate', 'docs-keeper', 'engineer',
-  'evaluator', 'explorer', 'legal-compliance', 'operations', 'orchestrator',
+  'evaluator', 'explorer', 'legal-compliance', 'operations', 'oracle', 'orchestrator',
   'platform-engineer', 'product-manager', 'qa', 'rd-lead', 'release-manager', 'researcher',
   'reviewer', 'security', 'sre', 'test-automation', 'trace-reviewer', 'ux-researcher',
 ];

package/lib/config/schema.mjs

@@ -65,6 +65,18 @@ export const DEFAULT_PROJECT_CONFIG = Object.freeze({
   hooks: Object.freeze({
     outputMode: 'auto',
   }),
+  models: Object.freeze({
+    visibility: Object.freeze({
+      mode: 'all_configured',
+      include: [],
+      exclude: [],
+      providers: {},
+    }),
+    catalog: Object.freeze({
+      liveOpenRouter: true,
+      maxLiveFree: 24,
+    }),
+  }),
   roleSelection: Object.freeze({
     primary: null,
     secondary: null,
@@ -171,14 +183,33 @@ export const FIELD_RULES = {
       billingMode: { type: 'string', enum: ['metered', 'subscription', 'mixed'] },
       enforce: { type: 'boolean' },
       budgets: { type: 'object' },
-      // Per-provider billing-mode overrides. The global billingMode is the
-      // fallback; entries here win for the provider id (anthropic, openai,
-      // openrouter, gemini, ollama, local, github-copilot, …). Subscription
-      // entries contribute $0 to "actual spend" headline numbers; the
-      // metered-equivalent stays in the footnote.
       providers: { type: 'object', required: false },
     },
   },
+  models: {
+    type: 'object',
+    required: false,
+    fields: {
+      visibility: {
+        type: 'object',
+        required: false,
+        fields: {
+          mode: { type: 'string', enum: ['all_configured', 'tier_defaults', 'explicit'] },
+          include: { type: 'array' },
+          exclude: { type: 'array' },
+          providers: { type: 'object' },
+        },
+      },
+      catalog: {
+        type: 'object',
+        required: false,
+        fields: {
+          liveOpenRouter: { type: 'boolean' },
+          maxLiveFree: { type: 'number' },
+        },
+      },
+    },
+  },
 };
 
 function checkType(value, expected) {

package/lib/contract-schemas/decision.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Decision",
+  "description": "Output from cx-architect: a documented architectural or design decision",
+  "type": "object",
+  "required": ["type", "goal", "approach", "tasks", "risks", "acceptanceCriteria"],
+  "properties": {
+    "type": { "type": "string", "enum": ["decision"] },
+    "goal": { "type": "string", "description": "Objective restated in one sentence" },
+    "approach": { "type": "string", "description": "Chosen strategy and rationale" },
+    "alternativesConsidered": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "tasks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["description", "owner", "complexity"],
+        "properties": {
+          "description": { "type": "string" },
+          "owner": { "type": "string" },
+          "complexity": { "type": "string", "enum": ["S", "M", "L"] }
+        }
+      }
+    },
+    "risks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["description", "mitigation"],
+        "properties": {
+          "description": { "type": "string" },
+          "mitigation": { "type": "string" }
+        }
+      }
+    },
+    "acceptanceCriteria": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1
+    },
+    "doNotTouch": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Files or systems that must stay unchanged"
+    }
+  },
+  "additionalProperties": false
+}

package/lib/contract-schemas/implementation.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Implementation",
+  "description": "Output from cx-engineer: summary of changes made",
+  "type": "object",
+  "required": ["type", "status", "filesChanged", "verificationChecklist"],
+  "properties": {
+    "type": { "type": "string", "enum": ["implementation"] },
+    "status": {
+      "type": "string",
+      "enum": ["DONE", "BLOCKED", "NEEDS_MAIN_INPUT"]
+    },
+    "filesChanged": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "action"],
+        "properties": {
+          "path": { "type": "string" },
+          "action": { "type": "string", "enum": ["created", "modified", "deleted"] },
+          "summary": { "type": "string" }
+        }
+      }
+    },
+    "verificationChecklist": {
+      "type": "object",
+      "properties": {
+        "compilesWithoutErrors": { "type": "boolean" },
+        "existingTestsPass": { "type": "boolean" },
+        "newBehaviorHasCoverage": { "type": "boolean" },
+        "noHardcodedSecrets": { "type": "boolean" },
+        "noFileOver800Lines": { "type": "boolean" }
+      },
+      "required": ["compilesWithoutErrors", "existingTestsPass", "newBehaviorHasCoverage", "noHardcodedSecrets", "noFileOver800Lines"]
+    },
+    "blockerDescription": {
+      "type": "string",
+      "description": "Required when status is BLOCKED or NEEDS_MAIN_INPUT"
+    },
+    "needsMainInput": {
+      "type": "object",
+      "description": "Required when status is NEEDS_MAIN_INPUT",
+      "properties": {
+        "taskKey": { "type": "string" },
+        "question": { "type": "string" },
+        "safeDefault": { "type": "string" }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/lib/contract-schemas/review-report.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ReviewReport",
+  "description": "Output from cx-reviewer or cx-security: findings from a code or security review",
+  "type": "object",
+  "required": ["type", "target", "verdict", "findings"],
+  "properties": {
+    "type": { "type": "string", "enum": ["review-report"] },
+    "target": { "type": "string", "description": "Files or scope reviewed" },
+    "verdict": {
+      "type": "string",
+      "enum": ["APPROVED", "APPROVED_WITH_WARNINGS", "BLOCKED"],
+      "description": "APPROVED = no CRITICAL/HIGH. APPROVED_WITH_WARNINGS = only HIGH (merge with caution). BLOCKED = CRITICAL found."
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["severity", "category", "location", "description", "fix"],
+        "properties": {
+          "severity": { "type": "string", "enum": ["CRITICAL", "HIGH", "MEDIUM", "LOW"] },
+          "category": { "type": "string", "description": "e.g. correctness, security, regression, coverage, maintainability" },
+          "location": { "type": "string", "description": "file:line" },
+          "description": { "type": "string" },
+          "fix": { "type": "string", "description": "Concrete remediation" }
+        }
+      }
+    },
+    "summary": { "type": "string", "description": "One-paragraph summary of overall quality" }
+  },
+  "additionalProperties": false
+}