@soleri/forge 0.0.1 → 4.0.0

package/src/scaffolder.ts

@@ -0,0 +1,386 @@
+import {
+  mkdirSync,
+  writeFileSync,
+  chmodSync,
+  existsSync,
+  readdirSync,
+  readFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import type { AgentConfig, ScaffoldResult, ScaffoldPreview, AgentInfo } from './types.js';
+
+import { generatePackageJson } from './templates/package-json.js';
+import { generateTsconfig } from './templates/tsconfig.js';
+import { generateVitestConfig } from './templates/vitest-config.js';
+import { generatePersona } from './templates/persona.js';
+import { generateDomainFacade } from './templates/domain-facade.js';
+import { generateCoreFacade } from './templates/core-facade.js';
+import { generateEntryPoint } from './templates/entry-point.js';
+import { generateFacadesTest } from './templates/test-facades.js';
+import { generateClaudeMdTemplate } from './templates/claude-md-template.js';
+import { generateInjectClaudeMd } from './templates/inject-claude-md.js';
+import { generateActivate } from './templates/activate.js';
+import { generateReadme } from './templates/readme.js';
+import { generateSetupScript } from './templates/setup-script.js';
+import { generateLLMClient } from './templates/llm-client.js';
+
+/**
+ * Preview what scaffold will create without writing anything.
+ */
+export function previewScaffold(config: AgentConfig): ScaffoldPreview {
+  const agentDir = join(config.outputDir, config.id);
+
+  const files = [
+    { path: 'package.json', description: 'NPM package with MCP SDK, SQLite, Zod dependencies' },
+    { path: 'tsconfig.json', description: 'TypeScript config (ES2022, NodeNext, strict)' },
+    { path: 'vitest.config.ts', description: 'Test config (vitest, forks pool, coverage)' },
+    { path: '.gitignore', description: 'Git ignore (node_modules, dist, coverage)' },
+    {
+      path: 'scripts/copy-assets.js',
+      description: 'Build script to copy intelligence data to dist',
+    },
+    {
+      path: 'src/index.ts',
+      description:
+        'Entry point — initializes vault, planner, brain, registers facades, starts stdio',
+    },
+    {
+      path: 'src/llm/llm-client.ts',
+      description:
+        'LLM client — unified OpenAI/Anthropic caller with model routing (optional, needs API keys)',
+    },
+    {
+      path: 'src/facades/core.facade.ts',
+      description: 'Core facade — search, vault stats, health, identity',
+    },
+    ...config.domains.map((d) => ({
+      path: `src/facades/${d}.facade.ts`,
+      description: `${d} facade — search, get_patterns, capture, remove`,
+    })),
+    ...config.domains.map((d) => ({
+      path: `src/intelligence/data/${d}.json`,
+      description: `Empty ${d} intelligence bundle — ready for knowledge capture`,
+    })),
+    {
+      path: 'src/identity/persona.ts',
+      description: `${config.name} persona — name, role, principles, greeting`,
+    },
+    {
+      path: 'src/activation/claude-md-content.ts',
+      description: `${config.name} CLAUDE.md content with activation triggers and facades table`,
+    },
+    {
+      path: 'src/activation/inject-claude-md.ts',
+      description: 'Idempotent CLAUDE.md injection — project-level or global (~/.claude/CLAUDE.md)',
+    },
+    {
+      path: 'src/activation/activate.ts',
+      description: `${config.name} activation system — persona adoption, setup status, tool recommendations`,
+    },
+    {
+      path: 'src/__tests__/facades.test.ts',
+      description: `Facade integration tests — all ${config.domains.length + 1} facades`,
+    },
+    { path: '.mcp.json', description: 'MCP client config for connecting to this agent' },
+    {
+      path: 'README.md',
+      description: `${config.name} documentation — quick start, domains, principles, commands`,
+    },
+    {
+      path: 'scripts/setup.sh',
+      description: 'Automated setup — Node.js check, build, Claude Code MCP registration',
+    },
+  ];
+
+  const facades = [
+    ...config.domains.map((d) => ({
+      name: `${config.id}_${d.replace(/-/g, '_')}`,
+      ops: ['get_patterns', 'search', 'get_entry', 'capture', 'remove'],
+    })),
+    {
+      name: `${config.id}_core`,
+      ops: [
+        'search',
+        'vault_stats',
+        'list_all',
+        'health',
+        'identity',
+        'activate',
+        'inject_claude_md',
+        'setup',
+        'register',
+        'memory_search',
+        'memory_capture',
+        'memory_list',
+        'session_capture',
+        'export',
+        'create_plan',
+        'get_plan',
+        'approve_plan',
+        'update_task',
+        'complete_plan',
+        'record_feedback',
+        'rebuild_vocabulary',
+        'brain_stats',
+        'llm_status',
+      ],
+    },
+  ];
+
+  return {
+    agentDir,
+    files,
+    facades,
+    domains: config.domains,
+    persona: { name: config.name, role: config.role },
+  };
+}
+
+/**
+ * Scaffold a complete MCP agent project.
+ */
+export function scaffold(config: AgentConfig): ScaffoldResult {
+  const agentDir = join(config.outputDir, config.id);
+  const filesCreated: string[] = [];
+
+  if (existsSync(agentDir)) {
+    return {
+      success: false,
+      agentDir,
+      filesCreated: [],
+      domains: config.domains,
+      summary: `Directory already exists: ${agentDir}. Choose a different ID or remove the existing directory.`,
+    };
+  }
+
+  // Create directory structure
+  const dirs = [
+    '',
+    'scripts',
+    'src',
+    'src/facades',
+    'src/intelligence',
+    'src/intelligence/data',
+    'src/identity',
+    'src/activation',
+    'src/llm',
+    'src/__tests__',
+  ];
+
+  for (const dir of dirs) {
+    mkdirSync(join(agentDir, dir), { recursive: true });
+  }
+
+  // Write project config files
+  const projectFiles: Array<[string, string]> = [
+    ['package.json', generatePackageJson(config)],
+    ['tsconfig.json', generateTsconfig()],
+    ['vitest.config.ts', generateVitestConfig()],
+    ['.gitignore', 'node_modules/\ndist/\ncoverage/\n*.tsbuildinfo\n.env\n.DS_Store\n*.log\n'],
+    [
+      '.mcp.json',
+      JSON.stringify(
+        { mcpServers: { [config.id]: { command: 'node', args: ['dist/index.js'], cwd: '.' } } },
+        null,
+        2,
+      ),
+    ],
+    ['scripts/copy-assets.js', generateCopyAssetsScript()],
+    ['README.md', generateReadme(config)],
+    ['scripts/setup.sh', generateSetupScript(config)],
+  ];
+
+  for (const [path, content] of projectFiles) {
+    writeFileSync(join(agentDir, path), content, 'utf-8');
+    filesCreated.push(path);
+  }
+
+  // Make setup script executable
+  chmodSync(join(agentDir, 'scripts', 'setup.sh'), 0o755);
+
+  // Write source files
+  const sourceFiles: Array<[string, string]> = [
+    ['src/facades/core.facade.ts', generateCoreFacade(config)],
+    ['src/identity/persona.ts', generatePersona(config)],
+    ['src/activation/claude-md-content.ts', generateClaudeMdTemplate(config)],
+    ['src/activation/inject-claude-md.ts', generateInjectClaudeMd(config)],
+    ['src/activation/activate.ts', generateActivate(config)],
+    ['src/index.ts', generateEntryPoint(config)],
+    ['src/llm/llm-client.ts', generateLLMClient(config)],
+    ['src/__tests__/facades.test.ts', generateFacadesTest(config)],
+  ];
+
+  // Domain facades and empty data files
+  for (const domain of config.domains) {
+    sourceFiles.push([`src/facades/${domain}.facade.ts`, generateDomainFacade(config.id, domain)]);
+    sourceFiles.push([`src/intelligence/data/${domain}.json`, generateEmptyBundle(domain)]);
+  }
+
+  for (const [path, content] of sourceFiles) {
+    writeFileSync(join(agentDir, path), content, 'utf-8');
+    filesCreated.push(path);
+  }
+
+  const totalOps = config.domains.length * 5 + 24; // 5 per domain + 24 core (activation, registration, memory, session, export, planning, brain, llm)
+
+  // Register the agent as an MCP server in ~/.claude.json
+  const mcpReg = registerMcpServer(config.id, agentDir);
+
+  const summaryLines = [
+    `Created ${config.name} agent at ${agentDir}`,
+    `${config.domains.length + 1} facades with ${totalOps} operations`,
+    `${config.domains.length} empty knowledge domains ready for capture`,
+    `Intelligence layer (Brain) — TF-IDF scoring, auto-tagging, duplicate detection`,
+    `Activation system included — say "Hello, ${config.name}!" to activate`,
+    `1 test suite — facades (vault, brain, planner, llm tests provided by @soleri/core)`,
+  ];
+
+  if (mcpReg.registered) {
+    summaryLines.push(`MCP server registered in ${mcpReg.path}`);
+  } else {
+    summaryLines.push(`Warning: Failed to register MCP server in ${mcpReg.path}: ${mcpReg.error}`);
+  }
+
+  summaryLines.push(
+    '',
+    'Next steps:',
+    `  cd ${agentDir}`,
+    '  npm install && npm run build',
+    '  npm test              # verify all tests pass',
+    '  Restart Claude Code',
+    `  Say "Hello, ${config.name}!" to activate the persona`,
+  );
+
+  return {
+    success: true,
+    agentDir,
+    filesCreated,
+    domains: config.domains,
+    summary: summaryLines.join('\n'),
+  };
+}
+
+/**
+ * List agents in a directory.
+ */
+export function listAgents(parentDir: string): AgentInfo[] {
+  if (!existsSync(parentDir)) return [];
+
+  const agents: AgentInfo[] = [];
+  let entries: string[];
+  try {
+    entries = readdirSync(parentDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name);
+  } catch {
+    return [];
+  }
+
+  for (const name of entries) {
+    const dir = join(parentDir, name);
+    const pkgPath = join(dir, 'package.json');
+    if (!existsSync(pkgPath)) continue;
+
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      if (!pkg.name?.endsWith('-mcp')) continue;
+
+      const dataDir = join(dir, 'src', 'intelligence', 'data');
+      let domains: string[] = [];
+      try {
+        domains = readdirSync(dataDir)
+          .filter((f) => f.endsWith('.json'))
+          .map((f) => f.replace('.json', ''));
+      } catch {
+        /* empty */
+      }
+
+      agents.push({
+        id: name,
+        name: pkg.name.replace('-mcp', ''),
+        role: pkg.description || '',
+        path: dir,
+        domains,
+        hasNodeModules: existsSync(join(dir, 'node_modules')),
+        hasDistDir: existsSync(join(dir, 'dist')),
+      });
+    } catch {
+      /* skip non-agent directories */
+    }
+  }
+
+  return agents;
+}
+
+/**
+ * Register the agent as an MCP server in ~/.claude.json (User MCPs).
+ * Idempotent — updates existing entry if present.
+ */
+function registerMcpServer(
+  agentId: string,
+  agentDir: string,
+): { registered: boolean; path: string; error?: string } {
+  const claudeJsonPath = join(homedir(), '.claude.json');
+
+  try {
+    let config: Record<string, unknown> = {};
+
+    if (existsSync(claudeJsonPath)) {
+      config = JSON.parse(readFileSync(claudeJsonPath, 'utf-8'));
+    }
+
+    if (!config.mcpServers || typeof config.mcpServers !== 'object') {
+      config.mcpServers = {};
+    }
+
+    const servers = config.mcpServers as Record<string, unknown>;
+    servers[agentId] = {
+      type: 'stdio',
+      command: 'node',
+      args: [join(agentDir, 'dist', 'index.js')],
+      env: {},
+    };
+
+    writeFileSync(claudeJsonPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    return { registered: true, path: claudeJsonPath };
+  } catch (err) {
+    return {
+      registered: false,
+      path: claudeJsonPath,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+function generateEmptyBundle(domain: string): string {
+  return JSON.stringify(
+    {
+      domain,
+      version: '1.0.0',
+      entries: [],
+    },
+    null,
+    2,
+  );
+}
+
+function generateCopyAssetsScript(): string {
+  return [
+    "import { cpSync, existsSync, mkdirSync } from 'node:fs';",
+    "import { join, dirname } from 'node:path';",
+    "import { fileURLToPath } from 'node:url';",
+    '',
+    'const __dirname = dirname(fileURLToPath(import.meta.url));',
+    "const root = join(__dirname, '..');",
+    "const dist = join(root, 'dist');",
+    "const dataSource = join(root, 'src', 'intelligence', 'data');",
+    "const dataDest = join(dist, 'intelligence', 'data');",
+    '',
+    'if (existsSync(dataSource)) {',
+    '  mkdirSync(dataDest, { recursive: true });',
+    '  cpSync(dataSource, dataDest, { recursive: true });',
+    "  console.log('Copied intelligence data to dist/');",
+    '}',
+  ].join('\n');
+}

package/src/templates/activate.ts

@@ -0,0 +1,145 @@
+import type { AgentConfig } from '../types.js';
+
+/**
+ * Generates src/activation/activate.ts for a new agent.
+ * Provides the activate/deactivate system that returns full context
+ * to Claude — persona, guidelines, tool recommendations, setup status.
+ *
+ * Uses array-joined pattern because generated code contains template literals.
+ */
+export function generateActivate(config: AgentConfig): string {
+  const facadeId = config.id.replace(/-/g, '_');
+  const _marker = `${config.id}:mode`;
+
+  // Build tool recommendations from config domains
+  const toolRecLines: string[] = [];
+  for (const d of config.domains) {
+    const toolName = `${facadeId}_${d.replace(/-/g, '_')}`;
+    toolRecLines.push(`      { intent: 'search ${d}', facade: '${toolName}', op: 'search' },`);
+    toolRecLines.push(
+      `      { intent: '${d} patterns', facade: '${toolName}', op: 'get_patterns' },`,
+    );
+    toolRecLines.push(`      { intent: 'capture ${d}', facade: '${toolName}', op: 'capture' },`);
+  }
+
+  // Build behavioral guidelines from config principles
+  const guidelineLines = config.principles
+    .map((p) => {
+      const escaped = p.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+      return `      '${escaped}',`;
+    })
+    .join('\n');
+
+  return [
+    "import { join } from 'node:path';",
+    "import { homedir } from 'node:os';",
+    "import { PERSONA } from '../identity/persona.js';",
+    "import { hasAgentMarker } from './inject-claude-md.js';",
+    "import type { Vault, Planner, Plan } from '@soleri/core';",
+    '',
+    'export interface ActivationResult {',
+    '  activated: boolean;',
+    '  persona: {',
+    '    name: string;',
+    '    role: string;',
+    '    description: string;',
+    '    greeting: string;',
+    '  };',
+    '  guidelines: string[];',
+    '  tool_recommendations: Array<{ intent: string; facade: string; op: string }>;',
+    '  session_instruction: string;',
+    '  setup_status: {',
+    '    claude_md_injected: boolean;',
+    '    global_claude_md_injected: boolean;',
+    '    vault_has_entries: boolean;',
+    '    vault_entry_count: number;',
+    '  };',
+    '  executing_plans: Array<{ id: string; objective: string; tasks: number; completed: number }>;',
+    '  next_steps: string[];',
+    '}',
+    '',
+    'export interface DeactivationResult {',
+    '  deactivated: boolean;',
+    '  message: string;',
+    '}',
+    '',
+    '/**',
+    ` * Activate ${config.name} — returns full context for Claude to adopt the persona.`,
+    ' */',
+    'export function activateAgent(vault: Vault, projectPath: string, planner?: Planner): ActivationResult {',
+    '  // Check CLAUDE.md injection status (project-level and global)',
+    "  const projectClaudeMd = join(projectPath, 'CLAUDE.md');",
+    "  const globalClaudeMd = join(homedir(), '.claude', 'CLAUDE.md');",
+    '  const claudeMdInjected = hasAgentMarker(projectClaudeMd);',
+    '  const globalClaudeMdInjected = hasAgentMarker(globalClaudeMd);',
+    '',
+    '  // Check vault status',
+    '  const stats = vault.stats();',
+    '  const vaultHasEntries = stats.totalEntries > 0;',
+    '',
+    "  // Build next steps based on what's missing",
+    '  const nextSteps: string[] = [];',
+    '  if (!globalClaudeMdInjected && !claudeMdInjected) {',
+    `    nextSteps.push('No CLAUDE.md configured — run inject_claude_md with global: true for all projects, or without for this project only');`,
+    '  } else if (!globalClaudeMdInjected) {',
+    `    nextSteps.push('Global CLAUDE.md not configured — run inject_claude_md with global: true to enable activation in all projects');`,
+    '  }',
+    '  if (!vaultHasEntries) {',
+    "    nextSteps.push('Vault is empty — start capturing knowledge with the domain capture ops');",
+    '  }',
+    '  if (nextSteps.length === 0) {',
+    `    nextSteps.push('All set! ${config.name} is fully integrated.');`,
+    '  }',
+    '',
+    '  // Check for executing plans',
+    '  const executingPlans = planner ? planner.getExecuting().map((p) => ({',
+    '    id: p.id,',
+    '    objective: p.objective,',
+    '    tasks: p.tasks.length,',
+    "    completed: p.tasks.filter((t) => t.status === 'completed').length,",
+    '  })) : [];',
+    '  if (executingPlans.length > 0) {',
+    '    nextSteps.unshift(`${executingPlans.length} plan(s) in progress — use get_plan to review`);',
+    '  }',
+    '',
+    '  return {',
+    '    activated: true,',
+    '    persona: {',
+    '      name: PERSONA.name,',
+    '      role: PERSONA.role,',
+    '      description: PERSONA.description,',
+    '      greeting: PERSONA.greeting,',
+    '    },',
+    '    guidelines: [',
+    guidelineLines,
+    '    ],',
+    '    tool_recommendations: [',
+    `      { intent: 'health check', facade: '${facadeId}_core', op: 'health' },`,
+    `      { intent: 'search all', facade: '${facadeId}_core', op: 'search' },`,
+    `      { intent: 'vault stats', facade: '${facadeId}_core', op: 'vault_stats' },`,
+    ...toolRecLines,
+    '    ],',
+    `    session_instruction: 'You are now ' + PERSONA.name + ', a ' + PERSONA.role + '. Stay in character for the ENTIRE session. ' +`,
+    `      'Reference patterns from the knowledge vault. Provide concrete examples. Flag anti-patterns with severity.',`,
+    '    setup_status: {',
+    '      claude_md_injected: claudeMdInjected,',
+    '      global_claude_md_injected: globalClaudeMdInjected,',
+    '      vault_has_entries: vaultHasEntries,',
+    '      vault_entry_count: stats.totalEntries,',
+    '    },',
+    '    executing_plans: executingPlans,',
+    '    next_steps: nextSteps,',
+    '  };',
+    '}',
+    '',
+    '/**',
+    ` * Deactivate ${config.name} — drops persona for the session.`,
+    ' */',
+    'export function deactivateAgent(): DeactivationResult {',
+    '  return {',
+    '    deactivated: true,',
+    `    message: 'Goodbye! ' + PERSONA.name + ' persona deactivated. Reverting to default behavior.',`,
+    '  };',
+    '}',
+  ].join('\n');
+}

package/src/templates/claude-md-template.ts

@@ -0,0 +1,137 @@
+import type { AgentConfig } from '../types.js';
+
+/**
+ * Generates src/activation/claude-md-content.ts for a new agent.
+ * Returns the CLAUDE.md section content with activation triggers,
+ * facade tables, intent detection, and knowledge protocol.
+ *
+ * Strategy: build the markdown as plain strings, then escape into
+ * single-quoted TypeScript string literals. This avoids nested
+ * backtick/template-literal escaping nightmares entirely.
+ */
+export function generateClaudeMdTemplate(config: AgentConfig): string {
+  const facadeId = config.id.replace(/-/g, '_');
+  const marker = `${config.id}:mode`;
+  const bt = '`'; // backtick — keeps template clean
+
+  // Build the raw markdown lines (plain text, no escaping needed)
+  const mdLines: string[] = [
+    `<!-- ${marker} -->`,
+    '',
+    `# ${config.name} Mode`,
+    '',
+    `## ${config.name} Integration`,
+    '',
+    `**Activate:** "Hello, ${config.name}!" \u2192 ${bt}${facadeId}_core op:activate params:{ projectPath: "." }${bt}`,
+    `**Deactivate:** "Goodbye, ${config.name}!" \u2192 ${bt}${facadeId}_core op:activate params:{ deactivate: true }${bt}`,
+    '',
+    'On activation, adopt the returned persona. Stay in character until deactivated.',
+    '',
+    '## Session Start',
+    '',
+    `On every new session: ${bt}${facadeId}_core op:register params:{ projectPath: "." }${bt}`,
+    '',
+    '## Facades',
+    '',
+    '| Need | Facade | Op |',
+    '|------|--------|----|',
+    `| Health check | ${bt}${facadeId}_core${bt} | ${bt}health${bt} |`,
+    `| Search all | ${bt}${facadeId}_core${bt} | ${bt}search${bt} |`,
+    `| Vault stats | ${bt}${facadeId}_core${bt} | ${bt}vault_stats${bt} |`,
+    `| Identity | ${bt}${facadeId}_core${bt} | ${bt}identity${bt} |`,
+  ];
+
+  // Domain-specific facade rows
+  for (const d of config.domains) {
+    const toolName = `${facadeId}_${d.replace(/-/g, '_')}`;
+    mdLines.push(`| ${d} patterns | ${bt}${toolName}${bt} | ${bt}get_patterns${bt} |`);
+    mdLines.push(`| Search ${d} | ${bt}${toolName}${bt} | ${bt}search${bt} |`);
+    mdLines.push(`| Capture ${d} | ${bt}${toolName}${bt} | ${bt}capture${bt} |`);
+  }
+
+  // Memory + Session + Export + Brain + Planning rows
+  mdLines.push(
+    `| Memory search | ${bt}${facadeId}_core${bt} | ${bt}memory_search${bt} |`,
+    `| Memory capture | ${bt}${facadeId}_core${bt} | ${bt}memory_capture${bt} |`,
+    `| Memory list | ${bt}${facadeId}_core${bt} | ${bt}memory_list${bt} |`,
+    `| Session capture | ${bt}${facadeId}_core${bt} | ${bt}session_capture${bt} |`,
+    `| Export knowledge | ${bt}${facadeId}_core${bt} | ${bt}export${bt} |`,
+    `| Record feedback | ${bt}${facadeId}_core${bt} | ${bt}record_feedback${bt} |`,
+    `| Rebuild vocabulary | ${bt}${facadeId}_core${bt} | ${bt}rebuild_vocabulary${bt} |`,
+    `| Brain stats | ${bt}${facadeId}_core${bt} | ${bt}brain_stats${bt} |`,
+    `| LLM status | ${bt}${facadeId}_core${bt} | ${bt}llm_status${bt} |`,
+    `| Create plan | ${bt}${facadeId}_core${bt} | ${bt}create_plan${bt} |`,
+    `| Get plan | ${bt}${facadeId}_core${bt} | ${bt}get_plan${bt} |`,
+    `| Approve plan | ${bt}${facadeId}_core${bt} | ${bt}approve_plan${bt} |`,
+    `| Update task | ${bt}${facadeId}_core${bt} | ${bt}update_task${bt} |`,
+    `| Complete plan | ${bt}${facadeId}_core${bt} | ${bt}complete_plan${bt} |`,
+  );
+
+  mdLines.push(
+    '',
+    '## Intent Detection',
+    '',
+    '| Signal | Intent |',
+    '|--------|--------|',
+    '| Problem described ("broken", "janky", "weird") | FIX |',
+    '| Need expressed ("I need", "we should have") | BUILD |',
+    '| Quality questioned ("is this right?") | REVIEW |',
+    '| Advice sought ("how should I", "best way") | PLAN |',
+    '| Improvement requested ("make it faster") | IMPROVE |',
+    '',
+    '## Knowledge Protocol',
+    '',
+    'When seeking guidance: vault before codebase before web.',
+    '',
+    `1. Search vault \u2014 ${bt}${facadeId}_core op:search${bt}`,
+    '2. Codebase \u2014 only if vault has nothing',
+    '3. Web \u2014 last resort',
+    '',
+    '## Knowledge Capture',
+    '',
+    'When learning something that should persist, use the domain capture ops.',
+    '',
+    '## Session Capture',
+    '',
+    'A PreCompact hook is configured to call `session_capture` before context compaction.',
+    'This automatically preserves session summaries as memories for future sessions.',
+    `To manually capture: ${bt}${facadeId}_core op:session_capture params:{ summary: "..." }${bt}`,
+    '',
+    '## Planning',
+    '',
+    'For multi-step tasks, use the planning system:',
+    `1. Create: ${bt}${facadeId}_core op:create_plan params:{ objective: "...", scope: "...", tasks: [...] }${bt}`,
+    `2. Approve: ${bt}${facadeId}_core op:approve_plan params:{ planId: "...", startExecution: true }${bt}`,
+    `3. Track: ${bt}${facadeId}_core op:update_task params:{ planId: "...", taskId: "...", status: "completed" }${bt}`,
+    `4. Complete: ${bt}${facadeId}_core op:complete_plan params:{ planId: "..." }${bt}`,
+    '',
+    'Check activation response for recovered plans in `executing` state — remind the user.',
+    '',
+    `<!-- /${marker} -->`,
+  );
+
+  // Escape each markdown line for use in a single-quoted TS string literal
+  const quotedLines = mdLines.map((line) => {
+    const escaped = line.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+    return `    '${escaped}',`;
+  });
+
+  // Build the generated TypeScript file
+  const tsLines = [
+    '/**',
+    ` * CLAUDE.md content for ${config.name}.`,
+    ' * Generated by Soleri — do not edit manually.',
+    ' */',
+    'export function getClaudeMdContent(): string {',
+    '  return [',
+    ...quotedLines,
+    "  ].join('\\n');",
+    '}',
+    '',
+    'export function getClaudeMdMarker(): string {',
+    `  return '${marker}';`,
+    '}',
+  ];
+
+  return tsLines.join('\n');
+}