@geraldmaron/construct 1.0.24 → 1.1.1

package/lib/audit-trail.mjs

@@ -1,22 +1,68 @@
 /**
- * lib/audit-trail.mjs — reads the append-only audit log produced by
- * lib/hooks/audit-trail.mjs and renders it for `construct audit trail`.
+ * lib/audit-trail.mjs — owns the append-only audit log written by
+ * lib/hooks/audit-trail.mjs and rendered for `construct audit trail`.
  *
  * The log is JSONL at ~/.cx/audit-trail.jsonl. Each line carries a
  * prev_line_hash pointing at the SHA-256 of the previous line — tampering
  * (reorder, delete, edit) breaks the chain and is surfaced by --verify.
+ *
+ * A serial hash chain cannot survive concurrent appends: a read-prev-hash +
+ * append done outside a critical section lets two processes (hook, daemon,
+ * parallel tool calls in one session) both chain off the same predecessor, so
+ * the second link points at a stale tail. appendAuditRecord
+ * closes that window by computing prev_line_hash and appending inside a single
+ * cross-process file lock, making every writer effectively serialized.
+ *
+ * Corrupted links cannot be re-derived, so a `chain_reset` boundary line seals
+ * the damaged prefix as immutable legacy and re-bases the live chain;
+ * verifyChain validates only from the last boundary forward. See
+ * docs/concepts/observability.mdx.
  */
-import { readFileSync, existsSync, statSync } from 'node:fs';
+import { readFileSync, existsSync, statSync, mkdirSync } from 'node:fs';
 import { createHash } from 'node:crypto';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 
+import { appendBounded, readLastLineAcrossSegments } from './logging/rotate.mjs';
+import { withFileLockSync } from './storage/file-lock.mjs';
+
 const AUDIT_FILE = join(homedir(), '.cx', 'audit-trail.jsonl');
 
 function sha256(input) {
   return createHash('sha256').update(input).digest('hex');
 }
 
+// prev_line_hash and the append must be one atomic step or concurrent writers
+// race; the file lock serializes them across processes.
+
+export function appendAuditRecord(partial, { file = AUDIT_FILE } = {}) {
+  return withFileLockSync(file, () => {
+    let prev = null;
+    try {
+      const last = readLastLineAcrossSegments(file);
+      if (last !== null) prev = sha256(last);
+    } catch { /* first record, or unreadable tail */ }
+    const record = { ...partial, prev_line_hash: prev };
+    mkdirSync(dirname(file), { recursive: true });
+    appendBounded('audit-trail', file, JSON.stringify(record) + '\n');
+    return record;
+  });
+}
+
+// A reset boundary seals the records it follows as legacy excluded from
+// verification and re-bases the live chain from this line.
+
+export function writeChainReset({ file = AUDIT_FILE, reason = 'manual reset' } = {}) {
+  return appendAuditRecord({
+    ts: new Date().toISOString(),
+    chain_reset: true,
+    reason,
+    agent: 'construct',
+    tool: null,
+    target: null,
+  }, { file });
+}
+
 export function readAuditTrail({ limit = 50, since = null, agent = null, tool = null } = {}) {
   if (!existsSync(AUDIT_FILE)) return [];
   const lines = readFileSync(AUDIT_FILE, 'utf8').split('\n').filter(Boolean);
@@ -34,19 +80,29 @@ export function readAuditTrail({ limit = 50, since = null, agent = null, tool =
   return filtered.slice(-limit);
 }
 
-export function verifyChain() {
-  if (!existsSync(AUDIT_FILE)) return { ok: true, verified: 0, broken: [] };
-  const lines = readFileSync(AUDIT_FILE, 'utf8').split('\n').filter(Boolean);
+export function verifyChain(file = AUDIT_FILE) {
+  if (!existsSync(file)) return { ok: true, verified: 0, broken: [], legacy: 0 };
+  const lines = readFileSync(file, 'utf8').split('\n').filter(Boolean);
+
+  // Validation starts at the last reset boundary; the prefix it seals is legacy
+  // and exempt, so concurrency damage predating the migration can't fail the chain.
+
+  let start = 0;
+  for (let i = 0; i < lines.length; i += 1) {
+    try { if (JSON.parse(lines[i]).chain_reset) start = i; } catch { /* legacy malformed */ }
+  }
+
   const broken = [];
   let prevHash = null;
-  for (let i = 0; i < lines.length; i += 1) {
+  for (let i = start; i < lines.length; i += 1) {
     const line = lines[i];
     let row;
     try { row = JSON.parse(line); } catch {
       broken.push({ line: i + 1, reason: 'malformed JSON' });
+      prevHash = sha256(line);
       continue;
     }
-    if (i > 0 && row.prev_line_hash !== prevHash) {
+    if (i > start && !row.chain_reset && row.prev_line_hash !== prevHash) {
       broken.push({
         line: i + 1,
         expected: prevHash,
@@ -56,7 +112,7 @@ export function verifyChain() {
     }
     prevHash = sha256(line);
   }
-  return { ok: broken.length === 0, verified: lines.length, broken };
+  return { ok: broken.length === 0, verified: lines.length - start, broken, legacy: start };
 }
 
 function formatRow(row) {
@@ -74,6 +130,9 @@ export async function runAuditTrailCli(args = []) {
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
     if (arg === '--verify') flags.add('verify');
+    else if (arg === '--reset') flags.add('reset');
+    else if (arg.startsWith('--reason=')) options.reason = arg.slice(9);
+    else if (arg === '--reason') options.reason = args[++i];
     else if (arg === '--json') flags.add('json');
     else if (arg === '--all') flags.add('all');
     else if (arg.startsWith('--limit=')) options.limit = Number(arg.slice(8));
@@ -97,6 +156,8 @@ Options:
   --agent <name>    Filter to a specific agent (e.g. cx-engineer)
   --tool <name>     Filter to a specific tool (Edit, Write, MultiEdit, NotebookEdit, Bash)
   --verify          Verify the tamper-evidence chain and exit
+  --reset           Seal the current chain as legacy and re-base a fresh chain
+  --reason <text>   Reason recorded on the --reset boundary
   --json            Emit raw JSONL lines instead of formatted output
   -h, --help        Show this message
 
@@ -105,6 +166,12 @@ Log location: ${AUDIT_FILE}
     return;
   }
 
+  if (flags.has('reset')) {
+    writeChainReset({ reason: options.reason || 'manual reset' });
+    console.log(`Audit chain re-based at ${AUDIT_FILE}. Prior records sealed as legacy; verification resumes from the new boundary.`);
+    return;
+  }
+
   if (flags.has('verify')) {
     const result = verifyChain();
     if (result.ok) {

package/lib/beads-client.mjs

@@ -252,6 +252,15 @@ export async function runBd(args, options = {}) {
  * Used as fallback when optimistic locking fails.
  */
 async function runWithLegacyLock(args, opts, cwd, commandDesc) {
+  // Telemetry: every legacy-fallback firing is recorded so the lock+queue removal
+  // decision rests on observed data — if this never fires over a representative
+  // window, the whole exclusive-lock path is removable; if it fires, the entries
+  // name the bd errors that actually need handling (bead construct-nhn5).
+  try {
+    const { logBeadsFallback } = await import('./telemetry/beads-fallback.mjs');
+    logBeadsFallback({ command: commandDesc || args[0] || 'unknown' });
+  } catch { /* telemetry is best-effort */ }
+
   // Clean up any stale locks before trying
   cleanupStaleLock({ cwd });
   cleanupStaleQueue({ cwd });

package/lib/beads-optimistic.mjs

@@ -1,14 +1,14 @@
 /**
- * lib/beads-optimistic.mjs — Optimistic locking and concurrent read support for beads.
+ * lib/beads-optimistic.mjs — concurrent reads + retry-on-conflict writes for beads.
  *
- * Addresses the beads lock contention issue by:
- * 1. Allowing concurrent reads (no lock required)
- * 2. Using optimistic locking for writes (version-based conflict detection)
- * 3. Automatic retry with exponential backoff on conflict
- * 4. Read-replicas for team mode (when available)
- *
- * Replaces the exclusive lock model with a more scalable approach
- * while maintaining consistency guarantees.
+ * Dolt commits are atomic, so it is the serializer: a write is executed and, on a
+ * transient conflict, retried with exponential backoff. There is no separate
+ * read-then-compare version check — that spanned two `bd` processes (a `bd show`
+ * to read the commit hash, then a `bd update`) and guarded nothing, since `bd
+ * update` accepts no expected version, so the window between the read and the
+ * write left the "optimistic lock" unable to actually detect a conflicting commit
+ * (bead construct-iufy). Reads run lock-free; `getBeadVersion` remains as an
+ * advisory reader, not a write-path primitive.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -34,8 +34,9 @@ const DEFAULT_RETRY_OPTIONS = {
 // ---------------------------------------------------------------------------
 
 /**
- * Read the current version of a bead from the database.
- * In Dolt, this uses the commit hash as a logical version.
+ * Read the current version of a bead from the database (the Dolt commit hash).
+ * Advisory only — exposed for callers that want to observe a bead's version; the
+ * write path does not gate on it (see file header).
  */
 export async function getBeadVersion(beadId, cwd = process.cwd()) {
   try {
@@ -56,75 +57,37 @@ export async function getBeadVersion(beadId, cwd = process.cwd()) {
 }
 
 /**
- * Execute a write operation with optimistic locking.
- * 
+ * Execute a bead write, retrying on a transient conflict. Dolt's atomic commit is
+ * the serializer; this does not pre-read or compare a version (see file header).
+ *
  * @param {Object} options
- * @param {string} options.beadId - The bead being modified
  * @param {Function} options.execute - Async function that performs the write
- * @param {string} options.expectedVersion - Version we expect the bead to have
  * @param {Object} options.retry - Retry configuration
  * @returns {Promise<{success: boolean, result: any, attempts: number}>}
  */
 export async function optimisticWrite({
-  beadId,
   execute,
-  expectedVersion,
   retry = DEFAULT_RETRY_OPTIONS,
-  cwd = process.cwd(),
 } = {}) {
   let attempts = 0;
   let delay = retry.baseDelayMs;
-  
+
   while (attempts < retry.maxRetries) {
     attempts++;
-    
-    // Verify version hasn't changed (optimistic check)
-    const currentVersion = await getBeadVersion(beadId, cwd);
-    
-    if (expectedVersion && currentVersion !== expectedVersion) {
-      // Conflict detected - another writer modified the bead
-      if (attempts >= retry.maxRetries) {
-        return {
-          success: false,
-          error: `Optimistic lock conflict after ${attempts} attempts. Bead ${beadId} was modified by another process.`,
-          attempts,
-          currentVersion,
-          expectedVersion,
-        };
-      }
-      
-      // Wait with exponential backoff and jitter
-      const jitter = Math.random() * 50;
-      await new Promise(r => setTimeout(r, delay + jitter));
-      delay = Math.min(delay * retry.backoffMultiplier, retry.maxDelayMs);
-      continue;
-    }
-    
     try {
-      // Execute the write operation
       const result = await execute();
       return { success: true, result, attempts };
     } catch (error) {
       if (attempts >= retry.maxRetries) {
-        return {
-          success: false,
-          error: error.message,
-          attempts,
-        };
+        return { success: false, error: error.message, attempts };
       }
-      
-      // Retry on transient errors
       const jitter = Math.random() * 50;
-      await new Promise(r => setTimeout(r, delay + jitter));
+      await new Promise((r) => setTimeout(r, delay + jitter));
       delay = Math.min(delay * retry.backoffMultiplier, retry.maxDelayMs);
     }
   }
-  
-  return {
-    success: false,
-    error: `Max retries (${retry.maxRetries}) exceeded`,
-    attempts,
-  };
+
+  return { success: false, error: `Max retries (${retry.maxRetries}) exceeded`, attempts };
 }
 
 // ---------------------------------------------------------------------------
@@ -187,21 +150,10 @@ export async function updateBeadOptimistic(
   options = {}
 ) {
   const { actor = 'construct', cwd = process.cwd(), notes } = options;
-  
-  // Get current version before attempting update
-  const currentVersion = await getBeadVersion(beadId, cwd);
-  
-  if (!currentVersion) {
-    return {
-      success: false,
-      error: `Bead ${beadId} not found`,
-    };
-  }
-  
+
+  // A `bd update` on a missing bead exits non-zero and surfaces as a failed
+  // result, so no separate existence pre-check is needed.
   return optimisticWrite({
-    beadId,
-    expectedVersion: currentVersion,
-    cwd,
     execute: async () => {
       const args = ['update', beadId];
       

package/lib/bridges/copilot-proxy.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * lib/bridges/copilot-proxy.mjs — Minimal GitHub Copilot to OpenAI-compatible bridge.
+ *
+ * Translates standard OpenAI /v1/chat/completions requests to the Copilot API
+ * using the user's active `gh` CLI session.
+ */
+import http from 'node:http';
+import { execSync } from 'node:child_process';
+
+const PORT = parseInt(process.argv.find(a => a.startsWith('--port='))?.split('=')[1] || '5174', 10);
+
+let cachedSession = null;
+
+async function getCopilotToken() {
+  if (cachedSession && cachedSession.expires_at > (Date.now() / 1000) + 60) {
+    return cachedSession.token;
+  }
+
+  try {
+    const ghToken = execSync('gh auth token', { encoding: 'utf8' }).trim();
+    const res = await fetch('https://api.github.com/copilot_internal/v2/token', {
+      headers: {
+        'Authorization': `Bearer ${ghToken}`,
+        'Accept': 'application/json',
+      }
+    });
+
+    if (!res.ok) throw new Error(`Failed to get session token: ${res.statusText}`);
+    
+    cachedSession = await res.json();
+    return cachedSession.token;
+  } catch (err) {
+    console.error('Error fetching Copilot token:', err.message);
+    return null;
+  }
+}
+
+const server = http.createServer(async (req, res) => {
+  // CORS
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'POST, GET, OPTIONS');
+  res.setHeader('Access-Control-Allow-Headers', '*');
+
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204);
+    res.end();
+    return;
+  }
+
+  if (req.url === '/v1/chat/completions' && req.method === 'POST') {
+    const token = await getCopilotToken();
+    if (!token) {
+      res.writeHead(401, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Failed to authenticate with GitHub Copilot via gh CLI.' }));
+      return;
+    }
+
+    let body = '';
+    req.on('data', chunk => { body += chunk; });
+    req.on('end', async () => {
+      try {
+        const payload = JSON.parse(body);
+        
+        // Map common model names to Copilot equivalents if needed
+        // For now, we pass them through or default to gpt-4o
+        const model = payload.model?.includes('gpt-4o') ? 'gpt-4o' : 
+                      payload.model?.includes('claude-3.5-sonnet') ? 'claude-3.5-sonnet' : 
+                      'gpt-4o';
+
+        const copilotRes = await fetch('https://api.githubcopilot.com/chat/completions', {
+          method: 'POST',
+          headers: {
+            'Authorization': `Bearer ${token}`,
+            'Content-Type': 'application/json',
+            'Accept': 'application/json',
+            'X-Github-Api-Version': '2023-07-07',
+            'Editor-Version': 'vscode/1.90.0', // Spoof VS Code for compatibility
+          },
+          body: JSON.stringify({
+            ...payload,
+            model
+          })
+        });
+
+        res.writeHead(copilotRes.status, {
+          'Content-Type': copilotRes.headers.get('Content-Type'),
+        });
+
+        if (payload.stream) {
+           const reader = copilotRes.body.getReader();
+           while (true) {
+             const { done, value } = await reader.read();
+             if (done) break;
+             res.write(value);
+           }
+           res.end();
+        } else {
+          const data = await copilotRes.text();
+          res.end(data);
+        }
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: err.message }));
+      }
+    });
+    return;
+  }
+
+  res.writeHead(404);
+  res.end('Not Found');
+});
+
+server.listen(PORT, '127.0.0.1', () => {
+  console.log(`Copilot Bridge listening on http://127.0.0.1:${PORT}`);
+});

package/lib/cli-commands.mjs

@@ -23,6 +23,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 +39,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 +51,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 +62,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,13 +77,19 @@ 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]',
+    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' },
+      { flag: '--with-docling',   desc: 'Eagerly provision the docling document-extraction venv now (heavy, ~10 min; else lazy on first ingest)' },
     ],
   },
   {
@@ -77,6 +99,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' },
@@ -102,6 +128,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' },
@@ -116,6 +146,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)' },
@@ -133,6 +167,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',
@@ -179,6 +217,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' },
@@ -193,6 +235,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' },
@@ -224,6 +270,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' },
@@ -237,6 +287,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' },
@@ -487,6 +541,7 @@ 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' },
@@ -559,6 +614,36 @@ 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: 'Record reproducible terminal demos via VHS/asciinema (optional system binaries; ADR-0001)',
+    usage: 'construct demo <name> [--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' },
+    ],
+  },
   {
     name: 'ollama',
     emoji: '🦙',
@@ -936,6 +1021,9 @@ export const CLI_COMMANDS = [
   { name: 'lint:contracts',    category: 'Internal', core: false, internal: true, description: 'Internal lint: specialist contracts', usage: 'construct lint:contracts' },
   { name: 'lint:research',     category: 'Internal', core: false, internal: true, description: 'Internal lint: research artifacts', usage: 'construct lint:research' },
   { 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: '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,5 +1119,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

@@ -86,7 +86,7 @@ function isConstructSelfRepo(rootDir) {
 
 function requiresHeader(rel) {
   const ext = path.extname(rel);
-  if (['.yaml', '.yml', '.json', '.jsonl', '.toml'].includes(ext)) return { required: false, type: null };
+  if (['.yaml', '.yml', '.json', '.jsonl', '.toml', '.txt'].includes(ext)) return { required: false, type: null };
   const jsMatch = JS_HEADER_GLOBS.some(r => r.test(rel));
   const mdMatch = MD_HEADER_GLOBS.some(r => r.test(rel));
   // Exclude static assets under lib/server/static from requiring headers