diff --git a/README.md b/README.md
index bd65587e..02988a99 100644
--- a/README.md
+++ b/README.md
@@ -1,182 +1,55 @@
-# Story Kit
+# Storkit
 
-This app runs as a single Rust web server binary that serves the Vite/React frontend and exposes APIs.
-The frontend lives in the `frontend/` directory.
+A story-driven development server that manages work items, spawns coding agents, and runs them through a pipeline from backlog to done. Ships as a single Rust binary with an embedded React frontend. Communicates via Matrix, WhatsApp, and Slack bot transports, and exposes MCP tools for programmatic access.
 
-You can also run the frontend and backend separately in development (Vite dev server + Rust API).
+## Prerequisites
 
-## Running it in development
+- Rust (2024 edition)
+- Node.js and npm
+- Docker (for Linux cross-compilation and container deployment)
+- `cross` (`cargo install cross`) for Linux static builds
+
+## Building for production
 
 ```bash
-# Build the frontend
-cd frontend
-npm install
-npm run dev
-
-# In another terminal - run the server (serves embedded frontend/dist/)
-cargo run
-```
-
-## Production
-
-```bash
-# Build the release binary (also builds the frontend via build.rs)
 cargo build --release
-
-# Run the server (serves embedded frontend/dist/)
-./target/release/storkit
 ```
 
-## Cross-Platform Distribution
+The release binary embeds the frontend via `rust-embed`. Output: `target/release/storkit`.
 
-Story Kit ships as a **single self-contained binary** with the React frontend embedded via
-`rust-embed`. No Rust toolchain, Node.js, or extra libraries are required on the target machine.
-
-### macOS
+For a static Linux binary (musl, zero dynamic deps):
 
 ```bash
-# Native build – no extra tools required beyond Rust + npm
-make build-macos
-# Output: target/release/storkit
-
-# Verify only system frameworks are linked (Security.framework, libSystem.B.dylib, etc.)
-otool -L target/release/storkit
+cross build --release --target x86_64-unknown-linux-musl
 ```
 
-### Linux (static x86_64, zero dynamic deps)
-
-The Linux build uses the `x86_64-unknown-linux-musl` target to produce a fully static binary.
-
-**Prerequisites:**
+Docker:
 
 ```bash
-# Install cross – a Rust cross-compilation tool backed by Docker
-cargo install cross
-
-# Ensure Docker Desktop (or Docker Engine) is running
+docker compose -f docker/docker-compose.yml build
 ```
 
-**Build:**
+## Running in development
 
 ```bash
-make build-linux
-# Output: target/x86_64-unknown-linux-musl/release/storkit
+# Run tests
+script/test
 
-# Verify the binary is statically linked
-file target/x86_64-unknown-linux-musl/release/storkit
-# Expected: ELF 64-bit LSB executable, x86-64, statically linked
+# Run the server
+cargo run -- --port 3000
 
-ldd target/x86_64-unknown-linux-musl/release/storkit
-# Expected: not a dynamic executable
+# In another terminal, run the frontend dev server
+cd frontend && npm install && npm run dev
 ```
 
-**Running on any Linux x86_64 machine:**
-
-```bash
-# No Rust, Node, glibc, or any other library needed – just copy and run
-./storkit
-```
+Configuration lives in `.storkit/project.toml`. See `.storkit/bot.toml.*.example` for transport setup.
 
 ## Releasing
 
-Builds both macOS and Linux binaries locally, tags the repo, and publishes a Gitea release with a changelog.
-
-**One-time setup:**
-
-1. Create a Gitea API token at `https://code.crashlabs.io/user/settings/applications` (needs repository read/write)
-2. Add it to `.env` (gitignored): `GITEA_TOKEN=your_token`
-3. Ensure `cross` is installed (`cargo install cross`) and Docker is running
-
-**To release:**
+Requires a Gitea API token in `.env` (`GITEA_TOKEN=your_token`).
 
 ```bash
-make release V=0.2.0
+script/release 0.6.1
 ```
 
-This will:
-- Build macOS arm64 (native) and Linux amd64 (static musl via cross/Docker)
-- Generate a changelog from commits since the last tag
-- Tag the repo as `v0.2.0` and push the tag
-- Create a Gitea release with both binaries and the changelog attached
-
-## Testing
-
-### Frontend Tests
-
-The frontend uses **Vitest** for unit tests and **Playwright** for end-to-end tests.
-
-```bash
-cd frontend
-
-# Run unit tests
-npm test
-
-# Run end-to-end tests
-npm run test:e2e
-```
-
-### Backend Tests
-
-This project uses **nextest** for running tests and **cargo-llvm-cov** for code coverage.
-
-### Install Tools
-
-```bash
-cargo install cargo-nextest cargo-llvm-cov
-```
-
-### Run Tests
-
-```bash
-# Run all tests
-cargo nextest run
-
-# Run specific module
-cargo nextest run search_files
-
-# Run with verbose output
-cargo nextest run --no-capture
-```
-
-### Generate Coverage
-
-```bash
-# HTML report (opens in browser)
-cargo llvm-cov nextest --html --open
-
-# Terminal output
-cargo llvm-cov nextest
-
-# LCOV format (for CI)
-cargo llvm-cov nextest --lcov --output-path lcov.info
-
-# Clean coverage data
-cargo llvm-cov clean
-```
-
-### Configuration
-
-- **Nextest config**: `.config/nextest.toml`
-- **Coverage output**: `target/llvm-cov/html/index.html`
-
-## Current Coverage (search_files module)
-
-```
-Module: commands/search.rs
-├── Region Coverage:   75.36%
-├── Function Coverage: 69.05%
-└── Line Coverage:     72.55%
-```
-
-### Available Test Profiles
-
-```bash
-# Development (default)
-cargo nextest run
-
-# CI with retries
-cargo nextest run --profile ci
-
-# Coverage optimized
-cargo nextest run --profile coverage
-```
+This bumps version in `Cargo.toml` and `package.json`, builds macOS arm64 and Linux amd64 binaries, tags the repo, and publishes a Gitea release with changelog and binaries attached.