Release Railway configuration commands

assets/railway-config/README.md

@@ -0,0 +1,53 @@
+# Railway configuration
+
+This project defines its Railway infrastructure in code.
+
+```txt
+.railway/railway.ts
+```
+
+Use this file to describe the Railway project you want: services, databases, buckets, custom domains, replicas, groups, and environment variables.
+
+## Common commands
+
+Create the configuration files:
+
+```bash
+railway config init
+```
+
+Import an existing Railway project into code:
+
+```bash
+railway config pull
+```
+
+Preview what Railway would change:
+
+```bash
+railway config plan
+```
+
+Apply the planned changes:
+
+```bash
+railway config apply
+```
+
+Deploy this directory:
+
+```bash
+railway up
+```
+
+If `.railway/railway.ts` has pending project changes, `railway up` previews them and asks before applying them.
+
+## Notes
+
+- `railway config plan` is safe and does not change Railway.
+- `railway config apply` asks before applying unless you pass `--yes`.
+- `railway up` deploys this directory when the service has no GitHub or image source.
+- Services already managed by `railway.json` / `railway.toml` must be migrated before `.railway/railway.ts` can manage them.
+- Use `replicas` for scaling; advanced placement can still specify region names.
+- Use `group("Name", [resources])` to keep large projects organized on the Railway canvas.
+- Secrets imported from Railway may be omitted or represented with `preserve()` so they are not overwritten.

assets/railway-config/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: railway-config
+description: Edit this project's Railway infrastructure-as-code configuration. Use this skill whenever the user asks to create, change, import, review, deploy, or troubleshoot Railway project infrastructure for the current repository, including services, databases, buckets, custom domains, replicas/regions, groups, environment variables, `railway config *`, `.railway/railway.ts`, or `railway up` behavior.
+---
+
+# Railway configuration skill
+
+Use this skill when editing this repository's Railway configuration.
+
+The source of desired Railway project state is:
+
+```txt
+.railway/railway.ts
+```
+
+## Core rules
+
+1. Express Railway product intent, not internal API details.
+2. Do not write Railway UUIDs into `.railway/railway.ts`.
+3. Do not write `EnvironmentConfigPatch`, `ServiceInstance`, Backboard internals, or generated Railway domains into source.
+4. Prefer Railway configuration helpers like `service()`, `postgres()`, `redis()`, `mysql()`, `mongo()`, `bucket()`, `group()`, `github()`, and `image()`.
+5. Use `service.env.VARIABLE` and `database.env.VARIABLE` for references.
+6. Keep secrets out of source. Prefer omitting unknown imported secrets; use `preserve()` when an existing Railway-managed value must be explicitly retained.
+7. Prefer product DSL names such as `domains`, `replicas`, and `group`; avoid internal names like `customDomains` and `multiRegionConfig`.
+8. Do not add platform defaults unless the user explicitly wants them.
+9. Do not manage a service from both `.railway/railway.ts` and `railway.json` / `railway.toml`; migrate the repo config first.
+10. After editing `.railway/railway.ts`, run `railway config plan`.
+11. Do not run `railway config apply` unless the user asks.
+
+## Commands
+
+Initialize configuration files:
+
+```bash
+railway config init
+```
+
+Import current Railway state:
+
+```bash
+railway config pull
+```
+
+Preview changes:
+
+```bash
+railway config plan
+```
+
+Apply changes:
+
+```bash
+railway config apply
+```
+
+Deploy this directory:
+
+```bash
+railway up
+```
+
+Machine-readable preview:
+
+```bash
+railway config plan --json
+```
+
+## Authoring
+
+Use Railway configuration helpers:
+
+```ts
+import {
+  bucket,
+  defineRailway,
+  github,
+  group,
+  image,
+  mongo,
+  mysql,
+  postgres,
+  preserve,
+  project,
+  redis,
+  service,
+} from "railway/iac";
+```
+
+Minimal local service:
+
+```ts
+const web = service("web", {
+  build: "bun run build",
+  start: "NODE_ENV=production bun src/index.ts",
+});
+```
+
+GitHub service:
+
+```ts
+const web = service("web", {
+  source: github("owner/repo", { branch: "main" }),
+  build: "pnpm run build",
+  start: "pnpm start",
+});
+```
+
+Docker image service:
+
+```ts
+const worker = service("worker", {
+  source: image("ghcr.io/acme/worker:latest"),
+});
+```
+
+Database reference:
+
+```ts
+const db = postgres("postgres");
+
+const web = service("web", {
+  env: {
+    DATABASE_URL: db.env.DATABASE_URL,
+  },
+});
+```
+
+Service-to-service reference:
+
+```ts
+const api = service("api", {
+  env: {
+    INTERNAL_TOKEN: preserve(),
+  },
+});
+
+const web = service("web", {
+  env: {
+    API_TOKEN: api.env.INTERNAL_TOKEN,
+    API_HOST: api.env.RAILWAY_PRIVATE_DOMAIN,
+  },
+});
+```
+
+Custom domains:
+
+```ts
+const web = service("web", {
+  domains: ["app.example.com"],
+});
+```
+
+Replicas:
+
+```ts
+const web = service("web", {
+  replicas: 3,
+});
+```
+
+Advanced placement:
+
+```ts
+const web = service("web", {
+  replicas: {
+    "us-west2": 2,
+    "europe-west4": 1,
+  },
+});
+```
+
+Groups:
+
+```ts
+const api = service("api");
+const worker = service("worker");
+const backend = group("Backend", [api, worker]);
+```
+
+Bucket:
+
+```ts
+const media = bucket("media", { region: "iad" });
+```
+
+Project shape:
+
+```ts
+export default defineRailway(() => {
+  const db = postgres("postgres");
+  const web = service("web", {
+    env: {
+      DATABASE_URL: db.env.DATABASE_URL,
+    },
+  });
+
+  return project("my-app", {
+    resources: [db, web],
+  });
+});
+```
+
+## Review checklist
+
+Before applying changes, confirm:
+
+- `railway config plan` shows only expected changes.
+- Secrets are not replaced with literal placeholder values.
+- Existing Railway-managed variables are omitted or use `preserve()` when the value should remain untouched.
+- Custom domains are declared with `domains`, not networking internals.
+- Scaling is declared with `replicas`, not `multiRegionConfig`.
+- No generated Railway service domains are committed.