@distributionos/cli 0.1.10 → 0.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@distributionos/cli",
-  "version": "0.1.10",
+  "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,7 +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.',
+      '- 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

@@ -0,0 +1,187 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { MCP_SERVER_URL } from './constants.js';
+import { pathExists } from './detect.js';
+
+export const PROJECT_MCP_CONFIG_PATH = '.mcp.json';
+export const DISTRIBUTIONOS_MCP_SERVER_NAME = 'distributionos';
+
+export async function buildProjectMcpConfigPlan(cwd, serverUrl = MCP_SERVER_URL) {
+  const target = safeResolve(cwd, PROJECT_MCP_CONFIG_PATH);
+  const base = {
+    path: PROJECT_MCP_CONFIG_PATH,
+    serverName: DISTRIBUTIONOS_MCP_SERVER_NAME,
+    serverUrl,
+    authMode: 'oauth',
+    requiresRestart: true,
+    writesSecrets: false,
+    recommendedConfig: recommendedMcpConfig(serverUrl),
+  };
+
+  if (!(await pathExists(target))) {
+    return {
+      ...base,
+      supported: true,
+      action: 'create',
+      reason: 'Create a project-local MCP config with the DistributionOS remote server URL only.',
+    };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(await fs.readFile(target, 'utf8'));
+  } catch {
+    return {
+      ...base,
+      supported: false,
+      action: 'manual',
+      reason: 'Existing .mcp.json is not valid JSON, so the CLI will not edit it automatically.',
+    };
+  }
+
+  if (!isRecord(parsed)) {
+    return {
+      ...base,
+      supported: false,
+      action: 'manual',
+      reason: 'Existing .mcp.json is not an object, so the CLI will not edit it automatically.',
+    };
+  }
+
+  if (containsSecretLikeConfig(parsed)) {
+    return {
+      ...base,
+      supported: false,
+      action: 'manual',
+      reason: 'Existing .mcp.json appears to contain secret headers, tokens, or env values. The CLI will not rewrite it.',
+    };
+  }
+
+  const servers = isRecord(parsed.mcpServers) ? parsed.mcpServers : {};
+  const existing = servers[DISTRIBUTIONOS_MCP_SERVER_NAME];
+  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 && existingType === 'http') {
+    return {
+      ...base,
+      supported: true,
+      action: 'none',
+      reason: 'Project-local MCP config already includes the DistributionOS server.',
+    };
+  }
+
+  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,
+      supported: false,
+      action: 'manual',
+      reason: 'Existing distributionos MCP server points to a different URL. The CLI will not overwrite it automatically.',
+    };
+  }
+
+  return {
+    ...base,
+    supported: true,
+    action: 'update',
+    reason: 'Add the DistributionOS remote MCP server to the existing project-local MCP config.',
+  };
+}
+
+export async function applyProjectMcpConfig(cwd, plan) {
+  if (!plan || plan.action === 'none') {
+    return { type: 'mcp', changed: false, file: plan?.path ?? PROJECT_MCP_CONFIG_PATH, reason: plan?.reason ?? 'No MCP config change planned.' };
+  }
+
+  if (plan.action === 'manual' || !plan.supported) {
+    return { type: 'mcp', changed: false, file: plan.path, reason: plan.reason };
+  }
+
+  const target = safeResolve(cwd, plan.path);
+  let existing = {};
+  if (await pathExists(target)) {
+    existing = JSON.parse(await fs.readFile(target, 'utf8'));
+  }
+  if (!isRecord(existing)) {
+    return { type: 'mcp', changed: false, file: plan.path, reason: 'Existing MCP config was not an object.' };
+  }
+
+  const next = {
+    ...existing,
+    mcpServers: {
+      ...(isRecord(existing.mcpServers) ? existing.mcpServers : {}),
+      [DISTRIBUTIONOS_MCP_SERVER_NAME]: {
+        type: 'http',
+        url: plan.serverUrl ?? MCP_SERVER_URL,
+      },
+    },
+  };
+
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await fs.writeFile(target, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+  return {
+    type: 'mcp',
+    changed: true,
+    file: plan.path,
+    action: plan.action === 'create' ? 'created' : 'updated',
+  };
+}
+
+function recommendedMcpConfig(serverUrl) {
+  return {
+    mcpServers: {
+      [DISTRIBUTIONOS_MCP_SERVER_NAME]: {
+        type: 'http',
+        url: serverUrl,
+      },
+    },
+  };
+}
+
+function containsSecretLikeConfig(value) {
+  if (Array.isArray(value)) return value.some(containsSecretLikeConfig);
+  if (!isRecord(value)) return false;
+  for (const [key, nested] of Object.entries(value)) {
+    if (/authorization|api[-_]?key|token|secret|password|credential|headers|env/i.test(key)) {
+      if (nested !== null && nested !== undefined && nested !== '') return true;
+    }
+    if (containsSecretLikeConfig(nested)) return true;
+  }
+  return false;
+}
+
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function safeResolve(cwd, relativePath) {
+  const root = path.resolve(cwd);
+  const target = path.resolve(root, relativePath);
+  const relative = path.relative(root, target);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`Refusing to write outside repo root: ${relativePath}`);
+  }
+  return target;
+}

package/src/mutate.js

@@ -1,5 +1,6 @@
-import { promises as fs } from 'node:fs';
-import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { applyProjectMcpConfig } from './mcp-config.js';
 
 const BOOTSTRAP_BLOCK_RE =
   /<!--\s*DISTRIBUTIONOS:START[\s\S]*?DISTRIBUTIONOS:END\s*-->/i;
@@ -17,13 +18,16 @@ export async function applySetupPlan(plan, options = {}) {
   const bootstrap = await applyBootstrap(plan.cwd, plan.bootstrap);
   if (bootstrap.changed) changes.push(bootstrap);
 
-  if (!options.skipAnalytics) {
-    const analytics = await applyAnalytics(plan.cwd, plan.analytics);
-    if (analytics.changed || analytics.reason) changes.push(analytics);
-  }
-
-  return changes;
-}
+  if (!options.skipAnalytics) {
+    const analytics = await applyAnalytics(plan.cwd, plan.analytics);
+    if (analytics.changed || analytics.reason) changes.push(analytics);
+  }
+
+  const mcp = await applyProjectMcpConfig(plan.cwd, plan.mcp);
+  if (mcp.changed || mcp.reason) changes.push(mcp);
+
+  return changes;
+}
 
 async function applyBootstrap(cwd, bootstrap) {
   const targetPath = safeResolve(cwd, bootstrap.target);

package/src/plan.js

@@ -10,11 +10,16 @@ import {
   buildSetupCommand,
   getBootstrapAction,
 } from './bootstrap.js';
-import { scanRepo } from './detect.js';
-import {
-  buildAnalyticsRouteConfigScript,
-  buildAnalyticsRouteConfigSnippet,
-} from './privacy.js';
+import { scanRepo } from './detect.js';
+import { buildProjectMcpConfigPlan } from './mcp-config.js';
+import {
+  buildAnalyticsRouteConfigScript,
+  buildAnalyticsRouteConfigSnippet,
+} from './privacy.js';
+import {
+  extractBootstrapMetadata,
+  formatSetupReportSummary,
+} from './setup-report.js';
 
 export async function createSetupPlan(options) {
   const cwd = options.cwd;
@@ -33,10 +38,11 @@ export async function createSetupPlan(options) {
     remote.instructions?.recommendedBootstrapBlock ??
     buildLocalBootstrapBlock(instructionPackVersion, appId);
   const bootstrap = getBootstrapAction(repo.instructionFiles, recommendedBootstrapBlock);
-  const analyticsContract = remote.analyticsContract;
-  const planRepo = sanitizeRepoForPlan(repo);
-
-  return {
+  const analyticsContract = remote.analyticsContract;
+  const planRepo = sanitizeRepoForPlan(repo);
+  const mcp = await buildProjectMcpConfigPlan(cwd);
+
+  return {
     appId,
     cwd,
     mode: options.apply ? 'apply' : 'review',
@@ -47,35 +53,41 @@ export async function createSetupPlan(options) {
     repo: planRepo,
     remote,
     instructionPackVersion,
-    bootstrap,
-    analytics: buildAnalyticsPlan({ analyticsContract, repo: planRepo, instructionPackVersion }),
+    bootstrap,
+    mcp,
+    analytics: buildAnalyticsPlan({ analyticsContract, repo: planRepo, instructionPackVersion }),
     fallbackInstructions: buildFallbackMcpInstructions(appId),
     warnings: buildWarnings({ repo: planRepo, remote }),
     validation: buildValidationPlan(planRepo),
-    deploymentChecklist: [
-      'Review this plan and any proposed file edits.',
-      'Apply reviewed bootstrap and analytics changes only.',
-      'Run baseline tests before mutation when the worktree is messy.',
+    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) {
@@ -113,11 +125,12 @@ export function formatPlanText(plan) {
     ...plan.remote.errors.map(error => `- ${error}`),
     '',
     'Planned changes',
-    `1. Agent bootstrap: ${plan.bootstrap.action} ${plan.bootstrap.target}`,
-    `   ${plan.bootstrap.reason}`,
-    `2. Agent instructions: ${plan.remote.instructions ? 'use fetched current instruction pack' : 'use fallback MCP/OAuth instructions until authenticated'}`,
-    `3. Analytics: ${analyticsSummary(plan.analytics)}`,
-    '',
+    `1. Agent bootstrap: ${plan.bootstrap.action} ${plan.bootstrap.target}`,
+    `   ${plan.bootstrap.reason}`,
+    `2. Agent instructions: ${plan.remote.instructions ? 'use fetched current instruction pack' : 'use fallback MCP/OAuth instructions until authenticated'}`,
+    `3. Analytics: ${analyticsSummary(plan.analytics)}`,
+    `4. Agent MCP config: ${mcpSummary(plan.mcp)}`,
+    '',
     'Route privacy review',
     `- Allowed public candidates: ${formatList(plan.repo.routePrivacy.allowed, 8)}`,
     `- Blocked private candidates: ${formatList(plan.repo.routePrivacy.blocked, 8)}`,
@@ -128,17 +141,29 @@ export function formatPlanText(plan) {
     `- Test: ${plan.validation.test ?? 'not detected'}`,
     `- Lint: ${plan.validation.lint ?? 'not detected'}`,
     '',
-    'Fallback MCP/OAuth instructions',
-    ...plan.fallbackInstructions.map(item => `- ${item}`),
-    '',
+    'Fallback MCP/OAuth instructions',
+    ...plan.fallbackInstructions.map(item => `- ${item}`),
+    '',
+    'Agent live-data connection',
+    `- Project config: ${plan.mcp.path}`,
+    `- 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}`));
   }
@@ -175,7 +200,8 @@ function nextStepLines(plan) {
 
   lines.push(
     '',
-    'DistributionOS expects to edit only the managed agent instruction block and the supported analytics layout. Review git diff before committing or deploying.',
+    '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;
@@ -307,7 +333,7 @@ function meterText(value) {
   return `${value.used ?? 0}/${limit}`;
 }
 
-function analyticsSummary(analytics) {
+function analyticsSummary(analytics) {
   if (analytics.status === 'enabled') {
     return `contract ${analytics.contractVersion}; install script in ${analytics.layoutTarget ?? 'reviewed shared layout'}`;
   }
@@ -315,7 +341,15 @@ function analyticsSummary(analytics) {
     return 'tracker will be created or fetched during apply before analytics is installed';
   }
   return 'contract not fetched; print manual guidance only';
-}
+}
+
+function mcpSummary(mcp) {
+  if (!mcp) return 'manual instructions only';
+  if (mcp.action === 'none') return `${mcp.path} already includes DistributionOS`;
+  if (mcp.action === 'create') return `create ${mcp.path} with DistributionOS MCP server URL`;
+  if (mcp.action === 'update') return `update ${mcp.path} with DistributionOS MCP server URL`;
+  return `manual setup needed for ${mcp.path}`;
+}
 
 function formatList(values, limit = 5) {
   if (!values || values.length === 0) return 'none';

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,
+  };
+}