vybekiit 0.7.28 → 0.7.29

package/dist/global-skills/vybekiitReferences/extension/platform-skills/sentry-vybekiit.md

@@ -0,0 +1,33 @@
+# Platform wrapper: Sentry (agent-only)
+
+**Agent-only.** Invoked by buyer skill `track-errors` — not a buyer-facing name.
+
+## Official upstream
+
+- Docs: https://docs.sentry.io/platforms/javascript/guides/nextjs/
+- Package: `@vybekiit/observability` (Sentry adapter via `@sentry/core`)
+- Pinned skills: `.agents/skills/sentry-sdk-setup/SKILL.md`, `.agents/skills/sentry-workflow/SKILL.md`
+
+## Kit wiring
+
+1. Set in `.env`:
+   - `OBSERVABILITY_PROVIDER="sentry"`
+   - `SENTRY_DSN="<from Sentry dashboard>"`
+2. Confirm `instrumentation.ts` exists (calls `resolveObservabilityProvider`).
+3. Confirm `src/lib/observability.ts` exports the provider.
+4. Add a dev-only test route or button that throws once; verify alert in Sentry dashboard.
+5. Wire `app/global-error.tsx` or route error boundaries to call `observability.captureException`.
+
+## Builder manual step (one at a time)
+
+1. Open the Sentry project the agent created (or have them sign up at sentry.io).
+2. Copy the **DSN** from Project Settings → Client Keys.
+3. Paste when the agent asks — never paste into chat.
+
+## Verify-before-advance
+
+Trigger test error → Sentry shows the event → tell builder "You'll get an email when something breaks."
+
+## Mobile
+
+Same `@vybekiit/observability` interface; Expo uses Sentry React Native SDK when the mobile track-errors skill runs — follow Expo Sentry docs for native init if needed beyond the headless provider.

package/dist/global-skills/vybekiitReferences/extension/platform-skills/ship-via-pr-vybekiit.md

@@ -0,0 +1,49 @@
+# Platform wrapper: ship via PR (agent-only)
+
+**Agent-only.** Save work through a safe branch + online checker — use when changes are large or the builder is waiting.
+
+## When
+
+- After meaningful progress and `back-up-my-code` already created a remote
+- Builder is impatient — use a **git worktree** so main stays runnable while you work in parallel
+- Before merging to `main`, CI must be green on all three OS jobs (`ci-vybekiit.md`)
+
+## Flow
+
+1. **Worktree (optional, parallel work):**
+   ```bash
+   git worktree add ../my-app-feature feature/save-progress
+   cd ../my-app-feature
+   ```
+
+2. **Branch + commit:**
+   ```bash
+   git checkout -b feature/save-progress
+   git add -A
+   git commit -m "Save progress"
+   ```
+
+3. **Push + open PR:**
+   ```bash
+   git push -u origin HEAD
+   gh pr create --title "Save progress" --body "Agent checkpoint — checks running."
+   ```
+
+4. **Wait for CI** — all ubuntu/macOS/Windows jobs green (`gh pr checks --watch`).
+
+5. **Merge when green:**
+   ```bash
+   gh pr merge --squash --delete-branch
+   ```
+
+6. Tell the builder in plain words: *"Your latest work is saved and checked."*
+
+## Rules
+
+- Never expose PR, worktree, or branch jargon — see `language.md`.
+- Pre-push hook runs before push; fix locally first.
+- Never merge red CI — fix and push again.
+
+## Verify
+
+PR merged · `main` green on GitHub · builder hears one plain success line

package/dist/global-skills/vybekiitReferences/extension/platform-skills/testing-vybekiit.md

@@ -0,0 +1,33 @@
+# Platform wrapper: testing (agent-only)
+
+**Agent-only.** Run tests with every feature — the builder never hears "vitest" or "unit test."
+
+## When
+
+Every new feature, bug fix, API route change, or hook change.
+
+## How
+
+- **Runner:** `pnpm test` (Vitest)
+- **Web:** React Testing Library for components; test files live in `src/**/__tests__/`
+- **Patterns:** follow existing tests in `src/lib/__tests__/`, `src/hooks/__tests__/`, `src/components/__tests__/`
+
+## Rules
+
+1. Test **behavior users care about** — form submit succeeds, auth error shows, checkout redirects.
+2. No `toBeDefined()` theater — assert outcomes, not existence.
+3. Mock network at the client boundary (`fetch-json`, auth/billing clients), not deep kit internals.
+4. Run `pnpm test` **before** telling the builder something works.
+
+## Also read
+
+- `nextjs-vybekiit.md` — App Router + API route patterns
+- `react-patterns-vybekiit.md` — hooks and forms to test
+
+## Verify
+
+```bash
+pnpm test
+```
+
+Green before "done."

package/dist/global-skills/vybekiitReferences/extension/platform-skills/ui-consistency-vybekiit.md

@@ -0,0 +1,33 @@
+# Platform wrapper: UI consistency (agent-only)
+
+**Agent-only.** Professional, symmetric UI — not a buyer goal skill.
+
+## Catalog
+
+Web/extension: `.vybekiit/agent/ui-sources.md`  
+Mobile: `.vybekiit/agent/ui-sources.mobile.md`
+
+## Non-negotiable contract
+
+1. **Primitive-first** — `Button`, `Input`, `Card`, `Alert`, `Badge`, `Separator`, `Skeleton`, `Avatar`, `Tabs`, `Dialog`, `Sheet`, `Select`, `DropdownMenu`, `Sonner` from `src/components/ui/`; popup ships the core subset (`Button`, `Input`, `Card`, `Alert`)
+2. **Locked size scale** — `sm | default | lg | icon` only; no custom `h-11`, `px-7`, arbitrary heights
+3. **Token SSOT** — semantic colors (`bg-primary`, `text-muted-foreground`); no `bg-blue-500` or hard-coded hex
+4. **Spacing rhythm** — token/Tailwind scale (`gap-4`, `p-6`); ban `mt-[13px]` except while refactoring imports
+5. **Normalize on import** — third-party blocks → swap to kit primitives + CSS vars before shipping
+6. **One visual voice per screen** — one effect library flavor per page max on marketing; dashboard stays minimal
+7. **Symmetric layouts** — equal card heights, consistent `px-4 md:px-6`, logical properties (`ms-`, `me-`)
+8. **No second design system** — Tremor/charts-only exception for dashboards
+
+## Normalize-on-import workflow
+
+1. Copy block from approved source (see catalog)
+2. `rg '<button|<input' <file>` — replace with kit components
+3. Map colors to CSS variables / theme tokens
+4. Strip conflicting Tailwind size classes
+5. Preview in dev — confirm buttons match existing screens
+6. Run UI checks from `check-safety` step 7
+
+## Cross-refs
+
+- `shadcn-vybekiit.md` — kit component conventions
+- `code-hygiene-vybekiit.md` — no duplicate helpers in UI code

package/dist/global-skills/vybekiitReferences/mobile/AGENTS.md

@@ -0,0 +1,460 @@
+# AGENTS.md — your build agent (read this first)
+
+> **You are talking to a non-technical vibe coder.** They can describe what they want
+> and follow simple steps, but they do **not** want to understand environment variables, builds,
+> app stores, or signing. Your job is to make every technical decision and do the work — and
+> translate the few steps only they can do into plain, one-at-a-time instructions.
+>
+> This is the **single source of truth** for how you behave in this project. Codex reads this file
+> natively; `CLAUDE.md` (Claude Code) and `.cursor/rules/vybekiit.mdc` (Cursor) are thin pointers to
+> it; `.cursor/rules/patterns.mdc` summarizes code conventions (not SSOT). Supported assistants:
+> Claude Code · Codex · Cursor.
+
+## This is a phone app — it talks to your backend
+
+A phone app **cannot safely keep private keys** (anyone can pull them off a device), so this app
+holds **no secrets**. Sign-in, saved data, payments, and email all live on the vibe coder's **backend**
+— the web app they already deployed — and the phone app just **connects to it** over the internet.
+
+- The only setting the phone app needs is the backend's web address (`EXPO_PUBLIC_APP_URL` in `.env`,
+  resolved once in `src/lib/config.ts`). Everything sensitive stays on the backend, never on the
+  device.
+- So mobile skills here **point the app at the backend and wire the screens** — they never set up a
+  database, email, or secret keys on the phone. If the backend doesn't have a feature yet (e.g.
+  sign-in), the matching mobile skill sends the vibe coder to set it up on the **web** side first.
+- The phone may safely store one thing: the user's own sign-in pass, kept in the device's secure
+  storage. That's it.
+
+<!-- vybekiit:generated:start contract -->
+## The contract: Decide + Guide
+
+A request such as "Can people book my classes?" means build the working feature. Inspect the connected provider and run `vybekiit list-presets` before saying the kit lacks the capability. Reuse the booking and organizations presets, add only app-specific behavior, and verify saved bookings and access rules. Read `.vybekiit/agent/session-bootstrap.md` for the persistence workflow. Continue ordinary authorized work without asking the buyer to reconfirm it.
+
+① **One action at a time** — Give the buyer one manual action at a time. Continue authorized work independently, checking each step until the requested work is complete or blocked. Requests to let people book, pay, or join a team mean implement that behavior; do not replace the requested feature with an easier alternative.
+② **Verify before advancing** — Confirm each step actually worked before moving on, so the vibe coder can't get silently stuck. Shared bookings, payments, and team access need real saved information; a preview does not complete them.
+③ **Plain language** — Translate every technical term using language.md — the vibe coder never has to understand or decide.
+④ **Translate errors** — Turn any failure into "what happened + the one thing to do about it" — never paste a raw stack trace.
+⑤ **Celebrate progress** — Celebrate only verified progress. State whether it works locally, in practice, or online.
+⑥ **Record decisions** — After every completing skill, append one entry to checklist.md Decision log via formatChecklistEntry().
+⑦ **Official source fallback** — If MCP or the first debug attempt fails once, run vybekiit doc-fallback and tell the vibe coder the plain stuck phrase only.
+<!-- vybekiit:generated:end contract -->
+
+## How to work
+
+Simple questions need brief answers, without setup or skill searches. Inspect before making
+project-specific claims. Requests for work mean do the work and verify the requested behavior.
+Reuse instructions already loaded in the conversation. Continue authorized work independently;
+one action at a time limits steps the buyer must take. Prefer this project's skills over global
+copies. Do not use helper agents for simple exchanges.
+
+1. **Find the goal.** Buyer goal skills in `.agents/skills/` (also via `.cursor/skills/` and
+   `.claude/skills/`) load automatically from their descriptions — use the matching skill when the
+   vibe coder's intent fits. If nothing fits or you're unsure, fall back to `.vybekiit/agent/goal-index.md`
+   and read the skill in `.vybekiit/skills/`. Also check `.vybekiit/extensions/goal-index.md` when present.
+   Routine edits need no new skill. Consult `platform-skills/extend-capabilities-vybekiit.md`
+   only for a real uncovered integration.
+2. **One action at a time.** Do a step, then **verify it worked before moving on** (the skills call
+   this *verify-before-advance* — it's what stops a vibe coder getting silently stuck and asking for a
+   refund). Publishing to the stores has waits you can't rush — set expectations, don't fake them.
+3. **Translate every error** into "what happened + the one thing to do about it." Never paste a raw
+   stack trace or a red build log at the vibe coder.
+4. **Celebrate progress.** Small wins out loud ("Your app is on your phone! 🎉") keep a non-coder
+   going.
+5. **Write tests as you build features** and keep them green — that green suite is the vibe coder's
+   safety net and the reason updates are safe to apply.
+
+## Planning before big builds
+
+When the vibe coder asks for something **large or vague** (a whole product shape, "like X but for Y",
+many features at once) and you have not planned together this session:
+
+1. **Offer once** (never force): *"Want to think it through together first? I'll ask one question at
+   a time until we're totally aligned."*
+2. If they **accept** → follow `skills/plan-my-idea.md`.
+3. If they **decline** → build anyway. Impatient builders stay in control.
+
+During onboarding, preserve the requested goal. Ask about planning only if a missing product decision blocks the work or the builder asks to plan.
+
+## What you may decide without asking
+
+Generic coding, design tweaks, screen layout, data shapes, and which kit package to use. These are
+**not** skills — just do them well, following the conventions below.
+
+## Conventions (so the code stays clean and updatable)
+
+- The kit's logic lives in `@vybekiit/*` packages (accounts, payments, shared helpers). **Use them —
+  don't reinvent them.** They update separately; the vibe coder's customizations stay in this repo.
+- The backend's web address lives in **one** place: `EXPO_PUBLIC_APP_URL` in `.env` (documented by
+  `.env.example`), resolved in `src/lib/config.ts`. Never scatter raw addresses through the screens.
+- **Never read `.env` values aloud or paste them in chat** — reference keys from `.env.example` only.
+  Read `env-secrets-vybekiit.md`.
+- Every call to the backend goes through `src/lib/fetch-json.ts` (relative paths resolve against the
+  backend automatically). Don't hand-roll `fetch` in a screen.
+- Keep screens small and readable. Use the kit's UI primitives in `src/components`.
+- Layout uses logical flex and the system's right-to-left support, so the app mirrors automatically
+  for Hebrew/Arabic users. Never hard-code `left`/`right` positions — use `start`/`end` and let the
+  system flip it.
+- **All user-facing copy** lives in `messages/en.json` and is rendered via `t('flat.dotted.key')`
+  — never inline strings in screens. See `i18n-vybekiit.md`.
+
+### Before you write code (invisible quality — vibe coder never hears this)
+
+1. **Check before create** — read `src/lib/README.md` before adding a helper; extend existing code if ≥80% overlap.
+2. **One home per concern** — auth → `auth-client.ts`, billing → `billing-client.ts`, logging → `logger.ts`.
+3. **Use the kit logger** — `import { log } from '@/lib/logger'`; never `console.log` in app code (tests may use console).
+4. **KISS** — no duplicate validation; backend validates on the server.
+5. **SSOT** — backend URL in `config.ts` only; plans in `plans.ts`.
+6. **Test as you build** — add/update tests with every feature; `pnpm test` green before saying done.
+7. **Format + lint silently** — run `pnpm format && pnpm lint` after substantive edits.
+8. **Use kit hooks** — `useAsync` / `useUser` / `useToast` / `FormField`; read `src/hooks/README.md`.
+9. **Keep functions small** (~5 lines) and props few (~5); split rather than grow.
+
+Read `.vybekiit/platform-skills/code-hygiene-vybekiit.md`, `observability-vybekiit.md`, `testing-vybekiit.md`, `format-lint-vybekiit.md`, `react-patterns-vybekiit.md`, and `planning-vybekiit.md` (when running `plan-my-idea`) for details.
+
+### UI (professional & symmetric — port, don't install new UI stacks)
+
+- Build only with `src/components/ui/*` and `@vybekiit/tokens` via `useTheme()` (ADR-0004).
+- Web block libraries (Magic UI, 21st.dev, etc.) are **visual reference** — reimplement with kit primitives. See `.vybekiit/agent/ui-sources.mobile.md`.
+- Locked sizes: `sm | default | lg | icon`. Read `.vybekiit/platform-skills/ui-consistency-vybekiit.md`.
+
+## Wire-up markers (how "finish setup" works)
+
+Some files ship as **ready layouts with the logic stubbed**, so the app builds and looks finished
+before any backend connection exists (the sign-in, sign-up, verify, pricing, and dashboard screens
+are like this). Every unfinished point carries one greppable marker:
+
+```
+TODO(vybekiit): <what to do> — skill: <skill-name>
+```
+
+When the vibe coder says "set it up", "finish setup", "wire it up", or "make it work", list every
+marker and resolve them one at a time:
+
+```
+grep -rn "TODO(vybekiit)" .
+```
+
+Each marker names the skill that completes it (e.g. `connect-account`, `setup-payments`,
+`publish-app`). Run that skill, replace the stub, verify, then re-grep — you're done when it comes
+back empty. The stubs are centralized so a skill edits **one** file, not every screen:
+
+- sign-in lives in `src/lib/auth-client.ts` (skill: `connect-account`)
+- checkout lives in `src/lib/billing-client.ts` (skill: `setup-payments`)
+- the app's identity (name, unique id) lives in `app.json` (skill: `publish-app`)
+- the store-deploy details live in `launch.config.ts` (skill: `publish-app`)
+
+Never show the vibe coder a marker or the word "stub" — just do the work and tell them what now works.
+
+## Boundaries
+
+- You fix and extend **this app** and connect it to the vibe coder's backend. You don't put secrets on
+  the device, and you don't promise things the kit doesn't do.
+- If the vibe coder asks for something genuinely outside the kit, say so plainly and offer the closest
+  thing the kit supports.
+
+
+
+<!-- launch:start -->
+## Shipping this app with Launch
+
+<!-- generated by launch v0.32.12 - `npx launch agents init` - do not hand-edit -->
+
+This repo ships with **Launch** - an open-source, self-hosted alternative to Expo EAS that builds, signs, and ships this Expo / React Native app to TestFlight and Google Play from the developer's own machine, with their own keys, and no per-build bill. Everything is driven from one typed `launch.config.ts`. The pipeline mirrors EAS: prebuild -> resolve credentials -> compile & sign -> size-check -> store -> submit to the **testing** track (TestFlight / Play internal). `launch release` is the separate, deliberately confirmed **public** release.
+
+### EAS -> Launch
+
+| EAS | Launch | Notes |
+| --- | --- | --- |
+| `eas build` | `launch build` | uploads to the testing track (TestFlight / Play internal) |
+| `eas submit` | `launch release` | the confirmed PUBLIC production release |
+| `eas update` | `launch update` | Expo Updates protocol, on the user's own bucket; `launch updates rollback` reverses it |
+| `eas metadata` | `launch metadata` | store listing for iOS and Android |
+| `eas credentials` | `launch creds` | multi-account, keychain-stored signing material |
+
+### Safety rails
+
+- **Secrets stay in the OS keychain.** Never write, log, or commit a `.p8`, `.p12`, keystore, or private key, and never put a real secret in a committed `.env` - store build secrets with `npx launch secret set <NAME>` instead.
+- **`launch.config.ts` is the source of truth** for store config. The reconcilers (`sync`, `metadata`) run a read-only plan -> confirm -> apply and never clobber a live or in-review version; preview any of them with `--dry-run`.
+- **Learn as you go.** `npx launch <command> --explain` expands any step into plain English, and `npx launch demo` walks the whole pipeline as a zero-setup simulation.
+- **iOS signing needs a Mac.** With no local Mac, build on a cloud Mac in the user's own AWS account, over SSH to any Mac, or hand off to EAS (`npx launch build ios --remote`). Android builds anywhere a JDK runs.
+- **Non-interactive by design.** Pass `--yes` to run the safe, idempotent commands unattended; Launch already degrades to non-interactive when it detects CI, a pipe, or an agent.
+
+### What an agent may run vs must confirm
+
+**Run freely (idempotent, reversible, or read-only):**
+
+- **Setup & onboarding** - `init`, `adopt`, `migrate eas|fastlane`, and first-time `creds set-key` / `creds setup` (provisioning is idempotent).
+- **Builds to the testing track** - `build ios|android` uploads to TestFlight / Play internal, not the public store.
+- **Reads & rehearsals** - `status`, `doctor`, `diagnose`, `demo`, `sync --dry-run`, `metadata pull`, and any command with `--explain`.
+- **Planning & readiness (read-only)** - `plan`, `drift`, `audit`, `store doctor`, `iap doctor`, `privacy scan`, `snapshot create|diff`, and `insights` only read live state.
+- **Local-only tooling** - `dashboard` (a read-only local web UI over CLI state) and `mcp install` (expose Launch to local AI clients) run on the developer's machine, never touching the store.
+- **Over-the-air updates** - `update` and `updates list|view` (and `updates rollback` to reverse a bad one).
+
+**Confirm with a human first (irreversible / public-facing):**
+
+- **`launch release ios|android`** - submits to the PUBLIC production track and is hard to reverse. Run `--dry-run` first, show the plan, and let a human trigger the real submit.
+- **`launch rollout complete`** and accelerating a phased rollout - it pushes a public release toward 100%.
+- **Credential changes that switch or delete signing material** - `launch creds use|rename|remove`. (First-time `creds set-key` / `creds setup` during onboarding is fine.)
+- **Applying a store reconcile to a live or in-review listing** - `launch sync` / `launch metadata push` without `--dry-run`, and especially `sync --allow-destructive`. Show the `--dry-run` plan and get confirmation before applying.
+
+### Getting started
+
+- Install Launch as a dev dependency: `npm install --save-dev launch-store` (or `--global` to put `launch` on the PATH).
+- Verify the toolchain and config before building: `npx launch doctor` (add `--fix` to install missing iOS tools).
+- The recipes below call `npx launch ...`, which resolves the locally-installed binary; with a global install you can drop the `npx`.
+
+### Common tasks
+
+### Set up and ship to TestFlight / Play
+
+_Use when: ship the app to TestFlight or Play internal testing; build and upload a test build; set up code signing / credentials for the app; onboard an existing (already-shipping) app to Launch._
+
+1. `npx launch init` - scaffold launch.config.ts (+ .env.example); skip if it already exists
+2. `npx launch adopt` - OPTIONAL - app already on the store? import its live App Store Connect setup into config
+3. `npx launch creds set-key` - store the App Store Connect API key (.p8) in the OS keychain
+4. `npx launch creds setup` - register the app id and create or reuse the cert + provisioning profile
+5. `npx launch doctor` - verify the iOS/Android toolchain and config; add --fix to install missing tools
+6. `npx launch build ios` - run the full pipeline and upload to TestFlight (use 'android' for Play; --no-submit builds only)
+
+Run the steps in order. `init` writes the config, `creds` puts the signing material in the keychain, `doctor` catches toolchain and store-side blockers, and `build` produces a signed binary and uploads it to the **testing** track.
+
+- `build` flags worth knowing: `--profile <name>` selects a build profile, `--no-submit` builds without uploading, `--dry-run` rehearses every step, `--explain` teaches as it runs, and `--remote [aws|user@host]` builds iOS without a local Mac.
+- Manage testers after the upload with `launch testflight` (groups, add/remove testers, `testflight release` to push a build to a group). `launch builds` lists build history; `launch build:resign` re-signs a stored artifact without rebuilding.
+- Android: `build android` signs with the upload keystore and uploads to the Play track (`--track internal|closed|open|production`).
+
+**Cautions:**
+- `build` uploads to the TESTING track only - that's safe. Putting the app in front of the PUBLIC is `launch release` (see the launch-release skill), which needs human confirmation.
+- First-time `creds setup` provisions real signing assets in the Apple Developer account - expected during onboarding. Switching or removing an account later (`creds use|remove`) needs human confirmation.
+
+### Public release & phased rollout
+
+_Use when: release the app to the App Store / production / make it public; submit for review or go live; check review or rollout status; pause, resume, or complete a phased rollout._
+
+1. `npx launch status` - show each app's store version, review state, and phased-rollout state (--json for CI)
+2. `npx launch release ios` - submit the latest build to the PUBLIC production track - preview with --dry-run first
+3. `npx launch rollout pause` - steer an iOS phased release: pause | resume | complete
+4. `npx launch release-train start` - coordinate iOS + Android + OTA as one resumable release record (start | status | release | abort)
+
+`release` is the deliberate public step, distinct from `build` (which only reaches the testing track). Always preview first.
+
+- `release <platform> --dry-run` prints the release plan and touches nothing - run it, show the plan, then let a human trigger the real submit.
+- iOS options: `--phased` opts into Apple's 7-day phased rollout, `--build latest|<n>` promotes an existing build instead of uploading, `--manual` holds the approved build for manual release, `--scheduled <iso>` schedules go-live.
+- `status --watch` polls until review reaches a terminal verdict; `rollout pause|resume|complete` steers an in-progress phased release.
+- Shipping iOS + Android (and an OTA leg) together? `release-train start` records the whole release as one resumable unit - `--hold` gates every leg until all are approved and releases them together, `--platform`/`--no-ota` scope it, and `status`/`release`/`abort` drive or unwind it.
+
+**Cautions:**
+- `launch release` makes the app PUBLIC and is hard to reverse. Run `launch release <platform> --dry-run`, show the plan, and get explicit human confirmation before the real submit.
+- `rollout complete` accelerates a public rollout to 100% - confirm before running it.
+
+### Store configuration as code
+
+_Use when: add or change an in-app purchase or subscription; sync store config / capabilities to App Store Connect; push or pull the store listing metadata; set up Google Play products, subscriptions, or tracks; generate promo offer codes, an in-app event, or an A/B experiment._
+
+1. `npx launch sync` - reconcile ASC IAPs, subscriptions, pricing, and capabilities from config - run with --dry-run first
+2. `npx launch metadata pull` - pull the current listing into store.config.json to edit (--platform android for Play)
+3. `npx launch metadata push` - push edited listing copy / screenshots back to the store - --dry-run rehearses
+4. `npx launch play-products` - reconcile Google Play in-app products from config
+5. `npx launch play-subscriptions` - reconcile Google Play subscriptions (base plans + offers)
+
+Store config lives in `launch.config.ts` (catalog) and `store.config.json` (listing). One catalog drives BOTH stores. Every reconcile runs plan -> confirm -> apply.
+
+The safe loop: preview with `--dry-run` (or `metadata pull`), review the plan, then apply. See the bundled command reference for the full surface across both stores.
+
+Preview the full cross-surface diff with `launch plan` and gate drift in CI with `launch drift` (see the launch-plan skill); draft listing copy with `launch ai listing` before pushing it (see the launch-ai-listing skill).
+
+**Command reference.** The full store-config surface, both stores. Each runs a read-only plan -> confirm -> apply; preview with `--dry-run` and never apply to a live or in-review listing without human confirmation.
+
+| Command | What it does |
+| --- | --- |
+| `npx launch sync` | App Store Connect: reconcile IAPs, subscriptions, pricing, capabilities (--dry-run, --allow-destructive, --yes) |
+| `npx launch metadata pull` | pull the store listing (copy, screenshots, previews) into store.config.json |
+| `npx launch metadata push` | push the edited listing back to the store |
+| `npx launch offers list` | list promotional offers for a subscription product |
+| `npx launch offers generate-codes` | generate one-time promo / offer codes for a product |
+| `npx launch offers deactivate` | deactivate an offer |
+| `npx launch play-products` | Google Play: reconcile in-app products |
+| `npx launch play-subscriptions` | Google Play: reconcile subscriptions (base plans + offers) |
+| `npx launch play-tracks status` | show Google Play track state |
+| `npx launch play-tracks promote` | promote a build between Play tracks |
+| `npx launch availability` | manage territory / country availability |
+| `npx launch custom-pages` | manage custom product pages |
+| `npx launch experiments` | manage product-page A/B experiments |
+| `npx launch events list` | list in-app events |
+| `npx launch events create` | create an in-app event |
+| `npx launch app-clips` | configure App Clips |
+| `npx launch game-center` | configure Game Center leaderboards / achievements |
+| `npx launch accessibility` | set the accessibility declarations on the listing |
+
+**Cautions:**
+- These commands change a LIVE store. Always preview with `--dry-run` (or `metadata pull`), show the plan, and get human confirmation before applying.
+- `sync --allow-destructive` can remove a capability or product - treat it as requiring explicit human sign-off.
+
+### Over-the-air updates & rollback
+
+_Use when: publish an OTA update / push a JS-only change without a rebuild; ship a hotfix over the air; list or inspect published updates; roll back a bad update._
+
+1. `npx launch update` - publish a code-signed OTA update to the channel (--channel, --platform; --dry-run rehearses)
+2. `npx launch updates list` - list published updates for a channel
+3. `npx launch updates view latest` - inspect an update by id (or 'latest')
+4. `npx launch updates rollback` - reverse a bad update - promote a known-good one or drop clients to the embedded bundle
+
+OTA updates ship only JS and asset changes the installed runtime can accept (same runtime version), code-signed and hosted on the user's own bucket. **Native** changes (new dependencies, config plugins, permissions) need a full `build` + `release`, not an update.
+
+- `update --channel <name> --platform ios|android|all` publishes; `--dry-run` prints the layout without uploading. Avoid `--no-sign` (it lets anyone who can write the bucket push JS).
+- `updates rollback` is the escape hatch - it promotes a known-good update or drops clients back to the embedded bundle.
+
+**Cautions:**
+- An OTA update reaches real users immediately. Rehearse with `--dry-run`, and confirm the channel and runtime version before publishing to a production channel.
+
+### CI on a hosted runner
+
+_Use when: set up CI / GitHub Actions to build and ship the app; build and ship from a hosted runner without a local Mac; run Launch unattended / headless; wire up the release pipeline secrets._
+
+1. `npx launch ci init` - write .github/workflows/launch.yml for a hosted runner (--android adds an Android job)
+2. `npx launch doctor --yes` - non-interactive preflight inside the workflow
+3. `npx launch build ios --yes` - unattended build + upload to the testing track
+
+`ci init` writes a transparent, editable workflow (not a black-box action) wired to the same unattended commands Launch already supports.
+
+- It installs `launch-store` globally on the runner, triggers on `workflow_dispatch` and pushed `v*` tags, and reads credentials from repository secrets decoded at runtime: `ASC_KEY_ID`, `ASC_ISSUER_ID`, `ASC_API_KEY_BASE64` (Android adds `PLAY_SERVICE_ACCOUNT_BASE64`, `ANDROID_KEYSTORE_BASE64`, and the key alias/passwords).
+- Pass `--yes` on the safe commands; Launch also auto-detects CI and degrades to non-interactive on its own.
+
+**Cautions:**
+- Keep `launch release` (public production) OUT of an automatic CI trigger - put it behind a manual approval / protected environment so a push can't publish to the store unattended. CI should target the TESTING track by default.
+- Supply credentials only via repository secrets decoded at runtime; never commit a `.p8`, keystore, or service-account JSON.
+
+### Diagnose toolchain & build failures
+
+_Use when: the build is failing or broken - fix it; fix the toolchain / install missing build tools; diagnose a native build error; signing or credentials won't resolve._
+
+1. `npx launch doctor` - detect the iOS/Android toolchain and store-side blockers; --fix installs missing brew tools (--yes for CI)
+2. `npx launch diagnose` - analyze the most recent build log (or a given logfile) and explain the native failure
+3. `npx launch creds status` - show which Apple account and signing assets are active when signing fails
+
+Start with `doctor` to separate environment problems from build problems, then `diagnose` to read the actual native failure.
+
+- `doctor --fix` asks for consent, then installs missing iOS tools via Homebrew (`--yes` skips the prompt for CI/agents). `doctor --platform android` checks the Android toolchain.
+- `diagnose` reads the newest log under `~/.launch/logs` (or a path you pass) and explains the failure in plain English. A config footgun check also runs at the head of every `build`.
+- When signing is the problem, `creds status` shows the active account; `creds set-key` / `creds setup` fix a missing key or profile.
+
+**Cautions:**
+- `doctor --fix` installs build tools via Homebrew. It's safe to run, but review what it proposes; pass `--yes` only in CI where unattended installs are intended.
+
+### Pre-submit readiness & verification
+
+_Use when: is the app ready to submit / would it get rejected?; run a pre-submit readiness check; verify the App Store / Play account and in-app purchases are set up; check the privacy declarations against the app's permissions._
+
+1. `npx launch audit` - one-shot pre-submit sweep - would a submission be rejected right now? (read-only)
+2. `npx launch store doctor` - store-account readiness: the Apple app record, Play onboarding & access (read-only)
+3. `npx launch iap doctor` - in-app-purchase readiness: products & subscriptions exist and are submittable (read-only)
+4. `npx launch privacy scan` - reconcile permissions / manifests against the privacy declarations; flags undeclared collection
+
+Run these before a `release` to catch rejections on your machine instead of in App Review. Every command here only reads - none of them changes the store.
+
+- `audit` is the headline sweep; the focused doctors (`store doctor`, `iap doctor`) and `privacy scan` drill into the specific area that fails.
+- Pair this with `launch plan` (see the launch-plan skill) to also diff your config-as-code against live state before submitting.
+
+### Store config as code: plan & drift
+
+_Use when: preview the store config diff before syncing; what would `launch sync` change?; detect or gate configuration drift in CI; check that the live store still matches launch.config.ts._
+
+1. `npx launch plan` - diff launch.config against live store state across every config-as-code surface (read-only)
+2. `npx launch drift` - fail when live state has drifted from config - `plan --check` for CI
+
+`plan` is the read-only preview behind `sync` / `metadata` / the Play reconcilers: it diffs config against live state across capabilities, IAPs, subscriptions, pricing, listing, and the rest of the config-as-code surfaces. `drift` is the same diff as a CI gate (exit non-zero on any difference).
+
+- `plan [surface]` narrows the diff to one surface; bare `plan` covers them all.
+- Use `drift` in CI to keep the store and `launch.config.ts` from silently diverging; apply changes with the launch-store-config skill once the plan looks right.
+
+### Snapshot & restore live store state
+
+_Use when: snapshot the current store state before a risky change; what changed in the store since the last snapshot?; restore / roll back the store listing to a saved snapshot; clean up old snapshots._
+
+1. `npx launch snapshot create` - capture live App Store + Play state into a named snapshot
+2. `npx launch snapshot diff <name>` - compare a saved snapshot against another snapshot or live state (default: live)
+3. `npx launch snapshot restore <name>` - restore a snapshot's App Store listing back to live - additive; previews unless --yes
+4. `npx launch snapshot prune` - delete old user snapshots by --keep <n> and/or --older-than <days> (auto baselines untouched)
+
+Take a `snapshot create` before any risky reconcile so you have a labelled baseline, then `snapshot diff` to see exactly what moved. `restore` writes the saved App Store listing back to live (other surfaces are preview-only for now).
+
+- `snapshot diff <name>` defaults to comparing against live state; pass a second name to compare two saved snapshots.
+- `snapshot prune` requires at least one of `--keep`/`--older-than` and never touches the automatic pre-sync baselines.
+
+**Cautions:**
+- `snapshot restore` changes a LIVE listing (additive, never destructive). It previews the plan by default - show that plan and get human confirmation before re-running with `--yes`.
+
+### Migrate from EAS / fastlane, or adopt a live app
+
+_Use when: migrate from Expo EAS / eas.json to Launch; import an existing fastlane setup; onboard an app that already ships on the store; validate my launch.config.ts against the schema._
+
+1. `npx launch migrate eas` - read eas.json/app.json and emit launch.config.ts, .env.example, store.config.json + a report
+2. `npx launch migrate fastlane` - read fastlane config (Appfile/Fastfile/Matchfile...) and emit the same Launch config set + a report
+3. `npx launch adopt` - onboard an already-shipping app: import its live App Store Connect setup into config
+4. `npx launch config validate` - validate the config against the schema, reporting each problem by field path
+
+Pick the migrator that matches the current setup: `migrate eas` for an Expo EAS project, `migrate fastlane` for a fastlane one, or `adopt` to pull a live App Store Connect setup into config. Each writes a `launch.config.ts` (plus `.env.example` and `store.config.json`) and a report of what it found.
+
+- Migration only writes local config files - it touches no store and provisions nothing.
+- Always finish with `config validate` to confirm the emitted config is schema-clean, then `launch plan` (see the launch-plan skill) to see how it compares to live state.
+
+### Ratings, reviews, sales & analytics insights
+
+_Use when: how is the app rated / how are reviews trending?; read the latest customer reviews; download a sales or finance report; pull App Store analytics._
+
+1. `npx launch insights` - aggregate rating & review trends across the App Store and Play (read-only)
+2. `npx launch reports sales` - download a Sales & Trends report (gzipped TSV, or --json)
+3. `npx launch reviews list` - list an app's customer reviews, newest first (filter by rating/territory)
+
+`insights` is the aggregated cross-store view (ratings and review trends); drop to `reviews list` for the individual reviews and `reports` for the raw Sales & Trends / finance / analytics data.
+
+- Everything here only reads - safe to run unattended.
+- Reply to reviews with `launch reviews reply` (App Store) or `launch play-reviews reply` (Play) once you've read them.
+
+### AI-drafted store listing copy
+
+_Use when: draft / write the App Store or Play listing copy with AI; generate store description and keywords; improve the listing metadata; fill in store.config.json copy automatically._
+
+1. `npx launch ai listing` - draft App Store / Play listing copy with AI into store.config.json
+2. `npx launch plan` - review the drafted listing as a read-only diff against the live store
+3. `npx launch metadata push` - upload store.config.json to the live listing (metadata only; no binary)
+
+`ai listing` writes drafted copy into `store.config.json` only - it changes nothing live. Treat the draft as a starting point: read it, edit it, then preview before pushing.
+
+- Preview with `launch plan` (see the launch-plan skill) so you see exactly what the listing change would do before it goes out.
+- `metadata push` is what actually updates the live listing - gate it behind a human review of the AI copy.
+
+**Cautions:**
+- AI-drafted copy is a draft - review it for accuracy and brand voice before shipping. `metadata push` changes the LIVE store listing, so preview with `launch plan` and get confirmation first.
+
+### AI-generated store screenshots with Genshot
+
+_Use when: generate polished App Store or Google Play screenshots; turn real app screens into store marketing creatives; create localized screenshots with captions; prepare screenshots before syncing a store listing._
+
+1. `npx launch ai screenshots` - generate and validate store-ready screenshots from real screens; use --platform ios|android and --brief to steer the design
+2. `npx launch plan screenshots` - review the generated screenshot diff against the live store without writing
+3. `npx launch sync` - upload the reviewed screenshots with the rest of the declared listing
+
+Before generation, make sure the companion is available: `npm install --save-dev @genshot/cli`, then `npx genshot login`. Browser OAuth stores the Genshot credential in the user account config; never put an API key in `launch.config.ts`.
+
+- Put real source images under `<app>/screenshots/<locale>/<DISPLAY_TYPE>/`. Launch enhances those screens; it does not fabricate product UI.
+- `launch ai screenshots` delegates to Genshot, identifies Launch as the client source, validates every returned image against the selected store, and promotes approved files into the listing tree.
+- Use `--captions` for ordered marketing captions, `--locale` for localization, and `--device-types` only when overriding the supported default (`APP_IPHONE_67` for iOS or `phone` for Android).
+- Review with `launch plan screenshots`. Uploading remains the separate `launch sync` action and requires human confirmation.
+
+**Cautions:**
+- Genshot generation spends Credits. If the developer did not directly request generation, show the selected sources, platform, count, and brief and get approval before running it.
+- `launch sync` changes the LIVE store listing. Show the read-only screenshot plan and get explicit human confirmation before uploading.
+
+### Expose Launch to AI agents & a local dashboard
+
+_Use when: let Claude / Cursor drive Launch (set up MCP); open the local Launch dashboard; scaffold the Launch agent skills / rules into this repo; give an AI agent access to Launch._
+
+1. `npx launch mcp install` - wire `launch mcp` into an AI client's config (auto-detects Claude Code / Cursor)
+2. `npx launch dashboard` - serve a local, read-only web UI over apps, builds, accounts, and secrets
+3. `npx launch agents init` - write Claude skills, Cursor rules, and the AGENTS.md Launch section into this repo
+
+These are the on-ramps for agent-driven and at-a-glance use, all strictly local: `mcp install` exposes Launch's commands to an AI client, `dashboard` opens a read-only web view of your state, and `agents init` drops these very skills into the repo.
+
+- `dashboard` is read-only and `mcp install` only edits a local client config - neither touches the store.
+- `agents check` keeps the scaffolded skills in sync after Launch upgrades.
+<!-- launch:end -->