docs: synchronize Codebuff vs Claude Code docs and related agent docs; improve navigation and copy-link UX across docs

Why: align with recent edits and improve hash navigation and copy-link consistency.

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>

Author: brandonkachen

web/src/app/docs/layout.tsx

@@ -2,7 +2,7 @@
 
 import { Menu } from 'lucide-react'
 import { usePathname } from 'next/navigation'
-import { useState } from 'react'
+import { useState, useEffect } from 'react'
 
 import { DocSidebar, sections } from '@/components/docs/doc-sidebar'
 import { Button } from '@/components/ui/button'
@@ -15,6 +15,23 @@ export default function DocsLayout({
 }) {
   const pathname = usePathname()
   const [open, setOpen] = useState(false)
+
+  // New: Smoothly scroll to hash target on back/forward navigation
+  useEffect(() => {
+    const handleHashChange = () => {
+      const id = window.location.hash.slice(1)
+      if (id) {
+        document.getElementById(id)?.scrollIntoView({ behavior: 'smooth' })
+      }
+    }
+
+    // If landing with a hash, ensure smooth scroll to target
+    handleHashChange()
+
+    window.addEventListener('hashchange', handleHashChange)
+    return () => window.removeEventListener('hashchange', handleHashChange)
+  }, [])
+
   return (
     <div className="pt-8">
       <div className="container flex md:space-x-8 overflow-x-hidden">

web/src/components/docs/copy-heading.tsx

@@ -29,10 +29,11 @@ export function CopyHeading({
         {...props}
         id={id}
         className="inline-block hover:cursor-pointer hover:underline -mb-4 scroll-mt-24 font-serif"
-        onClick={() =>
-          id &&
+        onClick={() => {
+          if (!id) return
+          history.pushState(null, '', `${window.location.pathname}#${id}`)
           document.getElementById(id)?.scrollIntoView({ behavior: 'smooth' })
-        }
+        }}
       >
         {title}
         <button

web/src/components/docs/mdx/mdx-components.tsx

@@ -97,6 +97,8 @@ const createHeadingWithCopyLink = (
 
     const handleClick = () => {
       if (id) {
+        // Add a history entry with the new hash and smoothly scroll
+        history.pushState(null, '', `${window.location.pathname}#${id}`)
         document.getElementById(id)?.scrollIntoView({ behavior: 'smooth' })
       }
 

web/src/content/advanced/claude-code-comparison.mdx

@@ -25,22 +25,36 @@ Codebuff might be a better choice if you value:
 - 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.
+- 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.
 
 ## When to Choose Claude Code
 
 Claude Code might be a better choice if you:
 
-- Can't use an intermediary provider, need to use the API directly from Anthropic
+- You require first-party Anthropic integration (no intermediary/proxy) for procurement, data handling, or legal reasons
+- You need enterprise security/compliance controls directly from Anthropic (e.g., SOC 2/ISO programs, data-retention controls, private/VPC networking options)
+- Your org needs centralized admin controls within Anthropic's ecosystem (SSO, RBAC, governance, auditability)
+- You prioritize early access to Anthropic model capabilities and first-party tooling
+
 
 ## Feature Comparison
 
 <MarkdownTable>
-  | Feature | Codebuff | Claude Code | | --- | --- | --- | | CLI-based
-  interaction | ✅ | ✅ | | Natural language commands | ✅ | ✅ | | Autonomous
-  test execution | ✅ | ✅ | | Deep, targeted context awareness | ✅ | ❌ | |
-  Large context window | ✅ (200k - 1M) | ✅ (200k) | | Fast diff edits (no full
-  rewrites) | ✅ | ❌ | | Accuracy at scale | ✅ | ❌ | | Cost | $ | $$$ | |
-  Polished UI | ❌ | ✅ | | Minimal interruptions | ✅ | ❌ |
+| Feature | Codebuff | Claude Code |
+| --- | --- | --- |
+| CLI-based interaction | ✅ | ✅ |
+| Natural language commands | ✅ | ✅ |
+| Autonomous test execution | ✅ | ✅ |
+| Large context window | ✅ (200k-1M) | ✅ (200k-1M) |
+| Directory-specific context awareness | ✅ | 🔄 |
+| Fast diff edits (no full rewrites) | ✅ | ❌ |
+| Cost | $ | $$ |
+| Polished UI | ❌ | ✅ |
+| Minimal interruptions | ✅ | ❌ |
+| Full-featured SDK | ✅ | ❌ |
+| Programmatic agent creation | ✅ | ❌ |
+| Project templates | ✅ | ❌ |
 </MarkdownTable>
 
 ## Summary

web/src/content/agents/creating-new-agents.mdx

@@ -6,82 +6,24 @@ order: 2
 ---
 
 # Creating New Agents
-
 Create specialized agents from scratch using TypeScript files in the `.agents/` directory.
 
 **Types:**
 
-- **LLM-based** - Use prompts and language models
-- **Programmatic** - Use TypeScript generator functions with `handleSteps`
-
-## Basic Structure
-
-Create a new TypeScript file in `.agents/` directory:
-
-**.agents/code-analyzer.ts**
-```typescript
-import { AgentDefinition } from './types/agent-definition'
-
-const definition: AgentDefinition = {
-  id: "code-analyzer",
-  displayName: "Code Analysis Expert",
-  spawnerPrompt: "Spawn for deep code analysis and refactoring suggestions",
-  model: "anthropic/claude-4-sonnet-20250522",
-
-  toolNames: ["read_files", "code_search", "spawn_agents", "write_file"],
-  spawnableAgents: ["codebuff/thinker@0.0.1", "codebuff/reviewer@0.0.1"],
-
-  handleSteps: function* ({ agentState, prompt, params }) {
-    // First, find relevant files
-    const { toolResult: files } = yield {
-      toolName: 'find_files',
-      input: { query: prompt }
-    }
-
-    // Read the most important files
-    if (files) {
-      const filePaths = JSON.parse(files).slice(0, 5)
-
-      const { toolResult } = yield {
-        toolName: 'read_files',
-        input: { paths: ['file1.ts', 'file2.ts'] }
-      }
-    }
-
-    // Spawn a thinker for deep analysis
-    yield {
-      toolName: 'spawn_agents',
-      input: {
-        agents: [{
-          agent_type: 'thinker',
-          prompt: `Analyze the code structure and suggest improvements for: ${prompt}`
-        }]
-      }
-    }
-
-    // Let the agent generate its response
-    yield 'STEP_ALL'
-
-export default definition
-```
-
-```
+  - **LLM-based** - Use prompts and language models
+  - **Programmatic** - Use TypeScript generator functions with `handleSteps`
 
 **Control Flow:**
-- `yield 'STEP'` - Run one LLM generation step
-- `yield 'STEP_ALL'` - Run until completion
-- `return` - End the agent's turn
+
+  - `yield 'STEP'` - Run one LLM generation step
+  - `yield 'STEP_ALL'` - Run until completion
+  - `return` - End the agent's turn
 
 **Accessing Context:**
-- `agentState` - Current agent state and message history
-- `prompt` - User's prompt to the agent
-- `params` - Additional parameters passed to the agent
-# Creating New Agents
-Create specialized agents from scratch using TypeScript files in the `.agents/` directory.
-**Types:**
 
-- **LLM-based** - Use prompts and language models
-- **Programmatic** - Use TypeScript generator functions with `handleSteps`
+  - `agentState` - Current agent state and message history
+  - `prompt` - User's prompt to the agent
+  - `params` - Additional parameters passed to the agent
 
 ## Basic Structure
 
@@ -118,22 +60,8 @@ const definition: AgentDefinition = {
 
 export default definition
 ```
-**.agents/templates/doc-writer-system.md**
-
-```markdown
-# Documentation Writer
-
-Create clear, comprehensive documentation for codebases.
-
-## Guidelines
-
-- Research codebase first
-- Use clear, concise language
-- Include practical examples
-- Test examples for accuracy
-```
 
-## More Domain-Specific Examples
+## Domain-Specific Examples
 
 ### API Documentation Agent
 
@@ -208,133 +136,16 @@ const definition: AgentDefinition = {
 
 export default definition
 ```
-**.agents/templates/migration-guidelines.md**
-
-```markdown
-# Database Migration Guidelines
-
-## Safety First
-
-- Always create reversible migrations (up and down)
-- Test migrations on a copy of production data
-- Add indexes for new foreign keys
-- Use transactions where supported
-
-## Performance Considerations
-
-- Avoid locking tables during peak hours
-- Use `ADD COLUMN` with defaults carefully
-- Consider batching large data changes
-- Monitor migration execution time
-
-## Best Practices
-
-- Include descriptive migration names
-- Add comments explaining complex changes
-- Validate data integrity after migration
-- Keep migrations atomic and focused
-```
-
-## Advanced Examples
-
-### Frontend Development Coordinator
-
-**.agents/frontend-coordinator.ts**
-```typescript
-import { AgentDefinition } from './types/agent-definition'
-
-const definition: AgentDefinition = {
-  id: "frontend-coordinator",
-  version: "1.0.0",
-  displayName: "Frontend Development Coordinator",
-  spawnerPrompt: "Spawn this agent to coordinate frontend development tasks with React best practices and component architecture",
-  model: "anthropic/claude-4-sonnet-20250522",
-  outputMode: "last_message",
-  includeMessageHistory: true,
-  toolNames: ["read_files", "write_file", "code_search", "spawn_agents", "end_turn"],
-  spawnableAgents: ["codebuff/reviewer@0.0.1", "codebuff/researcher@0.0.1", "codebuff/file-picker@0.0.1"],
-  inputSchema: {
-    prompt: {
-      type: "string",
-      description: "Frontend development task to coordinate"
-    }
-  },
-  systemPrompt: "You are a frontend development coordinator specializing in React best practices. Guide development workflows and ensure code quality.",
-  instructionsPrompt: "Coordinate the frontend development task, spawning appropriate agents as needed.",
-  stepPrompt: "Continue coordinating the frontend development workflow. Use end_turn when complete."
-}
-
-export default definition
-```
-
-### API Development Specialist
-
-**.agents/api-specialist.ts**
-```typescript
-import { AgentDefinition } from './types/agent-definition'
-
-const definition: AgentDefinition = {
-  id: "api-specialist",
-  version: "1.0.0",
-  displayName: "API Development Specialist",
-  spawnerPrompt: "Spawn this agent for REST API development, OpenAPI compliance, and endpoint documentation",
-  model: "anthropic/claude-4-sonnet-20250522",
-  outputMode: "last_message",
-  includeMessageHistory: true,
-  toolNames: ["read_files", "write_file", "code_search", "spawn_agents", "run_terminal_command", "end_turn"],
-  spawnableAgents: ["codebuff/reviewer@0.0.1", "codebuff/researcher@0.0.1", "codebuff/file-picker@0.0.1"],
-  inputSchema: {
-    prompt: {
-      type: "string",
-      description: "API development or documentation task"
-    }
-  },
-  systemPrompt: "You are an API development specialist focused on creating robust, well-documented REST APIs following industry standards.",
-  instructionsPrompt: "Handle the API development task, ensuring proper design patterns and documentation.",
-  stepPrompt: "Continue working on the API development task. Use end_turn when complete."
-}
-
-export default definition
-```
-
-### DevOps Automation Agent
-
-**.agents/devops-automator.ts**
-```typescript
-import { AgentDefinition } from './types/agent-definition'
-
-const definition: AgentDefinition = {
-  id: "devops-automator",
-  version: "1.0.0",
-  displayName: "DevOps Automation Specialist",
-  spawnerPrompt: "Spawn this agent for infrastructure automation, CI/CD pipelines, and deployment configuration",
-  model: "anthropic/claude-4-sonnet-20250522",
-  outputMode: "last_message",
-  includeMessageHistory: true,
-  toolNames: ["read_files", "write_file", "code_search", "spawn_agents", "run_terminal_command", "end_turn"],
-  spawnableAgents: ["codebuff/reviewer@0.0.1", "codebuff/researcher@0.0.1", "codebuff/file-picker@0.0.1"],
-  inputSchema: {
-    prompt: {
-      type: "string",
-      description: "Infrastructure or deployment automation task"
-    }
-  },
-  systemPrompt: "You are a DevOps automation specialist focused on secure, scalable infrastructure and deployment pipelines.",
-  instructionsPrompt: "Handle the infrastructure or deployment automation task with security and reliability in mind.",
-  stepPrompt: "Continue working on the DevOps automation task. Use end_turn when complete."
-}export default definition
-```
 
 ## Programmatic Agents (Advanced)
 
-**🎯 This is where Codebuff agents become truly powerful!** While LLM-based agents work well for many tasks, programmatic agents give you precise control over complex workflows.
+**🎯 This is where Codebuff agents become truly powerful!** While LLM-based agents work well for many tasks, programmatic agents give you precise control over complex workflows, while still letting you tap into LLMs when you want them.
 
 ### Why Use Programmatic Agents?
 
 - **Deterministic workflows** - Guarantee specific steps happen in order
-- **Dynamic decision making** - Branch based on actual file contents or tool results
+- **Dynamic decision making** - Branch based on your own logic
 - **Complex orchestration** - Coordinate multiple agents and tools with logic
-- **Error handling** - Catch and handle tool errors programmatically
 - **State management** - Maintain state across multiple agent steps
 
 ### How It Works
@@ -397,9 +208,9 @@ Your `handleSteps` function receives context and yields actions:
 
 ```typescript
 handleSteps: function* ({ agentState, prompt, params }) {
-  // agentState - Current conversation and agent state
-  // prompt - What the user asked this agent to do
-  // params - Additional parameters passed to the agent
+  // agentState: Current conversation and agent state
+  // prompt: What the user asked this agent to do
+  // params: Additional parameters passed to the agent
 
   // Your logic here...
 }
@@ -426,11 +237,10 @@ if (toolError) {
 
 #### 3. Control Flow Options
 
-| Command | Purpose | When to Use |
-|---------|---------|------------|
-| `yield 'STEP'` | Run one LLM generation | Need single response |
-| `yield 'STEP_ALL'` | Run until completion | Let LLM finish the task |
-| `return` | End immediately | Task complete or error |
+**Control Flow:**
+- `yield 'STEP'` - Run one LLM generation step
+- `yield 'STEP_ALL'` - Run until completion
+- `return` - End the agent's turn
 
 #### 4. Advanced Example: Conditional Workflow