@horka/app-forge 0.1.0

package/templates/packs/swift-ios/Packages/{{PROJECT_NAME}}DS/Sources/{{PROJECT_NAME}}DS/DSFont.swift

@@ -0,0 +1,26 @@
+import SwiftUI
+
+public extension DS {
+    /// Typography scale. Use through `.designSystem(font:)` — never `.font(.system(...))` in app code.
+    enum Font {
+        case largeTitle, title, h2, h3, body, callout, caption, button, mono
+
+        var font: SwiftUI.Font {
+            switch self {
+            case .largeTitle: .system(size: 34, weight: .bold)
+            case .title: .system(size: 28, weight: .bold)
+            case .h2: .system(size: 22, weight: .semibold)
+            case .h3: .system(size: 17, weight: .semibold)
+            case .body: .system(size: 17)
+            case .callout: .system(size: 15)
+            case .caption: .system(size: 12)
+            case .button: .system(size: 17, weight: .semibold)
+            case .mono: .system(size: 15, design: .monospaced)
+            }
+        }
+    }
+}
+
+public extension View {
+    func designSystem(font: DS.Font) -> some View { self.font(font.font) }
+}

package/templates/packs/swift-ios/claude/memory/COMMANDS.md

@@ -0,0 +1,18 @@
+# {{PROJECT_NAME}} — Commands
+
+> Only commands proven to work in THIS project, with exact flags.
+
+## Packages (fast loop — always first)
+swift build --package-path Packages/{{PROJECT_NAME}}Core
+swift test  --package-path Packages/{{PROJECT_NAME}}Core
+swift build --package-path Packages/DataLayer
+swift build --package-path Packages/{{PROJECT_NAME}}DS
+
+## App target
+xcodegen generate   # regenerate .xcodeproj after adding files (run at project root)
+xcodebuild -project {{PROJECT_NAME}}.xcodeproj -scheme {{PROJECT_NAME}} \
+  -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
+  -derivedDataPath /tmp/{{PROJECT_NAME}}_dd build 2>&1 | grep -E "error:|BUILD"
+
+## Simulator (via ios-simulator MCP)
+# install_app → launch_app({{BUNDLE_ID}}) → screenshot → inspect

package/templates/packs/swift-ios/docs-architecture/ARCHITECTURE.md

@@ -0,0 +1,246 @@
+# ARCHITECTURE — Layered "Lego Brick" iOS App
+
+Pattern for SwiftUI apps (Swift 6.2, strict concurrency, iOS 26 everywhere — app target AND packages (one deployment story; bump together)). The app
+is assembled from
+independently buildable bricks: 3 local SPM packages + 3 app-target folders. Every layer below the
+app target compiles and tests with plain `swift build` / `swift test` — no Xcode, no simulator.
+
+## 1. Layer Model — Swift instantiation of the universal L0–L5 contract
+
+This maps `ARCHITECTURE_PRINCIPLES.md` (read it first) onto SPM packages + app folders:
+
+```
+L5  COMPLETE FEATURES   App/      user-facing screens assembling bricks (VVM-I)
+                        Store/    @Observable app state, composition root (picks real vs InMemory)
+                        Tools/    cross-cutting: router, schedulers, formatters, location
+L4  SHARED FEATURES     Module/   reusable domain-aware UI bricks   Module/Item, Module/ItemGroup, Module/Map
+L3  CORE LOGIC          Packages/{{PROJECT_NAME}}Core   (pure Swift) domain models + engines + services
+                                                        + repository CONTRACTS + InMemory impls
+L3  CORE UI             Packages/{{PROJECT_NAME}}DS — Components/   domain-blind components (buttons, cards…)
+L2  DATA                Packages/DataLayer  (IO)  repository IMPLEMENTATIONS (CloudKit/network)
+                                                  + CKRecord↔domain mapping  — implements L3 contracts
+L1  OPS                 no dedicated package until needed — logging conventions live in CONVENTIONS.md;
+                        create Packages/Ops (remote config, analytics, feature flags) the day a slice needs it
+L0  FOUNDATION          Packages/{{PROJECT_NAME}}DS — tokens   DS.Padding/Radius, Color.DS.*, DS.Font
+                        + base extensions/formatters
+```
+
+Notes on the mapping:
+- **The DS package physically hosts two layers**: L0 (tokens) and L3 Core UI (Components/).
+  Internal rule: Components import tokens, never the reverse.
+- **DataLayer implements Core's contracts** — the one sanctioned upward arrow (ports & adapters):
+  it may import L3 protocols + models, never services/engines.
+- **Imports point downward only** everywhere else; a feature never imports a sibling feature.
+
+Brick rule: **Module/ components must work in any app screen; App/ screens are throwaway
+assemblies.** When in doubt, start in App/ and promote to Module/ on second use.
+
+## 2. Dependency Direction Rules
+
+| Layer (L#) | May import | Must NEVER import | Why |
+|---|---|---|---|
+| L3 Core Logic ({{PROJECT_NAME}}Core) | Foundation (the Swift module) only | SwiftUI, UIKit, CloudKit, DataLayer | Tests run on the macOS host in seconds; logic stays platform-portable |
+| L2 DataLayer | L3 contracts/models + IO frameworks (CloudKit, URLSession) | SwiftUI, the app target | It only implements Core protocols |
+| L0+L3-UI {{PROJECT_NAME}}DS | SwiftUI | Core, DataLayer | Tokens/components are domain-blind, reusable across apps |
+| L4 Module/ | L3 Core, DS | DataLayer, Store types in signatures | Bricks take domain values + closures, not the store |
+| L5 App/ | everything | — | Final assembly point |
+| L5 Store/ | L3 Core, L2 DataLayer | DS (it has no UI) | Sole place that knows which repository implementation runs |
+
+> ⚠️ **Gotcha:** Symptom — `swift test` on Core suddenly needs a simulator destination and takes
+> minutes. Cause — someone added `import SwiftUI` (often for `Color` or `@Observable` view helpers)
+> to a domain file. Fix — Core stays UI-free; presentation mapping (colors, labels) lives in
+> Module/ extensions, e.g. `extension Item.Status { var dsColor: Color }` in the app target.
+
+> ⚠️ **Gotcha:** Symptom — testing a Service or ViewModel forces importing CloudKit and an iCloud
+> account. Cause — repository protocol was declared in DataLayer next to its implementation.
+> Fix — `protocol ItemRepository: Sendable` lives in **Core**, alongside an
+> `actor InMemoryItemRepository: ItemRepository` for tests/previews/offline. DataLayer only ships
+> `CloudKitItemRepository` (or `URLSessionItemRepository`, etc.) conforming to it.
+
+## 3. SPM Local Packages — one Package.swift per layer
+
+```swift
+// Packages/{{PROJECT_NAME}}Core/Package.swift
+// swift-tools-version: 6.2
+import PackageDescription
+
+let package = Package(
+    name: "{{PROJECT_NAME}}Core",
+    platforms: [.iOS(.v18), .macOS(.v14)],          // macOS = host-runnable tests
+    products: [.library(name: "{{PROJECT_NAME}}Core", targets: ["{{PROJECT_NAME}}Core"])],
+    targets: [
+        .target(name: "{{PROJECT_NAME}}Core", swiftSettings: [.swiftLanguageMode(.v6)]),
+        .testTarget(name: "{{PROJECT_NAME}}CoreTests", dependencies: ["{{PROJECT_NAME}}Core"],
+                    swiftSettings: [.swiftLanguageMode(.v6)]),
+    ]
+)
+```
+
+- DataLayer adds `dependencies: [.package(path: "../{{PROJECT_NAME}}Core")]` and its own test target.
+- The DS package adds `.defaultIsolation(MainActor.self)` to its swiftSettings.
+- Xcode: add the three local packages to the app target once; they resolve by path.
+
+> ⚠️ **Gotcha:** Symptom — a SwiftUI-only design-system package drowns in Swift 6 errors
+> ("call to main actor-isolated…") on every component. Cause — SwiftUI types are MainActor-bound
+> but package code defaults to nonisolated. Fix — set `.defaultIsolation(MainActor.self)` on the
+> DS target instead of annotating every struct. Do NOT set it on Core (its actors/engines must
+> stay nonisolated) or DataLayer.
+
+## 4. Layer Contracts
+
+### Core — pure business logic
+- **Domain**: `Sendable` value types (`Item`, `ItemDraft`, `User`, `ItemGroup`, `Coordinate`, `Stats`).
+  Never name a domain type `Group` — it collides with `SwiftUI.Group` in every view file.
+- **Engine**: pure static funcs on caseless enums — `ScoreEngine`, `StatsEngine.compute(...)`,
+  `AchievementEngine`. Deterministic in/out, no IO, no clock access (pass `now: Date` as parameter).
+- **Catalog**: static data tables (achievement definitions, levels) — rules stay in engines, data
+  in catalogs; never encode rules as stored JSON conditions.
+- **Repository**: protocols + in-memory actor implementations.
+- **Service**: `actor ItemService` orchestrating one transaction across engines + repository,
+  e.g. `addItem(_:now:) -> AddItemResult` (persist + score + unlocks in one testable unit).
+
+### DataLayer — IO implementations
+- One repository class/actor per Core protocol, plus mapping files (`CKRecord+Mapping.swift`,
+  `DTO+Mapping.swift`) and config (`CloudKitConfig` holding the single container ID constant
+  `iCloud.{{BUNDLE_ID}}` — one constant, referenced everywhere, equal to the entitlement).
+
+> ⚠️ **Gotcha:** Symptom — Swift 6 data-race errors (or runtime corruption) around `CKRecord`.
+> Cause — `CKRecord` is non-`Sendable`; it must not cross actor boundaries. Fix — fetch and map
+> to `Sendable` domain values **inside** the repository actor; only domain types ever leave it.
+
+> ⚠️ **Gotcha:** Symptom — right after accepting a share / receiving a push, an immediate refresh
+> fails with "Record not found" though the data exists. Cause — server-side propagation delay on
+> freshly shared zones/records. Fix — on remote-triggered refreshes, add a short delay (~1.5 s)
+> or one retry before surfacing an error.
+
+### {{PROJECT_NAME}}DS — design system
+Tokens as namespaces (`DS.Padding.m`, `DS.Gradients.brand`, `Color.DS.accent`, `DSFont`), plus
+generic components (`DSBackground`, button styles, cards). Nothing here knows the domain.
+
+### Module/ — reusable UI bricks (app target)
+One folder per domain concept (`Module/Item/`, `Module/Map/`). Bricks receive domain values and
+closures — never the store. Prefer generics for shared mechanics, e.g. one
+`ItemMap<Item, Marker: View, Detail: View>` used by every map screen (selection, clustering,
+anchored popover live here; screens inject `marker:` and `detail:` builders).
+A brick becomes navigable through closures injected by the parent screen — no router dependency:
+
+```swift
+// child brick:    var onAccept: () -> Void   // plain stored closure(s); domain value captured by value
+// parent screen:  Button { interactor.openDetail(group) } label: { ItemGroup.Row(group: group) }
+//                 ItemGroup.InviteCard(group: group, onAccept: { Task { await interactor.accept(group) } }, …)
+```
+The parent's Interactor owns the routing (`viewModel.path.append`) — no environment plumbing,
+no third-party DI/navigation package.
+
+### App/ — screens, VVM-I pattern
+Per screen, one folder with up to 4 files:
+- `App<Screen>.swift` — View, namespaced via extension: `extension App { struct Detail: View }`,
+  `body` in `extension App.Detail`. Deps via `@Environment`; `@State private var viewModel = ViewModel()`.
+- `App<Screen>ViewModel.swift` — `@Observable final class ViewModel`: local UI state ONLY. No business
+  logic, no navigation, no store reference.
+- `App<Screen>Interactor.swift` — `struct Interactor` with deps injected by init (store, router path);
+  business calls + routing. Recreated on demand:
+  `private var interactor: Interactor { Interactor(viewModel: viewModel, store: store) }`.
+  Trivial screens (no routing/orchestration) may omit it.
+- `App<Screen>+Translate.swift` — `nonisolated enum Translate` of user-facing string constants
+  (+ pure formatting helpers). No state, no logic.
+
+Navigation: a `TabView` shell where **each tab owns its `NavigationStack`** with value-based
+`.navigationDestination(for: ItemGroup.self)`. Add a global `@Observable` Coordinator (path array +
+`goTo(_:)`) only for single-stack, deep-link-driven apps — most tab apps don't need one.
+
+### Store/ — observable state + composition root
+`@MainActor @Observable final class AppStore`: wraps Core services, exposes `private(set)` state
+and intent methods. It is the ONLY place deciding which backend runs:
+
+```swift
+func bootstrap() async {
+    guard service == nil else { return }
+    if ProcessInfo.processInfo.arguments.contains("-uitest-mock") {
+        activateMemoryBackend(); await refresh(); return
+    }
+    let cloud = CloudKitItemRepository()
+    if await cloud.isAccountAvailable() { service = ItemService(repository: cloud); backend = .cloud }
+    else { activateMemoryBackend() }   // seeded with SampleData → app fully demoable offline
+    await refresh()
+}
+```
+
+Injected once at the root: `@State private var store = AppStore()` → `.environment(store)` on the
+root view. No DI container. `SampleData` lives next to the store and feeds previews, the in-memory
+backend, and UI tests. On `scenePhase == .active`, upgrade a memory backend to cloud if an account
+appeared, then refresh. Intents that gate UI return success:
+`@discardableResult func addItem(_ draft: ItemDraft) async -> Bool` — the sheet dismisses only
+when the write landed.
+
+> ⚠️ **Gotcha:** Symptom — UI tests and cold simulators hang on first launch. Cause — the cloud
+> account probe (`CKContainer.accountStatus`) can stall with no account configured. Fix — a launch
+> argument (`-uitest-mock`) short-circuits straight to the in-memory backend; the simulator
+> fallback path keeps the app demoable with sample data.
+
+> ⚠️ **Gotcha:** Symptom — infinite splash spinner when the first load fails. Cause — `isReady`
+> was only set on the success path. Fix — set `isReady = true` in the catch too, and surface
+> `lastError`; an empty state beats a dead spinner.
+
+> ⚠️ **Gotcha:** Symptom — a stale error alert pops during an unrelated, successful action.
+> Cause — `lastError` from a previous failure was never cleared. Fix — first line of every intent:
+> `lastError = nil`.
+
+> ⚠️ **Gotcha:** Symptom — error alert never appears while a sheet is presented. Cause — an alert
+> attached to the presenting view cannot cover a presented sheet. Fix — the app-wide alert lives on
+> the root view, AND any sheet that can fail (e.g. the add form) declares its own local alert.
+
+### Tools/ — cross-cutting
+Router/Coordinator (if used), notification scheduler, push routing, formatters, location provider.
+Anything used by multiple screens that is neither domain logic nor a visual component.
+
+## 5. Where Does a New File Go?
+
+| You are adding… | It lives in… |
+|---|---|
+| A domain value type | `Packages/{{PROJECT_NAME}}Core/Sources/{{PROJECT_NAME}}Core/Domain/` |
+| A pure rule (scoring, validation, stats) | `Core/Engine/` — static func, `now`/inputs as params |
+| Static data tables (levels, definitions) | `Core/Catalog/` |
+| A persistence/network contract | `Core/Repository/` (protocol + `InMemory…` actor) |
+| Multi-step domain transaction | `Core/Service/` (actor) |
+| The real backend implementation + DTO mapping | `Packages/DataLayer/` |
+| Color/spacing/font token, domain-blind component | `Packages/{{PROJECT_NAME}}DS/` |
+| Reusable UI for a domain concept (ItemCard, ItemMap) | app `Module/<Concept>/` |
+| A user-facing screen | app `App/<Screen>/` — View + ViewModel (+ Interactor + Translate) |
+| App-wide state or a new user intent | `Store/AppStore.swift` |
+| Preview/demo/test fixture data | `Store/SampleData.swift` |
+| Scheduler, router, formatter, location | `Tools/` |
+
+## 6. Why This Works Exceptionally Well With AI Agents
+
+- **Fast ground truth without Xcode.** `cd Packages/{{PROJECT_NAME}}Core && swift test` runs the whole business
+  logic suite on the host Mac in seconds — no simulator boot, no signing. Agents iterate on
+  logic with a compile+test loop per edit.
+- **Compiler-enforced boundaries.** An agent that violates layering (imports SwiftUI in Core,
+  references the store in a Module brick) gets an immediate build error instead of silently
+  degrading the architecture.
+- **Deterministic UI without a backend.** The in-memory repository + `SampleData` + `-uitest-mock`
+  launch arg let agents build screens, run UI tests, and take simulator screenshots with zero
+  accounts or network.
+- **Predictable file placement.** The VVM-I naming convention and the table above mean an agent
+  knows exactly which 3–4 files to create for a feature — diffs stay small and reviewable.
+- **Engines are pure functions.** Time, randomness, and IO are parameters, so agents can write
+  exhaustive table-driven tests (`swift test`) without mocks or fakes beyond `InMemory…` actors.
+
+Build matrix an agent should run before claiming "done":
+```
+cd Packages/{{PROJECT_NAME}}Core && swift test            # logic — seconds
+cd Packages/DataLayer && swift build      # IO compiles against Core contracts
+cd Packages/{{PROJECT_NAME}}DS && swift build
+xcodebuild -project {{PROJECT_NAME}}.xcodeproj -scheme {{PROJECT_NAME}} \
+  -destination 'generic/platform=iOS Simulator' build                  # app assembly only
+```
+
+
+## Acceptable variations
+The Store-internal `bootstrap()` shown above is the default, not dogma. Known-good variants:
+- **Protocol-based init injection** (`Store(repository: some ItemRepository)`) — preferred by
+  teams that want the composition root outside the Store. Fine: record it in
+  `.claude/memory/DECISIONS.md` and keep ONE pattern per project.
+Deviating consciously is healthy; deviating silently is how two conventions end up in one repo
+(see ANTI_PATTERNS.md).

package/templates/packs/swift-ios/docs-architecture/CLOUDKIT_GUIDE.md

@@ -0,0 +1,224 @@
+# CloudKit Guide — Private Sync + CKShare Groups (no server)
+
+Battle-tested patterns from two production apps. CloudKit IS the backend: private DB for the user's
+own data, shared DB for groups via `CKShare`. Read the Gotchas section before touching any of this.
+
+## 1. Architecture
+
+```
+Private DB (per user)                 Shared DB (per user)
+├── ItemsZone (custom zone)           └── GroupZone-<UUID>  ← zones OTHER owners shared with me
+│     ├── Item records                      (zoneID.ownerName = the REAL owner id)
+│     └── Profile record (singleton)
+└── GroupZone-<UUID> (one per group I own)
+      ├── Group root record ──── CKShare
+      └── SharedItem records (parent → Group root)
+```
+
+- **Repository protocol lives in the pure Core package** (no CloudKit import) → services/ViewModels
+  testable with `swift test`. `CloudKitRepository` / `CloudKitGroupRepository` (actors) live in
+  DataLayer. An `InMemory*Repository` backs tests, previews, and the simulator.
+- **Custom zones are mandatory** — change tokens (`recordZoneChanges`) and `CKShare` don't work in
+  the default zone. One zone per shared group (`GroupZone-<UUID>`), found later by name prefix.
+- **One container constant, used everywhere** (both repositories AND share acceptance), identical to
+  the entitlement: `iCloud.{{BUNDLE_ID}}`. A second hardcoded id = silent data split.
+- Centralize every record type / field / subscription id in one `CloudKitConfig` enum. No string
+  literals at call sites.
+
+## 2. Record Mapping
+
+Two-way mapping as extensions on the domain model. `init?(record:)` validates required fields
+(guard-let, return nil on malformed); optional fields get defaults on read.
+
+```swift
+extension Item {
+    init?(record: CKRecord) {
+        guard record.recordType == CloudKitConfig.RecordType.item,
+              let id = UUID(uuidString: record.recordID.recordName),
+              let createdAt = record[Field.createdAt] as? Date else { return nil }
+        self.init(id: id, title: (record[Field.title] as? String) ?? "", createdAt: createdAt)
+    }
+    /// New records only — recordName IS the model's UUID (deterministic IDs, no lookup table).
+    func makeRecord(in zoneID: CKRecordZone.ID) -> CKRecord { ... }
+    /// Updates — write fields into the FETCHED record to preserve its server change tag.
+    func apply(to record: CKRecord) { ... }
+}
+```
+
+Rules:
+- **Never build a fresh `CKRecord` to update an existing one** — you lose the change tag and get
+  `serverRecordChanged`. Fetch, `apply(to:)`, save.
+- Loading: prefer `database.recordZoneChanges(inZoneWith:since:)` loops (handles `moreComing`,
+  surfaces deletions) over `CKQuery`. Persist tokens per (scope, zoneID) via a small
+  `ChangeTokenStore` actor (NSKeyedArchiver → UserDefaults). On a cold launch with an empty
+  in-memory cache, ignore the persisted token once and do a full scan — a stale token + empty cache
+  returns an incomplete list.
+- Conflict handling (`serverRecordChanged`, also nested inside `partialFailure`): take
+  `error.serverRecord`, merge local state into it, re-save **once**. Never retry in a loop.
+
+## 3. CKShare Lifecycle
+
+**Create** — zone first, then root record + share **in the same atomic write**:
+
+```swift
+let zone = CKRecordZone(zoneName: "GroupZone-\(group.id.uuidString)")
+_ = try await privateDB.modifyRecordZones(saving: [zone], deleting: [])
+
+let rootRecord = group.makeRecord(in: zone.zoneID)
+let share = CKShare(rootRecord: rootRecord)
+share[CKShare.SystemFieldKey.title] = group.name as CKRecordValue
+share.publicPermission = .readWrite   // link sharing: anyone with the URL joins & can write
+_ = try await privateDB.modifyRecords(saving: [rootRecord, share], deleting: [],
+                                      savePolicy: .ifServerRecordUnchanged, atomically: true)
+return share.url   // hand to ShareLink / UIActivityViewController
+```
+
+Permission matrix: `.readOnly` participants can read but **cannot create even with a correct
+parent**; creating requires `.readWrite`. For invite-only apps use `publicPermission = .none` +
+explicit participants at `.readWrite` (via `UICloudSharingController`, or
+`CKFetchShareParticipantsOperation` + `CKShare.addParticipant(_:)`) — a leaked link then grants nothing.
+
+**Child records** — every record a participant must be able to create needs the hierarchy parent:
+
+```swift
+record.parent = CKRecord.Reference(recordID: rootRecordID, action: .none)  // system sharing prop
+```
+
+**Accept** — fires in the app/scene delegate (see Gotcha 2). `CKShare.Metadata` is NOT `Sendable`:
+consume it synchronously on `@MainActor`, extract the Sendable group UUID from
+`metadata.hierarchicalRootRecordID.recordName` *before* any `await`, then run
+`CKAcceptSharesOperation`. Only the UUID escapes. After accept, the zone appears in the
+participant's `sharedCloudDatabase` (with delay — Gotcha 4).
+
+**Locate** — load groups from BOTH databases by listing `allRecordZones()` and filtering by zone
+name prefix; cache the **exact** `(scope, zoneID)` per group. All later operations route through
+that cache (owner → private DB, participant → shared DB).
+
+**Members** — do NOT persist a member-list field; it drifts. The authoritative list is
+`share.participants` (fetch root record → `record.share` reference → fetch the `CKShare`). Map to a
+Sendable struct inside the actor; never let `CKShare` escape it.
+
+**Remove a participant** (owner): find the non-owner participant by
+`userIdentity.userRecordID?.recordName`, `share.removeParticipant(...)`, save the share with
+`savePolicy: .changedKeys`. With a public link this is best-effort — they can re-accept the
+still-valid URL until you rotate it.
+
+**Rotate the invite link**: delete the old `CKShare` record, re-fetch the root record (its `share`
+reference is now cleared), create a new `CKShare(rootRecord:)`, save root + share atomically →
+brand-new URL, old one dead.
+
+**Delete / leave**: owner deletes the zone in the private DB (removes the group for everyone);
+participant deletes the zone from their shared DB (= leave). Clear cached change tokens.
+
+## 4. Push, Refresh, Notifications
+
+- Register `CKDatabaseSubscription` with `notificationInfo.shouldSendContentAvailable = true`
+  (silent push) on **both** the private DB (owner sees participants' writes) and the shared DB
+  (participants see everyone else's writes). Idempotent, best-effort (`try?`). A
+  `CKRecordZoneSubscription` on the private items zone keeps the user's own devices in sync.
+- AppDelegate: `application.registerForRemoteNotifications()` at launch (no user permission needed
+  for silent push), Info.plist `UIBackgroundModes: [remote-notification]`.
+- `didReceiveRemoteNotification` → `CKNotification(fromRemoteNotificationDictionary:)` → route:
+  `.database` → refresh groups; `.recordZone` → refresh items; unknown → refresh both. Return
+  `.newData`. CloudKit pushes carry no payload beyond "something changed" — always re-fetch.
+- Visible alerts: silent push + local notification on diff (you computed what changed during the
+  refresh), or implement `userNotificationCenter(_:willPresent:) async -> [.banner, .sound]` to show
+  banners in the foreground.
+- Cold-launch race: a push/share-accept can arrive before SwiftUI wires your store. Use a small
+  `@MainActor PushRouter` holding `weak var store`; if nil, set a `pending` flag and flush it in
+  `store`'s `didSet`.
+
+## 5. Gotchas (production bugs — each cost hours/days)
+
+> ⚠️ **Gotcha 1 — Empty array on a List field.** Symptom: first save fails with
+> `cannot use an empty list to initialize a new field`. Cause: CloudKit infers a List field's
+> element type from the first non-empty save and rejects `[]` on a not-yet-existing field. Fix:
+> when the collection is empty, set the field to `nil` (omit it); read side defaults to `[]`. The
+> schema field is created the first time a non-empty value is saved.
+
+> ⚠️ **Gotcha 2 — Share acceptance never fires.** Symptom: tapping an invite link opens the app,
+> nothing happens; `userDidAcceptCloudKitShareWith` on the AppDelegate is never called. Cause: in a
+> SwiftUI-lifecycle app the callback is delivered to the **scene** delegate. Fix: implement
+> `application(_:configurationForConnecting:options:)` returning a config with
+> `delegateClass = SceneDelegate.self`, and implement
+> `windowScene(_:userDidAcceptCloudKitShareWith:)` there. Keep the AppDelegate variant too as
+> belt-and-braces. Don't implement `scene(_:willConnectTo:)` — SwiftUI still owns the window.
+
+> ⚠️ **Gotcha 3 — Invite link says "you need a newer version of the app".** Cause: missing
+> `CKSharingSupported = true` (Boolean) in Info.plist. Fix: add it. No code change.
+
+> ⚠️ **Gotcha 4 — "Record not found" right after accepting a share.** Cause: server-side
+> propagation delay — the shared zone isn't visible in the participant's shared DB immediately
+> after `CKAcceptSharesOperation` succeeds. Fix: refresh immediately, then refresh again after
+> ~2 s (`try? await Task.sleep(for: .seconds(2))`). Never treat the first miss as an error.
+
+> ⚠️ **Gotcha 5 — Works in Debug/Dev, broken on TestFlight.** Symptom: TestFlight build sees zero
+> data or errors on every record type. Cause: the schema only exists in the **Development**
+> environment; TestFlight/App Store use **Production**. Fix: exercise every record type AND field
+> in code against Dev (fields are created lazily on first save — including `parent`! see Gotcha 1),
+> then CloudKit Dashboard → "Deploy Schema Changes" to Production **before** the TestFlight build.
+
+> ⚠️ **Gotcha 6 — Silent pushes never arrive in production.** Cause: `aps-environment` entitlement
+> is `development` for Xcode builds; TestFlight/App Store need `production`. Xcode rewrites it at
+> archive time for App Store distribution — but verify in the built `.ipa` if pushes are dead, and
+> never test push on a device while the entitlement/profile mismatch.
+
+> ⚠️ **Gotcha 7 — Participant gets "CREATE operation not permitted".** Cause: hierarchical sharing
+> only lets participants create records whose `record.parent` chain reaches the shared root.
+> Orphan records save fine for the owner and fail for everyone else. Fix: always set
+> `record.parent` → root record on shared child records (keep a separate custom Reference field if
+> you also need queries — `parent` is invisible in the Dashboard).
+
+> ⚠️ **Gotcha 8 — Wrong zone owner (`__defaultOwner__`).** Symptom: participant operations hit
+> `zoneNotFound` though the zone exists. Cause: `CKCurrentUserDefaultName` resolves to the current
+> user — reconstructing a shared zoneID with it points at the participant's own (nonexistent) zone.
+> Fix: never reconstruct zone IDs. Keep the exact `CKRecordZone.ID` from `allRecordZones()` /
+> `record.recordID.zoneID`; resolve the real owner via `metadata.ownerIdentity.userRecordID`.
+
+> ⚠️ **Gotcha 9 — Share created but URL is nil / root not shared.** Cause: root record and its
+> `CKShare` were saved in separate operations. Fix: first save must include **both** in one
+> `modifyRecords(atomically: true)`.
+
+> ⚠️ **Gotcha 10 — `CKShare.Metadata` across actors.** Symptom: Swift 6 sendability errors, or
+> crashes when stashing metadata for later. Fix: consume it synchronously on `@MainActor`, extract
+> Sendable values (root record UUID) before the first `await`, never store it.
+
+> ⚠️ **Gotcha 11 — `CKQuery` fails in custom zones.** Symptom: "recordName is not marked
+> queryable". Fix: don't query; iterate `recordZoneChanges(inZoneWith:since:)` until
+> `!moreComing` — it's also the only way to observe deletions.
+
+> ⚠️ **Gotcha 12 — Participants show as "Anonymous"/stale members.** Cause: member list persisted
+> as a record field drifts from reality. Fix: derive members exclusively from
+> `share.participants` (name via `PersonNameComponentsFormatter` on `userIdentity.nameComponents`,
+> fallback `lookupInfo?.emailAddress`).
+
+Minor but real: treat `CKError.unknownItem` on delete as success (idempotent); coalesce concurrent
+bootstrap (zone + subscription creation) onto a single in-flight `Task` inside the actor.
+
+## 6. Dev / Test Workflow
+
+- **Simulator**: CRUD against the private DB works (signed-in iCloud account required). Share
+  acceptance and push do NOT work → fall back to `InMemoryGroupRepository` on simulator.
+- **Device required** for: silent push, share accept, multi-account flows. Full validation needs
+  **two real iCloud accounts**: A creates + invites → B accepts → B writes → A receives push.
+- Debugging on device: `os.Logger(subsystem:category:)` with `privacy: .public` on interpolations
+  (otherwise values show as `<private>` in Console.app). Log every share-accept and push entry
+  point — these paths are unreproducible in a debugger session that started after the tap.
+- CloudKit Dashboard: inspect records per zone (Dev env), check "Deploy Schema Changes" diff, and
+  use Logs to confirm pushes were emitted.
+
+## 7. Checklist — adding a shared record type
+
+1. Add type + fields to `CloudKitConfig`. 2. Mapping extension (`init?(record:)` /
+`makeRecord(in:parent:)` with `record.parent` → root). 3. Route through the `(scope, zoneID)` cache
+— never hardcode a DB. 4. Exercise every field in Dev (non-empty lists!), then deploy schema to
+Production. 5. Two-account device test before shipping.
+
+
+## Atomic multi-record persistence — encode it in the CONTRACT
+> ⚠️ **Gotcha:** Symptom — a pin saves but the player profile write fails (or vice-versa):
+> XP/achievements drift from the pin set forever. Cause — two separate `save` calls where the
+> domain requires all-or-nothing. Fix — the repository CONTRACT exposes the atomic operation
+> (`savePinAndPlayer(_:_:)` — one method, one `modifyRecords(atomically: true)` underneath),
+> so no caller CAN write them separately. If two records must stay consistent, their atomicity
+> belongs in the protocol, not in caller discipline.