@nerviq/cli 1.18.0 → 1.20.0

package/src/gemini/techniques.js

@@ -14,11 +14,11 @@
 const os = require('os');
 const path = require('path');
 const { GeminiProjectContext } = require('./context');
-const { EMBEDDED_SECRET_PATTERNS, containsEmbeddedSecret } = require('../secret-patterns');
-const { attachSourceUrls } = require('../source-urls');
-const { buildSupplementalChecks } = require('../supplemental-checks');
-const { buildStackChecks } = require('../stack-checks');
-const { resolveProjectStateReadPath } = require('../state-paths');
+const { EMBEDDED_SECRET_PATTERNS, containsEmbeddedSecret } = require('../secret-patterns');
+const { attachSourceUrls } = require('../source-urls');
+const { buildSupplementalChecks } = require('../supplemental-checks');
+const { buildStackChecks } = require('../stack-checks');
+const { resolveProjectStateReadPath } = require('../state-paths');
 
 const GEMINI_SUPPLEMENTAL_SOURCE_URLS = {
   'testing-strategy': 'https://geminicli.com/docs/get-started/',
@@ -93,10 +93,37 @@ function settingsData(ctx) {
   return result && result.ok ? result.data : null;
 }
 
+/**
+ * True when .gemini/settings.json is effectively an MCP-only config — i.e.
+ * it configures external tool servers but does not attempt to tune CLI
+ * behaviour (model, sandbox, approval, theme, history, etc.). Checks that
+ * assert on CLI-behaviour keys should be N/A on such configs.
+ */
+function isMcpOnlySettings(data) {
+  if (!data || typeof data !== 'object') return false;
+  const keys = Object.keys(data).filter(k => k !== '$schema' && k !== 'ide' && k !== 'context');
+  if (keys.length === 0) return true;
+  const behaviourKeys = new Set(['model', 'sandbox', 'safety', 'theme', 'approval', 'approvalMode', 'history', 'session', 'telemetry', 'hooks', 'tools', 'skills', 'commands', 'extensions', 'security']);
+  return keys.every(k => k === 'mcpServers' || !behaviourKeys.has(k));
+}
+
 function docsBundle(ctx) {
   const gmd = geminiMd(ctx) || '';
   const readme = ctx.fileContent('README.md') || '';
-  return `${gmd}\n${readme}`;
+  const agents = ctx.fileContent('AGENTS.md') || '';
+  const claudeMd = ctx.fileContent('CLAUDE.md') || '';
+  const contributing = ctx.fileContent('CONTRIBUTING.md') || '';
+  const architecture = ctx.fileContent('ARCHITECTURE.md') || '';
+  const development = ctx.fileContent('DEVELOPMENT.md') || ctx.fileContent('docs/development.md') || '';
+  return [gmd, readme, agents, claudeMd, contributing, architecture, development].join('\n');
+}
+
+// Broader bundle for stack-specific docs discovery (mirrors the Copilot
+// PP-01 stackDocsBundle approach): consults common developer docs in
+// addition to the instruction surfaces so stack checks don't hard-fail
+// when conventions live in CONTRIBUTING/DEVELOPMENT instead of GEMINI.md.
+function stackDocsBundle(ctx) {
+  return docsBundle(ctx);
 }
 
 function expectedVerificationCategories(ctx) {
@@ -262,11 +289,18 @@ const GEMINI_TECHNIQUES = {
 
   geminiMdArchitecture: {
     id: 'GM-A04',
-    name: 'GEMINI.md has architecture section or Mermaid diagram',
+    name: 'Instructions have architecture section or Mermaid diagram',
     check: (ctx) => {
       const content = geminiMd(ctx);
       if (!content) return null;
-      return hasArchitecture(content);
+      if (hasArchitecture(content)) return true;
+      // Credit an ARCHITECTURE.md at repo root, or architecture content
+      // surfaced in README.md — both are legitimate ways Gemini will pick
+      // up repo shape, especially when GEMINI.md is a pointer/import.
+      const arch = ctx.fileContent('ARCHITECTURE.md') || ctx.fileContent('docs/architecture.md');
+      if (arch) return true;
+      const readme = ctx.fileContent('README.md') || '';
+      return hasArchitecture(readme);
     },
     impact: 'medium',
     rating: 4,
@@ -352,7 +386,15 @@ const GEMINI_TECHNIQUES = {
   geminiSettingsExists: {
     id: 'GM-B01',
     name: '.gemini/settings.json exists',
-    check: (ctx) => Boolean(ctx.fileContent('.gemini/settings.json')),
+    check: (ctx) => {
+      if (ctx.fileContent('.gemini/settings.json')) return true;
+      // N/A when the repo uses only the GEMINI.md-instruction convention
+      // without any .gemini/ configuration directory. settings.json is
+      // opt-in for CLI tuning; instruction-only repos should not fail.
+      const hasGeminiDir = ctx.hasDir && ctx.hasDir('.gemini');
+      if (!hasGeminiDir) return null;
+      return false;
+    },
     impact: 'high',
     rating: 5,
     category: 'config',
@@ -397,6 +439,7 @@ const GEMINI_TECHNIQUES = {
     check: (ctx) => {
       const data = settingsData(ctx);
       if (!data) return null;
+      if (isMcpOnlySettings(data)) return null;
       if (!data.model) return false;
       // v0.36.0: model field MUST be an object { name: "..." }, not a string
       // String format causes exit code 41: "Expected object, received string"
@@ -419,8 +462,9 @@ const GEMINI_TECHNIQUES = {
     check: (ctx) => {
       const data = settingsData(ctx);
       if (!data) return null;
-      // At least sandbox or safety setting should be explicit
-      return Boolean(data.sandbox || data.safety || data.theme);
+      if (isMcpOnlySettings(data)) return null;
+      // At least one CLI-behaviour setting should be explicit.
+      return Boolean(data.sandbox || data.safety || data.theme || data.approval || data.approvalMode);
     },
     impact: 'medium',
     rating: 4,
@@ -479,13 +523,17 @@ const GEMINI_TECHNIQUES = {
 
   geminiEnvApiKey: {
     id: 'GM-B07',
-    name: '.env exists with required API keys (GEMINI_API_KEY or Google auth)',
+    name: 'API key / auth documented (env file, README, or GEMINI.md)',
     check: (ctx) => {
       const envContent = ctx.fileContent('.env') || '';
-      const envExample = ctx.fileContent('.env.example') || ctx.fileContent('.env.template') || '';
-      const combined = `${envContent}\n${envExample}`;
-      // Check for Gemini API key or Google auth
-      return /\bGEMINI_API_KEY\b|\bGOOGLE_API_KEY\b|\bGOOGLE_APPLICATION_CREDENTIALS\b|\bgcloud\b/i.test(combined) || Boolean(envContent);
+      const envExample = ctx.fileContent('.env.example') || ctx.fileContent('.env.template') || ctx.fileContent('.env.sample') || '';
+      const docs = docsBundle(ctx);
+      const combined = `${envContent}\n${envExample}\n${docs}`;
+      if (!combined.trim()) return null;
+      // Credit env files OR documentation that mentions any Gemini/Google auth mechanism,
+      // including `gemini auth`, ADC / application default credentials, Vertex AI, or a
+      // direct mention of the standard env var names.
+      return /\bGEMINI_API_KEY\b|\bGOOGLE_API_KEY\b|\bGOOGLE_APPLICATION_CREDENTIALS\b|\bgcloud\b|\bapplication[- ]default credentials?\b|\bADC\b|\bvertex[- ]?ai\b|\bgemini auth\b|\bservice account\b/i.test(combined);
     },
     impact: 'high',
     rating: 4,
@@ -542,6 +590,7 @@ const GEMINI_TECHNIQUES = {
     check: (ctx) => {
       const data = settingsData(ctx);
       if (!data) return null;
+      if (isMcpOnlySettings(data)) return null;
       return Boolean(data.sandbox && (data.sandbox.mode || typeof data.sandbox === 'string'));
     },
     impact: 'high',
@@ -1017,6 +1066,7 @@ const GEMINI_TECHNIQUES = {
     check: (ctx) => {
       const data = settingsData(ctx);
       if (!data) return null;
+      if (isMcpOnlySettings(data)) return null;
       const sandbox = data.sandbox;
       if (!sandbox) return false;
       const mode = typeof sandbox === 'string' ? sandbox : sandbox.mode;
@@ -1633,8 +1683,9 @@ const GEMINI_TECHNIQUES = {
     id: 'GM-J01',
     name: 'Rate limit/quota awareness documented',
     check: (ctx) => {
-      const gmd = geminiMd(ctx) || '';
-      return /\brate limit\b|\bquota\b|\brequests? per\b|\bcost\b|\btoken\b.*\blimit\b/i.test(gmd);
+      const docs = docsBundle(ctx);
+      if (!docs.trim()) return null;
+      return /\brate[- ]?limit\b|\bquota\b|\brequests? per\b|\bcost\b|\btoken\b.*\blimit\b|\bthrottl|\b429\b/i.test(docs);
     },
     impact: 'medium',
     rating: 3,
@@ -1677,6 +1728,7 @@ const GEMINI_TECHNIQUES = {
     check: (ctx) => {
       const data = settingsData(ctx);
       if (!data) return null;
+      if (isMcpOnlySettings(data)) return null;
       // Check if session/history settings are explicit
       return data.history !== undefined || data.session !== undefined || data.telemetry !== undefined;
     },
@@ -1836,11 +1888,11 @@ const GEMINI_TECHNIQUES = {
 
   geminiTokenUsageAwareness: {
     id: 'GM-K05',
-    name: 'Token usage awareness in GEMINI.md',
+    name: 'Token usage awareness documented',
     check: (ctx) => {
-      const gmd = geminiMd(ctx) || '';
-      if (!gmd) return null;
-      return /\btoken\b|\bcontext window\b|\bcontext length\b|\b1M\b|\btruncat/i.test(gmd);
+      const docs = docsBundle(ctx);
+      if (!docs.trim()) return null;
+      return /\btoken\b|\bcontext window\b|\bcontext length\b|\b1M\b|\btruncat/i.test(docs);
     },
     impact: 'low',
     rating: 2,
@@ -1863,7 +1915,12 @@ const GEMINI_TECHNIQUES = {
     name: 'Custom commands exist in .gemini/commands/',
     check: (ctx) => {
       const commandFiles = ctx.commandFiles ? ctx.commandFiles() : [];
-      return commandFiles.length > 0;
+      if (commandFiles.length > 0) return true;
+      // Custom commands are opt-in — only fire when the repo already has
+      // a .gemini/commands/ directory (implying the user intends to use
+      // commands but hasn't populated it).
+      const hasCommandsDir = ctx.hasDir && ctx.hasDir('.gemini/commands');
+      return hasCommandsDir ? false : null;
     },
     impact: 'medium',
     rating: 3,
@@ -2063,23 +2120,23 @@ const GEMINI_TECHNIQUES = {
   },
 
   // CP-08: O. Repeat-Usage Hygiene (3 checks)
-  geminiSnapshotRetention: {
-    id: 'GM-O01', name: 'At least one prior audit snapshot exists',
-    check: (ctx) => { try { const fs = require('fs'); const p = resolveProjectStateReadPath(ctx.dir, 'snapshots', 'index.json'); if (!fs.existsSync(p)) return null; const e = JSON.parse(fs.readFileSync(p, 'utf8')); return Array.isArray(e) && e.length > 0; } catch { return null; } },
+  geminiSnapshotRetention: {
+    id: 'GM-O01', name: 'At least one prior audit snapshot exists',
+    check: (ctx) => { try { const fs = require('fs'); const p = resolveProjectStateReadPath(ctx.dir, 'snapshots', 'index.json'); if (!fs.existsSync(p)) return null; const e = JSON.parse(fs.readFileSync(p, 'utf8')); return Array.isArray(e) && e.length > 0; } catch { return null; } },
     impact: 'medium', rating: 3, category: 'repeat-usage',
     fix: 'Run `npx nerviq --platform gemini --snapshot` to save your first snapshot.',
     template: null, file: () => null, line: () => null,
   },
-  geminiFeedbackLoopHealth: {
-    id: 'GM-O02', name: 'Feedback loop functional when feedback submitted',
-    check: (ctx) => { try { const fs = require('fs'); const p = resolveProjectStateReadPath(ctx.dir, 'outcomes', 'index.json'); if (!fs.existsSync(p)) return null; const e = JSON.parse(fs.readFileSync(p, 'utf8')); return Array.isArray(e) && e.length > 0; } catch { return null; } },
+  geminiFeedbackLoopHealth: {
+    id: 'GM-O02', name: 'Feedback loop functional when feedback submitted',
+    check: (ctx) => { try { const fs = require('fs'); const p = resolveProjectStateReadPath(ctx.dir, 'outcomes', 'index.json'); if (!fs.existsSync(p)) return null; const e = JSON.parse(fs.readFileSync(p, 'utf8')); return Array.isArray(e) && e.length > 0; } catch { return null; } },
     impact: 'medium', rating: 3, category: 'repeat-usage',
     fix: 'Submit feedback using `npx nerviq --platform gemini feedback`.',
     template: null, file: () => null, line: () => null,
   },
-  geminiTrendDataAvailability: {
-    id: 'GM-O03', name: 'Trend data computable (2+ snapshots)',
-    check: (ctx) => { try { const fs = require('fs'); const p = resolveProjectStateReadPath(ctx.dir, 'snapshots', 'index.json'); if (!fs.existsSync(p)) return null; const e = JSON.parse(fs.readFileSync(p, 'utf8')); return (Array.isArray(e) ? e : []).filter(x => x.snapshotKind === 'audit').length >= 2; } catch { return null; } },
+  geminiTrendDataAvailability: {
+    id: 'GM-O03', name: 'Trend data computable (2+ snapshots)',
+    check: (ctx) => { try { const fs = require('fs'); const p = resolveProjectStateReadPath(ctx.dir, 'snapshots', 'index.json'); if (!fs.existsSync(p)) return null; const e = JSON.parse(fs.readFileSync(p, 'utf8')); return (Array.isArray(e) ? e : []).filter(x => x.snapshotKind === 'audit').length >= 2; } catch { return null; } },
     impact: 'low', rating: 2, category: 'repeat-usage',
     fix: 'Run at least 2 audits with --snapshot for trend tracking.',
     template: null, file: () => null, line: () => null,
@@ -2109,7 +2166,22 @@ const GEMINI_TECHNIQUES = {
   },
   geminiPropagationCompleteness: {
     id: 'GM-P03', name: 'No dangling surface references',
-    check: (ctx) => { const g = ctx.geminiMdContent(); if (!g) return null; const issues = []; if (/\bhooks?\b/i.test(g)) { const s = ctx.settingsJson(); if (!s || (!s.hooks && !s.BeforeTool && !s.AfterTool)) issues.push('hooks'); } if (/\bskills?\b/i.test(g) && !(ctx.hasDir ? ctx.hasDir('.gemini/skills') : false)) issues.push('skills'); if (/\bextensions?\b/i.test(g) && !(ctx.hasDir ? ctx.hasDir('.gemini/extensions') : false)) issues.push('extensions'); return issues.length === 0; },
+    check: (ctx) => {
+      const g = ctx.geminiMdContent();
+      if (!g) return null;
+      const issues = [];
+      // Require specific Gemini-CLI vocabulary before asserting a dangling
+      // reference. "skills" is too generic a word (appears in unrelated
+      // product copy); require `.gemini/skills` path or `gemini skills`
+      // phrasing. Same for hooks/extensions.
+      if (/\.gemini\/hooks\b|\bgemini hooks?\b|\bhooksConfig\b|\bBeforeTool\b|\bAfterTool\b/i.test(g)) {
+        const s = ctx.settingsJson();
+        if (!s || !s.ok || (!s.data || (!s.data.hooks && !s.data.BeforeTool && !s.data.AfterTool))) issues.push('hooks');
+      }
+      if (/\.gemini\/skills\b|\bgemini skills?\b/i.test(g) && !(ctx.hasDir ? ctx.hasDir('.gemini/skills') : false)) issues.push('skills');
+      if (/\.gemini\/extensions\b|\bgemini extensions?\b/i.test(g) && !(ctx.hasDir ? ctx.hasDir('.gemini/extensions') : false)) issues.push('extensions');
+      return issues.length === 0;
+    },
     impact: 'high', rating: 4, category: 'release-freshness',
     fix: 'Ensure all surfaces mentioned in GEMINI.md have corresponding definition files.',
     template: 'gemini-md', file: () => 'GEMINI.md', line: () => 1,

package/src/governance.js

@@ -1,7 +1,7 @@
-const { DOMAIN_PACKS } = require('./domain-packs');
-const { MCP_PACKS, mergeMcpServers, normalizeMcpPackKeys } = require('./mcp-packs');
-const { getCodexGovernanceSummary } = require('./codex/governance');
-const { formatTerminologyLines } = require('./terminology');
+const { DOMAIN_PACKS } = require('./domain-packs');
+const { MCP_PACKS, mergeMcpServers, normalizeMcpPackKeys } = require('./mcp-packs');
+const { getCodexGovernanceSummary } = require('./codex/governance');
+const { formatTerminologyLines } = require('./terminology');
 
 const PERMISSION_PROFILES = [
   {
@@ -104,19 +104,19 @@ const HOOK_REGISTRY = [
     dryRunExample: 'Edit a catalog file and verify duplicate check runs without blocking.',
     rollbackPath: 'Remove the PostToolUse hook entry from settings.',
   },
-  {
-    key: 'injection-defense',
-    file: '.claude/hooks/injection-defense.js',
-    triggerPoint: 'PostToolUse',
-    matcher: 'WebFetch|WebSearch|Read|Grep|Glob|mcp__.*',
-    purpose: 'Scans external content flows for common prompt injection patterns and logs suspicious findings.',
-    filesTouched: ['.claude/logs/prompt-injection-alerts.log'],
-    sideEffects: ['Appends an alert line when suspicious external content is detected.'],
-    risk: 'low',
-    riskLevel: 'low',
-    dryRunExample: 'Run a WebFetch or MCP-backed tool call and verify suspicious content is logged for review.',
-    rollbackPath: 'Remove the PostToolUse hook entry from settings.',
-  },
+  {
+    key: 'injection-defense',
+    file: '.claude/hooks/injection-defense.js',
+    triggerPoint: 'PostToolUse',
+    matcher: 'WebFetch|WebSearch|Read|Grep|Glob|mcp__.*',
+    purpose: 'Scans external content flows for common prompt injection patterns and logs suspicious findings.',
+    filesTouched: ['.claude/logs/prompt-injection-alerts.log'],
+    sideEffects: ['Appends an alert line when suspicious external content is detected.'],
+    risk: 'low',
+    riskLevel: 'low',
+    dryRunExample: 'Run a WebFetch or MCP-backed tool call and verify suspicious content is logged for review.',
+    rollbackPath: 'Remove the PostToolUse hook entry from settings.',
+  },
   {
     key: 'trust-drift-check',
     file: '.claude/hooks/trust-drift-check.sh',
@@ -299,24 +299,24 @@ function buildHookConfig(hookFiles, profileKey) {
     return {};
   }
 
-  // Detect hook runtime: .js files use node, .sh files use bash
-  const hookCommand = (file) => {
-    if (file.endsWith('.js')) return `node .claude/hooks/${file}`;
-    return `bash .claude/hooks/${file}`;
-  };
-  const isSecrets = (f) => f === 'protect-secrets.sh' || f === 'protect-secrets.js';
-  const isSession = (f) => f === 'session-start.sh' || f === 'session-start.js';
-  const isInjection = (f) => f === 'injection-defense.sh' || f === 'injection-defense.js';
-
-  const hookConfig = {
-    PostToolUse: [{
-      matcher: 'Write|Edit',
-      hooks: uniqueFiles
-        .filter(file => !isSecrets(file) && !isSession(file) && !isInjection(file))
-        .map(file => ({
-          type: 'command',
-          command: hookCommand(file),
-          timeout: 10,
+  // Detect hook runtime: .js files use node, .sh files use bash
+  const hookCommand = (file) => {
+    if (file.endsWith('.js')) return `node .claude/hooks/${file}`;
+    return `bash .claude/hooks/${file}`;
+  };
+  const isSecrets = (f) => f === 'protect-secrets.sh' || f === 'protect-secrets.js';
+  const isSession = (f) => f === 'session-start.sh' || f === 'session-start.js';
+  const isInjection = (f) => f === 'injection-defense.sh' || f === 'injection-defense.js';
+
+  const hookConfig = {
+    PostToolUse: [{
+      matcher: 'Write|Edit',
+      hooks: uniqueFiles
+        .filter(file => !isSecrets(file) && !isSession(file) && !isInjection(file))
+        .map(file => ({
+          type: 'command',
+          command: hookCommand(file),
+          timeout: 10,
         })),
     }],
   };
@@ -334,29 +334,29 @@ function buildHookConfig(hookFiles, profileKey) {
   }
 
   const sessionFile = uniqueFiles.find(isSession);
-  if (sessionFile) {
-    hookConfig.SessionStart = [{
-      matcher: '*',
-      hooks: [{
-        type: 'command',
+  if (sessionFile) {
+    hookConfig.SessionStart = [{
+      matcher: '*',
+      hooks: [{
+        type: 'command',
         command: hookCommand(sessionFile),
         timeout: 5,
-      }],
-    }];
-  }
-
-  const injectionFile = uniqueFiles.find(isInjection);
-  if (injectionFile) {
-    hookConfig.PostToolUse = hookConfig.PostToolUse || [];
-    hookConfig.PostToolUse.push({
-      matcher: 'WebFetch|WebSearch|Read|Grep|Glob|mcp__.*',
-      hooks: [{
-        type: 'command',
-        command: hookCommand(injectionFile),
-        timeout: 5,
-      }],
-    });
-  }
+      }],
+    }];
+  }
+
+  const injectionFile = uniqueFiles.find(isInjection);
+  if (injectionFile) {
+    hookConfig.PostToolUse = hookConfig.PostToolUse || [];
+    hookConfig.PostToolUse.push({
+      matcher: 'WebFetch|WebSearch|Read|Grep|Glob|mcp__.*',
+      hooks: [{
+        type: 'command',
+        command: hookCommand(injectionFile),
+        timeout: 5,
+      }],
+    });
+  }
 
   if ((hookConfig.PostToolUse[0].hooks || []).length === 0) {
     delete hookConfig.PostToolUse;
@@ -421,15 +421,15 @@ function printGovernanceSummary(summary, options = {}) {
   console.log('');
   console.log(`  nerviq ${summary.platformLabel.toLowerCase()} governance`);
   console.log('  ═══════════════════════════════════════');
-  console.log(`  Safe defaults, hook transparency, and pilot guidance for ${summary.platformLabel}.`);
-  console.log('');
-
-  for (const line of formatTerminologyLines(['governance', 'hooks', 'denyRules', 'mcp'])) {
-    console.log(line);
-  }
-  console.log('');
-
-  console.log('  Permission Profiles');
+  console.log(`  Safe defaults, hook transparency, and pilot guidance for ${summary.platformLabel}.`);
+  console.log('');
+
+  for (const line of formatTerminologyLines(['governance', 'hooks', 'denyRules', 'mcp'])) {
+    console.log(line);
+  }
+  console.log('');
+
+  console.log('  Permission Profiles');
   for (const profile of summary.permissionProfiles) {
     console.log(`  - ${profile.label} [${profile.risk}]`);
     console.log(`    ${profile.useWhen}`);
@@ -590,13 +590,13 @@ function renderGovernanceMarkdown(summary) {
   return lines.join('\n');
 }
 
-module.exports = {
-  PERMISSION_PROFILES,
-  HOOK_REGISTRY,
-  POLICY_PACKS,
-  getPermissionProfile,
-  isWritableProfile,
-  ensureWritableProfile,
+module.exports = {
+  PERMISSION_PROFILES,
+  HOOK_REGISTRY,
+  POLICY_PACKS,
+  getPermissionProfile,
+  isWritableProfile,
+  ensureWritableProfile,
   buildSettingsForProfile,
   getGovernanceSummary,
   printGovernanceSummary,

package/src/harmony/add.js

@@ -1,68 +1,68 @@
-/**
- * Platform Addition Wizard
- * Helps users add a new platform config to their project.
- */
-
-const fs = require('fs');
-const path = require('path');
-const { detectActivePlatforms, PLATFORM_SIGNATURES } = require('./canon');
-const { applyHarmonySync } = require('./sync');
-
-const PLATFORM_BOOTSTRAPS = {
-  claude: { files: [{ path: 'CLAUDE.md', content: '# Project Instructions\n\nAdd your Claude Code instructions here.\n' }] },
-  codex: { files: [{ path: 'AGENTS.md', content: '# Agents Instructions\n\nAdd your Codex instructions here.\n' }] },
-  gemini: { files: [{ path: 'GEMINI.md', content: '# Gemini Instructions\n\nAdd your Gemini CLI instructions here.\n' }] },
-  copilot: { files: [{ path: '.github/copilot-instructions.md', content: '# Copilot Instructions\n\nAdd your GitHub Copilot instructions here.\n' }] },
-  cursor: { files: [{ path: '.cursorrules', content: '# Cursor Rules\n\nAdd your Cursor rules here.\n' }] },
-  windsurf: { files: [{ path: '.windsurfrules', content: '# Windsurf Rules\n\nAdd your Windsurf rules here.\n' }] },
-  aider: { files: [{ path: '.aider.conf.yml', content: '# Aider Configuration\n# See: https://aider.chat/docs/config/aider_conf.html\n' }] },
-  opencode: { files: [{ path: 'opencode.json', content: '{\n  "instructions": "Add your OpenCode instructions here."\n}\n' }] },
-};
-
-function addPlatform(dir, platformKey) {
-  // Validate platform
-  if (!PLATFORM_SIGNATURES[platformKey]) {
-    return { success: false, error: `Unknown platform: ${platformKey}. Available: ${Object.keys(PLATFORM_SIGNATURES).join(', ')}` };
-  }
-
-  // Check if already active
-  const active = detectActivePlatforms(dir);
-  const alreadyActive = active.find(p => p.platform === platformKey);
-  if (alreadyActive) {
-    return { success: false, error: `${platformKey} is already active in this project.` };
-  }
-
-  const beforeCount = active.length;
-  const bootstrap = PLATFORM_BOOTSTRAPS[platformKey];
-  const created = [];
-
-  // Create bootstrap files
-  for (const file of bootstrap.files) {
-    const fullPath = path.join(dir, file.path);
-    if (fs.existsSync(fullPath)) continue;
-    const dirName = path.dirname(fullPath);
-    fs.mkdirSync(dirName, { recursive: true });
-    fs.writeFileSync(fullPath, file.content, 'utf8');
-    created.push(file.path);
-  }
-
-  // Run harmony sync to populate managed blocks
-  let syncResult = null;
-  try {
-    syncResult = applyHarmonySync(dir);
-  } catch { /* sync is optional */ }
-
-  const afterActive = detectActivePlatforms(dir);
-  const afterCount = afterActive.length;
-
-  return {
-    success: true,
-    platform: platformKey,
-    created,
-    beforeCount,
-    afterCount,
-    syncApplied: syncResult ? syncResult.applied.length : 0,
-  };
-}
-
-module.exports = { addPlatform, PLATFORM_BOOTSTRAPS };
+/**
+ * Platform Addition Wizard
+ * Helps users add a new platform config to their project.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { detectActivePlatforms, PLATFORM_SIGNATURES } = require('./canon');
+const { applyHarmonySync } = require('./sync');
+
+const PLATFORM_BOOTSTRAPS = {
+  claude: { files: [{ path: 'CLAUDE.md', content: '# Project Instructions\n\nAdd your Claude Code instructions here.\n' }] },
+  codex: { files: [{ path: 'AGENTS.md', content: '# Agents Instructions\n\nAdd your Codex instructions here.\n' }] },
+  gemini: { files: [{ path: 'GEMINI.md', content: '# Gemini Instructions\n\nAdd your Gemini CLI instructions here.\n' }] },
+  copilot: { files: [{ path: '.github/copilot-instructions.md', content: '# Copilot Instructions\n\nAdd your GitHub Copilot instructions here.\n' }] },
+  cursor: { files: [{ path: '.cursorrules', content: '# Cursor Rules\n\nAdd your Cursor rules here.\n' }] },
+  windsurf: { files: [{ path: '.windsurfrules', content: '# Windsurf Rules\n\nAdd your Windsurf rules here.\n' }] },
+  aider: { files: [{ path: '.aider.conf.yml', content: '# Aider Configuration\n# See: https://aider.chat/docs/config/aider_conf.html\n' }] },
+  opencode: { files: [{ path: 'opencode.json', content: '{\n  "instructions": "Add your OpenCode instructions here."\n}\n' }] },
+};
+
+function addPlatform(dir, platformKey) {
+  // Validate platform
+  if (!PLATFORM_SIGNATURES[platformKey]) {
+    return { success: false, error: `Unknown platform: ${platformKey}. Available: ${Object.keys(PLATFORM_SIGNATURES).join(', ')}` };
+  }
+
+  // Check if already active
+  const active = detectActivePlatforms(dir);
+  const alreadyActive = active.find(p => p.platform === platformKey);
+  if (alreadyActive) {
+    return { success: false, error: `${platformKey} is already active in this project.` };
+  }
+
+  const beforeCount = active.length;
+  const bootstrap = PLATFORM_BOOTSTRAPS[platformKey];
+  const created = [];
+
+  // Create bootstrap files
+  for (const file of bootstrap.files) {
+    const fullPath = path.join(dir, file.path);
+    if (fs.existsSync(fullPath)) continue;
+    const dirName = path.dirname(fullPath);
+    fs.mkdirSync(dirName, { recursive: true });
+    fs.writeFileSync(fullPath, file.content, 'utf8');
+    created.push(file.path);
+  }
+
+  // Run harmony sync to populate managed blocks
+  let syncResult = null;
+  try {
+    syncResult = applyHarmonySync(dir);
+  } catch { /* sync is optional */ }
+
+  const afterActive = detectActivePlatforms(dir);
+  const afterCount = afterActive.length;
+
+  return {
+    success: true,
+    platform: platformKey,
+    created,
+    beforeCount,
+    afterCount,
+    syncApplied: syncResult ? syncResult.applied.length : 0,
+  };
+}
+
+module.exports = { addPlatform, PLATFORM_BOOTSTRAPS };