@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/cli-commands.mjs

@@ -5,405 +5,560 @@
  *   - bin/construct         (usage text + emoji output)
  *   - lib/completions.mjs   (bash + zsh completion generation)
  *   - lib/server/index.mjs  (/api/status → dashboard)
+ *
+ * Command Visibility:
+ *   - core: true → shown in default --help (90% of users)
+ *   - core: false → hidden unless --all flag (advanced/internal commands)
  */
 
 export const CLI_COMMANDS = [
-  // ── Services ──────────────────────────────────────────────────────────
+  // ── Core (shown by default) ───────────────────────────────────────────
   {
-    name: 'up',
+    name: 'dev',
     emoji: '🚀',
-    category: 'Services',
-    description: 'Start services (memory, dashboard)',
-    usage: 'construct up',
+    category: 'Core',
+    core: true,
+    description: 'Start services for development',
+    usage: 'construct dev',
   },
   {
-    name: 'down',
+    name: 'stop',
     emoji: '⏹',
-    category: 'Services',
+    category: 'Core',
+    core: true,
     description: 'Stop all running services',
-    usage: 'construct down',
+    usage: 'construct stop',
   },
   {
     name: 'status',
     emoji: '📡',
-    category: 'Services',
-    description: 'Show canonical system health across runtime and integrations',
+    category: 'Core',
+    core: true,
+    description: 'Show system health and credentials',
     usage: 'construct status',
     options: [
       { flag: '--json', desc: 'Output full status payload as JSON' },
     ],
   },
   {
-    name: 'show',
-    emoji: '📊',
-    category: 'Services',
-    description: 'Show runtime service URLs and live status (compat view)',
-    usage: 'construct show',
-  },
-  {
-    name: 'serve',
-    emoji: '🌐',
-    category: 'Services',
-    description: 'Start the Construct dashboard (auto-selects port)',
-    usage: 'construct serve',
+    name: 'install',
+    emoji: '🛠️',
+    category: 'Core',
+    core: true,
+    description: 'Machine setup: install Docker, cm, and bootstrap config',
+    usage: 'construct install [--yes]',
+    options: [
+      { flag: '--yes', desc: 'Apply defaults without prompts' },
+    ],
   },
   {
-    name: 'setup',
-    emoji: '🛠️',
-    category: 'Services',
-    description: 'Bootstrap user config after npm, Homebrew, or manual install',
-    usage: 'construct setup [--yes] [--no-docker]',
+    name: 'init',
+    emoji: '🏗️',
+    category: 'Core',
+    core: true,
+    description: 'Initialize project and start services',
+    usage: 'construct init [path] [options]',
     options: [
-      { flag: '--yes', desc: 'Apply sensible defaults without pausing for prompts' },
-      { flag: '--no-docker', desc: 'Skip managed local Postgres startup' },
+      { flag: '--yes', desc: 'Accept all defaults (non-interactive)' },
+      { flag: '--no-start', desc: 'Do not start services after init' },
+      { flag: '--interactive, -i', desc: 'Enable interactive setup with project detection' },
+      { flag: '--quiet, -q', desc: 'Minimal output' },
+      { flag: '--verbose, -v', desc: 'Detailed output' },
+      { flag: '--with-docs=adrs,rfcs', desc: 'Enable specific doc lanes (comma-separated)' },
+      { flag: '--with-all-docs', desc: 'Enable all documentation lanes' },
+      { flag: '--with-adrs', desc: 'Enable Architecture Decision Records' },
+      { flag: '--with-rfcs', desc: 'Enable RFCs (design reviews)' },
+      { flag: '--with-runbooks', desc: 'Enable operational runbooks' },
+      { flag: '--with-postmortems', desc: 'Enable incident postmortems' },
+      { flag: '--with-architecture', desc: 'Create architecture.md' },
     ],
   },
-
-  // ── Agents & Sync ─────────────────────────────────────────────────────
   {
     name: 'sync',
     emoji: '🔄',
-    category: 'Agents & Sync',
-    description: 'Generate agent adapters for all platforms',
-    usage: 'construct sync [--project]',
-    options: [
-      { flag: '--project', desc: 'Sync to current project directory only' },
-    ],
+    category: 'Core',
+    core: true,
+    description: 'Sync agent adapters to AI tools',
+    usage: 'construct sync',
   },
   {
-    name: 'list',
-    emoji: '📋',
-    category: 'Agents & Sync',
-    description: 'Show all personas and specialist agents',
-    usage: 'construct list',
+    name: 'intake',
+    emoji: '📥',
+    category: 'Core',
+    core: true,
+    description: 'View and process R&D intake queue',
+    usage: 'construct intake list|show|done|skip',
   },
-
-  // ── Work ──────────────────────────────────────────────────────────────
   {
-    name: 'do',
-    emoji: '⚡',
+    name: 'recommendations',
+    emoji: '💡',
+    category: 'Core',
+    core: true,
+    description: 'View and manage artifact recommendations',
+    usage: 'construct recommendations list|show|dismiss|stats',
+  },
+  {
+    name: 'integrations',
+    emoji: '🔗',
     category: 'Work',
-    description: 'Execute a natural language goal via the orchestrator',
-    usage: 'construct do <goal>',
+    core: false,
+    description: 'Check and manage external system connections',
+    usage: 'construct integrations status',
+    subcommands: [
+      { name: 'status', desc: 'Check which external integrations are configured' },
+    ],
   },
   {
-    name: 'distill',
-    emoji: '🔬',
+    name: 'customer',
+    emoji: '👤',
     category: 'Work',
-    description: 'Distill documents with query-focused, citation-ready chunk selection',
-    usage: 'construct distill <dir> [--format=summary|decisions|full|extract] [--query=TEXT] [--mode=auto|prompt|json] [--out=FILE]',
-    options: [
-      { flag: '--format=TYPE', desc: 'Output format: summary | decisions | full | extract (default: summary)' },
-      { flag: '--query=TEXT',  desc: 'Focus chunk selection and output on a specific question' },
-      { flag: '--mode=TYPE',   desc: 'Execution mode: auto | prompt | json (default: auto)' },
-      { flag: '--out=FILE',    desc: 'Write output to file instead of stdout' },
-      { flag: '--depth=N',     desc: 'Max directory depth to scan (default: 3)' },
-      { flag: '--ext=LIST',    desc: 'Comma-separated extensions to include (default: all text)' },
+    core: false,
+    description: 'Manage customer profiles for product intelligence',
+    usage: 'construct customer list|show|add|update|search',
+    subcommands: [
+      { name: 'list', desc: 'List all customer profiles' },
+      { name: 'show <id>', desc: 'Show a customer profile' },
+      { name: 'add --name=Acme --owner=Jane', desc: 'Create a new customer profile' },
+      { name: 'search <query>', desc: 'Search customer profiles by name/alias' },
     ],
   },
   {
-    name: 'research',
-    emoji: '🔎',
+    name: 'workspace',
+    emoji: '🏢',
     category: 'Work',
-    description: 'Run query-focused bounded retrieval over project documents',
-    usage: 'construct research <query> [--dir=PATH] [--ext=LIST] [--depth=N]',
-    options: [
-      { flag: '--dir=PATH', desc: 'Directory to search (default: docs)' },
-      { flag: '--ext=LIST', desc: 'Comma-separated extensions to include' },
-      { flag: '--depth=N', desc: 'Max directory depth to scan (default: 3)' },
+    core: false,
+    description: 'Manage PM workspaces for multi-PM signal routing',
+    usage: 'construct workspace list|create|show|assign',
+    subcommands: [
+      { name: 'list', desc: 'List all workspaces' },
+      { name: 'create --name=X --owner=Jane', desc: 'Create a new workspace' },
+      { name: 'show <id>', desc: 'Show workspace details' },
+      { name: 'assign --customer=X --workspace=Y', desc: 'Assign customer to workspace' },
     ],
   },
   {
     name: 'docs',
-    emoji: '📚',
-    category: 'Work',
-    description: 'Run documentation-focused bounded retrieval over markdown-like files',
-    usage: 'construct docs <query> [--dir=PATH] [--depth=N]',
-    options: [
-      { flag: '--dir=PATH', desc: 'Directory to search (default: docs)' },
-      { flag: '--depth=N', desc: 'Max directory depth to scan (default: 3)' },
+    emoji: '📄',
+    category: 'Core',
+    core: true,
+    description: 'Documentation commands',
+    usage: 'construct docs check|verify|update',
+    subcommands: [
+      { name: 'check', desc: 'Check for missing how-to guides' },
+      { name: 'verify', desc: 'Validate documentation quality' },
+      { name: 'update', desc: 'Regenerate AUTO-managed regions' },
     ],
   },
+  {
+    name: 'models',
+    emoji: '🧠',
+    category: 'Core',
+    core: true,
+    description: 'Manage AI model assignments',
+    usage: 'construct models [--apply|--poll]',
+  },
+  {
+    name: 'doctor',
+    emoji: '🩺',
+    category: 'Core',
+    core: true,
+    description: 'Check installation health',
+    usage: 'construct doctor',
+  },
+  
+  // ── 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]',
+  },
+  {
+    name: 'ingest',
+    emoji: '📥',
+    category: 'Work',
+    core: false,
+    description: 'Convert documents to indexed markdown',
+    usage: 'construct ingest <file> [--sync]',
+  },
+  {
+    name: 'infer',
+    emoji: '🧠',
+    category: 'Work',
+    core: false,
+    description: 'Infer schema from documents',
+    usage: 'construct infer <file> [--unified]',
+  },
   {
     name: 'search',
     emoji: '🔎',
     category: 'Work',
-    description: 'Run hybrid file, SQL, and semantic retrieval over core project state',
-    usage: 'construct search <query> [--limit=N]',
-    options: [
-      { flag: '--limit=N', desc: 'Maximum results to return (default: 10)' },
-    ],
+    core: false,
+    description: 'Hybrid search across project state',
+    usage: 'construct search <query>',
   },
   {
     name: 'storage',
     emoji: '🗄️',
     category: 'Work',
-    description: 'Sync and inspect the hybrid storage backend',
-    usage: 'construct storage <sync|status>',
-    subcommands: [
-      { name: 'sync', desc: 'Sync file-state artifacts into shared storage' },
-      { name: 'status', desc: 'Show storage backend configuration and health' },
-    ],
+    core: false,
+    description: 'Manage storage backend',
+    usage: 'construct storage sync|status|reset',
   },
   {
     name: 'headhunt',
     emoji: '🧭',
     category: 'Work',
-    description: 'Create a temporary domain expertise overlay or promotion request',
-    usage: 'construct headhunt <domain> [--for=OBJECTIVE] [--scope=TEXT] [--temp|--save] [--team=a,b] | construct headhunt <list|promote|challenge|cleanup|template>',
-    options: [
-      { flag: '--for=OBJECTIVE', desc: 'Outcome the domain expertise should support' },
-      { flag: '--scope=TEXT', desc: 'Optional scope boundary for the overlay' },
-      { flag: '--temp', desc: 'Force temporary overlay mode' },
-      { flag: '--save', desc: 'Create a promotion request in addition to the temporary overlay' },
-      { flag: '--team=a,b', desc: 'Explicit existing specialists to attach the overlay to' },
-      { flag: '--freshness=current|stable', desc: 'Research freshness requirement (default: current)' },
-      { flag: 'list', desc: 'List active overlays and promotion requests' },
-      { flag: 'promote <id>', desc: 'Create a promotion request from an existing overlay' },
-      { flag: 'challenge <id>', desc: 'Update devil\'s advocate challenge status for a promotion request' },
-      { flag: 'cleanup', desc: 'Remove expired temporary overlays' },
-      { flag: 'template [name] --for=OBJECTIVE', desc: 'Assemble a named team template as a domain overlay' },
-    ],
+    core: false,
+    description: 'Create domain expertise overlays',
+    usage: 'construct headhunt <domain>',
   },
   {
-    name: 'workflow',
-    emoji: '🗂️',
+    name: 'graph',
+    emoji: '🕸️',
     category: 'Work',
-    description: 'Manage .cx/workflow.json orchestration state',
-    usage: 'construct workflow <init|add|task|align|from-plan>',
-    subcommands: [
-      { name: 'init',      desc: 'Initialize a new workflow' },
-      { name: 'add',       desc: 'Add a task to the workflow' },
-      { name: 'task',      desc: 'Update a task status' },
-      { name: 'align',     desc: 'Check alignment findings' },
-      { name: 'from-plan', desc: 'Import tasks from a plan markdown file' },
-    ],
+    core: false,
+    description: 'Task graph management',
+    usage: 'construct graph list|show|from-intake',
   },
   {
-    name: 'init-docs',
-    emoji: '📝',
+    name: 'memory',
+    emoji: '💡',
     category: 'Work',
-    description: 'Generate AI-tailored doc structure for the current project',
-    usage: 'construct init-docs [path] [--yes]',
-    options: [
-      { flag: '--yes', desc: 'Skip interactive questions, use defaults' },
-    ],
+    core: false,
+    description: 'Inspect memory layer',
+    usage: 'construct memory stats|consolidate',
   },
-
-  // ── Models & Integrations ─────────────────────────────────────────────
   {
-    name: 'models',
-    emoji: '🧠',
-    category: 'Models & Integrations',
-    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' },
-    ],
+    name: 'reflect',
+    emoji: '🪞',
+    category: 'Work',
+    core: false,
+    description: 'Capture improvement feedback',
+    usage: 'construct reflect [--summary=<text>]',
+  },
+  {
+    name: 'drop',
+    emoji: '📥',
+    category: 'Work',
+    core: false,
+    description: 'Ingest file from Downloads/Desktop',
+    usage: 'construct drop [--list]',
+  },
+  {
+    name: 'wireframe',
+    emoji: '✏️',
+    category: 'Work',
+    core: false,
+    description: 'Generate wireframes from description',
+    usage: 'construct wireframe "<description>"',
+  },
+  {
+    name: 'bootstrap',
+    emoji: '🌱',
+    category: 'Work',
+    core: false,
+    description: 'Import seed observations',
+    usage: 'construct bootstrap',
   },
+  {
+    name: 'team',
+    emoji: '👥',
+    category: 'Work',
+    core: false,
+    description: 'Team review and templates',
+    usage: 'construct team review|templates',
+  },
+  
+  // ── Integrations ──────────────────────────────────────────────────────
   {
     name: 'mcp',
     emoji: '🔌',
-    category: 'Models & Integrations',
+    category: 'Integrations',
+    core: false,
     description: 'Manage MCP integrations',
-    usage: 'construct mcp <list|add|remove|info> [name]',
-    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' },
-    ],
+    usage: 'construct mcp list|add|remove',
+  },
+  {
+    name: 'ollama',
+    emoji: '🦙',
+    category: 'Integrations',
+    core: false,
+    description: 'Manage local Ollama models',
+    usage: 'construct ollama status|pull|test',
+  },
+  {
+    name: 'plugin',
+    emoji: '🧩',
+    category: 'Integrations',
+    core: false,
+    description: 'Manage plugin manifests',
+    usage: 'construct plugin list|validate',
   },
   {
     name: 'hosts',
     emoji: '🖥️',
-    category: 'Models & Integrations',
-    description: 'Show host support for Construct orchestration',
+    category: 'Integrations',
+    core: false,
+    description: 'Check host capabilities',
     usage: 'construct hosts',
   },
-
+  {
+    name: 'claude:allow',
+    emoji: '🔓',
+    category: 'Integrations',
+    core: false,
+    description: 'Manage Claude Code permissions',
+    usage: 'construct claude:allow list|add|check',
+  },
+  
   // ── Observability ─────────────────────────────────────────────────────
+  {
+    name: 'cost',
+    emoji: '💰',
+    category: 'Observability',
+    core: false,
+    description: 'Token usage and cost breakdown',
+    usage: 'construct cost [--days=N]',
+  },
+  {
+    name: 'efficiency',
+    emoji: '🧮',
+    category: 'Observability',
+    core: false,
+    description: 'Read efficiency metrics',
+    usage: 'construct efficiency',
+  },
   {
     name: 'review',
     emoji: '📈',
     category: 'Observability',
-    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)' },
-    ],
+    core: false,
+    description: 'Agent performance review',
+    usage: 'construct review [--days=N]',
   },
   {
     name: 'optimize',
     emoji: '⚙️',
     category: 'Observability',
-    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)' },
-    ],
+    core: false,
+    description: 'Prompt optimization',
+    usage: 'construct optimize <agent>',
   },
   {
-    name: 'telemetry-backfill',
-    emoji: '🩹',
+    name: 'evals',
+    emoji: '🧪',
     category: 'Observability',
-    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' },
-    ],
+    core: false,
+    description: 'Evaluator catalog',
+    usage: 'construct evals',
   },
   {
-    name: 'cost',
-    emoji: '💰',
+    name: 'llm-judge',
+    emoji: '⚖️',
     category: 'Observability',
-    description: 'Show token usage, cost, cache read rate, and per-agent breakdown',
-    usage: 'construct cost [--days=N] [--agent=NAME] [--reset] [--json]',
-    options: [
-      { flag: '--days=N',     desc: 'Limit report to last N days' },
-      { flag: '--agent=NAME', desc: 'Filter to a specific agent (e.g. cx-engineer)' },
-      { flag: '--reset',      desc: 'Clear the cost log' },
-      { flag: '--json',       desc: 'Output raw JSON' },
-    ],
+    core: false,
+    description: 'LLM-as-judge evaluations',
+    usage: 'construct llm-judge',
   },
+  
+  // ── Advanced (hidden by default) ──────────────────────────────────────
   {
-    name: 'efficiency',
-    emoji: '🧮',
-    category: 'Observability',
-    description: 'Show read efficiency, repeated files, and context-budget guidance',
-    usage: 'construct efficiency [--json]',
-    options: [
-      { flag: '--json', desc: 'Output raw JSON' },
-    ],
+    name: 'beads',
+    emoji: '📿',
+    category: 'Advanced',
+    core: false,
+    description: 'Task queue management',
+    usage: 'construct beads status|cleanup',
   },
   {
-    name: 'evals',
-    emoji: '🧪',
-    category: 'Observability',
-    description: 'Show evaluator catalog for prompt and agent experiments',
-    usage: 'construct evals [--json]',
-    options: [
-      { flag: '--json', desc: 'Output raw JSON' },
-    ],
+    name: 'config',
+    emoji: '⚙️',
+    category: 'Advanced',
+    core: false,
+    description: 'Deployment mode configuration',
+    usage: 'construct config mode',
   },
-
-  // ── Teams & Audit ────────────────────────────────────────────────────
   {
-    name: 'team',
-    emoji: '👥',
-    category: 'Work',
-    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 agents/teams.json' },
-    ],
+    name: 'uninstall',
+    emoji: '🧹',
+    category: 'Advanced',
+    core: false,
+    description: 'Remove Construct state',
+    usage: 'construct uninstall',
   },
   {
-    name: 'audit',
-    emoji: '🔍',
-    category: 'Diagnostics',
-    description: 'Audit Construct internals for gaps or drift',
-    usage: 'construct audit <skills>',
-    subcommands: [
-      { name: 'skills', desc: 'Audit skill files for stub headers, broken references, and missing content' },
-    ],
+    name: 'update',
+    emoji: '⬆️',
+    category: 'Advanced',
+    core: false,
+    description: 'Reinstall this checkout',
+    usage: 'construct update',
   },
-
-  // ── Docs ──────────────────────────────────────────────────────────────
   {
-    name: 'docs:update',
-    emoji: '📄',
-    category: 'Docs',
-    description: 'Regenerate AUTO-managed regions in README and docs/',
-    usage: 'construct docs:update [--check]',
-    options: [
-      { flag: '--check', desc: 'Exit non-zero if any region would change (used by CI)' },
-    ],
+    name: 'upgrade',
+    emoji: '🚀',
+    category: 'Advanced',
+    core: false,
+    description: 'Upgrade to latest npm version',
+    usage: 'construct upgrade',
   },
   {
-    name: 'docs:site',
-    emoji: '🌐',
-    category: 'Docs',
-    description: 'Generate site/docs/ content for the MkDocs GitHub Pages site',
-    usage: 'construct docs:site',
+    name: 'completions',
+    emoji: '⌨️',
+    category: 'Advanced',
+    core: false,
+    description: 'Shell completion scripts',
+    usage: 'construct completions',
   },
   {
-    name: 'lint:comments',
-    emoji: '🗒️',
-    category: 'Docs',
-    description: 'Check all files against the comment policy (rules/common/comments.md)',
-    usage: 'construct lint:comments [--fix]',
-    options: [
-      { flag: '--fix', desc: 'Insert stub headers for files missing one' },
-    ],
+    name: 'list',
+    emoji: '📋',
+    category: 'Advanced',
+    core: false,
+    description: 'List all agents',
+    usage: 'construct list',
   },
-
-  // ── Diagnostics ───────────────────────────────────────────────────────
   {
-    name: 'doctor',
-    emoji: '🩺',
-    category: 'Diagnostics',
-    description: 'Run installation health checks',
-    usage: 'construct doctor',
+    name: 'role',
+    emoji: '🎭',
+    category: 'Advanced',
+    core: false,
+    description: 'Role framework management',
+    usage: 'construct role list|status',
+  },
+  {
+    name: 'embed',
+    emoji: '🔁',
+    category: 'Advanced',
+    core: false,
+    description: 'Embed mode management',
+    usage: 'construct embed start|stop|status',
+  },
+  {
+    name: 'audit',
+    emoji: '🔍',
+    category: 'Advanced',
+    core: false,
+    description: 'Audit Construct internals',
+    usage: 'construct audit skills|trail',
+  },
+  {
+    name: 'backup',
+    emoji: '💾',
+    category: 'Advanced',
+    core: false,
+    description: 'System backups',
+    usage: 'construct backup create|restore',
   },
   {
     name: 'validate',
     emoji: '✅',
-    category: 'Diagnostics',
-    description: 'Validate registry.json structure and field constraints',
+    category: 'Advanced',
+    core: false,
+    description: 'Validate registry structure',
     usage: 'construct validate',
   },
   {
     name: 'diff',
     emoji: '📍',
-    category: 'Diagnostics',
-    description: 'Show which agents changed prompts or settings since HEAD',
+    category: 'Advanced',
+    core: false,
+    description: 'Show agent changes since HEAD',
     usage: 'construct diff',
   },
   {
     name: 'version',
     emoji: 'ℹ️',
-    category: 'Diagnostics',
+    category: 'Advanced',
+    core: false,
     description: 'Show version',
     usage: 'construct version',
   },
+  {
+    name: 'cleanup',
+    emoji: '🧹',
+    category: 'Advanced',
+    core: false,
+    description: 'Clean stale processes',
+    usage: 'construct cleanup',
+  },
+  {
+    name: 'skills',
+    emoji: '🎯',
+    category: 'Advanced',
+    core: false,
+    description: 'Skill relevance detection',
+    usage: 'construct skills scope|apply',
+  },
+  {
+    name: 'hooks:health',
+    emoji: '🩺',
+    category: 'Advanced',
+    core: false,
+    description: 'Check hook health',
+    usage: 'construct hooks:health',
+  },
+  {
+    name: 'gates:audit',
+    emoji: '🛡️',
+    category: 'Advanced',
+    core: false,
+    description: 'Audit policy gates',
+    usage: 'construct gates:audit',
+  },
+  {
+    name: 'provider',
+    emoji: '🔌',
+    category: 'Advanced',
+    core: false,
+    description: 'Provider management',
+    usage: 'construct provider list|test',
+  },
+  {
+    name: 'auth:status',
+    emoji: '🔐',
+    category: 'Advanced',
+    core: false,
+    description: 'Check auth status',
+    usage: 'construct auth:status',
+  },
 ];
 
 /** Flat list of all top-level command names (for completions). */
 export const COMMAND_NAMES = CLI_COMMANDS.map(c => c.name);
 
-/** Commands grouped by category, preserving order within each group. */
+/** 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;
 }, {});
+for (const cat of Object.keys(CLI_COMMANDS_BY_CATEGORY)) {
+  CLI_COMMANDS_BY_CATEGORY[cat].sort((a, b) => a.name.localeCompare(b.name));
+}
 
 /** Canonical category display order. */
 export const CATEGORY_ORDER = [
-  'Services',
-  'Agents & Sync',
+  'Core',
   'Work',
-  'Models & Integrations',
+  'Integrations',
   'Observability',
-  'Docs',
-  'Diagnostics',
+  'Advanced',
 ];
+
+/** 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);
+  return cmd?.core ?? false;
+}
+
+/** 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);
+}