diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c8bbe42
--- /dev/null
+++ b/README.md
@@ -0,0 +1,38 @@
+# Clean Architecture Monorepo Template
+
+Turborepo + pnpm monorepo organized by vertical features. See `CLAUDE.md` for the full conventions reference and `AGENTS.md` for the package map.
+
+## Quick Start
+
+```bash
+pnpm install           # Install all dependencies
+pnpm dev               # Start all dev servers
+pnpm build             # Build all packages
+pnpm test              # Run all tests
+pnpm turbo boundaries  # Validate workspace dependency graph
+pnpm turbo gen feature # Scaffold a new feature package
+docker compose up -d   # Start PostgreSQL
+```
+
+## Optional packages
+
+The default template includes the must-have core packages and all 5 feature packages. Four core packages are optional and scaffold on demand:
+
+```bash
+pnpm turbo gen core-package realtime  # Socket.IO realtime layer (ADR-016)
+pnpm turbo gen core-package events    # Cross-feature events + Payload jobs (ADR-015)
+pnpm turbo gen core-package trpc      # tRPC server setup
+pnpm turbo gen core-package ui        # Design system
+```
+
+See `docs/architecture/template-tiers.md` for the full tier list.
+
+## Key ports
+
+| Service | Port |
+|---|---|
+| Next.js | 3000 |
+| Payload CMS | 3001 |
+| TanStack Start | 3002 |
+| PostgreSQL | 5432 |
+| Storybook | 6006 |