@nerviq/cli 0.9.3 → 0.9.4

package/src/migrate.js

@@ -0,0 +1,354 @@
+/**
+ * Nerviq Migrate
+ *
+ * Helps migrate configuration files from one version/format of a platform
+ * to a newer version, applying safe in-place transformations.
+ *
+ * Supports:
+ *   cursor  v2 → v3   (legacy .cursorrules → .cursor/rules/*.mdc)
+ *   codex   v1 → v2   (AGENTS.md additions, .codex/ bootstrap)
+ *   aider   v0 → v1   (basic .aider.conf.yml creation from CLI pattern)
+ *   gemini  v1 → v2   (.gemini/ settings.json schema update)
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const COLORS = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[36m',
+};
+
+function c(text, color) {
+  return `${COLORS[color] || ''}${text}${COLORS.reset}`;
+}
+
+// ─── Migration definitions ───────────────────────────────────────────────────
+
+const MIGRATIONS = {
+  cursor: {
+    'v2→v3': {
+      description: 'Migrate legacy .cursorrules to .cursor/rules/*.mdc with proper frontmatter',
+      from: 'v2',
+      to: 'v3',
+      detect: (dir) => {
+        const hasLegacy = fs.existsSync(path.join(dir, '.cursorrules'));
+        const hasMdc = fs.existsSync(path.join(dir, '.cursor', 'rules'));
+        return { applicable: hasLegacy, notes: hasLegacy ? (hasMdc ? 'Legacy .cursorrules present alongside .cursor/rules/ (coexistence)' : 'Legacy .cursorrules present, no .cursor/rules/ yet') : 'No legacy .cursorrules found' };
+      },
+      apply: (dir, { dryRun = false } = {}) => {
+        const legacyPath = path.join(dir, '.cursorrules');
+        if (!fs.existsSync(legacyPath)) return { changes: [], warnings: ['No .cursorrules found'] };
+
+        const content = fs.readFileSync(legacyPath, 'utf8').trim();
+        const targetDir = path.join(dir, '.cursor', 'rules');
+        const targetFile = path.join(targetDir, 'core.mdc');
+
+        const mdcContent = [
+          '---',
+          'alwaysApply: true',
+          '---',
+          '',
+          content,
+          '',
+        ].join('\n');
+
+        const changes = [];
+        const warnings = [];
+
+        if (fs.existsSync(targetFile)) {
+          warnings.push('.cursor/rules/core.mdc already exists — skipped to avoid overwrite');
+        } else {
+          if (!dryRun) {
+            fs.mkdirSync(targetDir, { recursive: true });
+            fs.writeFileSync(targetFile, mdcContent, 'utf8');
+          }
+          changes.push({ action: dryRun ? 'would-create' : 'created', file: '.cursor/rules/core.mdc', detail: 'Converted from .cursorrules with alwaysApply: true' });
+        }
+
+        // Optionally rename .cursorrules → .cursorrules.migrated
+        const migratedPath = path.join(dir, '.cursorrules.migrated');
+        if (!fs.existsSync(migratedPath) && !dryRun) {
+          fs.renameSync(legacyPath, migratedPath);
+          changes.push({ action: 'renamed', file: '.cursorrules → .cursorrules.migrated', detail: 'Preserved as backup' });
+        } else if (dryRun) {
+          changes.push({ action: 'would-rename', file: '.cursorrules → .cursorrules.migrated', detail: 'Backup rename' });
+        }
+
+        return { changes, warnings };
+      },
+    },
+  },
+
+  codex: {
+    'v1→v2': {
+      description: 'Bootstrap .codex/ directory with config.toml and update AGENTS.md',
+      from: 'v1',
+      to: 'v2',
+      detect: (dir) => {
+        const hasAgents = fs.existsSync(path.join(dir, 'AGENTS.md'));
+        const hasCodexDir = fs.existsSync(path.join(dir, '.codex'));
+        return {
+          applicable: hasAgents && !hasCodexDir,
+          notes: !hasAgents
+            ? 'No AGENTS.md found'
+            : hasCodexDir
+              ? '.codex/ already exists'
+              : 'AGENTS.md found, .codex/ missing — upgrade applicable',
+        };
+      },
+      apply: (dir, { dryRun = false } = {}) => {
+        const changes = [];
+        const warnings = [];
+        const codexDir = path.join(dir, '.codex');
+
+        if (!fs.existsSync(codexDir)) {
+          const configToml = [
+            '# Codex configuration — generated by nerviq migrate',
+            '[agent]',
+            'auto_approve = false',
+            '',
+            '[context]',
+            'files = ["AGENTS.md"]',
+            '',
+          ].join('\n');
+
+          if (!dryRun) {
+            fs.mkdirSync(codexDir, { recursive: true });
+            fs.writeFileSync(path.join(codexDir, 'config.toml'), configToml, 'utf8');
+          }
+          changes.push({ action: dryRun ? 'would-create' : 'created', file: '.codex/config.toml', detail: 'Codex config with safe defaults' });
+        } else {
+          warnings.push('.codex/ already exists');
+        }
+
+        return { changes, warnings };
+      },
+    },
+  },
+
+  aider: {
+    'v0→v1': {
+      description: 'Create .aider.conf.yml if missing and add .aider* to .gitignore',
+      from: 'v0',
+      to: 'v1',
+      detect: (dir) => {
+        const hasConf = fs.existsSync(path.join(dir, '.aider.conf.yml'));
+        return {
+          applicable: !hasConf,
+          notes: hasConf ? '.aider.conf.yml already exists' : 'No .aider.conf.yml found — migration applicable',
+        };
+      },
+      apply: (dir, { dryRun = false } = {}) => {
+        const changes = [];
+        const warnings = [];
+
+        const confPath = path.join(dir, '.aider.conf.yml');
+        if (!fs.existsSync(confPath)) {
+          const conf = [
+            '# Aider configuration — generated by nerviq migrate',
+            'auto-commits: true',
+            'auto-lint: false',
+            'auto-test: false',
+            '# model: gpt-4o',
+            '# weak-model: gpt-4o-mini',
+            '# edit-format: diff',
+          ].join('\n') + '\n';
+          if (!dryRun) fs.writeFileSync(confPath, conf, 'utf8');
+          changes.push({ action: dryRun ? 'would-create' : 'created', file: '.aider.conf.yml', detail: 'Safe defaults with auto-commits enabled' });
+        }
+
+        const gitignorePath = path.join(dir, '.gitignore');
+        if (fs.existsSync(gitignorePath)) {
+          const gi = fs.readFileSync(gitignorePath, 'utf8');
+          if (!/\.aider/i.test(gi)) {
+            if (!dryRun) fs.appendFileSync(gitignorePath, '\n# Aider artifacts\n.aider*\n');
+            changes.push({ action: dryRun ? 'would-append' : 'appended', file: '.gitignore', detail: 'Added .aider* pattern' });
+          } else {
+            warnings.push('.gitignore already has .aider* pattern');
+          }
+        }
+
+        return { changes, warnings };
+      },
+    },
+  },
+
+  gemini: {
+    'v1→v2': {
+      description: 'Update .gemini/settings.json schema (model field: string → object)',
+      from: 'v1',
+      to: 'v2',
+      detect: (dir) => {
+        const settingsPath = path.join(dir, '.gemini', 'settings.json');
+        if (!fs.existsSync(settingsPath)) {
+          return { applicable: false, notes: 'No .gemini/settings.json found' };
+        }
+        try {
+          const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+          const needsMigration = typeof settings.model === 'string';
+          return {
+            applicable: needsMigration,
+            notes: needsMigration
+              ? `model field is a string "${settings.model}" — needs to be an object`
+              : 'model field already uses object format',
+          };
+        } catch {
+          return { applicable: false, notes: 'settings.json is invalid JSON' };
+        }
+      },
+      apply: (dir, { dryRun = false } = {}) => {
+        const changes = [];
+        const warnings = [];
+        const settingsPath = path.join(dir, '.gemini', 'settings.json');
+
+        if (!fs.existsSync(settingsPath)) {
+          warnings.push('.gemini/settings.json not found');
+          return { changes, warnings };
+        }
+
+        let settings;
+        try {
+          settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+        } catch {
+          warnings.push('settings.json is invalid JSON — skipped');
+          return { changes, warnings };
+        }
+
+        if (typeof settings.model === 'string') {
+          const oldModel = settings.model;
+          settings.model = { name: oldModel };
+          if (!dryRun) fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+          changes.push({
+            action: dryRun ? 'would-update' : 'updated',
+            file: '.gemini/settings.json',
+            detail: `model: "${oldModel}" → { name: "${oldModel}" }`,
+          });
+        } else {
+          warnings.push('model field already in correct format');
+        }
+
+        return { changes, warnings };
+      },
+    },
+  },
+};
+
+// ─── Main migrate function ────────────────────────────────────────────────────
+
+async function runMigrate({ dir = process.cwd(), platform, from: fromVersion, to: toVersion, dryRun = false, json = false } = {}) {
+  if (!platform) throw new Error('--platform is required. Example: nerviq migrate --platform cursor --from v2 --to v3');
+
+  const platformMigrations = MIGRATIONS[platform];
+  if (!platformMigrations) {
+    throw new Error(`No migrations available for platform '${platform}'. Supported: ${Object.keys(MIGRATIONS).join(', ')}`);
+  }
+
+  // Determine migration key
+  let migrationKey = null;
+  if (fromVersion && toVersion) {
+    migrationKey = `${fromVersion}→${toVersion}`;
+  } else {
+    // Auto-detect applicable migration
+    for (const [key, migration] of Object.entries(platformMigrations)) {
+      const detection = migration.detect(dir);
+      if (detection.applicable) {
+        migrationKey = key;
+        break;
+      }
+    }
+  }
+
+  if (!migrationKey) {
+    // Show available migrations
+    const availableKeys = Object.keys(platformMigrations);
+    const detectionResults = availableKeys.map(key => {
+      const detection = platformMigrations[key].detect(dir);
+      return { key, ...detection };
+    });
+
+    if (json) {
+      return JSON.stringify({ platform, status: 'no-migration-applicable', detectionResults }, null, 2);
+    }
+
+    const lines = [''];
+    lines.push(c(`  nerviq migrate — ${platform}`, 'bold'));
+    lines.push('');
+    lines.push(c('  No applicable migration found.', 'yellow'));
+    lines.push('');
+    lines.push('  Available migrations:');
+    for (const r of detectionResults) {
+      const icon = r.applicable ? c('✓', 'green') : c('-', 'dim');
+      lines.push(`    ${icon}  ${r.key.padEnd(10)}  ${r.notes}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  const migration = platformMigrations[migrationKey];
+  if (!migration) {
+    throw new Error(`Migration '${migrationKey}' not found for platform '${platform}'`);
+  }
+
+  const detection = migration.detect(dir);
+  const { changes, warnings } = migration.apply(dir, { dryRun });
+
+  const result = {
+    platform,
+    migration: migrationKey,
+    description: migration.description,
+    dryRun,
+    applicable: detection.applicable,
+    detectionNotes: detection.notes,
+    changes,
+    warnings,
+  };
+
+  if (json) return JSON.stringify(result, null, 2);
+
+  const lines = [''];
+  lines.push(c(`  nerviq migrate  ${platform} ${migrationKey}`, 'bold'));
+  lines.push(c('  ═══════════════════════════════════════', 'dim'));
+  lines.push('');
+  lines.push(`  ${migration.description}`);
+  lines.push(`  Directory: ${dir}`);
+  lines.push('');
+
+  if (dryRun) lines.push(c('  Dry run — no files modified', 'yellow'));
+
+  if (changes.length > 0) {
+    lines.push('  Changes:');
+    for (const ch of changes) {
+      const icon = ch.action.startsWith('would') ? c('→', 'blue') : c('✓', 'green');
+      lines.push(`    ${icon}  [${ch.action}] ${ch.file}`);
+      if (ch.detail) lines.push(c(`         ${ch.detail}`, 'dim'));
+    }
+  } else {
+    lines.push(c('  No changes made.', 'dim'));
+  }
+
+  if (warnings.length > 0) {
+    lines.push('');
+    lines.push('  Warnings:');
+    for (const w of warnings) lines.push(`    ${c('⚠', 'yellow')}  ${w}`);
+  }
+
+  lines.push('');
+  if (!dryRun && changes.length > 0) {
+    lines.push(c(`  ✓ Migration complete. Run \`nerviq audit --platform ${platform}\` to verify.`, 'green'));
+  } else if (dryRun) {
+    lines.push(c('  Run without --dry-run to apply changes.', 'dim'));
+  }
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+module.exports = { runMigrate, MIGRATIONS };

package/src/opencode/techniques.js

@@ -23,6 +23,7 @@
 const os = require('os');
 const path = require('path');
 const { EMBEDDED_SECRET_PATTERNS, containsEmbeddedSecret } = require('../secret-patterns');
+const { attachSourceUrls } = require('../source-urls');
 
 const DEFAULT_PROJECT_DOC_MAX_BYTES = 32768;
 
@@ -1679,6 +1680,8 @@ const OPENCODE_TECHNIQUES = {
   },
 };
 
+attachSourceUrls('opencode', OPENCODE_TECHNIQUES);
+
 module.exports = {
   OPENCODE_TECHNIQUES,
 };

package/src/source-urls.js

@@ -0,0 +1,219 @@
+/**
+ * Official source URL registry for platform technique catalogs.
+ *
+ * These URLs intentionally point to the nearest authoritative official page for
+ * a given category or check. Some advisory/internal heuristics do not have a
+ * single line-item normative doc, so they fall back to the closest official
+ * platform page that governs the surrounding feature area.
+ */
+
+const SOURCE_URLS = {
+  claude: {
+    defaultUrl: 'https://code.claude.com/docs/en/overview',
+    byCategory: {
+      memory: 'https://code.claude.com/docs/en/memory',
+      quality: 'https://code.claude.com/docs/en/common-workflows',
+      git: 'https://code.claude.com/docs/en/settings',
+      workflow: 'https://code.claude.com/docs/en/common-workflows',
+      security: 'https://code.claude.com/docs/en/permissions',
+      automation: 'https://code.claude.com/docs/en/hooks',
+      design: 'https://code.claude.com/docs/en/best-practices',
+      devops: 'https://code.claude.com/docs/en/common-workflows',
+      hygiene: 'https://code.claude.com/docs/en/overview',
+      performance: 'https://code.claude.com/docs/en/memory',
+      tools: 'https://code.claude.com/docs/en/mcp',
+      prompting: 'https://code.claude.com/docs/en/best-practices',
+      features: 'https://code.claude.com/docs/en/commands',
+      'quality-deep': 'https://code.claude.com/docs/en/best-practices',
+    },
+    byKey: {
+      customCommands: 'https://code.claude.com/docs/en/commands',
+      multipleCommands: 'https://code.claude.com/docs/en/commands',
+      deployCommand: 'https://code.claude.com/docs/en/commands',
+      reviewCommand: 'https://code.claude.com/docs/en/commands',
+      agents: 'https://code.claude.com/docs/en/sub-agents',
+      multipleAgents: 'https://code.claude.com/docs/en/sub-agents',
+      agentsHaveMaxTurns: 'https://code.claude.com/docs/en/sub-agents',
+      agentHasAllowedTools: 'https://code.claude.com/docs/en/sub-agents',
+      skills: 'https://code.claude.com/docs/en/skills',
+      multipleSkills: 'https://code.claude.com/docs/en/skills',
+      skillUsesPaths: 'https://code.claude.com/docs/en/skills',
+      frontendDesignSkill: 'https://code.claude.com/docs/en/skills',
+    },
+  },
+  codex: {
+    defaultUrl: 'https://developers.openai.com/codex/cli',
+    byCategory: {
+      instructions: 'https://developers.openai.com/codex/guides/agents-md',
+      config: 'https://developers.openai.com/codex/config-reference',
+      trust: 'https://developers.openai.com/codex/agent-approvals-security',
+      rules: 'https://developers.openai.com/codex/rules',
+      hooks: 'https://developers.openai.com/codex/hooks',
+      mcp: 'https://developers.openai.com/codex/mcp',
+      skills: 'https://developers.openai.com/codex/skills',
+      agents: 'https://developers.openai.com/codex/subagents',
+      automation: 'https://developers.openai.com/codex/cli',
+      review: 'https://developers.openai.com/codex/cli',
+      local: 'https://developers.openai.com/codex/app/local-environments',
+      'quality-deep': 'https://developers.openai.com/codex/feature-maturity',
+      advisory: 'https://developers.openai.com/codex/cli',
+      'pack-posture': 'https://developers.openai.com/codex/mcp',
+      'repeat-usage': 'https://developers.openai.com/codex/cli',
+      'release-freshness': 'https://developers.openai.com/codex/changelog',
+    },
+    byKey: {
+      codexAutomationManuallyTested: 'https://developers.openai.com/codex/app/automations',
+      codexAutomationAppPrereqAcknowledged: 'https://developers.openai.com/codex/app/automations',
+      codexGitHubActionSafeStrategy: 'https://developers.openai.com/codex/github-action',
+      codexGitHubActionPromptSourceExclusive: 'https://developers.openai.com/codex/github-action',
+      codexGitHubActionTriggerAllowlistsExplicit: 'https://developers.openai.com/codex/github-action',
+      codexCiAuthUsesManagedKey: 'https://developers.openai.com/codex/github-action',
+      codexPluginConfigValid: 'https://developers.openai.com/codex/skills',
+      codexUndoExplicit: 'https://developers.openai.com/codex/config-reference',
+      codexWorktreeLifecycleDocumented: 'https://developers.openai.com/codex/app/local-environments',
+    },
+  },
+  gemini: {
+    defaultUrl: 'https://geminicli.com/docs/get-started/',
+    byCategory: {
+      instructions: 'https://geminicli.com/docs/cli/gemini-md/',
+      config: 'https://geminicli.com/docs/reference/configuration/',
+      trust: 'https://geminicli.com/docs/cli/trusted-folders/',
+      hooks: 'https://geminicli.com/docs/hooks/reference/',
+      mcp: 'https://geminicli.com/docs/tools/mcp-server/',
+      sandbox: 'https://geminicli.com/docs/cli/sandbox/',
+      agents: 'https://geminicli.com/docs/core/subagents/',
+      skills: 'https://geminicli.com/docs/cli/skills/',
+      automation: 'https://google-gemini.github.io/gemini-cli/docs/cli/headless.html',
+      extensions: 'https://geminicli.com/docs/extensions/',
+      review: 'https://ai.google.dev/gemini-api/docs/coding-agents',
+      'quality-deep': 'https://geminicli.com/docs/get-started/',
+      commands: 'https://geminicli.com/docs/cli/custom-commands/',
+      advisory: 'https://geminicli.com/docs/get-started/',
+      'pack-posture': 'https://geminicli.com/docs/tools/mcp-server/',
+      'repeat-usage': 'https://geminicli.com/docs/cli/session-management/',
+      'release-freshness': 'https://geminicli.com/docs/changelogs/latest/',
+    },
+  },
+  copilot: {
+    defaultUrl: 'https://docs.github.com/copilot',
+    byCategory: {
+      instructions: 'https://docs.github.com/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot',
+      config: 'https://code.visualstudio.com/docs/copilot/customization/custom-instructions',
+      trust: 'https://code.visualstudio.com/docs/copilot/security',
+      mcp: 'https://code.visualstudio.com/docs/copilot/chat/mcp-servers',
+      'cloud-agent': 'https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-coding-agent',
+      organization: 'https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-organization/manage-policies',
+      'prompt-files': 'https://code.visualstudio.com/docs/copilot/customization/prompt-files',
+      'skills-agents': 'https://code.visualstudio.com/docs/copilot/agents/overview',
+      'ci-automation': 'https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment',
+      enterprise: 'https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-enterprise',
+      extensions: 'https://docs.github.com/en/copilot/building-copilot-extensions/about-building-copilot-extensions',
+      'quality-deep': 'https://docs.github.com/copilot',
+      advisory: 'https://docs.github.com/copilot',
+      freshness: 'https://github.blog/changelog/',
+    },
+  },
+  cursor: {
+    defaultUrl: 'https://cursor.com/docs',
+    byCategory: {
+      rules: 'https://cursor.com/docs/context/rules',
+      config: 'https://cursor.com/docs',
+      trust: 'https://cursor.com/docs/enterprise/privacy-and-data-governance',
+      'agent-mode': 'https://docs.cursor.com/en/chat/agent',
+      mcp: 'https://cursor.com/docs/cli/mcp',
+      'instructions-quality': 'https://docs.cursor.com/guides/working-with-context',
+      'background-agents': 'https://docs.cursor.com/en/background-agents',
+      automations: 'https://cursor.com/docs/cloud-agent/automations',
+      enterprise: 'https://cursor.com/docs/enterprise',
+      bugbot: 'https://cursor.com/docs/bugbot',
+      'cross-surface': 'https://cursor.com/docs',
+      'quality-deep': 'https://docs.cursor.com/guides/working-with-context',
+      advisory: 'https://cursor.com/docs',
+      freshness: 'https://cursor.com/changelog',
+    },
+  },
+  windsurf: {
+    defaultUrl: 'https://docs.windsurf.com/windsurf/cascade',
+    byCategory: {
+      rules: 'https://windsurf.com/university/general-education/intro-rules-memories',
+      config: 'https://docs.windsurf.com/windsurf/cascade/cascade',
+      trust: 'https://windsurf.com/security',
+      'cascade-agent': 'https://docs.windsurf.com/windsurf/cascade/agents-md',
+      mcp: 'https://docs.windsurf.com/windsurf/cascade/mcp',
+      'instructions-quality': 'https://docs.windsurf.com/windsurf/cascade/agents-md',
+      workflows: 'https://docs.windsurf.com/windsurf/cascade/workflows',
+      memories: 'https://docs.windsurf.com/windsurf/cascade/memories',
+      enterprise: 'https://windsurf.com/security',
+      cascadeignore: 'https://docs.windsurf.com/windsurf/cascade/cascade',
+      'cross-surface': 'https://docs.windsurf.com/windsurf/cascade/cascade',
+      'quality-deep': 'https://docs.windsurf.com/windsurf/cascade/cascade',
+      advisory: 'https://docs.windsurf.com/windsurf/cascade/cascade',
+      freshness: 'https://windsurf.com/changelog',
+    },
+  },
+  aider: {
+    defaultUrl: 'https://aider.chat/docs/',
+    byCategory: {
+      config: 'https://aider.chat/docs/config.html',
+      'advanced-config': 'https://aider.chat/docs/config/aider_conf.html',
+      'git-safety': 'https://aider.chat/docs/git.html',
+      'model-config': 'https://aider.chat/docs/config/adv-model-settings.html',
+      conventions: 'https://aider.chat/docs/usage/conventions.html',
+      architecture: 'https://aider.chat/docs/usage/modes.html',
+      security: 'https://aider.chat/docs/config/dotenv.html',
+      ci: 'https://aider.chat/docs/scripting.html',
+      quality: 'https://aider.chat/docs/usage/lint-test.html',
+      'workflow-patterns': 'https://aider.chat/docs/usage/modes.html',
+      'editor-integration': 'https://aider.chat/docs/config/editor.html',
+      'release-readiness': 'https://aider.chat/docs/',
+    },
+  },
+  opencode: {
+    defaultUrl: 'https://opencode.ai/docs/',
+    byCategory: {
+      instructions: 'https://opencode.ai/docs/rules/',
+      config: 'https://opencode.ai/docs/config/',
+      permissions: 'https://opencode.ai/docs/permissions',
+      plugins: 'https://opencode.ai/docs/plugins/',
+      security: 'https://opencode.ai/docs/tools/',
+      mcp: 'https://opencode.ai/docs/mcp-servers/',
+      ci: 'https://opencode.ai/docs/github/',
+      'quality-deep': 'https://opencode.ai/docs/',
+      skills: 'https://opencode.ai/docs/skills/',
+      agents: 'https://opencode.ai/docs/agents/',
+      commands: 'https://opencode.ai/docs/commands/',
+      tui: 'https://opencode.ai/docs/themes/',
+      governance: 'https://opencode.ai/docs/github/',
+      'release-freshness': 'https://opencode.ai/docs/',
+      'mixed-agent': 'https://opencode.ai/docs/modes/',
+      propagation: 'https://opencode.ai/docs/config/',
+    },
+  },
+};
+
+function attachSourceUrls(platform, techniques) {
+  const mapping = SOURCE_URLS[platform];
+  if (!mapping) {
+    throw new Error(`Unknown source-url platform '${platform}'`);
+  }
+
+  for (const [key, technique] of Object.entries(techniques)) {
+    if (technique.sourceUrl) continue;
+    const resolved =
+      mapping.byKey?.[key] ||
+      mapping.byCategory?.[technique.category] ||
+      mapping.defaultUrl;
+    if (!resolved) {
+      throw new Error(`No sourceUrl mapping found for ${platform}:${key}`);
+    }
+    technique.sourceUrl = resolved;
+  }
+
+  return techniques;
+}
+
+module.exports = {
+  SOURCE_URLS,
+  attachSourceUrls,
+};

package/src/techniques.js

@@ -11,6 +11,7 @@ function hasFrontendSignals(ctx) {
 }
 
 const { containsEmbeddedSecret } = require('./secret-patterns');
+const { attachSourceUrls } = require('./source-urls');
 
 const TECHNIQUES = {
   // ============================================================
@@ -1443,4 +1444,6 @@ const STACKS = {
   dotnet: { files: ['global.json', 'Directory.Build.props'], content: {}, label: '.NET' },
 };
 
+attachSourceUrls('claude', TECHNIQUES);
+
 module.exports = { TECHNIQUES, STACKS, containsEmbeddedSecret };

package/src/windsurf/techniques.js

@@ -28,6 +28,7 @@ const os = require('os');
 const path = require('path');
 const { WindsurfProjectContext } = require('./context');
 const { EMBEDDED_SECRET_PATTERNS, containsEmbeddedSecret } = require('../secret-patterns');
+const { attachSourceUrls } = require('../source-urls');
 const { tryParseJson, validateMcpEnvVars } = require('./config-parser');
 
 // ─── Shared helpers ─────────────────────────────────────────────────────────
@@ -1826,6 +1827,8 @@ const WINDSURF_TECHNIQUES = {
   },
 };
 
+attachSourceUrls('windsurf', WINDSURF_TECHNIQUES);
+
 module.exports = {
   WINDSURF_TECHNIQUES,
 };