@geraldmaron/construct 1.0.16 → 1.0.18

package/README.md

@@ -32,9 +32,11 @@ Initialize a project:
 
 ```bash
 cd ~/your-project
-construct init --auto-start
+construct init --yes
 ```
 
+`construct init` scaffolds the project (`.cx/`, `AGENTS.md`, `plan.md`, adapters) and starts the local services by default. Pass `--no-start` to skip service startup, or `--interactive` for the guided flow.
+
 Open your editor and talk to `@construct`. A walkthrough lives in `construct_guide.md` at your project root.
 
 No Node? Try `brew install geraldmaron/construct/construct`. Cloning a project that already uses Construct? `npx -y @geraldmaron/construct init` wires it up.
@@ -155,6 +157,7 @@ The embed daemon writes its supervisor stdout log to `~/.cx/runtime/embed-daemon
 
 | Command | What it does |
 |---|---|
+| `construct capability` | Describe what this Construct install can do (embedded contract; read-only, secret-free) |
 | `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 |

package/bin/construct

@@ -165,12 +165,14 @@ async function showInteractiveMenu() {
   }
 }
 
-function runNodeScript(scriptPath, args = [], extraEnv = {}) {
+function runNodeScript(scriptPath, args = [], extraEnv = {}, { exitOnError = true } = {}) {
   const result = spawnSync(process.execPath, [scriptPath, ...args], {
     stdio: 'inherit',
     env: { ...process.env, ...extraEnv },
   });
-  if (result.status !== 0) process.exit(result.status ?? 1);
+  const status = result.status ?? 1;
+  if (status !== 0 && exitOnError) process.exit(status);
+  return status;
 }
 
 async function cmdStatus() {
@@ -238,12 +240,24 @@ async function cmdShow() {
 }
 
 async function cmdSync(args) {
+  const { startOpLog } = await import('../lib/op-log.mjs');
+  const opLog = startOpLog('sync', { homeDir: HOME });
+  opLog.event('args', { args });
+
   generateCompletions();
-  runNodeScript(path.join(ROOT_DIR, 'scripts', 'sync-specialists.mjs'), args);
-  if (args.includes('--no-docs')) return;
+  const syncStatus = runNodeScript(path.join(ROOT_DIR, 'scripts', 'sync-specialists.mjs'), args, {}, { exitOnError: false });
+  if (syncStatus !== 0) {
+    opLog.close('failed', { stage: 'sync-specialists', status: syncStatus });
+    process.exit(syncStatus);
+  }
+  if (args.includes('--no-docs')) {
+    opLog.close('ok', { docs: 'skipped' });
+    return;
+  }
   const { regenerateDocs } = await import('../lib/auto-docs.mjs');
   const { changed } = await regenerateDocs({ rootDir: ROOT_DIR });
   for (const f of changed) ok(`Updated ${path.relative(ROOT_DIR, f)}`);
+  opLog.close('ok', { docsChanged: changed.length });
 }
 
 async function cmdCompletions(args) {
@@ -498,9 +512,9 @@ async function cmdDoctor() {
 
   // (Pre-push bypass doctor check removed in v1.0.16.) v1.0.15 deleted the
   // entire skip-var infrastructure (CONSTRUCT_SKIP_PREPUSH, _COMMENT_LINT,
-  // _PR_LINT, _DOCS, CONSTRUCT_ALLOW_CLAUDE_PUSH). There is no longer any
-  // writer to ~/.construct/audit/prepush-bypass.log, so any historical
-  // entries are stale and the warning surfaced forever. The file itself
+  // _PR_LINT, _DOCS, CONSTRUCT_ALLOW_CLAUDE_PUSH). Nothing writes to
+  // ~/.construct/audit/prepush-bypass.log, so any entries there are stale
+  // and would otherwise surface the warning indefinitely. The file itself
   // is harmless — next cleanup tick may sweep it.
 
   // Embed daemon log size. The daemon's own scheduler rotates every
@@ -1071,15 +1085,77 @@ async function cmdDoctor() {
   if (failCount > 0) process.exit(1);
 }
 
-async function cmdUp() {
+// Resolve which services `construct dev` should start. Returns null (start
+// everything) unless --only= or --select narrows it. Unknown --only keys fail
+// loud rather than silently starting the wrong set; --select on a non-TTY is an
+// error pointing at --only so scripts get a deterministic path.
+async function resolveServiceSelection(args, selectable) {
+  const validKeys = new Set(selectable.map((s) => s.key));
+  const onlyArg = args.find((a) => a.startsWith('--only='));
+
+  if (onlyArg) {
+    const keys = onlyArg.slice('--only='.length).split(',').map((k) => k.trim()).filter(Boolean);
+    const unknown = keys.filter((k) => !validKeys.has(k));
+    if (unknown.length) {
+      errorln(`Unknown service(s) for --only: ${unknown.join(', ')}`);
+      errorln(`Valid services: ${[...validKeys].join(', ')}`);
+      process.exit(1);
+    }
+    if (keys.length === 0) {
+      errorln('--only requires at least one service.');
+      process.exit(1);
+    }
+    return new Set(keys);
+  }
+
+  if (args.includes('--select')) {
+    if (!process.stdin.isTTY) {
+      errorln('--select needs an interactive terminal. Use --only=<a,b,c> in scripts.');
+      errorln(`Valid services: ${[...validKeys].join(', ')}`);
+      process.exit(1);
+    }
+    const { multiSelect } = await import('../lib/tty-prompts.mjs');
+    try {
+      const chosen = await multiSelect({
+        title: 'Start which services?',
+        instructions: 'Pressure Guard and Doctor always run. Space toggles, Enter confirms.',
+        options: selectable.map((s) => ({ label: s.label, value: s.key, description: s.description, checked: true })),
+      });
+      if (!chosen.length) {
+        errorln('No services selected — nothing to start.');
+        process.exit(1);
+      }
+      return new Set(chosen);
+    } catch {
+      errorln('Service selection canceled.');
+      process.exit(1);
+    }
+  }
+
+  return null;
+}
+
+async function cmdUp(args = []) {
+  const { SELECTABLE_SERVICES } = await import('../lib/service-manager.mjs');
+
+  // --only=a,b,c picks services non-interactively; --select opens a checklist.
+  // Both resolve to a Set of service keys (null = start everything).
+
+  const selected = await resolveServiceSelection(args, SELECTABLE_SERVICES);
+
+  const { startOpLog } = await import('../lib/op-log.mjs');
+  const opLog = startOpLog('dev', { homeDir: HOME });
+  opLog.event('selection', { services: selected ? [...selected] : 'all' });
+
   // Auto-magic health check — catch missing prerequisites before starting services
   const { quickHealthCheck, detectCredentials, resolveCredentials } = await import('../lib/health-check.mjs');
-  
+
   // Resolve credentials from env, .env files, and 1Password before starting services
   const resolvedCreds = await resolveCredentials({ homeDir: HOME });
-  
+
   const health = await quickHealthCheck({ homeDir: HOME, showCredentials: true });
-  
+  opLog.event('prereq', { ok: health.ok, missing: health.missing ?? [] });
+
   if (!health.ok) {
     errorln('Prerequisites missing for starting services:');
     for (const item of health.missing) {
@@ -1087,10 +1163,12 @@ async function cmdUp() {
     }
     println('');
     info('Run `construct install --yes` to install missing dependencies.');
+    opLog.close('failed', { reason: 'prerequisites-missing' });
     process.exit(1);
   }
-  
-  const { results, recovery } = await startServices({ rootDir: ROOT_DIR, homeDir: HOME });
+
+  const { results, recovery } = await startServices({ rootDir: ROOT_DIR, homeDir: HOME, selected });
+  opLog.event('services', { results: results.map((r) => ({ name: r.name, status: r.status })) });
   for (const svc of results) {
     const label = svc.url ? `${svc.name} → ${svc.url}` : svc.name;
     if (svc.status === 'started') ok(svc.note ? `${label} (${svc.note})` : label);
@@ -1128,8 +1206,10 @@ async function cmdUp() {
     try {
       const { runEmbedCli } = await import('../lib/embed/cli.mjs');
       await runEmbedCli(['start'], { rootDir: ROOT_DIR });
+      opLog.event('embed', { status: 'started' });
     } catch (err) {
       warn(`embed start failed: ${err.message} — check ~/.cx/runtime/embed-daemon.log`);
+      opLog.warn('embed', { status: 'failed', error: err.message });
     }
   }
 
@@ -1176,6 +1256,9 @@ async function cmdUp() {
   println('Dashboard: http://127.0.0.1:4242');
   println('Run \x1b[32mconstruct\x1b[0m for commands');
   println('');
+
+  const failed = results.filter((r) => r.status === 'error' || r.status === 'failed');
+  opLog.close(failed.length ? 'degraded' : 'ok', { failed: failed.map((r) => r.name) });
 }
 
 async function cmdDown() {
@@ -1304,7 +1387,14 @@ async function cmdReview(args) {
   process.exit(1);
 }
 
-async function cmdInit(args) { runNodeScript(path.join(ROOT_DIR, 'lib', 'init-unified.mjs'), args); }
+async function cmdInit(args) {
+  const { startOpLog } = await import('../lib/op-log.mjs');
+  const opLog = startOpLog('init', { homeDir: HOME });
+  opLog.event('args', { args });
+  const status = runNodeScript(path.join(ROOT_DIR, 'lib', 'init-unified.mjs'), args, {}, { exitOnError: false });
+  opLog.close(status === 0 ? 'ok' : 'failed', { status });
+  if (status !== 0) process.exit(status);
+}
 async function cmdDocsVerify(args) { runNodeScript(path.join(ROOT_DIR, 'lib', 'docs-verify.mjs'), args); }
 async function cmdInitUpdate(args) { 
   runNodeScript(path.join(ROOT_DIR, 'lib', 'init-update.mjs'), args);
@@ -1747,7 +1837,22 @@ async function cmdHosts() {
     printHostCapabilities();
   }
 }
-async function cmdSetup(args) { await runSetup({ rootDir: ROOT_DIR, args, homeDir: HOME }); }
+async function cmdSetup(args) {
+  const { startOpLog } = await import('../lib/op-log.mjs');
+  const opLog = startOpLog('install', { homeDir: HOME });
+  opLog.event('args', { args });
+  try {
+    await runSetup({ rootDir: ROOT_DIR, args, homeDir: HOME });
+    opLog.close('ok');
+  } catch (err) {
+    opLog.error('setup', { error: err.message });
+    opLog.close('failed');
+    errorln(`\nSetup did not complete: ${err.message}`);
+    errorln('  -> Diagnose with: construct doctor');
+    errorln('  -> Re-run setup:  construct install   (add --reconfigure to re-prompt for services)');
+    process.exit(1);
+  }
+}
 
 function printConfigModeHelp() {
   println('Construct config — inspect and set deployment posture.');
@@ -1841,6 +1946,45 @@ function formatIntakeTable(rows, { intakeQueueLabel, signalNoun } = { intakeQueu
   for (const row of rows) println(fmt(row));
 }
 
+// Embedded triage/planning surface — classifies an artifact and returns a
+// role-aware plan with no enqueue and no durable write. Shared by
+// `intake classify` and `graph recommend`. Input comes from --text, --file, or
+// stdin; --no-enqueue is accepted for explicitness (this path never enqueues).
+
+async function cmdEmbeddedTriage(args) {
+  const flag = (name) => { const i = args.indexOf(name); return i !== -1 ? args[i + 1] : undefined; };
+  const fileArg = flag('--file');
+  let input = flag('--text') || '';
+  let ingestion = null;
+  if (!input && fileArg) {
+    const { resolveInput } = await import('../lib/embedded-contract/ingest.mjs');
+    const resolved = await resolveInput({ filePath: fileArg });
+    input = resolved.text;
+    ingestion = resolved.error ? { ...(resolved.ingestion || {}), error: resolved.error } : resolved.ingestion;
+  }
+  if (!input && !process.stdin.isTTY) {
+    input = fs.readFileSync(0, 'utf8');
+  }
+  if (!input.trim() && !ingestion?.error) {
+    errorln('Usage: construct intake classify --json [--text "..." | --file <path> | <stdin>] [--source <path>] [--artifact-type <t>] [--available-roles a,b]');
+    process.exit(1);
+  }
+  const request = {
+    input,
+    sourcePath: flag('--source') || (fileArg || ''),
+    ingestion,
+    artifactType: flag('--artifact-type'),
+    domain: flag('--domain'),
+    desiredOutcome: flag('--desired-outcome'),
+    constraints: flag('--constraints')?.split(',').map((s) => s.trim()).filter(Boolean),
+    availableRoles: flag('--available-roles')?.split(',').map((s) => s.trim()).filter(Boolean),
+  };
+  const { recommendPlan } = await import('../lib/embedded-contract/triage.mjs');
+  const { wrapContractResult } = await import('../lib/embedded-contract/envelope.mjs');
+  const envelope = wrapContractResult(recommendPlan(request), { surface: 'cli' });
+  println(JSON.stringify(envelope, null, 2));
+}
+
 async function cmdIntake(args) {
   const sub = args[0];
 
@@ -1849,6 +1993,10 @@ async function cmdIntake(args) {
     return;
   }
 
+  if (sub === 'classify') {
+    return await cmdEmbeddedTriage(args.slice(1));
+  }
+
   const { createIntakeQueue } = await import('../lib/intake/queue.mjs');
   const { getRebrand } = await import('../lib/profiles/rebrand.mjs');
   const cwd = process.cwd();
@@ -2941,6 +3089,10 @@ async function cmdGraph(args) {
   const sub = args[0];
   if (!sub || sub === '--help' || sub === '-h') { printGraphHelp(); return; }
 
+  if (sub === 'recommend') {
+    return await cmdEmbeddedTriage(args.slice(1));
+  }
+
   const { FilesystemTaskGraphStore } = await import('../lib/task-graph/store.mjs');
   const { generateTaskGraphFromTriage } = await import('../lib/task-graph/generate.mjs');
   const cwd = process.cwd();
@@ -3174,6 +3326,23 @@ async function cmdValidate() {
 }
 
 async function cmdModels(args) {
+  if (args[0] === 'resolve') {
+    const flag = (name) => { const i = args.indexOf(name); return i !== -1 ? args[i + 1] : undefined; };
+    const { resolveEmbeddedModel } = await import('../lib/embedded-contract/model-resolve.mjs');
+    const { wrapContractResult } = await import('../lib/embedded-contract/envelope.mjs');
+    const request = {
+      workflowType: flag('--workflow-type'),
+      requestedTier: flag('--tier'),
+      host: flag('--host'),
+      hostModel: flag('--host-model'),
+      hostProvider: flag('--host-provider'),
+      capabilities: flag('--capabilities')?.split(',').map((s) => s.trim()).filter(Boolean),
+      allowCrossProviderFallback: args.includes('--allow-cross-provider'),
+    };
+    const envelope = wrapContractResult(resolveEmbeddedModel(request), { surface: 'cli' });
+    println(JSON.stringify(envelope, null, 2));
+    return;
+  }
   const tier = args.find((arg) => arg.startsWith('--tier='))?.split('=')[1] ?? '';
   const setModel = args.find((arg) => arg.startsWith('--set='))?.split('=')[1] ?? '';
   const envPath = getUserEnvPath(HOME);
@@ -4571,9 +4740,56 @@ async function cmdProviders(args) {
   process.exit(1);
 }
 
+// Capability discovery surface — a read-only, secret-free description of the
+// installed Construct's capabilities, for embedding applications.
+
+async function cmdCapability(args) {
+  const sub = args[0];
+  if (sub && sub !== 'describe' && !sub.startsWith('--')) {
+    errorln(`Unknown capability subcommand: ${sub}. Available: describe`);
+    process.exit(1);
+  }
+  const { buildCapabilityContract } = await import('../lib/embedded-contract/capability.mjs');
+  const { wrapContractResult } = await import('../lib/embedded-contract/envelope.mjs');
+  const envelope = wrapContractResult(buildCapabilityContract({ rootDir: ROOT_DIR }), { surface: 'cli' });
+  println(JSON.stringify(envelope, null, 2));
+}
+
 async function cmdWorkflow(args) {
   const sub = args[0] || 'list';
 
+  if (sub === 'invoke') {
+    const rest = args.slice(1);
+    const flag = (name) => { const i = rest.indexOf(name); return i !== -1 ? rest[i + 1] : undefined; };
+    let input = flag('--text') || '';
+    const fileArg = flag('--file');
+    let ingestion = null;
+    if (!input && fileArg) {
+      const { resolveInput } = await import('../lib/embedded-contract/ingest.mjs');
+      const resolved = await resolveInput({ filePath: fileArg });
+      input = resolved.text;
+      ingestion = resolved.error ? { ...(resolved.ingestion || {}), error: resolved.error } : resolved.ingestion;
+    }
+    if (!input && !process.stdin.isTTY) input = fs.readFileSync(0, 'utf8');
+    const request = {
+      workflowType: flag('--workflow-type'),
+      input,
+      ingestion,
+      roleStrategy: flag('--role-strategy'),
+      requestedRoles: flag('--roles')?.split(',').map((s) => s.trim()).filter(Boolean),
+      approvalMode: flag('--approval-mode'),
+      trace: !rest.includes('--no-trace'),
+      host: flag('--host'),
+      hostModel: flag('--host-model'),
+      hostProvider: flag('--host-provider'),
+    };
+    const { invokeWorkflow } = await import('../lib/embedded-contract/workflow-invoke.mjs');
+    const { wrapContractResult } = await import('../lib/embedded-contract/envelope.mjs');
+    const envelope = wrapContractResult(await invokeWorkflow(request), { surface: 'cli' });
+    println(JSON.stringify(envelope, null, 2));
+    return;
+  }
+
   if (sub === 'list') {
     const { existsSync, readdirSync } = await import('node:fs');
     const { join } = await import('node:path');
@@ -4951,6 +5167,7 @@ const handlers = new Map([
   ['creds', cmdCreds],
   ['providers', cmdProviders],
   ['workflow', cmdWorkflow],
+  ['capability', cmdCapability],
   ['tags', cmdTags],
   ['scheduler', cmdScheduler],
   ['lint:research', cmdLintResearch],
@@ -4994,13 +5211,11 @@ const handlers = new Map([
   ['roles:list', async (args) => {
     const { listRoles, formatRoleList } = await import('../lib/roles/catalog.mjs');
     const json = args.includes('--json');
-    const departments = args.includes('--departments');
-    const consolidated = args.includes('--consolidated');
-    
+
     if (json) {
-      println(JSON.stringify(listRoles({ departments, consolidated }), null, 2));
+      println(JSON.stringify(listRoles(), null, 2));
     } else {
-      process.stdout.write(formatRoleList({ departments, consolidated }));
+      process.stdout.write(formatRoleList());
     }
   }],
   ['roles:set', async (args) => {
@@ -5921,7 +6136,7 @@ if (!handler) {
 // commands like `dev`, `stop`, `init`, `uninstall` silently ignore --help
 // and execute (running `construct stop --help` actually stops services).
 // Every command — including internal ones — gets the same shape via
-// formatCommandHelp(); per-command handlers no longer need to opt in.
+// formatCommandHelp(); per-command handlers need no opt-in.
 
 if (rest.includes('--help') || rest.includes('-h')) {
   process.stdout.write(formatCommandHelp(command, { colors: true }));

package/bin/construct-postinstall.mjs

@@ -34,6 +34,18 @@ const PKG_VERSION = (() => {
 
 const log = (msg) => process.stdout.write(`[construct-postinstall] ${msg}\n`);
 
+// Failures go to stderr as a prominent, actionable block so they are visible in
+// npm output instead of scrolling past as a benign-looking line. The script
+// stays exit-0 by design (see the staging catch): best-effort adapter staging
+// must not hard-fail a consumer's `npm install` — the package is installed and
+// usable, and `construct init` completes staging on demand.
+
+const fail = (msg, hint) => {
+  process.stderr.write(`\n[construct-postinstall] WARNING: ${msg}\n`);
+  if (hint) process.stderr.write(`[construct-postinstall]   -> ${hint}\n`);
+  process.stderr.write('\n');
+};
+
 if (process.env.CONSTRUCT_SKIP_POSTINSTALL === '1') {
   log('skipping (CONSTRUCT_SKIP_POSTINSTALL=1)');
   process.exit(0);
@@ -72,7 +84,7 @@ if (process.env.npm_config_global === 'true' || process.env.npm_config_global ==
       stdio: 'inherit',
     });
     if (result.status !== 0) {
-      log(`global sync failed (exit ${result.status}); run \`construct sync --global\` manually`);
+      fail(`Global front-door sync failed (exit ${result.status}).`, 'Run `construct sync --global` to complete it.');
     }
   }
   process.exit(0);
@@ -103,6 +115,9 @@ try {
     log,
   });
 } catch (err) {
-  log(`staging failed: ${err.message}; leaving project in a clean state`);
+  fail(`Adapter staging failed: ${err.message}`, 'The package is installed; run `npx construct init` in this project to complete setup.');
+  // Intentionally exit 0: staging is best-effort completion, and a non-zero exit
+  // here would fail the consumer's entire `npm install`. The failure is loud on
+  // stderr above and recoverable via `construct init`.
   process.exit(0);
 }

package/commands/design/flow.md

@@ -8,3 +8,5 @@ Produce:
 - JOBS-TO-BE-DONE: "When [situation], I want to [motivation], so I can [outcome]."
 - FRICTION MAP: 5 likely points where users get stuck, confused, or quit
 - DESIGN-DRIVING QUESTIONS: a small set of questions (typically 3-7) whose answers would change layout, flow, or interaction decisions
+
+To capture the flow as a committed artifact, run `construct wireframe "<flow description>" --type=flow` (or `--type=user-journey` for a persona funnel) to emit a diffable Mermaid diagram under `.cx/wireframes/`. Stay text-first (no new diagramming dependency).

package/commands/design/ui.md

@@ -10,3 +10,5 @@ Every meaningful UI surface needs:
 - WCAG AA baseline: keyboard-navigable, 4.5:1 contrast, visible focus, ARIA labels
 
 Does it look intentional, or like a default template? Flag experience drift.
+
+For a layout sketch, run `construct wireframe "<screen description>" --type=layout` to produce a committed low-fi HTML/Mermaid artifact under `.cx/wireframes/`, then refine it. Stay text-first (no new diagramming dependency). Valid `--type` values: layout, flow, state, sequence, er, user-journey.

package/lib/cli-commands.mjs

@@ -20,7 +20,11 @@ export const CLI_COMMANDS = [
     category: 'Core',
     core: true,
     description: 'Start services for development',
-    usage: 'construct dev',
+    usage: 'construct dev [--select] [--only=postgres,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)' },
+    ],
   },
   {
     name: 'stop',
@@ -47,10 +51,11 @@ export const CLI_COMMANDS = [
     category: 'Core',
     core: true,
     description: 'Machine setup (once per machine): Docker, cm/cass, config, embeddings',
-    usage: 'construct install [--yes] [--no-docker]',
+    usage: 'construct install [--yes] [--no-docker] [--reconfigure]',
     options: [
-      { flag: '--yes',       desc: 'Apply defaults without prompts' },
-      { flag: '--no-docker', desc: 'Skip Docker-based service setup (local Postgres)' },
+      { 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' },
     ],
   },
   {
@@ -95,7 +100,16 @@ export const CLI_COMMANDS = [
     category: 'Core',
     core: true,
     description: 'View and process the active profile\'s intake queue (queue label varies by profile)',
-    usage: 'construct intake list|show|done|skip',
+    usage: 'construct intake list|show|done|skip|reopen|integrate|classify',
+    subcommands: [
+      { name: 'list', desc: 'List pending packets' },
+      { name: 'show <id>', desc: 'Show one packet (triage, related docs, excerpt, tag suggestions)' },
+      { name: 'done <id> [--output=<path>]', desc: 'Mark processed; optionally stamp the produced artifact' },
+      { name: 'skip <id> [--reason=…]', desc: 'Drop without action; preserves audit trail' },
+      { name: 'reopen <id>', desc: 'Move a processed or skipped packet back to pending' },
+      { name: 'integrate <id> <github|jira|confluence> [--publish-issues]', desc: 'Create an external ticket from a packet (--publish-issues unlocks the demo-source gate)' },
+      { name: 'classify --json [--text|--file|<stdin>]', desc: 'Classify an artifact and return a role-aware plan without enqueuing (embedded contract)' },
+    ],
   },
   {
     name: 'recommendations',
@@ -207,7 +221,17 @@ export const CLI_COMMANDS = [
     category: 'Core',
     core: true,
     description: 'Check installation health',
-    usage: 'construct doctor [--fix-legacy-agents]',
+    usage: 'construct doctor [<status|logs|tick|report|consistency|watch|stop|credentials>] [--fix-legacy-agents]',
+    subcommands: [
+      { name: 'status', desc: 'Doctor daemon status' },
+      { name: 'logs', desc: 'Tail doctor daemon logs' },
+      { name: 'tick', desc: 'Run one doctor daemon check cycle now' },
+      { name: 'report', desc: 'Print the latest health report' },
+      { name: 'consistency', desc: 'Run cross-surface consistency checks' },
+      { name: 'watch', desc: 'Start the doctor daemon (continuous checks)' },
+      { name: 'stop', desc: 'Stop the doctor daemon' },
+      { name: 'credentials', desc: 'Diagnose provider credential resolution' },
+    ],
     options: [
       { flag: '--fix-legacy-agents', desc: 'Sweep legacy cx-*.md agents at user scope and re-sync' },
     ],
@@ -266,7 +290,10 @@ export const CLI_COMMANDS = [
     category: 'Work',
     core: false,
     description: 'Task graph management',
-    usage: 'construct graph <show|update>',
+    usage: 'construct graph <list|show|from-intake|recommend>',
+    subcommands: [
+      { name: 'recommend --json [--text|--file|<stdin>]', desc: 'Return a role-aware plan for an artifact without enqueuing (embedded contract; alias of intake classify)' },
+    ],
   },
   {
     name: 'models',
@@ -274,7 +301,7 @@ export const CLI_COMMANDS = [
     category: 'Models & Integrations',
     core: false,
     description: 'Show or update model tier assignments',
-    usage: 'construct models <list|set|free|reset|usage|cost>',
+    usage: 'construct models <list|set|free|reset|usage|cost|resolve>',
     subcommands: [
       { name: 'list', desc: 'Show current tier assignments' },
       { name: 'set --tier=<reasoning|standard|fast> --model=<model>', desc: 'Set a model for a tier' },
@@ -282,6 +309,18 @@ export const CLI_COMMANDS = [
       { name: 'reset', desc: 'Reset all tier assignments' },
       { name: 'usage', desc: 'Show token usage per tier' },
       { name: 'cost', desc: 'Show cost breakdown' },
+      { name: 'resolve --json', desc: 'Resolve the model for an embedded workflow given host context' },
+    ],
+  },
+  {
+    name: 'capability',
+    emoji: '🧩',
+    category: 'Models & Integrations',
+    core: false,
+    description: 'Describe what this Construct install can do (embedded contract; read-only, secret-free)',
+    usage: 'construct capability describe --json',
+    subcommands: [
+      { name: 'describe --json', desc: 'Emit versions, interfaces, roles, skills, workflows, schemas, models, policies, telemetry, plugins' },
     ],
   },
   {
@@ -304,7 +343,14 @@ export const CLI_COMMANDS = [
     category: 'Models & Integrations',
     core: false,
     description: 'Manage external Construct plugin manifests',
-    usage: 'construct plugin <list|info|init>',
+    usage: 'construct plugin <list|info|init|validate|engine>',
+    subcommands: [
+      { name: 'list', desc: 'List discovered plugin manifests' },
+      { name: 'info <id>', desc: 'Show details for one plugin' },
+      { name: 'init', desc: 'Scaffold a new plugin manifest' },
+      { name: 'validate', desc: 'Validate a plugin manifest against the schema' },
+      { name: 'engine', desc: 'Plugin engine operations' },
+    ],
   },
   {
     name: 'hosts',
@@ -487,10 +533,13 @@ export const CLI_COMMANDS = [
     category: 'Advanced',
     core: false,
     description: 'Remove Construct state',
-    usage: 'construct uninstall [--yes] [--all]',
+    usage: 'construct uninstall [--dry-run] [--yes] [--all] [--keep-state] [--scope=project|machine|all]',
     options: [
-      { flag: '--yes', desc: 'Remove auto-risk categories without prompting' },
-      { flag: '--all', desc: 'Combined with --yes: also remove ask-risk categories (project data, machine config)' },
+      { flag: '--dry-run',          desc: 'Print the plan and exit; change nothing' },
+      { flag: '--yes',              desc: 'Remove auto-risk (✓) categories without prompting' },
+      { flag: '--all',              desc: 'Combined with --yes: also remove ask-risk (◐) categories (project data, machine config)' },
+      { flag: '--keep-state',       desc: 'Only remove the launcher + adapters; preserve .cx/, ~/.construct, Postgres' },
+      { flag: '--scope=<...>',      desc: 'Limit to project | machine | all (default: all)' },
     ],
   },
   {
@@ -675,7 +724,10 @@ export const CLI_COMMANDS = [
     category: 'Work',
     core: false,
     description: 'Instantiate workflow templates (PRD-to-review chains, onboarding, handoffs)',
-    usage: 'construct workflow <list|show|new>',
+    usage: 'construct workflow <list|show|new|invoke>',
+    subcommands: [
+      { name: 'invoke --json --workflow-type <t> [--text|--file|<stdin>]', desc: 'Invoke a workflow (roles/skills) non-interactively with approval gating and provenance (embedded contract)' },
+    ],
   },
   {
     name: 'telemetry',

package/lib/embed/semantic.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/embed/semantic.mjs — Semantic analysis for intake signals.
  *
- * Generates embeddings via @xenova/transformers, caches them to disk,
+ * Generates embeddings via @huggingface/transformers, caches them to disk,
  * computes cosine similarity, and clusters related signals by topic.
  * All local — no external API calls. Default model is all-MiniLM-L6-v2
  * (384-dimensional vectors, ~50MB on disk, fast inference).
@@ -23,7 +23,7 @@ import { homedir } from 'node:os';
 
 const CACHE_DIR = join(homedir(), '.cx', 'cache', 'embeddings');
 const INDEX_FILE = join(CACHE_DIR, 'index.json');
-const MODEL_NAME = 'all-MiniLM-L6-v2';
+const MODEL_NAME = 'Xenova/all-MiniLM-L6-v2';
 const DIMENSIONS = 384;
 const LOG = process.env.CONSTRUCT_DEBUG_EMBED === '1';
 
@@ -35,7 +35,9 @@ let embedder = null;
 async function getEmbedder() {
   if (embedder !== null) return embedder;
   try {
-    const { pipeline } = await import('@xenova/transformers');
+    const { pipeline, env: hfEnv } = await import('@huggingface/transformers');
+    hfEnv.allowLocalModels = true;
+    hfEnv.useBrowserCache = false;
     embedder = await pipeline('feature-extraction', MODEL_NAME, {
       quantized: true,
     });