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

# Quickstart

> Ship your iOS app in a weekend — from purchase to a running, themed app.

<Note>
  **AcornKit — the agent-ready SwiftUI starter kit.** The only kit your AI coding
  agent already understands: it ships `CLAUDE.md`, `AGENTS.md`, `TOKENS.md`, and a
  scaffold skill, so you can tell Claude Code or Cursor *"add a settings screen"* and
  it follows the kit's conventions instead of guessing.
</Note>

## What's in the box

* **`AcornCore`** — the dependency-free engine: design system (`AcornTheme` + tokens), StoreKit 2 subscriptions, onboarding→paywall→home gate, analytics protocol, account/data-deletion, an auth seam, an AI-chat seam, and composable UI.
* **`acorn-ios-template`** — a runnable app shell that composes AcornCore: 2 onboarding styles, 2 paywall styles, a tabbed home + settings, and an example AI Assistant tab.
* **Optional modules** — swap a vendor in one line: `AcornCoreRevenueCat`, `AcornCoreSupabase` (auth), `AcornCorePostHog` (analytics), `AcornCoreAI` (OpenAI/Claude), `AcornCoreFirebase`.
* **Agent files + scaffold skill** — `CLAUDE.md` / `AGENTS.md` / `CONTEXT.md` / `TOKENS.md`, a `Makefile`, SwiftLint + token-lint, and `scaffold-ios-app`.
* **Real proof** — built by the studio behind shipped apps (Focus0, Habit0, OnePushMan, …).

## Requirements

* macOS + **Xcode 16+**, iOS **17+** target. Swift 6.
* A paid Apple Developer account (to ship; not needed to build/run locally).
* Optional, only if you use them: a Supabase project (auth), RevenueCat account, an LLM key.

## 1. Scaffold your app

The template ships with `{{PLACEHOLDER}}` tokens (`{{APP_DISPLAY_NAME}}`,
`{{APP_TAGLINE}}`, `{{APP_SLUG}}`, `{{BUNDLE_ID}}`, `{{SIMULATOR_ID}}`). Use the
**`scaffold-ios-app`** skill to stamp a fresh app from the template — it replaces the
placeholders and lays out the workspace + feature package. Keep `AcornCore` beside your
app (the package references it at `../../AcornCore`).

<Tip>
  Prefer your agent? Open the kit in Claude Code / Cursor and ask it to scaffold a new
  app — the agent files tell it exactly how.
</Tip>

## 2. Make it yours

Everything app-specific lives in one file — `AppConfig.swift` (the composition root):

* **Brand:** override only the colors that differ from the premium-dark default in `BrandConfig` / `BrandColors`; set the app name. Read `TOKENS.md` before touching UI — raw colors/fonts/padding fail `make lint`.
* **Pick screen styles:** `AppConfig.onboardingStyle` (`.valueStack` / `.story`) and `paywallStyle` (`.planList` / `.singleCTA`).
* **Product IDs:** set `productIDPrefix` → `<prefix>.{weekly,monthly,yearly,lifetime}`.

## 3. Run it

From the app directory (never call `xcodebuild` directly — use the Makefile):

| Task                                        | Command       |
| ------------------------------------------- | ------------- |
| Build & run on the simulator                | `make build`  |
| Unit tests                                  | `make test`   |
| Token + SwiftLint                           | `make lint`   |
| Full verification (build/test/screens/a11y) | `make verify` |
| Print the design-token reference            | `make tokens` |

You now have a working onboarding → paywall → home → settings flow with a hard paywall,
the design system, and the example Assistant tab — all running.

## The architecture in 60 seconds

AcornKit's rule: **your app talks to protocols, never to vendors.** Each capability is a
swappable seam with a dependency-free default and an optional vendor module:

| Capability    | Seam (protocol)         | Default (no deps)                        | Optional swap                                                                    |
| ------------- | ----------------------- | ---------------------------------------- | -------------------------------------------------------------------------------- |
| Subscriptions | `SubscriptionProviding` | `StoreKitSubscriptionProvider`           | `RevenueCatSubscriptionProvider` → [RevenueCat setup](/revenuecat-setup)         |
| Auth          | `AuthProviding`         | `AnonymousAuthProvider` (guest)          | `SupabaseAuthProvider` → [Auth setup](/auth-setup)                               |
| Analytics     | `AnalyticsProviding`    | `ConsoleAnalytics`                       | `PostHogAnalytics`                                                               |
| AI chat       | `ChatProviding`         | `EchoChatProvider` / `ProxyChatProvider` | `OpenAIChatProvider` / `AnthropicChatProvider` → [AI chat setup](/ai-chat-setup) |
| Data deletion | `DataResetting`         | `LocalDataResetter`                      | `FirebaseDataResetter` / `Composite`                                             |

Swapping any of them is a one-line change in `AppConfig` — the screens never change.

## Add features the agent-ready way

This is the kit's edge. In Claude Code / Cursor, ask for a feature in plain English —
*"add a journal feature with a list and a detail screen"* — and the agent reads
`CLAUDE.md` / `AGENTS.md` / `TOKENS.md` and produces code that uses your tokens, your
`@Observable` pattern, and your folder structure. No re-teaching conventions every time.

## Ship checklist

<Steps>
  <Step title="Brand + product IDs">
    Set in `AppConfig`; `make lint` clean.
  </Step>

  <Step title="Subscriptions">
    StoreKit products in App Store Connect (or swap to RevenueCat — see [RevenueCat setup](/revenuecat-setup)).
  </Step>

  <Step title="Auth (if used)">
    Supabase + Sign in with Apple configured — see [Auth setup](/auth-setup).
  </Step>

  <Step title="AI (if used)">
    Proxy deployed, key server-side — see [AI chat setup](/ai-chat-setup).
  </Step>

  <Step title="App Store compliance">
    Privacy policy + Terms in `legalLinks`; "Delete all data" wired (it's built in).
  </Step>

  <Step title="Verify">
    `make verify` passes (build + tests + a11y).
  </Step>
</Steps>

## Next

<CardGroup cols={3}>
  <Card title="Auth setup" icon="key" href="/auth-setup">
    Add accounts in 3 steps with Supabase + Sign in with Apple.
  </Card>

  <Card title="RevenueCat in one line" icon="credit-card" href="/revenuecat-setup">
    Swap StoreKit for RevenueCat without touching a screen.
  </Card>

  <Card title="Add an AI chat" icon="robot" href="/ai-chat-setup">
    Stream completions with the key kept server-side.
  </Card>
</CardGroup>

Design tokens live in `TOKENS.md`; architecture & conventions in `AGENTS.md` / `CLAUDE.md` (shipped in the kit).