codebyplan 1.5.1 → 1.8.0

package/templates/skills/cbp-ship/reference/surface-tauri.md

@@ -0,0 +1,138 @@
+# Surface: tauri-desktop
+
+Build, sign, notarize, and release a Tauri desktop app via GitHub Actions tag-trigger.
+
+This surface file is the orchestrator's interface to the Tauri release pipeline — secrets, CI workflow, signing, notarization, and gotchas are all covered in the sections below.
+
+## Detection
+
+Signals:
+
+- `src-tauri/tauri.conf.json` present
+- `apps/desktop/src-tauri/` (monorepo) — instance is `apps/desktop`
+
+## Configured indicators
+
+`configured: true` requires:
+
+1. `src-tauri/tauri.conf.json` parseable, with `productName` + `version`
+2. `.github/workflows/release-desktop.yml` (or similar tag-trigger workflow) present
+3. Required GitHub secrets set (per architecture doc — 9 secrets for the WBP setup)
+4. `gh auth status` succeeds (CLI authenticated)
+
+Probe: `gh secret list -R OWNER/REPO` and check that the 9 secret names from the architecture doc are present.
+
+## Variants
+
+| Variant | When |
+|---|---|
+| `tag-and-release` | Version bump detected in `src-tauri/tauri.conf.json` `version` OR root `package.json` |
+| `skip` | No version change since last shipment — desktop releases are tag-driven, not branch-driven |
+
+## STEPS — tag-and-release variant
+
+1. **Read version from tauri config**:
+   ```bash
+   VERSION=$(jq -r .version "$APP_PATH/src-tauri/tauri.conf.json")
+   ```
+
+2. **Verify tag doesn't already exist**:
+   ```bash
+   git fetch origin --tags
+   if git rev-parse "v$VERSION" >/dev/null 2>&1; then
+     echo "Tag v$VERSION already exists — skip or bump version"; exit 1
+   fi
+   ```
+
+3. **Confirm with user** via AskUserQuestion:
+   ```
+   Push tag v$VERSION? This triggers GH Actions build + sign + notarize + release.
+   The build takes ~15 min. You'll receive a GH Releases page when complete.
+   A) Push tag — start the release
+   B) Skip — bump version in another commit first
+   ```
+
+4. **Push the tag**:
+   ```bash
+   git tag -a "v$VERSION" -m "Release v$VERSION"
+   git push origin "v$VERSION"
+   ```
+
+5. **Get the workflow run** triggered by the tag:
+   ```bash
+   sleep 5  # GH Actions registration lag
+   RUN_ID=$(gh run list --workflow=release-desktop.yml --limit 1 --json databaseId,headBranch,event \
+     | jq -r ".[] | select(.event == \"push\" and .headBranch == \"v$VERSION\") | .databaseId")
+   ```
+
+6. **Watch the run** (15 min cap):
+   ```bash
+   gh run watch "$RUN_ID" --exit-status
+   ```
+
+7. **Verify GH Release was created**:
+   ```bash
+   gh release view "v$VERSION" --json assets,publishedAt | jq
+   ```
+   Expect: 2 assets minimum (ARM .dmg + Intel .dmg) for macOS-only builds; more for Win/Linux if configured.
+
+8. **Result**:
+   ```json
+   {
+     "status": "verified",
+     "version": "v1.4.0",
+     "release_url": "https://github.com/OWNER/REPO/releases/tag/v1.4.0",
+     "assets": ["WorkByPlan_1.4.0_aarch64.dmg", "WorkByPlan_1.4.0_x64.dmg"],
+     "workflow_run_id": "1234567890"
+   }
+   ```
+
+## Verification
+
+`scripts/verify-tauri.sh`:
+
+```bash
+VERSION="$1"
+
+# Tag exists locally + remote
+git rev-parse "v$VERSION" >/dev/null 2>&1 || { echo "Tag missing"; exit 1; }
+git ls-remote --tags origin "v$VERSION" | grep -q . || { echo "Tag not pushed"; exit 1; }
+
+# GH Release published
+PUBLISHED=$(gh release view "v$VERSION" --json publishedAt -q .publishedAt 2>/dev/null)
+[ -n "$PUBLISHED" ] || { echo "Release not published"; exit 1; }
+
+# At least one signed .dmg in assets
+ASSETS=$(gh release view "v$VERSION" --json assets -q '.assets | length')
+[ "$ASSETS" -ge 1 ] || { echo "No release assets"; exit 1; }
+
+# Updater manifest (latest.json) updated — Tauri auto-update needs this
+gh release view "v$VERSION" --json assets -q '.assets[].name' | grep -q "latest.json" \
+  || echo "WARN: latest.json missing from release — auto-update may not work"
+
+echo "OK"
+```
+
+## Common failures
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Workflow fails at "Notarize" step | Apple API key file path issue | See architecture doc § "Apple Notarization Key" — `.p8` content must be written to a file path, not passed as string |
+| `latest.json` missing | Tauri updater config disabled in tauri.conf.json | Enable `tauri.bundle.updater` |
+| ARM/Intel asset missing | matrix build for one arch failed | Check workflow logs; commonly Rust toolchain issue on the failed runner |
+| "Invalid signing identity" | `APPLE_SIGNING_IDENTITY` secret has wrong format | Must be exact match: `Developer ID Application: Name (TEAMID)` |
+| Public download URL broken | Vercel Blob upload step failed | Check `BLOB_READ_WRITE_TOKEN` secret + Vercel storage quota |
+
+## Rollback
+
+Tauri's auto-updater honors the most recent `latest.json` published. To rollback:
+
+1. Delete the bad release: `gh release delete v$VERSION --yes`
+2. Republish a prior tag: `gh release create v$PRIOR --notes "Republish after rollback" $PRIOR_ASSETS`
+3. The auto-updater will roll users back at their next launch
+
+The orchestrator surfaces this as an option when verification fails.
+
+## Configure-once setup
+
+See `${CLAUDE_PLUGIN_ROOT}/skills/ship-configure/reference/tauri-desktop.md` for first-time setup (Apple Developer cert, key generation, secrets upload, workflow scaffolding).

package/templates/skills/cbp-ship/reference/surface-vercel.md

@@ -0,0 +1,124 @@
+# Surface: vercel-web
+
+Deploy a Next.js (or static) app to Vercel.
+
+## Detection
+
+Signals (any one is sufficient):
+
+- `vercel.json` at app root
+- `.vercel/project.json` at app root (links repo to Vercel project)
+- App directory contains `next` in `package.json` dependencies AND no other surface signal claims it
+
+A repo can have multiple `vercel-web` instances — one per app folder under `apps/*`.
+
+## Configured indicators
+
+`configured: true` requires:
+
+1. `.vercel/project.json` present with `projectId` and `orgId`
+2. Vercel CLI authenticated (`vercel whoami` succeeds)
+3. `.codebyplan/shipment.json` `.surfaces.vercel-web.{instance}` block (optional but recommended)
+
+If `.vercel/project.json` is missing → `configured: false`, reason "not linked to Vercel project — run /cbp-ship-configure".
+
+## Variant: production
+
+Default for shipping to PRODUCTION branch (per `branch_config.production`). Vercel auto-deploys on push to the linked production branch — this variant **observes** the auto-deploy, doesn't trigger it.
+
+### STEPS — production variant
+
+1. **Read project ID** from `.vercel/project.json`:
+   ```bash
+   PROJECT_ID=$(jq -r .projectId .vercel/project.json)
+   ORG_ID=$(jq -r .orgId .vercel/project.json)
+   ```
+
+2. **Get the deployment triggered by the merge commit**:
+   ```bash
+   MERGE_SHA=$(git rev-parse HEAD)
+   DEPLOYMENT=$(vercel ls --json 2>/dev/null | jq -r ".[] | select(.meta.githubCommitSha == \"$MERGE_SHA\") | .uid" | head -1)
+   ```
+
+   If no deployment found within 60s, Vercel is slow — wait up to 5min:
+   ```bash
+   timeout 300 bash -c "while ! vercel ls --json | jq -e '.[] | select(.meta.githubCommitSha == \"$MERGE_SHA\")' > /dev/null; do sleep 10; done"
+   ```
+
+3. **Wait for READY state**:
+   ```bash
+   vercel inspect "$DEPLOYMENT" --wait
+   ```
+
+4. **Capture URL + readyState**:
+   ```bash
+   STATUS=$(vercel inspect "$DEPLOYMENT" --json | jq -r '.readyState')
+   URL=$(vercel inspect "$DEPLOYMENT" --json | jq -r '.alias[0] // .url')
+   ```
+
+5. **Result**: `{ status: STATUS, url: URL, deployment_id: DEPLOYMENT }` to orchestrator.
+
+## Variant: manual-redeploy
+
+For "the auto-deploy failed, force a redeploy" path. User triggers explicitly.
+
+### STEPS — manual-redeploy variant
+
+```bash
+cd "$APP_PATH"
+vercel --prod --yes
+```
+
+Capture deployment ID from output, then run Steps 3–5 from production variant.
+
+## Variant: preview
+
+Vercel auto-creates a preview deployment per PR. The orchestrator typically does NOT need to trigger anything for staging shipments — but it CAN verify the preview deployment for the integration branch:
+
+```bash
+INTEGRATION=$(jq -r .branch_config.integration .codebyplan/git.json)
+INTEGRATION_SHA=$(git rev-parse "origin/$INTEGRATION")
+vercel ls --json | jq ".[] | select(.meta.githubCommitSha == \"$INTEGRATION_SHA\" and .target == \"preview\")"
+```
+
+## Verification
+
+`scripts/verify-vercel.sh` does:
+
+1. `vercel inspect "$DEPLOYMENT_ID" --json | jq -r .readyState` returns `READY`
+2. `curl -sI "$URL" | head -1` returns `HTTP/2 200` (or 401 for password-protected previews — also success)
+3. If `apps/{instance}/public/health.json` or `/api/health` exists, hit it: expect 200
+
+Timeouts:
+- Build: 5 min (Vercel Hobby is slower; allow 8 min)
+- HTTP probe: 30s
+
+## Common failures
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `vercel ls` shows no deployment for the merge SHA | GitHub integration not connected, or push didn't trigger | Check Vercel dashboard → Settings → Git; reconnect if needed |
+| Build fails with "Module not found" | Monorepo root not configured | In Vercel project settings: Build Command → `cd ../.. && pnpm turbo build --filter={instance}`, Root Directory → `apps/{instance}` |
+| Preview URL 404s | Project paused or env var missing | Check Vercel logs for the deployment; common: missing `DATABASE_URL` |
+| Build succeeds but page is blank | Production env vars missing | `vercel env ls production` — compare to `.env.example` |
+
+## Rollback
+
+```bash
+vercel rollback                    # interactive: pick a prior deployment
+vercel promote "$PRIOR_DEPLOYMENT" # promote a specific deployment to production
+```
+
+The orchestrator surfaces this as an option when a verification fails:
+
+```
+Vercel deployment failed verification.
+Options:
+A) Retry — the deploy may complete async
+B) Rollback to prior production deployment
+C) Investigate manually — show me the build logs
+```
+
+## Configure-once setup
+
+See `${CLAUDE_PLUGIN_ROOT}/skills/ship-configure/reference/vercel.md` for first-time setup (vercel link, env var sync, GH integration verification).

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/)