@monoes/monomindcli 2.9.24 → 2.9.27

package/dist/src/commands/platforms.js

@@ -1,639 +1,293 @@
-/**
- * CLI Platforms Command
- * Install/uninstall Monograph context instructions for 14 AI coding platforms
- *
- * github.com/monoes/monomind
- */
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { basename, dirname, join, resolve } from 'node:path';
+/** Evidence-gated platform adapter lifecycle commands. */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
 import { output } from '../output.js';
-export const SUPPORTED_PLATFORMS = [
-    'claude',
-    'gemini',
-    'cursor',
-    'vscode',
-    'copilot',
-    'opencode',
-    'aider',
-    'kiro',
-    'trae',
-    'claw',
-    'droid',
-    'antigravity',
-    'hermes',
-    'codex',
-];
-const PLATFORM_CONFIG_FILES = {
-    claude: ['CLAUDE.md'],
-    gemini: ['GEMINI.md'],
-    cursor: ['.cursorrules', '.cursor/rules/monomind.mdc'],
-    vscode: ['.github/copilot-instructions.md'],
-    copilot: ['.github/copilot-instructions.md'],
-    opencode: ['AGENTS.md'],
-    aider: ['.aider.conf.yml'],
-    kiro: ['.kiro/steering/monomind.md'],
-    trae: ['.trae/rules/monomind.md'],
-    claw: ['.claw/config.md'],
-    droid: ['DROID.md'],
-    antigravity: ['.agents/rules/monomind.md'],
-    hermes: ['HERMES.md'],
-    codex: ['AGENTS.md'],
-};
+import { renderCompatibilityMatrix } from '../platform-adapters/docs.js';
+import { installPlatform, migrateLegacyInstall, planInstall, runPlatformsDoctor, uninstallPlatform, upgradePlatforms, } from '../platform-adapters/operations.js';
+import { PLATFORM_IDS, PLATFORM_REGISTRY, resolvePlatformId, } from '../platform-adapters/registry.js';
+export const SUPPORTED_PLATFORMS = PLATFORM_IDS;
 /**
- * YAML/MDC frontmatter to prepend for platform rule files that require it.
- * Cursor .mdc files use MDC YAML frontmatter; agy workspace rules use alwaysApply.
+ * Compatibility helper retained for callers that package portable skill roots.
+ * Adapter operations only materialize the router; distribution remains
+ * manifest-owned and never installs prompt-injection hooks.
  */
-const FILE_FRONTMATTER = {
-    '.cursor/rules/monomind.mdc': [
-        '---',
-        'description: Monomind monograph knowledge graph integration',
-        'alwaysApply: true',
-        '---',
-    ].join('\n'),
-    '.agents/rules/monomind.md': [
-        '---',
-        'name: monomind-integration',
-        'alwaysApply: true',
-        'description: Enable monomind monograph knowledge graph',
-        '---',
-    ].join('\n'),
-};
-const MONOMIND_BLOCK_START = '<!-- monomind:start -->';
-const MONOMIND_BLOCK_END = '<!-- monomind:end -->';
-function getMonomindInstructions(relPath) {
-    const body = `${MONOMIND_BLOCK_START}
-# Monograph Knowledge Graph
-
-This repository is indexed by Monograph. Before starting complex tasks:
-- Use \`monograph_query\` to search the knowledge graph
-- Use \`monograph_neighbors\` to explore dependencies
-- Use \`monograph_impact\` to understand change blast radius
-
-Graph is at \`.monomind/monograph.db\`. Rebuild with: \`npx monograph build\`
-
-# Mastermind Skills
-
-If mastermind skills are installed, invoke the matching skill BEFORE any response or action.
-Even a 1% chance a skill applies means you must check first.
-
-Skills live in \`~/.agents/skills/\` (Codex/Gemini/Copilot/Cursor) or \`~/.claude/skills/\` (Claude Code).
-Load the relevant \`SKILL.md\` before acting on any non-trivial task.
-${MONOMIND_BLOCK_END}
-`;
-    const frontmatter = relPath ? FILE_FRONTMATTER[relPath] : undefined;
-    return frontmatter ? `${frontmatter}\n\n${body}` : body;
-}
-// The mastermind-activate script (embedded so setup can write it to platform-specific locations).
-// Walks up from process.cwd() to find master.md, extracts the MASTERMIND PROTOCOL section,
-// and writes it to stdout for SessionStart hook injection.
-const MASTERMIND_ACTIVATE_SCRIPT = `'use strict';
-const fs = require('fs');
-const path = require('path');
-
-function findMasterPath() {
-  const candidates = [];
-  if (process.env.CLAUDE_PROJECT_DIR) candidates.push(process.env.CLAUDE_PROJECT_DIR);
-  let dir = process.cwd();
-  for (let i = 0; i < 12; i++) {
-    candidates.push(dir);
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  for (const base of candidates) {
-    const p = path.join(base, '.claude', 'commands', 'mastermind', 'master.md');
-    if (fs.existsSync(p)) return p;
-  }
-  return null;
-}
-
-function extractProtocol(content) {
-  const marker = '\\n---\\n\\n**If $ARGUMENTS is empty:**';
-  const idx = content.indexOf(marker);
-  if (idx !== -1) return content.slice(0, idx).trim();
-  const fallback = content.indexOf('\\n**MASTERMIND** —');
-  if (fallback !== -1) return content.slice(0, fallback).trim();
-  return content.trim();
-}
-
-const masterPath = findMasterPath();
-if (!masterPath) process.exit(0);
-
-try {
-  let raw = fs.readFileSync(masterPath, 'utf8');
-  const body = raw.replace(/^---[\\s\\S]*?---\\s*/, '');
-  const protocol = extractProtocol(body);
-  if (protocol) process.stdout.write(protocol + '\\n');
-} catch { process.exit(0); }
-`;
-// ──────────────────────────────────────────────────────────────
-// Skills packaging helpers
-// ──────────────────────────────────────────────────────────────
-/** Walk up from cwd to find the mastermind commands directory. */
-function findMastermindSourceDir() {
-    let dir = process.cwd();
-    for (let i = 0; i < 12; i++) {
-        const candidate = join(dir, '.claude', 'commands', 'mastermind');
-        if (existsSync(candidate))
-            return candidate;
-        const parent = dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    return null;
-}
-/**
- * Copy mastermind skill files into targetDir as <skill-name>/SKILL.md packages.
- * Files starting with _ are internal helpers and are skipped.
- * master.md → targetDir/mastermind/SKILL.md (root routing skill)
- * build.md  → targetDir/mastermind-build/SKILL.md
- *
- * Also copies the references/ subdir alongside mastermind/SKILL.md so
- * platforms that follow relative links (e.g. agy's antigravity-tools.md) can resolve them.
- */
-function installMastermindSkills(targetDir, sourceDir) {
+export function installMastermindSkills(targetDir, sourceDir) {
     const written = [];
-    const files = readdirSync(sourceDir).filter((f) => f.endsWith('.md') && !f.startsWith('_'));
-    for (const file of files) {
-        const name = basename(file, '.md');
-        const skillDir = name === 'master' ? join(targetDir, 'mastermind') : join(targetDir, `mastermind-${name}`);
-        const destFile = join(skillDir, 'SKILL.md');
-        if (!existsSync(destFile)) {
-            mkdirSync(skillDir, { recursive: true });
-            const content = readFileSync(join(sourceDir, file), 'utf8');
-            writeFileSync(destFile, content, 'utf8');
-            written.push(destFile);
-        }
-        // Copy references/ alongside the mastermind umbrella skill (checked independently)
-        if (name === 'master') {
-            const refSrc = join(sourceDir, 'references');
-            if (existsSync(refSrc)) {
-                const refDest = join(skillDir, 'references');
-                mkdirSync(refDest, { recursive: true });
-                for (const ref of readdirSync(refSrc).filter((f) => f.endsWith('.md'))) {
-                    const destRef = join(refDest, ref);
-                    if (!existsSync(destRef)) {
-                        writeFileSync(destRef, readFileSync(join(refSrc, ref), 'utf8'), 'utf8');
-                        written.push(destRef);
-                    }
-                }
-            }
+    for (const source of readdirSync(sourceDir).filter((file) => file.endsWith('.md') && !file.startsWith('_'))) {
+        const name = basename(source, '.md');
+        const skillName = name === 'master' ? 'mastermind' : `mastermind-${name}`;
+        const destination = join(targetDir, skillName, 'SKILL.md');
+        const content = '---\nname: ' +
+            skillName +
+            '\ndescription: "Mastermind ' +
+            name +
+            ' workflow."\n---\n\n' +
+            readFileSync(join(sourceDir, source), 'utf8');
+        const existing = existsSync(destination) ? readFileSync(destination, 'utf8') : '';
+        if (existing !== content) {
+            mkdirSync(join(targetDir, skillName), { recursive: true });
+            writeFileSync(destination, content, 'utf8');
+            written.push(destination);
         }
     }
     return written;
 }
-// ──────────────────────────────────────────────────────────────
-// Global setup helpers (platform-specific, user-level config)
-// ──────────────────────────────────────────────────────────────
-function setupCodex(activateScriptPath) {
-    const home = homedir();
-    const codexDir = join(home, '.codex');
-    mkdirSync(codexDir, { recursive: true });
-    // Write the activate script
-    writeFileSync(activateScriptPath, MASTERMIND_ACTIVATE_SCRIPT, 'utf8');
-    // Merge a [[hooks]] entry into ~/.codex/config.toml
-    const configPath = join(codexDir, 'config.toml');
-    const hookBlock = [
-        '',
-        '# monomind:start',
-        '[[hooks]]',
-        'event = "SessionStart"',
-        'matcher = ""',
-        '[[hooks.hooks]]',
-        'type = "command"',
-        `command = "node ${activateScriptPath}"`,
-        'statusMessage = "Loading mastermind protocol"',
-        'timeout = 5000',
-        '# monomind:end',
-    ].join('\n');
-    const config = existsSync(configPath) ? readFileSync(configPath, 'utf8') : '';
-    const written = [];
-    if (!config.includes('# monomind:start')) {
-        writeFileSync(configPath, config + hookBlock, 'utf8');
-        written.push(configPath, activateScriptPath);
-    }
-    // Install mastermind skills to ~/.agents/skills/ (shared cross-runtime dir)
-    const sourceDir = findMastermindSourceDir();
-    if (sourceDir) {
-        const skillsDir = join(home, '.agents', 'skills');
-        written.push(...installMastermindSkills(skillsDir, sourceDir));
-    }
-    return written;
+function scopeFrom(ctx) {
+    return ctx.flags.scope === 'user' ? 'user' : 'project';
 }
-function setupCursor(activateScriptPath, repoPath) {
-    // Write the activate script to ~/.cursor/
-    writeFileSync(activateScriptPath, MASTERMIND_ACTIVATE_SCRIPT, 'utf8');
-    // Merge SessionStart hook into .cursor/settings.json (project-level)
-    const settingsPath = join(repoPath, '.cursor', 'settings.json');
-    mkdirSync(dirname(settingsPath), { recursive: true });
-    let settings = {};
-    if (existsSync(settingsPath)) {
-        try {
-            settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
-        }
-        catch (e) {
-            if (process.env.DEBUG || process.env.MONOMIND_DEBUG)
-                console.error('[setupCursor] failed to parse existing .cursor/settings.json, overwriting with empty:', e);
-        }
-    }
-    const hooks = settings.hooks ?? {};
-    const sessionStart = hooks.SessionStart ?? [];
-    const alreadyAdded = sessionStart.some((h) => typeof h === 'object' &&
-        h !== null &&
-        h.hooks?.some?.((inner) => typeof inner === 'object' &&
-            inner !== null &&
-            inner.command?.includes('monomind-activate')));
-    const written = [];
-    if (!alreadyAdded) {
-        sessionStart.push({
-            matcher: '',
-            hooks: [{ type: 'command', command: `node "${activateScriptPath}"`, timeout: 5000 }],
-        });
-        hooks.SessionStart = sessionStart;
-        settings.hooks = hooks;
-        writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf8');
-        written.push(settingsPath, activateScriptPath);
-    }
-    // Install mastermind skills to ~/.agents/skills/ (Cursor shares the cross-runtime dir)
-    const sourceDir = findMastermindSourceDir();
-    if (sourceDir) {
-        const skillsDir = join(homedir(), '.agents', 'skills');
-        written.push(...installMastermindSkills(skillsDir, sourceDir));
-    }
-    return written;
+function targetFrom(ctx) {
+    const raw = ctx.flags.platform;
+    return typeof raw === 'string' ? resolvePlatformId(raw) : undefined;
 }
-function setupAntigravity() {
-    const home = homedir();
-    const pluginDir = join(home, '.gemini', 'antigravity-cli', 'plugins', 'monomind');
-    const rulesDir = join(pluginDir, 'rules');
-    mkdirSync(rulesDir, { recursive: true });
-    const pluginJson = join(pluginDir, 'plugin.json');
-    const ruleFile = join(rulesDir, 'mastermind.md');
-    const written = [];
-    if (!existsSync(pluginJson)) {
-        writeFileSync(pluginJson, JSON.stringify({
-            name: 'monomind',
-            version: '1.0.0',
-            description: 'Monomind monograph knowledge graph and mastermind skills for Antigravity CLI',
-        }, null, 2), 'utf8');
-        written.push(pluginJson);
-    }
-    if (!existsSync(ruleFile)) {
-        writeFileSync(ruleFile, [
-            '---',
-            'name: monomind-integration',
-            'alwaysApply: true',
-            'description: Enable monomind monograph and mastermind skills',
-            '---',
-            '',
-            '# Monomind Integration',
-            '',
-            'This project uses Monograph for knowledge graph navigation.',
-            'Before starting complex tasks, use `view_file` on `.monomind/monograph.db` context',
-            'and invoke the relevant mastermind skill SKILL.md before acting.',
-            '',
-            '## Monograph',
-            '- `monograph_query` — BM25 search the knowledge graph',
-            '- `monograph_impact` — blast radius before any change',
-            '- `monograph_neighbors` — explore dependencies',
-            '',
-            '## Mastermind Skills',
-            'Check `~/.gemini/skills/` for installed mastermind skills.',
-            'Load SKILL.md with `view_file` (IsSkillFile: true) before acting on non-trivial tasks.',
-        ].join('\n'), 'utf8');
-        written.push(ruleFile);
-    }
-    // Install mastermind skills to ~/.gemini/skills/ (agy's skill dir)
-    const sourceDir = findMastermindSourceDir();
-    if (sourceDir) {
-        const skillsDir = join(home, '.gemini', 'skills');
-        written.push(...installMastermindSkills(skillsDir, sourceDir));
+function targetsFrom(ctx) {
+    if (ctx.flags.all === true)
+        return [...PLATFORM_IDS];
+    const target = targetFrom(ctx);
+    return target ? [target] : undefined;
+}
+function mutationRequest(ctx, platform) {
+    return {
+        platform,
+        all: ctx.flags.all === true,
+        scope: scopeFrom(ctx),
+        path: resolve(typeof ctx.flags.path === 'string' ? ctx.flags.path : ctx.cwd),
+        yes: ctx.flags.yes === true,
+        dryRun: ctx.flags['dry-run'] === true,
+        enableHooks: ctx.flags['enable-hooks'] === true,
+        enableBlockingHooks: ctx.flags['enable-blocking-hooks'] === true,
+        removeLegacy: ctx.flags['remove-legacy'] === true,
+    };
+}
+function resultError(reason) {
+    output.error(reason instanceof Error ? reason.message : String(reason));
+    return { success: false, exitCode: 1 };
+}
+function printResults(results) {
+    for (const result of results) {
+        result.changed.forEach((path) => output.success(`Updated ${path}`));
+        result.skipped.forEach((path) => output.info(`Skipped ${path}`));
+        result.diagnostics.forEach((diagnostic) => output.info(diagnostic));
     }
-    return written;
 }
-async function handleSetup(ctx) {
-    const platform = ctx.flags.platform;
-    const all = ctx.flags.all;
-    let repoPath;
+function requireTargets(ctx) {
+    const targets = targetsFrom(ctx);
+    if (targets)
+        return targets;
+    return resultError(typeof ctx.flags.platform === 'string'
+        ? `Unknown platform: ${ctx.flags.platform}`
+        : 'Specify --platform <id|alias> or --all');
+}
+async function handlePlan(ctx) {
+    const targets = requireTargets(ctx);
+    if (!Array.isArray(targets))
+        return targets;
     try {
-        repoPath = resolveRepoPath(ctx.flags.path ?? '.');
-    }
-    catch (err) {
-        output.error(`Invalid --path: ${err instanceof Error ? err.message : String(err)}`);
-        return { success: false, exitCode: 1 };
+        const plans = await Promise.all(targets.map((platform) => planInstall({ ...mutationRequest(ctx, platform), platform })));
+        if (ctx.flags.json === true)
+            output.printJson(plans);
+        else
+            plans.forEach((plan) => {
+                output.info(`Plan: ${plan.intents.length} artifact(s)`);
+                plan.diagnostics.forEach((diagnostic) => output.info(diagnostic));
+            });
+        return { success: true, data: plans };
     }
-    if (!platform && !all) {
-        output.error('Specify --platform <name> or --all');
-        output.info(`Platforms with global setup: cursor, codex, antigravity`);
-        return { success: false, exitCode: 1 };
+    catch (reason) {
+        return resultError(reason);
     }
-    const targets = all ? [...SUPPORTED_PLATFORMS] : [platform];
-    const home = homedir();
-    let totalFiles = 0;
-    for (const p of targets) {
-        let written = [];
-        try {
-            if (p === 'codex') {
-                written = setupCodex(join(home, '.codex', 'monomind-activate.cjs'));
-            }
-            else if (p === 'cursor') {
-                written = setupCursor(join(home, '.cursor', 'monomind-activate.cjs'), repoPath);
-            }
-            else if (p === 'antigravity') {
-                written = setupAntigravity();
-            }
-            else {
-                output.info(`[${p}] No global setup needed — use \`platforms install\``);
-                continue;
-            }
-        }
-        catch (err) {
-            output.error(`[${p}] Setup failed: ${err instanceof Error ? err.message : String(err)}`);
-            continue;
-        }
-        if (written.length > 0) {
-            for (const f of written)
-                output.success(`[${p}] ✓ ${f}`);
-            totalFiles += written.length;
-        }
-        else {
-            output.info(`[${p}] Already set up — skipped`);
-        }
-    }
-    output.success(`Done. ${totalFiles} file(s) written.`);
-    return { success: true };
 }
-/**
- * Maximum size for a platform config file we will read or append to.
- * Platform config files (CLAUDE.md, .cursorrules, etc.) are never legitimately
- * larger than a few hundred KB — a 1 MB cap prevents OOM when the flag points
- * at an enormous file such as a binary or a DB dump.
- */
-const MAX_CONFIG_FILE_BYTES = 1 * 1024 * 1024; // 1 MB
-/**
- * Resolve and validate the user-supplied --path flag.
- *
- * SECURITY: the flag is attacker-controlled. Without validation an adversary can
- *   pass --path /etc to overwrite system files, or --path "../../.." to escape
- *   the project. We resolve to an absolute path and reject anything that isn't
- *   a directory (or doesn't exist yet under a parent that does exist).
- *   We do NOT further restrict the path to cwd because a legitimate use case is
- *   "install into another repo at an absolute path", but we do require the
- *   resolved path to be a directory (or the parent to exist) so that the caller
- *   cannot aim the flag at a file.
- */
-function resolveRepoPath(rawPath) {
-    // Prevent shell-injection via null bytes or unusual separators
-    if (rawPath.includes('\0'))
-        throw new Error('Invalid path: contains null byte');
-    const resolved = resolve(rawPath);
-    // If the path exists it must be a directory
-    if (existsSync(resolved)) {
-        const st = statSync(resolved);
-        if (!st.isDirectory())
-            throw new Error(`--path must be a directory, got a file: ${resolved}`);
+async function handleInstall(ctx) {
+    const targets = requireTargets(ctx);
+    if (!Array.isArray(targets))
+        return targets;
+    try {
+        const results = ctx.flags.all === true
+            ? await upgradePlatforms(mutationRequest(ctx))
+            : [await installPlatform({ ...mutationRequest(ctx, targets[0]), platform: targets[0] })];
+        printResults(results);
+        return { success: true, data: results };
     }
-    return resolved;
-}
-/**
- * Validate that fullPath is contained within repoRoot (path traversal defence).
- * relPath comes from our own PLATFORM_CONFIG_FILES map, but we validate anyway
- * to guard against future changes that introduce dynamic paths.
- */
-function assertWithinRoot(fullPath, repoRoot) {
-    if (!fullPath.startsWith(`${repoRoot}/`) && fullPath !== repoRoot) {
-        throw new Error(`Path escapes repository root: ${fullPath}`);
+    catch (reason) {
+        return resultError(reason);
     }
 }
-function installPlatform(platform, repoPath) {
-    const files = PLATFORM_CONFIG_FILES[platform];
-    const written = [];
-    for (const relPath of files) {
-        const instructions = getMonomindInstructions(relPath);
-        const fullPath = resolve(join(repoPath, relPath));
-        assertWithinRoot(fullPath, repoPath);
-        const dir = dirname(fullPath);
-        mkdirSync(dir, { recursive: true });
-        if (existsSync(fullPath)) {
-            // Guard against reading oversized files (e.g. the flag points at a data file)
-            const fileStat = statSync(fullPath);
-            if (fileStat.size > MAX_CONFIG_FILE_BYTES) {
-                throw new Error(`Config file too large to read (${fileStat.size} bytes): ${relPath}`);
-            }
-            const existing = readFileSync(fullPath, 'utf8');
-            if (existing.includes(MONOMIND_BLOCK_START))
-                continue;
-            writeFileSync(fullPath, `${existing}\n${instructions}`, 'utf8');
-        }
-        else {
-            writeFileSync(fullPath, instructions, 'utf8');
-        }
-        written.push(relPath);
+async function handleUpgrade(ctx) {
+    const targets = requireTargets(ctx);
+    if (!Array.isArray(targets))
+        return targets;
+    try {
+        const request = mutationRequest(ctx, ctx.flags.all === true ? undefined : targets[0]);
+        const results = await upgradePlatforms(request);
+        printResults(results);
+        return { success: true, data: results };
     }
-    return written;
-}
-function uninstallPlatform(platform, repoPath) {
-    const files = PLATFORM_CONFIG_FILES[platform];
-    const blockRe = new RegExp(`\\n?${MONOMIND_BLOCK_START}[\\s\\S]*?${MONOMIND_BLOCK_END}\\n?`, 'g');
-    const cleaned = [];
-    for (const relPath of files) {
-        const fullPath = resolve(join(repoPath, relPath));
-        assertWithinRoot(fullPath, repoPath);
-        if (!existsSync(fullPath))
-            continue;
-        // Guard against reading oversized files
-        const fileStat = statSync(fullPath);
-        if (fileStat.size > MAX_CONFIG_FILE_BYTES) {
-            throw new Error(`Config file too large to read (${fileStat.size} bytes): ${relPath}`);
-        }
-        const content = readFileSync(fullPath, 'utf8');
-        writeFileSync(fullPath, content.replace(blockRe, ''), 'utf8');
-        cleaned.push(relPath);
+    catch (reason) {
+        return resultError(reason);
     }
-    return cleaned;
 }
-async function handleInstall(ctx) {
-    const platform = ctx.flags.platform;
-    const all = ctx.flags.all;
-    let repoPath;
+async function handleUninstall(ctx) {
+    const targets = requireTargets(ctx);
+    if (!Array.isArray(targets))
+        return targets;
     try {
-        repoPath = resolveRepoPath(ctx.flags.path ?? '.');
+        const request = mutationRequest(ctx, ctx.flags.all === true ? undefined : targets[0]);
+        const results = await uninstallPlatform(request);
+        printResults(results);
+        return { success: true, data: results };
     }
-    catch (err) {
-        output.error(`Invalid --path: ${err instanceof Error ? err.message : String(err)}`);
-        return { success: false, exitCode: 1 };
-    }
-    if (!platform && !all) {
-        output.error('Specify --platform <name> or --all');
-        output.info(`Supported platforms: ${SUPPORTED_PLATFORMS.join(', ')}`);
-        return { success: false, exitCode: 1 };
+    catch (reason) {
+        return resultError(reason);
     }
-    const targets = all ? [...SUPPORTED_PLATFORMS] : [platform];
-    const invalid = targets.filter((p) => !SUPPORTED_PLATFORMS.includes(p));
-    if (invalid.length > 0) {
-        output.error(`Unknown platform(s): ${invalid.join(', ')}`);
-        output.info(`Supported platforms: ${SUPPORTED_PLATFORMS.join(', ')}`);
-        return { success: false, exitCode: 1 };
+}
+async function handleDoctor(ctx) {
+    const raw = typeof ctx.flags.platform === 'string' ? ctx.flags.platform : undefined;
+    const platform = targetFrom(ctx);
+    if (raw && !platform)
+        return resultError(`Unknown platform: ${raw}`);
+    try {
+        const reports = await runPlatformsDoctor({
+            platform,
+            path: resolve(typeof ctx.flags.path === 'string' ? ctx.flags.path : ctx.cwd),
+            scope: scopeFrom(ctx),
+        });
+        if (ctx.flags.json === true)
+            output.printJson(reports);
+        else
+            reports.forEach((report) => {
+                const state = report.artifacts.map((artifact) => artifact.state).join(', ') || 'no declared artifacts';
+                output.info(`${report.platform}: ${state}`);
+                report.diagnostics.forEach((diagnostic) => output.info(diagnostic));
+            });
+        return { success: true, data: reports };
     }
-    let totalFiles = 0;
-    for (const p of targets) {
-        let written;
-        try {
-            written = installPlatform(p, repoPath);
-        }
-        catch (err) {
-            output.error(`[${p}] Install failed: ${err instanceof Error ? err.message : String(err)}`);
-            continue;
-        }
-        if (written.length > 0) {
-            output.success(`[${p}] Installed Monograph context → ${written.join(', ')}`);
-            totalFiles += written.length;
-        }
-        else {
-            output.info(`[${p}] Already installed — skipped`);
-        }
+    catch (reason) {
+        return resultError(reason);
     }
-    output.success(`Done. ${totalFiles} file(s) updated.`);
-    return { success: true };
 }
-async function handleUninstall(ctx) {
-    const platform = ctx.flags.platform;
-    const all = ctx.flags.all;
-    let repoPath;
+async function handleSetup(ctx) {
+    const targets = requireTargets(ctx);
+    if (!Array.isArray(targets))
+        return targets;
+    output.info('platforms setup is deprecated and no longer writes SessionStart hooks or global plugins.');
+    output.info('Use platforms doctor, then platforms install --scope user --yes.');
     try {
-        repoPath = resolveRepoPath(ctx.flags.path ?? '.');
+        const result = await migrateLegacyInstall({
+            ...mutationRequest(ctx, ctx.flags.all === true ? undefined : targets[0]),
+            dryRun: true,
+        });
+        printResults(result);
+        return { success: true, data: result };
     }
-    catch (err) {
-        output.error(`Invalid --path: ${err instanceof Error ? err.message : String(err)}`);
-        return { success: false, exitCode: 1 };
+    catch (reason) {
+        return resultError(reason);
     }
-    if (!platform && !all) {
-        output.error('Specify --platform <name> or --all');
-        output.info(`Supported platforms: ${SUPPORTED_PLATFORMS.join(', ')}`);
-        return { success: false, exitCode: 1 };
+}
+async function handleDocs(ctx) {
+    const rendered = renderCompatibilityMatrix(PLATFORM_REGISTRY);
+    if (ctx.flags.check !== true) {
+        output.writeln(rendered);
+        return { success: true, data: rendered };
     }
-    const targets = all ? [...SUPPORTED_PLATFORMS] : [platform];
-    const invalid = targets.filter((p) => !SUPPORTED_PLATFORMS.includes(p));
-    if (invalid.length > 0) {
-        output.error(`Unknown platform(s): ${invalid.join(', ')}`);
-        output.info(`Supported platforms: ${SUPPORTED_PLATFORMS.join(', ')}`);
+    const path = resolve(ctx.cwd, 'docs', 'platforms', 'compatibility.md');
+    if (!existsSync(path) || readFileSync(path, 'utf8') !== rendered) {
+        output.error('Platform compatibility documentation is stale; regenerate it from the platform registry.');
         return { success: false, exitCode: 1 };
     }
-    let totalFiles = 0;
-    for (const p of targets) {
-        let cleaned;
-        try {
-            cleaned = uninstallPlatform(p, repoPath);
-        }
-        catch (err) {
-            output.error(`[${p}] Uninstall failed: ${err instanceof Error ? err.message : String(err)}`);
-            continue;
-        }
-        if (cleaned.length > 0) {
-            output.success(`[${p}] Removed Monograph context from ${cleaned.join(', ')}`);
-            totalFiles += cleaned.length;
-        }
-        else {
-            output.info(`[${p}] Nothing to remove — skipped`);
-        }
-    }
-    output.success(`Done. ${totalFiles} file(s) cleaned.`);
+    output.success('Platform compatibility documentation is current.');
     return { success: true };
 }
-const platformOptions = [
-    {
-        name: 'platform',
-        description: `Target platform (${SUPPORTED_PLATFORMS.join(', ')})`,
-        type: 'string',
-    },
-    {
-        name: 'all',
-        description: 'Apply to all 14 supported platforms',
-        type: 'boolean',
-        default: false,
-    },
+const targetOptions = [
+    { name: 'platform', description: 'Target platform id or legacy alias', type: 'string' },
+    { name: 'all', description: 'Apply to all supported platforms', type: 'boolean', default: false },
+    { name: 'path', description: 'Project root', type: 'string', default: '.' },
     {
-        name: 'path',
-        description: 'Path to the repository root (default: current directory)',
+        name: 'scope',
+        description: 'Scope',
         type: 'string',
-        default: '.',
+        choices: ['project', 'user'],
+        default: 'project',
     },
 ];
+const mutationOptions = [
+    ...targetOptions,
+    { name: 'yes', description: 'Authorize user-scope mutation', type: 'boolean', default: false },
+    { name: 'dry-run', description: 'Plan without writing files', type: 'boolean', default: false },
+];
 export const platformsCommand = {
     name: 'platforms',
-    description: 'Install or uninstall Monograph context instructions for AI coding platforms',
+    description: 'Plan and apply evidence-gated Monomind platform integrations',
     subcommands: [
+        {
+            name: 'plan',
+            description: 'Render a read-only adapter plan',
+            options: [
+                ...targetOptions,
+                { name: 'json', description: 'Print JSON', type: 'boolean', default: false },
+            ],
+            action: handlePlan,
+        },
         {
             name: 'install',
-            description: 'Inject Monograph knowledge-graph instructions into platform config file(s)',
-            options: platformOptions,
-            examples: [
-                {
-                    command: 'monomind platforms install --platform claude',
-                    description: 'Install for Claude',
-                },
+            description: 'Apply a platform plan',
+            options: [
+                ...mutationOptions,
                 {
-                    command: 'monomind platforms install --all',
-                    description: 'Install for all 14 platforms',
+                    name: 'enable-hooks',
+                    description: 'Opt in to deterministic hooks',
+                    type: 'boolean',
+                    default: false,
                 },
                 {
-                    command: 'monomind platforms install --platform cursor --path /path/to/repo',
-                    description: 'Install for Cursor in a specific repo',
+                    name: 'enable-blocking-hooks',
+                    description: 'Permit blocking hook decisions',
+                    type: 'boolean',
+                    default: false,
                 },
             ],
             action: handleInstall,
         },
+        {
+            name: 'upgrade',
+            description: 'Reapply managed platform artifacts',
+            options: mutationOptions,
+            action: handleUpgrade,
+        },
         {
             name: 'uninstall',
-            description: 'Remove Monograph knowledge-graph instructions from platform config file(s)',
-            options: platformOptions,
-            examples: [
-                {
-                    command: 'monomind platforms uninstall --platform claude',
-                    description: 'Uninstall for Claude',
-                },
+            description: 'Remove only Monomind-owned artifacts',
+            options: [
+                ...mutationOptions,
                 {
-                    command: 'monomind platforms uninstall --all',
-                    description: 'Uninstall from all 14 platforms',
+                    name: 'remove-legacy',
+                    description: 'Remove marker-verified legacy artifacts',
+                    type: 'boolean',
+                    default: false,
                 },
             ],
             action: handleUninstall,
         },
         {
-            name: 'setup',
-            description: 'Write global (user-level) SessionStart hooks and plugin packages for cursor, codex, and antigravity',
-            options: platformOptions,
-            examples: [
-                {
-                    command: 'monomind platforms setup --platform codex',
-                    description: 'Wire SessionStart hook into ~/.codex/config.toml',
-                },
-                {
-                    command: 'monomind platforms setup --platform cursor',
-                    description: 'Wire SessionStart hook into .cursor/settings.json',
-                },
-                {
-                    command: 'monomind platforms setup --platform antigravity',
-                    description: 'Install monomind plugin into ~/.gemini/antigravity-cli/plugins/',
-                },
+            name: 'doctor',
+            description: 'Inspect platform state without writes',
+            options: [
+                ...targetOptions,
+                { name: 'json', description: 'Print JSON', type: 'boolean', default: false },
             ],
-            action: handleSetup,
-        },
-    ],
-    examples: [
-        {
-            command: 'monomind platforms install --all',
-            description: 'Install Monograph context for all platforms',
+            action: handleDoctor,
         },
         {
-            command: 'monomind platforms setup --platform codex',
-            description: 'Wire Codex SessionStart hook (run once per machine)',
+            name: 'setup',
+            description: 'Deprecated legacy detection shim',
+            options: targetOptions,
+            action: handleSetup,
         },
         {
-            command: 'monomind platforms uninstall --platform cursor',
-            description: 'Remove context from Cursor config',
+            name: 'docs',
+            description: 'Render or verify generated platform compatibility documentation',
+            options: [
+                { name: 'check', description: 'Fail when the checked-in matrix is stale', type: 'boolean' },
+            ],
+            action: handleDocs,
         },
     ],
 };