@synapta/skills 0.1.1 → 0.2.0

package/skills/deploy-railway/references/configure.md

@@ -0,0 +1,309 @@
+# Configure
+
+Manage environments, variables, service config, domains, and networking.
+
+## Environments
+
+### List and switch
+
+```bash
+railway environment list --json
+railway environment list --ephemeral --json      # only PR environments
+railway environment list --no-ephemeral --json   # hide PR environments
+railway environment link <environment>           # switch active environment
+```
+
+### Create
+
+```bash
+railway environment new <name>
+railway environment new <name> --duplicate <source-environment>    # clone config from existing
+```
+
+Duplicating copies all service configurations and variables from the source environment.
+
+## Variables
+
+### Read, set, and delete
+
+```bash
+railway variable list --service <service> --environment <env> --json
+railway variable set KEY=value --service <service> --environment <env>
+railway variable delete KEY --service <service> --environment <env>
+```
+
+Variable changes trigger a redeployment by default. This is usually the desired behavior, since the service picks up the values on restart. Use `--skip-deploys` only when you plan to redeploy or restart separately.
+
+### Set sensitive values
+
+Use stdin for secrets or values that shouldn't appear in shell history:
+
+```bash
+printf "%s" "$SECRET_VALUE" | railway variable set API_KEY --stdin --service <service>
+railway variable set FEATURE_FLAG=true --service <service> --skip-deploys
+railway variable set API_URL=https://api.example.com --project <project-id> --environment <env> --service <service>
+```
+
+### Template syntax
+
+Railway supports interpolation between services and shared variables:
+
+```text
+${{KEY}}                                         # same-service variable
+${{shared.API_KEY}}                              # shared variable
+${{postgres.DATABASE_URL}}                       # variable from another service
+${{api.RAILWAY_PRIVATE_DOMAIN}}                  # another service's private domain
+```
+
+Wiring example, a frontend connecting to a backend over private networking:
+
+```text
+BACKEND_URL=http://${{api.RAILWAY_PRIVATE_DOMAIN}}:${{api.PORT}}
+```
+
+### Wiring services together
+
+Each managed database creates connection variables automatically. Reference them from other services using template syntax:
+
+| Database | Variable reference |
+|---|---|
+| Postgres | `${{Postgres.DATABASE_URL}}` |
+| Redis | `${{Redis.REDIS_URL}}` |
+| MySQL | `${{MySQL.MYSQL_URL}}` |
+| MongoDB | `${{MongoDB.MONGO_URL}}` |
+
+Service names in references are case-sensitive and must match the service name exactly as it appears in the project.
+
+**Public vs private networking decision:**
+
+| Traffic path | Use |
+|---|---|
+| Browser → API | Public domain |
+| Service → Service | Private domain (`RAILWAY_PRIVATE_DOMAIN`) |
+| Service → Database | Private (automatic, uses internal DNS) |
+
+**Frontend apps cannot use private networking.** Frontends run in the user's browser, not on Railway's network. They cannot reach `RAILWAY_PRIVATE_DOMAIN` or internal database URLs. Options:
+
+1. **Backend proxy** (recommended): frontend calls a backend API on a public domain, backend connects to the database over the private network.
+2. **Public database URL**: use the public connection variable (for example, `${{Postgres.DATABASE_PUBLIC_URL}}`). This requires a TCP proxy on the database service and exposes the database to the internet. Use this only for development or low-sensitivity data.
+
+### Railway-provided variables
+
+These are set automatically at runtime. Availability depends on resource configuration.
+
+**Networking:**
+
+| Variable | Available when |
+|---|---|
+| `RAILWAY_PUBLIC_DOMAIN` | Public domain is configured |
+| `RAILWAY_PRIVATE_DOMAIN` | Always (internal DNS for service-to-service traffic) |
+| `RAILWAY_TCP_PROXY_DOMAIN` | TCP proxy is enabled |
+| `RAILWAY_TCP_PROXY_PORT` | TCP proxy is enabled |
+
+**Context:**
+
+| Variable | Available when |
+|---|---|
+| `RAILWAY_PROJECT_ID` | Always |
+| `RAILWAY_ENVIRONMENT_ID` | Always |
+| `RAILWAY_ENVIRONMENT_NAME` | Always |
+| `RAILWAY_SERVICE_ID` | Always |
+| `RAILWAY_SERVICE_NAME` | Always |
+| `RAILWAY_DEPLOYMENT_ID` | Always |
+| `RAILWAY_REPLICA_ID` | Replicas configured |
+| `RAILWAY_REPLICA_REGION` | Multi-region configured |
+
+**Git (present when deployed from a linked repo):**
+
+| Variable | Description |
+|---|---|
+| `RAILWAY_GIT_COMMIT_SHA` | Full commit hash of the deployed revision |
+| `RAILWAY_GIT_AUTHOR` | Commit author name |
+| `RAILWAY_GIT_COMMIT_MESSAGE` | First line of the commit message |
+| `RAILWAY_GIT_BRANCH` | Branch that triggered the deploy |
+
+**Storage (present when a volume is attached):**
+
+| Variable | Description |
+|---|---|
+| `RAILWAY_VOLUME_MOUNT_PATH` | Filesystem path where the volume is mounted |
+| `RAILWAY_VOLUME_NAME` | Name of the attached volume |
+
+Sealed variables are write-only. Their values don't appear in CLI output.
+
+## Service config
+
+Service configuration controls source, build, deploy, and networking settings. There are two ways to mutate it.
+
+### Dot-path patch
+
+For single-field changes:
+
+```bash
+railway environment edit --service-config <service> deploy.startCommand "npm start"
+railway environment edit --service-config <service> build.buildCommand "npm run build"
+railway environment edit --service-config <service> source.rootDirectory "/apps/api"
+railway environment edit --service-config <service> deploy.numReplicas 2
+railway environment edit --project <project-id> --environment production --service-config <service> deploy.startCommand "npm start"
+```
+
+### JSON patch
+
+For multi-field changes or complex structures:
+
+```bash
+railway environment edit --json <<'JSON'
+{"services":{"<service-id>":{"build":{"buildCommand":"npm run build"},"deploy":{"startCommand":"npm start"}}}}
+JSON
+```
+
+Resolve exact service IDs from `railway service list --json` before constructing JSON patches. Using names in the JSON payload doesn't work.
+
+### Stage config changes
+
+Stage changes when the user wants to review config before committing it:
+
+```bash
+railway environment edit --service-config <service> build.buildCommand "npm run build" --stage
+railway environment edit --service-config <service> deploy.startCommand "npm start" --message "Set production start command"
+```
+
+Use `--stage` only when the user requests staged config changes. Use regular edits for immediate mutations.
+
+### Config schema (typed paths)
+
+Include only keys you're changing. The full shape:
+
+**Source**: `source.image` (string), `source.repo` (string), `source.branch` (string), `source.rootDirectory` (string), `source.checkSuites` (boolean), `source.commitSha` (string), `source.autoUpdates.type` (string: `disabled`, `patch`, `minor`)
+
+**Build**: `build.builder` (string: `RAILPACK`, `NIXPACKS`, `DOCKERFILE`), `build.buildCommand` (string), `build.dockerfilePath` (string), `build.watchPatterns` (string array), `build.nixpacksConfigPath` (string)
+
+**Deploy**: `deploy.startCommand` (string), `deploy.preDeployCommand` (string), `deploy.healthcheckPath` (string), `deploy.healthcheckTimeout` (integer), `deploy.numReplicas` (integer), `deploy.restartPolicyType` (string: `ON_FAILURE`, `ALWAYS`, `NEVER`), `deploy.restartPolicyMaxRetries` (integer), `deploy.sleepApplication` (boolean), `deploy.cronSchedule` (string), `deploy.multiRegionConfig` (object)
+
+**Multi-region config** structure for `deploy.multiRegionConfig`:
+
+```json
+{ "us-west2": { "numReplicas": 2 }, "europe-west4-drams3a": { "numReplicas": 1 } }
+```
+
+| Region identifier | Location |
+|---|---|
+| `us-west2` | US West (Oregon) |
+| `us-east4-eqdc4a` | US East (Virginia) |
+| `europe-west4-drams3a` | Europe (Netherlands) |
+| `asia-southeast1-eqsg3a` | Asia (Singapore) |
+
+Natural language mapping: "add replicas in Europe" → `europe-west4-drams3a`, "US East" → `us-east4-eqdc4a`. When the user doesn't specify a region, query current config first with `railway environment config --json` to see existing region assignments before modifying.
+
+**Variables**: `variables.<KEY>.value` (string), `variables.<KEY>.isOptional` (boolean), `variables.<KEY>.isSealed` (boolean). Delete a variable by setting it to `null`.
+
+**Lifecycle**: `isDeleted` (boolean) removes the service. `isCreated` (boolean) marks as new. Prefer `railway service delete` for normal service deletion.
+
+**Storage**: `volumeMounts.<volume-id>.mountPath` (string), `volumes.<volume-id>.isDeleted` (boolean)
+
+**Buckets**: `buckets.<bucket-id>.region` (string: `sjc`, `iad`, `ams`, `sin`), `buckets.<bucket-id>.isCreated` (boolean), `buckets.<bucket-id>.isDeleted` (boolean). Buckets are created at the project level via `railway bucket create` and deployed to environments via config patches. The CLI handles this automatically, so use `railway bucket` commands
+
+### Shared variables and project-level config
+
+```bash
+railway environment edit --json <<'JSON'
+{"sharedVariables":{"API_BASE":{"value":"https://example.com"}}}
+JSON
+```
+
+Shared variables are accessible from any service via `${{shared.KEY}}`.
+
+### Read config
+
+Always inspect before mutating. Config patches merge, so you need to know the state to avoid overwriting fields unintentionally:
+
+```bash
+railway environment config --json
+```
+
+Verify after mutation to confirm the change took effect:
+
+```bash
+railway environment config --json
+railway service list --json
+```
+
+## Domains
+
+### Railway domain
+
+One Railway-provided domain per service, generated automatically:
+
+```bash
+railway domain --service <service> --json
+```
+
+### Custom domain
+
+```bash
+railway domain example.com --service <service> --json
+```
+
+This returns the DNS records you need to configure at your DNS provider. Multiple custom domains per service are supported.
+
+### Target port
+
+If the service listens on a non-default port:
+
+```bash
+railway domain example.com --service <service> --port 8080 --json
+```
+
+### Private networking
+
+For service-to-service traffic within a project, use private domain references instead of public URLs. This avoids egress and is faster:
+
+```text
+BACKEND_URL=http://${{api.RAILWAY_PRIVATE_DOMAIN}}:${{api.PORT}}
+```
+
+### Read current domains
+
+Domain configuration lives in `config.services.<service-id>.networking` under `serviceDomains` (Railway-provided) and `customDomains`. Inspect with:
+
+```bash
+railway environment config --json
+```
+
+### Remove a domain
+
+Remove domains via JSON config patch by setting the domain ID to `null`:
+
+**Remove a custom domain:**
+
+```bash
+railway environment edit --json <<'JSON'
+{"services":{"<service-id>":{"networking":{"customDomains":{"<domain-id>":null}}}}}
+JSON
+```
+
+**Remove a Railway-provided domain:**
+
+```bash
+railway environment edit --json <<'JSON'
+{"services":{"<service-id>":{"networking":{"serviceDomains":{"<domain-id>":null}}}}}
+JSON
+```
+
+Get the domain IDs from `railway environment config --json` under the service's `networking` object.
+
+## Troubleshoot configuration
+
+- **Invalid dot-path**: check field names and types in the config schema section above
+- **Wrong service key in JSON patch**: resolve service IDs from `railway service list --json`
+- **Variable change didn't take effect**: verify with `railway variable list`, changes trigger redeploy by default
+- **Domain returns errors**: verify the service has a healthy deployment and the target port is correct
+- **DNS propagation delay**: custom domains take time to propagate, this is normal
+- **Cloudflare proxy issues**: align SSL/TLS mode per Railway's domain guidance
+- **Private networking failing**: verify the service is listening on the referenced port and that the private domain variable reference is correct
+- **Multi-region patch ignored**: verify region names match the exact identifiers (`us-west2`, `us-east4-eqdc4a`, `europe-west4-drams3a`, `asia-southeast1-eqsg3a`)
+
+## Validated against
+
+- Docs: [environment.md](https://docs.railway.com/cli/environment), [variable.md](https://docs.railway.com/cli/variable), [variables.md](https://docs.railway.com/variables), [domains.md](https://docs.railway.com/networking/domains), [public-networking.md](https://docs.railway.com/networking/public-networking), [private-networking.md](https://docs.railway.com/networking/private-networking)
+- CLI source: [environment/mod.rs](https://github.com/railwayapp/cli/blob/v4.58.0/src/commands/environment/mod.rs), [environment/edit.rs](https://github.com/railwayapp/cli/blob/v4.58.0/src/commands/environment/edit.rs), [variable.rs](https://github.com/railwayapp/cli/blob/v4.58.0/src/commands/variable.rs), [domain.rs](https://github.com/railwayapp/cli/blob/v4.58.0/src/commands/domain.rs), [controllers/config/patch.rs](https://github.com/railwayapp/cli/blob/v4.58.0/src/controllers/config/patch.rs)

package/skills/deploy-railway/references/deploy.md

@@ -0,0 +1,195 @@
+# Deploy
+
+Ship code, manage releases, and configure builds.
+
+## Deploy code
+
+### Standard deploy
+
+```bash
+railway up --detach -m "<release summary>"
+```
+
+`--detach` returns immediately instead of streaming build logs. Without it, the deploy blocks execution until the build finishes. Always include `-m` with a release summary for auditability.
+
+### Watch the build
+
+```bash
+railway up --ci -m "<release summary>"
+```
+
+`--ci` streams build logs and exits when the build completes. Use this when the user wants to see build output or when you need to triage build failures immediately.
+
+### Targeted deploy
+
+When multiple services exist, target explicitly:
+
+```bash
+railway up --service <service> --environment <environment> --detach -m "<summary>"
+```
+
+### Deploy to an unlinked project
+
+For CI or cross-project deploys where the directory isn't linked:
+
+```bash
+railway up --project <project-id> --environment <environment> --detach -m "<summary>"
+```
+
+`--project` requires `--environment`. Railway needs both to resolve context.
+
+## Manage releases
+
+### Redeploy and restart
+
+```bash
+railway redeploy --service <service> --yes              # redeploy the latest deployment
+railway redeploy --service <service> --from-source --yes # pull latest commit or image
+railway restart --service <service> --yes                # restart without rebuilding
+```
+
+Redeploy recreates the latest deployment without uploading local code. Use `--from-source` when the service is linked to a repo or image and you need Railway to pull the latest configured source. Restart only restarts the running container. Use restart when the code hasn't changed but the service needs a fresh process.
+
+### Remove latest deployment
+
+```bash
+railway down --service <service> --yes
+```
+
+This removes the latest successful deployment but doesn't delete the service. To delete a service entirely, use `railway service delete`.
+
+### Delete a service
+
+Use service deletion when the user wants to remove the service itself:
+
+```bash
+railway service delete --service <service> --environment <environment> --yes --json
+```
+
+Deleting a service is destructive. Confirm the target service and environment before running it.
+
+## Deployment history and logs
+
+```bash
+railway deployment list --service <service> --limit 20 --json
+railway logs --service <service> --lines 200 --json              # runtime logs
+railway logs --service <service> --build --lines 200 --json      # build logs
+railway logs --latest --lines 200 --json                         # latest deployment
+```
+
+In an interactive terminal, `railway logs` streams indefinitely when no bounding flags are given. Always use `--lines`, `--since`, or `--until` to get a bounded fetch for agent workflows.
+
+## Build configuration
+
+Railway uses Railpack as the default builder. It detects language and framework from repo contents and assembles a build plan automatically.
+
+### Builder selection
+
+Three builder options, set via service config:
+
+- **RAILPACK** auto-detects language and framework, builds from source (default)
+- **NIXPACKS** is the legacy builder. Use RAILPACK instead.
+- **DOCKERFILE** uses a Dockerfile you provide
+
+```bash
+railway environment edit --service-config <service> build.builder RAILPACK
+railway environment edit --service-config <service> build.builder DOCKERFILE
+railway environment edit --service-config <service> build.dockerfilePath "docker/Dockerfile.prod"
+```
+
+### Build and start commands
+
+Override when auto-detection gets it wrong:
+
+```bash
+railway environment edit --service-config <service> build.buildCommand "npm run build"
+railway environment edit --service-config <service> deploy.startCommand "npm start"
+```
+
+Common reasons to override: wrong package manager detected, multiple build targets in a monorepo, framework-specific output paths.
+
+### Railpack environment variables
+
+Control Railpack behavior by setting these as service variables:
+
+| Variable | Purpose |
+|---|---|
+| `RAILPACK_NODE_VERSION` | Pin Node.js version (e.g., `20`, `22.1.0`) |
+| `RAILPACK_PYTHON_VERSION` | Pin Python version (e.g., `3.12`) |
+| `RAILPACK_GO_BIN` | Go binary name to build |
+| `RAILPACK_STATIC_FILE_ROOT` | Directory for static site output (e.g., `dist`, `build`) |
+| `RAILPACK_SPA_OUTPUT_DIR` | SPA output directory with client-side routing support |
+| `RAILPACK_PACKAGES` | Additional system packages for the build |
+| `RAILPACK_BUILD_APT_PACKAGES` | Apt packages available during build only |
+| `RAILPACK_DEPLOY_APT_PACKAGES` | Apt packages available at runtime only |
+
+For full Railpack documentation including language-specific detection, config files, and framework support: https://railpack.com/llms.txt
+
+### Static sites
+
+Railpack detects static sites from `Staticfile`, `index.html`, or `RAILPACK_STATIC_FILE_ROOT` and serves them with a built-in static file server. If the build outputs to a non-standard directory (for example, `dist/`, `build/`), set `RAILPACK_STATIC_FILE_ROOT` as a variable so Railpack knows where to find the output.
+
+## Monorepo patterns
+
+### Isolated monorepo
+
+When services don't share code, isolate each with its own root directory:
+
+```bash
+railway environment edit --service-config <service> source.rootDirectory "/packages/api"
+```
+
+Each service sees only its subdirectory. This approach is clean but breaks if services import from shared packages.
+
+### Shared monorepo
+
+When services depend on shared packages or root-level workspace config, keep the full repo context and scope via build/start commands instead:
+
+```bash
+# pnpm workspaces
+railway environment edit --service-config <service> build.buildCommand "pnpm --filter api build"
+railway environment edit --service-config <service> deploy.startCommand "pnpm --filter api start"
+
+# yarn workspaces
+railway environment edit --service-config <service> build.buildCommand "yarn workspace api build"
+railway environment edit --service-config <service> deploy.startCommand "yarn workspace api start"
+
+# bun workspaces
+railway environment edit --service-config <service> build.buildCommand "bun run --filter api build"
+railway environment edit --service-config <service> deploy.startCommand "bun run --filter api start"
+
+# turborepo (works with any package manager)
+railway environment edit --service-config <service> build.buildCommand "npx turbo run build --filter=api"
+railway environment edit --service-config <service> deploy.startCommand "npx turbo run start --filter=api"
+```
+
+Don't set a restrictive `rootDirectory` in this case. The build needs access to the workspace root.
+
+### Watch paths
+
+Prevent unrelated package changes from redeploying every service:
+
+```bash
+railway environment edit --service-config <service> build.watchPatterns '["packages/api/**","packages/shared/**"]'
+```
+
+### Common monorepo pitfalls
+
+- **Using `rootDirectory` with shared imports**: if service A imports from `packages/shared/`, setting `rootDirectory: "/packages/a"` hides the shared code. Use the shared monorepo pattern instead.
+- **Forgetting watch paths**: without watch paths, every push redeploys all services, even when only one package changed.
+- **Wrong filter target**: `pnpm --filter api` uses the `name` field in each package's `package.json`, not the directory name. Verify the package name matches.
+
+## Troubleshoot deploys
+
+- **No project/service context**: run `railway link` or pass `--project` with `--environment`
+- **Build fails before compile**: check dependency graph, lockfiles, and whether the right builder is selected
+- **Build succeeds but app crashes**: verify start command and required runtime variables
+- **Wrong files in build**: check root directory and watch patterns
+- **`railway down` treated as delete**: `down` only removes the latest deployment. For service deletion, use `railway service delete`
+- **Wrong Node/Python version detected**: set `RAILPACK_NODE_VERSION` or `RAILPACK_PYTHON_VERSION` as a service variable to pin the version
+- **Missing system package at runtime**: add the package to `RAILPACK_DEPLOY_APT_PACKAGES`
+
+## Validated against
+
+- Docs: [up.md](https://docs.railway.com/cli/up), [deploying.md](https://docs.railway.com/cli/deploying), [deployment.md](https://docs.railway.com/cli/deployment), [redeploy.md](https://docs.railway.com/cli/redeploy), [service.md](https://docs.railway.com/cli/service), [down.md](https://docs.railway.com/cli/down), [railpack.md](https://docs.railway.com/builds/railpack), [monorepo.md](https://docs.railway.com/deployments/monorepo)
+- CLI source: [up.rs](https://github.com/railwayapp/cli/blob/v4.58.0/src/commands/up.rs), [deployment.rs](https://github.com/railwayapp/cli/blob/v4.58.0/src/commands/deployment.rs), [down.rs](https://github.com/railwayapp/cli/blob/v4.58.0/src/commands/down.rs), [redeploy.rs](https://github.com/railwayapp/cli/blob/v4.58.0/src/commands/redeploy.rs), [restart.rs](https://github.com/railwayapp/cli/blob/v4.58.0/src/commands/restart.rs), [service.rs](https://github.com/railwayapp/cli/blob/v4.58.0/src/commands/service.rs)