codebyplan 1.5.1 → 1.9.0

package/templates/skills/cbp-ship/reference/surface-vscode-ext.md

@@ -0,0 +1,144 @@
+# Surface: vscode-ext
+
+Publish a VS Code extension to the Visual Studio Marketplace.
+
+## Detection
+
+Signals:
+
+- `package.json` with `engines.vscode` field present
+- `package.json` with `publisher` field present
+- A `.vsixmanifest` template or built `.vsix` may be present (optional)
+
+## Configured indicators
+
+`configured: true` requires:
+
+1. `package.json` has `name`, `displayName`, `publisher`, `version`, `engines.vscode`
+2. `vsce` CLI installed (`npx @vscode/vsce --version` succeeds)
+3. The user has a Personal Access Token (PAT) for the marketplace publisher
+4. `vsce verify-pat <publisher>` succeeds
+
+PAT scope required: "Marketplace → Manage" on Azure DevOps for the publisher.
+
+## Variants
+
+| Variant | When |
+|---|---|
+| `vsce-publish` | `package.json` version > marketplace version |
+| `skip` | No version bump |
+
+## STEPS — vsce-publish variant
+
+The `vsce` flow is similar to npm — token auth, the user runs the publish command for security.
+
+1. **Detect extension package**:
+   ```bash
+   EXT_PATH=$(find apps packages -maxdepth 3 -name package.json -exec sh -c \
+     'jq -e ".engines.vscode and .publisher" "$1" >/dev/null 2>&1 && dirname "$1"' _ {} \; | head -1)
+   ```
+
+2. **Check version vs marketplace**:
+   ```bash
+   PUBLISHER=$(jq -r .publisher "$EXT_PATH/package.json")
+   NAME=$(jq -r .name "$EXT_PATH/package.json")
+   LOCAL=$(jq -r .version "$EXT_PATH/package.json")
+   MARKET=$(npx @vscode/vsce show "$PUBLISHER.$NAME" --json 2>/dev/null | jq -r '.versions[0].version' || echo "")
+
+   [ "$LOCAL" = "$MARKET" ] && { echo "Already published"; exit 0; }
+   ```
+
+3. **Build the extension** (orchestrator-side):
+   ```bash
+   cd "$EXT_PATH"
+   pnpm run build       # if defined
+   ```
+
+4. **Package locally to verify** (no publish):
+   ```bash
+   cd "$EXT_PATH"
+   npx @vscode/vsce package --no-yarn -o "/tmp/$NAME-$LOCAL.vsix"
+   ```
+
+   If packaging fails (typical: missing icon, README too short), HALT — surface error.
+
+5. **Display publish command** for the user:
+   ```
+   ## VS Code Marketplace publish — manual step
+
+   Extension: $PUBLISHER.$NAME @ $LOCAL
+   Directory: $EXT_PATH
+
+   Run in your terminal:
+       cd $EXT_PATH
+       npx @vscode/vsce publish
+
+   You'll be prompted for the PAT if not cached. Reply 'done' when published, 'fail' if it errored.
+   ```
+
+6. **Verify publication**:
+   ```bash
+   sleep 30  # marketplace propagation
+   RESOLVED=$(npx @vscode/vsce show "$PUBLISHER.$NAME" --json | jq -r '.versions[0].version')
+   [ "$RESOLVED" = "$LOCAL" ] || { echo "Not yet visible — Marketplace can lag 1-5min"; exit 2; }
+   ```
+
+7. **Result**:
+   ```json
+   {
+     "status": "verified",
+     "extension": "publisher.name",
+     "version": "1.4.0",
+     "marketplace_url": "https://marketplace.visualstudio.com/items?itemName=publisher.name"
+   }
+   ```
+
+## Pre-release channel
+
+VS Code supports a "pre-release" channel via `vsce publish --pre-release`. Useful for staged rollouts:
+
+```bash
+npx @vscode/vsce publish --pre-release    # version must already include preid (e.g., 1.4.0-rc.1)
+```
+
+If the extension supports pre-release, the orchestrator asks the user which channel:
+
+```
+A) Stable channel — 1.4.0 → all users
+B) Pre-release channel — 1.4.0-rc.1 → users opted into pre-release
+```
+
+## Verification
+
+`scripts/verify-vscode-ext.sh`:
+
+```bash
+PUBLISHER_NAME="$1"  # e.g., publisher.name
+VERSION="$2"
+
+RESOLVED=$(npx @vscode/vsce show "$PUBLISHER_NAME" --json 2>/dev/null | jq -r '.versions[0].version')
+[ "$RESOLVED" = "$VERSION" ] || { echo "Not on marketplace: $VERSION (latest: $RESOLVED)"; exit 1; }
+
+# Activation events resolvable
+EVENTS=$(npx @vscode/vsce show "$PUBLISHER_NAME" --json | jq -r '.activationEvents | length // 0')
+[ "$EVENTS" -gt 0 ] || echo "WARN: no activation events declared — extension won't load"
+
+echo "OK"
+```
+
+## Common failures
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `vsce publish` fails with 401 | PAT expired or wrong scope | Regenerate PAT with "Marketplace → Manage" scope |
+| Package size > 50MB | `.vscodeignore` missing critical entries | Add `node_modules/**`, `*.test.*`, `.git/**` to `.vscodeignore` |
+| Icon validation fails | PNG must be ≥128×128 | Replace icon, ensure PNG format |
+| Marketplace 5xx during publish | Azure DevOps infra | Wait 5-10 min, retry |
+
+## Rollback
+
+`vsce unpublish <publisher>.<name> --force` removes the entire extension. To unpublish just one version, use the marketplace web UI → Manage Extension → Versions → remove. Surface as manual step.
+
+## Configure-once setup
+
+See `${CLAUDE_PLUGIN_ROOT}/skills/ship-configure/reference/vscode-ext.md` for first-time setup (publisher account creation, PAT generation, vsce login).

package/templates/skills/cbp-ship/reference/surfaces.md

@@ -0,0 +1,60 @@
+# Shipment Surface Catalog
+
+Authoritative list of every surface `/cbp-ship` knows how to deploy. The detection script (`scripts/detect-surfaces.sh`) maps repo signals to one of these IDs.
+
+## Surfaces
+
+| ID                | Runtime                         | Detection signal                                                                          | Deploy mechanism                                                                       | Reference                                      |
+| ----------------- | ------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| `vercel-web`      | Web (Next.js, static)           | `vercel.json` OR `.vercel/project.json` OR Next.js app under `apps/*` with `next` in deps | Auto-deploy on git push to linked branch + optional `vercel --prod` for force redeploy | [surface-vercel.md](surface-vercel.md)         |
+| `expo-mobile`     | Mobile (iOS/Android)            | `app.json` / `app.config.{ts,js}` AND `expo` in deps                                      | EAS Build → EAS Submit → TestFlight (iOS) / Play Console (Android)                     | [surface-expo-eas.md](surface-expo-eas.md)     |
+| `tauri-desktop`   | Desktop (macOS/Windows/Linux)   | `src-tauri/tauri.conf.json`                                                               | Push `v*.*.*` tag → GH Actions builds + signs + releases                               | [surface-tauri.md](surface-tauri.md)           |
+| `npm-package`     | Package distribution            | `package.json` with `private: false` OR `publishConfig` AND not under `apps/`             | `npm publish` from local (2FA) or GH Actions (OIDC trusted publishing)                 | [surface-npm.md](surface-npm.md)               |
+| `vscode-ext`      | VS Code Marketplace             | `package.json` with `engines.vscode` AND `publisher` field                                | `vsce publish` from local OR GH Actions workflow                                       | [surface-vscode-ext.md](surface-vscode-ext.md) |
+| `railway-backend` | Backend (NestJS / Node service) | `railway.toml` OR `railway.json` OR `.railway/` AND non-frontend `package.json`           | `railway up` from local OR auto-deploy on git push to linked branch                    | [surface-railway.md](surface-railway.md)       |
+| `supabase`        | Database migrations             | `supabase/migrations/` with at least one .sql newer than last shipment                    | `supabase db push` (interactive review of diff)                                        | [surface-supabase.md](surface-supabase.md)     |
+
+## Variant rules
+
+Each surface has variant choices that the orchestrator picks per-checkpoint:
+
+| Surface           | Variants                                       | Default rule                                                                                                 |
+| ----------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `vercel-web`      | `production`, `preview`, `manual-redeploy`     | `production` if shipped to PRODUCTION branch this checkpoint, else skip (preview already auto-created on PR) |
+| `expo-mobile`     | `expo-go-only`, `eas-internal`, `eas-external` | Always ASK — never default; mobile shipment is opt-in per checkpoint                                         |
+| `tauri-desktop`   | `tag-and-release`, `skip`                      | `tag-and-release` if version bump detected in `src-tauri/tauri.conf.json` or root, else `skip`               |
+| `npm-package`     | `publish`, `skip`                              | `publish` if `package.json` version is unpublished on registry, else `skip`                                  |
+| `vscode-ext`      | `vsce-publish`, `skip`                         | `vsce-publish` if version bump, else `skip`                                                                  |
+| `railway-backend` | `deploy`, `skip`                               | `deploy` if linked AND any service code changed this checkpoint, else `skip`                                 |
+| `supabase`        | `push-migrations`, `skip`                      | `push-migrations` if pending migration count > 0, else `skip`                                                |
+
+## Detection precedence
+
+When a surface signal is ambiguous (e.g., `apps/web` has both `vercel.json` and a `Dockerfile`), use this precedence:
+
+1. Explicit `.codebyplan/shipment.json` `surfaces.{id}` block — definitive
+2. Explicit `.codebyplan/shipment.json` `disabled[]` list — surface is hidden
+3. Filesystem signal in priority order (above table)
+4. Fallback — emit with `configured: false` and surface to user
+
+## Multiple instances of one surface
+
+A monorepo can have multiple instances of the same surface — e.g., `tarkur` ships 3 Vercel apps (`apps/homepage`, `apps/creator`, `apps/tenant`). Detection emits each as a separate entry:
+
+```json
+{ "id": "vercel-web", "instance": "apps/homepage", "configured": true }
+{ "id": "vercel-web", "instance": "apps/creator", "configured": true }
+{ "id": "vercel-web", "instance": "apps/tenant", "configured": true }
+```
+
+`/cbp-ship` deploys each instance independently and reports each separately.
+
+## Excluded by design
+
+These don't have surfaces because shipment doesn't apply:
+
+- `apps/cli` — bundled inside an npm package; ships via `npm-package`
+- `packages/auth`, `packages/design-tokens`, etc. — internal workspace packages, never published
+- Storybook builds — typically deployed as part of `vercel-web` (Storybook on Vercel) or skipped
+
+If a project genuinely needs a missing surface (Cloudflare Pages, Fly.io, Heroku, AWS Amplify), open a feedback report — adding a surface is a structured change to this catalog plus a new reference file plus detection signal.

package/templates/skills/cbp-ship/reference/testflight-automation.md

@@ -0,0 +1,215 @@
+# TestFlight Automation
+
+Automation contract for shipping to TestFlight from `/cbp-ship` (expo-mobile surface): App Store Connect API key setup, EAS Submit wiring, the common ITMS-90xxx error catalogue with remediations, build-expiration handling, and beta-group management via API.
+
+## App Store Connect API Key
+
+The API key replaces interactive Apple ID + 2FA prompts. It is the **only** sane authentication mechanism for CI / agent-driven submission.
+
+### Generation
+
+1. Sign in to [App Store Connect](https://appstoreconnect.apple.com/) as the Account Holder (or an Admin with the right permission).
+2. Navigate to **Users and Access → Integrations → App Store Connect API → Team Keys**.
+3. Click **Generate API Key**, give it a name (e.g. `cbp-ship-ci`), and pick an access role:
+   - **Developer** — sufficient for build upload + TestFlight distribution.
+   - **App Manager** — needed to create beta groups, manage testers, edit metadata.
+   - **Admin** — only if you also need account-level operations (rarely needed for `/cbp-ship`).
+4. Download the `.p8` private key file. **Apple shows this exactly once** — store it immediately in the secret manager.
+5. Note the **Key ID** (10-char alphanumeric, shown next to the key) and the **Issuer ID** (UUID, shown at the top of the API page — same for all keys on the team).
+
+You now have three secrets:
+
+| Field | Format | Where it lives |
+|---|---|---|
+| `ASC_API_KEY_ID` | 10-char string | Plain env var |
+| `ASC_API_ISSUER_ID` | UUID | Plain env var |
+| `ASC_API_KEY` (the `.p8` content) | PEM-encoded private key | Secret manager |
+
+Reference: [App Store Connect API — Get started](https://developer.apple.com/help/app-store-connect/get-started/app-store-connect-api/).
+
+### Rotation
+
+Keys do not expire automatically, but Apple recommends rotating annually. Revoke via the same Integrations page; no grace period — revoked keys 401 immediately. Plan rotations during low-ship windows.
+
+## EAS Submit Wiring
+
+EAS Submit is the canonical upload path for Expo apps. Configuration lives in `eas.json` under the `submit` profile.
+
+### Minimal `eas.json`
+
+```jsonc
+{
+  "submit": {
+    "production": {
+      "ios": {
+        "ascAppId": "1234567890",
+        "appleTeamId": "ABCDE12345",
+        "ascApiKeyPath": "./secrets/AuthKey_ABC1234567.p8",
+        "ascApiKeyId": "ABC1234567",
+        "ascApiKeyIssuerId": "11111111-2222-3333-4444-555555555555"
+      }
+    }
+  }
+}
+```
+
+- `ascAppId` — the numeric App Store Connect app ID (visible in the URL when viewing the app in ASC, NOT the bundle identifier).
+- `appleTeamId` — 10-char Team ID from the Apple Developer Portal **Membership** page.
+- `ascApiKey*` fields — the three values from key generation above. The `.p8` path is relative to the repo root.
+
+For CI, prefer the env-var form so the `.p8` doesn't get checked in:
+
+```jsonc
+{
+  "submit": {
+    "production": {
+      "ios": {
+        "ascAppId": "$ASC_APP_ID",
+        "ascApiKeyPath": "$ASC_API_KEY_PATH",
+        "ascApiKeyId": "$ASC_API_KEY_ID",
+        "ascApiKeyIssuerId": "$ASC_API_ISSUER_ID"
+      }
+    }
+  }
+}
+```
+
+The CI step writes `$ASC_API_KEY` (the PEM content) to a temp file and points `$ASC_API_KEY_PATH` at it.
+
+Reference: [EAS Submit — Submit to the Apple App Store](https://docs.expo.dev/submit/ios/).
+
+### Invocation
+
+```bash
+eas submit --platform ios --profile production --non-interactive
+```
+
+`--non-interactive` is required for agent-driven runs; it fails fast instead of prompting for missing credentials. Exit code 0 on successful upload (NOT on processing completion — see polling below).
+
+### Post-Upload Polling
+
+`eas submit` returns once the binary is handed off to App Store Connect. Apple's processing takes 10–15 minutes typically. To wait for `VALID` state, query `/v1/builds`:
+
+```
+GET /v1/builds?filter[app]={ascAppId}&filter[preReleaseVersion.version]={version}&sort=-uploadedDate&limit=1
+```
+
+Poll every 30 seconds. The `processingState` attribute transitions `PROCESSING` → `VALID` or `INVALID`. On `INVALID`, fetch the build's `buildBetaDetails` for the rejection reason.
+
+## Common ITMS-90xxx Errors
+
+These come back as email from Apple AND on the build record after upload. Capture and surface them in `/cbp-ship` failure output.
+
+| Code | Meaning | Remediation |
+|---|---|---|
+| ITMS-90034 | Missing or invalid signature | EAS credentials drift — run `eas credentials` and re-sync. Often caused by an expired distribution certificate. |
+| ITMS-90078 | Missing Push Notification Entitlement | `app.config` declares APNs capability but provisioning profile lacks it. Regenerate profile via `eas credentials`. |
+| ITMS-90161 | Invalid provisioning profile | Profile mismatch with bundle ID or team. Re-fetch via EAS. |
+| ITMS-90164 | Invalid code-signing entitlements | Entitlements in build don't match what the provisioning profile authorises. Common after adding capabilities (HealthKit, Background Modes) without regenerating the profile. |
+| ITMS-90189 | Redundant binary upload | Build number already used for this version. Increment `CFBundleVersion` and re-upload. Apple never lets a build number be reused. |
+| ITMS-90338 | Non-public API usage | A dependency uses a private symbol. Identify via the error's symbol list; usually a stale native module. Update or remove. |
+| ITMS-90683 | Missing Purpose String | Info.plist lacks a `NSXxxUsageDescription` for a permission the app declares. Add the string in `app.config` under `ios.infoPlist`. |
+| ITMS-90685 | CFBundleIdentifier collision | Two frameworks share a bundle ID. Usually a duplicated CocoaPod. Clean derived data and rebuild. |
+| ITMS-90713 | Missing Info.plist value | A required key (e.g. `CFBundleIconName`) is missing. Check `app.config` and `eas build` output. |
+| ITMS-91053 | Missing API declaration | New as of iOS 17 — privacy manifest required for certain "required reason" APIs (e.g. `UserDefaults`, `fileTimestamp`). Add `PrivacyInfo.xcprivacy` to the iOS bundle. |
+| ITMS-91061 | Missing privacy manifest | Same family as 91053 — the manifest file itself is absent. |
+| ITMS-4088 | Beta upload missing build | EAS submit uploaded but ASC didn't register the build. Often a transient ASC issue; retry. See [eas-cli#824](https://github.com/expo/eas-cli/issues/824). |
+
+When `/cbp-ship` sees an ITMS-90xxx error, it should:
+
+1. Capture the full error text from the ASC API response or email.
+2. Match against the table above for a known remediation.
+3. If unknown, surface to the user verbatim — do not guess.
+
+## Build Expiration Handling
+
+The 90-day rule (see [testflight-overview.md](./testflight-overview.md)) means long-running checkpoints risk silent expiry. Detection:
+
+```
+GET /v1/builds/{id}?fields[builds]=expirationDate,expired
+```
+
+`/cbp-ship` should:
+
+- On every ship, query the previous build's `expirationDate`. If `< now + 14 days`, log a warning so the user knows a refresh is imminent.
+- On `expired = true`, treat the previous TestFlight as gone — new testers will not be able to install. The next ship is no longer additive; it's a replacement.
+
+There is no API to extend expiry. The only remedy is a fresh upload.
+
+## Beta Groups via API
+
+Group management is necessary when a checkpoint introduces a new tester segment.
+
+### Create an internal group
+
+```
+POST /v1/betaGroups
+{
+  "data": {
+    "type": "betaGroups",
+    "attributes": {
+      "name": "Engineering",
+      "isInternalGroup": true,
+      "publicLinkEnabled": false
+    },
+    "relationships": {
+      "app": { "data": { "type": "apps", "id": "{ascAppId}" } }
+    }
+  }
+}
+```
+
+### Create an external group with public link
+
+```
+POST /v1/betaGroups
+{
+  "data": {
+    "type": "betaGroups",
+    "attributes": {
+      "name": "Public Beta",
+      "isInternalGroup": false,
+      "publicLinkEnabled": true,
+      "publicLinkLimitEnabled": true,
+      "publicLinkLimit": 1000
+    },
+    "relationships": {
+      "app": { "data": { "type": "apps", "id": "{ascAppId}" } }
+    }
+  }
+}
+```
+
+`publicLink` is returned in the response — that's the URL to share.
+
+### Assign a build to a group
+
+```
+POST /v1/betaGroups/{groupId}/relationships/builds
+{ "data": [{ "type": "builds", "id": "{buildId}" }] }
+```
+
+For external groups, the build must be `VALID` AND have an approved Beta App Review submission before assignment results in distribution.
+
+### Submit for Beta App Review
+
+```
+POST /v1/betaAppReviewSubmissions
+{
+  "data": {
+    "type": "betaAppReviewSubmissions",
+    "relationships": {
+      "build": { "data": { "type": "builds", "id": "{buildId}" } }
+    }
+  }
+}
+```
+
+Poll `/v1/betaAppReviewSubmissions/{id}` for `betaReviewState`: `WAITING_FOR_REVIEW` → `IN_REVIEW` → `APPROVED` / `REJECTED`. On rejection, fetch the rejection reason from the related `betaAppReviewDetails`.
+
+## References
+
+- [App Store Connect API — Get started](https://developer.apple.com/help/app-store-connect/get-started/app-store-connect-api/)
+- [EAS Submit — Submit to the Apple App Store](https://docs.expo.dev/submit/ios/)
+- [EAS Submit — Introduction](https://docs.expo.dev/submit/introduction/)
+- [TestFlight overview](https://developer.apple.com/help/app-store-connect/test-a-beta-version/testflight-overview/)

package/templates/skills/cbp-ship/reference/testflight-internal-vs-external.md

@@ -0,0 +1,69 @@
+# TestFlight — Internal vs External Testers
+
+When `/cbp-ship` lands a build on TestFlight, the orchestrator must decide which tester population to target. The two paths have different latency, audit, and access semantics. Pick the wrong one and either (a) the right people don't get the build, or (b) you wait 24+ hours on a Beta Review you didn't need.
+
+## The Core Trade-off
+
+| Dimension | Internal | External |
+|---|---|---|
+| Tester ceiling | 100 | 10,000 |
+| Identity | Apple ID on your App Store Connect team | Any email address |
+| Beta App Review | **Not required** | **Required** for first build of each version |
+| Time to availability after `VALID` | Minutes (push notification) | 24–48 hours typical (review queue) |
+| Public link | No | Yes (self-enrolment up to group cap) |
+| Tester role required | App Store Connect role: Account Holder, Admin, App Manager, Developer, or Marketing | None (no ASC account needed) |
+| Devices per tester | 30 | 30 |
+| Build expiry | 90 days | 90 days |
+| Auto-distribute on new build | Yes (per-group toggle) | Yes (per-group toggle), but each build still passes through review unless minor-change exemption applies |
+| Crash + feedback collection | Yes | Yes |
+| Cost | Free (within team) | Free |
+
+## Decision Table
+
+| Checkpoint scenario | Choose | Why |
+|---|---|---|
+| Engineering smoke-test before any external eyes | Internal | No review wait; team already has ASC accounts |
+| Daily / per-PR builds during active development | Internal | Review queue would block iteration speed |
+| Designer or PM previewing a feature pre-merge | Internal (add them as App Manager / Marketing role) | Avoids review delay for trusted reviewers |
+| Closed beta with a named friends-and-family list (≤100 people, all willing to be added to ASC) | Internal | Faster, simpler, no review |
+| Closed beta with >100 testers OR testers unwilling/unable to join ASC | External | Internal cap exceeded; ASC role not appropriate |
+| Public beta with a shareable signup link | External | Only external supports public links |
+| Marketing-driven preview to press / influencers | External | Don't grant ASC roles to non-employees |
+| Final pre-release rehearsal mirroring real-world install | External | Mirrors the post-launch update mechanic; flushes out review-time issues before App Store submission |
+| Region-restricted or audience-segmented rollouts | External (multiple groups) | Group-scoped distribution is the segmentation primitive |
+
+## Operational Notes
+
+### Internal-only fast-path
+
+If a checkpoint declares `testflight.audience: internal`, `/cbp-ship` should:
+
+1. `eas submit --platform ios` and wait for `VALID`.
+2. Verify the build is auto-assigned to the internal group(s) configured on the app (or assign explicitly via App Store Connect API `POST /v1/betaGroups/{id}/relationships/builds`).
+3. Stop. Skip the Beta Review submission step entirely. Surface the TestFlight install link to the user.
+
+### External path
+
+If `testflight.audience: external`:
+
+1. Run the internal-fast-path first (so the team gets the build immediately).
+2. Then submit for Beta App Review: `POST /v1/betaAppReviewSubmissions` with the build ID.
+3. Poll `betaAppReviewSubmissions/{id}` for state transitions (`WAITING_FOR_REVIEW` → `IN_REVIEW` → `APPROVED` / `REJECTED`).
+4. On approval, the build auto-distributes to assigned external groups (if the group's auto-notify is on).
+
+### Hybrid
+
+Most production checkpoints want both: internal testers get the build immediately for smoke-testing, then the same build goes to external review for the broader beta. This is the default unless the checkpoint explicitly opts out.
+
+## Common Mistakes
+
+- **Adding non-employees as internal testers.** They get an ASC role, which exposes more than intended. Use external groups instead.
+- **Submitting for Beta Review when only internal distribution is needed.** Wastes 24–48 hours and an Apple review slot.
+- **Assuming "external review approved" persists across versions.** It is per-version (technically per-`CFBundleShortVersionString`). A new marketing version requires a fresh review.
+- **Missing the encryption-export declaration.** External review will reject builds without `ITSAppUsesNonExemptEncryption` resolved. Internal builds are also blocked from distribution until resolved, even though no review is required.
+
+## References
+
+- [Add internal testers — App Store Connect Help](https://developer.apple.com/help/app-store-connect/test-a-beta-version/add-internal-testers/)
+- [Invite external testers — App Store Connect Help](https://developer.apple.com/help/app-store-connect/test-a-beta-version/invite-external-testers/)
+- [TestFlight overview — App Store Connect Help](https://developer.apple.com/help/app-store-connect/test-a-beta-version/testflight-overview/)

package/templates/skills/cbp-ship/reference/testflight-overview.md

@@ -0,0 +1,98 @@
+# TestFlight Overview
+
+TestFlight is Apple's first-party beta-distribution service for iOS, iPadOS, macOS, tvOS, visionOS, and watchOS apps. It is the **only** sanctioned path for distributing pre-release builds of an Expo / React Native iOS app to testers without going through the public App Store. For the `expo-mobile` surface of `/cbp-ship`, TestFlight is the terminal hop after `eas build --platform ios` produces a signed `.ipa`.
+
+## What TestFlight Is
+
+- A subsystem of App Store Connect — every TestFlight build is a real App Store Connect build record, with the same processing pipeline, export-compliance metadata, and version/build-number rules.
+- A separate iOS app (`TestFlight.app`) that testers install from the App Store; they receive a public link or email invitation to redeem.
+- The pre-flight gate for App Store review: the same binary uploaded to TestFlight is the one promoted to production. There is no separate "production-only" upload step — you promote the existing TestFlight build.
+
+Reference: [TestFlight overview — App Store Connect Help](https://developer.apple.com/help/app-store-connect/test-a-beta-version/testflight-overview/) and [developer.apple.com/testflight](https://developer.apple.com/testflight/).
+
+## Tester Categories
+
+TestFlight has two distinct tester populations with very different rules:
+
+### Internal Testers
+
+- Up to **100 internal testers** per app.
+- Must be App Store Connect users on your team with one of these roles: Account Holder, Admin, App Manager, Developer, or Marketing.
+- **No Beta App Review required** — builds are available to internal testers as soon as Apple finishes processing the upload (typically 10–15 minutes).
+- Identified by Apple ID (the address tied to their App Store Connect account).
+
+Reference: [Add internal testers](https://developer.apple.com/help/app-store-connect/test-a-beta-version/add-internal-testers/).
+
+### External Testers
+
+- Up to **10,000 external testers** per app, organised into groups (max 100 groups, up to 10,000 testers per group, with the 10K cap shared across the app).
+- Anyone with a valid email address — no App Store Connect account required.
+- **First build per version requires Beta App Review** by Apple (typically 24–48 hours, sometimes same-day, occasionally several days).
+- Subsequent builds with the same version may auto-pass review if the changes are minor (Apple's discretion).
+- Public link distribution is supported — anyone with the link can self-enrol up to the group cap.
+
+Reference: [Invite external testers](https://developer.apple.com/help/app-store-connect/test-a-beta-version/invite-external-testers/).
+
+## Processing Pipeline
+
+After `eas submit --platform ios` (or any upload tool) hands the `.ipa` to App Store Connect:
+
+1. **Upload** — Transporter / `altool` / EAS streams the `.ipa` to App Store Connect. Returns immediately with a build record in `PROCESSING` state.
+2. **Apple processing** — Apple validates the binary, extracts dSYMs, scans for export-compliance and missing-Info.plist keys, and re-signs as needed. Usually 10–15 minutes; can stretch to an hour during peak windows. State transitions: `PROCESSING` → `VALID` (or `INVALID` with ITMS error).
+3. **Compliance gate** — Build must declare encryption-export compliance. Set `ITSAppUsesNonExemptEncryption = false` in `Info.plist` (or `app.config` `ios.config.usesNonExemptEncryption`) for the auto-pass on standard HTTPS-only apps; otherwise App Store Connect will block distribution until you answer the encryption questionnaire.
+4. **Internal availability** — Once `VALID`, the build appears in TestFlight for any internal-tester group it's been assigned to. Manual assignment is required unless auto-distribute is enabled on the group.
+5. **External submission** — To distribute externally, submit the build for Beta App Review (separate from internal availability). On approval, the build is pushed to assigned external groups.
+
+## Build Expiration — the 90-Day Rule
+
+Every TestFlight build expires **90 days after upload**, regardless of tester activity. Expired builds:
+
+- Cannot be installed by new testers.
+- Existing installs continue to work but receive no updates.
+- Must be replaced by uploading a fresh build (incremented build number).
+
+Implication for `/cbp-ship`: a checkpoint that ships to TestFlight on day 0 will be unavailable to new testers on day 91. If the cadence between TestFlight ship and App Store promotion exceeds 90 days, plan for a refresh build.
+
+## Version and Build Number Rules
+
+App Store Connect enforces:
+
+- `CFBundleShortVersionString` (marketing version, e.g. `1.4.2`) — must match or exceed the latest version of this app.
+- `CFBundleVersion` (build number, e.g. `42`) — must be **strictly greater** than every previous build for the same `CFBundleShortVersionString`. Once a build number is uploaded, it can never be reused for that version, even if the upload was rejected.
+- EAS auto-increments build numbers when `cli.appVersionSource = remote` in `eas.json` and `autoIncrement = true` in the build profile. Verify before assuming.
+
+## Device Limits per Tester
+
+A single tester (Apple ID) can install TestFlight builds on up to **30 devices**. This is per-tester, not per-app. Not to be confused with the 100-device limit on the Apple Developer Program account (which applies to ad-hoc / development provisioning, NOT TestFlight).
+
+## Relationship to App Store Connect API
+
+The App Store Connect API exposes TestFlight as a set of REST resources:
+
+- `/v1/builds` — list / query builds, including processing state and expiry date.
+- `/v1/betaGroups` — internal and external group CRUD.
+- `/v1/betaTesters` — invite / remove individual testers.
+- `/v1/buildBetaDetails` and `/v1/betaAppReviewSubmissions` — submit a build for external review.
+- `/v1/preReleaseVersions` — query version groupings.
+
+Authentication uses an issuer-scoped JWT signed with a `.p8` private key. See [testflight-automation.md](./testflight-automation.md) for the full automation contract.
+
+Reference: [App Store Connect API — Get started](https://developer.apple.com/help/app-store-connect/get-started/app-store-connect-api/).
+
+## Where TestFlight Fits in `/cbp-ship` (expo-mobile)
+
+```
+eas build --platform ios          → produces signed .ipa
+eas submit --platform ios         → uploads to App Store Connect (TestFlight)
+                                    [10–15 min processing]
+internal group auto-distribute    → testers get push notification
+[optional] beta review submission → 24–48h, then external groups receive build
+```
+
+The `/cbp-ship` orchestrator owns the trigger (`eas submit`) and the wait-loop (poll build state until `VALID`). It does NOT own the Beta Review submission decision — that is gated on whether the checkpoint targets external testers, which is metadata on the checkpoint itself.
+
+## See also
+
+- [testflight-internal-vs-external.md](./testflight-internal-vs-external.md) — picking the right tester population per checkpoint
+- [testflight-automation.md](./testflight-automation.md) — ASC API key + EAS Submit + ITMS error catalogue + beta groups via API
+- [surface-expo-eas.md](./surface-expo-eas.md) — the `/cbp-ship` deploy steps that consume this content