codebyplan 1.5.1 → 1.8.0

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

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

@@ -0,0 +1,283 @@
+# GitHub CLI — Shipment Commands
+
+Commands `/cbp-ship` actually runs, organised by surface. Authoritative reference: <https://cli.github.com/manual>. Each section: exact command, flags we use, JSON shape (where applicable), common errors.
+
+## 1. Pull Requests
+
+### `gh pr create` — open a PR
+
+```bash
+gh pr create --base main --head "$BRANCH" \
+  --title "$TITLE" --body-file .claude/tmp/pr-body.md --draft
+```
+
+| Flag | Purpose |
+|------|---------|
+| `--base <branch>` | Target. CBP ships `feat/* -> main`; always set explicitly. |
+| `--head <branch>` | Source. Defaults to current; pass explicitly with `--repo`. |
+| `--title` | One-line title. Obey `rules/git-workflow.md` (no Claude attribution). |
+| `--body-file <path>` | Multiline body. Preferred over `--body`. |
+| `--draft` | Open in draft. CBP default for non-trivial PRs. |
+| `--reviewer @me,user,team/slug` | Optional. |
+| `--label`, `--assignee`, `--milestone`, `--project` | Optional metadata. |
+| `--fill` | Use commit subject + body as title/body. |
+| `--repo OWNER/REPO` | Required outside the checkout. |
+
+Output: prints the URL on stdout (no JSON). Capture the PR number with `gh pr view --json number`.
+
+Common errors:
+
+- `A pull request already exists for ...` — branch has an open PR; use `gh pr view`.
+- `must provide --title and --body (or --fill)` — non-TTY without flags.
+- `Head sha can't be blank` — branch not pushed; `git push -u origin <branch>` first.
+
+### `gh pr view` — read PR state
+
+```bash
+gh pr view "$PR_NUMBER" \
+  --json number,state,mergeable,mergeStateStatus,headRefOid,baseRefName,reviewDecision,statusCheckRollup,url \
+  --jq .
+```
+
+| Field | Type | Use |
+|-------|------|-----|
+| `state` | `OPEN`/`CLOSED`/`MERGED` | Gate further actions |
+| `mergeable` | `MERGEABLE`/`CONFLICTING`/`UNKNOWN` | Pre-merge gate |
+| `mergeStateStatus` | `CLEAN`/`BLOCKED`/`BEHIND`/`DIRTY`/`UNSTABLE`/`HAS_HOOKS` | Why merge is blocked |
+| `headRefOid` | sha | Pin a `--match-head-commit` merge |
+| `reviewDecision` | `APPROVED`/`CHANGES_REQUESTED`/`REVIEW_REQUIRED` | Review gate |
+| `statusCheckRollup` | array | Per-check status; filter with `--jq` |
+
+Pass `--json` with no value to discover the full field list.
+
+### `gh pr merge` — merge a PR
+
+```bash
+gh pr merge "$PR_NUMBER" --merge --delete-branch --match-head-commit "$HEAD_OID"
+```
+
+| Flag | Purpose |
+|------|---------|
+| `--merge`/`--squash`/`--rebase` | Strategy. CBP default is `--merge`. `--rebase` often blocked by branch protection. |
+| `--auto` | Auto-merge once required checks pass. |
+| `--delete-branch` (`-d`) | Delete head after merge. Always set for `feat/*`. |
+| `--admin` | Bypass branch protection. Reserved for emergency hotfixes; never default. |
+| `--match-head-commit <oid>` | Refuse merge if HEAD has moved. Use `headRefOid` from `gh pr view`. |
+| `--subject`, `--body` | Override merge commit message. |
+
+Common errors:
+
+- `Pull request is not mergeable: <reason>` — inspect `mergeStateStatus`. `BLOCKED` = required checks/reviews missing.
+- `auto-merge is not allowed for this repository` — repo disables it; remove `--auto`.
+- HTTP 405 on protected branches without `--admin` — expected; do NOT auto-escalate.
+
+## 2. Releases
+
+### `gh release create`
+
+```bash
+gh release create "$TAG" --title "$TITLE" --notes-file CHANGELOG-fragment.md \
+  --target "$COMMIT_SHA" --latest ./dist/*.tar.gz ./dist/*.zip
+```
+
+Argument order: `gh release create <tag> [<asset>...]`. Tag is positional + required.
+
+| Flag | Purpose |
+|------|---------|
+| `--title` (`-t`) | Title. Defaults to tag. |
+| `--notes-file` (`-F`) | Notes from file. `-` for stdin. |
+| `--generate-notes` | Auto-generate via API; combinable with `--notes-file` (file content goes above generated). |
+| `--target <branch-or-sha>` | Tag-target if tag does not exist. |
+| `--draft` (`-d`) | Save as draft. CBP default for human review. |
+| `--prerelease` (`-p`) | Prerelease flag. |
+| `--latest` / `--latest=false` | Mark/unmark as Latest. |
+| `--verify-tag` | Refuse if tag does not exist remotely. |
+| `--discussion-category <name>` | Open a discussion. |
+| `--fail-on-no-commits` | Abort if no new commits since last release. |
+
+Asset upload: paths after the tag. Custom labels via `'/path/to/file.zip#Display Label'`.
+
+Common errors:
+
+- `tag already exists` (without `--target`) — local tag points to different sha; `git push --tags` or `git tag -d` + recreate.
+- `validation failed: name has already been taken` — use `gh release edit` or `gh release delete` first.
+- `could not find tag` with `--verify-tag` — push the tag first.
+
+### `gh release view`
+
+```bash
+gh release view "$TAG" --json tagName,name,isDraft,isLatest,isPrerelease,publishedAt,url,assets --jq .
+```
+
+JSON fields: `tagName`, `name`, `body`, `isDraft`, `isLatest`, `isPrerelease`, `publishedAt`, `url`, `tarballUrl`, `zipballUrl`, `assets[].{name,size,downloadCount,url}`.
+
+### `gh release delete`
+
+```bash
+gh release delete "$TAG" --yes --cleanup-tag
+```
+
+`--yes` skips confirmation (required non-TTY). `--cleanup-tag` also deletes the underlying git tag. `release not found` is a soft failure — treat as already-clean.
+
+## 3. Secrets
+
+### `gh secret list`
+
+```bash
+gh secret list --repo "$OWNER/$REPO"
+gh secret list --org "$ORG"
+gh secret list --env "$ENV" --repo "$OWNER/$REPO"
+```
+
+Output is tab-separated `NAME UPDATED`. No `--json`. Secret values are never returned.
+
+### `gh secret set`
+
+```bash
+echo -n "$VALUE" | gh secret set MY_SECRET                                            # repo-level
+gh secret set --env-file .env.production                                              # bulk from dotenv
+echo -n "$VALUE" | gh secret set MY_SECRET --env production                           # environment
+echo -n "$VALUE" | gh secret set MY_SECRET --org myorg --visibility selected --repos repo1,repo2
+echo -n "$VALUE" | gh secret set MY_SECRET --app dependabot                           # dependabot
+```
+
+Scope matrix:
+
+| Flag combo | Scope | Token scope |
+|------------|-------|-------------|
+| (none) | Repository | `repo` |
+| `--env <name>` | Repository environment (env must exist) | `repo` |
+| `--org <name> --visibility all`/`private` | Org-wide | `admin:org` |
+| `--org <name> --visibility selected --repos a,b` | Org allow-list | `admin:org` |
+| `--app actions` (default) / `dependabot` / `codespaces` | Per-application surface | as above |
+
+Input precedence: `--body <value>` > stdin > interactive prompt. Prefer stdin to keep values out of process listings and shell history.
+
+Common errors:
+
+- `HTTP 404` with `--env` — environment must exist (`gh api repos/{o}/{r}/environments/{name} --method PUT`).
+- `HTTP 422: visibility 'selected' requires --repos` — supply allow-list.
+- `HTTP 403` against `--org` — `gh auth refresh --scopes admin:org`.
+
+## 4. Workflow Runs
+
+### `gh run list`
+
+```bash
+gh run list --workflow ci.yml --branch "$BRANCH" --limit 10 \
+  --json databaseId,status,conclusion,headSha,event,createdAt,workflowName,url \
+  --jq '.[] | select(.conclusion != "success")'
+```
+
+Flags: `--workflow` (filename/ID/name), `--branch`, `--user`, `--status`, `--event`, `--limit` (default 20), `--created`, `--json`, `-R/--repo`.
+
+JSON fields: `attempt`, `conclusion`, `createdAt`, `databaseId`, `displayTitle`, `event`, `headBranch`, `headSha`, `name`, `number`, `startedAt`, `status`, `updatedAt`, `url`, `workflowDatabaseId`, `workflowName`.
+
+`status`: `queued`, `in_progress`, `completed`, `requested`, `waiting`. `conclusion` (when `status=completed`): `success`, `failure`, `cancelled`, `skipped`, `timed_out`, `action_required`, `neutral`, `stale`.
+
+### `gh run watch`
+
+```bash
+gh run watch "$RUN_ID" --exit-status --interval 5 --compact
+```
+
+| Flag | Purpose |
+|------|---------|
+| `--exit-status` | Non-zero on failure. Required for `set -e`. |
+| `--interval <sec>` (`-i`) | Poll interval (default 3). Bump to 5-10 for long runs. |
+| `--compact` | Show only failed/relevant steps. |
+| `-R/--repo` | Override repo. |
+
+Never omit `RUN_ID` in `/cbp-ship` — without it the command prompts (no TTY).
+
+### `gh run view`
+
+```bash
+gh run view "$RUN_ID" --json status,conclusion,jobs,workflowName,url --jq .   # summary
+gh run view "$RUN_ID" --log-failed                                            # failed-step logs
+gh run view --job "$JOB_ID" --log                                             # one job
+gh run view "$RUN_ID" --exit-status                                           # script-friendly
+```
+
+JSON fields: same as `run list` plus `jobs`. `jobs[].{databaseId,name,status,conclusion,steps[].{name,conclusion,number}}` — canonical drill-down from a failed run to the responsible step.
+
+Common errors:
+
+- `could not find any workflow run with ID <x>` — wrong repo or expired; verify with `gh run list -R <repo>`.
+- `--log-failed` empty while in progress — pair with `gh run watch` first.
+- Logs older than 90 days unavailable (GitHub-side retention).
+
+## 5. Deployments API (Non-Vercel)
+
+For non-Vercel deploy targets, `/cbp-ship` records deploys via the GitHub Deployments API using `gh api`. There is no `gh deployment` subcommand.
+
+### Create a deployment
+
+```bash
+gh api "repos/$OWNER/$REPO/deployments" --method POST \
+  -f ref="$COMMIT_SHA" -f environment=production -f description="ship: $TAG" \
+  -F auto_merge=false -f required_contexts='[]'
+```
+
+- `-f key=value` — string field.
+- `-F key=value` — typed field (`true`/`false`/`null`/integer auto-converted).
+- `required_contexts='[]'` — empty JSON array as a string to skip status-check gating.
+- `--input <file>` — for complex payloads, pass JSON from file.
+
+Response (excerpt):
+
+```json
+{
+  "id": 12345678,
+  "url": "https://api.github.com/repos/.../deployments/12345678",
+  "sha": "abc123...",
+  "ref": "main",
+  "environment": "production",
+  "statuses_url": "https://api.github.com/repos/.../deployments/12345678/statuses"
+}
+```
+
+Capture `id` for status follow-ups.
+
+### Update deployment status
+
+```bash
+gh api "repos/$OWNER/$REPO/deployments/$DEPLOYMENT_ID/statuses" --method POST \
+  -f state=success -f environment_url="https://app.example.com" \
+  -f log_url="https://github.com/.../actions/runs/$RUN_ID" -f description="Live"
+```
+
+`state` values: `error`, `failure`, `inactive`, `in_progress`, `queued`, `pending`, `success`. Only `success` and `inactive` are terminal in the UI.
+
+### List deployments
+
+```bash
+gh api "repos/$OWNER/$REPO/deployments?environment=production&per_page=10" \
+  --jq '.[] | {id, sha, created_at, ref}'
+```
+
+Combine `--paginate` for full history, but bound it — Deployments grow unbounded.
+
+Common errors:
+
+- `HTTP 422: required_contexts is invalid` — pass `'[]'` literal with `-f`.
+- `HTTP 422: Conflict merging <ref>` — `auto_merge` defaulted to true; pass `-F auto_merge=false`.
+- `HTTP 404` — ref does not exist remotely, or token lacks `repo_deployment` (subset of `repo`).
+
+## Quick-Reference: What `/cbp-ship` Calls
+
+| Phase | Command |
+|-------|---------|
+| Open PR | `gh pr create --base ... --head ... --title ... --body-file ... --draft` |
+| Wait for checks | `gh run watch $RUN_ID --exit-status --interval 5` |
+| Inspect failure | `gh run view $RUN_ID --log-failed` |
+| Pre-merge gate | `gh pr view $PR --json mergeable,mergeStateStatus,reviewDecision,headRefOid` |
+| Merge | `gh pr merge $PR --merge --delete-branch --match-head-commit $OID` |
+| Cut release | `gh release create $TAG --title ... --notes-file ... --target $SHA --latest` |
+| Record deploy (non-Vercel) | `gh api repos/.../deployments --method POST -f ref=$SHA -f environment=production` |
+
+## Pairs With
+
+- [gh-cli-overview.md](./gh-cli-overview.md) — install, auth, config locations
+- `/cbp-ship` skill — orchestrator that sequences these calls
+- `.claude/rules/git-workflow.md` — branch/commit conventions enforced before any of these commands run