@moda-ai/cli 1.3.0 → 1.6.0

package/dist/cli.js

@@ -14,6 +14,7 @@ import { runSyncCommand } from './sync.js';
 import { runDoctorCommand, runStatusCommand } from './doctor.js';
 import { CliInputError } from './errors.js';
 import { isTelemetryDisabled, sendCliUsageTelemetry, stripTelemetryFlag, } from './telemetry.js';
+import { isUpdateCheckDisabled, printUpdateNotice, startUpdateCheck, stripUpdateCheckFlag, } from './update-check.js';
 import { createCommandContext } from './command-context.js';
 import { createCommandRegistry } from './command-registry.js';
 import { createAgentErrorEnvelope, errorToAgentError, outputModeFromFlags, } from './output.js';
@@ -160,6 +161,8 @@ Commands:
   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)
+  skills sync                      Push local .claude/skills/**/SKILL.md up to Moda
+  skills sync --dry-run            Show what would be pushed without writing
 
 Options:
   --help                           Show this help message
@@ -178,6 +181,7 @@ Common flags:
   --yes                            Accept explicit automation defaults
   --tui                            Force the human analyst dashboard when supported
   --no-tui                         Show raw analyst stream instead of dashboard
+  --no-update-check                Skip the daily new-version check (or MODA_CLI_UPDATE_CHECK=0)
 
 Runs flags:
   --outcome=OUTCOME                Filter by outcome (running|succeeded|partial|failed|loop|abandoned|unknown)
@@ -190,10 +194,11 @@ Init flags:
                                    Choose harness analyst adapter
   --tui                            Show full-screen analyst dashboard in human TTYs
   --no-tui                         Show raw external analyst output
-  --sdk-guide                      Write .moda/SDK_INTEGRATION.md
-  --no-sdk-guide                   Skip SDK integration guide creation
+  --sdk-integrate                  Run your coding agent to install the Moda SDK and instrument LLM calls
+  --no-sdk-integrate               Skip SDK integration (alias: --no-sdk-guide)
   --ci-cd                          Create GitHub Actions Moda validation workflow
   --no-ci-cd                       Skip CI/CD workflow creation
+  --offline                        Run final validation offline (skip the online telemetry check)
 
 Examples:
   moda init
@@ -576,7 +581,7 @@ 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'],
+        examples: ['moda init', 'moda init --sdk-integrate', 'moda init --ci-cd'],
         auth: 'none',
         outputModes: ['human', 'json', 'agent'],
         mutability: 'write',
@@ -900,8 +905,8 @@ export const commandRegistry = createCommandRegistry([
     // },
     {
         name: 'skills',
-        description: 'Generate and pull Moda skills',
-        examples: ['moda skills gen', 'moda skills pull'],
+        description: 'Generate, pull, and sync Moda skills',
+        examples: ['moda skills gen', 'moda skills pull', 'moda skills sync'],
         auth: 'none',
         outputModes: ['human', 'json', 'agent'],
         mutability: 'write',
@@ -961,8 +966,9 @@ function printAgentCliError(command, error) {
 }
 export async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
     const { command, flags } = parsed;
-    const commandFlags = stripTelemetryFlag(flags);
+    const commandFlags = stripUpdateCheckFlag(stripTelemetryFlag(flags));
     const telemetryDisabled = isTelemetryDisabled(flags);
+    const updateCheckDisabled = isUpdateCheckDisabled(flags);
     if (command === '--version' || command === '-V' || flags.version === 'true') {
         console.log(`moda-cli ${VERSION}`);
         return 0;
@@ -989,6 +995,11 @@ export async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
     if (definition.name === 'agent' && commandFlags.json !== 'true') {
         commandFlags.agent = 'true';
     }
+    // Kick off the registry check before the handler so the (at most daily)
+    // request overlaps with command work instead of delaying exit.
+    if (!updateCheckDisabled) {
+        void startUpdateCheck();
+    }
     if (definition.validateConfigBeforeRun) {
         validateConfig();
     }
@@ -1014,6 +1025,9 @@ export async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
                 apiRequestCount: getApiRequestCount(),
             });
         }
+        if (!updateCheckDisabled) {
+            printUpdateNotice();
+        }
         return result.exitCode;
     }
     catch (error) {
@@ -1035,6 +1049,9 @@ export async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
         else {
             printCliError(error);
         }
+        if (!updateCheckDisabled) {
+            printUpdateNotice();
+        }
         return 1;
     }
 }

package/dist/harness.d.ts

@@ -222,9 +222,40 @@ export interface HarnessSyncState {
     privacy: string[];
     written: string[];
 }
+type HarnessAnalystAdapter = 'claude' | 'codex' | 'cursor' | 'local-scan';
+type ExternalHarnessAnalystAdapter = Exclude<HarnessAnalystAdapter, 'local-scan'>;
+export type CodingAgentMode = 'read-only' | 'write';
 export declare function runHarnessCommand(context: CommandContext): Promise<{
     exitCode: number;
 }>;
+export type CodingAgentAdapter = ExternalHarnessAnalystAdapter;
+export interface CodingAgentRun {
+    adapter: CodingAgentAdapter;
+    command: string;
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    failedToStart: boolean;
+}
+/** Coding-agent CLIs found on PATH, ranked best-first (claude > codex > cursor). */
+export declare function detectAvailableCodingAgents(): Array<{
+    adapter: CodingAgentAdapter;
+    command: string;
+}>;
+export declare function codingAgentDisplayName(adapter: CodingAgentAdapter): string;
+/** Spawn an installed coding-agent CLI with a prompt; capture its output. */
+export declare function runCodingAgent(options: {
+    adapter: CodingAgentAdapter;
+    prompt: string;
+    rootDir: string;
+    mode: CodingAgentMode;
+    env?: NodeJS.ProcessEnv;
+    stream?: boolean;
+    timeoutMs?: number;
+    progressToStderr?: boolean;
+    onProgress?: (message: string, phase?: string) => void;
+}): Promise<CodingAgentRun>;
 export declare function scanHarness(options?: ScanOptions): HarnessGraph;
 export declare function summarizeHarness(graph: HarnessGraph): HarnessSummary;
 export declare function readHarnessSyncState(rootDir: string): HarnessSyncState | undefined;

package/dist/harness.js

@@ -1215,6 +1215,7 @@ function normalizeAnalystAdapter(raw) {
     throw new CliInputError(`Unknown harness analyst '${raw}'.`, 'Use `--analyst=claude|codex|cursor|local-scan`.');
 }
 function resolveExternalHarnessAnalystInvocation(options) {
+    const mode = options.mode ?? 'read-only';
     const override = options.flags['analyst-command'] || process.env.MODA_HARNESS_ANALYST_COMMAND;
     if (override) {
         const [command, ...args] = splitCommandLine(override);
@@ -1229,16 +1230,19 @@ function resolveExternalHarnessAnalystInvocation(options) {
     }
     if (options.adapter === 'claude') {
         const extraArgs = externalAnalystExtraArgs(options.adapter);
+        // Write mode auto-accepts edits and unblocks the tools an integration needs
+        // (Edit/Write/Bash for package installs); read-only stays in plan mode with a
+        // safe-Bash allowlist so the harness analyst can never mutate the tree.
+        const permission = mode === 'write'
+            ? ['--permission-mode', 'acceptEdits', '--allowedTools', 'Read,Grep,Glob,Edit,Write,Bash']
+            : ['--permission-mode', 'plan', '--allowedTools', 'Read,Grep,Glob,Bash(pwd),Bash(ls *),Bash(find *),Bash(rg *),Bash(grep *),Bash(cat *),Bash(git status *),Bash(git ls-files *),Bash(git grep *)'];
         return {
             adapter: options.adapter,
             command,
             args: [
                 '--print',
                 ...extraArgs,
-                '--permission-mode',
-                'plan',
-                '--allowedTools',
-                'Read,Grep,Glob,Bash(pwd),Bash(ls *),Bash(find *),Bash(rg *),Bash(grep *),Bash(cat *),Bash(git status *),Bash(git ls-files *),Bash(git grep *)',
+                ...permission,
                 ...(options.stream ? ['--verbose'] : []),
                 '--output-format',
                 options.stream ? 'stream-json' : 'text',
@@ -1256,7 +1260,7 @@ function resolveExternalHarnessAnalystInvocation(options) {
                 'exec',
                 '--skip-git-repo-check',
                 '--sandbox',
-                'read-only',
+                mode === 'write' ? 'workspace-write' : 'read-only',
                 ...(options.stream ? ['--json'] : []),
                 '-C',
                 options.rootDir,
@@ -1271,10 +1275,7 @@ function resolveExternalHarnessAnalystInvocation(options) {
         args: cursorSubcommandArgs(command, [
             '--print',
             '--trust',
-            '--mode',
-            'plan',
-            '--sandbox',
-            'enabled',
+            ...(mode === 'write' ? ['--force'] : ['--mode', 'plan', '--sandbox', 'enabled']),
             '--workspace',
             options.rootDir,
             '--output-format',
@@ -1284,6 +1285,49 @@ function resolveExternalHarnessAnalystInvocation(options) {
         streamEvents: options.stream,
     };
 }
+/** Coding-agent CLIs found on PATH, ranked best-first (claude > codex > cursor). */
+export function detectAvailableCodingAgents() {
+    return rankHarnessAnalysts(detectAvailableHarnessAnalysts());
+}
+export function codingAgentDisplayName(adapter) {
+    return analystDisplayName(adapter);
+}
+/** Spawn an installed coding-agent CLI with a prompt; capture its output. */
+export async function runCodingAgent(options) {
+    const stream = options.stream ?? false;
+    const invocation = resolveExternalHarnessAnalystInvocation({
+        adapter: options.adapter,
+        flags: {},
+        prompt: options.prompt,
+        rootDir: options.rootDir,
+        stream,
+        mode: options.mode,
+    });
+    const timeoutMs = options.timeoutMs ?? numericEnv('MODA_HARNESS_ANALYST_TIMEOUT_MS', 20 * 60 * 1000);
+    const result = await runExternalAnalystWithRetries(invocation, {
+        cwd: options.rootDir,
+        env: buildExternalAnalystEnv(options.env ?? process.env),
+        inheritedOutput: false,
+        timeoutMs,
+        maxBuffer: 20 * 1024 * 1024,
+        progress: Boolean(options.onProgress) || Boolean(options.progressToStderr),
+        progressToStderr: options.progressToStderr ?? false,
+        streamEvents: stream,
+        adapter: invocation.adapter,
+        maxAttempts: externalAnalystMaxAttempts(options.adapter),
+        backoffMs: numericEnvAllowZero('MODA_HARNESS_ANALYST_RETRY_BACKOFF_MS', 6_000),
+        onProgress: options.onProgress,
+    });
+    return {
+        adapter: invocation.adapter,
+        command: invocation.command,
+        status: result.status,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        timedOut: result.timedOut,
+        failedToStart: Boolean(result.error),
+    };
+}
 function externalAnalystExtraArgs(adapter) {
     return splitCommandLine(process.env[`MODA_HARNESS_ANALYST_${adapter.toUpperCase()}_ARGS`] ?? '');
 }

package/dist/init/index.js

@@ -6,15 +6,16 @@ import { login, loadToken } from '../auth.js';
 import { selectTenantAndCreateKey } from './tenant.js';
 import { detectAgents } from './mcp.js';
 import { installRules } from './rules.js';
-import { initPrompts } from '../prompts.js';
-import { pullSkills } from '../skills.js';
+import { initPrompts, runPromptSync } from '../prompts.js';
+import { runSkillSync } from '../skills.js';
 // Coding-agent capture is temporarily disabled — see the hooks phase below.
 // import { runHooksInstall } from '../workspace.js';
 import { SDK_GUIDE_PATH, writeSdkIntegrationGuide } from './sdk-guide.js';
+import { runSdkIntegration } from './sdk-integration.js';
 import { createCommandContext } from '../command-context.js';
 import { CliInputError } from '../errors.js';
 import { runHarnessCommand } from '../harness.js';
-import { runDoctorCommand } from '../doctor.js';
+import { buildDoctorReport } from '../doctor.js';
 import { renderInitBanner, renderInitComplete, renderInitNote, renderInitSetupPlan, renderInitStep, } from '../tui.js';
 export async function runInit(flags, options = {}) {
     const explicitYes = flags.yes === true ||
@@ -30,9 +31,7 @@ export async function runInit(flags, options = {}) {
         if (human)
             console.log(message);
     };
-    // `warn` is only used by the temporarily-disabled hooks phase below; keep the
-    // underscore-prefixed binding so re-enabling it is a rename away.
-    const _warn = (message) => {
+    const warn = (message) => {
         if (human)
             console.error(message);
     };
@@ -102,6 +101,32 @@ export async function runInit(flags, options = {}) {
     if (human)
         printHarnessDetectionSummary();
     emit('harness', 'Harness discovery complete.', 'completed');
+    // Upload the cited harness graph so Moda's backend has the understanding, not
+    // just local artifacts. `harness sync --from-report` refuses an unapproved
+    // report, so approve it first. Best-effort: a network blip on either call must
+    // not abort onboarding — auth + key provisioning already succeeded.
+    try {
+        await runHarnessCommand(createCommandContext({
+            command: 'harness',
+            positional: 'approve',
+            positionals: ['approve'],
+            flags: commandFlags({ yes: true, json: json || agent, agent, quiet: true, 'no-telemetry': true }),
+        }));
+        await runHarnessCommand(createCommandContext({
+            command: 'harness',
+            positional: 'sync',
+            positionals: ['sync'],
+            flags: commandFlags({ 'from-report': true, yes: true, json: json || agent, agent, quiet: true, 'no-telemetry': true }),
+        }));
+        log(renderInitNote('Synced harness graph to Moda'));
+        emit('harness', 'Harness graph synced to Moda.', 'completed');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        warn(renderInitNote(`Harness sync skipped: ${message}`, 'warning'));
+        warn('  Run `moda harness approve --yes && moda harness sync --from-report` later to upload.');
+        emit('harness', 'Harness sync skipped.', 'warning');
+    }
     phases.push({ id: 'harness', title: 'Harness Discovery', status: 'completed' });
     // Step 5: Setup plan
     log(renderInitStep(5, 7, 'Setup Plan', 'Every write/sync action is explicit before it is applied.'));
@@ -109,7 +134,7 @@ export async function runInit(flags, options = {}) {
         // Coding-agent capture is temporarily disabled; never prompt for or install trace hooks.
         // installHooks: await shouldIngestCodingAgentTraces(flags, yes),
         installHooks: false,
-        installSdkGuide: await shouldCreateSdkGuide(flags, yes),
+        integrateSdk: await shouldIntegrateSdk(flags, yes),
         configureCiCd: await shouldConfigureCiCd(flags, yes),
     });
     log(renderInitSetupPlan(setupPlan));
@@ -140,34 +165,69 @@ export async function runInit(flags, options = {}) {
     const agents = detectAgents();
     if (agents.length > 0) {
         log(renderInitNote(`Detected coding agents: ${agents.join(', ')}`));
+        // Install only the moda-cli skill so those agents can query Moda analytics
+        // from the terminal. SDK integration is a one-shot agent run below, not a
+        // persistent skill.
         await installRules(agents, { yes, silent: !human });
-        // Pull any skills the pipeline has already generated for this tenant into
-        // the local agent skill dirs. Best-effort: a brand-new tenant has none yet,
-        // and a transient ingest/network error must not fail setup.
-        try {
-            const pulled = await pullSkills({ silent: true });
-            if (pulled.wrote + pulled.updated > 0) {
-                log(renderInitNote(`Pulled ${pulled.wrote + pulled.updated} learned skill(s) into agent skills`));
-            }
-        }
-        catch {
-            // Silent: skills are additive; never block init on them.
-        }
     }
     else {
         log(renderInitNote('No coding agents detected, skipping', 'skipped'));
     }
     await initPrompts({ silent: true });
     log(renderInitNote('Created or verified .moda/prompts.yml'));
-    const installSdkGuide = setupPlan.find((action) => action.category === 'sdk')?.approved === true;
-    if (installSdkGuide) {
-        const guidePath = writeSdkIntegrationGuide();
-        log(renderInitNote(`Wrote ${guidePath}`));
-        markApplied(setupPlan, 'sdk');
+    // Push the manifest's prompt files to Moda so production traces can attribute
+    // managed prompt versions. A fresh repo has none yet — that's a harmless no-op.
+    try {
+        const promptSync = await runPromptSync({}, { profile: stringFlag(flags.profile) });
+        log(renderInitNote(promptSync.synced.length > 0
+            ? `Synced ${promptSync.synced.length} prompt(s) to Moda`
+            : 'No prompt files to sync yet (add paths to .moda/prompts.yml)'));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        warn(renderInitNote(`Prompt sync skipped: ${message}`, 'warning'));
+    }
+    // Push locally-authored skills (`.claude/skills/**/SKILL.md`) to Moda, in
+    // parallel intent with prompt sync. A fresh repo has none yet — harmless
+    // no-op. Best-effort: a network blip must not abort onboarding.
+    try {
+        const skillSync = await runSkillSync({}, { profile: stringFlag(flags.profile) });
+        if (skillSync.synced.length > 0) {
+            log(renderInitNote(`Synced ${skillSync.synced.length} skill(s) to Moda`));
+        }
+        else {
+            log(renderInitNote('No local skills to sync yet (add .claude/skills/<name>/SKILL.md)'));
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        warn(renderInitNote(`Skill sync skipped: ${message}`, 'warning'));
+    }
+    const sdkAction = setupPlan.find((action) => action.category === 'sdk');
+    if (sdkAction?.approved === true) {
+        log(renderInitNote('Running your coding agent to integrate the Moda SDK (this can take a few minutes)...', 'warning'));
+        const result = await runSdkIntegration({ human });
+        if (result.status === 'integrated') {
+            log(renderInitNote(`Integrated the Moda SDK with ${result.adapter}. Review the diff before committing.`));
+            markApplied(setupPlan, 'sdk');
+        }
+        else if (result.status === 'no-agent') {
+            const guidePath = writeSdkIntegrationGuide();
+            sdkAction.files = [guidePath];
+            log(renderInitNote(`No coding agent CLI found; wrote ${guidePath} to integrate by hand`, 'warning'));
+            markApplied(setupPlan, 'sdk');
+        }
+        else {
+            const guidePath = writeSdkIntegrationGuide();
+            sdkAction.files = [guidePath];
+            warn(renderInitNote(`SDK integration via ${result.adapter} did not complete: ${result.detail}`, 'warning'));
+            log(renderInitNote(`Wrote ${guidePath} so you can finish the integration manually`));
+            markApplied(setupPlan, 'sdk');
+        }
     }
     else {
-        log(renderInitNote('Skipped SDK integration guide', 'skipped'));
-        markApplied(setupPlan, 'sdk', 'User skipped SDK integration guide.');
+        log(renderInitNote('Skipped SDK integration', 'skipped'));
+        markApplied(setupPlan, 'sdk', 'User skipped SDK integration.');
     }
     const configureCiCd = setupPlan.find((action) => action.category === 'ci-cd')?.approved === true;
     if (configureCiCd) {
@@ -182,22 +242,26 @@ export async function runInit(flags, options = {}) {
     markApplied(setupPlan, 'skills');
     emit('apply', 'Approved changes applied.', 'completed');
     phases.push({ id: 'apply', title: 'Apply Approved Changes', status: 'completed' });
-    log(renderInitStep(7, 7, 'Validate', 'Running local doctor checks so the setup leaves a clear state.'));
-    emit('validate', 'Running local Moda doctor diagnostics.');
-    await runDoctorCommand(createCommandContext({
+    const offlineValidation = isTruthyFlag(flagValue(flags, 'offline'));
+    log(renderInitStep(7, 7, 'Validate', offlineValidation
+        ? 'Running local doctor checks so the setup leaves a clear state.'
+        : 'Running Moda doctor online to confirm setup and that telemetry is reaching Moda.'));
+    emit('validate', `Running Moda doctor diagnostics (${offlineValidation ? 'offline' : 'online'}).`);
+    const doctorReport = await buildDoctorReport(createCommandContext({
         command: 'doctor',
         positional: undefined,
         positionals: [],
-        flags: commandFlags({
-            json: true,
-            quiet: true,
-            offline: true,
-            'no-telemetry': true,
-        }),
-    }));
+        flags: commandFlags({ json: true, quiet: true, 'no-telemetry': true }),
+    }), { offline: offlineValidation });
     markApplied(setupPlan, 'validation');
-    log(renderInitNote('Local validation checks completed'));
-    emit('validate', 'Local validation checks complete.', 'completed');
+    log(renderInitNote(`Validation checks completed: ${doctorReport.summary.pass} passing, ${doctorReport.summary.warning} warning, ${doctorReport.summary.fail} failing`));
+    if (!offlineValidation) {
+        const cloud = doctorReport.checks.find((check) => check.id === 'cloud_data_flow');
+        if (cloud) {
+            log(renderInitNote(`Moda Cloud telemetry: ${cloud.status}`, cloud.status === 'pass' ? undefined : 'warning'));
+        }
+    }
+    emit('validate', 'Validation checks complete.', doctorReport.summary.fail > 0 ? 'warning' : 'completed');
     phases.push({ id: 'validate', title: 'Validate', status: 'completed' });
     // Done
     log(renderInitComplete({
@@ -212,7 +276,7 @@ function buildSetupPlan(options) {
     return [
         {
             category: 'harness',
-            title: 'Analyze harness and write cited Moda report',
+            title: 'Analyze harness, write cited report, and sync the graph to Moda',
             status: 'planned',
             approved: true,
             files: [
@@ -222,7 +286,7 @@ function buildSetupPlan(options) {
                 '.moda/harness.json',
                 '.moda/HARNESS.md',
             ],
-            command: 'moda harness analyze --analyst=auto --summary',
+            command: 'moda harness analyze --analyst=auto --summary && moda harness approve --yes && moda harness sync --from-report',
         },
         {
             category: 'hooks',
@@ -235,30 +299,34 @@ function buildSetupPlan(options) {
         },
         {
             category: 'prompts',
-            title: 'Initialize prompt registry manifest',
+            title: 'Initialize the prompt registry manifest and sync prompts to Moda',
             status: 'planned',
             approved: true,
             files: ['.moda/prompts.yml'],
-            command: 'moda prompts init',
+            command: 'moda prompts init && moda prompts sync',
         },
         {
             category: 'skills',
-            title: 'Pull approved Moda skills when available',
+            title: 'Install the moda-cli skill into detected coding agents and sync local skills to Moda',
             status: 'planned',
             approved: true,
             files: ['.claude/skills', '.cursor/rules'],
-            command: 'moda skills pull',
+            // Skill install into detected agents happens inside `moda init`; there is no
+            // standalone install command, so surface only the re-runnable sync here.
+            command: 'moda skills sync',
         },
         {
             category: 'sdk',
-            title: 'Write SDK integration guide',
-            status: options.installSdkGuide ? 'planned' : 'manual',
-            approved: options.installSdkGuide,
-            files: [SDK_GUIDE_PATH],
-            command: 'open .moda/SDK_INTEGRATION.md',
-            reason: options.installSdkGuide
-                ? 'Guide only; package installs and source edits remain human-approved/manual.'
-                : 'SDK package installation and code instrumentation stay human-approved/manual.',
+            title: 'Run a coding agent to integrate the Moda SDK',
+            status: options.integrateSdk ? 'planned' : 'manual',
+            approved: options.integrateSdk,
+            // Files are repo-specific and unknown ahead of the agent run; the fallback
+            // path rewrites this to the guide path when no agent CLI is available.
+            files: [],
+            command: 'moda init',
+            reason: options.integrateSdk
+                ? 'Installs the SDK package and edits source via your coding agent; review the diff before committing.'
+                : `SDK integration stays manual; see ${SDK_GUIDE_PATH} if you generate the guide.`,
         },
         {
             category: 'ci-cd',
@@ -271,11 +339,11 @@ function buildSetupPlan(options) {
         },
         {
             category: 'validation',
-            title: 'Run local Moda doctor diagnostics',
+            title: 'Run Moda doctor online to confirm telemetry is reaching Moda',
             status: 'planned',
             approved: true,
             files: [],
-            command: 'moda doctor',
+            command: 'moda doctor --online',
         },
     ];
 }
@@ -383,16 +451,19 @@ async function shouldConfigureCiCd(flags, yes) {
         default: false,
     });
 }
-async function shouldCreateSdkGuide(flags, yes) {
-    const explicit = parseOptionalBoolean(flagValue(flags, 'sdk-guide', 'sdk_guide', 'sdk'));
+async function shouldIntegrateSdk(flags, yes) {
+    const explicit = parseOptionalBoolean(flagValue(flags, 'sdk-integrate', 'sdk_integrate', 'sdk-guide', 'sdk_guide', 'sdk'));
     if (explicit !== undefined)
         return explicit;
-    if (isTruthyFlag(flagValue(flags, 'no-sdk-guide', 'no_sdk_guide')))
+    if (isTruthyFlag(flagValue(flags, 'no-sdk-integrate', 'no_sdk_integrate', 'no-sdk-guide', 'no_sdk_guide', 'no-sdk', 'no_sdk'))) {
         return false;
+    }
+    // SDK integration now installs packages and edits source via a coding agent.
+    // Never do that unattended (--yes/--json/--agent); require an explicit opt-in.
     if (yes)
-        return true;
+        return false;
     return confirm({
-        message: 'Create a Moda SDK integration guide? (No packages installed, no source files edited.)',
+        message: 'Run your coding agent now to install the Moda SDK and instrument your LLM calls? (Edits source, installs packages.)',
         default: true,
     });
 }

package/dist/init/sdk-guide.d.ts

@@ -1,3 +1,21 @@
 export declare const SDK_GUIDE_PATH = ".moda/SDK_INTEGRATION.md";
+type RuntimeSummary = {
+    runtimeAgents: number;
+    agentFamilies: number;
+    frameworks: string[];
+    providers: string[];
+    runtimeAgentNames: string[];
+};
+export type SdkGuideContext = {
+    languages: string[];
+    installCommands: string[];
+    providerHints: string[];
+    frameworkHints: string[];
+    packageManagers: string[];
+    runtimeSummary: RuntimeSummary;
+};
 export declare function writeSdkIntegrationGuide(cwd?: string): string;
+export declare function detectSdkGuideContext(cwd: string): SdkGuideContext;
+export declare function renderSdkIntegrationGuide(context: SdkGuideContext): string;
+export {};
 //# sourceMappingURL=sdk-guide.d.ts.map

package/dist/init/sdk-guide.js

@@ -8,7 +8,7 @@ export function writeSdkIntegrationGuide(cwd = process.cwd()) {
     writeFileSync(absolutePath, renderSdkIntegrationGuide(detectSdkGuideContext(cwd)));
     return relativePath;
 }
-function detectSdkGuideContext(cwd) {
+export function detectSdkGuideContext(cwd) {
     const languages = [];
     const installCommands = [];
     const packageManagers = [];
@@ -64,7 +64,7 @@ function detectSdkGuideContext(cwd) {
         runtimeSummary,
     };
 }
-function renderSdkIntegrationGuide(context) {
+export function renderSdkIntegrationGuide(context) {
     const languages = context.languages.length > 0 ? context.languages.join(', ') : 'Not detected yet';
     const packageManagers = context.packageManagers.length > 0 ? context.packageManagers.join(', ') : 'Not detected yet';
     const installCommands = context.installCommands.length > 0

package/dist/init/sdk-integration.d.ts

@@ -0,0 +1,26 @@
+import { type CodingAgentAdapter } from '../harness.js';
+export type SdkIntegrationResult = {
+    status: 'integrated';
+    adapter: CodingAgentAdapter;
+} | {
+    status: 'no-agent';
+} | {
+    status: 'failed';
+    adapter: CodingAgentAdapter;
+    detail: string;
+};
+export interface SdkIntegrationOptions {
+    cwd?: string;
+    /** Explicit adapter override (e.g. from --analyst); otherwise best-ranked installed CLI. */
+    adapter?: CodingAgentAdapter;
+    /** Stream the agent's progress to the user (human terminals only). */
+    human?: boolean;
+    onProgress?: (message: string) => void;
+}
+/**
+ * Pick an installed coding-agent CLI and run it, in write mode, to integrate the
+ * Moda SDK into the repo. Returns `no-agent` (without throwing) when no CLI is
+ * installed so the caller can fall back to writing the static guide.
+ */
+export declare function runSdkIntegration(options?: SdkIntegrationOptions): Promise<SdkIntegrationResult>;
+//# sourceMappingURL=sdk-integration.d.ts.map

package/dist/init/sdk-integration.js

@@ -0,0 +1,80 @@
+// src/init/sdk-integration.ts — Run an installed coding agent to integrate the
+// Moda SDK directly, instead of leaving a guide for the user to action by hand.
+//
+// This reuses the same coding-agent spawn machinery as `moda harness analyze`
+// (see src/harness.ts), but in write mode: the agent is expected to install the
+// SDK package and edit source to instrument LLM calls.
+import { codingAgentDisplayName, detectAvailableCodingAgents, runCodingAgent, } from '../harness.js';
+import { detectSdkGuideContext, renderSdkIntegrationGuide } from './sdk-guide.js';
+/**
+ * Pick an installed coding-agent CLI and run it, in write mode, to integrate the
+ * Moda SDK into the repo. Returns `no-agent` (without throwing) when no CLI is
+ * installed so the caller can fall back to writing the static guide.
+ */
+export async function runSdkIntegration(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const available = detectAvailableCodingAgents();
+    if (available.length === 0)
+        return { status: 'no-agent' };
+    const adapter = options.adapter && available.some((item) => item.adapter === options.adapter)
+        ? options.adapter
+        : available[0].adapter;
+    const prompt = renderSdkIntegrationPrompt(cwd);
+    const human = options.human ?? false;
+    const emit = (message) => {
+        options.onProgress?.(message);
+        if (human)
+            process.stderr.write(`  ${codingAgentDisplayName(adapter)}: ${message}\n`);
+    };
+    const run = await runCodingAgent({
+        adapter,
+        prompt,
+        rootDir: cwd,
+        mode: 'write',
+        stream: human,
+        progressToStderr: false,
+        onProgress: (message) => emit(message),
+    });
+    if (run.failedToStart) {
+        return { status: 'failed', adapter, detail: `${codingAgentDisplayName(adapter)} CLI failed to start.` };
+    }
+    if (run.timedOut) {
+        return { status: 'failed', adapter, detail: `${codingAgentDisplayName(adapter)} timed out during SDK integration.` };
+    }
+    if (run.status !== 0) {
+        const tail = `${run.stdout}\n${run.stderr}`.trim().slice(-800);
+        return {
+            status: 'failed',
+            adapter,
+            detail: `${codingAgentDisplayName(adapter)} exited with status ${run.status ?? 'unknown'}.${tail ? `\n${tail}` : ''}`,
+        };
+    }
+    return { status: 'integrated', adapter };
+}
+function renderSdkIntegrationPrompt(cwd) {
+    const guide = renderSdkIntegrationGuide(detectSdkGuideContext(cwd));
+    return [
+        'You are running inside `moda init` as a one-shot SDK integration task. The user has',
+        'approved letting you install packages and edit source files in THIS repository to add',
+        'Moda LLM observability. Do the integration now — do not just describe it.',
+        '',
+        'Scope and safety rules:',
+        '- Only touch this repository (the working directory you were launched in).',
+        '- Install the Moda SDK with the package manager this repo already uses.',
+        '- Instrument the real LLM call sites; do not invent files or frameworks that are not here.',
+        '- Never write MODA_API_KEY (or any secret) into source files, and never create or edit',
+        '  .env files. The key belongs in the environment / a secret manager at runtime.',
+        '- Make the smallest correct change. Match the existing code style and imports.',
+        '- If something is ambiguous or the repo has no LLM calls to instrument, stop and explain',
+        '  rather than guessing.',
+        '',
+        'Follow this Moda-authored integration spec exactly (it reflects the detected languages,',
+        'package managers, providers, and frameworks for this repo):',
+        '',
+        guide,
+        '',
+        'When finished, print a short summary of: the package(s) installed, the files you edited,',
+        'and any step a human still needs to do (e.g. setting MODA_API_KEY in the deploy env).',
+    ].join('\n');
+}
+//# sourceMappingURL=sdk-integration.js.map

package/dist/prompts.d.ts

@@ -3,4 +3,20 @@ export declare function runPromptsCommand(positionals: string[], flags: Record<s
 export declare function initPrompts(options?: {
     silent?: boolean;
 }): Promise<void>;
+export interface PromptSyncResult {
+    synced: Array<{
+        key: string;
+        promptId?: string;
+        versionId?: string;
+        contentHash: string;
+        sourcePath?: string;
+    }>;
+    dryRun: boolean;
+}
+/**
+ * Sync the manifest's prompt files to the backend and update the lockfile.
+ * Returns the synced list without printing, so callers (e.g. `moda init`)
+ * control their own output. `moda prompts sync` wraps this with JSON output.
+ */
+export declare function runPromptSync(flags: Record<string, string>, profileOptions: ProfileIOOptions): Promise<PromptSyncResult>;
 //# sourceMappingURL=prompts.d.ts.map

package/dist/prompts.js

@@ -59,7 +59,12 @@ async function syncPrompts(flags, profileOptions) {
     }
     await syncPromptsOnce(flags, profileOptions);
 }
-async function syncPromptsOnce(flags, profileOptions) {
+/**
+ * Sync the manifest's prompt files to the backend and update the lockfile.
+ * Returns the synced list without printing, so callers (e.g. `moda init`)
+ * control their own output. `moda prompts sync` wraps this with JSON output.
+ */
+export async function runPromptSync(flags, profileOptions) {
     await initPrompts({ silent: true });
     const prompts = discoverPrompts();
     const sourceCommit = getGitCommit();
@@ -81,9 +86,13 @@ async function syncPromptsOnce(flags, profileOptions) {
     if (!dryRun) {
         writeLock(prompts, response.synced ?? []);
     }
+    return { synced: response.synced ?? [], dryRun };
+}
+async function syncPromptsOnce(flags, profileOptions) {
+    const result = await runPromptSync(flags, profileOptions);
     printJson({
-        synced: response.synced ?? [],
-        lockfile: dryRun ? undefined : LOCK_PATH,
+        synced: result.synced,
+        lockfile: result.dryRun ? undefined : LOCK_PATH,
     });
 }
 async function watchPromptSync(flags, profileOptions) {

package/dist/skills.d.ts

@@ -1,4 +1,5 @@
 import type { ParsedArgs } from './cli.js';
+import type { ProfileIOOptions } from './profiles.js';
 interface PullSummary {
     total: number;
     pruned: number;
@@ -17,6 +18,31 @@ export declare function pullSkills(options?: {
     cwd?: string;
     silent?: boolean;
 }): Promise<PullSummary>;
+export interface SkillSyncResult {
+    synced: Array<{
+        key: string;
+        skillId?: string;
+        versionId?: string;
+        version?: number;
+        contentHash: string;
+        changed?: boolean;
+        sourcePath?: string;
+    }>;
+    dryRun: boolean;
+}
+/**
+ * Push locally-authored `.claude/skills/**\/SKILL.md` files up to Moda via
+ * `POST /api/skills/sync`. Modeled on `runPromptSync`: returns the synced list
+ * without printing so callers (e.g. `moda init`) control their own output.
+ * `moda skills sync` wraps this with JSON output.
+ *
+ * Skills that Moda itself manages — those previously pulled/generated (tracked
+ * in `.moda/skills.yml`) and the shipped `moda-cli` skill — are excluded so we
+ * only push skills the user authored.
+ */
+export declare function runSkillSync(flags?: Record<string, string>, profileOptions?: ProfileIOOptions, options?: {
+    cwd?: string;
+}): Promise<SkillSyncResult>;
 /**
  * `moda skills <subcommand>` dispatcher.
  */

package/dist/skills.js

@@ -15,9 +15,11 @@
 // Skills are managed artifacts. A pull installs the latest server-published
 // generation snapshot, tracked in .moda/skills.yml, and prunes only files that a
 // previous Moda pull wrote.
+import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmdirSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmdirSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { basename, dirname, isAbsolute, join, normalize, relative, resolve } from 'node:path';
+import { callControlAPI } from './api-client.js';
 import { resolveApiKey, resolveIngestUrl, resolveTenantId } from './config.js';
 import { claudeSkillToCursorRule } from './init/rules.js';
 import { detectAgents } from './init/mcp.js';
@@ -189,6 +191,157 @@ function recordOutcome(summary, status, log, relativePath) {
             break;
     }
 }
+const SKILLS_DIR = join('.claude', 'skills');
+const SKILL_FILE = 'SKILL.md';
+const MAX_SKILL_WALK_DEPTH = 4;
+/**
+ * Push locally-authored `.claude/skills/**\/SKILL.md` files up to Moda via
+ * `POST /api/skills/sync`. Modeled on `runPromptSync`: returns the synced list
+ * without printing so callers (e.g. `moda init`) control their own output.
+ * `moda skills sync` wraps this with JSON output.
+ *
+ * Skills that Moda itself manages — those previously pulled/generated (tracked
+ * in `.moda/skills.yml`) and the shipped `moda-cli` skill — are excluded so we
+ * only push skills the user authored.
+ */
+export async function runSkillSync(flags = {}, profileOptions = {}, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const dryRun = flags['dry-run'] === 'true';
+    const skills = discoverLocalSkills(cwd);
+    if (skills.length === 0) {
+        return { synced: [], dryRun };
+    }
+    const sourceCommit = getGitCommit(cwd);
+    const response = (await callControlAPI('/skills/sync', {
+        method: 'POST',
+        body: JSON.stringify({
+            skills: skills.map((skill) => ({
+                key: skill.key,
+                name: skill.name,
+                description: skill.description,
+                skillMd: skill.skillMd,
+                sourcePath: skill.sourcePath,
+                contentHash: skill.contentHash,
+                sourceCommit,
+            })),
+            sourceCommit,
+            dryRun,
+        }),
+    }, profileOptions));
+    return { synced: response.synced ?? [], dryRun };
+}
+/**
+ * Discover user-authored skills under `.claude/skills/`. Excludes Moda-managed
+ * skills (the `.moda/skills.yml` managed paths and the shipped `moda-cli`
+ * skill) and validates each directory key.
+ */
+function discoverLocalSkills(cwd) {
+    const skillsRoot = join(cwd, SKILLS_DIR);
+    if (!existsSync(skillsRoot))
+        return [];
+    const managed = new Set(managedSkillPaths(cwd));
+    const skills = [];
+    for (const absPath of walkSkillFiles(skillsRoot, 0)) {
+        const sourcePath = relative(cwd, absPath).replace(/\\/g, '/');
+        if (managed.has(sourcePath))
+            continue;
+        const key = basename(dirname(absPath));
+        // Never re-upload Moda's own shipped skill; only accept plain identifiers.
+        if (key === 'moda-cli' || !/^[A-Za-z0-9_-]+$/.test(key))
+            continue;
+        let content;
+        try {
+            content = readFileSync(absPath, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        if (!content.trim())
+            continue;
+        const { name, description } = parseSkillFrontmatter(content, key);
+        skills.push({
+            key,
+            name,
+            description,
+            skillMd: content,
+            sourcePath,
+            contentHash: sha256(content),
+        });
+    }
+    return skills.sort((a, b) => a.key.localeCompare(b.key));
+}
+/** Managed SKILL.md paths recorded by a previous `moda skills pull`. */
+function managedSkillPaths(cwd) {
+    const manifest = readSkillsManifest(cwd);
+    if (!manifest)
+        return [];
+    return manifest.managedPaths.filter((path) => path.startsWith('.claude/skills/') && path.endsWith('/SKILL.md'));
+}
+/** Recursively find `SKILL.md` files, never following symlinks. */
+function walkSkillFiles(dir, depth) {
+    if (depth > MAX_SKILL_WALK_DEPTH)
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = join(dir, entry);
+        let stat;
+        try {
+            stat = lstatSync(fullPath);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isSymbolicLink())
+            continue;
+        if (stat.isDirectory()) {
+            files.push(...walkSkillFiles(fullPath, depth + 1));
+        }
+        else if (stat.isFile() && entry === SKILL_FILE) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+/** Pull `name`/`description` from a SKILL.md YAML frontmatter block. */
+function parseSkillFrontmatter(raw, fallbackKey) {
+    let name = fallbackKey;
+    let description;
+    if (raw.startsWith('---')) {
+        const end = raw.indexOf('\n---', 3);
+        if (end !== -1) {
+            const frontmatter = raw.slice(3, end);
+            const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
+            const descMatch = frontmatter.match(/^description:\s*(.+)$/m);
+            if (nameMatch)
+                name = stripQuotes(nameMatch[1].trim()) || fallbackKey;
+            if (descMatch)
+                description = stripQuotes(descMatch[1].trim()) || undefined;
+        }
+    }
+    return { name, description };
+}
+function stripQuotes(value) {
+    return value.replace(/^["']|["']$/g, '');
+}
+function getGitCommit(cwd) {
+    try {
+        return execFileSync('git', ['rev-parse', 'HEAD'], {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * `moda skills <subcommand>` dispatcher.
  */
@@ -218,8 +371,13 @@ export async function runSkillsCommand(args) {
         }
         return Number(result.sessions_failed ?? 0) > 0 ? 1 : 0;
     }
+    if (sub === 'sync') {
+        const result = await runSkillSync(args.flags, { profile: args.flags.profile });
+        console.log(JSON.stringify({ synced: result.synced, dryRun: result.dryRun }));
+        return 0;
+    }
     if (sub !== 'pull') {
-        throw new CliInputError(sub ? `Unknown skills subcommand '${sub}'` : 'A skills subcommand is required', 'Usage: moda skills gen [--source=all|sdk|coding-agent] [--max-sessions=N] [--start-at=ISO] [--end-at=ISO] [--replay] [--reprocess-segments] [--force-reprocess] [--wait] | moda skills pull [--status=approved|proposed|all]');
+        throw new CliInputError(sub ? `Unknown skills subcommand '${sub}'` : 'A skills subcommand is required', 'Usage: moda skills gen [--source=all|sdk|coding-agent] [--max-sessions=N] [--start-at=ISO] [--end-at=ISO] [--replay] [--reprocess-segments] [--force-reprocess] [--wait] | moda skills pull [--status=approved|proposed|all] | moda skills sync [--dry-run]');
     }
     const status = (args.flags.status ?? 'approved').toLowerCase();
     if (!VALID_STATUSES.has(status)) {

package/dist/update-check.d.ts

@@ -0,0 +1,31 @@
+import { type ProfileIOOptions } from './profiles.js';
+export declare function stripUpdateCheckFlag(flags: Record<string, string>): Record<string, string>;
+export declare function isUpdateCheckDisabled(flags: Record<string, string>, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Numeric semver comparison ignoring prerelease/build suffixes; npm's
+ * `latest` dist-tag only carries stable releases, so this is sufficient
+ * without pulling in a semver dependency.
+ */
+export declare function isNewerVersion(candidate: string, current: string): boolean;
+/**
+ * Refresh the cached latest version from the npm registry at most once per
+ * 24 hours. Fire-and-forget from the CLI dispatcher. The abort timer is
+ * unref'd so it can't keep the process alive after the socket closes (it does
+ * not unref the in-flight fetch itself — a fast command may still wait up to
+ * REGISTRY_TIMEOUT_MS for the request to resolve, matching the telemetry
+ * module's trade-off). Every failure path is swallowed — an update check must
+ * never break a command.
+ */
+export declare function startUpdateCheck(options?: ProfileIOOptions, now?: number): Promise<void>;
+/**
+ * Returns the upgrade notice when the cached registry version is newer than
+ * the running build, or undefined. Reads only the local cache — never the
+ * network — so it is safe to call synchronously at the end of every command.
+ */
+export declare function getUpdateNotice(options?: ProfileIOOptions): string | undefined;
+/**
+ * Print the upgrade notice to stderr in interactive terminals only: stdout
+ * stays machine-readable, and piped/CI invocations stay noise-free.
+ */
+export declare function printUpdateNotice(options?: ProfileIOOptions): void;
+//# sourceMappingURL=update-check.d.ts.map

package/dist/update-check.js

@@ -0,0 +1,141 @@
+// src/update-check.ts — Daily npm-registry version check with an upgrade
+// notice. Mirrors the telemetry contract: fire-and-forget, short abort
+// timeout, never throws, and never touches stdout (notice goes to stderr so
+// JSON/agent output stays machine-readable).
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { VERSION } from './config.js';
+import { getModaDir } from './profiles.js';
+const UPDATE_CHECK_FLAG = 'no-update-check';
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const REGISTRY_TIMEOUT_MS = 1_500;
+const REGISTRY_LATEST_URL = 'https://registry.npmjs.org/@moda-ai/cli/latest';
+// npm's `latest` dist-tag is always a stable semver. Anchored, no control
+// chars: a registry response intercepted by a proxy can't smuggle ANSI escape
+// sequences into the cache (and thus the terminal notice) this way.
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+export function stripUpdateCheckFlag(flags) {
+    const { [UPDATE_CHECK_FLAG]: _drop, ...rest } = flags;
+    return rest;
+}
+export function isUpdateCheckDisabled(flags, env = process.env) {
+    return (flags[UPDATE_CHECK_FLAG] === 'true' ||
+        env.MODA_CLI_UPDATE_CHECK === '0' ||
+        env.DO_NOT_TRACK === '1' ||
+        // Treat CI as set only when it carries a real truthy value: `CI=false`
+        // and `CI=0` are common ways to simulate a non-CI shell locally.
+        (env.CI !== undefined &&
+            env.CI !== '' &&
+            env.CI !== 'false' &&
+            env.CI !== '0'));
+}
+function cachePath(options = {}) {
+    return join(getModaDir(options), 'update-check.json');
+}
+function readCache(options = {}) {
+    try {
+        const parsed = JSON.parse(readFileSync(cachePath(options), 'utf8'));
+        if (parsed &&
+            typeof parsed === 'object' &&
+            typeof parsed.checked_at === 'number' &&
+            typeof parsed.latest === 'string') {
+            return parsed;
+        }
+    }
+    catch {
+        // Missing or corrupt cache means "never checked".
+    }
+    return undefined;
+}
+function writeCache(cache, options = {}) {
+    try {
+        mkdirSync(getModaDir(options), { recursive: true });
+        writeFileSync(cachePath(options), `${JSON.stringify(cache, null, 2)}\n`, 'utf8');
+    }
+    catch {
+        // Best-effort: an unwritable cache only means we re-check next run.
+    }
+}
+/**
+ * Numeric semver comparison ignoring prerelease/build suffixes; npm's
+ * `latest` dist-tag only carries stable releases, so this is sufficient
+ * without pulling in a semver dependency.
+ */
+export function isNewerVersion(candidate, current) {
+    const parse = (v) => v.split(/[-+]/)[0].split('.').map((part) => Number.parseInt(part, 10) || 0);
+    const a = parse(candidate);
+    const b = parse(current);
+    for (let i = 0; i < 3; i++) {
+        if ((a[i] ?? 0) > (b[i] ?? 0))
+            return true;
+        if ((a[i] ?? 0) < (b[i] ?? 0))
+            return false;
+    }
+    return false;
+}
+/**
+ * Refresh the cached latest version from the npm registry at most once per
+ * 24 hours. Fire-and-forget from the CLI dispatcher. The abort timer is
+ * unref'd so it can't keep the process alive after the socket closes (it does
+ * not unref the in-flight fetch itself — a fast command may still wait up to
+ * REGISTRY_TIMEOUT_MS for the request to resolve, matching the telemetry
+ * module's trade-off). Every failure path is swallowed — an update check must
+ * never break a command.
+ */
+export async function startUpdateCheck(options = {}, now = Date.now()) {
+    const cache = readCache(options);
+    if (cache && now - cache.checked_at < CHECK_INTERVAL_MS) {
+        return;
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), REGISTRY_TIMEOUT_MS);
+    if (typeof timeout.unref === 'function') {
+        timeout.unref();
+    }
+    try {
+        const res = await fetch(REGISTRY_LATEST_URL, {
+            headers: { Accept: 'application/json' },
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return;
+        const body = (await res.json());
+        if (typeof body.version !== 'string' || !SEMVER_RE.test(body.version))
+            return;
+        writeCache({ checked_at: now, latest: body.version }, options);
+    }
+    catch {
+        // Network/timeout errors are expected offline; try again next run.
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * Returns the upgrade notice when the cached registry version is newer than
+ * the running build, or undefined. Reads only the local cache — never the
+ * network — so it is safe to call synchronously at the end of every command.
+ */
+export function getUpdateNotice(options = {}) {
+    const cache = readCache(options);
+    if (!cache || !isNewerVersion(cache.latest, VERSION)) {
+        return undefined;
+    }
+    return [
+        '',
+        `Update available: moda-cli ${VERSION} → ${cache.latest}`,
+        'Run `npm install -g @moda-ai/cli@latest` to update.',
+    ].join('\n');
+}
+/**
+ * Print the upgrade notice to stderr in interactive terminals only: stdout
+ * stays machine-readable, and piped/CI invocations stay noise-free.
+ */
+export function printUpdateNotice(options = {}) {
+    if (!process.stderr.isTTY)
+        return;
+    const notice = getUpdateNotice(options);
+    if (notice)
+        console.error(notice);
+}
+//# sourceMappingURL=update-check.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moda-ai/cli",
-  "version": "1.3.0",
+  "version": "1.6.0",
   "description": "CLI for Moda - AI agent analytics and observability",
   "type": "module",
   "bin": {