diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000000..104fddd174
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,59 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch: # Allow manual triggering
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v2
+        with:
+          mdbook-version: "0.4.52"
+
+      - name: Install mdbook-mermaid
+        run: |
+          cargo install mdbook-mermaid --version 0.16.0
+          mdbook-mermaid install docs
+
+      - name: Install mdbook-linkcheck
+        run: cargo install mdbook-linkcheck --version 0.7.7
+
+      - name: Build docs
+        run: cd docs && mdbook build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs/book
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
index 94680a9f92..e9d46f791f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -62,6 +62,9 @@ release
 
 # Documentation
 docs/vercel/
+docs/book/
+docs/mermaid-init.js
+docs/mermaid.min.js
 
 # Secrets
 .env
diff --git a/AGENTS.md b/AGENTS.md
index 681311eb9c..8f40feedc9 120000
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1 +1 @@
-CLAUDE.md
\ No newline at end of file
+docs/src/AGENTS.md
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
deleted file mode 100644
index aeaca99d2b..0000000000
--- a/CLAUDE.md
+++ /dev/null
@@ -1,383 +0,0 @@
-# CLAUDE.md - Project Notes for AI Assistants
-
-## Project Context
-
-- Electron + React desktop application
-- No existing users - migration code is not needed when changing data structures
-
-## AI-Generated Content Attribution
-
-When creating public operations (commits, PRs, issues), always include:
-
-- 🤖 emoji in the title
-- "_Generated with `cmux`_" in the body (if applicable)
-
-This ensures transparency about AI-generated contributions.
-
-## PR Management
-
-After submitting or updating PRs, **always check merge status**:
-
-```bash
-gh pr view <number> --json mergeable,mergeStateStatus | jq '.'
-```
-
-This is especially important with rapid development where branches quickly fall behind.
-
-**Wait for PR checks to complete:**
-
-```bash
-./scripts/wait_pr_checks.sh <pr_number>
-```
-
-This script polls every 5 seconds and fails immediately on CI failure or bad merge status.
-
-**Key status values:**
-
-- `mergeable: "MERGEABLE"` = No conflicts, can merge
-- `mergeable: "CONFLICTING"` = Has conflicts, needs resolution
-- `mergeStateStatus: "CLEAN"` = Ready to merge ✅
-- `mergeStateStatus: "BLOCKED"` = Waiting for CI checks
-- `mergeStateStatus: "BEHIND"` = Branch is behind base, rebase needed
-- `mergeStateStatus: "DIRTY"` = Has conflicts
-
-**If branch is behind:**
-
-```bash
-git fetch origin
-git rebase origin/main
-git push --force-with-lease
-```
-
-## Project Structure
-
-- `src/main.ts` - Main Electron process
-- `src/preload.ts` - Preload script for IPC
-- `src/App.tsx` - Main React component
-- `src/config.ts` - Configuration management
-- `~/.cmux/config.json` - User configuration file
-- `~/.cmux/src/<project_name>/<branch>` - Workspace directories for git worktrees
-- `~/.cmux/sessions/<workspace_id>/chat.jsonl` - Session chat histories
-
-## Docs
-
-DO NOT visit https://sdk.vercel.ai/docs/ai-sdk-core. All of that content is already
-in `./docs/vercel/**.mdx`.
-
-(Generate them with `./scripts/update_vercel_docs.sh` if they don't exist.)
-
-## Key Features
-
-- Projects sidebar (left panel)
-- Workspaces using git worktrees
-- Configuration persisted to `~/.cmux/config.json`
-
-## Package Manager
-
-- **Using bun** - All dependencies are managed with bun (not npm)
-- Use bun over npm whenever possible, including to:
-  - Install dependencies: `bun install`
-  - Add packages: `bun add <package>`
-  - Run scripts: `bun run <script>`
-  - etc.
-
-## Development Commands
-
-- `bun dev` - Start development server (Vite + TypeScript watcher)
-- `bun start` - Start Electron app
-- `bun build` - Build the application
-- `bun lint` - Run ESLint & typecheck (also: `bun lint:fix`)
-- `bun fmt` - Format all source files with Prettier
-- `bun fmt:check` - Check if files are formatted correctly
-
-## Refactoring
-
-- When refactoring, use `git mv` to preserve file history instead of rewriting files from scratch
-
-## Testing
-
-- Always run `bun typecheck` and `bun typecheck:main` after making changes to verify types
-- **Unit tests should be colocated with their business logic** - Place unit test files (\*.test.ts) in the same directory as the code they test (e.g., `aiService.test.ts` next to `aiService.ts`)
-- E2E and integration tests may live in `./tests/` directory, but unit tests must be colocated
-- Strive to decompose complex logic away from the components and into `.src/utils/`
-  - utils should be either pure functions or easily isolated (e.g. if they operate on the FS they accept
-    a path). Testing them should not require complex mocks or setup.
-- **Integration tests:**
-  - Run specific integration test: `TEST_INTEGRATION=1 bun x jest tests/ipcMain/sendMessage.test.ts -t "test name pattern"`
-  - Run all integration tests: `TEST_INTEGRATION=1 bun x jest tests` (~35 seconds, runs 40 tests)
-  - **Performance**: Tests use `test.concurrent()` to run in parallel within each file
-  - **NEVER bypass IPC in integration tests** - Integration tests must use the real IPC communication paths (e.g., `mockIpcRenderer.invoke()`) even when it's harder. Directly accessing services (HistoryService, PartialService, etc.) or manipulating config/state directly bypasses the integration layer and defeats the purpose of the test.
-
-  **Examples of bypassing IPC (DON'T DO THIS):**
-
-  ```typescript
-  // ❌ BAD - Directly manipulating config
-  const config = env.config.loadConfigOrDefault();
-  config.projects.set(projectPath, { path: projectPath, workspaces: [] });
-  env.config.saveConfig(config);
-
-  // ❌ BAD - Directly accessing services
-  const history = await env.historyService.getHistory(workspaceId);
-  await env.historyService.appendToHistory(workspaceId, message);
-  ```
-
-  **Correct approach (DO THIS):**
-
-  ```typescript
-  // ✅ GOOD - Use IPC to save config
-  await env.mockIpcRenderer.invoke(IPC_CHANNELS.CONFIG_SAVE, {
-    projects: Array.from(projectsConfig.projects.entries()),
-  });
-
-  // ✅ GOOD - Use IPC to interact with services
-  await env.mockIpcRenderer.invoke(IPC_CHANNELS.HISTORY_GET, workspaceId);
-  await env.mockIpcRenderer.invoke(IPC_CHANNELS.WORKSPACE_CREATE, projectPath, branchName);
-  ```
-
-  **Acceptable exceptions:**
-  - Reading context (like `env.config.loadConfigOrDefault()`) to prepare IPC call parameters
-  - Verifying filesystem state (like checking if files exist) after IPC operations complete
-  - Loading existing data to avoid expensive API calls in test setup
-
-  If IPC is hard to test, fix the test infrastructure or IPC layer, don't work around it by bypassing IPC.
-
-## Styling
-
-- Colors are centralized as CSS variables in `src/styles/colors.tsx`
-- Use CSS variables (e.g., `var(--color-plan-mode)`) instead of hardcoded colors
-- Fonts are centralized as CSS variables in `src/styles/fonts.tsx`
-
-## TypeScript Best Practices
-
-- **Avoid `as any` in all contexts** - Never use `as any` casts. Instead:
-  - Use proper type narrowing with discriminated unions
-  - Leverage TypeScript's type guards and the compiler's type checking
-  - Import and reuse existing types from dependencies rather than creating anonymous clones
-  - If a type is truly complex, create a proper type definition or interface
-
-- **Use `Record<EnumType, ValueType>` for exhaustive mappings** - When mapping enum values to strings, colors, or other values, use `Record` types instead of switch statements or if/else chains. This ensures TypeScript catches missing or invalid cases at compile time.
-
-  ```typescript
-  // ✅ Good - TypeScript ensures all modes are handled
-  const MODE_COLORS: Record<UIPermissionMode, string> = {
-    plan: "var(--color-plan-mode)",
-    edit: "var(--color-edit-mode)",
-    yolo: "var(--color-yolo-mode)",
-  };
-
-  // ❌ Avoid - Can miss cases, typos won't be caught
-  switch (mode) {
-    case "plan":
-      return "blue";
-    case "edits":
-      return "green"; // Typo won't be caught!
-  }
-  ```
-
-- **Leverage TypeScript's utility types for UI-specific data** - Use `Omit`, `Pick`, and other utility types to create UI-specific versions of backend types. This prevents unnecessary re-renders and clearly separates concerns.
-
-  ```typescript
-  // Backend type with all fields
-  export interface WorkspaceMetadata {
-    id: string;
-    projectName: string;
-    permissionMode: UIPermissionMode;
-    nextSequenceNumber: number; // Backend bookkeeping
-  }
-
-  // UI type excludes backend-only fields
-  export type WorkspaceMetadataUI = Omit<WorkspaceMetadata, "nextSequenceNumber">;
-  ```
-
-  This pattern ensures:
-  - UI components don't re-render on backend-only changes
-  - Clear separation between UI and backend concerns
-  - Type safety - compiler catches if you try to access excluded fields
-  - Self-documenting code - types clearly show what data UI needs
-
-- **Prefer type-driven development** - Let TypeScript guide your architecture. When types become complex or you need many runtime checks, it often indicates a design issue. Simplify by:
-  - Creating focused types for specific contexts (UI vs backend)
-  - Using discriminated unions for state variations
-  - Leveraging the compiler to catch errors at build time
-
-- **Use `using` for leakable system resources** - Always use explicit resource management (`using` declarations) for resources that need cleanup such as child processes, file handles, database connections, etc. This ensures proper cleanup even when errors occur.
-
-  ```typescript
-  // ✅ Good - Process is automatically cleaned up
-  using process = createDisposableProcess(spawn("command"));
-  const output = await readFromProcess(process);
-  // process.kill() called automatically when going out of scope
-
-  // ❌ Avoid - Process may leak if error occurs before cleanup
-  const process = spawn("command");
-  const output = await readFromProcess(process);
-  process.kill(); // May never be reached if error thrown
-  ```
-
-- This pattern maximizes type safety and prevents runtime errors from typos or missing cases
-
-## Module Imports
-
-- **NEVER use dynamic imports** - Always use static `import` statements at the top of files. Dynamic imports (`await import()`) are a code smell that indicates improper module structure.
-
-  ```typescript
-  // ❌ BAD - Dynamic import hides circular dependency
-  const { getTokenizerForModel } = await import("../utils/tokenizer");
-
-  // ✅ GOOD - Static import at top of file
-  import { getTokenizerForModel } from "../utils/tokenizer";
-  ```
-
-- **If you encounter circular dependencies** - Restructure the code to eliminate them. Common solutions:
-  - Extract shared types/interfaces into a separate file
-  - Move shared utilities into a common module
-  - Invert the dependency relationship
-  - Use dependency injection instead of direct imports
-
-  Dynamic imports are NOT an acceptable workaround for circular dependencies.
-
-## Workspace IDs - NEVER Construct in Frontend
-
-**CRITICAL: Workspace IDs must NEVER be constructed in the frontend.** This is a dangerous form of duplication that makes the codebase brittle.
-
-- ❌ **BAD** - Constructing workspace ID from parts:
-
-  ```typescript
-  const newWorkspaceId = `${projectName}-${newName}`; // WRONG!
-  ```
-
-- ✅ **GOOD** - Get workspace ID from backend:
-  ```typescript
-  const result = await window.api.workspace.rename(workspaceId, newName);
-  if (result.success) {
-    const newWorkspaceId = result.data.newWorkspaceId; // Backend provides it
-  }
-  ```
-
-**Why this matters:**
-
-- Workspace ID format is a backend implementation detail
-- If the backend changes ID format, frontend breaks silently
-- Creates multiple sources of truth
-- Leads to subtle bugs and inconsistencies
-
-**Always:**
-
-- Backend operations that change workspace IDs must return the new ID
-- Frontend must use the returned ID, never construct it
-- Backend is the single source of truth for workspace identity
-
-## IPC Type Boundaries
-
-**Backend types vs Frontend types - Keep them separate.**
-
-The IPC layer is the boundary between backend and frontend. Follow these rules to maintain clean separation:
-
-### Rules:
-
-1. **IPC methods should return backend types** - Use `WorkspaceMetadata`, not custom inline types
-
-   ```typescript
-   // ✅ GOOD - Returns backend type
-   create(): Promise<{ success: true; metadata: WorkspaceMetadata } | { success: false; error: string }>
-
-   // ❌ BAD - Duplicates type definition inline
-   create(): Promise<{ success: true; workspace: { workspaceId: string; projectName: string; ... } }>
-   ```
-
-2. **Frontend types extend backend types with UI context** - Frontend has information backend doesn't
-
-   ```typescript
-   // Backend type (no projectPath - backend doesn't need it)
-   interface WorkspaceMetadata {
-     id: string;
-     projectName: string;
-     workspacePath: string;
-   }
-
-   // Frontend type (adds projectPath and branch for UI)
-   interface WorkspaceSelection extends WorkspaceMetadata {
-     projectPath: string; // Frontend initiated the call, so it has this
-     branch: string; // Frontend tracks this for display
-     workspaceId: string; // Alias for 'id' to match UI conventions
-   }
-   ```
-
-3. **Frontend constructs UI types from backend types + local context**
-
-   ```typescript
-   // ✅ GOOD - Frontend combines backend data with context it already has
-   const result = await window.api.workspace.create(projectPath, branchName);
-   if (result.success) {
-     setSelectedWorkspace({
-       ...result.metadata,
-       projectPath, // Frontend already had this
-       branch: branchName, // Frontend already had this
-       workspaceId: result.metadata.id,
-     });
-   }
-
-   // ❌ BAD - Backend returns frontend-specific data
-   const result = await window.api.workspace.create(projectPath, branchName);
-   if (result.success) {
-     setSelectedWorkspace(result.workspace); // Backend shouldn't know about WorkspaceSelection
-   }
-   ```
-
-4. **Never duplicate type definitions in IPC layer** - Always import and use existing types
-
-### Why this matters:
-
-- **Single source of truth** - Backend types are defined once
-- **Clean boundaries** - Backend doesn't know about UI concerns
-- **Type safety** - Changes to backend types propagate to IPC automatically
-- **Prevents duplication** - No need to keep inline types in sync with source types
-
-## Debugging
-
-- `bun debug ui-messages --workspace <workspace-name>` - Show UI messages for a workspace
-- `bun debug ui-messages --workspace <workspace-name> --drop <n>` - Show messages with last n dropped
-- Workspace names can be found in `~/.cmux/sessions/`
-
-## UX Guidelines
-
-- **DO NOT add UX complexity without permission** - Keep interfaces simple and predictable. Do not add features like auto-dismiss, animations, tooltips, or other UX enhancements unless explicitly requested by the user.
-
-  Example of adding unwanted complexity:
-
-  ```typescript
-  // ❌ BAD - Added auto-dismiss without being asked
-  useEffect(() => {
-    if (errorMessage) {
-      const timer = setTimeout(() => {
-        setErrorMessage(null);
-      }, 10000);
-      return () => clearTimeout(timer);
-    }
-  }, [errorMessage]);
-  ```
-
-  Instead, implement the simplest solution that meets the requirement.
-
-## DRY
-
-Notice when you've made the same change many times, refactor to create a shared function
-or component, update all the duplicated code, and then continue on with the original work.
-
-## UX Considerations
-
-- For every operation in the frontend, there should be a keyboard shortcut.
-- Buttons, widgets, etc. that have a keybind should display a tooltip for it during hover.
-
-## Logging
-
-In the backend, use the `log` class from `log.ts` to log messages. Particularly spammy messages
-should go through `log.debug()`.
-
-## Solving Bugs
-
-- When solving a new bug, consider whether there's a solution that simplifies the overall codebase
-  _to_ simplify the bug.
-- If you're fixing via simplifcation, a new test case is generally not necessary.
-- If fixing through additional complexity, add a test case if an existing convenient harness exists.
-  - Otherwise if creating complexity, propose a new test harness to contain the new tests.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 0000000000..8f40feedc9
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+docs/src/AGENTS.md
\ No newline at end of file
diff --git a/README.md b/README.md
index 4c6dbf4f16..69e67b5d37 100644
--- a/README.md
+++ b/README.md
@@ -1,58 +1,33 @@
-# cmux - Coding Agent Multiplexer
-
-A cross-platform desktop application for managing multiple coding agents.
-
-## Build Status
+# cmux - coding agent multiplexer
 
 [![CI](https://github.com/coder/cmux/actions/workflows/ci.yml/badge.svg)](https://github.com/coder/cmux/actions/workflows/ci.yml)
 [![Build](https://github.com/coder/cmux/actions/workflows/build.yml/badge.svg)](https://github.com/coder/cmux/actions/workflows/build.yml)
 
-## Downloads
-
-### Development Builds
-
-Pre-built binaries are available from [GitHub Actions](https://github.com/coder/cmux/actions/workflows/build.yml):
-
-- **macOS**: Universal binary DMG (Intel + Apple Silicon)
-- **Linux**: AppImage (portable, works on most distros)
-
-To download:
-
-1. Go to the [Build workflow](https://github.com/coder/cmux/actions/workflows/build.yml)
-2. Click on the latest successful run
-3. Scroll down to "Artifacts" section
-4. Download `macos-dmg` or `linux-appimage`
-
-### Installation
+A cross-platform desktop application for embarassingly parallel development.
 
-**macOS:**
+## Documentation
 
-⚠️ **Note**: The app is unsigned, so you'll need to bypass Gatekeeper security.
+📚 **[Read the full documentation →](https://cmux.io)**
 
-1. Download and open the DMG file
-2. Drag Cmux to Applications folder
-3. **First time opening**:
-   - Don't double-click the app (macOS will block it)
-   - Right-click (or Control+click) on Cmux.app
-   - Select "Open" from the menu
-   - Click "Open" in the security dialog
-   - The app will now be allowed to run
+- [Installation](https://cmux.io/install.html)
+- [Keyboard Shortcuts](https://cmux.io/keybinds.html)
+- [Developer Guide](https://cmux.io/AGENTS.html)
 
-**Alternative method if the above doesn't work:**
+## Quick Install
 
-1. After step 2, open Terminal
-2. Run: `xattr -cr /Applications/Cmux.app`
-3. Run: `codesign --force --deep --sign - /Applications/Cmux.app`
-4. Now you can open the app normally
+Download pre-built binaries from [GitHub Actions artifacts](https://github.com/coder/cmux/actions/workflows/build.yml):
 
-These steps are only needed once. After that, you can open the app normally.
+- **macOS**: Universal binary DMG (Intel + Apple Silicon)
+- **Linux**: AppImage
 
-**Linux:**
+## Development
 
-1. Download the AppImage file
-2. Make it executable: `chmod +x Cmux-*.AppImage`
-3. Run it: `./Cmux-*.AppImage`
+See [AGENTS.md](./AGENTS.md) for development setup and guidelines.
 
-## Development
+## Features
 
-See [CLAUDE.md](CLAUDE.md) for development setup and guidelines.
+- 🔀 Git worktree integration for multi-branch workflows
+- 🤖 Multiple AI permission modes (plan/edit/yolo)
+- 📦 Multi-project management
+- 💬 Persistent session history
+- ⌨️ Keyboard-first interface
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000000..2584db37b9
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,68 @@
+# cmux Documentation
+
+This directory contains the source for cmux documentation built with [mdbook](https://rust-lang.github.io/mdBook/).
+
+## Quick Start
+
+```bash
+# Serve docs with hot reload (opens in browser)
+bun docs
+
+# Build docs
+bun docs:build
+
+# Watch for changes (no server)
+bun docs:watch
+```
+
+## Features
+
+- ✅ **Mermaid diagrams** - Add diagrams with ` ```mermaid ` code blocks
+- ✅ **Link checking** - Automatically validates all links during build
+- ✅ **GitHub Pages** - Auto-deploys to https://cmux.io on push to main
+
+## Structure
+
+```
+docs/
+├── book.toml        # mdbook configuration
+├── src/
+│   ├── SUMMARY.md   # Table of contents
+│   └── *.md         # Documentation pages
+└── book/            # Build output (gitignored)
+```
+
+## Adding Content
+
+1. Create a new `.md` file in `src/`
+2. Add it to `src/SUMMARY.md` to make it appear in the sidebar
+3. Use standard markdown + mermaid diagrams
+
+### Example Mermaid Diagram
+
+~~~markdown
+```mermaid
+graph LR
+    A[Start] --> B[Process]
+    B --> C[End]
+```
+~~~
+
+## CI/CD
+
+Docs are automatically built and deployed via `.github/workflows/docs.yml` when:
+- Changes are pushed to `main` branch in the `docs/` directory
+- Workflow is manually triggered
+
+## Requirements
+
+The following tools are needed to build locally:
+- `mdbook` (v0.4.52+)
+- `mdbook-mermaid` (v0.16.0+)
+- `mdbook-linkcheck` (v0.7.7+)
+
+Install via cargo:
+```bash
+cargo install mdbook mdbook-mermaid mdbook-linkcheck
+mdbook-mermaid install docs
+```
diff --git a/docs/book.toml b/docs/book.toml
new file mode 100644
index 0000000000..296f0f744f
--- /dev/null
+++ b/docs/book.toml
@@ -0,0 +1,28 @@
+[book]
+authors = ["Ammar Bandukwala"]
+language = "en"
+multilingual = false
+src = "src"
+title = "cmux docs"
+
+[build]
+build-dir = "book"
+create-missing = true
+use-default-preprocessors = true
+
+[preprocessor.mermaid]
+command = "mdbook-mermaid"
+
+[output.html]
+git-repository-url = "https://github.com/coder/cmux"
+edit-url-template = "https://github.com/coder/cmux/edit/main/docs/{path}"
+additional-js = ["mermaid.min.js", "mermaid-init.js"]
+additional-css = ["theme/custom.css"]
+default-theme = "navy"
+preferred-dark-theme = "navy"
+
+[output.html.fold]
+enable = true
+level = 0
+
+[output.linkcheck]
diff --git a/docs/src/AGENTS.md b/docs/src/AGENTS.md
new file mode 100644
index 0000000000..7ac4f3eb78
--- /dev/null
+++ b/docs/src/AGENTS.md
@@ -0,0 +1,383 @@
+# AGENT INSTRUCTIONS
+
+## Project Context
+
+- Electron + React desktop application
+- No existing users - migration code is not needed when changing data structures
+
+## AI-Generated Content Attribution
+
+When creating public operations (commits, PRs, issues), always include:
+
+- 🤖 emoji in the title
+- "_Generated with `cmux`_" in the body (if applicable)
+
+This ensures transparency about AI-generated contributions.
+
+## PR Management
+
+After submitting or updating PRs, **always check merge status**:
+
+```bash
+gh pr view <number> --json mergeable,mergeStateStatus | jq '.'
+```
+
+This is especially important with rapid development where branches quickly fall behind.
+
+**Wait for PR checks to complete:**
+
+```bash
+./scripts/wait_pr_checks.sh <pr_number>
+```
+
+This script polls every 5 seconds and fails immediately on CI failure or bad merge status.
+
+**Key status values:**
+
+- `mergeable: "MERGEABLE"` = No conflicts, can merge
+- `mergeable: "CONFLICTING"` = Has conflicts, needs resolution
+- `mergeStateStatus: "CLEAN"` = Ready to merge ✅
+- `mergeStateStatus: "BLOCKED"` = Waiting for CI checks
+- `mergeStateStatus: "BEHIND"` = Branch is behind base, rebase needed
+- `mergeStateStatus: "DIRTY"` = Has conflicts
+
+**If branch is behind:**
+
+```bash
+git fetch origin
+git rebase origin/main
+git push --force-with-lease
+```
+
+## Project Structure
+
+- `src/main.ts` - Main Electron process
+- `src/preload.ts` - Preload script for IPC
+- `src/App.tsx` - Main React component
+- `src/config.ts` - Configuration management
+- `~/.cmux/config.json` - User configuration file
+- `~/.cmux/src/<project_name>/<branch>` - Workspace directories for git worktrees
+- `~/.cmux/sessions/<workspace_id>/chat.jsonl` - Session chat histories
+
+## Docs
+
+DO NOT visit https://sdk.vercel.ai/docs/ai-sdk-core. All of that content is already
+in `./docs/vercel/**.mdx`.
+
+(Generate them with `./scripts/update_vercel_docs.sh` if they don't exist.)
+
+## Key Features
+
+- Projects sidebar (left panel)
+- Workspaces using git worktrees
+- Configuration persisted to `~/.cmux/config.json`
+
+## Package Manager
+
+- **Using bun** - All dependencies are managed with bun (not npm)
+- Use bun over npm whenever possible, including to:
+  - Install dependencies: `bun install`
+  - Add packages: `bun add <package>`
+  - Run scripts: `bun run <script>`
+  - etc.
+
+## Development Commands
+
+- `bun dev` - Start development server (Vite + TypeScript watcher)
+- `bun start` - Start Electron app
+- `bun build` - Build the application
+- `bun lint` - Run ESLint & typecheck (also: `bun lint:fix`)
+- `bun fmt` - Format all source files with Prettier
+- `bun fmt:check` - Check if files are formatted correctly
+
+## Refactoring
+
+- When refactoring, use `git mv` to preserve file history instead of rewriting files from scratch
+
+## Testing
+
+- Always run `bun typecheck` and `bun typecheck:main` after making changes to verify types
+- **Unit tests should be colocated with their business logic** - Place unit test files (\*.test.ts) in the same directory as the code they test (e.g., `aiService.test.ts` next to `aiService.ts`)
+- E2E and integration tests may live in `./tests/` directory, but unit tests must be colocated
+- Strive to decompose complex logic away from the components and into `.src/utils/`
+  - utils should be either pure functions or easily isolated (e.g. if they operate on the FS they accept
+    a path). Testing them should not require complex mocks or setup.
+- **Integration tests:**
+  - Run specific integration test: `TEST_INTEGRATION=1 bun x jest tests/ipcMain/sendMessage.test.ts -t "test name pattern"`
+  - Run all integration tests: `TEST_INTEGRATION=1 bun x jest tests` (~35 seconds, runs 40 tests)
+  - **Performance**: Tests use `test.concurrent()` to run in parallel within each file
+  - **NEVER bypass IPC in integration tests** - Integration tests must use the real IPC communication paths (e.g., `mockIpcRenderer.invoke()`) even when it's harder. Directly accessing services (HistoryService, PartialService, etc.) or manipulating config/state directly bypasses the integration layer and defeats the purpose of the test.
+
+  **Examples of bypassing IPC (DON'T DO THIS):**
+
+  ```typescript
+  // ❌ BAD - Directly manipulating config
+  const config = env.config.loadConfigOrDefault();
+  config.projects.set(projectPath, { path: projectPath, workspaces: [] });
+  env.config.saveConfig(config);
+
+  // ❌ BAD - Directly accessing services
+  const history = await env.historyService.getHistory(workspaceId);
+  await env.historyService.appendToHistory(workspaceId, message);
+  ```
+
+  **Correct approach (DO THIS):**
+
+  ```typescript
+  // ✅ GOOD - Use IPC to save config
+  await env.mockIpcRenderer.invoke(IPC_CHANNELS.CONFIG_SAVE, {
+    projects: Array.from(projectsConfig.projects.entries()),
+  });
+
+  // ✅ GOOD - Use IPC to interact with services
+  await env.mockIpcRenderer.invoke(IPC_CHANNELS.HISTORY_GET, workspaceId);
+  await env.mockIpcRenderer.invoke(IPC_CHANNELS.WORKSPACE_CREATE, projectPath, branchName);
+  ```
+
+  **Acceptable exceptions:**
+  - Reading context (like `env.config.loadConfigOrDefault()`) to prepare IPC call parameters
+  - Verifying filesystem state (like checking if files exist) after IPC operations complete
+  - Loading existing data to avoid expensive API calls in test setup
+
+  If IPC is hard to test, fix the test infrastructure or IPC layer, don't work around it by bypassing IPC.
+
+## Styling
+
+- Colors are centralized as CSS variables in `src/styles/colors.tsx`
+- Use CSS variables (e.g., `var(--color-plan-mode)`) instead of hardcoded colors
+- Fonts are centralized as CSS variables in `src/styles/fonts.tsx`
+
+## TypeScript Best Practices
+
+- **Avoid `as any` in all contexts** - Never use `as any` casts. Instead:
+  - Use proper type narrowing with discriminated unions
+  - Leverage TypeScript's type guards and the compiler's type checking
+  - Import and reuse existing types from dependencies rather than creating anonymous clones
+  - If a type is truly complex, create a proper type definition or interface
+
+- **Use `Record<EnumType, ValueType>` for exhaustive mappings** - When mapping enum values to strings, colors, or other values, use `Record` types instead of switch statements or if/else chains. This ensures TypeScript catches missing or invalid cases at compile time.
+
+  ```typescript
+  // ✅ Good - TypeScript ensures all modes are handled
+  const MODE_COLORS: Record<UIPermissionMode, string> = {
+    plan: "var(--color-plan-mode)",
+    edit: "var(--color-edit-mode)",
+    yolo: "var(--color-yolo-mode)",
+  };
+
+  // ❌ Avoid - Can miss cases, typos won't be caught
+  switch (mode) {
+    case "plan":
+      return "blue";
+    case "edits":
+      return "green"; // Typo won't be caught!
+  }
+  ```
+
+- **Leverage TypeScript's utility types for UI-specific data** - Use `Omit`, `Pick`, and other utility types to create UI-specific versions of backend types. This prevents unnecessary re-renders and clearly separates concerns.
+
+  ```typescript
+  // Backend type with all fields
+  export interface WorkspaceMetadata {
+    id: string;
+    projectName: string;
+    permissionMode: UIPermissionMode;
+    nextSequenceNumber: number; // Backend bookkeeping
+  }
+
+  // UI type excludes backend-only fields
+  export type WorkspaceMetadataUI = Omit<WorkspaceMetadata, "nextSequenceNumber">;
+  ```
+
+  This pattern ensures:
+  - UI components don't re-render on backend-only changes
+  - Clear separation between UI and backend concerns
+  - Type safety - compiler catches if you try to access excluded fields
+  - Self-documenting code - types clearly show what data UI needs
+
+- **Prefer type-driven development** - Let TypeScript guide your architecture. When types become complex or you need many runtime checks, it often indicates a design issue. Simplify by:
+  - Creating focused types for specific contexts (UI vs backend)
+  - Using discriminated unions for state variations
+  - Leveraging the compiler to catch errors at build time
+
+- **Use `using` for leakable system resources** - Always use explicit resource management (`using` declarations) for resources that need cleanup such as child processes, file handles, database connections, etc. This ensures proper cleanup even when errors occur.
+
+  ```typescript
+  // ✅ Good - Process is automatically cleaned up
+  using process = createDisposableProcess(spawn("command"));
+  const output = await readFromProcess(process);
+  // process.kill() called automatically when going out of scope
+
+  // ❌ Avoid - Process may leak if error occurs before cleanup
+  const process = spawn("command");
+  const output = await readFromProcess(process);
+  process.kill(); // May never be reached if error thrown
+  ```
+
+- This pattern maximizes type safety and prevents runtime errors from typos or missing cases
+
+## Module Imports
+
+- **NEVER use dynamic imports** - Always use static `import` statements at the top of files. Dynamic imports (`await import()`) are a code smell that indicates improper module structure.
+
+  ```typescript
+  // ❌ BAD - Dynamic import hides circular dependency
+  const { getTokenizerForModel } = await import("../utils/tokenizer");
+
+  // ✅ GOOD - Static import at top of file
+  import { getTokenizerForModel } from "../utils/tokenizer";
+  ```
+
+- **If you encounter circular dependencies** - Restructure the code to eliminate them. Common solutions:
+  - Extract shared types/interfaces into a separate file
+  - Move shared utilities into a common module
+  - Invert the dependency relationship
+  - Use dependency injection instead of direct imports
+
+  Dynamic imports are NOT an acceptable workaround for circular dependencies.
+
+## Workspace IDs - NEVER Construct in Frontend
+
+**CRITICAL: Workspace IDs must NEVER be constructed in the frontend.** This is a dangerous form of duplication that makes the codebase brittle.
+
+- ❌ **BAD** - Constructing workspace ID from parts:
+
+  ```typescript
+  const newWorkspaceId = `${projectName}-${newName}`; // WRONG!
+  ```
+
+- ✅ **GOOD** - Get workspace ID from backend:
+  ```typescript
+  const result = await window.api.workspace.rename(workspaceId, newName);
+  if (result.success) {
+    const newWorkspaceId = result.data.newWorkspaceId; // Backend provides it
+  }
+  ```
+
+**Why this matters:**
+
+- Workspace ID format is a backend implementation detail
+- If the backend changes ID format, frontend breaks silently
+- Creates multiple sources of truth
+- Leads to subtle bugs and inconsistencies
+
+**Always:**
+
+- Backend operations that change workspace IDs must return the new ID
+- Frontend must use the returned ID, never construct it
+- Backend is the single source of truth for workspace identity
+
+## IPC Type Boundaries
+
+**Backend types vs Frontend types - Keep them separate.**
+
+The IPC layer is the boundary between backend and frontend. Follow these rules to maintain clean separation:
+
+### Rules:
+
+1. **IPC methods should return backend types** - Use `WorkspaceMetadata`, not custom inline types
+
+   ```typescript
+   // ✅ GOOD - Returns backend type
+   create(): Promise<{ success: true; metadata: WorkspaceMetadata } | { success: false; error: string }>
+
+   // ❌ BAD - Duplicates type definition inline
+   create(): Promise<{ success: true; workspace: { workspaceId: string; projectName: string; ... } }>
+   ```
+
+2. **Frontend types extend backend types with UI context** - Frontend has information backend doesn't
+
+   ```typescript
+   // Backend type (no projectPath - backend doesn't need it)
+   interface WorkspaceMetadata {
+     id: string;
+     projectName: string;
+     workspacePath: string;
+   }
+
+   // Frontend type (adds projectPath and branch for UI)
+   interface WorkspaceSelection extends WorkspaceMetadata {
+     projectPath: string; // Frontend initiated the call, so it has this
+     branch: string; // Frontend tracks this for display
+     workspaceId: string; // Alias for 'id' to match UI conventions
+   }
+   ```
+
+3. **Frontend constructs UI types from backend types + local context**
+
+   ```typescript
+   // ✅ GOOD - Frontend combines backend data with context it already has
+   const result = await window.api.workspace.create(projectPath, branchName);
+   if (result.success) {
+     setSelectedWorkspace({
+       ...result.metadata,
+       projectPath, // Frontend already had this
+       branch: branchName, // Frontend already had this
+       workspaceId: result.metadata.id,
+     });
+   }
+
+   // ❌ BAD - Backend returns frontend-specific data
+   const result = await window.api.workspace.create(projectPath, branchName);
+   if (result.success) {
+     setSelectedWorkspace(result.workspace); // Backend shouldn't know about WorkspaceSelection
+   }
+   ```
+
+4. **Never duplicate type definitions in IPC layer** - Always import and use existing types
+
+### Why this matters:
+
+- **Single source of truth** - Backend types are defined once
+- **Clean boundaries** - Backend doesn't know about UI concerns
+- **Type safety** - Changes to backend types propagate to IPC automatically
+- **Prevents duplication** - No need to keep inline types in sync with source types
+
+## Debugging
+
+- `bun debug ui-messages --workspace <workspace-name>` - Show UI messages for a workspace
+- `bun debug ui-messages --workspace <workspace-name> --drop <n>` - Show messages with last n dropped
+- Workspace names can be found in `~/.cmux/sessions/`
+
+## UX Guidelines
+
+- **DO NOT add UX complexity without permission** - Keep interfaces simple and predictable. Do not add features like auto-dismiss, animations, tooltips, or other UX enhancements unless explicitly requested by the user.
+
+  Example of adding unwanted complexity:
+
+  ```typescript
+  // ❌ BAD - Added auto-dismiss without being asked
+  useEffect(() => {
+    if (errorMessage) {
+      const timer = setTimeout(() => {
+        setErrorMessage(null);
+      }, 10000);
+      return () => clearTimeout(timer);
+    }
+  }, [errorMessage]);
+  ```
+
+  Instead, implement the simplest solution that meets the requirement.
+
+## DRY
+
+Notice when you've made the same change many times, refactor to create a shared function
+or component, update all the duplicated code, and then continue on with the original work.
+
+## UX Considerations
+
+- For every operation in the frontend, there should be a keyboard shortcut.
+- Buttons, widgets, etc. that have a keybind should display a tooltip for it during hover.
+
+## Logging
+
+In the backend, use the `log` class from `log.ts` to log messages. Particularly spammy messages
+should go through `log.debug()`.
+
+## Solving Bugs
+
+- When solving a new bug, consider whether there's a solution that simplifies the overall codebase
+  _to_ simplify the bug.
+- If you're fixing via simplifcation, a new test case is generally not necessary.
+- If fixing through additional complexity, add a test case if an existing convenient harness exists.
+  - Otherwise if creating complexity, propose a new test harness to contain the new tests.
diff --git a/docs/src/CLAUDE.md b/docs/src/CLAUDE.md
new file mode 100644
index 0000000000..2b0b7f6c20
--- /dev/null
+++ b/docs/src/CLAUDE.md
@@ -0,0 +1 @@
+# Developer Guide
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
new file mode 100644
index 0000000000..6ad3fae5a7
--- /dev/null
+++ b/docs/src/SUMMARY.md
@@ -0,0 +1,6 @@
+# Summary
+
+- [Introduction](./intro.md)
+- [Install](./install.md)
+- [Keyboard Shortcuts](./keybinds.md)
+- [AGENTS](./AGENTS.md)
diff --git a/docs/src/install.md b/docs/src/install.md
new file mode 100644
index 0000000000..b191665ea0
--- /dev/null
+++ b/docs/src/install.md
@@ -0,0 +1,47 @@
+# Install
+
+## Downloads
+
+### Development Builds
+
+Pre-built binaries are available from [GitHub Actions](https://github.com/coder/cmux/actions/workflows/build.yml):
+
+- **macOS**: Universal binary DMG (Intel + Apple Silicon)
+- **Linux**: AppImage (portable, works on most distros)
+
+To download:
+
+1. Go to the [Build workflow](https://github.com/coder/cmux/actions/workflows/build.yml)
+2. Click on the latest successful run
+3. Scroll down to "Artifacts" section
+4. Download `macos-dmg` or `linux-appimage`
+
+### Installation
+
+**macOS:**
+
+⚠️ **Note**: The app is unsigned, so you'll need to bypass Gatekeeper security.
+
+1. Download and open the DMG file
+2. Drag Cmux to Applications folder
+3. **First time opening**:
+   - Don't double-click the app (macOS will block it)
+   - Right-click (or Control+click) on Cmux.app
+   - Select "Open" from the menu
+   - Click "Open" in the security dialog
+   - The app will now be allowed to run
+
+**Alternative method if the above doesn't work:**
+
+1. After step 2, open Terminal
+2. Run: `xattr -cr /Applications/Cmux.app`
+3. Run: `codesign --force --deep --sign - /Applications/Cmux.app`
+4. Now you can open the app normally
+
+These steps are only needed once. After that, you can open the app normally.
+
+**Linux:**
+
+1. Download the AppImage file
+2. Make it executable: `chmod +x Cmux-*.AppImage`
+3. Run it: `./Cmux-*.AppImage`
diff --git a/docs/src/intro.md b/docs/src/intro.md
new file mode 100644
index 0000000000..6048a5f5b2
--- /dev/null
+++ b/docs/src/intro.md
@@ -0,0 +1,24 @@
+# Introduction
+
+**cmux** (Coding Agent Multiplexer) is a cross-platform desktop application for AI-assisted development with git worktree integration.
+
+## What is cmux?
+
+cmux helps you work with AI coding assistants more effectively by:
+
+- 🔀 **Git Worktree Integration** - Work on multiple branches simultaneously
+- 🤖 **Multiple Permission Modes** - Control how aggressively the AI can modify your code (plan/exec)
+- 📦 **Project Management** - Organize and switch between multiple projects seamlessly
+- 💬 **Session History** - Full chat history persistence across sessions
+- 🔄 **Flexible Workflows** - Support for different AI models and providers
+
+## Why cmux?
+
+- Effective use of many simultaneous agents
+- Richer dialogue with assistant due to GUI (e.g. native mermaid diagrams)
+
+## Quick Links
+
+- [Install](./install.md) - Download and installation instructions
+- [Keyboard Shortcuts](./keybinds.md) - Complete keyboard reference
+- [AGENTS](./AGENTS.md) - Developer guide for AI assistants
diff --git a/docs/src/keybinds.md b/docs/src/keybinds.md
new file mode 100644
index 0000000000..90e3cdf7d7
--- /dev/null
+++ b/docs/src/keybinds.md
@@ -0,0 +1,48 @@
+# Keyboard Shortcuts
+
+cmux is designed to be keyboard-driven for maximum efficiency. All major actions have keyboard shortcuts.
+
+> **Note**: This document should be kept in sync with `src/utils/ui/keybinds.ts`, which is the source of truth for keybind definitions.
+
+## Platform Conventions
+
+- **macOS**: Shortcuts use `⌘` (Command) as the primary modifier
+- **Linux/Windows**: Shortcuts use `Ctrl` as the primary modifier
+
+When documentation shows `Ctrl`, it means:
+- `⌘` (Command) on macOS
+- `Ctrl` on Linux/Windows
+
+## General
+
+| Action | Shortcut |
+|--------|----------|
+| Cancel / Close / Interrupt | `Esc` |
+
+## Chat & Messages
+
+| Action | Shortcut |
+|--------|----------|
+| Send message | `Enter` |
+| New line in message | `Shift+Enter` |
+| Jump to bottom of chat | `Shift+G` |
+
+## Workspaces
+
+| Action | Shortcut |
+|--------|----------|
+| Create new workspace | `Ctrl+N` |
+| Next workspace | `Ctrl+J` |
+| Previous workspace | `Ctrl+K` |
+
+## Modes
+
+| Action | Shortcut |
+|--------|----------|
+| Toggle between Plan and Exec modes | `Ctrl+Shift+M` |
+
+## Tips
+
+- **Vim-inspired navigation**: We use `J`/`K` for next/previous navigation, similar to Vim
+- **Consistent modifiers**: Most workspace/project operations use `Ctrl` as the modifier
+- **Natural expectations**: We try to use shortcuts users would naturally expect (e.g., `Ctrl+N` for new)
diff --git a/docs/theme/custom.css b/docs/theme/custom.css
new file mode 100644
index 0000000000..2d72cc31a3
--- /dev/null
+++ b/docs/theme/custom.css
@@ -0,0 +1,219 @@
+/* cmux Documentation Theme - Matching the app's design */
+
+:root {
+  /* Colors from colors.tsx */
+  --bg-primary: #1e1e1e;
+  --bg-secondary: #262626;
+  --bg-tertiary: #333333;
+  
+  --text-primary: #d4d4d4;
+  --text-secondary: #6b6b6b;
+  --text-muted: #404040;
+  
+  --accent-blue: #3b7fb5;
+  --accent-green: #4a8a5f;
+  --accent-yellow: #f59e0b;
+  --accent-red: #b54040;
+  
+  --border-color: #404040;
+  --link-color: #4a9eff;
+  --link-hover: #6bb0ff;
+  
+  /* Override mdbook's default variables */
+  --bg: var(--bg-primary) !important;
+  --table-alternate-bg: var(--bg-secondary) !important; /* Fix blue alternate row background */
+}
+
+/* Base styles */
+body {
+  background-color: var(--bg-primary) !important;
+  color: var(--text-primary) !important;
+}
+
+.content {
+  background-color: var(--bg-primary) !important;
+}
+
+/* Sidebar */
+.sidebar {
+  background-color: var(--bg-secondary) !important;
+  border-right: 1px solid var(--border-color) !important;
+}
+
+.sidebar-resize-handle {
+  background-color: var(--bg-tertiary) !important; /* #333333 - close to #323232 */
+}
+
+.sidebar .chapter li.chapter-item a {
+  color: var(--text-primary) !important;
+}
+
+.sidebar .chapter li.chapter-item a.active {
+  color: var(--accent-blue) !important;
+  background-color: transparent !important;
+}
+
+.sidebar .chapter li.chapter-item a:hover {
+  color: var(--text-primary) !important;
+  background-color: var(--bg-tertiary) !important;
+}
+
+/* Links */
+a {
+  color: var(--link-color) !important;
+}
+
+a:hover {
+  color: var(--link-hover) !important;
+  text-decoration: none !important;
+}
+
+/* Code blocks */
+pre {
+  background-color: var(--bg-secondary) !important;
+  border: 1px solid var(--border-color) !important;
+  border-radius: 4px;
+}
+
+:not(pre) > code {
+  background-color: var(--bg-secondary) !important;
+  color: var(--accent-green) !important;
+  border-radius: 3px;
+  padding: 2px 6px;
+}
+
+pre > code {
+  background-color: transparent !important;
+  color: var(--text-primary) !important;
+  padding: 6px;
+}
+
+/* Tables - LEFT ALIGN ALL CELLS */
+table {
+  border-collapse: collapse;
+  width: 100%;
+  margin: 1em 0;
+  background-color: var(--bg-secondary) !important;
+}
+
+table thead {
+  background-color: var(--bg-tertiary) !important;
+  border-bottom: 2px solid var(--border-color) !important;
+}
+
+table th,
+table td {
+  padding: 0.75em 1em;
+  border: 1px solid var(--border-color) !important;
+  text-align: left !important; /* Force left alignment */
+  color: var(--text-primary) !important;
+}
+
+table th {
+  font-weight: 600;
+}
+
+table tbody tr:hover {
+  background-color: var(--bg-tertiary) !important;
+}
+
+/* Inline code in tables */
+table code {
+  background-color: var(--bg-primary) !important;
+  color: var(--accent-yellow) !important;
+  font-family: 'Monaco', 'Menlo', 'Courier New', monospace;
+  font-size: 0.9em;
+}
+
+/* Blockquotes */
+blockquote {
+  border-left: 4px solid var(--accent-blue) !important;
+  background-color: var(--bg-secondary) !important;
+  padding: 1em;
+  margin: 1em 0;
+  color: var(--text-secondary) !important;
+}
+
+blockquote strong {
+  color: var(--accent-blue) !important;
+}
+
+/* Headers */
+h1, h2, h3, h4, h5, h6 {
+  color: var(--text-primary) !important;
+  border-bottom-color: var(--border-color) !important;
+}
+
+h1 {
+  border-bottom: 2px solid var(--border-color) !important;
+}
+
+h2 {
+  border-bottom: 1px solid var(--border-color) !important;
+}
+
+/* Search */
+#searchbar {
+  background-color: var(--bg-tertiary) !important;
+  border: 1px solid var(--border-color) !important;
+  color: var(--text-primary) !important;
+}
+
+#searchbar:focus {
+  border-color: var(--accent-blue) !important;
+  outline: none;
+}
+
+/* Navigation buttons */
+.nav-chapters {
+  color: var(--text-secondary) !important;
+}
+
+.nav-chapters:hover {
+  color: var(--text-primary) !important;
+  background-color: var(--bg-tertiary) !important;
+}
+
+/* Menu bar */
+#menu-bar {
+  background-color: var(--bg-secondary) !important;
+  border-bottom: 1px solid var(--border-color) !important;
+}
+
+.icon-button {
+  color: var(--text-secondary) !important;
+}
+
+.icon-button:hover {
+  color: var(--text-primary) !important;
+}
+
+/* Hide theme selector */
+#theme-toggle,
+.theme-popup {
+  display: none !important;
+}
+
+/* Page wrapper */
+.page-wrapper {
+  background-color: var(--bg-primary) !important;
+}
+
+/* Scrollbar */
+::-webkit-scrollbar {
+  width: 10px;
+  height: 10px;
+}
+
+::-webkit-scrollbar-track {
+  background: var(--bg-primary);
+}
+
+::-webkit-scrollbar-thumb {
+  background: var(--bg-tertiary);
+  border-radius: 5px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: var(--border-color);
+}
diff --git a/package.json b/package.json
index c19d3d0fb5..0c4e030961 100644
--- a/package.json
+++ b/package.json
@@ -26,7 +26,10 @@
     "dist": "bun run build && electron-builder --publish never",
     "dist:mac": "bun run build && electron-builder --mac --publish never",
     "dist:win": "bun run build && electron-builder --win --publish never",
-    "dist:linux": "bun run build && electron-builder --linux --publish never"
+    "dist:linux": "bun run build && electron-builder --linux --publish never",
+    "docs": "./scripts/docs.sh",
+    "docs:build": "./scripts/docs_build.sh",
+    "docs:watch": "cd docs && mdbook watch"
   },
   "dependencies": {
     "@ai-sdk/anthropic": "^2.0.20",
diff --git a/scripts/docs.sh b/scripts/docs.sh
new file mode 100755
index 0000000000..ac859d93b7
--- /dev/null
+++ b/scripts/docs.sh
@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Ensure mdbook-mermaid assets are installed
+if [ ! -f "docs/mermaid-init.js" ] || [ ! -f "docs/mermaid.min.js" ]; then
+  echo "📦 Installing mermaid assets..."
+  cd docs && mdbook-mermaid install
+  cd ..
+fi
+
+# Serve the docs
+cd docs && mdbook serve --open
diff --git a/scripts/docs_build.sh b/scripts/docs_build.sh
new file mode 100755
index 0000000000..7d8d8ea2c2
--- /dev/null
+++ b/scripts/docs_build.sh
@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Ensure mdbook-mermaid assets are installed
+if [ ! -f "docs/mermaid-init.js" ] || [ ! -f "docs/mermaid.min.js" ]; then
+  echo "📦 Installing mermaid assets..."
+  cd docs && mdbook-mermaid install
+  cd ..
+fi
+
+# Build the docs
+cd docs && mdbook build
diff --git a/src/utils/ui/keybinds.ts b/src/utils/ui/keybinds.ts
index e11589a572..55e0cde2d2 100644
--- a/src/utils/ui/keybinds.ts
+++ b/src/utils/ui/keybinds.ts
@@ -1,6 +1,9 @@
 /**
  * Centralized keybind utilities for consistent keyboard shortcut handling
  * and OS-aware display across the application.
+ *
+ * NOTE: This file is the source of truth for keybind definitions.
+ * When adding/modifying keybinds, also update docs/src/keybinds.md
  */
 
 /**