@distributionos/cli 0.1.11 → 0.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@distributionos/cli",
-  "version": "0.1.11",
+  "version": "0.1.14",
   "description": "DistributionOS repo setup CLI for agent onboarding and first-party analytics.",
   "homepage": "https://distributionos.dev",
   "repository": {

package/src/api.js

@@ -42,7 +42,7 @@ export async function resolveAuthToken({ env, apiBase, appId, fetchImpl }) {
     : null;
 }
 
-export async function fetchDistributionOsSetupContext(input) {
+export async function fetchDistributionOsSetupContext(input) {
   const token = await resolveAuthToken({
     env: input.env,
     apiBase: input.apiBase ?? DEFAULT_API_BASE,
@@ -61,6 +61,7 @@ export async function fetchDistributionOsSetupContext(input) {
       usage: null,
       instructions: null,
       analyticsContract: null,
+      setupContract: null,
       errors: [],
     };
   }
@@ -76,7 +77,7 @@ export async function fetchDistributionOsSetupContext(input) {
     return null;
   };
 
-  const [instructions, analyticsContract, usage] = await Promise.all([
+  const [instructions, analyticsContract, usage, setupContract] = await Promise.all([
     fetchJson({
       fetchImpl: input.fetch,
       apiBase,
@@ -95,6 +96,12 @@ export async function fetchDistributionOsSetupContext(input) {
       token: token.value,
       path: `/api/v1/apps/${encodeURIComponent(input.appId)}/usage`,
     }).catch(capture('Usage fetch')),
+    fetchJson({
+      fetchImpl: input.fetch,
+      apiBase,
+      token: token.value,
+      path: `/api/v1/apps/${encodeURIComponent(input.appId)}/setup/contract`,
+    }).catch(capture('Setup contract fetch')),
   ]);
 
   return {
@@ -108,9 +115,38 @@ export async function fetchDistributionOsSetupContext(input) {
     usage,
     instructions,
     analyticsContract,
+    setupContract,
     errors,
   };
 }
+
+export async function reportSetupInstallation(input) {
+  const token = await resolveAuthToken({
+    env: input.env,
+    apiBase: input.apiBase ?? DEFAULT_API_BASE,
+    appId: input.appId,
+    fetchImpl: input.fetch,
+  });
+  if (!token) {
+    throw new Error('No stored OAuth token or env token was available.');
+  }
+
+  const apiBase = normalizeApiBase(input.apiBase ?? DEFAULT_API_BASE);
+  const response = await input.fetch(`${apiBase}/api/v1/apps/${encodeURIComponent(input.appId)}/setup/report`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token.value}`,
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+    },
+    body: JSON.stringify(input.report),
+  });
+  const body = await response.json().catch(() => null);
+  if (!response.ok || body?.success === false) {
+    throw new Error(body?.error || `Setup report failed with HTTP ${response.status}`);
+  }
+  return body?.data ?? body;
+}
 
 export async function ensureAnalyticsSite(input) {
   const token = await resolveAuthToken({

package/src/bootstrap.js

@@ -7,9 +7,10 @@ import {
 const BOOTSTRAP_BLOCK_RE =
   /<!--\s*DISTRIBUTIONOS:START[\s\S]*?DISTRIBUTIONOS:END\s*-->/i;
 
-export function buildSetupCommand(appId, packageName = CLI_PACKAGE_NAME) {
-  return `npx ${packageName} setup --app ${shellToken(appId)}`;
-}
+export function buildSetupCommand(appId, packageName = CLI_PACKAGE_NAME) {
+  const packageSpec = packageName === CLI_PACKAGE_NAME ? `${packageName}@latest` : packageName;
+  return `npx --yes ${packageSpec} setup --app ${shellToken(appId)}`;
+}
 
 export function buildLocalBootstrapBlock(version = CURRENT_BOOTSTRAP_VERSION, appId) {
   const appIdAttribute = appId ? ` appId=${appId}` : '';

package/src/cli.js

@@ -1,15 +1,17 @@
-import { CLI_LOCAL_VERSION, DEFAULT_API_BASE } from './constants.js';
-import {
-  ensureAnalyticsSite,
-  reportImplementation,
-  resolveAuthToken,
-  verifyAnalyticsInstall,
-} from './api.js';
+import { CLI_LOCAL_VERSION, DEFAULT_API_BASE } from './constants.js';
+import {
+  ensureAnalyticsSite,
+  reportSetupInstallation,
+  reportImplementation,
+  resolveAuthToken,
+  verifyAnalyticsInstall,
+} from './api.js';
 import { loginWithOAuth } from './oauth.js';
 import { createSetupPlan, formatPlanText } from './plan.js';
 import { applySetupPlan } from './mutate.js';
-import { submitInitialization } from './initialization.js';
-import { compareValidationResults, inspectInstallArtifacts, runValidationPlan } from './validation.js';
+import { submitInitialization } from './initialization.js';
+import { compareValidationResults, inspectInstallArtifacts, runValidationPlan } from './validation.js';
+import { buildSetupReport } from './setup-report.js';
 
 export async function runCli(argv, runtime) {
   const stdout = runtime.stdout;
@@ -139,15 +141,21 @@ export async function runCli(argv, runtime) {
     if (!authReady) return 1;
   }
 
-  let plan = await createSetupPlan({
-    appId: args.appId,
-    cwd: args.cwd ?? runtime.cwd,
-    apiBase: args.apiBase ?? DEFAULT_API_BASE,
+  let plan = await createSetupPlan({
+    appId: args.appId,
+    cwd: args.cwd ?? runtime.cwd,
+    apiBase: args.apiBase ?? DEFAULT_API_BASE,
     env: runtime.env,
     fetch: runtime.fetch,
-    noFetch: args.noFetch,
-    apply: args.apply,
-  });
+    noFetch: args.noFetch,
+    apply: args.apply,
+  });
+  plan.setupReport = await submitSetupReportSafely({
+    args,
+    runtime,
+    plan,
+    phase: 'plan',
+  });
 
   if (!args.apply && !args.yes) {
     stdout.write(args.json ? `${JSON.stringify(plan, null, 2)}\n` : formatPlanText(plan));
@@ -185,15 +193,21 @@ export async function runCli(argv, runtime) {
     }
   }
 
-  plan = await createSetupPlan({
-    appId: args.appId,
-    cwd: args.cwd ?? runtime.cwd,
-    apiBase: args.apiBase ?? DEFAULT_API_BASE,
+  plan = await createSetupPlan({
+    appId: args.appId,
+    cwd: args.cwd ?? runtime.cwd,
+    apiBase: args.apiBase ?? DEFAULT_API_BASE,
     env: runtime.env,
     fetch: runtime.fetch,
-    noFetch: args.noFetch,
-    apply: args.apply,
-  });
+    noFetch: args.noFetch,
+    apply: args.apply,
+  });
+  plan.setupReport = await submitSetupReportSafely({
+    args,
+    runtime,
+    plan,
+    phase: args.apply ? 'apply_started' : 'plan',
+  });
 
   if (!args.apply) {
     stdout.write(args.json ? `${JSON.stringify(plan, null, 2)}\n` : formatPlanText(plan));
@@ -205,36 +219,99 @@ export async function runCli(argv, runtime) {
     const changes = await applySetupPlan(plan, {
       allowDirty: args.allowDirty,
       skipAnalytics: args.skipAnalytics,
+    });
+    const postValidation = args.skipValidate ? [] : await runValidationPlan(plan);
+    const validation = compareValidationResults(baselineValidation, postValidation);
+    const inspection = args.skipAnalytics ? [] : await inspectInstallArtifacts(plan);
+    const completedPlan = await createSetupPlan({
+      appId: args.appId,
+      cwd: args.cwd ?? runtime.cwd,
+      apiBase: args.apiBase ?? DEFAULT_API_BASE,
+      env: runtime.env,
+      fetch: runtime.fetch,
+      noFetch: args.noFetch,
+      apply: true,
+    });
+    completedPlan.setupReport = await submitSetupReportSafely({
+      args,
+      runtime,
+      plan: completedPlan,
+      phase: 'apply_completed',
+      details: {
+        changes,
+        validation,
+        inspection,
+        requiresAgentRestart: changes.some((change) => change.type === 'mcp' && change.changed),
+      },
+    });
+    const token = await resolveAuthToken({
+      env: runtime.env,
+      apiBase: args.apiBase ?? DEFAULT_API_BASE,
+      appId: args.appId,
+      fetchImpl: runtime.fetch,
     });
-    const postValidation = args.skipValidate ? [] : await runValidationPlan(plan);
-    const validation = compareValidationResults(baselineValidation, postValidation);
-    const inspection = args.skipAnalytics ? [] : await inspectInstallArtifacts(plan);
-    const token = await resolveAuthToken({
-      env: runtime.env,
-      apiBase: args.apiBase ?? DEFAULT_API_BASE,
-      appId: args.appId,
-      fetchImpl: runtime.fetch,
-    });
-    const initialization = token
-      ? await submitInitialization({
-        plan,
-        token: token.value,
-        apiBase: args.apiBase ?? DEFAULT_API_BASE,
-        fetchImpl: runtime.fetch,
-        domain: args.domain,
-      })
-      : null;
-
-    stdout.write(args.json
-      ? `${JSON.stringify({ plan, changes, initialization, validation, inspection }, null, 2)}\n`
-      : formatApplyResult(plan, changes, initialization, validation, inspection, args.skipValidate, args.apiBase ?? DEFAULT_API_BASE));
+    const initialization = token
+      ? await submitInitialization({
+        plan: completedPlan,
+        token: token.value,
+        apiBase: args.apiBase ?? DEFAULT_API_BASE,
+        fetchImpl: runtime.fetch,
+        domain: args.domain,
+      })
+      : null;
+
+    stdout.write(args.json
+      ? `${JSON.stringify({ plan: completedPlan, changes, initialization, validation, inspection }, null, 2)}\n`
+      : formatApplyResult(completedPlan, changes, initialization, validation, inspection, args.skipValidate, args.apiBase ?? DEFAULT_API_BASE));
     return hasBlockingApplyFailure(validation, inspection) ? 1 : 0;
-  } catch (error) {
-    stderr.write(`${error instanceof Error ? error.message : 'Setup apply failed'}\n`);
-    return 1;
-  }
-}
-
+  } catch (error) {
+    await submitSetupReportSafely({
+      args,
+      runtime,
+      plan,
+      phase: 'apply_failed',
+      details: {
+        applyResult: {
+          validation: [{
+            name: 'apply',
+            status: 'failed',
+          }],
+        },
+      },
+    });
+    stderr.write(`${error instanceof Error ? error.message : 'Setup apply failed'}\n`);
+    return 1;
+  }
+}
+
+async function submitSetupReportSafely({ args, runtime, plan, phase, details = {} }) {
+  if (args.noFetch || args.skipSetupReport) {
+    return null;
+  }
+
+  try {
+    const report = await buildSetupReport(plan, phase, details);
+    const result = await reportSetupInstallation({
+      appId: args.appId,
+      apiBase: args.apiBase ?? DEFAULT_API_BASE,
+      env: runtime.env,
+      fetch: runtime.fetch,
+      report,
+    });
+    return {
+      status: 'submitted',
+      phase,
+      result,
+    };
+  } catch (error) {
+    return {
+      status: 'failed',
+      phase,
+      error: error instanceof Error ? error.message : 'Setup report failed',
+    };
+  }
+}
+
 function hasBlockingApplyFailure(validation, inspection) {
   return validation.some((result) => result.introducedFailure) ||
     inspection.some((result) => result.status === 'failed');
@@ -266,10 +343,11 @@ export function parseArgs(rawArgs) {
     apply: false,
     allowDirty: false,
     skipAnalytics: false,
-    skipValidate: false,
-    noOpen: false,
-    noLogin: false,
-    yes: false,
+    skipValidate: false,
+    noOpen: false,
+    noLogin: false,
+    skipSetupReport: false,
+    yes: false,
     url: null,
     contentId: null,
     contractVersion: null,
@@ -301,10 +379,11 @@ export function parseArgs(rawArgs) {
     else if (arg === '--apply') parsed.apply = true;
     else if (arg === '--allow-dirty') parsed.allowDirty = true;
     else if (arg === '--skip-analytics') parsed.skipAnalytics = true;
-    else if (arg === '--skip-validate') parsed.skipValidate = true;
-    else if (arg === '--no-open') parsed.noOpen = true;
-    else if (arg === '--no-login') parsed.noLogin = true;
-    else if (arg === '--yes' || arg === '-y') parsed.yes = true;
+    else if (arg === '--skip-validate') parsed.skipValidate = true;
+    else if (arg === '--no-open') parsed.noOpen = true;
+    else if (arg === '--no-login') parsed.noLogin = true;
+    else if (arg === '--skip-setup-report') parsed.skipSetupReport = true;
+    else if (arg === '--yes' || arg === '-y') parsed.yes = true;
     else if (arg === '--app') parsed.appId = args[++index] ?? null;
     else if (arg.startsWith('--app=')) parsed.appId = arg.slice('--app='.length);
     else if (arg === '--cwd') parsed.cwd = args[++index] ?? null;
@@ -337,9 +416,9 @@ function helpText() {
   return [
     'DistributionOS CLI',
     '',
-    'Usage:',
-    '  distributionos setup --app <appId> [--api-base <url>] [--cwd <path>] [--json] [--no-fetch]',
-    '  distributionos setup --app <appId> --apply [--domain <domain>] [--allow-dirty]',
+    'Usage:',
+    '  distributionos setup --app <appId> [--api-base <url>] [--cwd <path>] [--json] [--no-fetch]',
+    '  distributionos setup --app <appId> --apply [--domain <domain>] [--allow-dirty] [--skip-setup-report]',
     '  distributionos login --app <appId> [--api-base <url>]',
     '  distributionos verify --app <appId> --url <liveUrl> [--content-id <id>]',
     '  distributionos report-implementation --app <appId> --artifact <artifactId> [--url <liveUrl>] [--summary <text>]',
@@ -507,9 +586,10 @@ function formatApplyResult(plan, changes, initialization, validation, inspection
     lines.push(
       '- Open this DistributionOS review page now:',
       `  ${reviewUrl}`,
-      '- Review the generated Brain Doc and Brain Vault context before asking your agent to keep working.',
       '- If .mcp.json was created or updated, restart or reconnect your agent session so it can load the DistributionOS MCP server.',
-      '- After reconnecting, ask your agent: "Check DistributionOS connection and tell me today\'s analytics summary."',
+      '- On the review page, copy the verification prompt and ask your agent to run it.',
+      '- DistributionOS will wait for a successful app-scoped MCP/API call before you continue to Brain Doc review.',
+      '- Verification prompt: "Check DistributionOS connection, fetch the latest agent instructions, then tell me today\'s analytics summary for this app."',
       '- After review, come back to this repo and inspect git diff before committing, pushing, or deploying.',
     );
   } else {

package/src/constants.js

@@ -8,6 +8,7 @@ export const DEFAULT_API_BASE = 'https://distributionos.dev';
 export const MCP_SERVER_URL = 'https://distributionos.dev/api/mcp';
 export const CURRENT_BOOTSTRAP_VERSION = '2026.06.14';
 export const CURRENT_ANALYTICS_CONTRACT_VERSION = '2026.06.14';
+export const CURRENT_SETUP_CONTRACT_VERSION = '2026.06.18';
 
 export const TOKEN_ENV_NAMES = [
   'DISTRIBUTIONOS_API_KEY',

package/src/mcp-config.js

@@ -62,8 +62,11 @@ export async function buildProjectMcpConfigPlan(cwd, serverUrl = MCP_SERVER_URL)
   const existingUrl = isRecord(existing) && typeof existing.url === 'string'
     ? existing.url
     : null;
+  const existingType = isRecord(existing) && typeof existing.type === 'string'
+    ? existing.type
+    : null;
 
-  if (existingUrl === serverUrl) {
+  if (existingUrl === serverUrl && existingType === 'http') {
     return {
       ...base,
       supported: true,
@@ -72,6 +75,24 @@ export async function buildProjectMcpConfigPlan(cwd, serverUrl = MCP_SERVER_URL)
     };
   }
 
+  if (existingUrl === serverUrl && !existingType) {
+    return {
+      ...base,
+      supported: true,
+      action: 'update',
+      reason: 'Add the Claude-compatible HTTP transport type to the DistributionOS MCP server entry.',
+    };
+  }
+
+  if (existingUrl === serverUrl && existingType !== 'http') {
+    return {
+      ...base,
+      supported: false,
+      action: 'manual',
+      reason: 'Existing distributionos MCP server uses a non-HTTP transport. The CLI will not overwrite it automatically.',
+    };
+  }
+
   if (existingUrl) {
     return {
       ...base,
@@ -112,6 +133,7 @@ export async function applyProjectMcpConfig(cwd, plan) {
     mcpServers: {
       ...(isRecord(existing.mcpServers) ? existing.mcpServers : {}),
       [DISTRIBUTIONOS_MCP_SERVER_NAME]: {
+        type: 'http',
         url: plan.serverUrl ?? MCP_SERVER_URL,
       },
     },
@@ -131,6 +153,7 @@ function recommendedMcpConfig(serverUrl) {
   return {
     mcpServers: {
       [DISTRIBUTIONOS_MCP_SERVER_NAME]: {
+        type: 'http',
         url: serverUrl,
       },
     },

package/src/plan.js

@@ -15,7 +15,11 @@ import { buildProjectMcpConfigPlan } from './mcp-config.js';
 import {
   buildAnalyticsRouteConfigScript,
   buildAnalyticsRouteConfigSnippet,
-} from './privacy.js';
+} from './privacy.js';
+import {
+  extractBootstrapMetadata,
+  formatSetupReportSummary,
+} from './setup-report.js';
 
 export async function createSetupPlan(options) {
   const cwd = options.cwd;
@@ -55,31 +59,35 @@ export async function createSetupPlan(options) {
     fallbackInstructions: buildFallbackMcpInstructions(appId),
     warnings: buildWarnings({ repo: planRepo, remote }),
     validation: buildValidationPlan(planRepo),
-    deploymentChecklist: [
-      'Review this plan and any proposed file edits.',
+    deploymentChecklist: [
+      'Review this plan and any proposed file edits.',
       'Apply reviewed bootstrap, analytics, and non-secret project MCP config changes only.',
       'Restart or reconnect your agent if the project-local MCP config changed.',
+      'Return to the DistributionOS onboarding page and verify the agent MCP connection before reviewing generated context.',
       'Run baseline tests before mutation when the worktree is messy.',
       'Run build and test commands after mutation.',
       'Do not deploy until a human reviews the diff.',
       'After deployment, call verify_analytics_install on representative public URLs.',
-      'Call report_implementation for shipped artifacts or analytics opt-outs.',
-    ],
-  };
-}
+      'Call report_implementation for shipped artifacts or analytics opt-outs.',
+    ],
+    setupReport: null,
+  };
+}
 
 function sanitizeRepoForPlan(repo) {
   return {
     ...repo,
     packageJson: sanitizePackageJson(repo.packageJson),
-    instructionFiles: (repo.instructionFiles ?? []).map(file => ({
-      path: file.path,
-      priority: file.priority,
-      exists: file.exists,
-      hasManagedDistributionOsBlock: /<!--\s*DISTRIBUTIONOS:START[\s\S]*?DISTRIBUTIONOS:END\s*-->/i.test(file.content ?? ''),
-      contentOmitted: true,
-    })),
-  };
+    instructionFiles: (repo.instructionFiles ?? []).map(file => ({
+      path: file.path,
+      priority: file.priority,
+      exists: file.exists,
+      hasManagedDistributionOsBlock: extractBootstrapMetadata(file.content).hasManagedDistributionOsBlock,
+      managedDistributionOsVersion: extractBootstrapMetadata(file.content).version,
+      managedDistributionOsAppId: extractBootstrapMetadata(file.content).appId,
+      contentOmitted: true,
+    })),
+  };
 }
 
 function sanitizePackageJson(packageJson) {
@@ -141,15 +149,21 @@ export function formatPlanText(plan) {
     `- Planned action: ${plan.mcp.action}`,
     `- Auth mode: ${plan.mcp.authMode}; no API keys or OAuth tokens are written.`,
     `- ${plan.mcp.reason}`,
+    '- Verification is separate from install: after apply, restart or reconnect your agent and ask it to call check_distributionos_connection.',
     '',
     'Deployment checklist',
     ...plan.deploymentChecklist.map(item => `- ${item}`),
   ];
 
-  if (plan.analytics.configSnippet) {
-    lines.push('', 'Future-compatible route gate config', plan.analytics.configSnippet);
-  }
-
+  if (plan.analytics.configSnippet) {
+    lines.push('', 'Future-compatible route gate config', plan.analytics.configSnippet);
+  }
+
+  const setupReportLines = formatSetupReportSummary(plan.setupReport);
+  if (setupReportLines.length > 0) {
+    lines.push('', ...setupReportLines);
+  }
+
   if (plan.warnings.length > 0) {
     lines.push('', 'Warnings', ...plan.warnings.map(item => `- ${item}`));
   }
@@ -187,6 +201,7 @@ function nextStepLines(plan) {
   lines.push(
     '',
     'DistributionOS expects to edit only the managed agent instruction block, supported analytics layout, and non-secret project MCP config. Review git diff before committing or deploying.',
+    'After apply, return to the DistributionOS onboarding page. It will wait for a real MCP/API call before letting you continue.',
   );
 
   return lines;

package/src/setup-report.js

@@ -0,0 +1,222 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import {
+  CLI_LOCAL_VERSION,
+  CURRENT_ANALYTICS_CONTRACT_VERSION,
+  CURRENT_BOOTSTRAP_VERSION,
+  CURRENT_SETUP_CONTRACT_VERSION,
+  MCP_SERVER_URL,
+} from './constants.js';
+
+const BOOTSTRAP_BLOCK_RE =
+  /<!--\s*DISTRIBUTIONOS:START([^>]*)-->[\s\S]*?<!--\s*DISTRIBUTIONOS:END\s*-->/i;
+const ANALYTICS_BLOCK_RE =
+  /DISTRIBUTIONOS:START analytics[\s\S]*?DISTRIBUTIONOS:END analytics/i;
+
+export async function buildSetupReport(plan, phase = 'plan', details = {}) {
+  const detectedCapabilities = new Set([
+    'analytics.verificationReady',
+    'setup.reporting',
+  ]);
+  const managedFiles = [];
+  let blockedReason = null;
+
+  const bootstrapVersion = detectBootstrapVersion(plan);
+  if (bootstrapVersion && plan.bootstrap.action === 'none') {
+    detectedCapabilities.add('agent.bootstrap');
+    detectedCapabilities.add('agent.liveInstructions');
+  }
+  managedFiles.push({
+    path: plan.bootstrap.target,
+    type: 'agent.bootstrap',
+    action: plan.bootstrap.action,
+    status: plan.bootstrap.action === 'none' ? 'current' : 'planned',
+    reason: plan.bootstrap.reason,
+  });
+
+  if (plan.mcp?.action === 'none') {
+    detectedCapabilities.add('agent.mcp.remoteConfig');
+  } else if (plan.mcp?.action === 'manual') {
+    blockedReason = plan.mcp.reason;
+  }
+  if (plan.mcp) {
+    managedFiles.push({
+      path: plan.mcp.path,
+      type: 'agent.mcp.remoteConfig',
+      action: plan.mcp.action,
+      status: plan.mcp.action === 'none' ? 'current' : plan.mcp.action === 'manual' ? 'blocked_manual' : 'planned',
+      reason: plan.mcp.reason,
+    });
+  }
+
+  const analytics = await inspectAnalyticsInstall(plan);
+  if (analytics.publicTracker) detectedCapabilities.add('analytics.publicTracker');
+  if (analytics.routePrivacy) detectedCapabilities.add('analytics.routePrivacy');
+  if (plan.analytics.layoutTarget) {
+    managedFiles.push({
+      path: plan.analytics.layoutTarget,
+      type: 'analytics.publicTracker',
+      action: analytics.publicTracker && analytics.routePrivacy ? 'none' : 'update',
+      status: analytics.publicTracker && analytics.routePrivacy ? 'current' : 'planned',
+      reason: analytics.reason,
+    });
+  }
+
+  if (plan.remote?.tokenName && /oauth/i.test(plan.remote.tokenName)) {
+    detectedCapabilities.add('agent.oauthReady');
+  }
+
+  const applyResult = details.applyResult ?? buildApplyResult(details);
+  return {
+    phase,
+    cliVersion: CLI_LOCAL_VERSION,
+    localContractVersion: CURRENT_SETUP_CONTRACT_VERSION,
+    detectedCapabilities: [...detectedCapabilities].sort(),
+    ...(blockedReason ? { blockedReason } : {}),
+    requiresAgentRestart: Boolean(details.requiresAgentRestart),
+    managedFiles: managedFiles.map(sanitizeManagedFile),
+    repo: {
+      framework: plan.repo.framework,
+      packageManager: plan.repo.packageManager,
+      layoutTarget: plan.analytics.layoutTarget ?? null,
+      routeCounts: {
+        allowed: plan.repo.routePrivacy.allowed.length,
+        blocked: plan.repo.routePrivacy.blocked.length,
+        review: plan.repo.routePrivacy.review.length,
+      },
+    },
+    ...(applyResult ? { applyResult } : {}),
+  };
+}
+
+export function formatSetupReportSummary(setupReport) {
+  if (!setupReport) return [];
+  const localSetup = setupReport.result?.localSetup ?? null;
+  const lines = [
+    'Local setup contract',
+    `- CLI version: ${CLI_LOCAL_VERSION}`,
+    `- Local contract: ${CURRENT_SETUP_CONTRACT_VERSION}`,
+  ];
+
+  if (setupReport.status === 'skipped') {
+    lines.push('- Server report: skipped by --skip-setup-report');
+    return lines;
+  }
+
+  if (setupReport.status === 'failed') {
+    lines.push(`- Server report: failed (${setupReport.error})`);
+    lines.push('- Local file changes are still reviewable; DistributionOS may not show the latest install state until reporting succeeds.');
+    return lines;
+  }
+
+  if (!localSetup) {
+    lines.push('- Server report: pending');
+    return lines;
+  }
+
+  lines.push(`- Server status: ${localSetup.status}`);
+  lines.push(`- Missing capabilities: ${formatList(localSetup.missingCapabilities)}`);
+  if (localSetup.status !== 'current') {
+    lines.push(`- Review command: ${localSetup.updateCommand}`);
+    lines.push(`- Apply command: ${localSetup.applyCommand}`);
+  }
+  if (localSetup.requiresAgentRestart) {
+    lines.push('- Agent restart: required after apply so MCP changes load.');
+  }
+  return lines;
+}
+
+function detectBootstrapVersion(plan) {
+  const current = (plan.repo.instructionFiles ?? []).find((file) => file.hasManagedDistributionOsBlock);
+  return current?.managedDistributionOsVersion ??
+    (plan.bootstrap.action === 'none' ? CURRENT_BOOTSTRAP_VERSION : null);
+}
+
+async function inspectAnalyticsInstall(plan) {
+  const target = plan.analytics.layoutTarget;
+  if (!target) {
+    return {
+      publicTracker: false,
+      routePrivacy: false,
+      reason: 'No supported shared analytics layout was detected.',
+    };
+  }
+
+  let content = '';
+  try {
+    content = await fs.readFile(path.join(plan.cwd, target), 'utf8');
+  } catch {
+    return {
+      publicTracker: false,
+      routePrivacy: false,
+      reason: 'Analytics layout could not be read.',
+    };
+  }
+
+  const managed = ANALYTICS_BLOCK_RE.test(content);
+  const publicTracker = managed && content.includes(`${new URL(MCP_SERVER_URL).origin}/api/analytics/script/`);
+  const contractVersion = plan.analytics.contractVersion || CURRENT_ANALYTICS_CONTRACT_VERSION;
+  const routePrivacy =
+    managed &&
+    content.includes('distributionOSAnalyticsConfig') &&
+    content.includes(contractVersion) &&
+    content.includes('/workflow/**') &&
+    content.includes('/workflows/**');
+
+  return {
+    publicTracker,
+    routePrivacy,
+    reason: publicTracker && routePrivacy
+      ? 'Managed analytics install is current.'
+      : 'Managed analytics install is missing or stale.',
+  };
+}
+
+function buildApplyResult(details) {
+  if (!details.changes && !details.validation && !details.inspection) return null;
+  return {
+    changedFiles: [...new Set((details.changes ?? [])
+      .filter((change) => change.changed && change.file)
+      .map((change) => change.file))],
+    validation: (details.validation ?? []).map((result) => ({
+      name: result.name,
+      status: result.exitCode === 0
+        ? 'passed'
+        : result.introducedFailure
+          ? 'failed_after_cli_changes'
+          : result.preExistingFailure
+            ? 'pre_existing_failure'
+            : 'failed',
+    })),
+    inspection: (details.inspection ?? []).map((result) => ({
+      name: result.name,
+      status: result.status,
+    })),
+  };
+}
+
+function sanitizeManagedFile(file) {
+  return {
+    path: file.path,
+    type: file.type,
+    action: file.action,
+    status: file.status,
+    reason: file.reason,
+  };
+}
+
+function formatList(values) {
+  if (!Array.isArray(values) || values.length === 0) return 'none';
+  return values.join(', ');
+}
+
+export function extractBootstrapMetadata(content) {
+  const match = String(content ?? '').match(BOOTSTRAP_BLOCK_RE);
+  if (!match) return { hasManagedDistributionOsBlock: false, version: null, appId: null };
+  const attrs = match[1] ?? '';
+  return {
+    hasManagedDistributionOsBlock: true,
+    version: attrs.match(/\bversion=([^\s>]+)/i)?.[1] ?? null,
+    appId: attrs.match(/\bappId=([^\s>]+)/i)?.[1] ?? null,
+  };
+}