@geraldmaron/construct 1.0.15 → 1.0.17

package/lib/cli-commands.mjs

@@ -9,6 +9,7 @@
  * Command Visibility:
  *   - core: true → shown in default --help (90% of users)
  *   - core: false → hidden unless --all flag (advanced/internal commands)
+ *   - internal: true → hidden from --help and --all; callable but not advertised
  */
 
 export const CLI_COMMANDS = [
@@ -19,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',
@@ -45,10 +50,12 @@ export const CLI_COMMANDS = [
     emoji: '🛠️',
     category: 'Core',
     core: true,
-    description: 'Machine setup: install Docker, cm, and bootstrap config',
-    usage: 'construct install [--yes]',
+    description: 'Machine setup (once per machine): Docker, cm/cass, config, embeddings',
+    usage: 'construct install [--yes] [--no-docker] [--reconfigure]',
     options: [
-      { flag: '--yes', desc: 'Apply defaults without prompts' },
+      { 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' },
     ],
   },
   {
@@ -56,7 +63,7 @@ export const CLI_COMMANDS = [
     emoji: '🏗️',
     category: 'Core',
     core: true,
-    description: 'Initialize project and start services',
+    description: 'Project setup (once per repo): scaffold .cx/, AGENTS.md, plan.md, adapters',
     usage: 'construct init [path] [options]',
     options: [
       { flag: '--yes', desc: 'Accept all defaults (non-interactive)' },
@@ -93,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',
@@ -205,17 +221,28 @@ export const CLI_COMMANDS = [
     category: 'Core',
     core: true,
     description: 'Check installation health',
-    usage: 'construct doctor',
+    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' },
+    ],
   },
-  
-  // ── Work (project workflows) ──────────────────────────────────────────
   {
     name: 'distill',
     emoji: '🔬',
     category: 'Work',
     core: false,
     description: 'Distill documents with query-focused chunking',
-    usage: 'construct distill <dir> [--format=summary|decisions|full]',
+    usage: 'construct distill <file>',
   },
   {
     name: 'ingest',
@@ -223,7 +250,7 @@ export const CLI_COMMANDS = [
     category: 'Work',
     core: false,
     description: 'Convert documents to indexed markdown',
-    usage: 'construct ingest <file> [--sync]',
+    usage: 'construct ingest <file> [--strict] [--legacy-extractor]',
   },
   {
     name: 'infer',
@@ -231,7 +258,7 @@ export const CLI_COMMANDS = [
     category: 'Work',
     core: false,
     description: 'Infer schema from documents',
-    usage: 'construct infer <file> [--unified]',
+    usage: 'construct infer <file>',
   },
   {
     name: 'search',
@@ -247,7 +274,7 @@ export const CLI_COMMANDS = [
     category: 'Work',
     core: false,
     description: 'Manage storage backend',
-    usage: 'construct storage sync|status|reset',
+    usage: 'construct storage <status|reset>',
   },
   {
     name: 'headhunt',
@@ -255,7 +282,7 @@ export const CLI_COMMANDS = [
     category: 'Work',
     core: false,
     description: 'Create domain expertise overlays',
-    usage: 'construct headhunt <domain>',
+    usage: 'construct headhunt <create|list>',
   },
   {
     name: 'graph',
@@ -263,229 +290,202 @@ export const CLI_COMMANDS = [
     category: 'Work',
     core: false,
     description: 'Task graph management',
-    usage: 'construct graph list|show|from-intake',
+    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)' },
+    ],
   },
-
-  // ── Models & Integrations ─────────────────────────────────────────────
   {
     name: 'models',
     emoji: '🧠',
     category: 'Models & Integrations',
+    core: false,
     description: 'Show or update model tier assignments',
-    usage: 'construct models [--poll|--apply|--reset|--tier=TIER|--set=MODEL|--prefer-free|--prefer-free-same-family]',
-    options: [
-      { flag: '--poll',        desc: 'Query OpenRouter for currently free models' },
-      { flag: '--apply',       desc: 'Auto-apply best free models and sync' },
-      { flag: '--reset',       desc: 'Remove model overrides, restore defaults' },
-      { flag: '--tier=TIER',   desc: 'Target tier: reasoning | standard | fast' },
-      { flag: '--set=MODEL_ID',desc: 'Set specific model for the tier' },
-      { flag: '--prefer-free', desc: 'When inferring sibling tiers, prefer free models where possible' },
-      { flag: '--prefer-free-same-family', desc: 'Prefer free siblings only when they stay in the same provider family' },
+    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' },
+      { name: 'free', desc: 'List available free models' },
+      { 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' },
     ],
   },
   {
     name: 'mcp',
     emoji: '🔌',
     category: 'Models & Integrations',
+    core: false,
     description: 'Manage MCP integrations',
-    usage: 'construct mcp <list|add|remove|info> [name]',
+    usage: 'construct mcp <list|add|remove|info>',
     subcommands: [
-      { name: 'list',   desc: 'Show all MCP integrations and status' },
-      { name: 'add',    desc: 'Add an MCP integration interactively' },
-      { name: 'remove', desc: 'Remove an MCP integration' },
-      { name: 'info',   desc: 'Show setup details for an integration' },
+      { name: 'list', desc: 'List configured MCP integrations' },
+      { name: 'add <id>', desc: 'Add an MCP integration by id' },
+      { name: 'remove <id>', desc: 'Remove an MCP integration' },
+      { name: 'info <id>', desc: 'Show details for one MCP integration' },
     ],
   },
   {
     name: 'plugin',
     emoji: '🧩',
     category: 'Models & Integrations',
+    core: false,
     description: 'Manage external Construct plugin manifests',
-    usage: 'construct plugin <list|info|validate|init> [name]',
+    usage: 'construct plugin <list|info|init|validate|engine>',
     subcommands: [
-      { name: 'list', desc: 'Show loaded plugins and manifest sources' },
-      { name: 'info', desc: 'Show details for a plugin' },
-      { name: 'validate', desc: 'Validate all discovered plugin manifests' },
-      { name: 'init', desc: 'Create a starter plugin manifest in .cx/plugins/' },
+      { 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',
     emoji: '🖥️',
     category: 'Models & Integrations',
+    core: false,
     description: 'Show host support for Construct orchestration',
-    usage: 'construct hosts',
+    usage: 'construct hosts [--json]',
   },
   {
     name: 'claude:allow',
     emoji: '🔓',
     category: 'Models & Integrations',
+    core: false,
     description: 'Manage Claude Code `permissions.allow` from the outside (auto-classifier blocks the agent from editing it)',
-    usage: 'construct claude:allow <list|add|remove|check> [pattern...] [--apply]',
-    subcommands: [
-      { name: 'list',   desc: 'Print every allowlist entry' },
-      { name: 'add',    desc: 'Add one or more patterns (idempotent)' },
-      { name: 'remove', desc: 'Remove patterns' },
-      { name: 'check',  desc: 'Detect branch-prefix gaps; `--apply` writes the suggestions' },
-    ],
+    usage: 'construct claude:allow <check|apply|add|remove>',
   },
-
-  // ── Observability ─────────────────────────────────────────────────────
   {
     name: 'review',
     emoji: '📈',
     category: 'Observability',
+    core: false,
     description: 'Generate agent performance review from Langfuse trace backend',
-    usage: 'construct review [--days=N] [--agent=NAME] [--schedule]',
-    options: [
-      { flag: '--days=N',      desc: 'Review window in days (default: 30)' },
-      { flag: '--agent=NAME',  desc: 'Filter to a specific agent' },
-      { flag: '--out=PATH',    desc: 'Output directory' },
-      { flag: '--json-only',   desc: 'Write raw JSON only, skip markdown report' },
-      { flag: '--schedule',    desc: 'Schedule automatic weekly reviews' },
-      { flag: '--cadence=CRON',desc: 'Cron expression for --schedule (default: Monday 9am)' },
-    ],
+    usage: 'construct review [--agent=<id>] [--days=N]',
   },
   {
     name: 'optimize',
     emoji: '⚙️',
     category: 'Observability',
+    core: false,
     description: 'Prompt optimization using Langfuse trace quality scores',
-    usage: 'construct optimize <agent> [--dry-run] [--list]',
-    options: [
-      { flag: '--dry-run',       desc: 'Preview changes without applying' },
-      { flag: '--list',          desc: 'Show all agents with quality scores' },
-      { flag: '--threshold=N',   desc: 'Quality threshold to trigger optimization (default: 0.7)' },
-      { flag: '--days=N',        desc: 'Trace window in days (default: 7)' },
-      { flag: '--min-traces=N',  desc: 'Minimum traces required (default: 20)' },
-    ],
+    usage: 'construct optimize <agent>',
   },
   {
     name: 'telemetry-backfill',
     emoji: '🩹',
     category: 'Observability',
+    core: false,
     description: 'Backfill sparse traces with observations (trace backend)',
-    usage: 'construct telemetry-backfill [--limit=N]',
-    options: [
-      { flag: '--limit=N', desc: 'Maximum sparse traces to backfill (default: 10)' },
-      { flag: '--best-effort', desc: 'Skip failures instead of exiting non-zero' },
-    ],
+    usage: 'construct telemetry-backfill',
   },
   {
     name: 'eval-datasets',
     emoji: '📊',
     category: 'Observability',
+    core: false,
     description: 'Sync scored Langfuse traces into eval datasets for prompt regression testing',
-    usage: 'construct eval-datasets [--limit=N]',
-    options: [
-      { flag: '--limit=N', desc: 'Maximum scored traces to sync (default: 100)' },
-    ],
+    usage: 'construct eval-datasets',
   },
   {
     name: 'llm-judge',
     emoji: '⚖️',
     category: 'Observability',
+    core: false,
     description: 'Run LLM-as-a-judge evaluations on unscored traces for continuous quality feedback',
-    usage: 'construct llm-judge [--limit=N] [--model=NAME]',
-    options: [
-      { flag: '--limit=N', desc: 'Maximum traces to evaluate (default: 10)' },
-      { flag: '--model=NAME', desc: 'LLM model to use for evaluation (default: claude-3-5-sonnet-20241022)' },
-    ],
+    usage: 'construct llm-judge',
   },
   {
     name: 'efficiency',
     emoji: '🧮',
     category: 'Observability',
+    core: false,
     description: 'Show read efficiency, repeated files, and context-budget guidance',
     usage: 'construct efficiency [--json]',
-    options: [
-      { flag: '--json', desc: 'Output raw JSON' },
-    ],
   },
   {
     name: 'evals',
     emoji: '🧪',
     category: 'Observability',
+    core: false,
     description: 'Show evaluator catalog for prompt and agent experiments',
-    usage: 'construct evals [--json]',
-    options: [
-      { flag: '--json', desc: 'Output raw JSON' },
-    ],
+    usage: 'construct evals <list|run>',
   },
   {
     name: 'cleanup',
     emoji: '🧹',
     category: 'Diagnostics',
+    core: false,
     description: 'Release dev-agent memory pressure by cleaning stale helper and bridge processes',
-    usage: 'construct cleanup [--pressure-release] [--quiet]',
+    usage: 'construct cleanup [--dry-run] [--quiet] [--pressure-release] [--pressure-only] [--disk-only]',
     options: [
-      { flag: '--pressure-release', desc: 'Also terminate stale cass index processes when swap is above threshold' },
-      { flag: '--quiet', desc: 'Suppress per-process output and only act on the current policy' },
+      { flag: '--dry-run',          desc: 'Show what would be cleaned without changing anything' },
+      { flag: '--quiet',            desc: 'Minimal output' },
+      { flag: '--pressure-release', desc: 'Also kill stale dev-agent processes' },
+      { flag: '--pressure-only',    desc: 'Pressure release only — skip disk cleanup' },
+      { flag: '--disk-only',        desc: 'Disk cleanup only — skip pressure release' },
     ],
   },
-
-  // ── Teams & Audit ────────────────────────────────────────────────────
   {
     name: 'team',
     emoji: '👥',
     category: 'Work',
+    core: false,
     description: 'Team review and template listing',
-    usage: 'construct team <review|templates>',
-    subcommands: [
-      { name: 'review',    desc: 'Run telemetry-backed team performance review' },
-      { name: 'templates', desc: 'List available team templates from specialists/teams.json' },
-    ],
+    usage: 'construct team <list|review>',
   },
   {
     name: 'audit',
     emoji: '🔍',
     category: 'Diagnostics',
+    core: false,
     description: 'Audit Construct internals and review the mutation trail',
-    usage: 'construct audit <skills|trail>',
-    subcommands: [
-      { name: 'skills', desc: 'Audit skill files for stub headers, broken references, and missing content' },
-      { name: 'trail',  desc: 'Show the append-only audit trail of every mutation (agent, task, file, hash). Supports --verify, --agent, --tool, --since, --json.' },
-    ],
+    usage: 'construct audit <events|trail>',
   },
   {
     name: 'doc',
     emoji: '🔏',
     category: 'Diagnostics',
+    core: false,
     description: 'Verify or inspect auditability stamps on Construct-generated markdown files',
-    usage: 'construct doc <verify|install-hooks> [path] [--json]',
-    subcommands: [
-      { name: 'verify',       desc: 'Check body_hash stamps on one file or all .md files under a path. Exits non-zero if any fail.' },
-      { name: 'install-hooks', desc: 'Install the prepare-commit-msg git hook into .git/hooks/ for AI provenance trailers.' },
-    ],
+    usage: 'construct doc <verify|inspect>',
+  },
+  {
+    name: 'bootstrap',
+    emoji: '🌱',
+    category: 'Work',
+    core: false,
+    description: 'Import seed observation corpus into local memory store for cold-start acceleration',
+    usage: 'construct bootstrap',
+  },
+  {
+    name: 'reflect',
+    emoji: '🪞',
+    category: 'Work',
+    core: false,
+    description: 'Capture improvement feedback from chat session and update Construct core',
+    usage: 'construct reflect',
   },
-   {
-     name: 'bootstrap',
-     emoji: '🌱',
-     category: 'Work',
-     description: 'Import seed observation corpus into local memory store for cold-start acceleration',
-     usage: 'construct bootstrap [--verbose]',
-     options: [
-       { flag: '--verbose', desc: 'Print each observation imported or skipped' },
-     ],
-   },
-   {
-     name: 'reflect',
-     emoji: '🪞',
-     category: 'Work',
-     description: 'Capture improvement feedback from chat session and update Construct core',
-     usage: 'construct reflect [--target=<internal|how-tos|decisions>] [--summary=<text>]',
-     options: [
-       { flag: '--target=<internal|how-tos|decisions>', desc: 'Knowledge subdir to store feedback (default: internal)' },
-       { flag: '--summary=<text>', desc: 'Brief summary of the improvement feedback' },
-     ],
-   },
   {
     name: 'memory',
     emoji: '💡',
     category: 'Work',
     core: false,
     description: 'Inspect memory layer',
-    usage: 'construct memory stats|consolidate',
+    usage: 'construct memory <status|search>',
   },
   {
     name: 'drop',
@@ -493,7 +493,7 @@ export const CLI_COMMANDS = [
     category: 'Work',
     core: false,
     description: 'Ingest file from Downloads/Desktop',
-    usage: 'construct drop [--list]',
+    usage: 'construct drop <file>',
   },
   {
     name: 'wireframe',
@@ -501,7 +501,7 @@ export const CLI_COMMANDS = [
     category: 'Work',
     core: false,
     description: 'Generate wireframes from description',
-    usage: 'construct wireframe "<description>"',
+    usage: 'construct wireframe <description>',
   },
   {
     name: 'ollama',
@@ -509,17 +509,15 @@ export const CLI_COMMANDS = [
     category: 'Integrations',
     core: false,
     description: 'Manage local Ollama models',
-    usage: 'construct ollama status|pull|test',
+    usage: 'construct ollama <list|pull|run>',
   },
-  
-  // ── Advanced (hidden by default) ──────────────────────────────────────
   {
     name: 'beads',
     emoji: '📿',
     category: 'Advanced',
     core: false,
     description: 'Task queue management',
-    usage: 'construct beads status|cleanup',
+    usage: 'construct beads <list|show|create|update|close|drift|stats>',
   },
   {
     name: 'config',
@@ -527,7 +525,7 @@ export const CLI_COMMANDS = [
     category: 'Advanced',
     core: false,
     description: 'Deployment mode configuration',
-    usage: 'construct config mode',
+    usage: 'construct config <get|set>',
   },
   {
     name: 'uninstall',
@@ -535,7 +533,14 @@ export const CLI_COMMANDS = [
     category: 'Advanced',
     core: false,
     description: 'Remove Construct state',
-    usage: 'construct uninstall',
+    usage: 'construct uninstall [--dry-run] [--yes] [--all] [--keep-state] [--scope=project|machine|all]',
+    options: [
+      { 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)' },
+    ],
   },
   {
     name: 'update',
@@ -559,7 +564,7 @@ export const CLI_COMMANDS = [
     category: 'Advanced',
     core: false,
     description: 'Shell completion scripts',
-    usage: 'construct completions',
+    usage: 'construct completions <bash|zsh|install>',
   },
   {
     name: 'list',
@@ -575,7 +580,7 @@ export const CLI_COMMANDS = [
     category: 'Advanced',
     core: false,
     description: 'Role framework management',
-    usage: 'construct role list|status',
+    usage: 'construct role <list|set|latest>',
   },
   {
     name: 'embed',
@@ -719,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',
@@ -729,18 +737,143 @@ export const CLI_COMMANDS = [
     description: 'Query telemetry traces and latency data',
     usage: 'construct telemetry query <latency|top-slow|errors|trace>',
   },
+  {
+    name: 'ask',
+    emoji: '❓',
+    category: 'Work',
+    core: false,
+    description: 'One-shot ask against the active knowledge index',
+    usage: 'construct ask <query>',
+  },
+  {
+    name: 'handoffs',
+    emoji: '📦',
+    category: 'Work',
+    core: false,
+    description: 'List and inspect session handoff files in .cx/handoffs/',
+    usage: 'construct handoffs <list|show>',
+  },
+  {
+    name: 'feedback:record',
+    emoji: '📝',
+    category: 'Observability',
+    core: false,
+    description: 'Record an outcome rating for a recent specialist invocation',
+    usage: 'construct feedback:record <id> --score=<0-1> [--note="..."]',
+  },
+  {
+    name: 'feedback:history',
+    emoji: '📜',
+    category: 'Observability',
+    core: false,
+    description: 'Show recorded outcome ratings',
+    usage: 'construct feedback:history [--days=N]',
+  },
+  {
+    name: 'roles:list',
+    emoji: '🎭',
+    category: 'Advanced',
+    core: false,
+    description: 'List installed role contracts',
+    usage: 'construct roles:list',
+  },
+  {
+    name: 'roles:set',
+    emoji: '🎭',
+    category: 'Advanced',
+    core: false,
+    description: 'Activate a role contract',
+    usage: 'construct roles:set <role>',
+  },
+  {
+    name: 'docs:check',
+    emoji: '📄',
+    category: 'Diagnostics',
+    core: false,
+    description: 'Check for missing how-to guides (alias for `docs check`)',
+    usage: 'construct docs:check',
+  },
+  {
+    name: 'docs:verify',
+    emoji: '📄',
+    category: 'Diagnostics',
+    core: false,
+    description: 'Validate documentation quality (alias for `docs verify`)',
+    usage: 'construct docs:verify',
+  },
+  {
+    name: 'docs:update',
+    emoji: '📄',
+    category: 'Diagnostics',
+    core: false,
+    description: 'Regenerate AUTO-managed doc regions (alias for `docs update`)',
+    usage: 'construct docs:update',
+  },
+  {
+    name: 'docs:reconcile',
+    emoji: '📄',
+    category: 'Diagnostics',
+    core: false,
+    description: 'Reconcile docs against the registry',
+    usage: 'construct docs:reconcile',
+  },
+  {
+    name: 'docs:site',
+    emoji: '📄',
+    category: 'Diagnostics',
+    core: false,
+    description: 'Manage the docs static site build',
+    usage: 'construct docs:site <build|serve>',
+  },
+  {
+    name: 'beads:stats',
+    emoji: '📿',
+    category: 'Advanced',
+    core: false,
+    description: 'Show beads counters and drift summary',
+    usage: 'construct beads:stats',
+  },
+  {
+    name: 'telemetry-setup',
+    emoji: '🩹',
+    category: 'Observability',
+    core: false,
+    description: 'Configure Langfuse credentials and trace export',
+    usage: 'construct telemetry-setup',
+  },
+  // ── Internal — callable but not advertised in help or completions ────
+  { name: 'hook',              category: 'Internal', core: false, internal: true, description: 'Hook dispatch — invoked by the harness, not by users', usage: 'construct hook <event>' },
+  { name: 'seed-traces',       category: 'Internal', core: false, internal: true, description: 'Dev fixture: seed traces for testing', usage: 'construct seed-traces' },
+  { name: 'migrate',           category: 'Internal', core: false, internal: true, description: 'Internal: run pending storage migrations', usage: 'construct migrate' },
+  { name: 'dashboard:sync',    category: 'Internal', core: false, internal: true, description: 'Internal: refresh dashboard state from the registry', usage: 'construct dashboard:sync' },
+  { name: 'init:update',       category: 'Internal', core: false, internal: true, description: 'Internal: re-run init scaffolding for an existing project', usage: 'construct init:update' },
+  { name: 'lint:agents',       category: 'Internal', core: false, internal: true, description: 'Internal lint: agent definitions', usage: 'construct lint:agents' },
+  { name: 'lint:comments',     category: 'Internal', core: false, internal: true, description: 'Internal lint: source comments', usage: 'construct lint:comments' },
+  { name: 'lint:contracts',    category: 'Internal', core: false, internal: true, description: 'Internal lint: specialist contracts', usage: 'construct lint:contracts' },
+  { name: 'lint:research',     category: 'Internal', core: false, internal: true, description: 'Internal lint: research artifacts', usage: 'construct lint:research' },
+  { name: 'lint:templates',    category: 'Internal', core: false, internal: true, description: 'Internal lint: shipped templates', usage: 'construct lint:templates' },
+  { name: 'evaluator:rubrics', category: 'Internal', core: false, internal: true, description: 'Internal: list registered evaluator rubrics', usage: 'construct evaluator:rubrics' },
+  { name: 'activation:status', category: 'Internal', core: false, internal: true, description: 'Internal: agent activation telemetry', usage: 'construct activation:status' },
+  { name: 'prune',             category: 'Internal', core: false, internal: true, description: 'Internal: prune ephemeral storage entries', usage: 'construct prune' },
+  { name: 'overrides',         category: 'Internal', core: false, internal: true, description: 'Internal: list project overrides over the catalog', usage: 'construct overrides' },
+  { name: 'resources',         category: 'Internal', core: false, internal: true, description: 'Internal: resource probe', usage: 'construct resources' },
 ];
 
 /** Flat list of all top-level command names (for completions). */
-export const COMMAND_NAMES = CLI_COMMANDS.map(c => c.name);
+export const COMMAND_NAMES = CLI_COMMANDS.filter((c) => !c.internal).map((c) => c.name);
+
+/** Every handler key (including internal) — used for catalog-parity tests. */
+export const ALL_COMMAND_NAMES = CLI_COMMANDS.map((c) => c.name);
 
 /** Commands grouped by category, sorted alphabetically by name within each group. */
-export const CLI_COMMANDS_BY_CATEGORY = CLI_COMMANDS.reduce((acc, cmd) => {
-  const cat = cmd.category ?? 'Other';
-  if (!acc[cat]) acc[cat] = [];
-  acc[cat].push(cmd);
-  return acc;
-}, {});
+export const CLI_COMMANDS_BY_CATEGORY = CLI_COMMANDS
+  .filter((c) => !c.internal)
+  .reduce((acc, cmd) => {
+    const cat = cmd.category ?? 'Other';
+    if (!acc[cat]) acc[cat] = [];
+    acc[cat].push(cmd);
+    return acc;
+  }, {});
 for (const cat of Object.keys(CLI_COMMANDS_BY_CATEGORY)) {
   CLI_COMMANDS_BY_CATEGORY[cat].sort((a, b) => a.name.localeCompare(b.name));
 }
@@ -758,13 +891,66 @@ export const CATEGORY_ORDER = [
 
 /** Check if a command should be shown by default (core: true) or hidden (core: false). */
 export function isCoreCommand(commandName) {
-  const cmd = CLI_COMMANDS.find(c => c.name === commandName);
+  const cmd = CLI_COMMANDS.find((c) => c.name === commandName);
   return cmd?.core ?? false;
 }
 
+/** Check if a command is internal (hidden from --help and --all). */
+export function isInternalCommand(commandName) {
+  const cmd = CLI_COMMANDS.find((c) => c.name === commandName);
+  return cmd?.internal === true;
+}
+
 /** Get commands filtered by visibility. */
 export function getCommands(options = {}) {
   const { showAll = false } = options;
-  if (showAll) return CLI_COMMANDS;
-  return CLI_COMMANDS.filter(cmd => cmd.core);
+  const visible = CLI_COMMANDS.filter((c) => !c.internal);
+  if (showAll) return visible;
+  return visible.filter((cmd) => cmd.core);
+}
+
+/** Look up a single command entry by name. */
+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 spec = getCommandSpec(name);
+  if (!spec) {
+    return `Unknown command: ${name}\n\nRun 'construct --help' for available commands.\n`;
+  }
+  const lines = [];
+  lines.push(`${c.bold}construct ${spec.name}${c.reset} — ${spec.description}`);
+  lines.push('');
+  if (spec.usage) {
+    lines.push(`${c.dim}Usage:${c.reset} ${spec.usage}`);
+    lines.push('');
+  }
+  if (spec.subcommands && spec.subcommands.length > 0) {
+    lines.push(`${c.bold}Subcommands${c.reset}`);
+    const width = Math.max(...spec.subcommands.map((s) => s.name.length));
+    for (const sub of spec.subcommands) {
+      lines.push(`  ${sub.name.padEnd(width)}  ${sub.desc}`);
+    }
+    lines.push('');
+  }
+  if (spec.options && spec.options.length > 0) {
+    lines.push(`${c.bold}Options${c.reset}`);
+    const width = Math.max(...spec.options.map((o) => o.flag.length));
+    for (const opt of spec.options) {
+      lines.push(`  ${opt.flag.padEnd(width)}  ${opt.desc}`);
+    }
+    lines.push('');
+  }
+  return lines.join('\n');
 }