@horka/app-forge 0.1.0

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

@@ -0,0 +1,241 @@
+# NAVIGATION.md — Navigation Architecture
+
+No navigation library, no global Coordinator. Three layers:
+1. **Root gating** — `RootView` switches on store state (splash → onboarding → tabs).
+2. **Per-tab `NavigationStack(path:)`** — value-based destinations, path mutated by Interactors.
+3. **External-event routing** — a dedicated `PushRouter` object owned by the AppDelegate, with a weak store reference and a pending-event queue for cold-launch races.
+
+## 1. Root gating
+
+`RootView` is a pure state switch. No `NavigationStack` at the root — stacks live inside tabs.
+
+```swift
+@main
+struct App: SwiftUI.App {
+    @UIApplicationDelegateAdaptor(AppDelegate.self) private var appDelegate
+    @State private var store = ItemStore()
+
+    var body: some Scene {
+        WindowGroup {
+            RootView()
+                .environment(store)
+                .task {
+                    appDelegate.pushRouter.store = store   // wire BEFORE bootstrap
+                    await store.bootstrap()
+                }
+        }
+    }
+}
+
+struct RootView: View {
+    @Environment(ItemStore.self) private var store
+    @Environment(\.scenePhase) private var scenePhase
+
+    var body: some View {
+        Group {
+            if !store.isReady {
+                App.Splash()            // first load — no flash of empty/default data
+            } else if store.needsOnboarding {
+                App.Welcome()           // first launch — complete profile before entering
+            } else {
+                tabs
+            }
+        }
+        .onChange(of: scenePhase) { _, phase in
+            if phase == .active { Task { await store.handleForeground() } }
+        }
+    }
+
+    private var tabs: some View {
+        TabView {
+            Tab("Feed", systemImage: "house.fill") { App.Feed() }        // owns its stack
+            Tab("Map", systemImage: "map.fill") { NavigationStack { App.Map() } }
+            Tab("Groups", systemImage: "person.2.fill") { App.Groups() } // owns its stack
+            Tab("Profile", systemImage: "person.crop.circle.fill") { NavigationStack { App.Profile() } }
+        }
+    }
+}
+```
+
+Rules:
+- Gate on `store.isReady`, never on "data is empty" — empty is a valid state, loading is not.
+- Tabs that push destinations own their `NavigationStack` *inside* the tab view (so the path lives in that tab's ViewModel). Tabs that never push get a plain `NavigationStack { }` wrapper in `RootView` for the nav bar.
+- App-wide errors surface as one alert on `RootView` bound to `store.lastError`.
+
+> ⚠️ **Gotcha:** an alert attached to the presenter cannot appear over a presented sheet. Symptom: errors thrown from a sheet's save action silently never show. Cause: SwiftUI presents one thing per branch; the root alert is occluded by the sheet. Fix: sheets that can fail keep their **own** local alert.
+
+## 2. Per-tab stacks: typed paths + Interactor-driven navigation
+
+Each tab follows View / ViewModel / Interactor. The **path is state on the ViewModel**; the **Interactor mutates it**. Views never use raw `NavigationLink` to other features and never know sibling screens exist.
+
+```swift
+extension App.Feed {
+    @Observable
+    final class ViewModel {
+        /// Navigation path for this tab's stack — driven by the Interactor.
+        var path: [ItemGroup] = []
+        /// Drives the anchored popover for the tapped badge.
+        var selectedBadgeID: String?
+    }
+
+    struct Interactor {
+        let store: ItemStore
+        let viewModel: ViewModel
+
+        /// Navigation goes through the Interactor (no NavigationLink in the View).
+        func openGroup(_ group: ItemGroup) {
+            viewModel.path.append(group)
+        }
+    }
+}
+
+extension App.Feed {
+    var body: some View {
+        NavigationStack(path: $viewModel.path) {
+            ScrollView { /* sections */ }
+                .navigationDestination(for: ItemGroup.self) { App.GroupDetail(group: $0) }
+        }
+    }
+}
+```
+
+- Single destination type per tab → path is `[ItemGroup]` directly. Multiple destination types → declare a tab-local `enum Route: Hashable { case group(ItemGroup), item(Item.ID) }`, path is `[Route]`, one `navigationDestination(for: Route.self)` switch.
+- Pop = `viewModel.path.removeLast()`; pop-to-root = `viewModel.path = []`. Both testable without UI.
+- Cross-tab "navigation" does not exist. If an external event must land on a specific screen, the store exposes state (e.g. `pendingInviteGroupID`) and the owning tab reacts to it — never reach into another tab's path.
+- Name the domain type `ItemGroup`, not `Group`: `Group` collides with `SwiftUI.Group` in every view file.
+
+## 3. External-event routing: `PushRouter`
+
+One small `@MainActor` object bridges system callbacks (silent pushes, share/deeplink acceptance) to store refreshes. The AppDelegate owns it; the SwiftUI scene wires the store after launch.
+
+```swift
+@MainActor
+final class PushRouter {
+    weak var store: ItemStore? {
+        didSet {
+            // Cold-launch race: a share accepted before the scene wired the store
+            // would otherwise be lost. Flush the queued event once the store connects.
+            if store != nil, pendingShareAccept {
+                pendingShareAccept = false
+                Task { await didAcceptShare() }
+            }
+        }
+    }
+    private var pendingShareAccept = false
+
+    /// Silent CloudKit push → targeted refresh (payload only says "something changed").
+    func handle(_ notification: CKNotification) async {
+        switch notification.notificationType {
+        case .database:   await store?.refreshGroups()
+        case .recordZone: await store?.refresh()
+        default:          await store?.refresh(); await store?.refreshGroups()
+        }
+    }
+
+    func didAcceptShare() async {
+        guard let store else { pendingShareAccept = true; return }   // queue, don't drop
+        await store.refreshGroups()
+        try? await Task.sleep(for: .seconds(2))  // server-side propagation delay
+        await store.refreshGroups()              // second pass picks up the new shared zone
+    }
+}
+```
+
+> ⚠️ **Gotcha (cold-launch race):** symptom — accepting a share invite while the app is cold-launched does nothing; the joined group never appears. Cause — `userDidAcceptCloudKitShareWith` fires *before* the SwiftUI scene runs `.task` and wires `pushRouter.store`, so the event hits a `nil` store and is dropped. Fix — set a `pending` flag in the guard and flush it in `store`'s `didSet` (shown above). Apply this queue-and-flush pattern to **every** external entry point (deeplinks, notification taps).
+
+> ⚠️ **Gotcha (propagation delay):** symptom — after accepting a share, the first refresh returns no new data. Cause — the backend needs time to surface the newly shared zone after `accept`. Fix — refresh immediately *and* again after ~2s. Never rely on a single post-accept fetch.
+
+## 4. Scene delegate: required even with SwiftUI lifecycle
+
+In a SwiftUI App-lifecycle app, some system callbacks are delivered to the **scene** delegate, not the app delegate — CloudKit share acceptance (`userDidAcceptCloudKitShareWith`) is the canonical example. SwiftUI still creates and owns the window; you only *declare* the delegate class:
+
+```swift
+final class AppDelegate: NSObject, UIApplicationDelegate {
+    let pushRouter = PushRouter()
+
+    /// Declare the scene delegate class. SwiftUI keeps ownership of the window.
+    func application(_ application: UIApplication,
+                     configurationForConnecting session: UISceneSession,
+                     options: UIScene.ConnectionOptions) -> UISceneConfiguration {
+        let config = UISceneConfiguration(name: nil, sessionRole: session.role)
+        if session.role == .windowApplication {
+            config.delegateClass = SceneDelegate.self
+        }
+        return config
+    }
+}
+
+final class SceneDelegate: NSObject, UIWindowSceneDelegate {
+    func windowScene(_ windowScene: UIWindowScene,
+                     userDidAcceptCloudKitShareWith metadata: CKShare.Metadata) {
+        let pushRouter = (UIApplication.shared.delegate as? AppDelegate)?.pushRouter
+        Task {
+            try? await ShareAcceptance.accept(metadata)  // metadata is non-Sendable: consume it here
+            await pushRouter?.didAcceptShare()
+        }
+    }
+}
+```
+
+Rules:
+- Do **not** implement `scene(_:willConnectTo:)` — that would take window ownership away from SwiftUI.
+- Implement the share-accept callback in **both** delegates (app delegate gets it on some OS paths, scene delegate on others). Both funnel into the same `PushRouter` method, so duplication is one line.
+- `CKShare.Metadata` is non-Sendable: accept it inside one `@MainActor` helper and only let Sendable results (IDs) escape.
+
+> ⚠️ **Gotcha:** symptom — tapped invite links open the app but nothing happens; the app-delegate hook never fires. Cause — with the SwiftUI lifecycle the system delivers share acceptance to the *scene* delegate, and no scene delegate exists by default. Fix — the `configurationForConnecting` + `delegateClass` wiring above. Without it the callback is silently lost.
+
+## 5. Popovers & sheets
+
+Anchored detail (map markers, badge cells) uses `.popover` + `.presentationCompactAdaptation(.popover)` (anchored glass popover on iPhone instead of a sheet). One selection at a time via a `selectedID` + derived `Binding<Bool>`:
+
+```swift
+@State private var selectedID: UUID?
+
+marker(item)
+    .onTapGesture { selectedID = item.id }
+    .popover(isPresented: binding(for: item.id)) {
+        detail(item).presentationCompactAdaptation(.popover)
+    }
+
+private func binding(for id: UUID) -> Binding<Bool> {
+    Binding(
+        get: { selectedID == id },
+        set: { isPresented in
+            if isPresented { selectedID = id }
+            else if selectedID == id { selectedID = nil }   // only clear if still ours
+        }
+    )
+}
+```
+
+In the `set:` closure, guard `selectedID == id` before clearing — a stale dismiss from a previous popover must not wipe a newer selection.
+
+> ⚠️ **Gotcha (orphaned popover — real production bug):** symptom — after deleting an item while its popover was open, tapping any other marker did nothing; the map was stuck. Cause — the item vanished from the list but `selectedID` still pointed to it, so SwiftUI kept trying to re-present a popover anchored to a non-existent annotation on every camera change, swallowing new selections. Two-part fix:
+> 1. **Dismiss before mutating** in the detail view's destructive action:
+> ```swift
+> Button("Delete", role: .destructive) {
+>     dismiss()        // close the popover FIRST so it can't orphan
+>     onDelete?()
+> }
+> ```
+> 2. **Prune stale selection** defensively in the container:
+> ```swift
+> .onChange(of: items.map(\.id)) { _, ids in
+>     if let selected = selectedID, !ids.contains(selected) { selectedID = nil }
+> }
+> ```
+> Do both. Never mutate a list while a presentation anchored to one of its rows is open.
+
+Sheets (create/edit flows) follow the same discipline: a `Bool` or optional-item flag on the ViewModel (`isCreating`, `pendingInvite: GroupShare?`), toggled by the Interactor on success — the View never decides when a flow ends.
+
+## Decision summary
+
+| Concern | Pattern |
+|---|---|
+| Root routing | State switch in `RootView` (splash / onboarding / tabs) |
+| In-tab navigation | `NavigationStack(path:)`, path on ViewModel, mutated by Interactor |
+| Cross-feature navigation | Forbidden; react to store state instead |
+| External events | `PushRouter` (weak store + pending queue flushed in `didSet`) |
+| Share/deeplink entry | App delegate **and** scene delegate → same `PushRouter` |
+| Anchored detail | `.popover` + `presentationCompactAdaptation(.popover)` + `selectedID` binding |
+| Delete-while-presented | `dismiss()` first, then mutate; prune `selectedID` on list change |

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

@@ -0,0 +1,176 @@
+# TESTING — Strategy & Patterns
+
+Swift Testing (`@Test` / `#expect`), not XCTest — the only exception is XCUITest UI automation, which the framework forces onto `XCTestCase`. All domain tests live in the Core package and run with plain `swift test` — no simulator, no Xcode project, < 10 s.
+
+## 1. Test Pyramid
+
+| Layer | Coverage | How |
+|---|---|---|
+| **Core package** (engines, services, models) | Exhaustive unit tests | `swift test --package-path Packages/{{PROJECT_NAME}}Core`. Pure logic, fast, deterministic. This is where ~95% of tests live. |
+| **DataLayer** (CloudKit repositories) | Mapping & persistence-format tests, offline | Gate `swift build --package-path Packages/DataLayer` today (the skeleton ships no test target — `swift test` would exit 1, "no tests found"). Add a `DataLayerTests` target and switch to `swift test` once you have `CKRecord`↔domain round-trips, change-token store, merge policy — all in memory, no iCloud account. Real cloud IO (push, share accept) is validated manually on device. `InMemory*Repository` actors in Core keep every Store/Service testable without a database. |
+| **UI** (SwiftUI views) | Thin XCUITest smoke/flow tests + simulator-MCP validation | XCUITests launch the app on the in-memory backend (`-uitest-mock` launch arg) so flows are deterministic and instant. Keep them few — views stay dumb; logic worth testing belongs in Core. |
+
+What makes this work: engines are `public enum` with only `static` pure functions, `nonisolated` by nature, with `Calendar` (and `now: Date`) injected. No singletons, no system-clock reads, no I/O. Testable by construction.
+
+```swift
+public enum AchievementEngine {
+    public static func satisfiedIDs(
+        profile: Profile,
+        items: [Item],
+        calendar: Calendar = .current   // injected — tests pass a fixed UTC calendar
+    ) -> Set<String> { ... }
+}
+```
+
+## 2. Swift Testing Patterns
+
+One `@Suite struct` per engine/service; `@Test` functions; `#expect` for assertions; `await #expect(throws: SomeError.x)` for async error paths.
+
+### Fixture helpers (`TestSupport.swift`)
+
+A single `Fixture` enum provides builder functions with defaults, so each test only spells out what matters:
+
+```swift
+extension Calendar {
+    /// Deterministic calendar for tests (Gregorian, UTC) so day/hour boundaries are stable.
+    static var utcTest: Calendar {
+        var calendar = Calendar(identifier: .gregorian)
+        calendar.timeZone = TimeZone(identifier: "UTC")!
+        return calendar
+    }
+}
+
+enum Fixture {
+    static let calendar = Calendar.utcTest
+
+    static func date(_ year: Int, _ month: Int, _ day: Int,
+                     _ hour: Int = 12, _ minute: Int = 0) -> Date {
+        var c = DateComponents()
+        (c.year, c.month, c.day, c.hour, c.minute) = (year, month, day, hour, minute)
+        return calendar.date(from: c)!
+    }
+
+    static func item(lat: Double = 48.85, lon: Double = 2.35,
+                     country: String? = "FR", rating: Int = 3,
+                     at occurredAt: Date) -> Item {
+        Item(coordinate: Coordinate(latitude: lat, longitude: lon),
+             countryCode: country, rating: rating,
+             occurredAt: occurredAt, createdAt: occurredAt)
+    }
+}
+```
+
+Rules:
+- **Explicit dates always.** Every test passes `Fixture.date(2026, 6, 1)` — never `Date()`, never `.now`. Domain logic that reads the system clock is untestable; pass `now: Date` as a parameter instead.
+- **Vary coordinates to isolate rules.** When a test needs N distinct places, use `lat: Double(index)` so place-dedup rules don't interfere with the rule under test.
+- **Test both sides of every boundary.** A rule "hour in 5..<8" gets one test at 6 (unlocks) and one at 8 (must NOT unlock — exclusive bound).
+
+## 3. Catalog-Consistency Tests
+
+Whenever content lives in a catalog (achievements, ranks, themes) AND in engine rules, add one test that locks them together:
+
+```swift
+@Test func catalogIsConsistent() {
+    let ids = AchievementCatalog.all.map(\.id)
+    #expect(Set(ids).count == ids.count)                          // no duplicate ids
+    #expect(ids.allSatisfy { AchievementID(rawValue: $0) != nil }) // no orphan slug / typo
+    #expect(AchievementCatalog.all.count == AchievementID.allCases.count) // full coverage
+}
+```
+
+Pair it with a typed-ID enum inside the engine: rules insert `AchievementID` cases (typo = compile error) and convert to `String` slugs only at the return boundary.
+
+> ⚠️ **Gotcha:** A new catalog entry shipped with no engine rule — visible in the UI, permanently locked, zero test failures. Cause: catalog and engine were two unlinked lists. Fix: the consistency test above. **Never hardcode counts** (`#expect(ids.count == 37)`); derive from `CaseIterable.allCases.count` so adding content can't silently desync, and the test never needs editing.
+
+## 4. Service Tests via InMemory Repositories
+
+Every repository protocol gets a thread-safe `actor InMemory*Repository` in the Core package itself (also reused by SwiftUI previews). Services are then tested end-to-end without persistence:
+
+```swift
+@Suite struct ItemServiceTests {
+    let calendar = Fixture.calendar
+
+    private func makeService(profile: Profile = Profile(id: "u"), items: [Item] = []) -> ItemService {
+        ItemService(repository: InMemoryItemRepository(profile: profile, items: items),
+                    calendar: calendar)
+    }
+
+    @Test func addFirstItemAwardsXPAndFirstBadge() async throws {
+        let service = makeService()
+        let result = try await service.addItem(
+            ItemDraft(coordinate: .init(latitude: 48, longitude: 2),
+                      occurredAt: Fixture.date(2026, 6, 1)),
+            now: Fixture.date(2026, 6, 1))   // `now` injected, never read inside
+        #expect(result.xpGained == 25)
+        #expect(result.newAchievements.contains { $0.id == "first_item" })
+    }
+}
+```
+
+Test the *invariants*, not just happy paths: delete reverses item XP but keeps earned achievements; recompute is idempotent (`second.newAchievements.isEmpty`); best-streak is monotonic across deletions; validation errors throw (`await #expect(throws: GroupValidationError.emptyName) { ... }`).
+
+## 5. Concurrency Tests (actor reentrancy)
+
+> ⚠️ **Gotcha:** Concurrent `addItem` calls lost writes despite the service being an `actor`. Cause: actors are **reentrant across `await`** — two read-modify-write sequences interleaved at the repository `await` and the second save clobbered the first. Fix: a `serialized()` operation queue inside the service; proven by tests, not by reading the code:
+
+```swift
+@Test func concurrentAddsLoseNoWrites() async throws {
+    let service = makeService()
+    await withTaskGroup(of: Void.self) { group in
+        for i in 0..<25 {
+            group.addTask { _ = try? await service.addItem(draft(index: i), now: day) }
+        }
+    }
+    let snapshot = try await service.snapshot()
+    #expect(snapshot.items.count == 25)   // no lost updates
+    // persisted XP == one deterministic from-scratch recompute over the final item set
+    #expect(snapshot.profile.xp == ProgressEngine.recompute(
+        identity: Profile(id: "u"), items: snapshot.items, calendar: calendar).profile.xp)
+}
+```
+
+The "converges to a deterministic recompute" assertion catches both double-counting and lost increments — stronger than counting alone.
+
+## 6. Merge / Sync Logic Tests
+
+For local↔server merge (`Profile.merged(with:)`), test the field-by-field policy explicitly:
+- Monotonic fields (`xp`, `streakBest`, unlocked-achievement set): max / union — **never regress**, and merge must be **symmetric** (`a.merged(b) == b.merged(a)` on those fields — test it).
+- Non-monotonic fields (`streakCurrent`, `lastActiveDay`): follow the more recent day, **even if the value shrinks** — write a test documenting that shrinking is intentional, or someone will "fix" it.
+
+## 7. Determinism Gotchas
+
+> ⚠️ **Gotcha:** Time-window rules (e.g. "22:00–05:00") passed locally, failed on CI. Cause: `Calendar.current` uses the machine's timezone; an hour-boundary test is a different wall-clock hour elsewhere. Fix: inject `Calendar` into every engine function; tests always pass `Calendar.utcTest` (Gregorian + UTC).
+
+> ⚠️ **Gotcha:** "Most visited place" flickered between app launches. Cause: tie between two equally-visited places resolved by `Dictionary` iteration order, which is nondeterministic. Fix: stable tie-break (smaller key wins) + a test computing stats on `items` and `items.reversed()` and asserting equal output.
+
+> ⚠️ **Gotcha:** Two coordinates centimeters apart counted as two distinct places. Cause: place keys built by stringifying rounded doubles — `-0.0` and `0.0` stringify differently around the equator/meridian. Fix: integer quantization before keying; regression test asserts `placeKey` of `+0.00001` and `-0.00001` are both `"0,0"` and contain no `"-0"`.
+
+> ⚠️ **Gotcha:** UI showed a "7-day streak" days after it died. Cause: `currentStreak` is frozen at the last activity day; nothing recomputes it until the next write. Fix: a separate `liveStreak` derived with an explicit `now:` parameter (0 if last activity > 1 day ago); tested at now = same day, next day (still alive — user can still extend), and +2 days (dead).
+
+General rules:
+- `sorted()` before comparing collections or picking "first" from grouped data — `Set`/`Dictionary` order is never stable.
+- Engines never call `Date()`, `Calendar.current`, `TimeZone.current`, or `Locale.current` internally. All injected.
+- Weekday/weekend logic must be locale-independent: match `calendar.component(.weekday, ...)` values (1 = Sunday, 7 = Saturday), never rely on `firstWeekday`.
+
+## 8. How AI Agents Must Use Tests
+
+1. **Run `swift test --package-path Packages/{{PROJECT_NAME}}Core` after EVERY engine/domain change.** It's seconds. No "I'll run it at the end".
+2. **Every new rule ships with its tests** in the same change: the unlock case, the just-below-threshold case, and the boundary case. A rule without a test does not exist.
+3. **New catalog entry?** The consistency test fails until you add the matching enum case + engine rule. That failure is the workflow — don't weaken the test.
+4. **Tests are the spec.** When behavior is ambiguous, the test file is the authority (e.g. "merge can shrink current streak" is documented intent, not a bug). Read the relevant suite before changing an engine.
+5. **Never edit an existing assertion to make your change pass** without understanding why it was written — most encode a fixed production bug. If a behavior change is intentional, update the test *and* its doc comment.
+
+## UI / snapshot tests — when to add them (V2, deliberately not V1)
+MVP skips UI tests on purpose: layouts churn too fast and brittle tests slow every slice. Add them
+when (a) a screen has survived 3+ slices unchanged, or (b) a visual regression actually bit you.
+Then prefer snapshot tests of MODULE bricks (L4 — stable contracts, no navigation) over full-screen
+flows, and keep them in the app target, not the packages. Until then: the simulator screenshot at
+every slice gate IS the UI regression net — actually look at it.
+
+## Concurrency testing (Swift)
+- The Thread Sanitizer is the truth serum: `swift test --sanitize=thread` on packages periodically
+  (it's slow — not every run; before each release at minimum).
+- A concurrency bug fixed = a regression test that reproduces the race (e.g. N concurrent calls via
+  `TaskGroup` asserting a single side effect) — same discipline as any other gotcha.
+- Swift 6 strict concurrency catches data races at compile time; never silence it with
+  `@unchecked Sendable` to make a test pass — fix the isolation instead.

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

@@ -0,0 +1,165 @@
+# WORKFLOW — Dev Loop & AI-Agent Operating Manual
+
+How to ship features in {{PROJECT_NAME}}. Prescriptive. Follow exactly.
+
+## 1. Slice-Based Delivery
+
+Ship **vertical slices**: thin end-to-end features (UI → domain → persistence), never horizontal layers across the whole app. One slice = one shippable increment validated on simulator.
+
+**Per slice:**
+1. **Blueprint first** — write the slice's blueprint as a section of `docs/SLICES.md` before any
+   code (single canonical file — per-slice standalone files drift). Must contain:
+   - The key architectural decision for the slice (e.g. "one CKRecordZone per Group, root record carries the CKShare") and why alternatives were rejected.
+   - Phases mapped to layers, each with an explicit file list (`NEW`/`MODIFY`) and signatures.
+   - A "Gotchas" section (known traps for the APIs involved).
+   - A production checklist (schema deploys, entitlements, device-only validations).
+2. **Implement layer by layer**, gating each phase:
+   - **Phase A — Core package** (pure Swift, zero IO): domain types, engines, repository *protocols*, `InMemory*Repository`, service actors. Gate: `swift test` green.
+   - **Phase B — DataLayer package** (CloudKit/IO, depends on Core): record mapping, repositories as actors. Gate: `swift build` green today (DataLayer ships no test target yet); `swift test` once you add one for the mapping round-trips (they run offline, in memory).
+   - **Phase C — Module + App**: reusable UI components in `Module/`, then screens (`View / @Observable ViewModel / struct Interactor`). Gate: `xcodebuild build` green + app launched + screens rendered from sample data.
+3. **Validate on simulator** (screenshots, tapping through flows — see §3).
+4. **Update memory files** (§5) before considering the slice done.
+
+Track slice status with checkboxes in `NEXT_STEPS.md`; log what was actually built (with test counts and verification status) in `PROJECT_STATE.md`.
+
+## 2. Build & Test Loop (agents: this exact order)
+
+**Packages FIRST. Always.** `swift test` on a pure package takes seconds and gives precise errors; `xcodebuild` takes minutes and buries them.
+
+```bash
+# 1. Per-package, fast, no simulator needed
+swift test  --package-path Packages/{{PROJECT_NAME}}Core
+swift build --package-path Packages/DataLayer     # swift test once DataLayer has a test target (CKRecord mapping round-trips)
+swift build --package-path Packages/{{PROJECT_NAME}}DS
+
+# 2. App target — ONLY when all packages are green (xcodegen puts the .xcodeproj at the repo 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:|warning:.*deprecated|BUILD"
+
+# 3. App-target tests (only for app-layer logic: stores, formatting, UI tests)
+xcodebuild -project {{PROJECT_NAME}}.xcodeproj -scheme {{PROJECT_NAME}} \
+  -destination 'platform=iOS Simulator,name=iPhone 17 Pro' test 2>&1 | grep -E "error:|Test Suite|passed|failed"
+```
+
+- Pin `-derivedDataPath /tmp/{{PROJECT_NAME}}_dd` so the built `.app` is at a known path for install.
+- Always pipe through `grep -E "error:|BUILD"` — never dump full xcodebuild output into context.
+- Quote paths: a `&` or space in a directory name breaks zsh silently.
+- New code that is testable without UI goes in a package, not the app target — that's the whole point of the split.
+
+> ⚠️ **Gotcha — XcodeGen owns the project, not the pbxproj:** this project is generated by XcodeGen from `project.yml`, and the `.xcodeproj` is gitignored. Source files are picked up from the `sources:` globs in `project.yml` and packages from its `packages:`/`dependencies:` — adding a new `.swift` file under the app folder is included automatically on the next `xcodegen generate` (NOT by Xcode synchronized folders — those aren't in play here). Adding a *new local package* means editing `project.yml` (a `packages:` entry + a `dependencies:` line on the target), then re-running `xcodegen generate`. Never hand-edit the `.xcodeproj` — it's regenerated and your edit is lost.
+
+### Simulator install / launch / visual check
+
+After a green build, install and drive the app via the iOS-simulator MCP tools:
+
+1. Rebuild with `-derivedDataPath /tmp/{{PROJECT_NAME}}_dd`.
+2. `install_app` with `/tmp/{{PROJECT_NAME}}_dd/Build/Products/Debug-iphonesimulator/{{PROJECT_NAME}}.app`.
+3. `launch_app` with terminate-running enabled.
+4. `screenshot` to verify rendering; `ui_describe_all` for element coords; `ui_tap` / `ui_type` / `ui_swipe` to drive flows end-to-end.
+
+`screenshot` / `launch_app` / `record_video` ride on `simctl` and always work. `ui_tap` / `ui_describe_all` / `ui_find_element` require **idb**: `brew install facebook/fb/idb-companion` + `uv tool install fb-idb`, verify with `idb list-targets`.
+
+> ⚠️ **Gotcha — stale simulator binary:** the app on the simulator can be an old build (you tap a button that "doesn't exist"). **Always reinstall the current build before visual verification.** Symptom: feature missing on screen that compiles fine. Cause: you launched yesterday's binary. Fix: rebuild → `install_app` → `launch_app`, every time.
+
+> ⚠️ **Gotcha — SwiftUI toolbar items invisible to accessibility tooling:** navigation-bar items (back, "+") are collapsed into an unexposed "Nav bar" group, so `ui_find_element` never finds them. Tap visual coordinates instead (vertical center of the nav bar ≈ y=88 on current iPhones).
+
+> ⚠️ **Gotcha — CloudKit account probe stalls UI tests:** `CKContainer.accountStatus` can hang ~150 s on a freshly cloned simulator, freezing app startup. Fix: a launch argument (e.g. `-uitest-mock`) that makes the store bootstrap force the in-memory backend instantly; pass it in every UITest and agent-driven launch.
+
+## 3. Device Debugging: `os.Logger`, never `print()`
+
+`print()` output is only visible when Xcode's debugger is attached. On a real device launched from the home screen — exactly when CloudKit, push, and share-acceptance bugs appear — `print()` goes nowhere. Use `os.Logger`:
+
+```swift
+import os
+
+let logger = Logger(subsystem: "{{BUNDLE_ID}}", category: "Store")
+
+logger.info("account=\(status.rawValue, privacy: .public) backend=\(backendName, privacy: .public)")
+logger.error("bootstrap failed: \(error.localizedDescription, privacy: .public)")
+```
+
+- Interpolated values are `<private>` by default — add `privacy: .public` to every value you actually need to read, or the log is useless.
+- Read logs in Xcode (Window → Devices, or the console while running) or Console.app filtered by subsystem. Logs persist even when the app was launched without a debugger.
+- Log at every backend decision point: account status, chosen backend (cloud vs in-memory), and raw server errors.
+
+> ⚠️ **Gotcha — bug invisible on simulator, found only via device logs:** real-device sync "silently" loaded 0 items while the simulator (in-memory fallback) looked fine. Device logs showed CloudKit error 12/2006: *"cannot use an empty list to initialize a new field"*. Cause: CloudKit (Development) infers a List field's type at first save and **rejects an empty array** — so any fresh user whose record had `unlockedIDs = []` failed its very first save. Fix: in `CKRecord` mapping, **omit list fields when empty** (reads default to `[]`; the schema field is created on the first non-empty save). Without device logging this is undiagnosable.
+
+> ⚠️ **Gotcha — CKShare acceptance never fires in AppDelegate:** with the SwiftUI App lifecycle, `userDidAcceptCloudKitShareWith` is delivered to the **scene delegate**, not the app delegate. Provide a `SceneDelegate` via `application(_:configurationForConnecting:options:)` (`delegateClass`) and implement `windowScene(_:userDidAcceptCloudKitShareWith:)`. Log in both handlers to see which fires. Also: invite links show "you need a newer version of this app" unless Info.plist contains `CKSharingSupported = true`.
+
+## 4. Memory System (anti-hallucination)
+
+Persistent context lives in `.claude/memory/`. **Restore at session start** (read all five files before doing anything). **Update after every significant change** — a session whose work isn't in memory didn't happen, because the next session can't see it.
+
+| File | Contains |
+|------|----------|
+| `PROJECT_STATE.md` | What the app is, stack, package list with test counts, per-slice done log, **session-by-session changelog with verification status**, gotchas discovered, known remaining issues. The priority file. |
+| `ARCHITECTURE.md` | Technical structure: layers, patterns (VVM-I, actors), package dependency graph, data flow. |
+| `DECISIONS.md` | Numbered table (`D1, D2, …`): decision + one-line *why*. Append-only; reference IDs (e.g. "per D11") instead of re-litigating. |
+| `NEXT_STEPS.md` | Roadmap with checkboxes per slice/phase, deferred findings, tech debt with file:line pointers. |
+| `COMMANDS.md` | Real, verified commands (build, test, simulator, scripts) + environment quirks. Copy-paste ready. |
+
+Rules:
+- **Never invent project facts.** If memory doesn't cover it, read the code or ask.
+- Record *negative* results too ("clustering: SwiftUI `Map` still has no native API even on iOS 26 — verified against docs; hand-rolled instead"). They prevent the next session from re-exploring dead ends.
+- Track unfixable-offline issues explicitly (e.g. a "needs 2 iCloud accounts / real device" list) so they aren't silently forgotten before release.
+
+## 5. Validation Etiquette (non-negotiable)
+
+1. **Never claim "done" without building.** "It should work" is not a status. Minimum bar: packages `swift test` green + app `xcodebuild build` green.
+2. **UI changes require a screenshot.** Rebuild → reinstall → launch → screenshot (and tap through the flow for interactions). "Build succeeded" says nothing about rendering.
+3. **Logic changes require tests.** New domain rules get unit tests in the owning package, including non-regression tests for every fixed bug (the empty-list fix above shipped with one).
+4. **Report status honestly, in tiers:**
+   - *Tested* — unit tests cover it, green.
+   - *Verified on simulator* — seen working via screenshot/taps.
+   - *Builds, unverified* — compiles; behavior not observed.
+   - *Device-only, NOT validated* — push, share acceptance, real iCloud accounts. Say so explicitly and keep a running list; never imply these work because the simulator fallback ran.
+5. **Run adversarial review before release-grade milestones.** Confirmed findings get fixed *and re-validated* (tests + build + simulator); deferred findings go to `NEXT_STEPS.md` with the reason.
+
+> ⚠️ **Gotcha — orphaned popover after deleting its anchor:** deleting an item from its own anchored popover left the popover floating (anchor gone), blocked selecting other items, and made the deleted marker "re-pop" while panning (SwiftUI recreated the annotation to serve the anchor). Fix: the detail card dismisses itself via `@Environment(\.dismiss)` on delete, AND the map clears `selectedID` in `onChange(of: items.ids)` when the selected item disappears. Verify deletion flows by actually deleting on the simulator — this class of bug is invisible to builds and unit tests.
+
+> ⚠️ **Gotcha — UITests welded to display copy:** UITests matching localized button text break on every rewording. Put stable `accessibilityIdentifier`s on test-critical controls (FABs, tabs, primary CTAs, markers) and match those; keep `accessibilityLabel` for VoiceOver.
+
+
+## Tooling gate (run BEFORE Phase 1 of any kickoff — hard stop, not a parting note)
+```bash
+xcodegen --version                                   # required to generate the .xcodeproj
+xcrun simctl list runtimes | grep iOS                # a runtime must match project.yml's deploymentTarget
+```
+Missing tool → tell the user the one-line install NOW (`brew install xcodegen`) and agree on the
+degraded-proof plan below before writing any code. Never discover this mid-build.
+
+## Degraded-proof ladder (no .xcodeproj / no simulator available)
+L5 app-target sources cannot be left "written but never compiled" — that shipped a broken screen
+once. When `xcodegen`/simulator are unavailable, the MINIMUM proof is:
+```bash
+# 1. Build each package for the simulator (works WITHOUT an .xcodeproj — xcodebuild understands SPM):
+cd Packages/{{PROJECT_NAME}}DS && xcodebuild -scheme {{PROJECT_NAME}}DS \
+  -destination 'generic/platform=iOS Simulator' -derivedDataPath /tmp/dd build
+# (repeat for Core and DataLayer)
+# 2. Typecheck the app-target sources against those products:
+xcrun swiftc -typecheck -parse-as-library -swift-version 6 \
+  -default-isolation MainActor -module-name {{PROJECT_NAME}} \
+  -sdk $(xcrun --sdk iphonesimulator --show-sdk-path) \
+  -target arm64-apple-ios26.0-simulator \
+  -I /tmp/dd/Build/Products/Debug-iphonesimulator $(find {{PROJECT_NAME}} -name '*.swift')
+# -parse-as-library (required for @main) · -default-isolation MainActor (mirrors the app
+# target's SWIFT_DEFAULT_ACTOR_ISOLATION) · without these the typecheck fails on valid sources
+```
+Report which rung was reached (simulator screenshot > app build > typecheck > package tests).
+A lower rung is acceptable ONLY if stated explicitly in the slice report and logged as debt.
+
+> ⚠️ **Gotcha:** Symptom — a demo value ("~12 min", "5 items") presented as "computed by the
+> engine" turns out fabricated. Rule — any number/string attributed to code must come from
+> actually executed output (test log, REPL, app run). If you didn't run it, label it an estimate.
+
+
+## Launch checklist (before ANY external testers)
+- CloudKit: schema deployed Dev→Prod, `aps-environment` = production (see CLOUDKIT_GUIDE).
+- User-generated content (shared groups, names, notes): report + block + ≤24h takedown path
+  (App Store Guideline 1.2 — rejection otherwise).
+- Age rating honest to the content; age gate in-app if 17+/18+.
+- Privacy: policy URL + App Privacy labels; precise location = sensitive (GDPR Art. 9 when
+  combined with intimate-life data) — collect the minimum, state the purpose.
+- Shared-data privacy review: what does a group member SEE about others (stable user ids?
+  exact coordinates?) — decide precision/pseudonymization consciously, log it in DECISIONS.md.

package/templates/packs/swift-ios/github/workflows/ci.yml

@@ -0,0 +1,48 @@
+# CI for {{PROJECT_NAME}} — proof over claims, automated from the first push.
+name: CI
+on:
+  push: { branches: [main, develop] }
+  pull_request:
+jobs:
+  packages:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Select newest Xcode (templates use swift-tools 6.2 → Xcode 26+)
+        # macos-latest defaults to an older Xcode whose Swift can't build swift-tools 6.2.
+        # Pick the newest installed Xcode (mirrors the AppForge scaffold-swift job).
+        run: |
+          set -o pipefail
+          LATEST="$(ls -d /Applications/Xcode*.app | sort -V | tail -n 1)"
+          echo "Using $LATEST"
+          sudo xcode-select -s "$LATEST"
+          swift --version
+      - name: Core tests (the spec)
+        run: swift test --package-path Packages/{{PROJECT_NAME}}Core
+      - name: DS builds
+        run: swift build --package-path Packages/{{PROJECT_NAME}}DS
+      - name: DataLayer builds
+        run: swift build --package-path Packages/DataLayer
+      - name: L5 typecheck ladder (no .xcodeproj needed)
+        # Build EVERY package for the simulator into ONE shared derivedData, then typecheck the
+        # app sources against ALL of their products — app code imports DS + Core + DataLayer, so a
+        # single-package -I would fail 'no such module'. A shared -derivedDataPath collects every
+        # .swiftmodule under one Products dir. pipefail makes `... | tail -1` surface a failed build
+        # instead of masking it behind tail's exit 0.
+        run: |
+          set -o pipefail
+          ROOT="$PWD"
+          DD=/tmp/dd
+          for pkg in {{PROJECT_NAME}}DS {{PROJECT_NAME}}Core DataLayer; do
+            ( cd "$ROOT/Packages/$pkg" && \
+              xcodebuild -scheme "$pkg" \
+                -destination 'generic/platform=iOS Simulator' \
+                -derivedDataPath "$DD" build 2>&1 | tail -1 )
+          done
+          PRODUCTS="$DD/Build/Products/Debug-iphonesimulator"
+          xcrun swiftc -typecheck -parse-as-library -swift-version 6 \
+            -default-isolation MainActor -module-name {{PROJECT_NAME}} \
+            -sdk "$(xcrun --sdk iphonesimulator --show-sdk-path)" \
+            -target arm64-apple-ios26.0-simulator \
+            -I "$PRODUCTS" \
+            $(find {{PROJECT_NAME}} -name '*.swift')

package/templates/packs/swift-ios/gitignore

@@ -0,0 +1,5 @@
+xcuserdata/
+*.xcodeproj
+DerivedData/
+.build/
+.swiftpm/

package/templates/packs/swift-ios/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "ios-simulator": {
+      "command": "npx",
+      "args": ["-y", "ios-simulator-mcp"]
+    }
+  }
+}