@geraldmaron/construct 1.0.11 → 1.0.14

package/README.md

@@ -2,7 +2,7 @@
 
 **One AI interface. A team of specialists behind it. Hard gates. Runs locally, or deploys for teams.**
 
-📖 **[Read the docs →](https://geraldmaron.github.io/construct/)** · 🚀 **[5-minute quickstart →](https://geraldmaron.github.io/construct/docs/start)** · 📦 `npm install -g @geraldmaron/construct`
+📖 **[Read the docs →](https://geraldmaron.github.io/construct/)** · 🚀 **[5-minute quickstart →](https://geraldmaron.github.io/construct/start)** · 📦 `npm install -g @geraldmaron/construct`
 
 ---
 
@@ -10,7 +10,7 @@
 
 Construct sits on top of Claude Code, OpenCode, Codex, Cursor, and Copilot. You talk to one persona called `construct`. Behind it is a team of specialists shaped by your **org profile**: software R&D by default, with curated profiles for operations, creative, and research orgs, plus a schema-validated escape hatch for custom profiles. Each profile organizes its specialists by department (Product, Engineering, Operations, etc.) and carries its own intake taxonomy, doc templates, and role set. Sessions survive boundary changes via durable state in `.cx/`, beads, and a local vector index. Solo by default. Can deploy centrally for teams that want shared memory, telemetry, queues, and policy.
 
-`construct profile show|list|set <id>` to switch. See [Profile lifecycle](https://geraldmaron.github.io/construct/docs/concepts/profile-lifecycle) for how new profiles are built (it's a research process, not a JSON exercise).
+`construct profile show|list|set <id>` to switch. See [Profile lifecycle](https://geraldmaron.github.io/construct/concepts/profile-lifecycle) for how new profiles are built (it's a research process, not a JSON exercise).
 
 The team and enterprise modes exist because I wanted to learn what shipping a real multi-tenant tool would look like. The project is still open source, the code is still public, and the bar is still "does this help me learn." Run it solo if that's all you need.
 
@@ -39,20 +39,33 @@ Open your editor and talk to `@construct`. A walkthrough lives in `construct_gui
 
 No Node? Try `brew install geraldmaron/construct/construct`. Cloning a project that already uses Construct? `npx -y @geraldmaron/construct init` wires it up.
 
-[Five minute walkthrough](https://geraldmaron.github.io/construct/docs/start).
+[Five minute walkthrough](https://geraldmaron.github.io/construct/start).
+
+## Usage
+
+Most days, the loop is:
+
+```bash
+construct status          # confirm services and editor adapters are healthy
+construct sync            # refresh host adapters after registry, prompt, or config changes
+construct intake list     # review new signals, if your project uses the inbox
+construct doctor          # diagnose install, service, MCP, and adapter drift
+```
+
+In your editor, start with `@construct`. Ask for the outcome, not the specialist. Construct routes to the right specialist chain, keeps durable state in `.cx/` and Beads, and blocks risky mutations until the configured gates pass.
 
 ## What you can do
 
 | If you want to... | Read |
 |---|---|
-| Install and run a first task | [Start](https://geraldmaron.github.io/construct/docs/start) |
-| Understand how it works | [Architecture](https://geraldmaron.github.io/construct/docs/concepts/architecture) |
-| Pick a deployment mode | [Deployment model](https://geraldmaron.github.io/construct/docs/concepts/deployment-model) |
-| Drop a signal and triage it | [Intake and triage](https://geraldmaron.github.io/construct/docs/concepts/intake-and-triage) |
-| Add a custom specialist | [Add a custom agent](https://geraldmaron.github.io/construct/docs/cookbook/add-a-custom-agent) |
-| Fix a blocked commit or red CI | [Fix a policy violation](https://geraldmaron.github.io/construct/docs/cookbook/fix-a-policy-violation) |
-| Plug in your own LLM | [Plug in your own LLM](https://geraldmaron.github.io/construct/docs/cookbook/plug-in-your-own-llm) |
-| Look up a CLI command | [CLI reference](https://geraldmaron.github.io/construct/docs/reference/cli) |
+| Install and run a first task | [Start](https://geraldmaron.github.io/construct/start) |
+| Understand how it works | [Architecture](https://geraldmaron.github.io/construct/concepts/architecture) |
+| Pick a deployment mode | [Deployment model](https://geraldmaron.github.io/construct/concepts/deployment-model) |
+| Drop a signal and triage it | [Intake and triage](https://geraldmaron.github.io/construct/concepts/intake-and-triage) |
+| Add a custom specialist | [Add a custom specialist](https://geraldmaron.github.io/construct/cookbook/add-a-custom-agent) |
+| Fix a blocked commit or red CI | [Fix a policy violation](https://geraldmaron.github.io/construct/cookbook/fix-a-policy-violation) |
+| Plug in your own LLM | [Plug in your own LLM](https://geraldmaron.github.io/construct/cookbook/plug-in-your-own-llm) |
+| Look up a CLI command | [CLI reference](https://geraldmaron.github.io/construct/reference/cli) |
 
 Works with Anthropic, OpenRouter, Ollama, and other OpenAI-compatible providers.
 
@@ -64,21 +77,27 @@ Three modes. `solo` is the default and runs everything locally. Filesystem queue
 
 `enterprise` adds tenant isolation, RBAC and ABAC scaffolding, isolated worker containers, signed MCP allowlists, and mandatory audit.
 
-Pick or change modes with `construct config mode [solo|team|enterprise]`. [Deployment model](https://geraldmaron.github.io/construct/docs/concepts/deployment-model).
+Pick or change modes with `construct config mode [solo|team|enterprise]`. [Deployment model](https://geraldmaron.github.io/construct/concepts/deployment-model).
 
 ## Intake
 
 Anything dropped into `.cx/inbox/` (a bug report, a customer comment, a competitor PDF, a postmortem draft) is classified by the active profile's intake taxonomy. The default `rnd` profile uses bug, user-signal, experiment, architecture, incident, security, requirement, research, ops, eval-finding, launch-asset, legal-compliance. The `operations` profile uses request, incident, ops, security, docs. The `creative` profile uses brief, content-request, asset, experiment, report. The `research` profile uses question, study, synthesis, report.
 
-Each signal gets a primary owner and a recommended handoff chain. Inspect with `construct intake list` and `construct intake show <id>`. Generate a task graph with `construct graph from-intake <id>`. The classifier runs in the daemon and is deterministic. The agent in your editor does the actual analysis. [Intake and triage](https://geraldmaron.github.io/construct/docs/concepts/intake-and-triage).
+Each signal gets a primary owner and a recommended handoff chain. Inspect with `construct intake list` and `construct intake show <id>`. Generate a task graph with `construct graph from-intake <id>`. The classifier runs in the daemon and is deterministic. The agent in your editor does the actual analysis. [Intake and triage](https://geraldmaron.github.io/construct/concepts/intake-and-triage).
 
 ## Hard gates
 
-Every code mutation runs through enforcement. No secrets committed, tests green, docs current, comments lint-clean, CI passes. Gates live in three places: write-time, commit-time, CI safety net. They can only be bypassed with explicit env vars so every exception leaves an audit trail. [Gates and enforcement](https://geraldmaron.github.io/construct/docs/concepts/gates-and-enforcement).
+Every code mutation runs through enforcement. No secrets committed, tests green, docs current, comments lint-clean, CI passes. Gates live in three places: write-time, commit-time, CI safety net. They can only be bypassed with explicit env vars so every exception leaves an audit trail. [Gates and enforcement](https://geraldmaron.github.io/construct/concepts/gates-and-enforcement).
 
 ## Learning loops
 
-Construct gets smarter on its own. Every session ends with an automatic capture: tools used, files touched, what the final reply said. That goes into `.cx/observations/` and is searchable from the next session. See [`docs/concepts/learning-loops.md`](./docs/concepts/learning-loops.md) for what's wired, what's coming, and how to turn pieces off.
+Construct gets smarter on its own. Every session ends with an automatic capture: tools used, files touched, what the final reply said. That goes into `.cx/observations/` and is searchable from the next session. See [`docs/concepts/learning-loops.mdx`](./docs/concepts/learning-loops.mdx) for what's wired, what's coming, and how to turn pieces off.
+
+## `.cx/` is local-only runtime state
+
+`construct init` writes a runtime state tree at `.cx/` inside the project root: observations, sessions, vector index, intake packets, task graphs, and traces. **It's local-only and must never be committed.** `construct init` adds `.cx/` to your project's `.gitignore` automatically (idempotent: it won't double-add if you already have it). Daily trace shards (`.cx/traces/<date>.jsonl`) cap at 100 MB and rotate to `<date>.<n>.jsonl` so a stray commit never crosses GitHub's single-file limit. Override the cap with `CONSTRUCT_TRACE_MAX_MB`.
+
+The embed daemon writes its supervisor stdout log to `~/.cx/runtime/embed-daemon.log`. That log rotates every minute at 50 MB and keeps 5 gzipped segments by default; override via `CONSTRUCT_EMBED_LOG_MAX_MB` and `CONSTRUCT_EMBED_LOG_MAX_SEGMENTS`.
 
 ## Core commands
 
@@ -124,6 +143,16 @@ Construct gets smarter on its own. Every session ends with an automatic capture:
 | `construct workflow` | Instantiate workflow templates (PRD-to-review chains, onboarding, handoffs) |
 | `construct workspace` | Manage PM workspaces for multi-PM signal routing |
 
+### Models & Integrations
+
+| Command | What it does |
+|---|---|
+| `construct claude:allow` | Manage Claude Code `permissions.allow` from the outside (auto-classifier blocks the agent from editing it) |
+| `construct hosts` | Show host support for Construct orchestration |
+| `construct mcp` | Manage MCP integrations |
+| `construct models` | Show or update model tier assignments |
+| `construct plugin` | Manage external Construct plugin manifests |
+
 ### Integrations
 
 | Command | What it does |
@@ -145,6 +174,14 @@ Construct gets smarter on its own. Every session ends with an automatic capture:
 | `construct telemetry` | Query telemetry traces and latency data |
 | `construct telemetry-backfill` | Backfill sparse traces with observations (trace backend) |
 
+### Diagnostics
+
+| Command | What it does |
+|---|---|
+| `construct audit` | Audit Construct internals and review the mutation trail |
+| `construct cleanup` | Release dev-agent memory pressure by cleaning stale helper and bridge processes |
+| `construct doc` | Verify or inspect auditability stamps on Construct-generated markdown files |
+
 ### Advanced
 
 | Command | What it does |
@@ -176,7 +213,7 @@ Construct gets smarter on its own. Every session ends with an automatic capture:
 
 - [`CONTRIBUTING.md`](./CONTRIBUTING.md). Branch workflow, gates, review expectations.
 - [`CHANGELOG.md`](./CHANGELOG.md). Release history.
-- [`docs/concepts/architecture.md`](./docs/concepts/architecture.md). Canonical architecture.
+- [`docs/concepts/architecture.mdx`](./docs/concepts/architecture.mdx). Canonical architecture.
 - [`AGENTS.md`](./AGENTS.md). Agent operating contract.
 
 ## Project structure
@@ -184,16 +221,16 @@ Construct gets smarter on its own. Every session ends with an automatic capture:
 <!-- AUTO:structure -->
 ```text
 construct/
-├── apps             User-facing apps shipped from this repo (e.g. apps/docs/, the Fumadocs docs site)
+├── apps             User-facing apps shipped from this repo (e.g. apps/docs/, the Next.js docs site)
 ├── bin              CLI entrypoint (`construct`)
 ├── commands         Command prompt assets
 ├── config
-├── dashboard
 ├── db
 ├── deploy
 ├── docs             Architecture notes, runbooks, and documentation contract
 ├── examples
 ├── lib              Core runtime: CLI, hooks, MCP, status, sync, workflow
+├── packages
 ├── personas         Persona prompt definitions
 ├── platforms
 ├── profiles

package/bin/construct

@@ -416,11 +416,190 @@ async function cmdDoctor() {
     return;
   }
 
+  // --fix-* flags drive auto-remediation for legacy state left behind by
+  // pre-2.0 installs. Layer-2 update triggers (npm i -g postinstall, brew
+  // upgrade) normally handle this; --fix-* is the manual recovery path.
+  // --fix-all runs every available fix.
+
+  const wantsFixAll = args.includes('--fix-all') || args.includes('--fix');
+  const wantsFixGitignore = wantsFixAll || args.includes('--fix-gitignore');
+  const wantsFixLegacyAgents = wantsFixAll || args.includes('--fix-legacy-agents');
+  const wantsFixEmbedLog = wantsFixAll || args.includes('--fix-embed-log');
+  const wantsFixMigrateState = wantsFixAll || args.includes('--fix-migrate-state');
+
   const checks = [];
   const add = (label, pass, optional = false) => checks.push({ label, pass, optional });
   add('registry.json exists', fs.existsSync(path.join(ROOT_DIR, 'specialists', 'registry.json')));
   add('sync-specialists.mjs exists', fs.existsSync(path.join(ROOT_DIR, 'scripts', 'sync-specialists.mjs')));
 
+  // Dashboard static build output. The Next.js app under apps/dashboard
+  // emits a static export into lib/server/static/ via its postbuild script;
+  // an empty static dir means lib/server/index.mjs will serve 404s.
+
+  const dashboardIndex = path.join(ROOT_DIR, 'lib', 'server', 'static', 'index.html');
+  add('Dashboard built (lib/server/static/index.html)', fs.existsSync(dashboardIndex));
+
+  // Project .gitignore must cover .cx/. Auto-fix via --fix-gitignore.
+  // Only checks when cwd looks like a Construct project (has .cx/ or
+  // .construct/); non-project cwds get no warning.
+
+  const cwd = process.cwd();
+  const isProject = fs.existsSync(path.join(cwd, '.cx')) || fs.existsSync(path.join(cwd, '.construct'));
+  if (isProject) {
+    const giPath = path.join(cwd, '.gitignore');
+    const giContent = fs.existsSync(giPath) ? fs.readFileSync(giPath, 'utf8') : '';
+    const lines = giContent.split('\n').map((l) => l.trim());
+    const cxIgnored = lines.some((l) => l === '.cx' || l === '.cx/' || l === '.cx/**' || l === '*' || l === '**');
+    if (!cxIgnored && wantsFixGitignore) {
+      const prefix = giContent.length === 0 || giContent.endsWith('\n') ? '' : '\n';
+      fs.writeFileSync(giPath, giContent + `${prefix}\n# Construct runtime state — local-only, never source\n.cx/\n`, 'utf8');
+      println(`  fix: appended .cx/ to ${path.relative(cwd, giPath)}`);
+      add('Project .gitignore covers .cx/', true);
+    } else {
+      add('Project .gitignore covers .cx/' + (cxIgnored ? '' : ' (run `construct doctor --fix-gitignore` to add)'), cxIgnored);
+    }
+  }
+
+  // Legacy cx-* files at user scope. Layer-2 (npm postinstall, brew
+  // upgrade) sweeps these via `construct sync --global`; this check is
+  // the manual safety net. Counts files matching a registered specialist
+  // name across Claude / Codex / Copilot user-scope dirs.
+
+  const userHome = HOME;
+  const registry = JSON.parse(fs.readFileSync(path.join(ROOT_DIR, 'specialists', 'registry.json'), 'utf8'));
+  const specialistSet = new Set((registry.specialists ?? []).map((s) => `cx-${s.name}`));
+  const legacyTargets = [
+    { dir: path.join(userHome, '.claude', 'agents'), ext: '.md' },
+    { dir: path.join(userHome, '.codex', 'agents'), ext: '.toml' },
+    { dir: path.join(userHome, '.github', 'prompts'), ext: '.prompt.md' },
+  ];
+  let legacyCount = 0;
+  for (const t of legacyTargets) {
+    if (!fs.existsSync(t.dir)) continue;
+    for (const f of fs.readdirSync(t.dir)) {
+      if (!f.endsWith(t.ext)) continue;
+      const base = f.slice(0, -t.ext.length);
+      if (specialistSet.has(base)) legacyCount++;
+    }
+  }
+  if (legacyCount > 0 && wantsFixLegacyAgents) {
+    const syncScript = path.join(ROOT_DIR, 'scripts', 'sync-specialists.mjs');
+    const result = spawnSync(process.execPath, [syncScript, '--global'], { stdio: 'pipe', encoding: 'utf8' });
+    if (result.status === 0) {
+      println(`  fix: swept ${legacyCount} legacy cx-* file(s) from user scope via construct sync --global`);
+      add('No legacy cx-* files at user scope', true);
+    } else {
+      add(`Legacy cx-* sweep failed: ${result.stderr?.substring(0, 200)}`, false);
+    }
+  } else {
+    // Soft-warn instead of hard-fail: legacy v1.0.10 cx-* files are an
+    // expected upgrade-state, not real drift. The hint is what matters;
+    // the fix is one --fix-legacy-agents run away and CI never sees this.
+    // Mirrors the parity check's legacy-install reclassification.
+
+    add(
+      legacyCount === 0
+        ? 'No legacy cx-* files at user scope'
+        : `Legacy cx-* files at user scope: ${legacyCount} (run \`construct doctor --fix-legacy-agents\` to sweep)`,
+      true,
+      legacyCount !== 0,
+    );
+  }
+
+  // Pre-push bypass frequency. Every honored CONSTRUCT_SKIP_PREPUSH /
+  // CONSTRUCT_ALLOW_CLAUDE_PUSH / CONSTRUCT_SKIP_PR_LINT writes a JSONL
+  // entry to ~/.construct/audit/prepush-bypass.log. Surfacing frequent
+  // usage here is the early warning that the gate is the wrong shape —
+  // the alternative is letting the bypass quietly become the default.
+
+  const bypassLogPath = path.join(userHome, '.construct', 'audit', 'prepush-bypass.log');
+  if (fs.existsSync(bypassLogPath)) {
+    try {
+      const cutoff = Date.now() - 7 * 24 * 60 * 60 * 1000;
+      const recent = fs.readFileSync(bypassLogPath, 'utf8')
+        .split('\n')
+        .filter(Boolean)
+        .map((line) => { try { return JSON.parse(line); } catch { return null; } })
+        .filter((e) => e && Date.parse(e.ts) >= cutoff);
+      const BYPASS_WARN_THRESHOLD = Number(process.env.CONSTRUCT_DOCTOR_BYPASS_WARN) || 3;
+      if (recent.length >= BYPASS_WARN_THRESHOLD) {
+        add(
+          `Pre-push bypasses in last 7 days: ${recent.length} (gate may be wrong-sized — see ${bypassLogPath})`,
+          false,
+          true,
+        );
+      } else {
+        add(`Pre-push bypasses in last 7 days: ${recent.length}`, true);
+      }
+    } catch { /* audit log read is best-effort */ }
+  } else {
+    add('Pre-push bypass log not present (no bypasses honored yet)', true);
+  }
+
+  // Embed daemon log size. The daemon's own scheduler rotates every
+  // minute at 50MB, but a freshly-upgraded install with a 34GB legacy
+  // log shouldn't wait 60s. --fix-embed-log forces rotation now.
+
+  const embedLogPath = path.join(userHome, '.cx', 'runtime', 'embed-daemon.log');
+  if (fs.existsSync(embedLogPath)) {
+    const sizeMb = fs.statSync(embedLogPath).size / 1024 / 1024;
+    const FORCE_THRESHOLD_MB = Number(process.env.CONSTRUCT_DOCTOR_EMBED_LOG_FORCE_MB) || 500;
+    if (sizeMb > FORCE_THRESHOLD_MB && wantsFixEmbedLog) {
+      const { rotateIfOversized } = await import('../lib/logging/rotate.mjs');
+      println(`  fix: rotating ${sizeMb.toFixed(0)}MB embed-daemon.log (gzipping may take a moment)…`);
+      const start = Date.now();
+      const seg = await rotateIfOversized(embedLogPath, { maxBytes: 1, maxSegments: 5, gzip: true });
+      const elapsed = ((Date.now() - start) / 1000).toFixed(0);
+      println(`  fix: rotated to ${path.basename(seg)} in ${elapsed}s`);
+      add('Embed daemon log size sane', true);
+    } else {
+      const label = sizeMb > FORCE_THRESHOLD_MB
+        ? `Embed daemon log oversized: ${sizeMb.toFixed(0)}MB (run \`construct doctor --fix-embed-log\` to rotate now)`
+        : `Embed daemon log size: ${sizeMb.toFixed(1)}MB`;
+      add(label, sizeMb <= FORCE_THRESHOLD_MB);
+    }
+  }
+
+  // Legacy ~/.cx/<project-scoped>.jsonl files left over from before the
+  // cross-project state isolation refactor. Four files moved from user
+  // scope to <project>/.cx/: contract-violations, audit-reads, agent-log,
+  // intent-verifications. Pre-refactor data still sits at ~/.cx/ where it
+  // mixed every project together. --fix-migrate-state archives them to
+  // ~/.cx/legacy/<name>.<ts>.jsonl so the new writers start fresh; the
+  // legacy data stays readable for forensics.
+
+  const projectScopedNames = [
+    'contract-violations.jsonl',
+    'audit-reads.jsonl',
+    'agent-log.jsonl',
+    'intent-verifications.jsonl',
+  ];
+  const legacyState = projectScopedNames
+    .map((name) => ({ name, path: path.join(userHome, '.cx', name) }))
+    .filter((p) => fs.existsSync(p.path) && fs.statSync(p.path).size > 0);
+
+  if (legacyState.length > 0 && wantsFixMigrateState) {
+    const archiveDir = path.join(userHome, '.cx', 'legacy');
+    fs.mkdirSync(archiveDir, { recursive: true });
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const moved = [];
+    for (const { name, path: src } of legacyState) {
+      const dest = path.join(archiveDir, `${name.replace('.jsonl', '')}.${ts}.jsonl`);
+      fs.renameSync(src, dest);
+      moved.push(path.basename(dest));
+    }
+    println(`  fix: archived ${moved.length} legacy user-scope file(s) to ~/.cx/legacy/`);
+    for (const m of moved) println(`         → ${m}`);
+    add('No legacy user-scope project-state files', true);
+  } else {
+    add(
+      legacyState.length === 0
+        ? 'No legacy user-scope project-state files'
+        : `Legacy user-scope project-state files: ${legacyState.length} (run \`construct doctor --fix-migrate-state\` to archive)`,
+      legacyState.length === 0,
+    );
+  }
+
   // Tier model selection. Construct ships with no default — at least
   // one tier must be configured (registry.json primary OR CX_MODEL_*
   // env override) before any LLM-backed workflow can run.
@@ -704,7 +883,11 @@ async function cmdDoctor() {
     try {
       const { checkParity } = await import('../lib/parity.mjs');
       const parity = checkParity({ rootDir: ROOT_DIR, homeDir: HOME });
-      add(`Cross-surface adapter parity (${parity.summary.join(' · ')})`, parity.ok);
+      // Legacy-install rolls up to ok (so the gate doesn't hard-fail during
+      // a v1.0.10 → v1.0.13+ upgrade) but renders as a warning so the
+      // --fix-legacy-agents hint stays visible.
+      const hasLegacy = parity.surfaces.some((s) => s.status === 'legacy-install');
+      add(`Cross-surface adapter parity (${parity.summary.join(' · ')})`, parity.ok, hasLegacy);
     } catch {
       add('Cross-surface adapter parity', false);
     }
@@ -1643,6 +1826,10 @@ async function printIntakeHelp() {
   println('  construct intake done <id> [--notes=…] [--output=<path>] [--no-output=<rejected|deferred|merged>]');
   println('                                       Mark a pending packet processed. --output stamps intake_id + confidence into the artifact frontmatter (provenance).');
   println('  construct intake skip <id> [--reason=…]   Mark a pending packet skipped (preserves audit trail).');
+  println('  construct intake process [--dry-run] [--wait[=<sec>]]');
+  println('                                       One-shot inbox sweep — same logic the daemon runs, exits when the queue is empty.');
+  println('                                       Concurrency is controlled by a poll lock — fail-fast by default, --wait[=<sec>] blocks for up to N seconds.');
+  println('                                       --dry-run lists candidate inboxes without ingesting.');
   println('  construct intake reopen <id>         Move a processed or skipped packet back to pending.');
   println('  construct intake quarantine list             List packets held for human review (low confidence or close margin).');
   println('  construct intake quarantine show <id>        Show a quarantined packet with top-3 candidate types and margins.');
@@ -1910,6 +2097,10 @@ async function cmdIntake(args) {
     return await cmdIntakeIntegrate(id, args.slice(2), cwd);
   }
 
+  if (sub === 'process') {
+    return await cmdIntakeProcess(args.slice(1), cwd);
+  }
+
   if (sub === 'config') {
     return await cmdIntakeConfig(args.slice(1));
   }
@@ -1922,10 +2113,75 @@ async function cmdIntake(args) {
     return await cmdIntakeNeedsAsr(args.slice(1));
   }
 
-  errorln(`Unknown intake subcommand: ${sub}. Available: list, show, done, skip, reopen, quarantine, reroute, integrate, config, extraction-warnings, needs-asr`);
+  errorln(`Unknown intake subcommand: ${sub}. Available: list, show, done, skip, reopen, process, quarantine, reroute, integrate, config, extraction-warnings, needs-asr`);
   process.exit(1);
 }
 
+async function cmdIntakeProcess(args, cwd) {
+  const dryRun = args.includes('--dry-run');
+  const waitFlag = args.find((a) => a === '--wait' || a.startsWith('--wait='));
+  const { InboxWatcher, resolveInboxDirs } = await import('../lib/embed/inbox.mjs');
+
+  if (dryRun) {
+    const dirs = resolveInboxDirs(cwd, process.env);
+    if (dirs.length === 0) {
+      println('No inbox directories configured. Run `construct intake config` to add one.');
+      return;
+    }
+    println('Would scan:');
+    for (const d of dirs) println(`  ${d}`);
+    println('');
+    println('(dry-run — no files processed; re-run without --dry-run to actually ingest.)');
+    return;
+  }
+
+  // Concurrency is controlled by the intake poll lock inside
+  // InboxWatcher.poll. Default behavior is fail-fast: if the daemon (or
+  // another CLI invocation) is mid-poll, raise an actionable error rather
+  // than serializing silently. --wait[=<seconds>] opts into blocking for
+  // up to N seconds (default 30s when --wait is bare).
+
+  let waitMs = 0;
+  if (waitFlag) {
+    const m = /^--wait(?:=(\d+))?$/.exec(waitFlag);
+    const seconds = m && m[1] ? Number(m[1]) : 30;
+    waitMs = Math.max(0, seconds) * 1000;
+  }
+
+  const watcher = new InboxWatcher({ rootDir: cwd, env: process.env, cwd });
+  let result;
+  try {
+    result = await watcher.poll({ waitMs, actor: 'construct intake process' });
+  } catch (err) {
+    const { POLL_LOCK_BUSY } = await import('../lib/intake/poll-lock.mjs');
+    if (err && err.code === POLL_LOCK_BUSY) {
+      const holder = err.holder || {};
+      errorln('Another intake poll is in progress.');
+      errorln(`  holder: ${holder.actor || 'unknown'} (pid ${holder.pid})`);
+      errorln(`  started: ${holder.startedAt || 'unknown'}`);
+      errorln('');
+      errorln('Choose one:');
+      errorln('  construct intake process --wait        Block until the holder finishes (default 30s).');
+      errorln('  construct intake process --wait=<sec>  Block for a custom window.');
+      errorln('  construct down                          Stop background services, then retry.');
+      process.exit(2);
+    }
+    throw err;
+  }
+
+  println(`Processed: ${result.processed.length}`);
+  println(`Skipped (unchanged): ${result.skipped}`);
+  if (result.errors.length) {
+    println(`Errors: ${result.errors.length}`);
+    for (const e of result.errors) println(`  ${e.path}: ${e.error}`);
+  }
+  for (const item of result.processed) {
+    const note = item.needsAsr ? ' (queued for ASR)' : '';
+    println(`  + ${item.path}${note}`);
+  }
+  if (result.errors.length) process.exitCode = 1;
+}
+
 async function cmdIntakeQuarantine(args, cwd) {
   const action = args[0];
   const { listQuarantine, readQuarantine } = await import('../lib/intake/quarantine.mjs');
@@ -4584,14 +4840,6 @@ const handlers = new Map([
       process.exit(1);
     }
   }],
-  ['policy:list', async (args) => {
-    const { listPolicies, formatPolicyList } = await import('../lib/policy/unified-gates.mjs');
-    if (args.includes('--json')) {
-      println(JSON.stringify(listPolicies(), null, 2));
-    } else {
-      process.stdout.write(formatPolicyList());
-    }
-  }],
   ['policy', async (args) => {
     const sub = args[0];
     if (!sub || sub === '--help' || sub === '-h') {
@@ -4602,7 +4850,7 @@ const handlers = new Map([
     if (sub === 'show') {
       const { readFileSync, existsSync } = await import('node:fs');
       const { join } = await import('node:path');
-      const inventoryPath = join(ROOT_DIR, 'agents', 'policy-inventory.json');
+      const inventoryPath = join(ROOT_DIR, 'specialists', 'policy-inventory.json');
       if (!existsSync(inventoryPath)) {
         errorln('specialists/policy-inventory.json not found');
         process.exit(1);

package/bin/construct-postinstall.mjs

@@ -58,8 +58,29 @@ try {
   }
 } catch { /* fall through */ }
 
-// Require a package.json at the install target so monorepo nested installs
-// don't accidentally trigger staging in the wrong directory.
+// `npm i -g @geraldmaron/construct` runs the postinstall with
+// npm_config_global=true. Wire the `construct` front-door agent into the
+// user's home directories so it's reachable from every host (Claude Code,
+// Codex, Copilot, OpenCode) immediately after a global install. Specialists
+// stay project-only and land when the user runs `construct init` in a repo.
+
+if (process.env.npm_config_global === 'true' || process.env.npm_config_global === true) {
+  const syncScript = path.join(PKG_ROOT, 'scripts', 'sync-specialists.mjs');
+  if (existsSync(syncScript)) {
+    log('global install detected; syncing front-door agent into ~/');
+    const result = spawnSync(process.execPath, [syncScript, '--global'], {
+      stdio: 'inherit',
+    });
+    if (result.status !== 0) {
+      log(`global sync failed (exit ${result.status}); run \`construct sync --global\` manually`);
+    }
+  }
+  process.exit(0);
+}
+
+// Project install path: require a package.json at the install target so
+// monorepo nested installs don't accidentally trigger staging in the wrong
+// directory.
 
 const consumerPkgPath = path.join(initCwd, 'package.json');
 if (!existsSync(consumerPkgPath)) {

package/lib/auto-docs.mjs

@@ -1,5 +1,5 @@
 /**
- * lib/auto-docs.mjs — regenerate managed regions in markdown docs and build the MkDocs site tree.
+ * lib/auto-docs.mjs — regenerate managed regions in markdown docs and generated docs-site references.
  *
  * Managed regions are HTML comment markers in the form:
  *   <!-- AUTO:region-name -->
@@ -9,8 +9,9 @@
  * Running regenerateDocs() is idempotent. With check:true it returns whether
  * anything would change without writing files — the mode CI uses to detect drift.
  *
- * buildSite() writes site/docs/ from the same sources feeding the AUTO regions
- * so the GitHub Pages site never drifts from the in-repo markdown.
+ * buildSite() is retained for compatibility; the public site now renders docs/
+ * directly through Next.js (apps/docs/) and buildFumadocsReference() emits
+ * generated reference Markdown into docs/reference/.
  */
 
 import fs from 'node:fs';
@@ -82,7 +83,7 @@ function buildCoreDocsContract() {
 
 const DIR_DESCRIPTIONS = {
   agents: 'Registry and generated platform adapter chains',
-  apps: 'User-facing apps shipped from this repo (e.g. apps/docs/, the Fumadocs docs site)',
+  apps: 'User-facing apps shipped from this repo (e.g. apps/docs/, the Next.js docs site)',
   bin: 'CLI entrypoint (`construct`)',
   claude: 'Claude Code integration (agents, settings template)',
   commands: 'Command prompt assets',
@@ -93,7 +94,7 @@ const DIR_DESCRIPTIONS = {
   opencode: 'OpenCode integration config',
   personas: 'Persona prompt definitions',
   rules: 'Coding and quality standards',
-  site: 'MkDocs source for the GitHub Pages documentation site',
+  site: 'Legacy docs-site output',
   skills: 'Reusable domain knowledge files',
   tests: 'Test suite',
 };
@@ -151,7 +152,7 @@ function buildHooksTable(rootDir) {
 }
 
 function buildAgentsTable(rootDir) {
-  const registryPath = path.join(rootDir, 'agents', 'registry.json');
+  const registryPath = path.join(rootDir, 'specialists', 'registry.json');
   let registry;
   try { registry = JSON.parse(fs.readFileSync(registryPath, 'utf8')); } catch { return ''; }
 
@@ -237,12 +238,12 @@ export async function regenerateDocs({ rootDir, check = false } = {}) {
  * Check CLI command coverage against how-to links in docs/README.md.
  *
  * Returns an object with:
- *   - covered: string[]    commands that have a linked how-to
- *   - uncovered: string[]  commands with no how-to link in docs/README.md
+ *   - covered: string[]    commands that have a linked guide
+ *   - uncovered: string[]  commands with no linked guide in docs/README.md
  *   - total: number
  *
- * A command is considered covered if its name appears in any markdown link
- * inside the how-to guides section of docs/README.md.
+ * A command is considered covered if its name appears in docs/README.md or in
+ * a linked cookbook/how-to guide.
  */
 export function checkDocsCoverage({ rootDir } = {}) {
   rootDir = rootDir ?? process.cwd();
@@ -251,11 +252,10 @@ export function checkDocsCoverage({ rootDir } = {}) {
   // Extract all href targets from markdown links in docs/README.md
   const linkTargets = [...docsReadme.matchAll(/\[.*?\]\((.*?)\)/g)].map(m => m[1]);
 
-  // Build a combined corpus: docs/README.md + every linked how-to file
-  const howToDir = path.join(rootDir, 'docs', 'how-to');
+  // Build a combined corpus: docs/README.md + every linked guide file
   let corpus = docsReadme;
   for (const target of linkTargets) {
-    if (!target.startsWith('./how-to/')) continue;
+    if (!target.startsWith('./how-to/') && !target.startsWith('./cookbook/')) continue;
     const filePath = path.join(rootDir, 'docs', target.replace(/^\.\//, ''));
     const content = readFile(filePath);
     if (content) corpus += '\n' + content;
@@ -304,18 +304,16 @@ export function checkDocsCoverage({ rootDir } = {}) {
   return { covered, uncovered, total: covered.length + uncovered.length };
 }
 
-// Categories surfaced in the Fumadocs reference. Internal commands (e.g.,
+// Categories surfaced in the generated CLI reference. Internal commands (e.g.,
 // `construct hook <name>`) are not user-facing reference material.
 const REFERENCE_CATEGORIES = [
-  'Services',
-  'Agents & Sync',
+  'Core',
   'Work',
-  'Embed',
   'Models & Integrations',
-  'Providers',
+  'Integrations',
   'Observability',
-  'Docs',
   'Diagnostics',
+  'Advanced',
 ];
 
 function slugify(category) {
@@ -410,9 +408,12 @@ function renderAgentsPage(rootDir) {
 }
 
 /**
- * Emit MDX reference pages into docs/reference/ for the Fumadocs site.
- * Mirrors the data sources behind AUTO regions and buildSite() but writes
- * Markdown files Fumadocs can render directly (no MkDocs intermediate).
+ * Emit MDX reference pages into docs/reference/ for the Next.js docs site
+ * in apps/docs/. Mirrors the data sources behind AUTO regions and buildSite()
+ * but writes Markdown files the docs app can pull in directly (no MkDocs
+ * intermediate). Name kept for backwards compatibility with callers that
+ * still import buildFumadocsReference; the rendering layer is now plain
+ * Next.js + @next/mdx.
  */
 export function buildFumadocsReference({ rootDir } = {}) {
   rootDir = rootDir ?? process.cwd();

package/lib/cli-commands.mjs

@@ -749,8 +749,10 @@ for (const cat of Object.keys(CLI_COMMANDS_BY_CATEGORY)) {
 export const CATEGORY_ORDER = [
   'Core',
   'Work',
+  'Models & Integrations',
   'Integrations',
   'Observability',
+  'Diagnostics',
   'Advanced',
 ];