codebyplan 1.5.1 → 1.9.0

package/templates/skills/cbp-ship/SKILL.md

@@ -0,0 +1,332 @@
+---
+scope: org-shared
+name: cbp-ship
+description: Orchestrate runtime deployment for a checkpoint — Vercel web, EAS mobile (Expo Go dev build / TestFlight preview), Tauri desktop, npm package publish, VS Code extension, Railway backend, Supabase migrations. Detects configured surfaces, walks the user through what to deploy, executes per-surface deploy steps, verifies each landed.
+effort: xhigh
+---
+
+# Ship Command
+
+Single orchestrator for deploying a checkpoint to every runtime it has — web (Vercel), mobile (EAS / TestFlight), desktop (Tauri), npm packages, VS Code extension, backend (Railway), database migrations (Supabase).
+
+Step 1 of `/cbp-checkpoint-end` handles branch promotion to main via `/cbp-ship-main` (which runs `codebyplan ship`). Runtime deployment happens here, after the branch is already merged.
+
+## When to Use
+
+- Auto-called by `/cbp-checkpoint-end` after branch promotion to main completes
+- User-invokable directly when re-running shipment after a fix (e.g., "Vercel deploy failed, fix the env var, re-run `/cbp-ship`")
+- NOT for mid-checkpoint dev iteration — local development uses `npx expo start` / `pnpm dev` etc., not this skill
+
+## Inputs
+
+| Source                        | What's read                                                                               |
+| ----------------------------- | ----------------------------------------------------------------------------------------- |
+| MCP `get_current_task`        | Active checkpoint (for context.shipment write-back)                                       |
+| `.codebyplan/git.json` + `.codebyplan/shipment.json`            | `branch_config`, `shipment` section if present (per `ship-configure`)      |
+| Repo scan                     | Detect surfaces from filesystem (vercel.json, eas.json, package.json publishConfig, etc.) |
+| `checkpoint.context.shipment` | Last shipment record (timestamp, surfaces, results)                                       |
+
+## Instructions
+
+### Step 1 — Detect applicable surfaces
+
+Run the detection script:
+
+```bash
+bash "${CLAUDE_SKILL_DIR}/scripts/detect-surfaces.sh"
+```
+
+It emits JSON of the form:
+
+```json
+{
+  "surfaces": [
+    {
+      "id": "vercel-web",
+      "app_path": "apps/web",
+      "configured": true,
+      "reason": "vercel.json + .vercel/project.json present"
+    },
+    {
+      "id": "expo-mobile",
+      "app_path": "apps/mobile",
+      "configured": false,
+      "reason": "app.json present but eas.json missing"
+    },
+    {
+      "id": "tauri-desktop",
+      "app_path": "apps/desktop",
+      "configured": true,
+      "reason": "src-tauri/ + .github/workflows/release-desktop.yml present"
+    },
+    {
+      "id": "npm-package",
+      "app_path": "packages/codebyplan-package",
+      "configured": true,
+      "reason": "publishConfig.access set"
+    },
+    {
+      "id": "vscode-ext",
+      "app_path": "apps/vscode",
+      "configured": false,
+      "reason": "package.json contributes block missing publisher"
+    },
+    {
+      "id": "railway-backend",
+      "app_path": "apps/backend",
+      "configured": false,
+      "reason": "Dockerfile missing + railway.toml absent"
+    },
+    {
+      "id": "supabase",
+      "migrations_pending": 4,
+      "configured": true,
+      "reason": "supabase/migrations/ has 4 entries newer than last shipment"
+    }
+  ]
+}
+```
+
+Each surface is one of: `configured: true` (ready to ship), `configured: false` (detected but missing setup), or absent from the array (not detected at all — e.g., a repo with no mobile app).
+
+Surface catalog reference: [reference/surfaces.md](reference/surfaces.md).
+
+### Step 2 — Handle gaps for early-stage repos
+
+For each surface with `configured: false`, present the gap to the user:
+
+```
+[surface-id] detected at [app_path] but not configured for shipment.
+Reason: [reason]
+
+Options:
+A) Configure now via /cbp-ship-configure --surface=[id]
+B) Skip this surface for this checkpoint
+C) Mark "not shipping yet" — record in .codebyplan/shipment.json `disabled[]` (no future prompts)
+```
+
+Use AskUserQuestion. Skip is the safe default for first-stage repos — a Next.js app that's never been Vercel-linked shouldn't block checkpoint shipment. Choice C writes `{"disabled":["vercel-web"]}` to `.codebyplan/shipment.json` so subsequent checkpoints don't re-ask.
+
+If ALL detected surfaces are unconfigured AND the user picks Skip/Mark for all, exit with `## No deployable surfaces configured. Branch promotion already completed; runtime deploy skipped.` Do NOT treat this as failure.
+
+### Step 3 — Build the shipment plan
+
+For each surface with `configured: true`, determine the deploy variant:
+
+| Surface           | Variants                                                                                                                                                                                               |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `vercel-web`      | `production` (when shipping to PRODUCTION branch — Vercel auto-deploys), `preview` (Vercel auto-creates per-PR), `manual` (force redeploy via `vercel --prod`)                                         |
+| `expo-mobile`     | `expo-go` (dev build via `npx expo start`, no shipment — informational only), `eas-internal` (EAS build + TestFlight internal group), `eas-external` (TestFlight external — review-gated, opt-in only) |
+| `tauri-desktop`   | `tag-and-release` (push `v*.*.*` tag, GH Actions builds + signs) — variant matters only when version bumped this checkpoint                                                                            |
+| `npm-package`     | `publish` (only when `package.json` version bumped or release-please PR merged this checkpoint)                                                                                                        |
+| `vscode-ext`      | `vsce-publish` (only when version bumped)                                                                                                                                                              |
+| `railway-backend` | `deploy` (Railway redeploys on integration push if linked; manual `railway up` otherwise)                                                                                                              |
+| `supabase`        | `push-migrations` (only when pending count > 0) — interactive, walks user through diff/review/push                                                                                                     |
+
+For mobile: ask the user via AskUserQuestion which variant for THIS checkpoint:
+
+```
+Mobile shipment for this checkpoint:
+A) Skip — local dev only this checkpoint
+B) EAS build + TestFlight internal (preview to internal testers)
+C) EAS build + TestFlight external (review-gated, public-facing beta)
+```
+
+For all other surfaces, default to the variant that matches the branch the checkpoint just shipped to (`production` for main, `preview` for staging/integration). Don't ask unless the inferred variant is ambiguous (e.g., mobile, or version-gated surfaces where no version bump happened).
+
+### Step 4 — Confirm the shipment plan
+
+Present the plan in one block, ask for confirmation:
+
+```
+## Shipment Plan — Checkpoint CHK-NNN [title]
+
+Will deploy:
+- vercel-web (apps/web)              → production (auto-deploy on main merge)
+- expo-mobile (apps/mobile)          → eas-internal (TestFlight internal group)
+- supabase                           → push 4 pending migrations (interactive review)
+
+Will skip:
+- tauri-desktop  → no version bump this checkpoint
+- npm-package    → no version bump this checkpoint
+- vscode-ext     → not configured (run /cbp-ship-configure when ready)
+
+Confirm shipment? [yes / change / abort]
+```
+
+Use AskUserQuestion. On `change`, re-enter Step 3 with prior answers as defaults. On `abort`, write `checkpoint.context.shipment.aborted_at` and stop — caller (`/cbp-checkpoint-end`) treats abort as "do not call `/cbp-checkpoint-complete`."
+
+### Step 5 — Execute per-surface deploys
+
+For each confirmed surface, load the surface reference file and execute its deploy procedure:
+
+| Surface           | Reference                                                          |
+| ----------------- | ------------------------------------------------------------------ |
+| `vercel-web`      | [reference/surface-vercel.md](reference/surface-vercel.md)         |
+| `expo-mobile`     | [reference/surface-expo-eas.md](reference/surface-expo-eas.md)     |
+| `tauri-desktop`   | [reference/surface-tauri.md](reference/surface-tauri.md)           |
+| `npm-package`     | [reference/surface-npm.md](reference/surface-npm.md)               |
+| `vscode-ext`      | [reference/surface-vscode-ext.md](reference/surface-vscode-ext.md) |
+| `railway-backend` | [reference/surface-railway.md](reference/surface-railway.md)       |
+| `supabase`        | [reference/surface-supabase.md](reference/surface-supabase.md)     |
+
+Each reference file has a `## STEPS` section the orchestrator follows literally. When a step needs user input (npm OTP, TestFlight credentials, Supabase migration approval), use AskUserQuestion inline — do NOT batch user input upfront, because a user may need to abort after seeing one surface's prompt.
+
+Run surfaces sequentially in the order: `supabase` → `vercel-web` → `railway-backend` → `expo-mobile` → `tauri-desktop` → `vscode-ext` → `npm-package`. Database migrations first (web/backend depend on schema). Mobile/desktop/extension/npm later (independent tails).
+
+If a surface fails:
+
+- Capture the error in `shipment_results[surface_id]`
+- Continue with subsequent surfaces (don't block the whole shipment on one failure)
+- Surface the failure in the final report with a clear remediation hint
+
+EXCEPTION: `supabase` migration push failure halts the rest. Schema mismatch downstream is worse than partial shipment.
+
+### Step 6 — Verify each surface landed
+
+After each surface deploys, run its verification:
+
+```bash
+bash "${CLAUDE_SKILL_DIR}/scripts/verify-vercel.sh" "$VERCEL_DEPLOYMENT_ID"
+bash "${CLAUDE_SKILL_DIR}/scripts/verify-expo-eas.sh" "$EAS_BUILD_ID"
+bash "${CLAUDE_SKILL_DIR}/scripts/verify-railway.sh" "$RAILWAY_PROJECT_ID"
+bash "${CLAUDE_SKILL_DIR}/scripts/verify-supabase.sh" "$MIGRATION_VERSION"
+```
+
+Verification timeouts are conservative (Vercel: 5min, EAS: 30min, TestFlight processing: 15min). On timeout, mark `verification_pending` (not failure) — the deploy may still complete async.
+
+### Step 7 — Persist shipment record
+
+Write to `checkpoint.context.shipment` via MCP `update_checkpoint`:
+
+```json
+{
+  "shipment": {
+    "timestamp": "2026-04-29T14:32:00Z",
+    "surfaces": [
+      {
+        "id": "vercel-web",
+        "variant": "production",
+        "status": "verified",
+        "url": "https://codebyplan.com",
+        "deployment_id": "dpl_xyz"
+      },
+      {
+        "id": "expo-mobile",
+        "variant": "eas-internal",
+        "status": "verified",
+        "build_id": "abc123",
+        "testflight_group": "internal"
+      },
+      {
+        "id": "supabase",
+        "variant": "push-migrations",
+        "status": "verified",
+        "migrations_applied": [
+          "0083_add_x",
+          "0084_index_y",
+          "0085_rls_z",
+          "0086_view_w"
+        ]
+      }
+    ],
+    "skipped": [
+      { "id": "tauri-desktop", "reason": "no version bump" },
+      { "id": "vscode-ext", "reason": "not configured" }
+    ],
+    "aborted_at": null
+  }
+}
+```
+
+### Step 8 — Report
+
+```
+## Shipment Complete — CHK-NNN
+
+| Surface | Variant | Status | URL/ID |
+|---|---|---|---|
+| vercel-web | production | ✓ verified | https://codebyplan.com (dpl_xyz) |
+| expo-mobile | eas-internal | ✓ verified | TestFlight build #42 |
+| supabase | push-migrations | ✓ verified | 4 migrations applied |
+| tauri-desktop | — | ⊘ skipped | no version bump |
+| vscode-ext | — | ⊘ skipped | not configured |
+
+All shipments succeeded. Returning control to /cbp-checkpoint-end.
+```
+
+If any surface failed, the report leads with the failures and offers re-run paths:
+
+```
+## Shipment Partial — CHK-NNN
+
+✓ vercel-web (production) → https://codebyplan.com
+✗ expo-mobile (eas-internal) → BUILD FAILED: missing APPLE_TEAM_ID
+  Fix: /cbp-ship-configure --surface=expo-mobile, then re-run /cbp-ship
+⊘ tauri-desktop → skipped (no version bump)
+
+Checkpoint shipment is incomplete. /cbp-checkpoint-end will hold; resolve and re-run.
+```
+
+## Shipment Manifest in `.codebyplan/shipment.json` (optional)
+
+Repos can override default detection by adding entries to `.codebyplan/shipment.json`:
+
+```json
+{
+  "disabled": ["vscode-ext"],
+  "surfaces": {
+    "vercel-web": { "project_id": "prj_abc", "team_id": "team_xyz" },
+    "railway-backend": {
+      "project_id": "rl_123",
+      "service_id": "svc_456",
+      "platform": "railway"
+    },
+    "expo-mobile": {
+      "eas_project_id": "ea_789",
+      "default_testflight_group": "internal"
+    },
+    "supabase": { "project_ref": "abcdefgh", "skip_seed": true }
+  }
+}
+```
+
+When present, this overrides scan results. `ship-configure` writes here.
+
+## Key Rules
+
+- **Branch promotion happens BEFORE this skill** — `/cbp-checkpoint-end` calls `/cbp-ship-main` first (which runs `codebyplan ship`); this skill handles runtime deployment only, never branch promotion
+- **Sequential, not parallel** — surfaces deploy in defined order; supabase first
+- **One verification per surface** — never claim shipment without running the verify script
+- **AskUserQuestion inline, not batched** — user can abort mid-shipment
+- **Skip ≠ fail** — unconfigured surfaces are normal for early-stage repos; never block on them
+- **No mid-checkpoint invocation for dev builds** — local dev uses `npx expo start` / `pnpm dev`; this skill is end-of-checkpoint only
+- **Credentials never live in `.claude/`** — Apple keys, npm tokens, supabase access tokens stay in CLI session / keychain / GH secrets; this skill checks they're reachable, never stores them
+- **Read all platform names from config** — never hardcode "production"/"main"/"development"
+
+## Error Recovery
+
+| Failure                       | Action                                                                      |
+| ----------------------------- | --------------------------------------------------------------------------- |
+| Vercel deploy timeout         | Mark `verification_pending`, continue — Vercel async-deploys                |
+| EAS build failed (credential) | Stop mobile surface, surface error, continue other surfaces                 |
+| Supabase migration error      | HALT shipment — schema mismatch is worse than partial deploy                |
+| npm publish 2FA reject        | Stop npm surface, ask user to re-run with fresh OTP                         |
+| Railway deploy failed         | Continue, mark failed — backend can be re-deployed independently            |
+| All surfaces failed           | Write `shipment.aborted_at`, return failure to `/cbp-checkpoint-end` |
+
+## Additional resources
+
+- Surface catalog: [reference/surfaces.md](reference/surfaces.md)
+- Versioning rules: [reference/versioning.md](reference/versioning.md)
+- Pre-flight checklist: [reference/preflight-checklist.md](reference/preflight-checklist.md)
+- Configure setup: `/cbp-ship-configure`
+- Detection script: [scripts/detect-surfaces.sh](scripts/detect-surfaces.sh)
+
+## Integration
+
+- **Triggered by**: `/cbp-checkpoint-end` (auto, after branch promotion to main via `/cbp-ship-main`); user direct invocation for re-runs
+- **Reads**: MCP `get_current_task`, `.codebyplan/git.json` + `.codebyplan/shipment.json` (`branch_config` + `shipment`), filesystem scan
+- **Writes**: MCP `update_checkpoint` (context.shipment)
+- **Calls**: per-surface deploy via reference files (vercel CLI, eas CLI, supabase CLI, npm, vsce, railway CLI, gh release)
+- **Triggers**: returns control to caller — does NOT auto-trigger `/cbp-checkpoint-complete` (that's the caller's job)

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

@@ -0,0 +1,120 @@
+# Changesets — Overview
+
+`@changesets/cli` is a versioning + changelog tool optimized for monorepos with many published packages. Devs add a `.changeset/*.md` entry alongside their feature work describing which packages bump and how (major/minor/patch). An aggregator GH Action (`changesets/action`) opens a "Version Packages" PR that consolidates pending changesets into version bumps + CHANGELOG entries; merging that PR triggers `changeset publish` to npm.
+
+Used by the `npm-package` surface in `/cbp-ship` as one of three versioning modes — recommended for monorepos with 3+ published packages.
+
+Upstream: https://github.com/changesets/changesets
+
+## How `/cbp-ship` uses it
+
+The `npm-package` surface ([surface-npm.md](./surface-npm.md)) offers changesets as one of three versioning modes. When a repo opts in via `/cbp-ship-configure`:
+
+1. Configure runs `pnpm add -Dw @changesets/cli` + `npx changeset init` + scaffolds the workflow from `templates/workflow-changesets.yml`
+2. Devs run `pnpm changeset` after each feature, committing the resulting `.changeset/*.md` file
+3. The `changesets/action` workflow opens a "Version Packages" PR (or updates the existing one)
+4. Maintainer reviews + merges
+5. The action runs `pnpm changeset publish` which calls `pnpm publish -r` for every bumped package, with OIDC `--provenance`
+
+A pre-merge gate (`changeset status` in CI) prevents merges without an accompanying changeset for changes to published packages.
+
+## Changeset file format
+
+```markdown
+---
+"@codebyplan/cli": minor
+"@codebyplan/auth": patch
+---
+
+Add new export `foo` and fix bug in `bar`.
+```
+
+The frontmatter lists affected packages with bump types. The body becomes the changelog entry. Filenames are auto-generated (e.g. `funky-tigers-dance.md`) — random words to avoid merge conflicts when multiple devs add changesets in parallel.
+
+## Config
+
+`.changeset/config.json` essentials:
+
+```json
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": ["@codebyplan/web", "@codebyplan/backend"]
+}
+```
+
+| Field | Purpose |
+|---|---|
+| `access` | npm publish access (`public` for scoped public packages) |
+| `baseBranch` | Branch the aggregator PR is opened against |
+| `commit` | If `true`, commits version bumps directly; CBP keeps `false` for PR-based review |
+| `fixed` | Arrays of package names that always bump together as one unit (same version) |
+| `linked` | Arrays of packages that bump together but keep independent versions |
+| `updateInternalDependencies` | When pkg A depends on pkg B and B bumps, what version range update A gets |
+| `ignore` | Packages excluded from version-PR consideration (apps, internal-only) |
+
+## Workflow shape
+
+`templates/workflow-changesets.yml`:
+
+```yaml
+name: changesets
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+  id-token: write    # for npm OIDC trusted publishing
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: https://registry.npmjs.org
+      - run: pnpm install --frozen-lockfile
+      - uses: changesets/action@v1
+        with:
+          version: pnpm changeset version
+          publish: pnpm changeset publish
+          commit: 'chore(release): version packages'
+          title: 'chore(release): version packages'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_CONFIG_PROVENANCE: 'true'
+```
+
+Note `NPM_CONFIG_PROVENANCE: 'true'` — equivalent to `--provenance` on every publish. Combined with `id-token: write` and trusted publishing, no NPM_TOKEN is needed.
+
+## Common gotchas
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Forgotten changesets | Dev merged a PR without `pnpm changeset` | Add `changeset status` step in CI to fail PRs that touch published packages without a changeset |
+| Version PR conflicts | Two parallel branches both have changesets that bump the same package | Last-merged wins; the `changeset version` command consumes existing changesets, so the next aggregator run is clean |
+| Accidental publish of internal package | Forgot `"private": true` on an internal package | `npm unpublish` within 72h, OR `npm deprecate` after; add `"private": true` and ship |
+| `workspace:*` strings in tarball | Used `npm publish` instead of `pnpm publish` | Always use pnpm publish for workspace packages — it rewrites the protocol at pack time |
+
+## Comparison vs release-please
+
+See [versioning.md](./versioning.md) and [npm-publish-monorepo.md](./npm-publish-monorepo.md) for the full decision. Short version: changesets is the default for monorepos with many independent packages and mixed-contributor PRs; release-please is simpler when Conventional Commits are already enforced and there's a single (or few) tightly-coupled packages.
+
+## Pairs With
+
+- [surface-npm.md](./surface-npm.md) — npm publish surface that consumes bumped versions
+- [versioning.md](./versioning.md) — when changesets is the right pick
+- [npm-publish-monorepo.md](./npm-publish-monorepo.md) — pnpm-monorepo-specific config and pre-publish gates
+- `templates/workflow-changesets.yml` — workflow scaffold dropped by the configure skill

package/templates/skills/cbp-ship/reference/eas-cli-overview.md

@@ -0,0 +1,60 @@
+# EAS CLI — Overview
+
+`eas-cli` (latest stable: 16.21.0 family) is the command-line tool for Expo Application Services. It builds Expo / React Native apps in the cloud (`eas build`), submits them to TestFlight / Play Console (`eas submit`), pushes runtime updates over-the-air (`eas update`), and manages credentials (`eas credentials`). Required for any mobile shipment via the `expo-mobile` surface in `/cbp-ship`.
+
+Upstream docs: https://docs.expo.dev/eas/
+
+## Commands `/cbp-ship` actually calls
+
+The `expo-mobile` surface ([surface-expo-eas.md](./surface-expo-eas.md)) calls these:
+
+| Command | Purpose |
+|---|---|
+| `eas build --profile <name> --platform <p> --non-interactive --no-wait` | Kick off a cloud build; returns build IDs immediately |
+| `eas build:wait --build-id <id>` | Block until build reaches FINISHED state |
+| `eas build:view <id> --json` | Inspect build status (used by `verify-expo-eas.sh`) |
+| `eas submit --platform <p> --id <build-id> --non-interactive` | Upload finished build to TestFlight (iOS) / Play (Android) |
+| `eas submit:list --status finished --json` | Verify submission completed |
+| `eas credentials` | Interactive — Apple Distribution Certificate, Provisioning Profile, Push Notification Key, Android keystore |
+| `eas init` | Initialise EAS project (one-time, configure setup only) |
+| `eas whoami` | Probe — verify CLI auth |
+
+## Build profiles used
+
+Per `templates/eas.json` in this skill:
+
+| Profile | Distribution | Auto-increment | Use |
+|---|---|---|---|
+| `development` | internal (dev client) | none | Local dev iteration |
+| `preview` | internal | buildNumber | TestFlight internal group, fast feedback |
+| `production` | store | buildNumber | TestFlight external review → App Store |
+
+## Auth model
+
+EAS auth is a CLI session bound to an Expo account:
+
+- `eas login` — interactive browser auth, stores token at `~/.expo/state.json`
+- `EXPO_TOKEN` env var — for CI; bypasses interactive login
+- `eas whoami` — probe that auth is alive
+
+Unlike many CLIs, there is no "key file" — the session token IS the credential. Apple/Google credentials are stored separately, encrypted, on Expo's servers (managed via `eas credentials`).
+
+## Auto-increment behaviour
+
+When `eas.json` build profile sets `autoIncrement: "buildNumber"` (iOS) or `"versionCode"` (Android), EAS bumps the value remotely on each build. The bumped value is the source of truth — local `app.json` may show stale values until `eas build:configure` syncs them down. This is why CBP's mobile shipment never has the user manually bump build numbers; semver `expo.version` stays manual.
+
+## Common failure modes
+
+| Error | Cause | Fix |
+|---|---|---|
+| `Provisioning profile not found` | Apple credential drift | `eas credentials` → Apple → resync |
+| `EAS Build worker not available` | Quota or platform incident | Check https://status.expo.dev; wait + retry |
+| `Build failed: Native module link error` | Native module added to package.json without prebuild | `npx expo prebuild --clean`, commit, retry |
+| `eas submit` errors with "Invalid bundle" | `app.json` `bundleIdentifier` doesn't match ASC record | Verify ASC app record; bundle IDs are immutable once published |
+
+## Pairs With
+
+- [surface-expo-eas.md](./surface-expo-eas.md) — operational deploy steps (variants: expo-go-only / eas-internal / eas-external)
+- [testflight-overview.md](./testflight-overview.md) — what happens AFTER `eas submit` lands on App Store Connect
+- [testflight-automation.md](./testflight-automation.md) — ASC API key setup that EAS Submit consumes
+- `templates/eas.json` — canonical eas.json shape for CBP mobile apps

package/templates/skills/cbp-ship/reference/gh-cli-overview.md

@@ -0,0 +1,135 @@
+# GitHub CLI (`gh`) — Overview
+
+Reference for the `/cbp-ship` orchestrator and other shipment-surface skills. Authoritative manual: <https://cli.github.com/manual>.
+
+## What `gh` Is
+
+`gh` is GitHub's official command-line interface. It wraps the REST + GraphQL APIs in ergonomic subcommands (`gh pr`, `gh release`, `gh run`, `gh secret`, `gh api`) and authenticates against `github.com` or a GitHub Enterprise host.
+
+For CodeByPlan we use it for: PR creation/merge, release creation, secret management, watching workflow runs, and (for non-Vercel platforms) hitting the Deployments API.
+
+## Install
+
+| Platform | Command |
+|----------|---------|
+| macOS (Homebrew) | `brew install gh` |
+| macOS (MacPorts) | `sudo port install gh` |
+| Linux (apt) | `sudo apt install gh` (after adding the repo per <https://github.com/cli/cli/blob/trunk/docs/install_linux.md>) |
+| Windows (winget) | `winget install --id GitHub.cli` |
+| Direct | <https://github.com/cli/cli/releases> |
+
+Verify: `gh --version` (this worktree's pipelines target the latest stable; v2.x is the supported major).
+
+## Auth Flow
+
+### Initial login
+
+```bash
+gh auth login
+```
+
+Interactive prompts cover: hostname (`github.com` vs Enterprise), git protocol (HTTPS vs SSH), credential storage, browser-based vs token-based. The default path is web flow against `github.com` with HTTPS git protocol.
+
+### Headless / CI
+
+```bash
+echo "$GITHUB_TOKEN" | gh auth login --with-token
+```
+
+Or rely on env vars — `gh` honours `GITHUB_TOKEN` / `GH_TOKEN` automatically and skips the credential store entirely. Useful inside GitHub Actions where `${{ secrets.GITHUB_TOKEN }}` is already in scope.
+
+### Scopes
+
+Minimum scopes for the `gh` default flow: `repo`, `read:org`, `gist`. Shipment work additionally needs:
+
+| Scope | Why |
+|-------|-----|
+| `repo` | PR create/merge, release create, secret set (repo-level) |
+| `workflow` | Trigger / re-run workflows via `gh workflow run` |
+| `admin:org` | Org-level secrets via `gh secret set --org` |
+| `admin:public_key` | SSH key upload during `gh auth login` (skipped with `--skip-ssh-key`) |
+| `read:packages` / `write:packages` | Container/release asset interactions touching GHCR |
+
+Bump scopes on an existing login with:
+
+```bash
+gh auth refresh --scopes workflow,admin:org
+```
+
+### Status & switching
+
+```bash
+gh auth status                    # which host(s), which user, where token is stored
+gh auth switch --user <login>     # multi-account
+gh auth logout --hostname github.com
+```
+
+## Config Locations
+
+| Path | Purpose |
+|------|---------|
+| `~/.config/gh/config.yml` | Global preferences (editor, git_protocol, prompt) |
+| `~/.config/gh/hosts.yml` | Per-host auth state (token if insecure storage; otherwise pointer into OS keychain) |
+| `$XDG_CONFIG_HOME/gh/...` | Honoured if `XDG_CONFIG_HOME` is set |
+| OS keychain (macOS Keychain / Windows Credential Manager / `secret-tool` on Linux) | Default secure token storage |
+
+Inspect or override with `gh config get/set <key>`.
+
+## SSH vs HTTPS
+
+`gh auth login --git-protocol ssh|https` controls which URL form is written into git remotes. SSH requires either an existing key or `gh` generating one (it'll offer to upload it via the `admin:public_key` scope). HTTPS is simpler for headless contexts because git push reuses the `gh` token via the credential helper.
+
+The token used for `gh api` calls is independent of the git protocol — flipping between SSH and HTTPS does not re-auth the API.
+
+## GitHub Enterprise
+
+`gh` supports Enterprise Server out of the box:
+
+```bash
+gh auth login --hostname ghe.example.com
+```
+
+After login, every command honours an explicit `--hostname` flag or the `GH_HOST` env var. Repository references can be qualified inline:
+
+```bash
+gh pr list --repo ghe.example.com/team/repo
+```
+
+CodeByPlan production targets `github.com`; the Enterprise path is documented for completeness in case downstream consumers fork the pipeline.
+
+## Common Flags (Cross-Cutting)
+
+| Flag | Behaviour |
+|------|-----------|
+| `--repo <[HOST/]OWNER/REPO>` (`-R`) | Override the inferred repo. Required when running outside a checkout, or against a different repo than `origin`. |
+| `--json <fields>` | Switch a list/view command to JSON output. Field list is command-specific (`gh pr view --json` differs from `gh run view --json`). Pass `--json` with no value to discover available fields. |
+| `--jq <expr>` | Apply a `jq` expression to the JSON output server-side (in-process, no `jq` binary needed). |
+| `--template <go-tmpl>` | Apply a Go text/template instead of JSON output. |
+| `--web` | Open the browser to the equivalent UI page rather than performing the API action. |
+
+JSON + jq is the canonical pattern for scripting:
+
+```bash
+gh pr view 123 --json state,mergeable --jq '.state'
+```
+
+## The `gh api` Escape Hatch
+
+Anything not covered by a dedicated subcommand falls back to `gh api`:
+
+```bash
+gh api repos/{owner}/{repo}/deployments --method POST -f ref=main -f environment=production
+```
+
+`gh api` reuses the authenticated token, handles pagination (`--paginate`), supports both REST and GraphQL (`graphql` as the path), and accepts typed (`-F`) or raw (`-f`) fields. See [gh-cli-shipment-commands.md](./gh-cli-shipment-commands.md) for the deployment-specific invocation.
+
+## Where to Look Next
+
+- [gh-cli-shipment-commands.md](./gh-cli-shipment-commands.md) — exact shipment commands `/cbp-ship` runs, with flags, JSON shapes, and error modes
+- <https://cli.github.com/manual> — authoritative per-command reference (always reflects the latest release)
+- `gh <command> --help` — the same content, offline, pinned to your installed version
+
+## Pairs With
+
+- `/cbp-ship` skill (orchestrator that wraps these commands)
+- `.claude/rules/git-workflow.md` — branch / commit conventions that `gh pr create` must respect