How the kit works

The kit separates product experience from provider setup. That is why a complete app can run on day one without pretending real services are connected.

1. Routes stay thin

Files in src/app decide which screen is shown. Product behavior lives in components, hooks, providers, typed mock data, and integrations. This keeps an AI edit from turning every route into a vendor-specific tangle.

2. Mock and production share contracts

The app asks for capabilities such as “sign this person in”, “load a paywall”, or “stream a coach reply”. It does not make screens depend directly on Supabase, RevenueCat, PostHog, or Sentry types.

The active implementation is selected by environment values:

EXPO_PUBLIC_AUTH_ADAPTER=mock
EXPO_PUBLIC_PAYMENTS_ADAPTER=mock
EXPO_PUBLIC_AI_ADAPTER=mock

Changing one to a production value is the last step—not the first. Before the switch, the matching provider must be configured and verified.

3. Every real-service boundary is searchable

Integration points use a stable comment:

🔌 INTEGRATION: Area — see agent-skills/the-matching-skill.md

Your agent can inventory them with:

pnpm seams
pnpm setup:check

4. Skills are instructions for your AI

When you say “connect RevenueCat”, the project rules tell the agent to read agent-skills/wire-payments.md. That file records the code already present, the safe setup order, the failure cases to test, and the evidence required.

You do not execute a skill as a magic command. You ask for an outcome; your AI reads the skill and performs the work with you.

5. Native changes require the right proof

A JavaScript-only copy edit can hot reload. A permission, config plugin, icon, native package, URL scheme, or capability change needs a fresh development build. A simulator cannot prove camera, real purchases, push delivery, biometrics, or universal links.