diff --git a/.claude/rules/docs.md b/.claude/rules/docs.md
new file mode 100644
index 0000000..e2623e1
--- /dev/null
+++ b/.claude/rules/docs.md
@@ -0,0 +1,12 @@
+---
+globs: ["docs/**/*.md", "docs/**/*.mdx", "blog/**/*.md"]
+---
+
+- Use MDX for pages needing interactive components; plain Markdown for simple content.
+- Always include frontmatter with at least `title` and `sidebar_position`.
+- Use Mermaid code blocks for diagrams (theme plugin is configured).
+- Use Docusaurus admonitions (`:::note`, `:::tip`, `:::warning`, `:::danger`) for callouts.
+- Links between docs must be relative paths, not absolute URLs.
+- Code examples must be complete and runnable — no pseudo-code in tutorials.
+- Images go in `static/img/` and are referenced as `/img/filename.png`.
+- When adding a new doc page, update the relevant sidebar file (`sidebars.ts` or `sidebarsYellowSdk.ts`).
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 0000000..4b7f737
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,27 @@
+{
+  "permissions": {
+    "allow": [
+      "npm start*",
+      "npm run build*",
+      "npm run serve*",
+      "npm run typecheck*",
+      "npm run sync:*",
+      "npm run version:*",
+      "npx prettier*",
+      "npx docusaurus*",
+      "git status*",
+      "git log*",
+      "git diff*",
+      "git branch*",
+      "gh pr *",
+      "gh issue *",
+      "gh run *"
+    ],
+    "deny": [
+      "git push --force*",
+      "git reset --hard*",
+      "rm -rf *",
+      "npm publish*"
+    ]
+  }
+}
diff --git a/.gitignore b/.gitignore
index b580350..b173237 100644
--- a/.gitignore
+++ b/.gitignore
@@ -21,3 +21,7 @@ npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 .vercel
+
+# Claude Code local files
+.claude/settings.local.json
+.claude/agent-memory/
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..d9ff431
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,72 @@
+# Yellow Network Documentation Site
+
+Docusaurus 3.9.2 documentation site for Yellow Network / Nitrolite protocol.
+
+## Quick Reference
+
+| Command | What it does |
+|---------|-------------|
+| `npm start` | Dev server on :3000 |
+| `npm run build` | Production build |
+| `npm run serve` | Serve production build locally |
+| `npm run typecheck` | TypeScript type check |
+| `npm run sync:contracts` | Sync contract docs from nitrolite repo |
+| `npm run version:release` | Create a new versioned snapshot |
+| `npm run version:remove` | Remove a version |
+
+## Site Configuration
+
+- **Config:** `docusaurus.config.ts` — site metadata, plugins, theme config
+- **Sidebars:** `sidebars.ts` (main) + `sidebarsYellowSdk.ts` (SDK section)
+- **Tailwind:** `tailwind.config.js`, `postcss.config.js`
+- **TypeScript:** `tsconfig.json`
+- **URL:** https://docs.yellow.org
+
+## Documentation Structure
+
+| Path | Content |
+|------|---------|
+| `docs/learn/` | Conceptual explainers (architecture, state channels, clearing) |
+| `docs/guides/` | How-to guides (integration, setup) |
+| `docs/tutorials/` | Step-by-step walkthroughs |
+| `docs/api-reference/` | SDK and contract API reference |
+| `docs/protocol/` | Protocol specification |
+| `docs/build/` | Builder guides |
+
+## Versioning
+
+- Versioned docs live in `versioned_docs/` and `versioned_sidebars/`
+- `versions.json` tracks released versions
+- Scripts in `scripts/` manage version lifecycle
+
+## Content Conventions
+
+- Use **MDX** for interactive content, plain **Markdown** for simple pages
+- Always include frontmatter: `title`, `sidebar_position` (minimum)
+- Diagrams: use Mermaid (theme plugin included)
+- Admonitions: `:::note`, `:::tip`, `:::warning`, `:::danger`
+- Code blocks must be complete and runnable
+- Use relative links between docs (not absolute URLs)
+- Images go in `static/img/`
+
+## Search
+
+- Primary: Algolia DocSearch
+- Fallback: Lunr (local, `docusaurus-lunr-search`)
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `docusaurus.config.ts` | Site config, plugins, navbar, footer |
+| `sidebars.ts` | Main sidebar structure |
+| `sidebarsYellowSdk.ts` | SDK docs sidebar |
+| `src/pages/` | Custom pages (landing, whitepaper) |
+| `src/css/custom.css` | Global style overrides |
+| `scripts/sync-contracts-docs.js` | Syncs Solidity NatSpec to docs |
+
+## Git
+
+- Default branch: `master`
+- PR target: `master`
+- Commit style: `docs|feat|fix(scope): message`