Phase 1 work

- Create dev.ulfrx.recipe.shared sub-package with .gitkeep marker
- Phase 2+ will populate with cross-target DTOs / domain models
- Satisfies INFRA-06 file-existence criterion for empty package scaffold

.editorconfig

@@ -0,0 +1,21 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+
+[*.{kt,kts}]
+# ktlint configuration for Compose Multiplatform.
+# - function-naming is disabled because @Composable functions and Kotlin/Native
+#   entry-point factories (e.g. MainViewController) are PascalCase by convention.
+# - filename is disabled because Compose-Multiplatform entry-point files
+#   (jvmMain/main.kt, webMain/main.kt) follow the Kotlin `fun main()` convention.
+ktlint_standard_function-naming = disabled
+ktlint_standard_filename = disabled
+
+[*.md]
+trim_trailing_whitespace = false

.planning/PROJECT.md

@@ -21,12 +21,12 @@ A mobile-first meal planning app for a small household — pick recipes for the
 - [ ] Sessions persist across app launches; offline access works with cached credentials
 
 **Household sharing**
-- [ ] Two users (me + partner) share one household: one plan, one pantry, one shopping list
+- [ ] Users can join a household: one plan, one pantry, one shopping list
 - [ ] Changes by either user converge on all devices when online
 
 **Recipes (browse & detail)**
 - [ ] User can browse a curated recipe catalog with a grid view
-- [ ] User can filter recipes by meal slot, tags, and cooking time
+- [ ] User can filter recipes by meal slot, tags, cooking time, and ingredients
 - [ ] User can search recipes by title/tag
 - [ ] User can open a recipe detail view with ingredients, steps, and nutrition per serving
 
@@ -73,13 +73,13 @@ A mobile-first meal planning app for a small household — pick recipes for the
 - True native iOS 26 Liquid Glass via SwiftUI interop — *Compose approximation for v1; revisit only if real-device chrome feels clearly inadequate*
 - Desktop and Wasm as shipped products — *Desktop useful for hot-reload dev; Wasm is a possible future target, neither is a v1 deliverable*
 - Sign in with Apple as a first-class button — *user's Authentik handles auth; Apple can be federated upstream in Authentik if needed later*
+- Barcode scanning / receipt OCR for pantry updates — *manual entry is fine for a 2-person household*
+- AI-generated recipes — *curated catalog is the value*
 
 **Permanently out of scope (explicit exclusions):**
 - Social features: comments, ratings, recipe feeds, public profiles — *this is a private household app, not a community product*
 - Meal-plan marketplaces / paid plans — *personal-use product*
 - Grocery delivery integrations (Instacart, etc.) — *Polish market + small scope; not worth the integration cost*
-- Barcode scanning / receipt OCR for pantry updates — *manual entry is fine for a 2-person household*
-- AI-generated recipes — *curated catalog is the value*
 
 **Deliberately not carried forward from the mockup:**
 - The mockup's seed data (~80 ingredients, ~30 recipes) — *user chose to start the catalog fresh*
@@ -113,6 +113,8 @@ A mobile-first meal planning app for a small household — pick recipes for the
 
 ## Key Decisions
 
+### Product & scope
+
 | Decision | Rationale | Outcome |
 |----------|-----------|---------|
 | KMP with Compose Multiplatform for UI | iOS-primary + Android secondary + Desktop/Wasm optional; single codebase for 90%+ of UI | — Pending |
@@ -126,6 +128,52 @@ A mobile-first meal planning app for a small household — pick recipes for the
 | Nutrition is informational only in v1 | Keep scope tight; tracking/goals are a natural v2 if usage patterns justify | — Pending |
 | Mockup is functional spec only, not visual spec | Visual direction is changing (Liquid Glass); logic is mature and worth mining | — Pending |
 
+### Client tech stack (composeApp)
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Navigation: Jetpack Navigation Compose (CMP port) — `org.jetbrains.androidx.navigation:navigation-compose:2.9.x` | JetBrains-official recommendation on kotlinlang.org; type-safe routes via `@Serializable`; works across Android/iOS/Desktop/Wasm; skill transferable to Android | — Pending |
+| Architecture: ViewModel + StateFlow + method-per-action | Standard modern pattern; matches JetBrains/Google samples; lowest ceremony; upgrade individual screens to sealed-event onEvent only when they grow complex | — Pending |
+| DI: Koin — `koin-core`, `koin-compose`, `koin-compose-viewmodel` | De facto KMP standard; smoothest `koinViewModel()` integration with Jetpack Nav back-stack scoping; no codegen; small surface to learn | — Pending |
+| Local DB: SQLDelight 2.x | Most mature KMP DB; Wasm-ready (hedge for future Compose-for-Web target); raw SQL is a transferable skill; clear migration story via .sq files | — Pending |
+| HTTP client: Ktor Client | Same team as server; first-class KMP; shared serialization config | — Pending |
+| Serialization: kotlinx.serialization (JSON) | Standard; works everywhere; pairs with Ktor and SQLDelight | — Pending |
+| Date/time: kotlinx.datetime | Standard; SQLDelight adapters available | — Pending |
+| Logging: Kermit (Touchlab) | KMP-native logger; simple API; optional Crashlytics/Sentry bridges | — Pending |
+| Image loading: Coil 3 (`io.coil-kt.coil3:coil-compose`) | First-class Compose Multiplatform support; modern API | — Pending |
+| Key-value settings: `com.russhwolf:multiplatform-settings` | Small prefs (last tab, theme toggles) that don't belong in SQLDelight | — Pending |
+| Glass/blur effects: Haze (`dev.chrisbanes.haze:haze`) | Purpose-built for glass UI in CMP; handles content capture + efficient re-blur; multiplatform | — Pending |
+| Mobile OIDC: AppAuth (Android) + ASWebAuthenticationSession wrapper (iOS), exposed via KMP interface | Platform-native OAuth flows; no cross-platform auth library mature enough yet for this in 2026 | — Pending |
+
+### Server tech stack
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Server framework: Ktor Server 3.x | Same team as client HTTP; Kotlin-native; fits homelab deployment; coroutines throughout | — Pending |
+| Database: Postgres | Homelab-friendly (Docker); JSONB for meal-entry extras; room to grow; standard skill | — Pending |
+| SQL: Exposed DSL | Kotlin-backend standard; type-safe SQL builders; JSONB first-class; strong tutorial trail with Ktor. Avoid Exposed's DAO (active record) API | — Pending |
+| Migrations: Flyway | Industry-standard numbered `V__.sql` files; auto-apply on startup; works with any JDBC-backed stack | — Pending |
+| Token validation: `io.ktor:ktor-server-auth-jwt` | Built-in JWKS support with caching + rotation; direct integration with Authentik's OIDC endpoint | — Pending |
+
+### Sync
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Strategy: last-write-wins with server-assigned `updated_at` per row | Household of 2 has negligible concurrent-edit risk; simplest to implement and debug; upgradeable per-table to op-log later if hurt | — Pending |
+| Transport: HTTP polling (20–30s when foreground) + pull-to-refresh + debounced push after local writes | Sufficient freshness for a household; SSE is a v2 enhancement if polling feels laggy | — Pending |
+| API shape: REST, versioned `/api/v1`, two sync endpoints (`POST /sync/push`, `GET /sync/pull?since=...`) plus catalog + households/invites CRUD | Versioning leaves room to evolve; minimal surface area; read-mostly catalog is heavily cached on client | — Pending |
+| Server-side data model: `users`, `households`, `memberships`, `invites` + household-scoped tables carrying `household_id`, `updated_at`, `deleted_at` | Supports household sharing + invites, JIT user provisioning from OIDC `sub`, soft deletes for sync | — Pending |
+
+### Build & module structure
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Gradle version catalog (`gradle/libs.versions.toml`) | Single source of truth for versions; standard KMP practice | — Pending |
+| Convention plugins (`build-logic/` module) from day 1 | Centralizes Kotlin/Compose/test config; educational payoff; small upfront cost | — Pending |
+| Keep template modules: `composeApp/`, `iosApp/`, `server/`, `shared/` — no feature modules in v1 | Feature modules don't pay off until ~10 features or multiple devs; flat is clearer at this scale | — Pending |
+| `shared/commonMain` holds: domain models + API DTOs only (no UI, no HTTP, no DB) | Keeps shared dep graph minimal; both client and server depend on `shared/` | — Pending |
+| `composeApp/commonMain` package layout: `app/ navigation/ ui/{theme,components,screens/{recipes,planner,pantry,shopping}} data/{local,remote,repository} domain/` | Groups by UI concern + data layer; resists premature modularization | — Pending |
+
 ## Evolution
 
 This document evolves at phase transitions and milestone boundaries.
@@ -144,4 +192,4 @@ This document evolves at phase transitions and milestone boundaries.
 4. Update Context with current state
 
 ---
-*Last updated: 2026-04-23 after initialization*
+*Last updated: 2026-04-24 after initial tech-stack discussion*

.planning/REQUIREMENTS.md

@@ -0,0 +1,242 @@
+# Requirements: Recipe
+
+**Defined:** 2026-04-24
+**Core Value:** "My week is planned." I pick recipes, the calendar fills up, and I know what we're eating.
+
+## v1 Requirements
+
+### Authentication & identity
+
+- [ ] **AUTH-01**: User can sign in via the self-hosted Authentik instance using OIDC (authorization code flow with PKCE)
+- [ ] **AUTH-02**: Client stores access + refresh tokens securely (iOS Keychain / Android EncryptedSharedPreferences)
+- [ ] **AUTH-03**: Ktor server validates incoming access tokens via Authentik's JWKS endpoint (issuer, audience, expiry, signature, clock skew leeway)
+- [ ] **AUTH-04**: User session persists across app launches without re-authentication (token refresh handled transparently)
+- [ ] **AUTH-05**: User can sign out, which revokes local tokens and returns to the login screen
+- [ ] **AUTH-06**: Users are JIT-provisioned in the server database on first successful login (by OIDC `sub` claim)
+
+### Household sharing
+
+- [ ] **HSHD-01**: On first login, user is prompted to create a new household or join an existing one via invite code
+- [ ] **HSHD-02**: User can create a new household and become its first member
+- [ ] **HSHD-03**: User can generate an invite code for their household (short-lived, single-use)
+- [ ] **HSHD-04**: Another user can redeem an invite code to join the household
+- [ ] **HSHD-05**: All household members see the same plan, pantry, and shopping list
+- [ ] **HSHD-06**: Server-side tenancy is enforced: every household-scoped query filters by `household_id` derived from the authenticated principal, never from the request body
+- [ ] **HSHD-07**: Client queries for household data filter locally by active `household_id` (defense in depth)
+
+### Recipes — browse & detail
+
+- [ ] **RCPE-01**: User can view a grid of the household's recipe catalog
+- [ ] **RCPE-02**: User can filter recipes by meal slot (śniadanie / drugie śniadanie / obiad / przekąska / kolacja)
+- [ ] **RCPE-03**: User can filter recipes by tag (e.g., "szybkie", "wegetariańskie", "wysokobiałkowe")
+- [ ] **RCPE-04**: User can filter recipes by cooking time range (minutes)
+- [ ] **RCPE-05**: User can search recipes by title or tag text
+- [ ] **RCPE-06**: User can open a recipe detail view showing ingredients (with amounts + units), steps, nutrition per serving, and cooking time
+- [ ] **RCPE-07**: Recipe detail shows ingredient alternatives (substitutions) where defined in the catalog
+- [ ] **RCPE-08**: Recipe catalog is seeded via server-side SQL fixtures or admin CLI (no in-app authoring in v1)
+
+### Meal planner (hero feature)
+
+- [ ] **PLAN-01**: User can view a calendar showing planned meals per day
+- [ ] **PLAN-02**: User can navigate between days/weeks/months in the calendar
+- [ ] **PLAN-03**: User can add a recipe to any of the 5 slots on any day (śniadanie, drugie śniadanie, obiad, przekąska, kolacja)
+- [ ] **PLAN-04**: User can remove a meal entry from a slot
+- [ ] **PLAN-05**: User can replace a meal entry by picking a different recipe
+- [ ] **PLAN-06**: User can adjust servings on a meal entry (1–12)
+- [ ] **PLAN-07**: User can substitute an ingredient in a meal entry with one of the defined alternatives
+- [ ] **PLAN-08**: User can exclude an ingredient from a meal entry (won't appear in shopping/pantry calculations)
+- [ ] **PLAN-09**: User can add an extra ingredient to a meal entry (amount + unit from the ingredient catalog)
+- [ ] **PLAN-10**: User can override the amount of an ingredient in a meal entry
+- [ ] **PLAN-11**: User can select a specific product (pack size) for a given ingredient in a meal entry
+- [ ] **PLAN-12**: User can mark a meal slot as skipped for a day
+- [ ] **PLAN-13**: User sees daily nutrition totals (kcal, protein, fat, carbs) aggregated from all planned meals that day, respecting customizations
+- [ ] **PLAN-14**: Meal entries have stable UUID identity (never composite keys like `date + slot`) to survive concurrent edits
+
+### Pantry
+
+- [ ] **PNTR-01**: User can view pantry inventory grouped by ingredient category (pieczywo, nabiał, mięso i ryby, warzywa, owoce, suche, przyprawy, inne)
+- [ ] **PNTR-02**: User can manually add or update the quantity of an ingredient in the pantry (using its pantry unit: g, ml, szt.)
+- [ ] **PNTR-03**: User sees which ingredients fall short over a user-selected planning horizon (e.g., next 7 days) based on the plan minus current pantry
+- [ ] **PNTR-04**: User can filter pantry view by category
+- [ ] **PNTR-05**: User can filter pantry view by shortfall status (needed / sufficient / not in plan)
+
+### Shopping list
+
+- [ ] **SHOP-01**: User can select a date range from the plan to generate a shopping list
+- [ ] **SHOP-02**: Shopping list aggregates all ingredient needs across selected days minus current pantry quantities
+- [ ] **SHOP-03**: Shopping list groups items by ingredient category for efficient in-store navigation
+- [ ] **SHOP-04**: User can mark an item as bought during a shopping session; the item is removed from active needs and added to pantry in its pantry unit
+- [ ] **SHOP-05**: User can undo a recently marked-bought item within the same session
+- [ ] **SHOP-06**: Session log persists across app restarts until the user explicitly clears it
+
+### Offline + sync
+
+- [ ] **SYNC-01**: Client reads all household data from local SQLDelight without requiring network
+- [ ] **SYNC-02**: Client writes all household data locally first (optimistic UI), then queues the change for sync
+- [ ] **SYNC-03**: Server assigns `updated_at` (server time, monotonic) on every accepted write; clients never trust their own device clock for sync ordering
+- [ ] **SYNC-04**: Client pulls household changes via `GET /sync/pull?since=...` using a lexicographic `(updated_at, id)` cursor to survive same-millisecond writes
+- [ ] **SYNC-05**: Client pushes pending writes via `POST /sync/push` (batched); accepted writes come back with server-assigned `updated_at`
+- [ ] **SYNC-06**: Deletes are soft deletes (`deleted_at` column); synced as state changes, not as "delete ops"
+- [ ] **SYNC-07**: Sync runs on: app foreground, pull-to-refresh, debounced 2s after every local write, and polls every 20–30s while foreground
+- [ ] **SYNC-08**: Sync failures (network error, 5xx) retry with exponential backoff and do not block the UI
+- [ ] **SYNC-09**: Sync engine is implemented as a single Koin singleton owning the outbox queue and pull cursor — features never issue HTTP writes directly
+- [ ] **SYNC-10**: When two household members edit the same row, the server-assigned later write wins; no silent data loss because writes use UUID identity, not natural keys
+
+### UI foundation (polish + glass aesthetic)
+
+- [ ] **UI-01**: All user-facing strings are externalized as Compose resources (i18n-ready), even though v1 ships Polish only
+- [ ] **UI-02**: App ships with Polish-language copy throughout
+- [ ] **UI-03**: Bottom tab navigation with 4 tabs: Przepisy / Planer / Spiżarnia / Zakupy, each preserving its own back stack independently
+- [ ] **UI-04**: Tab bar and nav bar use Haze-based glass/blur effects (Liquid Glass approximation)
+- [ ] **UI-05**: App supports light and dark color schemes with translucent surfaces working in both
+- [ ] **UI-06**: UI is iOS-idiomatic within Compose constraints (safe areas, swipe-back gesture where applicable, keyboard avoidance)
+- [ ] **UI-07**: Visual hierarchy is less cramped than the mockup — deliberate spacing, calmer typography, readable at arm's length
+- [ ] **UI-08**: Locale-aware date formatting for display (days, months, weekday names in Polish); sync wire-format stays UTC ISO-8601
+- [ ] **UI-09**: App starts cleanly on first launch (no blank flash) and shows appropriate empty states when catalog / plan / pantry / shopping are empty
+
+### Infrastructure & build
+
+- [ ] **INFRA-01**: Gradle version catalog at `gradle/libs.versions.toml` is the single source of truth for library versions
+- [ ] **INFRA-02**: `build-logic/` convention plugins centralize Kotlin/Compose/test configuration across modules
+- [ ] **INFRA-03**: iOS Kotlin/Native binary options set from day 1: `kotlin.native.binary.objcDisposeOnMain=false`, `gc=cms`
+- [ ] **INFRA-04**: Server Docker image builds and deploys to user's homelab alongside Authentik
+- [ ] **INFRA-05**: Flyway migrations run automatically on server startup in a known order
+- [ ] **INFRA-06**: `shared/commonMain` contains only domain models + API DTOs — no UI, no HTTP, no DB code
+- [ ] **INFRA-07**: App is distributed to partner via TestFlight (iOS) for initial dogfooding
+
+## v2 Requirements
+
+Explicitly acknowledged but deferred. Not in the v1 roadmap.
+
+### In-app recipe authoring
+
+- **AUTHR-01**: User can create a new recipe with ingredients, steps, nutrition, allowed slots, tags
+- **AUTHR-02**: User can edit an existing recipe
+- **AUTHR-03**: User can archive/delete a recipe they created
+
+### Nutrition goal tracking
+
+- **NUTR-01**: User can set daily macro targets (kcal, protein, fat, carbs)
+- **NUTR-02**: Planner shows deficit/surplus vs. targets per day
+- **NUTR-03**: User can view weekly nutrition trends
+
+### Additional platforms
+
+- **PLAT-01**: Android app distributed to household members (APK or Play Store)
+- **PLAT-02**: Web (Compose for Wasm) as a PWA replacement for the current mockup
+- **PLAT-03**: English localization (full copy pass)
+
+### Sync hardening
+
+- **SYNC2-01**: Server-sent events (SSE) for near-realtime sync instead of polling
+- **SYNC2-02**: Per-table upgrade path from LWW to operation-log sync if concurrent-edit data loss becomes observable
+
+### iOS Liquid Glass fidelity
+
+- **LG2-01**: Native SwiftUI interop for tab bar and nav bar (real iOS 26 Liquid Glass material) if Compose approximation proves inadequate on real hardware
+
+## Out of Scope
+
+Explicitly excluded. Documented to prevent scope creep.
+
+| Feature | Reason |
+|---------|--------|
+| Social features (comments, ratings, public profiles, feeds) | Private household app, not a community product |
+| Recipe sharing between households | Households are isolated in v1; recipe marketplace is not the point |
+| Meal-plan marketplace / paid plans | Personal-use product |
+| Grocery-delivery integrations (Instacart, Carrefour Online, etc.) | Polish-market + small scope; integration cost not justified |
+| Barcode scanning / receipt OCR for pantry updates | Manual entry is fine for a 2-person household |
+| AI-generated recipes | Curated catalog is the value |
+| Apple Sign-in as a first-class button | Authentik OIDC is user's IdP, not a third-party social login |
+| Port of mockup's vanilla-JS visual design | Visual rebuild around Liquid-Glass language; mockup is functional spec only |
+| Port of mockup's ~80 ingredients + ~30 recipes as seed data | User explicitly chose to re-curate catalog fresh |
+| Device-clock-based sync timestamps | Silent data loss under drift; server-assigned timestamps mandatory |
+| True iOS 26 Liquid Glass native material in v1 | Requires SwiftUI interop; Compose approximation is v1 scope |
+
+## Traceability
+
+Populated during roadmap creation. Each v1 requirement maps to exactly one phase.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| AUTH-01 | Phase 2: Authentication Foundation | Pending |
+| AUTH-02 | Phase 2: Authentication Foundation | Pending |
+| AUTH-03 | Phase 2: Authentication Foundation | Pending |
+| AUTH-04 | Phase 2: Authentication Foundation | Pending |
+| AUTH-05 | Phase 2: Authentication Foundation | Pending |
+| AUTH-06 | Phase 2: Authentication Foundation | Pending |
+| HSHD-01 | Phase 3: Households, Membership & Server Data Foundation | Pending |
+| HSHD-02 | Phase 3: Households, Membership & Server Data Foundation | Pending |
+| HSHD-03 | Phase 3: Households, Membership & Server Data Foundation | Pending |
+| HSHD-04 | Phase 3: Households, Membership & Server Data Foundation | Pending |
+| HSHD-05 | Phase 3: Households, Membership & Server Data Foundation | Pending |
+| HSHD-06 | Phase 3: Households, Membership & Server Data Foundation | Pending |
+| HSHD-07 | Phase 3: Households, Membership & Server Data Foundation | Pending |
+| RCPE-01 | Phase 5: Recipe Catalog (Read Path) | Pending |
+| RCPE-02 | Phase 5: Recipe Catalog (Read Path) | Pending |
+| RCPE-03 | Phase 5: Recipe Catalog (Read Path) | Pending |
+| RCPE-04 | Phase 5: Recipe Catalog (Read Path) | Pending |
+| RCPE-05 | Phase 5: Recipe Catalog (Read Path) | Pending |
+| RCPE-06 | Phase 5: Recipe Catalog (Read Path) | Pending |
+| RCPE-07 | Phase 5: Recipe Catalog (Read Path) | Pending |
+| RCPE-08 | Phase 5: Recipe Catalog (Read Path) | Pending |
+| PLAN-01 | Phase 6: Meal Planner — Core Write Path | Pending |
+| PLAN-02 | Phase 6: Meal Planner — Core Write Path | Pending |
+| PLAN-03 | Phase 6: Meal Planner — Core Write Path | Pending |
+| PLAN-04 | Phase 6: Meal Planner — Core Write Path | Pending |
+| PLAN-05 | Phase 6: Meal Planner — Core Write Path | Pending |
+| PLAN-06 | Phase 6: Meal Planner — Core Write Path | Pending |
+| PLAN-07 | Phase 7: Meal Planner — Customization & Nutrition | Pending |
+| PLAN-08 | Phase 7: Meal Planner — Customization & Nutrition | Pending |
+| PLAN-09 | Phase 7: Meal Planner — Customization & Nutrition | Pending |
+| PLAN-10 | Phase 7: Meal Planner — Customization & Nutrition | Pending |
+| PLAN-11 | Phase 7: Meal Planner — Customization & Nutrition | Pending |
+| PLAN-12 | Phase 6: Meal Planner — Core Write Path | Pending |
+| PLAN-13 | Phase 7: Meal Planner — Customization & Nutrition | Pending |
+| PLAN-14 | Phase 6: Meal Planner — Core Write Path | Pending |
+| PNTR-01 | Phase 8: Pantry | Pending |
+| PNTR-02 | Phase 8: Pantry | Pending |
+| PNTR-03 | Phase 8: Pantry | Pending |
+| PNTR-04 | Phase 8: Pantry | Pending |
+| PNTR-05 | Phase 8: Pantry | Pending |
+| SHOP-01 | Phase 9: Shopping List & Session Log | Pending |
+| SHOP-02 | Phase 9: Shopping List & Session Log | Pending |
+| SHOP-03 | Phase 9: Shopping List & Session Log | Pending |
+| SHOP-04 | Phase 9: Shopping List & Session Log | Pending |
+| SHOP-05 | Phase 9: Shopping List & Session Log | Pending |
+| SHOP-06 | Phase 9: Shopping List & Session Log | Pending |
+| SYNC-01 | Phase 4: Sync Engine Skeleton | Pending |
+| SYNC-02 | Phase 4: Sync Engine Skeleton | Pending |
+| SYNC-03 | Phase 4: Sync Engine Skeleton | Pending |
+| SYNC-04 | Phase 4: Sync Engine Skeleton | Pending |
+| SYNC-05 | Phase 4: Sync Engine Skeleton | Pending |
+| SYNC-06 | Phase 4: Sync Engine Skeleton | Pending |
+| SYNC-07 | Phase 4: Sync Engine Skeleton | Pending |
+| SYNC-08 | Phase 4: Sync Engine Skeleton | Pending |
+| SYNC-09 | Phase 4: Sync Engine Skeleton | Pending |
+| SYNC-10 | Phase 4: Sync Engine Skeleton | Pending |
+| UI-01 | Phase 11: Localization & iOS Deployment | Pending |
+| UI-02 | Phase 11: Localization & iOS Deployment | Pending |
+| UI-03 | Phase 10: UI Chrome & Haze Liquid-Glass Polish | Pending |
+| UI-04 | Phase 10: UI Chrome & Haze Liquid-Glass Polish | Pending |
+| UI-05 | Phase 5: Recipe Catalog (Read Path) | Pending |
+| UI-06 | Phase 10: UI Chrome & Haze Liquid-Glass Polish | Pending |
+| UI-07 | Phase 10: UI Chrome & Haze Liquid-Glass Polish | Pending |
+| UI-08 | Phase 5: Recipe Catalog (Read Path) | Pending |
+| UI-09 | Phase 10: UI Chrome & Haze Liquid-Glass Polish | Pending |
+| INFRA-01 | Phase 1: Project Infrastructure & Module Wiring | Pending |
+| INFRA-02 | Phase 1: Project Infrastructure & Module Wiring | Pending |
+| INFRA-03 | Phase 1: Project Infrastructure & Module Wiring | Pending |
+| INFRA-04 | Phase 11: Localization & iOS Deployment | Pending |
+| INFRA-05 | Phase 3: Households, Membership & Server Data Foundation | Pending |
+| INFRA-06 | Phase 1: Project Infrastructure & Module Wiring | Pending |
+| INFRA-07 | Phase 11: Localization & iOS Deployment | Pending |
+
+**Coverage:**
+- v1 requirements: **72 total** (AUTH=6, HSHD=7, RCPE=8, PLAN=14, PNTR=5, SHOP=6, SYNC=10, UI=9, INFRA=7)
+- Mapped to phases: **72**
+- Unmapped: **0**
+
+---
+*Requirements defined: 2026-04-24*
+*Last updated: 2026-04-23 after roadmap creation*

.planning/ROADMAP.md

@@ -0,0 +1,236 @@
+# Roadmap: Recipe
+
+**Core Value:** "My week is planned." I pick recipes, the calendar fills up, and I know what we're eating.
+
+**Granularity:** Fine (11 phases)
+**Mode:** YOLO
+**Source of truth:** Derived from `.planning/REQUIREMENTS.md` (72 v1 requirements) guided by `.planning/research/SUMMARY.md` (suggested skeleton) and `.planning/research/ARCHITECTURE.md` (build-order reasoning).
+
+## Phases
+
+- [ ] **Phase 1: Project Infrastructure & Module Wiring** — Running-but-empty KMP client + Ktor server with all build infra baked in
+- [ ] **Phase 2: Authentication Foundation** — User signs in through Authentik (OIDC+PKCE) and the server validates tokens
+- [ ] **Phase 3: Households, Membership & Server Data Foundation** — Users create/join households; server enforces household scope
+- [ ] **Phase 4: Sync Engine Skeleton** — Offline-first read/write with outbox-backed LWW sync on a sentinel table
+- [ ] **Phase 5: Recipe Catalog (Read Path)** — User browses, filters, and opens recipe details from a seeded catalog
+- [ ] **Phase 6: Meal Planner — Core Write Path** — User picks recipes into the 5-slot calendar; first real outbox-backed aggregate
+- [ ] **Phase 7: Meal Planner — Customization & Nutrition** — User tweaks servings/ingredients/products per meal entry and sees daily nutrition
+- [ ] **Phase 8: Pantry** — User tracks what's on hand and sees shortfalls against the plan
+- [ ] **Phase 9: Shopping List & Session Log** — User generates a grouped shopping list from the plan and shops with "bought" tracking
+- [ ] **Phase 10: UI Chrome & Haze Liquid-Glass Polish** — Tab/nav glass effects, iOS-idiomatic chrome, calmer visual hierarchy
+- [ ] **Phase 11: Localization & iOS Deployment** — Full Polish copy pass, i18n-ready resources, TestFlight to partner
+
+## Phase Summary Table
+
+| # | Name | Goal (one line) | Requirements | #SC |
+|---|------|-----------------|--------------|-----|
+| 1 | Project Infrastructure & Module Wiring | KMP client + Ktor server build cleanly with convention plugins, version catalog, iOS binary flags, and a shared DTO module | INFRA-01, INFRA-02, INFRA-03, INFRA-06 | 4 |
+| 2 | Authentication Foundation | End-to-end OIDC+PKCE login to Authentik with JIT user provisioning and server-side JWT validation | AUTH-01, AUTH-02, AUTH-03, AUTH-04, AUTH-05, AUTH-06 | 5 |
+| 3 | Households, Membership & Server Data Foundation | Create/join households via invites; every request carries a household-scoped principal derived from JWT | HSHD-01, HSHD-02, HSHD-03, HSHD-04, HSHD-05, HSHD-06, HSHD-07, INFRA-05 | 5 |
+| 4 | Sync Engine Skeleton | Outbox-backed LWW sync works round-trip on a sentinel table with server-assigned timestamps and cursor pull | SYNC-01, SYNC-02, SYNC-03, SYNC-04, SYNC-05, SYNC-06, SYNC-07, SYNC-08, SYNC-09, SYNC-10 | 5 |
+| 5 | Recipe Catalog (Read Path) | User browses a seeded recipe catalog, filters/searches, and opens a detail view — offline-capable | RCPE-01, RCPE-02, RCPE-03, RCPE-04, RCPE-05, RCPE-06, RCPE-07, RCPE-08, UI-05, UI-08 | 5 |
+| 6 | Meal Planner — Core Write Path | User fills the 5-slot calendar with recipes; adds/removes/replaces/skips; writes survive offline and sync | PLAN-01, PLAN-02, PLAN-03, PLAN-04, PLAN-05, PLAN-06, PLAN-12, PLAN-14 | 5 |
+| 7 | Meal Planner — Customization & Nutrition | User customizes ingredients per meal entry and sees daily macro totals that respect customizations | PLAN-07, PLAN-08, PLAN-09, PLAN-10, PLAN-11, PLAN-13 | 4 |
+| 8 | Pantry | User manages pantry inventory by category and sees shortfalls for a chosen horizon | PNTR-01, PNTR-02, PNTR-03, PNTR-04, PNTR-05 | 4 |
+| 9 | Shopping List & Session Log | User generates a category-grouped shopping list and marks items bought during a session | SHOP-01, SHOP-02, SHOP-03, SHOP-04, SHOP-05, SHOP-06 | 4 |
+| 10 | UI Chrome & Haze Liquid-Glass Polish | 4-tab nav with independent back stacks, Haze glass chrome, iOS idioms, breathing-room visual hierarchy | UI-03, UI-04, UI-06, UI-07, UI-09 | 5 |
+| 11 | Localization & iOS Deployment | All strings externalized, Polish copy throughout, partner installs via TestFlight | UI-01, UI-02, INFRA-04, INFRA-07 | 4 |
+
+## Phase Details
+
+### Phase 1: Project Infrastructure & Module Wiring
+
+**Goal:** Stand up a KMP + Ktor repo whose build is "boring correct" from day 1 — version catalog, convention plugins, iOS binary flags, and a pure-Kotlin `shared/` module — so every later phase slots into an already-configured system.
+**Depends on:** Nothing (first phase)
+**Requirements:** INFRA-01, INFRA-02, INFRA-03, INFRA-06
+**Success Criteria** (what must be TRUE):
+  1. `./gradlew build` succeeds across `composeApp`, `server`, `shared`, and produces an iOS framework and an Android APK from the bare template screens.
+  2. All library versions are resolved through `gradle/libs.versions.toml`; no version literals exist inside any `build.gradle.kts`.
+  3. iOS `gradle.properties` carry `kotlin.native.binary.objcDisposeOnMain=false` and `kotlin.native.binary.gc=cms`; a debug launch on simulator boots without warnings about legacy memory-management flags.
+  4. `build-logic/` convention plugins apply the Kotlin/Compose/test configuration to every module — adding a new module requires only applying a convention plugin, not copying compiler args.
+  5. `shared/commonMain` contains only domain models + serializable DTOs; no Ktor, Compose, or SQLDelight imports appear anywhere under `shared/`.
+**Plans:** 7 plans
+
+Plans:
+- [ ] 01-01-PLAN.md — Version catalog extensions (Koin/Kermit/Spotless/Flyway/Postgres) + iOS K/N flags + verify-*.sh invariant scripts
+- [ ] 01-02-PLAN.md — build-logic/ included build with 5 precompiled plugins (recipe.quality, recipe.kotlin.multiplatform, recipe.compose.multiplatform, recipe.android.application, recipe.jvm.server) + root settings.gradle.kts includeBuild wiring
+- [ ] 01-03-PLAN.md — Module refactor: composeApp/shared/server build.gradle.kts apply recipe.* conventions; drop js target; enable explicitApi() on shared/
+- [ ] 01-04-PLAN.md — Koin + Kermit bootstrap across all 4 platforms (commonMain Koin.kt/AppModule.kt/Logging.kt; iOS KoinIos.kt bridge; Android MainApplication.kt + manifest; JVM/Wasm main() rewrites; iOSApp.swift wiring)
+- [ ] 01-05-PLAN.md — Server /health + Flyway bootstrap + HOCON config (application.conf, Database.kt with fail-loud contract, db/migration/.gitkeep, ApplicationTest.kt covers /health without Postgres)
+- [ ] 01-06-PLAN.md — docker-compose.yml (postgres:16) + README.md Local development section (drops js docs)
+- [ ] 01-07-PLAN.md — shared/ package scaffold + full green-build gate (spotlessApply, verify-*.sh, ./gradlew build, ./gradlew check)
+**UI hint:** no
+**Research flag:** no
+
+### Phase 2: Authentication Foundation
+
+**Goal:** Deliver a working end-to-end login: the app opens Authentik via OIDC (authorization code + PKCE), stores the tokens securely, and the Ktor server validates them on a protected `/api/v1/me` endpoint, JIT-provisioning users on first sign-in.
+**Depends on:** Phase 1
+**Requirements:** AUTH-01, AUTH-02, AUTH-03, AUTH-04, AUTH-05, AUTH-06
+**Success Criteria** (what must be TRUE):
+  1. From a fresh install on iOS, I can tap "Zaloguj się", complete Authentik's hosted login, and land back in the app as an authenticated user.
+  2. I close and reopen the app an hour later; I am still signed in without re-entering credentials (refresh token flow runs transparently).
+  3. I tap "Wyloguj się"; the app returns to the login screen and the stored tokens are gone from Keychain/EncryptedSharedPreferences.
+  4. Calling `GET /api/v1/me` with a valid token returns my user record; the same call with a missing, expired, or wrong-audience token returns 401.
+  5. My user row exists in the server DB after my first successful login, keyed by the OIDC `sub` claim (no manual user creation needed).
+**Plans:** TBD
+**UI hint:** yes
+**Research flag:** yes
+
+### Phase 3: Households, Membership & Server Data Foundation
+
+**Goal:** Introduce the tenancy model before any feature tables land — `users`, `households`, `memberships`, `invites` with Flyway migrations; server's `PrincipalResolver` maps JWT `sub` to an active `householdId`; client finishes onboarding by creating or joining a household.
+**Depends on:** Phase 2
+**Requirements:** HSHD-01, HSHD-02, HSHD-03, HSHD-04, HSHD-05, HSHD-06, HSHD-07, INFRA-05
+**Success Criteria** (what must be TRUE):
+  1. On my first login, I see an onboarding screen asking me to create a new household or enter an invite code.
+  2. I create a household, receive a short-lived single-use invite code, send it to my partner, and they redeem it to join the same household.
+  3. Once both users are in the same household, any household-scoped API call returns identical data regardless of which member made it.
+  4. A crafted API request that puts a different `household_id` in the body is ignored — the server always derives `household_id` from the authenticated principal, not the payload.
+  5. The server starts up and Flyway automatically applies `V1__init.sql` (or equivalent) in the correct order; restarting the server twice in a row is idempotent.
+**Plans:** TBD
+**UI hint:** yes
+**Research flag:** no
+
+### Phase 4: Sync Engine Skeleton
+
+**Goal:** Build the offline-first spine — a Koin-singleton `SyncEngine` that owns the outbox and pull cursor, server endpoints `POST /sync/push` + `GET /sync/pull?since=`, and a sentinel table round-trips through it — so every later feature just adds a table, not a sync strategy.
+**Depends on:** Phase 3
+**Requirements:** SYNC-01, SYNC-02, SYNC-03, SYNC-04, SYNC-05, SYNC-06, SYNC-07, SYNC-08, SYNC-09, SYNC-10
+**Success Criteria** (what must be TRUE):
+  1. I write to the sentinel table while the app is offline (airplane mode); the write appears instantly in the UI, and when I reconnect it reaches the server within seconds without manual intervention.
+  2. My partner edits the same sentinel row on their device; within the poll interval (20–30 s while foregrounded) I see their change, and if we both edited concurrently the server's later-assigned `updated_at` wins with no silent data loss.
+  3. I delete a sentinel row on device A; after sync the row is gone on device B — and if I re-create "the same" row it comes back with a fresh UUID identity and does not resurrect old fields.
+  4. Killing the app with pending writes in the outbox and relaunching later preserves those writes; they drain on the next sync cycle.
+  5. Network failures and 5xx responses trigger exponential backoff retries without blocking the UI; no feature code issues HTTP sync writes directly — all go through the `SyncEngine`.
+**Plans:** TBD
+**UI hint:** no
+**Research flag:** yes
+
+### Phase 5: Recipe Catalog (Read Path)
+
+**Goal:** Deliver the first real user-visible feature — a browseable recipe catalog — via a pull-only cache path that exercises Exposed + SQLDelight + Ktor + Coil end-to-end without write-path complexity, seeded server-side so the rest of the app has real data to develop against.
+**Depends on:** Phase 4
+**Requirements:** RCPE-01, RCPE-02, RCPE-03, RCPE-04, RCPE-05, RCPE-06, RCPE-07, RCPE-08, UI-05, UI-08
+**Success Criteria** (what must be TRUE):
+  1. I open "Przepisy" and see a grid of recipe cards with thumbnail, title, and cooking time — fully populated from server-seeded catalog data.
+  2. I can filter the grid by meal slot, tag, and cooking-time range, and search by title/tag text; results update as I type.
+  3. I tap a recipe and see a detail view with ingredients (amounts + units), steps, nutrition per serving, cooking time, and any defined substitutions.
+  4. I put the device in airplane mode, relaunch the app, and the catalog still renders from the local SQLDelight cache.
+  5. The app respects my system light/dark appearance setting, and recipe-list dates/times render in Polish locale format (day and month names in Polish).
+**Plans:** TBD
+**UI hint:** yes
+**Research flag:** no
+
+### Phase 6: Meal Planner — Core Write Path
+
+**Goal:** Ship the hero feature's skeleton — the calendar with 5 slots per day — as the first real household-scoped write aggregate. Every add/remove/replace/skip/serving-change goes through the outbox, proving the sync spine on realistic load.
+**Depends on:** Phase 5
+**Requirements:** PLAN-01, PLAN-02, PLAN-03, PLAN-04, PLAN-05, PLAN-06, PLAN-12, PLAN-14
+**Success Criteria** (what must be TRUE):
+  1. I open "Planer", navigate between days/weeks/months, and see each day's 5 slots (śniadanie, drugie śniadanie, obiad, przekąska, kolacja) with whatever I've planned.
+  2. I can tap a slot, pick a recipe from the catalog, and see it appear instantly — even while offline — then reappear on my partner's device after a sync cycle.
+  3. I can remove a meal entry, replace it with a different recipe, adjust its servings (1–12), and mark a slot as "skipped" for a specific day.
+  4. Every meal entry has a stable UUID identity; deleting and re-adding the same recipe on the same (day, slot) creates a distinct new entry rather than reviving the old one.
+  5. Two household members concurrently editing the same slot converge deterministically on whichever edit the server stamped last, with no silent data loss.
+**Plans:** TBD
+**UI hint:** yes
+**Research flag:** no
+
+### Phase 7: Meal Planner — Customization & Nutrition
+
+**Goal:** Flesh out the hero feature with per-entry customization (substitutions, excludes, extras, amount overrides, product/pack choice) and the nutrition numbers that close the "am I eating right" loop — all while respecting customizations so the math is honest.
+**Depends on:** Phase 6
+**Requirements:** PLAN-07, PLAN-08, PLAN-09, PLAN-10, PLAN-11, PLAN-13
+**Success Criteria** (what must be TRUE):
+  1. On any meal entry I can substitute an ingredient with one of the catalog-defined alternatives and the change sticks after sync and restart.
+  2. On any meal entry I can exclude an ingredient, add an extra ingredient from the catalog (amount + unit), and override an ingredient's amount — each of these reflects in shopping/pantry calculations later.
+  3. On any meal entry I can select a specific product (pack size) for a given ingredient when multiple exist.
+  4. Each day in the planner shows daily nutrition totals (kcal, protein, fat, carbs) aggregated across all planned meals for that day, recomputed when any customization changes.
+**Plans:** TBD
+**UI hint:** yes
+**Research flag:** no
+
+### Phase 8: Pantry
+
+**Goal:** Give the household a view of what's actually on hand and what's missing, so the plan connects to real life. Reuses the Phase 4 sync foundation on a second household-scoped aggregate.
+**Depends on:** Phase 7
+**Requirements:** PNTR-01, PNTR-02, PNTR-03, PNTR-04, PNTR-05
+**Success Criteria** (what must be TRUE):
+  1. I open "Spiżarnia" and see my pantry inventory grouped by category (pieczywo, nabiał, mięso i ryby, warzywa, owoce, suche, przyprawy, inne).
+  2. I can manually add or update the quantity of any pantry ingredient using its pantry unit (g, ml, szt.), and the change syncs to my partner's device.
+  3. I pick a planning horizon (e.g., "next 7 days") and see which ingredients fall short based on the plan minus current pantry.
+  4. I can filter the pantry view by category and by shortfall status (needed / sufficient / not in plan).
+**Plans:** TBD
+**UI hint:** yes
+**Research flag:** no
+
+### Phase 9: Shopping List & Session Log
+
+**Goal:** Close the loop from plan to store — generate a category-grouped shopping list from a chosen date range, mark items bought during an in-store session, and move bought items into the pantry automatically.
+**Depends on:** Phase 8
+**Requirements:** SHOP-01, SHOP-02, SHOP-03, SHOP-04, SHOP-05, SHOP-06
+**Success Criteria** (what must be TRUE):
+  1. I open "Zakupy", pick a date range from the plan, and see a shopping list aggregating ingredient needs minus current pantry, grouped by category for an efficient store trip.
+  2. During a shopping session I can mark an item bought; it disappears from active needs and shows up in the pantry in its pantry unit.
+  3. I can undo a recently marked-bought item within the same session; the item reappears in active needs.
+  4. I close and reopen the app mid-shopping; my session's bought/unbought state is still there until I explicitly clear it.
+**Plans:** TBD
+**UI hint:** yes
+**Research flag:** no
+
+### Phase 10: UI Chrome & Haze Liquid-Glass Polish
+
+**Goal:** Swap the boring default chrome used in Phases 5–9 for the intended Liquid-Glass-inspired feel — 4-tab bottom nav with independent back stacks, Haze-based blur on tab/nav chrome, iOS-idiomatic safe-area/keyboard/swipe-back behaviors, and a calmer spacing/typography pass across every screen. Measurable against realistic data already present.
+**Depends on:** Phase 9
+**Requirements:** UI-03, UI-04, UI-06, UI-07, UI-09
+**Success Criteria** (what must be TRUE):
+  1. The app has a 4-tab bottom nav (Przepisy / Planer / Spiżarnia / Zakupy); tapping into a recipe detail, switching tabs, and coming back preserves the detail — each tab keeps its own back stack.
+  2. The tab bar and top nav bar use Haze-based translucent blur over content beneath them, consistent in light and dark schemes, and scrolling a full recipe grid on iPhone 11 stays above ~55 fps.
+  3. The app respects iOS safe areas, supports the swipe-back gesture where applicable, and keyboards never cover focused inputs.
+  4. Typography and spacing feel noticeably calmer than the legacy PWA mockup — more whitespace between cards, larger hit targets, readable at arm's length.
+  5. On a fresh install I never see a blank flash on launch, and every main screen (catalog / planner / pantry / shopping) renders a deliberate empty state when there's nothing to show yet.
+**Plans:** TBD
+**UI hint:** yes
+**Research flag:** yes
+
+### Phase 11: Localization & iOS Deployment
+
+**Goal:** Externalize every string into Compose resources with complete Polish copy (correct plural forms), build and deploy the Ktor server image to the homelab alongside Authentik, and get the iOS build into my partner's hands via TestFlight.
+**Depends on:** Phase 10
+**Requirements:** UI-01, UI-02, INFRA-04, INFRA-07
+**Success Criteria** (what must be TRUE):
+  1. Every user-facing string across every screen is resolved through Compose resources — a grep for raw Polish literals inside composables returns only fixture/test data.
+  2. The whole app reads as correctly-grammatical Polish, including plural forms (1 / 2 / 5 / 22 counts all render with the right form) and date/weekday names.
+  3. The Ktor server builds into a Docker image and is running in the homelab reachable over HTTPS with a real (Let's-Encrypt-issued) cert, alongside Authentik.
+  4. My partner installs the iOS app through TestFlight, signs in through Authentik, joins our household via invite, and can plan a meal that I see on my device.
+**Plans:** TBD
+**UI hint:** yes
+**Research flag:** no
+
+## Progress Table
+
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 1. Project Infrastructure & Module Wiring | 0/0 | Not started | - |
+| 2. Authentication Foundation | 0/0 | Not started | - |
+| 3. Households, Membership & Server Data Foundation | 0/0 | Not started | - |
+| 4. Sync Engine Skeleton | 0/0 | Not started | - |
+| 5. Recipe Catalog (Read Path) | 0/0 | Not started | - |
+| 6. Meal Planner — Core Write Path | 0/0 | Not started | - |
+| 7. Meal Planner — Customization & Nutrition | 0/0 | Not started | - |
+| 8. Pantry | 0/0 | Not started | - |
+| 9. Shopping List & Session Log | 0/0 | Not started | - |
+| 10. UI Chrome & Haze Liquid-Glass Polish | 0/0 | Not started | - |
+| 11. Localization & iOS Deployment | 0/0 | Not started | - |
+
+## Coverage Summary
+
+- **v1 requirements total:** 72 (AUTH=6, HSHD=7, RCPE=8, PLAN=14, PNTR=5, SHOP=6, SYNC=10, UI=9, INFRA=7)
+- **Mapped to phases:** 72
+- **Unmapped:** 0
+- **Coverage:** 100%
+
+---
+*Roadmap created: 2026-04-23*
+*Granularity: fine (11 phases) | Mode: yolo*

.planning/STATE.md

@@ -0,0 +1,75 @@
+---
+gsd_state_version: 1.0
+milestone: v1.0
+milestone_name: milestone
+current_plan: 1
+status: executing
+last_updated: "2026-04-24T17:39:22.205Z"
+progress:
+  total_phases: 11
+  completed_phases: 0
+  total_plans: 7
+  completed_plans: 4
+  percent: 57
+---
+
+# Project State: Recipe
+
+**Project reference:** `.planning/PROJECT.md`
+**Roadmap:** `.planning/ROADMAP.md`
+**Requirements:** `.planning/REQUIREMENTS.md`
+
+## Core Value
+
+"My week is planned." I pick recipes, the calendar fills up, and I know what we're eating. Everything else — pantry tracking, shopping list, nutrition numbers — exists to reinforce that one moment.
+
+## Current Position
+
+Phase: --phase (01) — EXECUTING
+Plan: 1 of --name
+**Current focus:** Phase --phase — 01
+**Current plan:** 1
+**Status:** Executing Phase --phase
+**Phase progress:** 0 / 11 phases complete
+**Progress bar:** `░░░░░░░░░░░░░░░░░░░░` 0%
+
+## Performance Metrics
+
+| Metric | Value |
+|--------|-------|
+| Phases planned | 11 |
+| v1 requirements | 72 |
+| Coverage | 100% |
+| Phases complete | 0 |
+| Plans complete | 0 |
+
+## Accumulated Context
+
+### Decisions carried in
+
+All locked tech-stack decisions are captured in `.planning/PROJECT.md § Key Decisions`. Architectural patterns are in `.planning/research/ARCHITECTURE.md`. High-risk pitfalls by phase are in `.planning/research/PITFALLS.md`. Do not re-relitigate locked decisions during phase planning.
+
+### Open todos
+
+- None yet — first action is `/gsd-plan-phase 1`.
+
+### Blockers
+
+- None.
+
+## Session Continuity
+
+**Last session:** --stopped-at
+
+**Next action:** `/gsd-plan-phase 1` — decompose Phase 1 (Project Infrastructure & Module Wiring) into plans.
+
+**Research flags to revisit during phase planning:**
+
+- Phase 2 (Auth): Authentik-specific OIDC setup; iOS OIDC wrapper library choice; token refresh behavior.
+- Phase 4 (SyncEngine): concrete cursor format, outbox schema ordering guarantees, retry/backoff policy.
+- Phase 10 (UI chrome): current Haze CMP-iOS perf on iPhone 11/12-era hardware; liquid-glass approximation patterns.
+
+---
+*Last updated: 2026-04-23*
+
+**Planned Phase:** 1 (Project Infrastructure & Module Wiring) — 7 plans — 2026-04-24T16:07:36.289Z

.planning/config.json

@@ -0,0 +1,42 @@
+{
+  "model_profile": "quality",
+  "commit_docs": true,
+  "parallelization": true,
+  "search_gitignored": false,
+  "brave_search": false,
+  "firecrawl": false,
+  "exa_search": false,
+  "git": {
+    "branching_strategy": "none",
+    "phase_branch_template": "gsd/phase-{phase}-{slug}",
+    "milestone_branch_template": "gsd/{milestone}-{slug}",
+    "quick_branch_template": null
+  },
+  "workflow": {
+    "research": true,
+    "plan_check": true,
+    "verifier": true,
+    "nyquist_validation": true,
+    "auto_advance": false,
+    "node_repair": true,
+    "node_repair_budget": 2,
+    "ui_phase": true,
+    "ui_safety_gate": true,
+    "text_mode": false,
+    "research_before_questions": false,
+    "discuss_mode": "discuss",
+    "skip_discuss": false,
+    "code_review": true,
+    "code_review_depth": "standard",
+    "_auto_chain_active": false
+  },
+  "hooks": {
+    "context_warnings": true
+  },
+  "project_code": null,
+  "phase_naming": "sequential",
+  "agent_skills": {},
+  "features": {},
+  "mode": "yolo",
+  "granularity": "fine"
+}

.planning/phases/01-project-infrastructure-module-wiring/01-01-PLAN.md

@@ -0,0 +1,342 @@
+---
+phase: 01-project-infrastructure-module-wiring
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - gradle/libs.versions.toml
+  - gradle.properties
+  - tools/verify-no-version-literals.sh
+  - tools/verify-shared-pure.sh
+  - tools/verify-ios-flags.sh
+autonomous: true
+requirements: [INFRA-01, INFRA-03]
+requirements_addressed: [INFRA-01, INFRA-03]
+
+must_haves:
+  truths:
+    - "gradle/libs.versions.toml is the sole source of library/plugin versions (D-09 / INFRA-01 SC#2)"
+    - "iOS K/N binary flags kotlin.native.binary.gc=cms and kotlin.native.binary.objcDisposeOnMain=false are set in gradle.properties (D-18 / INFRA-03)"
+    - "Shell-based invariant checks (no-version-literals, shared-pure, ios-flags) are executable and fail-loud"
+  artifacts:
+    - path: "gradle/libs.versions.toml"
+      provides: "Version + library + plugin aliases for Koin, Kermit, Spotless, Flyway, PostgreSQL JDBC, Ktor content-negotiation, Ktor JSON serializer"
+      contains: "koin = ", "kermit = ", "spotless = ", "flyway = ", "postgresql ="
+    - path: "gradle.properties"
+      provides: "iOS K/N binary flags"
+      contains: "kotlin.native.binary.gc=cms", "kotlin.native.binary.objcDisposeOnMain=false"
+    - path: "tools/verify-no-version-literals.sh"
+      provides: "Invariant check — no numeric version literals outside catalog in any *.gradle.kts (except build-logic/build.gradle.kts bootstrap coordinates)"
+    - path: "tools/verify-shared-pure.sh"
+      provides: "Invariant check — shared/src/commonMain must not import Ktor / Compose / SQLDelight"
+    - path: "tools/verify-ios-flags.sh"
+      provides: "Invariant check — both iOS K/N flags present in gradle.properties"
+  key_links:
+    - from: "build-logic/ (Plan 02)"
+      to: "gradle/libs.versions.toml"
+      via: "VersionCatalogsExtension.named(\"libs\").findLibrary(...) inside precompiled plugins"
+      pattern: "findLibrary\\(\"koin-core\"\\)"
+    - from: "gradle.properties"
+      to: ":composeApp:linkDebugFrameworkIosSimulatorArm64"
+      via: "Kotlin/Native compiler reads project properties at link time"
+      pattern: "kotlin\\.native\\.binary\\."
+---
+
+<objective>
+Extend the Gradle version catalog with every new alias required by Phase 1 (Koin, Kermit, Spotless, Flyway, Postgres JDBC, ktor-serverContentNegotiation, ktor-serializationKotlinxJson), append the two mandatory iOS Kotlin/Native binary flags to `gradle.properties`, and ship three shell-based invariant scripts under `tools/` that Plan 07 will use as phase-gate checks.
+
+Purpose: This plan creates the **foundation** on which every other Phase 1 plan rests. Without these catalog entries, `build-logic/` (Plan 02) cannot resolve `findLibrary("koin-core")`; without the iOS flags, INFRA-03 fails silently. The verification scripts are required by 01-VALIDATION.md Wave 0 — every subsequent plan's `<automated>` block calls one of them.
+
+Output: An extended `gradle/libs.versions.toml` (additive only, no version bumps to existing entries), extended `gradle.properties` with exactly two new lines, and three executable `.sh` scripts under a new `tools/` directory.
+</objective>
+
+<execution_context>
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/REQUIREMENTS.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-CONTEXT.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-PATTERNS.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-VALIDATION.md
+@gradle/libs.versions.toml
+@gradle.properties
+@CLAUDE.md
+
+<interfaces>
+<!-- Existing catalog aliases (do NOT rename or remove — only add new entries alongside) -->
+
+From gradle/libs.versions.toml (current state, to extend):
+```toml
+[versions]
+kotlin = "2.3.20"
+ktor = "3.4.1"
+composeMultiplatform = "1.10.3"
+# (plus agp, androidx-*, composeHotReload, junit, kotlinx-coroutines, logback, material3)
+
+[libraries]
+# Existing: kotlin-test, kotlin-testJunit, junit, androidx-*, compose-*, kotlinx-coroutinesSwing,
+#           logback, ktor-serverCore, ktor-serverNetty, ktor-serverTestHost
+
+[plugins]
+# Existing: androidApplication, androidLibrary, composeHotReload, composeMultiplatform,
+#           composeCompiler, kotlinJvm, ktor, kotlinMultiplatform
+```
+
+From gradle.properties (current state — 10 lines of Kotlin + Gradle + Android config):
+```properties
+kotlin.code.style=official
+kotlin.daemon.jvmargs=-Xmx3072M
+org.gradle.jvmargs=-Xmx4096M -Dfile.encoding=UTF-8
+org.gradle.configuration-cache=true
+org.gradle.caching=true
+android.nonTransitiveRClass=true
+android.useAndroidX=true
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Extend gradle/libs.versions.toml with Phase 1 aliases</name>
+  <files>gradle/libs.versions.toml</files>
+  <read_first>
+    - gradle/libs.versions.toml (see current state of versions/libraries/plugins tables)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md lines 110-175 (§ Standard Stack + Installation TOML fragments)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-PATTERNS.md lines 446-490 (delta blocks for [versions] / [libraries] / [plugins])
+    - .planning/phases/01-project-infrastructure-module-wiring/01-CONTEXT.md D-09 (catalog-only hard rule), D-14 (Koin deps needed), D-15 (Kermit), D-10 (Spotless), D-16 (Flyway + Postgres + content-negotiation)
+  </read_first>
+  <action>
+  Extend `gradle/libs.versions.toml` with the new aliases for Phase 1. Preserve every existing entry verbatim (do NOT rename, remove, or bump any existing version).
+
+  Append the following to `[versions]`, in the existing alphabetical-ish order:
+
+  ```toml
+  flyway = "12.4.0"
+  kermit = "2.1.0"
+  koin = "4.2.1"
+  kotlinx-serialization = "1.7.3"
+  postgresql = "42.7.10"
+  spotless = "8.4.0"
+  ```
+
+  Append the following to `[libraries]`:
+
+  ```toml
+  # Koin (client DI — D-14)
+  koin-bom = { module = "io.insert-koin:koin-bom", version.ref = "koin" }
+  koin-core = { module = "io.insert-koin:koin-core" }
+  koin-compose = { module = "io.insert-koin:koin-compose" }
+  koin-composeViewmodel = { module = "io.insert-koin:koin-compose-viewmodel" }
+  koin-android = { module = "io.insert-koin:koin-android" }
+
+  # Kermit (client logger — D-15)
+  kermit = { module = "co.touchlab:kermit", version.ref = "kermit" }
+
+  # Server: Ktor content-negotiation + JSON serializer + Flyway + Postgres (D-16)
+  ktor-serverContentNegotiation = { module = "io.ktor:ktor-server-content-negotiation-jvm", version.ref = "ktor" }
+  ktor-serializationKotlinxJson = { module = "io.ktor:ktor-serialization-kotlinx-json-jvm", version.ref = "ktor" }
+  flyway-core = { module = "org.flywaydb:flyway-core", version.ref = "flyway" }
+  flyway-database-postgresql = { module = "org.flywaydb:flyway-database-postgresql", version.ref = "flyway" }
+  postgresql = { module = "org.postgresql:postgresql", version.ref = "postgresql" }
+  ```
+
+  Append the following to `[plugins]`:
+
+  ```toml
+  spotless = { id = "com.diffplug.spotless", version.ref = "spotless" }
+  flywayPlugin = { id = "org.flywaydb.flyway", version.ref = "flyway" }
+  ```
+
+  IMPORTANT invariants:
+  - `koin-core`, `koin-compose`, `koin-compose-viewmodel`, `koin-android` have NO `version.ref` — they are BOM-managed by `koin-bom`.
+  - `kotlin-test` is already in the catalog (line 22) — do NOT re-add.
+  - Do NOT bump any existing version alias (kotlin, ktor, composeMultiplatform, logback, etc.).
+  - The `koin-composeViewmodel` alias name uses camelCase (Gradle converts dashes-to-dots for accessors, but camelCase preserves `koin.composeViewmodel.get()`).
+  </action>
+  <verify>
+    <automated>grep -E '^(flyway|kermit|koin|kotlinx-serialization|postgresql|spotless)\s*=' gradle/libs.versions.toml | wc -l | grep -q '^6$' && grep -E '^koin-bom\s*=' gradle/libs.versions.toml && grep -E '^koin-core\s*=' gradle/libs.versions.toml && grep -E '^koin-compose\s*=' gradle/libs.versions.toml && grep -E '^koin-composeViewmodel\s*=' gradle/libs.versions.toml && grep -E '^koin-android\s*=' gradle/libs.versions.toml && grep -E '^kermit\s*=' gradle/libs.versions.toml && grep -E '^ktor-serverContentNegotiation\s*=' gradle/libs.versions.toml && grep -E '^ktor-serializationKotlinxJson\s*=' gradle/libs.versions.toml && grep -E '^flyway-core\s*=' gradle/libs.versions.toml && grep -E '^flyway-database-postgresql\s*=' gradle/libs.versions.toml && grep -E '^postgresql\s*=' gradle/libs.versions.toml && grep -E '^spotless\s*=\s*\{\s*id\s*=' gradle/libs.versions.toml && grep -E '^flywayPlugin\s*=\s*\{\s*id\s*=' gradle/libs.versions.toml</automated>
+  </verify>
+  <acceptance_criteria>
+    - `grep -E '^kotlin\s*=\s*"2\.3\.20"' gradle/libs.versions.toml` returns exactly 1 line (existing, unmodified)
+    - `grep -E '^ktor\s*=\s*"3\.4\.1"' gradle/libs.versions.toml` returns exactly 1 line (existing, unmodified)
+    - `grep -E '^koin\s*=\s*"4\.2\.1"' gradle/libs.versions.toml` returns exactly 1 line (new)
+    - `grep -E '^kermit\s*=\s*"2\.1\.0"' gradle/libs.versions.toml` returns exactly 1 line (new)
+    - `grep -E '^spotless\s*=\s*"8\.4\.0"' gradle/libs.versions.toml` returns exactly 1 line (new)
+    - `grep -E '^flyway\s*=\s*"12\.4\.0"' gradle/libs.versions.toml` returns exactly 1 line (new)
+    - `grep -E '^postgresql\s*=\s*"42\.7\.10"' gradle/libs.versions.toml` returns exactly 1 line (new)
+    - `grep -c '^koin-' gradle/libs.versions.toml` returns `5` (koin-bom, koin-core, koin-compose, koin-composeViewmodel, koin-android)
+    - `grep -c '^flyway-' gradle/libs.versions.toml` returns `2` (flyway-core, flyway-database-postgresql)
+    - `grep -E '^\s*module\s*=\s*"io.insert-koin:koin-core"' gradle/libs.versions.toml` returns 1 line with NO `version.ref` attribute on same line (BOM-managed)
+  </acceptance_criteria>
+  <done>All Phase 1 catalog aliases present; no existing aliases modified; file parses as valid TOML.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Append iOS K/N binary flags to gradle.properties</name>
+  <files>gradle.properties</files>
+  <read_first>
+    - gradle.properties (see current 10-line content)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md lines 1082-1107 (§ `gradle.properties` — iOS binary flags — exact content to append)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-CONTEXT.md D-18 (INFRA-03, PITFALL #1)
+    - CLAUDE.md convention #7 (iOS binary flags on day 1)
+  </read_first>
+  <action>
+  Append the following 5 lines to `gradle.properties` exactly as shown (including the blank separator line and both comment lines). Do NOT modify any existing line:
+
+  ```properties
+
+  # Kotlin/Native iOS (PITFALLS.md #1; D-18; INFRA-03) — MANDATORY day 1
+  # CMS GC + non-main-thread Obj-C deinit to avoid UI-thread pause spikes in Compose Multiplatform.
+  kotlin.native.binary.gc=cms
+  kotlin.native.binary.objcDisposeOnMain=false
+  ```
+
+  IMPORTANT:
+  - Place AT THE END of the file (append). The existing `android.useAndroidX=true` stays as the last non-iOS line.
+  - Use EXACTLY the property keys `kotlin.native.binary.gc` and `kotlin.native.binary.objcDisposeOnMain`. Do not add quotes, spaces, or alternate spellings (the K/N compiler reads these keys literally).
+  - Value `cms` is lowercase. Value `false` is lowercase.
+  </action>
+  <verify>
+    <automated>grep -E '^kotlin\.native\.binary\.gc=cms$' gradle.properties | wc -l | grep -q '^1$' && grep -E '^kotlin\.native\.binary\.objcDisposeOnMain=false$' gradle.properties | wc -l | grep -q '^1$'</automated>
+  </verify>
+  <acceptance_criteria>
+    - `grep -cE '^kotlin\.native\.binary\.gc=cms$' gradle.properties` returns `1`
+    - `grep -cE '^kotlin\.native\.binary\.objcDisposeOnMain=false$' gradle.properties` returns `1`
+    - `grep -c '^kotlin\.code\.style=official$' gradle.properties` returns `1` (unmodified existing)
+    - `grep -c '^android\.useAndroidX=true$' gradle.properties` returns `1` (unmodified existing)
+    - No duplicate of either flag (run grep twice — expect `1` each time, not `2`)
+  </acceptance_criteria>
+  <done>Both iOS K/N flags present once; original 10 lines unchanged.</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Create verify-*.sh invariant scripts under tools/</name>
+  <files>tools/verify-no-version-literals.sh, tools/verify-shared-pure.sh, tools/verify-ios-flags.sh</files>
+  <read_first>
+    - .planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md lines 1174-1218 (§ tools/verify-*.sh — canonical shell sketches)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-PATTERNS.md lines 1174-1218 (same scripts, same content — Pattern Map confirms no in-repo analog)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-VALIDATION.md lines 62-79 (Wave 0 Requirements — these three scripts gate every task's `<automated>` check)
+  </read_first>
+  <action>
+  Create the three executable bash scripts under `tools/` (create the directory — it does not exist yet). Each must be marked executable (`chmod +x`).
+
+  **File 1: `tools/verify-no-version-literals.sh`** (enforces D-09 / INFRA-01 SC#2):
+
+  ```sh
+  #!/usr/bin/env bash
+  # Enforces INFRA-01 SC#2 / D-09: no literal version strings outside catalog.
+  # Scans every *.gradle.kts for numeric version literals (e.g. version = "1.2.3"),
+  # excluding build-logic/build.gradle.kts which needs literal asDependency() coordinates.
+  set -euo pipefail
+  VIOLATIONS=$(grep -rn -E 'version[[:space:]]*=[[:space:]]*"[0-9]' --include='*.gradle.kts' . 2>/dev/null | grep -v 'build-logic/build.gradle.kts' || true)
+  if [ -n "$VIOLATIONS" ]; then
+      echo "ERROR: version literals found outside catalog:" >&2
+      echo "$VIOLATIONS" >&2
+      exit 1
+  fi
+  echo "OK: no version literals outside catalog."
+  ```
+
+  **File 2: `tools/verify-shared-pure.sh`** (enforces INFRA-06 / D-19):
+
+  ```sh
+  #!/usr/bin/env bash
+  # Enforces INFRA-06 / D-19: shared/commonMain must not import Ktor, Compose, SQLDelight.
+  # Runs grep against shared/src/commonMain/ only. Allowed imports: kotlin.*, kotlinx.serialization, kotlinx.datetime.
+  set -euo pipefail
+  if [ ! -d shared/src/commonMain ]; then
+      echo "OK: shared/src/commonMain does not exist yet (pre-scaffold)."
+      exit 0
+  fi
+  VIOLATIONS=$(grep -rn -E '^import[[:space:]]+(io\.ktor|androidx\.compose|org\.jetbrains\.compose|app\.cash\.sqldelight)' shared/src/commonMain/ 2>/dev/null || true)
+  if [ -n "$VIOLATIONS" ]; then
+      echo "ERROR: shared/commonMain has forbidden imports:" >&2
+      echo "$VIOLATIONS" >&2
+      exit 1
+  fi
+  echo "OK: shared/commonMain is pure."
+  ```
+
+  **File 3: `tools/verify-ios-flags.sh`** (enforces INFRA-03 / D-18):
+
+  ```sh
+  #!/usr/bin/env bash
+  # Enforces INFRA-03 / D-18: iOS K/N flags present in gradle.properties.
+  set -euo pipefail
+  grep -q '^kotlin\.native\.binary\.gc=cms$' gradle.properties || { echo "MISSING: kotlin.native.binary.gc=cms" >&2; exit 1; }
+  grep -q '^kotlin\.native\.binary\.objcDisposeOnMain=false$' gradle.properties || { echo "MISSING: kotlin.native.binary.objcDisposeOnMain=false" >&2; exit 1; }
+  echo "OK: iOS binary flags present."
+  ```
+
+  After writing all three files, run: `chmod +x tools/verify-no-version-literals.sh tools/verify-shared-pure.sh tools/verify-ios-flags.sh`.
+
+  IMPORTANT:
+  - Use `#!/usr/bin/env bash` (not `#!/bin/sh`) — `set -euo pipefail` requires bash semantics.
+  - `tools/verify-shared-pure.sh` deliberately returns 0 if `shared/src/commonMain` does not exist (pre-scaffold state). This lets Plan 07 run the script before Plan 07 itself creates the scaffold.
+  - `tools/verify-no-version-literals.sh` excludes `build-logic/build.gradle.kts` (its `asDependency()` trick requires literal plugin version coordinates — D-09 acknowledged exception).
+  </action>
+  <verify>
+    <automated>test -x tools/verify-no-version-literals.sh && test -x tools/verify-shared-pure.sh && test -x tools/verify-ios-flags.sh && bash tools/verify-ios-flags.sh && bash tools/verify-shared-pure.sh && bash tools/verify-no-version-literals.sh</automated>
+  </verify>
+  <acceptance_criteria>
+    - `test -f tools/verify-no-version-literals.sh && test -x tools/verify-no-version-literals.sh` succeeds
+    - `test -f tools/verify-shared-pure.sh && test -x tools/verify-shared-pure.sh` succeeds
+    - `test -f tools/verify-ios-flags.sh && test -x tools/verify-ios-flags.sh` succeeds
+    - `bash tools/verify-ios-flags.sh` exits 0 and prints `OK: iOS binary flags present.` (proves Task 2 wrote flags)
+    - `bash tools/verify-shared-pure.sh` exits 0 (current `shared/src/commonMain/kotlin/dev/ulfrx/recipe/` has only Greeting.kt/Platform.kt/Constants.kt — no ktor/compose imports)
+    - `bash tools/verify-no-version-literals.sh` exits 0 (current *.gradle.kts files use `libs.plugins.*` aliases — no literal versions)
+    - Each script has `#!/usr/bin/env bash` as line 1
+    - Each script uses `set -euo pipefail`
+  </acceptance_criteria>
+  <done>Three executable verification scripts exist, each runs green against the current repo state.</done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| developer → Gradle build | Local-only; Gradle reads `libs.versions.toml` + `gradle.properties` verbatim. No untrusted input. |
+| Gradle → Maven Central + Gradle Plugin Portal | Existing repository declarations in `settings.gradle.kts` (Plan 03 doesn't change them). Pinned versions via catalog reduce supply-chain drift. |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-01-01-01 | Tampering (supply chain) | `gradle/libs.versions.toml` new entries | mitigate | All new version refs are pinned to specific stable releases (`koin = "4.2.1"`, `kermit = "2.1.0"`, `flyway = "12.4.0"`, `spotless = "8.4.0"`, `postgresql = "42.7.10"`) — no version ranges, no `latest.release`. Gradle verifies SHA-256 via `gradle/verification-metadata.xml` if enabled in later phases. |
+| T-01-01-02 | Tampering | `tools/*.sh` scripts | accept | Scripts live in repo and run locally; their only effect is exit 0/1. Read `gradle.properties` and `*.gradle.kts` only — no network I/O, no write. Risk = low. |
+| T-01-01-03 | Information Disclosure | `gradle.properties` iOS flags | accept | Flag values (`cms`, `false`) are build configuration, not secrets. Public in every iOS KMP tutorial. |
+| T-01-01-04 | Denial of Service | wrong catalog syntax breaks build | mitigate | Task 1 `<acceptance_criteria>` greps for exact alias presence; Wave 2 plans that consume the catalog will fail fast if an alias is misspelled. |
+</threat_model>
+
+<verification>
+Phase-level verification for this plan:
+- All three `tools/verify-*.sh` scripts run green against the post-plan repo.
+- `gradle/libs.versions.toml` parses (Gradle will surface a TOML parse error at next `./gradlew` invocation in Plan 02).
+- `gradle.properties` has exactly two new iOS K/N flag lines and is otherwise byte-identical to its pre-plan content.
+
+No Gradle build is expected to run fully in this plan — we have not yet scaffolded `build-logic/` (Plan 02) nor refactored modules (Plan 03), so `./gradlew build` would fail to resolve the new library aliases. Catalog additions ARE safe for Gradle configuration though (unused entries are inert).
+</verification>
+
+<success_criteria>
+- `tools/verify-ios-flags.sh` exits 0
+- `tools/verify-no-version-literals.sh` exits 0
+- `tools/verify-shared-pure.sh` exits 0
+- Catalog contains 6 new `[versions]` keys (flyway, kermit, koin, kotlinx-serialization, postgresql, spotless)
+- Catalog contains 10 new `[libraries]` entries (5 koin-*, kermit, 2 ktor-*, 2 flyway-*, postgresql)
+- Catalog contains 2 new `[plugins]` entries (spotless, flywayPlugin)
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/01-project-infrastructure-module-wiring/01-01-SUMMARY.md` recording: catalog entries added (count), gradle.properties append location, shell-script paths, and any deviation from the planned version pins (if Maven Central shows a newer stable, record the downgrade decision).
+</output>

.planning/phases/01-project-infrastructure-module-wiring/01-01-SUMMARY.md

@@ -0,0 +1,154 @@
+---
+phase: 01-project-infrastructure-module-wiring
+plan: 01
+subsystem: infra
+tags: [gradle, version-catalog, kotlin-native, ios-binary-flags, bash, invariants, koin, kermit, flyway, postgresql, spotless, ktor]
+
+# Dependency graph
+requires: []
+provides:
+  - Gradle version catalog extended with Koin (BOM + core/compose/composeViewmodel/android), Kermit, Spotless, Flyway (core + postgresql), Postgres JDBC, Ktor content-negotiation + kotlinx-json serializer
+  - kotlinx-serialization = 1.7.3 version alias (kept even though no library wires it in Plan 01 — Phase 2+ wire Ktor plugins using this pin)
+  - iOS K/N binary flags kotlin.native.binary.gc=cms + kotlin.native.binary.objcDisposeOnMain=false in gradle.properties
+  - tools/verify-no-version-literals.sh (D-09 invariant check)
+  - tools/verify-shared-pure.sh (INFRA-06 / D-19 invariant check — tolerant of pre-scaffold shared/commonMain)
+  - tools/verify-ios-flags.sh (INFRA-03 / D-18 invariant check)
+affects: [01-02-build-logic, 01-03-module-wiring, 01-04-compose-app, 01-05-server, 01-06-shared, 01-07-validation, 02-auth, 10-ui-chrome, 11-localization-deployment]
+
+# Tech tracking
+tech-stack:
+  added:
+    - Koin 4.2.1 (BOM + 4 consumed modules)
+    - Kermit 2.1.0
+    - Spotless 8.4.0 (plugin)
+    - Flyway 12.4.0 (core + database-postgresql module + Gradle plugin)
+    - PostgreSQL JDBC 42.7.10
+    - Ktor server content-negotiation + kotlinx-json serializer (version.ref = existing ktor 3.4.1)
+    - kotlinx-serialization = 1.7.3 version alias (no library entry yet — pre-wire for ktor serializer which derives its version from ktor)
+  patterns:
+    - "Catalog-only versioning: no numeric version literals in *.gradle.kts outside build-logic/ (D-09 / INFRA-01 SC#2)"
+    - "BOM-managed Koin libs omit version.ref (koin-core/koin-compose/koin-composeViewmodel/koin-android pinned via koin-bom)"
+    - "Fail-loud shell invariants under tools/ — every Phase 1 plan's <automated> block calls one of these three scripts"
+
+key-files:
+  created:
+    - tools/verify-no-version-literals.sh
+    - tools/verify-shared-pure.sh
+    - tools/verify-ios-flags.sh
+  modified:
+    - gradle/libs.versions.toml
+    - gradle.properties
+
+key-decisions:
+  - "Refined verify-no-version-literals.sh to exclude top-level project-version assignments (^version = \"x.y.z\") — these are Gradle artifact metadata, not library-version pins. D-09 guards dependencies, not project identity. server/build.gradle.kts:8 keeps its project version."
+
+patterns-established:
+  - "Pattern 1: All Phase 1+ library/plugin versions declared ONLY in gradle/libs.versions.toml; build scripts reference via libs.* accessors"
+  - "Pattern 2: iOS Kotlin/Native binary flags live in gradle.properties — single file, compiler reads verbatim at link time"
+  - "Pattern 3: Invariant checks as bash scripts under tools/; shebang #!/usr/bin/env bash; set -euo pipefail; fail-loud on violation, silent-pass on clean"
+  - "Pattern 4: Pre-scaffold tolerance — verify-shared-pure.sh exits 0 if shared/src/commonMain doesn't exist (lets invariant scripts run before Plan 07 scaffolds)"
+
+requirements-completed: [INFRA-01, INFRA-03]
+
+# Metrics
+duration: 4min
+completed: 2026-04-24
+---
+
+# Phase 01 Plan 01: Foundations Summary
+
+**Gradle version catalog extended with 6 versions / 11 libraries / 2 plugins (Koin + Kermit + Spotless + Flyway + Postgres + Ktor content-negotiation), iOS K/N binary flags (gc=cms + objcDisposeOnMain=false) added to gradle.properties, and three tools/verify-*.sh invariant scripts shipped — the foundation every remaining Phase 1 plan leans on.**
+
+## Performance
+
+- **Duration:** 4 min
+- **Started:** 2026-04-24T16:12:45Z
+- **Completed:** 2026-04-24T16:16:53Z
+- **Tasks:** 3
+- **Files modified:** 2 (catalog + gradle.properties)
+- **Files created:** 3 (tools/verify-*.sh)
+
+## Accomplishments
+
+- **Version catalog now covers every Phase 1+ library and plugin**, including BOM-managed Koin modules (omitting `version.ref` by design) and fine-grained Ktor server-side JSON plumbing. No existing version ref was bumped; additive-only per D-09.
+- **iOS K/N binary flags wired on day 1** (gc=cms + objcDisposeOnMain=false), closing PITFALL #1 before any iOS framework is linked.
+- **Three invariant scripts ship green** — `verify-ios-flags.sh`, `verify-shared-pure.sh`, `verify-no-version-literals.sh` — exit 0 against current repo state, ready to gate every subsequent plan's automated checks.
+
+## Task Commits
+
+Each task committed atomically on this worktree branch:
+
+1. **Task 1: Extend gradle/libs.versions.toml with Phase 1 aliases** — `b609cb6` (feat)
+2. **Task 2: Append iOS K/N binary flags to gradle.properties** — `d873c31` (feat)
+3. **Task 3: Create verify-*.sh invariant scripts under tools/** — `aaa8042` (feat)
+
+_No TDD for this plan — all tasks are config/scaffold, not behavior._
+
+## Files Created/Modified
+
+### Created
+- `tools/verify-no-version-literals.sh` — Grep `*.gradle.kts` for `version = "[0-9]..."`; skip `build-logic/build.gradle.kts` (legitimate plugin-dep literals) and top-level project-version assignments (artifact metadata, not library pins).
+- `tools/verify-shared-pure.sh` — Grep `shared/src/commonMain/` for imports from `io.ktor`, `androidx.compose`, `org.jetbrains.compose`, `app.cash.sqldelight`. Exits 0 if the directory doesn't exist yet (Plan 07 hasn't scaffolded it).
+- `tools/verify-ios-flags.sh` — Grep `gradle.properties` for both K/N flags; fail with a clear MISSING: line if either absent.
+
+### Modified
+- `gradle/libs.versions.toml` — +6 versions (flyway, kermit, koin, kotlinx-serialization, postgresql, spotless); +11 libraries (5 koin-*, kermit, 2 ktor-server-*, 2 flyway-*, postgresql); +2 plugins (spotless, flywayPlugin). 24 / 33 / 10 totals after edit.
+- `gradle.properties` — +5 lines (blank separator + comment + comment + 2 K/N flags) appended after existing Android block. Original 10 lines unchanged.
+
+## Decisions Made
+
+- **Refined verify-no-version-literals.sh script semantics** — The plan's canonical script (from 01-RESEARCH.md lines 1174–1218 and 01-PATTERNS.md lines 446–490) excluded only `build-logic/build.gradle.kts`. Running it against the current repo tripped on `server/build.gradle.kts:8: version = "1.0.0"` — the Ktor template's project-version property. Per D-09, the invariant targets **library/plugin** version literals, not project/artifact metadata. I added a second, narrow exclusion: lines where the matched `version = "..."` begins at column 0 (unindented project-version assignments). Library and plugin version literals always appear inside a `dependencies { }` or `plugins { }` block and are therefore indented, so they remain caught. Sanity-check: the script still flags a synthetic `dependencies { implementation("x:y") { version = "9.9.9" } }` as a violation.
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Refined verify-no-version-literals.sh to not fire on project-version metadata**
+- **Found during:** Task 3 (running the script for the first time)
+- **Issue:** The canonical script in the plan (quoted verbatim from 01-RESEARCH.md) exit-1'd on `server/build.gradle.kts:8: version = "1.0.0"`. That line is the Gradle project-version property (artifact name metadata), not a library-version pin. The plan's acceptance criterion ("`bash tools/verify-no-version-literals.sh` exits 0 today") cannot be satisfied without either removing the project version or refining the script. D-09 (CONTEXT.md line 32) says the rule is "no library versions outside catalog" — project version is out of scope for D-09.
+- **Fix:** Added a second `grep -v` to exclude lines matching `:[0-9]+:version[[:space:]]*=[[:space:]]*"[0-9]` (unindented top-level project-version). Library/plugin version literals in Gradle DSL are always indented inside a block, so they remain caught. Updated the script's header comment to document the refinement rationale.
+- **Files modified:** `tools/verify-no-version-literals.sh`
+- **Verification:** Script exits 0 against current repo state; synthetic indented `version = "9.9.9"` test case still trips the script with exit 1. Both conditions tested.
+- **Committed in:** `aaa8042` (Task 3 commit — the refined script is the only shipped version; no redundant fix-up commit).
+
+---
+
+**Total deviations:** 1 auto-fixed (Rule 3 — blocking)
+**Impact on plan:** Minimal. The refinement strengthens the script's semantic correctness (targets library/plugin pins, not project identity). Success criteria and all acceptance criteria still pass. No additional tasks; no scope creep.
+
+## Issues Encountered
+
+- **Initial worktree base mismatch** — Worktree branch HEAD was `0ca22f9e` (a later commit in the worktree's own history), not the expected `875055a` base. The `<worktree_branch_check>` guard caught it and reset to `875055a` before any work. All three task commits therefore sit cleanly on the required base.
+- **Planner arithmetic off-by-one** — Plan success criteria say "10 new [libraries] entries"; the plan's own enumeration lists 11 (5 koin + kermit + 2 ktor + 2 flyway + postgresql). I shipped all 11 explicitly named entries. This is a planner-side typo, not a deviation.
+
+## User Setup Required
+
+None. This plan is pure build configuration — no secrets, no external services, no dashboard config.
+
+## Next Phase Readiness
+
+- **Plan 02 (build-logic/) unblocked** — `VersionCatalogsExtension.named("libs").findLibrary("koin-core")` etc. will resolve in precompiled plugins; every alias the downstream plans need is now present.
+- **Plan 03+ module build files unblocked** — modules can reference `libs.koin.core`, `libs.kermit`, `libs.ktor.serverContentNegotiation`, `libs.flyway.core`, `libs.flyway.database.postgresql`, `libs.postgresql` via type-safe accessors.
+- **Plan 07 (validation) unblocked** — the three `tools/verify-*.sh` scripts are the Wave 0 gate it enumerates.
+- **No blockers.** `./gradlew build` is NOT expected to pass until Plan 02 wires up `build-logic/` and Plan 03 refactors module build scripts — that's by design and stated in this plan's `<verification>` block.
+
+## Self-Check: PASSED
+
+Verification of claims in this summary:
+
+**Created files exist:**
+- `tools/verify-no-version-literals.sh` — FOUND + executable
+- `tools/verify-shared-pure.sh` — FOUND + executable
+- `tools/verify-ios-flags.sh` — FOUND + executable
+
+**Commits exist in branch history:**
+- `b609cb6` — FOUND (feat(01-01): extend version catalog with Phase 1 aliases)
+- `d873c31` — FOUND (feat(01-01): add iOS Kotlin/Native binary flags to gradle.properties)
+- `aaa8042` — FOUND (feat(01-01): add Phase 1 invariant verification scripts)
+
+**All three invariant scripts exit 0 against the current repo state.** All success criteria from the plan pass.
+
+---
+
+*Phase: 01-project-infrastructure-module-wiring*
+*Completed: 2026-04-24*

.planning/phases/01-project-infrastructure-module-wiring/01-02-PLAN.md

@@ -0,0 +1,587 @@
+---
+phase: 01-project-infrastructure-module-wiring
+plan: 02
+type: execute
+wave: 2
+depends_on: [01]
+files_modified:
+  - build-logic/settings.gradle.kts
+  - build-logic/build.gradle.kts
+  - build-logic/src/main/kotlin/recipe.quality.gradle.kts
+  - build-logic/src/main/kotlin/recipe.kotlin.multiplatform.gradle.kts
+  - build-logic/src/main/kotlin/recipe.compose.multiplatform.gradle.kts
+  - build-logic/src/main/kotlin/recipe.android.application.gradle.kts
+  - build-logic/src/main/kotlin/recipe.jvm.server.gradle.kts
+  - settings.gradle.kts
+  - build.gradle.kts
+autonomous: true
+requirements: [INFRA-02]
+requirements_addressed: [INFRA-02]
+
+must_haves:
+  truths:
+    - "build-logic/ is an included build resolved via pluginManagement.includeBuild (PITFALL #9)"
+    - "5 precompiled script plugins exist under build-logic/src/main/kotlin/: recipe.quality, recipe.kotlin.multiplatform, recipe.compose.multiplatform, recipe.android.application, recipe.jvm.server (D-06)"
+    - "Each precompiled plugin reads versions via extensions.getByType<VersionCatalogsExtension>().named(\"libs\") (PITFALL #1)"
+    - "recipe.kotlin.multiplatform locks the D-05 target matrix (androidTarget, iosArm64, iosSimulatorArm64, jvm, wasmJs) + JVM toolchain 21 + framework basename 'ComposeApp' + Koin/Kermit/kotlin-test deps + allWarningsAsErrors"
+    - "recipe.compose.multiplatform layers on recipe.kotlin.multiplatform (does NOT re-declare KMP plugin — PITFALL #2)"
+    - "recipe.jvm.server uses quoted dependency configurations (\"implementation\"(...) — quoted-config footgun)"
+    - "settings.gradle.kts places includeBuild(\"build-logic\") INSIDE pluginManagement { } block (PITFALL #9)"
+  artifacts:
+    - path: "build-logic/settings.gradle.kts"
+      provides: "Included-build settings with shared catalog access (from files(\"../gradle/libs.versions.toml\"))"
+    - path: "build-logic/build.gradle.kts"
+      provides: "kotlin-dsl plugin + compileOnly(asDependency()) entries for every alias-based plugin referenced by precompiled plugins"
+    - path: "build-logic/src/main/kotlin/recipe.quality.gradle.kts"
+      provides: "Spotless + ktlint + allWarningsAsErrors safety net (D-10 / D-11)"
+    - path: "build-logic/src/main/kotlin/recipe.kotlin.multiplatform.gradle.kts"
+      provides: "D-05 target matrix + JVM toolchain + common deps + allWarningsAsErrors (D-07, D-08, D-11)"
+    - path: "build-logic/src/main/kotlin/recipe.compose.multiplatform.gradle.kts"
+      provides: "Compose MP plugin + hot-reload + Compose deps for commonMain (layered on KMP)"
+    - path: "build-logic/src/main/kotlin/recipe.android.application.gradle.kts"
+      provides: "com.android.application + namespace + SDK versions (composeApp only)"
+    - path: "build-logic/src/main/kotlin/recipe.jvm.server.gradle.kts"
+      provides: "kotlin(jvm) + Ktor + Flyway + server deps (server only)"
+    - path: "settings.gradle.kts"
+      provides: "Root settings with pluginManagement { includeBuild(\"build-logic\") }"
+    - path: "build.gradle.kts"
+      provides: "Root build with apply-false entries for spotless + flywayPlugin (classloader hint)"
+  key_links:
+    - from: "build-logic/src/main/kotlin/recipe.*.gradle.kts"
+      to: "gradle/libs.versions.toml"
+      via: "VersionCatalogsExtension.named(\"libs\")"
+      pattern: "extensions\\.getByType<VersionCatalogsExtension>\\(\\)\\.named\\(\"libs\"\\)"
+    - from: "Plan 03 module build files"
+      to: "build-logic/src/main/kotlin/recipe.*.gradle.kts"
+      via: "plugins { id(\"recipe.kotlin.multiplatform\") }"
+      pattern: "id\\(\"recipe\\."
+---
+
+<objective>
+Scaffold the `build-logic/` included build with 5 precompiled script plugins (`recipe.quality`, `recipe.kotlin.multiplatform`, `recipe.compose.multiplatform`, `recipe.android.application`, `recipe.jvm.server`) that every module in Plan 03 will apply. Wire the included build into `settings.gradle.kts` via `pluginManagement.includeBuild("build-logic")` and extend the root `build.gradle.kts` with `apply false` declarations for the two new plugins (Spotless + Flyway) so Gradle's classloader resolves them consistently.
+
+Purpose: This is the **dependency root** for every subsequent Phase 1 plan. Plan 03 cannot refactor module builds until these plugins exist. Plan 05 cannot wire Flyway into the server without `recipe.jvm.server`. The design (per D-06) enforces role declarations — `shared/` applies only `recipe.kotlin.multiplatform` + `recipe.quality` and therefore CANNOT pull Compose transitively (INFRA-06).
+
+Output: A fully populated `build-logic/` directory whose included-build settings resolve the parent catalog, a root settings file that finds `recipe.*` plugins by ID, and 5 precompiled plugins whose internals are verbatim (or near-verbatim) copies of 01-RESEARCH.md § Code Examples / § Architecture Patterns.
+</objective>
+
+<execution_context>
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-CONTEXT.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-PATTERNS.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-VALIDATION.md
+@settings.gradle.kts
+@build.gradle.kts
+@gradle/libs.versions.toml
+@CLAUDE.md
+
+<interfaces>
+<!-- These are the canonical excerpts the executor MUST copy verbatim. Line ranges refer to 01-RESEARCH.md. -->
+
+Plugin applications reference (01-PATTERNS.md and 01-RESEARCH.md):
+- `id("recipe.quality")` → from .gradle.kts file named `recipe.quality.gradle.kts` (Gradle convention)
+- `id("recipe.kotlin.multiplatform")` → `recipe.kotlin.multiplatform.gradle.kts`
+- etc.
+
+Version-catalog access pattern inside precompiled plugins (PITFALL #1, RESEARCH.md lines 362-380):
+```kotlin
+import org.gradle.api.artifacts.VersionCatalogsExtension
+import org.gradle.kotlin.dsl.getByType
+
+val libs = extensions.getByType<VersionCatalogsExtension>().named("libs")
+
+// Usage:
+val v = libs.findVersion("kotlin").get().toString()
+val lib = libs.findLibrary("koin-core").get()
+```
+
+Quoted configuration names in precompiled plugin dependencies (RESEARCH.md line 603, Pattern 7):
+```kotlin
+dependencies {
+    "implementation"(libs.findLibrary("ktor-serverCore").get())  // quoted!
+    // NOT: implementation(...)  — unresolved reference in precompiled plugin context
+}
+```
+
+The root `settings.gradle.kts` layout required by PITFALL #9 (RESEARCH.md lines 749-767):
+```kotlin
+pluginManagement {
+    includeBuild("build-logic")    // MUST be inside pluginManagement { }
+    repositories { ... }
+}
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Scaffold build-logic/ included build + 5 precompiled plugins</name>
+  <files>build-logic/settings.gradle.kts, build-logic/build.gradle.kts, build-logic/src/main/kotlin/recipe.quality.gradle.kts, build-logic/src/main/kotlin/recipe.kotlin.multiplatform.gradle.kts, build-logic/src/main/kotlin/recipe.compose.multiplatform.gradle.kts, build-logic/src/main/kotlin/recipe.android.application.gradle.kts, build-logic/src/main/kotlin/recipe.jvm.server.gradle.kts</files>
+  <read_first>
+    - .planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md lines 308-605 (§ Pattern 1 through § Pattern 7 — canonical excerpts for every file in this task)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md lines 652-774 (§ Common Pitfalls 1-10 — especially #1 catalog access, #2 double-apply KMP, #3 warnings-as-errors scope, #7 kotlinOptions, #9 includeBuild location, #10 framework basename)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-PATTERNS.md lines 105-443 (pattern assignments for each build-logic/ file with deltas)
+    - gradle/libs.versions.toml (Plan 01 added these aliases — verify they exist before writing `findLibrary(...)` references)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-CONTEXT.md D-06 through D-17 (plugin split, JVM split, warnings-as-errors, Koin deps, Flyway, server scope)
+  </read_first>
+  <action>
+  Create the `build-logic/` directory and all 7 files listed in `<files>`. Each file's content comes directly from 01-RESEARCH.md. Use the Write tool for every file (no heredoc).
+
+  ---
+
+  **File 1: `build-logic/settings.gradle.kts`** (01-RESEARCH.md lines 316-331, verbatim):
+
+  ```kotlin
+  dependencyResolutionManagement {
+      repositories {
+          google()
+          mavenCentral()
+          gradlePluginPortal()
+      }
+      versionCatalogs {
+          create("libs") {
+              from(files("../gradle/libs.versions.toml"))
+          }
+      }
+  }
+
+  rootProject.name = "build-logic"
+  ```
+
+  ---
+
+  **File 2: `build-logic/build.gradle.kts`** (01-RESEARCH.md lines 333-358, verbatim):
+
+  ```kotlin
+  plugins {
+      `kotlin-dsl`
+  }
+
+  dependencies {
+      compileOnly(libs.plugins.kotlinMultiplatform.asDependency())
+      compileOnly(libs.plugins.androidApplication.asDependency())
+      compileOnly(libs.plugins.composeMultiplatform.asDependency())
+      compileOnly(libs.plugins.composeCompiler.asDependency())
+      compileOnly(libs.plugins.composeHotReload.asDependency())
+      compileOnly(libs.plugins.kotlinJvm.asDependency())
+      compileOnly(libs.plugins.ktor.asDependency())
+      compileOnly(libs.plugins.spotless.asDependency())
+      compileOnly(libs.plugins.flywayPlugin.asDependency())
+  }
+
+  fun Provider<PluginDependency>.asDependency(): Provider<String> =
+      map { "${it.pluginId}:${it.pluginId}.gradle.plugin:${it.version.requiredVersion}" }
+  ```
+
+  ---
+
+  **File 3: `build-logic/src/main/kotlin/recipe.quality.gradle.kts`** (01-RESEARCH.md lines 483-512 + D-11 safety net):
+
+  ```kotlin
+  plugins {
+      id("com.diffplug.spotless")
+  }
+
+  spotless {
+      kotlin {
+          target("src/**/*.kt")
+          targetExclude("**/build/**", "**/generated/**")
+          ktlint()
+      }
+      kotlinGradle {
+          target("*.gradle.kts")
+          ktlint()
+      }
+      format("markdown") {
+          target("*.md", "docs/**/*.md")
+          endWithNewline()
+          trimTrailingWhitespace()
+      }
+  }
+
+  // D-11 redundancy guard: if a module applies recipe.quality alongside a Kotlin plugin
+  // (multiplatform or jvm), ensure allWarningsAsErrors still applies even if the module
+  // build didn't already configure it. Guarded with plugins.withId so this plugin is
+  // safely composable even when applied alone (no KotlinCompilationTask type available
+  // on the classpath until a Kotlin plugin is present).
+  plugins.withId("org.jetbrains.kotlin.multiplatform") {
+      tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask<*>>().configureEach {
+          compilerOptions {
+              allWarningsAsErrors.set(true)
+          }
+      }
+  }
+  plugins.withId("org.jetbrains.kotlin.jvm") {
+      tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask<*>>().configureEach {
+          compilerOptions {
+              allWarningsAsErrors.set(true)
+          }
+      }
+  }
+  ```
+
+  ---
+
+  **File 4: `build-logic/src/main/kotlin/recipe.kotlin.multiplatform.gradle.kts`** (01-RESEARCH.md lines 777-835, verbatim — the canonical KMP plugin):
+
+  ```kotlin
+  // build-logic/src/main/kotlin/recipe.kotlin.multiplatform.gradle.kts
+  // Establishes the D-05 target matrix + JVM toolchain + common deps.
+  // Android bytecode is JVM 11 (D-08); server + desktop + shared/jvm are JVM 21.
+
+  import org.gradle.api.artifacts.VersionCatalogsExtension
+  import org.gradle.kotlin.dsl.getByType
+  import org.jetbrains.kotlin.gradle.ExperimentalWasmDsl
+  import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
+  plugins {
+      id("org.jetbrains.kotlin.multiplatform")
+  }
+
+  val libs = extensions.getByType<VersionCatalogsExtension>().named("libs")
+
+  kotlin {
+      jvmToolchain(21)
+
+      androidTarget {
+          compilerOptions {
+              jvmTarget.set(JvmTarget.JVM_11)
+          }
+      }
+
+      listOf(iosArm64(), iosSimulatorArm64()).forEach { iosTarget ->
+          iosTarget.binaries.framework {
+              baseName = "ComposeApp"
+              isStatic = true
+          }
+      }
+
+      jvm {
+          compilerOptions {
+              jvmTarget.set(JvmTarget.JVM_21)
+          }
+      }
+
+      @OptIn(ExperimentalWasmDsl::class)
+      wasmJs { browser() }
+
+      compilerOptions {
+          allWarningsAsErrors.set(true)
+      }
+
+      sourceSets {
+          commonMain.dependencies {
+              implementation(project.dependencies.platform(libs.findLibrary("koin-bom").get()))
+              implementation(libs.findLibrary("koin-core").get())
+              implementation(libs.findLibrary("kermit").get())
+          }
+          commonTest.dependencies {
+              implementation(libs.findLibrary("kotlin-test").get())
+          }
+      }
+  }
+  ```
+
+  ---
+
+  **File 5: `build-logic/src/main/kotlin/recipe.compose.multiplatform.gradle.kts`** (01-RESEARCH.md lines 447-477 + 01-PATTERNS.md lines 247-287 — layers on KMP, PITFALL #2):
+
+  ```kotlin
+  import org.gradle.api.artifacts.VersionCatalogsExtension
+  import org.gradle.kotlin.dsl.getByType
+
+  plugins {
+      id("recipe.kotlin.multiplatform")
+      id("org.jetbrains.compose")
+      id("org.jetbrains.kotlin.plugin.compose")
+      id("org.jetbrains.compose.hot-reload")
+  }
+
+  val libs = extensions.getByType<VersionCatalogsExtension>().named("libs")
+
+  kotlin {
+      sourceSets {
+          commonMain.dependencies {
+              implementation(libs.findLibrary("compose-runtime").get())
+              implementation(libs.findLibrary("compose-foundation").get())
+              implementation(libs.findLibrary("compose-material3").get())
+              implementation(libs.findLibrary("compose-ui").get())
+              implementation(libs.findLibrary("compose-components-resources").get())
+              implementation(libs.findLibrary("androidx-lifecycle-viewmodelCompose").get())
+              implementation(libs.findLibrary("androidx-lifecycle-runtimeCompose").get())
+              implementation(libs.findLibrary("koin-compose").get())
+              implementation(libs.findLibrary("koin-composeViewmodel").get())
+          }
+      }
+  }
+  ```
+
+  CRITICAL: this plugin applies `id("recipe.kotlin.multiplatform")` — NOT `id("org.jetbrains.kotlin.multiplatform")`. The KMP plugin is applied transitively by the recipe plugin. Double-applying throws "Plugin already applied" (PITFALL #2).
+
+  ---
+
+  **File 6: `build-logic/src/main/kotlin/recipe.android.application.gradle.kts`** (01-RESEARCH.md lines 516-552, catalog-accessor-adjusted for precompiled-plugin context):
+
+  ```kotlin
+  import org.gradle.api.artifacts.VersionCatalogsExtension
+  import org.gradle.kotlin.dsl.getByType
+
+  plugins {
+      id("com.android.application")
+  }
+
+  val libs = extensions.getByType<VersionCatalogsExtension>().named("libs")
+
+  android {
+      namespace = "dev.ulfrx.recipe"
+      compileSdk = libs.findVersion("android-compileSdk").get().toString().toInt()
+
+      defaultConfig {
+          applicationId = "dev.ulfrx.recipe"
+          minSdk = libs.findVersion("android-minSdk").get().toString().toInt()
+          targetSdk = libs.findVersion("android-targetSdk").get().toString().toInt()
+          versionCode = 1
+          versionName = "1.0"
+      }
+      packaging {
+          resources {
+              excludes += "/META-INF/{AL2.0,LGPL2.1}"
+          }
+      }
+      buildTypes {
+          getByName("release") {
+              isMinifyEnabled = false
+          }
+      }
+      compileOptions {
+          sourceCompatibility = JavaVersion.VERSION_11
+          targetCompatibility = JavaVersion.VERSION_11
+      }
+  }
+  ```
+
+  CRITICAL: the version lookup is `libs.findVersion("android-compileSdk").get().toString().toInt()` — NOT `libs.versions.android.compileSdk.get().toInt()` (that accessor does not exist in precompiled plugins — PITFALL #1).
+
+  ---
+
+  **File 7: `build-logic/src/main/kotlin/recipe.jvm.server.gradle.kts`** (01-RESEARCH.md lines 558-601, quoted-config variant per PATTERNS.md line 395):
+
+  ```kotlin
+  import org.gradle.api.artifacts.VersionCatalogsExtension
+  import org.gradle.kotlin.dsl.getByType
+
+  plugins {
+      id("org.jetbrains.kotlin.jvm")
+      id("io.ktor.plugin")
+      id("org.flywaydb.flyway")
+      application
+  }
+
+  val libs = extensions.getByType<VersionCatalogsExtension>().named("libs")
+
+  kotlin {
+      jvmToolchain(21)
+      compilerOptions {
+          allWarningsAsErrors.set(true)
+      }
+  }
+
+  dependencies {
+      "implementation"(libs.findLibrary("ktor-serverCore").get())
+      "implementation"(libs.findLibrary("ktor-serverNetty").get())
+      "implementation"(libs.findLibrary("ktor-serverContentNegotiation").get())
+      "implementation"(libs.findLibrary("ktor-serializationKotlinxJson").get())
+      "implementation"(libs.findLibrary("logback").get())
+      "implementation"(libs.findLibrary("flyway-core").get())
+      "implementation"(libs.findLibrary("flyway-database-postgresql").get())
+      "implementation"(libs.findLibrary("postgresql").get())
+      "testImplementation"(libs.findLibrary("ktor-serverTestHost").get())
+      "testImplementation"(libs.findLibrary("kotlin-testJunit").get())
+  }
+
+  flyway {
+      url = System.getenv("DATABASE_URL") ?: "jdbc:postgresql://localhost:5432/recipe"
+      user = System.getenv("DATABASE_USER") ?: "recipe"
+      password = System.getenv("DATABASE_PASSWORD") ?: "recipe"
+      locations = arrayOf("classpath:db/migration")
+      cleanDisabled = true
+      baselineOnMigrate = true
+      validateOnMigrate = true
+  }
+  ```
+
+  CRITICAL:
+  - `"implementation"(...)` with quoted-string configuration is MANDATORY inside precompiled plugins — the unquoted form is a typed method that only exists in module build scripts.
+  - The `flyway { }` block is for CLI ergonomics (`./gradlew flywayInfo`). Runtime migration uses the Java API (Plan 05 wires this).
+
+  ---
+
+  After writing all 7 files, verify that `build-logic/build.gradle.kts` can see the catalog by running a syntax-only check. No `./gradlew build` yet — Plan 03 wires the modules.
+  </action>
+  <verify>
+    <automated>test -f build-logic/settings.gradle.kts && test -f build-logic/build.gradle.kts && test -f build-logic/src/main/kotlin/recipe.quality.gradle.kts && test -f build-logic/src/main/kotlin/recipe.kotlin.multiplatform.gradle.kts && test -f build-logic/src/main/kotlin/recipe.compose.multiplatform.gradle.kts && test -f build-logic/src/main/kotlin/recipe.android.application.gradle.kts && test -f build-logic/src/main/kotlin/recipe.jvm.server.gradle.kts && grep -q 'from(files("../gradle/libs.versions.toml"))' build-logic/settings.gradle.kts && grep -q '`kotlin-dsl`' build-logic/build.gradle.kts && grep -q 'asDependency' build-logic/build.gradle.kts && grep -q 'id("org.jetbrains.kotlin.multiplatform")' build-logic/src/main/kotlin/recipe.kotlin.multiplatform.gradle.kts && grep -q 'id("recipe.kotlin.multiplatform")' build-logic/src/main/kotlin/recipe.compose.multiplatform.gradle.kts && ! grep -q 'id("org.jetbrains.kotlin.multiplatform")' build-logic/src/main/kotlin/recipe.compose.multiplatform.gradle.kts && grep -q '"implementation"' build-logic/src/main/kotlin/recipe.jvm.server.gradle.kts && grep -q 'extensions.getByType<VersionCatalogsExtension>' build-logic/src/main/kotlin/recipe.kotlin.multiplatform.gradle.kts</automated>
+  </verify>
+  <acceptance_criteria>
+    - All 7 files exist at their declared paths
+    - `build-logic/settings.gradle.kts` contains literal `from(files("../gradle/libs.versions.toml"))`
+    - `build-logic/settings.gradle.kts` ends with `rootProject.name = "build-logic"`
+    - `build-logic/build.gradle.kts` contains `` `kotlin-dsl` `` (triple-backtick plugin alias)
+    - `build-logic/build.gradle.kts` defines the `Provider<PluginDependency>.asDependency()` extension function
+    - `build-logic/build.gradle.kts` has exactly 9 `compileOnly(libs.plugins.*.asDependency())` calls (kotlinMultiplatform, androidApplication, composeMultiplatform, composeCompiler, composeHotReload, kotlinJvm, ktor, spotless, flywayPlugin) — no `androidLibrary` because no precompiled plugin applies `com.android.library`; `shared/build.gradle.kts` applies that alias directly
+    - `recipe.kotlin.multiplatform.gradle.kts` contains `id("org.jetbrains.kotlin.multiplatform")` (exactly ONCE, in the plugins block)
+    - `recipe.kotlin.multiplatform.gradle.kts` contains `baseName = "ComposeApp"` (D-20 / PITFALL #10)
+    - `recipe.kotlin.multiplatform.gradle.kts` contains `jvmToolchain(21)` AND `JvmTarget.JVM_11` AND `JvmTarget.JVM_21` (D-08 split)
+    - `recipe.kotlin.multiplatform.gradle.kts` contains `allWarningsAsErrors.set(true)` at the `kotlin { compilerOptions { } }` extension level (D-11)
+    - `recipe.kotlin.multiplatform.gradle.kts` does NOT contain `js {` or `iosX64` (D-01 / D-02)
+    - `recipe.compose.multiplatform.gradle.kts` contains `id("recipe.kotlin.multiplatform")` AND does NOT contain `id("org.jetbrains.kotlin.multiplatform")` (PITFALL #2 guard)
+    - `recipe.compose.multiplatform.gradle.kts` contains `id("org.jetbrains.compose.hot-reload")` (preserves commit c50d747)
+    - `recipe.android.application.gradle.kts` contains `namespace = "dev.ulfrx.recipe"` (D-20)
+    - `recipe.android.application.gradle.kts` uses `libs.findVersion("android-compileSdk").get().toString().toInt()` (PITFALL #1)
+    - `recipe.jvm.server.gradle.kts` uses quoted `"implementation"` (not unquoted `implementation(...)` — quoted-config footgun)
+    - `recipe.jvm.server.gradle.kts` contains `cleanDisabled = true` (PITFALL #6 safety)
+    - `recipe.quality.gradle.kts` contains `targetExclude("**/build/**", "**/generated/**")` (avoids scanning generated Compose resources)
+    - Every precompiled plugin that reads the catalog contains `extensions.getByType<VersionCatalogsExtension>().named("libs")`
+  </acceptance_criteria>
+  <done>build-logic/ scaffold complete; all 7 files follow canonical patterns; no PITFALL #1/#2/#7/#9/#10 violations detectable via grep.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Wire build-logic into root settings.gradle.kts and update root build.gradle.kts</name>
+  <files>settings.gradle.kts, build.gradle.kts</files>
+  <read_first>
+    - settings.gradle.kts (current 37-line content — target of edit)
+    - build.gradle.kts (current 12-line content — target of edit)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md lines 749-767 (PITFALL #9 — includeBuild MUST be inside pluginManagement)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-PATTERNS.md lines 510-572 (settings.gradle.kts + root build.gradle.kts deltas)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-CONTEXT.md lines 107-109 (build-logic/ as included build — standard Gradle pattern)
+  </read_first>
+  <action>
+  Edit two files.
+
+  ---
+
+  **Edit 1: `settings.gradle.kts`** — add `includeBuild("build-logic")` as the FIRST statement inside the existing `pluginManagement { }` block. Do NOT move or remove any other line.
+
+  The current `pluginManagement { }` block (lines 4-16 of the existing file) should become:
+
+  ```kotlin
+  pluginManagement {
+      includeBuild("build-logic")
+      repositories {
+          google {
+              mavenContent {
+                  includeGroupAndSubgroups("androidx")
+                  includeGroupAndSubgroups("com.android")
+                  includeGroupAndSubgroups("com.google")
+              }
+          }
+          mavenCentral()
+          gradlePluginPortal()
+      }
+  }
+  ```
+
+  PITFALL #9 is load-bearing: `includeBuild` MUST be inside `pluginManagement { }`, NOT at top level, and NOT inside `dependencyResolutionManagement { }`. Placing it elsewhere means child modules cannot resolve `id("recipe.*")` plugin IDs.
+
+  Do NOT modify:
+  - Line 1: `rootProject.name = "recipe"`
+  - Line 2: `enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")`
+  - `dependencyResolutionManagement { }` block
+  - `plugins { id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0" }`
+  - `include(":composeApp")`, `include(":server")`, `include(":shared")`
+
+  ---
+
+  **Edit 2: `build.gradle.kts`** — append two new `alias(...) apply false` entries to the existing plugins block. Keep the existing 8 entries in their current order.
+
+  Result:
+
+  ```kotlin
+  plugins {
+      // this is necessary to avoid the plugins to be loaded multiple times
+      // in each subproject's classloader
+      alias(libs.plugins.androidApplication) apply false
+      alias(libs.plugins.androidLibrary) apply false
+      alias(libs.plugins.composeHotReload) apply false
+      alias(libs.plugins.composeMultiplatform) apply false
+      alias(libs.plugins.composeCompiler) apply false
+      alias(libs.plugins.kotlinJvm) apply false
+      alias(libs.plugins.kotlinMultiplatform) apply false
+      alias(libs.plugins.ktor) apply false
+      alias(libs.plugins.spotless) apply false
+      alias(libs.plugins.flywayPlugin) apply false
+  }
+  ```
+
+  Why the `apply false` entries: Gradle's plugin classloader uses these declarations as hints when the plugin is applied through an included-build's precompiled plugin. `recipe.quality` applies `com.diffplug.spotless` and `recipe.jvm.server` applies `org.flywaydb.flyway` — the root `apply false` entries ensure a single resolved classpath per plugin ID (per the existing template's comment).
+  </action>
+  <verify>
+    <automated>grep -q 'includeBuild("build-logic")' settings.gradle.kts && awk '/pluginManagement \{/,/^\}/' settings.gradle.kts | grep -q 'includeBuild("build-logic")' && ! awk '/dependencyResolutionManagement \{/,/^\}/' settings.gradle.kts | grep -q 'includeBuild' && grep -q 'alias(libs.plugins.spotless) apply false' build.gradle.kts && grep -q 'alias(libs.plugins.flywayPlugin) apply false' build.gradle.kts && grep -c 'apply false' build.gradle.kts | grep -q '^10$'</automated>
+  </verify>
+  <acceptance_criteria>
+    - `settings.gradle.kts` contains `includeBuild("build-logic")` exactly 1 time
+    - That `includeBuild("build-logic")` line appears INSIDE the `pluginManagement { ... }` block (verifiable: `awk '/pluginManagement \{/,/^\}/' settings.gradle.kts | grep -q 'includeBuild("build-logic")'`)
+    - `settings.gradle.kts` does NOT contain `includeBuild` anywhere else (NOT at top level, NOT in `dependencyResolutionManagement`)
+    - `settings.gradle.kts` still contains `rootProject.name = "recipe"` (unmodified line 1)
+    - `settings.gradle.kts` still contains `include(":composeApp")`, `include(":server")`, `include(":shared")` (unmodified)
+    - `build.gradle.kts` contains `alias(libs.plugins.spotless) apply false`
+    - `build.gradle.kts` contains `alias(libs.plugins.flywayPlugin) apply false`
+    - `grep -c 'apply false' build.gradle.kts` returns `10` (8 existing + 2 new)
+    - All 8 existing `alias(...)` lines are preserved
+  </acceptance_criteria>
+  <done>build-logic/ is discoverable as an included build for plugin resolution; root `build.gradle.kts` declares classloader hints for Spotless + Flyway.</done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| Gradle build → build-logic/ (included build) | Same-repo; no external trust boundary. Precompiled plugins run in the Gradle daemon's JVM with full project access by design. |
+| build-logic precompiled plugins → Maven Central + plugin portal | Inherits repository set from `build-logic/settings.gradle.kts.dependencyResolutionManagement` (google, mavenCentral, gradlePluginPortal). Pinned plugin versions via catalog aliases. |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-01-02-01 | Tampering (supply chain) | Precompiled plugin classpath | mitigate | Plugin versions resolved exclusively from catalog aliases via `asDependency()` — no literal versions leak into build-logic/build.gradle.kts. D-09 catalog-only rule enforced by Plan 07's `tools/verify-no-version-literals.sh`. |
+| T-01-02-02 | Elevation of Privilege | `recipe.jvm.server` applying Flyway to non-server modules | mitigate | `recipe.jvm.server` is applied ONLY to `server/build.gradle.kts` (Plan 03). The plugin bundles `io.ktor.plugin` + `org.flywaydb.flyway` + Postgres JDBC — if accidentally applied to `composeApp`, AGP would fail at configuration time. Role-declaration design (D-06) makes misuse obvious. |
+| T-01-02-03 | Tampering | `recipe.quality` Spotless scanning untrusted paths | accept | Spotless config restricted via `target("src/**/*.kt")` + `targetExclude("**/build/**", "**/generated/**")`. No execution of scanned code; ktlint is pure static analysis. |
+| T-01-02-04 | Denial of Service | Misspelled plugin ID breaks entire root build | mitigate | Task 1 `<acceptance_criteria>` greps for exact plugin IDs and the `id("recipe.kotlin.multiplatform")` layering in `recipe.compose.multiplatform.gradle.kts`. Plan 03's `./gradlew help` invocations will surface any remaining typos immediately. |
+</threat_model>
+
+<verification>
+Phase-level verification for this plan:
+
+- `tools/verify-no-version-literals.sh` still exits 0 (build-logic/build.gradle.kts is explicitly excluded by the script — the `asDependency()` coordinates contain a version string as part of the synthesized artifact coord, but the script excludes that single file).
+- No Gradle command is run yet — Plan 03 refactors modules to apply these plugins; until then, the root `./gradlew build` will still work against the EXISTING module build files (which have not yet been refactored).
+
+Optional fast sanity check (if needed):
+- `./gradlew --help` exits 0 (proves `settings.gradle.kts` still parses).
+- `./gradlew help` (without args) exits 0 (proves `includeBuild` is legal).
+
+These sanity checks are NOT in the `<automated>` verify blocks to keep them fast; run them once manually if a later plan fails unexpectedly.
+</verification>
+
+<success_criteria>
+- 7 files under `build-logic/` created with canonical content (exact path listing in `files_modified`)
+- `settings.gradle.kts` has `includeBuild("build-logic")` inside `pluginManagement { }`
+- `build.gradle.kts` has 10 `apply false` entries (8 existing + 2 new for Spotless + Flyway)
+- No existing version aliases or source files modified in Plan 01 or prior
+- `tools/verify-no-version-literals.sh` continues to exit 0
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/01-project-infrastructure-module-wiring/01-02-SUMMARY.md` recording: file tree under `build-logic/`, any deviations from canonical excerpts (expected: none), and the final plugin ID list (10 applies from recipe-family + spotless/flyway).
+</output>

.planning/phases/01-project-infrastructure-module-wiring/01-02-SUMMARY.md

@@ -0,0 +1,98 @@
+---
+phase: 01-project-infrastructure-module-wiring
+plan: 02
+subsystem: infra
+tags: [gradle, build-logic, included-build, precompiled-plugins, version-catalog, kotlin-multiplatform, compose, ktor, spotless, flyway, pitfall-1, pitfall-2, pitfall-9, pitfall-10]
+
+requires: [01-01]
+provides:
+  - "build-logic/ included build resolving the parent catalog via files(\"../gradle/libs.versions.toml\")"
+  - "Precompiled plugin recipe.quality (Spotless + ktlint + D-11 allWarningsAsErrors safety net via plugins.withId guard)"
+  - "Precompiled plugin recipe.kotlin.multiplatform (D-05 target matrix: androidTarget, iosArm64, iosSimulatorArm64, jvm, wasmJs; JVM toolchain 21 + JVM 11 Android bytecode per D-08; framework baseName = ComposeApp; Koin BOM + koin-core + Kermit + kotlin-test common deps; allWarningsAsErrors at kotlin{} level)"
+  - "Precompiled plugin recipe.compose.multiplatform (layers on recipe.kotlin.multiplatform — PITFALL #2 avoided; Compose + composeCompiler + composeHotReload + commonMain Compose deps + lifecycle-viewmodel-compose + koin-compose)"
+  - "Precompiled plugin recipe.android.application (namespace dev.ulfrx.recipe; findVersion catalog accessor per PITFALL #1; SDK versions from catalog)"
+  - "Precompiled plugin recipe.jvm.server (Kotlin JVM + Ktor + Flyway + application; quoted \"implementation\" configs; cleanDisabled=true; D-08 JVM toolchain 21)"
+  - "Root settings.gradle.kts with includeBuild(\"build-logic\") placed inside pluginManagement{} (PITFALL #9)"
+  - "Root build.gradle.kts with 10 alias(...) apply false entries (8 existing + Spotless + Flyway classloader hints)"
+affects: [01-03, 01-04, 01-05, 01-06, 01-07]
+
+tech-stack:
+  added:
+    - "build-logic/ included build (kotlin-dsl convention-plugin project)"
+    - "5 precompiled script plugins: recipe.quality, recipe.kotlin.multiplatform, recipe.compose.multiplatform, recipe.android.application, recipe.jvm.server"
+  patterns:
+    - "PITFALL #1 mitigation: every precompiled plugin reads versions via extensions.getByType<VersionCatalogsExtension>().named(\"libs\")"
+    - "PITFALL #2 mitigation: recipe.compose.multiplatform applies id(\"recipe.kotlin.multiplatform\") — KMP plugin applied transitively"
+    - "PITFALL #9 mitigation: includeBuild(\"build-logic\") sits inside pluginManagement{}"
+    - "PITFALL #10 mitigation: baseName = \"ComposeApp\" set on both iOS frameworks"
+    - "Quoted-configuration footgun avoidance: recipe.jvm.server uses \"implementation\"(...) string-literal configs"
+    - "D-11 redundancy guard: recipe.quality uses plugins.withId guards for composability"
+    - "Plugin coordinate synthesis via Provider<PluginDependency>.asDependency() keeps build-logic/build.gradle.kts catalog-only"
+
+key-files:
+  created:
+    - build-logic/settings.gradle.kts
+    - build-logic/build.gradle.kts
+    - build-logic/src/main/kotlin/recipe.quality.gradle.kts
+    - build-logic/src/main/kotlin/recipe.kotlin.multiplatform.gradle.kts
+    - build-logic/src/main/kotlin/recipe.compose.multiplatform.gradle.kts
+    - build-logic/src/main/kotlin/recipe.android.application.gradle.kts
+    - build-logic/src/main/kotlin/recipe.jvm.server.gradle.kts
+  modified:
+    - settings.gradle.kts
+    - build.gradle.kts
+
+key-decisions:
+  - "Content for all 7 build-logic/ files copied verbatim from 01-RESEARCH.md § Code Examples + 01-PATTERNS.md; no structural changes."
+  - "9 compileOnly(...asDependency()) entries omit androidLibrary — no recipe-family precompiled plugin applies com.android.library; shared/build.gradle.kts applies that plugin directly in 01-03."
+  - "recipe.quality's D-11 safety net is plugins.withId-guarded so the plugin remains composable when applied standalone."
+
+patterns-established:
+  - "Pattern 1 (role declarations): each recipe.* plugin encodes a module role; shared/ cannot pull Compose transitively (INFRA-06)."
+  - "Pattern 2 (catalog-only versioning inside build-logic): plugin coordinates via asDependency(); library refs via findLibrary; version refs via findVersion.toString().toInt()."
+  - "Pattern 3 (Flyway CLI + runtime split): flyway{} block for CLI ergonomics; runtime migration handled in 01-05."
+  - "Pattern 4 (JVM target split): jvmToolchain(21) drives shared/server/desktop; Android bytecode pinned at JVM 11; server JVM output at JVM 21."
+
+requirements-completed: [INFRA-02]
+
+duration: ~5min
+completed: 2026-04-24
+tasks-completed: 2
+files-created: 7
+files-modified: 2
+---
+
+# Phase 01 Plan 02: build-logic included build + 5 precompiled script plugins
+
+`build-logic/` scaffolded as an included build whose 5 precompiled script plugins encode D-05/D-06/D-08/D-11/D-20 constraints once, and whose single hook into the root project is `includeBuild("build-logic")` inside `settings.gradle.kts pluginManagement { }` per PITFALL #9.
+
+## What was built
+
+- **`build-logic/settings.gradle.kts`** — resolves parent catalog via `from(files("../gradle/libs.versions.toml"))`; `rootProject.name = "build-logic"`.
+- **`build-logic/build.gradle.kts`** — applies `` `kotlin-dsl` ``; 9 `compileOnly(libs.plugins.*.asDependency())` entries; `Provider<PluginDependency>.asDependency()` extension synthesises coordinates.
+- **`recipe.quality.gradle.kts`** — Spotless + ktlint on `src/**/*.kt` with `targetExclude("**/build/**", "**/generated/**")`; two `plugins.withId` guards enforce `allWarningsAsErrors.set(true)` on `KotlinCompilationTask<*>` when a Kotlin plugin is present.
+- **`recipe.kotlin.multiplatform.gradle.kts`** — canonical KMP plugin; `jvmToolchain(21)`; `androidTarget { jvmTarget = JVM_11 }`; `iosArm64()` + `iosSimulatorArm64()` with `baseName = "ComposeApp"; isStatic = true`; `jvm { jvmTarget = JVM_21 }`; `wasmJs { browser() }`; commonMain deps: Koin BOM + koin-core + Kermit; commonTest: kotlin-test.
+- **`recipe.compose.multiplatform.gradle.kts`** — applies `id("recipe.kotlin.multiplatform")` (PITFALL #2) + compose MP + compose compiler + compose hot-reload; commonMain Compose deps + lifecycle-viewmodel + koin-compose.
+- **`recipe.android.application.gradle.kts`** — `namespace = "dev.ulfrx.recipe"`; SDK versions via `libs.findVersion("android-compileSdk").get().toString().toInt()` (PITFALL #1); JVM 11 compile options.
+- **`recipe.jvm.server.gradle.kts`** — Kotlin JVM + Ktor + Flyway + application; `jvmToolchain(21)` + `allWarningsAsErrors.set(true)`; 10 quoted `"implementation"(...)` deps (ktor-server*, logback, flyway-core + flyway-database-postgresql, postgresql JDBC, ktor-serverTestHost, kotlin-testJunit); `flyway{}` block with env-driven URL + `cleanDisabled = true`.
+- **Root `settings.gradle.kts`** — added `includeBuild("build-logic")` as first statement inside existing `pluginManagement { }`.
+- **Root `build.gradle.kts`** — appended `alias(libs.plugins.spotless) apply false` and `alias(libs.plugins.flywayPlugin) apply false`. Total apply-false count: 10.
+
+## Commits
+
+| Task | Description | Hash |
+|------|-------------|------|
+| 1 | Scaffold build-logic/ included build + 5 precompiled plugins | `6a69910` |
+| 2 | Wire build-logic into root settings.gradle.kts + Spotless/Flyway apply-false | `60221f6` |
+
+## Deviations from Plan
+
+None — every `<automated>` grep block and acceptance criterion passed first-try.
+
+## Note
+
+This SUMMARY.md was drafted by the executor agent but hook-blocked from being written inside the worktree sandbox; the orchestrator persisted it after merging the worktree into master.
+
+## Requirements completed
+
+INFRA-02

.planning/phases/01-project-infrastructure-module-wiring/01-03-PLAN.md

@@ -0,0 +1,352 @@
+---
+phase: 01-project-infrastructure-module-wiring
+plan: 03
+type: execute
+wave: 2
+depends_on: [01, 02]
+files_modified:
+  - composeApp/build.gradle.kts
+  - shared/build.gradle.kts
+  - server/build.gradle.kts
+  - shared/src/jsMain
+autonomous: true
+requirements: [INFRA-02, INFRA-06]
+requirements_addressed: [INFRA-02, INFRA-06]
+
+must_haves:
+  truths:
+    - "composeApp/build.gradle.kts applies recipe.kotlin.multiplatform + recipe.compose.multiplatform + recipe.android.application + recipe.quality, and nothing else (D-06 role declaration)"
+    - "shared/build.gradle.kts applies recipe.kotlin.multiplatform + recipe.quality + androidLibrary alias, with explicitApi() set directly in the module (D-12)"
+    - "server/build.gradle.kts applies recipe.jvm.server + recipe.quality, and keeps only the module-specific application { } block"
+    - "The js target is removed from composeApp and shared (D-01); shared/src/jsMain/ directory is deleted"
+    - "iosX64 target is never referenced (D-02) — only iosArm64 + iosSimulatorArm64 via the convention plugin"
+    - "No version literals exist in any *.gradle.kts outside gradle/libs.versions.toml (INFRA-01 / D-09)"
+    - "shared/ framework basename is overridden to 'Shared' (D-07, PITFALL #10); composeApp keeps 'ComposeApp' from the convention plugin"
+  artifacts:
+    - path: "composeApp/build.gradle.kts"
+      provides: "Module build applying 4 recipe.* convention plugins + module-only source-set deps (androidMain, commonMain projects.shared, jvmMain desktop)"
+      min_lines: 15
+    - path: "shared/build.gradle.kts"
+      provides: "Module build applying recipe.kotlin.multiplatform + recipe.quality + androidLibrary; enabling explicitApi(); overriding framework baseName to 'Shared'; keeping android { namespace } block"
+      min_lines: 15
+    - path: "server/build.gradle.kts"
+      provides: "Module build applying recipe.jvm.server + recipe.quality; keeping application { mainClass } block and implementation(projects.shared) dep"
+      min_lines: 10
+  key_links:
+    - from: "composeApp/build.gradle.kts"
+      to: "build-logic/src/main/kotlin/recipe.kotlin.multiplatform.gradle.kts"
+      via: "plugins { id(\"recipe.kotlin.multiplatform\") }"
+      pattern: "id\\(\"recipe\\.kotlin\\.multiplatform\"\\)"
+    - from: "composeApp/build.gradle.kts"
+      to: "build-logic/src/main/kotlin/recipe.compose.multiplatform.gradle.kts"
+      via: "plugins { id(\"recipe.compose.multiplatform\") }"
+      pattern: "id\\(\"recipe\\.compose\\.multiplatform\"\\)"
+    - from: "server/build.gradle.kts"
+      to: "build-logic/src/main/kotlin/recipe.jvm.server.gradle.kts"
+      via: "plugins { id(\"recipe.jvm.server\") }"
+      pattern: "id\\(\"recipe\\.jvm\\.server\"\\)"
+---
+
+<objective>
+Refactor the three module build scripts (`composeApp/`, `shared/`, `server/`) to apply the convention plugins from Plan 02 and remove the content those plugins now own. Drop the `js` target (D-01), confirm `iosX64` stays absent (D-02), add `explicitApi()` + framework-basename override to `shared/` (D-12 / PITFALL #10), and ensure every module's `plugins { }` block reads as a role declaration (D-06). Also delete the `shared/src/jsMain/` source directory (D-01).
+
+Purpose: This plan delivers INFRA-02's structural payoff — adding a new KMP module in the future should require only `plugins { id("recipe.kotlin.multiplatform") }` + source-set declarations, not copy-pasting Compose configs. It also delivers INFRA-06's structural prerequisite: after this refactor, `shared/` no longer pulls Compose transitively (because `recipe.compose.multiplatform` is applied only to `composeApp/`).
+
+Output: Three rewritten `build.gradle.kts` files (each ≤40 lines), `shared/src/jsMain/` directory deleted. No `./gradlew build` run in this plan — Plan 04/05 verify via their own targets, Plan 07 runs the full green-build gate.
+</objective>
+
+<execution_context>
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-CONTEXT.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-PATTERNS.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-VALIDATION.md
+@composeApp/build.gradle.kts
+@shared/build.gradle.kts
+@server/build.gradle.kts
+@CLAUDE.md
+
+<interfaces>
+<!-- Plans 01 + 02 must be complete before this plan runs. -->
+
+From gradle/libs.versions.toml (Plan 01 extended):
+- `libs.plugins.androidLibrary` — still referenced as alias inside shared/build.gradle.kts
+- `libs.compose.uiToolingPreview` — referenced from composeApp/build.gradle.kts module-specific deps
+- `libs.androidx.activity.compose` — referenced from composeApp androidMain deps
+- `libs.kotlinx.coroutinesSwing` — referenced from composeApp jvmMain deps
+- `libs.compose.uiTooling` — referenced from composeApp debugImplementation
+- `libs.koin.android` — NEW alias (Plan 01) for MainApplication's `androidContext(...)` in Plan 04
+
+From build-logic/src/main/kotlin/ (Plan 02 created):
+- `recipe.kotlin.multiplatform` — applies KMP, sets D-05 targets, JVM toolchain, adds koin-bom/koin-core/kermit to commonMain, kotlin-test to commonTest, allWarningsAsErrors
+- `recipe.compose.multiplatform` — applies Compose MP + hot-reload on top of KMP, adds compose-* deps to commonMain
+- `recipe.android.application` — applies com.android.application, sets namespace + SDK versions
+- `recipe.jvm.server` — applies kotlin(jvm) + io.ktor.plugin + flyway + all server deps + quoted-config dependency block
+- `recipe.quality` — applies Spotless + allWarningsAsErrors safety net
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Rewrite composeApp/build.gradle.kts and shared/build.gradle.kts, delete shared/src/jsMain/</name>
+  <files>composeApp/build.gradle.kts, shared/build.gradle.kts, shared/src/jsMain</files>
+  <read_first>
+    - composeApp/build.gradle.kts (current 114 lines — target of rewrite)
+    - shared/build.gradle.kts (current 55 lines — target of rewrite)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-PATTERNS.md lines 574-672 (exact deltas for composeApp + shared)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-CONTEXT.md D-01 (drop js), D-03 (no desktop packaging), D-12 (explicitApi on shared only), D-20 (namespace + baseName)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md lines 1144-1155 (Open Question #1 — keep com.android.library on shared/ in Phase 1)
+  </read_first>
+  <action>
+  Two file rewrites plus one directory deletion.
+
+  **Rewrite 1: `composeApp/build.gradle.kts`** — replace entire file content with:
+
+  ```kotlin
+  plugins {
+      id("recipe.kotlin.multiplatform")
+      id("recipe.compose.multiplatform")
+      id("recipe.android.application")
+      id("recipe.quality")
+  }
+
+  kotlin {
+      sourceSets {
+          androidMain.dependencies {
+              implementation(libs.compose.uiToolingPreview)
+              implementation(libs.androidx.activity.compose)
+              implementation(libs.koin.android)
+          }
+          commonMain.dependencies {
+              implementation(libs.compose.uiToolingPreview)
+              implementation(projects.shared)
+          }
+          jvmMain.dependencies {
+              implementation(compose.desktop.currentOs)
+              implementation(libs.kotlinx.coroutinesSwing)
+          }
+      }
+  }
+
+  dependencies {
+      debugImplementation(libs.compose.uiTooling)
+  }
+  ```
+
+  DELETIONS relative to the current file:
+  - DROP all 3 imports on lines 1-3 (no longer needed — convention plugins supply JvmTarget/ExperimentalWasmDsl/TargetFormat)
+  - DROP the original `plugins { alias(...) alias(...) }` block (lines 5-11) — replaced with 4 recipe.* IDs
+  - DROP the `kotlin { androidTarget { ... } iosArm64() iosSimulatorArm64() jvm { ... } js { ... } wasmJs { ... } }` structural block (lines 13-46) — moved into `recipe.kotlin.multiplatform`
+  - DROP `commonMain.dependencies` Compose entries (lines 52-62 — compose.runtime, compose.foundation, compose.material3, compose.ui, compose.components.resources, androidx.lifecycle.viewmodelCompose, androidx.lifecycle.runtimeCompose) — moved into `recipe.compose.multiplatform`. KEEP `implementation(projects.shared)` and the module-only `implementation(libs.compose.uiToolingPreview)` (the preview tooling is needed by `@Preview` annotations in composeApp's common code).
+  - DROP `commonTest.dependencies { implementation(libs.kotlin.test) }` (lines 63-65) — moved into `recipe.kotlin.multiplatform`
+  - DROP the entire `android { ... }` block (lines 73-98) — moved into `recipe.android.application`
+  - DROP `compose.desktop { application { ... nativeDistributions { ... } } }` (lines 104-114) — D-03 says no desktop packaging
+
+  ADDITIONS:
+  - ADD `implementation(libs.koin.android)` to `androidMain.dependencies` (Plan 04's MainApplication.kt calls `androidContext(...)` which comes from koin-android; the catalog alias was added in Plan 01).
+
+  KEEP:
+  - `androidMain.dependencies { implementation(libs.compose.uiToolingPreview); implementation(libs.androidx.activity.compose) }` — Android-only deps
+  - `jvmMain.dependencies { implementation(compose.desktop.currentOs); implementation(libs.kotlinx.coroutinesSwing) }` — Desktop-only deps
+  - `dependencies { debugImplementation(libs.compose.uiTooling) }` — Android debug-only tooling
+
+  **Rewrite 2: `shared/build.gradle.kts`** — replace entire file content with:
+
+  ```kotlin
+  plugins {
+      id("recipe.kotlin.multiplatform")
+      id("recipe.quality")
+      alias(libs.plugins.androidLibrary)
+  }
+
+  kotlin {
+      explicitApi()
+
+      // Override framework baseName: shared exposes "Shared.framework" to Swift, while
+      // composeApp's convention-plugin default is "ComposeApp.framework". (D-07 / PITFALL #10)
+      targets.withType<org.jetbrains.kotlin.gradle.plugin.mpp.KotlinNativeTarget>().configureEach {
+          binaries.withType<org.jetbrains.kotlin.gradle.plugin.mpp.Framework>().configureEach {
+              baseName = "Shared"
+          }
+      }
+
+      sourceSets {
+          commonMain.dependencies {
+              // Phase 1: intentionally empty. Domain models + DTOs land Phase 2+.
+              // D-19 / INFRA-06: Do NOT add Ktor, Compose, or SQLDelight deps here — EVER.
+          }
+      }
+  }
+
+  android {
+      namespace = "dev.ulfrx.recipe.shared"
+      compileSdk = libs.versions.android.compileSdk.get().toInt()
+      compileOptions {
+          sourceCompatibility = JavaVersion.VERSION_11
+          targetCompatibility = JavaVersion.VERSION_11
+      }
+      defaultConfig {
+          minSdk = libs.versions.android.minSdk.get().toInt()
+      }
+  }
+  ```
+
+  DELETIONS relative to the current file:
+  - DROP both imports on lines 1-2 (no longer needed)
+  - DROP the original `plugins { alias(libs.plugins.kotlinMultiplatform); alias(libs.plugins.androidLibrary) }` (lines 4-7) — replaced with `id("recipe.kotlin.multiplatform")` + kept `alias(libs.plugins.androidLibrary)`
+  - DROP the entire `kotlin { androidTarget { ... } iosArm64() iosSimulatorArm64() jvm { ... } js { ... } wasmJs { ... } ... }` structural block (lines 9-41) — moved into `recipe.kotlin.multiplatform`
+  - DROP `js { browser() }` (lines 25-27) — D-01
+
+  ADDITIONS:
+  - ADD `explicitApi()` inside the `kotlin { }` block (D-12 — strict on shared/ only, configured directly in module)
+  - ADD the framework baseName override block targeting `KotlinNativeTarget`/`Framework` (overrides the convention plugin's `"ComposeApp"` default to `"Shared"` — D-07 / PITFALL #10)
+
+  KEEP:
+  - `android { namespace = "dev.ulfrx.recipe.shared"; compileSdk; compileOptions; defaultConfig.minSdk }` — per 01-RESEARCH.md Open Question #1, keep `com.android.library` applied in Phase 1 (deferring the "do we need it" question to a future `recipe.android.library` plugin)
+
+  Note on `libs.versions.android.compileSdk.get().toInt()` vs `libs.findVersion(...)`: the `libs.versions.*` accessor IS available in MODULE `build.gradle.kts` files (it's only unavailable in precompiled plugins — PITFALL #1 applies only there). So the typed accessor is correct here.
+
+  **Directory deletion: `shared/src/jsMain/`**
+
+  Delete the entire `shared/src/jsMain/` directory (contains `kotlin/dev/ulfrx/recipe/Platform.js.kt`). D-01 drops the `js` target; with `recipe.kotlin.multiplatform` no longer declaring `js()`, this source directory becomes orphaned.
+
+  Run: `rm -rf shared/src/jsMain`
+
+  Do NOT delete `shared/src/wasmJsMain/` — `wasmJs` is kept per D-01. `composeApp/src/webMain/` is the wasmJs source set, also kept.
+  </action>
+  <verify>
+    <automated>grep -q 'id("recipe.kotlin.multiplatform")' composeApp/build.gradle.kts && grep -q 'id("recipe.compose.multiplatform")' composeApp/build.gradle.kts && grep -q 'id("recipe.android.application")' composeApp/build.gradle.kts && grep -q 'id("recipe.quality")' composeApp/build.gradle.kts && ! grep -q 'androidTarget' composeApp/build.gradle.kts && ! grep -q 'iosArm64' composeApp/build.gradle.kts && ! grep -q 'js {' composeApp/build.gradle.kts && ! grep -q 'nativeDistributions' composeApp/build.gradle.kts && ! grep -q '^android {' composeApp/build.gradle.kts && grep -q 'implementation(libs.koin.android)' composeApp/build.gradle.kts && grep -q 'id("recipe.kotlin.multiplatform")' shared/build.gradle.kts && grep -q 'id("recipe.quality")' shared/build.gradle.kts && grep -q 'explicitApi()' shared/build.gradle.kts && grep -q 'baseName = "Shared"' shared/build.gradle.kts && ! grep -q 'js {' shared/build.gradle.kts && ! test -d shared/src/jsMain && bash tools/verify-no-version-literals.sh && bash tools/verify-shared-pure.sh</automated>
+  </verify>
+  <acceptance_criteria>
+    - `composeApp/build.gradle.kts` has exactly 4 `id("recipe.*")` lines: `recipe.kotlin.multiplatform`, `recipe.compose.multiplatform`, `recipe.android.application`, `recipe.quality`
+    - `composeApp/build.gradle.kts` does NOT contain `androidTarget`, `iosArm64`, `iosSimulatorArm64`, `jvm {`, `js {`, `wasmJs {`, or any `binaries.framework` block (all moved to convention plugin)
+    - `composeApp/build.gradle.kts` does NOT contain an `^android {` block header (moved to `recipe.android.application`)
+    - `composeApp/build.gradle.kts` does NOT contain `nativeDistributions` or `compose.desktop { application { ... } }` (D-03)
+    - `composeApp/build.gradle.kts` does NOT contain `import org.jetbrains.compose.desktop.application.dsl.TargetFormat` (D-03)
+    - `composeApp/build.gradle.kts` contains `implementation(libs.koin.android)` inside an `androidMain.dependencies` block
+    - `composeApp/build.gradle.kts` contains `implementation(projects.shared)` in `commonMain.dependencies` (preserved for Plan 04 usage)
+    - `composeApp/build.gradle.kts` line count ≤ 30 (was 114)
+    - `shared/build.gradle.kts` has `id("recipe.kotlin.multiplatform")` + `id("recipe.quality")` + `alias(libs.plugins.androidLibrary)` (exactly 3 plugin applications)
+    - `shared/build.gradle.kts` contains `explicitApi()` (D-12)
+    - `shared/build.gradle.kts` contains `baseName = "Shared"` (exactly that capitalization — PITFALL #10)
+    - `shared/build.gradle.kts` does NOT contain `js {` or `iosX64`
+    - `shared/build.gradle.kts` contains the `android { namespace = "dev.ulfrx.recipe.shared" }` block (kept per Open Question #1)
+    - `shared/src/jsMain` directory no longer exists (`test ! -d shared/src/jsMain`)
+    - `tools/verify-no-version-literals.sh` exits 0 (no version literals leaked during rewrite)
+    - `tools/verify-shared-pure.sh` exits 0 (shared/commonMain has only Greeting.kt/Platform.kt/Constants.kt — no forbidden imports)
+  </acceptance_criteria>
+  <done>Both module builds apply recipe.* conventions; js target source dir deleted; explicitApi + Shared basename set on shared/.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Rewrite server/build.gradle.kts</name>
+  <files>server/build.gradle.kts</files>
+  <read_first>
+    - server/build.gradle.kts (current 23 lines — target of rewrite)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-PATTERNS.md lines 674-706 (server/build.gradle.kts delta)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md lines 556-605 (§ Pattern 7 — what's ALREADY in the convention plugin and does NOT need to be in the module)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-CONTEXT.md D-16 (server scope — Flyway, Postgres, /health)
+  </read_first>
+  <action>
+  Replace the entire content of `server/build.gradle.kts` with:
+
+  ```kotlin
+  plugins {
+      id("recipe.jvm.server")
+      id("recipe.quality")
+  }
+
+  group = "dev.ulfrx.recipe"
+  version = "1.0.0"
+
+  application {
+      mainClass.set("dev.ulfrx.recipe.ApplicationKt")
+
+      val isDevelopment: Boolean = project.ext.has("development")
+      applicationDefaultJvmArgs = listOf("-Dio.ktor.development=$isDevelopment")
+  }
+
+  dependencies {
+      implementation(projects.shared)
+  }
+  ```
+
+  DELETIONS:
+  - DROP original plugins block (lines 1-5 — `alias(libs.plugins.kotlinJvm); alias(libs.plugins.ktor); application`) → replaced with 2 recipe.* IDs. The `application` plugin is applied by `recipe.jvm.server`.
+  - DROP individual dependency lines (lines 16-22 — `libs.logback`, `libs.ktor.serverCore`, `libs.ktor.serverNetty`, `libs.ktor.serverTestHost`, `libs.kotlin.testJunit`) → all moved into `recipe.jvm.server`.
+
+  KEEP:
+  - `group = "dev.ulfrx.recipe"` and `version = "1.0.0"` (module coordinates — per-module concern)
+  - `application { mainClass.set(...) }` + `applicationDefaultJvmArgs` (per-module config — the `application` plugin is applied by `recipe.jvm.server` but this config is module-specific)
+  - `implementation(projects.shared)` — module-specific project dependency (server depends on shared for Greeting, SERVER_PORT, future DTOs)
+
+  Note: `ktor-serverContentNegotiation`, `ktor-serializationKotlinxJson`, `flyway-core`, `flyway-database-postgresql`, `postgresql` are ALL bundled in `recipe.jvm.server` and do NOT need to be declared here.
+  </action>
+  <verify>
+    <automated>grep -q 'id("recipe.jvm.server")' server/build.gradle.kts && grep -q 'id("recipe.quality")' server/build.gradle.kts && ! grep -q 'libs.plugins.kotlinJvm' server/build.gradle.kts && ! grep -q 'libs.plugins.ktor' server/build.gradle.kts && grep -q 'mainClass.set("dev.ulfrx.recipe.ApplicationKt")' server/build.gradle.kts && grep -q 'implementation(projects.shared)' server/build.gradle.kts && ! grep -q 'libs.logback' server/build.gradle.kts && ! grep -q 'libs.ktor.serverCore' server/build.gradle.kts && bash tools/verify-no-version-literals.sh</automated>
+  </verify>
+  <acceptance_criteria>
+    - `server/build.gradle.kts` has exactly 2 `id("recipe.*")` lines: `recipe.jvm.server`, `recipe.quality`
+    - `server/build.gradle.kts` does NOT contain `alias(libs.plugins.kotlinJvm)` or `alias(libs.plugins.ktor)`
+    - `server/build.gradle.kts` does NOT contain `libs.logback`, `libs.ktor.serverCore`, `libs.ktor.serverNetty`, `libs.ktor.serverTestHost`, or `libs.kotlin.testJunit` (all relocated to convention plugin)
+    - `server/build.gradle.kts` contains `mainClass.set("dev.ulfrx.recipe.ApplicationKt")` (unchanged)
+    - `server/build.gradle.kts` contains `implementation(projects.shared)` (unchanged)
+    - `server/build.gradle.kts` contains `group = "dev.ulfrx.recipe"` and `version = "1.0.0"` (unchanged module coordinates)
+    - `server/build.gradle.kts` line count ≤ 20 (was 23; effectively unchanged but deps block shrinks)
+    - `tools/verify-no-version-literals.sh` exits 0
+  </acceptance_criteria>
+  <done>server build applies recipe.jvm.server + recipe.quality; module-only config (mainClass, shared dep) preserved.</done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| Module build scripts → build-logic precompiled plugins | Same repo; plugins apply privileged build configuration (namespace, SDK versions, dep injection). No external trust boundary. |
+| Gradle module configuration → dependency resolution | Same as Plan 02 — aliases resolved via `libs.versions.toml` (pinned); no runtime consequences until Plan 04/05 actually compile code. |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-01-03-01 | Tampering (supply-chain leak) | Accidental version literal in rewrites | mitigate | Every task's `<automated>` runs `tools/verify-no-version-literals.sh` which scans every `*.gradle.kts` after the rewrite. Any inlined version (e.g. a forgotten `"1.0.0"` as a dep version) fails the check. Note: `version = "1.0.0"` on `server/build.gradle.kts` line 2 is PROJECT coordinate, not a dependency version — the verify script targets `version\s*=\s*"[0-9]` inside dependency declarations only; project-version assignments pass (not declared as `libs.*` lookup). Verify script scope matches PATTERNS.md spec. |
+| T-01-03-02 | Elevation of Privilege | Compose deps leak into shared/ | mitigate | `shared/build.gradle.kts` applies ONLY `recipe.kotlin.multiplatform` + `recipe.quality` + `androidLibrary` — NOT `recipe.compose.multiplatform`. Plan 07's `tools/verify-shared-pure.sh` will catch forbidden imports if they ever appear. |
+| T-01-03-03 | Denial of Service | Missing `recipe.compose.multiplatform` application on composeApp breaks Compose | mitigate | Task 1 `<acceptance_criteria>` greps for all 4 recipe IDs explicitly. Plan 04 will fail at compile time if the Compose plugin ID is missing. |
+| T-01-03-04 | Tampering | `js` target remnants in source tree after D-01 drop | mitigate | Task 1 explicitly deletes `shared/src/jsMain/` directory and greps for `js {` blocks. `composeApp/src/webMain/` (wasmJs target, kept) is NOT touched. |
+</threat_model>
+
+<verification>
+Phase-level verification for this plan:
+
+- All three `tools/verify-*.sh` scripts exit 0 after rewrites.
+- `shared/src/jsMain/` directory no longer exists.
+- `composeApp/build.gradle.kts` shrinks from 114 to ~30 lines — INFRA-02 payoff visible.
+- `shared/build.gradle.kts` shrinks from 55 to ~35 lines and now sets `explicitApi()`.
+
+Optional sanity check (NOT in `<automated>` — Plan 07 runs the full gate):
+- `./gradlew :composeApp:help -q` emits a non-empty help output without a configuration error (proves plugin IDs resolve). Skip for speed — Plan 04 and Plan 05 will surface plugin-application errors via their own `./gradlew` targets.
+</verification>
+
+<success_criteria>
+- `composeApp/build.gradle.kts` applies 4 recipe.* IDs and contains NO `kotlin { androidTarget { ... } ... }` structural block and NO `android { ... }` block and NO `nativeDistributions`
+- `shared/build.gradle.kts` applies 3 plugins (2 recipe.* + androidLibrary), enables `explicitApi()`, overrides baseName to `"Shared"`
+- `server/build.gradle.kts` applies 2 recipe.* IDs and keeps only `application { mainClass }` + `implementation(projects.shared)`
+- `shared/src/jsMain/` deleted
+- `tools/verify-no-version-literals.sh` exits 0
+- `tools/verify-shared-pure.sh` exits 0
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/01-project-infrastructure-module-wiring/01-03-SUMMARY.md` recording: final LOC of each module build file (target: composeApp ≤30, shared ≤35, server ≤20), any deviations from the canonical patterns (expected: none), and confirmation that `shared/src/jsMain/` is gone.
+</output>

.planning/phases/01-project-infrastructure-module-wiring/01-03-SUMMARY.md

@@ -0,0 +1,148 @@
+---
+phase: 01-project-infrastructure-module-wiring
+plan: 03
+subsystem: infra
+tags: [gradle, kmp, convention-plugins, compose-multiplatform, ktor-server, android-library, explicitApi, ios-framework]
+
+# Dependency graph
+requires:
+  - phase: 01-project-infrastructure-module-wiring
+    provides: "Plan 01 extended libs.versions.toml (koin.android alias); Plan 02 created 5 recipe.* convention plugins in build-logic/"
+provides:
+  - "composeApp/build.gradle.kts reduced from 114 to 28 lines; role-declaration plugin block applying recipe.kotlin.multiplatform + recipe.compose.multiplatform + recipe.android.application + recipe.quality"
+  - "shared/build.gradle.kts reduced from 55 to 36 lines; applies recipe.kotlin.multiplatform + recipe.quality + androidLibrary; enables explicitApi(); overrides iOS framework baseName to 'Shared'"
+  - "server/build.gradle.kts reduced from 23 to 18 lines; applies recipe.jvm.server + recipe.quality; retains only module-specific mainClass + projects.shared dep"
+  - "js target fully removed: shared/src/jsMain/ directory deleted (D-01)"
+  - "iosX64 remains absent across all modules (D-02)"
+  - "INFRA-02 structural payoff visible: adding a new KMP module henceforth requires only plugins { id('recipe.kotlin.multiplatform') } + sourceSet declarations"
+  - "INFRA-06 structural prerequisite: shared/ no longer applies recipe.compose.multiplatform, so Compose cannot leak transitively"
+affects: [02-auth, 03-households, 04-sync-skeleton, 05-recipe-catalog, 10-ui-chrome]
+
+# Tech tracking
+tech-stack:
+  added: []  # Plan 03 is pure refactor — all libraries/tools already added in Plans 01/02
+  patterns:
+    - "Role-declaration plugin blocks (D-06): module build.gradle.kts plugins {} lists only recipe.* IDs + module-specific aliases (e.g. androidLibrary on shared/)"
+    - "Per-module override pattern: shared/ overrides framework baseName by targeting KotlinNativeTarget + Framework directly in the module, not from the convention plugin (D-07 / PITFALL #10)"
+    - "Module-specific dep retention: jvmMain compose.desktop.currentOs + kotlinx.coroutinesSwing stay in composeApp; android debug-only libs.compose.uiTooling stays as debugImplementation"
+
+key-files:
+  created: []
+  modified:
+    - "composeApp/build.gradle.kts — rewritten: 4 recipe.* plugin IDs + 3-source-set dep block + 1 debug tooling line"
+    - "shared/build.gradle.kts — rewritten: 3 plugins + explicitApi() + Framework baseName override + android {} block retained"
+    - "server/build.gradle.kts — rewritten: 2 recipe.* plugin IDs + application {} + projects.shared dep"
+    - "shared/src/jsMain/kotlin/dev/ulfrx/recipe/Platform.js.kt — DELETED (D-01 drops js target)"
+
+key-decisions:
+  - "Keep android { namespace = 'dev.ulfrx.recipe.shared' } block applied in Phase 1 per Open Question #1 (com.android.library retained; future recipe.android.library convention plugin deferred)"
+  - "libs.versions.* typed accessor used directly in module build.gradle.kts (not libs.findVersion) — PITFALL #1 only applies to precompiled plugin scripts, not module scripts"
+  - "libs.koin.android added to composeApp androidMain (not commonMain) — Koin's androidContext(...) lives in the android-specific artifact; commonMain stays platform-neutral"
+  - "Framework baseName override placed in the module, not hoisted into recipe.kotlin.multiplatform — shared/ is the only module needing 'Shared' (composeApp keeps convention default 'ComposeApp'), so keeping it local avoids a plugin parameter"
+
+patterns-established:
+  - "Plugin role declaration: each module build.gradle.kts opens with id('recipe.<role>') IDs — reading the plugins block tells you what the module IS, not how it's configured"
+  - "Zero version literals in module build files: dependencies always go through libs.* aliases; only project coordinate 'version = 1.0.0' (unindented) is exempted by tools/verify-no-version-literals.sh"
+  - "Per-module framework basename: KotlinNativeTarget.binaries.withType<Framework>().configureEach { baseName = … } pattern is the canonical override point"
+
+requirements-completed: [INFRA-02, INFRA-06]
+
+# Metrics
+duration: ~8min
+completed: 2026-04-24
+---
+
+# Phase 01 Plan 03: Module Build Scripts Wiring Summary
+
+**Rewrote all three module build.gradle.kts files as role declarations applying recipe.* convention plugins; dropped the js target (shared/src/jsMain/ deleted); enabled explicitApi() + 'Shared' framework basename on shared/.**
+
+## Performance
+
+- **Duration:** ~8 min
+- **Started:** 2026-04-24T16:14:27Z
+- **Completed:** 2026-04-24T16:22:17Z
+- **Tasks:** 2
+- **Files modified:** 3 (composeApp, shared, server build.gradle.kts) + 1 deleted (Platform.js.kt)
+
+## Accomplishments
+- **composeApp/build.gradle.kts:** 114 → 28 lines (-75%). Structural blocks (androidTarget, iosArm64/iosSimulatorArm64, jvm, js, wasmJs, android { }, compose.desktop { nativeDistributions }) all removed and inherited from convention plugins. Only 3 source-set dep blocks + 1 debug tooling line remain.
+- **shared/build.gradle.kts:** 55 → 36 lines (-35%). Structural target blocks moved to recipe.kotlin.multiplatform; explicitApi() + KotlinNativeTarget/Framework baseName = "Shared" override added (D-07 / D-12 / PITFALL #10); android {} block kept per Open Question #1.
+- **server/build.gradle.kts:** 23 → 18 lines (-22%). Dependency declarations (logback, ktor-serverCore/Netty/TestHost, kotlin-testJunit) fully relocated into recipe.jvm.server; only module coordinates + mainClass + projects.shared remain.
+- **js target eliminated:** `shared/src/jsMain/kotlin/dev/ulfrx/recipe/Platform.js.kt` deleted (D-01). No `js { browser() }` blocks remain in any module build file.
+- **INFRA-02 payoff visible:** the plugin block in each module now reads as a role declaration (D-06). A future KMP module just needs `plugins { id("recipe.kotlin.multiplatform") }` + sourceSet declarations — no target/SDK copy-pasting.
+- **INFRA-06 structural prerequisite delivered:** recipe.compose.multiplatform is applied ONLY to composeApp/, never to shared/, so Compose deps cannot leak transitively into the shared module's classpath.
+
+## Task Commits
+
+Each task was committed atomically (with `--no-verify` per parallel-executor protocol):
+
+1. **Task 1: Rewrite composeApp + shared build files, delete shared/src/jsMain/** — `d76dcea` (refactor)
+2. **Task 2: Rewrite server build file** — `d316a48` (refactor)
+
+_Note: no test/feat/refactor trio — the plan is marked `type=execute`, not `type=tdd`, and all work is build-script configuration (no production code to test)._
+
+## Files Created/Modified
+- `composeApp/build.gradle.kts` — rewritten: 4 recipe.* plugin IDs, androidMain/commonMain/jvmMain dep blocks, debugImplementation line
+- `shared/build.gradle.kts` — rewritten: 3 plugins (recipe.kotlin.multiplatform + recipe.quality + androidLibrary), explicitApi(), Framework baseName = "Shared" override, android {} retained
+- `server/build.gradle.kts` — rewritten: 2 recipe.* plugin IDs, application { mainClass + JVM args }, implementation(projects.shared)
+- `shared/src/jsMain/kotlin/dev/ulfrx/recipe/Platform.js.kt` — DELETED (D-01 — js target dropped)
+
+## Decisions Made
+- **`libs.versions.*` typed accessor used in module build.gradle.kts rather than `libs.findVersion(...)`** — PITFALL #1 restricts the typed accessor to precompiled plugins; module scripts have full access, so the typed form (`libs.versions.android.compileSdk.get().toInt()`) is correct and preserved from the prior version of `shared/build.gradle.kts`.
+- **Framework baseName override kept local to shared/** — only shared/ needs `"Shared"`; composeApp/ keeps the convention-plugin default `"ComposeApp"`. Hoisting the override into `recipe.kotlin.multiplatform` would require a plugin parameter for a single consumer — not worth the indirection.
+- **`android { }` block retained on shared/** — Open Question #1 in RESEARCH.md defers "do we actually need com.android.library on shared/?" to a future `recipe.android.library` convention plugin. Phase 1 keeps the block applied; a future plan may remove it.
+- **`libs.koin.android` placed in composeApp androidMain, not commonMain** — the `androidContext(...)` helper used by Plan 04's MainApplication lives in koin-android (JVM/Android artifact). commonMain keeps only platform-neutral deps.
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+One minor note (not a deviation, not a failure): `shared/build.gradle.kts` ended at 36 lines vs. the plan's informal `~35-line` target. The single-line delta is the non-negotiable explanatory comment above the `KotlinNativeTarget`/`Framework` block. The plan's `acceptance_criteria` does not set a line cap on `shared/` (only `composeApp/ ≤ 30` which passes at 28 and `server/ ≤ 20` which passes at 18), so all criteria are green.
+
+---
+
+**Total deviations:** 0
+**Impact on plan:** Plan executed as specified. All `<automated>` verify blocks pass (grep chain for each module + `tools/verify-no-version-literals.sh` + `tools/verify-shared-pure.sh`).
+
+## Issues Encountered
+None.
+
+## User Setup Required
+None - pure build-script refactor; no external service configuration required.
+
+## Parallel-Wave Coordination Notes
+
+This plan ran as a parallel executor in Wave 2 alongside Plans 02, 04, 05, 06. Per the wave-2 coordination note:
+
+- **No `./gradlew` commands executed in this plan.** The convention plugins referenced by `id("recipe.kotlin.multiplatform")` etc. are created by Plan 02 in a separate worktree; this worktree does NOT see those files. Gradle plugin resolution will succeed after all Wave 2 worktrees merge back to master and Plan 07 runs the full green-build gate.
+- **Verification is entirely grep-based**, matching the plan's `<automated>` specification. No runtime build invocation needed at this stage.
+
+## Next Phase Readiness
+
+Ready for downstream plans in Phase 01:
+- **Plan 04 (compose app skeleton)** can now rely on composeApp's `recipe.compose.multiplatform` application — Compose deps (compose.runtime/foundation/material3/ui/components.resources/lifecycle.*compose) flow in via the convention.
+- **Plan 05 (server skeleton)** can rely on server's `recipe.jvm.server` — Ktor server + Flyway + Postgres + serialization flow in via the convention; module only needs to declare `mainClass` and `projects.shared`.
+- **Plan 07 (invariant gate)** will validate the wired build via `./gradlew build` after all Wave 2 worktrees merge back.
+
+Downstream phases (Phase 02+ auth, Phase 05 recipe catalog, etc.) inherit a strict boundary: `shared/commonMain` enforces `explicitApi()` and carries no Compose / Ktor / SQLDelight deps. Any attempt to add forbidden imports will be caught by `tools/verify-shared-pure.sh`.
+
+## Self-Check: PASSED
+
+**Files verified:**
+- FOUND: `composeApp/build.gradle.kts` (28 lines, 4 recipe.* plugin IDs present, no androidTarget/iosArm64/js/nativeDistributions/^android{, libs.koin.android present)
+- FOUND: `shared/build.gradle.kts` (36 lines, 3 plugins present, explicitApi() present, `baseName = "Shared"` present, no js {, android {} retained)
+- FOUND: `server/build.gradle.kts` (18 lines, 2 recipe.* plugin IDs present, mainClass present, projects.shared present, no legacy aliases or deps)
+- MISSING (intentional): `shared/src/jsMain/` directory no longer exists
+
+**Commits verified:**
+- FOUND: `d76dcea` — refactor(01-03): apply recipe.* conventions to composeApp + shared, drop js
+- FOUND: `d316a48` — refactor(01-03): apply recipe.jvm.server + recipe.quality to server module
+
+**Verify scripts:**
+- `tools/verify-no-version-literals.sh` → exit 0 (OK: no version literals outside catalog)
+- `tools/verify-shared-pure.sh` → exit 0 (OK: shared/commonMain is pure)
+
+---
+*Phase: 01-project-infrastructure-module-wiring*
+*Plan: 03*
+*Completed: 2026-04-24*

.planning/phases/01-project-infrastructure-module-wiring/01-04-PLAN.md

@@ -0,0 +1,495 @@
+---
+phase: 01-project-infrastructure-module-wiring
+plan: 04
+type: execute
+wave: 2
+depends_on: [01, 02]
+files_modified:
+  - composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/Koin.kt
+  - composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/AppModule.kt
+  - composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/logging/Logging.kt
+  - composeApp/src/iosMain/kotlin/dev/ulfrx/recipe/di/KoinIos.kt
+  - composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/MainApplication.kt
+  - composeApp/src/androidMain/AndroidManifest.xml
+  - composeApp/src/jvmMain/kotlin/dev/ulfrx/recipe/main.kt
+  - composeApp/src/webMain/kotlin/dev/ulfrx/recipe/main.kt
+  - iosApp/iosApp/iOSApp.swift
+autonomous: true
+requirements: [INFRA-02]
+requirements_addressed: [INFRA-02]
+
+must_haves:
+  truths:
+    - "initKoin() is defined once in commonMain and called exactly once per platform entry point (no double-init — PITFALL #4)"
+    - "configureLogging() runs BEFORE initKoin() on every platform (so Koin module loading can use Kermit)"
+    - "App.kt (@Composable) never calls startKoin — Koin is started outside composition (anti-pattern guard in Pattern 4)"
+    - "appModule is an empty Koin module placeholder; Phase 2+ adds authModule, syncModule, etc."
+    - "Kermit tag is 'recipe' (D-15)"
+    - "iOS Swift side calls KoinIosKt.doInitKoin() inside iOSApp.init() — one call site"
+    - "Android uses MainApplication registered via android:name=\".MainApplication\" in AndroidManifest.xml"
+    - "wasmJs main() initializes Koin + logging BEFORE ComposeViewport { App() } (PITFALL #8 future-proof)"
+  artifacts:
+    - path: "composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/Koin.kt"
+      provides: "initKoin(config: KoinAppDeclaration? = null): KoinApplication helper invoking startKoin { modules(appModule) }"
+      exports: ["initKoin"]
+    - path: "composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/AppModule.kt"
+      provides: "Empty val appModule = module { } placeholder"
+      exports: ["appModule"]
+    - path: "composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/logging/Logging.kt"
+      provides: "configureLogging() — Logger.setTag(\"recipe\")"
+      exports: ["configureLogging"]
+    - path: "composeApp/src/iosMain/kotlin/dev/ulfrx/recipe/di/KoinIos.kt"
+      provides: "fun doInitKoin() { configureLogging(); initKoin() } — exported as Swift symbol KoinIosKt.doInitKoin"
+      exports: ["doInitKoin"]
+    - path: "composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/MainApplication.kt"
+      provides: "class MainApplication : Application() { onCreate → configureLogging(); initKoin { androidContext(this) } }"
+    - path: "composeApp/src/androidMain/AndroidManifest.xml"
+      provides: "<application android:name=\".MainApplication\" ...>"
+      contains: "android:name=\".MainApplication\""
+    - path: "composeApp/src/jvmMain/kotlin/dev/ulfrx/recipe/main.kt"
+      provides: "Desktop main() invoking configureLogging() + initKoin() before application { Window { App() } }"
+    - path: "composeApp/src/webMain/kotlin/dev/ulfrx/recipe/main.kt"
+      provides: "Wasm main() invoking configureLogging() + initKoin() before ComposeViewport { App() } (PITFALL #8)"
+    - path: "iosApp/iosApp/iOSApp.swift"
+      provides: "Swift @main struct with init() { KoinIosKt.doInitKoin() } and import ComposeApp"
+      contains: "import ComposeApp", "KoinIosKt.doInitKoin()"
+  key_links:
+    - from: "iosApp/iosApp/iOSApp.swift"
+      to: "composeApp/src/iosMain/kotlin/dev/ulfrx/recipe/di/KoinIos.kt"
+      via: "Kotlin top-level fun doInitKoin → Swift symbol KoinIosKt.doInitKoin()"
+      pattern: "KoinIosKt\\.doInitKoin\\(\\)"
+    - from: "composeApp/src/androidMain/AndroidManifest.xml"
+      to: "composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/MainApplication.kt"
+      via: "android:name=\".MainApplication\" attribute on <application>"
+      pattern: "android:name=\"\\.MainApplication\""
+    - from: "MainApplication.onCreate / iOSApp.init / jvm main / wasm main"
+      to: "composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/Koin.kt"
+      via: "initKoin() call"
+      pattern: "initKoin\\("
+---
+
+<objective>
+Wire the Koin + Kermit bootstrap across every composeApp platform entry point. Create the two commonMain source files (`di/Koin.kt`, `di/AppModule.kt`, `logging/Logging.kt`), the iOS Kotlin bridge (`iosMain/di/KoinIos.kt`), the Android `Application` subclass + manifest registration, modify the JVM + Wasm entry points to call `configureLogging() → initKoin()` before composition, and modify Swift's `iOSApp.swift` to call `KoinIosKt.doInitKoin()` inside `init()`. The Kermit tag is `"recipe"` (D-15); the Koin module is an empty placeholder (D-14) that Phase 2+ extends.
+
+Purpose: Phase 1 proves the DI + logging wiring is correct from day 1 so Phase 2 (Auth) can add `authModule`, Phase 4 can add `syncModule`, etc. without revisiting the bootstrap mechanics. PITFALL #4 (double-init on iOS) is neutralized by concentrating all startup into one `initKoin()` helper with a single call site per platform.
+
+Output: 9 files created or modified (6 new Kotlin files, 1 manifest edit, 2 existing entry-point rewrites, 1 Swift rewrite). No ViewModels yet — Phase 1 has no screens beyond the template.
+</objective>
+
+<execution_context>
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-CONTEXT.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-PATTERNS.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-VALIDATION.md
+@composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/App.kt
+@composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/MainActivity.kt
+@composeApp/src/androidMain/AndroidManifest.xml
+@composeApp/src/iosMain/kotlin/dev/ulfrx/recipe/MainViewController.kt
+@composeApp/src/jvmMain/kotlin/dev/ulfrx/recipe/main.kt
+@composeApp/src/webMain/kotlin/dev/ulfrx/recipe/main.kt
+@iosApp/iosApp/iOSApp.swift
+@CLAUDE.md
+
+<interfaces>
+<!-- These come from the Koin library (already wired via recipe.kotlin.multiplatform in Plan 02) -->
+
+From io.insert-koin:koin-core:
+```kotlin
+fun startKoin(appDeclaration: KoinAppDeclaration): KoinApplication  // top-level
+interface KoinApplication
+typealias KoinAppDeclaration = KoinApplication.() -> Unit
+```
+
+From io.insert-koin:koin-dsl:
+```kotlin
+fun module(createdAtStart: Boolean = false, moduleDeclaration: ModuleDeclaration): Module
+```
+
+From io.insert-koin:koin-android (androidMain only):
+```kotlin
+// package org.koin.android.ext.koin
+fun KoinApplication.androidContext(context: Context): KoinApplication
+```
+
+From co.touchlab:kermit:
+```kotlin
+object Logger {
+    fun setTag(tag: String)
+    // plus .i { }, .d { }, .e { }, .w { } methods on Logger companion
+}
+```
+
+From existing composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/App.kt (do NOT modify):
+```kotlin
+@Composable
+@Preview
+fun App() { /* template body — stays as-is */ }
+```
+
+From existing composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/MainActivity.kt (do NOT modify — sibling reference):
+```kotlin
+package dev.ulfrx.recipe
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+// class MainActivity : ComponentActivity() { ... setContent { App() } }
+```
+
+From existing composeApp/src/iosMain/kotlin/dev/ulfrx/recipe/MainViewController.kt (do NOT modify):
+```kotlin
+package dev.ulfrx.recipe
+import androidx.compose.ui.window.ComposeUIViewController
+fun MainViewController() = ComposeUIViewController { App() }
+```
+
+Current Android manifest shape (attributes to preserve when adding android:name):
+```xml
+<application
+    android:allowBackup="true"
+    android:icon="@mipmap/ic_launcher"
+    android:label="@string/app_name"
+    android:roundIcon="@mipmap/ic_launcher_round"
+    android:supportsRtl="true"
+    android:theme="@android:style/Theme.Material.Light.NoActionBar">
+```
+
+Current iOS Swift entry (to replace):
+```swift
+import SwiftUI
+@main
+struct iOSApp: App {
+    var body: some Scene { WindowGroup { ContentView() } }
+}
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Create commonMain DI + logging files and iOS Kotlin bridge</name>
+  <files>composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/Koin.kt, composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/AppModule.kt, composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/logging/Logging.kt, composeApp/src/iosMain/kotlin/dev/ulfrx/recipe/di/KoinIos.kt</files>
+  <read_first>
+    - .planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md lines 840-870 (Koin bootstrap canonical excerpts: initKoin + appModule + doInitKoin)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md lines 933-948 (Kermit bootstrap: Logger.setTag + init order)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md lines 675-690 (PITFALL #4 — single call site per platform, never from inside @Composable)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-PATTERNS.md lines 710-796 (pattern assignments for all 4 files)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-CONTEXT.md D-14 (Koin empty appModule), D-15 (Kermit tag "recipe")
+  </read_first>
+  <action>
+  Create 4 new files.
+
+  **File 1: `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/Koin.kt`**:
+
+  ```kotlin
+  package dev.ulfrx.recipe.di
+
+  import org.koin.core.KoinApplication
+  import org.koin.core.context.startKoin
+  import org.koin.dsl.KoinAppDeclaration
+
+  fun initKoin(config: KoinAppDeclaration? = null): KoinApplication = startKoin {
+      config?.invoke(this)
+      modules(appModule)
+  }
+  ```
+
+  **File 2: `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/AppModule.kt`**:
+
+  ```kotlin
+  package dev.ulfrx.recipe.di
+
+  import org.koin.dsl.module
+
+  // Phase 2 adds authModule; Phase 4 adds syncModule; Phase 5 adds catalogModule; etc.
+  val appModule = module {
+      // intentionally empty in Phase 1
+  }
+  ```
+
+  **File 3: `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/logging/Logging.kt`**:
+
+  ```kotlin
+  package dev.ulfrx.recipe.logging
+
+  import co.touchlab.kermit.Logger
+
+  fun configureLogging() {
+      Logger.setTag("recipe")
+      // Platform log writers (OSLog iOS, LogCat Android, System.out JVM/Wasm) install by default.
+  }
+  ```
+
+  **File 4: `composeApp/src/iosMain/kotlin/dev/ulfrx/recipe/di/KoinIos.kt`**:
+
+  ```kotlin
+  package dev.ulfrx.recipe.di
+
+  import dev.ulfrx.recipe.logging.configureLogging
+
+  fun doInitKoin() {
+      configureLogging()
+      initKoin()
+  }
+  ```
+
+  CRITICAL notes (PITFALL #4 / #10):
+  - The top-level `fun doInitKoin()` in file `KoinIos.kt` becomes the Swift-accessible symbol `KoinIosKt.doInitKoin()` (Kotlin generates `<FileName>Kt` for top-level declarations).
+  - `doInitKoin()` is the SINGLE iOS entry point. `MainViewController()` (the `ComposeUIViewController` factory) must NOT call `startKoin` or `initKoin` — it assumes Koin is already started.
+  - `configureLogging()` runs BEFORE `initKoin()` so Koin module loading can use Kermit.
+
+  Do NOT add any expect/actual declarations — the iOS bridge is a plain top-level function, and Kermit's multiplatform Logger handles the platform-specific writer selection internally.
+  </action>
+  <verify>
+    <automated>test -f composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/Koin.kt && test -f composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/AppModule.kt && test -f composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/logging/Logging.kt && test -f composeApp/src/iosMain/kotlin/dev/ulfrx/recipe/di/KoinIos.kt && grep -q 'package dev.ulfrx.recipe.di' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/Koin.kt && grep -q 'fun initKoin(config: KoinAppDeclaration? = null)' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/Koin.kt && grep -q 'startKoin' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/Koin.kt && grep -q 'modules(appModule)' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/Koin.kt && grep -q 'val appModule = module' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/AppModule.kt && grep -q 'Logger.setTag("recipe")' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/logging/Logging.kt && grep -q 'fun doInitKoin' composeApp/src/iosMain/kotlin/dev/ulfrx/recipe/di/KoinIos.kt && grep -q 'configureLogging()' composeApp/src/iosMain/kotlin/dev/ulfrx/recipe/di/KoinIos.kt && grep -q 'initKoin()' composeApp/src/iosMain/kotlin/dev/ulfrx/recipe/di/KoinIos.kt</automated>
+  </verify>
+  <acceptance_criteria>
+    - `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/Koin.kt` exists and contains package declaration `package dev.ulfrx.recipe.di`
+    - `Koin.kt` imports `org.koin.core.KoinApplication`, `org.koin.core.context.startKoin`, `org.koin.dsl.KoinAppDeclaration`
+    - `Koin.kt` defines exactly one top-level function `fun initKoin(config: KoinAppDeclaration? = null): KoinApplication` whose body is `startKoin { config?.invoke(this); modules(appModule) }`
+    - `AppModule.kt` exists and contains package declaration `package dev.ulfrx.recipe.di`
+    - `AppModule.kt` imports `org.koin.dsl.module`
+    - `AppModule.kt` declares `val appModule = module { }` (empty — D-14)
+    - `Logging.kt` exists and contains package declaration `package dev.ulfrx.recipe.logging`
+    - `Logging.kt` imports `co.touchlab.kermit.Logger`
+    - `Logging.kt` defines `fun configureLogging()` whose body calls `Logger.setTag("recipe")` (D-15 — exact string)
+    - `KoinIos.kt` exists and contains package declaration `package dev.ulfrx.recipe.di`
+    - `KoinIos.kt` imports `dev.ulfrx.recipe.logging.configureLogging`
+    - `KoinIos.kt` defines `fun doInitKoin()` whose body is `configureLogging(); initKoin()` in that exact order
+    - No file references `startKoin` directly outside `Koin.kt` (grep `startKoin` across composeApp/src returns only Koin.kt)
+    - `App.kt` is NOT modified (anti-pattern guard — startKoin never called from inside @Composable)
+  </acceptance_criteria>
+  <done>Koin + Kermit commonMain wiring is in place; iOS bridge exposes a Swift-callable `KoinIosKt.doInitKoin()`.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Create MainApplication.kt + register in AndroidManifest.xml</name>
+  <files>composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/MainApplication.kt, composeApp/src/androidMain/AndroidManifest.xml</files>
+  <read_first>
+    - composeApp/src/androidMain/AndroidManifest.xml (current 22-line content — target of edit)
+    - composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/MainActivity.kt (sibling reference for androidMain package + imports)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md lines 895-911 (canonical MainApplication.kt)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-PATTERNS.md lines 800-849 (MainApplication + manifest deltas)
+    - composeApp/build.gradle.kts (verify `libs.koin.android` was added to androidMain.dependencies in Plan 03)
+  </read_first>
+  <action>
+  Create one new file and edit one existing file.
+
+  **Create: `composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/MainApplication.kt`**:
+
+  ```kotlin
+  package dev.ulfrx.recipe
+
+  import android.app.Application
+  import dev.ulfrx.recipe.di.initKoin
+  import dev.ulfrx.recipe.logging.configureLogging
+  import org.koin.android.ext.koin.androidContext
+
+  class MainApplication : Application() {
+      override fun onCreate() {
+          super.onCreate()
+          configureLogging()
+          initKoin {
+              androidContext(this@MainApplication)
+          }
+      }
+  }
+  ```
+
+  CRITICAL:
+  - `package dev.ulfrx.recipe` (not `dev.ulfrx.recipe.android` — matches the existing `MainActivity.kt` sibling).
+  - `androidContext(this@MainApplication)` — the qualified `this` is required because the `initKoin { ... }` lambda's `this` is a `KoinApplication`, not the Application.
+  - `configureLogging()` runs FIRST, then `initKoin { ... }` — establishes the required order (PATTERNS.md "Init order on every platform entry").
+  - `org.koin.android.ext.koin.androidContext` comes from `io.insert-koin:koin-android` (catalog alias `libs.koin.android`, added to `composeApp/build.gradle.kts` androidMain deps in Plan 03).
+
+  **Edit: `composeApp/src/androidMain/AndroidManifest.xml`** — add `android:name=".MainApplication"` as the first attribute on the `<application>` element. Do NOT modify any other attribute or element.
+
+  Resulting `<application>` tag:
+
+  ```xml
+  <application
+          android:name=".MainApplication"
+          android:allowBackup="true"
+          android:icon="@mipmap/ic_launcher"
+          android:label="@string/app_name"
+          android:roundIcon="@mipmap/ic_launcher_round"
+          android:supportsRtl="true"
+          android:theme="@android:style/Theme.Material.Light.NoActionBar">
+  ```
+
+  The `<activity>` child element (with `android:name=".MainActivity"`) stays unchanged. The full XML structure (declarations, `<manifest>`, `<intent-filter>`) is preserved — only the single `android:name=".MainApplication"` attribute is added.
+  </action>
+  <verify>
+    <automated>test -f composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/MainApplication.kt && grep -q '^package dev.ulfrx.recipe$' composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/MainApplication.kt && grep -q 'class MainApplication : Application()' composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/MainApplication.kt && grep -q 'override fun onCreate()' composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/MainApplication.kt && grep -q 'configureLogging()' composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/MainApplication.kt && grep -q 'androidContext(this@MainApplication)' composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/MainApplication.kt && grep -q 'android:name="\.MainApplication"' composeApp/src/androidMain/AndroidManifest.xml && grep -q 'android:name="\.MainActivity"' composeApp/src/androidMain/AndroidManifest.xml</automated>
+  </verify>
+  <acceptance_criteria>
+    - `composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/MainApplication.kt` exists
+    - Package declaration is exactly `package dev.ulfrx.recipe` (matches sibling `MainActivity.kt`)
+    - Imports include `android.app.Application`, `dev.ulfrx.recipe.di.initKoin`, `dev.ulfrx.recipe.logging.configureLogging`, `org.koin.android.ext.koin.androidContext`
+    - Class declaration is `class MainApplication : Application()`
+    - `onCreate()` body calls `super.onCreate()` first, then `configureLogging()`, then `initKoin { androidContext(this@MainApplication) }` — in exactly that order
+    - `composeApp/src/androidMain/AndroidManifest.xml` contains literal `android:name=".MainApplication"` attribute on the `<application>` element
+    - `composeApp/src/androidMain/AndroidManifest.xml` still contains `android:name=".MainActivity"` on the `<activity>` element (unchanged)
+    - `composeApp/src/androidMain/AndroidManifest.xml` still contains `<intent-filter>` with MAIN action + LAUNCHER category (unchanged)
+    - `composeApp/src/androidMain/AndroidManifest.xml` top-level `<manifest>` declaration unchanged
+  </acceptance_criteria>
+  <done>Android Application subclass starts Koin + Kermit on process boot; manifest registers the subclass.</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Wire JVM + Wasm main() entries and Swift iOSApp.swift</name>
+  <files>composeApp/src/jvmMain/kotlin/dev/ulfrx/recipe/main.kt, composeApp/src/webMain/kotlin/dev/ulfrx/recipe/main.kt, iosApp/iosApp/iOSApp.swift</files>
+  <read_first>
+    - composeApp/src/jvmMain/kotlin/dev/ulfrx/recipe/main.kt (current content — target of rewrite)
+    - composeApp/src/webMain/kotlin/dev/ulfrx/recipe/main.kt (current content — target of rewrite)
+    - iosApp/iosApp/iOSApp.swift (current 11-line content — target of rewrite)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md lines 874-931 (Swift + Desktop + Wasm bootstrap)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md lines 733-747 (PITFALL #8 — Wasm init order)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-PATTERNS.md lines 852-937 (per-file deltas for these three files)
+  </read_first>
+  <action>
+  Replace three file contents.
+
+  **Replace: `composeApp/src/jvmMain/kotlin/dev/ulfrx/recipe/main.kt`**:
+
+  ```kotlin
+  package dev.ulfrx.recipe
+
+  import androidx.compose.ui.window.Window
+  import androidx.compose.ui.window.application
+  import dev.ulfrx.recipe.di.initKoin
+  import dev.ulfrx.recipe.logging.configureLogging
+
+  fun main() {
+      configureLogging()
+      initKoin()
+      application {
+          Window(
+              onCloseRequest = ::exitApplication,
+              title = "recipe",
+          ) {
+              App()
+          }
+      }
+  }
+  ```
+
+  **Replace: `composeApp/src/webMain/kotlin/dev/ulfrx/recipe/main.kt`**:
+
+  ```kotlin
+  package dev.ulfrx.recipe
+
+  import androidx.compose.ui.ExperimentalComposeUiApi
+  import androidx.compose.ui.window.ComposeViewport
+  import dev.ulfrx.recipe.di.initKoin
+  import dev.ulfrx.recipe.logging.configureLogging
+
+  @OptIn(ExperimentalComposeUiApi::class)
+  fun main() {
+      configureLogging()
+      initKoin()
+      ComposeViewport {
+          App()
+      }
+  }
+  ```
+
+  CRITICAL (PITFALL #8): `configureLogging()` and `initKoin()` MUST run BEFORE `ComposeViewport { }` — otherwise the first `koinViewModel<X>()` inside composition throws. Phase 1 has no ViewModels, so this is defensive — but the shape must be correct from day 1.
+
+  **Replace: `iosApp/iosApp/iOSApp.swift`** (Swift file, not Kotlin):
+
+  ```swift
+  import SwiftUI
+  import ComposeApp
+
+  @main
+  struct iOSApp: App {
+      init() {
+          KoinIosKt.doInitKoin()
+      }
+
+      var body: some Scene {
+          WindowGroup {
+              ContentView()
+          }
+      }
+  }
+  ```
+
+  CRITICAL:
+  - `import ComposeApp` — matches the framework basename set in `recipe.kotlin.multiplatform` (D-20 / PITFALL #10). The existing file does NOT import ComposeApp; add it.
+  - `init() { KoinIosKt.doInitKoin() }` — the Swift symbol `KoinIosKt` is auto-generated from Kotlin file `KoinIos.kt` in package `dev.ulfrx.recipe.di` (created in Task 1).
+  - `ContentView()` invocation stays unchanged; `ContentView.swift` already calls `MainViewControllerKt.MainViewController()` which returns a `ComposeUIViewController` — do NOT modify `ContentView.swift`.
+  - Do NOT call `startKoin` from `MainViewController()` — iOS init is centralized in `iOSApp.init()` to avoid PITFALL #4.
+  </action>
+  <verify>
+    <automated>grep -q '^package dev.ulfrx.recipe$' composeApp/src/jvmMain/kotlin/dev/ulfrx/recipe/main.kt && grep -q 'configureLogging()' composeApp/src/jvmMain/kotlin/dev/ulfrx/recipe/main.kt && grep -q 'initKoin()' composeApp/src/jvmMain/kotlin/dev/ulfrx/recipe/main.kt && grep -q 'Window(' composeApp/src/jvmMain/kotlin/dev/ulfrx/recipe/main.kt && grep -q '^package dev.ulfrx.recipe$' composeApp/src/webMain/kotlin/dev/ulfrx/recipe/main.kt && grep -q 'configureLogging()' composeApp/src/webMain/kotlin/dev/ulfrx/recipe/main.kt && grep -q 'initKoin()' composeApp/src/webMain/kotlin/dev/ulfrx/recipe/main.kt && grep -q 'ComposeViewport' composeApp/src/webMain/kotlin/dev/ulfrx/recipe/main.kt && grep -q 'import ComposeApp' iosApp/iosApp/iOSApp.swift && grep -q 'KoinIosKt.doInitKoin()' iosApp/iosApp/iOSApp.swift && grep -q 'init() {' iosApp/iosApp/iOSApp.swift</automated>
+  </verify>
+  <acceptance_criteria>
+    - `composeApp/src/jvmMain/kotlin/dev/ulfrx/recipe/main.kt` has `configureLogging()` on a line preceding `initKoin()`, and both precede `application {` (init order invariant)
+    - JVM main imports include `dev.ulfrx.recipe.di.initKoin` AND `dev.ulfrx.recipe.logging.configureLogging`
+    - JVM main preserves `Window(onCloseRequest = ::exitApplication, title = "recipe") { App() }`
+    - `composeApp/src/webMain/kotlin/dev/ulfrx/recipe/main.kt` has `configureLogging()` on a line preceding `initKoin()`, and both precede `ComposeViewport {` (PITFALL #8)
+    - Web main imports include `dev.ulfrx.recipe.di.initKoin` AND `dev.ulfrx.recipe.logging.configureLogging`
+    - Web main still has `@OptIn(ExperimentalComposeUiApi::class)` on `fun main()`
+    - `iosApp/iosApp/iOSApp.swift` contains exactly `import SwiftUI` AND `import ComposeApp` (both imports required)
+    - `iosApp/iosApp/iOSApp.swift` contains `init() {` followed by `KoinIosKt.doInitKoin()` — exactly one call
+    - `iosApp/iosApp/iOSApp.swift` preserves `@main struct iOSApp: App { ... body: some Scene { WindowGroup { ContentView() } } }`
+    - `MainViewController.kt` is NOT modified (the existing file returns `ComposeUIViewController { App() }` — Koin bootstrapped outside, PITFALL #4)
+    - `App.kt` is NOT modified (anti-pattern guard)
+  </acceptance_criteria>
+  <done>All four platform entry points call `configureLogging()` then `initKoin()` before composition; iOS Swift wires `KoinIosKt.doInitKoin()` exactly once in `init()`.</done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| Platform process start → DI container initialization | Each platform (Android onCreate, iOS App.init, JVM main, Wasm main) is a trusted bootstrap context; `initKoin()` is called once, from code we control. |
+| Kotlin top-level fun → Swift generated symbol | `KoinIos.kt` in package `dev.ulfrx.recipe.di` is compiled into the `ComposeApp.framework` Swift binary as `KoinIosKt.doInitKoin()`. No runtime risk — compile-time symbol mapping. |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-01-04-01 | Denial of Service | Koin double-init on iOS second cold launch (PITFALL #4) | mitigate | Only `iOSApp.init()` calls `KoinIosKt.doInitKoin()`. `MainViewController.kt` does NOT call `startKoin`. Task 3 acceptance criteria explicitly prohibits `startKoin` in `MainViewController.kt`. If Koin is accidentally started twice, `KoinApplicationAlreadyStartedException` fires on launch — visible and easy to diagnose. |
+| T-01-04-02 | Denial of Service | Wasm composition runs before Koin init (PITFALL #8) | mitigate | Task 3 explicitly orders `configureLogging() → initKoin() → ComposeViewport { }`. Phase 1 has no ViewModels so the symptom would not surface until Phase 5+, but the order is correct from day 1. |
+| T-01-04-03 | Tampering | `App.kt` calling `startKoin` from inside @Composable | mitigate | Task 1 + Task 3 acceptance criteria prohibit modification of `App.kt`. `App.kt` template preserves the anti-pattern-free shape. |
+| T-01-04-04 | Information Disclosure | Kermit logs leaking sensitive data | accept | Phase 1 has no sensitive data in the codebase (no auth, no user records, no PII). Kermit tag `"recipe"` is a build identifier, not a secret. Revisit when Phase 2 (Auth) introduces tokens — at that point, Kermit's `.i { }` lambda evaluation prevents accidental string concat of secrets if authors follow the lambda idiom. |
+| T-01-04-05 | Elevation of Privilege | Android manifest `android:name=".MainApplication"` registers custom Application subclass | accept | This is the standard Android lifecycle — `MainApplication.onCreate()` runs in the app's own process, same privilege as `MainActivity`. No escalation. |
+</threat_model>
+
+<verification>
+Phase-level verification for this plan:
+
+- Task 1, 2, 3 `<automated>` blocks pass (grep-based).
+- `tools/verify-no-version-literals.sh` continues to exit 0 (no build files modified).
+- `tools/verify-shared-pure.sh` continues to exit 0 (shared/ not touched).
+- Plan 07 runs `./gradlew build` and `./gradlew :composeApp:jvmTest` — those will exercise `initKoin()` via composition and catch any Koin config error.
+
+No `./gradlew` invocation is in this plan's `<automated>` blocks — Plan 05 + Plan 07 run the compile gates. Keep this plan's verification grep-fast (<5s total).
+</verification>
+
+<success_criteria>
+- 6 new commonMain/iosMain/androidMain Kotlin files created (Koin.kt, AppModule.kt, Logging.kt, KoinIos.kt, MainApplication.kt — and the init order is correct in each)
+- AndroidManifest.xml has `android:name=".MainApplication"` attribute added
+- JVM + Wasm main() entries call `configureLogging()` THEN `initKoin()` BEFORE composition
+- `iOSApp.swift` imports `ComposeApp` and calls `KoinIosKt.doInitKoin()` in `init()`
+- `App.kt` unmodified (anti-pattern guard)
+- `MainViewController.kt` unmodified (PITFALL #4 guard)
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/01-project-infrastructure-module-wiring/01-04-SUMMARY.md` recording: 6 files created + 3 files modified paths, Kermit tag set to `"recipe"`, Koin appModule content (empty), and confirmation that `App.kt` / `MainViewController.kt` / `ContentView.swift` were NOT modified.
+</output>

.planning/phases/01-project-infrastructure-module-wiring/01-04-SUMMARY.md

@@ -0,0 +1,138 @@
+---
+phase: 01-project-infrastructure-module-wiring
+plan: 04
+subsystem: client-bootstrap
+tags: [koin, kermit, di, logging, ios-bridge, android-application, wasm-bootstrap]
+requires:
+  - 01-02 (build-logic conventions providing Koin + Kermit dependencies via recipe.kotlin.multiplatform)
+  - 01-03 (composeApp/build.gradle.kts wired to convention plugin + libs.koin.android in androidMain)
+provides:
+  - "initKoin(config: KoinAppDeclaration?): KoinApplication — single bootstrap helper"
+  - "appModule: Koin Module — empty placeholder; Phase 2+ extends with authModule, syncModule, catalogModule"
+  - "configureLogging() — sets Kermit Logger.setTag(\"recipe\")"
+  - "KoinIosKt.doInitKoin() — Swift-callable iOS bridge"
+  - "MainApplication: Android Application subclass invoking configureLogging + initKoin on process boot"
+affects:
+  - "All future phases (2-11) plug Koin modules into appModule and call Logger.x { } via Kermit"
+  - "Phase 2 (Auth) will register authModule; Phase 4 (SyncEngine) will register syncModule singleton"
+tech-stack:
+  added: []
+  patterns:
+    - "Single initKoin() call site per platform entry point (PITFALL #4 — no double-init on iOS)"
+    - "configureLogging() ALWAYS precedes initKoin() so Koin module loading can use Kermit"
+    - "App.kt (@Composable) NEVER calls startKoin (Pattern 4 anti-pattern guard)"
+    - "iOS Kotlin bridge: top-level fun doInitKoin in KoinIos.kt → Swift symbol KoinIosKt.doInitKoin"
+    - "Wasm init order: configureLogging → initKoin → ComposeViewport (PITFALL #8)"
+key-files:
+  created:
+    - composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/Koin.kt
+    - composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/AppModule.kt
+    - composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/logging/Logging.kt
+    - composeApp/src/iosMain/kotlin/dev/ulfrx/recipe/di/KoinIos.kt
+    - composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/MainApplication.kt
+  modified:
+    - composeApp/src/androidMain/AndroidManifest.xml
+    - composeApp/src/jvmMain/kotlin/dev/ulfrx/recipe/main.kt
+    - composeApp/src/webMain/kotlin/dev/ulfrx/recipe/main.kt
+    - iosApp/iosApp/iOSApp.swift
+  unchanged_by_design:
+    - composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/App.kt  # anti-pattern guard: no startKoin in @Composable
+    - composeApp/src/iosMain/kotlin/dev/ulfrx/recipe/MainViewController.kt  # PITFALL #4: Koin started exclusively in iOSApp.init()
+    - iosApp/iosApp/ContentView.swift  # already wraps MainViewControllerKt.MainViewController()
+decisions:
+  - "Kermit tag = \"recipe\" (D-15) — exact string"
+  - "appModule is empty in Phase 1 (D-14); Phase 2+ adds modules"
+  - "Single iOS Koin call site is iOSApp.init() (PITFALL #4 mitigation)"
+  - "androidContext(this@MainApplication) — qualified `this` because initKoin lambda receiver is KoinApplication"
+metrics:
+  tasks_completed: 3
+  tasks_total: 3
+  files_created: 5
+  files_modified: 4
+  duration: ~10m
+  completed: 2026-04-24
+---
+
+# Phase 1 Plan 4: Koin + Kermit Bootstrap Wiring — Summary
+
+Wired the Koin DI container and Kermit structured logger across all four composeApp platform entry points (Android Application subclass, iOS SwiftUI App.init, JVM desktop main, Wasm browser main) with a single `initKoin()` helper in commonMain and an empty `appModule` placeholder that Phase 2+ extends.
+
+## What was built
+
+### Task 1 — commonMain DI + logging + iOS bridge (commit `cc5002d`)
+
+Created four files:
+
+- **`composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/Koin.kt`** — exports `fun initKoin(config: KoinAppDeclaration? = null): KoinApplication = startKoin { config?.invoke(this); modules(appModule) }`. The optional `config` lambda is how Android passes `androidContext(...)` and how Phase 2+ tests can inject overrides without touching the helper itself.
+- **`composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/AppModule.kt`** — declares `val appModule = module { }` (empty per D-14). Phase 2 adds `authModule`, Phase 4 adds `syncModule`, etc.
+- **`composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/logging/Logging.kt`** — `fun configureLogging() { Logger.setTag("recipe") }`. Kermit's per-platform writers (OSLog/LogCat/println) install themselves by default; setting the tag is the only required call.
+- **`composeApp/src/iosMain/kotlin/dev/ulfrx/recipe/di/KoinIos.kt`** — `fun doInitKoin() { configureLogging(); initKoin() }`. The top-level `fun` in file `KoinIos.kt` becomes the Swift-accessible symbol `KoinIosKt.doInitKoin()` automatically (Kotlin/Native generates `<FileName>Kt` for top-level decls).
+
+### Task 2 — Android MainApplication + manifest (commit `8cd608a`)
+
+- **`composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/MainApplication.kt`** — `class MainApplication : Application()` whose `onCreate()` calls `super.onCreate()`, then `configureLogging()`, then `initKoin { androidContext(this@MainApplication) }`. Qualified `this@MainApplication` is required because the `initKoin { }` lambda receiver is `KoinApplication`, not the `Application`.
+- **`composeApp/src/androidMain/AndroidManifest.xml`** — added `android:name=".MainApplication"` as the first attribute on `<application>`. All other attributes and the `<activity>`/`<intent-filter>` subtree preserved verbatim.
+
+### Task 3 — JVM + Wasm + Swift entry points (commit `fd3e7e1`)
+
+- **`composeApp/src/jvmMain/kotlin/dev/ulfrx/recipe/main.kt`** — converted `fun main() = application { ... }` (single-expression) into a body block: `configureLogging()` → `initKoin()` → `application { Window(title = "recipe") { App() } }`. Window title and exit handler preserved.
+- **`composeApp/src/webMain/kotlin/dev/ulfrx/recipe/main.kt`** — same init order before `ComposeViewport { App() }`. `@OptIn(ExperimentalComposeUiApi::class)` retained. Defensive against PITFALL #8 (Wasm composition running before DI is ready) — Phase 1 has no ViewModels so the symptom would not surface yet, but the shape is correct from day 1.
+- **`iosApp/iosApp/iOSApp.swift`** — added `import ComposeApp` (matches framework basename set by `recipe.kotlin.multiplatform`) and `init() { KoinIosKt.doInitKoin() }`. The `WindowGroup { ContentView() }` body is unchanged. `MainViewController.kt` and `ContentView.swift` were intentionally NOT modified — Koin is bootstrapped exclusively from `iOSApp.init()` (PITFALL #4 mitigation).
+
+## Init order invariant (every platform)
+
+```
+configureLogging()   → installs Kermit tag "recipe"
+initKoin()           → starts Koin with empty appModule
+[platform composition entry — application { } / ComposeViewport { } / ComposeUIViewController { } / setContent { }]
+```
+
+## Deviations from Plan
+
+None — plan executed exactly as written. All 3 tasks completed; all artifacts produced; all `<acceptance_criteria>` satisfied.
+
+## Confirmations (per `<output>` section of PLAN)
+
+- Kermit tag = `"recipe"` (D-15) — set in `configureLogging()`.
+- `appModule` content: empty (D-14) — `val appModule = module { }`.
+- `App.kt` NOT modified (anti-pattern guard).
+- `MainViewController.kt` NOT modified (PITFALL #4 guard — Koin started outside).
+- `ContentView.swift` NOT modified (already wraps `MainViewControllerKt.MainViewController()`).
+
+## Threat Mitigations Verified
+
+| Threat ID | Mitigation in delivered code |
+|-----------|------------------------------|
+| T-01-04-01 (Koin double-init iOS) | `KoinIosKt.doInitKoin()` is the only init call site on iOS; `MainViewController.kt` does not call `startKoin`. |
+| T-01-04-02 (Wasm init order) | webMain `main()` orders `configureLogging() → initKoin() → ComposeViewport { }`. |
+| T-01-04-03 (App.kt calling startKoin) | `App.kt` unchanged; verified no `startKoin` reference outside `Koin.kt`. |
+
+## Verification gates
+
+- All three task `<automated>` grep blocks passed.
+- No build files modified → `tools/verify-no-version-literals.sh` and `tools/verify-shared-pure.sh` remain at exit 0.
+- Compile gates (`./gradlew build`, `:composeApp:jvmTest`) deferred to Plan 07 per the verification block in 01-04-PLAN.md.
+
+## Commits
+
+- `cc5002d` — feat(01-04): add Koin + Kermit bootstrap commonMain + iOS bridge
+- `8cd608a` — feat(01-04): add Android MainApplication + manifest registration
+- `fd3e7e1` — feat(01-04): wire JVM + Wasm main + Swift iOSApp to bootstrap Koin + Kermit
+
+## Self-Check: PASSED
+
+Files verified to exist on disk:
+- FOUND: composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/Koin.kt
+- FOUND: composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/AppModule.kt
+- FOUND: composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/logging/Logging.kt
+- FOUND: composeApp/src/iosMain/kotlin/dev/ulfrx/recipe/di/KoinIos.kt
+- FOUND: composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/MainApplication.kt
+- FOUND: composeApp/src/androidMain/AndroidManifest.xml (modified, contains `android:name=".MainApplication"`)
+- FOUND: composeApp/src/jvmMain/kotlin/dev/ulfrx/recipe/main.kt (modified)
+- FOUND: composeApp/src/webMain/kotlin/dev/ulfrx/recipe/main.kt (modified)
+- FOUND: iosApp/iosApp/iOSApp.swift (modified)
+
+Commits verified in `git log`:
+- FOUND: cc5002d
+- FOUND: 8cd608a
+- FOUND: fd3e7e1

.planning/phases/01-project-infrastructure-module-wiring/01-05-PLAN.md

@@ -0,0 +1,498 @@
+---
+phase: 01-project-infrastructure-module-wiring
+plan: 05
+type: execute
+wave: 2
+depends_on: [01, 02]
+files_modified:
+  - server/src/main/kotlin/dev/ulfrx/recipe/Application.kt
+  - server/src/main/kotlin/dev/ulfrx/recipe/Database.kt
+  - server/src/main/resources/application.conf
+  - server/src/main/resources/db/migration/.gitkeep
+  - server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt
+autonomous: true
+requirements: [INFRA-02]
+requirements_addressed: [INFRA-02]
+
+must_haves:
+  truths:
+    - "GET /health returns 200 with Content-Type: application/json and body {\"status\":\"ok\"} (D-16)"
+    - "Server reads database.url / database.user / database.password from application.conf, with localhost defaults and env overrides via HOCON ${?X} syntax (PITFALL #5)"
+    - "Flyway runs Flyway.configure().dataSource(url, user, password).locations(\"classpath:db/migration\").load().migrate() during Application.module() startup"
+    - "Server fails loudly with IllegalStateException if Postgres is unreachable — the exception is thrown from Database.migrate() and NOT swallowed"
+    - "server/src/main/resources/db/migration/ directory exists (with .gitkeep) so Flyway.locations classpath resolution finds it even when empty"
+    - "ApplicationTest.kt has a test named 'health endpoint returns 200 with status ok' (or similar) that does NOT require a running Postgres — it composes routing in isolation"
+    - "Application.kt uses explicit Ktor imports (no wildcard imports) so D-11 allWarningsAsErrors is satisfied"
+  artifacts:
+    - path: "server/src/main/kotlin/dev/ulfrx/recipe/Application.kt"
+      provides: "main() → embeddedServer(Netty, SERVER_PORT, ::module).start(); Application.module() installs ContentNegotiation(json), invokes Database.migrate(this), and registers GET /health"
+      exports: ["main", "Application.module"]
+    - path: "server/src/main/kotlin/dev/ulfrx/recipe/Database.kt"
+      provides: "object Database { fun migrate(app: Application) } — reads HOCON config, runs Flyway, throws IllegalStateException on failure"
+      exports: ["Database"]
+    - path: "server/src/main/resources/application.conf"
+      provides: "HOCON config with ktor.deployment.port (8080 + ${?PORT}) and database.url/user/password (localhost defaults + ${?DATABASE_URL/USER/PASSWORD})"
+    - path: "server/src/main/resources/db/migration/.gitkeep"
+      provides: "Empty directory placeholder ensuring classpath:db/migration resolves for Flyway even when no SQL files exist yet"
+    - path: "server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt"
+      provides: "ApplicationTest with /health route assertion — composes routing without calling Database.migrate (no Postgres required)"
+  key_links:
+    - from: "server/src/main/kotlin/dev/ulfrx/recipe/Application.kt"
+      to: "server/src/main/kotlin/dev/ulfrx/recipe/Database.kt"
+      via: "Database.migrate(this) inside Application.module()"
+      pattern: "Database\\.migrate\\(this\\)"
+    - from: "server/src/main/kotlin/dev/ulfrx/recipe/Database.kt"
+      to: "server/src/main/resources/application.conf"
+      via: "app.environment.config.property(\"database.url\").getString() etc."
+      pattern: "config\\.property\\(\"database\\."
+    - from: "Flyway.configure().locations(...)"
+      to: "server/src/main/resources/db/migration/"
+      via: "classpath:db/migration"
+      pattern: "classpath:db/migration"
+---
+
+<objective>
+Deliver the server's running-but-empty state: a `GET /health` route returning `{"status":"ok"}`, HOCON-based config (`application.conf`) with env-var overrides, a `Database` object that runs Flyway against Postgres at boot time (failing loudly if Postgres is unreachable), and an updated `ApplicationTest.kt` that asserts the route in isolation without requiring a running database. Also scaffold `server/src/main/resources/db/migration/` as an empty directory so Flyway's classpath resolution succeeds before Phase 3 adds `V1__init.sql`.
+
+Purpose: This plan closes D-16 — Phase 3 drops its first migration into an already-working migrator; Phase 11 deploys to the homelab with the same Ktor HOCON config reading real env vars. The fail-loud contract for unreachable Postgres is load-bearing: it surfaces config errors at boot, not at first 5xx.
+
+Output: 2 Kotlin source files (Application.kt rewrite + Database.kt new), 1 HOCON config, 1 directory placeholder, 1 test rewrite.
+</objective>
+
+<execution_context>
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-CONTEXT.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-PATTERNS.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-VALIDATION.md
+@server/src/main/kotlin/dev/ulfrx/recipe/Application.kt
+@server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt
+@shared/src/commonMain/kotlin/dev/ulfrx/recipe/Constants.kt
+@CLAUDE.md
+
+<interfaces>
+<!-- Ktor 3.4.1 APIs (already in recipe.jvm.server via libs.ktor.*) -->
+
+From io.ktor.server.application:
+```kotlin
+interface Application
+interface ApplicationEnvironment {
+    val config: ApplicationConfig
+}
+interface ApplicationConfig {
+    fun property(path: String): ApplicationConfigValue
+    fun propertyOrNull(path: String): ApplicationConfigValue?
+}
+interface ApplicationConfigValue {
+    fun getString(): String
+}
+```
+
+From io.ktor.server.engine + io.ktor.server.netty:
+```kotlin
+fun embeddedServer(factory: ApplicationEngineFactory<...>, port: Int, host: String, module: Application.() -> Unit): EmbeddedServer
+object Netty : ApplicationEngineFactory<...>
+```
+
+From io.ktor.server.plugins.contentnegotiation + io.ktor.serialization.kotlinx.json:
+```kotlin
+object ContentNegotiation : BaseApplicationPlugin<...>
+fun ContentNegotiationConfig.json()  // installs kotlinx.serialization JSON converter
+```
+
+From io.ktor.server.routing + io.ktor.server.response:
+```kotlin
+fun Application.routing(block: Route.() -> Unit)
+fun Route.get(path: String, handler: suspend RoutingContext.() -> Unit)
+suspend fun ApplicationCall.respond(message: Any)
+```
+
+From io.ktor.server.testing (in testImplementation via recipe.jvm.server):
+```kotlin
+fun testApplication(block: suspend ApplicationTestBuilder.() -> Unit)
+// ApplicationTestBuilder provides:
+fun application(block: Application.() -> Unit)
+val client: HttpClient
+```
+
+From org.flywaydb.core:
+```kotlin
+object Flyway {
+    fun configure(): FluentConfiguration
+}
+// FluentConfiguration:
+fun dataSource(url: String, user: String, password: String): FluentConfiguration
+fun locations(vararg locations: String): FluentConfiguration
+fun baselineOnMigrate(b: Boolean): FluentConfiguration
+fun validateOnMigrate(b: Boolean): FluentConfiguration
+fun cleanDisabled(b: Boolean): FluentConfiguration
+fun load(): Flyway
+// Flyway instance:
+fun migrate(): MigrateResult
+```
+
+From kotlinx.serialization:
+```kotlin
+@Serializable
+```
+
+From org.slf4j:
+```kotlin
+object LoggerFactory {
+    fun getLogger(clazz: Class<*>): Logger
+}
+// org.slf4j.Logger: .info(msg: String, vararg args: Any), .error(msg: String, t: Throwable)
+```
+
+From shared/src/commonMain/kotlin/dev/ulfrx/recipe/Constants.kt (DO NOT modify):
+```kotlin
+package dev.ulfrx.recipe
+const val SERVER_PORT: Int = 8080  // or whatever current value is
+```
+
+Current server/src/main/kotlin/dev/ulfrx/recipe/Application.kt (to replace):
+```kotlin
+package dev.ulfrx.recipe
+import io.ktor.server.application.*
+import io.ktor.server.engine.*
+import io.ktor.server.netty.*
+import io.ktor.server.response.*
+import io.ktor.server.routing.*
+
+fun main() { embeddedServer(Netty, port = SERVER_PORT, host = "0.0.0.0", module = Application::module).start(wait = true) }
+fun Application.module() { routing { get("/") { call.respondText("Ktor: ${Greeting().greet()}") } } }
+```
+
+Current server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt (to replace):
+```kotlin
+// testRoot() asserts GET / returns "Ktor: ${Greeting().greet()}" — to be replaced with /health assertion
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Create application.conf + db/migration/.gitkeep + Database.kt</name>
+  <files>server/src/main/resources/application.conf, server/src/main/resources/db/migration/.gitkeep, server/src/main/kotlin/dev/ulfrx/recipe/Database.kt</files>
+  <read_first>
+    - .planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md lines 988-1023 (canonical Database.kt — SLF4J variant since server uses Logback not Kermit)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md lines 1029-1051 (canonical application.conf HOCON)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md lines 692-717 (PITFALL #5 — `${?X}` env-var HOCON syntax)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md lines 719-724 (PITFALL #6 — Flyway runtime API, not plugin at build time)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-PATTERNS.md lines 990-1076 (Database.kt + application.conf + .gitkeep deltas)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-CONTEXT.md D-16 (server /health + Flyway + Postgres env overrides)
+    - server/build.gradle.kts (verify Plan 03 made `implementation(projects.shared)` present so `SERVER_PORT` is still reachable)
+  </read_first>
+  <action>
+  Create three files.
+
+  **File 1: `server/src/main/resources/application.conf`** (HOCON, 01-RESEARCH.md lines 1031-1051):
+
+  ```hocon
+  ktor {
+      deployment {
+          port = 8080
+          port = ${?PORT}
+      }
+      application {
+          modules = [ dev.ulfrx.recipe.ApplicationKt.module ]
+      }
+  }
+
+  database {
+      url = "jdbc:postgresql://localhost:5432/recipe"
+      url = ${?DATABASE_URL}
+      user = "recipe"
+      user = ${?DATABASE_USER}
+      password = "recipe"
+      password = ${?DATABASE_PASSWORD}
+  }
+  ```
+
+  CRITICAL (PITFALL #5):
+  - The two-line `url = "default"; url = ${?DATABASE_URL}` pattern is MANDATORY. `${?X}` is optional substitution — the second line is a no-op when `DATABASE_URL` is unset, and an override when it is set. Do NOT use `${X}` (required — crashes if unset) or `${X:default}` (wrong HOCON syntax).
+  - `"jdbc:postgresql://localhost:5432/recipe"`, `"recipe"`, `"recipe"` MATCH the docker-compose defaults in Plan 06 exactly — allows `docker compose up -d postgres && ./gradlew :server:run` with zero extra env config.
+  - `modules = [ dev.ulfrx.recipe.ApplicationKt.module ]` — even though `main()` uses programmatic `embeddedServer(...)` in Application.kt, this key is informational for Ktor's HOCON config loader and future EngineMain switching.
+
+  **File 2: `server/src/main/resources/db/migration/.gitkeep`** — empty zero-byte file. Git does not track empty directories; this marker ensures `server/src/main/resources/db/migration/` ships in the repo so `classpath:db/migration` resolves for Flyway. Phase 3 drops `V1__init.sql` here.
+
+  **File 3: `server/src/main/kotlin/dev/ulfrx/recipe/Database.kt`** (SLF4J variant — the server uses Logback already, NOT Kermit; RESEARCH.md lines 996-1023 + lines 1025-1027 explain the logger choice):
+
+  ```kotlin
+  package dev.ulfrx.recipe
+
+  import io.ktor.server.application.Application
+  import org.flywaydb.core.Flyway
+  import org.slf4j.LoggerFactory
+
+  object Database {
+      private val log = LoggerFactory.getLogger(Database::class.java)
+
+      fun migrate(app: Application) {
+          val url = app.environment.config.property("database.url").getString()
+          val user = app.environment.config.property("database.user").getString()
+          val password = app.environment.config.property("database.password").getString()
+
+          log.info("Connecting to {} as {} and running Flyway migrations", url, user)
+
+          runCatching {
+              Flyway.configure()
+                  .dataSource(url, user, password)
+                  .locations("classpath:db/migration")
+                  .baselineOnMigrate(true)
+                  .validateOnMigrate(true)
+                  .cleanDisabled(true)
+                  .load()
+                  .migrate()
+          }.onFailure { ex ->
+              log.error("Flyway migration failed — cannot start server", ex)
+              throw IllegalStateException("Database unreachable or migration failed", ex)
+          }
+      }
+  }
+  ```
+
+  CRITICAL:
+  - `throw IllegalStateException(...)` is the fail-loud contract (D-16). Do NOT wrap it in a generic `try { } catch { return false }` — the server MUST refuse to start if the DB is unreachable.
+  - Use SLF4J (`LoggerFactory.getLogger(...)`), NOT Kermit. The server has Logback wired via `logback.xml`; Kermit is the CLIENT logger (composeApp only).
+  - Log credentials are NOT logged — only `url` and `user` appear in the info line. `password` is used for `dataSource(...)` only.
+  - `cleanDisabled = true` prevents accidental `flywayClean` wiping tables in dev/prod (matches `recipe.jvm.server.gradle.kts` plugin config — double-enforcement).
+  - `baselineOnMigrate = true` tolerates an existing DB with no Flyway history (defensive — Phase 1's DB is empty, Phase 11's homelab DB may pre-exist).
+  - `locations("classpath:db/migration")` points to the resource directory the `.gitkeep` keeps alive.
+  </action>
+  <verify>
+    <automated>test -f server/src/main/resources/application.conf && test -f server/src/main/resources/db/migration/.gitkeep && test -f server/src/main/kotlin/dev/ulfrx/recipe/Database.kt && grep -q 'port = 8080' server/src/main/resources/application.conf && grep -q 'port = \${?PORT}' server/src/main/resources/application.conf && grep -q 'url = "jdbc:postgresql://localhost:5432/recipe"' server/src/main/resources/application.conf && grep -q 'url = \${?DATABASE_URL}' server/src/main/resources/application.conf && grep -q 'user = "recipe"' server/src/main/resources/application.conf && grep -q 'user = \${?DATABASE_USER}' server/src/main/resources/application.conf && grep -q 'password = "recipe"' server/src/main/resources/application.conf && grep -q 'password = \${?DATABASE_PASSWORD}' server/src/main/resources/application.conf && grep -q 'object Database' server/src/main/kotlin/dev/ulfrx/recipe/Database.kt && grep -q 'org.flywaydb.core.Flyway' server/src/main/kotlin/dev/ulfrx/recipe/Database.kt && grep -q 'org.slf4j.LoggerFactory' server/src/main/kotlin/dev/ulfrx/recipe/Database.kt && grep -q 'cleanDisabled(true)' server/src/main/kotlin/dev/ulfrx/recipe/Database.kt && grep -q 'baselineOnMigrate(true)' server/src/main/kotlin/dev/ulfrx/recipe/Database.kt && grep -q 'throw IllegalStateException' server/src/main/kotlin/dev/ulfrx/recipe/Database.kt && grep -q 'classpath:db/migration' server/src/main/kotlin/dev/ulfrx/recipe/Database.kt</automated>
+  </verify>
+  <acceptance_criteria>
+    - `server/src/main/resources/application.conf` exists and contains exactly 6 env-var override lines (`port = ${?PORT}`, `url = ${?DATABASE_URL}`, `user = ${?DATABASE_USER}`, `password = ${?DATABASE_PASSWORD}` plus the two defaults for `port = 8080` and the DB trio)
+    - `application.conf` default values match docker-compose defaults: URL `jdbc:postgresql://localhost:5432/recipe`, user `recipe`, password `recipe`
+    - `application.conf` contains `modules = [ dev.ulfrx.recipe.ApplicationKt.module ]`
+    - `server/src/main/resources/db/migration/.gitkeep` exists (zero-byte file acceptable)
+    - `server/src/main/kotlin/dev/ulfrx/recipe/Database.kt` exists and declares `object Database`
+    - `Database.kt` imports `io.ktor.server.application.Application`, `org.flywaydb.core.Flyway`, `org.slf4j.LoggerFactory`
+    - `Database.kt` defines `fun migrate(app: Application)` that reads `app.environment.config.property("database.url|user|password").getString()`
+    - `Database.kt` body contains `Flyway.configure().dataSource(url, user, password).locations("classpath:db/migration").baselineOnMigrate(true).validateOnMigrate(true).cleanDisabled(true).load().migrate()` (all chained)
+    - `Database.kt` wraps the migration in `runCatching { ... }.onFailure { ... throw IllegalStateException(...) }` (fail-loud contract)
+    - `Database.kt` does NOT import `co.touchlab.kermit.Logger` (server uses SLF4J)
+    - `Database.kt` log.info line does NOT format the password value (only url + user in the format string)
+  </acceptance_criteria>
+  <done>HOCON config, Flyway migration resource dir, and fail-loud Database.migrate exist.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Rewrite Application.kt to install ContentNegotiation, call Database.migrate, expose /health</name>
+  <files>server/src/main/kotlin/dev/ulfrx/recipe/Application.kt</files>
+  <read_first>
+    - server/src/main/kotlin/dev/ulfrx/recipe/Application.kt (current 20 lines — target of rewrite)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md lines 952-985 (canonical Application.kt with ContentNegotiation + /health)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-PATTERNS.md lines 940-986 (Application.kt deltas)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-CONTEXT.md D-16 (sentinel JSON body for /health — Claude's discretion; use trivial `{"status":"ok"}`)
+    - shared/src/commonMain/kotlin/dev/ulfrx/recipe/Constants.kt (verify `SERVER_PORT` constant is defined)
+  </read_first>
+  <action>
+  Replace the entire content of `server/src/main/kotlin/dev/ulfrx/recipe/Application.kt` with:
+
+  ```kotlin
+  package dev.ulfrx.recipe
+
+  import io.ktor.serialization.kotlinx.json.json
+  import io.ktor.server.application.Application
+  import io.ktor.server.application.install
+  import io.ktor.server.engine.embeddedServer
+  import io.ktor.server.netty.Netty
+  import io.ktor.server.plugins.contentnegotiation.ContentNegotiation
+  import io.ktor.server.response.respond
+  import io.ktor.server.routing.get
+  import io.ktor.server.routing.routing
+  import kotlinx.serialization.Serializable
+
+  fun main() {
+      embeddedServer(Netty, port = SERVER_PORT, host = "0.0.0.0", module = Application::module)
+          .start(wait = true)
+  }
+
+  @Serializable
+  private data class Health(val status: String)
+
+  fun Application.module() {
+      install(ContentNegotiation) {
+          json()
+      }
+      Database.migrate(this)
+      configureRouting()
+  }
+
+  fun Application.configureRouting() {
+      routing {
+          get("/health") {
+              call.respond(Health(status = "ok"))
+          }
+      }
+  }
+  ```
+
+  DELETIONS:
+  - DROP the wildcard imports (`io.ktor.server.application.*`, `io.ktor.server.engine.*`, `io.ktor.server.netty.*`, `io.ktor.server.response.*`, `io.ktor.server.routing.*`) — replaced with explicit imports to satisfy D-11 allWarningsAsErrors (wildcard-unused warnings would fail the build)
+  - DROP `get("/") { call.respondText("Ktor: ${Greeting().greet()}") }` — replaced by `/health`
+
+  ADDITIONS:
+  - ADD `install(ContentNegotiation) { json() }` — required for `@Serializable` response serialization
+  - ADD `Database.migrate(this)` call inside `Application.module()` — fails loudly if Postgres unreachable
+  - ADD `@Serializable private data class Health(val status: String)` — the /health response shape
+  - ADD `Application.configureRouting()` extension function — extracted from `module()` so the test (Task 3) can compose routing WITHOUT invoking `Database.migrate()`
+
+  KEEP:
+  - `package dev.ulfrx.recipe` (unchanged)
+  - `fun main() { embeddedServer(Netty, port = SERVER_PORT, host = "0.0.0.0", module = Application::module).start(wait = true) }` — programmatic boot, unchanged shape
+  - `SERVER_PORT` constant is referenced from `shared/` (unchanged)
+
+  CRITICAL:
+  - The extraction of `configureRouting()` from `module()` is load-bearing for the test. Task 3 needs to test routing without calling `Database.migrate(this)` (which requires a real Postgres).
+  - `install(ContentNegotiation) { json() }` — MUST be installed before any route returns a `@Serializable` type. Both `module()` (for production) and the test (Task 3) must install it.
+  </action>
+  <verify>
+    <automated>grep -q '^package dev.ulfrx.recipe$' server/src/main/kotlin/dev/ulfrx/recipe/Application.kt && grep -q 'import io.ktor.server.plugins.contentnegotiation.ContentNegotiation' server/src/main/kotlin/dev/ulfrx/recipe/Application.kt && grep -q 'import io.ktor.serialization.kotlinx.json.json' server/src/main/kotlin/dev/ulfrx/recipe/Application.kt && grep -q 'import kotlinx.serialization.Serializable' server/src/main/kotlin/dev/ulfrx/recipe/Application.kt && ! grep -qE 'import io\.ktor\.server\.application\.\*' server/src/main/kotlin/dev/ulfrx/recipe/Application.kt && grep -q 'install(ContentNegotiation)' server/src/main/kotlin/dev/ulfrx/recipe/Application.kt && grep -q 'Database.migrate(this)' server/src/main/kotlin/dev/ulfrx/recipe/Application.kt && grep -q 'get("/health")' server/src/main/kotlin/dev/ulfrx/recipe/Application.kt && grep -q 'data class Health(val status: String)' server/src/main/kotlin/dev/ulfrx/recipe/Application.kt && grep -q 'fun Application.configureRouting()' server/src/main/kotlin/dev/ulfrx/recipe/Application.kt && ! grep -q 'call.respondText' server/src/main/kotlin/dev/ulfrx/recipe/Application.kt && grep -q 'embeddedServer(Netty, port = SERVER_PORT' server/src/main/kotlin/dev/ulfrx/recipe/Application.kt</automated>
+  </verify>
+  <acceptance_criteria>
+    - `Application.kt` has no wildcard imports (`import X.*`) — every `io.ktor.*` import is explicit
+    - `Application.kt` imports `io.ktor.server.plugins.contentnegotiation.ContentNegotiation`, `io.ktor.serialization.kotlinx.json.json`, `kotlinx.serialization.Serializable`
+    - `Application.kt` defines `@Serializable private data class Health(val status: String)`
+    - `Application.module()` body calls, in order: `install(ContentNegotiation) { json() }`, then `Database.migrate(this)`, then `configureRouting()`
+    - `Application.configureRouting()` is a top-level extension function containing the `routing { get("/health") { call.respond(Health(status = "ok")) } }` block
+    - `main()` is unchanged from its current shape: `embeddedServer(Netty, port = SERVER_PORT, host = "0.0.0.0", module = Application::module).start(wait = true)`
+    - No `get("/")` route remains (template root greeting is removed)
+    - No `call.respondText(...)` in Application.kt (Health returned via `call.respond(Health(...))` → kotlinx-json serializer)
+  </acceptance_criteria>
+  <done>Application.kt installs ContentNegotiation, runs Flyway at boot, exposes /health JSON, splits routing for testability.</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Rewrite ApplicationTest.kt to assert GET /health returns 200 with JSON body</name>
+  <files>server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt</files>
+  <read_first>
+    - server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt (current 20-line content — target of rewrite)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md lines 1084-1125 (canonical ApplicationTest.kt variant)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-PATTERNS.md lines 1079-1125 (test delta explaining the no-Postgres-required refactor)
+    - server/src/main/kotlin/dev/ulfrx/recipe/Application.kt (the freshly rewritten file — the test references `configureRouting()` from this file)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-VALIDATION.md lines 52-53 (automated command this test must satisfy: `./gradlew :server:test --tests "*Health*"`)
+  </read_first>
+  <action>
+  Replace the entire content of `server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt` with:
+
+  ```kotlin
+  package dev.ulfrx.recipe
+
+  import io.ktor.client.request.get
+  import io.ktor.client.statement.bodyAsText
+  import io.ktor.http.HttpStatusCode
+  import io.ktor.serialization.kotlinx.json.json
+  import io.ktor.server.application.install
+  import io.ktor.server.plugins.contentnegotiation.ContentNegotiation
+  import io.ktor.server.testing.testApplication
+  import kotlin.test.Test
+  import kotlin.test.assertEquals
+  import kotlin.test.assertTrue
+
+  class ApplicationTest {
+
+      @Test
+      fun `health endpoint returns 200 with status ok`() = testApplication {
+          application {
+              install(ContentNegotiation) {
+                  json()
+              }
+              configureRouting()
+          }
+          val response = client.get("/health")
+          assertEquals(HttpStatusCode.OK, response.status)
+          val body = response.bodyAsText()
+          assertTrue(body.contains("\"status\""), "expected body to contain status field, was: $body")
+          assertTrue(body.contains("\"ok\""), "expected body to contain ok value, was: $body")
+      }
+  }
+  ```
+
+  CRITICAL:
+  - The test invokes `configureRouting()` directly (extracted in Task 2) and does NOT call `Database.migrate(...)`. This is the KEY refactor: the test runs without a running Postgres, so `./gradlew :server:test` can succeed in CI / fresh clones.
+  - `install(ContentNegotiation) { json() }` is explicitly installed inside `application { }` — because the production `Application.module()` installs it, but the test composes only `configureRouting()` and must install the plugin itself.
+  - Imports are explicit (no wildcards) to satisfy D-11 allWarningsAsErrors.
+  - Assertions check for `"status"` and `"ok"` substrings in the JSON body — this is a structural check that works regardless of JSON field ordering.
+  - The test function name uses backtick-quoted natural-language identifier (`` `health endpoint returns 200 with status ok` ``) — standard Kotlin test-naming convention; the test will run via `./gradlew :server:test --tests "*health*"` or similar wildcards.
+
+  DELETIONS:
+  - DROP the existing `testRoot()` test — it asserted the template's `/` route response with `"Ktor: ${Greeting().greet()}"`, which no longer exists.
+  - DROP wildcard imports `io.ktor.client.request.*`, `io.ktor.client.statement.*`, `io.ktor.http.*`, `io.ktor.server.testing.*`, `kotlin.test.*`.
+  </action>
+  <verify>
+    <automated>test -f server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt && grep -q 'health endpoint returns 200' server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt && grep -q 'configureRouting()' server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt && ! grep -q 'Database.migrate' server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt && grep -q 'install(ContentNegotiation)' server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt && grep -q 'client.get("/health")' server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt && grep -q 'HttpStatusCode.OK' server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt && ! grep -q 'testRoot' server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt && ! grep -q 'Greeting().greet()' server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt && ! grep -qE 'import kotlin\.test\.\*' server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt && ./gradlew :server:test --tests "*health*" -q</automated>
+  </verify>
+  <acceptance_criteria>
+    - `ApplicationTest.kt` defines exactly one `@Test` method whose name contains `health` (case-insensitive)
+    - Test body invokes `configureRouting()` and does NOT invoke `Database.migrate(...)` (no-Postgres invariant)
+    - Test installs `ContentNegotiation { json() }` inside `application { ... }`
+    - Test asserts `response.status == HttpStatusCode.OK`
+    - Test asserts response body contains substring `"status"` AND `"ok"`
+    - No wildcard imports
+    - No reference to the removed `testRoot`, `Greeting`, or `respondText` — the old template test is fully replaced
+    - `./gradlew :server:test --tests "*health*"` runs and exits 0 (proves the test compiles AND passes; no Postgres needed because `configureRouting()` is composed directly)
+  </acceptance_criteria>
+  <done>/health test passes without requiring Postgres; old template test removed.</done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| HTTP client (unauthenticated) → GET /health | `/health` is intentionally unauthenticated (observability); reveals only `{"status":"ok"}` — no implementation detail, no version, no uptime. |
+| Ktor process → Postgres (JDBC) | HOCON defaults connect to `localhost:5432` with dev credentials. Real credentials arrive via `DATABASE_URL`/`DATABASE_USER`/`DATABASE_PASSWORD` env vars in Phase 11 homelab deploy. |
+| Developer → server/src/main/resources/application.conf | Committed to git; MUST contain only non-secret dev defaults. Real secrets never land in `application.conf`. |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-01-05-01 | Information Disclosure | `/health` endpoint leaking implementation details | mitigate | Body is `{"status":"ok"}` only — no version, no commit hash, no uptime, no DB state. Per ASVS V14 guidance + 01-RESEARCH.md § Security Domain. |
+| T-01-05-02 | Information Disclosure | `application.conf` committed with real secrets | mitigate | Defaults are non-secret localhost creds (`recipe/recipe/recipe`). Real secrets MUST arrive via `${?DATABASE_URL}` env override — never committed. Task 1 acceptance criteria enforces the six `${?X}` lines. |
+| T-01-05-03 | Tampering / Destruction | `flywayClean` wiping DB | mitigate | `cleanDisabled(true)` is set in BOTH `recipe.jvm.server.gradle.kts` (plugin CLI guard) AND in `Database.kt` runtime call (programmatic guard). Double-enforced per RESEARCH.md § Security Domain. |
+| T-01-05-04 | Denial of Service | Server silently runs with broken DB | mitigate | `Database.migrate()` throws `IllegalStateException` on any Flyway/JDBC error — server cannot start. Fail-loud contract (D-16) prevents stealth failure modes. |
+| T-01-05-05 | Error Handling (leaky stack traces) | 500 responses exposing internal stack | accept | No 500 handler registered yet; Ktor's default returns generic 500. Phase 2+ may introduce a StatusPages handler; Phase 1 scope is /health only which cannot 500 under normal operation. |
+| T-01-05-06 | Supply Chain | Flyway 12.4.0 + flyway-database-postgresql transitive deps | mitigate | Pinned versions via catalog (Plan 01). Postgres JDBC 42.7.10 pinned. No `latest.release` ranges. |
+</threat_model>
+
+<verification>
+Phase-level verification for this plan:
+
+- Task 3 `<automated>` runs `./gradlew :server:test --tests "*health*"` which proves:
+  - Application.kt compiles (confirms Task 2's explicit imports are correct)
+  - ApplicationTest.kt compiles (confirms Task 3's imports are correct)
+  - The /health route returns 200 with JSON containing `"status"` and `"ok"`
+  - Database.migrate is NOT required for the test (no Postgres needed in CI — D-11 test-runtime invariant)
+
+- `tools/verify-no-version-literals.sh` continues to exit 0 (no build files modified; server/build.gradle.kts was rewritten in Plan 03, untouched here).
+
+- Manual verification (deferred to Plan 07 or manual step):
+  - `docker compose up -d postgres && ./gradlew :server:run & sleep 5 && curl -sf http://localhost:8080/health | grep '"ok"'` — proves end-to-end boot + route + DB migration path.
+</verification>
+
+<success_criteria>
+- `server/src/main/resources/application.conf` exists with HOCON + 6 env overrides
+- `server/src/main/resources/db/migration/.gitkeep` exists
+- `server/src/main/kotlin/dev/ulfrx/recipe/Database.kt` runs Flyway with fail-loud contract
+- `server/src/main/kotlin/dev/ulfrx/recipe/Application.kt` installs ContentNegotiation, calls Database.migrate, exposes GET /health returning `{"status":"ok"}`
+- `server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt` passes via `./gradlew :server:test --tests "*health*"` WITHOUT a running Postgres
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/01-project-infrastructure-module-wiring/01-05-SUMMARY.md` recording: files created/modified, HOCON env-var pattern used (the `${?X}` two-line form), the fail-loud Database.migrate contract, and the `./gradlew :server:test` result.
+</output>

.planning/phases/01-project-infrastructure-module-wiring/01-05-SUMMARY.md

@@ -0,0 +1,132 @@
+---
+phase: 01-project-infrastructure-module-wiring
+plan: 05
+subsystem: infra
+tags: [ktor, flyway, hocon, postgres, slf4j, kotlinx-serialization]
+
+requires:
+  - phase: 01-project-infrastructure-module-wiring
+    provides: "recipe.jvm.server precompiled plugin (Plan 02) wires ktor-server-netty, ktor-server-content-negotiation, ktor-serialization-kotlinx-json, flyway-core, flyway-database-postgresql, postgresql JDBC, ktor-server-test-host, logback-classic. Plan 03 applied recipe.jvm.server + recipe.quality to server module and added implementation(projects.shared) so SERVER_PORT is reachable."
+provides:
+  - "Running-but-empty server: GET /health returns {\"status\":\"ok\"} with Content-Type application/json"
+  - "HOCON application.conf with localhost defaults + ${?ENV} overrides for PORT/DATABASE_URL/DATABASE_USER/DATABASE_PASSWORD"
+  - "Database.migrate() Flyway boot sequence with fail-loud IllegalStateException contract on unreachable Postgres"
+  - "server/src/main/resources/db/migration/ resource directory anchored by .gitkeep so classpath:db/migration resolves before Phase 3 adds V1__init.sql"
+  - "configureRouting() extension extracted from Application.module() so tests compose routing without invoking Database.migrate (no Postgres in CI)"
+affects: [phase-02-auth, phase-03-households, phase-05-recipe-catalog, phase-11-deployment]
+
+tech-stack:
+  added: [Flyway runtime API (flyway-core 12.x), HOCON env-var override pattern, SLF4J server-side logging]
+  patterns:
+    - "HOCON ${?ENV} two-line override pattern (PITFALL #5 mitigation)"
+    - "Fail-loud server boot: Database.migrate throws IllegalStateException on Flyway/JDBC failure"
+    - "Routing extracted to Application.configureRouting() extension so testApplication composes routing without DB dependency"
+    - "Server uses SLF4J/Logback (NOT Kermit — Kermit is client-only)"
+
+key-files:
+  created:
+    - server/src/main/kotlin/dev/ulfrx/recipe/Database.kt
+    - server/src/main/resources/application.conf
+    - server/src/main/resources/db/migration/.gitkeep
+  modified:
+    - server/src/main/kotlin/dev/ulfrx/recipe/Application.kt
+    - server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt
+
+key-decisions:
+  - "Use HOCON ${?ENV} optional substitution (two-line default + override) rather than ${ENV:default} (invalid HOCON) or ${ENV} (required, crashes on unset)"
+  - "Server logs via SLF4J/Logback, not Kermit — Kermit reserved for the multiplatform client"
+  - "Database.migrate is fail-loud: IllegalStateException on any Flyway error; no silent degraded mode"
+  - "cleanDisabled(true) is double-enforced (precompiled plugin CLI guard + programmatic Database.migrate guard)"
+  - "Extract Application.configureRouting() so /health test runs without Postgres — preserves D-11 invariant that ./gradlew :server:test passes in fresh clones / CI"
+  - "Default credentials in application.conf (recipe/recipe/recipe @ localhost:5432/recipe) match Plan 06 docker-compose for zero-config dev boot"
+
+patterns-established:
+  - "HOCON ${?ENV} override: every secret/per-env value gets a default line followed by ${?ENV_VAR} optional substitution"
+  - "Fail-loud infrastructure: critical boot operations (DB migration, future JWKS load) throw IllegalStateException rather than returning a status"
+  - "Routing extraction for testability: features expose Application.configureXxx() extensions; module() is the production composition root"
+
+requirements-completed: [INFRA-02]
+
+duration: ~1 min (executor work — implementation commits authored ahead of executor invocation)
+completed: 2026-04-24
+---
+
+# Phase 01 Plan 05: Server /health + Flyway + HOCON Boot Summary
+
+**Running-but-empty Ktor server: HOCON-configured Flyway boot with fail-loud Postgres contract, GET /health returning `{"status":"ok"}`, and a routing extraction that lets tests verify the route without a running database.**
+
+## Performance
+
+- **Duration:** Implementation commits span 2026-04-24 18:22:08 → 18:23:14 (~66s of authoring); executor verification + SUMMARY ~1 min
+- **Started:** 2026-04-24T18:22:08Z (commit 24018ef)
+- **Completed:** 2026-04-24T18:23:14Z (commit 59d0695)
+- **Tasks:** 3
+- **Files modified:** 5 (3 created, 2 modified)
+
+## Accomplishments
+
+- HOCON `application.conf` reads PORT + DATABASE_URL/USER/PASSWORD via the `${?ENV}` two-line override pattern; defaults match the Plan 06 docker-compose stack so `docker compose up -d postgres && ./gradlew :server:run` works with zero env config.
+- `Database.migrate(app: Application)` runs `Flyway.configure().dataSource(...).locations("classpath:db/migration").baselineOnMigrate(true).validateOnMigrate(true).cleanDisabled(true).load().migrate()` and throws `IllegalStateException` on any failure — D-16 fail-loud contract satisfied.
+- `db/migration/.gitkeep` keeps the resource directory in the repo so Flyway's classpath resolution succeeds before Phase 3 introduces the first SQL migration.
+- `Application.kt` rewritten with explicit Ktor imports (D-11 allWarningsAsErrors clean), installs `ContentNegotiation { json() }`, calls `Database.migrate(this)`, then delegates to `Application.configureRouting()` which exposes `GET /health → Health(status="ok")`.
+- `ApplicationTest.kt` rewritten to compose `configureRouting()` directly (skipping `Database.migrate`) so `./gradlew :server:test --tests "*health*"` passes without a running Postgres — required for fresh-clone / CI runs.
+
+## Task Commits
+
+Each task was committed atomically prior to executor invocation (commits already in branch history):
+
+1. **Task 1: HOCON config + db/migration/.gitkeep + Database.kt** — `24018ef` (feat)
+2. **Task 2: Application.kt rewrite (ContentNegotiation, Flyway boot, /health)** — `daefe6c` (refactor)
+3. **Task 3: ApplicationTest.kt rewrite (no-Postgres /health assertion)** — `59d0695` (test)
+
+**Plan metadata:** appended in this commit (docs).
+
+## Files Created/Modified
+
+- `server/src/main/resources/application.conf` (created) — HOCON config: ktor.deployment.port + database.{url,user,password} with `${?ENV}` overrides
+- `server/src/main/resources/db/migration/.gitkeep` (created) — anchors the Flyway classpath resource directory in git
+- `server/src/main/kotlin/dev/ulfrx/recipe/Database.kt` (created) — `object Database { fun migrate(app) }` with fail-loud Flyway invocation, SLF4J logging
+- `server/src/main/kotlin/dev/ulfrx/recipe/Application.kt` (modified) — explicit imports; installs ContentNegotiation; runs Database.migrate; delegates to configureRouting(); exposes GET /health returning serializable `Health(status)`
+- `server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt` (modified) — replaces template `testRoot()` with health-endpoint test that composes routing without DB
+
+## Decisions Made
+
+See `key-decisions` in frontmatter. Highlights:
+
+- HOCON `${?ENV}` optional substitution chosen over `${ENV}` (required) and `${ENV:default}` (invalid HOCON) per PITFALL #5.
+- Server logging via SLF4J/Logback (not Kermit) because Logback is already wired in `recipe.jvm.server` and Kermit is reserved for the multiplatform client.
+- `Application.configureRouting()` extension extracted to satisfy the no-Postgres-required invariant for `./gradlew :server:test`.
+
+## Deviations from Plan
+
+None — plan executed exactly as written. All artifacts match the plan's `must_haves` (truths, artifacts, key_links) verified against the filesystem; explicit imports satisfy D-11; `${?ENV}` lines all present; fail-loud contract intact; `Database.migrate` not referenced from the test.
+
+## Issues Encountered
+
+None.
+
+## User Setup Required
+
+None — no external service configuration required. Postgres for end-to-end boot is provided by the Plan 06 docker-compose stack; Plan 05's own success criteria (test passing without a running DB) require nothing from the operator.
+
+## Next Phase Readiness
+
+- Phase 2 (Auth) inherits a Ktor server with ContentNegotiation pre-installed, so JWT validation routes can return `@Serializable` DTOs immediately.
+- Phase 3 (Households) drops `V1__init.sql` into `server/src/main/resources/db/migration/`; the Flyway boot pathway is already validated.
+- Phase 11 (Deployment) inherits the HOCON `${?ENV}` pattern; homelab deploy configures `DATABASE_URL/USER/PASSWORD` via env vars without touching `application.conf`.
+- Manual end-to-end verification (`docker compose up -d postgres && ./gradlew :server:run && curl http://localhost:8080/health`) deferred to Plan 07 / manual smoke per the plan's verification section.
+
+## Self-Check: PASSED
+
+- File `server/src/main/resources/application.conf` — FOUND
+- File `server/src/main/resources/db/migration/.gitkeep` — FOUND
+- File `server/src/main/kotlin/dev/ulfrx/recipe/Database.kt` — FOUND
+- File `server/src/main/kotlin/dev/ulfrx/recipe/Application.kt` — FOUND
+- File `server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt` — FOUND
+- Commit `24018ef` (feat 01-05 Task 1) — FOUND in git log
+- Commit `daefe6c` (refactor 01-05 Task 2) — FOUND in git log
+- Commit `59d0695` (test 01-05 Task 3) — FOUND in git log
+
+---
+*Phase: 01-project-infrastructure-module-wiring*
+*Completed: 2026-04-24*

.planning/phases/01-project-infrastructure-module-wiring/01-06-PLAN.md

@@ -0,0 +1,308 @@
+---
+phase: 01-project-infrastructure-module-wiring
+plan: 06
+type: execute
+wave: 2
+depends_on: []
+files_modified:
+  - docker-compose.yml
+  - README.md
+autonomous: true
+requirements: [INFRA-02]
+requirements_addressed: [INFRA-02]
+
+must_haves:
+  truths:
+    - "docker-compose.yml at repo root launches postgres:16 with POSTGRES_DB=recipe / POSTGRES_USER=recipe / POSTGRES_PASSWORD=recipe — matching application.conf defaults exactly (D-17)"
+    - "The postgres service has a named volume (recipe-pgdata) so data survives container restarts"
+    - "The postgres service has a healthcheck using pg_isready that lets `docker compose up --wait` block until ready"
+    - "README.md has a 'Local development' section documenting the full dev loop (docker compose up, gradlew server:run, curl /health, gradlew spotlessApply)"
+    - "README.md no longer documents the dropped js target (D-01); wasmJs section is preserved"
+  artifacts:
+    - path: "docker-compose.yml"
+      provides: "postgres:16 service on port 5432 with named volume and healthcheck"
+      contains: "image: postgres:16", "POSTGRES_DB: recipe", "recipe-pgdata"
+    - path: "README.md"
+      provides: "Updated dev docs with Local development section, no js target docs"
+      contains: "Local development", "docker compose up -d postgres"
+  key_links:
+    - from: "docker-compose.yml"
+      to: "server/src/main/resources/application.conf"
+      via: "POSTGRES_DB=recipe / POSTGRES_USER=recipe / POSTGRES_PASSWORD=recipe defaults match HOCON localhost URL"
+      pattern: "POSTGRES_(DB|USER|PASSWORD):\\s*recipe"
+    - from: "README.md Local development section"
+      to: "server/src/main/kotlin/dev/ulfrx/recipe/Application.kt"
+      via: "curl http://localhost:8080/health"
+      pattern: "curl .+ /health"
+---
+
+<objective>
+Deliver the local developer ergonomics promised by D-17: a `docker-compose.yml` at the repo root running `postgres:16` with credentials + volume + healthcheck that align exactly with Plan 05's `application.conf` HOCON defaults, plus a "Local development" section in `README.md` documenting the dev loop. Drop the legacy `js` target documentation from `README.md` (D-01).
+
+Purpose: Phase 3 (Households / DB migrations) and Phase 11 (homelab deploy) both assume a working local Postgres is one command away. This plan closes that gap so `docker compose up -d postgres && ./gradlew :server:run` is a two-command dev loop. Authentik is NOT in this compose file — it lives on the user's homelab (CONTEXT.md D-17).
+
+Output: 1 new YAML file, 1 README edit. Entirely independent of Plans 01-05 in terms of files_modified — runs safely in parallel.
+</objective>
+
+<execution_context>
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-CONTEXT.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-PATTERNS.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-VALIDATION.md
+@README.md
+@CLAUDE.md
+
+<interfaces>
+<!-- Plan 05's application.conf expects these exact defaults -->
+
+From server/src/main/resources/application.conf (Plan 05 created — value match required):
+```hocon
+database {
+    url = "jdbc:postgresql://localhost:5432/recipe"
+    url = ${?DATABASE_URL}
+    user = "recipe"
+    user = ${?DATABASE_USER}
+    password = "recipe"
+    password = ${?DATABASE_PASSWORD}
+}
+```
+
+So docker-compose.yml MUST use:
+- `POSTGRES_DB: recipe` (matches `/recipe` in jdbc URL path)
+- `POSTGRES_USER: recipe`
+- `POSTGRES_PASSWORD: recipe`
+- port `5432:5432` (matches URL port)
+
+From README.md current content:
+- Section "Build and Run Web Application" (lines 63-85) documents BOTH `wasmJsBrowserDevelopmentRun` AND `jsBrowserDevelopmentRun` — the `js` part must go per D-01.
+- "Build and Run Android/Desktop/Server/iOS" sections are fine and stay.
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Create docker-compose.yml at repo root</name>
+  <files>docker-compose.yml</files>
+  <read_first>
+    - .planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md lines 1055-1077 (canonical docker-compose.yml)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-PATTERNS.md lines 1128-1158 (docker-compose pattern — matched defaults)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-CONTEXT.md D-17 (scope: postgres:16 + named volume; Authentik stays on homelab)
+    - (If Plan 05 is complete) server/src/main/resources/application.conf — verify credentials match
+  </read_first>
+  <action>
+  Create `docker-compose.yml` at the repo root with the following exact content:
+
+  ```yaml
+  services:
+    postgres:
+      image: postgres:16
+      container_name: recipe-postgres
+      environment:
+        POSTGRES_DB: recipe
+        POSTGRES_USER: recipe
+        POSTGRES_PASSWORD: recipe
+      ports:
+        - "5432:5432"
+      volumes:
+        - recipe-pgdata:/var/lib/postgresql/data
+      healthcheck:
+        test: ["CMD-SHELL", "pg_isready -U recipe -d recipe"]
+        interval: 5s
+        timeout: 5s
+        retries: 5
+
+  volumes:
+    recipe-pgdata:
+  ```
+
+  CRITICAL:
+  - `image: postgres:16` — pinned major version (D-17 specifies `postgres:16`).
+  - `POSTGRES_DB: recipe`, `POSTGRES_USER: recipe`, `POSTGRES_PASSWORD: recipe` — all MUST equal `"recipe"` (matches `application.conf` HOCON defaults from Plan 05 — `jdbc:postgresql://localhost:5432/recipe`, user `recipe`, password `recipe`).
+  - Named volume `recipe-pgdata` — survives container restart. Drop with `docker compose down -v` if you need a fresh DB.
+  - Healthcheck uses `pg_isready -U recipe -d recipe` so `docker compose up --wait postgres` or `depends_on: { postgres: { condition: service_healthy } }` works (Phase 3+ may add this).
+  - Port `5432:5432` — binds host port 5432 to container port 5432. Document in README that this is dev-local only.
+  - Do NOT add any other service (no Authentik — lives on user's homelab per D-17; no server — Ktor runs via Gradle on host for dev iteration).
+  - No `.env` file — D-17 / PATTERNS.md "Recommendation on `.env` vs inline": inline is fine for single-dev + matching application.conf defaults.
+
+  The file has NO leading version key (`version: "3"` etc. is legacy Docker Compose syntax — unnecessary in modern `docker compose v2`, and omitting it avoids a warning).
+  </action>
+  <verify>
+    <automated>test -f docker-compose.yml && grep -q 'image: postgres:16' docker-compose.yml && grep -q 'POSTGRES_DB: recipe' docker-compose.yml && grep -q 'POSTGRES_USER: recipe' docker-compose.yml && grep -q 'POSTGRES_PASSWORD: recipe' docker-compose.yml && grep -q 'recipe-pgdata:/var/lib/postgresql/data' docker-compose.yml && grep -q '"5432:5432"' docker-compose.yml && grep -q 'pg_isready -U recipe -d recipe' docker-compose.yml && grep -q '^volumes:$' docker-compose.yml && grep -q '  recipe-pgdata:' docker-compose.yml</automated>
+  </verify>
+  <acceptance_criteria>
+    - `docker-compose.yml` exists at repo root (`test -f docker-compose.yml`)
+    - `docker-compose.yml` contains `image: postgres:16` (not `postgres:latest`, not `postgres:15`, not `postgres`)
+    - `docker-compose.yml` contains `container_name: recipe-postgres`
+    - `docker-compose.yml` has `POSTGRES_DB: recipe`, `POSTGRES_USER: recipe`, `POSTGRES_PASSWORD: recipe` — all exactly `recipe` (lowercase, no variation)
+    - `docker-compose.yml` has port mapping `"5432:5432"`
+    - `docker-compose.yml` declares volume `recipe-pgdata` in both the service `volumes:` section AND the top-level `volumes:` section
+    - `docker-compose.yml` has a `healthcheck:` block using `pg_isready -U recipe -d recipe`
+    - `docker-compose.yml` does NOT contain a `version:` key (modern compose v2)
+    - `docker-compose.yml` does NOT define any service other than `postgres` (D-17: Authentik stays on homelab)
+    - `docker-compose.yml` credentials are the exact literals that Plan 05 hardcodes in `application.conf`: `grep -c '^\s*POSTGRES_\(DB\|USER\|PASSWORD\): recipe$' docker-compose.yml` returns `3` (DB, USER, PASSWORD all equal `recipe`). This is enforced on docker-compose.yml alone — the shared hardcoded contract (`recipe/recipe/recipe`) is stated identically in both plans' interfaces, so no cross-file lookup is required.
+  </acceptance_criteria>
+  <done>docker-compose.yml ships postgres:16 matching application.conf defaults; single-service compose file.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Add "Local development" section to README.md and drop js target docs</name>
+  <files>README.md</files>
+  <read_first>
+    - README.md (current 100-line content — target of edit)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-PATTERNS.md lines 1161-1169 (README delta summary)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-CONTEXT.md D-01 (drop js target), D-17 (docker-compose dev ergonomics)
+  </read_first>
+  <action>
+  Two edits to `README.md`:
+
+  **Edit A: Drop the `js` target section** — delete lines 77-85 of the current README (the "- for the JS target (slower, supports older browsers): - on macOS/Linux ... `./gradlew :composeApp:jsBrowserDevelopmentRun` - on Windows ..." block). Keep lines 68-76 (the wasmJs block). The entire "Build and Run Web Application" subsection should retain ONLY the wasmJs paragraph.
+
+  Resulting "Build and Run Web Application" subsection:
+
+  ```markdown
+  ### Build and Run Web Application
+
+  To build and run the development version of the web app, use the run configuration from the run widget
+  in your IDE's toolbar or run it directly from the terminal:
+
+  - for the Wasm target (faster, modern browsers):
+      - on macOS/Linux
+        ```shell
+        ./gradlew :composeApp:wasmJsBrowserDevelopmentRun
+        ```
+      - on Windows
+        ```shell
+        .\gradlew.bat :composeApp:wasmJsBrowserDevelopmentRun
+        ```
+  ```
+
+  **Edit B: Insert a new "Local development" section** AFTER the "Build and Run iOS Application" subsection and BEFORE the trailing `---` horizontal rule (around line 92 in the current file). The new section:
+
+  ```markdown
+  ### Local development
+
+  The server requires Postgres. A `docker-compose.yml` at the repo root ships a local Postgres
+  instance whose credentials match `application.conf` defaults (`recipe`/`recipe`/`recipe`).
+
+  Boot the database and server:
+
+  ```shell
+  docker compose up -d postgres
+  ./gradlew :server:run
+  ```
+
+  Verify the server is up:
+
+  ```shell
+  curl http://localhost:8080/health
+  # expected: {"status":"ok"}
+  ```
+
+  Environment overrides (optional — set any of these to override `application.conf` defaults):
+
+  - `DATABASE_URL` — JDBC URL (default `jdbc:postgresql://localhost:5432/recipe`)
+  - `DATABASE_USER` — DB user (default `recipe`)
+  - `DATABASE_PASSWORD` — DB password (default `recipe`)
+  - `PORT` — Ktor port (default `8080`)
+
+  Before committing, format all Kotlin + Gradle + Markdown files:
+
+  ```shell
+  ./gradlew spotlessApply
+  ```
+
+  The full check (Spotless + all tests across all targets):
+
+  ```shell
+  ./gradlew check
+  ```
+
+  Reset the local database (destroys the `recipe-pgdata` volume):
+
+  ```shell
+  docker compose down -v
+  ```
+  ```
+
+  Do NOT modify:
+  - The top-level introduction (lines 1-20)
+  - The "Build and Run Android Application" section
+  - The "Build and Run Desktop (JVM) Application" section
+  - The "Build and Run Server" section
+  - The "Build and Run iOS Application" section
+  - The trailing `---` + the learn-more links + the Compose/Wasm feedback paragraph
+
+  Keep the existing markdown heading level (`###`) for the new "Local development" section — matches the surrounding siblings.
+  </action>
+  <verify>
+    <automated>grep -q 'Local development' README.md && grep -q 'docker compose up -d postgres' README.md && grep -q 'curl http://localhost:8080/health' README.md && grep -q 'DATABASE_URL' README.md && grep -q 'gradlew spotlessApply' README.md && grep -q 'docker compose down -v' README.md && ! grep -q 'jsBrowserDevelopmentRun' README.md && grep -q 'wasmJsBrowserDevelopmentRun' README.md</automated>
+  </verify>
+  <acceptance_criteria>
+    - `README.md` contains the string `Local development` exactly once (new section heading)
+    - `README.md` contains `docker compose up -d postgres` as a documented command
+    - `README.md` contains `curl http://localhost:8080/health` as a documented command
+    - `README.md` lists all 4 env-var overrides: `DATABASE_URL`, `DATABASE_USER`, `DATABASE_PASSWORD`, `PORT`
+    - `README.md` contains `gradlew spotlessApply` (pre-commit formatter hint per D-10)
+    - `README.md` contains `gradlew check` (full-suite command)
+    - `README.md` contains `docker compose down -v` (volume reset hint)
+    - `README.md` does NOT contain `jsBrowserDevelopmentRun` (D-01 — js target dropped)
+    - `README.md` STILL contains `wasmJsBrowserDevelopmentRun` (wasmJs kept per D-01)
+    - All existing section headings ("Build and Run Android Application", "Build and Run Desktop (JVM) Application", "Build and Run Server", "Build and Run iOS Application") are preserved (unchanged)
+    - Top-of-file introduction (lines 1-20) is unchanged
+  </acceptance_criteria>
+  <done>README.md documents the dev loop (docker + gradle + curl + spotless + reset); legacy js target docs removed.</done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| Developer host → localhost:5432 Postgres | Dev-local; `docker-compose.yml` binds port on loopback via host mapping. Non-localhost access requires the developer's host to be reachable from outside the machine AND port 5432 firewall-open — normally not the case on a laptop. |
+| `docker-compose.yml` (committed to git) → POSTGRES_PASSWORD=recipe | Password is literal `recipe` — non-secret by design. Real homelab creds never land in this file; homelab has its own compose file or `.env` per Phase 11. |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-01-06-01 | Information Disclosure | Postgres port 5432 exposed on `0.0.0.0` | mitigate | Host-firewall is the developer's responsibility; the literal `"5432:5432"` mapping is Docker-default (binds to all host interfaces unless the host Docker is configured otherwise). README Local development section mentions "dev-local" usage but does NOT open a CVE window — this is standard dev practice. Phase 11 (homelab) uses a different compose file that does NOT expose the port publicly. |
+| T-01-06-02 | Information Disclosure | Committing real secrets to `docker-compose.yml` | mitigate | Only the literal `recipe/recipe/recipe` triple is in the file. Real homelab Postgres creds stay out of this compose file (Phase 11 will add a separate file or switch to env-var-driven compose). |
+| T-01-06-03 | Tampering | `docker compose down -v` accidentally destroying valuable data | accept | Dev-only volume (`recipe-pgdata`). If Phase 3+ develops real seed data, a developer running `down -v` repopulates from migrations — zero-trust default. |
+| T-01-06-04 | Denial of Service | `postgres:16` image unavailable from Docker Hub | accept | `docker pull postgres:16` is a standard image; outage would be transient and outside our control. Pinning to major version (not `:latest`) limits drift. |
+</threat_model>
+
+<verification>
+Phase-level verification for this plan:
+
+- Task 1 + Task 2 `<automated>` blocks pass.
+- `tools/verify-no-version-literals.sh` continues to exit 0 (no `.gradle.kts` files modified in this plan).
+- No `./gradlew` invocations — docker-compose + README are pure dev-ergonomics.
+
+Manual sanity check (optional, NOT blocking):
+- `docker compose config` parses the YAML without warnings.
+- `docker compose up -d postgres && sleep 3 && docker exec recipe-postgres pg_isready -U recipe -d recipe` returns "accepting connections".
+- `docker compose down` — cleans up afterward.
+</verification>
+
+<success_criteria>
+- `docker-compose.yml` exists at repo root with a single `postgres:16` service + named volume + healthcheck
+- Credentials in `docker-compose.yml` match `application.conf` defaults exactly (`recipe/recipe/recipe`)
+- `README.md` has a new "Local development" section
+- `README.md` no longer documents the `js` target
+- `README.md` still documents `wasmJs` target
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/01-project-infrastructure-module-wiring/01-06-SUMMARY.md` recording: docker-compose content summary (one service, one volume), credential match with Plan 05, README sections added/removed, and any deviation from D-17 (expected: none).
+</output>

.planning/phases/01-project-infrastructure-module-wiring/01-06-SUMMARY.md

@@ -0,0 +1,155 @@
+---
+phase: 01-project-infrastructure-module-wiring
+plan: 06
+subsystem: dev-ergonomics
+tags: [docker-compose, postgres, readme, local-dev, infra]
+dependency_graph:
+  requires: []
+  provides:
+    - "Local Postgres 16 dev instance matching application.conf HOCON defaults (recipe/recipe/recipe)"
+    - "Named volume recipe-pgdata for persistence across container restarts"
+    - "pg_isready healthcheck enabling docker compose up --wait usage"
+    - "README 'Local development' section documenting the two-command dev loop"
+  affects:
+    - "server/src/main/resources/application.conf (Plan 05 — credentials match contract)"
+    - "Phase 3 (Households + DB migrations) — depends on a working local Postgres"
+    - "Phase 11 (homelab deployment) — separate compose config will diverge from this dev-local one"
+tech_stack:
+  added:
+    - "postgres:16 (Docker image, pinned major version)"
+  patterns:
+    - "Dev-local compose file committed to repo (non-secret literal creds)"
+    - "Healthcheck via pg_isready gating sequencing"
+    - "Named Docker volume for data persistence"
+key_files:
+  created:
+    - "docker-compose.yml"
+  modified:
+    - "README.md"
+decisions:
+  - "Kept it single-service: postgres only. Authentik stays on homelab (CONTEXT.md D-17); Ktor server runs via Gradle on the dev host for fast iteration."
+  - "Pinned postgres:16 (not :latest, not :15) matching D-17 scope statement."
+  - "No version: key in compose file — modern docker compose v2 treats it as legacy and emits warnings."
+  - "No .env file in this plan — inline POSTGRES_* is fine for single-dev + matching application.conf defaults (D-17 / PATTERNS.md recommendation)."
+  - "Port binding 5432:5432 is dev-local; README calls it out. Phase 11 homelab compose will use a different approach."
+metrics:
+  duration_seconds: 92
+  duration_human: "1m32s"
+  tasks_completed: 2
+  files_created: 1
+  files_modified: 1
+  completed_at: "2026-04-24T16:22:48Z"
+---
+
+# Phase 01 Plan 06: Dev ergonomics — docker-compose + README Local development summary
+
+Shipped `docker-compose.yml` (single postgres:16 service, named volume, healthcheck — credentials matching Plan 05's `application.conf` HOCON defaults exactly) and a "Local development" README section documenting the `docker compose up -d postgres && ./gradlew :server:run && curl /health` dev loop, while dropping the legacy `js` target docs per D-01.
+
+## What was built
+
+### docker-compose.yml (20 lines)
+
+- `services.postgres`:
+  - `image: postgres:16` (pinned major version)
+  - `container_name: recipe-postgres`
+  - `environment`: `POSTGRES_DB / POSTGRES_USER / POSTGRES_PASSWORD` all literal `recipe`
+  - `ports: "5432:5432"` (dev-local loopback via host Docker)
+  - `volumes: recipe-pgdata:/var/lib/postgresql/data` (persistence)
+  - `healthcheck`: `pg_isready -U recipe -d recipe` every 5s, timeout 5s, 5 retries
+- Top-level `volumes.recipe-pgdata:` (named volume declaration)
+- No `version:` key (modern compose v2)
+- No additional services (no Authentik — lives on user's homelab per D-17)
+
+### README.md edits
+
+**Edit A — dropped js target block** (lines 77-85 of previous README): the "- for the JS target (slower, supports older browsers)" paragraph and its two command blocks were deleted. The `wasmJs` paragraph is preserved intact.
+
+**Edit B — inserted new "Local development" section** (after the iOS subsection, before the trailing `---` horizontal rule):
+
+- Two-command boot: `docker compose up -d postgres` + `./gradlew :server:run`
+- Smoke test: `curl http://localhost:8080/health` with expected `{"status":"ok"}` response
+- Documented env-var overrides: `DATABASE_URL`, `DATABASE_USER`, `DATABASE_PASSWORD`, `PORT`
+- Pre-commit formatter hint: `./gradlew spotlessApply` (D-10)
+- Full-suite: `./gradlew check`
+- DB reset: `docker compose down -v` (destroys `recipe-pgdata`)
+
+All other existing headings (Android, Desktop/JVM, Server, iOS, web `wasmJs`) and the top introduction (lines 1-20) are unchanged. The trailing `---` + learn-more links paragraph is unchanged.
+
+## Credential-match contract with Plan 05
+
+The three compose env-vars are byte-identical to the literals in `server/src/main/resources/application.conf`:
+
+| compose env | application.conf |
+|-------------|------------------|
+| `POSTGRES_DB: recipe` | JDBC URL path `/recipe` |
+| `POSTGRES_USER: recipe` | `user = "recipe"` |
+| `POSTGRES_PASSWORD: recipe` | `password = "recipe"` |
+
+Verified via `grep -c '^\s*POSTGRES_\(DB\|USER\|PASSWORD\): recipe$' docker-compose.yml` → `3`.
+
+## Requirements addressed
+
+- **INFRA-02** — local development environment via `docker-compose.yml` and README dev loop documentation.
+
+## Tasks executed
+
+| Task | Name | Commit | Files |
+|------|------|--------|-------|
+| 1 | Create docker-compose.yml at repo root | `af4428f` | docker-compose.yml (new) |
+| 2 | Add "Local development" section to README.md and drop js target docs | `f691400` | README.md (modified) |
+
+## Deviations from Plan
+
+None — plan executed exactly as written. No Rule 1-3 auto-fixes, no checkpoints, no auth gates. Both `<automated>` verify blocks and every acceptance criterion passed on first attempt.
+
+## Threat surface scan
+
+No new network endpoints, auth paths, file access patterns, or schema changes at trust boundaries were introduced beyond what the plan's `<threat_model>` already covers (T-01-06-01..04). The `5432:5432` host binding and literal `recipe/recipe/recipe` credentials are the exact surface the plan's STRIDE register dispositions (`mitigate`/`accept`) already cover. No new flags.
+
+## Known stubs
+
+None. Both deliverables are complete — no placeholders, no TODOs, no empty data paths.
+
+## Verification
+
+**Task 1 automated check:**
+```
+test -f docker-compose.yml && grep -q 'image: postgres:16' ... && grep -q 'pg_isready -U recipe -d recipe' ... && grep -q '^volumes:$' ...
+→ VERIFY PASS
+grep -c '^\s*POSTGRES_\(DB\|USER\|PASSWORD\): recipe$' docker-compose.yml → 3
+```
+
+**Task 2 automated check:**
+```
+grep -q 'Local development' && grep -q 'docker compose up -d postgres' && grep -q 'curl http://localhost:8080/health' && grep -q 'DATABASE_URL' && grep -q 'gradlew spotlessApply' && grep -q 'docker compose down -v' && ! grep -q 'jsBrowserDevelopmentRun' && grep -q 'wasmJsBrowserDevelopmentRun'
+→ VERIFY PASS
+```
+
+**Acceptance criteria — Task 2 individually confirmed:**
+- `Local development` appears exactly once (section heading)
+- All 4 env-vars listed: `DATABASE_URL`, `DATABASE_USER`, `DATABASE_PASSWORD`, `PORT`
+- `gradlew check` present
+- Existing section headings (Android / Desktop (JVM) / Server / iOS) all preserved (grep `-c` → `1` each)
+- `jsBrowserDevelopmentRun` absent; `wasmJsBrowserDevelopmentRun` present
+- Top introduction (lines 1-20) unchanged
+
+## Manual sanity checks (optional, not blocking)
+
+Skipped per plan `<verification>`:
+- `docker compose config` YAML parse — not blocking per plan; docker may not be running in this worktree sandbox.
+- `docker compose up -d postgres && pg_isready` live test — not required; will be validated in Phase 3 when migrations land.
+
+## Notes for downstream plans
+
+- **Plan 05** (this wave) — credential contract lives in both files; any future change to the `recipe/recipe/recipe` triple MUST update both `application.conf` AND `docker-compose.yml` in the same commit.
+- **Phase 3** (Households + DB migrations) — can add `depends_on: { postgres: { condition: service_healthy } }` to a future `server` service in compose if we ever run the Ktor server in Docker; the healthcheck is already wired for it.
+- **Phase 11** (homelab deployment) — will ship a separate compose file (not editing this one) because homelab creds are secret and this file's creds are deliberately non-secret literals.
+
+## Self-Check: PASSED
+
+- `docker-compose.yml` exists at repo root: FOUND
+- `README.md` contains "Local development" section: FOUND
+- Commit `af4428f` (Task 1): FOUND in `git log`
+- Commit `f691400` (Task 2): FOUND in `git log`
+- All acceptance criteria from both tasks verified via grep
+- No file deletions in either commit

.planning/phases/01-project-infrastructure-module-wiring/01-07-PLAN.md

@@ -0,0 +1,297 @@
+---
+phase: 01-project-infrastructure-module-wiring
+plan: 07
+type: execute
+wave: 3
+depends_on: [01, 02, 03, 04, 05, 06]
+files_modified:
+  - shared/src/commonMain/kotlin/dev/ulfrx/recipe/shared/.gitkeep
+autonomous: true
+requirements: [INFRA-01, INFRA-02, INFRA-03, INFRA-06]
+requirements_addressed: [INFRA-01, INFRA-02, INFRA-03, INFRA-06]
+
+must_haves:
+  truths:
+    - "shared/src/commonMain/kotlin/dev/ulfrx/recipe/shared/ package scaffold exists (as .gitkeep marker) — INFRA-06 file-existence criterion"
+    - "./gradlew spotlessApply runs green (no files need formatting, OR all files are auto-formatted)"
+    - "./gradlew build succeeds across composeApp, server, shared — produces Android APK + iOS framework + server JAR (SC1)"
+    - "tools/verify-no-version-literals.sh exits 0 across the whole repo (SC2 / INFRA-01)"
+    - "tools/verify-ios-flags.sh exits 0 (SC3 / INFRA-03)"
+    - "tools/verify-shared-pure.sh exits 0 (SC5 / INFRA-06)"
+    - "./gradlew :composeApp:help emits 'recipe.kotlin.multiplatform' among applied plugins (SC4 / INFRA-02)"
+    - "./gradlew check runs spotlessCheck + all tests and exits 0"
+  artifacts:
+    - path: "shared/src/commonMain/kotlin/dev/ulfrx/recipe/shared/.gitkeep"
+      provides: "Empty package scaffold marker ensuring dev.ulfrx.recipe.shared package exists in git (Phase 2+ adds DTOs here)"
+    - path: "composeApp/build/outputs/apk/debug/composeApp-debug.apk"
+      provides: "Android debug APK artifact from ./gradlew build (SC1 proof)"
+    - path: "composeApp/build/bin/iosSimulatorArm64/debugFramework/ComposeApp.framework"
+      provides: "iOS framework artifact from ./gradlew build (SC1 proof)"
+  key_links:
+    - from: "./gradlew build"
+      to: "composeApp/build.gradle.kts + shared/build.gradle.kts + server/build.gradle.kts"
+      via: "recipe.* convention plugin application (Plan 03 refactor)"
+      pattern: "id\\(\"recipe\\."
+    - from: "./gradlew :composeApp:help"
+      to: "build-logic/src/main/kotlin/recipe.kotlin.multiplatform.gradle.kts"
+      via: "help task enumerates applied plugins"
+      pattern: "recipe\\.kotlin\\.multiplatform"
+---
+
+<objective>
+Create the final piece of INFRA-06 (empty `dev.ulfrx.recipe.shared` package scaffold under `shared/src/commonMain`) and then run the full phase verification gate: `./gradlew spotlessApply`, `./gradlew build`, the 3 `tools/verify-*.sh` invariant scripts, and `./gradlew check`. This is the "green build" moment that every prior plan in Phase 1 has been building toward.
+
+Purpose: Phase 1 success is defined by 5 ROADMAP success criteria (SC1-SC5) and 4 phase requirements (INFRA-01/02/03/06). Plans 01-06 delivered the files and refactors; this plan PROVES they integrate cleanly. Any regression here is a phase-completion blocker.
+
+Output: 1 `.gitkeep` placeholder + verification artifacts (APK + iOS framework) + proof of all 5 SCs + green `./gradlew check`.
+</objective>
+
+<execution_context>
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-CONTEXT.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-PATTERNS.md
+@.planning/phases/01-project-infrastructure-module-wiring/01-VALIDATION.md
+@tools/verify-no-version-literals.sh
+@tools/verify-shared-pure.sh
+@tools/verify-ios-flags.sh
+@CLAUDE.md
+
+<interfaces>
+<!-- Inputs from prior plans -->
+
+From Plan 01:
+- tools/verify-no-version-literals.sh — greps every *.gradle.kts for version literals (exits 0 if none except build-logic/build.gradle.kts)
+- tools/verify-shared-pure.sh — greps shared/src/commonMain/ for forbidden imports (exits 0 if none OR if directory absent)
+- tools/verify-ios-flags.sh — greps gradle.properties for the two iOS K/N flags (exits 0 if both present)
+
+From Plan 02:
+- build-logic/ with 5 precompiled plugins applied via settings.gradle.kts pluginManagement.includeBuild
+
+From Plan 03:
+- composeApp/, shared/, server/ build.gradle.kts applying recipe.* convention plugins
+
+From Plan 04:
+- composeApp common/iOS/Android/Desktop/Wasm entry points calling initKoin() + configureLogging()
+- iosApp/iosApp/iOSApp.swift calling KoinIosKt.doInitKoin()
+
+From Plan 05:
+- server Application.kt with /health + Database.migrate + ContentNegotiation + extracted configureRouting()
+- server ApplicationTest.kt passing without Postgres
+
+From Plan 06:
+- docker-compose.yml with postgres:16 + matching credentials
+- README.md with Local development section
+
+Phase gate commands (from 01-VALIDATION.md § Sampling Rate):
+- Quick: `./gradlew spotlessCheck :server:test :shared:jvmTest` (<30s)
+- Per-wave: `./gradlew build` (full — iOS framework link + Android APK + server JAR)
+- Phase gate: `./gradlew check` + manual curl + iOS simulator boot (simulator boot is a manual-only verification, 01-VALIDATION.md § Manual-Only)
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Create shared/ package scaffold placeholder</name>
+  <files>shared/src/commonMain/kotlin/dev/ulfrx/recipe/shared/.gitkeep</files>
+  <read_first>
+    - shared/src/commonMain/kotlin/dev/ulfrx/recipe/ (current contents: Greeting.kt, Platform.kt, Constants.kt — these are the TEMPLATE classes; they stay in place for now. Phase 2+ reorganizes.)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-CONTEXT.md D-19 (shared/commonMain stays pure; Phase 1 ships an empty package scaffold under dev.ulfrx.recipe.shared)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-PATTERNS.md lines 73-77 (shared package scaffold as .gitkeep marker)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md line 289 (shared/src/commonMain/kotlin/dev/ulfrx/recipe/shared/ NEW empty pkg)
+  </read_first>
+  <action>
+  Create an empty `.gitkeep` file at `shared/src/commonMain/kotlin/dev/ulfrx/recipe/shared/.gitkeep`. The parent directories do not exist yet — create them as part of the write.
+
+  The file content is zero bytes (empty). Its purpose is purely to make `dev.ulfrx.recipe.shared` package discoverable in git and in the IDE, ready for Phase 2+ DTO additions.
+
+  DO NOT:
+  - Touch or delete `shared/src/commonMain/kotlin/dev/ulfrx/recipe/Greeting.kt` — template class, stays
+  - Touch `Platform.kt` or `Constants.kt` — template classes, stay
+  - Add any other file under the new `shared/` package
+  - Add `expect`/`actual` declarations anywhere in shared/ (Phase 2+ scope)
+
+  Note the namespace layering: `shared/src/commonMain/kotlin/dev/ulfrx/recipe/` is the ROOT package (`dev.ulfrx.recipe` — where Constants.kt lives), and `shared/src/commonMain/kotlin/dev/ulfrx/recipe/shared/` is a SUB-package (`dev.ulfrx.recipe.shared` — where Phase 2+ DTOs will live). Both are valid; Phase 1 keeps the root-package template files and adds the sub-package placeholder.
+  </action>
+  <verify>
+    <automated>test -f shared/src/commonMain/kotlin/dev/ulfrx/recipe/shared/.gitkeep && test -d shared/src/commonMain/kotlin/dev/ulfrx/recipe/shared && test -f shared/src/commonMain/kotlin/dev/ulfrx/recipe/Greeting.kt && test -f shared/src/commonMain/kotlin/dev/ulfrx/recipe/Constants.kt && bash tools/verify-shared-pure.sh</automated>
+  </verify>
+  <acceptance_criteria>
+    - `shared/src/commonMain/kotlin/dev/ulfrx/recipe/shared/.gitkeep` exists (file test: `test -f`)
+    - Parent directory `shared/src/commonMain/kotlin/dev/ulfrx/recipe/shared` exists (directory test: `test -d`)
+    - Existing template files are preserved: `shared/src/commonMain/kotlin/dev/ulfrx/recipe/Greeting.kt`, `Platform.kt`, `Constants.kt` all still exist
+    - `tools/verify-shared-pure.sh` exits 0 — the `.gitkeep` file is not a `.kt` file so the grep skips it; the existing Greeting/Platform/Constants files still contain no forbidden imports
+  </acceptance_criteria>
+  <done>Empty package scaffold created; shared/ is ready for Phase 2+ DTOs.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Run Spotless apply + full ./gradlew build + invariant scripts</name>
+  <files></files>
+  <read_first>
+    - .planning/phases/01-project-infrastructure-module-wiring/01-VALIDATION.md lines 40-58 (Per-Task Verification Map — the exact commands this task runs)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-VALIDATION.md lines 27-34 (Sampling Rate — per-wave and phase-gate commands)
+    - .planning/phases/01-project-infrastructure-module-wiring/01-RESEARCH.md lines 1216-1241 (Success Criteria → Test Map)
+  </read_first>
+  <action>
+  This task is purely verification — no file modifications. Run the full phase gate in sequence. If any step fails, STOP and report the failure (do NOT silently swallow errors — a failure here means a prior plan regressed and must be fixed before Phase 1 completes).
+
+  Execute these commands IN ORDER. Each must exit 0 before proceeding to the next.
+
+  1. **Spotless apply** — auto-formats Kotlin + Gradle + Markdown files across all modules using `recipe.quality`'s ktlint rules:
+
+     ```bash
+     ./gradlew spotlessApply
+     ```
+
+     Expected: exit 0. If formatting changes any file, the change is benign (whitespace/indentation normalization); the subsequent `build` still passes.
+
+  2. **Invariant script: no version literals** — enforces INFRA-01 SC#2:
+
+     ```bash
+     bash tools/verify-no-version-literals.sh
+     ```
+
+     Expected: exit 0 + `OK: no version literals outside catalog.`
+
+  3. **Invariant script: shared/ is pure** — enforces INFRA-06 SC#5:
+
+     ```bash
+     bash tools/verify-shared-pure.sh
+     ```
+
+     Expected: exit 0 + `OK: shared/commonMain is pure.`
+
+  4. **Invariant script: iOS K/N flags present** — enforces INFRA-03 SC#3:
+
+     ```bash
+     bash tools/verify-ios-flags.sh
+     ```
+
+     Expected: exit 0 + `OK: iOS binary flags present.`
+
+  5. **Full Gradle build** — enforces SC1: produces Android APK + iOS framework + server JAR:
+
+     ```bash
+     ./gradlew build
+     ```
+
+     Expected: exit 0. This compiles every target (androidTarget, iosArm64, iosSimulatorArm64, jvm, wasmJs), links the iOS framework, packages the Android APK, and builds the server fat JAR.
+
+     After success, verify the two proof artifacts exist:
+
+     ```bash
+     test -f composeApp/build/outputs/apk/debug/composeApp-debug.apk
+     test -d composeApp/build/bin/iosSimulatorArm64/debugFramework/ComposeApp.framework
+     ```
+
+  6. **Convention plugin applied** — enforces SC4 / INFRA-02:
+
+     ```bash
+     ./gradlew :composeApp:help -q 2>&1 | grep -q 'recipe.kotlin.multiplatform' || ./gradlew :composeApp:tasks --all -q 2>&1 | grep -q 'recipe' || true
+     ```
+
+     Ktlint/help output verification: the `help` task for a module does not always enumerate plugins in recent Gradle versions. An alternative proof: the `./gradlew build` success in step 5 IS the proof that `recipe.kotlin.multiplatform` was applied — if the plugin hadn't applied, compilation would have failed at configuration time. Record the `./gradlew build` success as SC4 satisfaction if `help` output is ambiguous.
+
+  7. **Full check** — enforces full-suite green (spotlessCheck + all tests):
+
+     ```bash
+     ./gradlew check
+     ```
+
+     Expected: exit 0. This includes:
+     - `spotlessCheck` (Spotless verification)
+     - `:server:test` (runs the /health test from Plan 05 — no Postgres needed)
+     - `:composeApp:jvmTest` (template test, if present)
+     - `:shared:jvmTest` (template test, if present)
+     - Other platform tests as declared
+
+  If any of steps 1-7 fails, report exactly which step failed, the full error output, and STOP. The failure indicates a regression in one of Plans 01-06 that needs a `/gsd-plan-phase --gaps` cycle.
+
+  IMPORTANT:
+  - Do NOT add a `docker compose up postgres` step here. The `/health` test in Plan 05 composes `configureRouting()` directly WITHOUT `Database.migrate()` — no Postgres required. The only manual-only verification in Phase 1 is iOS simulator boot (01-VALIDATION.md § Manual-Only) which is deferred to a later human review.
+  - Do NOT run `./gradlew :server:run` here — it would call `Database.migrate()` which requires a running Postgres. That's a manual smoke check (documented in README Local development) not a CI/phase-gate check.
+  </action>
+  <verify>
+    <automated>./gradlew spotlessApply -q && bash tools/verify-no-version-literals.sh && bash tools/verify-shared-pure.sh && bash tools/verify-ios-flags.sh && ./gradlew build -q && test -f composeApp/build/outputs/apk/debug/composeApp-debug.apk && test -d composeApp/build/bin/iosSimulatorArm64/debugFramework/ComposeApp.framework && ./gradlew check -q</automated>
+  </verify>
+  <acceptance_criteria>
+    - `./gradlew spotlessApply` exits 0
+    - `tools/verify-no-version-literals.sh` exits 0 (SC2)
+    - `tools/verify-shared-pure.sh` exits 0 (SC5)
+    - `tools/verify-ios-flags.sh` exits 0 (SC3)
+    - `./gradlew build` exits 0 (SC1)
+    - `composeApp/build/outputs/apk/debug/composeApp-debug.apk` exists (SC1 Android artifact)
+    - `composeApp/build/bin/iosSimulatorArm64/debugFramework/ComposeApp.framework` directory exists (SC1 iOS artifact)
+    - `./gradlew check` exits 0 (full-suite verification — includes spotlessCheck + all tests including /health)
+    - The `./gradlew build` success implicitly proves SC4 (convention plugins applied) — if `recipe.kotlin.multiplatform` hadn't applied, the build would have failed during module configuration
+    - No `BUILD FAILED` string appears in the transcript
+  </acceptance_criteria>
+  <done>Phase 1 green — all 5 SCs and all 4 phase requirements (INFRA-01/02/03/06) verified by automated commands.</done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| Developer host → Gradle daemon | Same process; Gradle executes precompiled plugin code from `build-logic/` with full project access by design. |
+| Gradle build → Maven Central + Gradle Plugin Portal + Google | First `./gradlew build` downloads new artifacts (Koin, Kermit, Spotless, Flyway, Postgres JDBC, ktor content-negotiation, kotlinx-serialization). All versions pinned via catalog (Plan 01). |
+| iOS framework link → K/N compiler | Uses the two binary flags from gradle.properties (`gc=cms`, `objcDisposeOnMain=false`). Verified by `tools/verify-ios-flags.sh` (infrastructure check) + deferred iOS simulator boot check (manual). |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-01-07-01 | Denial of Service | `./gradlew build` downloading fresh deps, causing slow first-build | accept | First build may take 2-5 minutes as Koin/Kermit/Flyway/Postgres JDBC artifacts download (~80 MB per 01-RESEARCH.md § Runtime State Inventory). Subsequent builds use Gradle cache. Not a threat — just an expectation. |
+| T-01-07-02 | Tampering (supply chain) | Malicious transitive dep snuck in via new library | mitigate | Every new dep is pinned via catalog (Plan 01). Gradle verification metadata (`gradle/verification-metadata.xml`) is NOT enabled in Phase 1 — it's a future enhancement (Phase 11 CI setup). Risk accepted for Phase 1 single-dev local-build scope. |
+| T-01-07-03 | Destruction | Stale `build/` cache from template's `js` target outputs | mitigate | 01-RESEARCH.md § Runtime State Inventory notes developers should `./gradlew clean` once after Phase 1 to flush stale js target outputs. Task 2's `./gradlew build` will still succeed (Gradle ignores orphaned outputs), but developers may see bloated `build/` until a clean. README Local development section's `./gradlew check` implicitly clears enough; full `clean` is a nice-to-have. |
+| T-01-07-04 | Information Disclosure | `./gradlew build` log leaking env variables to console | accept | Server-side env vars (`DATABASE_URL` etc.) are only read at server boot, not during `./gradlew build`. The `/health` test composes routing without the DB. No secrets logged during build. |
+</threat_model>
+
+<verification>
+Phase-level verification for this plan — this IS the phase gate. Success here equals Phase 1 completion.
+
+Hard gate commands (all must exit 0):
+1. `./gradlew spotlessApply` — auto-format
+2. `tools/verify-no-version-literals.sh` — SC2 / INFRA-01
+3. `tools/verify-shared-pure.sh` — SC5 / INFRA-06
+4. `tools/verify-ios-flags.sh` — SC3 / INFRA-03
+5. `./gradlew build` — SC1, implicitly SC4 / INFRA-02
+6. `./gradlew check` — full-suite (spotlessCheck + all tests)
+
+Manual-only verifications (deferred per 01-VALIDATION.md § Manual-Only — NOT in Task 2 `<automated>`):
+- iOS simulator debug launch without legacy memory-manager warnings (requires Xcode + simulator)
+- Hot-reload dev loop on Desktop (interactive)
+- Server `/health` reachable via curl when Postgres is up (requires `docker compose up -d postgres` + `./gradlew :server:run`)
+
+These manual checks are recommended for the developer to run once; they are NOT gate-blocking for automated Phase 1 completion.
+</verification>
+
+<success_criteria>
+- `shared/src/commonMain/kotlin/dev/ulfrx/recipe/shared/.gitkeep` created
+- `./gradlew spotlessApply` green
+- All 3 `tools/verify-*.sh` scripts green
+- `./gradlew build` green + Android APK + iOS framework artifacts exist
+- `./gradlew check` green
+- No manual step required to pass this plan
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/01-project-infrastructure-module-wiring/01-07-SUMMARY.md` recording: the final 7 verification command outputs (exit codes), the size of the produced APK and iOS framework, the total `./gradlew build` time, and explicit confirmation that all 5 ROADMAP SCs (SC1-SC5) and 4 phase requirements (INFRA-01/02/03/06) are satisfied.
+
+Include in the summary a brief "Manual smoke checks to run later" list pointing at 01-VALIDATION.md § Manual-Only:
+- iOS simulator boot without legacy-MM warnings
+- Desktop hot-reload regression check
+- docker compose up postgres + server /health curl smoke test
+</output>

.planning/phases/01-project-infrastructure-module-wiring/01-CONTEXT.md

@@ -0,0 +1,144 @@
+# Phase 1: Project Infrastructure & Module Wiring - Context
+
+**Gathered:** 2026-04-24
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Stand up a KMP client + Ktor server whose build is "boring correct" from day 1 — Gradle version catalog, `build-logic/` convention plugins, iOS binary flags, a pure-Kotlin `shared/` module, foundational DI + logging bootstrap, and a minimally-running Ktor server — so every later phase slots into an already-configured system. Scope is infrastructure only; no feature logic, no auth, no DB tables, no UI beyond the template screens.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Target matrix
+- **D-01:** Drop the `js` target from `composeApp` and `shared`. Keep `wasmJs` as the strategic future-web bet (per PROJECT.md "possible future target").
+- **D-02:** Skip `iosX64` (Intel simulator / iPhone 5S-SE1). User is on Apple Silicon; no Intel-Mac contributors anticipated. Saves a full iOS compile per build.
+- **D-03:** Keep `jvm` target in `composeApp` for Desktop — **as a dev tool only** (hot-reload iteration loop). No Compose Desktop packaging config; not a release surface; not a v1 deliverable per PROJECT.md.
+- **D-04:** `shared/` ships the exact same target set as `composeApp`: `androidTarget, iosArm64, iosSimulatorArm64, jvm, wasmJs`. Plus `jvm` covers the server dependency.
+- **D-05:** Final target matrix repo-wide: `androidTarget, iosArm64, iosSimulatorArm64, jvm (Desktop + Server), wasmJs`.
+
+### Convention plugins (build-logic/)
+- **D-06:** Fine-grained plugin split (5 plugins). Each module applies only what it needs:
+  - `recipe.kotlin.multiplatform` — KMP target matrix + JVM toolchain + common-test deps
+  - `recipe.compose.multiplatform` — Compose Multiplatform setup (layers on top of KMP)
+  - `recipe.android.application` — Android-app-only config (namespace, compileSdk, minSdk, targetSdk from catalog)
+  - `recipe.jvm.server` — Ktor server JVM config
+  - `recipe.quality` — Spotless + ktlint + compiler strictness (reusable across all modules)
+- **D-07:** `recipe.kotlin.multiplatform` locks in: the D-05 target set, JVM toolchain, framework basename convention (`ComposeApp` / `Shared`), and `kotlin-test` as a common-test dep. New KMP modules apply this plugin and get everything.
+- **D-08:** JVM toolchain: **JVM 21** for server, desktop, and `shared/jvm`. Android bytecode target stays **JVM 11** (Android 7 minSdk constraint per template). Document this split in the convention plugin comments.
+- **D-09:** **All library versions live in `gradle/libs.versions.toml`.** Hard rule: grep for a non-test version literal inside any `build.gradle.kts` returns zero matches. This is INFRA-01 Success Criterion #2. Plugin versions also routed through the catalog (aliases).
+
+### Code-quality toolchain (recipe.quality plugin)
+- **D-10:** Minimal baseline — ship ktlint via **Spotless** only. Spotless handles Kotlin + Gradle files + markdown. Commands: `./gradlew spotlessCheck`, `./gradlew spotlessApply`. No Detekt, no Konsist in Phase 1.
+- **D-11:** `allWarningsAsErrors = true` everywhere (configured in `recipe.kotlin.multiplatform`). Any Kotlin/compiler warning fails the build; forces conscious suppression rather than silent drift.
+- **D-12:** `explicitApi()` **strict on `shared/` only**. `shared/` is structurally a library (consumed by both composeApp and server as a wire-format contract); `composeApp` and `server` are app code and stay on Kotlin defaults. Configured in `shared/build.gradle.kts` directly, not in the KMP plugin (app modules shouldn't inherit it).
+- **D-13:** **No git hooks.** `./gradlew check` is the local gate; CI gate deferred to Phase 11 (deployment). Local hooks add commit friction and are trivially bypassed.
+
+### Phase 1 "running-but-empty" scope — what's wired beyond the template
+- **D-14:** **Koin bootstrap.** Add Koin deps (`koin-core`, `koin-compose`, `koin-compose-viewmodel`) via `recipe.kotlin.multiplatform`. Call `startKoin { modules(appModule) }` inside `App()` for composeApp and `MainViewController` for iOS. Ship an empty `appModule` placeholder in `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/AppModule.kt`. Phase 2 adds `authModule`; Phase 4 adds `syncModule`; etc.
+- **D-15:** **Kermit logger bootstrap.** Add Kermit dep via `recipe.kotlin.multiplatform`. Set a single top-level tag (`"recipe"`) during app init. Available from day 1 for subsequent phases.
+- **D-16:** **Server: `/health` endpoint + Flyway scaffold + Postgres conn config.**
+  - `GET /health` returns 200 with a trivial JSON body.
+  - Flyway Gradle plugin + runtime dep wired into `server/build.gradle.kts` via `recipe.jvm.server`; `src/main/resources/db/migration/` directory created (empty). Phase 3 drops `V1__init.sql` into an already-working migrator.
+  - `application.conf` reads `DATABASE_URL`, `DATABASE_USER`, `DATABASE_PASSWORD` from env with localhost defaults matching docker-compose.
+  - Server starts and connects to Postgres on boot; fails loudly (not silently) if Postgres is unreachable.
+- **D-17:** **`docker-compose.yml` at repo root** defines a `postgres:16` service with a named volume. `README.md` gets a "Local development" section. Phase 3 does not have to litigate local-Postgres setup. Authentik stays on user's homelab (not in docker-compose) but the compose file is the handle for future local services if they're ever needed.
+
+### Locked infrastructure hygiene (from PROJECT.md, enforced in Phase 1)
+- **D-18:** iOS binary flags added to `gradle.properties`: `kotlin.native.binary.objcDisposeOnMain=false` and `kotlin.native.binary.gc=cms` (INFRA-03, PITFALLS.md #1).
+- **D-19:** `shared/commonMain` stays pure: domain models + `@Serializable` DTOs only; no Ktor, no Compose, no SQLDelight imports. Phase 1 ships an empty package scaffold under `dev.ulfrx.recipe.shared` ready for Phase 2+ DTOs (INFRA-06).
+- **D-20:** Namespace `dev.ulfrx.recipe` (package root). Framework basename `ComposeApp` for iOS. No feature modules in v1.
+
+### Claude's Discretion
+- Exact ordering of plugin application inside each `build.gradle.kts`
+- Specific `spotless { kotlin { ktlint(...) } }` ruleset version (pick latest stable from catalog)
+- Whether `application.conf` or `ApplicationConfig.kt` code owns env-var parsing
+- Flyway `cleanDisabled` and `baselineOnMigrate` flag choices (use sane defaults for dev)
+- Whether Koin bootstrap in `MainViewController` uses `KoinApplication` vs `startKoin` (iOS-specific idiom)
+- Whether `docker-compose.yml` uses a `.env` file or inlines localhost defaults
+- The exact sentinel JSON body for `/health` (empty object is fine)
+
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+### Product + scope anchors
+- `.planning/PROJECT.md` — Locked tech stack (§ Key Decisions), constraints, module structure rules
+- `.planning/REQUIREMENTS.md` — INFRA-01, INFRA-02, INFRA-03, INFRA-06 are the in-scope requirements for this phase
+- `.planning/ROADMAP.md` § "Phase 1: Project Infrastructure & Module Wiring" — phase goal + 5 success criteria; ordering rationale for subsequent phases
+
+### Architecture + pitfalls
+- `.planning/research/ARCHITECTURE.md` — Recommended project structure (§ Recommended Project Structure) defines the `composeApp/commonMain` package layout that Phase 1 scaffolds; § Build Order Implication explains why the foundation-first order matters
+- `.planning/research/PITFALLS.md` — Phase 1 must prevent pitfalls #1 (K/N GC + objcDisposeOnMain), #2 (legacy freeze/SharedImmutable — Kotlin 2.x only), #5 (newSuspendedTransaction, not relevant in Phase 1 but plugin must not preclude it), #6 (DSL-only Exposed, infra impact only)
+- `.planning/research/SUMMARY.md` § "Phase 1: Project infrastructure + module wiring" — executive summary of the research-driven rationale
+
+### Project convention
+- `CLAUDE.md` — Non-negotiable conventions (§ Non-negotiable conventions). Items #5 (Exposed DSL only), #7 (iOS binary flags day 1), #8 (shared/commonMain stays light), #9 (strings externalized from day 1 — Phase 1 scaffold only, real copy in Phase 11) all touch Phase 1.
+
+No external ADRs or specs yet — project is greenfield; decisions flow from PROJECT.md + research/ files.
+
+</canonical_refs>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable assets (what the template already gives us)
+- `gradle/libs.versions.toml` exists and is the catalog. Needs to grow; does not need to be created.
+- `gradle.properties` exists with basic Gradle memory + Android settings. **Missing iOS binary flags** (D-18 adds them).
+- `settings.gradle.kts` already enables `TYPESAFE_PROJECT_ACCESSORS` — keep it.
+- Compose Multiplatform hot reload already works for Desktop (commit c50d747). The `recipe.compose.multiplatform` convention plugin should preserve that wiring.
+- `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/App.kt` is the template App(). Koin `startKoin { }` call goes here.
+- `server/src/main/kotlin/dev/ulfrx/recipe/Application.kt` is the template Ktor module. `/health` route + Flyway bootstrap go here.
+- `iosApp/iosApp/iOSApp.swift` + `ContentView.swift` — the MainViewController hookup for iOS lives here; that's where iOS-side `startKoin` + `ComposeUIViewController` wiring lands.
+
+### Established patterns
+- JetBrains KMP template conventions (plugin application style, source-set DSL) — Phase 1 refactors into convention plugins but must not break template compatibility (future template updates are an informal escape hatch).
+- `gradle/libs.versions.toml` uses `version.ref = "..."` aliases — continue that pattern; do not introduce inline versions.
+
+### Integration points
+- Each module's `build.gradle.kts` replaces its `plugins { alias(...) }` block with `plugins { id("recipe.kotlin.multiplatform"); id("recipe.quality"); ... }`. The actual alias-based plugins (`kotlinMultiplatform`, `composeMultiplatform`, etc.) are applied *inside* the convention plugins, so modules no longer touch `libs.plugins.*`.
+- Root `build.gradle.kts` keeps its `apply false` declarations for now (Gradle's plugin classloader hint); convention plugins rely on those declarations being present in the root build.
+- `build-logic/` is its own included build (`includeBuild("build-logic")` in `settings.gradle.kts`) — standard Gradle pattern, not a regular module.
+
+### What must NOT change in Phase 1
+- Package namespace (`dev.ulfrx.recipe`) — locked in CLAUDE.md and every existing file.
+- Android minSdk 24 / compileSdk 36 / targetSdk 36 — locked in `libs.versions.toml`.
+- Kotlin version (2.3.20), AGP (8.11.2), Compose Multiplatform (1.10.3), Ktor (3.4.1) — current template versions, upgraded only if catalog-wide bump becomes necessary.
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+- **"Fine-grained conventions" means a module's plugins block reads like a role declaration.** `composeApp/build.gradle.kts` should literally say: "I am a Kotlin Multiplatform module, I use Compose, I am an Android application, I follow the quality rules." No hidden Compose config leaking into `shared/`.
+- **`./gradlew build` succeeds green** is the verification ritual. Any deviation from Phase 1 AC#1 is a regression. Every plan in this phase should end with that check.
+- **Android minSdk 24 stays.** Partner's phones are modern enough; Android is secondary anyway. Revisit only if a library requires higher.
+- **docker-compose.yml is dev-ergonomics, not deploy infra.** Phase 11 handles the real homelab deploy (separate compose file on the homelab, alongside Authentik).
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- **Detekt static analysis** — skip day 1; add only if code review starts missing the same classes of bug. Revisit criterion: "we've had 3+ PR comments that Detekt would have caught."
+- **Konsist architecture fitness tests** — revisit ~Phase 4 (SyncEngine) when cross-layer rules like "repositories never import Ktor Client" or "no HTTP from composeApp/ui/" become meaningful to police. Pattern 2 in ARCHITECTURE.md is the first rule that deserves a fitness test.
+- **CI pipeline (GitHub Actions or homelab runner)** — Phase 11 per ROADMAP.md. Phase 1 is single-dev, local-build-only.
+- **Git hooks** — considered and explicitly rejected; revisit only if local formatting drift becomes a recurring problem.
+- **explicitApi for composeApp and server** — considered; rejected because both are app code, not libraries. Only `shared/` gets the discipline.
+- **iosX64 target** — rejected; revisit only if an Intel-Mac contributor joins.
+- **`js` target** — rejected; `wasmJs` covers the future-web ambition alone.
+- **Compose Desktop packaging (dmg/msi/exe)** — Desktop is dev-tool only in v1; full packaging is out of scope entirely.
+- **Konsist, Detekt, CI** listed above are the candidates most likely to be revisited first.
+
+</deferred>
+
+---
+
+*Phase: 01-project-infrastructure-module-wiring*
+*Context gathered: 2026-04-24*

.planning/phases/01-project-infrastructure-module-wiring/01-DISCUSSION-LOG.md

@@ -0,0 +1,216 @@
+# Phase 1: Project Infrastructure & Module Wiring - Discussion Log
+
+> **Audit trail only.** Do not use as input to planning, research, or execution agents.
+> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
+
+**Date:** 2026-04-24
+**Phase:** 01-project-infrastructure-module-wiring
+**Areas discussed:** Target matrix, Convention plugin split, Code-quality toolchain, "Running-but-empty" scope
+
+---
+
+## Target matrix
+
+### Q1: JS target in composeApp + shared — drop it?
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Drop js, keep wasmJs | PROJECT.md mentions Wasm but not js; js is legacy Kotlin/JS path | ✓ |
+| Keep both js and wasmJs | Preserve template exactly; zero risk of Kotlin/JS regression on future merges | |
+| Drop both | Strictest minimum; re-add wasmJs only if web becomes real | |
+
+**User's choice:** Drop js, keep wasmJs.
+
+### Q2: iosX64 target — include?
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Skip iosX64 | User is on Apple Silicon; iosArm64 + iosSimulatorArm64 sufficient | ✓ |
+| Add iosX64 for safety | Intel-Mac safety net; costs a second iOS compile per build | |
+
+**User's choice:** Skip iosX64.
+
+### Q3: Desktop JVM target — role?
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Dev-tool only, no shipped artifact | Hot-reload loop retained; no packaging; PROJECT.md alignment | ✓ |
+| Full desktop app, packaged + shipped | dmg/msi/exe as release surface; out of PROJECT.md scope | |
+| Drop desktop target entirely | Simplest; loses hot reload | |
+
+**User's choice:** Dev-tool only, no shipped artifact.
+
+### Q4: shared/ target set — mirror composeApp?
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Mirror composeApp exactly | Same target set; consistent dep graph | ✓ |
+| Superset: ship everything KMP supports | Every target just in case; build cost | |
+| Minimum: only what's used today | Strictest diet; same as Option 1 if we drop js | |
+
+**User's choice:** Mirror composeApp exactly.
+
+---
+
+## Convention plugin split
+
+### Q1: How granular should the convention plugins be?
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Fine-grained (4–5 plugins) | recipe.kotlin.multiplatform + .compose.multiplatform + .android.application + .jvm.server + .quality | ✓ |
+| Coarse (2 plugins) | recipe.kmp + recipe.server; leaks Compose config into shared | |
+| Monolith (1 plugin) | Single recipe.conventions with conditional logic | |
+
+**User's choice:** Fine-grained (4–5 plugins). Preview showed the role-declaration pattern in each module's plugins block.
+
+### Q2: What does the KMP convention plugin lock in?
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Targets + toolchain + common test deps | New KMP module = apply plugin, done | ✓ |
+| Targets + toolchain only | Thinner plugin, more repetition downstream | |
+| Everything incl. Koin + Kermit wiring | Upfront convenience, invasive over time | |
+
+**User's choice:** Targets + toolchain + common test deps.
+
+### Q3: JVM toolchain version?
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| JVM 21 everywhere, androidTarget stays JVM 11 | Split kept; modern JDK on server, Android constrained | ✓ |
+| JVM 17 everywhere | Unified; loses JVM-21 features (virtual threads) | |
+| Keep template defaults | Zero refactor risk; loses explicit control | |
+
+**User's choice:** JVM 21 everywhere, androidTarget stays JVM 11.
+
+### Q4: Where do library version strings live?
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| All versions in libs.versions.toml, nowhere else | Strict INFRA-01 SC#2 | ✓ |
+| Catalog for libs, plugin versions inline | Technically violates SC#2 | |
+
+**User's choice:** All versions in libs.versions.toml, nowhere else.
+
+---
+
+## Code-quality toolchain
+
+User clarified: "What are Detekt alternatives? Is ktlint OK?" Discussion explained Detekt = static analysis, ktlint = formatting — not alternatives, usually paired. Presented tiers (minimal / standard / architecture-aware) and user chose minimal.
+
+### Q1: Static analysis (Detekt)?
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Wire Detekt now | Default ruleset + baseline; catches Kotlin footguns | |
+| Skip Detekt; lean on IDE + compiler | No CI gate for static analysis | ✓ |
+| Placeholder task, no rules | Wire-in-place for future enablement | |
+
+**User's choice:** Skip Detekt. Minimal baseline.
+**Notes:** Konsist (architecture fitness) deferred to ~Phase 4 when SyncEngine rules exist.
+
+### Q2: Formatting / linting?
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| ktlint via Spotless plugin | One tool: Kotlin + Gradle + markdown | ✓ |
+| ktlint plugin directly | Thinner; loses multi-format coverage | |
+| Skip, rely on IDE + .editorconfig | No CI-level gate | |
+
+**User's choice:** ktlint via Spotless plugin.
+
+### Q3: Compiler warnings as errors?
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| allWarningsAsErrors = true everywhere | Max discipline; deprecations force conscious suppression | ✓ |
+| Warn only | Noise accumulates | |
+| As-errors for module code, relaxed for generated | Small config carve-out | |
+
+**User's choice:** allWarningsAsErrors = true everywhere.
+
+### Q4: Explicit API mode for shared/?
+
+User clarified: "I don't understand it. What is this explicit api?" and later "Is this some kind of a standard because I am writing kotlin server applications and didn't meet with that". Discussion explained explicitApi as a library-authoring convention (stdlib, coroutines, Ktor etc.) requiring `public` keyword + explicit return types. User weighed the tradeoff and picked strict-on-shared/ on library-contract grounds.
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Skip entirely | Kotlin defaults; no `public` ceremony | |
+| Strict on shared/ only | Library discipline on the cross-runtime contract | ✓ |
+
+**User's choice:** Strict on shared/ only.
+
+### Q5: Git hooks?
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| No git hooks | `./gradlew check` is the gate; CI later | ✓ |
+| Pre-commit hook running spotlessCheck | Blocks commits with formatting drift | |
+
+**User's choice:** No git hooks.
+
+---
+
+## "Running-but-empty" scope
+
+### Q1: Koin DI bootstrap — wire it in Phase 1?
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Wire minimal bootstrap now | Empty appModule + startKoin in App() and MainViewController | ✓ |
+| Defer to Phase 2 | Phase 2 does DI + auth together | |
+
+**User's choice:** Wire minimal bootstrap now.
+
+### Q2: Kermit logger bootstrap?
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Set up Kermit now | Logger available from day 1 | ✓ |
+| Defer | Add when first feature needs logging | |
+
+**User's choice:** Set up Kermit now.
+
+### Q3: Server "running-but-empty" — `/health` + Flyway scaffold + Postgres config?
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Health endpoint + Flyway scaffold + Postgres conn config | Phase 3 migrations drop into an already-wired migrator | ✓ |
+| Health endpoint only, no DB | Phase 3 wires Flyway + Postgres together | |
+| Strictly the template skeleton | Most minimal; Phase 2 and 3 do more | |
+
+**User's choice:** Health endpoint + Flyway scaffold + Postgres conn config.
+
+### Q4: docker-compose.yml in Phase 1?
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Add docker-compose.yml now | Phase 3 doesn't have to litigate local-Postgres setup | ✓ |
+| Defer to Phase 3 | Compose arrives with first migration | |
+| No compose; use homelab Postgres directly | Fastest setup; dev pollutes shared instance | |
+
+**User's choice:** Add docker-compose.yml now.
+
+---
+
+## Claude's Discretion
+
+- Exact ordering of plugin application inside each `build.gradle.kts`
+- Specific Spotless ktlint ruleset version (pick latest stable from catalog)
+- Whether `application.conf` or a Kotlin config class owns env-var parsing
+- Flyway `cleanDisabled` / `baselineOnMigrate` flag choices
+- iOS Koin bootstrap idiom (`KoinApplication` vs `startKoin` in MainViewController)
+- `docker-compose.yml` shape: `.env` file vs inline localhost defaults
+- Exact sentinel JSON body for `/health`
+
+## Deferred Ideas
+
+- Detekt static analysis — revisit only if review misses start compounding
+- Konsist architecture fitness tests — revisit ~Phase 4 (SyncEngine rules)
+- CI pipeline — Phase 11 (deployment)
+- Git hooks — considered; revisit only on recurring format drift
+- explicitApi for composeApp / server — rejected (app code, not libraries)
+- iosX64 target — rejected (no Intel-Mac contributors)
+- `js` target — rejected (wasmJs covers future-web intent)
+- Compose Desktop packaging (dmg/msi/exe) — Desktop is dev-only

.planning/phases/01-project-infrastructure-module-wiring/01-VALIDATION.md

@@ -0,0 +1,101 @@
+---
+phase: 1
+slug: project-infrastructure-module-wiring
+status: draft
+nyquist_compliant: false
+wave_0_complete: false
+created: 2026-04-24
+---
+
+# Phase 1 — Validation Strategy
+
+> Per-phase validation contract derived from `01-RESEARCH.md § Validation Architecture`. Phase 1 is predominantly **build-level** verification (Gradle tasks, file structure, grep invariants) rather than unit tests. The existing `ApplicationTest.kt` is the one test file extended (adds `/health` coverage).
+
+---
+
+## Test Infrastructure
+
+| Property | Value |
+|----------|-------|
+| **Framework** | `kotlin.test` (commonTest) + `ktor-server-test-host` (JUnit 4 runner for server) + existing KMP template test stubs |
+| **Config file** | `composeApp/src/commonTest/kotlin/ComposeAppCommonTest.kt`, `shared/src/commonTest/kotlin/SharedCommonTest.kt`, `server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt` (all present from template) |
+| **Quick run command** | `./gradlew :server:test :composeApp:jvmTest :shared:jvmTest` (JVM-only, <30s) |
+| **Full suite command** | `./gradlew check` (runs `spotlessCheck` + every `*Test` task across all targets) |
+| **Estimated runtime** | ~30s quick / ~3–5 min full (cold) |
+
+---
+
+## Sampling Rate
+
+- **After every task commit:** `./gradlew spotlessCheck :server:test :shared:jvmTest` (fast subset, <30s)
+- **After every plan wave:** `./gradlew build` (includes iOS framework link + Android APK)
+- **Before `/gsd-verify-work` (phase gate):** `./gradlew check` + manual server `/health` curl + iOS simulator boot check
+- **Max feedback latency:** 30s (quick subset) / 5 min (full)
+
+---
+
+## Per-Task Verification Map
+
+**Note:** Task IDs are populated by `gsd-planner` when PLAN.md files are written. Each row below is the per-requirement contract the planner MUST map to at least one task's `<automated>` block. Rows marked "Wave 0" require a helper file to be created before task execution can verify it.
+
+| Behavior | Requirement | Test Type | Automated Command | File Exists | Status |
+|----------|-------------|-----------|-------------------|-------------|--------|
+| No version literals in any `build.gradle.kts` | INFRA-01 | shell grep | `tools/verify-no-version-literals.sh` | ❌ Wave 0 | ⬜ pending |
+| `gradle/libs.versions.toml` is the single source of truth | INFRA-01 | grep | `grep -rE "libs\\.(versions\|plugins\|bundles)" build-logic/src/main/kotlin/` returns all version lookups | ✅ catalog exists | ⬜ pending |
+| Convention plugins apply without duplication | INFRA-02 | Gradle | `./gradlew :composeApp:help :server:help :shared:help` shows `recipe.*` in applied plugins | ❌ Wave 0 (plugins don't exist yet) | ⬜ pending |
+| Adding a new KMP module only needs `id("recipe.kotlin.multiplatform")` | INFRA-02 | visual | refactored `shared/build.gradle.kts` ≤15 LOC | Target Wave 2 | ⬜ pending |
+| `gradle.properties` contains both iOS K/N flags | INFRA-03 | grep | `tools/verify-ios-flags.sh` | ❌ Wave 0 | ⬜ pending |
+| iOS simulator build has no legacy memory-manager warnings | INFRA-03 | build-log | `./gradlew :composeApp:linkDebugFrameworkIosSimulatorArm64 --info 2>&1 \| grep -iE 'legacy\|freeze\|SharedImmutable'` is empty | Wave 2 (iOS) | ⬜ pending |
+| `shared/commonMain` has no Ktor/Compose/SQLDelight imports | INFRA-06 | grep | `tools/verify-shared-pure.sh` | ❌ Wave 0 | ⬜ pending |
+| `shared/` package scaffold exists | INFRA-06 | file | `test -d shared/src/commonMain/kotlin/dev/ulfrx/recipe/shared` | Wave 2 | ⬜ pending |
+| SC1: `./gradlew build` succeeds + produces iOS framework + APK | ROADMAP SC1 | Gradle | `./gradlew build && test -f composeApp/build/outputs/apk/debug/composeApp-debug.apk && test -d composeApp/build/bin/iosSimulatorArm64/debugFramework/ComposeApp.framework` | Phase gate | ⬜ pending |
+| SC4: each module's `help` shows its convention plugins | ROADMAP SC4 | Gradle | `./gradlew :composeApp:help -q \| grep 'recipe.kotlin.multiplatform'` etc. | Phase gate | ⬜ pending |
+| Server `/health` returns 200 JSON `{"status":"ok"}` | D-16 | integration | `./gradlew :server:test --tests "*HealthRoute*"` (added to ApplicationTest.kt) | ❌ Wave 0 (test update) | ⬜ pending |
+| Server fails loudly if Postgres unreachable | D-16 | manual | `docker compose down; ./gradlew :server:run` exits non-zero with "Database unreachable" in logs | Phase gate | ⬜ pending |
+| Spotless formatting clean | D-10 | Gradle | `./gradlew spotlessCheck` | Per-commit | ⬜ pending |
+| Koin starts without double-init | D-14 | Gradle test | `./gradlew :composeApp:jvmTest` (template test exercises App() composition path; no `KoinApplicationAlreadyStartedException`) | Per-wave | ⬜ pending |
+
+*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
+
+---
+
+## Wave 0 Requirements
+
+These assets MUST exist before any verification task can run green. The planner should place them in Wave 0 (or inside the plan that creates the infrastructure they verify).
+
+- [ ] `tools/verify-no-version-literals.sh` — greps every `build.gradle.kts` + `build-logic/**/*.gradle.kts` for a non-test numeric version literal; exits non-zero on match
+- [ ] `tools/verify-shared-pure.sh` — greps `shared/src/commonMain/` for forbidden imports (`io.ktor`, `androidx.compose`, `org.jetbrains.compose`, `app.cash.sqldelight`); exits non-zero on match
+- [ ] `tools/verify-ios-flags.sh` — greps `gradle.properties` for `kotlin.native.binary.objcDisposeOnMain=false` AND `kotlin.native.binary.gc=cms`; exits non-zero if either is missing
+- [ ] `build-logic/` scaffold — `settings.gradle.kts`, `build.gradle.kts`, and 5 `src/main/kotlin/recipe.*.gradle.kts` stubs
+- [ ] `server/src/main/resources/application.conf` — HOCON with `ktor.deployment`, `database.url/user/password` using `${?X}` env overrides
+- [ ] `server/src/main/resources/db/migration/.gitkeep` — directory placeholder for Flyway
+- [ ] `docker-compose.yml` — `postgres:16` service with named volume + healthcheck
+- [ ] `server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt` — extended with `/health` endpoint assertion
+- [ ] `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/Koin.kt` + `AppModule.kt` — `initKoin()` helper + empty module
+- [ ] `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/logging/Logging.kt` — Kermit `setTag("recipe")`
+- [ ] `composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/MainApplication.kt` + `AndroidManifest.xml` registration — calls `initKoin { androidContext(this) }`
+- [ ] `composeApp/src/iosMain/kotlin/dev/ulfrx/recipe/di/KoinIos.kt` — `fun doInitKoin()` exported for Swift
+- [ ] `iosApp/iosApp/iOSApp.swift` — modified to call `KoinIosKt.doInitKoin()` in `init()`
+
+---
+
+## Manual-Only Verifications
+
+| Behavior | Requirement | Why Manual | Test Instructions |
+|----------|-------------|------------|-------------------|
+| iOS simulator debug launch has no legacy K/N memory-manager warnings | INFRA-03 / SC3 | Requires Xcode simulator boot; not scriptable from Gradle reliably on CI | Run `./gradlew :composeApp:iosSimulatorArm64Test` OR open `iosApp.xcworkspace` in Xcode, run on iPhone 15 simulator, inspect console for `legacy`/`freeze`/`SharedImmutable` — expect none |
+| Hot-reload dev loop on Desktop still works post-refactor (regression check for commit c50d747) | — | Interactive | `./gradlew :composeApp:jvmRun --mainClass MainKt --auto-reload`; edit `App.kt`, observe reload without rebuild |
+| Server `/health` reachable via curl when Postgres up | D-16 | Requires running Postgres + server process | `docker compose up -d postgres`, `./gradlew :server:run &`, `sleep 5`, `curl -sf http://localhost:8080/health` returns `{"status":"ok"}` |
+
+---
+
+## Validation Sign-Off
+
+- [ ] All tasks have `<automated>` verify or Wave 0 dependencies
+- [ ] Sampling continuity: no 3 consecutive tasks without automated verify
+- [ ] Wave 0 covers all MISSING references (13 items listed above)
+- [ ] No watch-mode flags in any verification command
+- [ ] Feedback latency < 30s (quick) / 5min (full)
+- [ ] `nyquist_compliant: true` set in frontmatter after planner maps every task to a row above
+
+**Approval:** pending

.planning/research/ARCHITECTURE.md

@@ -0,0 +1,259 @@
+# Architecture Research
+
+**Domain:** Offline-first meal-planning app (KMP + Ktor, household-shared)
+**Researched:** 2026-04-23
+**Confidence:** HIGH (locked stack; standard patterns within it)
+
+## System Overview
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  composeApp/ (Android · iOS · Desktop · Wasm)                    │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │  UI: Compose screens + NavHost (Jetpack Nav CMP)          │   │
+│  │  ViewModel (StateFlow) ──► Repository (reactive Flow)     │   │
+│  │         │                         │                        │   │
+│  │         ▼                         ▼                        │   │
+│  │  SyncEngine (singleton) ◄──► SQLDelight (local) + Outbox  │   │
+│  │         │                                                  │   │
+│  │         │   AuthSession (AppAuth / ASWebAuth)              │   │
+│  │         ▼                                                  │   │
+│  │  Ktor Client (JWT bearer) ─────────────────┐               │   │
+│  └────────────────────────────────────────────┼───────────────┘   │
+└──────────────────────────────────────────────┼───────────────────┘
+                                               │  HTTPS
+              ┌────────────────────────────────┼───────────┐
+              │  Authentik (OIDC IdP, homelab) │  JWKS     │
+              └────────────────────────────────┴───────────┘
+                                               │
+┌──────────────────────────────────────────────▼───────────────────┐
+│  server/ (Ktor 3.x, same homelab)                                │
+│  Auth (ktor-server-auth-jwt) ──► Routes /api/v1/*                │
+│             │                          │                          │
+│             ▼                          ▼                          │
+│  PrincipalResolver ──► Services ──► Exposed DSL ──► Postgres     │
+│                                                    (Flyway)       │
+└──────────────────────────────────────────────────────────────────┘
+
+shared/commonMain: domain models + API DTOs (client + server both depend)
+```
+
+## Component Responsibilities
+
+| Component | Responsibility | Typical Implementation |
+|-----------|----------------|------------------------|
+| Screen (`@Composable`) | Render state, forward intents. No I/O. | `PlannerScreen(state, onAddMeal)`; consumes `collectAsStateWithLifecycle()` |
+| ViewModel | Expose `StateFlow`; coordinate repo calls; zero Compose imports | Extends `ViewModel`, scoped via `koinViewModel()`, method-per-action |
+| Repository | Single source of truth for one aggregate; hide local/remote split | Exposes `Flow<Domain>` from SQLDelight; write path goes through local DB + outbox |
+| SyncEngine | Own outbox drain, pull loop, backoff, auth failure handling | App-scoped Koin singleton; one `CoroutineScope(SupervisorJob)`; started after auth |
+| DataSource (local) | Thin SQLDelight wrapper, mapping rows ↔ domain | Per-table `Queries` injected; suspend + `asFlow().mapToList()` |
+| DataSource (remote) | Typed Ktor calls for `/sync/push`, `/sync/pull`, catalog endpoints | `HttpClient` with `Auth { bearer { ... } }` + `ContentNegotiation(Json)` |
+| AuthSession | Own tokens, refresh, sign-in/out; expose `StateFlow<AuthState>` | Platform-specific actual class (AppAuth / ASWebAuth) behind `expect` |
+| Koin Module | Wire graph per layer (`appModule`, `dataModule`, `syncModule`, `authModule`) | Declared in `commonMain`; `startKoin` in `App()` + `MainViewController` |
+| Ktor route | HTTP surface; validate DTO; call service; never touch DB directly | `Route.planRoutes()` under `authenticate("auth-jwt") { route("/api/v1") { ... } }` |
+| Exposed table | Schema definition + column types; DSL queries via `transaction {}` | `object PlanEntries : Table("plan_entries")` — no DAO |
+| Outbox | Durable queue of unsynced local writes keyed by aggregate+id | `sync_outbox` table in SQLDelight; `(op, table, pk, payload_json, attempts)` |
+
+## Recommended Project Structure
+
+```
+composeApp/src/commonMain/kotlin/app/recipe/
+├── app/                           # App() composable, root nav, Koin bootstrap
+├── navigation/                    # @Serializable route classes + NavGraphBuilder extensions
+├── ui/
+│   ├── theme/                     # Color, typography, Haze style tokens
+│   ├── components/                # Reusable (GlassCard, MealSlotChip, ...)
+│   └── screens/
+│       ├── recipes/               # RecipeListScreen, RecipeDetailScreen, *ViewModel
+│       ├── planner/               # PlannerScreen, DayColumn, *ViewModel
+│       ├── pantry/
+│       └── shopping/
+├── data/
+│   ├── local/                     # SQLDelight driver factory (expect/actual), Queries wrappers
+│   ├── remote/                    # HttpClient factory, DTOs mirroring shared/, auth interceptor
+│   ├── sync/                      # SyncEngine, Outbox, pull scheduler, conflict policy
+│   └── repository/                # PlanRepository, PantryRepository, CatalogRepository, ...
+├── domain/                        # Value types, enums (MealSlot), pure computations (shortfall, aggregation)
+├── auth/                          # AuthSession interface, token store, OIDC config
+└── di/                            # appModule, dataModule, syncModule, authModule
+
+server/src/main/kotlin/app/recipe/server/
+├── Application.kt                 # embeddedServer, install plugins, call moduleMain()
+├── plugins/                       # Auth, ContentNegotiation, CallLogging, StatusPages, CORS
+├── auth/                          # JWKS config, PrincipalResolver (sub → user → household)
+├── routes/
+│   ├── sync/                      # push.kt, pull.kt
+│   ├── catalog/                   # recipes, ingredients, products (read-mostly)
+│   ├── households/                # memberships, invites
+│   └── health/
+├── services/                      # PlanService, SyncService — orchestrate transactions
+├── db/
+│   ├── tables/                    # Exposed Table objects (no DAO)
+│   ├── Mappers.kt                 # ResultRow → shared DTO
+│   └── Database.kt                # HikariCP + Flyway.migrate()
+└── util/                          # Clock (injectable), IdGen, Json
+
+server/src/main/resources/db/migration/     # V1__init.sql, V2__plan_entries.sql, ...
+shared/src/commonMain/kotlin/app/recipe/shared/   # Domain + DTOs (@Serializable) — no I/O deps
+```
+
+Rationale: groups by UI concern then data layer, matching the locked decision in PROJECT.md. `data/sync/` is a first-class folder because sync is the spine of the app. `domain/` holds pure logic so it can be unit-tested without Android/iOS runtime. Server mirrors the client's layered split (routes → services → db) so reasoning transfers.
+
+## Architectural Patterns
+
+### Pattern 1: Repository → reactive Flow → StateFlow in ViewModel
+
+Repositories expose `Flow<Domain>` built from SQLDelight's `asFlow().mapToList()`. The ViewModel lifts that into a cold-hot `StateFlow` using `stateIn` with `WhileSubscribed(5_000)`. Writes go through the repo, which writes to SQLDelight; the reactive query re-emits automatically. **Never** pre-fetch state with a suspend call in `init {}` — that races with collection.
+
+```kotlin
+class PlannerViewModel(private val repo: PlanRepository) : ViewModel() {
+  val state: StateFlow<PlannerState> = repo.observeWeek(currentWeek)
+    .map(PlannerState::fromEntries)
+    .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), PlannerState.Loading)
+
+  fun onAddMeal(day: LocalDate, slot: MealSlot, recipeId: Uuid) =
+    viewModelScope.launch { repo.add(day, slot, recipeId) }
+}
+```
+
+### Pattern 2: Sync engine as a Koin singleton owning outbox + poll cycles
+
+One long-lived `SyncEngine` bound in `syncModule` with a `SupervisorJob`-backed scope. It exposes `pushNow()`, `pullNow()`, `status: StateFlow<SyncStatus>`. Two loops: a push loop that drains `sync_outbox` with exponential backoff on 5xx/network errors, and a pull loop that calls `GET /sync/pull?since={lastCursor}` every 20–30s while foregrounded. Repositories never talk to HTTP directly for household data — they enqueue outbox rows and trust the engine.
+
+```kotlin
+class SyncEngine(private val api: SyncApi, private val local: LocalDb, private val clock: Clock) {
+  private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default)
+  fun start() { scope.launch { pushLoop() }; scope.launch { pullLoop() } }
+  suspend fun nudge() = pushSignal.emit(Unit)
+}
+```
+
+Trade-off: single point of failure if the engine deadlocks, so all its work must be cancellable and idempotent (server-side push is keyed by `client_op_id`).
+
+### Pattern 3: Household-scope enforcement at three layers
+
+Defence in depth: (a) **Client query filter** — every SQLDelight query for household-scoped tables includes `WHERE household_id = :hh`, sourced from `AuthSession.activeHouseholdId`; (b) **Server principal resolver** — a `PrincipalResolver` turns the JWT `sub` claim into `(userId, householdId)` via a cached lookup against `memberships`; routes receive an `AuthPrincipal` already carrying `householdId`; (c) **DB row ownership** — every household-scoped table has `household_id uuid NOT NULL` with an index, and every `UPDATE`/`DELETE` includes `AND household_id = ?`.
+
+```kotlin
+fun Route.planRoutes(svc: PlanService) = authenticate("auth-jwt") {
+  post("/api/v1/sync/push") {
+    val p = call.principal<AuthPrincipal>()!!         // householdId baked in
+    val batch = call.receive<PushBatch>()
+    call.respond(svc.applyBatch(p.householdId, batch))
+  }
+}
+```
+
+Never trust a `householdId` field inside a client payload — overwrite with the principal's.
+
+### Pattern 4: Catalog (read-mostly) vs Household (read-write, synced) split
+
+Two cache + sync policies in one app. **Catalog** (recipes, ingredients, products) is pre-seeded server-side, pulled via versioned ETag (`GET /api/v1/catalog?etag=...`), cached in SQLDelight with a simple "replace all or diff by updated_at" refresh on app start + manual refresh. No outbox. **Household** (plan entries, pantry, shopping items) is LWW-synced with server-assigned `updated_at`, uses the outbox, and is reactively observed. Keep these in separate repositories and separate Koin modules so their refresh semantics don't leak into each other.
+
+## Data Flow — Hero Write Path (Add Meal to Plan)
+
+```
+User taps "add meal"
+    │
+    ▼
+PlannerScreen invokes onAddMeal(day, slot, recipeId)
+    │
+    ▼
+PlannerViewModel.onAddMeal → viewModelScope.launch { repo.add(...) }
+    │
+    ▼
+PlanRepository.add():
+  ├─ SQLDelight transaction:
+  │     INSERT plan_entry (id=localUuid, household_id, day, slot, recipe_id,
+  │                        updated_at=NULL /* server will stamp */, pending=1)
+  │     INSERT sync_outbox (op='upsert', table='plan_entry', pk=id,
+  │                         payload_json, client_op_id, attempts=0)
+  └─ Flow<PlanEntries> re-emits → PlannerViewModel.state recomputes → UI updates
+    │                              (optimistic; pending=1 may render a subtle marker)
+    ▼
+SyncEngine.nudge() — push loop wakes
+    │
+    ▼
+Ktor Client POST /api/v1/sync/push  (Authorization: Bearer <jwt>)
+    │
+    ▼
+Ktor Server: install(Authentication) { jwt("auth-jwt") { verifier(jwkProvider) } }
+    │  JWT validated against Authentik JWKS (cached, rotating)
+    ▼
+PrincipalResolver: sub → userId → householdId (cached)
+    │
+    ▼
+sync/push.kt → SyncService.applyBatch(householdId, batch)
+    │
+    ▼
+Exposed transaction {
+    PlanEntries.upsert { it[id]=...; it[householdId]=...; it[updatedAt]=Clock.now() }
+    // server clock is authoritative
+}
+    │
+    ▼
+Response { applied: [{ id, client_op_id, updated_at: <server ts> }] }
+    │
+    ▼
+Client: local tx {
+  UPDATE plan_entry SET updated_at = <server ts>, pending = 0 WHERE id = ?
+  DELETE FROM sync_outbox WHERE client_op_id = ?
+}
+    │
+    ▼
+Flow re-emits → pending marker vanishes
+    │
+    ~~~  (later) partner's device  ~~~
+    ▼
+Pull loop: GET /api/v1/sync/pull?since=<lastCursor>
+    │
+    ▼
+Server returns rows with updated_at > since, scoped to householdId
+    │
+    ▼
+Client upserts rows in a single SQLDelight tx; advances cursor
+    │
+    ▼
+Partner's PlannerViewModel StateFlow emits new state → their UI updates
+```
+
+## Anti-Patterns
+
+### Anti-Pattern 1: Suspend fetch in `init {}` feeding a `MutableStateFlow`
+
+```kotlin
+// WRONG
+init { viewModelScope.launch { _state.value = repo.getOnce() } }
+```
+
+Races with UI collection; loses SQLDelight's reactive updates; forces manual refresh after every write. **Instead:** build the `StateFlow` declaratively from `repo.observeX().stateIn(...)`.
+
+### Anti-Pattern 2: Using Exposed DAO (active record) for new tables
+
+Exposed's DAO API (`IntEntity`, `EntityClass`) looks convenient but leaks lazy-loading through transactions and fights JSONB/composite types. PROJECT.md already forbids it. **Instead:** use the DSL (`Table` objects + `transaction { Table.select { ... } }` + explicit `ResultRow → DTO` mappers). Predictable SQL, no session/transaction surprises.
+
+### Anti-Pattern 3: Sharing SQLDelight transactions across coroutine contexts on iOS
+
+SQLDelight's iOS driver (native-sqlite) uses thread-confined connections. Launching nested `withContext(Dispatchers.IO)` inside a `transaction { }` can throw `IllegalStateException` or silently serialize incorrectly. **Instead:** keep the entire transaction inside one coroutine, use SQLDelight's `transactionWithResult { }`, and do network/CPU work *outside* the tx. On iOS, the driver's own dispatcher handles threading.
+
+### Anti-Pattern 4: Using device clock for `updated_at`
+
+Phones have drifting clocks and timezone shenanigans; a device whose clock is 10 minutes fast will always "win" LWW. **Instead:** server stamps `updated_at` inside the push transaction (`Clock.System.now()` on the server, or `now()` in SQL). The client only stores what the server returns. Local-only edits carry `pending=1` until acknowledged.
+
+### Anti-Pattern 5: Putting UI, HTTP, or DB types in `shared/commonMain`
+
+PROJECT.md scopes `shared/` to domain models + DTOs. Dragging Ktor or SQLDelight into `shared/` pulls platform-specific deps into the server build graph and vice versa. **Instead:** client-only concerns live in `composeApp/`, server-only in `server/`, and `shared/` stays a pure-Kotlin library with `kotlinx.serialization` + `kotlinx.datetime` as its only non-stdlib deps.
+
+## Build Order Implication
+
+The layer that must exist first is **auth + a working Ktor skeleton that echoes an authenticated principal**, because every subsequent layer depends on having a real `householdId` to scope against. After that the unblock order is: (1) **sync engine foundation** — outbox table, empty push/pull endpoints, cursor persistence — so every feature slots into an already-synced path instead of being retrofitted; (2) **catalog read path** — lets the UI render recipes without any write-path complexity, proving HTTP + SQLDelight + Coil end-to-end on a trivial aggregate; (3) **household write path** — the planner as the first real outbox-backed aggregate, which flushes out LWW edge cases; (4) **UI chrome** — Haze-backed glass, navigation polish, theming — last, because decorating a working app is cheap while architecting around decoration is expensive. Skipping step 1 or 2 and jumping to the planner looks faster for a week and costs a month.
+
+## Sources
+
+- `/Users/rwilk/dev/repo/recipe/.planning/PROJECT.md` (authoritative stack + constraints)
+- Training knowledge: Compose Multiplatform 1.7+, Jetpack Nav CMP port 2.9.x, SQLDelight 2.x coroutine extensions, Ktor 3.x auth-jwt + JWKS, Exposed DSL transaction semantics, Authentik OIDC discovery
+- No web searches needed — patterns are standard within the locked stack
+
+---
+*Architecture research for: KMP + Ktor household meal planner*
+*Researched: 2026-04-23*

.planning/research/PITFALLS.md

@@ -0,0 +1,292 @@
+# Pitfalls Research
+
+**Domain:** Kotlin Multiplatform + Compose Multiplatform (iOS-primary), Ktor/Exposed/Postgres, OIDC, LWW delta sync
+**Researched:** 2026-04-23
+**Confidence:** HIGH for KMP/Ktor/Exposed gotchas; MEDIUM for Haze + Navigation-CMP specifics (behavior shifts across minor versions)
+
+## Critical Pitfalls
+
+### Pitfall 1: Kotlin/Native iOS GC thrashing and `objcDisposeOnMain` hangs
+
+**What goes wrong:** On-device (especially iPhone XR/11) the app consumes 300–700 MB steadily and freezes for 1–2 s under ViewModel churn. Flamegraphs show GC threads at >100% CPU.
+
+**Why:** The K/N memory manager dispatches Obj-C release to the main thread by default, serializing teardown behind UI frames. Compose/Koin graphs produce many bridged Obj-C references per navigation.
+
+**Warning signs:** Frame hitches on tab switches; main-thread time in `objc_release` / `Kotlin_ObjCExport_releaseReservedObjectTail`; Instruments shows growing K/N heap.
+
+**How to avoid:** Set `kotlin.native.binary.objcDisposeOnMain=false` and `kotlin.native.binary.gc=cms` in `gradle.properties` from day 1. Release Kotlin refs in `onDispose`; don't hold them in long-lived Swift closures.
+
+**Phase:** UI chrome.
+
+---
+
+### Pitfall 2: Legacy `freeze()` / strict-mm ceremony in copy-pasted snippets
+
+**What goes wrong:** Code from 2021–2022 tutorials adds `freeze()`, `@SharedImmutable`, `AtomicReference` from `kotlin.native.concurrent`, or `ensureNeverFrozen()`. Compiles on Kotlin 2.x but adds dead code and masks real bugs.
+
+**Why:** The new memory manager removed the freeze paradigm entirely; `freeze()` is a no-op and deprecated.
+
+**Warning signs:** Any of the above symbols appearing in snippets you're about to paste.
+
+**How to avoid:** Reject pre-1.7.20 KMP code. Use `kotlinx.atomicfu` if you truly need atomics; StateFlow is already thread-safe.
+
+**Phase:** Data.
+
+---
+
+### Pitfall 3: `ComposeUIViewController` state loss on iOS re-entry
+
+**What goes wrong:** Backgrounding then returning resets scroll positions, selected tabs, half-filled forms. Koin-scoped ViewModels re-create.
+
+**Why:** If the `UIViewController` is instantiated inside a SwiftUI `body`, each re-render builds a fresh composition. Compose state is owned by the controller's composition root.
+
+**Warning signs:** State survives Android rotation but dies on iOS foreground-return; ViewModel `init` fires on backgrounded return.
+
+**How to avoid:** Build the `UIViewController` **once** — store in `@StateObject` or a top-level property, not in a SwiftUI `body`. Use `rememberSaveable` for any UI state that must survive process death. Never nest multiple `ComposeUIViewController` wrappers.
+
+**Phase:** UI chrome.
+
+---
+
+### Pitfall 4: SQLDelight iOS — missing migration files, in-memory vs file driver divergence
+
+**What goes wrong:** JVM tests pass with in-memory driver; the iOS app crashes on launch with `no such column` after a schema change.
+
+**Why:** `NativeSqliteDriver` persists a real file. Editing `.sq` without a numbered `.sqm` migration and a bumped schema `version` means SQLDelight only *verifies* the schema on open — on a device with an existing install, that check fails.
+
+**Warning signs:** Works on fresh simulator install; breaks on physical device with prior install; Android OK, iOS fails.
+
+**How to avoid:** Every schema change gets a numbered `Nm.sqm`. Enable `verifyMigrations = true` and `verifyDefinitions = true`. Add a dev-only "wipe DB" debug button during early development. Reinstall on device before any QA.
+
+**Phase:** Data.
+
+---
+
+### Pitfall 5: Exposed `transaction {}` inside suspend functions → pool exhaustion
+
+**What goes wrong:** Plain `transaction { ... }` in Ktor handlers. Under modest concurrency (~20 requests) the pool exhausts, p99 cliffs, and `IllegalStateException: Transaction is not currently active` appears.
+
+**Why:** `transaction {}` is blocking and binds the transaction to the calling thread. In a coroutine it blocks event-loop threads; if the code suspends mid-transaction, resume lands on a different thread and loses the JDBC connection binding.
+
+**Warning signs:** Connection pool always fully leased at low RPS; latency cliffs; "transaction not active" in logs.
+
+**How to avoid:** Use `newSuspendedTransaction(Dispatchers.IO) { ... }` in suspend contexts. Pass the `Database` instance explicitly. No HTTP calls inside transactions. HikariCP pool size 8–10 is plenty for 5–10 users.
+
+**Phase:** Data.
+
+---
+
+### Pitfall 6: Exposed DAO + JSONB footguns
+
+**What goes wrong:** `IntEntity` + `jsonb<T>()` produces double-serialized JSON in Postgres (`"{\"key\":\"v\"}"`) or `SerializationException` on read.
+
+**Why:** DAO integration with JSONB is thin; it's easy to store a pre-stringified value. DAO lazy-loads hide *when* the column is read, so failures manifest far from the cause.
+
+**Warning signs:** Escaped JSON in `psql` output; serialization errors deep in read paths.
+
+**How to avoid:** Use DSL only (already locked in PROJECT.md). For JSONB, define `jsonb("extras", Json.Default, MealExtras.serializer())` once; never stringify upstream. Round-trip integration test per JSONB column.
+
+**Phase:** Data.
+
+---
+
+### Pitfall 7: Ktor JWT — audience, issuer, clock skew, JWKS cache
+
+**What goes wrong:** 401s in production only, after a while, or after Authentik restart. Messages: "Token can't be used before...", "Claim 'aud' doesn't contain required audience", or silent 401s post key-rotation.
+
+**Why:** Four defaults converge:
+1. `ktor-server-auth-jwt` requires explicit `.withAudience()` / `.withIssuer()`.
+2. Default clock leeway is **zero** — 2 s device drift rejects fresh tokens.
+3. JWKS cache defaults to `(10, 24h)` — key rotation invisible for hours.
+4. Authentik's `aud` can be array or string depending on provider config.
+
+**Warning signs:** 401 only in prod; 401 only on some devices; works briefly then fails; 401 after Authentik restart.
+
+**How to avoid:** Configure `.withIssuer(issuer).withAudience(clientId).acceptLeeway(30)`. JWKS provider with `.cached(10, 15, MINUTES).rateLimited(10, 1, MINUTES)`. In Authentik, emit `aud` as a single client_id string. Integration test: wrong `aud` → 401.
+
+**Phase:** Auth.
+
+---
+
+### Pitfall 8: OIDC redirect URI mismatch + missing PKCE
+
+**What goes wrong:** "redirect_uri does not match" or consent loop on one platform; or login succeeds without PKCE and is interceptable.
+
+**Why:** Native apps are *public* clients — no shippable secret, so Authentik requires PKCE. Redirect URIs must match byte-for-byte (trailing slash, case). iOS uses a custom URL scheme or Universal Link; Android uses an intent-filter. Debug and release builds can differ.
+
+**Warning signs:** Works on Android, fails on iOS (or vice versa); Authentik logs show `invalid_grant`; no `code_challenge` in auth request; fails on release build only.
+
+**How to avoid:** Authentik provider = "Public" + PKCE S256. Register both `recipe://callback` and `recipe://callback/`. AppAuth (Android) + ASWebAuthenticationSession (iOS) with `usePKCE = true`. Keep the redirect URI in one constant in `shared/commonMain`.
+
+**Phase:** Auth.
+
+---
+
+### Pitfall 9: LWW trusting client clocks
+
+**What goes wrong:** User A's phone clock is 90 s fast; A's edit beats B's real-time-later edit in LWW. B's change silently disappears.
+
+**Why:** Client-assigned timestamps trust unverifiable clocks. Even NTP-synced devices drift; simulators can be minutes off.
+
+**Warning signs:** "My edit vanished"; stable prior state reappears; most common with both household members editing the same meal.
+
+**How to avoid:** Server assigns `updated_at` on every write (already in PROJECT.md — enforce it). Client sends only content + prior `updated_at` for optimistic concurrency. Server sets `updated_at = now()` in the transaction and returns it. Make timestamps strictly monotonic per row (e.g. `GREATEST(now(), old.updated_at + interval '1 microsecond')`) to avoid tie collisions.
+
+**Phase:** Sync.
+
+---
+
+### Pitfall 10: Soft-delete + recreate race
+
+**What goes wrong:** Delete a meal entry, immediately re-add "the same" one. Depending on pull ordering, the new row is hidden by the tombstone, or the old row is resurrected with old fields.
+
+**Why:** If `(plan_date, slot)` is treated as identity, tombstone/recreate races are inevitable on concurrent 2-user editing.
+
+**Warning signs:** Undeleted items; deleted meals reappear on partner's device; duplicates in pantry.
+
+**How to avoid:** Identity is always a fresh UUID per row, never `(date, slot)`. Tombstones carry their own `updated_at`. Pull returns tombstones and live rows; client applies in `updated_at` order. Per-client push outbox replays in local sequence order — never parallel. Integration test: two clients alternating delete/recreate, assert convergence.
+
+**Phase:** Sync.
+
+---
+
+### Pitfall 11: Pull-cursor edge cases — missed updates, same-timestamp ties
+
+**What goes wrong:** Partner edits at 14:00:05; client's last pull cursor is `14:00:04.999`. If cursor semantics or timestamp precision are wrong, the change is skipped forever.
+
+**Why:** Cursor semantics are subtle. Second-precision timestamps, `>=` instead of `>`, and ties among rows sharing a `updated_at` all cause skipped or replayed rows. Debounced push interleaved with pull can reorder writes.
+
+**Warning signs:** Sporadic stale data that vanishes after pull-to-refresh; only reproduces near DB restarts or bulk imports; duplicates after manual refresh.
+
+**How to avoid:** `updated_at` is `timestamptz` with microsecond precision and strictly monotonic. Cursor is `(updated_at, id)` lexicographic: `WHERE (updated_at, id) > (:since_ts, :since_id) ORDER BY updated_at, id LIMIT N`. Pause pull while a push is in flight. Never split the write and its timestamp notification across transactions.
+
+**Phase:** Sync.
+
+---
+
+### Pitfall 12: Haze on scroll + nested children tank older iPhones
+
+**What goes wrong:** LazyColumn scrolling under a blurred top bar stutters badly on iPhone XR/11, dropping to ~30 fps. Nesting `hazeChild` inside a list item sitting in a `hazeSource` Scaffold makes it worse.
+
+**Why:** iOS Haze uses Skiko `GraphicsLayer` for offscreen capture + re-blur each frame. Progressive blur adds ~25% cost. Older A-series chips without hardware-accelerated RenderEffect equivalents jank under this load.
+
+**Warning signs:** Smooth on simulator/M-series, choppy on iPhone 11; FPS 40–50; Skiko render thread pegged in Instruments.
+
+**How to avoid:** One `hazeSource` per screen, never nested. Limit blur to chrome (tab bar, nav bar, sheet headers), not scrolling content. Avoid progressive blur on iOS pre-iPhone 13. Test on the oldest target device in real hardware. Feature-flag the effect with a solid-translucent fallback.
+
+**Phase:** UI chrome.
+
+---
+
+### Pitfall 13: Navigation-CMP tabs — `when`-switch kills per-tab back stack
+
+**What goes wrong:** Tabs implemented as `when (tab) { 0 -> RecipesScreen()... }`. Tapping into a detail, switching tabs, and returning loses the detail. System back exits the app instead of unwinding the tab.
+
+**Why:** A `when` switch destroys the non-current tab's Compose tree. Jetpack Navigation's multi-back-stack requires either each tab as a destination in a parent NavHost, or per-tab nested `NavHost` instances, with `popUpTo(saveState) + restoreState + launchSingleTop`.
+
+**Warning signs:** Deep-links don't restore; back from a nested screen jumps tabs; ViewModels re-created on tab switches.
+
+**How to avoid:** One top-level `NavHost`; `navigation(route = "recipesGraph", ...)` block per tab. Bottom bar navigates: `popUpTo(graph.findStartDestination().id) { saveState = true }; launchSingleTop = true; restoreState = true`. Scope `koinViewModel()` to the destination's `NavBackStackEntry`, not the parent graph. Wasm deep-links are deferred per PROJECT.md.
+
+**Phase:** UI chrome.
+
+---
+
+### Pitfall 14: Polish locale — plurals and timestamp zones
+
+**What goes wrong:** "added 2 godzina temu" (wrong plural form). Shopping items near midnight show on the wrong day across devices.
+
+**Why:** Polish has four CLDR plural forms (one / few / many / other). Naive `if (n == 1)` handles at most two. Serializing `LocalDateTime` over the wire (instead of UTC `Instant`) produces zone/DST bugs.
+
+**Warning signs:** Grammatically wrong Polish copy; yesterday's items shown as today's.
+
+**How to avoid:** Use Compose Resources `<plurals>` with all four forms; call `pluralStringResource(count)`. Wire format: `Instant` UTC ISO-8601 only; display: `.toLocalDateTime(TimeZone.currentSystemDefault())`. Unit test plurals with count 0/1/2/5/22.
+
+**Phase:** UI chrome (i18n foundation).
+
+---
+
+## Technical Debt Patterns
+
+| Shortcut | Immediate Benefit | Long-term Cost | When Acceptable |
+|---|---|---|---|
+| Ad-hoc `psql` DDL, skipping Flyway | Fast schema iteration | Dev/prod drift; can't rebuild from scratch | Pre-first-deploy only; squash into `V1__init.sql` before real data |
+| Hardcoded OIDC issuer/client_id in `shared/commonMain` | Avoids build-config plumbing | Can't run against staging Authentik; Authentik change forces rebuild | v1 single-environment only |
+| Plain `transaction {}` in admin endpoints | Simpler mental model | Mixing blocking + suspend patterns leaks; eventually every endpoint wants suspend | Admin-only, single-user endpoints |
+| Free-form `meal_entry.extras` JSONB without schema | Evolve without migrations | No DB validation; orphan fields accumulate; hard to query | Until extras shape stabilizes; then promote hot fields to columns |
+| No indices until queries are slow | Faster early dev | p99 cliffs during sync; adding indices under load is risky | Until first data import; then index every `(household_id, updated_at)` |
+
+## Integration Gotchas
+
+| Integration | Common Mistake | Correct Approach |
+|---|---|---|
+| Authentik OIDC | Confidential client type with secret shipped in binary | Public client + PKCE S256; never ship `client_secret` |
+| Authentik OIDC | Leaving default signing alg; Ktor JWT expects RS256 | Configure RS256 explicitly; verify `kid` resolves via JWKS |
+| Haze + Scaffold | `hazeSource` on Scaffold root + `hazeChild` on a sheet both capturing | `hazeSource` on scrollable content only; chrome uses `hazeChild` |
+| App Store / TestFlight | ATS exception to reach homelab self-signed cert | Real cert via Let's Encrypt + Caddy/Traefik; never ship ATS exceptions |
+| Postgres JSONB | `WHERE extras->>'k' = 'v'` with no GIN index | `CREATE INDEX ... USING GIN (extras jsonb_path_ops)` once access patterns emerge |
+
+## Performance Traps
+
+| Trap | Symptoms | Prevention | When It Breaks |
+|---|---|---|---|
+| Pull sync without pagination | First-sync-after-seed hangs seconds | Cursor-paginate `LIMIT 200 ORDER BY updated_at, id` | >500 rows in any scoped table |
+| Coil full-res images in recipe grid | Memory spikes, laggy scroll | Explicit thumbnail `Size`; memory+disk cache | >30 images on screen |
+| Compose recomposition of entire calendar per edit | Calendar flashes on slot change; scroll resets | Stable IDs per slot; hoist per-slot state; `derivedStateOf` for totals | Any calendar with >7 days visible |
+| Haze over full scrolling region | Jank on iPhone XR/11 | Blur chrome only, not content; fallback for old devices | Pre-A13 silicon on 60 Hz panels |
+
+## Security Mistakes
+
+| Mistake | Risk | Prevention |
+|---|---|---|
+| Missing `WHERE household_id = :caller_household` on reads | Cross-household data leak | All scoped reads go through a `HouseholdScope` helper; review rule: no raw `selectAll()` on scoped tables |
+| Trusting client-supplied `household_id` in request body | Tenancy bypass via crafted POST | Derive `household_id` from JWT `sub` → `memberships`; ignore body's value |
+| Logging the `Authorization` header in Ktor `CallLogging` | Tokens leak to log files → account compromise | Custom log filter redacting `Authorization`; never `log.info(token)` |
+| Storing OIDC refresh token in plain prefs | Local/backup exposure | `multiplatform-settings` with Keychain (iOS) / EncryptedSharedPreferences (Android) backends |
+
+## "Looks Done But Isn't" Checklist
+
+- [ ] **Auth:** Login works — verify token refresh runs before expiry (set Authentik access-token lifetime to 5 min in dev; watch for silent 401s)
+- [ ] **Sync:** Pull works — verify tombstones propagate (delete on A, confirm gone on B after pull, not just after push)
+- [ ] **Sync:** Offline writes survive app kill + relaunch + reconnect — not just a warm resume
+- [ ] **Household isolation:** Log in as household B; hit every endpoint; assert zero household A rows returned
+- [ ] **SQLDelight migrations:** Install prior release, launch once, upgrade in place; confirm no crash, no data loss
+- [ ] **Polish plurals:** Open every screen with counts 0, 1, 2, 5, 22; verify grammar
+- [ ] **Haze performance:** Test on oldest supported device (iPhone XS/11) scrolling a full screen; not just simulator
+
+## Pitfall-to-Phase Mapping
+
+| Pitfall | Prevention Phase | Verification |
+|---|---|---|
+| K/N GC thrash; `objcDisposeOnMain` | UI chrome (infra) | Gradle property set; Instruments shows no GC-main domination |
+| Legacy `freeze()` ceremony | Data | Code search for `freeze(`, `@SharedImmutable` returns empty |
+| UIViewController re-creation | UI chrome | State survives background/foreground cycle |
+| SQLDelight missing migration | Data | Prior-build → new-build upgrade test on real device |
+| Blocking Exposed transaction in suspend | Data | No `transaction {` in suspend paths; 50-concurrent-request load test with pool size 10 |
+| DAO + JSONB | Data | No `exposed.dao.*` imports; per-JSONB-column round-trip test |
+| JWT aud/iss/leeway/JWKS | Auth | Wrong-aud → 401; 30 s skew → 200; JWKS refreshes within 15 min |
+| OIDC redirect URI / PKCE | Auth | Flow passes on iOS *and* Android; Authentik logs show `code_challenge` per request |
+| LWW client-clock trust | Sync | All writes set `updated_at` server-side; clients never send it |
+| Soft-delete recreate race | Sync | Two-client alternating delete/recreate converges |
+| Pull-cursor edge cases | Sync | Cursor is `(updated_at, id)` lexicographic; same-timestamp test |
+| Haze scroll jank | UI chrome | iPhone 11 real-device FPS >55 on recipe grid scroll |
+| Nested NavHost / multi-back-stack | UI chrome | Tab switch preserves deep state; system back unwinds within tab |
+| Polish plurals / timestamps | UI chrome | Plural unit tests pass; wire format is UTC-only |
+| Household tenancy bypass | Auth + Sync | Cross-household read test asserts empty result sets |
+
+## Sources
+
+- [Kotlin/Native memory management](https://kotlinlang.org/docs/native-memory-manager.html) (HIGH)
+- [Compose Multiplatform for iOS Stable, 2025](https://www.kmpship.app/blog/compose-multiplatform-ios-stable-2025) (MEDIUM)
+- [Haze 1.0 release notes — Chris Banes](https://chrisbanes.me/posts/haze-1.0/) (HIGH)
+- [Haze Platforms documentation](https://chrisbanes.github.io/haze/latest/platforms/) (HIGH)
+- [Navigation in Compose Multiplatform — JetBrains](https://kotlinlang.org/docs/multiplatform/compose-navigation.html) (HIGH)
+- [Bottom Nav + Nested Navigation guide](https://saurabhjadhavblogs.com/jetpack-compose-bottom-navigation-nested-navigation-solved) (MEDIUM)
+- [Exposed — Working with Transactions](https://www.jetbrains.com/help/exposed/transactions.html) (HIGH)
+- [Exposed — JSON/JSONB types](https://www.jetbrains.com/help/exposed/json-and-jsonb-types.html) (HIGH)
+- [Exposed — Breaking Changes](https://www.jetbrains.com/help/exposed/breaking-changes.html) (HIGH)
+- Community-known K/N + KMP gotchas synthesized from training + surrounding sources (MEDIUM)
+
+---
+*Pitfalls research for: Kotlin Multiplatform recipe/meal-planning app with self-hosted Ktor + Postgres + Authentik backend*
+*Researched: 2026-04-23*

.planning/research/SUMMARY.md

@@ -0,0 +1,159 @@
+# Project Research Summary
+
+**Project:** Recipe (working title) — household meal planner + pantry + shopping list
+**Domain:** Mobile (iOS-primary) + self-hosted backend, offline-first collaborative app for a 2-person household
+**Researched:** 2026-04-24
+**Confidence:** HIGH
+
+## Executive Summary
+
+This is a household-scoped meal-planning app built as a Kotlin Multiplatform client (iOS-primary) against a self-hosted Ktor server, with offline-first operation and last-write-wins sync over HTTP polling. The core value is "my week is planned" — the planner is the hero feature; pantry and shopping exist to reinforce it. User-base is ~5-10 authenticated users across a handful of households. Tech stack was locked in a direct discussion rather than derived from research, so the research scope was narrowed to two areas where novel value was expected: **architecture patterns within the locked stack** and **pitfalls specific to this library combination**.
+
+The recommended approach centers on a **sync-engine-first** architecture: a single Koin-singleton `SyncEngine` owns the outbox, the pull cursor, and the push/pull cycles; repositories only write to SQLDelight + outbox, never to HTTP directly. Every feature in the app sits on top of this spine, which decouples UI/domain from transport concerns and makes offline-first a property of the system rather than a per-feature discipline. Household scope is enforced at **three layers** (client query filter, server `PrincipalResolver` deriving household from JWT `sub`, and a `household_id` column on every tenant-scoped table) — single-layer enforcement is consistently the source of cross-tenant data leaks in apps like this.
+
+The **highest-risk area** is sync correctness under concurrent household edits. LWW with device-clock timestamps silently loses data when clocks drift; the mitigation is server-assigned `updated_at` for every write, UUIDs (never composite natural keys like `(date, slot)`) as row identity, and a `(updated_at, id)` lexicographic pull cursor with microsecond precision to survive same-millisecond edits. Secondary risks: Kotlin/Native memory/GC on iPhone 12-era devices, Ktor JWT validation leeway and JWKS caching interactions with Authentik, and Haze blur over scrolling content on older iPhones.
+
+## Key Findings
+
+### Recommended Stack
+
+Locked via direct discussion (see PROJECT.md § Key Decisions). No research-driven changes required.
+
+**Core technologies:**
+- Compose Multiplatform + Jetpack Navigation CMP port — iOS-primary UI, official JetBrains-recommended router
+- Koin + SQLDelight + Ktor Client + kotlinx.serialization/datetime + Kermit + Coil 3 + Haze — canonical KMP client stack in 2026
+- Ktor Server + Exposed (DSL, not DAO) + Postgres + Flyway + ktor-server-auth-jwt — canonical Kotlin backend
+- Authentik OIDC — user's existing homelab identity provider
+
+### Expected Features
+
+Not researched (user explicitly opted to start catalog fresh rather than survey the market). Active v1 requirements captured directly in PROJECT.md § Requirements — four feature pillars: recipe catalog browse, meal planner, pantry, shopping list; plus auth, household sharing, and offline sync foundations.
+
+### Architecture Approach
+
+See `.planning/research/ARCHITECTURE.md` for the full treatment.
+
+**Major components (top to bottom):**
+1. **Compose UI + Navigation** — screens observe ViewModel state; navigation via Jetpack Nav CMP with nested NavHosts per tab for independent back stacks
+2. **ViewModel layer** — StateFlow of immutable `UiState`, method-per-action pattern, scoped to `NavBackStackEntry` via `koinViewModel()`
+3. **Repository layer** — domain-shaped API; reads return SQLDelight Flows `.asFlow().mapToList(dispatcher)`; writes go to SQLDelight + outbox atomically
+4. **SyncEngine (Koin singleton)** — drives outbox drain (push) and pull cursor (poll on foreground + pull-to-refresh + debounced-after-write); owns all HTTP sync traffic
+5. **Local DataSources** — thin wrappers over SQLDelight generated queries; one driver per process, threaded correctly for iOS NativeSqliteDriver
+6. **Remote DataSources** — Ktor Client with JSON negotiation; catalog fetches use HTTP caching; sync endpoints are separate from catalog
+7. **Server Ktor routes** — auth-gated via `Authentication.jwt("authentik")`; every household-scoped handler routes through a `PrincipalResolver` that looks up membership once
+8. **Server DB (Exposed + Postgres + Flyway)** — DSL-only, JSONB for meal-entry extras, `newSuspendedTransaction` for every coroutine-touching handler
+
+### Critical Pitfalls
+
+See `.planning/research/PITFALLS.md` for 14 critical pitfalls + anti-pattern tables. The five most load-bearing:
+
+1. **Sync correctness under concurrent edits** — server-assigned `updated_at`, UUID row identity, lexicographic `(updated_at, id)` pull cursor. Any shortcut here causes silent data loss.
+2. **Ktor JWT + Authentik integration** — audience, issuer, clock-skew leeway, JWKS cache TTL all configurable; default values fail silently when clocks drift or keys rotate. Explicit configuration mandatory.
+3. **OIDC redirect URI + PKCE** — byte-exact match required; mobile clients are public so PKCE is mandatory. Common cause of 400-series auth loops that are opaque without server logs.
+4. **Household tenancy derivation** — `household_id` always derived from authenticated `sub`, never accepted from request body. Single source of cross-tenant leaks.
+5. **iOS infra hygiene** — `kotlin.native.binary.objcDisposeOnMain=false`, `gc=cms`, single `ComposeUIViewController` instance, Haze on chrome only (never over scrolling content). Cheap to bake in day 1; painful to retrofit when iPhone XR/11 users complain about jank.
+
+## Implications for Roadmap
+
+The architecture research suggests an explicit **foundation-first** build order. The pitfalls research reinforces this by surfacing that most high-cost mistakes live in the foundation (sync engine, auth validation, household scope), not the feature layer. Suggested phase skeleton:
+
+### Phase 1: Project infrastructure + module wiring
+**Rationale:** One-time setup that blocks everything. Convention plugins, version catalog, Koin bootstrap, shared DTOs module, iOS target config with binary flags (`objcDisposeOnMain`, `gc=cms`), server Gradle setup, Flyway plumbing.
+**Delivers:** A running but empty composeApp (iOS + Android) + running but unrouted Ktor server.
+**Avoids:** Retrofit cost on iOS memory flags and Gradle conventions mid-project.
+
+### Phase 2: Authentication foundation
+**Rationale:** Nothing else can be built without authenticated principals. Blocks sync, household data, all CRUD.
+**Delivers:** Client OIDC flow (AppAuth on Android, ASWebAuthenticationSession on iOS) to Authentik → access token stored. Server ktor-server-auth-jwt validates token against Authentik JWKS. Protected `/api/v1/me` endpoint returns user.
+**Avoids:** Pitfalls 7 + 8 (JWT validation misconfig, redirect URI/PKCE errors).
+
+### Phase 3: Households + membership + server data foundation
+**Rationale:** Every feature table needs `household_id`. Introducing this after feature tables exist is a migration nightmare.
+**Delivers:** `users`, `households`, `memberships`, `invites` tables + Flyway migrations. `PrincipalResolver` that maps JWT `sub` → `household_id`. Endpoints for creating a household, generating invite codes, accepting invites. Client auth session now includes `household_id`.
+**Avoids:** Tenant-scope leaks, cross-household data bugs.
+
+### Phase 4: Sync engine skeleton
+**Rationale:** Second-hardest piece after auth. Must exist before any feature-specific data can be synced. Built on a trivial first table (e.g., a `notes` sentinel table or the `households` metadata).
+**Delivers:** SyncEngine interface + implementation. Outbox schema in SQLDelight with `id`, `table`, `row_id`, `op`, `payload`, `created_at`. `/api/v1/sync/push` and `/api/v1/sync/pull` endpoints. Polling scheduler + pull-to-refresh + debounced after-write trigger. Cursor persistence. Mock table round-trips.
+**Avoids:** Pitfalls 9, 10, 11 (LWW timestamp sources, delete-recreate races, cursor edge cases).
+
+### Phase 5: Recipe catalog (read path)
+**Rationale:** Read-mostly, simpler sync (no writes from client), teaches Exposed + SQLDelight + Ktor end-to-end. Seeds the rest of the app with real data to develop against.
+**Delivers:** `recipes`, `ingredients`, `products` tables on server (Flyway migrations). Seed data mechanism (SQL fixtures or admin CLI). Catalog Ktor routes. Client-side catalog cache in SQLDelight with pull-only sync. RecipeListScreen + RecipeDetailScreen reading from local cache.
+**Avoids:** Sync-strategy-by-accident (catalog uses different cache rules than household data).
+
+### Phase 6: Meal planner (hero write path)
+**Rationale:** Core value. Exercises the full write path: optimistic local write + outbox + sync.
+**Delivers:** `plan_entry` table (server + client) with `household_id` + `updated_at` + `deleted_at`. Planner calendar UI. Add/remove/edit meal flows. Nutrition totals computed client-side from catalog + plan.
+**Avoids:** Pitfall 1 (sync correctness), by this point the foundation is already correct.
+
+### Phase 7: Pantry
+**Rationale:** Second household-scoped feature. Reuses all of the plumbing from Phase 6. Validates that sync foundation generalizes.
+
+### Phase 8: Shopping list + session log
+**Rationale:** Computed view over pantry + plan + a small session table. Ties the three data sources together.
+
+### Phase 9: UI chrome with Haze liquid-glass approximation
+**Rationale:** Intentionally late. Earlier phases use boring default chrome to avoid blocking on design. Now swap in Haze-based nav and tab bars, glassy cards, dark mode polish. Measurable real-device perf can be validated against real data from Phase 6-8.
+**Avoids:** Pitfall 12 (Haze perf regressions — easier to measure once data volume is realistic).
+
+### Phase 10: Polish, polish infra, iOS deployment
+**Rationale:** Externalized strings with Polish copy, locale-aware date formatting (local display only — wire stays UTC), Bundle ID + privacy manifests, TestFlight distribution to partner.
+
+### Phase 11 (optional, post-v1): Recipe authoring in-app
+**Rationale:** Explicitly deferred in PROJECT.md. First v1 seeds catalog via server migrations.
+
+### Phase Ordering Rationale
+
+- **Auth → Households → SyncEngine → features**: each layer enables the next; skipping any accelerates for a week and costs a month (from ARCHITECTURE.md § Build Order).
+- **Catalog (read) before planner (write)**: reads are simpler and catch sync-pull bugs in isolation before writes introduce push/outbox/conflict bugs.
+- **UI chrome last**: Haze perf is measurable only with realistic data; design iteration shouldn't block data-layer correctness.
+
+### Research Flags
+
+Phases likely needing deeper phase-level research during planning:
+- **Phase 2 (Auth):** Authentik-specific OIDC provider setup steps; AppAuth vs custom iOS wrapper tradeoffs; token refresh behavior
+- **Phase 4 (SyncEngine):** Concrete cursor format, outbox schema ordering guarantees, retry/backoff policy
+- **Phase 9 (UI chrome):** Current Haze perf benchmarks on CMP iOS; liquid-glass approximation design patterns
+
+Phases with well-trodden paths (minimal research-phase needed):
+- **Phase 1 (Infra):** Convention plugins + version catalog is well-documented
+- **Phase 5 (Catalog read):** Basic CRUD + cache pattern
+- **Phases 6-8 (features):** Once foundation is in place, these follow the architecture patterns directly
+
+## Confidence Assessment
+
+| Area | Confidence | Notes |
+|------|------------|-------|
+| Stack | HIGH | Locked in direct discussion with tradeoff analysis per library |
+| Features | HIGH (scope-bounded) | User defined v1 directly in PROJECT.md; no market research done, intentionally |
+| Architecture | HIGH | Research agent produced concrete patterns specific to the locked stack |
+| Pitfalls | HIGH | 14 specific pitfalls with library-level detail; covers all major risk areas |
+
+**Overall confidence:** HIGH for entering the roadmap phase.
+
+### Gaps to Address
+
+- **Authentik-specific OIDC flow details** — the research documented WHAT to get right (JWT validation, PKCE, redirect URIs) but not Authentik's specific UI/config steps. Resolve during Phase 2 planning.
+- **Mobile OIDC library choice for iOS** — PROJECT.md notes "ASWebAuthenticationSession wrapper" with no specific KMP wrapper library recommended. Resolve during Phase 2 planning.
+- **Haze current CMP-iOS perf characteristics on iPhone 12-era hardware** — needs real-device measurement, not research. Covered by Phase 9.
+- **Seed-data mechanism** — "SQL migrations, JSON fixtures, or CLI tool" listed as options in PROJECT.md § Constraints. Resolve during Phase 5 planning.
+
+## Sources
+
+### Primary (HIGH confidence)
+- `.planning/PROJECT.md` — authoritative product scope + locked stack
+- `.planning/research/ARCHITECTURE.md` — agent-researched, ~1900 words, 7 sections
+- `.planning/research/PITFALLS.md` — agent-researched, ~2800 words, 14 critical pitfalls + tables
+
+### Secondary
+- Direct discussion transcript (April 2026) — tech-stack tradeoff conversation that led to PROJECT.md decisions
+- [Navigation in Compose Multiplatform](https://kotlinlang.org/docs/multiplatform/compose-navigation.html)
+- [Kotlin/Native memory management](https://kotlinlang.org/docs/native-memory-manager.html)
+- [Haze 1.0 — Chris Banes](https://chrisbanes.me/posts/haze-1.0/)
+- [Exposed — Transactions](https://www.jetbrains.com/help/exposed/transactions.html)
+- [Exposed — JSON/JSONB types](https://www.jetbrains.com/help/exposed/json-and-jsonb-types.html)
+
+---
+*Research completed: 2026-04-24*
+*Ready for roadmap: yes*

CLAUDE.md

@@ -0,0 +1,117 @@
+# CLAUDE.md
+
+Guidance for Claude Code when working in this repository.
+
+## Project
+
+**Recipe** (working title) — a household meal planning + pantry + shopping list app built with Kotlin Multiplatform (iOS-primary) and a self-hosted Ktor server. Offline-first with last-write-wins sync; household sharing (me + partner); auth via self-hosted Authentik (OIDC).
+
+**Core value:** "My week is planned." I pick recipes, the calendar fills up, and I know what we're eating.
+
+## Planning workflow — always start here
+
+This project uses GSD (Get Shit Done). All product scope, tech decisions, requirements, and phase structure live in `.planning/`. **Read these files before doing any implementation work.**
+
+| File | What it is | When to read |
+|------|-----------|--------------|
+| `.planning/PROJECT.md` | Product scope, locked tech decisions, constraints, out-of-scope | Every session — source of truth |
+| `.planning/REQUIREMENTS.md` | 72 v1 requirements with REQ-IDs grouped by category, plus v2 / out-of-scope | When touching any feature area |
+| `.planning/ROADMAP.md` | 11 phases with goals, mapped requirements, success criteria | To know which phase we're in |
+| `.planning/STATE.md` | Current phase + high-level pointer | Fast orientation |
+| `.planning/config.json` | Workflow settings (YOLO mode, fine granularity, quality models) | Rarely — set once |
+| `.planning/research/SUMMARY.md` | Executive synthesis of architecture + pitfalls research | When planning a phase |
+| `.planning/research/ARCHITECTURE.md` | Component structure, data flow, build-order reasoning | When structuring code |
+| `.planning/research/PITFALLS.md` | 14 critical pitfalls specific to this stack | Before touching auth, sync, or iOS specifics |
+
+## Tech stack (locked — see PROJECT.md § Key Decisions for full rationale)
+
+**Client (`composeApp/`):**
+- Kotlin Multiplatform + Compose Multiplatform (iOS-primary; Android, Desktop, Wasm secondary)
+- Navigation: `org.jetbrains.androidx.navigation:navigation-compose` (JetBrains-official CMP port of Jetpack Navigation)
+- State: ViewModel + StateFlow, method-per-action; `org.jetbrains.androidx.lifecycle:lifecycle-viewmodel-compose`
+- DI: Koin (`koin-core`, `koin-compose`, `koin-compose-viewmodel`)
+- Local DB: SQLDelight 2.x (raw `.sq` files, generated type-safe Kotlin)
+- HTTP: Ktor Client
+- Serialization: kotlinx.serialization
+- Date/time: kotlinx.datetime
+- Logging: Kermit (Touchlab)
+- Images: Coil 3 (`io.coil-kt.coil3:coil-compose`)
+- Settings/KV: `com.russhwolf:multiplatform-settings`
+- Glass/blur: Haze (`dev.chrisbanes.haze:haze`)
+- Mobile OIDC: AppAuth on Android; ASWebAuthenticationSession wrapper on iOS (KMP interface)
+
+**Server (`server/`):**
+- Ktor Server 3.x on the user's homelab (alongside Authentik)
+- Postgres
+- Exposed (DSL only — never the DAO / active-record API)
+- Flyway for migrations
+- Auth: `io.ktor:ktor-server-auth-jwt` validating Authentik tokens via JWKS
+
+**Shared (`shared/commonMain`):**
+- Domain models + API DTOs only
+- No UI, no HTTP, no DB code — keep dependency graph minimal
+
+**Sync:** Last-write-wins with server-assigned `updated_at`; HTTP polling (20–30s foreground) + pull-to-refresh + debounced push after writes. `POST /api/v1/sync/push`, `GET /api/v1/sync/pull?since=...`.
+
+## Module structure
+
+```
+recipe/
+├── composeApp/          # KMP: commonMain + androidMain + iosMain + jvmMain (desktop)
+├── iosApp/              # iOS bootstrap (Swift/SwiftUI thin shell)
+├── server/              # Ktor + Exposed + Postgres + Flyway
+├── shared/              # commonMain: domain + DTOs, no UI/HTTP/DB
+├── build-logic/         # Convention plugins (Kotlin/Compose/test config)
+├── gradle/libs.versions.toml  # Single source of truth for versions
+└── .planning/           # GSD planning artifacts (see above)
+```
+
+**Package layout inside `composeApp/commonMain`:**
+```
+dev.ulfrx.recipe/
+├── app/                 # App entry, Koin init, theme
+├── navigation/          # NavHost, routes, nav graph (nested NavHosts per tab)
+├── ui/
+│   ├── theme/           # Colors, typography, Haze glass styles
+│   ├── components/      # Shared composables
+│   └── screens/{recipes,planner,pantry,shopping}/  # Each with screen + ViewModel
+├── data/{local,remote,repository}/
+└── domain/              # Client-only logic; shared/ handles cross-cutting
+```
+
+**Rule:** No feature modules in v1. Flat `composeApp/commonMain` with the package layout above.
+
+## Non-negotiable conventions
+
+1. **Sync timestamps come from the server, never the device.** `updated_at` is assigned server-side; pulling uses lexicographic `(updated_at, id)` cursor.
+2. **Row identity is always UUIDs, never composite natural keys.** `(date, slot)` is not a primary key. See ARCHITECTURE.md § Anti-Patterns.
+3. **Household scope is enforced in 3 layers:** client query filter + server `PrincipalResolver` deriving `householdId` from JWT `sub` + DB `household_id` column. Never accept `household_id` from request body.
+4. **All sync I/O goes through the `SyncEngine` Koin singleton.** Features write to SQLDelight + outbox, never to HTTP directly. See ARCHITECTURE.md § Pattern 2.
+5. **Exposed DSL only, never DAO.** Active-record pattern has footguns with JSONB and coroutines.
+6. **`newSuspendedTransaction` for every coroutine-touching handler.** Plain `transaction {}` inside a `suspend` block exhausts the connection pool.
+7. **iOS binary flags on day 1:** `kotlin.native.binary.objcDisposeOnMain=false`, `kotlin.native.binary.gc=cms`.
+8. **`shared/commonMain` stays light.** No Ktor, Compose, or SQLDelight imports.
+9. **Strings externalized from day 1** — Polish-only content, but resources are multi-locale-ready.
+10. **Haze blur on chrome only** (tab bar, nav bar), never over fast-scrolling content.
+
+## Current phase
+
+See `.planning/STATE.md`. The roadmap has 11 phases; you must work within the currently active one. Don't jump ahead.
+
+**Build order (load-bearing — do not reorder):**
+Phase 1 Infra → Phase 2 Auth → Phase 3 Households → Phase 4 SyncEngine skeleton → Phase 5 Recipe catalog → Phase 6 Planner core → Phase 7 Planner customization/nutrition → Phase 8 Pantry → Phase 9 Shopping → Phase 10 UI chrome (Haze) → Phase 11 Localization + deployment.
+
+## GSD commands you'll use
+
+- `/gsd-progress` — show current state and suggest next action
+- `/gsd-discuss-phase N` — socratic phase clarification before planning
+- `/gsd-plan-phase N` — produce detailed PLAN.md for phase N
+- `/gsd-execute-phase N` — execute the plans in phase N
+- `/gsd-next` — automatically advance to the next logical step
+
+## Functional reference
+
+The legacy PWA mockup at `~/dev/repo/recipe-mockup/` is the **functional** reference (logic, data shapes, user flows). It is **not** a visual reference — UI is being rebuilt around a Liquid-Glass-inspired language. Mine it for planner customization logic (substitutions, amount overrides, product selections), shortfall computation, and shopping aggregation. Do not port its vanilla-JS data or Tailwind styling.
+
+---
+*Initialized: 2026-04-24. Update when `.planning/PROJECT.md` § Key Decisions gains load-bearing new entries.*

README.md

@@ -74,21 +74,56 @@ in your IDE's toolbar or run it directly from the terminal:
       ```shell
       .\gradlew.bat :composeApp:wasmJsBrowserDevelopmentRun
       ```
-- for the JS target (slower, supports older browsers):
-    - on macOS/Linux
-      ```shell
-      ./gradlew :composeApp:jsBrowserDevelopmentRun
-      ```
-    - on Windows
-      ```shell
-      .\gradlew.bat :composeApp:jsBrowserDevelopmentRun
-      ```
 
 ### Build and Run iOS Application
 
 To build and run the development version of the iOS app, use the run configuration from the run widget
 in your IDE’s toolbar or open the [/iosApp](./iosApp) directory in Xcode and run it from there.
 
+### Local development
+
+The server requires Postgres. A `docker-compose.yml` at the repo root ships a local Postgres
+instance whose credentials match `application.conf` defaults (`recipe`/`recipe`/`recipe`).
+
+Boot the database and server:
+
+```shell
+docker compose up -d postgres
+./gradlew :server:run
+```
+
+Verify the server is up:
+
+```shell
+curl http://localhost:8080/health
+# expected: {"status":"ok"}
+```
+
+Environment overrides (optional — set any of these to override `application.conf` defaults):
+
+- `DATABASE_URL` — JDBC URL (default `jdbc:postgresql://localhost:5432/recipe`)
+- `DATABASE_USER` — DB user (default `recipe`)
+- `DATABASE_PASSWORD` — DB password (default `recipe`)
+- `PORT` — Ktor port (default `8080`)
+
+Before committing, format all Kotlin + Gradle + Markdown files:
+
+```shell
+./gradlew spotlessApply
+```
+
+The full check (Spotless + all tests across all targets):
+
+```shell
+./gradlew check
+```
+
+Reset the local database (destroys the `recipe-pgdata` volume):
+
+```shell
+docker compose down -v
+```
+
 ---
 
 Learn more about [Kotlin Multiplatform](https://www.jetbrains.com/help/kotlin-multiplatform-dev/get-started.html),

build-logic/build.gradle.kts

@@ -0,0 +1,18 @@
+plugins {
+    `kotlin-dsl`
+}
+
+dependencies {
+    compileOnly(libs.plugins.kotlinMultiplatform.asDependency())
+    compileOnly(libs.plugins.androidApplication.asDependency())
+    compileOnly(libs.plugins.composeMultiplatform.asDependency())
+    compileOnly(libs.plugins.composeCompiler.asDependency())
+    compileOnly(libs.plugins.composeHotReload.asDependency())
+    compileOnly(libs.plugins.kotlinJvm.asDependency())
+    compileOnly(libs.plugins.ktor.asDependency())
+    compileOnly(libs.plugins.spotless.asDependency())
+    compileOnly(libs.plugins.flywayPlugin.asDependency())
+}
+
+fun Provider<PluginDependency>.asDependency(): Provider<String> =
+    map { "${it.pluginId}:${it.pluginId}.gradle.plugin:${it.version.requiredVersion}" }

build-logic/settings.gradle.kts

@@ -0,0 +1,14 @@
+dependencyResolutionManagement {
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+    versionCatalogs {
+        create("libs") {
+            from(files("../gradle/libs.versions.toml"))
+        }
+    }
+}
+
+rootProject.name = "build-logic"

build-logic/src/main/kotlin/recipe.android.application.gradle.kts

@@ -0,0 +1,35 @@
+import org.gradle.api.artifacts.VersionCatalogsExtension
+import org.gradle.kotlin.dsl.getByType
+
+plugins {
+    id("com.android.application")
+}
+
+val libs = extensions.getByType<VersionCatalogsExtension>().named("libs")
+
+android {
+    namespace = "dev.ulfrx.recipe"
+    compileSdk = libs.findVersion("android-compileSdk").get().toString().toInt()
+
+    defaultConfig {
+        applicationId = "dev.ulfrx.recipe"
+        minSdk = libs.findVersion("android-minSdk").get().toString().toInt()
+        targetSdk = libs.findVersion("android-targetSdk").get().toString().toInt()
+        versionCode = 1
+        versionName = "1.0"
+    }
+    packaging {
+        resources {
+            excludes += "/META-INF/{AL2.0,LGPL2.1}"
+        }
+    }
+    buildTypes {
+        getByName("release") {
+            isMinifyEnabled = false
+        }
+    }
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_11
+        targetCompatibility = JavaVersion.VERSION_11
+    }
+}

build-logic/src/main/kotlin/recipe.compose.multiplatform.gradle.kts

@@ -0,0 +1,27 @@
+import org.gradle.api.artifacts.VersionCatalogsExtension
+import org.gradle.kotlin.dsl.getByType
+
+plugins {
+    id("recipe.kotlin.multiplatform")
+    id("org.jetbrains.compose")
+    id("org.jetbrains.kotlin.plugin.compose")
+    id("org.jetbrains.compose.hot-reload")
+}
+
+val libs = extensions.getByType<VersionCatalogsExtension>().named("libs")
+
+kotlin {
+    sourceSets {
+        commonMain.dependencies {
+            implementation(libs.findLibrary("compose-runtime").get())
+            implementation(libs.findLibrary("compose-foundation").get())
+            implementation(libs.findLibrary("compose-material3").get())
+            implementation(libs.findLibrary("compose-ui").get())
+            implementation(libs.findLibrary("compose-components-resources").get())
+            implementation(libs.findLibrary("androidx-lifecycle-viewmodelCompose").get())
+            implementation(libs.findLibrary("androidx-lifecycle-runtimeCompose").get())
+            implementation(libs.findLibrary("koin-compose").get())
+            implementation(libs.findLibrary("koin-composeViewmodel").get())
+        }
+    }
+}

build-logic/src/main/kotlin/recipe.jvm.server.gradle.kts

@@ -0,0 +1,41 @@
+import org.gradle.api.artifacts.VersionCatalogsExtension
+import org.gradle.kotlin.dsl.getByType
+
+plugins {
+    id("org.jetbrains.kotlin.jvm")
+    id("io.ktor.plugin")
+    id("org.flywaydb.flyway")
+    application
+}
+
+val libs = extensions.getByType<VersionCatalogsExtension>().named("libs")
+
+kotlin {
+    jvmToolchain(21)
+    compilerOptions {
+        allWarningsAsErrors.set(true)
+    }
+}
+
+dependencies {
+    "implementation"(libs.findLibrary("ktor-serverCore").get())
+    "implementation"(libs.findLibrary("ktor-serverNetty").get())
+    "implementation"(libs.findLibrary("ktor-serverContentNegotiation").get())
+    "implementation"(libs.findLibrary("ktor-serializationKotlinxJson").get())
+    "implementation"(libs.findLibrary("logback").get())
+    "implementation"(libs.findLibrary("flyway-core").get())
+    "implementation"(libs.findLibrary("flyway-database-postgresql").get())
+    "implementation"(libs.findLibrary("postgresql").get())
+    "testImplementation"(libs.findLibrary("ktor-serverTestHost").get())
+    "testImplementation"(libs.findLibrary("kotlin-testJunit").get())
+}
+
+flyway {
+    url = System.getenv("DATABASE_URL") ?: "jdbc:postgresql://localhost:5432/recipe"
+    user = System.getenv("DATABASE_USER") ?: "recipe"
+    password = System.getenv("DATABASE_PASSWORD") ?: "recipe"
+    locations = arrayOf("classpath:db/migration")
+    cleanDisabled = true
+    baselineOnMigrate = true
+    validateOnMigrate = true
+}

build-logic/src/main/kotlin/recipe.kotlin.multiplatform.gradle.kts

@@ -0,0 +1,69 @@
+// build-logic/src/main/kotlin/recipe.kotlin.multiplatform.gradle.kts
+// Establishes the D-05 target matrix + JVM toolchain + common deps.
+// Android bytecode is JVM 11 (D-08); server + desktop + shared/jvm are JVM 21.
+
+import org.gradle.api.artifacts.VersionCatalogsExtension
+import org.gradle.kotlin.dsl.getByType
+import org.jetbrains.kotlin.gradle.ExperimentalWasmDsl
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
+plugins {
+    id("org.jetbrains.kotlin.multiplatform")
+}
+
+val libs = extensions.getByType<VersionCatalogsExtension>().named("libs")
+
+kotlin {
+    jvmToolchain(21)
+
+    androidTarget {
+        compilerOptions {
+            jvmTarget.set(JvmTarget.JVM_11)
+        }
+    }
+
+    listOf(iosArm64(), iosSimulatorArm64()).forEach { iosTarget ->
+        iosTarget.binaries.framework {
+            baseName = "ComposeApp"
+            isStatic = true
+        }
+    }
+
+    jvm {
+        compilerOptions {
+            jvmTarget.set(JvmTarget.JVM_21)
+        }
+    }
+
+    @OptIn(ExperimentalWasmDsl::class)
+    wasmJs { browser() }
+
+    compilerOptions {
+        allWarningsAsErrors.set(true)
+    }
+
+    sourceSets {
+        commonMain.dependencies {
+            implementation(project.dependencies.platform(libs.findLibrary("koin-bom").get()))
+            implementation(libs.findLibrary("koin-core").get())
+            implementation(libs.findLibrary("kermit").get())
+        }
+        commonTest.dependencies {
+            implementation(libs.findLibrary("kotlin-test").get())
+        }
+    }
+}
+
+// Relax allWarningsAsErrors for KLIB-merging metadata tasks. KotlinCompileCommon
+// aggregates dependency KLIBs and surfaces upstream "duplicated unique_name"
+// resolver warnings caused by androidx.lifecycle 2.10.0 (Android-only) and
+// org.jetbrains.androidx.lifecycle 2.10.0 (CMP) co-publishing artifacts with
+// matching KLIB unique_names. This is an upstream Compose-Multiplatform 1.10 +
+// lifecycle 2.10 ecosystem condition (KT-62515-style), not actionable in our
+// source — so we keep -Werror on real source compilation tasks but disable it
+// for the metadata-aggregation step where no user code is being compiled.
+tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompileCommon>().configureEach {
+    compilerOptions {
+        allWarningsAsErrors.set(false)
+    }
+}

build-logic/src/main/kotlin/recipe.quality.gradle.kts

@@ -0,0 +1,40 @@
+plugins {
+    id("com.diffplug.spotless")
+}
+
+spotless {
+    kotlin {
+        target("src/**/*.kt")
+        targetExclude("**/build/**", "**/generated/**")
+        ktlint()
+    }
+    kotlinGradle {
+        target("*.gradle.kts")
+        ktlint()
+    }
+    format("markdown") {
+        target("*.md", "docs/**/*.md")
+        endWithNewline()
+        trimTrailingWhitespace()
+    }
+}
+
+// D-11 redundancy guard: if a module applies recipe.quality alongside a Kotlin plugin
+// (multiplatform or jvm), ensure allWarningsAsErrors still applies even if the module
+// build didn't already configure it. Guarded with plugins.withId so this plugin is
+// safely composable even when applied alone (no KotlinCompilationTask type available
+// on the classpath until a Kotlin plugin is present).
+plugins.withId("org.jetbrains.kotlin.multiplatform") {
+    tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask<*>>().configureEach {
+        compilerOptions {
+            allWarningsAsErrors.set(true)
+        }
+    }
+}
+plugins.withId("org.jetbrains.kotlin.jvm") {
+    tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask<*>>().configureEach {
+        compilerOptions {
+            allWarningsAsErrors.set(true)
+        }
+    }
+}

build.gradle.kts

@@ -9,4 +9,6 @@ plugins {
     alias(libs.plugins.kotlinJvm) apply false
     alias(libs.plugins.kotlinMultiplatform) apply false
     alias(libs.plugins.ktor) apply false
+    alias(libs.plugins.spotless) apply false
+    alias(libs.plugins.flywayPlugin) apply false
 }

composeApp/build.gradle.kts

@@ -1,64 +1,24 @@
-import org.jetbrains.compose.desktop.application.dsl.TargetFormat
-import org.jetbrains.kotlin.gradle.ExperimentalWasmDsl
-import org.jetbrains.kotlin.gradle.dsl.JvmTarget
-
 plugins {
-    alias(libs.plugins.kotlinMultiplatform)
-    alias(libs.plugins.androidApplication)
-    alias(libs.plugins.composeMultiplatform)
-    alias(libs.plugins.composeCompiler)
-    alias(libs.plugins.composeHotReload)
+    // AGP must apply BEFORE recipe.kotlin.multiplatform — the latter calls androidTarget(),
+    // which requires the Android Gradle Plugin to already be on the project. Gradle applies
+    // plugin IDs in declaration order, so recipe.android.application is listed first.
+    id("recipe.android.application")
+    id("recipe.kotlin.multiplatform")
+    id("recipe.compose.multiplatform")
+    id("recipe.quality")
 }
 
 kotlin {
-    androidTarget {
-        compilerOptions {
-            jvmTarget.set(JvmTarget.JVM_11)
-        }
-    }
-
-    listOf(
-        iosArm64(),
-        iosSimulatorArm64()
-    ).forEach { iosTarget ->
-        iosTarget.binaries.framework {
-            baseName = "ComposeApp"
-            isStatic = true
-        }
-    }
-
-    jvm()
-
-    js {
-        browser()
-        binaries.executable()
-    }
-
-    @OptIn(ExperimentalWasmDsl::class)
-    wasmJs {
-        browser()
-        binaries.executable()
-    }
-
     sourceSets {
         androidMain.dependencies {
             implementation(libs.compose.uiToolingPreview)
             implementation(libs.androidx.activity.compose)
+            implementation(libs.koin.android)
         }
         commonMain.dependencies {
-            implementation(libs.compose.runtime)
-            implementation(libs.compose.foundation)
-            implementation(libs.compose.material3)
-            implementation(libs.compose.ui)
-            implementation(libs.compose.components.resources)
             implementation(libs.compose.uiToolingPreview)
-            implementation(libs.androidx.lifecycle.viewmodelCompose)
-            implementation(libs.androidx.lifecycle.runtimeCompose)
             implementation(projects.shared)
         }
-        commonTest.dependencies {
-            implementation(libs.kotlin.test)
-        }
         jvmMain.dependencies {
             implementation(compose.desktop.currentOs)
             implementation(libs.kotlinx.coroutinesSwing)
@@ -66,45 +26,6 @@ kotlin {
     }
 }
 
-android {
-    namespace = "dev.ulfrx.recipe"
-    compileSdk = libs.versions.android.compileSdk.get().toInt()
-
-    defaultConfig {
-        applicationId = "dev.ulfrx.recipe"
-        minSdk = libs.versions.android.minSdk.get().toInt()
-        targetSdk = libs.versions.android.targetSdk.get().toInt()
-        versionCode = 1
-        versionName = "1.0"
-    }
-    packaging {
-        resources {
-            excludes += "/META-INF/{AL2.0,LGPL2.1}"
-        }
-    }
-    buildTypes {
-        getByName("release") {
-            isMinifyEnabled = false
-        }
-    }
-    compileOptions {
-        sourceCompatibility = JavaVersion.VERSION_11
-        targetCompatibility = JavaVersion.VERSION_11
-    }
-}
-
 dependencies {
     debugImplementation(libs.compose.uiTooling)
 }
-
-compose.desktop {
-    application {
-        mainClass = "dev.ulfrx.recipe.MainKt"
-
-        nativeDistributions {
-            targetFormats(TargetFormat.Dmg, TargetFormat.Msi, TargetFormat.Deb)
-            packageName = "dev.ulfrx.recipe"
-            packageVersion = "1.0.0"
-        }
-    }
-}

composeApp/src/androidMain/AndroidManifest.xml

@@ -2,6 +2,7 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
 
     <application
+            android:name=".MainApplication"
             android:allowBackup="true"
             android:icon="@mipmap/ic_launcher"
             android:label="@string/app_name"

composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/MainApplication.kt

@@ -0,0 +1,16 @@
+package dev.ulfrx.recipe
+
+import android.app.Application
+import dev.ulfrx.recipe.di.initKoin
+import dev.ulfrx.recipe.logging.configureLogging
+import org.koin.android.ext.koin.androidContext
+
+class MainApplication : Application() {
+    override fun onCreate() {
+        super.onCreate()
+        configureLogging()
+        initKoin {
+            androidContext(this@MainApplication)
+        }
+    }
+}

composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/App.kt

@@ -10,12 +10,15 @@ import androidx.compose.foundation.layout.safeContentPadding
 import androidx.compose.material3.Button
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.Text
-import androidx.compose.runtime.*
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.tooling.preview.Preview
 import org.jetbrains.compose.resources.painterResource
-
 import recipe.composeapp.generated.resources.Res
 import recipe.composeapp.generated.resources.compose_multiplatform
 
@@ -25,7 +28,8 @@ fun App() {
     MaterialTheme {
         var showContent by remember { mutableStateOf(false) }
         Column(
-            modifier = Modifier
+            modifier =
+                Modifier
                     .background(MaterialTheme.colorScheme.primaryContainer)
                     .safeContentPadding()
                     .fillMaxSize(),

composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/AppModule.kt

@@ -0,0 +1,9 @@
+package dev.ulfrx.recipe.di
+
+import org.koin.dsl.module
+
+// Phase 2 adds authModule; Phase 4 adds syncModule; Phase 5 adds catalogModule; etc.
+val appModule =
+    module {
+        // intentionally empty in Phase 1
+    }

composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/Koin.kt

@@ -0,0 +1,11 @@
+package dev.ulfrx.recipe.di
+
+import org.koin.core.KoinApplication
+import org.koin.core.context.startKoin
+import org.koin.dsl.KoinAppDeclaration
+
+fun initKoin(config: KoinAppDeclaration? = null): KoinApplication =
+    startKoin {
+        config?.invoke(this)
+        modules(appModule)
+    }

composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/logging/Logging.kt

@@ -0,0 +1,8 @@
+package dev.ulfrx.recipe.logging
+
+import co.touchlab.kermit.Logger
+
+fun configureLogging() {
+    Logger.setTag("recipe")
+    // Platform log writers (OSLog iOS, LogCat Android, System.out JVM/Wasm) install by default.
+}

composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/ComposeAppCommonTest.kt

@@ -4,7 +4,6 @@ import kotlin.test.Test
 import kotlin.test.assertEquals
 
 class ComposeAppCommonTest {
-
     @Test
     fun example() {
         assertEquals(3, 1 + 2)

composeApp/src/iosMain/kotlin/dev/ulfrx/recipe/di/KoinIos.kt

@@ -0,0 +1,8 @@
+package dev.ulfrx.recipe.di
+
+import dev.ulfrx.recipe.logging.configureLogging
+
+fun doInitKoin() {
+    configureLogging()
+    initKoin()
+}

composeApp/src/jvmMain/kotlin/dev/ulfrx/recipe/main.kt

@@ -2,8 +2,13 @@ package dev.ulfrx.recipe
 
 import androidx.compose.ui.window.Window
 import androidx.compose.ui.window.application
+import dev.ulfrx.recipe.di.initKoin
+import dev.ulfrx.recipe.logging.configureLogging
 
-fun main() = application {
+fun main() {
+    configureLogging()
+    initKoin()
+    application {
         Window(
             onCloseRequest = ::exitApplication,
             title = "recipe",
@@ -11,3 +16,4 @@ fun main() = application {
             App()
         }
     }
+}

composeApp/src/webMain/kotlin/dev/ulfrx/recipe/main.kt

@@ -2,9 +2,13 @@ package dev.ulfrx.recipe
 
 import androidx.compose.ui.ExperimentalComposeUiApi
 import androidx.compose.ui.window.ComposeViewport
+import dev.ulfrx.recipe.di.initKoin
+import dev.ulfrx.recipe.logging.configureLogging
 
 @OptIn(ExperimentalComposeUiApi::class)
 fun main() {
+    configureLogging()
+    initKoin()
     ComposeViewport {
         App()
     }

docker-compose.yml

@@ -0,0 +1,20 @@
+services:
+  postgres:
+    image: postgres:16
+    container_name: recipe-postgres
+    environment:
+      POSTGRES_DB: recipe
+      POSTGRES_USER: recipe
+      POSTGRES_PASSWORD: recipe
+    ports:
+      - "5432:5432"
+    volumes:
+      - recipe-pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U recipe -d recipe"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  recipe-pgdata:

gradle.properties

@@ -8,3 +8,8 @@ org.gradle.caching=true
 #Android
 android.nonTransitiveRClass=true
 android.useAndroidX=true
+
+# Kotlin/Native iOS (PITFALLS.md #1; D-18; INFRA-03) — MANDATORY day 1
+# CMS GC + non-main-thread Obj-C deinit to avoid UI-thread pause spikes in Compose Multiplatform.
+kotlin.native.binary.gc=cms
+kotlin.native.binary.objcDisposeOnMain=false

gradle/libs.versions.toml

@@ -11,12 +11,18 @@ androidx-lifecycle = "2.10.0"
 androidx-testExt = "1.3.0"
 composeHotReload = "1.0.0"
 composeMultiplatform = "1.10.3"
+flyway = "12.4.0"
 junit = "4.13.2"
+kermit = "2.1.0"
+koin = "4.2.1"
 kotlin = "2.3.20"
 kotlinx-coroutines = "1.10.2"
+kotlinx-serialization = "1.7.3"
 ktor = "3.4.1"
 logback = "1.5.32"
 material3 = "1.10.0-alpha05"
+postgresql = "42.7.10"
+spotless = "8.4.0"
 
 [libraries]
 kotlin-test = { module = "org.jetbrains.kotlin:kotlin-test", version.ref = "kotlin" }
@@ -42,6 +48,23 @@ ktor-serverCore = { module = "io.ktor:ktor-server-core-jvm", version.ref = "ktor
 ktor-serverNetty = { module = "io.ktor:ktor-server-netty-jvm", version.ref = "ktor" }
 ktor-serverTestHost = { module = "io.ktor:ktor-server-test-host-jvm", version.ref = "ktor" }
 
+# Koin (client DI — D-14)
+koin-bom = { module = "io.insert-koin:koin-bom", version.ref = "koin" }
+koin-core = { module = "io.insert-koin:koin-core" }
+koin-compose = { module = "io.insert-koin:koin-compose" }
+koin-composeViewmodel = { module = "io.insert-koin:koin-compose-viewmodel" }
+koin-android = { module = "io.insert-koin:koin-android" }
+
+# Kermit (client logger — D-15)
+kermit = { module = "co.touchlab:kermit", version.ref = "kermit" }
+
+# Server: Ktor content-negotiation + JSON serializer + Flyway + Postgres (D-16)
+ktor-serverContentNegotiation = { module = "io.ktor:ktor-server-content-negotiation-jvm", version.ref = "ktor" }
+ktor-serializationKotlinxJson = { module = "io.ktor:ktor-serialization-kotlinx-json-jvm", version.ref = "ktor" }
+flyway-core = { module = "org.flywaydb:flyway-core", version.ref = "flyway" }
+flyway-database-postgresql = { module = "org.flywaydb:flyway-database-postgresql", version.ref = "flyway" }
+postgresql = { module = "org.postgresql:postgresql", version.ref = "postgresql" }
+
 [plugins]
 androidApplication = { id = "com.android.application", version.ref = "agp" }
 androidLibrary = { id = "com.android.library", version.ref = "agp" }
@@ -51,3 +74,5 @@ composeCompiler = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "k
 kotlinJvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
 ktor = { id = "io.ktor.plugin", version.ref = "ktor" }
 kotlinMultiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
+spotless = { id = "com.diffplug.spotless", version.ref = "spotless" }
+flywayPlugin = { id = "org.flywaydb.flyway", version.ref = "flyway" }

iosApp/iosApp/iOSApp.swift

@@ -1,7 +1,12 @@
 import SwiftUI
+import ComposeApp
 
 @main
 struct iOSApp: App {
+    init() {
+        KoinIosKt.doInitKoin()
+    }
+
     var body: some Scene {
         WindowGroup {
             ContentView()

server/build.gradle.kts

@@ -1,11 +1,11 @@
 plugins {
-    alias(libs.plugins.kotlinJvm)
-    alias(libs.plugins.ktor)
-    application
+    id("recipe.jvm.server")
+    id("recipe.quality")
 }
 
 group = "dev.ulfrx.recipe"
 version = "1.0.0"
+
 application {
     mainClass.set("dev.ulfrx.recipe.ApplicationKt")
 
@@ -15,9 +15,4 @@ application {
 
 dependencies {
     implementation(projects.shared)
-    implementation(libs.logback)
-    implementation(libs.ktor.serverCore)
-    implementation(libs.ktor.serverNetty)
-    testImplementation(libs.ktor.serverTestHost)
-    testImplementation(libs.kotlin.testJunit)
 }

server/src/main/kotlin/dev/ulfrx/recipe/Application.kt

@@ -1,20 +1,38 @@
 package dev.ulfrx.recipe
 
-import io.ktor.server.application.*
-import io.ktor.server.engine.*
-import io.ktor.server.netty.*
-import io.ktor.server.response.*
-import io.ktor.server.routing.*
+import io.ktor.serialization.kotlinx.json.json
+import io.ktor.server.application.Application
+import io.ktor.server.application.install
+import io.ktor.server.engine.embeddedServer
+import io.ktor.server.netty.Netty
+import io.ktor.server.plugins.contentnegotiation.ContentNegotiation
+import io.ktor.server.response.respond
+import io.ktor.server.routing.get
+import io.ktor.server.routing.routing
+import kotlinx.serialization.Serializable
 
 fun main() {
     embeddedServer(Netty, port = SERVER_PORT, host = "0.0.0.0", module = Application::module)
         .start(wait = true)
 }
 
+@Serializable
+private data class Health(
+    val status: String,
+)
+
 fun Application.module() {
+    install(ContentNegotiation) {
+        json()
+    }
+    Database.migrate(this)
+    configureRouting()
+}
+
+fun Application.configureRouting() {
     routing {
-        get("/") {
-            call.respondText("Ktor: ${Greeting().greet()}")
+        get("/health") {
+            call.respond(Health(status = "ok"))
         }
     }
 }

server/src/main/kotlin/dev/ulfrx/recipe/Database.kt

@@ -0,0 +1,41 @@
+package dev.ulfrx.recipe
+
+import io.ktor.server.application.Application
+import org.flywaydb.core.Flyway
+import org.slf4j.LoggerFactory
+
+object Database {
+    private val log = LoggerFactory.getLogger(Database::class.java)
+
+    fun migrate(app: Application) {
+        val url =
+            app.environment.config
+                .property("database.url")
+                .getString()
+        val user =
+            app.environment.config
+                .property("database.user")
+                .getString()
+        val password =
+            app.environment.config
+                .property("database.password")
+                .getString()
+
+        log.info("Connecting to {} as {} and running Flyway migrations", url, user)
+
+        runCatching {
+            Flyway
+                .configure()
+                .dataSource(url, user, password)
+                .locations("classpath:db/migration")
+                .baselineOnMigrate(true)
+                .validateOnMigrate(true)
+                .cleanDisabled(true)
+                .load()
+                .migrate()
+        }.onFailure { ex ->
+            log.error("Flyway migration failed — cannot start server", ex)
+            throw IllegalStateException("Database unreachable or migration failed", ex)
+        }
+    }
+}

server/src/main/resources/application.conf

@@ -0,0 +1,18 @@
+ktor {
+    deployment {
+        port = 8080
+        port = ${?PORT}
+    }
+    application {
+        modules = [ dev.ulfrx.recipe.ApplicationKt.module ]
+    }
+}
+
+database {
+    url = "jdbc:postgresql://localhost:5432/recipe"
+    url = ${?DATABASE_URL}
+    user = "recipe"
+    user = ${?DATABASE_USER}
+    password = "recipe"
+    password = ${?DATABASE_PASSWORD}
+}

server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt

@@ -1,20 +1,30 @@
 package dev.ulfrx.recipe
 
-import io.ktor.client.request.*
-import io.ktor.client.statement.*
-import io.ktor.http.*
-import io.ktor.server.testing.*
-import kotlin.test.*
+import io.ktor.client.request.get
+import io.ktor.client.statement.bodyAsText
+import io.ktor.http.HttpStatusCode
+import io.ktor.serialization.kotlinx.json.json
+import io.ktor.server.application.install
+import io.ktor.server.plugins.contentnegotiation.ContentNegotiation
+import io.ktor.server.testing.testApplication
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
 
 class ApplicationTest {
-
     @Test
-    fun testRoot() = testApplication {
+    fun `health endpoint returns 200 with status ok`() =
+        testApplication {
             application {
-            module()
+                install(ContentNegotiation) {
+                    json()
                 }
-        val response = client.get("/")
+                configureRouting()
+            }
+            val response = client.get("/health")
             assertEquals(HttpStatusCode.OK, response.status)
-        assertEquals("Ktor: ${Greeting().greet()}", response.bodyAsText())
+            val body = response.bodyAsText()
+            assertTrue(body.contains("\"status\""), "expected body to contain status field, was: $body")
+            assertTrue(body.contains("\"ok\""), "expected body to contain ok value, was: $body")
         }
 }

settings.gradle.kts

@@ -2,6 +2,7 @@ rootProject.name = "recipe"
 enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")
 
 pluginManagement {
+    includeBuild("build-logic")
     repositories {
         google {
             mavenContent {

shared/build.gradle.kts

@@ -1,50 +1,45 @@
-import org.jetbrains.kotlin.gradle.ExperimentalWasmDsl
-import org.jetbrains.kotlin.gradle.dsl.JvmTarget
-
 plugins {
-    alias(libs.plugins.kotlinMultiplatform)
+    // AGP must apply BEFORE recipe.kotlin.multiplatform — the latter calls androidTarget(),
+    // which requires the Android Gradle Plugin to already be on the project. Gradle applies
+    // plugin IDs in declaration order, so com.android.library is listed first.
     alias(libs.plugins.androidLibrary)
+    id("recipe.kotlin.multiplatform")
+    id("recipe.quality")
 }
 
 kotlin {
-    androidTarget {
-        compilerOptions {
-            jvmTarget.set(JvmTarget.JVM_11)
+    explicitApi()
+
+    // Override framework baseName: shared exposes "Shared.framework" to Swift, while
+    // composeApp's convention-plugin default is "ComposeApp.framework". (D-07 / PITFALL #10)
+    targets.withType<org.jetbrains.kotlin.gradle.plugin.mpp.KotlinNativeTarget>().configureEach {
+        binaries.withType<org.jetbrains.kotlin.gradle.plugin.mpp.Framework>().configureEach {
+            baseName = "Shared"
         }
     }
 
-    iosArm64()
-    iosSimulatorArm64()
-
-    jvm()
-
-    js {
-        browser()
-    }
-
-    @OptIn(ExperimentalWasmDsl::class)
-    wasmJs {
-        browser()
-    }
-
     sourceSets {
         commonMain.dependencies {
-            // put your Multiplatform dependencies here
-        }
-        commonTest.dependencies {
-            implementation(libs.kotlin.test)
+            // Phase 1: intentionally empty. Domain models + DTOs land Phase 2+.
+            // D-19 / INFRA-06: Do NOT add Ktor, Compose, or SQLDelight deps here — EVER.
         }
     }
 }
 
 android {
     namespace = "dev.ulfrx.recipe.shared"
-    compileSdk = libs.versions.android.compileSdk.get().toInt()
+    compileSdk =
+        libs.versions.android.compileSdk
+            .get()
+            .toInt()
     compileOptions {
         sourceCompatibility = JavaVersion.VERSION_11
         targetCompatibility = JavaVersion.VERSION_11
     }
     defaultConfig {
-        minSdk = libs.versions.android.minSdk.get().toInt()
+        minSdk =
+            libs.versions.android.minSdk
+                .get()
+                .toInt()
     }
 }

shared/src/androidMain/kotlin/dev/ulfrx/recipe/Platform.android.kt

@@ -2,8 +2,8 @@ package dev.ulfrx.recipe
 
 import android.os.Build
 
-class AndroidPlatform : Platform {
+public class AndroidPlatform : Platform {
     override val name: String = "Android ${Build.VERSION.SDK_INT}"
 }
 
-actual fun getPlatform(): Platform = AndroidPlatform()
+public actual fun getPlatform(): Platform = AndroidPlatform()

shared/src/commonMain/kotlin/dev/ulfrx/recipe/Constants.kt

@@ -1,3 +1,3 @@
 package dev.ulfrx.recipe
 
-const val SERVER_PORT = 8080
+public const val SERVER_PORT: Int = 8080

shared/src/commonMain/kotlin/dev/ulfrx/recipe/Greeting.kt

@@ -1,9 +1,7 @@
 package dev.ulfrx.recipe
 
-class Greeting {
+public class Greeting {
     private val platform = getPlatform()
 
-    fun greet(): String {
-        return "Hello, ${platform.name}!"
-    }
+    public fun greet(): String = "Hello, ${platform.name}!"
 }

shared/src/commonMain/kotlin/dev/ulfrx/recipe/Platform.kt

@@ -1,7 +1,7 @@
 package dev.ulfrx.recipe
 
-interface Platform {
-    val name: String
+public interface Platform {
+    public val name: String
 }
 
-expect fun getPlatform(): Platform
+public expect fun getPlatform(): Platform

shared/src/commonTest/kotlin/dev/ulfrx/recipe/SharedCommonTest.kt

@@ -4,7 +4,6 @@ import kotlin.test.Test
 import kotlin.test.assertEquals
 
 class SharedCommonTest {
-
     @Test
     fun example() {
         assertEquals(3, 1 + 2)

shared/src/iosMain/kotlin/dev/ulfrx/recipe/Platform.ios.kt

@@ -2,8 +2,8 @@ package dev.ulfrx.recipe
 
 import platform.UIKit.UIDevice
 
-class IOSPlatform : Platform {
+public class IOSPlatform : Platform {
     override val name: String = UIDevice.currentDevice.systemName() + " " + UIDevice.currentDevice.systemVersion
 }
 
-actual fun getPlatform(): Platform = IOSPlatform()
+public actual fun getPlatform(): Platform = IOSPlatform()

shared/src/jsMain/kotlin/dev/ulfrx/recipe/Platform.js.kt

@@ -1,7 +0,0 @@
-package dev.ulfrx.recipe
-
-class JsPlatform : Platform {
-    override val name: String = "Web with Kotlin/JS"
-}
-
-actual fun getPlatform(): Platform = JsPlatform()

shared/src/jvmMain/kotlin/dev/ulfrx/recipe/Platform.jvm.kt

@@ -1,7 +1,7 @@
 package dev.ulfrx.recipe
 
-class JVMPlatform : Platform {
+public class JVMPlatform : Platform {
     override val name: String = "Java ${System.getProperty("java.version")}"
 }
 
-actual fun getPlatform(): Platform = JVMPlatform()
+public actual fun getPlatform(): Platform = JVMPlatform()

shared/src/wasmJsMain/kotlin/dev/ulfrx/recipe/Platform.wasmJs.kt

@@ -1,7 +1,7 @@
 package dev.ulfrx.recipe
 
-class WasmPlatform : Platform {
+public class WasmPlatform : Platform {
     override val name: String = "Web with Kotlin/Wasm"
 }
 
-actual fun getPlatform(): Platform = WasmPlatform()
+public actual fun getPlatform(): Platform = WasmPlatform()

tools/verify-ios-flags.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Enforces INFRA-03 / D-18: iOS K/N flags present in gradle.properties.
+set -euo pipefail
+grep -q '^kotlin\.native\.binary\.gc=cms$' gradle.properties || { echo "MISSING: kotlin.native.binary.gc=cms" >&2; exit 1; }
+grep -q '^kotlin\.native\.binary\.objcDisposeOnMain=false$' gradle.properties || { echo "MISSING: kotlin.native.binary.objcDisposeOnMain=false" >&2; exit 1; }
+echo "OK: iOS binary flags present."

tools/verify-no-version-literals.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Enforces INFRA-01 SC#2 / D-09: no literal *library/plugin* version strings outside catalog.
+# Scans every *.gradle.kts for numeric version literals (e.g. version = "1.2.3") that would
+# represent a library or plugin pin leaking out of the catalog.
+#
+# Exclusions (all semantic, not loopholes):
+#   - build-logic/build.gradle.kts needs literal plugin-dependency coordinates (`asDependency()`)
+#   - Top-level project-version assignments (unindented `^version = "x.y.z"`) are Gradle project
+#     metadata (artifact name) — NOT a library version pin. D-09 guards dependency versions,
+#     not project identity.
+set -euo pipefail
+VIOLATIONS=$(grep -rn -E 'version[[:space:]]*=[[:space:]]*"[0-9]' --include='*.gradle.kts' . 2>/dev/null \
+    | grep -v 'build-logic/build.gradle.kts' \
+    | grep -vE ':[0-9]+:version[[:space:]]*=[[:space:]]*"[0-9]' \
+    || true)
+if [ -n "$VIOLATIONS" ]; then
+    echo "ERROR: version literals found outside catalog:" >&2
+    echo "$VIOLATIONS" >&2
+    exit 1
+fi
+echo "OK: no version literals outside catalog."

tools/verify-shared-pure.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Enforces INFRA-06 / D-19: shared/commonMain must not import Ktor, Compose, SQLDelight.
+# Runs grep against shared/src/commonMain/ only. Allowed imports: kotlin.*, kotlinx.serialization, kotlinx.datetime.
+set -euo pipefail
+if [ ! -d shared/src/commonMain ]; then
+    echo "OK: shared/src/commonMain does not exist yet (pre-scaffold)."
+    exit 0
+fi
+VIOLATIONS=$(grep -rn -E '^import[[:space:]]+(io\.ktor|androidx\.compose|org\.jetbrains\.compose|app\.cash\.sqldelight)' shared/src/commonMain/ 2>/dev/null || true)
+if [ -n "$VIOLATIONS" ]; then
+    echo "ERROR: shared/commonMain has forbidden imports:" >&2
+    echo "$VIOLATIONS" >&2
+    exit 1
+fi
+echo "OK: shared/commonMain is pure."