@damiangilgonzalez/harness 1.3.7

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 across services, attaching a volume, or fixing a deploy that builds but will not serve. NOT Render (that is `render`), NOT Fly machines (that is `fly-io`), NOT a 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.

package/skills/railway/references/config-as-code.md

@@ -0,0 +1,120 @@
+# railway.json / railway.toml — full field reference
+
+Config as code lives in `railway.json` **or** `railway.toml` at the service root. The fields a
+file sets **override the dashboard**; per-environment overrides nest under `environments.<name>`
+and take precedence over the base config. Schema: `https://railway.com/railway.schema.json`.
+
+Precedence, highest to lowest: `environments.<active>.*` → base file config → dashboard.
+
+## Build section
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `builder` | `RAILPACK` \| `DOCKERFILE` | Default `RAILPACK` (successor to Nixpacks). A Dockerfile is auto-detected; `DOCKERFILE` forces it. |
+| `buildCommand` | string | Overrides the inferred build step. |
+| `watchPatterns` | string[] | Glob paths that, when changed, trigger a rebuild on auto-deploy (e.g. `["src/**"]`). |
+| `dockerfilePath` | string | Path to the Dockerfile when not at root (with `builder: DOCKERFILE`). |
+| `railpackVersion` | string | Pin the Railpack version for reproducible builds. |
+
+## Deploy section
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `startCommand` | string | Command to run the service. Set this if Railpack can't infer it. |
+| `preDeployCommand` | string | Runs once before the new version goes live (e.g. DB migration). |
+| `healthcheckPath` | string | Path Railway polls before marking the deploy healthy (e.g. `/healthz`). Must return 2xx. |
+| `healthcheckTimeout` | number (s) | How long to wait for the healthcheck to pass before failing the deploy. |
+| `restartPolicyType` | `ON_FAILURE` \| `ALWAYS` \| `NEVER` | What to do when the container exits. |
+| `restartPolicyMaxRetries` | number | Cap on restart attempts under `ON_FAILURE`. |
+| `numReplicas` | number | Horizontal replica count. Incompatible with an attached volume (volume pins to 1). |
+| `multiRegionConfig` | object | Per-region replica config for multi-region deploys. |
+| `cronSchedule` | string (cron) | Run the service as a cron job on this schedule instead of long-running. |
+| `overlapSeconds` | number | Seconds the old + new versions overlap during a deploy (zero-downtime tuning). |
+| `drainingSeconds` | number | Grace period to drain in-flight requests before the old version is killed. |
+
+## JSON variant
+
+```jsonc
+{
+  "$schema": "https://railway.com/railway.schema.json",
+  "build": {
+    "builder": "RAILPACK",
+    "buildCommand": "npm run build",
+    "watchPatterns": ["src/**", "package.json"]
+  },
+  "deploy": {
+    "startCommand": "node dist/server.js",
+    "preDeployCommand": "npm run migrate:deploy",
+    "healthcheckPath": "/healthz",
+    "healthcheckTimeout": 300,
+    "restartPolicyType": "ON_FAILURE",
+    "restartPolicyMaxRetries": 10,
+    "overlapSeconds": 20,
+    "drainingSeconds": 15
+  },
+  "environments": {
+    "production": {
+      "deploy": { "numReplicas": 2 }
+    },
+    "staging": {
+      "build": { "buildCommand": "npm run build:staging" },
+      "deploy": { "numReplicas": 1 }
+    }
+  }
+}
+```
+
+## TOML variant (same fields)
+
+```toml
+"$schema" = "https://railway.com/railway.schema.json"
+
+[build]
+builder = "RAILPACK"
+buildCommand = "npm run build"
+watchPatterns = ["src/**", "package.json"]
+
+[deploy]
+startCommand = "node dist/server.js"
+preDeployCommand = "npm run migrate:deploy"
+healthcheckPath = "/healthz"
+healthcheckTimeout = 300
+restartPolicyType = "ON_FAILURE"
+restartPolicyMaxRetries = 10
+overlapSeconds = 20
+drainingSeconds = 15
+
+[environments.production.deploy]
+numReplicas = 2
+
+[environments.staging.build]
+buildCommand = "npm run build:staging"
+
+[environments.staging.deploy]
+numReplicas = 1
+```
+
+## Dockerfile builds
+
+```jsonc
+{
+  "$schema": "https://railway.com/railway.schema.json",
+  "build": {
+    "builder": "DOCKERFILE",
+    "dockerfilePath": "docker/Dockerfile.prod"
+  },
+  "deploy": { "startCommand": "" }
+}
+```
+
+With `DOCKERFILE`, the image's `CMD`/`ENTRYPOINT` drives startup; leave `startCommand` empty
+unless you intend to override it. For Dockerfile authoring itself, see the `docker` and
+`deployment` skills — this reference only covers wiring it into Railway.
+
+## Notes
+
+- Never inline secrets here. Anything sensitive belongs in variables, referenced as
+  `${{Service.VAR}}`. The config file is committed to the repo.
+- `cronSchedule` turns a service into a scheduled job; it should exit when done rather than
+  staying resident.
+- A volume forces a single replica — do not set `numReplicas > 1` on a service with a volume.