init codebase

CLAUDE.md

@@ -30,17 +30,54 @@ CLI           —     —      yes (external, via Auth GW)
 
 ## Common Commands
 
+### Task Runner (Babashka)
+
+Preferred way to run tasks — `bb` wraps `clj` commands and manages Docker infra automatically.
+
+```bash
+bb tasks                  # List all available tasks
+
+# Development
+bb dev                    # Start dev infra + nREPL (all modules)
+bb infra:dev              # Start dev Docker infra only
+bb infra:dev:stop         # Stop dev Docker infra
+
+# Testing
+bb test                   # All tests (starts test infra)
+bb test:unit              # Unit tests only (no Docker needed)
+bb test:integration       # Integration tests (starts test infra)
+bb test:e2e               # E2E tests (starts test infra)
+
+# Per-module testing
+bb test:shared            # All shared tests
+bb test:shared:unit       # Shared unit tests only
+bb test:api               # All API tests
+bb test:api:unit          # API unit tests only
+bb test:auth-gw           # All auth-gw tests
+
+# Per-module bb.edn (from module directory)
+cd shared && bb test:unit # Delegates to root bb.edn
+
+# Build & Deploy
+bb build api              # Build uberjar for a module
+bb clean api              # Clean module artifacts (or bb clean for all)
+bb prod                   # Start production stack (docker compose)
+bb prod:stop              # Stop production stack
+bb prod:logs              # Tail production logs
+
+# Database
+bb db:reset-test          # Drop & recreate test DB schema
+```
+
 ### Running Services (REPL-driven)
 
 ```bash
-# Single REPL with all modules
-clj -A:dev:api:web-sm:tui-sm:auth-gw
+# Via bb (recommended)
+bb dev                    # nREPL with all modules + dev infra
 
-# Individual service REPLs
-clj -M:dev:api        # API service
-clj -M:dev:web-sm     # Web session manager
-clj -M:dev:tui-sm     # TUI session manager
-clj -M:dev:auth-gw    # Auth gateway
+# Via clj directly
+clj -A:dev:api:web-sm:tui-sm:auth-gw   # Single REPL with all modules
+clj -M:dev:api                          # Individual service REPL
 ```
 
 Services expose `(start!)` / `(stop!)` / `(reset!)` in their REPL namespaces.
@@ -48,10 +85,15 @@ Services expose `(start!)` / `(stop!)` / `(reset!)` in their REPL namespaces.
 ### Testing (Kaocha)
 
 ```bash
-clj -M:test/unit          # Unit tests — no Docker needed
-clj -M:test/integration   # Integration — requires Docker (Postgres + MinIO + NATS)
-clj -M:test/e2e           # E2E — requires full stack in Docker
-clj -M:test/all           # All tiers
+# Via bb (recommended — manages Docker infra automatically)
+bb test:unit              # Unit tests — no Docker needed
+bb test:integration       # Integration — starts Docker automatically
+bb test                   # All tiers
+
+# Via clj directly (legacy — requires manual Docker management)
+clj -M:test/base:test/unit          # Unit tests
+clj -M:test/base:test/integration   # Integration tests
+clj -M:test -m kaocha.runner        # All tests (using unified :test alias)
 ```
 
 Docker infra for integration tests: `docker compose -f docker-compose.test.yml up -d`