@geraldmaron/construct 1.1.1 → 1.2.1

package/lib/chat/web-launcher.mjs

@@ -0,0 +1,63 @@
+/**
+ * lib/chat/web-launcher.mjs — start dashboard server and open /chat for construct chat --web.
+ *
+ * Reuses lib/service-manager.mjs startDashboard so the browser surface shares auth,
+ * CSRF, and static hosting with the operations dashboard.
+ */
+
+import { spawn } from 'node:child_process';
+import { startDashboard, readDashboardState } from '../service-manager.mjs';
+
+function openBrowser(url) {
+  const platform = process.platform;
+  let cmd;
+  let args;
+  if (platform === 'darwin') {
+    cmd = 'open';
+    args = [url];
+  } else if (platform === 'win32') {
+    cmd = 'cmd';
+    args = ['/c', 'start', '', url];
+  } else {
+    cmd = 'xdg-open';
+    args = [url];
+  }
+  try {
+    spawn(cmd, args, { detached: true, stdio: 'ignore' }).unref();
+  } catch {
+    /* browser open is best-effort */
+  }
+}
+
+export async function runWebChat({
+  cwd = process.cwd(),
+  env = process.env,
+  output = process.stdout,
+  errorOutput = process.stderr,
+  surface = null,
+} = {}) {
+  let dash = readDashboardState();
+  if (!dash?.port) {
+    const result = await startDashboard({ rootDir: cwd, preferredPort: parseInt(env.PORT || env.DASHBOARD_PORT || '4242', 10) });
+    if (result.started || result.reused) {
+      dash = { port: result.port, url: result.url || `http://127.0.0.1:${result.port}` };
+    } else {
+      errorOutput.write(`Failed to start dashboard: ${result.reason || 'unknown error'}\n`);
+      return 1;
+    }
+  }
+
+  const base = (dash.url || `http://127.0.0.1:${dash.port}`).replace(/\/$/, '');
+  const chatUrl = surface === 'desktop'
+    ? `${base}/chat/?surface=desktop`
+    : `${base}/chat/`;
+  output.write(`Construct web chat: ${chatUrl}\n`);
+  output.write('Press Ctrl-C to stop the dashboard server.\n');
+  openBrowser(chatUrl);
+
+  await new Promise((resolve) => {
+    process.once('SIGINT', resolve);
+    process.once('SIGTERM', resolve);
+  });
+  return 0;
+}

package/lib/chat/web-picker-keys.mjs

@@ -0,0 +1,46 @@
+/**
+ * lib/chat/web-picker-keys.mjs — keyboard routing for the web list picker.
+ *
+ * Arrow/enter/escape handling shared with Ink via list-picker.mjs; this module
+ * adapts DOM KeyboardEvent shapes for tests and the React overlay.
+ */
+
+import {
+  getPickerSelectedItem,
+  getPickerVisibleItems,
+  movePickerIndex,
+  reducePickerKey,
+} from './list-picker.mjs';
+
+export { getPickerSelectedItem, getPickerVisibleItems, movePickerIndex };
+
+export function domKeyToPickerKey(event) {
+  const key = event?.key || '';
+  return {
+    char: key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey ? key : undefined,
+    key: {
+      escape: key === 'Escape',
+      return: key === 'Enter',
+      upArrow: key === 'ArrowUp',
+      downArrow: key === 'ArrowDown',
+      backspace: key === 'Backspace',
+      delete: key === 'Delete',
+      ctrl: event.ctrlKey,
+      meta: event.metaKey,
+    },
+  };
+}
+
+export function isPickerNavigationKey(key) {
+  return key === 'ArrowUp' || key === 'ArrowDown' || key === 'Enter' || key === 'Escape';
+}
+
+export function reduceWebPickerKey(state, event) {
+  return reducePickerKey(state, domKeyToPickerKey(event));
+}
+
+export function commitWebPickerSelection(state) {
+  const item = getPickerSelectedItem(state);
+  if (!item || item.disabled) return { ok: false, item: null };
+  return { ok: true, item };
+}

package/lib/chat/web-session.mjs

@@ -0,0 +1,159 @@
+/**
+ * lib/chat/web-session.mjs — owned-loop runtime factory for browser chat.
+ *
+ * Builds the same driver + session shape as lib/chat/cli.mjs so dashboard SSE
+ * and construct chat --web share one configuration path. One runtime instance
+ * is kept per conversation id for the lifetime of the server process.
+ */
+import { randomBytes } from 'crypto';
+import { createOwnedLoopDriver } from '../../apps/chat/engine/loop-driver.mjs';
+import { resolveChatModelSelectionAsync, resolveSessionModel } from '../../apps/chat/engine/models.mjs';
+import { loadChatConfig } from './config.mjs';
+import { loadConstructEnv } from '../env-config.mjs';
+import { resolveLayers } from './transparency.mjs';
+import { buildSystemPrompt } from './system-prompt.mjs';
+import { createSessionUsage } from './tui/usage.mjs';
+import { resolveExecutionCapabilityProfile } from '../models/execution-capability-profile.mjs';
+import { compileExecutionPolicy } from '../models/execution-policy.mjs';
+import { resolveDemoGuideForChat } from '../demo-surface.mjs';
+
+const runtimes = new Map();
+const pendingPermissions = new Map();
+
+function createPermissionHandler({ session, onPermission = null }) {
+  return async (req) => {
+    const mode = session.permissionMode || 'allow_once';
+    if (mode === 'reject') return 'reject';
+    if (mode === 'allow_always') return 'allow_always';
+    if (mode === 'allow_once') return 'allow';
+    if (mode === 'ask') {
+      const requestId = req.requestId || `perm-${randomBytes(8).toString('hex')}`;
+      onPermission?.({
+        type: 'permission',
+        requestId,
+        toolCall: { title: req.tool || req.toolCall?.title || 'tool', input: req.input ?? null },
+        options: ['allow', 'allow_always', 'reject'],
+      });
+      return new Promise((resolve) => {
+        pendingPermissions.set(requestId, { resolve, req, convId: session.convId });
+        setTimeout(() => {
+          if (pendingPermissions.has(requestId)) {
+            pendingPermissions.delete(requestId);
+            resolve('reject');
+          }
+        }, 120_000);
+      });
+    }
+    return 'allow';
+  };
+}
+
+export function resolveWebPermission(requestId, decision) {
+  const pending = pendingPermissions.get(requestId);
+  if (!pending) return false;
+  pendingPermissions.delete(requestId);
+  pending.resolve(decision);
+  return true;
+}
+
+export function listPendingPermissions(convId) {
+  return [...pendingPermissions.entries()]
+    .filter(([, p]) => p.convId === convId)
+    .map(([requestId, p]) => ({
+      requestId,
+      title: p.req?.toolCall?.title || 'tool',
+      options: p.req?.options || ['allow', 'reject'],
+    }));
+}
+
+export function getWebChatRuntime(convId) {
+  return runtimes.get(convId) || null;
+}
+
+export async function ensureWebChatRuntime({
+  convId,
+  cwd = process.cwd(),
+  env = process.env,
+  onPermission = null,
+} = {}) {
+  if (runtimes.has(convId)) return runtimes.get(convId);
+
+  const effectiveEnv = loadConstructEnv({ rootDir: cwd, env, warn: false });
+  const { config } = loadChatConfig({ cwd });
+  const layers = resolveLayers({ flags: {}, env: effectiveEnv });
+  for (const key of Object.keys(config.layers || {})) {
+    if (config.layers[key] === false) layers[key] = false;
+  }
+
+  let modelMode = config.modelMode || 'pinned';
+  let resolvedModel = config.model || null;
+  if (modelMode === 'free-router') {
+    const sessionStub = { modelMode: 'free-router', failedModels: new Set() };
+    resolvedModel = await resolveSessionModel(sessionStub, { env: effectiveEnv, tier: 'standard' });
+  }
+
+  const modelResolution = modelMode === 'free-router' && resolvedModel
+    ? { id: resolvedModel, notice: null }
+    : await resolveChatModelSelectionAsync({ env: effectiveEnv, requested: resolvedModel });
+
+  const demoName = effectiveEnv.CONSTRUCT_DEMO || null;
+  const demoPack = demoName ? resolveDemoGuideForChat(demoName, { cwd, repoRoot: cwd }) : null;
+
+  const session = {
+    convId,
+    model: modelResolution.id || resolvedModel,
+    modelMode,
+    permissionMode: config.permissionMode || 'allow_once',
+    sandbox: config.sandbox || 'workspace-write',
+    layers,
+    usage: createSessionUsage(),
+    demoGuide: demoPack?.guide || null,
+    demoTitle: demoPack?.script?.title || null,
+  };
+
+  const handlers = {
+    getSandbox: () => session.sandbox,
+    getPermissionMode: () => session.permissionMode,
+    requestPermission: createPermissionHandler({ session, onPermission }),
+  };
+
+  const { createAiSdkAgent } = await import('../../apps/chat/engine/ai-sdk-agent.mjs');
+  const driver = createOwnedLoopDriver({
+    env: effectiveEnv,
+    cwd,
+    model: session.model,
+    handlers,
+    systemPrompt: buildSystemPrompt({
+      capabilityTier: compileExecutionPolicy({
+        profile: resolveExecutionCapabilityProfile({ model: session.model }),
+      }).prompt.systemPromptTier,
+    }),
+    createAgent: (opts) => createAiSdkAgent(opts),
+  });
+
+  const runtime = { convId, driver, session, layers, cwd, env: effectiveEnv, _started: false };
+  runtimes.set(convId, runtime);
+
+  if (!demoPack?.guide) {
+    await driver.start();
+    runtime._started = true;
+  }
+
+  return runtime;
+}
+
+export async function ensureDriverStarted(runtime) {
+  if (!runtime || runtime._started) return runtime;
+  await runtime.driver.start();
+  runtime._started = true;
+  return runtime;
+}
+
+export const createWebChatRuntime = ensureWebChatRuntime;
+
+export function dropWebChatRuntime(convId) {
+  const runtime = runtimes.get(convId);
+  if (!runtime) return;
+  try { runtime.driver.stop?.(); } catch { /* already stopped */ }
+  runtimes.delete(convId);
+}

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) ───────────────────────────────────────────
@@ -321,15 +322,63 @@ 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|--no-figures] [--plain] [--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: '--no-figures', desc: 'Skip diagram rendering' },
+      { flag: '--plain, --no-brand', desc: 'Explicitly opt out of Construct branding for a brand-capable output' },
+      { 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',
@@ -433,6 +482,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: '🔌',
@@ -534,6 +591,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: '🧹',
@@ -545,7 +611,7 @@ export const CLI_COMMANDS = [
     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' },
     ],
@@ -564,7 +630,42 @@ 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: 'Plan or locally execute manifest-backed artifact workflows with execution provenance',
+    usage: 'construct artifact <validate|workflow> ...',
+    subcommands: [
+      { name: 'validate', desc: 'Run manifest structure, citation, and reviewer checks' },
+      { name: 'workflow', desc: 'Return a truthful plan/run report; --apply only runs local validation/export after approval' },
+    ],
   },
   {
     name: 'doc',
@@ -635,13 +736,19 @@ export const CLI_COMMANDS = [
     emoji: '🎬',
     category: 'Work',
     core: false,
-    description: 'Record reproducible terminal demos via VHS/asciinema (optional system binaries; ADR-0001)',
-    usage: 'construct demo <name> [--format=gif|mp4|webm] [--out=<path>] [--source-only]',
+    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: '--format=<f>',  desc: 'gif (default) | mp4 | webm (VHS only)' },
-      { flag: '--out=<path>',  desc: 'Output path (default: .cx/demos/<name>-<ts>.<ext>)' },
-      { flag: '--source-only', desc: 'Always write the .tape source; skip recording' },
+      { 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' },
     ],
   },
   {
@@ -668,6 +775,20 @@ export const CLI_COMMANDS = [
     description: 'Deployment mode configuration',
     usage: 'construct config <get|set>',
   },
+  {
+    name: 'sources',
+    emoji: '🔗',
+    category: 'Advanced',
+    core: false,
+    description: 'Manage typed integration source targets in construct.config.json',
+    usage: 'construct sources list|add|remove|validate',
+    subcommands: [
+      { name: 'list', desc: 'Show config targets, legacy env merge, and effective set' },
+      { name: 'add <provider> <id> <selector-json>', desc: 'Add a typed target (github, jira, linear, slack)' },
+      { name: 'remove <id>', desc: 'Remove a config target by id' },
+      { name: 'validate', desc: 'Validate sources.targets in construct.config.json' },
+    ],
+  },
   {
     name: 'uninstall',
     emoji: '🧹',
@@ -876,8 +997,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',
@@ -991,8 +1112,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',
@@ -1023,7 +1144,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' },
@@ -1031,6 +1158,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);
 

package/lib/cli-service-inventory.mjs

@@ -0,0 +1,42 @@
+/**
+ * lib/cli-service-inventory.mjs — auditable public CLI/catalog/docs inventory.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { CLI_COMMANDS } from './cli-commands.mjs';
+
+function slugify(category) {
+  return category.toLowerCase().replace(/&/g, 'and').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+
+function handlerNames(rootDir) {
+  const source = fs.readFileSync(path.join(rootDir, 'bin', 'construct'), 'utf8');
+  const names = new Set();
+  for (const match of source.matchAll(/\n {2,3}\[\s*'([^']+)'\s*,/g)) names.add(match[1]);
+  return names;
+}
+
+/**
+ * The catalog is the public-service source of truth. This projection joins it
+ * to runtime dispatch and the generated reference pages so drift is observable
+ * without treating internal handlers as public services.
+ */
+export function buildCliServiceInventory({ rootDir = process.cwd() } = {}) {
+  const handlers = handlerNames(rootDir);
+  return CLI_COMMANDS.filter((spec) => !spec.internal).map((spec) => {
+    const page = path.join(rootDir, 'docs', 'reference', 'cli', `${slugify(spec.category)}.md`);
+    const pageText = fs.existsSync(page) ? fs.readFileSync(page, 'utf8') : '';
+    return {
+      name: spec.name,
+      category: spec.category,
+      runnable: handlers.has(spec.name),
+      documented: pageText.includes(`## construct ${spec.name}`),
+      usage: spec.usage,
+      subcommands: (spec.subcommands ?? []).map((sub) => ({
+        name: typeof sub === 'string' ? sub : sub.name,
+        documented: typeof sub === 'string' ? true : Boolean(sub.desc || sub.description),
+      })),
+    };
+  });
+}

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',
 ];