rsc-universal 0.1.1

package/skills/rails/references/testing.md

@@ -0,0 +1,110 @@
+# Rails testing
+
+Minitest + fixtures is the framework default and what fresh apps ship with. RSpec-rails
+is the popular alternative. Pick one per app; don't mix.
+
+## Minitest layout (default)
+
+```text
+test/
+  models/         ActiveSupport::TestCase
+  integration/    ActionDispatch::IntegrationTest
+  controllers/    ActionDispatch::IntegrationTest
+  system/         ApplicationSystemTestCase
+  jobs/           ActiveJob::TestCase
+  fixtures/       *.yml — loaded once per suite
+```
+
+Run: `bin/rails test` (unit/integration), `bin/rails test:system` (browser). Parallel
+execution is on by default via `parallelize(workers: :number_of_processors)` in
+`test_helper.rb`.
+
+## RSpec-rails setup
+
+```ruby
+# Gemfile (test group)
+gem "rspec-rails", "~> 8.0"
+gem "capybara"
+```
+
+```bash
+bundle exec rails generate rspec:install   # creates spec/ + spec_helper
+```
+
+Specs live under `spec/{models,requests,system,jobs}`. Prefer **request specs** over
+controller specs (the Rails team's guidance) — they hit the full middleware stack.
+
+## Fixtures vs factories
+
+- **Fixtures** (default): YAML rows loaded once into the test DB. Fast, but every test
+  shares the same data, so they drift toward a tangled global fixture set.
+- **Factories** (FactoryBot): build objects per test. More expressive for per-test
+  variation, slower if you `create` when `build`/`build_stubbed` would do.
+
+Default to fixtures; introduce FactoryBot when fixture sprawl makes intent unclear.
+
+```yaml
+# test/fixtures/posts.yml
+one:
+  title: First post
+  author: alice          # references users.yml by label, resolves the FK
+  published_at: <%= 2.days.ago %>
+```
+
+Gotcha: fixture labels become stable IDs via a hash — reference associations by label,
+never by hard-coded integer ID.
+
+## System-test driver config
+
+Default driver is Selenium + headless Chrome. It's the flakiest with Turbo. Swap to
+**Cuprite** (CDP, no Selenium) or **Playwright** to cut timing flake and speed up CI.
+
+```ruby
+# test/application_system_test_case.rb (Cuprite example)
+require "capybara/cuprite"
+
+class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  driven_by :cuprite, screen_size: [1400, 1400], options: { headless: true }
+end
+```
+
+Hardening rules:
+- Use auto-waiting matchers (`assert_selector`, `assert_text`, `assert_no_selector`,
+  `has_no_text?`) — they retry up to Capybara's default wait. Never `sleep N`.
+- Assert the *absence* of the old state with `assert_no_*` (also auto-waits) rather than
+  asserting presence too early.
+- Keep one logical interaction per assertion block so a failure points at the step.
+
+## Testing jobs
+
+```ruby
+class CommentNotificationJobTest < ActiveJob::TestCase
+  test "enqueues on comment create" do
+    assert_enqueued_with(job: CommentNotificationJob) do
+      posts(:one).comments.create!(body: "hi")
+    end
+  end
+
+  test "performs idempotently when comment is gone" do
+    assert_nothing_raised { CommentNotificationJob.perform_now(-1) }
+  end
+end
+```
+
+Use `perform_enqueued_jobs` / `assert_enqueued_jobs` to control whether jobs run inline
+or just enqueue.
+
+## Testing broadcasts
+
+```ruby
+assert_broadcasts [post, :comments], 1 do
+  post.comments.create!(body: "live")
+end
+```
+
+## What to test
+
+Behavior through the public surface: a request returns the right status/redirect/body;
+a model method changes state correctly; a job enqueues and is idempotent. Do **not**
+test private methods — they're implementation, and locking tests to them turns every
+refactor into a test rewrite.

package/skills/rails/scripts/verify.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+#
+# verify.sh - read-only static gate for a Rails 8 app.
+#
+# Usage:
+#   cd <rails-app-root>
+#   /path/to/verify.sh [TARGET_DIR]      # TARGET_DIR defaults to .
+#
+# Checks, all guarded so a clean/empty/non-Rails target still passes:
+#   1. RuboCop  - only if rubocop is installed AND a .rubocop.yml is present.
+#                 Report-only; style is advisory, never fatal here.
+#   2. bin/rails zeitwerk:check - autoload-path sanity, only if bin/rails exists.
+#   3. grep banlist for statically-detectable anti-patterns (HARD failures):
+#        a. Sidekiq / `gem "redis"` in an app that ships the Solid stack default.
+#        b. `.all.each` mass loads in app/.
+#        c. `add_index ... concurrently` without `disable_ddl_transaction!` in
+#           the same migration file.
+#
+# Read-only: never writes, formats, or mutates your source.
+# Exit codes: 0 = clean OR nothing to check OR only advisory issues;
+#             1 = a hard banlist violation.
+# Portable to stock macOS bash 3.2 (no mapfile, no associative arrays).
+
+set -euo pipefail
+
+target="${1:-.}"
+
+if [ -t 1 ]; then
+  YELLOW=$'\033[33m'; RED=$'\033[31m'; GREEN=$'\033[32m'; RESET=$'\033[0m'
+else
+  YELLOW=''; RED=''; GREEN=''; RESET=''
+fi
+
+have() { command -v "$1" >/dev/null 2>&1; }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$RESET" "$*"; }
+fail() { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$*"; }
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN" "$RESET" "$*"; }
+
+if [ ! -d "$target" ]; then
+  printf '%serror:%s target dir not found: %s\n' "$RED" "$RESET" "$target" >&2
+  exit 2
+fi
+
+# Is this even a Rails-ish tree? If not, pass cleanly (nothing to gate).
+if [ ! -d "$target/app" ] && [ ! -f "$target/config/routes.rb" ] \
+   && [ ! -f "$target/bin/rails" ] && [ ! -d "$target/db/migrate" ]; then
+  skip "no app/ , config/routes.rb , bin/rails or db/migrate under $target - nothing to check"
+  exit 0
+fi
+
+failed=0
+
+# ---- 1. RuboCop (report-only, advisory) ------------------------------------
+if [ -f "$target/.rubocop.yml" ] && have rubocop; then
+  printf -- '----- rubocop (report only)\n'
+  ( cd "$target" && rubocop ) || skip "rubocop reported style issues (non-fatal)"
+else
+  skip "rubocop or .rubocop.yml absent - skipping lint"
+fi
+
+# ---- 2. zeitwerk autoload check --------------------------------------------
+if [ -x "$target/bin/rails" ]; then
+  printf -- '----- bin/rails zeitwerk:check\n'
+  if ( cd "$target" && bin/rails zeitwerk:check ) >/dev/null 2>&1; then
+    ok "zeitwerk:check passed"
+  else
+    skip "zeitwerk:check did not pass cleanly (boot/env may be unavailable here) - non-fatal"
+  fi
+else
+  skip "bin/rails absent - skipping zeitwerk:check"
+fi
+
+# ---- 3. Static banlist (hard failures) -------------------------------------
+
+# 3a. Sidekiq / redis gem in a Solid-default app.
+gemfile="$target/Gemfile"
+if [ -f "$gemfile" ]; then
+  if grep -Eq '^\s*gem\s+["'\'']sidekiq["'\'']' "$gemfile" \
+     || grep -Eq '^\s*gem\s+["'\'']redis["'\'']' "$gemfile"; then
+    if grep -Eq '^\s*gem\s+["'\'']solid_queue["'\'']' "$gemfile"; then
+      fail "Gemfile pulls Sidekiq/redis alongside solid_queue - drop it unless a real throughput need is stated"
+      failed=1
+    else
+      skip "Gemfile references sidekiq/redis but no solid_queue - not a Rails-8-default app, leaving it"
+    fi
+  else
+    ok "no Sidekiq/redis gem in Gemfile"
+  fi
+fi
+
+# 3b. .all.each mass loads in app/.
+if [ -d "$target/app" ]; then
+  hits=$(grep -rEn '\.all\.each\b' "$target/app" --include='*.rb' 2>/dev/null || true)
+  if [ -n "$hits" ]; then
+    fail ".all.each mass load found - use find_each / includes:"
+    printf '%s\n' "$hits" | sed 's/^/      /'
+    failed=1
+  else
+    ok "no .all.each mass loads in app/"
+  fi
+fi
+
+# 3c. Concurrent add_index without disable_ddl_transaction!.
+if [ -d "$target/db/migrate" ]; then
+  bad=""
+  for f in "$target"/db/migrate/*.rb; do
+    [ -e "$f" ] || continue
+    if grep -Eq 'add_index.*:concurrently' "$f" \
+       && ! grep -q 'disable_ddl_transaction!' "$f"; then
+      bad="$bad $f"
+    fi
+  done
+  if [ -n "$bad" ]; then
+    fail "concurrent add_index without disable_ddl_transaction! :"
+    for f in $bad; do printf '      %s\n' "$f"; done
+    failed=1
+  else
+    ok "concurrent indexes (if any) declare disable_ddl_transaction!"
+  fi
+fi
+
+if [ "$failed" -ne 0 ]; then
+  printf '%sverify failed:%s hard violations above.\n' "$RED" "$RESET" >&2
+  exit 1
+fi
+
+printf '%sverify ok: no hard violations.%s\n' "$GREEN" "$RESET"
+exit 0

package/skills/railway/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: railway
+description: "Use when deploying an app to Railway — pushing a repo or running railway up, provisioning a managed database, wiring env and reference variables, attaching a volume, or fixing a Railway deploy that builds but won't serve. Triggers: 'deploy this on Railway', 'railway up', 'add Postgres to Railway', 'railway.json healthcheck path', 'my Railway service binds localhost and 502s', 'reference DATABASE_URL across two services', 'two Railway services need to talk privately', 'desplegar en Railway', 'mi servicio de Railway no arranca'. NOT Render (that is render), NOT Fly machines (that is fly-io), NOT self-hosted PaaS on your own box (that is coolify)."
+tags: [railway, paas, deploy, services, env-vars, volumes, databases, private-networking, railway-json]
+recommends: [render, fly-io, coolify, postgresdb, db-migrations, domains-dns, deployment, docker]
+origin: risco
+---
+
+# Railway — ship a repo to a managed PaaS
+
+Railway is an opinionated PaaS: connect a GitHub repo or run `railway up`, and it builds your
+code (Railpack by default, or your Dockerfile), runs the container, networks it, and hands you a
+domain. You manage *services, environments, variables, volumes, and databases* — not servers,
+not an OS. This skill makes you fast and correct on Railway's specific surface, not generic
+deploy theory.
+
+```text
+repo / `railway up`  →  Railpack (or Dockerfile) build  →  container runs (binds 0.0.0.0:$PORT)
+   →  variables + reference vars injected  →  private net (*.railway.internal) + public domain
+```
+
+## Is Railway the right target?
+
+Settle this before touching config. If the user named the platform, honor it and route.
+
+| Want | Use | Why / route |
+| --- | --- | --- |
+| Push a repo, get a built+running app with zero ops | **Railway** (this skill) | Managed PaaS, Railpack build, by-the-minute billing |
+| `render.yaml` Blueprint, free static sites, their dashboard model | `render` | Different PaaS — route to the `render` skill |
+| `fly.toml`, Firecracker microVMs, `fly machine`, multi-region edge | `fly-io` | Railway has no `fly machine` equivalent — route to `fly-io` |
+| Self-host the PaaS on your own Hetzner/DO box | `coolify` | Railway is fully managed; Coolify is BYO-server |
+| Raw VPS, you manage the OS | `hetzner` / `digitalocean` | IaaS, not PaaS |
+| Platform-agnostic release strategy (rolling, blue-green theory) | `deployment` | This skill is Railway mechanics, not strategy |
+
+## The 60-second path
+
+```bash
+# Install the CLI (pick one). npm form needs Node 16+.
+brew install railway                          # macOS
+npm i -g @railway/cli                          # any Node 16+ host
+bash <(curl -fsSL railway.com/install.sh)      # shell installer
+
+railway login            # opens browser; for CI use RAILWAY_TOKEN instead (no login)
+railway init             # create a NEW project from this dir, OR:
+railway link             # link this dir to an EXISTING project/service
+railway up               # build + deploy the current dir; streams build/deploy logs
+```
+
+Why `link` vs `init`: `init` makes a fresh project; `link` attaches an already-created project
+(the common case once the project exists in the dashboard). `railway up` deploys whatever is in
+the working dir — no git push required.
+
+## Two ways to deploy — pick one per service
+
+- **GitHub auto-deploy** (default for most teams): connect the repo in the dashboard; every push
+  to the watched branch triggers a build + deploy. Best when you want CI-style "merge to ship".
+- **CLI `railway up`**: deploy the working tree directly. Best for first setup, hotfixes, or
+  hosts without git. Use `railway up --detach` to not block on logs, `--service api` to target a
+  specific service in a multi-service project (otherwise it prompts).
+
+```bash
+railway up --detach --service api --environment production
+```
+
+There is no `railway deploy --prod` — that command does not exist. Use `railway up` (or push to
+the connected branch). To re-run the last deploy unchanged: `railway redeploy`.
+
+## Bind 0.0.0.0:$PORT — the #1 first-deploy failure
+
+Railway's edge proxy and private network reach your container over an injected `$PORT`. If you
+bind `localhost`/`127.0.0.1`, the build succeeds but every request 502s and healthchecks fail.
+
+```ts
+// Bad — only reachable from inside the container; proxy gets connection refused -> 502
+app.listen(3000, "127.0.0.1");
+
+// Good — listen on the injected port, bind all interfaces
+const port = Number(process.env.PORT) || 3000;
+app.listen(port, "0.0.0.0", () => console.log(`up on :${port}`));
+```
+
+Same rule for every stack: read `$PORT`, bind `0.0.0.0` (or `::` — see private networking).
+Never hardcode the port the proxy talks to.
+
+## Config as code — railway.json (or railway.toml)
+
+Commit `railway.json` to make build/deploy reproducible. **Code config overrides the
+dashboard** for the fields it sets. Per-environment overrides go under `environments.<name>`.
+
+```jsonc
+{
+  "$schema": "https://railway.com/railway.schema.json",
+  "build": {
+    "builder": "RAILPACK",
+    "buildCommand": "npm run build"
+  },
+  "deploy": {
+    "startCommand": "node dist/server.js",
+    "healthcheckPath": "/healthz",
+    "healthcheckTimeout": 300,
+    "restartPolicyType": "ON_FAILURE",
+    "restartPolicyMaxRetries": 10
+  },
+  "environments": {
+    "production": {
+      "deploy": { "numReplicas": 2 }
+    }
+  }
+}
+```
+
+`builder` is `RAILPACK` (default; Railway's successor to Nixpacks) or `DOCKERFILE` (a Dockerfile
+is also auto-detected). `restartPolicyType` is `ON_FAILURE` | `ALWAYS` | `NEVER`. The full field
+list — `watchPatterns`, `dockerfilePath`, `railpackVersion`, `preDeployCommand`,
+`multiRegionConfig`, `cronSchedule`, `overlapSeconds`, `drainingSeconds`, and TOML variants —
+lives in [references/config-as-code.md](references/config-as-code.md).
+
+## Variables & reference variables
+
+Set plain variables via CLI or dashboard; never inline secrets into `railway.json` (it's
+committed).
+
+```bash
+railway variables                         # list
+railway variables --set "LOG_LEVEL=info"  # set (older: railway variable set KEY=value)
+```
+
+Wire one service's value into another with template syntax instead of copying it. References
+stay correct across credential rotations and across environments.
+
+```bash
+# Bad — hardcoded, breaks the moment Railway rotates the DB password
+DATABASE_URL=postgresql://user:p4ss@containers-us-west-12.railway.app:6543/railway
+
+# Good — reference the Postgres service's own variable
+DATABASE_URL=${{Postgres.DATABASE_URL}}
+```
+
+Also available: `${{shared.SENTRY_DSN}}` (project-shared vars) and Railway-provided vars like
+`${{RAILWAY_PUBLIC_DOMAIN}}`. The left side of the dot is the *service name* exactly as it
+appears in the project.
+
+## Managed databases
+
+Add Postgres / MySQL / Redis / MongoDB as services from Railway's official templates, then
+reference their connection vars into the app.
+
+```bash
+railway add            # interactive: pick a database template (or use + New / cmd-K in dashboard)
+railway connect        # open a db shell (psql / mongosh / redis-cli) against the service
+```
+
+The DB service exposes vars (e.g. `DATABASE_URL`, `PGHOST`) on its Variables tab. Reference them
+into the app service as `${{Postgres.DATABASE_URL}}` — do not paste the literal URL. Schema
+design and SQL live in `postgresdb`; migrations live in `db-migrations`. This skill only
+provisions and wires.
+
+## Volumes
+
+Attach a volume to a service via the dashboard or CLI. Railway auto-injects
+`RAILWAY_VOLUME_NAME` and `RAILWAY_VOLUME_MOUNT_PATH` at runtime — read them, never define them
+yourself.
+
+```ts
+const dataDir = process.env.RAILWAY_VOLUME_MOUNT_PATH ?? "/data";
+```
+
+Gotcha: a volume pins the service to a single replica — **a volume blocks horizontal scaling**.
+If you need many replicas, keep state in a managed DB or object storage, not a volume.
+
+## Environments
+
+A project has `production` plus any environments you add (`staging`, PR environments). Each gets
+its own variables and its own `environments.<name>` config override. Switch with
+`railway environment <name>`; target a deploy with `railway up --environment staging`. Variables
+and reference targets resolve *within* the active environment.
+
+## Private networking
+
+Every service gets a DNS name under `*.railway.internal`. Talk service-to-service over it —
+internal egress is free, and traffic never leaves Railway.
+
+```bash
+# from the app service, reach the API service privately
+curl http://api.railway.internal:8080/internal/ping
+```
+
+IPv6 gotcha: environments created **before 2025-10-16 are IPv6-only** internally — bind `::`
+(not just `0.0.0.0`) or recreate the environment. Newer environments resolve both IPv4 and IPv6.
+Cross-project and cross-environment private traffic is blocked by design.
+
+## Domains
+
+```bash
+railway domain         # generate a *.up.railway.app domain for the current service
+```
+
+For a custom domain, add it in the service settings and Railway gives you a CNAME target. The
+registrar-side DNS record work (CNAME/ALIAS at your provider) belongs to `domains-dns` — this
+skill stops at "here is the CNAME target".
+
+## Healthcheck & failed-deploy triage
+
+Set `healthcheckPath` in `railway.json` so Railway gates the deploy on a real readiness route.
+When a deploy builds but won't go live, read `railway logs` and walk these in order:
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| 502 on every request, healthcheck times out | App bound `localhost`, not `0.0.0.0:$PORT` | Bind `0.0.0.0` (or `::`), listen on `$PORT` |
+| "no start command" / container exits 0 immediately | No `startCommand` and Railpack can't infer one | Set `deploy.startCommand` |
+| App crashes on boot referencing a config key | Missing variable / unresolved `${{...}}` reference | Set the var; check the service name in the reference |
+| Healthcheck 404s | `healthcheckPath` points at a route that doesn't exist | Point it at an existing route or remove it |
+
+## Cost awareness
+
+There is **no permanent free tier**. New accounts get a one-time **$5 trial credit**. Hobby is
+$5/mo (includes $5 usage), Pro is $20/mo (includes $20 usage); usage is billed **by the minute**
+and the included subscription credit is consumed first, then you pay the delta. An idle service
+left running still bills. Don't leave throwaway preview services up; delete environments you're
+done with.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| Binding `localhost` / `127.0.0.1` | Proxy + private net can't reach it → 502 | Bind `0.0.0.0` (or `::`), listen on `$PORT` |
+| Inlining a secret/connection string in `railway.json` | It's committed → leaked secret | Put secrets in variables; reference them |
+| Hardcoding `DATABASE_URL` into the app's vars | Breaks on credential rotation / env change | Use `${{Postgres.DATABASE_URL}}` |
+| One mega-service running web + worker + cron | No independent scaling/restart, tangled logs | Split into services in one project |
+| Assuming a free tier exists | Surprise — trial credit runs out, deploys stop | Plan for Hobby/Pro; watch by-the-minute usage |
+| Assuming IPv4 on a pre-2025-10-16 environment | Private DNS resolves IPv6-only → connection refused | Bind `::` or recreate the environment |
+| Committing the `.railway` link as if it were config | It's local link state, not portable config | Config-as-code goes in `railway.json` |
+
+## Verification
+
+- App reads `$PORT` and binds `0.0.0.0` (or `::`) — not a hardcoded port on localhost.
+- No secret/connection string is inlined in `railway.json`; secrets are variables.
+- Cross-service values use `${{Service.VAR}}` references, not copied literals.
+- `builder` ∈ {RAILPACK, DOCKERFILE}; `restartPolicyType` ∈ {ON_FAILURE, ALWAYS, NEVER}.
+- A real `healthcheckPath` route exists if one is configured.
+
+Run `bash scripts/verify.sh` from the target dir to structurally lint a present `railway.json`.
+It is a no-op pass when no config file exists (CLI/dashboard-only use is valid). For the deeper
+CLI recipe catalog (CI deploys with `RAILWAY_TOKEN`, `railway run` for local dev against prod
+vars, db shells, multi-service deploys), see [references/cli-cookbook.md](references/cli-cookbook.md).

package/skills/railway/evals/README.md

@@ -0,0 +1,14 @@
+# Evals — railway
+
+`cases.yaml` holds three buckets. `should_trigger` lists prompts (with a `why`) where an agent
+should reach for this skill, including non-obvious symptom phrasings (a 502 that never says
+"bind") and Spanish phrasings. `should_not_trigger` lists nearby prompts that must route to a
+real sibling (`render`, `fly-io`, `db-migrations`, `domains-dns`, `coolify`) with the routing
+reason. `capability` is an end-to-end scenario with a `must_include` rubric.
+
+There is no automated runner here. Evaluate by judgment or with your harness: feed each
+`should_trigger` / `should_not_trigger` prompt to a router and check the selection matches; for
+`capability`, have the agent produce a plan and check every `must_include` bullet is satisfied
+(uses the real CLI flow, references `${{Postgres.DATABASE_URL}}`, binds `0.0.0.0:$PORT`, sets
+`healthcheckPath`, and invents no fake commands). To sanity-check the emitted config artifact,
+run `bash ../scripts/verify.sh` from a dir containing a `railway.json`.

package/skills/railway/evals/cases.yaml

@@ -0,0 +1,44 @@
+skill: railway
+
+should_trigger:
+  - prompt: "Deploy my Next.js app to Railway."
+    why: "Names the platform plus deploy intent — the core 'push a repo / railway up' path this skill owns."
+  - prompt: "Add a Postgres database to my Railway project and connect it to the API service."
+    why: "DB provisioning on Railway plus reference-variable wiring (${{Postgres.DATABASE_URL}}) — squarely in scope."
+  - prompt: "My Railway service returns 502, it builds fine but the healthcheck keeps failing."
+    why: "Non-obvious: the symptom never says 'bind' or '$PORT', but this is the classic localhost/PORT-bind failure that is the skill's #1 triage item."
+  - prompt: "How do I set up a railway.json with a custom start command and a healthcheck path?"
+    why: "Config-as-code authoring — startCommand / healthcheckPath fields the skill documents directly."
+  - prompt: "Desplegar mi worker en Railway con una variable que referencie el DATABASE_URL del Postgres."
+    why: "Spanish phrasing for deploying a worker plus reference variables — same in-scope reference-variable wiring."
+  - prompt: "Two of my Railway services need to talk to each other privately without going over the public internet."
+    why: "Non-obvious phrasing for private networking (*.railway.internal); never says 'private DNS' but that is exactly the surface."
+  - prompt: "Mi servicio de Railway no arranca después del build, ¿qué reviso?"
+    why: "Spanish failed-deploy triage — start command / bind / missing var checklist the skill provides."
+
+should_not_trigger:
+  - prompt: "Deploy this to Render with a render.yaml blueprint."
+    route_to: "render"
+    why: "Different PaaS named explicitly with its own Blueprint format; the boundary routes Render work to the render skill."
+  - prompt: "Set up fly.toml and scale machines across regions with flyctl."
+    route_to: "fly-io"
+    why: "Fly-specific surface (fly.toml, fly machine, flyctl) that Railway has no equivalent of."
+  - prompt: "Write the SQL migration to add an index to the orders table."
+    route_to: "db-migrations"
+    why: "Schema change / migration authoring, not provisioning or connecting a database — that work lives in db-migrations."
+  - prompt: "Point my apex domain's DNS A and CNAME records at the host at my registrar."
+    route_to: "domains-dns"
+    why: "Registrar-side DNS record management; Railway only hands you a CNAME target, the record work is domains-dns."
+  - prompt: "Install Coolify on my Hetzner box and self-host the app."
+    route_to: "coolify"
+    why: "Self-hosted PaaS on your own server — the opposite of Railway's fully-managed model."
+
+capability:
+  - scenario: "I have a Node API in a GitHub repo. Deploy it to Railway with a managed Postgres, wire DATABASE_URL by reference, add a /healthz healthcheck, and make sure it actually serves traffic."
+    must_include:
+      - "Uses the CLI or GitHub repo connect: railway init/link plus railway up, OR connects the repo for auto-deploy — does not invent commands like 'railway deploy --prod'"
+      - "Adds Postgres via railway add (or + New in dashboard) and references it as ${{Postgres.DATABASE_URL}}, NOT a hardcoded connection string"
+      - "App reads $PORT and binds 0.0.0.0 (or ::), not localhost/127.0.0.1"
+      - "Sets healthcheckPath: \"/healthz\" in railway.json (or dashboard) and confirms the route exists"
+      - "Mentions cost awareness (no permanent free tier / billed by the minute) OR generates a public domain with railway domain"
+      - "Routes Postgres schema/migration work to postgresdb / db-migrations rather than doing SQL design here"

package/skills/railway/references/cli-cookbook.md

@@ -0,0 +1,137 @@
+# Railway CLI cookbook
+
+Full command catalog and recipes. Commands run against the linked project/environment unless you
+pass `--service` / `--environment`.
+
+## Install matrix
+
+```bash
+brew install railway                          # macOS (Homebrew)
+npm i -g @railway/cli                          # any host with Node 16+
+bash <(curl -fsSL railway.com/install.sh)      # shell installer (Linux/macOS)
+railway --version                              # verify
+```
+
+## Auth
+
+```bash
+railway login                # interactive browser login (dev machines)
+railway login --browserless  # paste a code; for headless/remote shells
+railway logout
+```
+
+For CI / non-interactive: **do not** `railway login`. Set a project token instead — the CLI
+reads `RAILWAY_TOKEN` and acts as that project, no login step.
+
+```bash
+RAILWAY_TOKEN=$RAILWAY_PROJECT_TOKEN railway up --detach --service api
+```
+
+## Project setup
+
+```bash
+railway init               # create a new project from the current directory
+railway link               # link this dir to an existing project (and pick service/env)
+railway status             # show the linked project / environment / service
+railway open               # open the project in the dashboard
+```
+
+## Deploy
+
+```bash
+railway up                                   # build + deploy current dir, stream logs
+railway up --detach                          # don't attach to build/deploy logs
+railway up --service api                     # target a service in a multi-service project
+railway up --environment staging             # deploy into a specific environment
+railway redeploy                             # re-run the latest deployment unchanged
+```
+
+There is no `railway deploy`. Deploys happen via `railway up` or a push to the GitHub-connected
+branch.
+
+## Variables
+
+```bash
+railway variables                            # list variables for the active service/env
+railway variables --set "LOG_LEVEL=info"     # set one (repeat --set for several)
+railway variables --set "API_URL=${{RAILWAY_PUBLIC_DOMAIN}}"   # set a reference var
+# older documented form:
+railway variable set KEY=value
+```
+
+Reference syntax (set as a variable's value): `${{ServiceName.VAR}}`, `${{shared.VAR}}`,
+`${{RAILWAY_PUBLIC_DOMAIN}}`, `${{RAILWAY_PRIVATE_DOMAIN}}`.
+
+## Run with Railway env injected
+
+```bash
+railway run <cmd>                            # run a local command with prod/linked env vars
+railway run npm run dev                      # local dev against the linked environment's vars
+railway run -- printenv DATABASE_URL         # inspect a resolved value locally
+```
+
+`railway run` injects the linked environment's variables into a local process — handy to run
+migrations or scripts locally against the real config without copying secrets.
+
+## Services & environments
+
+```bash
+railway service                              # switch the active service
+railway environment                          # switch the active environment
+railway environment staging                  # switch to a named environment
+```
+
+## Add services & databases
+
+```bash
+railway add                                  # interactive: add a service or a database template
+# pick Postgres / MySQL / Redis / MongoDB from the template list,
+# or in the dashboard use + New / cmd-K
+```
+
+After adding a DB, reference its vars into the app service as `${{Postgres.DATABASE_URL}}` rather
+than copying the literal URL.
+
+## Database shells
+
+```bash
+railway connect              # open a shell to the linked DB service (psql/mysql/mongosh/redis-cli)
+railway connect Postgres     # target a specific DB service by name
+```
+
+## Logs & domains
+
+```bash
+railway logs                 # stream logs for the active deployment
+railway logs --service api   # logs for a specific service
+railway domain               # generate a *.up.railway.app domain for the service
+```
+
+## CI/CD snippet (GitHub Actions)
+
+```yaml
+# .github/workflows/deploy.yml
+name: deploy
+on:
+  push:
+    branches: [main]
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm i -g @railway/cli
+      - run: railway up --detach --service api
+        env:
+          RAILWAY_TOKEN: ${{ secrets.RAILWAY_PROJECT_TOKEN }}
+```
+
+Use a **project token** (`RAILWAY_TOKEN`) for CI — never a personal login. Scope the token to the
+project and rotate it from the dashboard if leaked.
+
+## Notes
+
+- Most commands act on the *linked* project/env/service; run `railway status` if a command targets
+  the wrong place.
+- `railway run` resolves reference variables (`${{...}}`) the same way the deployed container
+  does, so it's a faithful local mirror of prod config.