> ## 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.

# Quick Start

> Go from zero to a running app in 10 minutes

<Info>
  This guide gets you running **fast**. For a full production setup with real backends, follow the step-by-step instructions in the setup guides.
</Info>

## 1. Prerequisites

Ensure you have:

* ✅ macOS 15+
* ✅ Xcode 26.2+ (iOS 26 SDK, Swift 6.0)
* ✅ 10 minutes

<Note>
  v2.2.0 ships with iOS 26 Liquid Glass. Runtime still supports iOS 17+ thanks to a Material fallback in `SAIGlass`, but the **build** requires Xcode 26.2+. Stuck on older Xcode? Pin the [`v1.9.0`](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v1.9.0) tag.
</Note>

## 2. Clone and Open

```bash theme={null}
git clone https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution.git
cd SwiftAIBoilerplatePro-Distribution
open SwiftAIBoilerplatePro.xcodeproj
```

<Note>
  Xcode will automatically resolve Swift Package dependencies. Wait \~30 seconds for this to complete.
</Note>

## 3. Run Immediately (No Configuration Needed!)

Press **⌘ + R** in Xcode - that's it!

<Tip>
  The app works immediately with placeholder configuration:

  * **MockAuthClient** - Sign in with any email/password
  * **EchoLLMClient** - AI echoes your messages back
  * All features work for exploration
  * No API keys or setup required
</Tip>

<Note>
  To use real services (Supabase, OpenRouter, RevenueCat), follow the [Production setup path](#production-setup-path) below.
</Note>

## 4. Explore the App

### What You'll See

<Steps>
  <Step title="Onboarding">
    Swipe through 3 onboarding pages → tap "Get Started"
  </Step>

  <Step title="Sign In">
    Tap "Debug Sign In" (or use any email/password in mock mode)
  </Step>

  <Step title="Home Screen">
    See feature cards, quick actions, and subscription status
  </Step>

  <Step title="Chat">
    Tap "Start Chat" → send a message → receive echo response
  </Step>
</Steps>

<Check>
  **Success!** If you can send chat messages, you have a working AI app foundation.
</Check>

## 5. Explore Features

### Try These Flows

**Chat UI Styles:**

* Tap the style switcher icon (top-right in chat)
* Switch between bubble style (WhatsApp) and centered style (ChatGPT)

**Profile:**

* Tap profile icon → edit display name
* Try uploading a photo (iOS 17+ PhotosPicker)
* Check subscription status

**Settings:**

* Open Settings tab
* Try different themes (5 included: System, Light, Dark, Aurora, Obsidian)
* Toggle preferences

**Chat Management:**

* Create multiple conversations
* Rename conversations (long press)
* Delete conversations (swipe left)
* Search conversations

## Verify Everything Works

<AccordionGroup>
  <Accordion title="✅ Authentication">
    * Sign in with any email/password (mock mode)
    * Sign out and sign back in
    * Profile persists across restarts
  </Accordion>

  <Accordion title="✅ Chat">
    * Create conversation
    * Send messages
    * Receive echo responses
    * Switch UI styles
    * Rename/delete conversations
  </Accordion>

  <Accordion title="✅ Profile">
    * Edit display name
    * Upload photo (compresses automatically)
    * View subscription status
  </Accordion>

  <Accordion title="✅ Settings">
    * Change themes (instant update)
    * Toggle preferences
    * All settings persist
  </Accordion>
</AccordionGroup>

## What's Running in Mock Mode

The app automatically detects missing backend configuration and uses mocks:

| Component    | Mock Behavior                           | Production                    |
| ------------ | --------------------------------------- | ----------------------------- |
| **Auth**     | `MockAuthClient` - any credentials work | `SupabaseAuthClient`          |
| **AI**       | `EchoLLMClient` - echoes messages       | `ProxyLLMClient` → OpenRouter |
| **Payments** | `MockPaymentsClient` - simulated states | `RevenueCatClient`            |
| **Storage**  | Local SwiftData                         | Local + optional cloud sync   |

<Info>
  Mock mode is **perfect for**:

  * Learning the codebase
  * UI development
  * Testing without API costs
  * Demo purposes
</Info>

## Next Steps

<Tabs>
  <Tab title="Customize Immediately">
    Jump straight to customization:

    **Change branding (5 minutes):**

    1. App display name: set `appDisplayName` in `Packages/DesignSystem/Sources/DesignSystem/Tokens/BrandConfig.swift` (and the target's Display Name under Xcode → General). Set the bundle ID via `APP_BUNDLE_ID` in `Config/App.xcconfig`.
    2. Colors: Edit `SwiftAIBoilerplatePro/Resources/DesignSystemColors.xcassets`
    3. Icon: Replace in `Assets.xcassets/AppIcon.appiconset`

    [Full customization guide in project →](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/BUILDING_YOUR_APP.md)
  </Tab>

  <Tab title="Understand Architecture">
    Learn how it's built:

    * [Architecture Overview](/pages/architecture)
    * [Module Documentation](/pages/modules/core)
    * [CLAUDE.md](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/CLAUDE.md) (for AI-assisted dev)
  </Tab>

  <Tab title="Setup Production Backends">
    Connect real services

    1. [Supabase Setup](/pages/guides/supabase-setup) - Auth + AI proxy
    2. [RevenueCat Setup](/pages/guides/revenuecat-setup) - Subscriptions
    3. [Crashlytics Setup](/pages/guides/crashlytics-setup) - Track crashes and bugs in prod
    4. [Chat Sync](/pages/guides/chat-sync) - Optional cloud sync for ChatSync
    5. [Photo Sync](/pages/guides/profile-photos) - Optional cloud sync for Profile Photo

    **Time needed:** \~2.5 hours for full backend setup
  </Tab>
</Tabs>

## Run Tests

Verify everything with the test suite:

```bash theme={null}
# In Xcode
⌘ + U

# Or command line — runs the Boilerplate.xctestplan in one pass
xcodebuild test \
  -scheme SwiftAIBoilerplatePro \
  -testPlan Boilerplate \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro,OS=26.2'
```

**Expected:** \~598 tests pass across 12 package test targets + the app test suites (one `Boilerplate.xctestplan` run). ✅

## Troubleshooting

<AccordionGroup>
  <Accordion title="Cannot find 'Glass' in scope on older Xcode">
    **Cause:** Liquid Glass APIs (`Glass`, `glassEffect`, `GlassEffectContainer`) are iOS 26 SDK symbols. Older toolchains cannot compile them, even behind `#available` checks.

    **Solution:** Upgrade to Xcode 26.2+ (the repo pins `26.3` via `.xcode-version`), or stay on the [`v1.9.0`](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v1.9.0) tag until you can upgrade.
  </Accordion>

  <Accordion title="Tab bar doesn't minimise on scroll">
    `.tabBarMinimizeBehavior(.onScrollDown)` is iOS 26 only. On iOS 17–25 the `saiTabBarMinimize(_:)` modifier is a no-op and returns the same view. No action needed; behaviour is progressive.
  </Accordion>

  <Accordion title="Dark blobs under my sheets / sheets look opaque">
    **Cause:** You (or downstream code) applied `DSColors.background.ignoresSafeArea()` or `.background(.black)` under the container. These block the Material SwiftUI already provides and fight Liquid Glass on iOS 26.

    **Solution:** Remove the manual background. SwiftUI handles sheet materials for you on iOS 26. See the [Migration Guide](/pages/migration/v1-9-to-v2-0) section "Fighting glass cleanup".
  </Accordion>

  <Accordion title="`any` keyword required everywhere">
    Swift 6 enforces explicit `any` on protocol-typed stored properties and parameters. The boilerplate has been audited for this already; your own types may need updates. See the [Migration Guide](/pages/migration/v1-9-to-v2-0).
  </Accordion>

  <Accordion title="MainActor-isolated error on ModelContext">
    **Cause:** `MessageRepositoryImpl`, `ConversationRepositoryImpl`, and `SettingsRepositoryImpl` are now `@MainActor`-pinned in v2.0.

    **Solution:** Create repositories from the main thread, or `await` when constructing them from a background context.
  </Accordion>

  <Accordion title="App won't build">
    **Solution:**

    ```bash theme={null}
    # Clean and rebuild
    ⌘ + Shift + K
    File → Packages → Reset Package Caches
    ⌘ + B
    ```
  </Accordion>

  <Accordion title="Debug sign-in not appearing">
    **Cause:** Running in Release mode

    **Solution:**

    1. Product → Scheme → Edit Scheme
    2. Run → Build Configuration → **Debug**
    3. Clean and rebuild
  </Accordion>

  <Accordion title="Dependencies won't resolve">
    **Solution:**

    ```bash theme={null}
    File → Packages → Resolve Package Versions
    # If still fails:
    File → Packages → Update to Latest Package Versions
    ```
  </Accordion>
</AccordionGroup>

## Production Setup Path

When you are ready to leave mock mode, set up real services in this order:

<Steps>
  <Step title="Configure Supabase">
    Create the Supabase project, copy `Config/Secrets.example.xcconfig` to `Config/Secrets.xcconfig`, and add your project URL and anon key.

    [Supabase setup guide](/pages/guides/supabase-setup)
  </Step>

  <Step title="Configure authentication providers">
    Keep mock auth while exploring. Set up Apple, Google, and email auth when you are ready for real accounts.

    [Authentication guide](/pages/guides/authentication)
  </Step>

  <Step title="Deploy the AI proxy">
    Add your OpenRouter key to the Supabase Edge Function and deploy the `ai` function so API keys stay server-side.

    [Deployment guide](/pages/guides/deployment#openrouter-setup)
  </Step>

  <Step title="Configure subscriptions">
    Set up RevenueCat products, entitlements, and API keys before testing paywalls.

    [RevenueCat setup guide](/pages/guides/revenuecat-setup)
  </Step>

  <Step title="Add optional production services">
    Add Crashlytics, OneSignal push notifications, chat sync, and profile photos only when your app needs them.

    [Crashlytics](/pages/guides/crashlytics-setup) · [OneSignal](/pages/guides/onesignal-setup) · [Chat Sync](/pages/guides/chat-sync) · [Profile Photos](/pages/guides/profile-photos)
  </Step>
</Steps>

## Quick Reference

### File Locations

```text theme={null}
Config/Secrets.xcconfig               # API keys (gitignored)
SwiftAIBoilerplatePro/AppShell/       # UI screens
SwiftAIBoilerplatePro/Composition/    # DI container
Packages/*/                           # 11 reusable Swift packages + TestSupport (test infra)
```

### Key Files for Customization

| What to Change   | File Location                                                                            |
| ---------------- | ---------------------------------------------------------------------------------------- |
| App display name | `Packages/DesignSystem/Sources/DesignSystem/Tokens/BrandConfig.swift` (`appDisplayName`) |
| App bundle ID    | `Config/App.xcconfig` (`APP_BUNDLE_ID`)                                                  |
| Colors           | `SwiftAIBoilerplatePro/Resources/DesignSystemColors.xcassets/`                           |
| Onboarding       | `AppShell/OnboardingPage.swift`                                                          |
| Home screen      | `AppShell/HomeContent.swift`                                                             |

### Useful Commands

```bash theme={null}
# Run tests with coverage
./scripts/run-tests.sh --coverage --open

# Clean build
⌘ + Shift + K (in Xcode)

# Resolve packages
File → Packages → Resolve Package Versions
```

## What You've Learned

<Check>
  You now have:

  * ✅ A running AI chat app
  * ✅ Working authentication (mock mode)
  * ✅ Functional chat with dual UIs
  * ✅ Profile management
  * ✅ Theme system (5 themes)
  * ✅ Understanding of mock vs production
</Check>

## Ready to Build?

<CardGroup cols={3}>
  <Card title="Customize" icon="palette" href="/pages/guides/customization">
    Change branding, features, and UI
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/pages/architecture">
    Learn the system design
  </Card>

  <Card title="Deploy" icon="rocket" href="/pages/guides/deployment">
    Ship to production
  </Card>
</CardGroup>

<Tip>
  **Pro tip:** Use the [Building Your App guide](/pages/guides/building-your-app) which includes ready-to-use **LLM prompts** for Cursor/Claude to speed up customization!
</Tip>

<Note>
  The **App Generator** — a standalone macOS app that drives your own coding-agent CLI (Claude Code, Codex, Gemini, or Cursor) to generate a differentiated app from this template — is a separate product (coming soon). See [pricing & license](/pages/reference/license) for details.
</Note>