@a-company/paradigm 1.5.0

package/dist/chunk-YDNKXH4Z.js

@@ -0,0 +1,2316 @@
+#!/usr/bin/env node
+import {
+  parseParadigmConfig
+} from "./chunk-YO6DVTL7.js";
+
+// src/core/ide-adapters/index.ts
+import * as fs6 from "fs";
+import * as path6 from "path";
+
+// src/core/ide-adapters/cursor.ts
+import * as fs from "fs";
+import * as path from "path";
+import * as os2 from "os";
+import * as yaml from "js-yaml";
+
+// src/core/ide-adapters/base.ts
+import * as os from "os";
+function generateHeader(projectName, ideName) {
+  const lines = [];
+  lines.push(`# ${projectName} - Paradigm Context`);
+  lines.push("");
+  lines.push(`Generated for ${ideName} by Paradigm.`);
+  lines.push("");
+  return lines.join("\n");
+}
+function generateOverview(config) {
+  const lines = [];
+  if (config["agent-guidelines"]?.overview) {
+    lines.push("## Overview");
+    lines.push("");
+    lines.push(config["agent-guidelines"].overview);
+    lines.push("");
+  }
+  if (config["agent-guidelines"]?.["how-to-use"]?.length) {
+    lines.push("## How to Use Paradigm");
+    lines.push("");
+    for (const instruction of config["agent-guidelines"]["how-to-use"]) {
+      lines.push(`- ${instruction}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function generateSymbolSystem(config) {
+  const lines = [];
+  lines.push("## Symbol System");
+  lines.push("");
+  lines.push("Use these prefixes to reference project elements:");
+  lines.push("");
+  lines.push("| Symbol | Name | Description |");
+  lines.push("|--------|------|-------------|");
+  const symbolSystem = config["symbol-system"];
+  if (symbolSystem) {
+    for (const [prefix, def] of Object.entries(symbolSystem)) {
+      lines.push(`| \`${prefix}\` | ${def.name} | ${def.description} |`);
+    }
+  }
+  lines.push("");
+  lines.push("See `.paradigm/specs/symbols.md` for complete reference.");
+  lines.push("");
+  return lines.join("\n");
+}
+function generateLoggingRules(config) {
+  const lines = [];
+  if (!config.logging?.enforce) {
+    return "";
+  }
+  lines.push("## Paradigm Logging");
+  lines.push("");
+  lines.push("**IMPORTANT:** Use the Paradigm logger instead of raw console.log/print.");
+  lines.push("");
+  lines.push("```");
+  lines.push("// Use this pattern:");
+  lines.push("log.component('#login-handler').info('Starting login', { email });");
+  lines.push("log.component('#database').debug('Query executed', { duration });");
+  lines.push("log.gate('^authenticated').warn('Access denied', { userId });");
+  lines.push("log.signal('!login-success').info('User authenticated');");
+  lines.push("```");
+  lines.push("");
+  if (config.logging["symbol-mapping"]) {
+    lines.push("### Symbol Mapping by Directory");
+    lines.push("");
+    lines.push("| Directory | Symbol | Logger Method |");
+    lines.push("|-----------|--------|---------------|");
+    for (const [pattern, symbol] of Object.entries(config.logging["symbol-mapping"])) {
+      const method = getLogMethodForSymbol(symbol);
+      lines.push(`| \`${pattern}\` | \`${symbol}\` | \`log.${method}()\` |`);
+    }
+    lines.push("");
+  }
+  lines.push("See `.paradigm/specs/logger.md` for full specification.");
+  lines.push("");
+  return lines.join("\n");
+}
+function getLogMethodForSymbol(symbol) {
+  const mapping = {
+    "#": "component",
+    "^": "gate",
+    "!": "signal",
+    "$": "flow",
+    "~": "aspect",
+    // v1 backwards compat — all map to component() in v2
+    "@": "component",
+    "%": "component",
+    "&": "component"
+  };
+  return mapping[symbol] || "raw";
+}
+function generateScanProtocol(config) {
+  if (!config.scan?.enabled) {
+    return "";
+  }
+  const lines = [];
+  lines.push("## Paradigm Scan");
+  lines.push("");
+  lines.push('When the user says "**paradigm scan**" with an image:');
+  lines.push("");
+  lines.push("1. Analyze the image for UI elements");
+  lines.push("2. Cross-reference with `.paradigm/scan-index.json`");
+  lines.push("3. Return structured mapping of visual elements to code");
+  lines.push("");
+  lines.push("| Mode | Use Case |");
+  lines.push("|------|----------|");
+  lines.push("| `paradigm scan` | Map any image to code |");
+  lines.push("| `paradigm scan ui` | Screenshot of running app |");
+  lines.push("| `paradigm scan design` | Mockup - gap analysis |");
+  lines.push("| `paradigm scan error` | Error screenshot |");
+  lines.push("");
+  lines.push("See `.paradigm/specs/scan.md` for full protocol.");
+  lines.push("");
+  return lines.join("\n");
+}
+function generateConventions(config) {
+  if (!config.conventions?.length) {
+    return "";
+  }
+  const lines = [];
+  lines.push("## Conventions");
+  lines.push("");
+  for (const convention of config.conventions) {
+    lines.push(`- ${convention}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function generateUpdateRules(config) {
+  if (!config["agent-guidelines"]?.["update-rules"]?.length) {
+    return "";
+  }
+  const lines = [];
+  lines.push("## When to Update Paradigm Files");
+  lines.push("");
+  for (const rule of config["agent-guidelines"]["update-rules"]) {
+    lines.push(`- ${rule}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function generateCommandsReference() {
+  const lines = [];
+  lines.push("## Paradigm Commands");
+  lines.push("");
+  lines.push("| Command | Description |");
+  lines.push("|---------|-------------|");
+  lines.push("| `paradigm init` | Initialize Paradigm in a project |");
+  lines.push("| `paradigm sync` | Regenerate IDE instruction files |");
+  lines.push("| `paradigm index` | Generate scan index |");
+  lines.push("| `paradigm doctor` | Health check |");
+  lines.push("| `paradigm status` | Show project status |");
+  lines.push("| `paradigm watch` | Auto-sync on changes |");
+  lines.push("");
+  lines.push("See `.paradigm/docs/commands.md` for full reference.");
+  lines.push("");
+  return lines.join("\n");
+}
+function generateNavigationSection(_config) {
+  const lines = [];
+  lines.push("## Paradigm Navigation");
+  lines.push("");
+  lines.push("Before exploring this codebase:");
+  lines.push("");
+  lines.push("1. Read `.paradigm/navigator.yaml` for structure map");
+  lines.push("2. Query by symbol - lookup paths directly");
+  lines.push("3. Respect skip patterns (node_modules, dist, etc.)");
+  lines.push("");
+  lines.push("### Exploration Protocol");
+  lines.push("");
+  lines.push("**INSTEAD OF:** Broad exploration (expensive token usage)");
+  lines.push("");
+  lines.push("**DO THIS:**");
+  lines.push("1. Read `.paradigm/navigator.yaml` for structure map");
+  lines.push("2. Find relevant symbol \u2192 go to path");
+  lines.push("3. Read only needed files");
+  lines.push("");
+  lines.push("### Task Recipes");
+  lines.push("");
+  lines.push("**Adding a feature:**");
+  lines.push("1. Check `navigator.yaml` \u2192 `structure.features.paths`");
+  lines.push("2. Read existing feature as template");
+  lines.push("3. Create in same location");
+  lines.push("");
+  lines.push("**Modifying a component:**");
+  lines.push("1. Look up symbol in `navigator.yaml` \u2192 `symbols`");
+  lines.push("2. Go directly to the path");
+  lines.push("3. Check `paradigm_ripple` for impact");
+  lines.push("");
+  lines.push("**Using MCP Tools:**");
+  lines.push('- `paradigm_navigate({ intent: "find", target: "#checkout" })` - locate symbol');
+  lines.push('- `paradigm_navigate({ intent: "explore", target: "auth" })` - browse area');
+  lines.push('- `paradigm_navigate({ intent: "context", task: "add login" })` - task context');
+  lines.push("");
+  lines.push("### PM Governance (Before/After Tasks)");
+  lines.push("");
+  lines.push("| When | Tool | Purpose |");
+  lines.push("|------|------|---------|");
+  lines.push("| Starting any task | `paradigm_pm_preflight` | Get compliance plan, affected symbols, required checks |");
+  lines.push("| Finishing any task | `paradigm_pm_postflight` | Check for violations: missing .purpose, missing gates |");
+  lines.push("");
+  return lines.join("\n");
+}
+function generateTerminalGuidance() {
+  const platform3 = os.platform();
+  const isWindows = platform3 === "win32";
+  const lines = [];
+  lines.push("## Terminal Syntax");
+  lines.push("");
+  if (isWindows) {
+    lines.push("This project runs on **Windows**. Use appropriate syntax:");
+    lines.push("");
+    lines.push("| Operation | Windows Syntax |");
+    lines.push("|-----------|----------------|");
+    lines.push("| Chain commands | `cmd1 ; cmd2` or `cmd1 && cmd2` (PowerShell) |");
+    lines.push("| Path separator | `\\` (backslash) |");
+    lines.push("| Environment vars | `$env:VAR` (PowerShell) or `%VAR%` (CMD) |");
+    lines.push("| Null device | `$null` (PowerShell) or `NUL` (CMD) |");
+    lines.push("| List files | `dir` or `Get-ChildItem` |");
+    lines.push("| Remove files | `del` or `Remove-Item` |");
+    lines.push("");
+    lines.push("**IMPORTANT:** Do NOT use Unix-style commands like `rm`, `cat`, `grep` directly.");
+  } else {
+    const osName = platform3 === "darwin" ? "macOS" : "Linux";
+    lines.push(`This project runs on **${osName}**. Use appropriate syntax:`);
+    lines.push("");
+    lines.push("| Operation | Unix Syntax |");
+    lines.push("|-----------|-------------|");
+    lines.push("| Chain commands | `cmd1 && cmd2` (stop on error) or `cmd1 ; cmd2` (always continue) |");
+    lines.push("| Path separator | `/` (forward slash) |");
+    lines.push("| Environment vars | `$VAR` or `${VAR}` |");
+    lines.push("| Null device | `/dev/null` |");
+    lines.push("| List files | `ls` |");
+    lines.push("| Remove files | `rm` |");
+    lines.push("");
+    lines.push("**IMPORTANT:** Do NOT use Windows-style commands like `dir`, `del`, or `%VAR%`.");
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function generateCommitConvention() {
+  const lines = [];
+  lines.push("## Commit Messages");
+  lines.push("");
+  lines.push("Use v2 symbols in commits for history tracking:");
+  lines.push("");
+  lines.push("### Format");
+  lines.push("```");
+  lines.push("type(#primary-symbol): short description");
+  lines.push("");
+  lines.push("- Detail with #component references");
+  lines.push("- Gate changes: ^gate-name");
+  lines.push("- Signals emitted: !signal-name");
+  lines.push("");
+  lines.push("Symbols: #symbol-a, #symbol-b, !signal-c");
+  lines.push("```");
+  lines.push("");
+  lines.push("### Convention");
+  lines.push("- **Subject**: `type(#symbol): description` \u2014 primary symbol in parens");
+  lines.push("- **Body**: Reference affected symbols with prefixes (# $ ^ ! ~)");
+  lines.push("- **Trailer**: `Symbols: #a, #b, !c` \u2014 machine-readable list of ALL affected symbols");
+  lines.push("- The `Symbols:` trailer is parsed by the post-commit hook for automatic history capture");
+  lines.push("");
+  lines.push("### Examples");
+  lines.push("```");
+  lines.push("feat(#payment-form): add Apple Pay support");
+  lines.push("");
+  lines.push("- Add #apple-pay-button component");
+  lines.push("- Update $checkout-flow with new payment step");
+  lines.push("- Emit !payment-method-added signal");
+  lines.push("- Gate: ^authenticated required");
+  lines.push("");
+  lines.push("Symbols: #payment-form, #apple-pay-button, $checkout-flow, !payment-method-added");
+  lines.push("```");
+  lines.push("");
+  return lines.join("\n");
+}
+function generateMcpToolReference() {
+  const lines = [];
+  lines.push("## MCP Tools");
+  lines.push("");
+  lines.push("Paradigm provides MCP tools for token-efficient, always-fresh data. Prefer these over reading files directly.");
+  lines.push("");
+  lines.push("| Tool | Description | When to Use |");
+  lines.push("|------|-------------|-------------|");
+  lines.push("| `paradigm_status` | Project overview and symbol counts | Starting a session |");
+  lines.push("| `paradigm_search` | Find symbols by name, description, or tags | Looking for symbols |");
+  lines.push("| `paradigm_navigate` | Find code locations, explore areas, get task context | Locating code |");
+  lines.push("| `paradigm_ripple` | Dependency and impact analysis | Before modifying symbols |");
+  lines.push("| `paradigm_related` | Direct relationships for a symbol | Understanding connections |");
+  lines.push("| `paradigm_gates_for_route` | Suggest gates for an API endpoint | Adding API routes |");
+  lines.push("| `paradigm_wisdom_context` | Team preferences and antipatterns | Before implementing |");
+  lines.push("| `paradigm_history_fragility` | Stability warnings for symbols | Before modifying fragile areas |");
+  lines.push("| `paradigm_flow_validate` | Validate flow definitions | Before/after implementing flows |");
+  lines.push("| `paradigm_flows_affected` | Flows impacted by symbol changes | After modifying symbols |");
+  lines.push("| `paradigm_test_fixtures` | Get test data for validation | Writing tests |");
+  lines.push("| `paradigm_orchestrate_inline` | Multi-agent task planning | Complex tasks (3+ files) |");
+  lines.push("| `paradigm_pm_preflight` | Pre-task compliance check | Starting any task |");
+  lines.push("| `paradigm_pm_postflight` | Post-task violation detection | Finishing any task |");
+  lines.push("| `paradigm_session_recover` | Load previous session breadcrumbs | Starting a new session |");
+  lines.push("| `paradigm_context_check` | Check context window usage | Every 10-15 tool calls |");
+  lines.push("| `paradigm_handoff_prepare` | Prepare session handoff summary | When context is high |");
+  lines.push("| `paradigm_reindex` | Rebuild static index files | After modifying .purpose files |");
+  lines.push("| `paradigm_session_checkpoint` | Save cognitive-transition checkpoint | Phase transitions |");
+  lines.push("| `paradigm_session_stats` | Current session token usage | Checking budget |");
+  lines.push("");
+  lines.push("**Rule**: Use MCP tools for discovery and validation, file reads for implementation.");
+  lines.push("");
+  return lines.join("\n");
+}
+function generateWorkflowProtocol() {
+  const lines = [];
+  lines.push("## Workflow Protocol");
+  lines.push("");
+  lines.push("### Before Each Task");
+  lines.push("");
+  lines.push("1. **Preflight**: Call `paradigm_pm_preflight` with your task description");
+  lines.push("   - Returns affected symbols, ripple analysis, required agents");
+  lines.push("2. **Impact check**: Call `paradigm_ripple` for any symbols you'll modify");
+  lines.push("3. **Gate check**: Call `paradigm_gates_for_route` before adding API endpoints");
+  lines.push('4. **Complex tasks** (3+ files, security + implementation): Call `paradigm_orchestrate_inline` with mode="plan"');
+  lines.push("");
+  lines.push("### After Each Task");
+  lines.push("");
+  lines.push("1. **Postflight**: Call `paradigm_pm_postflight` with modified files and symbols");
+  lines.push("   - Checks for missing .purpose files, unregistered routes, uncaptured wisdom");
+  lines.push("2. **Reindex**: Call `paradigm_reindex` to rebuild static index files");
+  lines.push("3. **Validate flows**: Call `paradigm_flow_validate` if you touched flow-related symbols");
+  lines.push("");
+  return lines.join("\n");
+}
+function generateHandoffProtocol() {
+  const lines = [];
+  lines.push("## Session Recovery & Handoff");
+  lines.push("");
+  lines.push("### Session Start (EVERY new session)");
+  lines.push("");
+  lines.push("Call `paradigm_session_recover` to load previous session breadcrumbs.");
+  lines.push("Returns: symbols modified, files explored, recent actions, and suggestions.");
+  lines.push("");
+  lines.push("### Context Monitoring");
+  lines.push("");
+  lines.push("Call `paradigm_context_check` every 10-15 tool calls to track context usage.");
+  lines.push("");
+  lines.push("| Usage | Recommendation | Action |");
+  lines.push("|-------|----------------|--------|");
+  lines.push("| <50% | continue | Keep working |");
+  lines.push("| 50-70% | consider-handoff | Plan a stopping point |");
+  lines.push("| 70-85% | handoff-recommended | Prepare handoff soon |");
+  lines.push("| >85% | handoff-urgent | Handoff after current task |");
+  lines.push("");
+  lines.push("### Handoff Process");
+  lines.push("");
+  lines.push("1. Call `paradigm_handoff_prepare` with summary, next steps, and target agent");
+  lines.push('2. User runs: `paradigm team handoff --to <agent> --summary "..."`');
+  lines.push("3. New session accepts: `paradigm team accept <handoff-id>`");
+  lines.push("");
+  return lines.join("\n");
+}
+function generateCheckpointProtocol() {
+  const lines = [];
+  lines.push("## Session Checkpoints");
+  lines.push("");
+  lines.push("**Auto-recovery**: Recovery data is automatically surfaced on your first Paradigm tool call \u2014 no action needed to receive it.");
+  lines.push("");
+  lines.push("Save checkpoints when transitioning between workflow phases to enable crash recovery:");
+  lines.push("");
+  lines.push("| Phase | Trigger | What to Capture |");
+  lines.push("|-------|---------|-----------------|");
+  lines.push("| `planning` | After reading requirements / before coding | Plan, approach, key decisions |");
+  lines.push("| `implementing` | After starting code changes | Modified files, symbols touched, decisions made |");
+  lines.push("| `validating` | After implementation, before tests/review | All modified files, test plan |");
+  lines.push("| `complete` | Task finished | Summary, final file list |");
+  lines.push("");
+  lines.push("### Usage");
+  lines.push("");
+  lines.push("```");
+  lines.push("paradigm_session_checkpoint({");
+  lines.push('  phase: "implementing",');
+  lines.push('  context: "Adding JWT auth middleware to /api/projects routes",');
+  lines.push('  modifiedFiles: ["src/middleware/auth.ts", "src/routes/projects.ts"],');
+  lines.push('  symbolsTouched: ["^authenticated", "#project-routes"],');
+  lines.push('  decisions: ["Using RS256 for JWT signing", "Storing refresh tokens in httpOnly cookies"]');
+  lines.push("})");
+  lines.push("```");
+  lines.push("");
+  lines.push("Keep it lightweight: `phase` + `context` are required, everything else is optional.");
+  lines.push("");
+  return lines.join("\n");
+}
+function generateFooter() {
+  const lines = [];
+  lines.push("---");
+  lines.push("");
+  lines.push("## Reference Files");
+  lines.push("");
+  lines.push("- `.paradigm/specs/symbols.md` - Symbol system reference");
+  lines.push("- `.paradigm/specs/logger.md` - Logging specification");
+  lines.push("- `.paradigm/specs/scan.md` - Scan protocol");
+  lines.push("- `.paradigm/docs/commands.md` - CLI reference");
+  lines.push("- `.paradigm/docs/patterns.md` - Coding patterns");
+  lines.push("- `.paradigm/docs/troubleshooting.md` - Common issues");
+  lines.push("- `.paradigm/prompts/` - Pre-written task prompts");
+  lines.push("");
+  lines.push("*Generated by Paradigm. Run `paradigm sync` to regenerate.*");
+  return lines.join("\n");
+}
+
+// src/core/ide-adapters/cursor.ts
+function frontmatter(description, options = {}) {
+  const lines = ["---", `description: ${description}`];
+  if (options.globs) {
+    lines.push(`globs: ${options.globs}`);
+  }
+  if (options.alwaysApply !== void 0) {
+    lines.push(`alwaysApply: ${options.alwaysApply}`);
+  }
+  lines.push("---", "");
+  return lines.join("\n");
+}
+var CursorAdapter = class {
+  name = "cursor";
+  displayName = "Cursor";
+  outputPath = ".cursor/rules";
+  multiFile = true;
+  detect(rootDir) {
+    if (fs.existsSync(path.join(rootDir, ".cursor"))) {
+      return true;
+    }
+    if (fs.existsSync(path.join(rootDir, ".cursorrules"))) {
+      return true;
+    }
+    if (fs.existsSync(path.join(rootDir, ".vscode"))) {
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Generate single file content (legacy fallback)
+   */
+  generate(files) {
+    const generatedFiles = this.generateFiles(files);
+    return generatedFiles.map((f) => `# ${f.path}
+
+${f.content}`).join("\n\n---\n\n");
+  }
+  /**
+   * Generate multiple .mdc files for the modern Cursor format
+   */
+  generateFiles(files, rootDir) {
+    const { config, projectName } = files;
+    const generatedFiles = [];
+    generatedFiles.push({
+      path: "paradigm-core.mdc",
+      content: this.generateCoreRules(projectName, config)
+    });
+    generatedFiles.push({
+      path: "paradigm-symbols.mdc",
+      content: this.generateSymbolRules(config)
+    });
+    const loggingContent = generateLoggingRules(config);
+    if (loggingContent) {
+      generatedFiles.push({
+        path: "paradigm-logging.mdc",
+        content: this.generateLoggingMdc(config)
+      });
+    }
+    generatedFiles.push({
+      path: "paradigm-purpose.mdc",
+      content: this.generatePurposeMdc()
+    });
+    generatedFiles.push({
+      path: "paradigm-portal.mdc",
+      content: this.generatePortalMdc()
+    });
+    generatedFiles.push({
+      path: "paradigm-commands.mdc",
+      content: this.generateCommandsMdc()
+    });
+    generatedFiles.push({
+      path: "paradigm-conventions.mdc",
+      content: this.generateConventionsMdc(config)
+    });
+    generatedFiles.push({
+      path: "paradigm-agent-hints.mdc",
+      content: this.generateAgentHintsMdc()
+    });
+    generatedFiles.push({
+      path: "paradigm-navigator.mdc",
+      content: this.generateNavigatorMdc()
+    });
+    generatedFiles.push({
+      path: "paradigm-context.mdc",
+      content: this.generateContextMdc()
+    });
+    const agentsManifest = rootDir ? this.loadAgentsManifest(rootDir) : null;
+    generatedFiles.push({
+      path: "paradigm-orchestration.mdc",
+      content: this.generateOrchestrationMdc(agentsManifest)
+    });
+    generatedFiles.push({
+      path: "paradigm-flows.mdc",
+      content: this.generateFlowsMdc()
+    });
+    generatedFiles.push({
+      path: "paradigm-commits.mdc",
+      content: this.generateCommitsMdc()
+    });
+    return generatedFiles;
+  }
+  /**
+   * Core rules - project overview and fundamentals
+   */
+  generateCoreRules(projectName, config) {
+    const overview = generateOverview(config);
+    return frontmatter("Paradigm core rules - project overview and fundamentals", { alwaysApply: true }) + `# Paradigm - ${projectName}
+
+` + overview + "\n\n" + generateUpdateRules(config);
+  }
+  /**
+   * Symbol system rules
+   */
+  generateSymbolRules(config) {
+    return frontmatter("Paradigm symbol system - understand #components, $flows, ^gates, !signals, ~aspects", { alwaysApply: true }) + generateSymbolSystem(config);
+  }
+  /**
+   * Logging rules for TypeScript/JavaScript
+   */
+  generateLoggingMdc(config) {
+    return frontmatter("Paradigm logger usage for TypeScript/JavaScript code", {
+      globs: "**/*.{ts,tsx,js,jsx}",
+      alwaysApply: false
+    }) + generateLoggingRules(config);
+  }
+  /**
+   * Purpose file conventions
+   */
+  generatePurposeMdc() {
+    return frontmatter("Purpose file conventions - .purpose file format and usage", {
+      globs: "**/.purpose",
+      alwaysApply: false
+    }) + `# Purpose Files
+
+Purpose files (\`.purpose\`) define the context for directories.
+
+## Format
+
+\`\`\`yaml
+# Directory context
+description: What this directory contains and why
+
+# Components (# symbol) \u2014 all documented code units
+components:
+  component-name:
+    description: What this component does
+    tags: [feature]                # Classification via tag bank
+    gates: [^gate1, ^gate2]       # Required gates
+    signals: [!signal1]           # Events emitted
+    used-by: [#other-component]
+\`\`\`
+
+## Symbol References (v2)
+
+- Reference components: \`#component-name\`
+- Reference flows: \`$flow-name\`
+- Reference gates: \`^gate-name\`
+- Reference signals: \`!signal-name\`
+- Reference aspects: \`~aspect-name\`
+`;
+  }
+  /**
+   * Portal rules
+   */
+  generatePortalMdc() {
+    return frontmatter("Portal (gate) configuration rules", {
+      globs: "**/portal.yaml",
+      alwaysApply: false
+    }) + `# Portal Configuration
+
+Portal files (\`portal.yaml\`) define authorization topology.
+
+## Format
+
+\`\`\`yaml
+version: "1.0"
+
+gates:
+  gate-name:
+    description: What this gate protects
+    locks:
+      - id: lock-id
+        description: Requirement description
+        keys:
+          - expression: "user.authenticated"
+            description: User must be logged in
+    prizes:
+      - id: prize-id
+        oneTime: true
+        metadata:
+          event: "gate_passed"
+
+flows:
+  flow-name:
+    description: User journey
+    gates: [gate1, gate2, gate3]
+\`\`\`
+
+## Portal Validation
+
+Use the Portal Validator for authorization checks:
+
+\`\`\`typescript
+import { portal } from '@a-company/portal-sdk/validator';
+
+const gate = portal.check('^gate-name')
+  .requires('requirement description')
+  .context({ userId, role });
+
+if (!condition) {
+  gate.deny('Reason for denial');
+  return redirect('/unauthorized');
+}
+
+gate.allow('Access granted');
+\`\`\`
+`;
+  }
+  /**
+   * Commands reference
+   */
+  generateCommandsMdc() {
+    return frontmatter("Paradigm CLI commands reference", { alwaysApply: false }) + generateCommandsReference();
+  }
+  /**
+   * Conventions
+   */
+  generateConventionsMdc(config) {
+    return frontmatter("Paradigm coding conventions", {
+      globs: "**/*.{ts,tsx,js,jsx}",
+      alwaysApply: false
+    }) + generateConventions(config);
+  }
+  /**
+   * Agent Hints - when to query CLI commands
+   */
+  generateAgentHintsMdc() {
+    return frontmatter("Paradigm CLI queries for AI agents - prefer CLI over reading large files", {
+      alwaysApply: true
+    }) + `# Agent CLI Queries (Token-Efficient)
+
+Instead of reading large context files, query Paradigm CLI on-demand for fresh, precise data.
+
+## When to Query
+
+| Before doing this... | Run this command |
+|---------------------|------------------|
+| Modifying a symbol | \`paradigm ripple #symbol --json\` |
+| Debugging an error | \`paradigm echo ERROR_CODE --json\` |
+| Starting a session | \`paradigm thread --json\` |
+| Understanding relationships | \`paradigm constellation\` |
+| Getting oriented | \`paradigm beacon --json\` |
+
+## Query Patterns
+
+### Before Changing Code
+
+\`\`\`bash
+# See what depends on what you're changing
+paradigm ripple #checkout --json
+
+# Output includes: upstream deps, downstream effects, flow membership
+\`\`\`
+
+### When Debugging
+
+\`\`\`bash
+# Look up error context
+paradigm echo AUTH_REQUIRED --json
+
+# Then check ripple effects of the related symbol
+paradigm ripple ^authenticated --json
+\`\`\`
+
+### Starting Work
+
+\`\`\`bash
+# Check previous session context
+paradigm thread --json
+
+# Quick orientation
+paradigm beacon --json
+\`\`\`
+
+### Querying Constellation
+
+\`\`\`bash
+# Get specific symbol
+jq '.stars["#checkout"]' .paradigm/constellation.json
+
+# Find what requires a gate
+jq '[.stars | to_entries[] | select(.value.gates[]? == "^authenticated") | .key]' .paradigm/constellation.json
+
+# List all flows
+jq '.orbits | keys' .paradigm/constellation.json
+\`\`\`
+
+## Benefits
+
+- **Fresh data**: Always current, not stale from file generation
+- **Precise**: Only get the data you need
+- **Token-efficient**: ~100 tokens per query vs ~2000 upfront
+`;
+  }
+  /**
+   * Navigator rules - AI exploration optimization
+   */
+  generateNavigatorMdc() {
+    return frontmatter("Paradigm Navigator - efficient codebase exploration", {
+      alwaysApply: true
+    }) + `# Paradigm Navigator
+
+## Exploration Protocol
+
+Before exploring this codebase:
+
+1. **Read \`.paradigm/navigator.yaml\`** for the structure map
+2. **Query by symbol** - lookup paths directly from the symbols map
+3. **Respect skip patterns** - avoid node_modules, dist, .git, etc.
+
+## Navigation Strategy
+
+**INSTEAD OF:** Broad exploration (expensive token usage)
+
+**DO THIS:**
+1. Read \`.paradigm/navigator.yaml\` for project structure
+2. Find relevant symbol \u2192 go directly to path
+3. Read only needed files
+
+## Using MCP Navigate Tool
+
+\`\`\`
+# Find a specific symbol
+paradigm_navigate({ intent: "find", target: "#checkout" })
+
+# Explore an area
+paradigm_navigate({ intent: "explore", target: "authentication" })
+
+# Get context for a task
+paradigm_navigate({ intent: "context", task: "add Apple Pay" })
+\`\`\`
+
+## Task Recipes
+
+### Adding a Feature
+1. Check \`navigator.yaml\` \u2192 \`structure.features.paths\`
+2. Read an existing feature as template
+3. Create in the same location
+
+### Modifying a Component
+1. Look up symbol in \`navigator.yaml\` \u2192 \`symbols\`
+2. Go directly to the path
+3. Use \`paradigm_ripple\` to check impact
+
+### Understanding Dependencies
+1. Use \`paradigm_navigate({ intent: "context", task: "..." })\`
+2. Read suggested files in order
+3. Skip patterns in the \`skip\` array
+
+## Key Files (Quick Reference)
+
+Always available in \`navigator.yaml\`:
+- \`key_files.config\` - Configuration files
+- \`key_files.entry\` - Entry points
+- \`key_files.types\` - Type definitions
+`;
+  }
+  /**
+   * Context monitoring rules - session management and handoff
+   */
+  generateContextMdc() {
+    return frontmatter("Session recovery and handoff - call paradigm_session_recover at session start, paradigm_context_check periodically during long sessions, paradigm_handoff_prepare when context is high.") + `# Context Monitoring Protocol
+
+## Session Start (EVERY new session)
+
+Call \`paradigm_session_recover\` to load previous session breadcrumbs.
+Returns: symbols modified, files explored, recent actions, and suggestions.
+
+## Periodic Checks
+
+**Every 10-15 tool calls** (or when user asks about context), call:
+
+\`\`\`
+paradigm_context_check()
+\`\`\`
+
+This returns a recommendation: \`continue\`, \`consider-handoff\`, \`handoff-recommended\`, or \`handoff-urgent\`.
+
+## When to Handoff
+
+| Usage | Recommendation | Action |
+|-------|----------------|--------|
+| <50% | continue | Keep working |
+| 50-70% | consider-handoff | Plan stopping point |
+| 70-85% | handoff-recommended | Prepare handoff soon |
+| >85% | handoff-urgent | Handoff after current task |
+
+## When Recommendation is NOT "continue"
+
+1. **Inform user**: "Context usage is at ~X%. Recommend handoff soon."
+2. **Offer to prepare**: Ask if user wants handoff summary
+3. **If urgent (>85%)**: Prioritize completing current task, then handoff
+
+## Handoff Process
+
+1. Call \`paradigm_handoff_prepare\` with:
+   - Summary of work completed
+   - List of next steps
+   - Target agent role
+
+2. User runs CLI command:
+   \`\`\`bash
+   paradigm team handoff --to <agent> --summary "..."
+   \`\`\`
+
+3. New session accepts:
+   \`\`\`bash
+   paradigm team accept <handoff-id>
+   \`\`\`
+
+## Session Stats
+
+Get current stats anytime:
+\`\`\`
+paradigm_session_stats()
+\`\`\`
+
+${generateCheckpointProtocol()}`;
+  }
+  /**
+   * Load agents manifest from .paradigm/agents.yaml
+   */
+  loadAgentsManifest(rootDir) {
+    const agentsPath = path.join(rootDir, ".paradigm", "agents.yaml");
+    if (!fs.existsSync(agentsPath)) {
+      return null;
+    }
+    try {
+      const content = fs.readFileSync(agentsPath, "utf-8");
+      return yaml.load(content);
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Orchestration protocol rules - multi-agent workflow
+   */
+  generateOrchestrationMdc(agentsManifest) {
+    let agentList = "(Run `paradigm team init` to configure agents)";
+    if (agentsManifest) {
+      const agents = agentsManifest.agents || agentsManifest.roles;
+      if (agents && typeof agents === "object") {
+        try {
+          agentList = Object.entries(agents).map(([name, agent]) => {
+            const roleText = agent.role || agent.description || "";
+            const roleFirstLine = roleText.split("\n")[0].trim() || name;
+            const writes = agent.focus?.writes;
+            const writesStr = Array.isArray(writes) ? writes.join(", ") : "any";
+            const model = agent.defaultModel || "sonnet";
+            return `- **${name}** (${model}): ${roleFirstLine} (writes: ${writesStr})`;
+          }).join("\n");
+        } catch {
+        }
+      }
+    }
+    const platform3 = os2.platform();
+    const isWindows = platform3 === "win32";
+    const terminalGuidance = isWindows ? `## Terminal Syntax (Windows)
+
+This project runs on **Windows**. Use appropriate syntax:
+
+| Operation | Windows Syntax |
+|-----------|----------------|
+| Chain commands | \`cmd1 ; cmd2\` or \`cmd1 && cmd2\` (PowerShell) |
+| Path separator | \`\\\` (backslash) |
+| Environment vars | \`$env:VAR\` (PowerShell) or \`%VAR%\` (CMD) |
+| Null device | \`$null\` (PowerShell) or \`NUL\` (CMD) |
+| List files | \`dir\` or \`Get-ChildItem\` |
+| Remove files | \`del\` or \`Remove-Item\` |
+
+**IMPORTANT:** Do NOT use Unix-style commands like \`rm\`, \`cat\`, \`grep\` directly.` : `## Terminal Syntax (${platform3 === "darwin" ? "macOS" : "Linux"})
+
+This project runs on **${platform3 === "darwin" ? "macOS" : "Linux"}**. Use appropriate syntax:
+
+| Operation | Unix Syntax |
+|-----------|-------------|
+| Chain commands | \`cmd1 && cmd2\` (stop on error) or \`cmd1 ; cmd2\` (always continue) |
+| Path separator | \`/\` (forward slash) |
+| Environment vars | \`$VAR\` or \`\${VAR}\` |
+| Null device | \`/dev/null\` |
+| List files | \`ls\` |
+| Remove files | \`rm\` |
+
+**IMPORTANT:** Do NOT use Windows-style commands like \`dir\`, \`del\`, or \`%VAR%\`.`;
+    return frontmatter("Multi-agent orchestration - use when task affects 3+ files, involves security AND implementation, or spans multiple features. Call paradigm_orchestrate_inline for planning.") + `# Paradigm Orchestration Protocol
+
+${terminalGuidance}
+
+## CRITICAL: When to Use Orchestration
+
+**ALWAYS call \`paradigm_orchestrate_inline\` FIRST when:**
+- Task affects 3+ files
+- Task involves security/auth AND implementation
+- Task mentions multiple features (#symbols)
+- Building a new feature end-to-end
+- User explicitly requests multi-agent workflow
+
+## Workflow
+
+1. **Plan first:** \`paradigm_orchestrate_inline({ task: "...", mode: "plan" })\`
+   - Review suggested agents and estimated tokens
+   - Check if parallel execution is possible
+
+2. **Execute:** \`paradigm_orchestrate_inline({ task: "...", mode: "execute" })\`
+   - Get full prompts and execution strategy
+   - Note which stages can run in parallel
+
+3. **Follow the plan sequentially:**
+   - For each stage/agent, adopt that role's prompt and focus areas
+   - Stage 0 (architect): Design and spec only \u2014 do NOT write implementation code
+   - Stage 1 (builder): Implement following the architect's design
+   - Stage 2 (tester/reviewer): Verify and test the implementation
+   - Pass context between phases as if handing off to a teammate
+
+4. **For true parallel execution**, suggest user runs:
+   \`paradigm team orchestrate "task description"\`
+
+5. **Record history:** \`paradigm_history_record({ type: "implement", symbols: [...], description: "..." })\`
+
+## Available Agents
+
+${agentList}
+
+## Red Flags - STOP and Orchestrate
+
+If you find yourself:
+- Implementing 5+ files without planning \u2192 STOP, call orchestrate
+- Adding auth without security review \u2192 STOP, involve security agent
+- Writing code without specs \u2192 STOP, involve architect first
+- Making cross-cutting changes \u2192 STOP, plan the stages
+
+## DO NOT Skip Orchestration
+
+Complex tasks need specialist agents. One agent trying to do everything leads to:
+- Missed security gates
+- Inconsistent patterns
+- Poor test coverage
+- Context overflow
+
+## CLI Shortcut
+
+You can also suggest agents via CLI:
+\`\`\`bash
+paradigm team agents suggest "Add user authentication with JWT"
+\`\`\`
+`;
+  }
+  /**
+   * Flow-First Development rules
+   */
+  generateFlowsMdc() {
+    return frontmatter("Flow-first development - apply when implementing features spanning multiple steps, requiring gates, or emitting signals. Define $flows before coding.") + `# Flow-First Development
+
+## What are Flows?
+
+Flows ($symbols) are composable sequences of gates, actions, and signals that represent the "happy path" for a feature.
+
+\`\`\`yaml
+# .paradigm/flows.yaml
+flows:
+  $task-creation:
+    name: Task Creation Flow
+    description: Complete flow for creating a new task
+    trigger: "POST /api/tasks"
+    steps:
+      - type: gate
+        symbol: ^authenticated
+        description: User must be logged in
+      - type: gate
+        symbol: ^project-member
+        description: User must be member of target project
+      - type: action
+        symbol: "#validate-task-input"
+        description: Validate task data
+      - type: action
+        symbol: "#create-task"
+        description: Create task in database
+      - type: signal
+        symbol: "!task-created"
+        description: Emit success event
+    successSignal: "!task-created"
+    failureSignal: "!task-creation-failed"
+\`\`\`
+
+## When to Define Flows
+
+**BEFORE implementing features that:**
+- Span multiple steps or components
+- Require authorization gates
+- Emit signals/events
+- Integrate with external systems
+
+## Flow-First Protocol
+
+1. **Define the flow first** in \`.paradigm/flows.yaml\`:
+   - What gates must pass?
+   - What actions occur in what order?
+   - What signals are emitted?
+
+2. **Validate before implementing:**
+   \`\`\`
+   paradigm_flow_validate({ flowId: "$task-creation" })
+   \`\`\`
+   - Ensures all gates are declared in portal.yaml
+   - Checks for missing symbols
+
+3. **Implement following the flow:**
+   - Each step becomes a clear implementation target
+   - Gates \u2192 middleware/authorization checks
+   - Actions \u2192 business logic functions
+   - Signals \u2192 event emitters/hooks
+
+## Flow Validation
+
+Call \`paradigm_flow_validate\` to check flows:
+
+\`\`\`
+// Validate specific flow
+paradigm_flow_validate({ flowId: "$task-creation" })
+
+// Validate all flows
+paradigm_flow_validate({ checkImplementation: true })
+\`\`\`
+
+**What gets checked:**
+- All ^gates are declared in portal.yaml
+- All #actions reference existing components
+- All !signals are documented
+
+## Benefits
+
+1. **Clear implementation targets** - Each flow step is a discrete unit
+2. **Gate coverage** - All authorization points are explicit
+3. **Testability** - Flows can be tested step-by-step
+4. **Documentation** - The flow IS the documentation
+5. **Parallel work** - Different team members can implement different steps
+
+## Red Flags
+
+**STOP and define a flow if:**
+- You're implementing a "happy path" without documenting it
+- You're adding gates without knowing the full sequence
+- You're emitting signals without knowing what listens
+- You're modifying existing flows without checking validation
+
+## MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| \`paradigm_flow_validate\` | Validate flow definitions |
+| \`paradigm_flows_affected\` | Check which flows are impacted by symbol changes |
+
+## CLI Commands
+
+\`\`\`bash
+# Validate all flows
+paradigm flow validate --all
+
+# Validate specific flow
+paradigm flow validate $task-creation
+\`\`\`
+`;
+  }
+  /**
+   * Commit convention rules
+   */
+  generateCommitsMdc() {
+    return frontmatter("Paradigm commit conventions with Symbols: trailer - apply when creating git commits for history tracking.") + generateCommitConvention();
+  }
+  /**
+   * Generate MCP configuration for Cursor
+   */
+  generateMcpConfig(rootDir) {
+    return {
+      mcpServers: {
+        paradigm: {
+          command: "paradigm-mcp",
+          args: ["."],
+          cwd: rootDir
+        }
+      }
+    };
+  }
+};
+var cursorAdapter = new CursorAdapter();
+
+// src/core/ide-adapters/copilot.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+function frontmatter2(applyTo, excludeAgent) {
+  if (!applyTo && !excludeAgent) {
+    return "";
+  }
+  const lines = ["---"];
+  if (applyTo) {
+    lines.push(`applyTo: "${applyTo}"`);
+  }
+  if (excludeAgent) {
+    lines.push(`excludeAgent: "${excludeAgent}"`);
+  }
+  lines.push("---", "");
+  return lines.join("\n");
+}
+var CopilotAdapter = class {
+  name = "copilot";
+  displayName = "GitHub Copilot";
+  outputPath = ".github/instructions";
+  multiFile = true;
+  detect(rootDir) {
+    if (fs2.existsSync(path2.join(rootDir, ".github", "instructions"))) {
+      return true;
+    }
+    if (fs2.existsSync(path2.join(rootDir, ".github", "copilot-instructions.md"))) {
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Generate single file content (legacy fallback)
+   */
+  generate(files) {
+    const generatedFiles = this.generateFiles(files);
+    return generatedFiles.map((f) => `# ${f.path}
+
+${f.content}`).join("\n\n---\n\n");
+  }
+  /**
+   * Generate multiple .instructions.md files for the modern Copilot format
+   */
+  generateFiles(files) {
+    const { config, projectName } = files;
+    const generatedFiles = [];
+    generatedFiles.push({
+      path: "../copilot-instructions.md",
+      // Goes to .github/copilot-instructions.md
+      content: this.generateCoreInstructions(projectName, config)
+    });
+    generatedFiles.push({
+      path: "paradigm-symbols.instructions.md",
+      content: this.generateSymbolInstructions(config)
+    });
+    const loggingContent = generateLoggingRules(config);
+    if (loggingContent) {
+      generatedFiles.push({
+        path: "paradigm-logging.instructions.md",
+        content: this.generateLoggingInstructions(config)
+      });
+    }
+    generatedFiles.push({
+      path: "paradigm-purpose.instructions.md",
+      content: this.generatePurposeInstructions()
+    });
+    generatedFiles.push({
+      path: "paradigm-portal.instructions.md",
+      content: this.generatePortalInstructions()
+    });
+    generatedFiles.push({
+      path: "paradigm-conventions.instructions.md",
+      content: this.generateConventionsInstructions(config)
+    });
+    generatedFiles.push({
+      path: "paradigm-commands.instructions.md",
+      content: this.generateCommandsInstructions()
+    });
+    generatedFiles.push({
+      path: "paradigm-agent-hints.instructions.md",
+      content: this.generateAgentHintsInstructions()
+    });
+    generatedFiles.push({
+      path: "paradigm-commits.instructions.md",
+      content: this.generateCommitsInstructions()
+    });
+    return generatedFiles;
+  }
+  /**
+   * Core instructions - always applies (via copilot-instructions.md)
+   */
+  generateCoreInstructions(projectName, config) {
+    const overview = generateOverview(config);
+    return `# Copilot Instructions for ${projectName}
+
+This file provides context for GitHub Copilot. Generated by Paradigm.
+
+${overview}
+
+${generateUpdateRules(config)}
+
+---
+
+## Additional Context
+
+For detailed specifications, reference these files:
+
+- \`.paradigm/specs/symbols.md\` - Complete symbol reference
+- \`.paradigm/specs/logger.md\` - Logging specification
+- \`.paradigm/specs/scan.md\` - Visual discovery protocol
+- \`.paradigm/docs/\` - Documentation and troubleshooting
+- \`.paradigm/prompts/\` - Pre-written task prompts
+
+*Generated by Paradigm. Run \`paradigm sync copilot\` to regenerate.*
+`;
+  }
+  /**
+   * Symbol system instructions
+   */
+  generateSymbolInstructions(config) {
+    return frontmatter2("**/*.ts,**/*.tsx,**/*.js,**/*.jsx") + `# Paradigm Symbol System
+
+${generateSymbolSystem(config)}
+`;
+  }
+  /**
+   * Logging instructions
+   */
+  generateLoggingInstructions(config) {
+    return frontmatter2("**/*.ts,**/*.tsx,**/*.js,**/*.jsx") + `# Paradigm Logging
+
+${generateLoggingRules(config)}
+`;
+  }
+  /**
+   * Purpose file instructions
+   */
+  generatePurposeInstructions() {
+    return frontmatter2("**/.purpose") + `# Purpose Files
+
+Purpose files (\`.purpose\`) define the context for directories.
+
+## Format
+
+\`\`\`yaml
+# Directory context
+description: What this directory contains and why
+
+# Components (# symbol) \u2014 all documented code units
+components:
+  component-name:
+    description: What this component does
+    tags: [feature]                # Classification via tag bank
+    gates: [^gate1, ^gate2]       # Required gates
+    signals: [!signal1]           # Events emitted
+    used-by: [#other-component]
+\`\`\`
+
+## Symbol References (v2)
+
+- Reference components: \`#component-name\`
+- Reference flows: \`$flow-name\`
+- Reference gates: \`^gate-name\`
+- Reference signals: \`!signal-name\`
+- Reference aspects: \`~aspect-name\`
+`;
+  }
+  /**
+   * Portal instructions
+   */
+  generatePortalInstructions() {
+    return frontmatter2("**/portal.yaml") + `# Portal Configuration
+
+Portal files (\`portal.yaml\`) define authorization topology.
+
+## Format
+
+\`\`\`yaml
+version: "1.0"
+
+gates:
+  gate-name:
+    description: What this gate protects
+    locks:
+      - id: lock-id
+        description: Requirement description
+        keys:
+          - expression: "user.authenticated"
+            description: User must be logged in
+    prizes:
+      - id: prize-id
+        oneTime: true
+        metadata:
+          event: "gate_passed"
+
+flows:
+  flow-name:
+    description: User journey
+    gates: [gate1, gate2, gate3]
+\`\`\`
+
+## Portal Validation
+
+Use the Portal Validator for authorization checks:
+
+\`\`\`typescript
+import { portal } from '@a-company/portal-sdk/validator';
+
+const gate = portal.check('^gate-name')
+  .requires('requirement description')
+  .context({ userId, role });
+
+if (!condition) {
+  gate.deny('Reason for denial');
+  return redirect('/unauthorized');
+}
+
+gate.allow('Access granted');
+\`\`\`
+`;
+  }
+  /**
+   * Conventions instructions
+   */
+  generateConventionsInstructions(config) {
+    return frontmatter2("**/*.ts,**/*.tsx,**/*.js,**/*.jsx") + `# Paradigm Conventions
+
+${generateConventions(config)}
+`;
+  }
+  /**
+   * Commands reference instructions
+   */
+  generateCommandsInstructions() {
+    return `# Paradigm CLI Commands
+
+${generateCommandsReference()}
+`;
+  }
+  /**
+   * Agent Hints instructions - when to query CLI
+   */
+  generateAgentHintsInstructions() {
+    return `# Agent CLI Queries (Token-Efficient)
+
+Instead of reading large context files, query Paradigm CLI on-demand for fresh, precise data.
+
+## When to Query
+
+| Before doing this... | Run this command |
+|---------------------|------------------|
+| Modifying a symbol | \`paradigm ripple #symbol --json\` |
+| Debugging an error | \`paradigm echo ERROR_CODE --json\` |
+| Starting a session | \`paradigm thread --json\` |
+| Understanding relationships | \`paradigm constellation\` |
+| Getting oriented | \`paradigm beacon --json\` |
+
+## Query Patterns
+
+### Before Changing Code
+
+\`\`\`bash
+# See what depends on what you're changing
+paradigm ripple #checkout --json
+
+# Output includes: upstream deps, downstream effects, flow membership
+\`\`\`
+
+### When Debugging
+
+\`\`\`bash
+# Look up error context
+paradigm echo AUTH_REQUIRED --json
+
+# Then check ripple effects of the related symbol
+paradigm ripple ^authenticated --json
+\`\`\`
+
+### Starting Work
+
+\`\`\`bash
+# Check previous session context
+paradigm thread --json
+
+# Quick orientation
+paradigm beacon --json
+\`\`\`
+
+### Querying Constellation
+
+\`\`\`bash
+# Get specific symbol
+jq '.stars["#checkout"]' .paradigm/constellation.json
+
+# Find what requires a gate
+jq '[.stars | to_entries[] | select(.value.gates[]? == "^authenticated") | .key]' .paradigm/constellation.json
+
+# List all flows
+jq '.orbits | keys' .paradigm/constellation.json
+\`\`\`
+
+## Benefits
+
+- **Fresh data**: Always current, not stale from file generation
+- **Precise**: Only get the data you need
+- **Token-efficient**: ~100 tokens per query vs ~2000 upfront
+`;
+  }
+  /**
+   * Commit conventions instructions
+   */
+  generateCommitsInstructions() {
+    return `# Paradigm Commit Conventions
+
+${generateCommitConvention()}
+`;
+  }
+};
+var copilotAdapter = new CopilotAdapter();
+
+// src/core/ide-adapters/windsurf.ts
+import * as fs3 from "fs";
+import * as path3 from "path";
+var WindsurfAdapter = class {
+  name = "windsurf";
+  displayName = "Windsurf";
+  outputPath = ".windsurfrules";
+  detect(rootDir) {
+    if (fs3.existsSync(path3.join(rootDir, ".windsurfrules"))) {
+      return true;
+    }
+    if (fs3.existsSync(path3.join(rootDir, ".windsurf"))) {
+      return true;
+    }
+    return false;
+  }
+  generate(files) {
+    const { config, projectName } = files;
+    const sections = [];
+    sections.push(generateHeader(projectName, this.displayName));
+    sections.push(generateOverview(config));
+    sections.push(generateSymbolSystem(config));
+    const loggingSection = generateLoggingRules(config);
+    if (loggingSection) {
+      sections.push(loggingSection);
+    }
+    const scanSection = generateScanProtocol(config);
+    if (scanSection) {
+      sections.push(scanSection);
+    }
+    sections.push(generateUpdateRules(config));
+    sections.push(generateConventions(config));
+    sections.push(generateCommitConvention());
+    sections.push(generateCommandsReference());
+    sections.push(generateFooter());
+    return sections.filter((s) => s.trim()).join("\n");
+  }
+};
+var windsurfAdapter = new WindsurfAdapter();
+
+// src/core/ide-adapters/claude.ts
+import * as fs4 from "fs";
+import * as path4 from "path";
+var ClaudeAdapter = class {
+  name = "claude";
+  displayName = "Claude";
+  outputPath = "CLAUDE.md";
+  detect(rootDir) {
+    if (fs4.existsSync(path4.join(rootDir, "CLAUDE.md"))) {
+      return true;
+    }
+    return false;
+  }
+  generate(files) {
+    const { config, projectName } = files;
+    const sections = [];
+    sections.push(`# ${projectName} - Claude Context`);
+    sections.push("");
+    sections.push("> **Paradigm v2.0** | For Claude Code, Claude API, and Claude-native interfaces");
+    sections.push("");
+    sections.push("## Project Overview");
+    sections.push("");
+    if (config["agent-guidelines"]?.overview) {
+      sections.push(config["agent-guidelines"].overview);
+    }
+    sections.push("");
+    sections.push("## Quick Orientation");
+    sections.push("");
+    sections.push("```");
+    sections.push(".paradigm/config.yaml  \u2192 Project configuration");
+    sections.push(".paradigm/specs/       \u2192 Detailed specifications");
+    sections.push(".paradigm/docs/        \u2192 Commands, patterns, troubleshooting");
+    sections.push(".cursorrules           \u2192 IDE instructions (if using Cursor)");
+    sections.push("portal.yaml            \u2192 Security/auth definitions");
+    sections.push("```");
+    sections.push("");
+    sections.push(generateTerminalGuidance());
+    sections.push("## Agent Onboarding");
+    sections.push("");
+    sections.push("**First Session:**");
+    sections.push("1. Call `paradigm_status` for project overview");
+    sections.push("2. Read `.paradigm/config.yaml` for conventions");
+    sections.push("3. Check if `portal.yaml` exists (for auth gates)");
+    sections.push("");
+    sections.push("**Before Each Task:**");
+    sections.push("1. `paradigm_wisdom_context` for symbols you'll modify");
+    sections.push("2. `paradigm_ripple` to check impact");
+    sections.push("3. `paradigm_history_fragility` for stability warnings");
+    sections.push("");
+    sections.push("## Symbol System");
+    sections.push("");
+    sections.push("Use these prefixes in documentation and commits:");
+    sections.push("");
+    sections.push("| Symbol | Meaning | Example |");
+    sections.push("|--------|---------|---------|");
+    const symbolSystem = config["symbol-system"];
+    if (symbolSystem) {
+      for (const [prefix, def] of Object.entries(symbolSystem)) {
+        const example = def.examples?.[0] || `${prefix}example`;
+        sections.push(`| \`${prefix}\` | ${def.name} | \`${example}\` |`);
+      }
+    }
+    sections.push("");
+    sections.push("## First Actions for New Sessions");
+    sections.push("");
+    sections.push("**Resuming a session:** Call `paradigm_session_recover` for previous session context.");
+    sections.push("");
+    sections.push("1. **Orient:** Call `paradigm_status` to see project overview and available symbols");
+    sections.push("2. **Verify:** Check `.paradigm/config.yaml` for discipline and conventions");
+    sections.push('3. **Locate:** Use `paradigm_navigate` with "context" intent for your task');
+    sections.push("4. **Review:** Read the nearest `.purpose` file before making changes");
+    sections.push("5. **Check:** Call `paradigm_gates_for_route` before adding API endpoints");
+    sections.push("");
+    sections.push("## Before Implementing (Every Task)");
+    sections.push("");
+    sections.push("1. **Is this task complex?** (3+ files, security + implementation, multiple features)");
+    sections.push('   \u2192 Call `paradigm_orchestrate_inline` with mode="plan" BEFORE writing code');
+    sections.push("2. **Does it affect existing symbols?** \u2192 Call `paradigm_ripple`");
+    sections.push("3. **Does it add API endpoints?** \u2192 Call `paradigm_gates_for_route`");
+    sections.push("");
+    sections.push("## Portal Protocol (Authorization)");
+    sections.push("");
+    sections.push("**Portal.yaml is REQUIRED when the project has protected routes.**");
+    sections.push("");
+    sections.push("### When to Create portal.yaml");
+    sections.push("");
+    sections.push("Create `portal.yaml` in project root when:");
+    sections.push("- Adding any endpoint that requires authentication");
+    sections.push("- Adding role-based access (admin, member, owner)");
+    sections.push("- Adding resource ownership checks (user can only edit their own data)");
+    sections.push("");
+    sections.push("### Portal.yaml Structure");
+    sections.push("");
+    sections.push("```yaml");
+    sections.push('version: "1.0"');
+    sections.push("gates:");
+    sections.push("  ^authenticated:");
+    sections.push("    description: User must be logged in");
+    sections.push("    check: req.user != null");
+    sections.push("  ^project-admin:");
+    sections.push("    description: User must be admin of the project");
+    sections.push("    check: project.admins.includes(req.user.id)");
+    sections.push("  ^comment-author:");
+    sections.push("    description: User must be the comment author");
+    sections.push("    check: comment.authorId === req.user.id");
+    sections.push("");
+    sections.push("routes:");
+    sections.push('  "GET /api/projects/:id": [^authenticated, ^project-member]');
+    sections.push('  "PUT /api/projects/:id": [^authenticated, ^project-admin]');
+    sections.push('  "DELETE /api/comments/:id": [^authenticated, ^comment-author]');
+    sections.push("```");
+    sections.push("");
+    sections.push("### When Adding New Endpoints");
+    sections.push("");
+    sections.push("**ALWAYS update portal.yaml when adding routes:**");
+    sections.push("");
+    sections.push("1. Call `paradigm_gates_for_route` to get suggestions");
+    sections.push("2. Add the route to portal.yaml with required gates");
+    sections.push("3. Implement the gate checks in your middleware/code");
+    sections.push("4. Test that unauthorized access returns 403");
+    sections.push("");
+    sections.push("### Common Gate Patterns");
+    sections.push("");
+    sections.push("| Pattern | Gate Name | Description |");
+    sections.push("|---------|-----------|-------------|");
+    sections.push("| Any logged-in user | `^authenticated` | Basic auth check |");
+    sections.push("| Resource membership | `^{resource}-member` | User is member of resource |");
+    sections.push("| Resource admin | `^{resource}-admin` | User is admin of resource |");
+    sections.push("| Resource owner | `^{resource}-owner` | User owns the resource |");
+    sections.push("| Author only | `^{resource}-author` | User created the resource |");
+    sections.push("");
+    sections.push("## Context Discovery");
+    sections.push("");
+    sections.push("**Before making changes:**");
+    sections.push("");
+    sections.push("1. Check `.paradigm/config.yaml` for project configuration");
+    sections.push("2. Read the `.purpose` file in the directory you're modifying");
+    sections.push("3. Check `portal.yaml` for existing auth gates");
+    sections.push("4. Check `.paradigm/docs/patterns.md` for coding patterns");
+    sections.push("");
+    sections.push(generateNavigationSection(config));
+    sections.push("## Context Monitoring Protocol");
+    sections.push("");
+    sections.push("**Periodically check context usage** by calling `paradigm_context_check` (every 10-15 tool calls or when user asks).");
+    sections.push("");
+    sections.push('**When recommendation is NOT "continue":**');
+    sections.push('1. Inform user: "Context usage is at ~X%. Recommend handoff soon."');
+    sections.push("2. Offer to prepare handoff summary");
+    sections.push("3. If urgent (>85%), prioritize completing current task then handoff");
+    sections.push("");
+    sections.push("**To handoff:**");
+    sections.push("1. Call `paradigm_handoff_prepare` with summary and next steps");
+    sections.push('2. User runs: `paradigm team handoff --to <agent> --summary "..."`');
+    sections.push("3. New session accepts with: `paradigm team accept <id>`");
+    sections.push("");
+    sections.push(generateCheckpointProtocol());
+    sections.push("## MCP Workflow Protocol");
+    sections.push("");
+    sections.push("**Query before modifying** - Use MCP tools for token-efficient, fresh data:");
+    sections.push("");
+    sections.push("| Before doing this... | Call this tool |");
+    sections.push("|---------------------|----------------|");
+    sections.push("| Modifying a symbol | `paradigm_ripple` with the symbol |");
+    sections.push("| Understanding code | `paradigm_navigate` with explore intent |");
+    sections.push("| Checking dependencies | `paradigm_related` for connections |");
+    sections.push("| Getting oriented | `paradigm_status` for project overview |");
+    sections.push("| **Adding API endpoint** | `paradigm_gates_for_route` for auth gates |");
+    sections.push("| **Validating changes** | `paradigm_flows_affected` for flow impact |");
+    sections.push("| **Getting test data** | `paradigm_test_fixtures` for fixtures |");
+    sections.push('| **Building a feature (3+ files)** | `paradigm_orchestrate_inline` mode="plan" |');
+    sections.push('| **Task involves security + code** | `paradigm_orchestrate_inline` mode="plan" |');
+    sections.push("| **Finishing work session** | `paradigm_reindex` to rebuild static index |");
+    sections.push("");
+    sections.push("**Benefits**: ~100 tokens per query vs ~2000 for reading files. Always fresh data from live index.");
+    sections.push("");
+    sections.push("**Authorization workflow:**");
+    sections.push("1. Adding endpoint? \u2192 Call `paradigm_gates_for_route`");
+    sections.push("2. Get suggested gates \u2192 Add them to `portal.yaml`");
+    sections.push("3. Implement gate checks \u2192 Test 403 responses");
+    sections.push("");
+    sections.push("## Token Budget Reference");
+    sections.push("");
+    sections.push("| Operation | Typical Tokens | Use When |");
+    sections.push("|-----------|---------------|----------|");
+    sections.push("| `paradigm_status` | ~100 | Starting a session |");
+    sections.push("| `paradigm_search` | ~150 | Looking for symbols |");
+    sections.push("| `paradigm_navigate` | ~200 | Finding code locations |");
+    sections.push("| `paradigm_ripple` | ~300 | Before modifying symbols |");
+    sections.push("| `paradigm_gates_for_route` | ~150 | Adding API endpoints |");
+    sections.push("| File read (small) | ~500 | Need exact code |");
+    sections.push("| File read (large) | ~2000+ | Avoid if possible |");
+    sections.push("| Full .purpose + config | ~1500 | Initial orientation |");
+    sections.push("");
+    sections.push("**Tip**: Prefer MCP queries over file reads. Check `paradigm_session_stats` for actual usage.");
+    sections.push("");
+    sections.push("### When to Use MCP vs File Reads");
+    sections.push("");
+    sections.push("| Need | Use MCP | Use File Read |");
+    sections.push("|------|---------|---------------|");
+    sections.push("| Find symbol | `paradigm_navigate` | Never |");
+    sections.push("| Check impact | `paradigm_ripple` | Never |");
+    sections.push("| Read implementation | MCP first | Then specific file |");
+    sections.push("| Write code | N/A | Existing patterns |");
+    sections.push("| Check team wisdom | `paradigm_wisdom_context` | Never |");
+    sections.push("");
+    sections.push("**Rule**: MCP for discovery, files for implementation.");
+    sections.push("");
+    sections.push("## MCP Resources (On-Demand Content)");
+    sections.push("");
+    sections.push("Reference content is served via MCP resources instead of being stored locally:");
+    sections.push("");
+    sections.push("| Resource | URI | Content |");
+    sections.push("|----------|-----|---------|");
+    sections.push("| Prompts | `paradigm://prompts` | Task templates (add-feature, refactor, etc.) |");
+    sections.push("| Commands | `paradigm://docs/commands` | CLI command reference |");
+    sections.push("| Queries | `paradigm://docs/queries` | jq query examples |");
+    sections.push("| Disciplines | `paradigm://specs/disciplines` | Symbol mappings by domain |");
+    sections.push("| Scan | `paradigm://specs/scan` | Visual discovery protocol |");
+    sections.push("");
+    sections.push("**Usage**: Read resources with `paradigm://prompts/{name}` (e.g., `paradigm://prompts/add-feature`).");
+    sections.push("");
+    sections.push("**Session Tracking**: Call `paradigm_session_stats` to see token usage and cost breakdown.");
+    sections.push("");
+    if (config["purpose-required"]?.length) {
+      sections.push("## Directory Structure");
+      sections.push("");
+      sections.push("`.purpose` files exist in:");
+      for (const req of config["purpose-required"]) {
+        sections.push(`- \`${req.pattern}\``);
+      }
+      sections.push("");
+    }
+    const loggingSection = generateLoggingRules(config);
+    if (loggingSection) {
+      sections.push(loggingSection);
+    }
+    const conventionsSection = generateConventions(config);
+    if (conventionsSection) {
+      sections.push(conventionsSection);
+    }
+    const updateSection = generateUpdateRules(config);
+    if (updateSection) {
+      sections.push(updateSection);
+    }
+    sections.push("## Multi-Agent Orchestration");
+    sections.push("");
+    sections.push("Paradigm supports multi-agent orchestration via `paradigm team` commands:");
+    sections.push("");
+    sections.push("### Commands");
+    sections.push("");
+    sections.push("| Command | Description |");
+    sections.push("|---------|-------------|");
+    sections.push('| `paradigm team spawn <agent> --task "..."` | Spawn a single agent |');
+    sections.push('| `paradigm team orchestrate "task"` | AI orchestrator coordinates agents |');
+    sections.push('| `paradigm team orchestrate "task" --solo` | Single Claude mode (no splitting) |');
+    sections.push('| `paradigm team orchestrate "task" --compare` | A/B test solo vs faceted |');
+    sections.push('| `paradigm team agents suggest "task"` | Suggest agents based on task triggers |');
+    sections.push("| `paradigm team providers` | Show available providers |");
+    sections.push("| `paradigm team providers --set X` | Set preferred provider |");
+    sections.push("| `paradigm team models` | View/configure agent model assignments |");
+    sections.push("| `paradigm team models --refresh` | Re-discover models from environment |");
+    sections.push("");
+    sections.push("### Agent Suggestions");
+    sections.push("");
+    sections.push("Before orchestrating, you can preview which agents will be involved:");
+    sections.push("");
+    sections.push("```bash");
+    sections.push('paradigm team agents suggest "Add user authentication with JWT"');
+    sections.push("```");
+    sections.push("");
+    sections.push("Or via MCP (returns `suggestedAgents` in plan mode):");
+    sections.push("```");
+    sections.push('paradigm_orchestrate_inline({ task: "...", mode: "plan" })');
+    sections.push("```");
+    sections.push("");
+    sections.push("## Flow-First Development");
+    sections.push("");
+    sections.push("**Define flows BEFORE implementing features that span multiple steps.**");
+    sections.push("");
+    sections.push("### When to Define Flows");
+    sections.push("");
+    sections.push("Create a flow ($symbol) when your feature:");
+    sections.push("- Has multiple authorization gates");
+    sections.push("- Spans multiple components or services");
+    sections.push("- Emits events that trigger other actions");
+    sections.push('- Needs clear documentation of the "happy path"');
+    sections.push("");
+    sections.push("### Flow Definition");
+    sections.push("");
+    sections.push("Define flows in `.paradigm/flows.yaml`:");
+    sections.push("");
+    sections.push("```yaml");
+    sections.push('version: "1.0"');
+    sections.push("flows:");
+    sections.push("  $task-creation:");
+    sections.push("    name: Task Creation Flow");
+    sections.push('    trigger: "POST /api/tasks"');
+    sections.push("    steps:");
+    sections.push("      - type: gate");
+    sections.push("        symbol: ^authenticated");
+    sections.push("      - type: gate");
+    sections.push("        symbol: ^project-member");
+    sections.push("      - type: action");
+    sections.push('        symbol: "#create-task"');
+    sections.push("      - type: signal");
+    sections.push('        symbol: "!task-created"');
+    sections.push('    successSignal: "!task-created"');
+    sections.push("```");
+    sections.push("");
+    sections.push("### Flow-First Protocol");
+    sections.push("");
+    sections.push("1. **Define the flow first** - What gates, actions, and signals?");
+    sections.push("2. **Validate** - Call `paradigm_flow_validate` to check completeness");
+    sections.push("3. **Implement** - Each step becomes a clear implementation target");
+    sections.push("");
+    sections.push("## Flow Validation");
+    sections.push("");
+    sections.push("**Validate flows before and after implementing:**");
+    sections.push("");
+    sections.push("```");
+    sections.push("# Validate specific flow");
+    sections.push('paradigm_flow_validate({ flowId: "$task-creation" })');
+    sections.push("");
+    sections.push("# Validate all flows");
+    sections.push("paradigm_flow_validate({})");
+    sections.push("");
+    sections.push("# Deep check (verify implementation exists)");
+    sections.push("paradigm_flow_validate({ checkImplementation: true })");
+    sections.push("```");
+    sections.push("");
+    sections.push("**After modifying symbols, check affected flows:**");
+    sections.push("");
+    sections.push("```");
+    sections.push("# Check what flows are affected by #tasks");
+    sections.push('paradigm_flows_affected({ symbol: "#tasks" })');
+    sections.push("```");
+    sections.push("");
+    sections.push(generateCommitConvention());
+    sections.push("## Automatic Enforcement (Claude Code Hooks)");
+    sections.push("");
+    sections.push("This project uses Claude Code hooks for paradigm compliance. These are installed");
+    sections.push("automatically via `paradigm shift` or `paradigm hooks install`.");
+    sections.push("");
+    sections.push("| Hook | Type | Behavior |");
+    sections.push("|------|------|----------|");
+    sections.push("| **Stop hook** | Stop | **BLOCKS** you from finishing if source files were modified without .purpose updates |");
+    sections.push("| **Pre-commit hook** | PreToolUse (Bash) | Auto-rebuilds index before `git commit` \u2014 never blocks |");
+    sections.push("| **Post-write hook** | PostToolUse (Edit/Write) | Advisory reminder when editing files without .purpose coverage |");
+    sections.push("");
+    sections.push("**If the Stop hook blocks you:**");
+    sections.push("1. Update the nearest `.purpose` file for each modified code area");
+    sections.push("2. Update `portal.yaml` if you added routes or gates");
+    sections.push("3. Call `paradigm_reindex` to rebuild the static index");
+    sections.push("4. Then finish your session");
+    sections.push("");
+    sections.push("## Troubleshooting");
+    sections.push("");
+    sections.push("| Issue | Solution |");
+    sections.push("|-------|----------|");
+    sections.push('| "Symbol not found" | Run `paradigm scan` to rebuild index |');
+    sections.push('| "Navigator not found" | Run `paradigm scan` to generate navigator.yaml |');
+    sections.push("| Empty search results | Check that .purpose files define symbols |");
+    sections.push("| High context usage | Call `paradigm_handoff_prepare` |");
+    sections.push("| Gate suggestions missing | Check that portal.yaml exists and defines gates |");
+    sections.push('| "Flow index not found" | Run `paradigm scan` and add flows to .purpose files |');
+    sections.push('| "Fixtures not found" | Create `.paradigm/fixtures.yaml` with test data |');
+    sections.push("");
+    sections.push("## Maintaining Paradigm Files");
+    sections.push("");
+    sections.push("**You MUST update Paradigm files when making code changes. The Stop hook will block you if you don't:**");
+    sections.push("");
+    sections.push("| Change Type | Action Required |");
+    sections.push("|-------------|-----------------|");
+    sections.push("| Add feature | Create `.purpose` in feature directory |");
+    sections.push("| Add ANY protected route | Create/update `portal.yaml` with gates |");
+    sections.push("| Add ownership check | Add `^{resource}-owner` gate to `portal.yaml` |");
+    sections.push("| Add role-based access | Add `^{role}` gate to `portal.yaml` |");
+    sections.push("| Add signal/event | Add to emitting feature's `.purpose` |");
+    sections.push("| Add multi-step flow | Document as `$flow` in `.purpose` |");
+    sections.push("| Rename/delete symbol | Update all `.purpose` references |");
+    sections.push("| Learn antipattern | Add to `.paradigm/wisdom/antipatterns.yaml` |");
+    sections.push("");
+    sections.push("**CRITICAL: Authorization requires portal.yaml**");
+    sections.push("");
+    sections.push("If your code has ANY of these, `portal.yaml` MUST exist:");
+    sections.push("- JWT/session authentication");
+    sections.push("- Role checks (admin, member, etc.)");
+    sections.push("- Ownership checks (user can only edit own resources)");
+    sections.push("- Protected API endpoints");
+    sections.push("");
+    sections.push("**Validation**: Run `paradigm doctor` to check for inconsistencies.");
+    sections.push("");
+    sections.push("See `.paradigm/docs/ai-maintenance-protocol.md` for detailed guidance.");
+    sections.push("");
+    sections.push("---");
+    sections.push("");
+    sections.push("*See `.cursorrules` for IDE-specific instructions, `.paradigm/specs/` for detailed specifications.*");
+    return sections.filter((s) => s !== void 0).join("\n");
+  }
+  /**
+   * Generate MCP configuration for Claude
+   */
+  generateMcpConfig(rootDir) {
+    return {
+      mcpServers: {
+        paradigm: {
+          command: "paradigm-mcp",
+          args: ["."],
+          cwd: rootDir
+        }
+      }
+    };
+  }
+  /**
+   * Generate nested CLAUDE.md files for directories with .purpose files
+   */
+  generateNestedContexts(rootDir, files) {
+    const generatedFiles = [];
+    const purposeFiles = findPurposeFiles(rootDir);
+    for (const purposePath of purposeFiles) {
+      const dirPath = path4.dirname(purposePath);
+      const relativePath = path4.relative(rootDir, dirPath);
+      if (relativePath === "" || relativePath === ".") continue;
+      const purposeContent = fs4.readFileSync(purposePath, "utf8");
+      const contextContent = this.generateDirectoryContext(relativePath, purposeContent, files);
+      generatedFiles.push({
+        path: path4.join(relativePath, "CLAUDE.md"),
+        content: contextContent
+      });
+    }
+    return generatedFiles;
+  }
+  /**
+   * Generate context for a specific directory
+   */
+  generateDirectoryContext(dirPath, purposeContent, files) {
+    const sections = [];
+    const dirName = path4.basename(dirPath);
+    sections.push(`# ${dirName} - Directory Context`);
+    sections.push("");
+    sections.push(`> Part of ${files.projectName} | See root CLAUDE.md for project overview`);
+    sections.push("");
+    sections.push("## Purpose");
+    sections.push("");
+    sections.push("```yaml");
+    sections.push(purposeContent.trim());
+    sections.push("```");
+    sections.push("");
+    sections.push("## Quick Reference");
+    sections.push("");
+    sections.push(`- **Path**: \`${dirPath}\``);
+    sections.push("- **Config**: See `.paradigm/config.yaml`");
+    sections.push("- **Patterns**: See `.paradigm/docs/patterns.md`");
+    sections.push("");
+    sections.push("## Symbols");
+    sections.push("");
+    sections.push("`#` component | `$` flow | `^` gate | `!` signal | `~` aspect");
+    sections.push("");
+    sections.push("---");
+    sections.push("");
+    sections.push("*Auto-generated by `paradigm sync claude`. Edit .purpose file to update.*");
+    return sections.join("\n");
+  }
+};
+function findPurposeFiles(dir) {
+  const results = [];
+  function walk(currentDir) {
+    const entries = fs4.readdirSync(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path4.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+        walk(fullPath);
+      } else if (entry.name === ".purpose") {
+        results.push(fullPath);
+      }
+    }
+  }
+  walk(dir);
+  return results;
+}
+var claudeAdapter = new ClaudeAdapter();
+
+// src/core/ide-adapters/agents.ts
+import * as fs5 from "fs";
+import * as path5 from "path";
+var AgentsAdapter = class {
+  name = "agents";
+  displayName = "AGENTS.md";
+  outputPath = "AGENTS.md";
+  multiFile = false;
+  detect(rootDir) {
+    return fs5.existsSync(path5.join(rootDir, "AGENTS.md"));
+  }
+  generate(files) {
+    const { config, projectName } = files;
+    const sections = [];
+    sections.push(`# ${projectName} - AI Agent Instructions`);
+    sections.push("");
+    sections.push("> Generated by [Paradigm](https://github.com/anthropics/paradigm) v2.0 | Universal AI agent instruction file");
+    sections.push("");
+    sections.push(generateOverview(config));
+    sections.push(generateSymbolSystem(config));
+    const conventionsSection = generateConventions(config);
+    if (conventionsSection) {
+      sections.push(conventionsSection);
+    }
+    const loggingSection = generateLoggingRules(config);
+    if (loggingSection) {
+      sections.push(loggingSection);
+    }
+    sections.push(generateMcpToolReference());
+    sections.push(generateNavigationSection(config));
+    sections.push(generateWorkflowProtocol());
+    sections.push(generateCommitConvention());
+    sections.push(generateHandoffProtocol());
+    const updateSection = generateUpdateRules(config);
+    if (updateSection) {
+      sections.push(updateSection);
+    }
+    sections.push(generateCommandsReference());
+    sections.push("---");
+    sections.push("");
+    sections.push("*Generated by Paradigm. Run `paradigm sync agents` to regenerate.*");
+    return sections.filter((s) => s !== void 0 && s !== "").join("\n");
+  }
+};
+var agentsAdapter = new AgentsAdapter();
+
+// src/core/ide-adapters/index.ts
+var adapters = /* @__PURE__ */ new Map([
+  ["cursor", cursorAdapter],
+  ["copilot", copilotAdapter],
+  ["windsurf", windsurfAdapter],
+  ["claude", claudeAdapter],
+  ["agents", agentsAdapter]
+]);
+function getAdapter(name) {
+  return adapters.get(name.toLowerCase());
+}
+function getAdapterNames() {
+  return Array.from(adapters.keys());
+}
+function detectIDE(rootDir) {
+  if (cursorAdapter.detect(rootDir)) {
+    return {
+      detected: "cursor",
+      confidence: "high",
+      reason: "Found .cursor directory or .cursorrules file"
+    };
+  }
+  if (windsurfAdapter.detect(rootDir)) {
+    return {
+      detected: "windsurf",
+      confidence: "high",
+      reason: "Found .windsurf directory or .windsurfrules file"
+    };
+  }
+  if (copilotAdapter.detect(rootDir)) {
+    return {
+      detected: "copilot",
+      confidence: "medium",
+      reason: "Found .github/copilot-instructions.md file"
+    };
+  }
+  if (fs6.existsSync(path6.join(rootDir, ".vscode"))) {
+    return {
+      detected: "cursor",
+      confidence: "low",
+      reason: "Found .vscode directory, defaulting to Cursor format"
+    };
+  }
+  return {
+    detected: null,
+    confidence: "low",
+    reason: "No IDE markers found"
+  };
+}
+function loadParadigmFiles(rootDir) {
+  const paradigmDir = path6.join(rootDir, ".paradigm");
+  const paradigmFile = path6.join(rootDir, ".paradigm");
+  let configPath;
+  let specsDir;
+  let docsDir;
+  if (fs6.existsSync(paradigmDir) && fs6.statSync(paradigmDir).isDirectory()) {
+    configPath = path6.join(paradigmDir, "config.yaml");
+    specsDir = path6.join(paradigmDir, "specs");
+    docsDir = path6.join(paradigmDir, "docs");
+  } else if (fs6.existsSync(paradigmFile) && fs6.statSync(paradigmFile).isFile()) {
+    configPath = paradigmFile;
+    specsDir = "";
+    docsDir = "";
+  } else {
+    return null;
+  }
+  if (!fs6.existsSync(configPath)) {
+    return null;
+  }
+  let config;
+  try {
+    const configContent = fs6.readFileSync(configPath, "utf8");
+    config = parseParadigmConfig(configContent);
+  } catch {
+    return null;
+  }
+  const specs = {};
+  if (specsDir && fs6.existsSync(specsDir)) {
+    const specFiles = ["logger.md", "scan.md", "symbols.md"];
+    for (const file of specFiles) {
+      const filePath = path6.join(specsDir, file);
+      if (fs6.existsSync(filePath)) {
+        const key = file.replace(".md", "");
+        specs[key] = fs6.readFileSync(filePath, "utf8");
+      }
+    }
+  }
+  const docs = {};
+  if (docsDir && fs6.existsSync(docsDir)) {
+    const docFiles = ["commands.md", "patterns.md", "troubleshooting.md"];
+    for (const file of docFiles) {
+      const filePath = path6.join(docsDir, file);
+      if (fs6.existsSync(filePath)) {
+        const key = file.replace(".md", "");
+        docs[key] = fs6.readFileSync(filePath, "utf8");
+      }
+    }
+  }
+  return {
+    config,
+    specs,
+    docs,
+    projectName: path6.basename(rootDir)
+  };
+}
+function syncToIDE(rootDir, ideName, files, force = false) {
+  const adapter = getAdapter(ideName);
+  if (!adapter) {
+    return {
+      success: false,
+      ide: ideName,
+      outputPath: "",
+      message: `Unknown IDE: ${ideName}. Available: ${getAdapterNames().join(", ")}`
+    };
+  }
+  const outputPath = path6.join(rootDir, adapter.outputPath);
+  try {
+    if (adapter.multiFile && adapter.generateFiles) {
+      return syncMultiFileAdapter(rootDir, adapter, files, force);
+    }
+    if (!force && fs6.existsSync(outputPath)) {
+    }
+    const parentDir = path6.dirname(outputPath);
+    if (!fs6.existsSync(parentDir)) {
+      fs6.mkdirSync(parentDir, { recursive: true });
+    }
+    const content = adapter.generate(files);
+    fs6.writeFileSync(outputPath, content, "utf8");
+    return {
+      success: true,
+      ide: ideName,
+      outputPath,
+      message: `Generated ${adapter.outputPath}`
+    };
+  } catch (error) {
+    return {
+      success: false,
+      ide: ideName,
+      outputPath,
+      message: `Failed to write ${adapter.outputPath}: ${error.message}`
+    };
+  }
+}
+function syncMultiFileAdapter(rootDir, adapter, files, force) {
+  const outputDir = path6.join(rootDir, adapter.outputPath);
+  if (!fs6.existsSync(outputDir)) {
+    fs6.mkdirSync(outputDir, { recursive: true });
+  }
+  const generatedFiles = adapter.generateFiles(files, rootDir);
+  const writtenFiles = [];
+  for (const file of generatedFiles) {
+    let filePath;
+    if (file.path.startsWith("../")) {
+      filePath = path6.join(outputDir, file.path);
+    } else {
+      filePath = path6.join(outputDir, file.path);
+    }
+    const parentDir = path6.dirname(filePath);
+    if (!fs6.existsSync(parentDir)) {
+      fs6.mkdirSync(parentDir, { recursive: true });
+    }
+    if (!force && fs6.existsSync(filePath)) {
+    }
+    fs6.writeFileSync(filePath, file.content, "utf8");
+    writtenFiles.push(file.path);
+  }
+  if (adapter.name === "cursor") {
+    const legacyCursorrules = path6.join(rootDir, ".cursorrules");
+    if (fs6.existsSync(legacyCursorrules)) {
+      const backupPath = path6.join(rootDir, ".cursorrules.bak");
+      if (!fs6.existsSync(backupPath)) {
+        fs6.renameSync(legacyCursorrules, backupPath);
+      }
+    }
+  }
+  const mainDirFiles = writtenFiles.filter((f) => !f.startsWith("../"));
+  const extraFiles = writtenFiles.filter((f) => f.startsWith("../"));
+  let message = `Generated ${mainDirFiles.length} files in ${adapter.outputPath}/`;
+  if (extraFiles.length > 0) {
+    message += ` + ${extraFiles.length} additional file(s)`;
+  }
+  return {
+    success: true,
+    ide: adapter.name,
+    outputPath: outputDir,
+    message
+  };
+}
+function syncToAllIDEs(rootDir, files, force = false) {
+  const results = [];
+  for (const [name] of adapters) {
+    results.push(syncToIDE(rootDir, name, files, force));
+  }
+  return results;
+}
+function writeMcpConfig(rootDir, ideName) {
+  const adapter = getAdapter(ideName);
+  if (!adapter || !adapter.generateMcpConfig) {
+    return {
+      success: false,
+      path: "",
+      message: `IDE ${ideName} does not support MCP configuration`
+    };
+  }
+  const mcpConfig = adapter.generateMcpConfig(rootDir);
+  let configPath;
+  switch (ideName) {
+    case "cursor":
+      configPath = path6.join(rootDir, ".cursor", "mcp.json");
+      break;
+    case "claude":
+      configPath = path6.join(rootDir, ".mcp.json");
+      break;
+    default:
+      return {
+        success: false,
+        path: "",
+        message: `Unknown MCP config path for ${ideName}`
+      };
+  }
+  try {
+    const parentDir = path6.dirname(configPath);
+    if (!fs6.existsSync(parentDir)) {
+      fs6.mkdirSync(parentDir, { recursive: true });
+    }
+    let existingConfig = {};
+    if (fs6.existsSync(configPath)) {
+      const content = fs6.readFileSync(configPath, "utf8");
+      existingConfig = JSON.parse(content);
+    }
+    const mergedConfig = {
+      ...existingConfig,
+      mcpServers: {
+        ...existingConfig.mcpServers || {},
+        ...mcpConfig.mcpServers
+      }
+    };
+    if (ideName === "claude") {
+      const existingPermissions = existingConfig.permissions || {};
+      const existingAllow = existingPermissions.allow || [];
+      const paradigmPermission = "Bash(paradigm *)";
+      if (!existingAllow.includes(paradigmPermission)) {
+        mergedConfig.permissions = {
+          ...existingPermissions,
+          allow: [...existingAllow, paradigmPermission]
+        };
+      }
+    }
+    fs6.writeFileSync(configPath, JSON.stringify(mergedConfig, null, 2));
+    return {
+      success: true,
+      path: configPath,
+      message: `MCP configuration written to ${path6.relative(rootDir, configPath)}`
+    };
+  } catch (error) {
+    return {
+      success: false,
+      path: configPath,
+      message: `Failed to write MCP config: ${error.message}`
+    };
+  }
+}
+function writeNestedContexts(rootDir, ideName, files) {
+  const adapter = getAdapter(ideName);
+  if (!adapter || !adapter.generateNestedContexts) {
+    return {
+      success: false,
+      count: 0,
+      message: `IDE ${ideName} does not support nested contexts`
+    };
+  }
+  try {
+    const generatedFiles = adapter.generateNestedContexts(rootDir, files);
+    for (const file of generatedFiles) {
+      const filePath = path6.join(rootDir, file.path);
+      const parentDir = path6.dirname(filePath);
+      if (!fs6.existsSync(parentDir)) {
+        fs6.mkdirSync(parentDir, { recursive: true });
+      }
+      fs6.writeFileSync(filePath, file.content, "utf8");
+    }
+    return {
+      success: true,
+      count: generatedFiles.length,
+      message: `Generated ${generatedFiles.length} nested context files`
+    };
+  } catch (error) {
+    return {
+      success: false,
+      count: 0,
+      message: `Failed to write nested contexts: ${error.message}`
+    };
+  }
+}
+
+export {
+  getAdapter,
+  getAdapterNames,
+  detectIDE,
+  loadParadigmFiles,
+  syncToIDE,
+  syncToAllIDEs,
+  writeMcpConfig,
+  writeNestedContexts
+};