docs: README + CLAUDE.md + .env.example + quickref reflect latest gates

README.md

@@ -1,22 +1,51 @@
 # 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.
+Turborepo + pnpm monorepo organised by vertical features, with an **agent-first workflow** and **five conformance gates**.
 
-## Quick Start
+## Start here
+
+Read [`docs/guides/runbook.md`](./docs/guides/runbook.md) — day-1 onboarding (prerequisites, env vars, daily commands, troubleshooting).
+
+## Quick reference
 
 ```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
+pnpm install           # Install + auto-wire husky pre-commit hooks
+pnpm dev               # All dev servers (web-next:3000, cms:3001, web-tanstack:3002, storybook:6006)
+pnpm test              # All tests
+pnpm typecheck         # TypeScript across all packages
+pnpm lint              # ESLint (incl. 8 conformance/* rules)
+pnpm conformance       # Cross-feature event closure
+pnpm fallow            # Whole-codebase: dead exports, dupes, complexity
+pnpm turbo boundaries  # Workspace dependency graph
+pnpm work status       # docs/work/ epic + story state
 docker compose up -d   # Start PostgreSQL
 ```
 
+## Documentation map
+
+- **[`docs/guides/runbook.md`](./docs/guides/runbook.md)** — start here
+- **[`CLAUDE.md`](./CLAUDE.md)** — full conventions reference
+- **[`AGENTS.md`](./AGENTS.md)** — package map + boundary rules
+- **[`docs/guides/conformance-quickref.md`](./docs/guides/conformance-quickref.md)** — manifest + 5-gate daily reference
+- **[`docs/architecture/agent-first-workflow-and-conformance.md`](./docs/architecture/agent-first-workflow-and-conformance.md)** — full design
+- **[`docs/architecture/feature-conformance-explainer.html`](./docs/architecture/feature-conformance-explainer.html)** — interactive explainer
+
+## Scaffolding
+
+```bash
+pnpm turbo gen feature <name>             # Lazar-conformant feature (manifest + contracts + tests)
+pnpm turbo gen event                      # Event contract or handler (requires gen core-package events)
+pnpm turbo gen job                        # Background job
+pnpm turbo gen realtime                   # Realtime channel (requires gen core-package realtime)
+pnpm turbo gen core-package <name>        # Optional core: events / realtime / trpc / ui / audit
+pnpm turbo gen core-ui-component <name>   # Atomic-design component
+```
+
+**Generator-first is non-negotiable** — hand-rolled feature/event/job/realtime/component code is rejected by reviewer agents and may fail the CI scaffold-drift check.
+
 ## Optional packages
 
-The default template includes the must-have core packages and all 5 feature packages. Five core packages are optional and scaffold on demand:
+Five core packages scaffold on demand:
 
 ```bash
 pnpm turbo gen core-package realtime  # Socket.IO realtime layer (ADR-016)
@@ -26,14 +55,4 @@ pnpm turbo gen core-package ui        # Design system
 pnpm turbo gen core-package audit     # DPA-compliant audit logging (ADR-018)
 ```
 
-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 |
+See [`docs/architecture/template-tiers.md`](./docs/architecture/template-tiers.md) for the full tier list.