diff --git a/README.md b/README.md
index 406aac0..82e1822 100644
--- a/README.md
+++ b/README.md
@@ -1,108 +1,185 @@
 # BeadBoard
-**Work in Progress, please contribute!** 
-**BeadBoard is a multi-agent swarm coordination system built on [Beads](https://github.com/steveyegge/beads) inspired by [Gastown](https://github.com/steveyegge/gastown).** Thanks [Steve Yegge](https://github.com/steveyegge)!
 
-BB is a visual operations layer for running agent teams against real dependency-constrained work.
+[![npm version](https://img.shields.io/npm/v/beadboard.svg)](https://www.npmjs.com/package/beadboard)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/zenchantlive/beadboard/ci.yml?branch=main)](https://github.com/zenchantlive/beadboard/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub stars](https://img.shields.io/github/stars/zenchantlive/beadboard?style=social)](https://github.com/zenchantlive/beadboard/stargazers)
+
+**Multi-agent swarm coordination system for dependency-constrained work.**
+
+Built on [Beads](https://github.com/steveyegge/beads) and inspired by [Gastown](https://github.com/steveyegge/gastown).
 
 ---
 
-## What This App Is
-BeadBoard is not just a task board. It is an execution system for coordinating agents around shared Beads workflows:
+## 🚀 Add BeadBoard to Your Agent
 
-- Agent-to-agent communication with explicit categories (`HANDOFF`, `BLOCKED`, `DECISION`, `INFO`)
-- Conversation threads merged from activity events, agent messages, and local interactions
-- Graph/topology context for deciding what should move next
-- Global project scope switching across single and aggregate workspaces
-- Swarm orchestration with archetypes/templates and assignment controls
+```bash
+npx skills add zenchantlive/beadboard --skill beadboard-driver
+```
+
+This one command installs the BeadBoard driver skill, enabling your AI agents to:
+- Coordinate work through dependency-constrained task graphs
+- Communicate with other agents via structured message passing
+- Track progress with real-time updates and activity streams
+- Manage work state through the `bd` CLI
+
+**[→ Full Agent Integration Guide](#agent-integration)**
 
 ---
 
-![alt text](image-9.png)
+## Quick Start
+
+### For Human Users
+
+```bash
+npm install -g beadboard
+beadboard start
+```
+
+Open [http://localhost:3000](http://localhost:3000) to access the coordination dashboard.
+
+### For Agent Developers
+
+```bash
+# Install the skill to your project
+npx skills add zenchantlive/beadboard --skill beadboard-driver
+
+# Or install globally for all your projects
+npx skills add zenchantlive/beadboard --skill beadboard-driver --global
+```
+
+Then add to your project's `AGENTS.md`:
+
+```markdown
+## BeadBoard Integration
+
+- Working directory: Run all `bd` commands from project root
+- Source of truth: `bd` CLI manages all work state
+- Evidence required: Never claim done without verification gates
+```
+
+---
+
+Open [http://localhost:3000](http://localhost:3000) to access the dashboard.
+
+---
+
+## Agent Integration
+
+BeadBoard is designed for AI agent coordination. Agents work in their own project repositories while humans observe and coordinate through the BeadBoard UI.
+
+### Configuration
+
+Add the following to your project's `AGENTS.md` or `CLAUDE.md`:
+
+```markdown
+## BeadBoard Integration
+
+- Install driver: `npx skills add zenchantlive/beadboard --skill beadboard-driver`
+- Working directory: run all `bd` commands from project root
+- Source of truth: `bd` CLI manages all work state
+- Evidence required: never claim done without running verification gates
+```
+
+### Key Concepts
+
+| Component | Purpose |
+|-----------|---------|
+| `bd` | Beads CLI - task and dependency management |
+| `bb` | BeadBoard CLI - dashboard launcher |
+| `beadboard-driver` skill | Agent operating contract for coordination |
+
+See [skills/beadboard-driver/SKILL.md](skills/beadboard-driver/SKILL.md) for the complete agent runbook.
+
+---
+
+## What BeadBoard Does
+
+BeadBoard is an execution system for coordinating agents around shared Beads workflows:
+
+- **Agent-to-agent communication** with explicit categories (`HANDOFF`, `BLOCKED`, `DECISION`, `INFO`)
+- **Conversation threads** merged from activity events, agent messages, and local interactions
+- **Graph/topology context** for deciding what should move next
+- **Global project scope switching** across single and aggregate workspaces
+- **Swarm orchestration** with archetypes/templates and assignment controls
+
+![BeadBoard Dashboard - Multi-agent coordination interface showing task graph, agent pool, and activity stream](image-9.png)
 
 ---
 
 ## Core Features
 
 ### 1. Agent Communication System
-- Structured message lifecycle: `send`, `inbox`, `read`, `ack`
-- Message states: `unread`, `read`, `acked`
-- Per-task conversation threads combining:
-  - activity events
-  - agent mail
-  - local bd interactions
-- Required acknowledgment semantics for high-signal categories (`HANDOFF`, `BLOCKED`)
+
+Structured message lifecycle for inter-agent coordination:
+
+- **Message states**: `unread`, `read`, `acked`
+- **Required acknowledgment** for high-signal categories (`HANDOFF`, `BLOCKED`)
+- **Per-task threads** combining activity events, agent mail, and local interactions
+
+```bash
+bd mail inbox
+bd mail send --to <agent> --bead <id> --category HANDOFF --subject "Ready for review"
+bd mail ack <message-id>
+```
 
 ### 2. Swarm Coordination Surface
-- Agent Pool Monitor with:
-  - Archetypes
-  - Templates
-  - Needs Agent queue
-  - Pre-assigned queue
-  - Squad roster
-- Assignment workflow through the graph workspace and right panel
-![alt text](image-7.png) 
+
+Agent Pool Monitor with:
+
+- Archetypes and templates for agent specialization
+- "Needs Agent" queue for unassigned work
+- Pre-assigned queue for reserved tasks
+- Squad roster for active team members
+
+![Swarm Coordination Panel - Agent pool monitor showing archetypes, assignment queues, and squad roster](image-7.png)
 
 ### 3. Graph + Dependency Topology
-- DAG-oriented graph workspace for execution decisions
+
+DAG-oriented workspace for execution decisions:
+
 - Task/dependency tab modes for different planning lenses
-- Blocker/unblock context surfaced directly in task cards
-- Graph analysis support (cycle and blocked-chain context)
-![alt text](image-8.png)
+- Blocker/unblock context surfaced in task cards
+- Graph analysis support (cycle detection, blocked-chain identification)
+
+![Dependency Graph View - DAG visualization showing task dependencies and execution order](image-8.png)
 
 ### 4. Global Project Scope + Scanner
+
 - Project registry and scanner-backed discovery
 - Single-project and aggregate modes
-- Runtime scope switching without leaving the primary workspace
+- Runtime scope switching without leaving the workspace
 
 ### 5. Realtime Operations Layer
-- Live updates via watchers + SSE
+
+- Live updates via file watchers + Server-Sent Events
 - Activity stream integration with session/task context
-- Mutation/writeback feedback integrated into the same operational surface
+- Mutation/writeback feedback integrated into the operational surface
 
 ---
 
-## Runtime Surface
-
-### Active Route
-- `/`
-
-### View Modes
-- `/?view=social`
-- `/?view=graph`
-- `/?view=activity`
-
-### Compatibility Redirects
-- `/graph` -> `/?view=graph`
-- `/sessions` -> `/?view=social`
-- `/timeline` -> `/?view=activity`
-- `/mockup` -> `/`
-
-### Archived Route Vault
-Legacy route implementations are preserved in `reference/routes/**` and excluded from active runtime validation scope.
-
----
-
-## Install
+## Installation & Setup
 
 ### Prerequisites
+
 - Node.js `18.18+` (Node `20 LTS` recommended)
 - npm
 
 ### Clone + Install
+
 ```bash
 git clone https://github.com/zenchantlive/beadboard.git
 cd beadboard
 npm install
 ```
 
-### Global CLI Install (Optional)
-Primary install path:
+### Global CLI Install
 
 ```bash
-npm i -g beadboard
+npm install -g beadboard
 ```
 
-Fallback wrappers from repo root:
+**Alternative: Platform-specific wrappers**
 
 POSIX (Linux/macOS):
 ```bash
@@ -122,113 +199,205 @@ Runtime home:
 - `~/.beadboard/runtime/<version>`
 - `~/.beadboard/runtime/current.json`
 
-Launcher commands:
-- `beadboard start`
-- `beadboard start --dolt` (runs `bd dolt start` in the current project folder, then starts BeadBoard)
-- `beadboard open`
-- `beadboard status`
-
-Startup note:
-- In project repositories, run `bd dolt start` from the project directory (the folder with `.beads`).
-- If you want one command for both steps, use `beadboard start --dolt`.
-
----
-
-## Quick Start
+### Development Setup
 
 ```bash
 npm run dev
 ```
 
-Open:
+Open [http://localhost:3000](http://localhost:3000)
 
-```text
-http://localhost:3000
-```
-
----
-
-## Configuration
-No external service is required for core local usage.
-
-Runtime behavior is driven by:
-- Local Beads project data
-- Registered/scanned project roots
-- URL query state (`view`, `task`, `swarm`, `agent`, `epic`, `graphTab`, panel state)
-
----
-
-## Operating Flow
-
-### 1. Coordinate through Graph + Pool
-Open `/?view=graph`, inspect dependency topology, and drive assignment from the pool panel.
-
-### 2. Communicate in Context
-Open a task thread to read merged conversation context and process message acknowledgments.
-
-### 3. Switch Scope as Work Expands
-Use registry/scanner controls to move between local and aggregate project scope.
-
-### 4. Track Live Signal
-Use social/activity views to monitor execution movement and operational events.
-
----
-
-## Roadmap Notes
-- Cross-view assign controls in all major views.
-- Social naming/UX evolution (including possible shift toward “swim” terminology).
-- Continued expansion of global project config/scanner workflows.
-
----
-
-## Scripts
+### Production Deployment
 
 ```bash
-npm run dev
 npm run build
 npm run start
-npm run typecheck
-npm run lint
-npm run test
-npm run video
-npm run video:render
-npm run video:thumbnail
+```
+
+---
+
+## Usage & Examples
+
+### CLI Commands
+
+```bash
+# Start BeadBoard dashboard
+beadboard start
+
+# Start with Dolt database
+beadboard start --dolt
+
+# Open dashboard in browser
+beadboard open
+
+# Check status
+beadboard status
+```
+
+### Workflow Example
+
+```bash
+# 1. Navigate to your project
+cd ~/my-project
+
+# 2. Start Dolt (if using version-controlled data)
+bd dolt start
+
+# 3. Start BeadBoard
+beadboard start --dolt
+
+# 4. Open dashboard
+beadboard open
+```
+
+### Common Patterns
+
+**Coordinate through Graph + Pool:**
+```
+Open /?view=graph → inspect dependency topology → drive assignment from pool panel
+```
+
+**Communicate in Context:**
+```
+Open task thread → read merged conversation → process message acknowledgments
+```
+
+**Switch Scope:**
+```
+Use registry/scanner controls → move between local and aggregate project scope
+```
+
+**Track Live Signal:**
+```
+Use social/activity views → monitor execution movement and operational events
 ```
 
 ---
 
 ## Architecture
-- **Frontend**: Next.js App Router + React 19 + Tailwind + Framer Motion + Radix
-- **Graph stack**: XYFlow + Dagre
-- **Core domain**: Beads issue model, graph/kanban/session/social builders
-- **Coordination layer**: agent mail + session communication + swarm orchestration state
-- **Realtime**: watchers + SSE + snapshot differ + activity persistence
-- **Validation/typing**: strict TypeScript + Zod contracts where applicable
+
+### High-Level Design
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      BeadBoard UI                           │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
+│  │  Social  │  │  Graph   │  │ Activity │  │  Swarm   │    │
+│  │  View    │  │  View    │  │  View    │  │  Panel   │    │
+│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
+└─────────────────────────────────────────────────────────────┘
+                           │
+              ┌────────────┼────────────┐
+              │            │            │
+        ┌─────▼─────┐ ┌────▼────┐ ┌────▼─────┐
+        │   SSE     │ │  Dolt   │ │  Watchers│
+        │  Events   │ │   DB    │ │ (Chokidar)│
+        └───────────┘ └─────────┘ └──────────┘
+              │            │            │
+              └────────────┼────────────┘
+                           │
+                    ┌──────▼──────┐
+                    │     bd      │
+                    │  (Beads CLI)│
+                    └─────────────┘
+```
+
+### Tech Stack
+
+| Layer | Technologies |
+|-------|-------------|
+| Frontend | Next.js 15, React 19, TypeScript |
+| Styling | Tailwind CSS, Radix UI, Framer Motion |
+| Graph | XYFlow, Dagre |
+| Database | Dolt (version-controlled SQL) |
+| Realtime | Chokidar watchers, Server-Sent Events |
+| Validation | Zod schemas, strict TypeScript |
+
+### Data Flow
+
+1. **Write Path**: `bd` commands write to `.beads/issues.jsonl` and Dolt DB
+2. **Read Path**: UI queries Dolt SQL server (falls back to JSONL if unreachable)
+3. **Realtime**: `bd` touches `.beads/last-touched` → Chokidar fires → SSE event → UI update
+
+### Runtime Artifacts
+
+| Directory | Purpose | Git Status |
+|-----------|---------|------------|
+| `.beads/` | Beads database, issues, coordination state | gitignored |
+| `.agents/` | Agent skills and configuration | gitignored |
 
 ---
 
 ## Project Structure
 
 ```text
-src/
-  app/
-    page.tsx                # active runtime route
-    api/                    # runtime API routes
-  components/
-    shared/ graph/ social/ activity/ sessions/ swarm/ kanban/
-  hooks/
-  lib/
-reference/
-  routes/                   # archived route implementations
+beadboard/
+├── src/
+│   ├── app/
+│   │   ├── page.tsx              # Active runtime route
+│   │   └── api/                  # Runtime API routes
+│   ├── components/
+│   │   ├── shared/               # Reusable UI components
+│   │   ├── graph/                # Dependency graph components
+│   │   ├── social/               # Social/activity views
+│   │   ├── swarm/                # Swarm coordination panel
+│   │   └── sessions/             # Agent session components
+│   ├── hooks/                    # React hooks
+│   └── lib/                      # Core domain logic
+├── skills/
+│   └── beadboard-driver/         # Agent skill package
+├── install/                      # Platform install scripts
+├── reference/
+│   └── routes/                   # Archived route implementations
+├── docs/                         # Documentation
+└── tests/                        # Test suite
 ```
 
+### Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/app/page.tsx` | Main dashboard entry point |
+| `src/lib/` | Core domain: Beads model, graph builders, coordination |
+| `skills/beadboard-driver/SKILL.md` | Agent operating contract |
+| `AGENTS.md` | Agent operating manual for this repo |
+| `next.config.ts` | Route redirects and Next.js config |
+
+---
+
+## Routes
+
+### Active Route
+
+- `/` - Main dashboard (query-driven)
+
+### View Modes
+
+| URL | View |
+|-----|------|
+| `/?view=social` | Agent social feed |
+| `/?view=graph` | Dependency graph |
+| `/?view=activity` | Activity timeline |
+
+### Compatibility Redirects
+
+| Old Route | Redirects To |
+|-----------|--------------|
+| `/graph` | `/?view=graph` |
+| `/sessions` | `/?view=social` |
+| `/timeline` | `/?view=activity` |
+| `/mockup` | `/` |
+
 ---
 
 ## Contributing
-1. Keep active runtime pages in `src/app` minimal.
-2. Promote reusable logic into `src/lib`, `src/components`, `src/hooks`.
-3. Archive non-runtime route experiments in `reference/routes`.
-4. Run quality gates before merge:
+
+### Development Workflow
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Make changes following existing patterns
+4. Run quality gates:
 
 ```bash
 npm run typecheck
@@ -236,7 +405,69 @@ npm run lint
 npm run test
 ```
 
+5. Submit a pull request
+
+### Code Guidelines
+
+- Keep active runtime pages minimal in `src/app`
+- Promote reusable logic to `src/lib`, `src/components`, `src/hooks`
+- Archive experimental routes in `reference/routes`
+- Follow existing TypeScript and React patterns
+- Add tests for new functionality
+
+### Code of Conduct
+
+- Be respectful and inclusive
+- Focus on constructive feedback
+- Support newcomers to the project
+
+---
+
+## Scripts
+
+```bash
+npm run dev          # Development server
+npm run build        # Production build
+npm run start        # Production server
+npm run typecheck    # TypeScript validation
+npm run lint         # ESLint
+npm run test         # Test suite
+npm run video        # Remotion video preview
+npm run video:render # Render video
+```
+
+---
+
+## Changelog
+
+### v0.1.0 (Current)
+
+- Initial release
+- Multi-agent coordination system
+- Graph-based dependency visualization
+- Real-time updates via SSE
+- Agent mail and communication system
+- Swarm coordination panel
+- Global project scope switching
+
+---
+
+## Roadmap
+
+- Cross-view assignment controls in all major views
+- Enhanced swarm UX and terminology
+- Expanded global project configuration workflows
+- Witness enforcement layer for agent liveness
+- Additional graph analysis features
+
 ---
 
 ## License
-MIT
+
+[MIT](LICENSE)
+
+---
+
+## Acknowledgments
+
+Built on [Beads](https://github.com/steveyegge/beads) and inspired by [Gastown](https://github.com/steveyegge/gastown). Thanks [Steve Yegge](https://github.com/steveyegge)!