codebyplan 1.5.1 → 1.9.0

package/templates/skills/cbp-ship/reference/npm-publish-overview.md

@@ -0,0 +1,171 @@
+# npm Publish — Overview
+
+Reference for the `/cbp-ship` orchestrator's `npm-package` surface. Covers what `npm publish` does, registry types, 2FA tiers, package metadata that affects publish output, and `latest` dist-tag semantics.
+
+## What `npm publish` Does
+
+`npm publish` packs the current package into a tarball and uploads it to a registry, registering the version under the package name. Once a version is published it is **immutable** — you cannot republish the same `name@version` (you can only `npm unpublish` within 72 hours, and only if no other public package depends on it).
+
+Pack rules:
+
+1. CLI computes the file list from (in order): `files` field in `package.json`, `.npmignore`, `.gitignore`. Always-included: `package.json`, `README*`, `LICENSE*`, the file at `main`/`bin`/`exports`. Always-excluded: `node_modules`, `.git`, `.npmrc`, `package-lock.json`.
+2. CLI runs lifecycle scripts: `prepublishOnly` → `prepack` → tarball write → `postpack` → `publish` → `postpublish`.
+3. Tarball uploaded to registry with auth (token or OIDC); registry assigns the `latest` dist-tag unless `--tag <name>` overrides.
+
+`npm publish --dry-run` runs all the above except the upload — use it to preview the file list and lifecycle execution.
+
+## Registry Types
+
+| Registry | Purpose | URL |
+|----------|---------|-----|
+| Public registry | Default; what `npm install <pkg>` hits | `https://registry.npmjs.org` |
+| GitHub Packages | npm packages scoped to a GitHub org | `https://npm.pkg.github.com` |
+| Private registry | Verdaccio, Nexus, JFrog Artifactory, Bytesafe, Cloudsmith | self-hosted or vendor URL |
+
+Registry selection comes from (highest precedence first):
+
+1. `publishConfig.registry` in `package.json`
+2. `--registry <url>` on the CLI
+3. `npm_config_registry` env var
+4. `registry=` line in `.npmrc` (project, then user, then global)
+5. Default — `https://registry.npmjs.org`
+
+Scoped packages (`@scope/name`) can route by scope: `@cbp-registry=https://npm.pkg.github.com` in `.npmrc` sends only that scope to GH Packages.
+
+## 2FA Tiers
+
+npm offers two 2FA modes (set with `npm profile enable-2fa <mode>`):
+
+| Mode | Covers | Use case |
+|------|--------|----------|
+| `auth-only` | Login, profile changes | Convenience — publishes work with token alone |
+| `auth-and-writes` | Login + every publish, `dist-tag`, `unpublish`, `access` change | Hardened — publish requires fresh OTP |
+
+Publishing requires **one** of:
+
+- 2FA enabled on the account (any mode), OR
+- A **granular access token** with "bypass 2FA" enabled (legacy automation tokens are deprecated; granular is the modern equivalent).
+
+For CI flows the modern recommendation is **OIDC trusted publishing** (no token at all) — see [npm-publish-oidc-trusted.md](./npm-publish-oidc-trusted.md). Granular tokens with bypass-2FA remain valid for non-CI release machines.
+
+## Package Metadata That Matters at Publish Time
+
+### `exports`
+
+Modern entry-point map. Replaces `main` for resolvers that honour it (Node ≥12.20, all modern bundlers). Conditional exports let you ship CJS + ESM + types from one package:
+
+```json
+{
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  }
+}
+```
+
+Always export `./package.json` — toolchains (`publint`, `attw`) and some bundlers expect it. If `exports` is set, `main` becomes a fallback only for legacy resolvers.
+
+### `files`
+
+Allowlist of paths to include in the tarball. Prefer `files` over `.npmignore` — allowlists fail closed (forgetting to ignore a build artefact never leaks a secret):
+
+```json
+{
+  "files": ["dist", "README.md", "LICENSE"]
+}
+```
+
+`package.json`, `README*`, `LICENSE*` are always included regardless. `test/`, `__tests__/`, `*.test.*` are excluded automatically.
+
+### `publishConfig`
+
+Per-package override of registry config, applied only at publish time. Common keys:
+
+```json
+{
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "tag": "next",
+    "provenance": true
+  }
+}
+```
+
+- `access: "public"` is required when first publishing a scoped package (`@scope/name`); otherwise registry assumes private and rejects free-tier accounts.
+- `tag: "next"` (or any non-`latest`) keeps the version off the default install pointer — useful for prereleases.
+- `provenance: true` is the package.json equivalent of `--provenance` (see [npm-publish-oidc-trusted.md](./npm-publish-oidc-trusted.md)).
+
+### `engines`
+
+Declares Node/npm version compatibility:
+
+```json
+{
+  "engines": { "node": ">=20.0.0", "pnpm": ">=10.0.0" }
+}
+```
+
+By default `engines` is advisory (warns, does not fail). `engine-strict=true` in `.npmrc` makes it a hard error on install.
+
+### `bin`
+
+Maps CLI command names to file paths. The published tarball will mark these executable; the install will create symlinks in `node_modules/.bin`:
+
+```json
+{
+  "bin": { "codebyplan": "./dist/cli.js" }
+}
+```
+
+The target file must have a shebang (`#!/usr/bin/env node`).
+
+## `latest` Dist-Tag Semantics
+
+When a user runs `npm install <pkg>` without a version specifier, npm resolves to whatever the `latest` dist-tag points at. Implications:
+
+- The first publish of a package always becomes `latest`.
+- Subsequent publishes become `latest` **unless** `--tag <name>` is passed (or `publishConfig.tag` is set to something other than `latest`).
+- Publishing a hotfix to an older major (e.g. `1.5.3` after `2.0.0` is already `latest`) will overwrite `latest` to point back at `1.5.3` — almost always a mistake. Use `npm publish --tag legacy` for hotfixes on old majors, then `npm dist-tag add <pkg>@1.5.3 v1-legacy` to give consumers an explicit pointer.
+
+Common dist-tag conventions:
+
+| Tag | Convention |
+|-----|-----------|
+| `latest` | Default install target — stable releases only |
+| `next` | Upcoming version (often release candidates) |
+| `beta` / `alpha` | Prereleases — opt-in via `npm install pkg@beta` |
+| `canary` / `nightly` | Auto-published from main branch |
+
+Manage tags after publish:
+
+```bash
+npm dist-tag ls <pkg>             # list all tags
+npm dist-tag add <pkg>@<ver> next # promote a version to a tag
+npm dist-tag rm <pkg> beta        # remove a tag (does not unpublish)
+```
+
+Tags must not parse as valid semver ranges — `v1.4` is rejected, `v1-legacy` is fine.
+
+## Pre-Publish Checklist
+
+For a clean publish via `/cbp-ship`:
+
+1. `npm whoami` (or OIDC trust verified) — confirm auth context.
+2. `npm publish --dry-run` — review the file list; nothing surprising.
+3. `npx publint` — lint package.json shape.
+4. `npx @arethetypeswrong/cli --pack` — verify type resolution across CJS/ESM.
+5. Version bump committed and tagged in git (release-please or changesets handles this).
+6. CI green on the commit being published.
+
+## Sources
+
+- [npm Docs — package.json](https://docs.npmjs.com/cli/v10/configuring-npm/package-json)
+- [npm Docs — npm publish](https://docs.npmjs.com/cli/v10/commands/npm-publish)
+- [npm Docs — npm dist-tag](https://docs.npmjs.com/cli/v10/commands/npm-dist-tag)
+- [npm Docs — Configuring 2FA](https://docs.npmjs.com/configuring-two-factor-authentication)
+- [npm CLI source](https://github.com/npm/cli)

package/templates/skills/cbp-ship/reference/preflight-checklist.md

@@ -0,0 +1,88 @@
+# Pre-flight Checklist
+
+Run before invoking `/cbp-ship`. The orchestrator's Step 1 detection runs this implicitly; this file documents what it checks and what to do when a check fails.
+
+## Universal pre-flight (every shipment)
+
+| # | Check | Why | If fails |
+|---|---|---|---|
+| 1 | `gh auth status` succeeds | gh CLI is needed for tag push, release verification | `gh auth login` |
+| 2 | Working tree is clean (no uncommitted changes) | Shipping uncommitted code = ghosts | Commit or stash; do NOT proceed |
+| 3 | Current branch matches expected post-promotion branch | Caller (`/cbp-checkpoint-end`) just merged into PRODUCTION | If wrong, `git checkout` correct branch |
+| 4 | `.codebyplan/` files are parseable | All config reads from per-concern files | Fix JSON; or run `npx codebyplan config` |
+| 5 | Active checkpoint exists in DB | Shipment is per-checkpoint | Run `/cbp-todo` to find/create checkpoint |
+| 6 | `checkpoint.context.check_results` exists | Checkpoint check must pass before shipment | Run `/cbp-checkpoint-check` first |
+
+## Per-surface pre-flight
+
+The detection script (`scripts/detect-surfaces.sh`) emits `configured: false` with a `reason` when a surface fails its pre-flight. Rather than duplicating those reasons here, see each surface's `## Configured indicators` section in its reference file.
+
+Quick reference:
+
+| Surface | Critical pre-flight check |
+|---|---|
+| `vercel-web` | `vercel whoami` succeeds AND `.vercel/project.json` exists |
+| `expo-mobile` | `eas whoami` succeeds AND `eas.json` parseable AND credentials valid (`eas credentials` audit) |
+| `tauri-desktop` | All 9 GH secrets present in repo (`gh secret list`) |
+| `npm-package` | `npm whoami` succeeds AND 2FA enabled AND local version > registry version |
+| `vscode-ext` | `vsce verify-pat <publisher>` succeeds |
+| `railway-backend` | `railway whoami` succeeds AND service is linked AND env vars set |
+| `supabase` | `supabase projects list` succeeds AND project ref matches |
+
+## Recommended pre-flight when adding a new surface
+
+If you're configuring a surface for the first time (via `/cbp-ship-configure`), run these once:
+
+1. **For Vercel**:
+   - Verify build works locally: `pnpm build`
+   - Verify env vars are documented: `cat .env.example`
+   - Verify domain DNS is healthy if using custom domain
+
+2. **For Expo / mobile**:
+   - Verify Apple Developer account is enrolled (paid)
+   - Verify ASC API key is generated and `.p8` file is readable
+   - Verify EAS project is created: `eas project:info`
+   - Run a development build first: `eas build --profile development --platform ios`
+
+3. **For Tauri desktop**:
+   - Generate signing key: `npx tauri signer generate -w ~/.tauri/{app}.key`
+   - Export Apple Developer ID cert as `.p12`
+   - Upload all 9 GH secrets per architecture doc
+   - Test the workflow on a non-production tag first (e.g., `v0.0.0-test`)
+
+4. **For npm package**:
+   - Verify `package.json` has `name`, `version`, `description`, `keywords`, `repository`, `license`, `author`
+   - Run `npm pack --dry-run` and verify the tarball contains the right files
+   - Run `pnpm publint` to catch metadata issues
+   - Run `pnpm attw --pack` to verify TS types resolve correctly
+
+5. **For VS Code extension**:
+   - Create a publisher account at https://aka.ms/vscode-create-publisher
+   - Generate PAT with "Marketplace → Manage" scope
+   - Run `vsce verify-pat <publisher>` — succeeds = good
+   - Verify `package.json` has `displayName`, `description`, `categories`, `icon` (≥128×128 PNG)
+
+6. **For Railway**:
+   - Create project: `railway init`
+   - Link service: `railway link`
+   - Add env vars: `railway variables set KEY=VALUE`
+   - Configure health endpoint in service code (`/health` returning 200)
+   - Test deploy: `railway up`
+
+7. **For Supabase**:
+   - Verify migrations directory is initialized: `ls supabase/migrations/`
+   - Link project: `supabase link --project-ref <ref>`
+   - Generate baseline migration if existing schema: `supabase db dump > supabase/migrations/0000_baseline.sql`
+   - Verify types path: `supabase gen types typescript --project-id <ref> > types.ts`
+
+## When pre-flight fails mid-shipment
+
+If `/cbp-ship` is mid-shipment and a per-surface pre-flight fails:
+
+1. Mark that surface failed
+2. Continue with remaining surfaces (don't halt the whole shipment unless `supabase` failed)
+3. Surface the failure in the final report
+4. Suggest the user run `/cbp-ship-configure --surface=<id>` to fix
+5. After fix, re-run `/cbp-ship` — it picks up where it left off (verified surfaces are skipped)
+
+The shipment record (`checkpoint.context.shipment`) tracks per-surface status, so partial re-runs are safe.

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