codebyplan 1.5.1 → 1.8.0

package/templates/skills/cbp-ship/reference/railway-nestjs-deployment.md

@@ -0,0 +1,169 @@
+# Railway — NestJS Deployment
+
+Concrete walkthrough for the canonical CodeByPlan backend shape: a NestJS app in `apps/backend` of a pnpm/Turborepo monorepo, talking to Supabase, deployed to Railway via GitHub auto-deploys. Read [railway-overview.md](./railway-overview.md) first for concept-level context.
+
+## Build Strategy: Dockerfile vs Nixpacks/Railpack
+
+Railway picks a builder in this order: **Dockerfile** at repo root (or `RAILWAY_DOCKERFILE_PATH`) → **Railpack** (Elixir, Ruby, Rust) → **Nixpacks** (auto-detect Node/Python/Go).
+
+For CBP NestJS backends, **always use a Dockerfile**:
+
+| Concern | Dockerfile | Nixpacks |
+|---------|-----------|----------|
+| Reproducible builds (pinned base) | Yes | Drifts on Nixpacks updates |
+| pnpm workspace / monorepo | Explicit, scoped | Heuristics often misfire |
+| Build caching | Predictable layers | Opaque |
+| Multi-stage slim runtime | Easy | Not supported |
+| Native deps (sharp, prisma) | Apt/apk control | Black-box failures |
+
+The only case for Nixpacks is a single-package repo with no native deps — and CBP doesn't have any of those.
+
+## Canonical NestJS Dockerfile (pnpm + Turborepo)
+
+Place at `apps/backend/Dockerfile`, set `RAILWAY_DOCKERFILE_PATH=apps/backend/Dockerfile` on the service. Build context is the repo root.
+
+```dockerfile
+# syntax=docker/dockerfile:1.7
+
+# ---- builder ----
+FROM node:22-alpine AS builder
+WORKDIR /repo
+RUN corepack enable && corepack prepare pnpm@10.12.4 --activate
+
+COPY pnpm-lock.yaml pnpm-workspace.yaml package.json turbo.json ./
+COPY apps/backend/package.json ./apps/backend/
+COPY packages/auth/package.json ./packages/auth/
+COPY packages/design-tokens/package.json ./packages/design-tokens/
+
+RUN --mount=type=cache,id=s/pnpm-store,target=/root/.local/share/pnpm/store \
+    pnpm install --frozen-lockfile
+
+COPY . .
+RUN pnpm turbo run build --filter=@codebyplan/backend...
+RUN pnpm --filter=@codebyplan/backend deploy --prod /out
+
+# ---- runtime ----
+FROM node:22-alpine AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+RUN apk add --no-cache tini
+
+COPY --from=builder /out/node_modules ./node_modules
+COPY --from=builder /out/dist ./dist
+COPY --from=builder /out/package.json ./package.json
+
+EXPOSE 3000
+ENTRYPOINT ["/sbin/tini", "--"]
+CMD ["node", "dist/main.js"]
+```
+
+Notes: `--mount=type=cache,id=s/...` uses Railway's persistent build cache. `pnpm deploy --prod` produces a self-contained dir with hoisted prod deps (slim image). `tini` as PID 1 forwards SIGTERM cleanly so NestJS shuts down on rolling deploys. `EXPOSE 3000` is documentation only — Railway routes to whatever `$PORT` your process binds.
+
+## $PORT Binding
+
+Railway assigns `PORT` per deployment. NestJS bootstrap MUST honour it:
+
+```ts
+// apps/backend/src/main.ts
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  app.enableShutdownHooks(); // pairs with tini in the Dockerfile
+  const port = parseInt(process.env.PORT ?? '3000', 10);
+  await app.listen(port, '0.0.0.0'); // 0.0.0.0, NOT localhost
+}
+bootstrap();
+```
+
+Two extremely common failures: (1) listening on `localhost`/`127.0.0.1` — Railway's proxy can't reach you and the healthcheck times out; (2) hardcoding `3000` — works locally but Railway thinks the service never came up.
+
+## Health Endpoint
+
+Configure per service: `Settings → Deploy → Healthcheck Path` (e.g. `/health`) and timeout (default 100s, max 300s). On failure the new deployment never replaces the old — old keeps serving, new is marked CRASHED.
+
+Use `@nestjs/terminus`:
+
+```ts
+// apps/backend/src/health/health.module.ts
+import { Module } from '@nestjs/common';
+import { TerminusModule } from '@nestjs/terminus';
+import { HealthController } from './health.controller';
+
+@Module({ imports: [TerminusModule], controllers: [HealthController] })
+export class HealthModule {}
+```
+
+```ts
+// apps/backend/src/health/health.controller.ts
+import { Controller, Get } from '@nestjs/common';
+import { HealthCheck, HealthCheckService, HttpHealthIndicator } from '@nestjs/terminus';
+
+@Controller('health')
+export class HealthController {
+  constructor(private health: HealthCheckService, private http: HttpHealthIndicator) {}
+
+  @Get()
+  @HealthCheck()
+  check() {
+    return this.health.check([
+      () => this.http.pingCheck('self', `http://localhost:${process.env.PORT ?? '3000'}/`),
+    ]);
+  }
+}
+```
+
+Keep healthchecks **cheap and dependency-free**. Don't ping Supabase here — a transient Supabase blip would mark every Railway deploy as failed and you'd be unable to ship. For "is my DB reachable" use a separate `/ready` endpoint that uptime monitors poll.
+
+## Env Var Management
+
+Three layers: **service vars** (`Settings → Variables`, default home for secrets) → **shared vars** (project-level, referenced as `${{ shared.NAME }}`) → **reference vars** (pull from another service: `${{ Postgres.DATABASE_URL }}`).
+
+CBP convention for a NestJS-on-Supabase backend:
+
+```
+# Shared (project-level)
+SUPABASE_URL=https://<project>.supabase.co
+SUPABASE_ANON_KEY=...
+
+# Service-only (api service)
+SUPABASE_SERVICE_ROLE_KEY=...   # never share — staging/prod must differ
+SENTRY_DSN=...
+NODE_ENV=production
+```
+
+Rules: `NODE_ENV=production` always — even in staging (differentiate via `RAILWAY_ENVIRONMENT_NAME`). Never put service-role secrets in shared. Use the dashboard "raw editor" for bulk paste; the UI input strips trailing newlines and occasionally mangles `=` in values.
+
+## Multi-Service Projects
+
+A typical CBP backend project:
+
+| Service | Source | Purpose |
+|---------|--------|---------|
+| `api` | GitHub: `apps/backend` | NestJS HTTP API |
+| `worker` | GitHub: `apps/backend` (different start cmd) | Queue/cron worker if needed |
+| `postgres` | Railway template | Optional fallback DB (Supabase is primary) |
+
+To run two services off one repo: create two services on the same GitHub repo, override `Settings → Deploy → Start Command` per service (`node dist/main.js` for api, `node dist/worker.js` for worker), set `RAILWAY_DOCKERFILE_PATH` the same on both.
+
+Internal traffic uses `<service-name>.railway.internal:<port>` (IPv6) — no public hop, no egress cost.
+
+## Custom Domains
+
+`Settings → Networking → Custom Domain → Add`. Railway provisions Let's Encrypt automatically. DNS: subdomain via `CNAME api → <generated>.up.railway.app`; apex via Railway's CNAME flattening / ALIAS, or buy the domain via Railway and it auto-wires.
+
+CBP convention: production `api.codebyplan.com` → Railway production env's api service. Staging stays on the generated `up.railway.app` domain unless there's a reason for a real subdomain.
+
+## Build Caching
+
+Two caches matter: (1) **layer cache** — Railway preserves Docker layers per service; order Dockerfile so manifest copy + install precedes source copy (canonical Dockerfile above does this); (2) **cache mounts** — `--mount=type=cache,id=s/<service id>-<path>,target=<path>` for pnpm store, npm cache. The `s/<service id>` prefix is Railway-specific and scopes the cache per service.
+
+Clean rebuild (no cache): ~3-5 min for a typical CBP backend. Cached: ~30-60 sec — almost entirely the source COPY + turbo build steps.
+
+## Sources
+
+- https://docs.railway.com/guides/dockerfiles
+- https://docs.railway.com/guides/healthchecks
+- https://docs.railway.com/guides/variables
+- https://docs.railway.com/reference/private-networking

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

@@ -0,0 +1,120 @@
+# Railway Overview
+
+Railway (railway.com, formerly railway.app) is the standard backend deployment target for the CodeByPlan family of repos. The `/cbp-ship` orchestrator's `railway-backend` surface targets it for NestJS API services, scheduled workers, and any long-running process that doesn't belong on Vercel's edge/serverless surface.
+
+## What Railway Is
+
+A platform-as-a-service that runs containers (or Nixpacks/Railpack-built images) from a GitHub repo or a CLI push. It handles:
+
+- Build (Dockerfile, Nixpacks, or Railpack — auto-detected)
+- Deploy (rolling, with healthcheck gating)
+- Networking (public HTTPS endpoint + private `*.railway.internal` mesh)
+- Env var management (per-service, per-environment, with shared groups)
+- Logs / metrics / smart diagnosis
+
+It is positioned as "Heroku, but you pay for what you use, with Docker as a first-class citizen."
+
+## When to Pick Railway (vs Alternatives)
+
+| Need | Pick |
+|------|------|
+| Long-running NestJS API, scheduled job, queue worker | **Railway** |
+| WebSocket server, gRPC, raw TCP | **Railway** |
+| Edge-rendered Next.js, ISR-heavy site | **Vercel** |
+| Static site / Jamstack with form handlers | **Vercel** or Netlify |
+| Self-host on a single $5 box, no CI/CD | Render or Fly.io |
+| Multi-region with Anycast and global edge state | **Fly.io** |
+| Already on Supabase + need adjacent worker | **Railway** (best Supabase neighbour — same VPC-style flow) |
+
+CodeByPlan's rule of thumb: **NestJS = Railway, Next.js web = Vercel**. The desktop and VS Code apps don't deploy to Railway at all.
+
+## Pricing Model (as of Apr 2026)
+
+| Plan | Base | Includes | Usage |
+|------|------|----------|-------|
+| Hobby | $5/mo | $5 of usage credit | $0.000231/GB-hour RAM, $0.000463/vCPU-hour |
+| Pro | $20/mo per seat | $20 of usage credit per seat | Same per-resource rates, no cap |
+| Enterprise | Custom | SOC2, dedicated support | Custom |
+
+The `$5/mo` Hobby fee **is** the $5 of usage — it's a credit, not a base + usage. A typical CBP NestJS backend (256 MB RAM, ~5% CPU avg) runs ~$3-4/mo, fitting inside Hobby.
+
+Pro is required for: team seats, priority support, multi-region, committed spend discounts, Metal regions for production workloads.
+
+See https://railway.com/pricing for the live rate card.
+
+## Key Concepts
+
+```
+Project
+  └── Environment (e.g. production, staging, pr-42)
+        └── Service (e.g. api, worker, postgres)
+              └── Deployment (a build+release of one commit)
+```
+
+- **Project** — top-level container; usually one per repo or one per app family. CBP convention: one project per backend repo.
+- **Environment** — a parallel copy of all services in a project. `production` is created by default. PR environments are auto-spawned via the GitHub integration if enabled.
+- **Service** — one running thing (an API, a worker, a managed Postgres). Each service has its own image, env vars, domain, replicas.
+- **Deployment** — one build of one service. Railway keeps deployment history; you can roll back via the dashboard or `railway redeploy`.
+
+## CLI Auth Model
+
+```bash
+npm i -g @railway/cli   # or pnpm add -g @railway/cli
+railway login           # opens browser, OAuths against your Railway account
+railway link            # binds CWD to a project + environment + service
+railway up              # tar-up CWD and push as a one-off deployment
+railway run -- <cmd>    # run <cmd> with the linked service's env vars
+railway logs            # tail logs for the linked service
+```
+
+`railway login --browserless` produces a pairing code for headless/CI environments. CI typically uses `RAILWAY_TOKEN` (project token, scoped to one project) instead — set it as an env var and skip `login` entirely.
+
+The `.railway/` directory in CWD stores the link (project ID, environment, service). It is gitignored by default — do not commit it.
+
+## GitHub Auto-Deploys
+
+Railway's GitHub integration is the production deploy path for every CBP backend. Mechanics:
+
+1. Connect the repo to the service via the dashboard (one-time).
+2. Pick a branch (CBP convention: `main` for production, `development` for staging if a staging environment exists).
+3. Every push to that branch triggers a build → healthcheck → swap.
+4. PRs against the configured branch can auto-spawn ephemeral environments (opt-in per project).
+
+**Important:** the GitHub integration uses a webhook. If Railway shows "no deployment triggered" after a push, check the webhook delivery log on the GitHub side first — see [railway-troubleshooting.md](./railway-troubleshooting.md).
+
+## How `/cbp-ship` Uses Railway
+
+The `railway-backend` surface in `/cbp-ship`:
+
+1. Confirms `apps/backend` (or whatever the NestJS app is) builds clean locally
+2. Runs the test suite tied to the backend
+3. Pushes the deploy branch (usually `main`) — Railway picks it up via webhook
+4. Polls `railway logs` (or the GraphQL API via `RAILWAY_TOKEN`) for the new deployment
+5. Verifies healthcheck passes and surfaces the deployment URL
+6. Records the deploy outcome (deployment ID + commit SHA) on the round/task record
+
+The orchestrator does NOT call `railway up` directly for production — that bypasses the GitHub history and breaks rollback. CLI push is reserved for one-off debugging.
+
+## Recent Platform Changes Worth Knowing
+
+(From https://railway.com/changelog — keep this short, prune when stale.)
+
+- **Railway Metal** — dedicated-hardware regions, including EU (Amsterdam) and SE Asia, available on Pro+. Use for latency-sensitive prod.
+- **Multi-region deployments** — single service can run replicas in multiple regions. Pro+.
+- **One-click HA Postgres** — replicated managed Postgres without manual setup. Useful when CBP repos outgrow Supabase's free tier and want a Railway-native DB.
+- **Buckets** — Railway-native object storage with CLI support. Alternative to S3/R2 when staying in-platform matters.
+- **Railpack** — successor build system to Nixpacks for some languages (Elixir, Ruby, Rust). Auto-detected; no migration needed.
+- **IPv6** — full IPv6 support across public + private networking.
+- **Smart Diagnosis** — automated build/deploy failure analysis surfaced in the dashboard. Read its output before opening a support ticket.
+
+## Sources
+
+- https://docs.railway.com — primary reference
+- https://railway.com/changelog — platform updates
+- https://railway.com/pricing — current rate card
+
+## See also
+
+- [railway-nestjs-deployment.md](./railway-nestjs-deployment.md) — concrete CBP-shape walkthrough
+- [railway-troubleshooting.md](./railway-troubleshooting.md) — failure-mode reference
+- [surface-railway.md](./surface-railway.md) — `/cbp-ship` deploy steps for this surface

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