@geraldmaron/construct 1.0.21 → 1.0.23

package/lib/agent-instructions/inject.mjs

@@ -0,0 +1,94 @@
+/**
+ * lib/agent-instructions/inject.mjs — non-destructive marker-block injection for
+ * agent-instruction files the user owns (AGENTS.md, CLAUDE.md) — ADR-0027 §2.
+ *
+ * Construct's integration guidance lives inside a versioned, hash-stamped block:
+ *
+ *   <!-- BEGIN CONSTRUCT INTEGRATION v:N hash:XXXX -->
+ *   ...pointers...
+ *   <!-- END CONSTRUCT INTEGRATION -->
+ *
+ * Everything outside the markers is preserved byte-for-byte. Injection is
+ * idempotent: an existing block with the same version+hash is a no-op; a
+ * different hash replaces the block content only; no block appends one. The
+ * block dedups against a sibling Beads Integration block — when one is present
+ * the tracker line points at it instead of repeating `bd` commands.
+ *
+ * Mirrors the marker pattern beads-automation uses for its own block, lifted
+ * into a reusable primitive so init and sync share one append-or-replace path.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+
+export const CONSTRUCT_INTEGRATION_VERSION = 1;
+
+const BEGIN_PREFIX = '<!-- BEGIN CONSTRUCT INTEGRATION';
+const END_MARKER = '<!-- END CONSTRUCT INTEGRATION -->';
+const BLOCK_RE = /<!-- BEGIN CONSTRUCT INTEGRATION[^>]*-->[\s\S]*?<!-- END CONSTRUCT INTEGRATION -->/;
+const BEADS_BLOCK_RE = /<!-- BEGIN BEADS INTEGRATION/;
+
+function shortHash(body) {
+  return createHash('sha256').update(body).digest('hex').slice(0, 12);
+}
+
+// The managed block: concise pointers to the surfaces an agent needs to work
+// with Construct (≤60 lines). When a Beads Integration block is already present
+// the tracker line defers to it rather than duplicating `bd` commands.
+
+export function buildConstructIntegrationBody({ hasBeadsBlock = false } = {}) {
+  const tracker = hasBeadsBlock
+    ? '- **Tracker**: see the Beads Integration block below for `bd` commands.'
+    : '- **Tracker**: use Beads (`bd`) for all task tracking — run `bd prime` for the workflow. Do not use ad-hoc TODO lists.';
+  return [
+    '## Construct integration',
+    '',
+    'This project is managed by Construct. Address `@construct` in your editor and ask',
+    'for the outcome, not the specialist — Construct routes to the right specialist chain.',
+    '',
+    '- **Durable state** lives in `.cx/` (context, knowledge, intake, traces) and Beads.',
+    '  If services are down, resume from `plan.md`, `.cx/context.md`, the latest',
+    '  `.cx/handoffs/` file, Beads, and git.',
+    '- **Signals**: drop a file into `.cx/inbox/`; `construct intake` classifies and routes it.',
+    '- **Specialists** (architect, reviewer, security, …) are dispatched by Construct — you',
+    '  do not call them directly.',
+    tracker,
+    '- **Single-writer rule**: one session owns a file\'s edits; others review or wait.',
+    '- Run `construct doctor` to check system health.',
+  ].join('\n');
+}
+
+// Inject or update the managed block in `content`. Returns the new content and
+// the action taken (`unchanged` | `updated` | `created`).
+
+export function injectConstructBlock(content, body, version = CONSTRUCT_INTEGRATION_VERSION) {
+  const hash = shortHash(body);
+  const block = `${BEGIN_PREFIX} v:${version} hash:${hash} -->\n${body}\n${END_MARKER}`;
+  const existing = content.match(BLOCK_RE);
+  if (existing) {
+    if (existing[0].includes(`v:${version} hash:${hash}`)) return { content, action: 'unchanged' };
+    return { content: content.replace(BLOCK_RE, block), action: 'updated' };
+  }
+  const sep = content.length === 0 ? '' : content.endsWith('\n') ? '\n' : '\n\n';
+  return { content: `${content}${sep}${block}\n`, action: 'created' };
+}
+
+// Apply the managed block to a single agent-instruction file. Creates the file
+// (with `header`) when missing; otherwise injects/updates in place, preserving
+// all surrounding content. Writes only when the content changes.
+
+export function injectIntoAgentFile(filePath, { version = CONSTRUCT_INTEGRATION_VERSION, header = '' } = {}) {
+  const existed = fs.existsSync(filePath);
+  const current = existed ? fs.readFileSync(filePath, 'utf8') : '';
+  const hasBeadsBlock = BEADS_BLOCK_RE.test(current);
+  const body = buildConstructIntegrationBody({ hasBeadsBlock });
+  const base = !existed && header ? (header.endsWith('\n') ? header : `${header}\n`) : current;
+  const { content, action } = injectConstructBlock(base, body, version);
+  const changed = !existed || action !== 'unchanged';
+  if (changed) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content, 'utf8');
+  }
+  return { action: existed ? action : 'created', existed, changed };
+}

package/lib/auto-docs.mjs

@@ -20,6 +20,14 @@ import { execSync } from 'node:child_process';
 
 import { CLI_COMMANDS_BY_CATEGORY, CATEGORY_ORDER } from './cli-commands.mjs';
 
+// A raw `|` inside a markdown table cell is parsed as a column delimiter, so a
+// description like `--scope=project|user|both` splits the row into phantom
+// columns. Escape pipes (and flatten newlines) for any value emitted into a cell.
+
+function tableCell(value) {
+  return String(value ?? '').replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+}
+
 // --- region helpers ---
 
 function replaceRegion(content, regionName, newBody) {
@@ -53,7 +61,7 @@ function buildCommandsTable() {
     rows.push('| Command | What it does |');
     rows.push('|---|---|');
     for (const cmd of cmds) {
-      rows.push(`| \`construct ${cmd.name}\` | ${cmd.description} |`);
+      rows.push(`| \`construct ${cmd.name}\` | ${tableCell(cmd.description)} |`);
     }
     rows.push('');
   }
@@ -335,7 +343,7 @@ function renderCommandPage(category, commands) {
   lines.push('| Command | What it does |');
   lines.push('|---|---|');
   for (const cmd of commands) {
-    lines.push(`| \`construct ${cmd.name}\` | ${cmd.description} |`);
+    lines.push(`| \`construct ${cmd.name}\` | ${tableCell(cmd.description)} |`);
   }
   lines.push('');
   for (const cmd of commands) {

package/lib/cli-commands.mjs

@@ -12,6 +12,8 @@
  *   - internal: true → hidden from --help and --all; callable but not advertised
  */
 
+import { resolveColors } from './term-format.mjs';
+
 export const CLI_COMMANDS = [
   // ── Core (shown by default) ───────────────────────────────────────────
   {
@@ -26,6 +28,14 @@ export const CLI_COMMANDS = [
       { flag: '--only=<a,b,c>', desc: 'Start only the named services (postgres, dashboard, telemetry, memory, opencode)' },
     ],
   },
+  {
+    name: 'dashboard',
+    emoji: '📊',
+    category: 'Core',
+    core: true,
+    description: 'Start the local dashboard/orchestration daemon (or --token to mint a dashboard token)',
+    usage: 'construct dashboard [--token]',
+  },
   {
     name: 'stop',
     emoji: '⏹',
@@ -50,12 +60,14 @@ export const CLI_COMMANDS = [
     emoji: '🛠️',
     category: 'Core',
     core: true,
-    description: 'Machine setup (once per machine): Docker, cm/cass, config, embeddings',
-    usage: 'construct install [--yes] [--no-docker] [--reconfigure]',
+    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]',
     options: [
-      { flag: '--yes',         desc: 'Apply defaults without prompts' },
-      { flag: '--no-docker',   desc: 'Skip Docker-based service setup (local Postgres)' },
-      { flag: '--reconfigure', desc: 'Re-prompt for service consent, ignoring cached answers' },
+      { 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: '--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' },
     ],
   },
   {
@@ -68,6 +80,9 @@ export const CLI_COMMANDS = [
     options: [
       { flag: '--yes', desc: 'Accept all defaults (non-interactive)' },
       { flag: '--no-start', desc: 'Do not start services after init' },
+      { flag: '--commit-bootstrap', desc: 'Keep the beads bootstrap commit (default: leave files uncommitted)' },
+      { flag: '--with-<host>', desc: 'Force an adapter set (claude|codex|opencode|vscode|cursor|copilot); default writes detected hosts only' },
+      { flag: '--all-hosts', desc: 'Write every adapter set regardless of what is installed' },
       { flag: '--interactive, -i', desc: 'Enable interactive setup with project detection' },
       { flag: '--quiet, -q', desc: 'Minimal output' },
       { flag: '--verbose, -v', desc: 'Detailed output' },
@@ -236,6 +251,8 @@ export const CLI_COMMANDS = [
       { flag: '--fix-legacy-agents', desc: 'Sweep legacy cx-*.md agents at user scope and re-sync' },
     ],
   },
+  
+  // ── Work (project workflows) ──────────────────────────────────────────
   {
     name: 'distill',
     emoji: '🔬',
@@ -252,6 +269,14 @@ export const CLI_COMMANDS = [
     description: 'Convert documents to indexed markdown',
     usage: 'construct ingest <file> [--strategy=adapter|provider] [--orchestration=prompt-only|orchestrated] [--strict] [--legacy-extractor]',
   },
+  {
+    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>]',
+  },
   {
     name: 'infer',
     emoji: '🧠',
@@ -339,13 +364,21 @@ export const CLI_COMMANDS = [
     emoji: '🎼',
     category: 'Models & Integrations',
     core: false,
-    description: 'Construct-owned local orchestration runtime (Mode-A: single-process, filesystem-backed, no Docker)',
-    usage: 'construct orchestrate <run|status> [options]',
+    description: 'Construct-owned local orchestration runtime, in-process or against the local daemon (--remote)',
+    usage: 'construct orchestrate <run|status> [options] [--remote]',
     subcommands: [
-      { name: 'run "<request>" [--strategy S] [--host H] [--no-construct] [--no-execute] [--json]', desc: 'Plan and run a request through a Construct-owned specialist chain; returns host-adapter metadata' },
-      { name: 'status [run-id] [--json]', desc: 'Inspect a run, or list recent runs' },
+      { name: 'run "<request>" [--strategy S] [--host H] [--worker-backend provider] [--no-construct] [--no-execute] [--json] [--remote]', desc: 'Plan and run a request through a Construct-owned specialist chain; --remote drives the local daemon over HTTP' },
+      { name: 'status [run-id] [--json] [--remote]', desc: 'Inspect a run, or list recent runs (locally or from the daemon)' },
     ],
   },
+  {
+    name: 'acp',
+    emoji: '🔗',
+    category: 'Models & Integrations',
+    core: false,
+    description: 'Run Construct as an Agent Client Protocol (ACP) server over stdio for Zed/JetBrains/VS Code ACP clients',
+    usage: 'construct acp',
+  },
   {
     name: 'mcp',
     emoji: '🔌',
@@ -965,17 +998,12 @@ export function getCommandSpec(name) {
   return CLI_COMMANDS.find((c) => c.name === name) || null;
 }
 
-const ESC = String.fromCharCode(27);
-
 // Render a per-command help block. Pulls usage, description, subcommands,
 // and options from the CLI_COMMANDS entry so help stays consistent across
 // every command. Internal commands fall back to a minimal block.
 
 export function formatCommandHelp(name, { colors = false } = {}) {
-  const useColor = colors && process.stdout.isTTY && !process.env.NO_COLOR && process.env.TERM !== 'dumb';
-  const c = useColor
-    ? { bold: `${ESC}[1m`, dim: `${ESC}[2m`, reset: `${ESC}[0m` }
-    : { bold: '', dim: '', reset: '' };
+  const c = resolveColors({ enabled: colors });
   const spec = getCommandSpec(name);
   if (!spec) {
     return `Unknown command: ${name}\n\nRun 'construct --help' for available commands.\n`;

package/lib/comment-lint.mjs

@@ -52,6 +52,38 @@ function isArtifactPath(rel) {
   return ARTIFACT_PATH_GLOBS.some((r) => r.test(rel));
 }
 
+// Deliverable surfaces where a tool-identity leak (rules/common/tool-invisibility.md)
+// matters: project docs and the durable .cx knowledge / research / handoff / strategy
+// stores. Broader than the fabrication-scoped ARTIFACT_PATH_GLOBS because a strategy
+// lands in docs/ root, not only docs/prd.
+
+const DELIVERABLE_LEAK_GLOBS = [
+  /^docs\/.*\.md$/,
+  /^\.cx\/(?:research|knowledge|handoffs)\//,
+  /^\.cx\/strategy\.md$/,
+];
+
+function isDeliverablePath(rel) {
+  return DELIVERABLE_LEAK_GLOBS.some((r) => r.test(rel));
+}
+
+// The Construct repo legitimately names Construct and its cx-* roles in its own docs —
+// the tool-identity check is for consuming projects only. Identify self by package name,
+// memoized per rootDir so a repo-wide lint reads package.json once, not once per file.
+
+const selfRepoCache = new Map();
+
+function isConstructSelfRepo(rootDir) {
+  if (selfRepoCache.has(rootDir)) return selfRepoCache.get(rootDir);
+  let isSelf = false;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(rootDir, 'package.json'), 'utf8'));
+    isSelf = pkg.name === '@geraldmaron/construct';
+  } catch { isSelf = false; }
+  selfRepoCache.set(rootDir, isSelf);
+  return isSelf;
+}
+
 function requiresHeader(rel) {
   const ext = path.extname(rel);
   if (['.yaml', '.yml', '.json', '.jsonl', '.toml'].includes(ext)) return { required: false, type: null };
@@ -284,6 +316,77 @@ function checkArtifactBanned(content, rel) {
   return violations;
 }
 
+// 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)
+// 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.
+
+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',
+  'platform-engineer', 'product-manager', 'qa', 'rd-lead', 'release-manager', 'researcher',
+  'reviewer', 'security', 'sre', 'test-automation', 'trace-reviewer', 'ux-researcher',
+];
+
+const CX_ROLE_LEAK = new RegExp(
+  `\\bcx-(?:${[...KNOWN_CX_ROLE_IDS].sort((a, b) => b.length - a.length).join('|')})\\b`,
+);
+
+// Code fences (``` or ~~~) wrap non-prose content, so a role id inside one is not a leak.
+// Only closed fences are skipped: an unclosed fence must not suppress scanning of the rest
+// of the document, or the backstop would fail open on a leak. Returns the line indices that
+// fall inside a properly terminated fence.
+
+function closedFenceLines(lines) {
+  const inside = new Set();
+  let openChar = null;
+  let pending = [];
+  for (let i = 0; i < lines.length; i++) {
+    const marker = lines[i].match(/^(```+|~~~+)/);
+    if (openChar === null) {
+      if (marker) { openChar = marker[1][0]; pending = [i]; }
+      continue;
+    }
+    pending.push(i);
+    if (marker && marker[1][0] === openChar) {
+      for (const idx of pending) inside.add(idx);
+      openChar = null;
+      pending = [];
+    }
+  }
+  return inside;
+}
+
+function findToolIdentityLeaks(content) {
+  const lines = content.split('\n');
+  const fenced = closedFenceLines(lines);
+  const violations = [];
+  let inFrontmatter = false;
+  let inComment = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (i === 0 && line.trim() === '---') { inFrontmatter = true; continue; }
+    if (inFrontmatter) { if (line.trim() === '---') inFrontmatter = false; continue; }
+    if (fenced.has(i)) continue;
+    if (inComment) { if (line.includes('-->')) inComment = false; continue; }
+    if (line.includes('construct-lint-ignore')) continue;
+    const scan = line.replace(/<!--.*?-->/g, '');
+    if (line.includes('<!--') && !line.includes('-->')) inComment = true;
+    if (CX_ROLE_LEAK.test(scan)) {
+      violations.push({
+        line: i + 1,
+        label: 'tool-identity leak: internal cx-* specialist role id in a deliverable — the artifact is about the user\'s project, not Construct\'s roles (tool-invisibility §2)',
+        kind: 'artifact',
+      });
+    }
+  }
+  return violations;
+}
+
 function checkBanned(content, filePath) {
   if (isBannedCheckSkipped(filePath)) return [];
 
@@ -366,6 +469,18 @@ export function lintFile(filePath, { rootDir = process.cwd(), fix = false } = {}
     for (const v of artifactHits) bucket.push(v);
   }
 
+  // Tool-identity leak (rules/common/tool-invisibility.md): consuming-project deliverables
+  // only — skipped on the Construct repo, where naming Construct and cx-* roles is correct.
+  // Same mode routing as the artifact lint (warn by default, block in the release gate).
+  if (!isConstructSelfRepo(rootDir) && isDeliverablePath(rel)) {
+    const leaks = findToolIdentityLeaks(content);
+    if (leaks.length > 0) {
+      const mode = process.env.CONSTRUCT_ARTIFACT_LINT_MODE || 'warn';
+      const bucket = mode === 'block' ? errors : warnings;
+      for (const v of leaks) bucket.push(v);
+    }
+  }
+
   return { path: rel, errors, warnings };
 }
 

package/lib/completions.mjs

@@ -5,7 +5,13 @@
  * Outputs to a platform-appropriate per-user completions directory.
  */
 
-import { CLI_COMMANDS } from './cli-commands.mjs';
+import { CLI_COMMANDS as ALL_CLI_COMMANDS } from './cli-commands.mjs';
+
+// Completions advertise only public commands. internal: true commands stay
+// callable but never appear as tab candidates (the cli-commands.mjs visibility
+// contract). Shadowing the imported list keeps every generator below public-only.
+
+const CLI_COMMANDS = ALL_CLI_COMMANDS.filter((c) => !c.internal);
 import { writeFileSync, mkdirSync, existsSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';

package/lib/config/schema.mjs

@@ -30,6 +30,7 @@ export const INGEST_ORCHESTRATIONS = ['prompt-only', 'orchestrated'];
 
 export const ORCHESTRATION_WORKER_BACKENDS = ['inline', 'provider'];
 export const ORCHESTRATION_STORES = ['filesystem', 'sqlite', 'postgres'];
+export const CHAIN_OF_THOUGHT_MODES = ['hidden', 'surface', 'telemetry_only'];
 
 // SessionStart context routing. `auto` keeps the rich payload on stdout for
 // interactive sessions and suppresses it (to a debug log) for non-interactive /
@@ -56,6 +57,7 @@ export const DEFAULT_PROJECT_CONFIG = Object.freeze({
   orchestration: Object.freeze({
     workerBackend: 'inline',
     store: 'filesystem',
+    chainOfThought: 'hidden',
   }),
   telemetry: Object.freeze({
     enabled: true,
@@ -93,6 +95,7 @@ export const DEFAULT_PROJECT_CONFIG = Object.freeze({
 });
 
 export const FIELD_RULES = {
+  $schema: { type: 'string', required: false },
   version: { type: 'number', required: true },
   alias: { type: 'string', required: false, maxLength: 120 },
   deployment: {
@@ -123,6 +126,7 @@ export const FIELD_RULES = {
     fields: {
       workerBackend: { type: 'string', enum: ORCHESTRATION_WORKER_BACKENDS },
       store: { type: 'string', enum: ORCHESTRATION_STORES },
+      chainOfThought: { type: 'string', enum: CHAIN_OF_THOUGHT_MODES },
     },
   },
   telemetry: {

package/lib/decisions/enforced-baseline.json

@@ -7,6 +7,8 @@
     "ADR-0019",
     "ADR-0020",
     "ADR-0021",
+    "ADR-0022",
+    "ADR-0023",
     "any-to-business-strategist",
     "any-to-explorer",
     "architect-to-data-engineer",

package/lib/docs-verify.mjs

@@ -122,26 +122,23 @@ function checkReadmeBasicSections(readmePath) {
   }
 }
 
-function checkAgentsRequiredSections(agentsPath) {
+// AGENTS.md is user-owned (ADR-0027 §2): a host project carries bd's skeleton
+// plus Construct's fenced integration block, while the meta-repo carries its own
+// hand-written contract. Neither has a fixed section list, so verify substance —
+// a heading and a non-trivial body past any frontmatter — not a prescribed shape.
+
+function checkAgentsPresent(agentsPath) {
   if (!fs.existsSync(agentsPath)) return false;
-  
+
   try {
-    const content = readFileSync(agentsPath, "utf8").toLowerCase();
-    const requiredSections = [
-      "operating hierarchy",
-      "start-of-session rules", 
-      "maintenance rules",
-      "end-of-session rules",
-      "verification rules"
-    ];
-    
-    const missingSections = requiredSections.filter(section => !content.includes(section));
-    
-    if (missingSections.length > 0) {
-      warnings.push(`AGENTS.md missing sections: ${missingSections.join(", ")} in ${path.relative(cwd, agentsPath)}`);
+    const content = readFileSync(agentsPath, "utf8");
+    const body = content.replace(/^---[\s\S]*?\n---\s*/, "").trim();
+
+    if (!/^#\s/m.test(body) || body.length < 40) {
+      warnings.push(`AGENTS.md is empty or lacks a usable agent guide: ${path.relative(cwd, agentsPath)}`);
       return false;
     }
-    
+
     return true;
   } catch (err) {
     warnings.push(`Cannot read AGENTS.md: ${path.relative(cwd, agentsPath)} (${err.message})`);
@@ -389,7 +386,7 @@ function main() {
   if (!quickMode) {
     // Detailed checks (warnings only)
     checkReadmeBasicSections(path.join(cwd, "README.md"));
-    checkAgentsRequiredSections(path.join(cwd, "AGENTS.md"));
+    checkAgentsPresent(path.join(cwd, "AGENTS.md"));
     if (planExists) checkPlanLinkedToIssues(path.join(cwd, "plan.md"));
     if (cxExists && fs.existsSync(contextMdPath)) checkContextHasProgress(contextMdPath);
     checkDocsSystem(path.join(cwd, "docs"));
@@ -454,7 +451,7 @@ export {
   checkExists,
   checkFileAge,
   checkReadmeBasicSections,
-  checkAgentsRequiredSections,
+  checkAgentsPresent,
   checkPlanLinkedToIssues,
   checkContextHasProgress,
   checkDocsSystem,

package/lib/doctor/cli.mjs

@@ -94,6 +94,13 @@ export async function runCli(args) {
     return 0;
   }
 
+  if (sub === 'bench:hooks') {
+    const { main } = await import('../../scripts/bench-hooks.mjs');
+    const report = await main();
+    const failed = report.results.filter((r) => r.status === 'fail');
+    return failed.length > 0 ? 1 : 0;
+  }
+
   if (sub === 'consistency') {
     const { runAllChecks } = await import('./watchers/consistency.mjs');
     const result = await runAllChecks();
@@ -109,6 +116,6 @@ export async function runCli(args) {
   }
 
   console.error(`Unknown doctor subcommand: ${sub}`);
-  console.error('Usage: construct doctor [status|watch|stop|logs|tick|consistency]');
+  console.error('Usage: construct doctor [status|watch|stop|logs|tick|consistency|bench:hooks]');
   return 2;
 }

package/lib/document-export.mjs

@@ -0,0 +1,124 @@
+/**
+ * lib/document-export.mjs — markdown → PDF / DOCX / HTML export via external
+ * binaries (Pandoc + Typst), per ADR-0024.
+ *
+ * Bound to system-binary tooling discovered at runtime, never bundled in core
+ * (ADR-0001 zero-npm-core; ADR-0014 optional-capability pattern). Both engines
+ * are spawned as separate processes — Pandoc isolates its GPLv2+ licence at
+ * the process boundary; Typst is the Apache-2.0 PDF engine driven through
+ * Pandoc's `--pdf-engine=typst` flag, so a single Pandoc invocation produces
+ * every target format the contract supports.
+ *
+ * detect(format) reports availability without spawning the engine for real.
+ * exportMarkdown({ inputPath, outputPath, format, env }) spawns the engine and
+ * returns a structured result. Both surface actionable "install X" guidance
+ * when a required binary is absent; neither throws on missing tooling.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+export const EXPORT_FORMATS = ['pdf', 'docx', 'html'];
+
+const FORMAT_ENGINES = {
+  pdf: { engine: 'pandoc', pdfEngine: 'typst', extraBinaries: ['typst'] },
+  docx: { engine: 'pandoc', pdfEngine: null, extraBinaries: [] },
+  html: { engine: 'pandoc', pdfEngine: null, extraBinaries: [] },
+};
+
+function whichBin(name, env = process.env) {
+  const cmd = process.platform === 'win32' ? 'where' : 'which';
+  const result = spawnSync(cmd, [name], { encoding: 'utf8', env });
+  if (result.status !== 0) return null;
+  const first = (result.stdout || '').trim().split('\n')[0];
+  return first || null;
+}
+
+function binVersion(name, args = ['--version'], env = process.env) {
+  const r = spawnSync(name, args, { encoding: 'utf8', env });
+  if (r.status !== 0) return null;
+  const line = (r.stdout || '').trim().split('\n')[0];
+  return line || null;
+}
+
+function installHint(name) {
+  if (name === 'pandoc') return 'Install pandoc to enable document export (e.g. `brew install pandoc` on macOS, `apt install pandoc` on Debian/Ubuntu, or https://pandoc.org/installing.html).';
+  if (name === 'typst') return 'Install typst to enable PDF export via Pandoc (`brew install typst` on macOS, https://github.com/typst/typst/releases for binaries).';
+  return `Install ${name} to enable this export format.`;
+}
+
+// detect returns the same structure regardless of format so callers can render
+// availability uniformly. `present` is the single boolean a caller should gate
+// on; `missing` enumerates the binaries to install when present is false.
+
+export function detect(format, env = process.env) {
+  const config = FORMAT_ENGINES[format];
+  if (!config) return { ok: false, format, present: false, missing: [], message: `Unsupported format: ${format}. Supported: ${EXPORT_FORMATS.join(', ')}.` };
+  const required = [config.engine, ...(config.extraBinaries || [])];
+  const status = required.map((name) => ({ name, path: whichBin(name, env), version: null }));
+  for (const s of status) if (s.path) s.version = binVersion(s.name, ['--version'], env);
+  const missing = status.filter((s) => !s.path).map((s) => s.name);
+  return {
+    ok: true,
+    format,
+    present: missing.length === 0,
+    binaries: status,
+    missing,
+    message: missing.length === 0
+      ? `Ready: ${status.map((s) => `${s.name} (${s.version?.split(' ').slice(0, 2).join(' ') ?? 'unknown'})`).join(', ')}`
+      : missing.map(installHint).join(' '),
+  };
+}
+
+function defaultOutputPath(inputPath, format) {
+  const parsed = path.parse(inputPath);
+  return path.join(parsed.dir, `${parsed.name}.${format}`);
+}
+
+// exportMarkdown is the single contract callers depend on (CLI / MCP / SDK).
+// Returns { ok, format, inputPath, outputPath, engine, missing?, message }.
+// ok=false with a populated `missing` means a required binary is absent — the
+// caller surfaces `message` (which carries the install hint) instead of
+// retrying or crashing.
+
+export function exportMarkdown({ inputPath, outputPath, format, env = process.env, spawnFn = spawnSync } = {}) {
+  if (!inputPath) return { ok: false, format, message: 'exportMarkdown: inputPath is required.' };
+  if (!EXPORT_FORMATS.includes(format)) return { ok: false, format, inputPath, message: `Unsupported format: ${format}. Supported: ${EXPORT_FORMATS.join(', ')}.` };
+  if (!fs.existsSync(inputPath)) return { ok: false, format, inputPath, message: `exportMarkdown: input does not exist: ${inputPath}` };
+
+  const detection = detect(format, env);
+  if (!detection.present) {
+    return { ok: false, format, inputPath, missing: detection.missing, message: detection.message };
+  }
+
+  const config = FORMAT_ENGINES[format];
+  const target = outputPath || defaultOutputPath(inputPath, format);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+
+  const args = ['-f', 'markdown', '-o', target, '--standalone'];
+  if (config.pdfEngine) args.push(`--pdf-engine=${config.pdfEngine}`);
+  args.push(inputPath);
+
+  const result = spawnFn(config.engine, args, { encoding: 'utf8', env });
+  if (result.status !== 0) {
+    return {
+      ok: false,
+      format,
+      inputPath,
+      outputPath: target,
+      engine: config.engine,
+      message: `Export failed (${config.engine} exit ${result.status}): ${(result.stderr || result.stdout || '').trim().slice(0, 400)}`,
+    };
+  }
+
+  return {
+    ok: true,
+    format,
+    inputPath,
+    outputPath: target,
+    engine: config.engine,
+    pdfEngine: config.pdfEngine,
+    message: `Wrote ${path.relative(process.cwd(), target)}`,
+  };
+}

package/lib/embed/daemon.mjs

@@ -1077,7 +1077,7 @@ this.#scheduler.register(
                 method: 'POST',
                 headers: {
                   Authorization: `Bearer ${orKey}`, 'content-type': 'application/json',
-                  'HTTP-Referer': 'https://github.com/construct',
+                  'HTTP-Referer': 'https://github.com/geraldmaron/construct',
                 },
                 body: JSON.stringify({
                   model: modelId.replace(/^openrouter\//, ''),