@moda-ai/cli 1.1.1 → 1.2.0

package/dist/cli.js

@@ -1,43 +1,82 @@
 #!/usr/bin/env node
 import { z } from 'zod';
-import { validateConfig, VERSION } from './config.js';
-import { callDataAPI, ApiError } from './api-client.js';
+import { validateConfig, VERSION, resolveApiKey } from './config.js';
+import { callDataAPI, ApiError, getApiRequestCount, resetApiRequestCount, } from './api-client.js';
 import { OverviewSchema, ClustersSchema, ClusterConversationsSchema, ConversationsSchema, ContextSchema, FrustrationsSchema, ToolFailuresSchema, ToolFailureDetailSchema, WorkflowsSchema, RunsSchema, RunDetailSchema, LoopsSchema, LoopDetailSchema, } from './schemas.js';
 import { withFrustrationAnchors, withToolFailureAnchors, embeddedWindowSize, asRecord, asString, asNumber } from './transforms.js';
+import { runPromptsCommand } from './prompts.js';
+import { runHooksInstall, runSparkCommand, runWorkspaceCommand } from './workspace.js';
+import { runSkillsCommand } from './skills.js';
+import { runHarnessCommand } from './harness.js';
+import { runSyncCommand } from './sync.js';
+import { runDoctorCommand, runStatusCommand } from './doctor.js';
+import { CliInputError } from './errors.js';
+import { isTelemetryDisabled, sendCliUsageTelemetry, stripTelemetryFlag, } from './telemetry.js';
+import { createCommandContext } from './command-context.js';
+import { createCommandRegistry } from './command-registry.js';
+import { createAgentErrorEnvelope, errorToAgentError, outputModeFromFlags, } from './output.js';
+import { runAuthCommand, runConfigCommand, runKeysCommand, runProfilesCommand } from './profile-commands.js';
+import { runAgentCommand } from './agent.js';
+import { runProductionCommand } from './production-intelligence.js';
+export { CliInputError } from './errors.js';
 export function parseArgs(argv) {
     const args = argv.slice(2);
-    const command = args[0] || '';
+    let command = '';
     const flags = {};
+    const positionals = [];
     let positional;
-    let i = 1;
+    let i = 0;
     while (i < args.length) {
         const arg = args[i];
         if (arg.startsWith('--')) {
-            const eqIndex = arg.indexOf('=');
-            if (eqIndex !== -1) {
-                // --key=value
-                const key = arg.slice(2, eqIndex);
-                flags[key] = arg.slice(eqIndex + 1);
-            }
-            else {
-                // --key value
-                const key = arg.slice(2);
-                const next = args[i + 1];
-                if (next !== undefined && !next.startsWith('--')) {
-                    flags[key] = next;
-                    i++;
-                }
-                else {
-                    flags[key] = 'true';
-                }
-            }
+            i = parseFlag(args, i, flags, command === '');
+        }
+        else if (command === '') {
+            command = arg;
         }
         else if (positional === undefined) {
             positional = arg;
+            positionals.push(arg);
+        }
+        else {
+            positionals.push(arg);
         }
         i++;
     }
-    return { command, positional, flags };
+    return { command, positional, positionals, flags };
+}
+const GLOBAL_BOOLEAN_FLAGS = new Set([
+    'agent',
+    'json',
+    'help',
+    'version',
+    'quiet',
+    'verbose',
+    'yes',
+    'dry-run',
+    'stream',
+    'tui',
+    'no-tui',
+]);
+function parseFlag(args, index, flags, beforeCommand) {
+    const arg = args[index];
+    const eqIndex = arg.indexOf('=');
+    if (eqIndex !== -1) {
+        flags[arg.slice(2, eqIndex)] = arg.slice(eqIndex + 1);
+        return index;
+    }
+    const key = arg.slice(2);
+    const next = args[index + 1];
+    if (beforeCommand && GLOBAL_BOOLEAN_FLAGS.has(key)) {
+        flags[key] = 'true';
+        return index;
+    }
+    if (next !== undefined && !next.startsWith('--')) {
+        flags[key] = next;
+        return index + 1;
+    }
+    flags[key] = 'true';
+    return index;
 }
 // Convert kebab-case flags to snake_case for Zod schema compatibility
 export function flagsToArgs(flags, positionalKey, positionalValue) {
@@ -59,7 +98,39 @@ function printHelp() {
 
 Commands:
   init                             Set up Moda in your project
-  overview                         Dashboard overview with KPIs
+  status                           Show concise local Moda setup status
+  doctor                           Diagnose local Moda setup and data flow
+  auth login                       Authenticate with Moda
+  auth logout                      Clear cached Moda auth
+  auth whoami                      Show the authenticated Moda user
+  profiles list                    List local Moda profiles
+  profiles use <name>              Switch active Moda profile
+  profiles create <name>           Create or update a local Moda profile
+  profiles doctor [name]           Validate a local Moda profile
+  keys list                        List local key descriptors
+  keys create                      Create a local key descriptor
+  config show                      Show resolved Moda config
+  harness analyze                  Produce a cited structured harness report
+  harness validate-report          Validate .moda/harness-report.json citations
+  harness approve                  Approve a validated harness report for sync
+  harness scan                     Discover local runtime agents and write .moda/harness.json
+  harness sync                     Sync the local harness graph to Moda Cloud
+  harness agents                   List detected runtime agents and families
+  harness explain                  Explain the discovered harness graph
+  agent context                    Emit local Moda context for coding agents
+  agent investigate                Diagnose local Moda readiness for agents
+  agent next-action                Emit prioritized next commands for agents
+  agent evidence <ref>             Expand one evidence reference
+  investigate                      Rank production issues with evidence
+  failures                         Show production failures worth fixing first
+  why-failed <run_id>              Explain a failed or partial production run
+  ask "question"                   Ask Moda a production/harness question
+  sync                             Sync the local harness graph to Moda Cloud
+  sync harness                     Sync the local harness graph to Moda Cloud
+  sync prompts                     Sync prompt versions to Moda Cloud
+  doctor --json                    Emit structured diagnostic checks
+  status --json                    Emit concise setup state
+  overview                         Harness health briefing with production signals
   clusters                         Browse topic cluster hierarchy
   cluster-conversations <node_id>  List conversations in a cluster
   conversations                    Search and filter conversations
@@ -75,6 +146,38 @@ Commands:
   loops                            Currently-active loop detections
   loop <detection_id>              Single loop detail
 
+  Prompt management:
+  prompts init                     Create .moda/prompts.yml
+  prompts status                   Show local prompt changes
+  prompts diff                     Show local prompt changes
+  prompts sync                     Upload changed prompt versions
+  prompts sync --watch             Upload again when prompt files change
+  prompts promote <key>            Move a dev/staging/prod label
+
+  Shadow workspace:
+  spark status                     Show Shadow Spark workspace state
+  spark explain                    Explain what Shadow Spark captures and posts
+  spark snapshot                   Manual / hook-invoked Shadow Spark snapshot
+  spark snapshot --dry-run         Show file inventory without copy/commit/post
+  spark log                        Show Shadow Spark history
+  spark bundle                     Bundle a shadow commit range for replay
+  spark remove --yes               Delete this repo's local shadow workspace
+  workspace init                   Create shadow workspace for current repo
+  workspace snapshot               Manual / hook-invoked sync + shadow commit
+  workspace status                 Show shadow workspace state
+  workspace explain                Explain shadow workspace behavior
+  workspace log                    Show Moda shadow history (not user git log)
+  workspace bundle                 Bundle a shadow commit range for replay
+  hooks install                    Install Claude Code shadow-workspace hooks
+  hooks install --agent=codex      Install Codex hooks
+  hooks install --agent=cursor     Install Cursor hooks
+  hooks install --agent=all        Install Claude Code, Codex, and Cursor hooks
+
+  Skills:
+  skills gen                       Kick off tenant-wide skill generation
+  skills pull                      Pull tenant-generated skills into .claude/skills (and .cursor/rules)
+  skills pull --status=proposed    Include not-yet-promoted skills (default: approved)
+
 Options:
   --help                           Show this help message
   --version                        Show version number
@@ -84,6 +187,14 @@ Common flags:
   --limit=N                        Maximum results to return
   --offset=N                       Number of results to skip
   --time-range=RANGE               Time range filter (all|1h|3d|7d|24h|30d|90d)
+  --profile=NAME                   Use a named local Moda profile
+  --json                           Emit machine-readable JSON
+  --agent                          Emit schema-versioned agent JSON
+  --stream                         With --agent, emit NDJSON agent events
+  --dry-run                        Show the planned mutation when supported
+  --yes                            Accept explicit automation defaults
+  --tui                            Force the human analyst dashboard when supported
+  --no-tui                         Show raw analyst stream instead of dashboard
 
 Runs flags:
   --outcome=OUTCOME                Filter by outcome (running|succeeded|partial|failed|loop|abandoned|unknown)
@@ -92,9 +203,47 @@ Runs flags:
 
 Init flags:
   --yes                            Accept all defaults (non-interactive)
+  --analyst=auto|claude|codex|cursor|local-scan
+                                   Choose harness analyst adapter
+  --tui                            Show full-screen analyst dashboard in human TTYs
+  --no-tui                         Show raw external analyst output
+  --coding-agent-traces            Install Claude/Codex/Cursor trace hooks
+  --no-coding-agent-traces         Skip Claude/Codex/Cursor trace hook installation
+  --sdk-guide                      Write .moda/SDK_INTEGRATION.md
+  --no-sdk-guide                   Skip SDK integration guide creation
+  --ci-cd                          Create GitHub Actions Moda validation workflow
+  --no-ci-cd                       Skip CI/CD workflow creation
 
 Examples:
   moda init
+  moda status
+  moda doctor --json
+  moda profiles list
+  moda profiles use staging
+  moda config show --profile=prod
+  moda harness analyze --summary
+  moda harness analyze --analyst=claude --tui
+  moda harness analyze --analyst=claude --no-tui
+  moda harness analyze --analyst=claude --summary
+  moda harness analyze --analyst=local-scan --summary
+  moda harness validate-report
+  moda harness approve --yes
+  moda harness sync --from-report .moda/harness-report.json
+  moda --agent doctor
+  moda agent context
+  moda agent next-action
+  moda agent evidence doctor:harness_report_approved_synced
+  moda investigate
+  moda failures
+  moda why-failed 12345678-1234-1234-1234-1234567890ab
+  moda ask "what should I fix first?"
+  moda sync --dry-run
+  moda sync harness --profile=prod
+  moda harness scan --json
+  moda harness explain --agent=agent_support
+  moda init --coding-agent-traces
+  moda init --no-coding-agent-traces
+  moda init --ci-cd
   moda overview --days-back=30
   moda clusters --time-range=7d
   moda conversations --search="error" --limit=5
@@ -105,7 +254,16 @@ Examples:
   moda runs --class-id=cron:helpscout-triage-hourly --limit=20
   moda run 12345678-1234-1234-1234-1234567890ab
   moda loops --limit=10
-  moda loop 12345678-1234-1234-1234-1234567890ab`);
+  moda loop 12345678-1234-1234-1234-1234567890ab
+  moda prompts status
+  moda prompts sync
+  moda prompts promote support.triage --label=prod --version=pver_abc123
+  moda spark explain
+  moda spark snapshot --dry-run --json
+  moda workspace snapshot --json
+  moda hooks install
+  moda hooks install --agent=all
+  moda skills pull`);
 }
 // --- Command Handlers ---
 async function attachWindows(rows, windowSize) {
@@ -141,25 +299,37 @@ async function attachWindows(rows, windowSize) {
         }
     }));
 }
-async function printWithOptionalWindows(enriched, listKey, includeWindow, windowSize) {
+async function printWithOptionalWindows(enriched, listKey, includeWindow, windowSize, output) {
     if (!includeWindow) {
-        console.log(JSON.stringify(enriched, null, 2));
+        output.writeData(enriched);
         return;
     }
     const list = Array.isArray(enriched[listKey])
         ? enriched[listKey]
         : [];
     const withWindows = await attachWindows(list, windowSize);
-    console.log(JSON.stringify({ ...enriched, [listKey]: withWindows }, null, 2));
+    output.writeData({ ...enriched, [listKey]: withWindows });
 }
-export async function runCommand(command, positional, flags) {
+export async function runCommand(command, positional, flags, positionals = positional ? [positional] : [], context = createCommandContext({ command, positional, positionals, flags })) {
     switch (command) {
+        case 'prompts': {
+            await runPromptsCommand(positionals, flags, {
+                profile: context.profile,
+                env: context.env,
+            });
+            break;
+        }
         case 'overview': {
             const args = flagsToArgs(flags);
-            const params = OverviewSchema.parse(args);
-            const queryString = params.days_back ? `?days_back=${params.days_back}` : '';
-            const data = await callDataAPI(`/overview${queryString}`);
-            console.log(JSON.stringify(data, null, 2));
+            OverviewSchema.parse(args);
+            await runProductionCommand(context);
+            break;
+        }
+        case 'investigate':
+        case 'failures':
+        case 'why-failed':
+        case 'ask': {
+            await runProductionCommand(context);
             break;
         }
         case 'clusters': {
@@ -172,14 +342,12 @@ export async function runCommand(command, positional, flags) {
                 query.set('time_range', params.time_range);
             const queryString = query.toString() ? `?${query.toString()}` : '';
             const data = await callDataAPI(`/clusters${queryString}`);
-            console.log(JSON.stringify(data, null, 2));
+            context.output.writeData(data);
             break;
         }
         case 'cluster-conversations': {
             if (!positional) {
-                console.error('Error: <node_id> is required');
-                console.error('Usage: moda cluster-conversations <node_id> [--limit=N] [--offset=N]');
-                process.exit(1);
+                throw new CliInputError('<node_id> is required', 'Usage: moda cluster-conversations <node_id> [--limit=N] [--offset=N]');
             }
             const args = flagsToArgs(flags, 'node_id', positional);
             const params = ClusterConversationsSchema.parse(args);
@@ -190,7 +358,7 @@ export async function runCommand(command, positional, flags) {
                 query.set('offset', params.offset.toString());
             const queryString = query.toString() ? `?${query.toString()}` : '';
             const data = await callDataAPI(`/clusters/${params.node_id}/conversations${queryString}`);
-            console.log(JSON.stringify(data, null, 2));
+            context.output.writeData(data);
             break;
         }
         case 'conversations': {
@@ -213,14 +381,12 @@ export async function runCommand(command, positional, flags) {
                 query.set('offset', params.offset.toString());
             const queryString = query.toString() ? `?${query.toString()}` : '';
             const data = await callDataAPI(`/conversations${queryString}`);
-            console.log(JSON.stringify(data, null, 2));
+            context.output.writeData(data);
             break;
         }
         case 'context': {
             if (!positional) {
-                console.error('Error: <conversation_id> is required');
-                console.error('Usage: moda context <conversation_id> [--msg-index=N] [--window=N]');
-                process.exit(1);
+                throw new CliInputError('<conversation_id> is required', 'Usage: moda context <conversation_id> [--msg-index=N] [--window=N]');
             }
             const args = flagsToArgs(flags, 'conversation_id', positional);
             const params = ContextSchema.parse(args);
@@ -231,7 +397,7 @@ export async function runCommand(command, positional, flags) {
                 query.set('window', params.window.toString());
             const queryString = query.toString() ? `?${query.toString()}` : '';
             const data = await callDataAPI(`/conversations/${params.conversation_id}/context${queryString}`);
-            console.log(JSON.stringify(data, null, 2));
+            context.output.writeData(data);
             break;
         }
         case 'frustrations': {
@@ -246,7 +412,7 @@ export async function runCommand(command, positional, flags) {
                 query.set('offset', params.offset.toString());
             const queryString = query.toString() ? `?${query.toString()}` : '';
             const data = await callDataAPI(`/frustrations${queryString}`);
-            await printWithOptionalWindows(withFrustrationAnchors(data), 'frustrations', params.include_window === true, params.window ?? 1);
+            await printWithOptionalWindows(withFrustrationAnchors(data), 'frustrations', params.include_window === true, params.window ?? 1, context.output);
             break;
         }
         case 'tool-failures': {
@@ -254,14 +420,12 @@ export async function runCommand(command, positional, flags) {
             const params = ToolFailuresSchema.parse(args);
             const queryString = params.days_back ? `?days_back=${params.days_back}` : '';
             const data = await callDataAPI(`/tool-failures${queryString}`);
-            console.log(JSON.stringify(data, null, 2));
+            context.output.writeData(data);
             break;
         }
         case 'tool-failure-detail': {
             if (!positional) {
-                console.error('Error: <tool_name> is required');
-                console.error('Usage: moda tool-failure-detail <tool_name> [--subtype=S] [--days-back=N] [--limit=N] [--offset=N]');
-                process.exit(1);
+                throw new CliInputError('<tool_name> is required', 'Usage: moda tool-failure-detail <tool_name> [--subtype=S] [--days-back=N] [--limit=N] [--offset=N]');
             }
             const args = flagsToArgs(flags, 'tool_name', positional);
             const params = ToolFailureDetailSchema.parse(args);
@@ -276,7 +440,7 @@ export async function runCommand(command, positional, flags) {
                 query.set('offset', params.offset.toString());
             const queryString = query.toString() ? `?${query.toString()}` : '';
             const data = await callDataAPI(`/tool-failures/${params.tool_name}${queryString}`);
-            await printWithOptionalWindows(withToolFailureAnchors(data), 'examples', params.include_window === true, params.window ?? 1);
+            await printWithOptionalWindows(withToolFailureAnchors(data), 'examples', params.include_window === true, params.window ?? 1, context.output);
             break;
         }
         // ─── Workflows + Runs ──────────────────────────────────────
@@ -290,7 +454,7 @@ export async function runCommand(command, positional, flags) {
                 query.set('user_id', params.user_id);
             const queryString = query.toString() ? `?${query.toString()}` : '';
             const data = await callDataAPI(`/workflows${queryString}`);
-            console.log(JSON.stringify(data, null, 2));
+            context.output.writeData(data);
             break;
         }
         case 'runs': {
@@ -311,19 +475,17 @@ export async function runCommand(command, positional, flags) {
                 query.set('offset', params.offset.toString());
             const queryString = query.toString() ? `?${query.toString()}` : '';
             const data = await callDataAPI(`/runs${queryString}`);
-            console.log(JSON.stringify(data, null, 2));
+            context.output.writeData(data);
             break;
         }
         case 'run': {
             if (!positional) {
-                console.error('Error: <run_id> is required');
-                console.error('Usage: moda run <run_id>');
-                process.exit(1);
+                throw new CliInputError('<run_id> is required', 'Usage: moda run <run_id>');
             }
             const args = flagsToArgs(flags, 'run_id', positional);
             const params = RunDetailSchema.parse(args);
             const data = await callDataAPI(`/runs/${params.run_id}`);
-            console.log(JSON.stringify(data, null, 2));
+            context.output.writeData(data);
             break;
         }
         case 'loops': {
@@ -334,47 +496,575 @@ export async function runCommand(command, positional, flags) {
                 query.set('limit', params.limit.toString());
             const queryString = query.toString() ? `?${query.toString()}` : '';
             const data = await callDataAPI(`/loops/active${queryString}`);
-            console.log(JSON.stringify(data, null, 2));
+            context.output.writeData(data);
             break;
         }
         case 'loop': {
             if (!positional) {
-                console.error('Error: <detection_id> is required');
-                console.error('Usage: moda loop <detection_id>');
-                process.exit(1);
+                throw new CliInputError('<detection_id> is required', 'Usage: moda loop <detection_id>');
             }
             const args = flagsToArgs(flags, 'detection_id', positional);
             const params = LoopDetailSchema.parse(args);
             const data = await callDataAPI(`/loops/${params.detection_id}`);
-            console.log(JSON.stringify(data, null, 2));
+            context.output.writeData(data);
             break;
         }
         default:
-            console.error(`Error: Unknown command '${command}'`);
-            console.error('Run "moda --help" for usage information.');
-            process.exit(1);
+            throw new CliInputError(`Unknown command '${command}'`, 'Run "moda --help" for usage information.');
     }
 }
+function legacyCommand(metadata) {
+    return {
+        ...metadata,
+        handler: async (context) => {
+            await runCommand(context.command, context.positional, context.flags, context.positionals, context);
+            return { exitCode: 0 };
+        },
+    };
+}
+function initAgentWriteOptions(result) {
+    const changedFiles = initChangedFiles(result.setupPlan);
+    const manualActions = result.setupPlan.filter((action) => action.status === 'manual' || action.status === 'skipped');
+    return {
+        summary: {
+            text: `Moda init completed for ${result.tenantName}. ${changedFiles.length} artifact(s) were created or verified.`,
+            confidence: 'high',
+        },
+        findings: result.phases.map((phase) => ({
+            id: `init:${phase.id}`,
+            title: phase.title,
+            status: phase.status,
+            description: phase.details,
+        })),
+        recommendedActions: manualActions.map((action) => ({
+            id: `init:action:${action.category}`,
+            title: action.title,
+            rationale: action.reason,
+            command: action.command,
+            mutability: action.command?.includes(' sync') ? 'sync' : 'write',
+            requires_approval: true,
+        })),
+        nextCommands: [
+            {
+                command: 'moda status',
+                purpose: 'Inspect the local Moda setup state.',
+                mutability: 'read',
+                requires_approval: false,
+            },
+            {
+                command: 'moda doctor',
+                purpose: 'Diagnose local setup and data-flow readiness.',
+                mutability: 'read',
+                requires_approval: false,
+            },
+            {
+                command: 'moda harness sync --summary',
+                purpose: 'Sync the approved harness graph to Moda Cloud after review.',
+                mutability: 'sync',
+                requires_approval: true,
+            },
+        ],
+        artifacts: changedFiles.map((file) => ({
+            kind: initArtifactKind(file),
+            path: file,
+            description: 'Created or verified during Moda init.',
+        })),
+        warnings: manualActions
+            .filter((action) => action.reason)
+            .map((action) => `${action.title}: ${action.reason}`),
+    };
+}
+function initChangedFiles(setupPlan) {
+    return [...new Set(setupPlan
+            .filter((action) => action.status === 'applied')
+            .flatMap((action) => action.files))].filter((file) => !file.includes('.env'));
+}
+function initArtifactKind(file) {
+    if (file.includes('harness'))
+        return 'harness_artifact';
+    if (file.includes('prompt'))
+        return 'prompt_manifest';
+    if (file.includes('workflow'))
+        return 'ci_workflow';
+    if (file.startsWith('~/'))
+        return 'agent_hook_config';
+    return 'init_artifact';
+}
+const dataApiDefaults = {
+    auth: 'api-key',
+    outputModes: ['human', 'json', 'agent'],
+    mutability: 'read',
+    validateConfigBeforeRun: true,
+    resetApiRequestCountBeforeRun: true,
+    telemetry: 'result-and-error',
+};
+export const commandRegistry = createCommandRegistry([
+    {
+        name: 'init',
+        description: 'Set up Moda in your project',
+        examples: ['moda init', 'moda init --coding-agent-traces', 'moda init --ci-cd'],
+        auth: 'none',
+        outputModes: ['human', 'json', 'agent'],
+        mutability: 'write',
+        validateConfigBeforeRun: false,
+        resetApiRequestCountBeforeRun: true,
+        telemetry: 'result',
+        handler: async (context) => {
+            const { runInit } = await import('./init/index.js');
+            if (context.outputMode === 'agent-stream') {
+                context.output.writeEvent({
+                    event: 'started',
+                    phase: 'init',
+                    message: 'Starting Moda init.',
+                    elapsed_ms: Date.now() - context.startedAt,
+                });
+            }
+            const result = await runInit(flagsToArgs(context.flags), {
+                onEvent: (event) => {
+                    context.output.writeEvent({
+                        event: 'progress',
+                        phase: event.phase,
+                        message: event.message,
+                        elapsed_ms: Date.now() - context.startedAt,
+                    });
+                },
+            });
+            if (context.outputMode !== 'human') {
+                context.output.writeData(result, initAgentWriteOptions(result));
+            }
+            return { exitCode: 0, apiKey: result.apiKey };
+        },
+    },
+    {
+        name: 'auth',
+        description: 'Authenticate and inspect browser auth sessions',
+        examples: ['moda auth login', 'moda auth whoami', 'moda auth logout'],
+        auth: 'none',
+        outputModes: ['human', 'json', 'agent'],
+        mutability: 'write',
+        validateConfigBeforeRun: false,
+        resetApiRequestCountBeforeRun: false,
+        telemetry: 'none',
+        handler: runAuthCommand,
+    },
+    {
+        name: 'status',
+        description: 'Show concise local Moda setup status',
+        examples: ['moda status', 'moda status --json'],
+        auth: 'none',
+        outputModes: ['human', 'json', 'agent'],
+        mutability: 'read',
+        validateConfigBeforeRun: false,
+        resetApiRequestCountBeforeRun: false,
+        telemetry: 'none',
+        handler: runStatusCommand,
+    },
+    {
+        name: 'doctor',
+        description: 'Diagnose local Moda setup and data flow',
+        examples: ['moda doctor', 'moda doctor --json', 'moda doctor --offline'],
+        auth: 'none',
+        outputModes: ['human', 'json', 'agent'],
+        mutability: 'read',
+        validateConfigBeforeRun: false,
+        resetApiRequestCountBeforeRun: false,
+        telemetry: 'none',
+        handler: runDoctorCommand,
+    },
+    {
+        name: 'profiles',
+        description: 'Manage local Moda profiles',
+        examples: ['moda profiles list', 'moda profiles use staging'],
+        auth: 'none',
+        outputModes: ['human', 'json', 'agent'],
+        mutability: 'write',
+        validateConfigBeforeRun: false,
+        resetApiRequestCountBeforeRun: false,
+        telemetry: 'none',
+        handler: runProfilesCommand,
+    },
+    {
+        name: 'config',
+        description: 'Show resolved local Moda configuration',
+        examples: ['moda config show', 'moda config show --profile=prod'],
+        auth: 'none',
+        outputModes: ['human', 'json', 'agent'],
+        mutability: 'read',
+        validateConfigBeforeRun: false,
+        resetApiRequestCountBeforeRun: false,
+        telemetry: 'none',
+        handler: runConfigCommand,
+    },
+    {
+        name: 'keys',
+        description: 'Manage local key descriptors and cloud key lifecycle requirements',
+        examples: ['moda keys list', 'moda keys create --name=local-dev'],
+        auth: 'none',
+        outputModes: ['human', 'json', 'agent'],
+        mutability: 'write',
+        validateConfigBeforeRun: false,
+        resetApiRequestCountBeforeRun: false,
+        telemetry: 'none',
+        handler: runKeysCommand,
+    },
+    {
+        name: 'harness',
+        description: 'Analyze, validate, approve, sync, and explain the local multi-agent harness graph',
+        examples: [
+            'moda harness analyze --summary',
+            'moda harness approve --yes',
+            'moda harness sync --from-report .moda/harness-report.json',
+            'moda harness explain --agent=agent_support',
+        ],
+        auth: 'none',
+        outputModes: ['human', 'json', 'agent'],
+        mutability: 'write',
+        validateConfigBeforeRun: false,
+        resetApiRequestCountBeforeRun: false,
+        telemetry: 'none',
+        handler: runHarnessCommand,
+    },
+    {
+        name: 'agent',
+        description: 'Agent-native Moda context, investigations, next actions, and evidence',
+        examples: [
+            'moda agent context',
+            'moda agent investigate',
+            'moda agent next-action',
+            'moda agent evidence doctor:harness_report_approved_synced',
+        ],
+        auth: 'none',
+        outputModes: ['agent', 'agent-stream', 'json'],
+        mutability: 'read',
+        validateConfigBeforeRun: false,
+        resetApiRequestCountBeforeRun: false,
+        telemetry: 'none',
+        handler: runAgentCommand,
+    },
+    {
+        name: 'sync',
+        description: 'Sync local Moda artifacts to Moda Cloud',
+        examples: [
+            'moda sync --dry-run',
+            'moda sync harness --from-report .moda/harness-report.json',
+            'moda sync prompts',
+        ],
+        auth: 'none',
+        outputModes: ['human', 'json', 'agent'],
+        mutability: 'write',
+        validateConfigBeforeRun: false,
+        resetApiRequestCountBeforeRun: false,
+        telemetry: 'none',
+        handler: runSyncCommand,
+    },
+    legacyCommand({
+        name: 'overview',
+        description: 'Harness health briefing from production data',
+        examples: ['moda overview --days-back=30', 'moda --agent overview'],
+        ...dataApiDefaults,
+    }),
+    legacyCommand({
+        name: 'investigate',
+        description: 'Rank production issues with evidence and next commands',
+        examples: ['moda investigate', 'moda investigate --tool lookupCustomer'],
+        ...dataApiDefaults,
+    }),
+    legacyCommand({
+        name: 'failures',
+        description: 'Show production failures worth fixing first',
+        examples: ['moda failures', 'moda failures --tool lookupCustomer'],
+        ...dataApiDefaults,
+    }),
+    legacyCommand({
+        name: 'why-failed',
+        description: 'Explain a failed or partial production run',
+        examples: ['moda why-failed 12345678-1234-1234-1234-1234567890ab'],
+        ...dataApiDefaults,
+    }),
+    legacyCommand({
+        name: 'ask',
+        description: 'Ask Moda a production intelligence question',
+        examples: ['moda ask "what should I fix first?"', 'moda --agent ask "why did this run fail?"'],
+        ...dataApiDefaults,
+    }),
+    legacyCommand({
+        name: 'clusters',
+        description: 'Browse topic cluster hierarchy',
+        examples: ['moda clusters --time-range=7d'],
+        ...dataApiDefaults,
+    }),
+    legacyCommand({
+        name: 'cluster-conversations',
+        description: 'List conversations in a cluster',
+        examples: ['moda cluster-conversations <node_id> --limit=20'],
+        ...dataApiDefaults,
+    }),
+    legacyCommand({
+        name: 'conversations',
+        description: 'Search and filter conversations',
+        examples: ['moda conversations --search="error" --limit=5'],
+        ...dataApiDefaults,
+    }),
+    legacyCommand({
+        name: 'context',
+        description: 'Get windowed conversation context',
+        examples: ['moda context <conversation_id> --window=3'],
+        ...dataApiDefaults,
+    }),
+    legacyCommand({
+        name: 'frustrations',
+        description: 'Get user frustration detections',
+        examples: ['moda frustrations --days-back=14 --include-window'],
+        ...dataApiDefaults,
+    }),
+    legacyCommand({
+        name: 'tool-failures',
+        description: 'Get tool failure overview',
+        examples: ['moda tool-failures --days-back=14'],
+        ...dataApiDefaults,
+    }),
+    legacyCommand({
+        name: 'tool-failure-detail',
+        description: 'Get per-tool failure detail',
+        examples: ['moda tool-failure-detail search --include-window'],
+        ...dataApiDefaults,
+    }),
+    legacyCommand({
+        name: 'workflows',
+        description: 'Recurring workflow catalog',
+        examples: ['moda workflows --time-range=7d'],
+        ...dataApiDefaults,
+    }),
+    legacyCommand({
+        name: 'runs',
+        description: 'List workflow executions',
+        examples: ['moda runs --time-range=24h --outcome=partial'],
+        ...dataApiDefaults,
+    }),
+    legacyCommand({
+        name: 'run',
+        description: 'Get a single workflow execution',
+        examples: ['moda run 12345678-1234-1234-1234-1234567890ab'],
+        ...dataApiDefaults,
+    }),
+    legacyCommand({
+        name: 'loops',
+        description: 'List currently-active loop detections',
+        examples: ['moda loops --limit=10'],
+        ...dataApiDefaults,
+    }),
+    legacyCommand({
+        name: 'loop',
+        description: 'Get a single loop detection',
+        examples: ['moda loop 12345678-1234-1234-1234-1234567890ab'],
+        ...dataApiDefaults,
+    }),
+    legacyCommand({
+        name: 'prompts',
+        description: 'Manage prompt versions and labels',
+        examples: ['moda prompts status', 'moda prompts sync'],
+        auth: 'api-key',
+        outputModes: ['human', 'json', 'agent'],
+        mutability: 'write',
+        validateConfigBeforeRun: true,
+        resetApiRequestCountBeforeRun: true,
+        telemetry: 'result-and-error',
+    }),
+    {
+        name: 'workspace',
+        description: 'Manage Moda shadow workspace snapshots',
+        examples: ['moda workspace init', 'moda workspace snapshot --json', 'moda workspace explain'],
+        auth: 'none',
+        outputModes: ['human', 'json', 'agent'],
+        mutability: 'write',
+        validateConfigBeforeRun: false,
+        resetApiRequestCountBeforeRun: false,
+        telemetry: 'none',
+        handler: async (context) => ({
+            exitCode: await runWorkspaceCommand({
+                command: context.command,
+                positional: context.positional,
+                positionals: context.positionals,
+                flags: context.flags,
+            }),
+        }),
+    },
+    {
+        name: 'spark',
+        aliases: ['shadow'],
+        description: 'Manage Shadow Spark workspace snapshots',
+        examples: ['moda spark status', 'moda spark explain', 'moda spark snapshot --dry-run --json'],
+        auth: 'none',
+        outputModes: ['human', 'json', 'agent'],
+        mutability: 'write',
+        validateConfigBeforeRun: false,
+        resetApiRequestCountBeforeRun: false,
+        telemetry: 'none',
+        handler: runSparkCommand,
+    },
+    {
+        name: 'hooks',
+        description: 'Install coding-agent trace hooks',
+        examples: ['moda hooks install', 'moda hooks install --agent=all'],
+        auth: 'none',
+        outputModes: ['human', 'json', 'agent'],
+        mutability: 'write',
+        validateConfigBeforeRun: false,
+        resetApiRequestCountBeforeRun: false,
+        telemetry: 'none',
+        handler: async (context) => ({
+            exitCode: await runHooksInstall({
+                command: context.command,
+                positional: context.positional,
+                positionals: context.positionals,
+                flags: context.flags,
+            }),
+        }),
+    },
+    {
+        name: 'skills',
+        description: 'Generate and pull Moda skills',
+        examples: ['moda skills gen', 'moda skills pull'],
+        auth: 'none',
+        outputModes: ['human', 'json', 'agent'],
+        mutability: 'write',
+        validateConfigBeforeRun: false,
+        resetApiRequestCountBeforeRun: false,
+        telemetry: 'result',
+        handler: async (context) => ({
+            exitCode: await runSkillsCommand({
+                command: context.command,
+                positional: context.positional,
+                positionals: context.positionals,
+                flags: context.flags,
+            }),
+        }),
+    },
+]);
 // --- Main ---
-async function main() {
-    const { command, positional, flags } = parseArgs(process.argv);
+export function classifyCliError(error) {
+    if (error instanceof z.ZodError || error instanceof CliInputError) {
+        return 'validation_error';
+    }
+    if (error instanceof ApiError) {
+        return 'api_error';
+    }
+    if (error instanceof Error &&
+        (error.message.startsWith('Network error:') ||
+            error.message.startsWith('Request timed out'))) {
+        return 'network_error';
+    }
+    return 'unknown_error';
+}
+export function printCliError(error) {
+    if (error instanceof CliInputError) {
+        console.error(`Error: ${error.message}`);
+        if (error.usage)
+            console.error(error.usage);
+    }
+    else if (error instanceof z.ZodError) {
+        const issues = error.errors.map((e) => {
+            const field = e.path.length ? e.path.join('.') : 'input';
+            return `  ${field}: ${e.message}`;
+        });
+        console.error(`Validation error:\n${issues.join('\n')}`);
+    }
+    else if (error instanceof ApiError) {
+        console.error(`API error (HTTP ${error.statusCode}): ${error.responseBody || error.message}`);
+    }
+    else if (error instanceof Error) {
+        console.error(`Error: ${error.message}`);
+    }
+    else {
+        console.error('Error:', error);
+    }
+}
+function printAgentCliError(command, error) {
+    console.log(JSON.stringify(createAgentErrorEnvelope(command || 'unknown', errorToAgentError(error))));
+}
+export async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
+    const { command, flags } = parsed;
+    const commandFlags = stripTelemetryFlag(flags);
+    const telemetryDisabled = isTelemetryDisabled(flags);
     if (command === '--version' || command === '-V' || flags.version === 'true') {
         console.log(`moda-cli ${VERSION}`);
-        process.exit(0);
+        return 0;
     }
-    if (!command || command === '--help' || command === '-h' || flags.help === 'true') {
+    if (command === '--help' || command === '-h' || flags.help === 'true') {
         printHelp();
-        process.exit(command ? 0 : 1);
+        return 0;
     }
-    // init does NOT require MODA_API_KEY — that's what it creates
-    if (command === 'init') {
-        const { runInit } = await import('./init/index.js');
-        const initFlags = flagsToArgs(flags);
-        await runInit(initFlags);
-        return;
+    if (!command) {
+        printHelp();
+        return 1;
+    }
+    const definition = commandRegistry.find(command);
+    if (!definition) {
+        const error = new CliInputError(`Unknown command '${command}'`, 'Run "moda --help" for usage information.');
+        if (outputModeFromFlags(commandFlags) === 'agent' || outputModeFromFlags(commandFlags) === 'agent-stream') {
+            printAgentCliError(command, error);
+        }
+        else {
+            printCliError(error);
+        }
+        return 1;
+    }
+    if (definition.name === 'agent' && commandFlags.json !== 'true') {
+        commandFlags.agent = 'true';
+    }
+    if (definition.validateConfigBeforeRun) {
+        validateConfig();
+    }
+    if (definition.resetApiRequestCountBeforeRun) {
+        resetApiRequestCount();
+    }
+    const context = createCommandContext(parsed, {
+        commandName: definition.name,
+        commandFlags,
+        rawFlags: flags,
+        startedAt,
+    });
+    try {
+        const result = await definition.handler(context);
+        if (!telemetryDisabled && definition.telemetry !== 'none') {
+            void sendCliUsageTelemetry({
+                apiKey: result.apiKey ?? resolveApiKey(),
+                command: definition.name,
+                flags: commandFlags,
+                status: result.exitCode === 0 ? 'success' : 'error',
+                exitCode: result.exitCode,
+                durationMs: Date.now() - startedAt,
+                apiRequestCount: getApiRequestCount(),
+            });
+        }
+        return result.exitCode;
+    }
+    catch (error) {
+        if (!telemetryDisabled && definition.telemetry === 'result-and-error') {
+            void sendCliUsageTelemetry({
+                apiKey: resolveApiKey(),
+                command: definition.name,
+                flags: commandFlags,
+                status: 'error',
+                errorType: classifyCliError(error),
+                exitCode: 1,
+                durationMs: Date.now() - startedAt,
+                apiRequestCount: getApiRequestCount(),
+            });
+        }
+        if (context.outputMode === 'agent' || context.outputMode === 'agent-stream') {
+            printAgentCliError(definition.name, error);
+        }
+        else {
+            printCliError(error);
+        }
+        return 1;
     }
-    validateConfig();
-    await runCommand(command, positional, flags);
+}
+async function main() {
+    // Set exitCode (don't process.exit) so any in-flight telemetry request
+    // can resolve before Node drains its event loop and exits naturally.
+    process.exitCode = await dispatchParsedCommand(parseArgs(process.argv));
 }
 // Only run main() when this file is executed directly (not when imported as a module).
 import { fileURLToPath } from 'url';
@@ -383,23 +1073,8 @@ const isMain = process.argv[1] &&
     fileURLToPath(import.meta.url) === realpathSync(process.argv[1]);
 if (isMain) {
     main().catch((error) => {
-        if (error instanceof z.ZodError) {
-            const issues = error.errors.map((e) => {
-                const field = e.path.length ? e.path.join('.') : 'input';
-                return `  ${field}: ${e.message}`;
-            });
-            console.error(`Validation error:\n${issues.join('\n')}`);
-        }
-        else if (error instanceof ApiError) {
-            console.error(`API error (HTTP ${error.statusCode}): ${error.responseBody || error.message}`);
-        }
-        else if (error instanceof Error) {
-            console.error(`Error: ${error.message}`);
-        }
-        else {
-            console.error('Error:', error);
-        }
-        process.exit(1);
+        printCliError(error);
+        process.exitCode = 1;
     });
 }
 //# sourceMappingURL=cli.js.map