feat(docs): add Developer Guide section to cookbook

content/docs/cookbook/advanced/contributing.mdx

@@ -0,0 +1,59 @@
+---
+title: Contributing
+description: How to set up a dev environment and contribute to BitRouter
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+# Contributing
+
+<Callout>First time? Start by picking a [good first issue](https://github.com/bitrouter/bitrouter/issues?q=label%3A%22good+first+issue%22) on GitHub.</Callout>
+
+## Prerequisites
+
+{/* Node/Bun/Go versions, required global tools */}
+
+## Local Dev Setup
+
+{/* Clone, install deps, run tests, start the dev server */}
+
+```bash
+# commands here
+```
+
+## Project Structure
+
+{/* Quick map of the repo — where the core router lives, where plugins live, where tests live */}
+
+```
+bitrouter/
+├── core/        # routing engine
+├── plugins/     # built-in plugins
+├── sdk/         # TypeScript + Python SDKs
+├── docs/        # this site
+└── tests/
+```
+
+## Running Tests
+
+{/* Unit, integration, and e2e test commands */}
+
+```bash
+# commands here
+```
+
+## PR Conventions
+
+{/* Branch naming, commit style, PR description template, what a good PR looks like */}
+
+## Code Review Process
+
+{/* Who reviews, typical turnaround, what reviewers look for */}
+
+## Release Process
+
+{/* How versions are cut — who does it, what triggers it */}
+
+## Getting Help
+
+If you're stuck, open a [Discussion](https://github.com/bitrouter/bitrouter/discussions) or ask in Discord.

content/docs/cookbook/advanced/custom-plugins.mdx

@@ -0,0 +1,104 @@
+---
+title: Build Custom Plugins
+description: Extend BitRouter's request lifecycle with your own plugins
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+
+# Build Custom Plugins
+
+<Callout>Requires BitRouter ≥ X.Y. Basic TypeScript knowledge recommended.</Callout>
+
+## Overview
+
+{/* What plugins can do: intercept requests, transform payloads, add headers, short-circuit with cached responses, emit metrics */}
+
+## Plugin Interface
+
+{/* The full Plugin interface type — show the hooks available */}
+
+<Tabs items={['TypeScript', 'JavaScript']}>
+  <Tab value="TypeScript">
+```typescript
+// plugin interface definition goes here
+```
+  </Tab>
+  <Tab value="JavaScript">
+```javascript
+// plugin interface definition goes here
+```
+  </Tab>
+</Tabs>
+
+## File Structure
+
+{/* Minimal plugin package layout */}
+
+```
+my-plugin/
+├── package.json
+├── src/
+│   └── index.ts
+└── dist/
+    └── index.js
+```
+
+## Lifecycle Hooks
+
+{/* Table or list of each hook, when it fires, what it receives, what it can return */}
+
+| Hook | Fires | Use Case |
+|------|-------|----------|
+| `onRequest` | Before routing | Auth, rate limiting, payload mutation |
+| `onRoute` | After route is selected | Override routing decision |
+| `onResponse` | After provider responds | Caching, logging, response mutation |
+| `onError` | On provider error | Fallback logic, alerting |
+
+## Building Your First Plugin
+
+{/* Step-by-step: init project, implement a hook, test locally */}
+
+### 1. Initialize the Project
+
+```bash
+# commands here
+```
+
+### 2. Implement a Hook
+
+```typescript
+// example hook implementation
+```
+
+### 3. Test Locally
+
+```bash
+# how to point a local BitRouter instance at the plugin
+```
+
+## Registering the Plugin
+
+{/* How to add the plugin to bitrouter.yaml */}
+
+```yaml
+plugins:
+  - path: ./my-plugin/dist/index.js
+```
+
+## Publishing
+
+{/* Optional: how to publish to npm and reference by package name */}
+
+## Troubleshooting
+
+🔴 **Plugin not loading** — _description and fix_
+
+🟡 **Hook fires but changes are ignored** — _description and fix_
+
+🔵 **TypeScript type errors on Plugin interface** — _description and fix_
+
+## Next Steps
+
+- [SDK Guide](/docs/cookbook/advanced/sdk-guide)
+- [GitHub CI/CD](/docs/cookbook/advanced/github-cicd)

content/docs/cookbook/advanced/index.mdx

@@ -0,0 +1,18 @@
+---
+title: Developer Guide
+description: Deep-dive tutorials for power users and teams running BitRouter in production
+---
+
+import { Cards, Card } from 'fumadocs-ui/components/card';
+
+# Developer Guide
+
+Tutorials for users who want to go beyond basic setup — extending BitRouter with plugins, the SDK, and contributing to the project.
+
+## Tutorials
+
+| Guide | What You'll Build |
+|-------|-------------------|
+| [**Custom Plugins**](/docs/cookbook/advanced/custom-plugins) | A first-party plugin that hooks into BitRouter's request lifecycle |
+| [**SDK Guide**](/docs/cookbook/advanced/sdk-guide) | A TypeScript/Python app built on the BitRouter SDK |
+| [**Contributing**](/docs/cookbook/advanced/contributing) | Set up your dev environment and open your first PR |

content/docs/cookbook/advanced/meta.json

@@ -0,0 +1,9 @@
+{
+  "title": "Developer Guide",
+  "pages": [
+    "index",
+    "custom-plugins",
+    "sdk-guide",
+    "contributing"
+  ]
+}

content/docs/cookbook/advanced/sdk-guide.mdx

@@ -0,0 +1,107 @@
+---
+title: BitRouter SDK Guide
+description: Build applications on top of BitRouter using the official SDK
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+
+# BitRouter SDK Guide
+
+<Callout>The SDK wraps the REST API and adds typed client objects, streaming helpers, and retry logic. Use it instead of raw HTTP calls for any non-trivial integration.</Callout>
+
+## Installation
+
+<Tabs items={['npm', 'pip', 'pnpm', 'yarn']}>
+  <Tab value="npm">
+```bash
+npm install @bitrouter/sdk
+```
+  </Tab>
+  <Tab value="pip">
+```bash
+pip install bitrouter-sdk
+```
+  </Tab>
+  <Tab value="pnpm">
+```bash
+pnpm add @bitrouter/sdk
+```
+  </Tab>
+  <Tab value="yarn">
+```bash
+yarn add @bitrouter/sdk
+```
+  </Tab>
+</Tabs>
+
+## Client Initialization
+
+<Tabs items={['TypeScript', 'Python']}>
+  <Tab value="TypeScript">
+```typescript
+// client init example
+```
+  </Tab>
+  <Tab value="Python">
+```python
+# client init example
+```
+  </Tab>
+</Tabs>
+
+## Core APIs
+
+### Chat Completions
+
+{/* Basic request / response, with the full options object */}
+
+### Streaming
+
+{/* How to consume streamed responses — event emitter vs async iterator */}
+
+### Route Resolution
+
+{/* How to query which route BitRouter would pick for a given request, without sending it */}
+
+### Admin API
+
+{/* Reload config, inspect provider health, flush cache */}
+
+## Error Handling
+
+{/* SDK error types, retry behavior, how to override retry policy */}
+
+```typescript
+// error handling example
+```
+
+## Full Example
+
+{/* End-to-end example: init client, send a request, stream the response, handle errors */}
+
+<Tabs items={['TypeScript', 'Python']}>
+  <Tab value="TypeScript">
+```typescript
+// full example
+```
+  </Tab>
+  <Tab value="Python">
+```python
+# full example
+```
+  </Tab>
+</Tabs>
+
+## Troubleshooting
+
+🔴 **`ConnectionRefused` on client init** — _description and fix_
+
+🟡 **Streamed response cuts off mid-token** — _description and fix_
+
+🔵 **TypeScript types out of sync with server version** — _description and fix_
+
+## Next Steps
+
+- [Custom Plugins](/docs/cookbook/advanced/custom-plugins)
+- [API Reference](/docs/api-reference)

content/docs/cookbook/meta.json

@@ -4,6 +4,7 @@
   "pages": [
     "index",
     "migration",
-    "integration"
+    "integration",
+    "advanced"
   ]
 }