docs: document Railway CLI tokens in .env.example

[BigSimmo]

Summary

Documents the two Railway CLI credentials in .env.example so remote agents and CI can authenticate without an interactive browser login. Affected area: .env.example only — documentation, no runtime surface.

Variable	Scope	Use for
RAILWAY_TOKEN	Project token — one project + environment	Deploys, redeploys, logs. Preferred for CI (narrowest blast radius)
RAILWAY_API_TOKEN	Account/workspace token — all projects	Account-level actions (railway list/link, GraphQL Public API)

Semantics were verified against Railway's CLI documentation rather than assumed.

Motivation: nothing in the repo recorded how Railway auth works for non-interactive use. The only local credential is ~/.railway/config.json, which holds a ~1h OAuth session plus absolute local worktree paths — not portable, and unsafe to copy or commit. This documents the correct path (mint a scoped token, store it in a secret store) instead.

Both keys ship commented out. Neither the Next.js app nor the worker reads them — src/lib/env.ts references neither — so runtime behaviour is unchanged.

Verification

Verification not run: this worktree has no node_modules, so the full npm run verify:pr-local gate could not execute locally. CI is the authority on the remaining checks. What was confirmed locally:

• check:runtime — pass (Node 24.18.0, npm 11.17.0)
• Format — pass, reproducing CI's exact invocation (prettier --check --ignore-unknown -- .env.example); prettier has no parser for .env files and skips it via --ignore-unknown
• .env.example syntax — every non-comment line is a valid KEY=VALUE
• Zero active RAILWAY* keys (both commented); diff scanned for secret-shaped strings, none found
• No gate parses .env.example keys — scripts/production-readiness.ts only asserts the file exists, so an unread key cannot break a check

Risk and rollout

• Risk: Low. Comment-only addition plus two disabled keys in a file no code parses; no import graph, no runtime read, no schema validation over its keys.
• Rollback: git revert the single commit — no migration, state, or config to unwind.
• Provider or production effects: None. No deploy is triggered and no token value is committed. Deploys remain operator-confirmed per AGENTS.md.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added a new section to the environment example covering Railway CLI deployment credentials for CI/remote agents only.
  • Clarified which Railway CLI tokens are not used by the Next.js app or worker, including the difference between RAILWAY_TOKEN and RAILWAY_API_TOKEN.
  • Added commented-out placeholders and usage guidance (set only one at a time, use secret stores, rotate tokens if exposed).

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[supabase]

This pull request has been ignored for the connected project sjrfecxgysukkwxsowpy because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 9d3d49e0-ae3d-42f9-8698-b282010c5560

📥 Commits

Reviewing files that changed from the base of the PR and between e17cda9 and 891d0fb.

📒 Files selected for processing (1)

• .env.example

🚧 Files skipped from review as they are similar to previous changes (1)

• .env.example

---

📝 Walkthrough

Walkthrough

Adds Railway deployment credential documentation to .env.example, including token distinctions, usage restrictions, secret storage guidance, rotation instructions, and commented placeholders.

Changes

Railway credential documentation

Layer / File(s)	Summary
Document Railway deployment credentials .env.example	Adds commented RAILWAY_TOKEN and RAILWAY_API_TOKEN placeholders with Railway CLI authentication guidance and secret-handling instructions.

Estimated code review effort: 1 (Trivial) | ~2 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: documenting Railway CLI tokens in .env.example.
Description check	✅ Passed	The description covers summary, verification, and risk/rollback sections, with enough detail despite using prose instead of checklist boxes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/railway-token-docs-638ad6

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.env.example:
- Around line 185-215: Remove .env.example from the repository and relocate the
Railway credential placeholders and usage guidance to tracked documentation,
preserving the existing security and deployment instructions. Update repository
ignore/configuration rules as needed so .env.example and other prohibited .env.*
files are not intentionally retained or committed.
- Around line 197-204: Update the Railway token documentation comments to point
project-token creation to Project Settings > Tokens instead of Account Settings.
In the RAILWAY_API_TOKEN description, accurately distinguish account/workspace
scope, state that workspace tokens are limited to one workspace, and clarify
that project-scoped requests use the Project-Access-Token mechanism.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 77ab0d7e-e0ff-4de3-9f29-e8d687c1ed46

📥 Commits

Reviewing files that changed from the base of the PR and between e128384 and e17cda9.

📒 Files selected for processing (1)

• .env.example