vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/use-railway/references/configure.md

@@ -0,0 +1,359 @@
+# 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 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
+
+Use the `railway domain` command for domain lifecycle work. Avoid raw `environment edit` JSON patches for normal domain management.
+
+### Create domains
+
+```bash
+railway domain --service <service> --json                  # generate a Railway domain
+railway domain example.com --service <service> --json      # add a custom domain
+railway domain example.com --service <service> --port 8080 --json
+```
+
+One Railway-provided domain is allowed per service. Multiple custom domains are supported. Custom domain creation returns the DNS records to add at the DNS provider. Add both the routing record and ownership verification record exactly as returned.
+
+Requests to a custom domain can return `404` until Railway verifies the ownership `TXT` record. DNS can take up to 72 hours to propagate.
+
+### Inspect and update domains
+
+```bash
+railway domain list --service <service> --json
+railway domain status example.com --service <service> --json
+railway domain update example.com --port 8080 --service <service> --json
+railway domain update old-name.up.railway.app --domain new-name --service <service> --json
+railway domain certificate retry example.com --service <service> --json
+```
+
+Use `status` when DNS or certificate issuance is not healthy. Retry certificate issuance only after fixing DNS.
+
+### Delete domains
+
+```bash
+railway domain delete example.com --service <service> --yes --json
+```
+
+Domain deletion is destructive. Confirm the domain and service before running it.
+
+## Networking commands
+
+### 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}}
+```
+
+```bash
+railway private-network status --service <service> --json
+railway private-network update api-internal --service <service> --json
+```
+
+When multiple private networks exist, pass `--network <name-or-id>`. Endpoint updates take the prefix only, without `.internal`.
+
+### TCP proxies
+
+Use TCP proxies to expose non-HTTP ports, such as database or game server ports, to the public internet. Only one TCP proxy is allowed per service instance.
+
+```bash
+railway tcp-proxy list --service <service> --json
+railway tcp-proxy create --service <service> --port 5432 --json
+railway tcp-proxy status <proxy-id-or-domain-or-port> --service <service> --json
+railway tcp-proxy delete <proxy-id-or-domain-or-port> --service <service> --yes --json
+```
+
+TCP proxy creation updates service networking config. If the proxy does not become active, redeploy the service and check status.
+
+### Outbound networking
+
+Use outbound networking commands for Static Outbound IPs and outbound IPv6:
+
+```bash
+railway outbound-network status --service <service> --json
+railway outbound-network static-ip status --service <service> --json
+railway outbound-network static-ip enable --service <service> --json
+railway outbound-network static-ip disable --service <service> --json
+railway outbound-network ipv6 status --service <service> --json
+railway outbound-network ipv6 enable --service <service> --json
+railway outbound-network ipv6 disable --service <service> --json
+```
+
+Static Outbound IP changes are committed directly but require a redeploy before outbound traffic uses the new assignment. Outbound IPv6 changes are staged as environment config changes; commit staged changes with `railway environment edit` to trigger the redeploy.
+
+### CDN caching
+
+CDN caching is service-scoped and requires an applied public domain.
+
+```bash
+railway cdn status --service <service> --json
+railway cdn enable --service <service> --json
+railway cdn update --service <service> --html-caching force --default-ttl 4h --json
+railway cdn update --service <service> --no-swr --purge-on-deploy all --json
+railway cdn purge html --service <service> --json
+railway cdn purge all --service <service> --json
+railway cdn disable --service <service> --json
+```
+
+Use the response headers `x-cache` and `age` to verify cache behavior. Cache hits do not reach the service, so service logs and server-side metrics can undercount traffic after caching is enabled.
+
+### WAF Under Attack Mode
+
+Under Attack Mode is service-scoped, requires an applied public domain, and is intended for active bot floods or DDoS events.
+
+```bash
+railway waf under-attack status --service <service> --json
+railway waf under-attack enable --service <service> --duration 1h --json
+railway waf under-attack enable --service <service> --json
+railway waf under-attack disable --service <service> --json
+```
+
+While active, browser visitors must pass a check. Non-browser API clients and webhooks may receive `429` responses, so warn the user before enabling it on API-only domains.
+
+## 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**: run `railway domain status`, verify the target port, then check HTTP logs
+- **DNS propagation delay**: custom domains can take up to 72 hours to propagate worldwide
+- **Cloudflare proxy issues**: align SSL/TLS mode per Railway's domain guidance
+- **Private networking failing**: run `railway private-network status`, verify the service is listening on the referenced port, and check network flow logs
+- **Outbound allowlist still sees old IPs**: redeploy after enabling/disabling Static Outbound IPs
+- **IPv6 still disabled**: commit the staged environment change and wait for redeploy
+- **CDN appears ineffective**: check `x-cache`, `age`, cache headers, `Set-Cookie`, `Authorization`, method, and response size
+- **WAF breaks API clients**: Under Attack Mode blocks non-browser traffic; disable it or scope protection to browser-facing services
+- **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), [domain.md](https://docs.railway.com/cli/domain), [tcp-proxy.md](https://docs.railway.com/cli/tcp-proxy), [private-network.md](https://docs.railway.com/cli/private-network), [outbound-network.md](https://docs.railway.com/cli/outbound-network), [cdn.md](https://docs.railway.com/cli/cdn), [waf.md](https://docs.railway.com/cli/waf)
+- CLI source: [environment/mod.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/environment/mod.rs), [environment/edit.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/environment/edit.rs), [variable.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/variable.rs), [domain.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/domain.rs), [tcp_proxy.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/tcp_proxy.rs), [private_network.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/private_network.rs), [outbound_networking.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/outbound_networking.rs), [cdn.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/cdn.rs), [waf.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/waf.rs)

package/dist/global-skills/use-railway/references/deploy.md

@@ -0,0 +1,225 @@
+# Deploy
+
+Ship code, manage releases, and configure builds.
+
+## Deploy code
+
+### Standard deploy
+
+```bash
+railway up --detach -m "<release summary>"
+```
+
+`--detach` (alias `--no-wait`) 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.
+
+### Verify before reporting — `--detach` only means QUEUED
+
+A detached `up` returns when the build is **queued**, not deployed. Never tell the user their app is deployed based on `--detach` output (or a streaming `up` that your shell timed out). Poll until the newest deployment reaches a terminal state:
+
+```bash
+railway deployment list --service <service> --environment <environment> --json    # newest first; check .status
+railway deployment list --project <project> --environment <environment> --service <service> --json
+```
+
+Poll with the same project, environment, and service scope used for `railway up`. If the deploy used URL-derived IDs or `--project`, do not rely on the directory's linked context.
+
+- `QUEUED` / `INITIALIZING` / `WAITING` / `BUILDING` / `DEPLOYING` → still in progress. Keep polling (every 10-15s); tell the user "build in progress" if you report interim status.
+- `NEEDS_APPROVAL` → waiting for manual approval. Report that approval is required; do not keep polling as if the deployment is still building.
+- `SUCCESS` → now it's deployed; report it.
+- `FAILED` / `CRASHED` → do not report success. Pull scoped logs (`railway logs --service <service> --json --lines 100`) and triage per [operate.md](operate.md).
+- `SLEEPING` / `SKIPPED` / `REMOVED` / `REMOVING` / unknown → do not report success. Report the exact state and inspect status/logs to decide the next action.
+
+A non-detached `railway up` streams to completion and its exit code is authoritative: 0 = SUCCESS, 1 = FAILED/CRASHED. If it was killed or timed out before printing a terminal status, treat the outcome as unknown and poll as above.
+
+### 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.
+
+### Path deploys
+
+Deploy a subdirectory without changing the shell's working directory:
+
+```bash
+railway up ./apps/api --path-as-root --service api --environment production --detach -m "<summary>"
+```
+
+Use `--path-as-root` when the path argument should be archived as the root of the deploy instead of preserving the parent directory prefix.
+
+## 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> --environment <environment> --limit 20 --json
+railway deployment list --project <project> --environment <environment> --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/v5.23.3/src/commands/up.rs), [deployment.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/deployment.rs), [down.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/down.rs), [redeploy.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/redeploy.rs), [restart.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/restart.rs), [service.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/service.rs)

package/dist/global-skills/use-railway/references/feature-flags.md

@@ -0,0 +1,89 @@
+# Feature flags
+
+Manage Railway feature flags (Signals): typed defaults, targeting rules, and runtime reads via the SDK or GraphQL.
+
+## What they are
+
+Railway feature flags are **project- or workspace-scoped** configuration values resolved at read time from a registry (not environment variables). Each flag has:
+
+- A **type**: `bool`, `string`, `number`, or `json`
+- A **default** value used when no rule matches
+- Optional **targeting rules** (attribute comparisons and rollout percentages)
+
+Project flags are managed in **Project Settings → Feature Flags**. Workspace flags are visible there read-only.
+
+Runtime apps read **one scope** at a time (`project:<id>` or `workspace:<id>`) via the [TypeScript SDK](https://github.com/railwayapp/railway-ts-sdk) or GraphQL — flags from other scopes are separate registries.
+
+## Agent / MCP workflow
+
+Prefer **Remote MCP** tools when OAuth-scoped project access is enough:
+
+| Tool | Access | Purpose |
+|---|---|---|
+| `list-feature-flags` | viewer | List project flags; includes workspace flags when present |
+| `get-feature-flag` | viewer | Inspect one flag (`scope`: `project` or `workspace`) |
+| `set-feature-flag` | admin | Create a flag or update its default |
+| `delete-feature-flag` | admin | Delete a project-scoped flag |
+
+Always pass explicit `projectId` (from a Railway URL or `railway status --json`).
+
+```text
+List feature flags for project 6adb5ae3-0e3a-4ead-b42c-1fd36f217ffb
+```
+
+```text
+Set feature flag checkout-v2 on project 6adb5ae3-0e3a-4ead-b42c-1fd36f217ffb to true (bool)
+```
+
+For targeting rules and rollouts, use the dashboard UI or GraphQL (`signalRuleSet`) until MCP rule tools exist.
+
+## CLI (when available)
+
+The Railway CLI exposes `railway flag` (alias `railway signal`) for registry CRUD. Upgrade the CLI if the command is missing:
+
+```bash
+railway upgrade --yes
+railway flag list --project <project-id> --json
+railway flag checkout-v2 true --project <project-id>
+```
+
+Use `--project` (or link first) so scope is explicit in agent workflows.
+
+## GraphQL fallback
+
+When MCP and CLI are unavailable, use the public GraphQL API (`signals`, `signalCreate`, `signalDefaultSet`, `signalRuleSet`, `signalDelete`) with owner `project:<projectId>` or `workspace:<workspaceId>`. See https://docs.railway.com/docs/feature-flags
+
+```bash
+scripts/railway-api.sh '{"owner":"project:<projectId>"}' <<'EOF'
+query projectSignals($owner: String!) {
+  signals(owner: $owner) { name type default rules version }
+}
+EOF
+```
+
+## Runtime SDK
+
+In deployed services, use the Railway SDK flags module:
+
+```typescript
+import { flags } from "railway";
+
+await flags.init({ scope: { projectId: process.env.RAILWAY_PROJECT_ID! } });
+
+const enabled = flags.getBoolean("checkout-v2", {
+  targetingKey: userId,
+  attributes: { plan: "enterprise" },
+});
+```
+
+Poll interval defaults are suitable for most apps; flags refresh when registry versions change.
+
+## Do not confuse with
+
+- **Environment variables** — static per-environment config (`railway variable set`). Use flags when you need typed defaults, targeting, and central registry semantics.
+- **Priority Boarding / account toggles** — internal beta switches on your Railway account, unrelated to project feature flags.
+- **Platform feature flags** — Railway staff tooling only.
+
+## Dashboard
+
+Human-friendly CRUD: open the project → **Settings → Feature Flags**. Workspace-scoped flags appear in a read-only section when they exist.