auditor-lambda 0.2.5 → 0.2.8

package/audit-code-wrapper-lib.mjs

@@ -1,4 +1,4 @@
-import { access, mkdir, open, readFile, readdir, stat, unlink, writeFile } from 'node:fs/promises';
+import { access, cp, mkdir, open, readFile, readdir, stat, unlink, writeFile } from 'node:fs/promises';
 import { constants } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { dirname, join, relative, resolve } from 'node:path';
@@ -18,9 +18,13 @@ const BUILD_LOCK_WAIT_INTERVAL_MS = 200;
 const INSTALL_MARKER_START = '<!-- audit-code:begin -->';
 const INSTALL_MARKER_END = '<!-- audit-code:end -->';
 const INSTALL_GUIDE_FILENAME = 'GETTING-STARTED.md';
+const INSTALL_MANIFEST_FILENAME = 'manifest.json';
 const DEFAULT_INSTALL_HOST = 'all';
 const INSTALLED_PROMPT_FILENAME = 'audit-code.import.md';
+const MCP_LAUNCHER_FILENAME = 'run-mcp-server.mjs';
 const packageVersion = JSON.parse(await readFile(packageJsonPath, 'utf8')).version;
+const MCP_PROTOCOL_VERSION = '2025-06-18';
+const INSTALL_VERIFY_TIMEOUT_MS = 10_000;
 
 function hasFlag(argv, name) {
   return argv.includes(name);
@@ -234,13 +238,17 @@ async function ensureBuilt() {
 
 function printHelp({ usageName, preferredEntrypoint }) {
   const lines = [
-    `Usage: node ${usageName} [--single-step] [--root PATH] [--artifacts-dir PATH] [--results FILE] [--updates FILE] [--external-analyzer-results FILE]`,
+    `Usage: node ${usageName} [--single-step] [--root PATH] [--artifacts-dir PATH] [--results FILE] [--batch-results DIR] [--updates FILE] [--external-analyzer-results FILE] [--timeout MS]`,
     '',
     'Helper commands:',
     '- prompt-path prints the absolute path to the canonical /audit-code prompt asset',
     '- install bootstraps /audit-code into supported repo-local host surfaces',
+    '- verify-install smoke-tests the generated host assets and repo-local MCP launchers after install',
+    '- mcp starts the local stdio MCP server for repo-local IDE integrations',
     '- install-host --host copilot keeps the narrower Copilot-focused install path available',
     '- validate checks the current artifact bundle plus session-config/provider readiness and exits non-zero when issues exist',
+    '- validate-results --results FILE validates AuditResult payloads against the active task manifest without ingesting them',
+    '- explain-task <task_id> prints the resolved file coverage and current status for a task id',
     '',
     'Primary usage:',
     '- from the repository root, run the wrapper with no arguments',
@@ -333,132 +341,698 @@ function buildInstallDirective(relativePromptPath) {
   ].join('\n');
 }
 
-function buildInstallHostGuidance({
-  installedPromptPath,
-  slashCommandSurfaces,
-  instructionSurfaces,
-}) {
-  const guidance = [];
+function upsertManagedBlock(existingContent, blockContent) {
+  const normalized = normalizeNewlines(existingContent);
+  const blockPattern = new RegExp(
+    `${INSTALL_MARKER_START}[\\s\\S]*?${INSTALL_MARKER_END}`,
+    'u',
+  );
 
-  if (slashCommandSurfaces.vscode_prompt) {
-    guidance.push({
-      host: 'vscode',
-      label: 'VS Code',
-      support_level: 'supported',
-      setup_kind: 'repo-local-slash-command',
-      summary:
-        'Use the generated VS Code / Copilot prompt surface, then invoke `/audit-code` in chat.',
-      primary_path: slashCommandSurfaces.vscode_prompt,
-      supporting_paths: [
-        instructionSurfaces.copilot_instructions,
-        instructionSurfaces.agents,
-      ].filter(Boolean),
-      steps: [
-        'Open this repository in VS Code or GitHub Copilot Chat.',
-        'Invoke `/audit-code` in chat.',
-        'Use the integrated terminal and run `audit-code` only when you intentionally need the repo-local backend fallback.',
-      ],
-    });
+  if (blockPattern.test(normalized)) {
+    return normalized.replace(blockPattern, blockContent);
   }
 
-  if (slashCommandSurfaces.opencode_command) {
-    guidance.push({
-      host: 'opencode',
-      label: 'OpenCode',
-      support_level: 'supported',
-      setup_kind: 'repo-local-slash-command',
-      summary:
-        'Use the generated OpenCode command surface so `/audit-code` is available without extra provider flags.',
-      primary_path: slashCommandSurfaces.opencode_command,
-      supporting_paths: [instructionSurfaces.agents].filter(Boolean),
-      steps: [
-        'Open this repository in OpenCode.',
-        'Invoke `/audit-code` from the OpenCode command surface.',
-        'Use the repo-local backend wrapper only when you intentionally need the fallback automation path.',
-      ],
-    });
+  if (normalized.trim().length === 0) {
+    return `${blockContent}\n`;
   }
 
-  if (slashCommandSurfaces.claude_code_command) {
-    guidance.push({
-      host: 'claude-code',
-      label: 'Claude Code',
-      support_level: 'supported',
-      setup_kind: 'repo-local-slash-command',
-      summary:
-        'Use the generated Claude Code command surface so `/audit-code` is available inside the repository without extra provider wiring.',
-      primary_path: slashCommandSurfaces.claude_code_command,
-      supporting_paths: [instructionSurfaces.claude].filter(Boolean),
-      steps: [
-        'Open this repository in Claude Code.',
-        'Invoke `/audit-code` from the Claude Code project command surface.',
-        'Use the terminal fallback and run `audit-code` only when you intentionally need the repo-local backend wrapper.',
-      ],
-    });
-  }
+  return `${normalized.replace(/\s+$/u, '')}\n\n${blockContent}\n`;
+}
 
-  guidance.push({
-    host: 'claude-desktop',
-    label: 'Claude Desktop',
-    support_level: 'manual-import',
-    setup_kind: 'prompt-import',
-    summary:
-      'No verified project-local slash-command surface is shipped for Claude Desktop, so use the installed prompt asset as the primary path.',
-    primary_path: installedPromptPath,
-    supporting_paths: [instructionSurfaces.claude].filter(Boolean),
-    steps: [
-      'Import the installed prompt asset into Claude Desktop\'s prompt or instruction surface.',
-      'Invoke `/audit-code` conversationally inside Claude Desktop after the prompt is available.',
-      'If you intentionally need the repo-local backend fallback instead, run `audit-code` from the repository root.',
-    ],
-  });
+async function writeManagedMarkdown(targetPath, blockContent) {
+  const existed = await fileExists(targetPath);
+  const existingContent = existed ? await readFile(targetPath, 'utf8') : '';
+  const nextContent = upsertManagedBlock(existingContent, blockContent);
+  await mkdir(dirname(targetPath), { recursive: true });
+  await writeFile(targetPath, nextContent, 'utf8');
+  return {
+    path: targetPath,
+    mode: existed ? 'updated' : 'created',
+  };
+}
 
-  guidance.push({
-    host: 'antigravity',
-    label: 'Antigravity',
-    support_level: 'manual-import',
-    setup_kind: 'prompt-import-or-terminal',
-    summary:
-      'No verified repo-local slash-command surface is shipped for Antigravity, so start from the installed prompt asset or an Antigravity-managed terminal.',
-    primary_path: installedPromptPath,
-    supporting_paths: [instructionSurfaces.agents].filter(Boolean),
-    steps: [
-      'Import the installed prompt asset into Antigravity\'s prompt or instruction surface when that surface is available.',
-      'Invoke `/audit-code` conversationally inside Antigravity.',
-      'If you prefer the backend fallback, run `audit-code` from an Antigravity-managed terminal with `local-subprocess` first.',
-    ],
-  });
+async function writeGeneratedMarkdown(targetPath, content) {
+  const existed = await fileExists(targetPath);
+  await mkdir(dirname(targetPath), { recursive: true });
+  await writeFile(targetPath, content, 'utf8');
+  return {
+    path: targetPath,
+    mode: existed ? 'updated' : 'created',
+  };
+}
 
-  return guidance;
+async function writeGeneratedJson(targetPath, value) {
+  const existed = await fileExists(targetPath);
+  await mkdir(dirname(targetPath), { recursive: true });
+  await writeFile(targetPath, JSON.stringify(value, null, 2) + '\n', 'utf8');
+  return {
+    path: targetPath,
+    mode: existed ? 'updated' : 'created',
+  };
 }
 
-function renderInstallHostSection(root, guide) {
-  const lines = [
-    `## ${guide.label}`,
+async function writeGeneratedBinary(targetPath, content) {
+  const existed = await fileExists(targetPath);
+  await mkdir(dirname(targetPath), { recursive: true });
+  await writeFile(targetPath, content);
+  return {
+    path: targetPath,
+    mode: existed ? 'updated' : 'created',
+  };
+}
+
+function replaceBackslashes(value) {
+  return value.replace(/\\/g, '/');
+}
+
+function renderVSCodeAgentFile() {
+  return [
+    '---',
+    'description: Plan and orchestrate /audit-code with the installed auditor MCP server before making code changes.',
+    '---',
     '',
-    `Support level: ${guide.support_level}`,
-    `Setup kind: ${guide.setup_kind}`,
+    '# Auditor Agent',
     '',
-    guide.summary,
+    'Use the installed auditor MCP server as the primary integration surface for the audit workflow.',
     '',
-    'Primary repo-local path:',
-    `- \`${toRepoRelativePath(root, guide.primary_path)}\``,
-  ];
+    'When the user asks to run or continue `/audit-code`:',
+    '',
+    '- call the `start_audit`, `get_status`, and `continue_audit` MCP tools instead of reconstructing backend state manually',
+    '- read `audit-code://handoff/current` and `audit-code://artifacts/current` when the audit blocks or you need current context',
+    '- prefer imported audit results and runtime updates over ad hoc manual state edits',
+    '- treat the deterministic audit report as the final source of truth once the audit completes',
+    '',
+  ].join('\n');
+}
+
+function renderCodexMcpSetupGuide(root) {
+  return [
+    '# Codex MCP setup',
+    '',
+    'Codex shares MCP configuration between the app, CLI, and IDE extension. Register a local stdio MCP server named `auditor` that launches the repo-local wrapper below.',
+    '',
+    'Recommended command:',
+    `- command: \`node\``,
+    `- args: \`${toRepoRelativePath(root, join(root, '.audit-code', 'install', MCP_LAUNCHER_FILENAME))}\``,
+    '',
+    'Equivalent config shape:',
+    '',
+    '```toml',
+    '[mcp_servers.auditor]',
+    'command = "node"',
+    `args = ["${replaceBackslashes(toRepoRelativePath(root, join(root, '.audit-code', 'install', MCP_LAUNCHER_FILENAME)))}"]`,
+    '```',
+    '',
+    'Once the server is registered, ask Codex to use the `auditor` MCP tools to start or continue the audit.',
+    '',
+  ].join('\n');
+}
+
+function renderCodexAutomationRecipe() {
+  return [
+    '# Codex re-audit automation recipe',
+    '',
+    'Suggested recurring task:',
+    '',
+    '- Prompt: Re-run the autonomous audit workflow for this repository. Use the installed auditor MCP tools, summarize only new or regressed findings, and stop once the deterministic report is current.',
+    '- Cadence: daily on active branches or before release cut-offs',
+    '- Inputs: repository root plus the installed `auditor` MCP server',
+    '',
+    'Use this recipe as a starting point for a Codex automation once the local workflow is stable in your environment.',
+    '',
+  ].join('\n');
+}
 
-  if (guide.supporting_paths.length > 0) {
-    lines.push('', 'Supporting repo-local paths:');
-    for (const targetPath of guide.supporting_paths) {
-      lines.push(`- \`${toRepoRelativePath(root, targetPath)}\``);
+function renderOpenCodeProjectConfig(root) {
+  const launcher = replaceBackslashes(toRepoRelativePath(root, join(root, '.audit-code', 'install', MCP_LAUNCHER_FILENAME)));
+  return JSON.stringify(
+    {
+      $schema: 'https://opencode.ai/config.json',
+      mcp: {
+        auditor: {
+          type: 'local',
+          command: ['node', launcher],
+          enabled: true,
+          timeout: 10000,
+        },
+      },
+      permission: {
+        read: 'allow',
+        glob: 'allow',
+        grep: 'allow',
+        edit: 'ask',
+        bash: {
+          '*': 'ask',
+          'git status*': 'allow',
+          'git diff*': 'allow',
+          'grep *': 'allow',
+          'rm *': 'deny',
+        },
+      },
+      agent: {
+        auditor: {
+          description:
+            'Read-heavy audit orchestration agent for the /audit-code workflow.',
+          tools: {
+            'auditor*': true,
+          },
+          permission: {
+            edit: 'ask',
+            bash: {
+              '*': 'ask',
+              'git status*': 'allow',
+              'git diff*': 'allow',
+              'grep *': 'allow',
+              'rm *': 'deny',
+            },
+            question: 'allow',
+          },
+        },
+      },
+    },
+    null,
+    2,
+  ) + '\n';
+}
+
+function renderVSCodeMcpConfig() {
+  return JSON.stringify(
+    {
+      servers: {
+        auditor: {
+          type: 'stdio',
+          command: 'node',
+          args: ['${workspaceFolder}/.audit-code/install/run-mcp-server.mjs'],
+        },
+      },
+    },
+    null,
+    2,
+  ) + '\n';
+}
+
+function renderClaudeDesktopProjectTemplate() {
+  return [
+    '# Claude Desktop project template',
+    '',
+    'Suggested project instructions:',
+    '',
+    '- Treat `/audit-code` as the canonical autonomous audit workflow for this repository.',
+    '- Prefer the installed auditor MCP tools over recreating state manually.',
+    '- Read the operator handoff and artifact resources before asking for more context.',
+    '- Present the final deterministic audit report as work blocks first.',
+    '',
+    'Suggested project knowledge uploads:',
+    '',
+    '- `.audit-code/install/audit-code.import.md`',
+    '- `.audit-code/install/GETTING-STARTED.md`',
+    '- `docs/agent-integrations.md` when you want host-specific operator context',
+    '',
+    'Starter prompt:',
+    '',
+    '> Start `/audit-code` for this repository using the installed auditor MCP tools. Continue until the audit is complete or blocked for operator input, and summarize the current handoff status before you stop.',
+    '',
+  ].join('\n');
+}
+
+function renderClaudeDesktopRemoteConnectorTemplate() {
+  return JSON.stringify(
+    {
+      name: 'auditor-lambda',
+      transport: 'remote-mcp',
+      url: 'https://example.com/auditor-lambda/mcp',
+      notes: [
+        'Replace the URL with your hosted auditor MCP endpoint.',
+        'Expose the same tool names as the local bundle: start_audit, get_status, continue_audit, explain_task, validate_artifacts, import_results, import_runtime_updates.',
+        'Use OAuth or host-level auth when deploying this connector for Team or Enterprise rollouts.',
+      ],
+    },
+    null,
+    2,
+  ) + '\n';
+}
+
+function renderAntigravityPlanningGuide(root) {
+  return [
+    '# Antigravity planning-mode guide',
+    '',
+    'Recommended workflow:',
+    '',
+    '1. Open Antigravity in Planning mode.',
+    '2. Load the repo-local prompt asset or the AGENTS instructions before starting the audit conversation.',
+    '3. Ask Antigravity to use the installed auditor MCP server for structured state inspection and continuation.',
+    '4. Review Antigravity artifacts before accepting major code changes or imported evidence.',
+    '',
+    'Recommended repo-local paths:',
+    `- prompt asset: \`${toRepoRelativePath(root, join(root, '.audit-code', 'install', INSTALLED_PROMPT_FILENAME))}\``,
+    `- MCP launcher: \`${toRepoRelativePath(root, join(root, '.audit-code', 'install', MCP_LAUNCHER_FILENAME))}\``,
+    '',
+    'Artifact round-tripping policy:',
+    '',
+    '- Browser walkthroughs and validation artifacts should be converted into runtime validation updates before import.',
+    '- Task-specific review artifacts should be normalized into `AuditResult` payloads before using `import_results`.',
+    '',
+  ].join('\n');
+}
+
+function renderSharedMcpLauncher(sourcePackageRoot) {
+  return [
+    "import { access, readFile } from 'node:fs/promises';",
+    "import { constants } from 'node:fs';",
+    "import { spawn } from 'node:child_process';",
+    "import { dirname, join, resolve } from 'node:path';",
+    "import { fileURLToPath } from 'node:url';",
+    '',
+    'const scriptDir = dirname(fileURLToPath(import.meta.url));',
+    "const repoRoot = resolve(scriptDir, '..', '..');",
+    "const artifactsDir = join(repoRoot, '.audit-artifacts');",
+    `const sourcePackageRoot = ${JSON.stringify(sourcePackageRoot)};`,
+    '',
+    'async function exists(path) {',
+    '  try {',
+    '    await access(path, constants.F_OK);',
+    '    return true;',
+    '  } catch {',
+    '    return false;',
+    '  }',
+    '}',
+    '',
+    'function spawnForward(command, args) {',
+    '  return new Promise((resolvePromise, rejectPromise) => {',
+    '    const child = spawn(command, args, {',
+    '      cwd: repoRoot,',
+    '      env: process.env,',
+    "      stdio: ['inherit', 'inherit', 'inherit'],",
+    '    });',
+    "    child.on('error', rejectPromise);",
+    "    child.on('exit', (code) => resolvePromise(code ?? 1));",
+    '  });',
+    '}',
+    '',
+    'async function tryCandidates() {',
+    "  const localPackageEntrypoint = join(repoRoot, 'node_modules', 'auditor-lambda', 'audit-code.mjs');",
+    "  const localBin = process.platform === 'win32'",
+    "    ? join(repoRoot, 'node_modules', '.bin', 'audit-code.cmd')",
+    "    : join(repoRoot, 'node_modules', '.bin', 'audit-code');",
+    "  const repoPackageJsonPath = join(repoRoot, 'package.json');",
+    "  const sourcePackageEntrypoint = sourcePackageRoot",
+    "    ? join(sourcePackageRoot, 'audit-code.mjs')",
+    "    : null;",
+    "  const sourcePackageJsonPath = sourcePackageRoot",
+    "    ? join(sourcePackageRoot, 'package.json')",
+    "    : null;",
+    '  const sharedArgs = [\'mcp\', \'--root\', repoRoot, \'--artifacts-dir\', artifactsDir];',
+    '',
+    '  if (await exists(localPackageEntrypoint)) {',
+    '    return await spawnForward(process.execPath, [localPackageEntrypoint, ...sharedArgs]);',
+    '  }',
+    '',
+    '  if (await exists(repoPackageJsonPath) && await exists(join(repoRoot, \'audit-code.mjs\'))) {',
+    '    try {',
+    "      const packageJson = JSON.parse(await readFile(repoPackageJsonPath, 'utf8'));",
+    "      if (packageJson?.name === 'auditor-lambda') {",
+    "        return await spawnForward(process.execPath, [join(repoRoot, 'audit-code.mjs'), ...sharedArgs]);",
+    '      }',
+    '    } catch {',
+    '      // fall through to the next candidate',
+    '    }',
+    '  }',
+    '',
+    '  if (sourcePackageEntrypoint && sourcePackageJsonPath && await exists(sourcePackageEntrypoint) && await exists(sourcePackageJsonPath)) {',
+    '    try {',
+    "      const packageJson = JSON.parse(await readFile(sourcePackageJsonPath, 'utf8'));",
+    "      if (packageJson?.name === 'auditor-lambda') {",
+    '        return await spawnForward(process.execPath, [sourcePackageEntrypoint, ...sharedArgs]);',
+    '      }',
+    '    } catch {',
+    '      // fall through to the next candidate',
+    '    }',
+    '  }',
+    '',
+    '  if (await exists(localBin)) {',
+    '    return await spawnForward(localBin, sharedArgs);',
+    '  }',
+    '',
+    "  const pathCandidate = process.platform === 'win32' ? 'audit-code.cmd' : 'audit-code';",
+    '  let exitCode = await spawnForward(pathCandidate, sharedArgs).catch(() => null);',
+    '  if (typeof exitCode === \'number\') {',
+    '    return exitCode;',
+    '  }',
+    '',
+    "  exitCode = await spawnForward('npx', ['--no-install', 'audit-code', ...sharedArgs]).catch(() => null);",
+    "  if (typeof exitCode === 'number') {",
+    '    return exitCode;',
+    '  }',
+    '',
+    '  throw new Error(',
+    "    'Unable to locate an audit-code executable. Install auditor-lambda as a dependency or make the audit-code binary available on PATH.',",
+    '  );',
+    '}',
+    '',
+    'const code = await tryCandidates();',
+    'process.exitCode = code;',
+    '',
+  ].join('\n');
+}
+
+function createCrc32Table() {
+  const table = new Uint32Array(256);
+  for (let index = 0; index < 256; index += 1) {
+    let value = index;
+    for (let bit = 0; bit < 8; bit += 1) {
+      value = (value & 1) !== 0 ? (0xedb88320 ^ (value >>> 1)) : (value >>> 1);
     }
+    table[index] = value >>> 0;
   }
+  return table;
+}
 
-  lines.push('', 'Recommended steps:');
-  for (const step of guide.steps) {
-    lines.push(`- ${step}`);
+const CRC32_TABLE = createCrc32Table();
+
+function crc32(buffer) {
+  let crc = 0xffffffff;
+  for (const byte of buffer) {
+    crc = CRC32_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
   }
-  lines.push('');
+  return (crc ^ 0xffffffff) >>> 0;
+}
 
-  return lines.join('\n');
+async function listFilesRecursive(root) {
+  const files = [];
+  const entries = await readdir(root, { withFileTypes: true });
+  for (const entry of entries) {
+    const absolutePath = join(root, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await listFilesRecursive(absolutePath)));
+      continue;
+    }
+    if (entry.isFile()) {
+      files.push(absolutePath);
+    }
+  }
+  return files.sort((a, b) => a.localeCompare(b));
+}
+
+async function createStoredZipBuffer(sourceDir) {
+  const absoluteFiles = await listFilesRecursive(sourceDir);
+  const localParts = [];
+  const centralParts = [];
+  let offset = 0;
+
+  for (const absolutePath of absoluteFiles) {
+    const relativePath = replaceBackslashes(relative(sourceDir, absolutePath));
+    const fileName = Buffer.from(relativePath, 'utf8');
+    const content = await readFile(absolutePath);
+    const checksum = crc32(content);
+
+    const localHeader = Buffer.alloc(30);
+    localHeader.writeUInt32LE(0x04034b50, 0);
+    localHeader.writeUInt16LE(20, 4);
+    localHeader.writeUInt16LE(0, 6);
+    localHeader.writeUInt16LE(0, 8);
+    localHeader.writeUInt16LE(0, 10);
+    localHeader.writeUInt16LE(0, 12);
+    localHeader.writeUInt32LE(checksum, 14);
+    localHeader.writeUInt32LE(content.length, 18);
+    localHeader.writeUInt32LE(content.length, 22);
+    localHeader.writeUInt16LE(fileName.length, 26);
+    localHeader.writeUInt16LE(0, 28);
+
+    localParts.push(localHeader, fileName, content);
+
+    const centralHeader = Buffer.alloc(46);
+    centralHeader.writeUInt32LE(0x02014b50, 0);
+    centralHeader.writeUInt16LE(20, 4);
+    centralHeader.writeUInt16LE(20, 6);
+    centralHeader.writeUInt16LE(0, 8);
+    centralHeader.writeUInt16LE(0, 10);
+    centralHeader.writeUInt16LE(0, 12);
+    centralHeader.writeUInt16LE(0, 14);
+    centralHeader.writeUInt32LE(checksum, 16);
+    centralHeader.writeUInt32LE(content.length, 20);
+    centralHeader.writeUInt32LE(content.length, 24);
+    centralHeader.writeUInt16LE(fileName.length, 28);
+    centralHeader.writeUInt16LE(0, 30);
+    centralHeader.writeUInt16LE(0, 32);
+    centralHeader.writeUInt16LE(0, 34);
+    centralHeader.writeUInt16LE(0, 36);
+    centralHeader.writeUInt32LE(0, 38);
+    centralHeader.writeUInt32LE(offset, 42);
+
+    centralParts.push(centralHeader, fileName);
+    offset += localHeader.length + fileName.length + content.length;
+  }
+
+  const centralDirectory = Buffer.concat(centralParts);
+  const endOfCentralDirectory = Buffer.alloc(22);
+  endOfCentralDirectory.writeUInt32LE(0x06054b50, 0);
+  endOfCentralDirectory.writeUInt16LE(0, 4);
+  endOfCentralDirectory.writeUInt16LE(0, 6);
+  endOfCentralDirectory.writeUInt16LE(absoluteFiles.length, 8);
+  endOfCentralDirectory.writeUInt16LE(absoluteFiles.length, 10);
+  endOfCentralDirectory.writeUInt32LE(centralDirectory.length, 12);
+  endOfCentralDirectory.writeUInt32LE(offset, 16);
+  endOfCentralDirectory.writeUInt16LE(0, 20);
+
+  return Buffer.concat([...localParts, centralDirectory, endOfCentralDirectory]);
+}
+
+async function buildClaudeDesktopBundle(root, results) {
+  const bundleRoot = join(root, '.audit-code', 'install', 'claude-desktop', 'bundle');
+  const serverRoot = join(bundleRoot, 'server');
+  const manifestPath = join(bundleRoot, 'manifest.json');
+  const serverEntrypointPath = join(serverRoot, 'index.js');
+  const dxtPath = join(root, '.audit-code', 'install', 'claude-desktop', 'auditor-lambda.dxt');
+  const mcpbPath = join(root, '.audit-code', 'install', 'claude-desktop', 'auditor-lambda.mcpb');
+
+  const bundleExisted = await fileExists(bundleRoot);
+  await mkdir(serverRoot, { recursive: true });
+  await cp(distEntry.replace(/dist[\\/]index\.js$/, 'dist'), join(bundleRoot, 'dist'), { recursive: true, force: true });
+  await cp(join(repoRoot, 'schemas'), join(bundleRoot, 'schemas'), { recursive: true, force: true });
+  await cp(join(repoRoot, 'skills', 'audit-code'), join(bundleRoot, 'skills', 'audit-code'), { recursive: true, force: true });
+  await writeFile(join(bundleRoot, 'audit-code.mjs'), await readFile(join(repoRoot, 'audit-code.mjs')));
+  await writeFile(join(bundleRoot, 'audit-code-wrapper-lib.mjs'), await readFile(join(repoRoot, 'audit-code-wrapper-lib.mjs')));
+  await writeFile(join(bundleRoot, 'package.json'), await readFile(join(repoRoot, 'package.json')));
+
+  results.push({ path: bundleRoot, mode: bundleExisted ? 'updated' : 'created' });
+
+  const serverEntry = [
+    "import { spawn } from 'node:child_process';",
+    "import { dirname, join } from 'node:path';",
+    "import { fileURLToPath } from 'node:url';",
+    '',
+    'const serverDir = dirname(fileURLToPath(import.meta.url));',
+    "const bundleRoot = join(serverDir, '..');",
+    "const repoRoot = process.env.AUDIT_CODE_REPO_ROOT;",
+    "const artifactsDir = process.env.AUDIT_CODE_ARTIFACTS_DIR || (repoRoot ? join(repoRoot, '.audit-artifacts') : undefined);",
+    '',
+    'if (!repoRoot) {',
+    "  console.error('AUDIT_CODE_REPO_ROOT must be configured before launching the auditor MCP bundle.');",
+    '  process.exit(1);',
+    '}',
+    '',
+    "const child = spawn(process.execPath, [join(bundleRoot, 'audit-code.mjs'), 'mcp', '--root', repoRoot, '--artifacts-dir', artifactsDir], {",
+    "  cwd: repoRoot,",
+    '  env: process.env,',
+    "  stdio: ['inherit', 'inherit', 'inherit'],",
+    '});',
+    '',
+    "child.on('exit', (code) => {",
+    '  process.exitCode = code ?? 1;',
+    '});',
+    '',
+  ].join('\n');
+
+  results.push(await writeGeneratedMarkdown(serverEntrypointPath, serverEntry));
+
+  const manifest = {
+    manifest_version: '0.3',
+    name: 'auditor-lambda',
+    display_name: 'Auditor Lambda',
+    version: packageVersion,
+    description: 'Local MCP bundle for the /audit-code autonomous audit workflow.',
+    long_description:
+      'Runs the auditor-lambda MCP server locally so Claude Desktop can start, inspect, and continue repository audits with structured tools, resources, and prompts.',
+    author: {
+      name: 'auditor-lambda',
+      url: 'https://github.com/OhOkThisIsFine/auditor-lambda',
+    },
+    repository: {
+      type: 'git',
+      url: 'https://github.com/OhOkThisIsFine/auditor-lambda.git',
+    },
+    documentation: 'https://github.com/OhOkThisIsFine/auditor-lambda/tree/main/docs',
+    support: 'https://github.com/OhOkThisIsFine/auditor-lambda/issues',
+    license: 'MIT',
+    compatibility: {
+      claude_desktop: '>=1.0.0',
+      platforms: ['darwin', 'win32', 'linux'],
+      runtimes: {
+        node: '>=20.0.0',
+      },
+    },
+    tools_generated: true,
+    prompts_generated: true,
+    server: {
+      type: 'node',
+      entry_point: 'server/index.js',
+      mcp_config: {
+        command: 'node',
+        args: ['${__dirname}/server/index.js'],
+        env: {
+          AUDIT_CODE_REPO_ROOT: '${user_config.repo_root}',
+          AUDIT_CODE_ARTIFACTS_DIR: '${user_config.artifacts_dir}',
+        },
+      },
+    },
+    user_config: {
+      repo_root: {
+        type: 'directory',
+        title: 'Repository Root',
+        description: 'Repository to audit with auditor-lambda.',
+        required: true,
+      },
+      artifacts_dir: {
+        type: 'directory',
+        title: 'Artifacts Directory',
+        description: 'Optional override for the audit artifacts directory.',
+        required: false,
+      },
+    },
+  };
+
+  results.push(await writeGeneratedJson(manifestPath, manifest));
+
+  const archive = await createStoredZipBuffer(bundleRoot);
+  results.push(await writeGeneratedBinary(dxtPath, archive));
+  results.push(await writeGeneratedBinary(mcpbPath, archive));
+
+  return {
+    bundleRoot,
+    manifestPath,
+    dxtPath,
+    mcpbPath,
+    serverEntrypointPath,
+  };
+}
+
+function buildHostCatalog({ root, host, assets }) {
+  const entries = {
+    codex: {
+      host: 'codex',
+      label: 'Codex',
+      support_level: 'supported',
+      setup_kind: 'skills+mcp+instructions',
+      summary:
+        'Use the generated Codex skill bundle, AGENTS instructions, and shared MCP launcher so Codex can drive the backend through native tools instead of raw shell commands.',
+      primary_path: assets.codexSkillPath,
+      supporting_paths: [
+        assets.agentsInstructionsPath,
+        assets.codexMcpSetupPath,
+        assets.codexAutomationRecipePath,
+      ].filter(Boolean),
+      steps: [
+        'Open this repository in Codex.',
+        'Ensure Codex can access the repo-local auditor MCP server using the generated setup guide.',
+        'Ask Codex to use the auditor MCP tools to start or continue `/audit-code`.',
+      ],
+    },
+    'claude-desktop': {
+      host: 'claude-desktop',
+      label: 'Claude Desktop',
+      support_level: 'supported',
+      setup_kind: 'local-mcp-bundle',
+      summary:
+        'Install the generated local MCP bundle in Claude Desktop, then use the project template and prompt asset as supporting context.',
+      primary_path: assets.claudeDesktopDxtPath,
+      supporting_paths: [
+        assets.claudeDesktopMcpbPath,
+        assets.claudeDesktopProjectTemplatePath,
+        assets.claudeDesktopRemoteConnectorPath,
+        assets.installedPromptPath,
+      ].filter(Boolean),
+      steps: [
+        'Open Claude Desktop Settings and install the generated `.dxt` bundle.',
+        'Configure the repository root when prompted so the bundle can launch the local auditor MCP server.',
+        'Use the project template and prompt asset to kick off `/audit-code` in conversation.',
+      ],
+    },
+    opencode: {
+      host: 'opencode',
+      label: 'OpenCode',
+      support_level: 'supported',
+      setup_kind: 'command+agent+mcp',
+      summary:
+        'Use the generated OpenCode command and project config so `/audit-code` and the local auditor MCP server are available together.',
+      primary_path: assets.opencodeCommandPath,
+      supporting_paths: [
+        assets.opencodeConfigPath,
+        assets.opencodeSkillPath,
+        assets.agentsInstructionsPath,
+        assets.mcpLauncherPath,
+      ].filter(Boolean),
+      steps: [
+        'Open this repository in OpenCode.',
+        'Let OpenCode load the generated `opencode.json` so the auditor MCP server is available.',
+        'Invoke `/audit-code` and keep the audit loop on the auditor MCP tools.',
+      ],
+    },
+    vscode: {
+      host: 'vscode',
+      label: 'VS Code',
+      support_level: 'supported',
+      setup_kind: 'prompt+agent+mcp',
+      summary:
+        'Use the generated prompt file, custom agent, and workspace MCP configuration for the cleanest VS Code integration.',
+      primary_path: assets.vscodePromptPath,
+      supporting_paths: [
+        assets.vscodeAgentPath,
+        assets.vscodeMcpConfigPath,
+        assets.copilotInstructionsPath,
+      ].filter(Boolean),
+      steps: [
+        'Open this repository in VS Code with Copilot.',
+        'Allow VS Code to discover the workspace MCP server from `.vscode/mcp.json`.',
+        'Invoke `/audit-code` in chat and use the custom auditor agent when you want the dedicated orchestration persona.',
+      ],
+    },
+    antigravity: {
+      host: 'antigravity',
+      label: 'Antigravity',
+      support_level: 'guided',
+      setup_kind: 'planning-guide+mcp-ready',
+      summary:
+        'Start in Planning mode with the generated guide and AGENTS instructions, then use the shared MCP launcher once Antigravity is ready to call structured tools.',
+      primary_path: assets.antigravityPlanningGuidePath,
+      supporting_paths: [
+        assets.agentsInstructionsPath,
+        assets.mcpLauncherPath,
+        assets.installedPromptPath,
+      ].filter(Boolean),
+      steps: [
+        'Open this repository in Antigravity Planning mode.',
+        'Load the generated planning guide and AGENTS instructions before starting the audit.',
+        'Use the shared auditor MCP server when Antigravity needs structured audit state instead of free-form shell guesses.',
+      ],
+    },
+  };
+
+  const hostOrder = host === 'all'
+    ? ['codex', 'claude-desktop', 'opencode', 'vscode', 'antigravity']
+    : host === 'copilot'
+      ? ['vscode']
+      : [host];
+
+  return hostOrder
+    .map((hostKey) => entries[hostKey])
+    .filter((entry) => entry?.primary_path)
+    .map((entry) => ({
+      ...entry,
+      primary_path: entry.primary_path,
+      supporting_paths: entry.supporting_paths,
+      repo_relative_primary_path: toRepoRelativePath(root, entry.primary_path),
+      repo_relative_supporting_paths: entry.supporting_paths.map((path) => toRepoRelativePath(root, path)),
+    }));
 }
 
 function renderInstallGuide({
@@ -466,180 +1040,753 @@ function renderInstallGuide({
   host,
   installedPromptPath,
   installedSkillPath,
-  slashCommandSurfaces,
-  instructionSurfaces,
-  unsupportedHosts,
+  installManifestPath,
+  mcpLauncherPath,
   hostGuidance,
 }) {
-  const slashCommandPaths = Object.values(slashCommandSurfaces).filter(Boolean);
-  const instructionPaths = Object.values(instructionSurfaces).filter(Boolean);
   const lines = [
     '# audit-code bootstrap guide',
     '',
     'The canonical product route is `/audit-code` in conversation.',
     '',
-    'Canonical installed assets:',
+    'Shared repo-local assets:',
     `- prompt asset: \`${toRepoRelativePath(root, installedPromptPath)}\``,
     `- skill asset: \`${toRepoRelativePath(root, installedSkillPath)}\``,
+    `- host manifest: \`${toRepoRelativePath(root, installManifestPath)}\``,
+    `- shared MCP launcher: \`${toRepoRelativePath(root, mcpLauncherPath)}\``,
+    '',
+    'Host-specific quick starts:',
   ];
 
-  if (slashCommandPaths.length > 0) {
-    lines.push('', 'Repo-local slash-command surfaces:');
-    for (const targetPath of slashCommandPaths) {
-      lines.push(`- \`${toRepoRelativePath(root, targetPath)}\``);
+  for (const guide of hostGuidance) {
+    lines.push(`- ${guide.label}: ${guide.summary}`);
+  }
+
+  for (const guide of hostGuidance) {
+    lines.push('', `## ${guide.label}`, '');
+    lines.push(`Support level: ${guide.support_level}`);
+    lines.push(`Setup kind: ${guide.setup_kind}`);
+    lines.push('');
+    lines.push(guide.summary);
+    lines.push('');
+    lines.push('Primary repo-local path:');
+    lines.push(`- \`${toRepoRelativePath(root, guide.primary_path)}\``);
+    if (guide.supporting_paths.length > 0) {
+      lines.push('', 'Supporting repo-local paths:');
+      for (const path of guide.supporting_paths) {
+        lines.push(`- \`${toRepoRelativePath(root, path)}\``);
+      }
+    }
+    lines.push('', 'Recommended steps:');
+    for (const step of guide.steps) {
+      lines.push(`- ${step}`);
     }
   }
 
-  if (instructionPaths.length > 0) {
-    lines.push('', 'Compatibility instruction surfaces:');
-    for (const targetPath of instructionPaths) {
-      lines.push(`- \`${toRepoRelativePath(root, targetPath)}\``);
+  lines.push('', 'Backend fallback:');
+  lines.push('- from the repository root, run `audit-code` only when you intentionally need the repo-local backend wrapper');
+  lines.push('- run `audit-code verify-install` after bootstrap when you want to smoke-test the generated launchers and host configs');
+
+  if (host !== 'all') {
+    lines.push('');
+    lines.push(`This install was scoped to \`${host}\`, so assets for other hosts may be intentionally omitted.`);
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+function getInstallProfile(host) {
+  switch (host) {
+    case 'all':
+      return {
+        writeVSCode: true,
+        writeCopilotInstructions: true,
+        writeOpenCode: true,
+        writeCodex: true,
+        writeClaudeDesktop: true,
+        writeAntigravity: true,
+        writeAgents: true,
+      };
+    case 'copilot':
+      return {
+        writeVSCode: true,
+        writeCopilotInstructions: true,
+        writeAgents: false,
+        writeOpenCode: false,
+        writeCodex: false,
+        writeClaudeDesktop: false,
+        writeAntigravity: false,
+      };
+    case 'vscode':
+      return {
+        writeVSCode: true,
+        writeCopilotInstructions: true,
+        writeAgents: false,
+        writeOpenCode: false,
+        writeCodex: false,
+        writeClaudeDesktop: false,
+        writeAntigravity: false,
+      };
+    case 'opencode':
+      return {
+        writeVSCode: false,
+        writeCopilotInstructions: false,
+        writeAgents: true,
+        writeOpenCode: true,
+        writeCodex: false,
+        writeClaudeDesktop: false,
+        writeAntigravity: false,
+      };
+    case 'codex':
+      return {
+        writeVSCode: false,
+        writeCopilotInstructions: false,
+        writeAgents: true,
+        writeOpenCode: false,
+        writeCodex: true,
+        writeClaudeDesktop: false,
+        writeAntigravity: false,
+      };
+    case 'claude-desktop':
+      return {
+        writeVSCode: false,
+        writeCopilotInstructions: false,
+        writeAgents: false,
+        writeOpenCode: false,
+        writeCodex: false,
+        writeClaudeDesktop: true,
+        writeAntigravity: false,
+      };
+    case 'antigravity':
+      return {
+        writeVSCode: false,
+        writeCopilotInstructions: false,
+        writeAgents: true,
+        writeOpenCode: false,
+        writeCodex: false,
+        writeClaudeDesktop: false,
+        writeAntigravity: true,
+      };
+    default:
+      throw new Error(
+        `Unsupported host "${host}". Supported hosts: all, copilot, vscode, opencode, codex, claude-desktop, antigravity.`,
+      );
+  }
+}
+
+async function assertDirectoryExists(path, description) {
+  let stats;
+  try {
+    stats = await stat(path);
+  } catch {
+    throw new Error(`${description} does not exist: ${path}`);
+  }
+
+  if (!stats.isDirectory()) {
+    throw new Error(`${description} is not a directory: ${path}`);
+  }
+}
+
+function encodeMcpMessage(payload) {
+  const body = Buffer.from(JSON.stringify(payload), 'utf8');
+  return Buffer.concat([
+    Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, 'utf8'),
+    body,
+  ]);
+}
+
+function createInstallMcpClient(command, args, options = {}) {
+  const child = spawn(command, args, {
+    cwd: options.cwd,
+    env: { ...process.env, ...(options.env ?? {}) },
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  let buffer = Buffer.alloc(0);
+  let stderr = '';
+  let exitError = null;
+  const pending = new Map();
+
+  function failPending(error) {
+    for (const { reject } of pending.values()) {
+      reject(error);
     }
+    pending.clear();
   }
 
-  lines.push('', 'Host-specific quick starts:');
-  for (const guide of hostGuidance) {
-    lines.push(`- ${guide.label}: ${guide.summary}`);
+  child.stdout.on('data', (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+
+    while (true) {
+      const separator = buffer.indexOf('\r\n\r\n');
+      if (separator < 0) {
+        return;
+      }
+
+      const headerBlock = buffer.slice(0, separator).toString('utf8');
+      const contentLengthHeader = headerBlock
+        .split('\r\n')
+        .find((header) => header.toLowerCase().startsWith('content-length:'));
+      if (!contentLengthHeader) {
+        return;
+      }
+
+      const contentLength = Number(contentLengthHeader.split(':')[1]?.trim());
+      const frameLength = separator + 4 + contentLength;
+      if (buffer.length < frameLength) {
+        return;
+      }
+
+      const payload = JSON.parse(
+        buffer.slice(separator + 4, frameLength).toString('utf8'),
+      );
+      buffer = buffer.slice(frameLength);
+
+      if (pending.has(payload.id)) {
+        const { resolve, reject } = pending.get(payload.id);
+        pending.delete(payload.id);
+        if (payload.error) {
+          reject(
+            new Error(payload.error.message ?? JSON.stringify(payload.error)),
+          );
+          continue;
+        }
+        resolve(payload.result);
+      }
+    }
+  });
+
+  child.stderr.on('data', (chunk) => {
+    stderr += String(chunk);
+  });
+
+  child.on('error', (error) => {
+    exitError = error;
+    failPending(error);
+  });
+
+  child.on('exit', (code, signal) => {
+    if (exitError) {
+      return;
+    }
+    exitError = new Error(
+      `MCP process exited early with code ${code ?? 'null'}${signal ? ` and signal ${signal}` : ''}.${stderr.trim().length > 0 ? ` ${stderr.trim()}` : ''}`,
+    );
+    failPending(exitError);
+  });
+
+  function request(id, method, params = {}) {
+    return new Promise((resolve, reject) => {
+      if (exitError) {
+        reject(exitError);
+        return;
+      }
+      pending.set(id, { resolve, reject });
+      child.stdin.write(
+        encodeMcpMessage({
+          jsonrpc: '2.0',
+          id,
+          method,
+          params,
+        }),
+      );
+    });
+  }
+
+  function notify(method, params = {}) {
+    if (exitError) {
+      return;
+    }
+    child.stdin.write(
+      encodeMcpMessage({
+        jsonrpc: '2.0',
+        method,
+        params,
+      }),
+    );
+  }
+
+  async function close() {
+    if (!exitError) {
+      await request('shutdown', 'shutdown');
+      notify('exit');
+      child.stdin.end();
+    }
+
+    await new Promise((resolvePromise) => {
+      child.on('exit', () => resolvePromise());
+    });
+  }
+
+  return {
+    request,
+    notify,
+    close,
+    readStderr() {
+      return stderr.trim();
+    },
+  };
+}
+
+async function probeMcpServer(params) {
+  const client = createInstallMcpClient(params.command, params.args, {
+    cwd: params.cwd,
+    env: params.env,
+  });
+
+  let timerId;
+  const timeout = new Promise((_, reject) => {
+    timerId = setTimeout(() => {
+      reject(
+        new Error(
+          `${params.label} did not complete an MCP handshake within ${INSTALL_VERIFY_TIMEOUT_MS}ms.`,
+        ),
+      );
+    }, INSTALL_VERIFY_TIMEOUT_MS);
+  });
+
+  try {
+    const result = await Promise.race([
+      (async () => {
+        const initialize = await client.request('init', 'initialize', {
+          protocolVersion: MCP_PROTOCOL_VERSION,
+          capabilities: {},
+          clientInfo: {
+            name: 'audit-code-verify-install',
+            version: packageVersion,
+          },
+        });
+        client.notify('notifications/initialized');
+        const tools = await client.request('tools', 'tools/list');
+        const resources = await client.request('resources', 'resources/list');
+        await client.close();
+        return {
+          initialize,
+          tools,
+          resources,
+          stderr: client.readStderr(),
+        };
+      })(),
+      timeout,
+    ]);
+    clearTimeout(timerId);
+    return result;
+  } catch (error) {
+    clearTimeout(timerId);
+    const stderr = client.readStderr();
+    try {
+      await client.close();
+    } catch {
+      // already failed or exited
+    }
+    const suffix = stderr.length > 0 ? ` ${stderr}` : '';
+    throw new Error(`${error instanceof Error ? error.message : String(error)}${suffix}`);
+  }
+}
+
+async function collectVerifyCheck(target, id, fn) {
+  try {
+    const details = await fn();
+    target.push({
+      id,
+      status: 'ok',
+      ...(details ?? {}),
+    });
+  } catch (error) {
+    target.push({
+      id,
+      status: 'error',
+      summary: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+async function ensureFile(path, description) {
+  let stats;
+  try {
+    stats = await stat(path);
+  } catch {
+    throw new Error(`${description} does not exist: ${path}`);
+  }
+
+  if (!stats.isFile()) {
+    throw new Error(`${description} is not a file: ${path}`);
+  }
+
+  return stats;
+}
+
+async function readJson(path, description) {
+  const content = await readFile(path, 'utf8');
+  try {
+    return JSON.parse(content);
+  } catch (error) {
+    throw new Error(
+      `${description} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+    );
   }
+}
 
-  for (const guide of hostGuidance) {
-    lines.push('', renderInstallHostSection(root, guide).trimEnd());
+async function verifyZipFile(path, description) {
+  const content = await readFile(path);
+  if (content.length < 4 || content[0] !== 0x50 || content[1] !== 0x4b) {
+    throw new Error(`${description} is not a valid ZIP-like archive: ${path}`);
   }
+  return content.length;
+}
 
-  lines.push(
-    '',
-    'Backend fallback:',
-    '- from the repository root, run `audit-code` only when you intentionally need the repo-local backend wrapper',
+async function verifyInstalledBootstrap(argv) {
+  const root = resolve(getFlag(argv, '--root') ?? '.');
+  const requestedHost = getFlag(argv, '--host')?.toLowerCase() ?? null;
+  const installManifestPath = join(
+    root,
+    '.audit-code',
+    'install',
+    INSTALL_MANIFEST_FILENAME,
+  );
+  const installGuidePath = join(
+    root,
+    '.audit-code',
+    'install',
+    INSTALL_GUIDE_FILENAME,
   );
 
-  if (unsupportedHosts.length > 0) {
-    lines.push('', 'Hosts still requiring extra handling today:');
-    for (const item of unsupportedHosts) {
-      lines.push(`- ${item.host}: ${item.reason}`);
+  await assertDirectoryExists(root, 'Target repository root');
+
+  const generalChecks = [];
+  const hostResults = [];
+  let installManifest;
+
+  await collectVerifyCheck(generalChecks, 'install_manifest', async () => {
+    await ensureFile(installManifestPath, 'Install manifest');
+    installManifest = await readJson(installManifestPath, 'Install manifest');
+    if (installManifest?.contract_version !== 'audit-code-install/v1alpha1') {
+      throw new Error(
+        `Unexpected install manifest contract version: ${installManifest?.contract_version ?? 'missing'}.`,
+      );
     }
-  }
+    return {
+      summary: 'Install manifest parsed successfully.',
+      path: installManifestPath,
+    };
+  });
 
-  if (host !== 'all') {
-    lines.push(
-      '',
-      `This install was scoped to \`${host}\`, so some repo-local surfaces may be intentionally omitted.`,
+  if (!installManifest) {
+    console.log(
+      JSON.stringify(
+        {
+          root,
+          requested_host: requestedHost ?? 'all',
+          status: 'error',
+          issue_count: generalChecks.filter((check) => check.status === 'error').length,
+          checks: generalChecks,
+          hosts: [],
+        },
+        null,
+        2,
+      ),
     );
+    process.exitCode = 1;
+    return;
   }
 
-  lines.push('');
-  return lines.join('\n');
-}
-
-function upsertManagedBlock(existingContent, blockContent) {
-  const normalized = normalizeNewlines(existingContent);
-  const blockPattern = new RegExp(
-    `${INSTALL_MARKER_START}[\\s\\S]*?${INSTALL_MARKER_END}`,
-    'u',
+  const assetPaths = installManifest.asset_paths ?? {};
+  const hostCatalog = new Map(
+    (installManifest.hosts ?? []).map((entry) => [entry.host, entry]),
   );
+  const selectedHosts = requestedHost && requestedHost !== 'all'
+    ? [requestedHost]
+    : [...hostCatalog.keys()];
+
+  await collectVerifyCheck(generalChecks, 'install_guide', async () => {
+    const guide = await readFile(installGuidePath, 'utf8');
+    if (!guide.includes('# audit-code bootstrap guide')) {
+      throw new Error(`Install guide does not look like an audit-code bootstrap guide: ${installGuidePath}`);
+    }
+    return {
+      summary: 'Install guide is present and readable.',
+      path: installGuidePath,
+    };
+  });
 
-  if (blockPattern.test(normalized)) {
-    return normalized.replace(blockPattern, blockContent);
-  }
+  await collectVerifyCheck(generalChecks, 'installed_prompt', async () => {
+    await ensureFile(assetPaths.installedPromptPath, 'Installed prompt asset');
+    return {
+      summary: 'Installed prompt asset is present.',
+      path: assetPaths.installedPromptPath,
+    };
+  });
 
-  if (normalized.trim().length === 0) {
-    return `${blockContent}\n`;
-  }
+  await collectVerifyCheck(generalChecks, 'installed_skill', async () => {
+    await ensureFile(assetPaths.installedSkillPath, 'Installed skill asset');
+    return {
+      summary: 'Installed skill asset is present.',
+      path: assetPaths.installedSkillPath,
+    };
+  });
 
-  return `${normalized.replace(/\s+$/u, '')}\n\n${blockContent}\n`;
-}
+  await collectVerifyCheck(generalChecks, 'shared_launcher_file', async () => {
+    const launcher = await readFile(assetPaths.mcpLauncherPath, 'utf8');
+    if (!launcher.includes('Unable to locate an audit-code executable')) {
+      throw new Error(`Shared MCP launcher is missing the executable resolution fallback message: ${assetPaths.mcpLauncherPath}`);
+    }
+    if (!launcher.includes('sourcePackageRoot')) {
+      throw new Error(`Shared MCP launcher is missing the package-source fallback hint: ${assetPaths.mcpLauncherPath}`);
+    }
+    return {
+      summary: 'Shared MCP launcher is present and includes resolver fallbacks.',
+      path: assetPaths.mcpLauncherPath,
+    };
+  });
 
-async function writeManagedMarkdown(targetPath, blockContent) {
-  const existed = await fileExists(targetPath);
-  const existingContent = existed ? await readFile(targetPath, 'utf8') : '';
-  const nextContent = upsertManagedBlock(existingContent, blockContent);
-  await mkdir(dirname(targetPath), { recursive: true });
-  await writeFile(targetPath, nextContent, 'utf8');
-  return {
-    path: targetPath,
-    mode: existed ? 'updated' : 'created',
-  };
-}
+  await collectVerifyCheck(generalChecks, 'shared_launcher_mcp', async () => {
+    const probe = await probeMcpServer({
+      label: 'Shared MCP launcher',
+      command: process.execPath,
+      args: [assetPaths.mcpLauncherPath],
+      cwd: root,
+    });
+    const toolNames = (probe.tools?.tools ?? []).map((tool) => tool.name);
+    if (!toolNames.includes('start_audit')) {
+      throw new Error('Shared MCP launcher did not expose the start_audit tool.');
+    }
+    return {
+      summary: 'Shared MCP launcher completed an MCP handshake.',
+      server_name: probe.initialize?.serverInfo?.name ?? null,
+      tool_count: toolNames.length,
+      resource_count: (probe.resources?.resources ?? []).length,
+    };
+  });
 
-async function writeGeneratedMarkdown(targetPath, content) {
-  const existed = await fileExists(targetPath);
-  await mkdir(dirname(targetPath), { recursive: true });
-  await writeFile(targetPath, content, 'utf8');
-  return {
-    path: targetPath,
-    mode: existed ? 'updated' : 'created',
-  };
-}
+  for (const hostKey of selectedHosts) {
+    const checks = [];
+    const hostEntry = hostCatalog.get(hostKey);
 
-function getInstallProfile(host) {
-  switch (host) {
-    case 'all':
-      return {
-        writeVSCodePrompt: true,
-        writeCopilotInstructions: true,
-        writeAgents: true,
-        writeClaudeMemory: true,
-        writeOpenCodeCommand: true,
-        writeClaudeCommand: true,
-        writeCompatibilitySkills: true,
-      };
-    case 'copilot':
-      return {
-        writeVSCodePrompt: true,
-        writeCopilotInstructions: true,
-        writeAgents: false,
-        writeClaudeMemory: false,
-        writeOpenCodeCommand: false,
-        writeClaudeCommand: false,
-        writeCompatibilitySkills: false,
-      };
-    case 'vscode':
-      return {
-        writeVSCodePrompt: true,
-        writeCopilotInstructions: true,
-        writeAgents: true,
-        writeClaudeMemory: true,
-        writeOpenCodeCommand: false,
-        writeClaudeCommand: false,
-        writeCompatibilitySkills: false,
-      };
-    case 'opencode':
-      return {
-        writeVSCodePrompt: false,
-        writeCopilotInstructions: false,
-        writeAgents: true,
-        writeClaudeMemory: false,
-        writeOpenCodeCommand: true,
-        writeClaudeCommand: false,
-        writeCompatibilitySkills: true,
-      };
-    case 'claude-code':
-      return {
-        writeVSCodePrompt: false,
-        writeCopilotInstructions: false,
-        writeAgents: false,
-        writeClaudeMemory: true,
-        writeOpenCodeCommand: false,
-        writeClaudeCommand: true,
-        writeCompatibilitySkills: true,
-      };
-    default:
-      throw new Error(
-        `Unsupported host "${host}". Supported hosts: all, copilot, vscode, opencode, claude-code.`,
-      );
-  }
-}
+    if (!hostEntry) {
+      checks.push({
+        id: 'host_manifest_entry',
+        status: 'error',
+        summary: `Install manifest does not contain host guidance for "${hostKey}".`,
+      });
+      hostResults.push({ host: hostKey, status: 'error', checks });
+      continue;
+    }
 
-async function assertDirectoryExists(path, description) {
-  let stats;
-  try {
-    stats = await stat(path);
-  } catch {
-    throw new Error(`${description} does not exist: ${path}`);
-  }
+    await collectVerifyCheck(checks, 'host_manifest_entry', async () => ({
+      summary: `Host guidance exists for ${hostEntry.label}.`,
+      primary_path: hostEntry.primary_path,
+    }));
+
+    switch (hostKey) {
+      case 'codex':
+        await collectVerifyCheck(checks, 'codex_skill', async () => {
+          const content = await readFile(assetPaths.codexSkillPath, 'utf8');
+          if (!content.includes('# audit-code skill')) {
+            throw new Error(`Codex skill file is missing the expected heading: ${assetPaths.codexSkillPath}`);
+          }
+          return {
+            summary: 'Codex skill bundle is present.',
+            path: assetPaths.codexSkillPath,
+          };
+        });
+        await collectVerifyCheck(checks, 'codex_mcp_setup', async () => {
+          const content = await readFile(assetPaths.codexMcpSetupPath, 'utf8');
+          if (!content.includes(MCP_LAUNCHER_FILENAME)) {
+            throw new Error(`Codex MCP setup guide does not reference ${MCP_LAUNCHER_FILENAME}.`);
+          }
+          return {
+            summary: 'Codex MCP setup guide references the shared launcher.',
+            path: assetPaths.codexMcpSetupPath,
+          };
+        });
+        break;
+      case 'claude-desktop': {
+        const bundleManifestPath = join(
+          root,
+          '.audit-code',
+          'install',
+          'claude-desktop',
+          'bundle',
+          'manifest.json',
+        );
+        const bundleServerPath = join(
+          root,
+          '.audit-code',
+          'install',
+          'claude-desktop',
+          'bundle',
+          'server',
+          'index.js',
+        );
+
+        await collectVerifyCheck(checks, 'claude_bundle_manifest', async () => {
+          const manifest = await readJson(bundleManifestPath, 'Claude Desktop bundle manifest');
+          if (manifest?.server?.entry_point !== 'server/index.js') {
+            throw new Error(`Claude Desktop bundle manifest has an unexpected entry_point: ${manifest?.server?.entry_point ?? 'missing'}.`);
+          }
+          return {
+            summary: 'Claude Desktop bundle manifest parsed successfully.',
+            path: bundleManifestPath,
+          };
+        });
+        await collectVerifyCheck(checks, 'claude_connector_template', async () => {
+          const connector = await readJson(
+            assetPaths.claudeDesktopRemoteConnectorPath,
+            'Claude Desktop remote connector template',
+          );
+          if (connector?.transport !== 'remote-mcp') {
+            throw new Error(`Claude Desktop remote connector transport must be "remote-mcp", got ${connector?.transport ?? 'missing'}.`);
+          }
+          return {
+            summary: 'Claude Desktop remote connector template parsed successfully.',
+            path: assetPaths.claudeDesktopRemoteConnectorPath,
+          };
+        });
+        await collectVerifyCheck(checks, 'claude_dxt_archive', async () => ({
+          summary: 'Claude Desktop .dxt bundle is present.',
+          path: assetPaths.claudeDesktopDxtPath,
+          size_bytes: await verifyZipFile(
+            assetPaths.claudeDesktopDxtPath,
+            'Claude Desktop .dxt bundle',
+          ),
+        }));
+        await collectVerifyCheck(checks, 'claude_mcpb_archive', async () => ({
+          summary: 'Claude Desktop .mcpb bundle is present.',
+          path: assetPaths.claudeDesktopMcpbPath,
+          size_bytes: await verifyZipFile(
+            assetPaths.claudeDesktopMcpbPath,
+            'Claude Desktop .mcpb bundle',
+          ),
+        }));
+        await collectVerifyCheck(checks, 'claude_bundle_mcp', async () => {
+          const probe = await probeMcpServer({
+            label: 'Claude Desktop bundle server',
+            command: process.execPath,
+            args: [bundleServerPath],
+            cwd: root,
+            env: {
+              AUDIT_CODE_REPO_ROOT: root,
+              AUDIT_CODE_ARTIFACTS_DIR: join(root, '.audit-artifacts'),
+            },
+          });
+          const toolNames = (probe.tools?.tools ?? []).map((tool) => tool.name);
+          if (!toolNames.includes('start_audit')) {
+            throw new Error('Claude Desktop bundle server did not expose the start_audit tool.');
+          }
+          return {
+            summary: 'Claude Desktop bundle completed an MCP handshake.',
+            tool_count: toolNames.length,
+          };
+        });
+        break;
+      }
+      case 'opencode':
+        await collectVerifyCheck(checks, 'opencode_command', async () => {
+          const content = await readFile(assetPaths.opencodeCommandPath, 'utf8');
+          if (!content.includes('agent: auditor')) {
+            throw new Error(`OpenCode command file is missing the auditor agent frontmatter: ${assetPaths.opencodeCommandPath}`);
+          }
+          return {
+            summary: 'OpenCode command file is present.',
+            path: assetPaths.opencodeCommandPath,
+          };
+        });
+        await collectVerifyCheck(checks, 'opencode_config', async () => {
+          const config = await readJson(assetPaths.opencodeConfigPath, 'OpenCode project config');
+          const command = config?.mcp?.auditor?.command;
+          if (!Array.isArray(command) || command[0] !== 'node') {
+            throw new Error('OpenCode config must set mcp.auditor.command as a Node command array.');
+          }
+          if (command[1] !== '.audit-code/install/run-mcp-server.mjs') {
+            throw new Error(`OpenCode config must point at .audit-code/install/${MCP_LAUNCHER_FILENAME}, got ${command[1] ?? 'missing'}.`);
+          }
+          if (config?.mcp?.auditor?.type !== 'local') {
+            throw new Error(`OpenCode config must set mcp.auditor.type to "local", got ${config?.mcp?.auditor?.type ?? 'missing'}.`);
+          }
+          return {
+            summary: 'OpenCode project config parsed successfully.',
+            path: assetPaths.opencodeConfigPath,
+          };
+        });
+        break;
+      case 'vscode':
+        await collectVerifyCheck(checks, 'vscode_prompt', async () => {
+          const content = await readFile(assetPaths.vscodePromptPath, 'utf8');
+          if (!content.includes('name: audit-code')) {
+            throw new Error(`VS Code prompt file is missing the expected frontmatter name: ${assetPaths.vscodePromptPath}`);
+          }
+          return {
+            summary: 'VS Code prompt file is present.',
+            path: assetPaths.vscodePromptPath,
+          };
+        });
+        await collectVerifyCheck(checks, 'vscode_mcp_config', async () => {
+          const config = await readJson(assetPaths.vscodeMcpConfigPath, 'VS Code MCP config');
+          const args = config?.servers?.auditor?.args;
+          if (config?.servers?.auditor?.command !== 'node') {
+            throw new Error(`VS Code MCP config must use node as the command, got ${config?.servers?.auditor?.command ?? 'missing'}.`);
+          }
+          if (!Array.isArray(args) || args[0] !== '${workspaceFolder}/.audit-code/install/run-mcp-server.mjs') {
+            throw new Error(`VS Code MCP config must point at \${workspaceFolder}/.audit-code/install/${MCP_LAUNCHER_FILENAME}.`);
+          }
+          return {
+            summary: 'VS Code MCP config parsed successfully.',
+            path: assetPaths.vscodeMcpConfigPath,
+          };
+        });
+        break;
+      case 'antigravity':
+        await collectVerifyCheck(checks, 'antigravity_guide', async () => {
+          const content = await readFile(assetPaths.antigravityPlanningGuidePath, 'utf8');
+          if (!content.includes(MCP_LAUNCHER_FILENAME) || !content.includes(INSTALLED_PROMPT_FILENAME)) {
+            throw new Error(`Antigravity guide must reference both ${MCP_LAUNCHER_FILENAME} and ${INSTALLED_PROMPT_FILENAME}.`);
+          }
+          return {
+            summary: 'Antigravity planning guide references the repo-local prompt asset and MCP launcher.',
+            path: assetPaths.antigravityPlanningGuidePath,
+          };
+        });
+        break;
+      default:
+        checks.push({
+          id: 'host_handler',
+          status: 'error',
+          summary: `No verification handler is implemented for host "${hostKey}".`,
+        });
+    }
 
-  if (!stats.isDirectory()) {
-    throw new Error(`${description} is not a directory: ${path}`);
+    hostResults.push({
+      host: hostKey,
+      status: checks.some((check) => check.status === 'error') ? 'error' : 'ok',
+      checks,
+    });
   }
+
+  const issueCount =
+    generalChecks.filter((check) => check.status === 'error').length +
+    hostResults.reduce(
+      (sum, host) => sum + host.checks.filter((check) => check.status === 'error').length,
+      0,
+    );
+
+  console.log(
+    JSON.stringify(
+      {
+        root,
+        requested_host: requestedHost ?? 'all',
+        manifest_path: installManifestPath,
+        status: issueCount > 0 ? 'error' : 'ok',
+        issue_count: issueCount,
+        checks: generalChecks,
+        hosts: hostResults,
+      },
+      null,
+      2,
+    ),
+  );
+
+  process.exitCode = issueCount > 0 ? 1 : 0;
 }
 
 async function installBootstrap(argv) {
@@ -654,43 +1801,67 @@ async function installBootstrap(argv) {
   const legacyInstalledPromptPath = join(root, '.audit-code', 'install', 'audit-code.prompt.md');
   const installedSkillPath = join(root, '.audit-code', 'install', 'SKILL.md');
   const installGuidePath = join(root, '.audit-code', 'install', INSTALL_GUIDE_FILENAME);
-  const slashCommandSurfaces = {
-    vscode_prompt: profile.writeVSCodePrompt
-      ? join(root, '.github', 'prompts', 'audit-code.prompt.md')
+  const installManifestPath = join(root, '.audit-code', 'install', INSTALL_MANIFEST_FILENAME);
+  const mcpLauncherPath = join(root, '.audit-code', 'install', MCP_LAUNCHER_FILENAME);
+  const assetPaths = {
+    installedPromptPath,
+    installedSkillPath,
+    installGuidePath,
+    installManifestPath,
+    mcpLauncherPath,
+    agentsInstructionsPath: profile.writeAgents ? join(root, 'AGENTS.md') : null,
+    copilotInstructionsPath: profile.writeCopilotInstructions
+      ? join(root, '.github', 'copilot-instructions.md')
+      : null,
+    codexSkillPath: profile.writeCodex
+      ? join(root, '.codex', 'skills', 'audit-code', 'SKILL.md')
+      : null,
+    codexPromptPath: profile.writeCodex
+      ? join(root, '.codex', 'skills', 'audit-code', 'audit-code.prompt.md')
+      : null,
+    codexMcpSetupPath: profile.writeCodex
+      ? join(root, '.audit-code', 'install', 'codex', 'MCP-SETUP.md')
+      : null,
+    codexAutomationRecipePath: profile.writeCodex
+      ? join(root, '.audit-code', 'install', 'codex', 'RE-AUDIT-AUTOMATION.md')
       : null,
-    opencode_command: profile.writeOpenCodeCommand
+    claudeDesktopProjectTemplatePath: profile.writeClaudeDesktop
+      ? join(root, '.audit-code', 'install', 'claude-desktop', 'PROJECT-TEMPLATE.md')
+      : null,
+    claudeDesktopRemoteConnectorPath: profile.writeClaudeDesktop
+      ? join(root, '.audit-code', 'install', 'claude-desktop', 'remote-mcp-connector.json')
+      : null,
+    claudeDesktopDxtPath: profile.writeClaudeDesktop
+      ? join(root, '.audit-code', 'install', 'claude-desktop', 'auditor-lambda.dxt')
+      : null,
+    claudeDesktopMcpbPath: profile.writeClaudeDesktop
+      ? join(root, '.audit-code', 'install', 'claude-desktop', 'auditor-lambda.mcpb')
+      : null,
+    opencodeCommandPath: profile.writeOpenCode
       ? join(root, '.opencode', 'commands', 'audit-code.md')
       : null,
-    claude_code_command: profile.writeClaudeCommand
-      ? join(root, '.claude', 'commands', 'audit-code.md')
+    opencodeConfigPath: profile.writeOpenCode
+      ? join(root, 'opencode.json')
       : null,
-  };
-  const instructionSurfaces = {
-    copilot_instructions: profile.writeCopilotInstructions
-      ? join(root, '.github', 'copilot-instructions.md')
+    opencodeSkillPath: profile.writeOpenCode
+      ? join(root, '.opencode', 'skills', 'audit-code', 'SKILL.md')
+      : null,
+    opencodePromptPath: profile.writeOpenCode
+      ? join(root, '.opencode', 'skills', 'audit-code', 'audit-code.prompt.md')
+      : null,
+    vscodePromptPath: profile.writeVSCode
+      ? join(root, '.github', 'prompts', 'audit-code.prompt.md')
+      : null,
+    vscodeAgentPath: profile.writeVSCode
+      ? join(root, '.github', 'agents', 'auditor.agent.md')
+      : null,
+    vscodeMcpConfigPath: profile.writeVSCode
+      ? join(root, '.vscode', 'mcp.json')
+      : null,
+    antigravityPlanningGuidePath: profile.writeAntigravity
+      ? join(root, '.audit-code', 'install', 'antigravity', 'PLANNING-MODE.md')
       : null,
-    agents: profile.writeAgents ? join(root, 'AGENTS.md') : null,
-    claude: profile.writeClaudeMemory ? join(root, 'CLAUDE.md') : null,
   };
-  const unsupportedHosts = host === 'all'
-    ? [
-        {
-          host: 'claude-desktop',
-          reason:
-            'No verified project-local slash-command installation surface is currently shipped for Claude Desktop.',
-        },
-        {
-          host: 'antigravity',
-          reason:
-            'No verified repo-local slash-command installation surface is currently shipped for Antigravity.',
-        },
-      ]
-    : [];
-  const hostGuidance = buildInstallHostGuidance({
-    installedPromptPath,
-    slashCommandSurfaces,
-    instructionSurfaces,
-  });
 
   const results = [];
   if (await fileExists(legacyInstalledPromptPath)) {
@@ -704,84 +1875,161 @@ async function installBootstrap(argv) {
   );
   results.push(await writeGeneratedMarkdown(installedSkillPath, skillSource));
 
-  if (profile.writeVSCodePrompt) {
+  results.push(
+    await writeGeneratedMarkdown(mcpLauncherPath, renderSharedMcpLauncher(repoRoot)),
+  );
+
+  const compatibilityBlockTargets = [
+    assetPaths.agentsInstructionsPath,
+    assetPaths.copilotInstructionsPath,
+  ].filter(Boolean);
+
+  for (const targetPath of compatibilityBlockTargets) {
     results.push(
-      await writeGeneratedMarkdown(
-        join(root, '.github', 'prompts', 'audit-code.prompt.md'),
-        renderPromptFile(
-          {
-            name: 'audit-code',
-            description: 'Autonomous local loop code auditing',
-            agent: 'agent',
-          },
-          promptBody,
+      await writeManagedMarkdown(
+        targetPath,
+        buildInstallDirective(
+          relative(dirname(targetPath), installedPromptPath) || `./.audit-code/install/${INSTALLED_PROMPT_FILENAME}`,
         ),
       ),
     );
   }
 
-  if (profile.writeOpenCodeCommand) {
+  if (profile.writeCodex) {
+    results.push(
+      await writeGeneratedMarkdown(
+        assetPaths.codexSkillPath,
+        skillSource,
+      ),
+    );
+    results.push(
+      await writeGeneratedMarkdown(
+        assetPaths.codexPromptPath,
+        promptSource,
+      ),
+    );
+    results.push(
+      await writeGeneratedMarkdown(
+        assetPaths.codexMcpSetupPath,
+        renderCodexMcpSetupGuide(root),
+      ),
+    );
+    results.push(
+      await writeGeneratedMarkdown(
+        assetPaths.codexAutomationRecipePath,
+        renderCodexAutomationRecipe(),
+      ),
+    );
+  }
+
+  if (profile.writeClaudeDesktop) {
+    const claudeDesktopBundle = await buildClaudeDesktopBundle(root, results);
+    assetPaths.claudeDesktopDxtPath = claudeDesktopBundle.dxtPath;
+    assetPaths.claudeDesktopMcpbPath = claudeDesktopBundle.mcpbPath;
+    results.push(
+      await writeGeneratedMarkdown(
+        assetPaths.claudeDesktopProjectTemplatePath,
+        renderClaudeDesktopProjectTemplate(),
+      ),
+    );
+    results.push(
+      await writeGeneratedJson(
+        assetPaths.claudeDesktopRemoteConnectorPath,
+        JSON.parse(renderClaudeDesktopRemoteConnectorTemplate()),
+      ),
+    );
+  }
+
+  if (profile.writeOpenCode) {
     results.push(
       await writeGeneratedMarkdown(
-        join(root, '.opencode', 'commands', 'audit-code.md'),
+        assetPaths.opencodeCommandPath,
         renderPromptFile(
           {
             description: 'Autonomous local loop code auditing',
-            agent: 'build',
+            agent: 'auditor',
             subtask: false,
           },
           promptBody,
         ),
       ),
     );
+    results.push(
+      await writeGeneratedMarkdown(
+        assetPaths.opencodeSkillPath,
+        skillSource,
+      ),
+    );
+    results.push(
+      await writeGeneratedMarkdown(
+        assetPaths.opencodePromptPath,
+        promptSource,
+      ),
+    );
+    results.push(
+      await writeGeneratedMarkdown(
+        assetPaths.opencodeConfigPath,
+        renderOpenCodeProjectConfig(root),
+      ),
+    );
   }
 
-  if (profile.writeClaudeCommand) {
+  if (profile.writeVSCode) {
     results.push(
       await writeGeneratedMarkdown(
-        join(root, '.claude', 'commands', 'audit-code.md'),
+        assetPaths.vscodePromptPath,
         renderPromptFile(
           {
+            name: 'audit-code',
             description: 'Autonomous local loop code auditing',
+            agent: 'auditor',
           },
           promptBody,
         ),
       ),
     );
+    results.push(
+      await writeGeneratedMarkdown(
+        assetPaths.vscodeAgentPath,
+        renderVSCodeAgentFile(),
+      ),
+    );
+    results.push(
+      await writeGeneratedMarkdown(
+        assetPaths.vscodeMcpConfigPath,
+        renderVSCodeMcpConfig(),
+      ),
+    );
   }
 
-  const compatibilityBlockTargets = Object.values(instructionSurfaces).filter(Boolean);
-
-  for (const targetPath of compatibilityBlockTargets) {
+  if (profile.writeAntigravity) {
     results.push(
-      await writeManagedMarkdown(
-        targetPath,
-        buildInstallDirective(
-          relative(dirname(targetPath), installedPromptPath) || `./.audit-code/install/${INSTALLED_PROMPT_FILENAME}`,
-        ),
+      await writeGeneratedMarkdown(
+        assetPaths.antigravityPlanningGuidePath,
+        renderAntigravityPlanningGuide(root),
       ),
     );
   }
 
-  if (profile.writeCompatibilitySkills) {
-    const skillTargets = [
-      join(root, '.opencode', 'skills', 'audit-code'),
-      join(root, '.claude', 'skills', 'audit-code'),
-      join(root, '.agents', 'skills', 'audit-code'),
-    ];
+  const hostGuidance = buildHostCatalog({
+    root,
+    host,
+    assets: assetPaths,
+  });
 
-    for (const targetDir of skillTargets) {
-      results.push(
-        await writeGeneratedMarkdown(join(targetDir, 'SKILL.md'), skillSource),
-      );
-      results.push(
-        await writeGeneratedMarkdown(
-          join(targetDir, 'audit-code.prompt.md'),
-          promptSource,
-        ),
-      );
-    }
-  }
+  const installManifest = {
+    contract_version: 'audit-code-install/v1alpha1',
+    host,
+    repo_root: root,
+    installed_prompt_path: installedPromptPath,
+    installed_skill_path: installedSkillPath,
+    install_guide_path: installGuidePath,
+    install_manifest_path: installManifestPath,
+    mcp_server_launcher_path: mcpLauncherPath,
+    source_prompt_path: resolve(promptAssetPath),
+    asset_paths: assetPaths,
+    hosts: hostGuidance,
+  };
 
   results.push(
     await writeGeneratedMarkdown(
@@ -791,25 +2039,20 @@ async function installBootstrap(argv) {
         host,
         installedPromptPath,
         installedSkillPath,
-        slashCommandSurfaces,
-        instructionSurfaces,
-        unsupportedHosts,
+        installManifestPath,
+        mcpLauncherPath,
         hostGuidance,
       }),
     ),
   );
+  results.push(await writeGeneratedJson(installManifestPath, installManifest));
 
   const sessionConfigPath = join(root, '.audit-artifacts', 'session-config.json');
-  let sessionConfigWritten = false;
   if (!(await fileExists(sessionConfigPath))) {
-    const insideClaudeCode = Boolean(process.env.CLAUDECODE);
-    const defaultConfig = insideClaudeCode
-      ? { provider: 'local-subprocess' }
-      : { provider: 'auto' };
+    const defaultConfig = { provider: 'auto' };
     await mkdir(dirname(sessionConfigPath), { recursive: true });
     await writeFile(sessionConfigPath, JSON.stringify(defaultConfig, null, 2) + '\n', 'utf8');
     results.push({ path: sessionConfigPath, mode: 'created' });
-    sessionConfigWritten = true;
   }
 
   console.log(
@@ -820,16 +2063,34 @@ async function installBootstrap(argv) {
         installed_prompt_path: installedPromptPath,
         installed_skill_path: installedSkillPath,
         install_guide_path: installGuidePath,
+        install_manifest_path: installManifestPath,
+        mcp_server_launcher_path: mcpLauncherPath,
         source_prompt_path: resolve(promptAssetPath),
         files: results,
-        slash_command_surfaces: slashCommandSurfaces,
-        instruction_surfaces: instructionSurfaces,
+        slash_command_surfaces: {
+          vscode_prompt: assetPaths.vscodePromptPath,
+          opencode_command: assetPaths.opencodeCommandPath,
+        },
+        instruction_surfaces: {
+          agents: assetPaths.agentsInstructionsPath,
+          copilot_instructions: assetPaths.copilotInstructionsPath,
+        },
+        mcp_surfaces: {
+          vscode_workspace: assetPaths.vscodeMcpConfigPath,
+          opencode_project: assetPaths.opencodeConfigPath,
+          codex_setup: assetPaths.codexMcpSetupPath,
+          shared_launcher: mcpLauncherPath,
+          claude_desktop_dxt: assetPaths.claudeDesktopDxtPath,
+          claude_desktop_mcpb: assetPaths.claudeDesktopMcpbPath,
+          antigravity_planning_guide: assetPaths.antigravityPlanningGuidePath,
+        },
         host_guidance: hostGuidance,
-        unsupported_hosts: unsupportedHosts,
+        unsupported_hosts: [],
         next_steps: [
           'Open the repository in your preferred host and follow the matching host_guidance entry.',
-          `Open ${installGuidePath} for repo-local quick-start steps for VS Code, OpenCode, Claude Code, Claude Desktop, and Antigravity.`,
-          'If a host does not auto-discover slash commands, use the installed prompt asset or the listed compatibility instruction surfaces.',
+          `Open ${installGuidePath} for repo-local quick-start steps for Codex, Claude Desktop, OpenCode, VS Code, and Antigravity.`,
+          'Run `audit-code verify-install` from the repository root to smoke-test the generated launchers and host configs.',
+          'Use the shared MCP launcher as the source of truth for local stdio MCP registration across hosts.',
         ],
       },
       null,
@@ -898,11 +2159,31 @@ export async function runAuditCodeWrapper({
     return;
   }
 
+  if (argv[0] === 'verify-install') {
+    await verifyInstalledBootstrap(argv.slice(1));
+    return;
+  }
+
   if (argv[0] === 'validate') {
     await runDistCommand('validate', argv.slice(1));
     return;
   }
 
+  if (argv[0] === 'validate-results') {
+    await runDistCommand('validate-results', argv.slice(1));
+    return;
+  }
+
+  if (argv[0] === 'explain-task') {
+    await runDistCommand('explain-task', argv.slice(1));
+    return;
+  }
+
+  if (argv[0] === 'mcp') {
+    await runDistCommand('mcp', argv.slice(1), { ensureArtifactsDir: true });
+    return;
+  }
+
   const wrapperArgs = [...argv];
   if (defaultSingleStep && !hasFlag(wrapperArgs, '--single-step')) {
     wrapperArgs.push('--single-step');