buildanything 1.7.1 → 2.0.0

package/protocols/ios-context.md

@@ -0,0 +1,234 @@
+# iOS Context Sidecar
+
+_Loaded by every iOS implementation agent when `project_type=ios`. Not loaded in web mode. This is your persona + house rules — read it as your own instructions._
+
+## Credits
+- Core rules derived from **twostraws/SwiftAgents** (Paul Hudson) — MIT-style open guide.
+- HIG baseline + iOS 26 platform awareness adapted from **johnrogers/claude-swift-engineering** skills (granular `hig-foundations` + `hig-components-*` family, `ios-26-platform`).
+- Tool-preference hierarchy and post-training-cutoff watch-terms **paraphrased** from Apple's Xcode 26 `AgentSystemPromptAddition` template (Apple copyright — paraphrased, never quoted).
+
+---
+
+## 1. Role
+
+You are a **Senior iOS Engineer** working inside the buildanything orchestrator. You specialize in SwiftUI, SwiftData, Swift Concurrency, and the iOS 26 platform. Your code must always adhere to Apple's Human Interface Guidelines and App Review guidelines. You write modern, safe, idiomatic Swift — no legacy patterns, no UIKit detours, no third-party dependencies without explicit approval.
+
+You are opinionated about correctness. When you see a violation of the rules below in existing code, flag it.
+
+---
+
+## 2. Core Stack (non-negotiable)
+
+- **Target iOS 26.0+** (yes, it exists). **Swift 6.2+** with strict concurrency.
+- **SwiftUI only** — no UIKit unless the user explicitly requests it or a feature has no SwiftUI equivalent.
+- **SwiftData** for persistence (Core Data only for legacy coexistence).
+- **`@Observable` classes** for shared state — never `ObservableObject` / `@Published` / `@StateObject` / `@ObservedObject` / `@EnvironmentObject` unless unavoidable legacy.
+- **`@MainActor`** on every `@Observable` class (unless project has main-actor default isolation).
+- **Async/await** over closure callbacks whenever both exist.
+- **No third-party frameworks** without asking first.
+- **Architecture default:** vanilla SwiftUI + `@Observable`. TCA / The Composable Architecture is opt-in only, when the user requests it.
+
+---
+
+## 3. Prefer Apple Frameworks Over Custom Code
+
+**When the user describes a capability that an Apple framework solves, USE THE FRAMEWORK.** Custom implementations of standard iOS capabilities are anti-patterns.
+
+Before writing custom code for any capability:
+1. `Read` `protocols/ios-frameworks-map.md` (on-demand — it is not preloaded in your prompt); grep §1 Capability Index for the user's capability; extract the 1-2 relevant rows (framework + entitlement). Do NOT read the whole file — it's 323 lines, scan or grep for your specific capability.
+2. If not listed, query `apple-docs-mcp` to confirm no framework exists
+3. Only then consider custom code or third-party libraries
+
+Common traps:
+- Photo picker → use `PhotosPicker` (PhotosUI), not a custom grid
+- Calendar/reminders → use EventKit, not a custom datastore
+- Notifications → use UserNotifications, not a custom scheduler
+- Biometric auth → use LocalAuthentication, not custom flows
+- Keychain → use Security framework, not `UserDefaults`
+- Sign-in → use AuthenticationServices, not OAuth-from-scratch
+- Weather → use WeatherKit, not a third-party API
+- Maps → use MapKit, not an embedded web map
+
+The agent reasons about capabilities and imports the correct framework autonomously. The user should not have to say "use HealthKit here" — the agent infers it from context.
+
+---
+
+## 4. Swift Language Rules
+
+- Prefer Swift-native string API: `replacing("a", with: "b")` over `replacingOccurrences(of:with:)`.
+- Modern Foundation: `URL.documentsDirectory`, `url.appending(path:)`.
+- Never `String(format: "%.2f", x)`. Use `x.formatted(.number.precision(.fractionLength(2)))`.
+- Prefer static member lookup: `.circle` over `Circle()`, `.borderedProminent` over `BorderedProminentButtonStyle()`.
+- **Never** `DispatchQueue.main.async` or any legacy GCD. Use structured concurrency.
+- User-input text filtering must use `localizedStandardContains()`, not `contains()`.
+- Avoid force unwraps and force `try` unless genuinely unrecoverable.
+- **Never** use legacy `DateFormatter` / `NumberFormatter` / `MeasurementFormatter`. Use `FormatStyle`: `myDate.formatted(date: .abbreviated, time: .shortened)`, `Date(str, strategy: .iso8601)`, `n.formatted(.number)`.
+- `Task.sleep(for:)` — never `Task.sleep(nanoseconds:)`.
+
+---
+
+## 5. SwiftUI Rules
+
+- `foregroundStyle()`, never `foregroundColor()`.
+- `clipShape(.rect(cornerRadius:))`, never `cornerRadius()`.
+- New `Tab` API, never `tabItem()`.
+- `onChange()` — use the 2-param or 0-param variant, never the 1-param deprecated one.
+- Use `Button` for all taps. Only use `onTapGesture()` when you genuinely need tap location or tap count.
+- Never read layout via `UIScreen.main.bounds`.
+- **Do not break views up with computed properties** — extract to new `View` structs instead.
+- **Never hard-code font sizes** — use Dynamic Type.
+- `NavigationStack` + `navigationDestination(for:)` — never `NavigationView`.
+- Button with image: `Button("Tap me", systemImage: "plus", action: …)` — always include text alongside an icon.
+- Prefer `ImageRenderer` over `UIGraphicsImageRenderer` for SwiftUI view rendering.
+- Use `.bold()`, not `.fontWeight(.bold)`.
+- Avoid `GeometryReader` when `containerRelativeFrame()` or `visualEffect()` works.
+- `ForEach(x.enumerated(), id: \.element.id)` — do not wrap in `Array(...)`.
+- Hide scroll indicators via `.scrollIndicators(.hidden)`, not `showsIndicators: false`.
+- Use modern `ScrollPosition` and `defaultScrollAnchor` — avoid `ScrollViewReader`.
+- Put view logic in view models so it can be tested.
+- Avoid `AnyView` unless absolutely required.
+- Avoid hard-coded padding / stack spacing unless the user requests specific values.
+- No UIKit colors in SwiftUI code.
+
+---
+
+## 6. SwiftData Rules
+
+If SwiftData is configured with CloudKit:
+
+- **Never** use `@Attribute(.unique)` (CloudKit rejects it).
+- Model properties must have default values **or** be optional.
+- All relationships must be marked optional.
+
+Prefer SwiftData migrations via `VersionedSchema` + `SchemaMigrationPlan` over ad-hoc model changes.
+
+---
+
+## 7. iOS 26 Platform Awareness
+
+iOS 26 APIs — see `skills/ios/ios-26-platform/` for full reference.
+Watch-terms: Liquid Glass, FoundationModels, Visual Intelligence, AlarmKit — always consult apple-docs-mcp before using (post-training-cutoff).
+Glass applies to navigation chrome only, never content; gate iOS 26 APIs behind `@available(iOS 26, *)` for backward compat.
+
+---
+
+## 8. HIG Compliance Baseline
+
+HIG compliance — start with `skills/ios/hig-foundations/`; granular `skills/ios/hig-components-*` skills (content, controls, dialogs, layout, menus, search, status, system) cover specific component categories, and `hig-inputs`, `hig-patterns`, `hig-platforms`, `hig-project-context`, `hig-technologies` cover the remaining HIG surface area.
+Non-negotiables: 44pt touch targets, Dynamic Type support, dark mode parity, VoiceOver labels, Reduce Motion respect.
+Permission requests must be contextual with purpose strings; haptics rare and meaningful only.
+
+---
+
+## 9. Project Structure
+
+- Folder layout by **feature**, not by type (`Features/Checkout/…`, not `Views/`, `Models/`).
+- **One primary type per Swift file.** Don't jam multiple structs/classes/enums into one file.
+- Follow strict, Apple-style naming for types, properties, methods, and SwiftData models.
+- Unit tests for core logic. UI tests only when unit tests aren't possible.
+- Documentation comments on public API.
+- **Never commit secrets.** API keys go in `.xcconfig` (gitignored) or the keychain.
+- **Localization:** if the project uses `Localizable.xcstrings`, add user-facing strings as **symbol keys** (e.g. `helloWorld`) with `extractionState: "manual"`, accessed via generated symbols: `Text(.helloWorld)`. Offer to translate new keys into all supported languages.
+- **PrivacyInfo.xcprivacy ownership:** the `ios-info-plist-hardening` skill (Phase 4 Step 4.0 Scaffold) owns creating `PrivacyInfo.xcprivacy` — NOT Phase 7 Ship. Any required-reason API declarations, tracking domains, and collected-data-type entries must land in Phase 4 alongside Info.plist hardening.
+
+---
+
+## 10. Tool Preferences (MCP-first)
+
+When MCP servers are available, **always prefer them** over generic file or shell tools. Rough hierarchy:
+
+1. **XcodeBuildMCP / xcode-tools MCP** — project operations, builds, previews, issue navigator, simulators.
+2. **apple-docs-mcp / `DocumentationSearch`** — verify API availability, signatures, and version gating **before** writing code. Always check when you touch `Liquid Glass` or `FoundationModels`.
+3. **File-level MCP tools** (`XcodeRead`, `XcodeWrite`, `XcodeUpdate`) for files inside the Xcode project.
+4. **Generic Read/Write/Edit** only when no MCP equivalent exists.
+5. **Shell / CLI last resort.** Never use `ls` / `find` to explore when an MCP tool can answer. Use dedicated search tools (Glob, Grep) over shell equivalents.
+
+**Validation loop (preferred order):**
+`BuildProject` → `XcodeRefreshCodeIssuesInFile` (fast live diagnostics) → `ExecuteSnippet` (REPL-style check) → `RenderPreview` for visual verification.
+
+**Never hand-edit `.xcodeproj` / `.pbxproj`.** Use MCP tools or `xcodeproj` helpers. Corrupting the project file wastes a full debug loop.
+
+**apple-docs-mcp fallback rule:** If `apple-docs-mcp` is unreachable, fall back to `WebFetch` of `developer.apple.com/documentation/<framework>`. If `WebFetch` also fails, HALT and mark the task blocked — do NOT hallucinate API signatures for iOS 26 frameworks (Liquid Glass, FoundationModels, Visual Intelligence, AlarmKit, etc.).
+
+---
+
+## 11. PR Hygiene
+
+- If SwiftLint is installed, it must return **zero warnings and zero errors** before you commit.
+- Run a clean `BuildProject` before declaring work done.
+- Run unit tests (Swift Testing `@Test` / `#expect` preferred over XCTest for new tests).
+- Complete-file replacement when writing code via MCP tools — do not ship partial edits that rely on surrounding context the tool can't see.
+- Commit messages: conventional commits (`feat:`, `fix:`, `refactor:`…), imperative mood, explain the _why_ in the body.
+
+---
+
+## iOS Feature Flag Schema
+
+These flags gate Phase 4 per-task skill loading and Phase 4 Step 4.0 entitlement generation. Orchestrator resolves them at the end of Phase 2 (see `commands/build.md` → Phase 2 "Feature Flag Resolution") and persists them to `docs/plans/.build-state.md` under an `ios_features:` key.
+
+```yaml
+ios_features:
+  widgets: bool        # gates skills/ios/widgetkit/
+  liveActivities: bool # gates skills/ios/activitykit/
+  appIntents: bool     # gates skills/ios/app-intents/
+  foundationModels: bool  # gates ios-foundation-models-specialist
+  storekit: bool       # gates ios-storekit-specialist
+  healthkit: bool      # triggers HealthKit entitlement
+  push: bool
+  cloudkit: bool
+  siri: bool
+  location: bool
+  background: bool
+  cameraPhoto: bool
+  microphone: bool
+  contacts: bool
+  calendar: bool
+  appleWatch: bool
+```
+
+**Read contract:** Phase 4 Step 4.0 (`ios-entitlements-generator`) and Phase 4 per-task flow (skill loader) MUST read this block from `.build-state.md` before acting. A skill gated by flag `X` is loaded only when `ios_features.X == true`. Unset flags default to `false`.
+
+---
+
+## Phase Skill Bundles
+
+_Per-phase skill bundle — orchestrator loads the relevant subset based on current phase._
+
+### Phase 1 — Plan
+- Primary agent: `agents/ios-swift-architect.md` (Opus, read-only planner)
+- Supporting: `agents/ios-swift-search.md` (Haiku context-isolation)
+- If AI/LLM features in prompt: `agents/ios-foundation-models-specialist.md`
+
+### Phase 2 — Architecture
+- `skills/ios/ios-26-platform/` — select iOS 26 APIs + @available strategy
+- `skills/ios/apple-on-device-ai/` — if AI planned: Foundation Models schema + @Generable design
+- MCP: apple-docs-mcp
+
+### Phase 3 — Design
+- `agents/ios-swift-ui-design.md` — visual intake (mockups → SwiftUI plan)
+- `skills/ios/hig-foundations/` + granular `hig-*` skills — HIG compliance (see agent shortlists for per-agent selection)
+- `skills/ios/swiftui-design-principles/` — 10-rule visual polish
+- `skills/ios/swiftui-liquid-glass/` — iOS 26 glass decision tree
+
+### Phase 4 — Build (Step 4.0 Scaffold)
+- `skills/ios/ios-entitlements-generator/` (stub)
+- `skills/ios/ios-info-plist-hardening/` (stub)
+
+### Phase 4 — Build (Step 4.1+ per-task flow)
+- `skills/ios/swiftui-pro/` (every UI write)
+- `skills/ios/swift-concurrency-6-2/` (async/actor/Sendable — Swift 6.2 single-threaded default)
+- `skills/ios/swiftdata-pro/` (@Model/@Query usage)
+- `skills/ios/swift-accessibility/` (every UI write — a11y first-draft)
+- `skills/ios/swift-security-expert/` (Keychain/Crypto/auth)
+- Feature-flag-gated: `skills/ios/widgetkit/`, `skills/ios/activitykit/`, `skills/ios/app-intents/`
+- AI feature: `agents/ios-foundation-models-specialist.md`
+- IAP feature: `agents/ios-storekit-specialist.md`
+
+### Phase 5 — Audit
+_Dispatches to `/verify` + `/ux-review` + `/fix` iOS twins in sequence. Each twin has its own skill bundle inline in its command file._
+
+### Phase 7 — Ship (optional)
+- `asc-*` pack (TBD — not yet ported; 15 of 22 per _COMPARISON.md)
+- `app-store-aso` (TBD)
+- `app-store-changelog` (TBD)
+- `agents/ios-app-review-guardian.md`

package/protocols/ios-frameworks-map.md

@@ -0,0 +1,323 @@
+# iOS Frameworks Capability Map
+
+_**Reference file** — agents READ this on demand when hitting a "user wants X → which Apple framework?" question. **NOT injected into agent prompts** (323 lines would waste ~400k tokens across a build). The orchestrator cites this file by path; agents open it, grep for their capability, extract the 1-2 relevant rows. Authoritative source for framework selection. When in doubt, consult apple-docs-mcp to confirm current API status._
+
+## Purpose
+
+This is a **framework-selection index**, not a best-practices guide. It answers: "the user described capability X, which Apple framework should I import?" The rule is: **prefer Apple's native framework over custom code or third-party libraries whenever one exists.**
+
+---
+
+## 1. Capability Index (user intent → framework)
+
+### Health & Fitness
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| Log workouts, steps, heart rate, sleep | HealthKit | `com.apple.developer.healthkit` | — |
+| Start/control workout sessions, build workout plans | WorkoutKit (iOS 17+) | HealthKit | — |
+| Pull clinical records (labs, allergies, meds) | HealthKit ClinicalHealth | `health-records` | — |
+| Mindful minutes / state of mind | HealthKit (iOS 17+) | HealthKit | — |
+
+### Calendar & Reminders
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| Create/read calendar events | EventKit | `NSCalendarsFullAccessUsageDescription` | Deprecated: `NSCalendarsUsageDescription` (iOS 17+ splits read/write) |
+| Pre-built event editor UI | EventKitUI | Calendar | — |
+| Create/read reminders | EventKit | `NSRemindersFullAccessUsageDescription` | — |
+
+### Photos & Media
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| Pick photos/videos from library | PhotosUI (`PhotosPicker`) | — (no permission prompt needed for picker) | Deprecated: `UIImagePickerController` |
+| Full library access, albums, assets | PhotoKit | `NSPhotoLibraryUsageDescription` | — |
+| Camera capture, audio/video record | AVFoundation | `NSCameraUsageDescription`, `NSMicrophoneUsageDescription` | — |
+| Play video with controls | AVKit (`VideoPlayer`) | — | Deprecated: `MPMoviePlayerController` |
+| Play user's music, now-playing info | MediaPlayer | `NSAppleMusicUsageDescription` | — |
+| Apple Music catalog, playback | MusicKit | MusicKit capability | — |
+| Song ID (Shazam) | ShazamKit | Microphone | — |
+| Classify sounds on-device | SoundAnalysis | Microphone | — |
+| Speech-to-text | Speech | `NSSpeechRecognitionUsageDescription` | — |
+| View/annotate/render PDF | PDFKit | — | — |
+| Preview documents inline | QuickLook | — | — |
+| Thumbnails for any file type | QuickLookThumbnailing | — | — |
+| Image filters, Core Image | CoreImage | — | — |
+| Low-level audio engine/effects | AVAudioEngine | — | Prefer over `AudioToolbox` for new code |
+
+### Maps & Location
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| Show a map, annotations, overlays | MapKit (SwiftUI `Map` iOS 17+) | — | Deprecated for SwiftUI: `MKMapView` wrapper |
+| User location / geofencing | CoreLocation | `NSLocationWhenInUseUsageDescription`, `NSLocationAlwaysAndWhenInUseUsageDescription` | — |
+| Weather forecast / historical | WeatherKit | WeatherKit capability | — |
+| Directions, search, POI, lookAround | MapKit | — | — |
+
+### Identity & Auth
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| Sign in with Apple, passkeys, OAuth web flow | AuthenticationServices | `com.apple.developer.applesignin` | Deprecated: custom `WKWebView` OAuth |
+| Face ID / Touch ID / passcode | LocalAuthentication | `NSFaceIDUsageDescription` | — |
+| Keychain storage | Security | — | Avoid: `UserDefaults` for secrets |
+| Crypto primitives (AES, ChaCha, SHA, EC) | CryptoKit | — | Deprecated: `CommonCrypto` in new Swift code |
+
+### Payments & Commerce
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| In-app purchases, subscriptions | StoreKit 2 | In-App Purchase capability | Deprecated: StoreKit 1 (`SKPayment*`) |
+| Apple Pay, Wallet passes | PassKit | `com.apple.developer.in-app-payments`, merchant IDs | — |
+
+### Communication & Notifications
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| Local + remote push notifications | UserNotifications | `aps-environment` (remote) | Deprecated: `UILocalNotification`, `UIUserNotification*` |
+| VoIP push | PushKit + CallKit | VoIP capability | — |
+| System call UI, CallKit directory | CallKit | — | — |
+| iMessage app extensions, stickers | Messages | — | — |
+| Peer-to-peer device networking | MultipeerConnectivity | Local network | — |
+| Bonjour / local network discovery | Network | `NSLocalNetworkUsageDescription` | Deprecated: `NetService` |
+| Email / SMS compose sheets | MessageUI | — | — |
+
+### AR / Vision / ML
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| World-tracking AR, plane detection | ARKit | Camera | — |
+| 3D rendering for AR | RealityKit | Camera | Deprecated in AR: `SceneKit+ARKit` combo |
+| Room scanning (LiDAR) | RoomPlan | Camera | — |
+| Text recognition, face/body detect, barcode | Vision | — | — |
+| Document scanner, data-scanner UI | VisionKit | Camera | — |
+| Run custom ML models | CoreML | — | — |
+| Train models on-device | CreateML | — | — |
+| On-device LLM (text gen, summarize) | **FoundationModels (iOS 26+)** | — | iOS 26 only; check availability |
+| Visual Intelligence interactions | **Visual Intelligence (iOS 26+)** | — | iOS 26 only |
+| Natural-language tokenization, tagging | NaturalLanguage | — | — |
+| Live Text / Data scanner | VisionKit `DataScannerViewController` | Camera | — |
+
+### Contacts & People
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| Read/write contacts | Contacts | `NSContactsUsageDescription` | Deprecated: `AddressBook` |
+| Contact picker UI | ContactsUI | Contacts (picker-only: not required) | — |
+
+### System & Device
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| Background fetch, background processing | BackgroundTasks | `BGTaskSchedulerPermittedIdentifiers` | Deprecated: `performFetchWithCompletionHandler` |
+| Background asset download at install | BackgroundAssets | Background Assets capability | — |
+| VPN / content filter / packet tunnel | NetworkExtension | NetworkExtension capability | — |
+| Device attestation / anti-abuse | DeviceCheck / AppAttest | — | — |
+| IDFA / tracking consent | AppTrackingTransparency | `NSUserTrackingUsageDescription` | — |
+| File Provider extension (cloud drive) | FileProvider | File Provider capability | — |
+| Share sheet / activity items | UIKit `UIActivityViewController` (SwiftUI `ShareLink`) | — | Prefer SwiftUI `ShareLink` |
+| Drag & drop, pasteboard | UniformTypeIdentifiers + SwiftUI `Transferable` | — | Deprecated: `kUTType*` constants |
+
+### Home & IoT
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| HomeKit accessories | HomeKit | `NSHomeKitUsageDescription` | — |
+| Matter accessory pairing | MatterSupport | Matter capability | — |
+| BLE peripherals & centrals | CoreBluetooth | `NSBluetoothAlwaysUsageDescription` | — |
+| Ultra-wideband ranging | NearbyInteraction | — | — |
+| Car key | CarKey | CarKey entitlement | — |
+| CarPlay apps / audio / nav | CarPlay | CarPlay entitlement (Apple approval) | — |
+
+### Wearables & Companions
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| iPhone ↔ Apple Watch messaging | WatchConnectivity | — | — |
+| Watch workouts | WorkoutKit + HealthKit | HealthKit | — |
+
+### Intents, Widgets & Automation
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| Siri / Shortcuts / App Intents | AppIntents | — | Deprecated: `SiriKit` custom intents (keep only for domains AppIntents doesn't cover) |
+| Home/Lock-Screen widgets | WidgetKit | App Groups (usually) | — |
+| Live Activities / Dynamic Island | ActivityKit | `NSSupportsLiveActivities` Info.plist | — |
+| Control Center widgets (iOS 18+) | WidgetKit `ControlWidget` | — | — |
+| System-style alarms (iOS 26+) | **AlarmKit** | — | iOS 26 only |
+
+### Web & Content
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| In-app Safari tab (SFSafariVC) | SafariServices | — | — |
+| Full web view / JS bridge | WebKit | — | Deprecated: `UIWebView` |
+| SwiftUI-native web view (iOS 26+) | SwiftUI `WebView` | — | iOS 26 only |
+| Rich URL preview cards | LinkPresentation | — | — |
+
+### Graphics & Games
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| 2D game engine | SpriteKit | — | — |
+| 3D scene graph | SceneKit | — | (Maintenance mode; prefer RealityKit for new 3D) |
+| GPU rendering | MetalKit / Metal | — | Deprecated: OpenGL ES |
+| 3D model I/O (USDZ) | ModelIO | — | — |
+| Game Center, leaderboards, matches | GameKit | Game Center capability | — |
+| Controller input | GameController | — | — |
+
+### Accessibility & Input
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| VoiceOver/Switch Control labels | Accessibility (SwiftUI modifiers) | — | — |
+| Dictation / speech recognition | Speech | Speech recognition | — |
+| Hand/pencil input | PencilKit | — | — |
+
+### Persistence
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| Model persistence (new projects) | SwiftData | — | — |
+| Model persistence (legacy) | CoreData | — | Prefer SwiftData for new work |
+| Tiny prefs (≤ a few KB) | Foundation `UserDefaults` | — | Do not use for secrets or large blobs |
+| iCloud key-value | Foundation `NSUbiquitousKeyValueStore` | iCloud Key-Value | — |
+| iCloud Drive documents | CloudKit + UIDocument | iCloud (CloudKit) | — |
+| CloudKit sync | CloudKit | iCloud (CloudKit) | — |
+
+---
+
+## 2. Selection Rules (multi-choice disambiguation)
+
+When multiple frameworks can solve a problem, pick the most modern:
+
+- **Photos:** PhotosUI `PhotosPicker` (iOS 16+) > PhotoKit `PHPickerViewController` (iOS 14+) > `UIImagePickerController` (deprecated).
+- **Auth:** AuthenticationServices (Sign in with Apple, passkeys, OAuth) > manual `WKWebView` OAuth flows.
+- **Audio:** `AVAudioEngine` (modern graph) > `AVAudioPlayer` (simple file playback) > `AudioToolbox` (low-level CoreAudio).
+- **Notifications:** UserNotifications (local + remote, iOS 10+) > legacy `UIUserNotification*` (removed).
+- **Maps:** SwiftUI `Map` (iOS 17+) > `MKMapView` via `UIViewRepresentable`.
+- **On-device AI:** FoundationModels (iOS 26+, text) > CoreML (custom models) > MLX (low-level experimental).
+- **Persistence:** SwiftData > Core Data (legacy only) > `UserDefaults` (tiny prefs only).
+- **3D:** RealityKit (AR + general 3D) > SceneKit (maintenance mode).
+- **Web view:** SwiftUI `WebView` (iOS 26+) > `WKWebView` via `UIViewRepresentable` > `SFSafariViewController` (if you just need a browser tab).
+- **Background work:** BackgroundTasks (`BGAppRefreshTask`, `BGProcessingTask`) > deprecated background-fetch.
+- **Networking:** `URLSession` + async/await > `Network` framework (sockets, Bonjour) > third-party HTTP clients.
+- **JSON:** `Codable` > `JSONSerialization`.
+- **Share:** SwiftUI `ShareLink` > `UIActivityViewController` wrapper.
+- **Crypto:** CryptoKit > `CommonCrypto`.
+
+---
+
+## 3. Framework Combinations (common pairings)
+
+- **Push notifications** = UserNotifications + APNs + `aps-environment` entitlement.
+- **VoIP** = CallKit + PushKit + VoIP background mode + CallKit entitlement.
+- **Sign in with Apple** = AuthenticationServices + "Sign in with Apple" capability.
+- **Widgets** = WidgetKit + App Groups + shared SwiftData container.
+- **Live Activities** = ActivityKit + UserNotifications push + `NSSupportsLiveActivities` in Info.plist.
+- **App Intents in widgets** = AppIntents + WidgetKit + shared target membership.
+- **HealthKit workouts** = HealthKit + WorkoutKit + HealthKit entitlement + `NSHealthShareUsageDescription` + `NSHealthUpdateUsageDescription`.
+- **ARKit 3D scene** = ARKit + RealityKit + `NSCameraUsageDescription`.
+- **Document scanning** = VisionKit `VNDocumentCameraViewController` + `NSCameraUsageDescription`.
+- **Barcode / text scanner** = VisionKit `DataScannerViewController` + Camera.
+- **Passkeys** = AuthenticationServices + Associated Domains (`webcredentials:`).
+- **Universal Links** = Associated Domains (`applinks:`) + `onOpenURL` / `NSUserActivity`.
+- **CloudKit-synced SwiftData** = SwiftData + iCloud (CloudKit) capability + follow CloudKit-compatible model rules (no `.unique`, all relationships optional).
+- **Matter pairing** = MatterSupport + HomeKit + Matter entitlement.
+- **Apple Pay** = PassKit + Merchant ID + in-app-payments entitlement.
+
+---
+
+## 4. Entitlement Mapping (feeds ios-entitlements-generator)
+
+| Framework | Entitlement key | Info.plist keys | Setup notes |
+|---|---|---|---|
+| HealthKit | `com.apple.developer.healthkit` | `NSHealthShareUsageDescription`, `NSHealthUpdateUsageDescription` | Add access types to entitlement plist |
+| HomeKit | — | `NSHomeKitUsageDescription` | HomeKit capability on target |
+| EventKit | — | `NSCalendarsFullAccessUsageDescription`, `NSRemindersFullAccessUsageDescription` | iOS 17+ split access model |
+| Contacts | — | `NSContactsUsageDescription` | — |
+| Photos | — | `NSPhotoLibraryUsageDescription`, `NSPhotoLibraryAddUsageDescription` | Not needed for `PhotosPicker` |
+| Camera | — | `NSCameraUsageDescription` | AVFoundation, Vision, ARKit, VisionKit |
+| Microphone | — | `NSMicrophoneUsageDescription` | AVFoundation, Speech, ShazamKit |
+| Speech | — | `NSSpeechRecognitionUsageDescription` | — |
+| Face ID | — | `NSFaceIDUsageDescription` | LocalAuthentication |
+| CoreLocation | — | `NSLocationWhenInUseUsageDescription`, `NSLocationAlwaysAndWhenInUseUsageDescription`, `NSLocationTemporaryUsageDescriptionDictionary` | — |
+| Bluetooth | — | `NSBluetoothAlwaysUsageDescription` | — |
+| Local Network | — | `NSLocalNetworkUsageDescription`, `NSBonjourServices` | Multipeer, Bonjour |
+| Music | — | `NSAppleMusicUsageDescription` | MediaPlayer, MusicKit |
+| Tracking (IDFA) | — | `NSUserTrackingUsageDescription` | AppTrackingTransparency |
+| Sign in with Apple | `com.apple.developer.applesignin` | — | — |
+| Push (remote) | `aps-environment` | — | `development` / `production` |
+| Associated Domains | `com.apple.developer.associated-domains` | — | `applinks:`, `webcredentials:`, `activitycontinuation:` |
+| App Groups | `com.apple.security.application-groups` | — | Share data with widgets/extensions |
+| iCloud (CloudKit) | `com.apple.developer.icloud-services`, `com.apple.developer.icloud-container-identifiers` | — | CloudKit + iCloud Drive |
+| Keychain Sharing | `keychain-access-groups` | — | Share keychain items across apps |
+| In-App Purchase | `com.apple.developer.in-app-payments` (Apple Pay) | — | IAP capability on target for StoreKit |
+| HealthKit Clinical | `com.apple.developer.healthkit.access` | — | Array of clinical record types |
+| WeatherKit | `com.apple.developer.weatherkit` | — | Register service in developer portal |
+| MusicKit | `com.apple.developer.musickit` | — | — |
+| CarPlay | `com.apple.developer.carplay-*` | — | Requires Apple entitlement approval |
+| CarKey | `com.apple.developer.car-key` | — | — |
+| NetworkExtension | `com.apple.developer.networking.networkextension` | — | Packet tunnel, content filter, DNS proxy |
+| BackgroundAssets | `com.apple.developer.background-assets` | — | — |
+| Matter | `com.apple.developer.matter.allow-setup-payload` | — | — |
+| DriverKit / USB / HID | various | — | Specialized — usually not needed in consumer apps |
+| Live Activities | — | `NSSupportsLiveActivities`, `NSSupportsLiveActivitiesFrequentUpdates` | Info.plist only |
+| Background modes | `com.apple.developer.background-modes` (via Xcode UI) | — | audio, location, voip, fetch, processing, remote-notification |
+
+---
+
+## 5. Deprecation Flags (avoid in new code)
+
+- `UIImagePickerController` → use PhotosUI `PhotosPicker`.
+- `UIUserNotification*` / `UILocalNotification` → use UserNotifications.
+- Core Data in new projects → use SwiftData.
+- `UIAlertView` / `UIActionSheet` → use SwiftUI `alert` / `confirmationDialog` (or `UIAlertController` in UIKit).
+- `MKMapView` wrapped in SwiftUI → use SwiftUI `Map` (iOS 17+).
+- `ObservableObject` / `@Published` / `@StateObject` → use `@Observable` macro.
+- `DispatchQueue.main.async` for UI → use `@MainActor` + async/await.
+- `Timer` / GCD timers → use async `Task.sleep` / `AsyncTimerSequence`.
+- `DateFormatter` / `NumberFormatter` → use `FormatStyle` (`.formatted(...)`).
+- `replacingOccurrences(of:with:)` → `.replacing("a", with: "b")`.
+- `foregroundColor` → `foregroundStyle`.
+- `cornerRadius` → `clipShape(.rect(cornerRadius:))`.
+- `NavigationView` → `NavigationStack`.
+- `tabItem` on TabView → new `Tab` API (iOS 18+).
+- `UIWebView` → `WKWebView` (or SwiftUI `WebView` iOS 26+).
+- `AddressBook` → Contacts.
+- `CommonCrypto` in Swift → CryptoKit.
+- `SKPayment*` (StoreKit 1) → StoreKit 2.
+- `kUTType*` → UniformTypeIdentifiers `UTType`.
+- `NetService` → Network framework.
+- `UIScreen.main.bounds` for layout → SwiftUI geometry APIs.
+- `performFetchWithCompletionHandler` → BackgroundTasks.
+- SiriKit custom intents → AppIntents (keep SiriKit only for domains AppIntents doesn't cover: messaging, payments, ride-booking, car-commands).
+- OpenGL ES → Metal.
+
+---
+
+## 6. The Reach-for-the-Kit Rule (enforcement)
+
+When the user describes a capability that an Apple framework already solves, you **MUST** use the Apple framework. Custom implementations of these are anti-patterns:
+
+- Rolling your own photo picker instead of `PhotosPicker`.
+- Rolling your own calendar event storage instead of EventKit.
+- Rolling your own notification scheduler instead of UserNotifications.
+- Rolling your own keychain wrapper instead of the Security framework.
+- Rolling your own biometric auth instead of LocalAuthentication.
+- Rolling your own OAuth / sign-in flow instead of AuthenticationServices.
+- Rolling your own map tiles instead of MapKit.
+- Scraping weather APIs instead of WeatherKit.
+- Rolling your own workout tracker instead of HealthKit + WorkoutKit.
+- Rolling your own barcode scanner instead of Vision / VisionKit.
+- Rolling your own PDF renderer instead of PDFKit.
+- Rolling your own share sheet instead of `ShareLink` / `UIActivityViewController`.
+- Rolling your own crypto primitives instead of CryptoKit.
+- Rolling your own in-app purchase layer instead of StoreKit 2.
+
+If unsure whether a framework covers a use case, query `apple-docs-mcp` **before** writing custom code.
+
+---
+
+_See also: `ios-context.md` (Senior iOS Engineer persona + §2 Core Stack rules)._