codebyplan 1.5.1 → 1.9.0

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

@@ -0,0 +1,168 @@
+# Railway — Troubleshooting
+
+Failure modes the `/cbp-ship` orchestrator and human operators have hit on Railway, with the actual fix. Ordered roughly by frequency.
+
+For platform-level concept reference see [railway-overview.md](./railway-overview.md). For the canonical NestJS deployment shape see [railway-nestjs-deployment.md](./railway-nestjs-deployment.md).
+
+## 1. Healthcheck Timeout — Service Marked CRASHED
+
+**Symptom:** Build succeeds, deploy log shows `Starting Healthcheck` and then `Healthcheck failed!` after the configured timeout. New deployment never goes live; old one keeps serving.
+
+**Causes (in order of likelihood):**
+
+1. **App listening on `localhost`/`127.0.0.1` instead of `0.0.0.0`** — Railway's proxy is on a different interface and can't reach you.
+2. **Hardcoded port** — app listens on `3000` but Railway assigned `PORT=8080`.
+3. **Healthcheck path wrong** — configured `/health`, app exposes `/api/health`. Railway sees 404 → fail.
+4. **Healthcheck depends on Supabase / external service that's down** — transient outage cascades into a broken deploy.
+5. **Slow boot** — NestJS module init (e.g. running migrations on boot) takes longer than the healthcheck timeout (default 100s).
+
+**Fix:**
+
+```ts
+// Bind to 0.0.0.0, read $PORT
+await app.listen(parseInt(process.env.PORT ?? '3000', 10), '0.0.0.0');
+```
+
+Verify with: `railway logs` immediately after deploy — look for `Listening on 0.0.0.0:<port>` line.
+
+For slow boot, raise the healthcheck timeout in `Settings → Deploy → Healthcheck Timeout` (max 300s). Better: defer migrations out of boot path.
+
+For dependency-tainted healthcheck, see the "keep healthchecks cheap" guidance in [railway-nestjs-deployment.md](./railway-nestjs-deployment.md).
+
+## 2. Build OOM — `Killed` or Exit Code 137
+
+**Symptom:** Build log ends with `Killed` or `exit code 137` during `pnpm install` or `turbo build`. No useful stack.
+
+**Cause:** Railway's default build runner has a memory cap (~8 GB on Hobby). Heavy monorepo builds — particularly with `next build` in the same image, or when sharp/prisma engines compile from source — exceed it.
+
+**Fix:**
+
+1. Slim the build context. Add a `.dockerignore`:
+   ```
+   **/node_modules
+   **/.next
+   **/dist
+   **/.turbo
+   **/coverage
+   **/.git
+   ```
+2. Use multi-stage with `pnpm --filter=<pkg> deploy --prod /out` so the runtime image only carries one app's deps.
+3. Avoid `pnpm install --recursive` — let `pnpm install` (workspace-aware) do it once.
+4. If still OOMing on Hobby: upgrade to Pro (larger build runner) or move heavy compile steps to a CI step that publishes a prebuilt artefact.
+
+## 3. $PORT Binding Errors
+
+**Symptom:** `Error: listen EADDRINUSE` or `Error: Cannot find module 'PORT'` or app binds to literally the string `"$PORT"`.
+
+**Causes:**
+
+| Symptom | Cause |
+|---------|-------|
+| `listen EADDRINUSE: ::1:8080` | Two processes in the container both binding the same port (e.g. `tini` start script forking twice) |
+| Listens on string `"$PORT"` | Shell-form CMD without shell expansion: `CMD node main.js --port=$PORT` won't expand. Use `CMD ["sh", "-c", "node main.js --port=$PORT"]` or read from env in code (preferred) |
+| `parseInt(undefined)` → NaN | App didn't fall back; ensure `process.env.PORT ?? '3000'` |
+
+## 4. GitHub Webhook Desync — "I Pushed and Nothing Happened"
+
+**Symptom:** `git push` to the configured deploy branch lands on GitHub. No new deployment appears in Railway.
+
+**Diagnosis:**
+
+1. GitHub repo → `Settings → Webhooks` → find Railway's webhook → `Recent Deliveries` tab.
+2. Look at the latest delivery for your push. If it's `200 OK`, problem is on Railway's side. If it's red (4xx/5xx) or missing, problem is on GitHub's side.
+
+**Fixes:**
+
+- **Webhook delivery missing** — your push didn't match the configured branch filter. Check `Settings → Source` on the Railway service.
+- **Webhook 401/403** — Railway's GitHub App was uninstalled or its permissions were revoked. Reinstall: Railway dashboard → service → `Settings → Source → Reconnect`.
+- **Webhook 200 but no Railway deploy** — webhook reached Railway but was filtered out. Check that the branch matches and that the commit doesn't only touch ignored paths (Railway has an optional path filter).
+- **Last resort:** `Settings → Deploy → Trigger Deploy` manually.
+
+## 5. Env Var Typo / Missing Var
+
+**Symptom:** App boots, then crashes with `SUPABASE_URL is undefined` or similar. Deployment marked CRASHED.
+
+**Diagnosis:**
+
+```bash
+railway variables             # list all vars in current service
+railway run -- printenv | grep SUPABASE
+```
+
+**Common gotchas:**
+
+- Trailing newline or whitespace on a pasted value. Use the dashboard "raw editor" for multi-line values.
+- Variable defined on the wrong environment (you set it on `staging` but deployed `production`).
+- Reference variable broken: `${{ Postgres.DATABASE_URL }}` evaluates to empty string if the `Postgres` service was renamed.
+- `NODE_ENV=development` accidentally inherited — check it's `production` everywhere.
+
+**Fix:** Set the var, then redeploy. New env vars do NOT auto-restart the service — you must trigger a redeploy via dashboard or `railway redeploy`.
+
+## 6. Deploy Stuck in BUILDING
+
+**Symptom:** Deploy has been in `BUILDING` state for 15+ minutes with no log output, or logs frozen mid-build.
+
+**Causes:**
+
+1. Railway build runner is in a degraded region — check https://status.railway.com.
+2. Network stall pulling base image or pnpm packages.
+3. Cache mount corruption — rare, but happens when a build is killed mid-write.
+
+**Fixes:**
+
+1. Cancel the deployment from the dashboard (deployment row → kebab menu → Cancel).
+2. Trigger a fresh deploy.
+3. If second deploy stalls in the same place: clear build cache via `Settings → Danger → Clear build cache`, then redeploy.
+4. If still stuck after cache clear: status page check, then support ticket. Do NOT keep retrying — you're burning build minutes.
+
+## 7. Healthcheck Timeout Misconfiguration
+
+**Symptom:** Healthcheck path returns 200 quickly when curled directly, but Railway still marks it failed.
+
+**Diagnosis steps:**
+
+1. `railway run -- curl -v http://localhost:$PORT/health` — does it work from inside the container?
+2. If yes: Railway proxy timeout is too tight. Default is 100s for the *initial* healthcheck window. Bump to 300s if app boot is genuinely slow.
+3. Healthcheck path field accepts a path only — not a full URL. `/health` correct, `http://localhost:3000/health` wrong.
+4. HTTPS-only middleware (e.g. `helmet` with `hsts` redirect) can 301 the healthcheck. Whitelist the `/health` path from any redirect middleware.
+
+## 8. Logs Inspection — What to Run
+
+```bash
+railway logs                    # tail current service logs (live)
+railway logs --deployment <id>  # logs for a specific past deployment
+railway logs --build            # build logs (vs runtime logs)
+railway status                  # current service deployment + state
+railway whoami                  # confirm you're logged in as the right account
+railway environment             # which env is linked
+```
+
+For programmatic access (CI, `/cbp-ship` polling), use the GraphQL API at `https://backboard.railway.com/graphql/v2` with `Authorization: Bearer $RAILWAY_TOKEN`. The `deployments` and `deploymentLogs` queries are the relevant ones — see the API explorer linked from https://docs.railway.com.
+
+## 9. Private Networking Not Resolving
+
+**Symptom:** `api` service can't reach `worker.railway.internal` — `getaddrinfo ENOTFOUND` or connection refused.
+
+**Causes:**
+
+1. Service name has changed; the internal hostname follows the *current* service name (lowercase, no spaces).
+2. Calling code uses IPv4 socket but Railway internal mesh is IPv6-only. Node 18+ defaults are fine; if you've forced `family: 4` somewhere, drop it.
+3. Both services must be in the same project AND environment. Cross-environment internal DNS is not a thing.
+
+## 10. Rollback
+
+**Symptom:** Last deploy broke production; need to revert in <60 seconds.
+
+**Fix:**
+
+1. Dashboard → service → deployments list → find the last good deployment → kebab → `Redeploy`.
+2. Or CLI: `railway redeploy --deployment <id>`.
+
+This re-runs the *same image* — no rebuild — so it lands in seconds. After rollback, fix the offending commit on GitHub; the next push will deploy normally.
+
+## Sources
+
+- https://docs.railway.com — primary reference
+- https://railway.com/changelog — when behaviour changes here, update this file
+- https://status.railway.com — platform status, check first when something is "weird"
+- https://station.railway.com — community Q&A; useful for edge cases not in docs

package/templates/skills/cbp-ship/reference/release-please-overview.md

@@ -0,0 +1,99 @@
+# release-please — Overview
+
+`release-please` is a Google-maintained tool that automates semver releases by parsing Conventional Commits. It runs as a GitHub Action (`googleapis/release-please-action`), watches commits to a configured branch, opens a "Release PR" that bumps `package.json` version + updates `CHANGELOG.md`, and (when the Release PR merges) cuts a GH Release tag. Used by the `npm-package` surface in `/cbp-ship` for opt-in versioning automation, and optionally for `tauri-desktop`.
+
+Upstream: https://github.com/googleapis/release-please
+
+## How `/cbp-ship` uses it
+
+The `npm-package` surface ([surface-npm.md](./surface-npm.md)) offers `release-please` as one of three versioning modes (manual, release-please, changesets). When a repo opts in via `/cbp-ship-configure`:
+
+1. Configure scaffolds `.github/workflows/release-please.yml` from `templates/workflow-release-please.yml`
+2. Devs commit using Conventional Commits (`feat:`, `fix:`, etc.)
+3. release-please opens a Release PR on the watched branch (configured in .github/workflows/release-please.yml; typically `main`)
+4. Maintainer reviews + merges the Release PR
+5. release-please tags the release; `/cbp-ship` then publishes the bumped version to npm
+
+The release-please-managed CHANGELOG.md is the source of truth for release notes.
+
+## Commit message → version bump mapping
+
+| Prefix | Action |
+|---|---|
+| `feat:` | Minor bump in next release-please PR |
+| `fix:` | Patch bump |
+| `feat!:` / `fix!:` / `BREAKING CHANGE:` footer | Major bump |
+| `chore:`, `docs:`, `refactor:`, `test:`, `style:`, `perf:`, `ci:` | No bump |
+
+Reference: [versioning.md](./versioning.md) for the full rules including changesets and manual modes.
+
+## Config shape
+
+`release-please-config.json` (single-package):
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "release-type": "node",
+  "include-component-in-tag": false,
+  "bump-minor-pre-major": true,
+  "bump-patch-for-minor-pre-major": false,
+  "draft": false,
+  "prerelease": false,
+  "packages": {
+    ".": {
+      "package-name": "<your-package-name>",
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "node"
+    }
+  }
+}
+```
+
+`.release-please-manifest.json` tracks current versions:
+
+```json
+{ ".": "1.4.2" }
+```
+
+For monorepos, list each package in `packages` and use the `node-workspace` plugin to keep `workspace:*` deps in sync after bumps.
+
+## Release-types
+
+| release-type | Use for |
+|---|---|
+| `node` | npm packages — bumps `package.json`, generates CHANGELOG |
+| `python` | Python packages — bumps `pyproject.toml` / `setup.py` |
+| `rust` | Cargo crates — bumps `Cargo.toml` |
+| `go` | Go modules — tags only (no manifest file to bump) |
+| `simple` | Tag + CHANGELOG only — for repos with no language manifest |
+| `terraform-module` | Terraform modules |
+
+CBP defaults: `node` for `npm-package` surface, `simple` if applied to `tauri-desktop` (Tauri version lives in `tauri.conf.json` which release-please can update via `extra-files`).
+
+## Tokens + permissions
+
+The default `secrets.GITHUB_TOKEN` is sufficient for most use cases. A PAT is required when:
+
+- Release commits should re-trigger CI (default `GITHUB_TOKEN` doesn't trigger downstream workflows — this is a GH security feature)
+- Cross-repo releases (rare for CBP)
+- Repo has branch protections that exclude bots
+
+Workflow permissions:
+
+```yaml
+permissions:
+  contents: write       # to create tags + commit CHANGELOG
+  pull-requests: write  # to open the Release PR
+```
+
+## Comparison vs Changesets
+
+See [npm-publish-monorepo.md](./npm-publish-monorepo.md) "Changesets vs release-please" for the full decision matrix. Short version: release-please assumes Conventional Commits are enforced; changesets adds a per-PR ceremony but gives explicit per-PR intent.
+
+## Pairs With
+
+- [surface-npm.md](./surface-npm.md) — npm publish surface that consumes the bumped version
+- [versioning.md](./versioning.md) — when to pick release-please vs changesets vs manual
+- [npm-publish-monorepo.md](./npm-publish-monorepo.md) — release-please monorepo configuration with the `node-workspace` plugin
+- `templates/release-please-config.json`, `templates/workflow-release-please.yml` — scaffolds the configure skill drops into the repo

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