> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swiftaiboilerplate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog

> Version history and notable changes

All notable changes to SwiftAI Boilerplate Pro.

<Info>
  **Complete changelog:** [CHANGELOG.md](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/CHANGELOG.md) in the repo
</Info>

## Latest Version

### v2.2.0 - App Store 4.3 Hardening & Swift 6 Substrate - 2026-06-15

**Summary:** Ships a first-party App Store Guideline 4.3(a) playbook (audit gate + checklist + rebrand helper), a machine-readable `template.manifest.json` single source of truth, hero archetype recipes for differentiating apps, a new `TestSupport` package with a unified workspace test plan (\~598 tests in one run), a localized error surface (en + es), single-source app identity, and a production-hardening pass. Same toolchain floor as v2.0: **Xcode 26.2+** (iOS 26 SDK), iOS 17+ runtime.

<CardGroup cols={2}>
  <Card title="App Store 4.3(a) playbook" icon="shield-check">
    * `scripts/appstore-43-audit.sh` — Release-binary `strings` audit gate; fails on un-rebranded production fingerprints
    * `docs/checklists/APP_STORE_4_3_HARDENING.md` — binary audit, branding map, metadata, Review Notes, module removal
    * `docs/prompts/AppStore4_3Hardening.prompts.md` — prompt packs incl. the must-run starter-fingerprint clearing prompt (`SwiftAI`, `Boilerplate`, `DesignSystem/SAI`)
    * `scripts/rebrand-design-system-prefix.sh` — swaps the `SAI` design-system prefix
  </Card>

  <Card title="template.manifest.json" icon="file-code">
    * Repo-root machine-readable single source of truth
    * Identity surface, module graph (removable packages + couplings), config schema, canonical fingerprint list
    * Differentiation rules, recipes, verification commands
    * Consumed by the audit script + CI; validated by `scripts/validate-template-manifest.sh`
  </Card>

  <Card title="Hero archetype recipes" icon="layout-template">
    * `docs/recipes/hero/`: DashboardGrid, FeedTimeline, MapCanvas, GuidedTaskFlow, ConversationalHome
    * Plus onboarding / paywall / feature recipes (`docs/recipes/onboarding|paywall|features/`)
    * 4.3 differentiation enforced by mandatory archetype selection, not randomness
  </Card>

  <Card title="TestSupport + single test plan" icon="flask">
    * New `TestSupport` package — unified lock-protected `URLProtocolStub`
    * `Boilerplate.xctestplan` rebuilt; scheme now references it
    * \~598 tests across 12 package test targets + the app test suites (one `xcodebuild test` run)
  </Card>

  <Card title="Localized error surface" icon="globe">
    * `AppError.localizedUserMessage` (en + es) in the Localization package
    * Localization now linked by the app target, FeatureSettings, and FeatureChat
    * All UI error call sites migrated
  </Card>

  <Card title="Single-source app identity" icon="fingerprint">
    * Every target's bundle ID + app-group entitlements derive from one `APP_BUNDLE_ID` in `Config/App.xcconfig`
    * Stale upstream fingerprints purged from project metadata
  </Card>
</CardGroup>

**Production hardening:**

* **No `https://api.example.com` fallback.** Production app-linked code fails through an explicit unconfigured-backend HTTP client path instead of a silent placeholder.
* **DEBUG-only mock auth.** `MockAuthClient` and its literals (`Debug User`, `debug-token`) are kept out of Release binaries.
* **Configurable legal URLs.** Legal views point at configured HTTPS legal URLs; `[DATE]` / `[CONTACT EMAIL]` placeholder bodies and generic legal markdown are excluded from the Release bundle.
* **Account deletion.** `AccountDeletionClient` plumbing plus a `supabase/functions/delete-account/` Edge Function template for authenticated deletion.
* **Bundle packaging fix.** The app target no longer copies local `Packages/` source directories or `Boilerplate.xctestplan` into the `.app` bundle as resources.

**Coupling gotcha:** `LLMClient` / `LLMMessage` live in **FeatureChat**, and the **AI** package re-exports FeatureChat. Removing chat without moving those types breaks `Packages/AI` — the 4.3 module-removal notes cover the safe path.

**Toolchain (unchanged from v2.0):** build with **Xcode 26.2+** (iOS 26 SDK / Liquid Glass symbols); `.xcode-version` pins `26.3`. Runtime supports iOS 17+ via the SwiftUI `Material` fallback. Stuck on older Xcode? Stay on [`v1.9.0`](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v1.9.0).

<Note>
  The macOS **App Generator** — which drives your own coding-agent CLI (Claude Code / Codex / Gemini / Cursor) to produce a differentiated, 4.3-safe app from this template — is now a **separate product with its own repository and license**. It is **not** bundled in the boilerplate and ships no LLM; the manifest, hero recipes, and single-source identity here are the template-side foundation it builds on. It is **coming soon**. See the [license & pricing](/pages/reference/license) page for the pricing model and grandfathered-buyer benefits.
</Note>

[View Release Notes](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v2.2.0)

***

## Previous Versions

### v2.0.0 - Swift 6 & iOS 26 Liquid Glass - 2026-04-12

**Summary:** Major release. The toolchain floor moves to Xcode 26.2+, the entire codebase builds under Swift 6 strict concurrency, and the DesignSystem ships a Liquid Glass primitive that uses the iOS 26 `Glass` material with an automatic SwiftUI `Material` fallback on iOS 17–25. Every file over 400 lines was split into extension siblings, public APIs intact.

<CardGroup cols={2}>
  <Card title="iOS 26 Liquid Glass" icon="gem">
    * New `SAIGlass` primitive in DesignSystem
    * `SAIGlassStyle` (`.regular` / `.clear`), `.saiGlass(...)` modifier
    * `SAIGlassContainer` merges adjacent glass surfaces
    * `saiScrollEdgeGlass`, `saiSidebarAdaptable`, `saiTabBarMinimize`
    * Progressive: iOS 26 uses `Glass`, iOS 17–25 falls back to Material
  </Card>

  <Card title="Swift 6 Strict Concurrency" icon="shield-check">
    * `@MainActor`-pinned storage repositories
    * `@Observable` throughout (no `ObservableObject`, no `.onReceive`)
    * Explicit `any` on every protocol-typed property
    * Zero `DispatchQueue.main` in app code
    * Full build under strict concurrency checking
  </Card>

  <Card title="≤ 400-line file rule" icon="scissors">
    * `SessionManager` → `+SignIn`, `+Refresh`, `+Persistence`
    * `L10n.swift` → `L10n+<Namespace>.swift` per enum
    * `SettingsView` → ≤ 125-line root + `Views/Settings/*`
    * `ChatViewModel` → `ChatViewModel+Memory.swift`
    * Public API unchanged; no downstream breakage from the split
  </Card>

  <Card title="Backend + tooling" icon="wrench">
    * New Supabase migration: `20260408000000_fix_conversation_stats_auth`
    * `ai` edge function updated and ready to redeploy
    * Secrets pre-commit hook in `.githooks/`
    * `.xcode-version` pinned to `26.3`
  </Card>
</CardGroup>

**Breaking-ish changes (most have zero call-site impact):**

* **Xcode 26.2+ required.** v2.0 uses iOS 26 SDK symbols; older toolchains cannot compile, even behind `#available`. Stay on [`v1.9.0`](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v1.9.0) until you can upgrade.
* **Storage repositories are now `@MainActor`.** If downstream code built `MessageRepositoryImpl`, `ConversationRepositoryImpl`, or `SettingsRepositoryImpl` from a non-main actor, add an `await`.
* **`DeepLinkBus` and `ToastCenter` are `@Observable`.** Migrate any `.onReceive($center.currentToast)` to `.onChange(of: center.currentToast)`.
* **Paywall CTAs use standard `.borderedProminent` / `.bordered`.** If you themed them via `.background()`, switch to `.tint()` so Liquid Glass renders correctly.
* **Stop fighting glass.** Remove `.background(DSColors.background)` on SwiftUI containers and `DSColors.background.ignoresSafeArea()` under sheets.

**Upgrade path:** follow [Upgrading from v1.9 to v2.0](/pages/migration/v1-9-to-v2-0). It covers toolchain install, Supabase migration, edge function redeploy, hook setup, downstream customisation reapply, glass cleanup, and paywall theming.

[View Release Notes](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v2.0.0) | [Migration Guide](/pages/migration/v1-9-to-v2-0)

***

### v1.9.0 - Agent-Optimized Documentation - 2026-03-06

**Summary:** Every package in the boilerplate now has its own README and PROMPTS.md, and CLAUDE.md is environment-aware. Agents get different build instructions depending on whether they run through Xcode MCP or Claude Code in the terminal.

<CardGroup cols={2}>
  <Card title="Environment-Aware CLAUDE.md" icon="robot">
    * Detects Xcode MCP vs Claude Code CLI automatically
    * Different build instructions per environment
    * File organization patterns and naming conventions
    * Supabase, RevenueCat, OpenRouter integration specifics
    * Expanded anti-patterns (no UIKit, no ObservableObject, no raw URLSession)
  </Card>

  <Card title="Per-Module Documentation" icon="book">
    * READMEs for all 11 packages (3 were missing)
    * PROMPTS.md in every package with 2-4 example prompts
    * Prompts reference actual types, protocols, and patterns
    * DesignSystem, FeatureRating, FeatureSettings now documented
  </Card>
</CardGroup>

**Bugfix:** EchoLLMClient now activates correctly in debug mode. The guard previously checked for "YOUR" in `PROXY_BASE_URL`, but the default placeholder value contains "placeholder" instead. Fixed in both `createLLMClient()` and the `proxyBaseURL` property.

**All tests pass.**

**Upgrade Notes:** Pull the latest and your coding agent will automatically pick up the improved context. No code changes required.

***

### v1.8.0 - Agentic Development - 2026-03-01

**Summary:** CLAUDE.md rewritten for agentic development with Claude Code. New distribution email infrastructure for notifying buyers about updates. Package count corrected to 11 across all files.

<CardGroup cols={2}>
  <Card title="Agentic Development" icon="wand-magic-sparkles">
    * CLAUDE.md updated for Claude Code workflow
    * FeatureRating and Localization modules documented
    * New guide: Agentic Coding on iOS
    * Package count corrected to 11
  </Card>

  <Card title="Distribution Infrastructure" icon="envelope">
    * Email notification system for version updates
    * Buyer email list with manual and automated capture
    * Paddle webhook integration for new buyers
    * GitHub vs ZIP delivery routing
  </Card>
</CardGroup>

**Upgrade Notes:** Pull the latest to get the updated CLAUDE.md. No code changes required.

***

### v1.7.0 - Smart App Rating Prompts - 2026-02-10

**Summary:** New FeatureRating module for smart, sentiment-based app rating prompts. Track positive and negative user actions, automatically show a beautiful pre-prompt popup at the right moment, and trigger the native App Store review dialog when users are happiest. Includes a `stopAskingAfterRating` flag that permanently stops prompting once a user taps "Rate on App Store".

<CardGroup cols={2}>
  <Card title="⭐ Smart Rating Engine" icon="star">
    * Sentiment-based scoring with configurable weights
    * Time-based decay for inactive users
    * Cooldowns (30-day default) and yearly limits (3/year)
    * `stopAskingAfterRating` flag (default: true)
    * 25+ unit tests with MockRatingStorage
  </Card>

  <Card title="🎨 Pre-Prompt Popup" icon="window-maximize">
    * Beautiful themed popup before native dialog
    * Fully customizable text, icon, and styling
    * Works across all 5 themes
    * Dark mode and VoiceOver support
    * One-line `.ratingPrompt()` modifier
  </Card>
</CardGroup>

**Quick Integration:**

```swift theme={null}
import FeatureRating

// Record positive actions at key moments
ratingClient.record(.positive("task_done", weight: 2.0))
ratingClient.record(.positive("milestone_reached", weight: 3.0))

// Pre-defined templates
ratingClient.record(.taskCompleted)
ratingClient.record(.purchaseCompleted)

// The system handles the rest: pre-prompt popup + native review dialog
```

**Upgrade Notes:** This feature is optional. Existing code works without changes. The package is already included; customize `RatingConfig` in `CompositionRoot.swift` and add `.record()` calls at key moments.

## [View Release Notes](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v1.7.0)

### v1.6.0 - Localization & Accessibility Modules - 2026-01-04

**Summary:** New Localization module and comprehensive Accessibility features. Type-safe localization with `L10n` enum and full accessibility support with `A11y` labels and modifiers for building inclusive apps.

<CardGroup cols={2}>
  <Card title="🌍 Localization Module" icon="globe">
    * New `Localization` Swift Package
    * `L10n` enum with nested namespaces
    * Built-in pluralization via `.stringsdict`
    * English & Spanish included
    * Zero configuration required
  </Card>

  <Card title="♿ Accessibility Features" icon="universal-access">
    * `A11yLabel` struct for type-safe labels
    * `A11y` enum with pre-defined labels
    * 9 new accessibility modifiers
    * `A11yAudit` debug tool
    * Dynamic Type & Reduce Motion support
  </Card>
</CardGroup>

**Localization Usage:**

```swift theme={null}
import Localization

// Type-safe, organized string access
Text(L10n.Auth.tagline)
Text(L10n.Chat.sendButton)

// Pluralization support
Text(L10n.Chat.messagesRemaining(count))
```

**Accessibility Modifiers:**

```swift theme={null}
import DesignSystem

// Apply type-safe accessibility labels
Button("Send") { }
    .saiAccessible(A11y.Chat.sendButton)

// Dynamic Type support
Text("Title")
    .saiScaledFont(.title)

// Respect Reduce Motion
.saiMotionAwareAnimation(.spring())

// High Contrast mode
.saiHighContrastSupport(normal: .secondary, highContrast: .primary)
```

**New Accessibility Modifiers:**

* `.saiAccessible(_:)` - Apply type-safe accessibility labels
* `.saiAccessibilityHidden()` - Hide decorative elements
* `.saiAccessibilityGroup()` - Combine related elements
* `.saiAccessibilityValue(_:)` - Dynamic value announcements
* `.saiAccessibilitySortPriority(_:)` - Custom reading order
* `.saiScaledFont(_:)` - Dynamic Type support
* `.saiMotionAwareAnimation(_:)` - Respect Reduce Motion
* `.saiHighContrastSupport(normal:highContrast:)` - High Contrast mode
* `.saiFocusIndicator(_:)` - Visible focus rings for Switch Control

**Upgrade Notes:** Both features are optional - existing code works without changes. Just import and use when ready.

[View Release Notes](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v1.6.0) | [Localization Guide](/pages/modules/localization) | [Accessibility Guide](/pages/modules/accessibility)

***

### v1.5.0 - OneSignal Push Notifications & Session Fix - 2025-12-20

**Summary:** Complete OneSignal push notifications integration and critical fix for session management that was logging users out unexpectedly.

<CardGroup cols={2}>
  <Card title="🔔 Push Notifications" icon="bell">
    * Complete OneSignal SDK integration
    * Rich notifications (images, buttons, badges)
    * Confirmed delivery analytics
    * Graceful degradation without config
  </Card>

  <Card title="🔴 Critical Session Fix" icon="shield-check">
    * Fixed unexpected logouts after \~1 hour
    * Proper token refresh with retry logic
    * Users stay logged in 7+ days
    * Shows refreshing state during refresh
  </Card>
</CardGroup>

**Session Management Fix:**

| Scenario                | Before (Bug) | After (Fixed)     |
| ----------------------- | ------------ | ----------------- |
| Open app after 2 hours  | ❌ Logged out | ✅ Silent refresh  |
| Open app after 3 days   | ❌ Logged out | ✅ Silent refresh  |
| Open app after 14+ days | ❌ Logged out | ✅ Graceful logout |

**Upgrade Notes:**

* Session fix is automatic - just update
* Push notifications are optional - add `ONESIGNAL_APP_ID` to `Secrets.xcconfig` if needed

[View Release Notes](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v1.5.0) | [OneSignal Setup Guide](/pages/guides/onesignal-setup)

***

### v1.4.0 - Bug Fixes & Profile/Settings Restructure - 2025-12-01

**Summary:** Profile is now the main tab with Settings as a sheet, plus critical validation fixes and enhanced RevenueCat error handling.

<CardGroup cols={2}>
  <Card title="🏗️ UI Restructure" icon="table-layout">
    * Profile is now a main tab
    * Settings accessible via gear icon
    * New 'Already Subscribed' Paywall UI
    * Better subscription status display
  </Card>

  <Card title="🐛 Critical Fixes" icon="wrench">
    * Fixed Sign In/Sign Up validation deadlock
    * Enhanced RevenueCat error handling
    * Better StoreKit error messages
    * Comprehensive purchase flow logging
  </Card>
</CardGroup>

**Sign In/Sign Up Fix:**
Users could get stuck with a disabled submit button due to validation errors that weren't cleared when editing. Now all fields properly clear errors on change.

**Payment Improvements:**

* PaywallViewModel catches `PaymentsError` explicitly
* Better messages for receipt issues, invalid purchases, config problems
* Comprehensive logging for debugging purchase issues

**New Paywall 'Already Subscribed' UI:**

* Success state showing Pro status with checkmark
* Feature list of what Pro users have access to
* `Continue` and `Manage Subscription` buttons

[View Release Notes](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v1.4.0)

***

### v1.3.0 - AI-Assisted Development Configurations - 2025-11-18

**Summary:** Comprehensive Cursor AI and Bolt AI configurations for accelerated development with consistent, high-quality code generation.

<CardGroup cols={2}>
  <Card title="Cursor AI Rules" icon="wand-magic-sparkles">
    * 4 comprehensive `.mdc` rule files
    * Automatic code quality enforcement
    * DesignSystem usage enforced
    * Protocol-based dependencies
    * MVVM architecture patterns
  </Card>

  <Card title="Bolt AI Chat Modes" icon="robot">
    * 12 specialized AI assistants
    * Context-aware development
    * Domain-specific expertise
    * From architecture to deployment
    * Instant mode switching
  </Card>
</CardGroup>

**Key Features:**

* **Cursor Rules (`.cursor/rules/`)**: Architecture enforcement, SwiftUI patterns, DesignSystem usage, modular design
* **Bolt Chat Modes (`.bolt/`)**: iOS Developer, Architecture, SwiftUI, Feature Dev, Integration, Testing, Debug, Performance, Package, Deploy, Accessibility, Documentation
* **Zero Setup**: Works automatically when you open the project
* **SEO Optimized**: Cursor AI, Bolt AI, .MDC rules, AI-assisted iOS development

**Benefits:**

* ✅ Consistent code quality across AI-generated code
* ✅ Automatic adherence to architecture patterns
* ✅ Proper DesignSystem usage (DSColors, DSFonts, DSSpacing)
* ✅ Protocol-based dependencies for testability
* ✅ Comprehensive error handling
* ✅ Swift best practices (async/await, @MainActor, Sendable)

**Example AI Prompts That Work Perfectly:**

```text theme={null}
"Create a new settings view using DesignSystem components"
"Add a profile ViewModel following MVVM pattern"
"Create a new feature package for Notifications"
"Refactor this to use repository pattern"
```

[View Release Notes](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v1.3.0) | [Read AI Development Guide](/pages/guides/ai-assisted-development)

***

### v1.2.1 - Device & Archive Build Fixes - 2025-11-18

**Summary:** Critical bug fix for device and App Store archive builds.

<Card title="Bug Fix" icon="wrench">
  Fixed build failures when building for physical devices or creating App Store archives. Preview code now properly excluded from release builds.
</Card>

**Issues Fixed:**

* **Preview Code Errors:** `#Preview` blocks now properly wrapped in `#if DEBUG`
* **Bundle Extension Error:** Moved Bundle extension outside debug block
* **Device Builds:** Can now build for physical devices
* **Archive Builds:** Can now archive for App Store submission

**Files Fixed:**

* `ChatGPTStyleView.swift` - Preview blocks wrapped
* `DualStyleChatView.swift` - Preview blocks wrapped
* `SettingsView.swift` - Bundle extension moved

[View Release Notes](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v1.2.1)

***

### v1.2.0 - Authentication & Payments Improvements - 2025-11-17

**Summary:** Enhanced authentication error handling and added RevenueCat StoreKit Configuration support for simulator testing.

<CardGroup cols={2}>
  <Card title="Authentication" icon="shield">
    * Fixed misleading error messages
    * Improved sign-out navigation
    * Better error context
    * Email confirmation support
  </Card>

  <Card title="RevenueCat" icon="credit-card">
    * StoreKit Configuration added
    * Simulator testing fixed
    * Integration checklist created
    * Comprehensive troubleshooting
  </Card>
</CardGroup>

**Key Changes:**

* **Auth Error Messages:** More specific and helpful error messages instead of generic "Network error occurred"
* **Sign-Out Fix:** Users now immediately return to auth screen when signing out
* **Simulator Testing:** Added StoreKit Configuration file with correct Xcode scheme path
* **Product ID Guidance:** Clear documentation on matching product IDs across all systems
* **Integration Checklist:** New step-by-step verification checklist for RevenueCat setup

**Files Changed:**

* Enhanced error handling in Auth package
* Added `StoreKitConfiguration.storekit` for simulator testing
* Created `REVENUECAT_INTEGRATION.md` checklist
* Updated RevenueCat documentation with new Step 11

[View Release Notes](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v1.2.0)

***

### v1.1.0 - Documentation & Testing Overhaul - 2025-10-13

**Summary:** Complete documentation restructure with a comprehensive test suite achieving 85-90% coverage.

<CardGroup cols={2}>
  <Card title="Documentation" icon="book">
    * Single-path approach
    * 60KB+ of guides
    * Example-first
    * LLM-friendly
  </Card>

  <Card title="Testing" icon="flask">
    * Comprehensive test suite added
    * 85-90% coverage
    * CI enforcement
    * Comprehensive error scenarios
  </Card>
</CardGroup>

### Added

**Core Documentation:**

* `README.md` - 10-minute Quick Start
* `docs/INDEX.md` - Central documentation hub
* `docs/foundations/Architecture.md` - System design
* `BUILDING_YOUR_APP.md` - 60KB customization guide with LLM prompts
* `docs/testing-guide.md` - Comprehensive testing guide

**Module Documentation (12 modules):**

* Core, Networking, Storage, Auth, Payments, AI
* FeatureChat, FeatureSettings, DesignSystem
* Composition, plus 3 feature-specific docs

**Migration Guides:**

* Supabase setup (auth + AI proxy)
* RevenueCat setup (subscriptions)
* Chat sync setup (22KB guide)
* Profile photo setup (12KB guide)

**Testing Infrastructure:**

* Comprehensive unit, integration, and UI test coverage across the modules
* CI/CD with coverage enforcement

### Changed

* Documentation structure: Single-path, example-first
* Quick Start reduced from 30 to 10 minutes
* All module docs follow consistent template
* Test coverage increased from \~60% to 85-90%

### Removed

* 18 legacy/duplicate documentation files
* Scattered guides consolidated
* Outdated status tracking docs

## Earlier Versions

### Initial Release - 2024

**Complete boilerplate with:**

* 9 Swift Package modules (now 11 with Localization & FeatureRating; accessibility lives in DesignSystem)
* MVVM architecture
* Dual-style chat UI
* Supabase + RevenueCat integration
* 5 built-in themes
* Comprehensive error handling
* Mock implementations
* Production-ready patterns

## Version Format

We use **semantic versioning**: `MAJOR.MINOR.PATCH`

* **MAJOR** - Incompatible API changes
* **MINOR** - New features (backward compatible)
* **PATCH** - Bug fixes (backward compatible)

## Release Notes

<AccordionGroup>
  <Accordion title="Documentation Overhaul (Oct 2025)">
    **Focus:** Developer experience

    **Key improvements:**

    * 60KB customization guide with LLM prompts
    * Comprehensive test suite with 85-90% coverage
    * CI enforcement prevents regressions
    * Single-path documentation
    * Example-first approach

    **Time saved:** 30+ hours of documentation reading time
  </Accordion>

  <Accordion title="Initial Release (2024)">
    **Focus:** Production-ready foundation

    **Key features:**

    * Complete iOS app architecture
    * AI chat with 500+ models
    * Authentication (Supabase + Apple)
    * Subscriptions (RevenueCat)
    * Design system with 5 themes
    * Testing infrastructure
    * Comprehensive documentation

    **Time saved:** 400+ hours of development
  </Accordion>
</AccordionGroup>

## Upcoming

<Note>
  The macOS **App Generator** is the next product on the roadmap — a separate, standalone tool that drives your own coding-agent CLI to produce a differentiated, App Store Guideline 4.3-safe app from this template. It is **coming soon** with its own repository and license. See the [license & pricing](/pages/reference/license) page for details and grandfathered-buyer benefits.
</Note>

## Migration Guides

When upgrading between versions:

<Steps>
  <Step title="Read Changelog">
    Check what changed in the new version.
  </Step>

  <Step title="Update Dependencies">
    In Xcode: **File → Packages → Update to Latest Package Versions**.
  </Step>

  <Step title="Run Tests">
    One pass covers the whole workspace via `Boilerplate.xctestplan`:

    ```bash theme={null}
    ./scripts/run-tests.sh
    ```
  </Step>

  <Step title="Fix Breaking Changes">
    Follow the migration notes for your version.
  </Step>
</Steps>

## View Complete Changelog

<Card title="View Complete Changelog" icon="book" href="https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/CHANGELOG.md">
  Complete version history with detailed change notes
</Card>

## Related

<CardGroup cols={2}>
  <Card title="Features" href="/pages/reference/features">
    Complete feature list
  </Card>

  <Card title="Architecture" href="/pages/architecture">
    System design
  </Card>

  <Card title="Building Guide" href="/pages/guides/building-your-app">
    Customization guide
  </Card>

  <Card title="Testing" href="/pages/guides/testing">
    Testing guide
  </Card>
</CardGroup>