@soleri/forge 3.0.0 → 4.1.0

package/src/__tests__/scaffolder.test.ts

@@ -44,15 +44,16 @@ describe('Scaffolder', () => {
       expect(preview.domains).toEqual(['data-pipelines', 'data-quality', 'etl']);
       expect(preview.files.length).toBeGreaterThan(15);
 
-      // Should include README, setup script, and brain
+      // Should include README, setup script, and LLM client (static modules now in @soleri/core)
       const paths = preview.files.map((f) => f.path);
       expect(paths).toContain('README.md');
       expect(paths).toContain('scripts/setup.sh');
-      expect(paths).toContain('src/brain/brain.ts');
-      expect(paths).toContain('src/llm/types.ts');
       expect(paths).toContain('src/llm/llm-client.ts');
-      expect(paths).toContain('src/__tests__/llm.test.ts');
-      expect(paths).toContain('src/__tests__/brain.test.ts');
+      expect(paths).toContain('src/__tests__/facades.test.ts');
+      // Static modules should NOT be in preview (they live in @soleri/core now)
+      expect(paths).not.toContain('src/vault/vault.ts');
+      expect(paths).not.toContain('src/brain/brain.ts');
+      expect(paths).not.toContain('src/planning/planner.ts');
 
       // Should have domain facades + core facade
       expect(preview.facades).toHaveLength(4); // 3 domains + core
@@ -78,13 +79,14 @@ describe('Scaffolder', () => {
       const agentDir = join(tempDir, 'atlas');
 
       expect(existsSync(join(agentDir, 'src', 'facades'))).toBe(true);
-      expect(existsSync(join(agentDir, 'src', 'vault'))).toBe(true);
       expect(existsSync(join(agentDir, 'src', 'intelligence', 'data'))).toBe(true);
       expect(existsSync(join(agentDir, 'src', 'identity'))).toBe(true);
       expect(existsSync(join(agentDir, 'src', 'activation'))).toBe(true);
-      expect(existsSync(join(agentDir, 'src', 'planning'))).toBe(true);
-      expect(existsSync(join(agentDir, 'src', 'brain'))).toBe(true);
       expect(existsSync(join(agentDir, 'src', 'llm'))).toBe(true);
+      // Static module directories should NOT exist (now in @soleri/core)
+      expect(existsSync(join(agentDir, 'src', 'vault'))).toBe(false);
+      expect(existsSync(join(agentDir, 'src', 'planning'))).toBe(false);
+      expect(existsSync(join(agentDir, 'src', 'brain'))).toBe(false);
     });
 
     it('should create valid package.json', () => {
@@ -94,9 +96,11 @@ describe('Scaffolder', () => {
       expect(pkg.name).toBe('atlas-mcp');
       expect(pkg.type).toBe('module');
       expect(pkg.dependencies['@modelcontextprotocol/sdk']).toBeDefined();
-      expect(pkg.dependencies['better-sqlite3']).toBeDefined();
+      expect(pkg.dependencies['@soleri/core']).toBeDefined();
       expect(pkg.dependencies['zod']).toBeDefined();
       expect(pkg.dependencies['@anthropic-ai/sdk']).toBeDefined();
+      // better-sqlite3 is now transitive via @soleri/core
+      expect(pkg.dependencies['better-sqlite3']).toBeUndefined();
     });
 
     it('should create persona with correct config', () => {
@@ -120,8 +124,9 @@ describe('Scaffolder', () => {
       expect(files).toContain('data-quality.facade.ts');
       expect(files).toContain('etl.facade.ts');
       expect(files).toContain('core.facade.ts');
-      expect(files).toContain('facade-factory.ts');
-      expect(files).toContain('types.ts');
+      // facade-factory.ts and types.ts are now in @soleri/core
+      expect(files).not.toContain('facade-factory.ts');
+      expect(files).not.toContain('types.ts');
     });
 
     it('should create empty intelligence data files', () => {
@@ -139,7 +144,7 @@ describe('Scaffolder', () => {
       expect(bundle.entries).toEqual([]);
     });
 
-    it('should create entry point importing all facades', () => {
+    it('should create entry point importing from @soleri/core', () => {
       scaffold(testConfig);
       const entry = readFileSync(join(tempDir, 'atlas', 'src', 'index.ts'), 'utf-8');
 
@@ -153,6 +158,9 @@ describe('Scaffolder', () => {
       expect(entry).toContain('KeyPool');
       expect(entry).toContain('loadKeyPoolConfig');
       expect(entry).toContain('Hello');
+      // Should import shared modules from @soleri/core
+      expect(entry).toContain("from '@soleri/core'");
+      expect(entry).toContain("loadKeyPoolConfig('atlas')");
     });
 
     it('should create .mcp.json for client config', () => {
@@ -225,56 +233,34 @@ describe('Scaffolder', () => {
       expect(isExecutable).toBe(true);
     });
 
-    it('should create planner file', () => {
-      scaffold(testConfig);
-      const plannerPath = join(tempDir, 'atlas', 'src', 'planning', 'planner.ts');
-      expect(existsSync(plannerPath)).toBe(true);
-      const content = readFileSync(plannerPath, 'utf-8');
-      expect(content).toContain('class Planner');
-      expect(content).toContain('getExecuting');
-    });
-
-    it('should create LLM files', () => {
+    it('should create LLM client file importing from @soleri/core', () => {
       scaffold(testConfig);
       const llmDir = join(tempDir, 'atlas', 'src', 'llm');
-      expect(existsSync(join(llmDir, 'types.ts'))).toBe(true);
-      expect(existsSync(join(llmDir, 'utils.ts'))).toBe(true);
-      expect(existsSync(join(llmDir, 'key-pool.ts'))).toBe(true);
+      // Only llm-client.ts should exist (types, utils, key-pool are in @soleri/core)
       expect(existsSync(join(llmDir, 'llm-client.ts'))).toBe(true);
+      expect(existsSync(join(llmDir, 'types.ts'))).toBe(false);
+      expect(existsSync(join(llmDir, 'utils.ts'))).toBe(false);
+      expect(existsSync(join(llmDir, 'key-pool.ts'))).toBe(false);
 
       const client = readFileSync(join(llmDir, 'llm-client.ts'), 'utf-8');
       expect(client).toContain('class LLMClient');
       expect(client).toContain('class ModelRouter');
       expect(client).toContain('.atlas');
-
-      const keyPool = readFileSync(join(llmDir, 'key-pool.ts'), 'utf-8');
-      expect(keyPool).toContain('class KeyPool');
-      expect(keyPool).toContain('.atlas');
-    });
-
-    it('should create brain file with intelligence layer', () => {
-      scaffold(testConfig);
-      const brainPath = join(tempDir, 'atlas', 'src', 'brain', 'brain.ts');
-      expect(existsSync(brainPath)).toBe(true);
-      const content = readFileSync(brainPath, 'utf-8');
-      expect(content).toContain('class Brain');
-      expect(content).toContain('intelligentSearch');
-      expect(content).toContain('enrichAndCapture');
-      expect(content).toContain('recordFeedback');
-      expect(content).toContain('rebuildVocabulary');
+      expect(client).toContain("from '@soleri/core'");
     });
 
-    it('should create test files', () => {
+    it('should only create facades test file (static tests in @soleri/core)', () => {
       scaffold(testConfig);
       const testsDir = join(tempDir, 'atlas', 'src', '__tests__');
       const files = readdirSync(testsDir);
 
-      expect(files).toContain('vault.test.ts');
-      expect(files).toContain('loader.test.ts');
       expect(files).toContain('facades.test.ts');
-      expect(files).toContain('planner.test.ts');
-      expect(files).toContain('brain.test.ts');
-      expect(files).toContain('llm.test.ts');
+      // Static module tests are now in @soleri/core
+      expect(files).not.toContain('vault.test.ts');
+      expect(files).not.toContain('loader.test.ts');
+      expect(files).not.toContain('planner.test.ts');
+      expect(files).not.toContain('brain.test.ts');
+      expect(files).not.toContain('llm.test.ts');
     });
 
     it('should generate facade tests referencing all domains', () => {
@@ -289,6 +275,8 @@ describe('Scaffolder', () => {
       expect(facadesTest).toContain('atlas_etl');
       expect(facadesTest).toContain('atlas_core');
       expect(facadesTest).toContain('createDataPipelinesFacade');
+      // Should import shared modules from @soleri/core
+      expect(facadesTest).toContain("from '@soleri/core'");
       // Activation ops should be tested
       expect(facadesTest).toContain('activate');
       expect(facadesTest).toContain('inject_claude_md');

package/src/domain-manager.ts

@@ -0,0 +1,168 @@
+/**
+ * Domain manager — add new knowledge domains to existing agents.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { generateDomainFacade } from './templates/domain-facade.js';
+import { generateVaultOnlyDomainFacade } from './knowledge-installer.js';
+import { patchIndexTs, patchClaudeMdContent } from './patching.js';
+import type { AddDomainResult } from './types.js';
+
+interface AddDomainParams {
+  agentPath: string;
+  domain: string;
+  noBuild?: boolean;
+}
+
+/**
+ * Add a new knowledge domain to an existing agent.
+ *
+ * Steps:
+ * 1. Validate agent path and domain name
+ * 2. Create empty intelligence bundle
+ * 3. Generate domain facade
+ * 4. Patch src/index.ts with import + registration
+ * 5. Patch src/activation/claude-md-content.ts with facade table rows
+ * 6. Rebuild (unless noBuild)
+ */
+export async function addDomain(params: AddDomainParams): Promise<AddDomainResult> {
+  const { agentPath, domain, noBuild = false } = params;
+  const warnings: string[] = [];
+
+  // ── Validate agent ──
+
+  const pkgPath = join(agentPath, 'package.json');
+  if (!existsSync(pkgPath)) {
+    return fail(agentPath, domain, 'No package.json found — is this an agent project?');
+  }
+
+  let pkg: Record<string, unknown>;
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+  } catch {
+    return fail(agentPath, domain, 'Failed to parse package.json — is it valid JSON?');
+  }
+  const pkgName: string = (pkg.name as string) ?? '';
+  if (!pkgName.endsWith('-mcp')) {
+    return fail(agentPath, domain, `package.json name "${pkgName}" does not end with -mcp`);
+  }
+
+  const agentId = pkgName.replace(/-mcp$/, '');
+
+  // ── Validate domain name ──
+
+  if (!/^[a-z][a-z0-9-]*$/.test(domain)) {
+    return fail(agentPath, domain, `Invalid domain name "${domain}" — must be kebab-case`);
+  }
+
+  // ── Check if domain already exists ──
+
+  const dataDir = join(agentPath, 'src', 'intelligence', 'data');
+  if (!existsSync(dataDir)) {
+    return fail(agentPath, domain, 'src/intelligence/data/ directory not found');
+  }
+
+  const bundlePath = join(dataDir, `${domain}.json`);
+  if (existsSync(bundlePath)) {
+    return fail(agentPath, domain, `Domain "${domain}" already exists`);
+  }
+
+  const hasBrain = existsSync(join(agentPath, 'src', 'brain'));
+
+  // ── Step 1: Create empty bundle ──
+
+  const emptyBundle = JSON.stringify({ domain, version: '1.0.0', entries: [] }, null, 2);
+  writeFileSync(bundlePath, emptyBundle, 'utf-8');
+
+  // Also write to dist if it exists
+  const distDataDir = join(agentPath, 'dist', 'intelligence', 'data');
+  if (existsSync(join(agentPath, 'dist'))) {
+    mkdirSync(distDataDir, { recursive: true });
+    writeFileSync(join(distDataDir, `${domain}.json`), emptyBundle, 'utf-8');
+  }
+
+  // ── Step 2: Generate facade ──
+
+  const facadesDir = join(agentPath, 'src', 'facades');
+  const facadePath = join(facadesDir, `${domain}.facade.ts`);
+
+  if (existsSync(facadePath)) {
+    warnings.push(`Facade ${domain}.facade.ts already exists — skipped`);
+  } else {
+    const facadeCode = hasBrain
+      ? generateDomainFacade(agentId, domain)
+      : generateVaultOnlyDomainFacade(agentId, domain);
+    writeFileSync(facadePath, facadeCode, 'utf-8');
+  }
+
+  // ── Step 3: Patch src/index.ts ──
+
+  const indexPath = join(agentPath, 'src', 'index.ts');
+  if (existsSync(indexPath)) {
+    const patched = patchIndexTs(readFileSync(indexPath, 'utf-8'), [domain], hasBrain);
+    if (patched !== null) {
+      writeFileSync(indexPath, patched, 'utf-8');
+    } else {
+      warnings.push('Could not patch src/index.ts — anchor patterns not found');
+    }
+  }
+
+  // ── Step 4: Patch claude-md-content.ts ──
+
+  const claudeMdPath = join(agentPath, 'src', 'activation', 'claude-md-content.ts');
+  if (existsSync(claudeMdPath)) {
+    const patched = patchClaudeMdContent(readFileSync(claudeMdPath, 'utf-8'), agentId, [domain]);
+    if (patched !== null) {
+      writeFileSync(claudeMdPath, patched, 'utf-8');
+    } else {
+      warnings.push('Could not patch claude-md-content.ts — anchor not found');
+    }
+  }
+
+  // ── Step 5: Build ──
+
+  let buildOutput = '';
+  if (!noBuild) {
+    try {
+      buildOutput = execFileSync('npm', ['run', 'build'], {
+        cwd: agentPath,
+        encoding: 'utf-8',
+        timeout: 60_000,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+    } catch (err) {
+      const stderr = (err as { stderr?: string }).stderr ?? '';
+      buildOutput = `Build failed: ${stderr}`;
+      warnings.push('Build failed — check buildOutput for details');
+    }
+  }
+
+  const hasPatchFailure = warnings.some(
+    (w) => w.includes('Could not patch') || w.includes('Build failed'),
+  );
+
+  return {
+    success: !hasPatchFailure,
+    agentPath,
+    domain,
+    agentId,
+    facadeGenerated: !existsSync(facadePath) || !warnings.some((w) => w.includes('already exists')),
+    buildOutput,
+    warnings,
+    summary: `Added domain "${domain}" to ${agentId}${warnings.length > 0 ? ` (${warnings.length} warning(s))` : ''}`,
+  };
+}
+
+function fail(agentPath: string, domain: string, message: string): AddDomainResult {
+  return {
+    success: false,
+    agentPath,
+    domain,
+    agentId: '',
+    facadeGenerated: false,
+    buildOutput: '',
+    warnings: [message],
+    summary: message,
+  };
+}

package/src/facades/forge.facade.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { scaffold, previewScaffold, listAgents } from '../scaffolder.js';
 import { AgentConfigSchema } from '../types.js';
 import { installKnowledge } from '../knowledge-installer.js';
+import { addDomain } from '../domain-manager.js';
 
 interface OpDef {
   name: string;
@@ -147,4 +148,21 @@ export const forgeOps: OpDef[] = [
         params as { agentPath: string; bundlePath: string; generateFacades?: boolean },
       ),
   },
+  {
+    name: 'add_domain',
+    description:
+      'Add a new knowledge domain to an existing MCP agent. ' +
+      'Creates an empty bundle, generates a domain facade, patches index.ts and claude-md-content.ts, then rebuilds.',
+    schema: z.object({
+      agentPath: z.string().describe('Absolute path to the target agent project'),
+      domain: z.string().describe('Domain name in kebab-case (e.g., "security", "api-design")'),
+      noBuild: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Skip the build step after adding the domain'),
+    }),
+    handler: async (params) =>
+      addDomain(params as { agentPath: string; domain: string; noBuild?: boolean }),
+  },
 ];

package/src/knowledge-installer.ts

@@ -9,6 +9,7 @@ import {
 import { join, basename } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { generateDomainFacade, pascalCase, capitalize } from './templates/domain-facade.js';
+import { patchIndexTs, patchClaudeMdContent } from './patching.js';
 import type { InstallKnowledgeResult } from './types.js';
 
 // ---------- Bundle validation types ----------
@@ -149,7 +150,7 @@ export function create${pascalCase(domain)}Facade(vault: Vault): FacadeConfig {
 
 // ---------- Main installer ----------
 
-export interface InstallKnowledgeParams {
+interface InstallKnowledgeParams {
   agentPath: string;
   bundlePath: string;
   generateFacades?: boolean;
@@ -413,120 +414,4 @@ function validateBundle(bundle: Bundle, file: string): string[] {
   return issues;
 }
 
-// ---------- Source file patching ----------
-
-/**
- * Patch the agent's src/index.ts to add imports and facade registrations
- * for new domains.
- *
- * Anchor patterns:
- * - Import: insert before `import { createCoreFacade }`
- * - Facade array: insert before `createCoreFacade(`
- */
-export function patchIndexTs(
-  source: string,
-  newDomains: string[],
-  hasBrain: boolean,
-): string | null {
-  // Filter out domains whose imports already exist (idempotent)
-  const domainsToImport = newDomains.filter((d) => {
-    const fn = `create${pascalCase(d)}Facade`;
-    return !source.includes(`import { ${fn} }`);
-  });
-
-  // Filter out domains whose facade calls already exist
-  const domainsToRegister = newDomains.filter((d) => {
-    const fn = `create${pascalCase(d)}Facade(`;
-    return !source.includes(fn);
-  });
-
-  // Nothing to patch
-  if (domainsToImport.length === 0 && domainsToRegister.length === 0) {
-    return source;
-  }
-
-  let patched = source;
-
-  // ── Insert imports ──
-  if (domainsToImport.length > 0) {
-    const importAnchor = /^(import \{ createCoreFacade \}.*$)/m;
-    if (!importAnchor.test(patched)) return null;
-
-    const newImports = domainsToImport
-      .map((d) => {
-        const fn = `create${pascalCase(d)}Facade`;
-        return `import { ${fn} } from './facades/${d}.facade.js';`;
-      })
-      .join('\n');
-
-    patched = patched.replace(importAnchor, `${newImports}\n$1`);
-  }
-
-  // ── Insert facade creations ──
-  if (domainsToRegister.length > 0) {
-    const facadeAnchor = /^(\s+createCoreFacade\()/m;
-    if (!facadeAnchor.test(patched)) return null;
-
-    const newCreations = domainsToRegister
-      .map((d) => {
-        const fn = `create${pascalCase(d)}Facade`;
-        const args = hasBrain ? 'vault, brain' : 'vault';
-        return `    ${fn}(${args}),`;
-      })
-      .join('\n');
-
-    patched = patched.replace(facadeAnchor, `${newCreations}\n$1`);
-  }
-
-  return patched;
-}
-
-/**
- * Patch the agent's src/activation/claude-md-content.ts to add
- * facade table rows for new domains.
- *
- * Primary anchor: line containing `| Memory search |` (newer agents)
- * Fallback anchor: line containing `## Intent Detection` (older agents without memory/brain rows)
- */
-export function patchClaudeMdContent(
-  source: string,
-  agentId: string,
-  newDomains: string[],
-): string | null {
-  const facadeId = agentId.replace(/-/g, '_');
-  const bt = '`';
-
-  // Filter out domains whose rows already exist (idempotent)
-  const domainsToAdd = newDomains.filter((d) => {
-    const toolName = `${facadeId}_${d.replace(/-/g, '_')}`;
-    return !source.includes(`${toolName}`);
-  });
-
-  if (domainsToAdd.length === 0) return source;
-
-  // Try primary anchor first, then fallback for older agents
-  let anchorIdx = source.indexOf("'| Memory search |");
-  if (anchorIdx === -1) {
-    // Older agents: insert before the empty line preceding ## Intent Detection
-    anchorIdx = source.indexOf("'## Intent Detection'");
-    if (anchorIdx === -1) return null;
-    // Back up to include the preceding empty string line ('',)
-    const emptyLineIdx = source.lastIndexOf("'',", anchorIdx);
-    if (emptyLineIdx !== -1 && anchorIdx - emptyLineIdx < 20) {
-      // Find the start of that line (the indentation)
-      const lineStart = source.lastIndexOf('\n', emptyLineIdx);
-      anchorIdx = lineStart === -1 ? emptyLineIdx : lineStart + 1;
-    }
-  }
-
-  const newRows = domainsToAdd.flatMap((d) => {
-    const toolName = `${facadeId}_${d.replace(/-/g, '_')}`;
-    return [
-      `    '| ${d} patterns | ${bt}${toolName}${bt} | ${bt}get_patterns${bt} |',`,
-      `    '| Search ${d} | ${bt}${toolName}${bt} | ${bt}search${bt} |',`,
-      `    '| Capture ${d} | ${bt}${toolName}${bt} | ${bt}capture${bt} |',`,
-    ];
-  });
-
-  return source.slice(0, anchorIdx) + newRows.join('\n') + '\n' + source.slice(anchorIdx);
-}
+// patching functions (patchIndexTs, patchClaudeMdContent) are in patching.ts

package/src/lib.ts

@@ -0,0 +1,19 @@
+/**
+ * @soleri/forge — Public API
+ *
+ * Import this for programmatic access to forge functions.
+ * The main index.ts starts the MCP server — use this for library usage.
+ */
+export { scaffold, previewScaffold, listAgents } from './scaffolder.js';
+export { installKnowledge, generateVaultOnlyDomainFacade } from './knowledge-installer.js';
+export { addDomain } from './domain-manager.js';
+export { patchIndexTs, patchClaudeMdContent } from './patching.js';
+export type {
+  AgentConfig,
+  ScaffoldResult,
+  ScaffoldPreview,
+  AgentInfo,
+  InstallKnowledgeResult,
+  AddDomainResult,
+} from './types.js';
+export { AgentConfigSchema } from './types.js';

package/src/patching.ts

@@ -0,0 +1,123 @@
+/**
+ * Source file patching utilities — shared between knowledge-installer and domain-manager.
+ *
+ * These functions modify an agent's src/index.ts and src/activation/claude-md-content.ts
+ * to register new domain facades and their CLAUDE.md table rows.
+ */
+import { pascalCase } from './templates/domain-facade.js';
+
+/**
+ * Patch the agent's src/index.ts to add imports and facade registrations
+ * for new domains.
+ *
+ * Anchor patterns:
+ * - Import: insert before `import { createCoreFacade }`
+ * - Facade array: insert before `createCoreFacade(`
+ */
+export function patchIndexTs(
+  source: string,
+  newDomains: string[],
+  hasBrain: boolean,
+): string | null {
+  // Filter out domains whose imports already exist (idempotent)
+  const domainsToImport = newDomains.filter((d) => {
+    const fn = `create${pascalCase(d)}Facade`;
+    return !source.includes(`import { ${fn} }`);
+  });
+
+  // Filter out domains whose facade calls already exist
+  const domainsToRegister = newDomains.filter((d) => {
+    const fn = `create${pascalCase(d)}Facade(`;
+    return !source.includes(fn);
+  });
+
+  // Nothing to patch
+  if (domainsToImport.length === 0 && domainsToRegister.length === 0) {
+    return source;
+  }
+
+  let patched = source;
+
+  // ── Insert imports ──
+  if (domainsToImport.length > 0) {
+    const importAnchor = /^(import \{ createCoreFacade \}.*$)/m;
+    if (!importAnchor.test(patched)) return null;
+
+    const newImports = domainsToImport
+      .map((d) => {
+        const fn = `create${pascalCase(d)}Facade`;
+        return `import { ${fn} } from './facades/${d}.facade.js';`;
+      })
+      .join('\n');
+
+    patched = patched.replace(importAnchor, `${newImports}\n$1`);
+  }
+
+  // ── Insert facade creations ──
+  if (domainsToRegister.length > 0) {
+    const facadeAnchor = /^(\s+createCoreFacade\()/m;
+    if (!facadeAnchor.test(patched)) return null;
+
+    const newCreations = domainsToRegister
+      .map((d) => {
+        const fn = `create${pascalCase(d)}Facade`;
+        const args = hasBrain ? 'vault, brain' : 'vault';
+        return `    ${fn}(${args}),`;
+      })
+      .join('\n');
+
+    patched = patched.replace(facadeAnchor, `${newCreations}\n$1`);
+  }
+
+  return patched;
+}
+
+/**
+ * Patch the agent's src/activation/claude-md-content.ts to add
+ * facade table rows for new domains.
+ *
+ * Primary anchor: line containing `| Memory search |` (newer agents)
+ * Fallback anchor: line containing `## Intent Detection` (older agents without memory/brain rows)
+ */
+export function patchClaudeMdContent(
+  source: string,
+  agentId: string,
+  newDomains: string[],
+): string | null {
+  const facadeId = agentId.replace(/-/g, '_');
+  const bt = '`';
+
+  // Filter out domains whose rows already exist (idempotent)
+  const domainsToAdd = newDomains.filter((d) => {
+    const toolName = `${facadeId}_${d.replace(/-/g, '_')}`;
+    return !source.includes(`${toolName}`);
+  });
+
+  if (domainsToAdd.length === 0) return source;
+
+  // Try primary anchor first, then fallback for older agents
+  let anchorIdx = source.indexOf("'| Memory search |");
+  if (anchorIdx === -1) {
+    // Older agents: insert before the empty line preceding ## Intent Detection
+    anchorIdx = source.indexOf("'## Intent Detection'");
+    if (anchorIdx === -1) return null;
+    // Back up to include the preceding empty string line ('',)
+    const emptyLineIdx = source.lastIndexOf("'',", anchorIdx);
+    if (emptyLineIdx !== -1 && anchorIdx - emptyLineIdx < 20) {
+      // Find the start of that line (the indentation)
+      const lineStart = source.lastIndexOf('\n', emptyLineIdx);
+      anchorIdx = lineStart === -1 ? emptyLineIdx : lineStart + 1;
+    }
+  }
+
+  const newRows = domainsToAdd.flatMap((d) => {
+    const toolName = `${facadeId}_${d.replace(/-/g, '_')}`;
+    return [
+      `    '| ${d} patterns | ${bt}${toolName}${bt} | ${bt}get_patterns${bt} |',`,
+      `    '| Search ${d} | ${bt}${toolName}${bt} | ${bt}search${bt} |',`,
+      `    '| Capture ${d} | ${bt}${toolName}${bt} | ${bt}capture${bt} |',`,
+    ];
+  });
+
+  return source.slice(0, anchorIdx) + newRows.join('\n') + '\n' + source.slice(anchorIdx);
+}