diff --git a/evals/git-evals/eval-codebuff2.json b/evals/git-evals/eval-codebuff2.json
index cafa977cbc..fd505a34bc 100644
--- a/evals/git-evals/eval-codebuff2.json
+++ b/evals/git-evals/eval-codebuff2.json
@@ -343,8 +343,8 @@
         },
         {
           "path": "web/src/content/advanced/claude-code-comparison.mdx",
-          "preContent": "---\ntitle: 'Codebuff vs Claude Code'\nsection: 'advanced'\ntags: ['comparison', 'claude code']\norder: 5\n---\n\n# Codebuff vs Claude Code\n\nAnthropic recently released Claude Code, their own AI coding assistant.\n\nBoth Codebuff and Claude Code:\n\n- Run in your terminal for a seamless coding experience\n- Understand your entire codebase context\n- Can edit files and execute terminal commands\n- Use Claude Sonnet as their primary model\n\n## When to Choose Codebuff\n\nCodebuff might be a better choice if you value:\n\n- Speed: Codebuff is [nearly 4 times faster](https://x.com/jahooma/status/1894224663817195599)\n- Cost: Codebuff is one third the cost of Claude Code for equivalent tasks and even less for back-and-forth conversation\n- Codebase Analysis: Codebuff pulls more context from scanning your entire codebase, rather than file-by-file. Codebuff also [blends different models](/docs/advanced#what-models-do-you-use?) based on their strengths to provide more accurate results.\n- Staying in Flow: Codebuff requires fewer confirmation prompts for file edits and command execution.\n- Focused changes: Codebuff does just what you asked for, while Claude Code will often get carried away editing more and more files.\n\n## When to Choose Claude Code\n\nClaude Code might be a better choice if you:\n\n- Can't use an intermediary provider, need to use the API directly from Anthropic\n\n## Feature Comparison\n\n<MarkdownTable>\n  | Feature | Codebuff | Claude Code | | --- | --- | --- | | CLI-based\n  interaction | ✅ | ✅ | | Natural language commands | ✅ | ✅ | | Autonomous\n  test execution | ✅ | ✅ | | Deep, targeted context awareness | ✅ | ❌ | |\n  Large context window | ✅ (200k - 1M) | ✅ (200k) | | Fast diff edits (no full\n  rewrites) | ✅ | ❌ | | Accuracy at scale | ✅ | ❌ | | Cost | $ | $$$ | |\n  Polished UI | ❌ | ✅ | | Minimal interruptions | ✅ | ❌ |\n</MarkdownTable>\n\n## Summary\n\nBoth Codebuff and Claude Code are powerful AI coding assistants that can significantly boost your productivity. Codebuff offers more flexible pricing and performance options, while Claude Code provides direct integration with Anthropic's ecosystem.\n",
-          "postContent": "---\ntitle: 'Codebuff vs Claude Code'\nsection: 'advanced'\ntags: ['comparison', 'claude code']\norder: 5\n---\n\n# Codebuff vs Claude Code\n\nAnthropic recently released Claude Code, their own AI coding assistant.\n\nBoth Codebuff and Claude Code:\n\n- Run in your terminal for a seamless coding experience\n- Understand your entire codebase context\n- Can edit files and execute terminal commands\n- Use Claude Sonnet as their primary model\n\n## When to Choose Codebuff\n\nCodebuff might be a better choice if you value:\n\n- Speed: Codebuff is [nearly 4 times faster](https://x.com/jahooma/status/1894224663817195599)\n- Cost: Codebuff is one third the cost of Claude Code for equivalent tasks and even less for back-and-forth conversation\n- Codebase Analysis: Codebuff pulls more context from scanning your entire codebase, rather than file-by-file. Codebuff also [blends different models](/docs/advanced#what-models-do-you-use?) based on their strengths to provide more accurate results.\n- Staying in Flow: Codebuff requires fewer confirmation prompts for file edits and command execution.\n- Focused changes: Codebuff does just what you asked for, while Claude Code will often get carried away editing more and more files.\n- SDK and Programmatic Access: Codebuff provides a full TypeScript SDK for programmatic integration, allowing you to create custom workflows and embed AI coding capabilities into your own tools.\n- Advanced Agent System: Create custom agents with TypeScript generator functions, spawn subagents, and orchestrate complex multi-step workflows that go far beyond simple chat interactions.\n\n## When to Choose Claude Code\n\nClaude Code might be a better choice if you:\n\n- You require first-party Anthropic integration (no intermediary/proxy) for procurement, data handling, or legal reasons\n- You need enterprise security/compliance controls directly from Anthropic (e.g., SOC 2/ISO programs, data-retention controls, private/VPC networking options)\n- Your org needs centralized admin controls within Anthropic's ecosystem (SSO, RBAC, governance, auditability)\n- You prioritize early access to Anthropic model capabilities and first-party tooling\n\n\n## Feature Comparison\n\n<MarkdownTable>\n| Feature | Codebuff | Claude Code |\n| --- | --- | --- |\n| CLI-based interaction | ✅ | ✅ |\n| Natural language commands | ✅ | ✅ |\n| Autonomous test execution | ✅ | ✅ |\n| Large context window | ✅ (200k-1M) | ✅ (200k-1M) |\n| Directory-specific context awareness | ✅ | 🔄 |\n| Fast diff edits (no full rewrites) | ✅ | ❌ |\n| Cost | $ | $$ |\n| Polished UI | ❌ | ✅ |\n| Minimal interruptions | ✅ | ❌ |\n| Full-featured SDK | ✅ | ❌ |\n| Programmatic agent creation | ✅ | ❌ |\n| Project templates | ✅ | ❌ |\n</MarkdownTable>\n\n## Summary\n\nBoth Codebuff and Claude Code are powerful AI coding assistants that can significantly boost your productivity. Codebuff offers more flexible pricing and performance options, while Claude Code provides direct integration with Anthropic's ecosystem.\n"
+          "preContent": "---\ntitle: 'Codebuff vs Claude Code'\nsection: 'advanced'\ntags: ['comparison', 'claude code']\norder: 5\n---\n\n# Codebuff vs Claude Code\n\nAnthropic recently released Claude Code, their own AI coding assistant.\n\nBoth Codebuff and Claude Code:\n\n- Run in your terminal for a seamless coding experience\n- Understand your entire codebase context\n- Can edit files and execute terminal commands\n- Use Claude Sonnet as their primary model\n\n## When to Choose Codebuff\n\nCodebuff might be a better choice if you value:\n\n- Speed: Codebuff is [nearly 4 times faster](https://x.com/jahooma/status/1894224663817195599)\n- Cost: Codebuff is one third the cost of Claude Code for equivalent tasks and even less for back-and-forth conversation\n- Codebase Analysis: Codebuff pulls more context from scanning your entire codebase, rather than file-by-file. Codebuff also [blends different models](/docs/advanced#what-models-do-you-use) based on their strengths to provide more accurate results.\n- Staying in Flow: Codebuff requires fewer confirmation prompts for file edits and command execution.\n- Focused changes: Codebuff does just what you asked for, while Claude Code will often get carried away editing more and more files.\n\n## When to Choose Claude Code\n\nClaude Code might be a better choice if you:\n\n- Can't use an intermediary provider, need to use the API directly from Anthropic\n\n## Feature Comparison\n\n<MarkdownTable>\n  | Feature | Codebuff | Claude Code | | --- | --- | --- | | CLI-based\n  interaction | ✅ | ✅ | | Natural language commands | ✅ | ✅ | | Autonomous\n  test execution | ✅ | ✅ | | Deep, targeted context awareness | ✅ | ❌ | |\n  Large context window | ✅ (200k - 1M) | ✅ (200k) | | Fast diff edits (no full\n  rewrites) | ✅ | ❌ | | Accuracy at scale | ✅ | ❌ | | Cost | $ | $$$ | |\n  Polished UI | ❌ | ✅ | | Minimal interruptions | ✅ | ❌ |\n</MarkdownTable>\n\n## Summary\n\nBoth Codebuff and Claude Code are powerful AI coding assistants that can significantly boost your productivity. Codebuff offers more flexible pricing and performance options, while Claude Code provides direct integration with Anthropic's ecosystem.\n",
+          "postContent": "---\ntitle: 'Codebuff vs Claude Code'\nsection: 'advanced'\ntags: ['comparison', 'claude code']\norder: 5\n---\n\n# Codebuff vs Claude Code\n\nAnthropic recently released Claude Code, their own AI coding assistant.\n\nBoth Codebuff and Claude Code:\n\n- Run in your terminal for a seamless coding experience\n- Understand your entire codebase context\n- Can edit files and execute terminal commands\n- Use Claude Sonnet as their primary model\n\n## When to Choose Codebuff\n\nCodebuff might be a better choice if you value:\n\n- Speed: Codebuff is [nearly 4 times faster](https://x.com/jahooma/status/1894224663817195599)\n- Cost: Codebuff is one third the cost of Claude Code for equivalent tasks and even less for back-and-forth conversation\n- Codebase Analysis: Codebuff pulls more context from scanning your entire codebase, rather than file-by-file. Codebuff also [blends different models](/docs/advanced#what-models-do-you-use) based on their strengths to provide more accurate results.\n- Staying in Flow: Codebuff requires fewer confirmation prompts for file edits and command execution.\n- Focused changes: Codebuff does just what you asked for, while Claude Code will often get carried away editing more and more files.\n- SDK and Programmatic Access: Codebuff provides a full TypeScript SDK for programmatic integration, allowing you to create custom workflows and embed AI coding capabilities into your own tools.\n- Advanced Agent System: Create custom agents with TypeScript generator functions, spawn subagents, and orchestrate complex multi-step workflows that go far beyond simple chat interactions.\n\n## When to Choose Claude Code\n\nClaude Code might be a better choice if you:\n\n- You require first-party Anthropic integration (no intermediary/proxy) for procurement, data handling, or legal reasons\n- You need enterprise security/compliance controls directly from Anthropic (e.g., SOC 2/ISO programs, data-retention controls, private/VPC networking options)\n- Your org needs centralized admin controls within Anthropic's ecosystem (SSO, RBAC, governance, auditability)\n- You prioritize early access to Anthropic model capabilities and first-party tooling\n\n\n## Feature Comparison\n\n<MarkdownTable>\n| Feature | Codebuff | Claude Code |\n| --- | --- | --- |\n| CLI-based interaction | ✅ | ✅ |\n| Natural language commands | ✅ | ✅ |\n| Autonomous test execution | ✅ | ✅ |\n| Large context window | ✅ (200k-1M) | ✅ (200k-1M) |\n| Directory-specific context awareness | ✅ | 🔄 |\n| Fast diff edits (no full rewrites) | ✅ | ❌ |\n| Cost | $ | $$ |\n| Polished UI | ❌ | ✅ |\n| Minimal interruptions | ✅ | ❌ |\n| Full-featured SDK | ✅ | ❌ |\n| Programmatic agent creation | ✅ | ❌ |\n| Project templates | ✅ | ❌ |\n</MarkdownTable>\n\n## Summary\n\nBoth Codebuff and Claude Code are powerful AI coding assistants that can significantly boost your productivity. Codebuff offers more flexible pricing and performance options, while Claude Code provides direct integration with Anthropic's ecosystem.\n"
         },
         {
           "path": "web/src/content/agents/creating-new-agents.mdx",
@@ -353,7 +353,7 @@
         },
         {
           "path": "web/src/content/agents/customizing-agents.mdx",
-          "preContent": "---\ntitle: 'Customizing Agents'\nsection: 'advanced'\ntags: ['customization', 'agent templates', 'agents']\norder: 1\n---\n\n# Customizing Agents\n\nCreate specialized agents from scratch using TypeScript files in the `.agents/` directory:\n\n```markdown\n.agents/\n├── my-custom-agent.ts\n├── security-coordinator.ts\n└── types/\n    └── agent-definition.ts\n```\n## Example: Security Coordinator Agent\n\nCreate a specialized agent for security-focused workflows:\n\n**.agents/security-coordinator.ts**\n\n```typescript\nimport { AgentDefinition } from './types/agent-definition'\n\nconst definition: AgentDefinition = {\n  id: \"security-coordinator\",\n  version: \"1.0.0\",\n\n  displayName: \"Security Coordinator\",\n  spawnerPrompt: \"Spawn this agent to coordinate security-focused development workflows and ensure secure coding practices\",\n  model: \"anthropic/claude-4-sonnet-20250522\",\n  outputMode: \"last_message\",\n  includeMessageHistory: true,\n\n  toolNames: [\"read_files\", \"spawn_agents\", \"code_search\", \"end_turn\"],\n  spawnableAgents: [\"codebuff/reviewer@0.0.1\", \"codebuff/researcher@0.0.1\", \"codebuff/file-picker@0.0.1\"],\n\n  inputSchema: {\n    prompt: {\n      type: \"string\",\n      description: \"Security analysis or coordination task\"\n    }\n  },\n\n  systemPrompt: \"You are a security coordinator responsible for ensuring secure development practices.\",\n  instructionsPrompt: \"Analyze the security implications of the request and coordinate appropriate security-focused agents.\",\n  stepPrompt: \"Continue analyzing security requirements and coordinating the workflow. Use end_turn when complete.\"\n}\n\nexport default definition\n```\n\n## Advanced: Adding Programmatic Control\n\nMake your agent even more powerful with programmatic control:\n\n```typescript\nconst definition: AgentDefinition = {\n  id: \"security-coordinator\",\n  // ... other fields ...\n  \n  handleSteps: function* ({ prompt, params }) {\n    // 1. Scan for security vulnerabilities\n    const { toolResult: scanResults } = yield {\n      toolName: 'code_search',\n      input: { \n        pattern: '(eval|exec|dangerouslySetInnerHTML|process\\.env)',\n        flags: '-i'\n      }\n    }\n    \n    // 2. If vulnerabilities found, spawn security reviewer\n    if (scanResults) {\n      yield {\n        toolName: 'spawn_agents',\n        input: {\n          agents: [{\n            agent_type: 'security-reviewer',\n            prompt: `Review these potential security issues: ${scanResults}`\n          }]\n        }\n      }\n    }\n    \n    // 3. Let the agent handle the rest\n    yield 'STEP_ALL'\n  }\n}\n```\n\nWith `handleSteps`, your agent can:\n- Make decisions based on actual code analysis\n- Orchestrate multiple tools in sequence\n- Handle errors gracefully\n- Implement complex conditional logic\n\n## Available Fields\n\n**Core:** `id`, `displayName`, `model`, `version`, `publisher`\n**Tools:** `toolNames`, `spawnableAgents`\n**Prompts:** `spawnerPrompt`, `systemPrompt`, `instructionsPrompt`, `stepPrompt`\n**Input/Output:** `inputSchema`, `outputMode`, `outputSchema`, `includeMessageHistory`\n**Programmatic:** `handleSteps`\n\n## Built-in Agents\n\n- `codebuff/base` - Main coding assistant\n- `codebuff/reviewer` - Code review\n- `codebuff/thinker` - Deep thinking\n- `codebuff/researcher` - Research & docs\n- `codebuff/planner` - Planning & architecture\n- `codebuff/file-picker` - File discovery\n\n## Troubleshooting\n\n**Agent not loading:** Check TypeScript syntax, file must export default AgentDefinition\n**Type errors:** Import types from `'./types/agent-definition'`\n**Prompts not applying:** Verify file paths are relative to `.agents/` directory\n\n\n**Debug tips:**\n\n1. Check TypeScript: `bun run typecheck` in `.agents/` directory\n2. Restart Codebuff to see errors\n3. Test with `--agent <agent-id>` to debug specific agents\n**Next:** [Create new agents](/docs/agents/creating-new-agents) or see [troubleshooting guide](/docs/agents/troubleshooting)\n",
+          "preContent": "---\ntitle: 'Customizing Agents'\nsection: 'advanced'\ntags: ['customization', 'agent templates', 'agents']\norder: 1\n---\n\n# Customizing Agents\n\nCreate specialized agents from scratch using TypeScript files in the `.agents/` directory:\n\n```markdown\n.agents/\n├── my-custom-agent.ts\n├── security-coordinator.ts\n└── types/\n    └── agent-definition.ts\n```\n## Example: Security Coordinator Agent\n\nCreate a specialized agent for security-focused workflows:\n\n**.agents/security-coordinator.ts**\n\n```typescript\nimport { AgentDefinition } from './types/agent-definition'\n\nconst definition: AgentDefinition = {\n  id: \"security-coordinator\",\n  version: \"1.0.0\",\n\n  displayName: \"Security Coordinator\",\n  spawnerPrompt: \"Spawn this agent to coordinate security-focused development workflows and ensure secure coding practices\",\n  model: \"anthropic/claude-4-sonnet-20250522\",\n  outputMode: \"last_message\",\n  includeMessageHistory: true,\n\n  toolNames: [\"read_files\", \"spawn_agents\", \"code_search\", \"end_turn\"],\n  spawnableAgents: [\"codebuff/reviewer@0.0.1\", \"codebuff/researcher@0.0.1\", \"codebuff/file-picker@0.0.1\"],\n\n  inputSchema: {\n    prompt: {\n      type: \"string\",\n      description: \"Security analysis or coordination task\"\n    }\n  },\n\n  systemPrompt: \"You are a security coordinator responsible for ensuring secure development practices.\",\n  instructionsPrompt: \"Analyze the security implications of the request and coordinate appropriate security-focused agents.\",\n  stepPrompt: \"Continue analyzing security requirements and coordinating the workflow. Use end_turn when complete.\"\n}\n\nexport default definition\n```\n\n## Advanced: Adding Programmatic Control\n\nMake your agent even more powerful with programmatic control:\n\n```typescript\nconst definition: AgentDefinition = {\n  id: \"security-coordinator\",\n  // ... other fields ...\n  \n  handleSteps: function* ({ prompt, params }) {\n    // 1. Scan for security vulnerabilities\n    const { toolResult: scanResults } = yield {\n      toolName: 'code_search',\n      input: { \n        pattern: '(eval|exec|dangerouslySetInnerHTML|process\\.env)',\n        flags: '-i'\n      }\n    }\n    \n    // 2. If vulnerabilities found, spawn security reviewer\n    if (scanResults) {\n      yield {\n        toolName: 'spawn_agents',\n        input: {\n          agents: [{\n            agent_type: 'security-reviewer',\n            prompt: `Review these potential security issues: ${scanResults}`\n          }]\n        }\n      }\n    }\n    \n    // 3. Let the agent handle the rest\n    yield 'STEP_ALL'\n  }\n}\n```\n\nWith `handleSteps`, your agent can:\n- Make decisions based on actual code analysis\n- Orchestrate multiple tools in sequence\n- Handle errors gracefully\n- Implement complex conditional logic\n\n## Available Fields\n\n**Core:** `id`, `displayName`, `model`, `version`, `publisher`\n**Tools:** `toolNames`, `spawnableAgents`\n**Prompts:** `spawnerPrompt`, `systemPrompt`, `instructionsPrompt`, `stepPrompt`\n**Input/Output:** `inputSchema`, `outputMode`, `outputSchema`, `includeMessageHistory`\n**Programmatic:** `handleSteps`\n\n## Built-in Agents\n\n- `codebuff/base` - Main coding assistant\n- `codebuff/reviewer` - Code review\n- `codebuff/thinker` - Deep thinking\n- `codebuff/researcher` - Research & docs\n- `codebuff/planner` - Planning & architecture\n- `codebuff/file-picker` - File discovery\n\n## Troubleshooting\n\n**Agent not loading:** Check TypeScript syntax, file must export default AgentDefinition\n**Type errors:** Import types from `'./types/agent-definition'`\n**Prompts not applying:** Verify file paths are relative to `.agents/` directory\n\n\n**Debug tips:**\n\n1. Check TypeScript: `bun run typecheck` in `.agents/` directory\n2. Restart Codebuff to see errors\n3. Test with `--agent <agent-id>` to debug specific agents\n**Next:** [Create new agents](/docs/agents/creating-new-agents) or see [troubleshooting guide](/docs/agents#troubleshooting-agent-customization)\n",
           "postContent": "---\ntitle: 'Customizing Agents'\nsection: 'advanced'\ntags: ['customization', 'agent templates', 'agents']\norder: 1\n---\n\n# Customizing Agents\n\nCreate specialized agents from scratch using TypeScript files in the `.agents/` directory:\n\n```markdown\n.agents/\n├── my-custom-agent.ts\n├── security-coordinator.ts\n└── types/\n    └── agent-definition.ts\n```\n\n### Domain-Specific Customization\n\nAgents adapt to your specific workflow and project needs.\n\nKeep in mind you'll get the most value from agents if you see them as a means of managing your context window. Think about how you want to break down tasks and build your agents around that, as opposed to replicating engineering specialties.\n\nComparison: Context managers vs. specialty replicas\n\n<MarkdownTable>\n\n</MarkdownTable>\n\n**Tip:** Use specialty reviewers as spawnable subagents that your context-manager agent calls at the right time in the workflow.\n\n## Example: Security Coordinator Agent\n\nCreate a specialized agent for security-focused workflows:\n\n**.agents/security-coordinator.ts**\n\n```typescript\nimport { AgentDefinition } from './types/agent-definition'\n\nconst definition: AgentDefinition = {\n  id: \"security-coordinator\",\n  version: \"1.0.0\",\n\n  displayName: \"Security Coordinator\",\n  spawnerPrompt: \"Spawn this agent to coordinate security-focused development workflows and ensure secure coding practices\",\n  model: \"anthropic/claude-4-sonnet-20250522\",\n  outputMode: \"last_message\",\n  includeMessageHistory: true,\n\n  toolNames: [\"read_files\", \"spawn_agents\", \"code_search\", \"end_turn\"],\n  spawnableAgents: [\"codebuff/reviewer@0.0.1\", \"codebuff/researcher@0.0.1\", \"codebuff/file-picker@0.0.1\"],\n\n  inputSchema: {\n    prompt: {\n      type: \"string\",\n      description: \"Security analysis or coordination task\"\n    }\n  },\n\n  systemPrompt: \"You are a security coordinator responsible for ensuring secure development practices.\",\n  instructionsPrompt: \"Analyze the security implications of the request and coordinate appropriate security-focused agents.\",\n  stepPrompt: \"Continue analyzing security requirements and coordinating the workflow. Use end_turn when complete.\"\n}\n\nexport default definition\n```\n\n## Advanced: Adding Programmatic Control\n\nMake your agent even more powerful with programmatic control:\n\n```typescript\nconst definition: AgentDefinition = {\n  id: \"security-coordinator\",\n  // ... other fields ...\n\n  handleSteps: function* ({ prompt, params }) {\n    // 1. Scan for security vulnerabilities\n    const { toolResult: scanResults } = yield {\n      toolName: 'code_search',\n      input: {\n        pattern: '(eval|exec|dangerouslySetInnerHTML|process\\.env)',\n        flags: '-i'\n      }\n    }\n\n    // 2. If vulnerabilities found, spawn security reviewer\n    if (scanResults) {\n      yield {\n        toolName: 'spawn_agents',\n        input: {\n          agents: [{\n            agent_type: 'security-reviewer',\n            prompt: `Review these potential security issues: ${scanResults}`\n          }]\n        }\n      }\n    }\n\n    // 3. Let the agent handle the rest\n    yield 'STEP_ALL'\n  }\n}\n```\n\nWith `handleSteps`, your agent can:\n- Make decisions based on actual code analysis\n- Orchestrate multiple tools in sequence\n- Handle errors gracefully\n- Implement complex conditional logic\n\n## Available Fields\n\n**Core:**\n  - `id`\n  - `displayName`\n  - `model`\n  - `version`\n  - `publisher`\n\n**Tools:**\n  - `toolNames`\n  - `spawnableAgents`\n\n**Prompts:**\n  - `spawnerPrompt`\n  - `systemPrompt`\n  - `instructionsPrompt`\n  - `stepPrompt`\n\n**Input/Output:**\n  - `inputSchema`\n  - `outputMode`\n  - `outputSchema`\n  - `includeMessageHistory`\n\n**Programmatic:**\n  - `handleSteps`\n\n\n## Troubleshooting\n\n**Agent not loading:** Check TypeScript syntax, file must export default AgentDefinition\n\n**Type errors:** Import types from `'./types/agent-definition'`\n\n**Prompts not applying:** Verify file paths are relative to `.agents/` directory\n\n**Running specific agents:**\n\n1. Check TypeScript: `bun run typecheck` in `.agents/` directory\n2. Restart Codebuff to see errors\n3. Test with `--agent <agent-id>` to debug specific agents\n"
         },
         {
@@ -2232,13 +2232,13 @@
         },
         {
           "path": "web/src/content/agents/customizing-agents.mdx",
-          "preContent": "---\ntitle: 'Customizing Agents'\nsection: 'advanced'\ntags: ['customization', 'agent templates', 'agents']\norder: 1\n---\n\n# Customizing Agents\n\nCreate specialized agents from scratch using JSON templates in `.agents/templates/`:\n\n```markdown\n.agents/templates/\n├── my-custom-agent.json\n└── security-coordinator.json\n```\n\n## Example: Security Coordinator Agent\n\nCreate a specialized agent that provides guidance to other agents when spawning them:\n\n**.agents/templates/security-coordinator.json**\n\n```json\n{\n  \"id\": \"security-coordinator\",\n  \"version\": \"1.0.0\",\n  \"override\": false,\n\n  \"name\": \"Security Coordinator\",\n  \"purpose\": \"Coordinates security-focused development workflows\",\n  \"model\": \"anthropic/claude-4-sonnet-20250522\",\n  \"outputMode\": \"last_message\",\n  \"includeMessageHistory\": true,\n\n  \"toolNames\": [\"read_files\", \"spawn_agents\", \"code_search\", \"end_turn\"],\n  \"spawnableAgents\": [\"reviewer\", \"researcher\", \"file_picker\"],\n\n  \"inputSchema\": {\n    \"prompt\": {\n      \"type\": \"string\",\n      \"description\": \"Security analysis or coordination task\"\n    }\n  },\n  \"parentInstructions\": {\n    \"reviewer\": \"Security-sensitive code implemented? I must check for SQL injection, XSS, authentication bypasses, and input validation.\",\n    \"researcher\": \"Need security best practices or vulnerability info? Spawn me for OWASP guidelines and technology-specific threat research.\",\n    \"file_picker\": \"Security architecture understanding requires spawning me - I'll locate authentication configs, security middleware, and access control files.\"\n  },\n\n  \"systemPrompt\": \"You are a security coordinator responsible for ensuring secure development practices.\",\n  \"instructionsPrompt\": \"Analyze the security implications of the request and coordinate appropriate security-focused agents.\",\n  \"stepPrompt\": \"Continue security analysis and spawn relevant agents with security-focused instructions.\"\n}\n```\n\n**How parent instructions work:**\n\n- When `security-coordinator` spawns a `reviewer`, the reviewer automatically receives the security-focused instruction\n- Multiple agents can provide instructions for the same target - all instructions are combined\n- Instructions are injected into the target agent's `userInputPrompt` automatically\n\n## Available Fields\n\n**Core:** `model`, `toolNames`, `spawnableAgents`\n**Prompts:** `systemPrompt`, `instructionsPrompt`, `stepPrompt`\n**Parent Instructions:** `parentInstructions` - Guide spawned agents\n\n## Built-in Agents\n\n- `CodebuffAI/base` - Main coding assistant\n- `CodebuffAI/reviewer` - Code review\n- `CodebuffAI/thinker` - Deep thinking\n- `CodebuffAI/researcher` - Research & docs\n- `CodebuffAI/planner` - Planning & architecture\n- `CodebuffAI/file-picker` - File discovery\n\n## Troubleshooting\n\n**Agent not loading:** Check JSON syntax, file location in `.agents/templates/`\n**Prompts not applying:** Verify file paths are relative to project root\n**Path errors:** Use `.agents/templates/my-file.md` format\n\n**Debug tips:**\n\n1. Validate JSON: `cat file.json | jq`\n2. Restart Codebuff to see errors\n3. Test with `--agent <agent-id>` to debug specific agents\n\n**Next:** [Create new agents](/docs/agents/creating-new-agents) or see [troubleshooting guide](/docs/agents/troubleshooting)\n",
-          "postContent": "---\ntitle: 'Customizing Agents'\nsection: 'advanced'\ntags: ['customization', 'agent templates', 'agents']\norder: 1\n---\n\n# Customizing Agents\n\nCreate specialized agents from scratch using JSON templates in `.agents/templates/`:\n\n```markdown\n.agents/templates/\n├── my-custom-agent.json\n└── security-coordinator.json\n```\n\n## Example: Security Coordinator Agent\n\nCreate a specialized agent that provides guidance to other agents when spawning them:\n\n**.agents/templates/security-coordinator.json**\n\n```json\n{\n  \"id\": \"security-coordinator\",\n  \"version\": \"1.0.0\",\n\n  \"name\": \"Security Coordinator\",\n  \"purpose\": \"Coordinates security-focused development workflows\",\n  \"model\": \"anthropic/claude-4-sonnet-20250522\",\n  \"outputMode\": \"last_message\",\n  \"includeMessageHistory\": true,\n\n  \"toolNames\": [\"read_files\", \"spawn_agents\", \"code_search\", \"end_turn\"],\n  \"subagents\": [\"reviewer\", \"researcher\", \"file_picker\"],\n\n  \"inputSchema\": {\n    \"prompt\": {\n      \"type\": \"string\",\n      \"description\": \"Security analysis or coordination task\"\n    }\n  },\n\n  \"systemPrompt\": \"You are a security coordinator responsible for ensuring secure development practices.\",\n  \"instructionsPrompt\": \"Analyze the security implications of the request and coordinate appropriate security-focused agents.\",\n}\n```\n\n## Available Fields\n\n**Core:** `model`, `toolNames`, `spawnableAgents`\n**Prompts:** `systemPrompt`, `instructionsPrompt`, `stepPrompt`\n\n## Built-in Agents\n\n- `CodebuffAI/base` - Main coding assistant\n- `CodebuffAI/reviewer` - Code review\n- `CodebuffAI/thinker` - Deep thinking\n- `CodebuffAI/researcher` - Research & docs\n- `CodebuffAI/planner` - Planning & architecture\n- `CodebuffAI/file-picker` - File discovery\n\n## Troubleshooting\n\n**Agent not loading:** Check JSON syntax, file location in `.agents/templates/`\n**Prompts not applying:** Verify file paths are relative to project root\n**Path errors:** Use `.agents/templates/my-file.md` format\n\n**Debug tips:**\n\n1. Validate JSON: `cat file.json | jq`\n2. Restart Codebuff to see errors\n3. Test with `--agent <agent-id>` to debug specific agents\n\n**Next:** [Create new agents](/docs/agents/creating-new-agents) or see [troubleshooting guide](/docs/agents/troubleshooting)\n"
+          "preContent": "---\ntitle: 'Customizing Agents'\nsection: 'advanced'\ntags: ['customization', 'agent templates', 'agents']\norder: 1\n---\n\n# Customizing Agents\n\nCreate specialized agents from scratch using JSON templates in `.agents/templates/`:\n\n```markdown\n.agents/templates/\n├── my-custom-agent.json\n└── security-coordinator.json\n```\n\n## Example: Security Coordinator Agent\n\nCreate a specialized agent that provides guidance to other agents when spawning them:\n\n**.agents/templates/security-coordinator.json**\n\n```json\n{\n  \"id\": \"security-coordinator\",\n  \"version\": \"1.0.0\",\n  \"override\": false,\n\n  \"name\": \"Security Coordinator\",\n  \"purpose\": \"Coordinates security-focused development workflows\",\n  \"model\": \"anthropic/claude-4-sonnet-20250522\",\n  \"outputMode\": \"last_message\",\n  \"includeMessageHistory\": true,\n\n  \"toolNames\": [\"read_files\", \"spawn_agents\", \"code_search\", \"end_turn\"],\n  \"spawnableAgents\": [\"reviewer\", \"researcher\", \"file_picker\"],\n\n  \"inputSchema\": {\n    \"prompt\": {\n      \"type\": \"string\",\n      \"description\": \"Security analysis or coordination task\"\n    }\n  },\n  \"parentInstructions\": {\n    \"reviewer\": \"Security-sensitive code implemented? I must check for SQL injection, XSS, authentication bypasses, and input validation.\",\n    \"researcher\": \"Need security best practices or vulnerability info? Spawn me for OWASP guidelines and technology-specific threat research.\",\n    \"file_picker\": \"Security architecture understanding requires spawning me - I'll locate authentication configs, security middleware, and access control files.\"\n  },\n\n  \"systemPrompt\": \"You are a security coordinator responsible for ensuring secure development practices.\",\n  \"instructionsPrompt\": \"Analyze the security implications of the request and coordinate appropriate security-focused agents.\",\n  \"stepPrompt\": \"Continue security analysis and spawn relevant agents with security-focused instructions.\"\n}\n```\n\n**How parent instructions work:**\n\n- When `security-coordinator` spawns a `reviewer`, the reviewer automatically receives the security-focused instruction\n- Multiple agents can provide instructions for the same target - all instructions are combined\n- Instructions are injected into the target agent's `userInputPrompt` automatically\n\n## Available Fields\n\n**Core:** `model`, `toolNames`, `spawnableAgents`\n**Prompts:** `systemPrompt`, `instructionsPrompt`, `stepPrompt`\n**Parent Instructions:** `parentInstructions` - Guide spawned agents\n\n## Built-in Agents\n\n- `CodebuffAI/base` - Main coding assistant\n- `CodebuffAI/reviewer` - Code review\n- `CodebuffAI/thinker` - Deep thinking\n- `CodebuffAI/researcher` - Research & docs\n- `CodebuffAI/planner` - Planning & architecture\n- `CodebuffAI/file-picker` - File discovery\n\n## Troubleshooting\n\n**Agent not loading:** Check JSON syntax, file location in `.agents/templates/`\n**Prompts not applying:** Verify file paths are relative to project root\n**Path errors:** Use `.agents/templates/my-file.md` format\n\n**Debug tips:**\n\n1. Validate JSON: `cat file.json | jq`\n2. Restart Codebuff to see errors\n3. Test with `--agent <agent-id>` to debug specific agents\n\n**Next:** [Create new agents](/docs/agents/creating-new-agents) or see [troubleshooting guide](/docs/agents#troubleshooting-agent-customization)\n",
+          "postContent": "---\ntitle: 'Customizing Agents'\nsection: 'advanced'\ntags: ['customization', 'agent templates', 'agents']\norder: 1\n---\n\n# Customizing Agents\n\nCreate specialized agents from scratch using JSON templates in `.agents/templates/`:\n\n```markdown\n.agents/templates/\n├── my-custom-agent.json\n└── security-coordinator.json\n```\n\n## Example: Security Coordinator Agent\n\nCreate a specialized agent that provides guidance to other agents when spawning them:\n\n**.agents/templates/security-coordinator.json**\n\n```json\n{\n  \"id\": \"security-coordinator\",\n  \"version\": \"1.0.0\",\n\n  \"name\": \"Security Coordinator\",\n  \"purpose\": \"Coordinates security-focused development workflows\",\n  \"model\": \"anthropic/claude-4-sonnet-20250522\",\n  \"outputMode\": \"last_message\",\n  \"includeMessageHistory\": true,\n\n  \"toolNames\": [\"read_files\", \"spawn_agents\", \"code_search\", \"end_turn\"],\n  \"subagents\": [\"reviewer\", \"researcher\", \"file_picker\"],\n\n  \"inputSchema\": {\n    \"prompt\": {\n      \"type\": \"string\",\n      \"description\": \"Security analysis or coordination task\"\n    }\n  },\n\n  \"systemPrompt\": \"You are a security coordinator responsible for ensuring secure development practices.\",\n  \"instructionsPrompt\": \"Analyze the security implications of the request and coordinate appropriate security-focused agents.\",\n}\n```\n\n## Available Fields\n\n**Core:** `model`, `toolNames`, `spawnableAgents`\n**Prompts:** `systemPrompt`, `instructionsPrompt`, `stepPrompt`\n\n## Built-in Agents\n\n- `CodebuffAI/base` - Main coding assistant\n- `CodebuffAI/reviewer` - Code review\n- `CodebuffAI/thinker` - Deep thinking\n- `CodebuffAI/researcher` - Research & docs\n- `CodebuffAI/planner` - Planning & architecture\n- `CodebuffAI/file-picker` - File discovery\n\n## Troubleshooting\n\n**Agent not loading:** Check JSON syntax, file location in `.agents/templates/`\n**Prompts not applying:** Verify file paths are relative to project root\n**Path errors:** Use `.agents/templates/my-file.md` format\n\n**Debug tips:**\n\n1. Validate JSON: `cat file.json | jq`\n2. Restart Codebuff to see errors\n3. Test with `--agent <agent-id>` to debug specific agents\n\n**Next:** [Create new agents](/docs/agents/creating-new-agents) or see [troubleshooting guide](/docs/agents#troubleshooting-agent-customization)\n"
         },
         {
           "path": "web/src/content/agents/troubleshooting-agent-customization.mdx",
-          "preContent": "---\ntitle: 'Troubleshooting Agent Customization'\nsection: 'agents'\ntags: ['troubleshooting', 'debugging', 'agents']\norder: 5\n---\n\n# Troubleshooting Agent Customization\n\nQuick fixes for common agent customization issues.\n\n## Quick Fix Checklist\n\n1. **Restart Codebuff** to reload templates\n2. **Check JSON syntax:** `cat your-agent-file.json | jq`\n3. **Verify file paths** are relative to project root\n4. **Ensure `\"override\": true`** is set for overrides\n\n## Common Errors\n\n### \"Agent not found\"\n\n```text\nError: Agent 'my-custom-agent' not found\n```\n\n**Fix:** Check agent ID spelling, file location (`.agents/templates/`), JSON syntax (`cat file.json | jq`)\n\n### \"Invalid spawnable agent\"\n\n```text\nValidation error: spawnableAgents contains invalid agent 'researcher-typo'\n```\n\n**Fix:** Check spelling against [built-in agents list](/docs/agents/agent-reference#available-built-in-agents), use exact IDs\n\n### \"Path not found\" Error\n\n```text\nError: Cannot resolve prompt file './my-prompt.md'\n```\n\n**Causes:**\n\n- File doesn't exist at specified path\n- Incorrect relative path resolution\n- File permissions issue\n\n**Solutions:**\n\n1. Use paths relative to project root: `.agents/templates/my-prompt.md`\n2. Verify file exists: `ls -la .agents/templates/my-prompt.md`\n3. Check file permissions are readable\n\n## JSON Schema Issues\n\n### Invalid Override Type\n\n```json\n{\n  \"systemPrompt\": {\n    \"type\": \"add\", // ❌ Invalid\n    \"content\": \"...\"\n  }\n}\n```\n\n**Fix:** Use valid override types:\n\n```json\n{\n  \"systemPrompt\": {\n    \"type\": \"append\", // ✅ Valid: append, prepend, replace\n    \"content\": \"...\"\n  }\n}\n```\n\n### Missing Required Fields\n\n```json\n{\n  \"id\": \"my-agent\",\n  \"override\": false,\n  \"displayName\": \"My Agent\"\n  // ❌ Missing required fields for new agents\n}\n```\n\n**Fix:** Include all required fields for new agents:\n\n```json\n{\n  \"id\": \"my-agent\",\n  \"version\": \"1.0.0\",\n  \"override\": false,\n  \"displayName\": \"My Agent\",\n  \"purpose\": \"Brief description of the agent's purpose\",\n  \"model\": \"anthropic/claude-4-sonnet-20250522\",\n  \"systemPrompt\": \"You are a helpful assistant...\",\n  \"instructionsPrompt\": \"Process the user's request...\",\n  \"stepPrompt\": \"Continue working on the task...\"\n}\n```\n\n### \"Path not found\"\n\n**Fix:** Use project root relative paths: `.agents/templates/my-prompt.md`, verify file exists\n\n## Agent Behavior Issues\n\n### Agent Not Using Custom Prompts\n\n**Symptoms:**\n\n- Agent behaves like default version\n- Custom instructions ignored\n\n**Debug Steps:**\n\n1. Check override is properly applied:\n\n```bash\n# Restart Codebuff to reload templates\ncodebuff\n```\n\n2. Verify override syntax:\n\n```json\n{\n  \"id\": \"CodebuffAI/reviewer\", // ✅ Exact match required\n  \"override\": true, // ✅ Must be true for overrides\n  \"systemPrompt\": {\n    \"type\": \"append\", // ✅ Valid override type\n    \"content\": \"Custom instructions...\"\n  }\n}\n```\n\n### Agent Spawning Wrong Sub-agents\n\n**Symptoms:**\n\n- Unexpected agents being created\n- Missing expected specialized agents\n\n**Solutions:**\n\n1. Check `spawnableAgents` configuration:\n\n```json\n{\n  \"spawnableAgents\": {\n    \"type\": \"replace\", // Use \"replace\" to override completely\n    \"content\": [\"researcher\", \"thinker\"]\n  }\n}\n```\n\n2. Verify agent names are correct (no typos)\n\n## Performance Issues\n\n### Agent Taking Too Long\n\n**Causes:**\n\n- Complex prompts causing slow generation\n- Too many tools enabled\n- Large context from message history\n\n**Solutions:**\n\n1. Simplify prompts and remove unnecessary instructions\n2. Limit `toolNames` to only required tools\n3. Set `includeMessageHistory: false` for stateless agents\n4. Use faster models for simple tasks:\n\n```json\n{\n  \"model\": \"anthropic/claude-3-5-haiku-20241022\" // Faster model\n}\n```\n\n### High Credit Usage\n\n**Causes:**\n\n- Using expensive models unnecessarily\n- Agents spawning too many sub-agents\n- Large context windows\n\n**Solutions:**\n\n1. Use cost-effective models:\n\n```json\n{\n  \"model\": \"google/gemini-2.5-flash\" // More economical\n}\n```\n\n2. Limit spawnable agents:\n\n```json\n{\n  \"spawnableAgents\": [] // Prevent sub-agent spawning\n}\n```\n\n## File Organization Issues\n\n### Templates Not Loading\n\n**Symptoms:**\n\n- No custom agents available\n- Validation errors on startup\n\n**Debug Steps:**\n\n1. Check directory structure:\n\n```markdown\nyour-project/\n├── .agents/\n│ └── templates/\n│ ├── my-agent.json\n│ └── my-prompts.md\n```\n\n2. Verify file permissions:\n\n```bash\nls -la .agents/templates/\n```\n\n3. Check for hidden characters or encoding issues:\n\n```bash\nfile .agents/templates/*.json\n```\n\n## Best Practices for Debugging\n\n### 1. Start Simple\n\nBegin with minimal overrides and add complexity gradually:\n\n```json\n{\n  \"id\": \"CodebuffAI/reviewer\",\n  \"override\": true,\n  \"model\": \"anthropic/claude-4-sonnet-20250522\"\n}\n```\n\n### 2. Use Validation Tools\n\n- JSON validator: `cat file.json | jq`\n- File existence: `ls -la .agents/templates/`\n- Syntax check: Most editors highlight JSON errors\n\n### 3. Check Logs\n\nRestart Codebuff to see validation errors:\n\n```bash\ncodebuff  # Look for error messages on startup\n```\n\n### 4. Test Incrementally\n\nAdd one override at a time to isolate issues:\n\n1. Test basic override (model change)\n2. Add simple prompt override\n3. Add external file reference\n4. Add tool modifications\n\n### 5. Use Version Control\n\nTrack your agent templates in git to easily revert problematic changes:\n\n```bash\ngit add .agents/\ngit commit -m \"Add custom reviewer agent\"\n```\n\n## Getting Help\n\nIf you're still experiencing issues:\n\n1. **Check the logs**: Look for specific error messages when starting Codebuff\n2. **Simplify**: Remove customizations until it works, then add back gradually\n3. **Community**: Join our [Discord](https://codebuff.com/discord) for real-time help\n4. **Documentation**: Review the [Agent Reference](/docs/agents/agent-reference) for complete field descriptions\n\n## Quick Reference\n\n### Valid Override Types\n\n- `\"append\"` - Add to existing content\n- `\"prepend\"` - Add before existing content\n- `\"replace\"` - Replace entire content\n\n### Required Fields for New Agents\n\n- `id`, `version`, `override: false`\n- `displayName`, `purpose`, `model`\n- `systemPrompt`, `instructionsPrompt`, `stepPrompt`\n\n### Common File Paths\n\n- Agent templates: `.agents/templates/*.json`\n- External prompts: `.agents/templates/*.md`\n- Project root: `./` (for absolute paths)\n",
-          "postContent": "---\ntitle: 'Troubleshooting Agent Customization'\nsection: 'agents'\ntags: ['troubleshooting', 'debugging', 'agents']\norder: 5\n---\n\n# Troubleshooting Agent Customization\n\nQuick fixes for common agent customization issues.\n\n## Quick Fix Checklist\n\n1. **Restart Codebuff** to reload templates\n2. **Check JSON syntax:** `cat your-agent-file.json | jq`\n3. **Verify file paths** are relative to project root\n4. **Ensure `\"override\": true`** is set for overrides\n\n## Common Errors\n\n### \"Agent not found\"\n\n```text\nError: Agent 'my-custom-agent' not found\n```\n\n**Fix:** Check agent ID spelling, file location (`.agents/templates/`), JSON syntax (`cat file.json | jq`)\n\n### \"Invalid spawnable agent\"\n\n```text\nValidation error: spawnableAgents contains invalid agent 'researcher-typo'\n```\n\n**Fix:** Check spelling against [built-in agents list](/docs/agents/agent-reference#available-built-in-agents), use exact IDs\n\n### \"Path not found\" Error\n\n```text\nError: Cannot resolve prompt file './my-prompt.md'\n```\n\n**Causes:**\n\n- File doesn't exist at specified path\n- Incorrect relative path resolution\n- File permissions issue\n\n**Solutions:**\n\n1. Use paths relative to project root: `.agents/templates/my-prompt.md`\n2. Verify file exists: `ls -la .agents/templates/my-prompt.md`\n3. Check file permissions are readable\n\n## JSON Schema Issues\n\n### Invalid Override Type\n\n```json\n{\n  \"systemPrompt\": {\n    \"type\": \"add\", // ❌ Invalid\n    \"content\": \"...\"\n  }\n}\n```\n\n**Fix:** Use valid override types:\n\n```json\n{\n  \"systemPrompt\": {\n    \"type\": \"append\", // ✅ Valid: append, prepend, replace\n    \"content\": \"...\"\n  }\n}\n```\n\n### Missing Required Fields\n\n```json\n{\n  \"id\": \"my-agent\",\n  \"override\": false,\n  \"displayName\": \"My Agent\"\n  // ❌ Missing required fields for new agents\n}\n```\n\n**Fix:** Include all required fields for new agents:\n\n```json\n{\n  \"id\": \"my-agent\",\n  \"version\": \"1.0.0\",\n  \"override\": false,\n  \"displayName\": \"My Agent\",\n  \"purpose\": \"Brief description of the agent's purpose\",\n  \"model\": \"anthropic/claude-4-sonnet-20250522\",\n  \"systemPrompt\": \"You are a helpful assistant...\",\n  \"instructionsPrompt\": \"Process the user's request...\",\n  \"stepPrompt\": \"Continue working on the task...\"\n}\n```\n\n### \"Path not found\"\n\n**Fix:** Use project root relative paths: `.agents/templates/my-prompt.md`, verify file exists\n\n## Agent Behavior Issues\n\n### Agent Not Using Custom Prompts\n\n**Symptoms:**\n\n- Agent behaves like default version\n- Custom instructions ignored\n\n**Debug Steps:**\n\n1. Check override is properly applied:\n\n```bash\n# Restart Codebuff to reload templates\ncodebuff\n```\n\n2. Verify override syntax:\n\n```json\n{\n  \"id\": \"CodebuffAI/reviewer\", // ✅ Exact match required\n  \"override\": true, // ✅ Must be true for overrides\n  \"systemPrompt\": {\n    \"type\": \"append\", // ✅ Valid override type\n    \"content\": \"Custom instructions...\"\n  }\n}\n```\n\n### Agent Spawning Wrong Sub-agents\n\n**Symptoms:**\n\n- Unexpected agents being created\n- Missing expected specialized agents\n\n**Solutions:**\n\n1. Check `spawnableAgents` configuration:\n\n```json\n{\n  \"spawnableAgents\": {\n    \"type\": \"replace\", // Use \"replace\" to override completely\n    \"content\": [\"researcher\", \"thinker\"]\n  }\n}\n```\n\n2. Verify agent names are correct (no typos)\n\n## Performance Issues\n\n### Agent Taking Too Long\n\n**Causes:**\n\n- Complex prompts causing slow generation\n- Too many tools enabled\n- Large context from message history\n\n**Solutions:**\n\n1. Simplify prompts and remove unnecessary instructions\n2. Limit `toolNames` to only required tools\n3. Set `includeMessageHistory: false` for stateless agents\n4. Use faster models for simple tasks:\n\n```json\n{\n  \"model\": \"anthropic/claude-3-5-haiku-20241022\" // Faster model\n}\n```\n\n### High Credit Usage\n\n**Causes:**\n\n- Using expensive models unnecessarily\n- Agents spawning too many sub-agents\n- Large context windows\n\n**Solutions:**\n\n1. Use cost-effective models:\n\n```json\n{\n  \"model\": \"google/gemini-2.5-flash\" // More economical\n}\n```\n\n2. Limit spawnable agents:\n\n```json\n{\n  \"spawnableAgents\": [] // Prevent sub-agent spawning\n}\n```\n\n## File Organization Issues\n\n### Templates Not Loading\n\n**Symptoms:**\n\n- No custom agents available\n- Validation errors on startup\n\n**Debug Steps:**\n\n1. Check directory structure:\n\n```markdown\nyour-project/\n├── .agents/\n│ ├── my-agent.json\n│ └── my-prompts.md\n```\n\n2. Verify file permissions:\n\n```bash\nls -la .agents/templates/\n```\n\n3. Check for hidden characters or encoding issues:\n\n```bash\nfile .agents/templates/*.json\n```\n\n## Best Practices for Debugging\n\n### 1. Start Simple\n\nBegin with minimal overrides and add complexity gradually:\n\n```json\n{\n  \"id\": \"CodebuffAI/reviewer\",\n  \"override\": true,\n  \"model\": \"anthropic/claude-4-sonnet-20250522\"\n}\n```\n\n### 2. Use Validation Tools\n\n- JSON validator: `cat file.json | jq`\n- File existence: `ls -la .agents/templates/`\n- Syntax check: Most editors highlight JSON errors\n\n### 3. Check Logs\n\nRestart Codebuff to see validation errors:\n\n```bash\ncodebuff  # Look for error messages on startup\n```\n\n### 4. Test Incrementally\n\nAdd one override at a time to isolate issues:\n\n1. Test basic override (model change)\n2. Add simple prompt override\n3. Add external file reference\n4. Add tool modifications\n\n### 5. Use Version Control\n\nTrack your agent templates in git to easily revert problematic changes:\n\n```bash\ngit add .agents/\ngit commit -m \"Add custom reviewer agent\"\n```\n\n## Getting Help\n\nIf you're still experiencing issues:\n\n1. **Check the logs**: Look for specific error messages when starting Codebuff\n2. **Simplify**: Remove customizations until it works, then add back gradually\n3. **Community**: Join our [Discord](https://codebuff.com/discord) for real-time help\n4. **Documentation**: Review the [Agent Reference](/docs/agents/agent-reference) for complete field descriptions\n\n## Quick Reference\n\n### Valid Override Types\n\n- `\"append\"` - Add to existing content\n- `\"prepend\"` - Add before existing content\n- `\"replace\"` - Replace entire content\n\n### Required Fields for New Agents\n\n- `id`, `version`, `override: false`\n- `displayName`, `purpose`, `model`\n- `systemPrompt`, `instructionsPrompt`, `stepPrompt`\n\n### Common File Paths\n\n- Agent templates: `.agents/templates/*.json`\n- External prompts: `.agents/templates/*.md`\n- Project root: `./` (for absolute paths)\n"
+          "preContent": "---\ntitle: 'Troubleshooting Agent Customization'\nsection: 'agents'\ntags: ['troubleshooting', 'debugging', 'agents']\norder: 5\n---\n\n# Troubleshooting Agent Customization\n\nQuick fixes for common agent customization issues.\n\n## Quick Fix Checklist\n\n1. **Restart Codebuff** to reload templates\n2. **Check JSON syntax:** `cat your-agent-file.json | jq`\n3. **Verify file paths** are relative to project root\n4. **Ensure `\"override\": true`** is set for overrides\n\n## Common Errors\n\n### \"Agent not found\"\n\n```text\nError: Agent 'my-custom-agent' not found\n```\n\n**Fix:** Check agent ID spelling, file location (`.agents/templates/`), JSON syntax (`cat file.json | jq`)\n\n### \"Invalid spawnable agent\"\n\n```text\nValidation error: spawnableAgents contains invalid agent 'researcher-typo'\n```\n\n**Fix:** Check spelling against [built-in agents list](/docs/agents#h2-built-in-agents), use exact IDs\n\n### \"Path not found\" Error\n\n```text\nError: Cannot resolve prompt file './my-prompt.md'\n```\n\n**Causes:**\n\n- File doesn't exist at specified path\n- Incorrect relative path resolution\n- File permissions issue\n\n**Solutions:**\n\n1. Use paths relative to project root: `.agents/templates/my-prompt.md`\n2. Verify file exists: `ls -la .agents/templates/my-prompt.md`\n3. Check file permissions are readable\n\n## JSON Schema Issues\n\n### Invalid Override Type\n\n```json\n{\n  \"systemPrompt\": {\n    \"type\": \"add\", // ❌ Invalid\n    \"content\": \"...\"\n  }\n}\n```\n\n**Fix:** Use valid override types:\n\n```json\n{\n  \"systemPrompt\": {\n    \"type\": \"append\", // ✅ Valid: append, prepend, replace\n    \"content\": \"...\"\n  }\n}\n```\n\n### Missing Required Fields\n\n```json\n{\n  \"id\": \"my-agent\",\n  \"override\": false,\n  \"displayName\": \"My Agent\"\n  // ❌ Missing required fields for new agents\n}\n```\n\n**Fix:** Include all required fields for new agents:\n\n```json\n{\n  \"id\": \"my-agent\",\n  \"version\": \"1.0.0\",\n  \"override\": false,\n  \"displayName\": \"My Agent\",\n  \"purpose\": \"Brief description of the agent's purpose\",\n  \"model\": \"anthropic/claude-4-sonnet-20250522\",\n  \"systemPrompt\": \"You are a helpful assistant...\",\n  \"instructionsPrompt\": \"Process the user's request...\",\n  \"stepPrompt\": \"Continue working on the task...\"\n}\n```\n\n### \"Path not found\"\n\n**Fix:** Use project root relative paths: `.agents/templates/my-prompt.md`, verify file exists\n\n## Agent Behavior Issues\n\n### Agent Not Using Custom Prompts\n\n**Symptoms:**\n\n- Agent behaves like default version\n- Custom instructions ignored\n\n**Debug Steps:**\n\n1. Check override is properly applied:\n\n```bash\n# Restart Codebuff to reload templates\ncodebuff\n```\n\n2. Verify override syntax:\n\n```json\n{\n  \"id\": \"CodebuffAI/reviewer\", // ✅ Exact match required\n  \"override\": true, // ✅ Must be true for overrides\n  \"systemPrompt\": {\n    \"type\": \"append\", // ✅ Valid override type\n    \"content\": \"Custom instructions...\"\n  }\n}\n```\n\n### Agent Spawning Wrong Sub-agents\n\n**Symptoms:**\n\n- Unexpected agents being created\n- Missing expected specialized agents\n\n**Solutions:**\n\n1. Check `spawnableAgents` configuration:\n\n```json\n{\n  \"spawnableAgents\": {\n    \"type\": \"replace\", // Use \"replace\" to override completely\n    \"content\": [\"researcher\", \"thinker\"]\n  }\n}\n```\n\n2. Verify agent names are correct (no typos)\n\n## Performance Issues\n\n### Agent Taking Too Long\n\n**Causes:**\n\n- Complex prompts causing slow generation\n- Too many tools enabled\n- Large context from message history\n\n**Solutions:**\n\n1. Simplify prompts and remove unnecessary instructions\n2. Limit `toolNames` to only required tools\n3. Set `includeMessageHistory: false` for stateless agents\n4. Use faster models for simple tasks:\n\n```json\n{\n  \"model\": \"anthropic/claude-3-5-haiku-20241022\" // Faster model\n}\n```\n\n### High Credit Usage\n\n**Causes:**\n\n- Using expensive models unnecessarily\n- Agents spawning too many sub-agents\n- Large context windows\n\n**Solutions:**\n\n1. Use cost-effective models:\n\n```json\n{\n  \"model\": \"google/gemini-2.5-flash\" // More economical\n}\n```\n\n2. Limit spawnable agents:\n\n```json\n{\n  \"spawnableAgents\": [] // Prevent sub-agent spawning\n}\n```\n\n## File Organization Issues\n\n### Templates Not Loading\n\n**Symptoms:**\n\n- No custom agents available\n- Validation errors on startup\n\n**Debug Steps:**\n\n1. Check directory structure:\n\n```markdown\nyour-project/\n├── .agents/\n│ └── templates/\n│ ├── my-agent.json\n│ └── my-prompts.md\n```\n\n2. Verify file permissions:\n\n```bash\nls -la .agents/templates/\n```\n\n3. Check for hidden characters or encoding issues:\n\n```bash\nfile .agents/templates/*.json\n```\n\n## Best Practices for Debugging\n\n### 1. Start Simple\n\nBegin with minimal overrides and add complexity gradually:\n\n```json\n{\n  \"id\": \"CodebuffAI/reviewer\",\n  \"override\": true,\n  \"model\": \"anthropic/claude-4-sonnet-20250522\"\n}\n```\n\n### 2. Use Validation Tools\n\n- JSON validator: `cat file.json | jq`\n- File existence: `ls -la .agents/templates/`\n- Syntax check: Most editors highlight JSON errors\n\n### 3. Check Logs\n\nRestart Codebuff to see validation errors:\n\n```bash\ncodebuff  # Look for error messages on startup\n```\n\n### 4. Test Incrementally\n\nAdd one override at a time to isolate issues:\n\n1. Test basic override (model change)\n2. Add simple prompt override\n3. Add external file reference\n4. Add tool modifications\n\n### 5. Use Version Control\n\nTrack your agent templates in git to easily revert problematic changes:\n\n```bash\ngit add .agents/\ngit commit -m \"Add custom reviewer agent\"\n```\n\n## Getting Help\n\nIf you're still experiencing issues:\n\n1. **Check the logs**: Look for specific error messages when starting Codebuff\n2. **Simplify**: Remove customizations until it works, then add back gradually\n3. **Community**: Join our [Discord](https://codebuff.com/discord) for real-time help\n4. **Documentation**: Review the [Agent Reference](/docs/agents#agent-reference) for complete field descriptions\n\n## Quick Reference\n\n### Valid Override Types\n\n- `\"append\"` - Add to existing content\n- `\"prepend\"` - Add before existing content\n- `\"replace\"` - Replace entire content\n\n### Required Fields for New Agents\n\n- `id`, `version`, `override: false`\n- `displayName`, `purpose`, `model`\n- `systemPrompt`, `instructionsPrompt`, `stepPrompt`\n\n### Common File Paths\n\n- Agent templates: `.agents/templates/*.json`\n- External prompts: `.agents/templates/*.md`\n- Project root: `./` (for absolute paths)\n",
+          "postContent": "---\ntitle: 'Troubleshooting Agent Customization'\nsection: 'agents'\ntags: ['troubleshooting', 'debugging', 'agents']\norder: 5\n---\n\n# Troubleshooting Agent Customization\n\nQuick fixes for common agent customization issues.\n\n## Quick Fix Checklist\n\n1. **Restart Codebuff** to reload templates\n2. **Check JSON syntax:** `cat your-agent-file.json | jq`\n3. **Verify file paths** are relative to project root\n4. **Ensure `\"override\": true`** is set for overrides\n\n## Common Errors\n\n### \"Agent not found\"\n\n```text\nError: Agent 'my-custom-agent' not found\n```\n\n**Fix:** Check agent ID spelling, file location (`.agents/templates/`), JSON syntax (`cat file.json | jq`)\n\n### \"Invalid spawnable agent\"\n\n```text\nValidation error: spawnableAgents contains invalid agent 'researcher-typo'\n```\n\n**Fix:** Check spelling against [built-in agents list](/docs/agents#h2-built-in-agents), use exact IDs\n\n### \"Path not found\" Error\n\n```text\nError: Cannot resolve prompt file './my-prompt.md'\n```\n\n**Causes:**\n\n- File doesn't exist at specified path\n- Incorrect relative path resolution\n- File permissions issue\n\n**Solutions:**\n\n1. Use paths relative to project root: `.agents/templates/my-prompt.md`\n2. Verify file exists: `ls -la .agents/templates/my-prompt.md`\n3. Check file permissions are readable\n\n## JSON Schema Issues\n\n### Invalid Override Type\n\n```json\n{\n  \"systemPrompt\": {\n    \"type\": \"add\", // ❌ Invalid\n    \"content\": \"...\"\n  }\n}\n```\n\n**Fix:** Use valid override types:\n\n```json\n{\n  \"systemPrompt\": {\n    \"type\": \"append\", // ✅ Valid: append, prepend, replace\n    \"content\": \"...\"\n  }\n}\n```\n\n### Missing Required Fields\n\n```json\n{\n  \"id\": \"my-agent\",\n  \"override\": false,\n  \"displayName\": \"My Agent\"\n  // ❌ Missing required fields for new agents\n}\n```\n\n**Fix:** Include all required fields for new agents:\n\n```json\n{\n  \"id\": \"my-agent\",\n  \"version\": \"1.0.0\",\n  \"override\": false,\n  \"displayName\": \"My Agent\",\n  \"purpose\": \"Brief description of the agent's purpose\",\n  \"model\": \"anthropic/claude-4-sonnet-20250522\",\n  \"systemPrompt\": \"You are a helpful assistant...\",\n  \"instructionsPrompt\": \"Process the user's request...\",\n  \"stepPrompt\": \"Continue working on the task...\"\n}\n```\n\n### \"Path not found\"\n\n**Fix:** Use project root relative paths: `.agents/templates/my-prompt.md`, verify file exists\n\n## Agent Behavior Issues\n\n### Agent Not Using Custom Prompts\n\n**Symptoms:**\n\n- Agent behaves like default version\n- Custom instructions ignored\n\n**Debug Steps:**\n\n1. Check override is properly applied:\n\n```bash\n# Restart Codebuff to reload templates\ncodebuff\n```\n\n2. Verify override syntax:\n\n```json\n{\n  \"id\": \"CodebuffAI/reviewer\", // ✅ Exact match required\n  \"override\": true, // ✅ Must be true for overrides\n  \"systemPrompt\": {\n    \"type\": \"append\", // ✅ Valid override type\n    \"content\": \"Custom instructions...\"\n  }\n}\n```\n\n### Agent Spawning Wrong Sub-agents\n\n**Symptoms:**\n\n- Unexpected agents being created\n- Missing expected specialized agents\n\n**Solutions:**\n\n1. Check `spawnableAgents` configuration:\n\n```json\n{\n  \"spawnableAgents\": {\n    \"type\": \"replace\", // Use \"replace\" to override completely\n    \"content\": [\"researcher\", \"thinker\"]\n  }\n}\n```\n\n2. Verify agent names are correct (no typos)\n\n## Performance Issues\n\n### Agent Taking Too Long\n\n**Causes:**\n\n- Complex prompts causing slow generation\n- Too many tools enabled\n- Large context from message history\n\n**Solutions:**\n\n1. Simplify prompts and remove unnecessary instructions\n2. Limit `toolNames` to only required tools\n3. Set `includeMessageHistory: false` for stateless agents\n4. Use faster models for simple tasks:\n\n```json\n{\n  \"model\": \"anthropic/claude-3-5-haiku-20241022\" // Faster model\n}\n```\n\n### High Credit Usage\n\n**Causes:**\n\n- Using expensive models unnecessarily\n- Agents spawning too many sub-agents\n- Large context windows\n\n**Solutions:**\n\n1. Use cost-effective models:\n\n```json\n{\n  \"model\": \"google/gemini-2.5-flash\" // More economical\n}\n```\n\n2. Limit spawnable agents:\n\n```json\n{\n  \"spawnableAgents\": [] // Prevent sub-agent spawning\n}\n```\n\n## File Organization Issues\n\n### Templates Not Loading\n\n**Symptoms:**\n\n- No custom agents available\n- Validation errors on startup\n\n**Debug Steps:**\n\n1. Check directory structure:\n\n```markdown\nyour-project/\n├── .agents/\n│ ├── my-agent.json\n│ └── my-prompts.md\n```\n\n2. Verify file permissions:\n\n```bash\nls -la .agents/templates/\n```\n\n3. Check for hidden characters or encoding issues:\n\n```bash\nfile .agents/templates/*.json\n```\n\n## Best Practices for Debugging\n\n### 1. Start Simple\n\nBegin with minimal overrides and add complexity gradually:\n\n```json\n{\n  \"id\": \"CodebuffAI/reviewer\",\n  \"override\": true,\n  \"model\": \"anthropic/claude-4-sonnet-20250522\"\n}\n```\n\n### 2. Use Validation Tools\n\n- JSON validator: `cat file.json | jq`\n- File existence: `ls -la .agents/templates/`\n- Syntax check: Most editors highlight JSON errors\n\n### 3. Check Logs\n\nRestart Codebuff to see validation errors:\n\n```bash\ncodebuff  # Look for error messages on startup\n```\n\n### 4. Test Incrementally\n\nAdd one override at a time to isolate issues:\n\n1. Test basic override (model change)\n2. Add simple prompt override\n3. Add external file reference\n4. Add tool modifications\n\n### 5. Use Version Control\n\nTrack your agent templates in git to easily revert problematic changes:\n\n```bash\ngit add .agents/\ngit commit -m \"Add custom reviewer agent\"\n```\n\n## Getting Help\n\nIf you're still experiencing issues:\n\n1. **Check the logs**: Look for specific error messages when starting Codebuff\n2. **Simplify**: Remove customizations until it works, then add back gradually\n3. **Community**: Join our [Discord](https://codebuff.com/discord) for real-time help\n4. **Documentation**: Review the [Agent Reference](/docs/agents#agent-reference) for complete field descriptions\n\n## Quick Reference\n\n### Valid Override Types\n\n- `\"append\"` - Add to existing content\n- `\"prepend\"` - Add before existing content\n- `\"replace\"` - Replace entire content\n\n### Required Fields for New Agents\n\n- `id`, `version`, `override: false`\n- `displayName`, `purpose`, `model`\n- `systemPrompt`, `instructionsPrompt`, `stepPrompt`\n\n### Common File Paths\n\n- Agent templates: `.agents/templates/*.json`\n- External prompts: `.agents/templates/*.md`\n- Project root: `./` (for absolute paths)\n"
         }
       ]
     },
@@ -2426,4 +2426,4 @@
       ]
     }
   ]
-}
+}
\ No newline at end of file
diff --git a/web/src/content/advanced/claude-code-comparison.mdx b/web/src/content/advanced/claude-code-comparison.mdx
index 4852163fe1..43e40baabd 100644
--- a/web/src/content/advanced/claude-code-comparison.mdx
+++ b/web/src/content/advanced/claude-code-comparison.mdx
@@ -22,7 +22,7 @@ Codebuff might be a better choice if you value:
 
 - Speed: Codebuff is [nearly 4 times faster](https://x.com/jahooma/status/1894224663817195599)
 - Cost: Codebuff is one third the cost of Claude Code for equivalent tasks and even less for back-and-forth conversation
-- Codebase Analysis: Codebuff pulls more context from scanning your entire codebase, rather than file-by-file. Codebuff also [blends different models](/docs/advanced#what-models-do-you-use?) based on their strengths to provide more accurate results.
+- Codebase Analysis: Codebuff pulls more context from scanning your entire codebase, rather than file-by-file. Codebuff also [blends different models](/docs/advanced#what-models-do-you-use) based on their strengths to provide more accurate results.
 - Staying in Flow: Codebuff requires fewer confirmation prompts for file edits and command execution.
 - Focused changes: Codebuff does just what you asked for, while Claude Code will often get carried away editing more and more files.
 - SDK and Programmatic Access: Codebuff provides a full TypeScript SDK for programmatic integration, allowing you to create custom workflows and embed AI coding capabilities into your own tools.
diff --git a/web/src/content/advanced/config.mdx b/web/src/content/advanced/config.mdx
index 66cd0bf4ee..850396a3aa 100644
--- a/web/src/content/advanced/config.mdx
+++ b/web/src/content/advanced/config.mdx
@@ -75,4 +75,4 @@ If your startup processes aren't working as expected:
 3. Check the process output in the specified log files if you've configured them
 4. Make sure the JSON syntax in your configuration file is valid
 
-Need more help? Check out our [Troubleshooting](/docs/advanced/troubleshooting) guide or join our [Discord community](https://discord.gg/mcWTGjgTj3).
+Need more help? Check out our [Troubleshooting](/docs/advanced#troubleshooting) guide or join our [Discord community](https://discord.gg/mcWTGjgTj3).
diff --git a/web/src/content/agents/troubleshooting-agent-customization.mdx b/web/src/content/agents/troubleshooting-agent-customization.mdx
index f892feca8f..baa1b0a73e 100644
--- a/web/src/content/agents/troubleshooting-agent-customization.mdx
+++ b/web/src/content/agents/troubleshooting-agent-customization.mdx
@@ -32,7 +32,7 @@ Error: Agent 'my-custom-agent' not found
 Validation error: spawnableAgents contains invalid agent 'researcher-typo'
 ```
 
-**Fix:** Check spelling against [built-in agents list](/docs/agents/agent-reference#available-built-in-agents), use exact IDs
+**Fix:** Check spelling against [built-in agents list](/docs/agents#h2-built-in-agents), use exact IDs
 
 ### "Path not found" Error
 
@@ -294,7 +294,7 @@ If you're still experiencing issues:
 1. **Check the logs**: Look for specific error messages when starting Codebuff
 2. **Simplify**: Remove customizations until it works, then add back gradually
 3. **Community**: Join our [Discord](https://codebuff.com/discord) for real-time help
-4. **Documentation**: Review the [Agent Reference](/docs/agents/agent-reference) for complete field descriptions
+4. **Documentation**: Review the [Agent Reference](/docs/agents#agent-reference) for complete field descriptions
 
 ## Quick Reference
 
diff --git a/web/src/content/help/faq.mdx b/web/src/content/help/faq.mdx
index 4d88c43232..c0f4fafd56 100644
--- a/web/src/content/help/faq.mdx
+++ b/web/src/content/help/faq.mdx
@@ -88,4 +88,4 @@ Anthropic recently released [Claude Code](https://docs.anthropic.com/en/docs/age
 
 We're happy to answer! Contact us at [support@codebuff.com](mailto:support@codebuff.com) or [join our Discord](https://discord.gg/mcWTGjgTj3)!
 
-Having technical issues? Check out our [Troubleshooting](/docs/advanced/troubleshooting) guide for solutions to common problems.
+Having technical issues? Check out our [Troubleshooting](/docs/advanced#troubleshooting) guide for solutions to common problems.
diff --git a/web/src/content/help/getting-started.mdx b/web/src/content/help/getting-started.mdx
index 49af161035..09865e4ce1 100644
--- a/web/src/content/help/getting-started.mdx
+++ b/web/src/content/help/getting-started.mdx
@@ -51,4 +51,4 @@ If you run into issues during installation:
    - Try reinstalling Node using [nvm or fnm](https://nodejs.org/en/download)
    - Run the Codebuff install command again
 
-If you're still experiencing issues, check out our [Troubleshooting](/docs/advanced/troubleshooting) guide or join our [Discord community](https://codebuff.com/discord)!
+If you're still experiencing issues, check out our [Troubleshooting](/docs/advanced#troubleshooting) guide or join our [Discord community](https://codebuff.com/discord)!