docs: update MDX content and docs configuration

Author: brandonkachen

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to Codebuff
 
-Hey there! 👋 Thanks for wanting to contribute to Codebuff. Whether you're squashing bugs, building cool features, or making our docs better, we're excited to have you aboard!
+Hey there! 👋 Thanks for contributing to Codebuff. Bug fixes, features, and documentation improvements are welcome.
 
 ## Getting Started
 
@@ -147,15 +147,13 @@ Not sure where to start? Here are some great ways to jump in:
 
 ### Development Workflow
 
-Here's how we like to work together:
+1. **Fork and branch** - Create a fork and a new branch
+2. **Follow style guidelines** - See below
+3. **Test** - Write tests for new features, run `bun test`
+4. **Type check** - Run `bun run typecheck`
+5. **Submit a PR** - Clear description of changes
 
-1. **Fork and branch** - Create your own fork and a new branch for your changes
-2. **Code away** - Follow our style guidelines (more on that below)
-3. **Test it** - Write tests for new features and run `bun test` to make sure everything works
-4. **Type check** - Run `bun run typecheck` to catch any TypeScript issues
-5. **Submit a PR** - Open a pull request with a clear description of what you built and why
-
-_Pro tip: Small, focused PRs are easier to review and merge quickly!_
+Small PRs merge faster.
 
 ### Code Style Guidelines
 
@@ -218,27 +216,25 @@ test: add unit tests for file operations
 
 ## Areas Where We Need Help
 
-There are tons of ways to make Codebuff better! Here are some areas where your skills could really shine:
-
 ### 🤖 **Agent Development**
 
-Build specialized agents in `.agents/` for different languages, frameworks, or workflows. Think React experts, Python debuggers, or Git wizards!
+Build agents in `.agents/` for different languages, frameworks, or workflows.
 
 ### 🔧 **Tool System**
 
-Add new capabilities in `common/src/tools` and the SDK helpers - file operations, API integrations, development environment helpers. The sky's the limit!
+Add capabilities in `common/src/tools` and SDK helpers: file operations, API integrations, dev environment helpers.
 
 ### 📦 **SDK Improvements**
 
-Make the SDK in `sdk/` even more powerful with new methods, better TypeScript support, or killer integration examples.
+New methods, better TypeScript support, integration examples in `sdk/`.
 
-### 💻 **CLI Magic**
+### 💻 **CLI**
 
-Enhance the user experience in `cli/` with smoother commands, better error messages, or interactive features that make developers smile.
+Improve `cli/`: better commands, error messages, interactive features.
 
 ### 🌐 **Web Dashboard**
 
-Level up the web interface in `web/` with better agent management, project templates, analytics, or any UX improvements you can dream up.
+Improve `web/`: agent management, project templates, analytics.
 
 ## Getting Help
 

README.md

@@ -83,17 +83,17 @@ To get started building your own agents, run:
 codebuff init-agents
 ```
 
-> 💡 **Tip**: This command creates a comprehensive agent development guide at `.agents/README.md` (293 lines) with detailed documentation, complete examples, and full TypeScript type definitions. Start there for complete guidance.
+> 💡 **Tip**: This creates an agent development guide at `.agents/README.md` with examples and TypeScript types.
 
 This creates:
 ```
 .agents/
-├── README.md              # Comprehensive 293-line agent guide
-├── my-custom-agent.ts     # Working agent template to edit
-├── package.json           # NPM package configuration
-├── LICENSE                # Apache-2.0 license for publishing
-├── examples/              # 3 example agents (basic → advanced)
-└── types/                 # Complete TypeScript definitions
+├── README.md              # Agent development guide
+├── my-custom-agent.ts     # Working agent template
+├── package.json           # NPM package config
+├── LICENSE                # Apache-2.0 license
+├── examples/              # 3 example agents
+└── types/                 # TypeScript definitions
 ```
 
 You can write agent definition files that give you maximum control over agent behavior.
@@ -146,7 +146,7 @@ const client = new CodebuffClient({
 // 2. Do a coding task...
 const result = await client.run({
   agent: 'base', // Codebuff's base coding agent
-  prompt: 'Add comprehensive error handling to all API endpoints',
+  prompt: 'Add error handling to all API endpoints',
   handleEvent: (event) => {
     console.log('Progress', event)
   },
@@ -174,13 +174,13 @@ Learn more about the SDK [here](https://www.npmjs.com/package/@codebuff/sdk).
 
 ## Why choose Codebuff
 
-**Deep customizability**: Create sophisticated agent workflows with TypeScript generators that mix AI generation with programmatic control. Define custom agents that spawn subagents, implement conditional logic, and orchestrate complex multi-step processes that adapt to your specific use cases.
+**Custom workflows**: TypeScript generators let you mix AI generation with programmatic control. Agents can spawn subagents, branch on conditions, and run multi-step processes.
 
 **Any model on OpenRouter**: Unlike Claude Code which locks you into Anthropic's models, Codebuff supports any model available on [OpenRouter](https://openrouter.ai/models) - from Claude and GPT to specialized models like Qwen, DeepSeek, and others. Switch models for different tasks or use the latest releases without waiting for platform updates.
 
 **Reuse any published agent**: Compose existing [published agents](https://www.codebuff.com/store) to get a leg up. Codebuff agents are the new MCP!
 
-**Fully customizable SDK**: Build Codebuff's capabilities directly into your applications with a complete TypeScript SDK. Create custom tools, integrate with your CI/CD pipeline, build AI-powered development environments, or embed intelligent coding assistance into your products.
+**SDK**: Build Codebuff into your applications. Create custom tools, integrate with CI/CD, or embed coding assistance into your products.
 
 ## Contributing to Codebuff
 
@@ -232,7 +232,7 @@ Some ways you can help:
 
 **Documentation**: [codebuff.com/docs](https://codebuff.com/docs)
 
-**Community**: [Discord](https://codebuff.com/discord) - Join our friendly community
+**Community**: [Discord](https://codebuff.com/discord)
 
 **Issues & Ideas**: [GitHub Issues](https://github.com/CodebuffAI/codebuff/issues)
 

web/contentlayer.config.ts

@@ -1,4 +1,4 @@
-import { defineDocumentType, makeSource } from 'contentlayer/source-files'
+import { defineDocumentType, makeSource } from 'contentlayer2/source-files'
 
 import { remarkCodeToCodeDemo } from './src/lib/remark-code-to-codedemo'
 

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

@@ -1,6 +1,6 @@
 import { Check, Link } from 'lucide-react'
 import Image from 'next/image'
-import { useMDXComponent } from 'next-contentlayer/hooks'
+import { useMDXComponent } from 'next-contentlayer2/hooks'
 import React, { useState, useEffect } from 'react'
 
 import { CodeDemo } from './code-demo'

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

@@ -14,7 +14,7 @@ Both tools:
 - Run in your terminal
 - Understand your entire codebase context
 - Can edit files and execute terminal commands
-- Use Claude Sonnet 4 as their primary model
+- Use Claude models (Codebuff uses Claude Opus 4.5 as its orchestrator)
 
 ## When to Choose Codebuff
 

web/src/content/advanced/config.mdx

@@ -7,8 +7,37 @@ order: 2
 
 # How does Codebuff actually work?
 
-Codebuff scans your repo with tree-sitter and builds a quick index of the code. That index makes it fast to find files when you ask for help.
+Codebuff runs multiple agents, each tuned for a specific task.
 
-The server is stateless. It proxies requests to Anthropic, OpenAI, or Gemini over websockets and streams results back to the CLI.
+## The Orchestrator
 
-We use a fast model to pick files, load the right snippets into context, and let Claude Sonnet propose an edit. The main agent can hand work to other agents for planning or file search when needed.
+The main agent ("Buffy") runs on Claude Opus 4.5. It reads your prompt, gathers context, and spawns subagents. The orchestrator is available in several variants:
+
+- [`base2`](/publishers/codebuff/agents/base2) - Default mode orchestrator
+- [`base2-lite`](/publishers/codebuff/agents/base2-lite) - Lite mode (faster, cheaper)
+- [`base2-max`](/publishers/codebuff/agents/base2-max) - Max mode (best-of-N selection)
+- [`base2-plan`](/publishers/codebuff/agents/base2-plan) - Plan mode (no file writes)
+
+## Subagents
+
+- [**File Picker**](/publishers/codebuff/agents/file-picker) (Gemini 2.0 Flash) - finds relevant files
+- [**Code Searcher**](/publishers/codebuff/agents/code-searcher) - grep-style pattern matching
+- [**Researcher**](/publishers/codebuff/agents/researcher) (Grok 4 Fast) - web and docs lookup
+- [**Thinker**](/publishers/codebuff/agents/thinker) (GPT-5.1, Gemini 2.5 Pro) - works through hard problems
+- [**Editor**](/publishers/codebuff/agents/editor) (GPT-5.1, Claude Opus 4.5) - writes and modifies code
+- [**Reviewer**](/publishers/codebuff/agents/reviewer) (Claude Sonnet 4.5) - catches bugs and style issues
+- [**Commander**](/publishers/codebuff/agents/commander) (Grok 4 Fast or Claude Sonnet 4.5) - runs terminal commands
+
+## Best-of-N Selection (Max Mode)
+
+In Max mode, Codebuff spawns multiple editors with different strategies. A selector compares the outputs and picks the best one.
+
+## The Pipeline
+
+1. Tree-sitter scans your repo and builds a code map
+2. File pickers and searchers find relevant code
+3. Thinkers analyze the problem if needed
+4. Editors generate changes
+5. Reviewers check for issues; commanders run tests
+
+The server is stateless. It streams requests to model providers (Anthropic, OpenAI, Google, xAI) over websockets. Your code stays local; only relevant context is sent.

web/src/content/advanced/how-does-it-work.mdx

@@ -7,7 +7,7 @@ order: 4
 
 # Working with Large Projects
 
-Codebuff runs fine on very large repos (we test against the VS Code codebase). If it starts to wander or burn too many credits, use the tips below.
+Codebuff works on large repos (we test against VS Code). If it wanders or burns credits, try these.
 
 ## Directory-Based Approach
 

web/src/content/advanced/large-projects.mdx

@@ -7,7 +7,7 @@ order: 7
 
 # SDK & Programmatic Access
 
-The Codebuff SDK (`@codebuff/sdk`) lets you run Codebuff agents from your own code.
+Run Codebuff agents from your own code with `@codebuff/sdk`.
 
 ## Installation
 
@@ -17,10 +17,12 @@ npm install @codebuff/sdk
 
 ## Prerequisites
 
-Get your API key from [codebuff.com/api-keys](https://www.codebuff.com/api-keys).
+API key: [codebuff.com/api-keys](https://www.codebuff.com/api-keys)
 
 ## Quick Start
 
+Use the [`base`](/publishers/codebuff/agents/base) agent (or any agent from the [Agent Store](/store)) to run tasks:
+
 ```typescript
 import { CodebuffClient } from '@codebuff/sdk'
 
@@ -40,7 +42,7 @@ const result = await client.run({
 
 ## Continuing Conversations
 
-Pass the previous run state to maintain context across multiple interactions:
+Pass the previous run state to keep context:
 
 ```typescript
 // First run
@@ -59,8 +61,6 @@ const run2 = await client.run({
 
 ## Custom Agents
 
-Define your own agents with custom models, tools, and prompts:
-
 ```typescript
 import type { AgentDefinition } from '@codebuff/sdk'
 
@@ -81,8 +81,6 @@ await client.run({
 
 ## Custom Tools
 
-Extend agent capabilities with your own tools:
-
 ```typescript
 import { z } from 'zod/v4'
 import { getCustomToolDefinition } from '@codebuff/sdk'
@@ -110,8 +108,6 @@ await client.run({
 
 ## Loading Local Agents
 
-Load agent definitions from your `.agents/` directory:
-
 ```typescript
 import { loadLocalAgents, CodebuffClient } from '@codebuff/sdk'
 
@@ -129,8 +125,6 @@ await client.run({
 
 ### `CodebuffClient`
 
-Main client for interacting with Codebuff.
-
 ```typescript
 const client = new CodebuffClient({
   apiKey: string,        // Required: Your Codebuff API key
@@ -140,8 +134,6 @@ const client = new CodebuffClient({
 
 ### `client.run(options)`
 
-Run an agent with the specified options.
-
 <MarkdownTable>
 | Parameter | Type | Description |
 | --- | --- | --- |
@@ -159,26 +151,24 @@ Run an agent with the specified options.
 
 ### Event Types
 
-The `handleEvent` callback receives events during execution:
-
 - `agent_start` / `agent_finish` - Agent lifecycle
 - `tool_call` / `tool_result` - Tool execution
 - `text` - Text responses
 - `error` - Error events
 
 ### Return Value
 
-Returns a `RunState` object containing:
+`RunState` object:
 
 - `sessionState` - Internal state for continuing conversations
 - `output` - The agent's output (text, error, or structured data)
 
 ## Use Cases
 
-- CI/CD pipelines (code review, test generation, refactoring)
-- Batch processing across multiple files
-- Embedding in VS Code extensions or web apps
-- Scripts for repetitive coding tasks
+- CI/CD pipelines: code review, test generation, refactoring
+- Batch processing
+- VS Code extensions, web apps
+- Automation scripts
 
 ## Examples
 
@@ -214,6 +204,8 @@ async function generateTests(code: string) {
 
 ### Code Review in CI
 
+Use the [`reviewer`](/publishers/codebuff/agents/reviewer) agent for automated code review:
+
 ```typescript
 import { CodebuffClient } from '@codebuff/sdk'
 
@@ -355,6 +347,6 @@ jobs:
 
 ## Resources
 
-- [GitHub Repository](https://github.com/CodebuffAI/codebuff) - Source code
-- [Agent Store](https://codebuff.com/store) - Browse available agents
-- [API Keys](https://codebuff.com/api-keys) - Get your API key
+- [GitHub](https://github.com/CodebuffAI/codebuff)
+- [Agent Store](https://codebuff.com/store)
+- [API Keys](https://codebuff.com/api-keys)