codebyplan 1.5.0 → 1.8.0

package/templates/skills/cbp-ship/reference/surface-expo-eas.md

@@ -0,0 +1,155 @@
+# Surface: expo-mobile
+
+Build mobile apps via EAS and deliver via TestFlight (iOS) / Play Console internal testing (Android).
+
+**Local development uses `npx expo start`, not this surface.** This file covers checkpoint-end shipment only.
+
+## Detection
+
+Signals:
+
+- `app.json` or `app.config.{ts,js}` at repo root or `apps/mobile/`
+- `expo` in `package.json` dependencies
+- `eas.json` (configured) OR `app.json` with no `eas.json` (detected but not configured)
+
+## Configured indicators
+
+`configured: true` requires:
+
+1. `eas.json` present with at least one build profile (`development`, `preview`, `production` are conventional)
+2. `app.json` has `expo.slug`, `expo.name`, `expo.ios.bundleIdentifier`, `expo.android.package`
+3. `eas-cli` installed (`npx eas --version` succeeds)
+4. `eas whoami` returns a logged-in user
+5. `.codebyplan/shipment.json` `.surfaces.expo-mobile` block present with `eas_project_id`
+
+Reference: [eas-cli-overview.md](./eas-cli-overview.md) for EAS CLI commands. Library docs via DocsByPlan MCP (`resolve_library_id('expo')`).
+
+## Variants
+
+Mobile shipment is **always opt-in per checkpoint** — `/cbp-ship` asks the user which variant for THIS checkpoint:
+
+| Variant | What it does | When to use |
+|---|---|---|
+| `expo-go-only` | Marks "no shipment, dev via Expo Go only" — informational | Early development, no internal testers yet |
+| `eas-internal` | EAS Build (preview profile) → submit to TestFlight internal group | Internal team review, fast iteration |
+| `eas-external` | EAS Build (production profile) → TestFlight external (review-gated) | Public-facing beta, requires Apple review |
+
+App Store production submission is **NOT yet supported** by this skill — manually via App Store Connect when ready.
+
+## STEPS — eas-internal variant
+
+1. **Confirm intent** (already done by orchestrator's variant prompt — skip if already confirmed)
+
+2. **Auto-bump build numbers** (per `versioning.md`):
+   ```bash
+   cd "$APP_PATH"
+   # iOS buildNumber and Android versionCode auto-incremented by EAS by default
+   # if eas.json has "autoIncrement": "buildNumber" / "versionCode" — verify:
+   jq -r '.build.preview.autoIncrement // "manual"' eas.json
+   ```
+   If `manual`, prompt user to bump `app.json` `expo.ios.buildNumber` / `expo.android.versionCode` first.
+
+3. **Run EAS Build (preview profile, both platforms)**:
+   ```bash
+   cd "$APP_PATH"
+   eas build --profile preview --platform all --non-interactive --no-wait
+   ```
+   Capture the build IDs from output:
+   ```
+   iOS:     https://expo.dev/.../builds/IOS_BUILD_ID
+   Android: https://expo.dev/.../builds/ANDROID_BUILD_ID
+   ```
+
+4. **Wait for builds to complete** (10–25 min typical):
+   ```bash
+   eas build:wait --build-id "$IOS_BUILD_ID"
+   eas build:wait --build-id "$ANDROID_BUILD_ID"
+   ```
+   On failure, surface the build URL and stop this surface.
+
+5. **Submit iOS to TestFlight internal group**:
+   ```bash
+   eas submit --platform ios --id "$IOS_BUILD_ID" --non-interactive
+   ```
+   This uploads to App Store Connect. The build then enters Apple's processing queue (5–30 min).
+
+6. **Submit Android to Play internal track**:
+   ```bash
+   eas submit --platform android --id "$ANDROID_BUILD_ID" --non-interactive
+   ```
+
+7. **Wait for TestFlight processing** (iOS only — Android internal track is faster):
+   - The orchestrator waits up to 15 min, polling via App Store Connect API.
+   - On timeout: mark `verification_pending` (not failure) — Apple sometimes takes longer.
+
+8. **Result**:
+   ```json
+   {
+     "status": "verified",
+     "ios": { "build_id": "...", "testflight_group": "internal", "version": "1.4.0 (124)" },
+     "android": { "build_id": "...", "play_track": "internal", "version": "1.4.0 (124)" }
+   }
+   ```
+
+## STEPS — eas-external variant
+
+Same as `eas-internal` through Step 4. Then:
+
+5. **Submit iOS to TestFlight external** — requires Apple Beta Review (1–2 days):
+   ```bash
+   eas submit --platform ios --id "$IOS_BUILD_ID" --non-interactive
+   # In App Store Connect → TestFlight → External Group → add this build
+   # External submissions trigger Apple Beta Review automatically
+   ```
+
+6. **Submit Android to Play external testing track** (closed/open):
+   ```bash
+   eas submit --platform android --id "$ANDROID_BUILD_ID" --non-interactive --track beta
+   ```
+
+7. **Surface a notice** — external review is async; the orchestrator marks `verification_async` and reports back the App Store Connect URL for the user to monitor.
+
+## STEPS — expo-go-only variant
+
+No actual shipment. Record in shipment context:
+
+```json
+{ "status": "skipped_intentionally", "reason": "expo-go-only — local dev via npx expo start", "next_checkpoint_default": "ask-again" }
+```
+
+## Verification
+
+`scripts/verify-expo-eas.sh`:
+
+```bash
+BUILD_ID="$1"
+PROFILE="$2"  # internal | external
+
+# Build status
+STATUS=$(eas build:view "$BUILD_ID" --json | jq -r .status)
+[ "$STATUS" = "FINISHED" ] || { echo "Build not finished: $STATUS"; exit 1; }
+
+# Submission status (TestFlight processing)
+SUBMISSION=$(eas submit:list --status finished --json | jq -r ".[] | select(.buildId == \"$BUILD_ID\") | .status" | head -1)
+[ "$SUBMISSION" = "finished" ] && exit 0
+
+echo "Submission status: $SUBMISSION (Apple processing async — verification pending)"
+exit 2  # treat as verification_pending, not failure
+```
+
+## Common failures
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `eas build` errors with "Provisioning profile not found" | Apple credentials sync needed | `eas credentials` → Manage credentials → Apple Distribution Certificate |
+| TestFlight build stuck in "Processing" >1hr | Apple infra; may also indicate ITMS-90xxx warning | Check App Store Connect → Activity for the build; resubmit if needed |
+| `eas submit` errors "Invalid bundle" | `app.json` `bundleIdentifier` doesn't match App Store Connect record | Verify match in ASC; or create new ASC app record |
+| Build fails with "EXC_BAD_ACCESS" on TestFlight | Native module crash; not detectable in dev client | Use `eas build --profile development` + Sentry to debug |
+
+## Rollback
+
+TestFlight builds can be revoked via App Store Connect → TestFlight → Build → Expire. EAS doesn't support this from CLI. Surface to user as a manual step.
+
+## Configure-once setup
+
+See `${CLAUDE_PLUGIN_ROOT}/skills/ship-configure/reference/expo-mobile.md` for first-time setup (Apple Developer enrollment, ASC API key, EAS project init, eas.json scaffold).

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

@@ -0,0 +1,180 @@
+# Surface: npm-package
+
+Publish a package to the npm registry.
+
+## Detection
+
+Signals (all must hold):
+
+- `package.json` with `private: false` (or `private` absent — defaults to publishable)
+- Package is NOT under `apps/*` (apps are not published)
+- Either `publishConfig` is set, OR the package has explicit `name` + `version`
+- Workspace internal-only packages (`packages/auth`, `packages/design-tokens`) are excluded by listing them in `.codebyplan/shipment.json` `disabled[]`
+
+## Configured indicators
+
+`configured: true` requires:
+
+1. `package.json` has `name`, `version`, `main`/`exports`, `files` field
+2. `npm whoami` succeeds (logged in to registry)
+3. Package version on registry differs from local: `npm view <name>@<local-version>` returns 404 (or different SHA)
+4. 2FA is enabled on the npm account (verified via `npm profile get tfa` returning `auth-and-writes`)
+
+Reference: [npm-publish-overview.md](./npm-publish-overview.md), [npm-publish-oidc-trusted.md](./npm-publish-oidc-trusted.md), [npm-publish-monorepo.md](./npm-publish-monorepo.md).
+
+## Variants
+
+| Variant | When |
+|---|---|
+| `publish` | Local version > registry version AND build passes |
+| `publish-prerelease` | Version contains `-alpha`, `-beta`, `-rc` — uses `--tag` to avoid promoting to `latest` |
+| `skip` | Version unchanged since last shipment |
+
+## STEPS — publish variant
+
+The npm registry requires 2FA OTP for every publish. **The orchestrator NEVER runs `npm publish` directly** — the user runs it because the OTP is theirs.
+
+1. **Detect packages to publish**:
+   ```bash
+   bash "${CLAUDE_SKILL_DIR}/scripts/detect-surfaces.sh" --filter=npm-package
+   ```
+
+2. **Per package, check version status**:
+   ```bash
+   cd "$PKG_PATH"
+   PKG_NAME=$(jq -r .name package.json)
+   LOCAL_VERSION=$(jq -r .version package.json)
+   REMOTE_VERSION=$(npm view "$PKG_NAME@$LOCAL_VERSION" version 2>/dev/null || echo "")
+
+   if [ "$REMOTE_VERSION" = "$LOCAL_VERSION" ]; then
+     echo "Already published — skip"
+   else
+     echo "Publishable — local $LOCAL_VERSION, registry has $(npm view "$PKG_NAME" version)"
+   fi
+   ```
+
+3. **Build the package** (orchestrator-side; no OTP needed):
+   ```bash
+   pnpm --filter "$PKG_NAME" build
+   ```
+
+   If `package.json` `scripts.build` is absent, skip but warn — likely intentional (no build needed) but uncommon.
+
+4. **Pre-publish checks**:
+   ```bash
+   cd "$PKG_PATH"
+   npm pack --dry-run                          # see what will go in the tarball
+   pnpm publint || true                        # lints package.json, prints warnings
+   pnpm attw --pack 2>/dev/null || true        # arethetypeswrong — ESM/CJS sanity check
+   ```
+
+   If `npm pack --dry-run` shows missing entrypoints (`main`/`exports` files not in tarball), HALT — surface the error and the `files` field needs fixing.
+
+5. **Display publish command for the user to run** (the OTP step):
+   ```
+   ## npm publish — manual step
+
+   Package: @scope/pkg-name @ 1.4.0
+   Directory: /path/to/pkg
+
+   Run in your terminal:
+       cd /path/to/pkg
+       npm publish
+
+   Enter your 2FA code when prompted. Reply 'done' when published, 'fail' if it errored.
+   ```
+
+6. **Verify publication** (after user reports done):
+   ```bash
+   npm view "$PKG_NAME@$LOCAL_VERSION" version 2>&1
+   ```
+   If matches local version → success. Otherwise → ask user to retry.
+
+7. **Result**:
+   ```json
+   {
+     "status": "verified",
+     "package": "@scope/pkg-name",
+     "version": "1.4.0",
+     "registry_url": "https://www.npmjs.com/package/@scope/pkg-name/v/1.4.0",
+     "published_at": "2026-04-29T14:32:00Z"
+   }
+   ```
+
+## STEPS — publish-prerelease variant
+
+Same as `publish` but step 5 includes the `--tag` flag:
+
+```bash
+npm publish --tag next     # for X.Y.Z-rc.N
+npm publish --tag beta     # for X.Y.Z-beta.N
+```
+
+Prereleases must NOT promote to `latest`. The user-facing instruction must explicitly include `--tag`.
+
+## Versioning automation
+
+This surface respects three modes (set per-package in `.codebyplan/shipment.json` `surfaces.npm-package.{path}.versioning`):
+
+| Mode | Behavior |
+|---|---|
+| `manual` | User bumps `package.json` version manually before checkpoint shipment |
+| `release-please` | A GH Actions workflow opens version-bump PRs based on conventional commits — checkpoint merges those PRs as part of normal flow; `/cbp-ship` then publishes the bumped version |
+| `changesets` | User adds `.changeset/*.md` entries during development; release-please-style PR aggregates them |
+
+See [versioning.md](versioning.md) for which mode to pick.
+
+## OIDC trusted publishing (recommended for CI)
+
+For repos that publish from GH Actions instead of local, use OIDC trusted publishing — no token needed, no leaked credentials:
+
+1. Set up via npm web → Account → Trusted Publishing → add the GH workflow path
+2. In workflow, request `id-token: write` permission and use `npm publish --provenance`
+
+`/cbp-ship-configure` can scaffold the GH Actions workflow that uses this. See [npm-publish-oidc-trusted.md](./npm-publish-oidc-trusted.md) and [npm-publish-monorepo.md](./npm-publish-monorepo.md).
+
+## Verification
+
+`scripts/verify-npm.sh`:
+
+```bash
+PKG="$1"
+VERSION="$2"
+
+# Registry shows the version
+RESOLVED=$(npm view "$PKG@$VERSION" version 2>/dev/null)
+[ "$RESOLVED" = "$VERSION" ] || { echo "Not published: $PKG@$VERSION"; exit 1; }
+
+# Tarball has SRI hash (provenance bonus)
+SRI=$(npm view "$PKG@$VERSION" dist.integrity 2>/dev/null)
+[ -n "$SRI" ] || echo "WARN: no integrity hash"
+
+# If --provenance was used, attestation exists
+HAS_ATTESTATION=$(npm view "$PKG@$VERSION" --json | jq -r '.dist.attestations // empty')
+[ -n "$HAS_ATTESTATION" ] && echo "Provenance: yes"
+
+echo "OK"
+```
+
+## Common failures
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `npm publish` rejects with "You cannot publish over the previously published versions" | Local version already on registry | Bump version in `package.json` |
+| 403 forbidden | Not a maintainer of the package | `npm owner add <user> <pkg>` from an existing maintainer |
+| `EOTP` after correct OTP | Token expired or 2FA app de-synced | `npm logout && npm login` |
+| Tarball missing files | `files` field too restrictive | Verify with `npm pack --dry-run` and adjust `files` |
+| Types not picked up by consumers | `exports` field missing types | Add `"exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } }` |
+
+## Rollback
+
+`npm unpublish` is restricted (only within 72 hours; only if no dependents). Better path:
+
+```bash
+npm deprecate "$PKG@$BAD_VERSION" "Use $PKG@$GOOD_VERSION instead"
+# Then publish a patch version that fixes the issue
+```
+
+## Configure-once setup
+
+See `${CLAUDE_PLUGIN_ROOT}/skills/ship-configure/reference/npm-package.md` for first-time setup (npm login, 2FA enrollment, OIDC trusted publishing setup, choosing versioning mode).

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

@@ -0,0 +1,152 @@
+# Surface: railway-backend
+
+Deploy a backend service (NestJS / Node / Bun / Python) to Railway.
+
+Railway is the standard backend platform for the CBP family (per architectural decision 2026-04-29). Other Docker-friendly platforms (Fly, Render, Heroku) can be added as separate surfaces if needed — Railway is the default.
+
+## Detection
+
+Signals (any of):
+
+- `railway.toml` or `railway.json` at app root
+- `.railway/` directory at app root
+- `Dockerfile` AND `package.json` with non-frontend deps (no `next`, no `react-native`) AND not under workspace `packages/`
+
+## Configured indicators
+
+`configured: true` requires:
+
+1. `railway.toml` or `.railway/config.json` present with `project` ID
+2. `railway` CLI installed (`railway --version` succeeds)
+3. `railway whoami` returns a logged-in user
+4. `.codebyplan/shipment.json` `.surfaces.railway-backend` block has `project_id` AND `service_id` AND `environment_id`
+
+## Variants
+
+| Variant | When |
+|---|---|
+| `deploy` | Service code or Dockerfile changed since last shipment |
+| `skip` | No backend changes |
+
+Detection uses git diff: if any path under the service directory changed between the prior shipment SHA and the current ship SHA, mark `deploy`.
+
+## STEPS — deploy variant
+
+Railway has two deployment modes:
+
+- **Auto-deploy on push** — preferred. Linked to a GH branch; pushes trigger deploys via webhook.
+- **Manual `railway up`** — fallback when GH integration isn't desired.
+
+Detection: `railway service --json | jq .repoConfig` — if non-null, it's auto-deploy. Otherwise manual.
+
+### Auto-deploy mode
+
+1. **Verify GH integration is healthy**:
+   ```bash
+   railway service --json | jq -r .repoConfig.repoLink
+   # Should match the current repo
+   ```
+
+2. **Wait for the deploy webhook to fire** (up to 30s after PR merge):
+   ```bash
+   timeout 60 bash -c "while ! railway logs --json 2>/dev/null | jq -e '.[0].timestamp > \"$(date -u -v-1M +%FT%T)\"'; do sleep 5; done"
+   ```
+
+3. **Get the deployment ID**:
+   ```bash
+   DEPLOY_ID=$(railway deployment list --json | jq -r '.[0].id')
+   ```
+
+4. **Wait for deployment SUCCESS state**:
+   ```bash
+   timeout 600 bash -c "while [ \"\$(railway deployment status \"$DEPLOY_ID\" --json | jq -r .status)\" != \"SUCCESS\" ]; do
+     STATUS=\$(railway deployment status \"$DEPLOY_ID\" --json | jq -r .status)
+     [ \"\$STATUS\" = \"FAILED\" ] && exit 1
+     sleep 10
+   done"
+   ```
+
+5. **Capture URL**:
+   ```bash
+   URL=$(railway domain --json | jq -r '.[0].domain' | head -1)
+   ```
+
+### Manual deploy mode
+
+1. **Confirm with user**:
+   ```
+   Railway is configured for manual deploy. Run: railway up
+   This builds locally + uploads + deploys (5-10 min).
+   A) Run `railway up` — start the deploy
+   B) Skip — deploy manually later
+   ```
+
+2. **Run the deploy**:
+   ```bash
+   cd "$APP_PATH"
+   railway up --detach
+   ```
+
+3. **Steps 3-5 same as auto-deploy mode**.
+
+## Verification
+
+`scripts/verify-railway.sh`:
+
+```bash
+DEPLOY_ID="$1"
+URL="$2"
+
+# Deployment status
+STATUS=$(railway deployment status "$DEPLOY_ID" --json | jq -r .status)
+[ "$STATUS" = "SUCCESS" ] || { echo "Deploy not successful: $STATUS"; exit 1; }
+
+# Health endpoint (if configured)
+if [ -n "$URL" ]; then
+  HEALTH=$(curl -sI -m 10 "https://$URL/health" 2>/dev/null | head -1 | awk '{print $2}')
+  [ "$HEALTH" = "200" ] || echo "WARN: /health returned $HEALTH (may not be implemented)"
+fi
+
+echo "OK"
+```
+
+## Common failures
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Deploy fails at "Building" | Dockerfile build error | `railway logs --build` — usually missing system dep or wrong Node version |
+| Deploy succeeds, app crashes on start | Missing env var | `railway variables` — compare to `.env.example` |
+| Health endpoint times out | Service not listening on Railway's `$PORT` | Bind to `process.env.PORT` not hardcoded port |
+| GH webhook not firing | Disconnect or branch filter mismatch | Railway dashboard → service → Settings → Source → reconnect |
+| OOM during build | Large node_modules | Add `.dockerignore`; use multi-stage build |
+
+## Rollback
+
+```bash
+railway redeploy <prior-deployment-id>
+```
+
+The orchestrator surfaces this when verification fails:
+
+```
+Railway deployment FAILED.
+Options:
+A) Retry — sometimes transient
+B) Rollback to deployment <prior-id> (last successful)
+C) Investigate logs — railway logs --build / --runtime
+```
+
+## Multi-service projects
+
+A Railway project can have multiple services (e.g., `api`, `worker`, `cron`). Each shipment surface is per-service. The detection emits one entry per service:
+
+```json
+{ "id": "railway-backend", "instance": "apps/backend",  "service_id": "svc_abc", ... }
+{ "id": "railway-backend", "instance": "apps/worker",   "service_id": "svc_def", ... }
+```
+
+The orchestrator deploys each independently.
+
+## Configure-once setup
+
+See `${CLAUDE_PLUGIN_ROOT}/skills/ship-configure/reference/railway-backend.md` for first-time setup (railway login, project creation/link, env var sync, GH integration, custom domain, health endpoint config).

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

@@ -0,0 +1,178 @@
+# Surface: supabase
+
+Push pending database migrations to the linked Supabase project.
+
+This is the most consequential shipment surface — schema mismatches break web/backend immediately. Migration push is **always interactive** with explicit user review of the diff before applying.
+
+## Detection
+
+Signals:
+
+- `supabase/` directory with `config.toml`
+- `supabase/migrations/*.sql` — count of files newer than `last_shipped_migration_version` in `.codebyplan/shipment.json` `.surfaces.supabase`
+
+## Configured indicators
+
+`configured: true` requires:
+
+1. `supabase/config.toml` parseable with `project_id` field
+2. `supabase` CLI installed (`supabase --version` succeeds)
+3. `supabase projects list` succeeds (CLI authenticated)
+4. `.codebyplan/shipment.json` `.surfaces.supabase` block has `project_ref`
+
+Library docs via DocsByPlan MCP (`resolve_library_id('supabase')`).
+
+## Variants
+
+| Variant | When |
+|---|---|
+| `push-migrations` | At least one migration file is newer than `last_shipped_migration_version` |
+| `skip` | No new migrations |
+
+## STEPS — push-migrations variant
+
+This is **always interactive**. The orchestrator does NOT silently apply migrations even with confirmation up front, because the diff might surprise the user (auto-generated migrations sometimes include unintended changes).
+
+1. **List pending migrations**:
+   ```bash
+   PROJECT_REF=$(jq -r '.surfaces.supabase.project_ref' .codebyplan/shipment.json)
+   LAST_VERSION=$(jq -r '.surfaces.supabase.last_shipped_migration_version // ""' .codebyplan/shipment.json)
+
+   PENDING=$(ls supabase/migrations/*.sql | sort)
+   if [ -n "$LAST_VERSION" ]; then
+     PENDING=$(echo "$PENDING" | awk -v cutoff="$LAST_VERSION" '$0 > "supabase/migrations/" cutoff')
+   fi
+   echo "$PENDING"
+   ```
+
+2. **Show user the migration list** + counts:
+   ```
+   ## Pending migrations (4)
+
+   - 0083_add_user_avatars.sql       (12 lines)
+   - 0084_index_session_lookups.sql  (4 lines)
+   - 0085_rls_share_links.sql        (28 lines)
+   - 0086_view_active_users.sql      (8 lines)
+
+   Press Enter to review each diff individually, or type 'all' to see them concatenated.
+   ```
+
+3. **Walk through each migration** via AskUserQuestion (one per file):
+   ```
+   ### 0083_add_user_avatars.sql
+
+   ```sql
+   ALTER TABLE users ADD COLUMN avatar_url text;
+   CREATE INDEX users_avatar_url_idx ON users(avatar_url) WHERE avatar_url IS NOT NULL;
+   ```
+
+   Approve this migration?
+   A) Approve — include in push
+   B) Skip this one (manual review needed)
+   C) Abort — stop shipment, don't push anything
+   ```
+
+   The user reviews each file. If they pick C on any, halt — do NOT continue with subsequent surfaces.
+
+4. **Generate diff against the live project** for safety:
+   ```bash
+   supabase db diff --use-migra --schema public,auth
+   ```
+
+   This compares local migrations to remote state. If the diff shows things NOT in the migrations (drift on the remote), HALT and surface to the user — remote drift means someone applied changes via the dashboard, and we shouldn't blindly push.
+
+5. **Push approved migrations**:
+   ```bash
+   supabase db push --include-all
+   ```
+
+   If push fails partway (e.g., migration 0084 errors), Supabase rolls back to the last successful migration. Surface the failure:
+   ```
+   Migration push FAILED at 0084_index_session_lookups.sql
+   Reason: <error from supabase>
+
+   The migrations applied successfully:
+   ✓ 0083_add_user_avatars.sql
+
+   The remaining migrations (0085, 0086) were NOT applied.
+
+   Options:
+   A) Fix migration 0084 in code, re-run /cbp-ship
+   B) Skip 0084 and proceed with 0085+0086 (use --include-files)
+   C) Abort — schema is partially-shipped; revert the applied migration manually if needed
+   ```
+
+6. **Regenerate TypeScript types** (if the project uses generated types):
+   ```bash
+   if [ -f "supabase/functions/_shared/db.types.ts" ] || [ -f "packages/supabase/types.ts" ]; then
+     supabase gen types typescript --project-id "$PROJECT_REF" > "$TYPES_PATH"
+     # If diff exists, surface to user — types changes may need to be committed
+     if ! git diff --quiet "$TYPES_PATH"; then
+       echo "Types regenerated — diff present. Commit before completing checkpoint."
+     fi
+   fi
+   ```
+
+7. **Update the last-shipped marker**:
+   ```bash
+   LAST_APPLIED=$(echo "$PENDING" | tail -1 | xargs basename)
+   jq --arg v "$LAST_APPLIED" '.surfaces.supabase.last_shipped_migration_version = $v' .codebyplan/shipment.json > .codebyplan/shipment.json.tmp
+   mv .codebyplan/shipment.json.tmp .codebyplan/shipment.json
+   ```
+
+8. **Result**:
+   ```json
+   {
+     "status": "verified",
+     "migrations_applied": ["0083_...", "0084_...", "0085_...", "0086_..."],
+     "types_regenerated": true,
+     "project_ref": "abcdefgh"
+   }
+   ```
+
+## Verification
+
+`scripts/verify-supabase.sh`:
+
+```bash
+PROJECT_REF="$1"
+EXPECTED_LAST="$2"
+
+# All listed migrations are recorded in supabase_migrations table
+APPLIED=$(supabase migration list --remote --linked 2>/dev/null | grep -F "$EXPECTED_LAST" | wc -l)
+[ "$APPLIED" -gt 0 ] || { echo "Migration $EXPECTED_LAST not found on remote"; exit 1; }
+
+# No drift
+DRIFT=$(supabase db diff --use-migra 2>/dev/null | grep -v "^--" | grep -c .)
+[ "$DRIFT" -eq 0 ] || { echo "WARN: $DRIFT lines of drift between local migrations and remote"; }
+
+echo "OK"
+```
+
+## Common failures
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `db push` fails with permission error | Service role token missing scopes | `supabase login` again, ensure access token has full project access |
+| Migration fails on `RAISE EXCEPTION` | Data assertion failure | Inspect data; usually means a NOT NULL constraint with existing NULLs |
+| RLS policy fails to apply | References non-existent role | Migrations must be self-contained; check `supabase/seed.sql` for role creation |
+| Drift detected | Someone applied changes via dashboard | Pull dashboard changes into a migration: `supabase db diff -f resolve_drift` |
+| Types regen breaks compilation | New column not exposed via API | Add the table/column to `exposed_schemas` in `config.toml` |
+
+## Rollback
+
+There's no clean rollback for applied migrations. Two paths:
+
+1. **Forward-only revert** — write a new migration that undoes the change, push it
+2. **Point-in-time restore** — Supabase paid tier; via dashboard
+
+The orchestrator surfaces #1 as the recommended path:
+
+```
+Migration cannot be auto-rolled-back.
+Recommended: write a new migration that reverses the schema change, then re-run /cbp-ship.
+```
+
+## Configure-once setup
+
+See `${CLAUDE_PLUGIN_ROOT}/skills/ship-configure/reference/supabase.md` for first-time setup (supabase login, project link, types path config, optional auto-types-on-edit).