@soleri/forge 5.14.10 → 8.0.0

package/src/templates/entry-point.ts

@@ -1,5 +1,21 @@
 import type { AgentConfig } from '../types.js';
 
+/** Generate vault connection code for linked vaults. */
+function generateVaultConnections(config: AgentConfig): string {
+  if (!config.vaults?.length) return '';
+  const lines = ['', '  // ─── Linked vaults ──────────────────────────────────────────────'];
+  for (const v of config.vaults) {
+    lines.push(
+      `  try { runtime.vaultManager.connect('${v.name}', '${v.path}', ${v.priority ?? 0.5}); } catch { /* already connected or unavailable */ }`,
+    );
+  }
+  lines.push(
+    `  console.error(\`[\${tag}] Connected ${config.vaults.length} linked vault(s): ${config.vaults.map((v) => v.name).join(', ')}\`);`,
+    '',
+  );
+  return lines.join('\n');
+}
+
 /**
  * Generate the main index.ts entry point for the agent.
  *
@@ -9,6 +25,7 @@ import type { AgentConfig } from '../types.js';
  */
 export function generateEntryPoint(config: AgentConfig): string {
   const domainsLiteral = JSON.stringify(config.domains);
+  const hasDomainPacks = config.domainPacks && config.domainPacks.length > 0;
 
   return `#!/usr/bin/env node
 
@@ -24,12 +41,14 @@ import {
   registerAllFacades,
   seedDefaultPlaybooks,
   wrapWithMiddleware,
+  CapabilityRegistry,
+  loadAllFlows,
 } from '@soleri/core';
-import type { OpDefinition, AgentExtensions } from '@soleri/core';
+import type { OpDefinition, AgentExtensions } from '@soleri/core';${hasDomainPacks ? `\nimport { loadDomainPacksFromConfig, createPackRuntime } from '@soleri/core';` : ''}
 import { z } from 'zod';
 import { PERSONA, getPersonaPrompt } from './identity/persona.js';
 import { activateAgent, deactivateAgent } from './activation/activate.js';
-import { injectClaudeMd, injectClaudeMdGlobal, hasAgentMarker } from './activation/inject-claude-md.js';
+import { injectClaudeMd, injectClaudeMdGlobal, hasAgentMarker, injectAgentsMd, injectAgentsMdGlobal, hasAgentMarkerInAgentsMd } from './activation/inject-claude-md.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -37,11 +56,11 @@ async function main(): Promise<void> {
   // ─── Runtime — vault, brain, planner, curator, LLM, key pools ───
   const runtime = createAgentRuntime({
     agentId: '${config.id}',
-    dataDir: join(__dirname, 'intelligence', 'data'),
+    dataDir: join(__dirname, 'intelligence', 'data'),${config.sharedVaultPath ? `\n    sharedVaultPath: '${config.sharedVaultPath}',` : ''}${config.cognee ? `\n    cognee: true,` : ''}
   });
 
   const tag = PERSONA.name.toLowerCase();
-
+${generateVaultConnections(config)}
   // Seed built-in playbooks (idempotent)
   const seedResult = seedDefaultPlaybooks(runtime.vault);
   if (seedResult.seeded > 0) {
@@ -120,9 +139,24 @@ async function main(): Promise<void> {
         return injectClaudeMd((params.projectPath as string) ?? '.');
       },
     },
+    {
+      name: 'inject_agents_md',
+      description: 'Inject agent sections into AGENTS.md — project-level or global (~/.config/opencode/AGENTS.md). For OpenCode and Codex. Idempotent.',
+      auth: 'write',
+      schema: z.object({
+        projectPath: z.string().optional().default('.'),
+        global: z.boolean().optional().describe('If true, inject into ~/.config/opencode/AGENTS.md instead of project-level'),
+      }),
+      handler: async (params) => {
+        if (params.global) {
+          return injectAgentsMdGlobal();
+        }
+        return injectAgentsMd((params.projectPath as string) ?? '.');
+      },
+    },
     {
       name: 'setup',
-      description: 'Check setup status — CLAUDE.md configured? Vault has entries? What to do next?',
+      description: 'Check setup status — CLAUDE.md configured? AGENTS.md configured? Vault has entries? What to do next?',
       auth: 'read',
       schema: z.object({
         projectPath: z.string().optional().default('.'),
@@ -135,12 +169,19 @@ async function main(): Promise<void> {
 
         const projectClaudeMd = joinPath(projectPath, 'CLAUDE.md');
         const globalClaudeMd = joinPath(homedir(), '.claude', 'CLAUDE.md');
+        const projectAgentsMd = joinPath(projectPath, 'AGENTS.md');
+        const globalAgentsMd = joinPath(homedir(), '.config', 'opencode', 'AGENTS.md');
 
         const projectExists = existsSync(projectClaudeMd);
         const projectHasAgent = hasAgentMarker(projectClaudeMd);
         const globalExists = existsSync(globalClaudeMd);
         const globalHasAgent = hasAgentMarker(globalClaudeMd);
 
+        const agentsMdProjectExists = existsSync(projectAgentsMd);
+        const agentsMdProjectHasAgent = hasAgentMarkerInAgentsMd(projectAgentsMd);
+        const agentsMdGlobalExists = existsSync(globalAgentsMd);
+        const agentsMdGlobalHasAgent = hasAgentMarkerInAgentsMd(globalAgentsMd);
+
         const s = runtime.vault.stats();
 
         const recommendations: string[] = [];
@@ -149,6 +190,9 @@ async function main(): Promise<void> {
         } else if (!globalHasAgent) {
           recommendations.push('Global ~/.claude/CLAUDE.md not configured — run inject_claude_md with global: true to enable in all projects');
         }
+        if (!agentsMdGlobalHasAgent && !agentsMdProjectHasAgent) {
+          recommendations.push('No AGENTS.md configured — run inject_agents_md for OpenCode/Codex support');
+        }
         if (s.totalEntries === 0) {
           recommendations.push('Vault is empty — add intelligence data or capture knowledge via domain facades');
         }
@@ -193,6 +237,10 @@ async function main(): Promise<void> {
             project: { exists: projectExists, has_agent_section: projectHasAgent },
             global: { exists: globalExists, has_agent_section: globalHasAgent },
           },
+          agents_md: {
+            project: { exists: agentsMdProjectExists, has_agent_section: agentsMdProjectHasAgent },
+            global: { exists: agentsMdGlobalExists, has_agent_section: agentsMdGlobalHasAgent },
+          },
           vault: { entries: s.totalEntries, domains: Object.keys(s.byDomain) },
           hooks: hookStatus,
           recommendations,
@@ -209,7 +257,43 @@ async function main(): Promise<void> {
     ops: agentOps,
   };
 
-  const domainFacades = createDomainFacades(runtime, '${config.id}', ${domainsLiteral});
+${
+  hasDomainPacks
+    ? `  // ─── Domain packs ─────────────────────────────────────────────
+  const domainPacks = await loadDomainPacksFromConfig(${JSON.stringify(config.domainPacks)});
+  console.error(\`[\${tag}] Loaded \${domainPacks.length} domain packs\`);
+  for (const pack of domainPacks) {
+    if (pack.onActivate) await pack.onActivate(runtime);
+  }
+
+  // ─── Capability Registry ─────────────────────────────────────
+  const capabilityRegistry = new CapabilityRegistry();
+  const packRuntime = createPackRuntime(runtime);
+
+  // Register domain pack capabilities
+  for (const pack of domainPacks) {
+    if (pack.capabilities) {
+      const handlers = pack.capabilities(packRuntime);
+      // Use pack manifest capabilities if available, otherwise derive from handler keys
+      const definitions = (pack as Record<string, unknown>).manifest
+        ? ((pack as Record<string, unknown>).manifest as { capabilities?: Array<{ id: string; description: string; provides: string[]; requires: string[] }> }).capabilities ?? []
+        : [...handlers.keys()].map(id => ({ id, description: id, provides: [], requires: [] }));
+      capabilityRegistry.registerPack(pack.name, definitions, handlers, 50);
+    }
+  }
+
+  // Validate flows against installed capabilities
+  const flows = loadAllFlows();
+  for (const flow of flows) {
+    const validation = capabilityRegistry.validateFlow(flow);
+    if (validation.missing.length > 0) {
+      console.error(\`[\${tag}] Flow \${flow.id}: \${validation.missing.length} capabilities degraded (\${validation.missing.join(', ')})\`);
+    }
+  }
+  console.error(\`[\${tag}] Capability registry: \${capabilityRegistry.size} capabilities from \${capabilityRegistry.packCount} pack(s)\`);
+`
+    : ''
+}  const domainFacades = createDomainFacades(runtime, '${config.id}', ${domainsLiteral}${hasDomainPacks ? `, domainPacks` : ''});
 
   // ─── User extensions (auto-discovered from src/extensions/) ────
   let extensions: AgentExtensions = {};

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

@@ -44,6 +44,10 @@ export function generateInjectClaudeMd(config: AgentConfig): string {
     '  if (existing.includes(startMarker)) {',
     '    const startIdx = existing.indexOf(startMarker);',
     '    const endIdx = existing.indexOf(endMarker);',
+    '    if (endIdx !== -1) {',
+    '      const currentBlock = existing.slice(startIdx, endIdx + endMarker.length);',
+    "      if (currentBlock === content.trim()) return 'skipped';",
+    '    }',
     '    if (endIdx === -1) {',
     "      const updated = existing.slice(0, startIdx) + content + '\\n' + existing.slice(startIdx + startMarker.length);",
     "      writeFileSync(filePath, updated, 'utf-8');",
@@ -166,5 +170,54 @@ export function generateInjectClaudeMd(config: AgentConfig): string {
     "  const content = readFileSync(filePath, 'utf-8');",
     "  return content.includes('<!-- ' + getEngineRulesMarker() + ' -->');",
     '}',
+    '',
+    '// ─── AGENTS.md support (OpenCode, Codex) ──────────────────────',
+    '',
+    '/**',
+    ' * Inject agent sections into a project AGENTS.md.',
+    ' * Same engine rules + agent block as CLAUDE.md, targeting AGENTS.md instead.',
+    ' * OpenCode reads AGENTS.md as its primary instruction file.',
+    ' */',
+    'export function injectAgentsMd(projectPath: string): InjectResult {',
+    "  return injectIntoFile(join(projectPath, 'AGENTS.md'));",
+    '}',
+    '',
+    '/**',
+    ' * Inject into the global ~/.config/opencode/AGENTS.md.',
+    " * Creates ~/.config/opencode/ directory if it doesn't exist.",
+    ' * This makes the activation phrase work in any OpenCode project.',
+    ' */',
+    'export function injectAgentsMdGlobal(): InjectResult {',
+    "  const opencodeDir = join(homedir(), '.config', 'opencode');",
+    '  if (!existsSync(opencodeDir)) {',
+    '    mkdirSync(opencodeDir, { recursive: true });',
+    '  }',
+    "  return injectIntoFile(join(opencodeDir, 'AGENTS.md'));",
+    '}',
+    '',
+    '/**',
+    ' * Remove agent section from a project AGENTS.md.',
+    ' */',
+    'export function removeAgentsMd(projectPath: string): { removed: boolean; path: string } {',
+    "  const filePath = join(projectPath, 'AGENTS.md');",
+    '  return { removed: removeBlock(filePath, getClaudeMdMarker()), path: filePath };',
+    '}',
+    '',
+    '/**',
+    ' * Remove agent section from the global ~/.config/opencode/AGENTS.md.',
+    ' */',
+    'export function removeAgentsMdGlobal(): { removed: boolean; path: string } {',
+    "  const filePath = join(homedir(), '.config', 'opencode', 'AGENTS.md');",
+    '  return { removed: removeBlock(filePath, getClaudeMdMarker()), path: filePath };',
+    '}',
+    '',
+    '/**',
+    ' * Check if the agent marker exists in an AGENTS.md file.',
+    ' */',
+    'export function hasAgentMarkerInAgentsMd(filePath: string): boolean {',
+    '  if (!existsSync(filePath)) return false;',
+    "  const content = readFileSync(filePath, 'utf-8');",
+    `  return content.includes('<!-- ${marker} -->');`,
+    '}',
   ].join('\n');
 }

package/src/templates/package-json.ts

@@ -2,7 +2,7 @@ import type { AgentConfig } from '../types.js';
 
 export function generatePackageJson(config: AgentConfig): string {
   const pkg = {
-    name: `${config.id}-mcp`,
+    name: config.id,
     version: '1.0.0',
     description: config.description,
     type: 'module',
@@ -31,6 +31,9 @@ export function generatePackageJson(config: AgentConfig): string {
       '@soleri/core': '^2.0.0',
       zod: '^3.24.2',
       ...(config.telegram ? { grammy: '^1.35.0' } : {}),
+      ...(config.domainPacks?.length
+        ? Object.fromEntries(config.domainPacks.map((pack) => [pack.package, pack.version ?? '*']))
+        : {}),
     },
     optionalDependencies: {
       '@anthropic-ai/sdk': '^0.39.0',

package/src/templates/readme.ts

@@ -4,6 +4,7 @@ import type { AgentConfig } from '../types.js';
  * Generate a README.md for the scaffolded agent.
  */
 export function generateReadme(config: AgentConfig): string {
+  const skillCount = config.skills?.length ?? 17;
   const setupTarget = config.setupTarget ?? 'claude';
   const claudeSetup = setupTarget === 'claude' || setupTarget === 'both';
   const codexSetup = setupTarget === 'codex' || setupTarget === 'both';
@@ -78,10 +79,10 @@ export function generateReadme(config: AgentConfig): string {
 
   const skillsLead =
     claudeSetup && codexSetup
-      ? `${config.name} ships with 17 structured workflow skills. In Claude Code they are invocable via \`/<skill-name>\`; in Codex they are available via generated AGENTS.md + local skill files.`
+      ? `${config.name} ships with ${skillCount} structured workflow skills. In Claude Code they are invocable via \`/<skill-name>\`; in Codex they are available via generated AGENTS.md + local skill files.`
       : claudeSetup
-        ? `${config.name} ships with 17 structured workflow skills, invocable via \`/<skill-name>\` in Claude Code:`
-        : `${config.name} ships with 17 structured workflow skills, available via generated AGENTS.md + local skill files in Codex:`;
+        ? `${config.name} ships with ${skillCount} structured workflow skills, invocable via \`/<skill-name>\` in Claude Code:`
+        : `${config.name} ships with ${skillCount} structured workflow skills, available via generated AGENTS.md + local skill files in Codex:`;
 
   const skillsInstallNote =
     claudeSetup && codexSetup

package/src/templates/setup-script.ts

@@ -6,10 +6,15 @@ import type { AgentConfig } from '../types.js';
  */
 export function generateSetupScript(config: AgentConfig): string {
   const setupTarget = config.setupTarget ?? 'claude';
-  const claudeSetup = setupTarget === 'claude' || setupTarget === 'both';
-  const codexSetup = setupTarget === 'codex' || setupTarget === 'both';
-  const hostLabel =
-    claudeSetup && codexSetup ? 'Claude Code + Codex' : claudeSetup ? 'Claude Code' : 'Codex';
+  const claudeSetup = setupTarget === 'claude' || setupTarget === 'both' || setupTarget === 'all';
+  const codexSetup = setupTarget === 'codex' || setupTarget === 'both' || setupTarget === 'all';
+  const opencodeSetup = setupTarget === 'opencode' || setupTarget === 'all';
+  const hostParts = [
+    ...(claudeSetup ? ['Claude Code'] : []),
+    ...(codexSetup ? ['Codex'] : []),
+    ...(opencodeSetup ? ['OpenCode'] : []),
+  ];
+  const hostLabel = hostParts.join(' + ');
 
   const claudeSection = claudeSetup
     ? `
@@ -195,6 +200,103 @@ if [ -d "$SKILLS_DIR" ]; then
   done
   echo "[ok] Codex skills: $skill_installed installed, $skill_skipped already present"
 fi
+`
+    : '';
+
+  const opencodeSection = opencodeSetup
+    ? `
+# Check and install OpenCode (Soleri fork with title branding)
+if ! command -v opencode &>/dev/null; then
+  echo ""
+  INSTALLED=false
+  # Try Go install from Soleri fork (supports title branding)
+  if command -v go &>/dev/null; then
+    echo "Installing OpenCode (Soleri fork) via go install..."
+    if go install github.com/adrozdenko/opencode@latest 2>/dev/null; then
+      if command -v opencode &>/dev/null; then
+        echo "[ok] OpenCode installed from Soleri fork ($(opencode --version 2>/dev/null || echo 'installed'))"
+        INSTALLED=true
+      fi
+    fi
+  fi
+  # Fallback: upstream npm package (no title branding)
+  if [ "$INSTALLED" = false ]; then
+    echo "Installing OpenCode via npm (upstream — title branding requires Go)..."
+    npm install -g opencode-ai
+    if command -v opencode &>/dev/null; then
+      echo "[ok] OpenCode installed ($(opencode --version 2>/dev/null || echo 'unknown version'))"
+    else
+      echo ""
+      echo "Warning: Could not install OpenCode automatically."
+      echo "Install manually using one of:"
+      echo "  go install github.com/adrozdenko/opencode@latest  (recommended — includes title branding)"
+      echo "  npm install -g opencode-ai  (upstream)"
+      echo ""
+    fi
+  fi
+else
+  echo "[ok] OpenCode found ($(opencode --version 2>/dev/null || echo 'installed'))"
+fi
+
+# Register MCP server with OpenCode
+echo ""
+echo "Registering ${config.name} with OpenCode..."
+OPENCODE_CONFIG="$HOME/.opencode.json"
+AGENT_DIST="$AGENT_DIR/dist/index.js"
+
+OPENCODE_CONFIG="$OPENCODE_CONFIG" AGENT_NAME="$AGENT_NAME" AGENT_DIST="$AGENT_DIST" node <<'NODE'
+const fs = require('node:fs');
+const path = process.env.OPENCODE_CONFIG;
+const agentName = process.env.AGENT_NAME;
+const distPath = process.env.AGENT_DIST;
+
+let config = {};
+if (fs.existsSync(path)) {
+  try {
+    const raw = fs.readFileSync(path, 'utf-8');
+    const stripped = raw.replace(/^\\s*\\/\\/.*$/gm, '');
+    config = JSON.parse(stripped);
+  } catch {
+    config = {};
+  }
+}
+
+if (!config.mcp || typeof config.mcp !== 'object') {
+  config.mcp = {};
+}
+
+config.mcp[agentName] = {
+  type: 'local',
+  command: ['node', distPath],
+  enabled: true,
+};
+
+fs.writeFileSync(path, JSON.stringify(config, null, 2) + '\\n', 'utf-8');
+NODE
+echo "[ok] Registered ${config.name} as MCP server (OpenCode)"
+
+# Create launcher script — type "${config.id}" to start OpenCode
+LAUNCHER_PATH="/usr/local/bin/$AGENT_NAME"
+LAUNCHER_CONTENT="#!/usr/bin/env bash
+# Soleri agent launcher — starts OpenCode with $AGENT_NAME MCP agent
+cd \\"$AGENT_DIR\\" || exit 1
+exec opencode \\"\\$@\\""
+
+if [ -w "/usr/local/bin" ]; then
+  echo "$LAUNCHER_CONTENT" > "$LAUNCHER_PATH"
+  chmod +x "$LAUNCHER_PATH"
+  echo "[ok] Launcher created: type \\"${config.id}\\" to start OpenCode"
+else
+  echo "$LAUNCHER_CONTENT" > "$AGENT_DIR/scripts/$AGENT_NAME"
+  chmod +x "$AGENT_DIR/scripts/$AGENT_NAME"
+  if command -v sudo &>/dev/null; then
+    sudo ln -sf "$AGENT_DIR/scripts/$AGENT_NAME" "$LAUNCHER_PATH" 2>/dev/null && \\
+      echo "[ok] Launcher created: type \\"${config.id}\\" to start OpenCode" || \\
+      echo "Note: Run 'sudo ln -sf $AGENT_DIR/scripts/$AGENT_NAME $LAUNCHER_PATH' to enable \\"${config.id}\\" command"
+  else
+    echo "Note: Add $AGENT_DIR/scripts to PATH, or symlink $AGENT_DIR/scripts/$AGENT_NAME to /usr/local/bin/$AGENT_NAME"
+  fi
+fi
 `
     : '';
 
@@ -207,6 +309,9 @@ fi
       ? ['echo "  - Start a new Claude Code session (or restart if one is open)"']
       : []),
     ...(codexSetup ? ['echo "  - Start a new Codex session (or restart if one is open)"'] : []),
+    ...(opencodeSetup
+      ? ['echo "  - Start a new OpenCode session (or restart if one is open)"']
+      : []),
     `echo "  - Say: \\"Hello, ${config.name}!\\""`,
     'echo ""',
     `echo "${config.name} is ready."`,
@@ -248,6 +353,7 @@ fi
 ${claudeSection}
 ${hookPackSection}
 ${codexSection}
+${opencodeSection}
 ${nextSteps}
 `;
 }

package/src/templates/shared-rules.ts

@@ -28,6 +28,39 @@ const ENGINE_RULES_LINES: string[] = [
   "Shared behavioral rules for all Soleri agents. The active agent's facade table provides tool names.",
   '',
 
+  // ─── What is Soleri ─────────────────────────────────────
+  '## What is Soleri',
+  '<!-- soleri:what-is-soleri -->',
+  '',
+  'You are powered by the **Soleri engine** — an intelligence framework that makes AI agents learn, remember, and improve over time. You are not a stateless chatbot. You are a knowledge-driven agent with:',
+  '',
+  "- **Vault** — your knowledge graph (Zettelkasten). Patterns, anti-patterns, principles you've learned. Grows with every session.",
+  '- **Brain** — pattern learning loop. Tracks what works (strengths) and recommends approaches based on past success.',
+  '- **Memory** — session history that persists across conversations and projects.',
+  '- **Planning** — structured workflow: plan → approve → execute → reconcile → capture knowledge.',
+  '- **Packs** — installable capability bundles (knowledge + skills + hooks). Add domains without code changes.',
+  '',
+  '### The 5-Step Rhythm',
+  '',
+  'Every task follows this cycle — each iteration makes the next one better:',
+  '',
+  '1. **Search** — check vault for existing patterns before deciding anything',
+  '2. **Plan** — create a structured plan, get user approval',
+  '3. **Work** — execute with vault-informed decisions',
+  '4. **Capture** — persist what you learned (patterns, anti-patterns, decisions)',
+  '5. **Complete** — reconcile, capture knowledge, feed the brain',
+  '',
+  '### Growing Your Capabilities',
+  '',
+  'You start with core capabilities (vault, brain, planning, memory). To add more:',
+  '',
+  '- **Install packs**: `soleri pack install <name>` — adds knowledge, skills, and hooks for a domain',
+  '- **Capture knowledge**: every pattern you capture makes you smarter for next time',
+  '- **Add domains**: `soleri add-domain <name>` — expands your expertise',
+  '',
+  'When a user asks "what can you do?" — list your current domains and capabilities from your activation context, not a generic list.',
+  '',
+
   // ─── Response Integrity ─────────────────────────────────
   '## Response Integrity',
   '<!-- soleri:response-integrity -->',
@@ -48,14 +81,17 @@ const ENGINE_RULES_LINES: string[] = [
   "If in doubt, don't save. Less memory with high signal beats more memory with noise.",
   '',
 
-  // ─── Vault-First Protocol ────────────────────────────────
-  '## Vault as Source of Truth',
+  // ─── Vault-First Protocol (Zettelkasten) ─────────────────
+  '## Vault as Source of Truth (Zettelkasten)',
   '<!-- soleri:vault-protocol -->',
   '',
-  '- **MANDATORY**: Consult the vault BEFORE every decision — planning, design, architecture, patterns, problem-solving.',
-  '- Lookup order: 1) VAULT (`op:search_intelligent`) → 2) MEMORY (`op:memory_search`) → 3) CODEBASE → 4) WEB/TRAINING.',
-  '- If the vault has a pattern, follow it. If it has an anti-pattern, avoid it.',
-  '- Persist lessons: call `op:capture_knowledge` — don\'t just promise "I will remember this".',
+  'The vault is a **Zettelkasten** — a connected knowledge graph. Every knowledge operation follows Zettelkasten principles: atomic entries, typed links, dense connections.',
+  '',
+  '- **MANDATORY**: Consult the vault BEFORE every decision — search + traverse the link graph.',
+  '- Lookup order: 1) VAULT search → 2) VAULT traverse (follow links 2 hops) → 3) MEMORY → 4) CODEBASE → 5) WEB/TRAINING.',
+  "- **Search + Traverse**: Don't just search — traverse from the best result to discover connected knowledge and anti-patterns.",
+  '- Check `contradicts` links to know what to avoid. Check `sequences` links for ordering dependencies.',
+  '- Persist lessons: capture + link. An unlinked entry is incomplete.',
   '- Exceptions: runtime errors with stack traces → codebase first; user explicitly asks to search web.',
   '',
 
@@ -163,20 +199,25 @@ const ENGINE_RULES_LINES: string[] = [
   '```',
   '',
 
-  // ─── Knowledge Capture ───────────────────────────────────
+  // ─── Knowledge Capture (Zettelkasten) ───────────────────
   '## Knowledge Capture',
   '<!-- soleri:knowledge-capture -->',
   '',
-  "**MANDATORY**: Persist lessons, don't just promise them.",
+  "**MANDATORY**: Persist lessons, don't just promise them. **Always link after capturing.**",
   '',
   'When you learn something that should persist:',
   '1. **DON\'T** just say "I will remember this"',
   '2. **DO** call `op:capture_knowledge` to persist to vault',
-  "3. **DO** update relevant files if it's a behavioral change",
+  '3. **DO** review `suggestedLinks` in the capture response',
+  '4. **DO** create links for relevant suggestions: `op:link_entries`',
+  "5. **DO** update relevant files if it's a behavioral change",
+  '',
+  'An unlinked entry is an orphan — it adds noise, not knowledge.',
   '',
   '| Type | Op | Persists To |',
   '|------|-----|-------------|',
   '| Patterns/Anti-patterns | `op:capture_knowledge` | vault |',
+  '| Links between entries | `op:link_entries` | vault_links table |',
   '| Quick capture | `op:capture_quick` | vault |',
   '| Session summaries | `op:session_capture` | memory |',
   '',
@@ -277,12 +318,9 @@ const ENGINE_RULES_LINES: string[] = [
   '',
   '### Session Start Protocol',
   '',
-  'On EVERY new session:',
-  '1. Register project: `op:register params:{ projectPath: "." }`',
-  '2. Check activation response for `persistence.status`, `vault.connected`, `project.registered`.',
-  '3. Check for plans awaiting reconciliation via `op:check_persistence`:',
-  '   - `executing` → Remind user to call `op:plan_reconcile`.',
-  '   - `reconciling` → Remind user to call `op:plan_complete_lifecycle`.',
+  'Do NOT call tools automatically on session start — just greet the user in character.',
+  'Call `op:register` only when you need project context for a task (not on every message).',
+  'Call `op:activate` only when checking evolved capabilities or recovering session state.',
   '',
   '### Context Compaction',
   '',
@@ -302,7 +340,7 @@ const ENGINE_RULES_LINES: string[] = [
   '|---------|-------------|',
   '| `soleri agent status` | Health check — version, packs, vault, update availability |',
   '| `soleri agent update` | Update engine to latest compatible version (`--check` for dry run) |',
-  '| `soleri agent refresh` | Regenerate CLAUDE.md from latest forge templates (`--dry-run` to preview) |',
+  '| `soleri agent refresh` | Regenerate AGENTS.md/CLAUDE.md from latest forge templates (`--dry-run` to preview) |',
   '| `soleri agent diff` | Show drift between current templates and latest engine |',
   '| `soleri doctor` | Full system health and project status check |',
   '| `soleri dev` | Run agent in development mode (stdio MCP) |',
@@ -343,7 +381,7 @@ const ENGINE_RULES_LINES: string[] = [
   '',
   '| Command | What it does |',
   '|---------|-------------|',
-  '| `soleri install` | Register agent as MCP server (`--target claude\\|codex\\|both`) |',
+  '| `soleri install` | Register agent as MCP server (`--target opencode\\|claude\\|codex\\|all`) |',
   '| `soleri uninstall` | Remove agent MCP server entry |',
   '| `soleri governance --show` | Show vault governance policy |',
   '| `soleri governance --preset <name>` | Set policy preset (strict\\|moderate\\|permissive) |',