vybekiit 0.7.26 → 0.7.27

package/dist/global-skills/use-railway/SKILL.md

@@ -2,13 +2,16 @@
 name: use-railway
 description: >
   Operate Railway infrastructure: sign up for or sign in to a Railway account,
-  create projects, provision services and databases, manage object storage
-  buckets, deploy code, configure infrastructure as code, environments and variables, manage domains,
+  create projects, provision services, databases, and buckets, deploy code,
+  configure infrastructure as code, environments and variables, manage domains,
+  trace requests with OpenTelemetry,
   troubleshoot failures, check status and metrics, manage feature flags,
-  set up Railway agent tooling, and query Railway docs. Use this skill whenever
+  database recovery and HA, cloud agents, usage limits, and Railway agent tooling.
+  Use this skill whenever
   the user mentions Railway, feature flags, flag rollout, targeting rules,
   signing up, creating an account, registering, logging in, deployments,
-  services, environments, buckets, object storage, build failures, agent setup,
+  services, environments, buckets, object storage, tracing, traces, spans,
+  OpenTelemetry, OTLP, build failures, agent setup,
   MCP, or infrastructure operations, even if they don't say "Railway" explicitly.
   Also invoke this skill when the user asks to be signed up, registered, or
   onboarded to Railway: do not refuse — drive them through the unauthed
@@ -37,14 +40,16 @@ Most CLI commands operate on the linked project/environment/service context. Use
 Railway has three agent-facing operation paths. Choose the path that matches the job:
 
 - **Railway CLI** (`railway`): workflows that depend on local machine state such as current working directory deploys, `railway up`, `railway run`, SSH, database analysis scripts, local linking, interactive setup, or exact command output.
-- **Remote MCP** (`https://mcp.railway.com`): default plugin MCP path for account/project/service discovery, deployment state, bounded logs, feature flags, simple redeploys, simple project creation, or complex Railway workflows that can be handed to `railway-agent`. Remote MCP uses Railway OAuth and does not depend on local CLI state.
-- **GraphQL**: operations that neither MCP nor CLI exposes, or when a reference gives a specific GraphQL fallback.
+- **Remote MCP** (`https://mcp.railway.com`): default plugin MCP path for account/project/service discovery, deployment state, bounded logs, traces, feature flags, simple redeploys, simple project creation, or complex Railway workflows that can be handed to `railway-agent`. Remote MCP uses Railway OAuth and does not depend on local CLI state.
+- **GraphQL through `railway api`**: operations without a dedicated MCP tool or CLI command. Use schema search and inspection before constructing unfamiliar queries.
 
 If multiple paths are available, choose the one that preserves the needed context. The CLI fits workflows that need the current repo, local credentials, SSH, database scripts, or exact command output. Remote MCP fits OAuth-scoped platform operations that do not need local files or CLI state.
 
-Optional: if the current agent already has a user-installed local CLI MCP (`railway mcp`) configured, it can be used for CLI-backed platform operations not yet exposed by remote MCP. Published plugin configs do not install or launch local CLI MCP.
+On a Railway cloud agent VM the `railway` CLI only has credentials inside an SSH terminal session. In a dashboard or mobile chat session (Railway Agent) it is unauthenticated by design: do not run `railway` commands there, not even reads or `railway api`. The `railway` MCP server is authenticated in every session, so use its tools, resolve IDs with `list-services` instead of `railway status --json`, and when no tool covers the job say so and ask the user to make the change in the dashboard.
 
-Use `scripts/railway-api.sh` for GraphQL only when neither MCP nor CLI exposes the operation, or when a reference gives a specific GraphQL fallback.
+Optional: an already configured in-process CLI MCP (`railway mcp local`) can supply operations not available through hosted MCP. A bare `railway mcp` now starts the hosted MCP proxy using CLI authentication; it is not the in-process server. Published plugin configs connect directly to hosted MCP with editor OAuth.
+
+Prefer `railway api` (CLI 5.28+) for GraphQL execution. The legacy `scripts/railway-api.sh` remains a compatibility fallback for older CLIs; see [request.md](references/request.md).
 
 ## Parsing Railway URLs
 
@@ -58,13 +63,13 @@ https://railway.com/project/<PROJECT_ID>/service/<SERVICE_ID>
 The URL always contains `projectId` and `serviceId`. It may contain `environmentId` as a query parameter. If the environment ID is missing and the user specifies an environment by name (e.g., "production"), resolve it:
 
 ```bash
-scripts/railway-api.sh \
+railway api \
   'query getProject($id: String!) {
     project(id: $id) {
       environments { edges { node { id name } } }
     }
   }' \
-  '{"id": "<PROJECT_ID>"}'
+  --variables '{"id": "<PROJECT_ID>"}'
 ```
 
 Match the environment name (case-insensitive) to get the `environmentId`.
@@ -99,7 +104,7 @@ Before any mutation, verify the tool path and context:
 
 ```bash
 command -v railway                # CLI installed
-RAILWAY_CALLER="skill:use-railway@1.3.7" RAILWAY_AGENT_SESSION="railway-skill-$(date +%s)-$$" railway whoami --json
+RAILWAY_CALLER="skill:use-railway@1.5.5" RAILWAY_AGENT_SESSION="railway-skill-$(date +%s)-$$" railway whoami --json
 railway --version                 # check CLI version
 ```
 
@@ -123,7 +128,7 @@ Check once per session and don't re-run it after acting; the restart prompt to t
 
 When Railway MCP is available and the job is a platform-state read, use the matching MCP read instead of shelling out. If using the CLI path, run the CLI checks above.
 
-For Railway CLI calls made while this skill is active, prefix the command with `RAILWAY_CALLER=skill:use-railway@1.3.7` and a stable `RAILWAY_AGENT_SESSION` reused for the current user request. Generate the session id once per user request, then reuse that exact value for later Railway CLI calls in the same workflow. Do not run a separate `export` preflight solely for telemetry; inline env prefixes keep the shell output concise and avoid leaking setup steps into every response.
+For Railway CLI calls made while this skill is active, prefix the command with `RAILWAY_CALLER=skill:use-railway@1.5.5` and a stable `RAILWAY_AGENT_SESSION` reused for the current user request. Generate the session id once per user request, then reuse that exact value for later Railway CLI calls in the same workflow. Do not run a separate `export` preflight solely for telemetry; inline env prefixes keep the shell output concise and avoid leaking setup steps into every response.
 
 **Context resolution - URL IDs always win:**
 - If the user provides a Railway URL, extract IDs from it. Do NOT run `railway status --json`; it returns the locally linked project, which is usually unrelated.
@@ -205,6 +210,8 @@ The browser transport needs none of this — the CLI opens the browser on the us
 
 When you see `code: NOT_AUTHENTICATED`, authenticate the user with `railway login`, then retry the original command.
 
+`OAUTH_INSUFFICIENT_GRANT` is different: the session is valid but lacks access to the resource. Check IDs, workspace membership, and the integration's grant scope instead of looping through login; see [operate.md](references/operate.md).
+
 **Fully unattended (no human at all)**: set `RAILWAY_API_TOKEN` (account-scoped) or `RAILWAY_TOKEN` (project-scoped) instead of running an interactive login. A brand-new user with no token and no human present cannot complete signup — there is no headless account-creation path.
 
 ## Agent tooling
@@ -216,7 +223,7 @@ Set up Railway skills, MCP, and authentication with:
 ```bash
 railway setup agent
 railway setup agent -y
-railway setup agent --remote
+railway setup agent --oauth
 ```
 
 `railway setup agent -y` skips the interactive login flow. If the user isn't authenticated after setup, run `railway login`.
@@ -224,15 +231,23 @@ railway setup agent --remote
 Install or update MCP and skills directly when the user names a target tool:
 
 ```bash
-railway mcp install --remote
-railway mcp install --agent codex --remote
-railway mcp install --agent cursor --remote
+railway mcp install                              # hosted MCP via CLI login
+railway mcp install --agent codex --oauth         # direct HTTP, editor OAuth
+railway mcp install --agent cursor --oauth
 railway skills
 railway skills update --agent codex
 railway skills remove --agent cursor
 ```
 
-Supported targets include `claude-code`, `cursor`, `codex`, `opencode`, `copilot`, and `factory-droid`. The `--remote` flag configures `https://mcp.railway.com` instead of a local `railway mcp` stdio server.
+Supported targets include `claude-code`, `cursor`, `codex`, `opencode`, `copilot`, and `factory-droid`.
+
+| Install mode | Transport and authentication |
+|---|---|
+| Default / `--remote` | `railway mcp` stdio proxy to hosted MCP, authenticated by `railway login` |
+| `--oauth` | Direct HTTP to `https://mcp.railway.com`, authenticated by editor OAuth; matches the published plugins |
+| `--local` | In-process GraphQL-backed stdio server, invoked as `railway mcp local` |
+
+These modes apply to both `mcp install` and `setup agent`; interactive setup offers a choice. `railway mcp proxy` remains an alias for the default proxy. The proxy may fill only a linked project ID when the tool accepts it and the call supplies no resource scope. Continue passing explicit project, environment, and service IDs for scoped work.
 
 Use Railway Agent chat with:
 
@@ -272,7 +287,7 @@ railway bucket credentials --bucket <name> --json        # S3-compatible credent
 
 ## Routing
 
-For anything beyond quick operations, load the reference that matches the user's intent. Load only what you need, one reference is usually enough, two at most.
+For anything beyond quick operations, load the references needed for the user's intent. Most requests need one or two; compose more when the workflow crosses areas.
 
 | Intent | Reference | Use for |
 |---|---|---|
@@ -280,9 +295,13 @@ For anything beyond quick operations, load the reference that matches the user's
 | Create or connect resources | [setup.md](references/setup.md) | Projects, services, databases, buckets, templates, workspaces |
 | Ship code or manage releases | [deploy.md](references/deploy.md) | Deploy, redeploy, restart, build config, monorepo, Dockerfile |
 | Change configuration | [configure.md](references/configure.md) | Environments, variables, config patches, domains, networking |
-| Manage feature flags | [feature-flags.md](references/feature-flags.md) | List/create/update project flags via MCP; workspace flags read-only; SDK runtime reads |
-| Define configuration in source control ("IaC", "infrastructure as code", "config as code", `.railway/railway.ts`, `railway.json`, "config plan/apply/pull") | [iac.md](references/iac.md) | Choose TypeScript IaC or the `railway.json` fallback, then author, import, plan, apply, or check drift safely |
+| Manage feature flags | [feature-flags.md](references/feature-flags.md) | MCP registry operations; CLI targeting rules and rollouts; SDK runtime reads |
+| Define configuration in source control ("IaC", "infrastructure as code", "config as code", `.railway/railway.ts`, `.railway/railway.py`, `.railway/railway.go`, "config migrate/plan/apply/pull") | [iac.md](references/iac.md) | Author/import IaC, migrate legacy JSON/TOML, save and apply reviewed plans, check drift |
+| Manage databases ("PITR", "restore", "backup", "HA", "failover", "switchover", "PgBouncer", "connection pooling") | [databases.md](references/databases.md) | Postgres recovery, HA and pooling; MySQL/Redis HA; use analysis references for performance investigations |
+| Inspect costs or manage spending limits | [usage.md](references/usage.md) | Workspace/project/service usage, billing periods, workspace and Railway Agent limits |
+| Run a coding agent on Railway ("cloud agent", "railway ca", "railway code", "desktop SSH") | [cloud-agents.md](references/cloud-agents.md) | Provision, connect, wake, sleep, delete, or configure desktop access to cloud agent VMs |
 | Check health or debug failures | [operate.md](references/operate.md) | Status, logs, metrics, build/runtime triage, recovery |
+| Trace requests across services ("tracing", "traces", "trace ID", "spans", "OpenTelemetry", "OTel", "OTLP", "instrument my app", "instrument my function", "Bun function", "auto-instrumentation") | [tracing.md](references/tracing.md) | Enable tracing per project or service with the `get-tracing` / `set-service-tracing` / `set-project-tracing` MCP tools or `railway trace enable`, SDK instrumentation (preferred) vs automatic (eBPF), what to instrument, instrumenting a Function (Bun), the provided `OTEL_*` variables, sampling, reading traces with the `list-traces` / `get-trace` MCP tools or `railway trace list` / `get`, the Traces tab |
 | Use a sandbox or build remotely ("sandbox", "scratch environment", "ephemeral box", "build remotely", "remote build", "run this remotely", "checkpoint", "snapshot/save/restore sandbox state") | [sandbox.md](references/sandbox.md) | Create/fork sandboxes, run commands remotely, remote template builds, checkpoints (save/restore sandbox state), port forwarding, teardown. Requires Sandboxes enabled in Priority Boarding — if unavailable, prompt the user to enable it. |
 | Request from API, docs, or community | [request.md](references/request.md) | Railway GraphQL API queries/mutations, metrics queries, Central Station, official docs |
 
@@ -293,12 +312,12 @@ If the request spans two areas (for example, "deploy and then check if it's heal
 1. Use Railway CLI for workflows that need the current repo, local shell, SSH, database scripts, local Railway context, or exact command output.
 2. Use Remote MCP for OAuth-scoped platform operations that match an available MCP tool and do not need local files or CLI state.
 3. Use local CLI MCP only when the current agent already has it explicitly configured and it exposes a needed operation not available through Remote MCP.
-4. Fall back to `scripts/railway-api.sh` for operations neither MCP nor CLI exposes.
+4. Use `railway api` for operations without a dedicated MCP tool or CLI command; retain the legacy helper only for CLI compatibility.
 5. Use `--json` output where available for reliable parsing.
 6. Resolve context before mutation. Know which project, environment, and service you're acting on.
 7. For destructive actions (delete service, remove deployment, drop database), confirm intent and state impact before executing.
 8. After mutations, verify the result with a read-back command or MCP read.
-9. **Never report a deploy as successful without observing a terminal SUCCESS.** `railway up --detach` returning (it prints "Build queued") and a streaming `railway up` cut off by a shell timeout only confirm the build *started*. Poll `railway deployment list --json` with the same `--project`, `--environment`, and `--service` scope used for the deploy until the newest deployment's `status` is `SUCCESS` (report deployed). If status is `FAILED` or `CRASHED`, triage per [operate.md](references/operate.md). If status is `NEEDS_APPROVAL`, `SLEEPING`, `SKIPPED`, `REMOVED`, `REMOVING`, or an unknown value, report the exact state and next action; do not claim success. A streaming `up` that exits on its own is authoritative: exit 0 = deployed, exit 1 = failed.
+9. **Never report a deploy as successful without observing SUCCESS for that deployment.** `up --detach`, a non-TTY `up` without CI mode, or a timed-out stream may return after upload. Follow the deployment ID from the upload in `railway deployment list --json` with the same project/environment/service scope; do not substitute a concurrent newer deployment. If status is `FAILED` or `CRASHED`, triage per [operate.md](references/operate.md). If status is `NEEDS_APPROVAL`, `SLEEPING`, `SKIPPED`, `REMOVED`, `REMOVING`, or unknown, report that state and the next action. Exit 0 alone is insufficient; see [deploy.md](references/deploy.md) for CI streaming and polling.
 
 ## User-only commands (NEVER execute directly)
 
@@ -327,6 +346,7 @@ Multi-step workflows follow natural chains:
 - **First deploy**: setup (create project + service), configure (set variables and source), deploy, operate (verify healthy)
 - **Fix a failure**: operate (triage logs), configure (fix config/variables), deploy (redeploy), operate (verify recovery)
 - **Add a domain**: configure (add domain + set port), operate (verify DNS and service health)
+- **Add tracing**: tracing (enable for the project or service with `set-project-tracing` / `set-service-tracing` or `railway trace enable`, prefer SDK instrumentation over automatic, add spans around inbound work, I/O and logical units; for a Function, edit its file with `get-function-source-code` / `update-function-source-code`), configure (set `OTEL_METRICS_EXPORTER`/`OTEL_LOGS_EXPORTER`, start command), deploy (redeploy so the `OTEL_*` variables land), tracing (verify with `x-railway-trace-id` and `get-trace` or `railway trace get`)
 - **Docs to action**: request (fetch docs answer), route to the relevant operational reference
 
 When composing, return one unified response covering all steps. Don't ask the user to invoke each step separately.

package/dist/global-skills/use-railway/references/analyze-db.md

@@ -31,14 +31,14 @@ https://railway.com/project/<PROJECT_ID>/service/<SERVICE_ID>/database?environme
 Then query the API for the service name and database type in a **single call**:
 
 ```bash
-scripts/railway-api.sh \
+railway api \
   'query getServiceAndConfig($serviceId: String!, $environmentId: String!) {
     service(id: $serviceId) { name }
     environment(id: $environmentId) {
       config(decryptVariables: false)
     }
   }' \
-  '{"serviceId": "<SERVICE_ID>", "environmentId": "<ENV_ID>"}'
+  --variables '{"serviceId": "<SERVICE_ID>", "environmentId": "<ENV_ID>"}'
 ```
 
 From the response, get:
@@ -57,9 +57,9 @@ Then match the image to the database type:
 **If `environmentId` is empty in the URL** (e.g., `?environmentId=` or no query param at all), skip the `environment.config` query — it requires a valid ID. Instead, list the project's environments:
 
 ```bash
-scripts/railway-api.sh \
+railway api \
   'query getEnvs($id: String!) { project(id: $id) { environments { edges { node { id name } } } } }' \
-  '{"id": "<PROJECT_ID>"}'
+  --variables '{"id": "<PROJECT_ID>"}'
 ```
 
 Use the `production` environment by default. If multiple non-PR environments exist and the user hasn't specified one, ask which environment to analyze.
@@ -257,13 +257,13 @@ All three IDs come from the URL (see "Context: URL First" above). The service na
 If the URL has no `environmentId` and the user specifies an environment by name (e.g., "production"), resolve it:
 
 ```bash
-scripts/railway-api.sh \
+railway api \
   'query getProject($id: String!) {
     project(id: $id) {
       environments { edges { node { id name } } }
     }
   }' \
-  '{"id": "<PROJECT_ID>"}'
+  --variables '{"id": "<PROJECT_ID>"}'
 ```
 
 Match the environment name (case-insensitive) to get the `environmentId`.
@@ -342,3 +342,4 @@ Railway services auto-scale CPU, RAM, and disk based on actual usage. Users do N
 
 - Docs: [ssh.md](https://docs.railway.com/cli/ssh), [logs.md](https://docs.railway.com/cli/logs), [metrics.md](https://docs.railway.com/cli/metrics), [api docs](https://docs.railway.com/api/llms-docs.md)
 - Local scripts: [analyze-postgres.py](../scripts/analyze-postgres.py), [analyze-mysql.py](../scripts/analyze-mysql.py), [analyze-redis.py](../scripts/analyze-redis.py), [analyze-mongo.py](../scripts/analyze-mongo.py), [dal.py](../scripts/dal.py)
+- API command: [api.rs (v5.49.1)](https://github.com/railwayapp/cli/blob/v5.49.1/src/commands/api.rs)

package/dist/global-skills/use-railway/references/cloud-agents.md

@@ -0,0 +1,70 @@
+# Cloud agents
+
+Use `railway ca` / `railway code` to run coding harnesses on persistent Railway cloud agent VMs. Use `railway agent` for Railway Agent chat/investigations, and [sandbox.md](sandbox.md) for sandbox execution, builds, and checkpoints.
+
+## Availability and target
+
+Cloud agents arrived in CLI 5.32; flat lifecycle commands in 5.35 and desktop setup in 5.38. They are experimental and require **Cloud Agents** enabled in [Priority Boarding](https://railway.com/account/feature-flags). A feature-availability error calls for enabling that feature, not repeatedly provisioning VMs or changing project feature flags.
+
+Use explicit project and environment for creation. A directory's `railway link` context takes precedence over the saved default project; a stale link can fall back to the saved default. Verify the target rather than assuming the saved preference wins. Interactive `ca` can run login and continue; noninteractive unauthenticated calls fail instead of waiting on an unattended device code.
+
+```bash
+railway ca setup --show
+railway ca list --json
+railway ca list --project <project-id> --environment <env> --json
+```
+
+Bare `list` finds the user's agents across projects. `--all` includes other members' agents and requires an explicit environment. Address an existing agent by name or ID; an omitted identifier uses the directory's agent or the sole candidate, otherwise the CLI reports candidates.
+
+## Create, launch, and connect
+
+```bash
+railway ca create my-agent --project <project-id> --environment <env> --json
+railway ca create my-agent --project <project-id> --environment <env> --env-file .env.agent --json
+railway ca ssh my-agent
+railway ca ssh my-agent -- bash
+railway ca start --codex --project <project-id> --environment <env>
+railway ca start --railway --project <project-id> --environment <env>
+```
+
+Choose one creation command with the needed options. `create` provisions a VM without attaching; `ssh` connects to an existing VM and does not create one for a mistyped name. `start` can create and launch a harness, skipping the TUI. Harness flags are `--codex`, `--claude`, `--grok`, and `--railway`; the first three carry or mint a local sign-in, while `--railway` launches Railway's own agent with credentials already on the VM and needs no local sign-in, which suits unattended workflows. `--no-wait` on create/wake means requested, not ready: reread `ca list --json` before reporting readiness. Environment files and `--variable` inputs configure the agent VM; pass only values needed for the remote task.
+
+For a human terminal, bare `railway ca` opens the management TUI and `railway code` opens a session-focused view. Automated workflows should use explicit lifecycle commands rather than attempting to control that TUI. `ca setup` configures the default harness and skills; `ca setup --show` inspects preferences and `ca setup --reset` removes them when requested. Launching can carry harness authentication and skills from the local machine, so choose the harness and remote target deliberately.
+
+## Credentials inside the VM
+
+The VM ships the `railway` CLI, the `gh` CLI and the `railway` MCP server. The MCP server is authenticated in every session. The `railway` CLI is authenticated only inside an SSH terminal session (`railway ca ssh`, `railway code`, desktop SSH), which injects the user's token; a chat session started from the Railway dashboard or mobile app carries no CLI credential, by design. An agent working in such a session must not run `railway` commands, `railway api` included, and should use the MCP tools instead. `railway login` and `railway link` never help on the VM and fail in its non-interactive shell.
+
+## Sleep, wake, and delete
+
+```bash
+railway ca wake my-agent
+railway ca sleep my-agent
+railway ca delete my-agent
+```
+
+Sleep stops compute while retaining the disk; deletion removes the agent and its disk. Use sleep when the user wants to pause work and keep files. `sleep --all` acts across the user's running agents unless narrowed by environment; use it only when that broader scope was requested. Check `list --json` after lifecycle mutations. Do not mistake a disconnected harness session for a deleted VM.
+
+## Desktop SSH setup
+
+```bash
+railway ca desktop --codex --agent my-agent --dry-run
+railway ca desktop --codex --agent my-agent
+railway ca desktop --claude --agent my-agent
+```
+
+Choose the requested app; both flags can configure both on the same VM. The dry-run previews configuration. Actual setup prepares the remote harness and writes an OpenSSH entry; Claude setup also writes its desktop settings. Omitting `--agent` can create an agent when none exists. `--dir /app/api` selects the remote working directory. Restart the desktop app after setup.
+
+A desktop app cannot wake a sleeping agent through the relay: run `railway ca wake <name>` before connecting. To undo the local integration, use `railway ca desktop --codex --agent my-agent --remove` (or `--claude`); removing desktop configuration is distinct from deleting the VM.
+
+## Troubleshoot
+
+- **Wrong project**: inspect the directory link and `ca setup --show`, then use explicit scope.
+- **Access blocked**: check Cloud Agents in Priority Boarding; project feature flags do not enable it.
+- **Desktop cannot connect**: confirm the agent is awake, inspect the generated SSH host, and check CLI SSH access before rerunning setup.
+- **Session ended unexpectedly**: inspect `ca list` and reconnect to the existing agent before creating another VM.
+
+## Validated against
+
+- Docs: [Cloud agent CLI](https://docs.railway.com/cli/ca), [Code CLI](https://docs.railway.com/cli/code)
+- CLI source (v5.49.1): [cloud_agent/mod.rs](https://github.com/railwayapp/cli/blob/v5.49.1/src/commands/cloud_agent/mod.rs), [lifecycle.rs](https://github.com/railwayapp/cli/blob/v5.49.1/src/commands/cloud_agent/lifecycle.rs), [desktop.rs](https://github.com/railwayapp/cli/blob/v5.49.1/src/commands/cloud_agent/desktop.rs), [setup.rs](https://github.com/railwayapp/cli/blob/v5.49.1/src/commands/cloud_agent/setup.rs), [access.rs](https://github.com/railwayapp/cli/blob/v5.49.1/src/commands/cloud_agent/access.rs)

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

@@ -34,6 +34,21 @@ 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.
 
+CLI 5.34.2+ accepts an empty assignment such as `railway variable set OPTIONAL_VALUE= --service <service>`. Empty is a value, not a deletion. Before an idempotent delete, list keys and delete only if present.
+
+### Bulk edit with a reviewed diff
+
+CLI 5.48+ opens an editor and presents the changes before applying:
+
+```bash
+railway variable edit --project <project-id> --environment <env> --service <service>
+railway variable edit --demo                 # offline fixture; no Railway mutation
+```
+
+This workflow requires a TTY or an explicitly configured `$EDITOR`/`$VISUAL`. Prefer `set`/`delete` for deterministic agent edits when no editor workflow was requested. Saving the editor is not approval: the CLI shows a redacted diff and asks before applying. Noninteractive apply requires `--yes`; deletions in agent or noninteractive sessions also require `--confirm-destructive`, within the user's approved scope.
+
+Removing a line deletes that variable. Keep `<sealed>` placeholders unchanged to preserve sealed values. Railway-provided variables are comments and cannot be edited. `--reveal` exposes plaintext in the diff; use only when intended. `--skip-deploys` commits changes without triggering deploys.
+
 ### Set sensitive values
 
 Use stdin for secrets or values that shouldn't appear in shell history:
@@ -128,7 +143,7 @@ These are set automatically at runtime. Availability depends on resource configu
 | `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.
+Sealed variables are write-only. CLI 5.47.2+ lists their names with `null` in JSON, `<sealed>` in the table, or a comment in KV output. **A null value means the sealed key already exists; do not recreate or clear it as though it were missing.** Ordinary variable output can contain plaintext secrets.
 
 ## Service config
 
@@ -356,4 +371,4 @@ While active, browser visitors must pass a check. Non-browser API clients and we
 ## 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)
+- 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.49.1/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/databases.md

@@ -0,0 +1,107 @@
+# Database operations
+
+Use native CLI commands for database recovery, high availability, and connection pooling. Use [analyze-db.md](analyze-db.md) for performance analysis and [setup.md](setup.md) to create a database or connect a local client.
+
+## Choose the engine and scope
+
+| Engine | Commands |
+|---|---|
+| Postgres | `railway postgres pitr`, `ha`, `pgbouncer`, `history` |
+| MySQL | `railway mysql ha`, `history` |
+| Redis | `railway redis ha`, `history` |
+
+Postgres operations arrived in CLI 5.33; MySQL/Redis HA in 5.46. Use **5.47.1 or newer for HA mutations**: that release added the revert and scaling fixes (staged member changes, never deleting the acting primary) and `--remove-orphans`. MySQL/Redis do not expose PITR or PgBouncer commands. Availability and image eligibility also depend on Railway's engine templates; a command existing does not make every custom database image eligible.
+
+All these command trees accept `--project`, `--environment`, `--service`, and `--json`. Resolve the database service and environment first, especially when the supplied URL points at a replica or proxy. Use explicit IDs for cross-project work:
+
+```bash
+railway postgres pitr status --project <project-id> --environment <env> --service <service> --json
+railway postgres ha status --project <project-id> --environment <env> --service <service> --json
+railway postgres pgbouncer status --project <project-id> --environment <env> --service <service> --json
+railway mysql ha status --project <project-id> --environment <env> --service <service> --json
+railway redis ha status --project <project-id> --environment <env> --service <service> --json
+```
+
+The following examples abbreviate scope to `--service`; retain the resolved project and environment in actual calls. Config-changing actions deploy by default. Where supported, `--no-deploy` commits config but defers its runtime effect until the affected services deploy; it is not a dry-run. Use it only when deployment is deliberately deferred. Add `--yes` only for a mutation whose scope and impact the user authorized, and only where the command supports it.
+
+## Postgres point-in-time recovery
+
+```bash
+railway postgres pitr status --service <postgres> --json
+railway postgres pitr enable --service <postgres>
+railway postgres pitr disable --service <postgres>
+railway postgres pitr progress --service <postgres> --json
+railway postgres pitr progress --service <postgres> --watch
+```
+
+`enable`/`disable` recognize a standalone database or an HA cluster root. Standalone operations support `--no-deploy`; HA enable/disable runs a live rolling workflow. `progress`, `cancel`, and `clear` apply only to that HA workflow. Inspect progress before canceling a stuck workflow; clear a completed snapshot only when intended. Bound a watch process and report its last observed phase if it times out.
+
+Status includes a best-effort SSH probe of archive coverage and archiver health. `unavailable` or unknown probe results do not mean backups are disabled or healthy. Resolve SSH reachability or report the missing evidence.
+
+To restore to a separate service:
+
+```bash
+railway postgres pitr restore --service <postgres> --at 2026-09-04T10:00:00Z --new-service-name postgres-restored
+```
+
+Use an explicit UTC timestamp to avoid local-time ambiguity. Relative offsets such as `30m` are also accepted. Check available coverage first, then verify the restored service's deployment and data before changing application connection variables. `--source-repo-path` selects an archive history when needed. Creating a restored service does not itself switch application traffic.
+
+### Backups and schedules
+
+```bash
+railway postgres pitr backup list --service <postgres> --json
+railway postgres pitr backup create --service <postgres> --name pre-migration
+railway postgres pitr backup lock <backup-id> --service <postgres>
+railway postgres pitr schedule list --service <postgres> --json
+railway postgres pitr schedule set --daily --weekly --service <postgres>
+railway postgres pitr backup restore <backup-id> --service <postgres>
+railway postgres pitr backup delete <backup-id> --service <postgres>
+```
+
+`backup restore` overwrites the current data; it is different from `pitr restore`, which creates a new service. In-place backup restore on an HA cluster is rejected because replicas would diverge; use the dashboard workflow that reseeds replicas. Do not bypass the guard by restoring the root volume manually. `backup lock` keeps a backup indefinitely. `schedule set --none` removes automatic schedules while keeping existing backups. Verify the backup ID, target, and destructive impact before restore/delete.
+
+## High availability
+
+```bash
+railway postgres ha convert --service <postgres> --replicas 2 --coordinators 3 --edge 1
+railway postgres ha scale --service <postgres> --replicas 3
+railway postgres ha switchover --service <postgres> --to <replica-name-or-id>
+railway postgres ha revert --service <postgres>
+railway mysql ha convert --service <mysql> --replicas 2
+railway mysql ha scale --service <mysql> --replicas 4
+railway redis ha convert --service <redis> --replicas 2
+railway redis ha switchover --service <redis> --to <replica-name-or-id>
+```
+
+`--replicas` counts replicas **excluding the primary**. Omitted conversion counts preserve the template defaults. MySQL and Redis carry consensus on their data nodes: total data nodes must be odd and at least three, so pass an even replica count such as 2 or 4. These conversions require a source image tagged with an exact major.minor version. Separate `--coordinators` applies only to templates with that tier; its count must be odd. Follow the template's reported constraints rather than copying a Postgres topology to another engine.
+
+Before scaling or switching, inspect live member roles and probe errors. Switchover requires a reachable eligible target and may briefly interrupt connections. After conversion/scale/switchover, reread HA status and verify primary role, replica health, and application connectivity; a committed config alone is not evidence that replication is healthy.
+
+Revert returns the database to standalone and removes cluster members. Current CLI fixes protect the acting primary and retain the independent PgBouncer pooler. `--remove-orphans` is a separate cleanup opt-in: orphaned members may no longer identify which same-engine cluster owned them. Do not add it merely to make a retry succeed. If an operation fails midway, inspect current config, live roles, and history before retrying or cleaning up.
+
+## Postgres connection pooling
+
+```bash
+railway postgres pgbouncer status --service <postgres> --json
+railway postgres pgbouncer add --service <postgres> --pool-mode transaction
+railway postgres pgbouncer configure --service <postgres> --max-client-conn 200
+railway postgres pgbouncer scale --service <postgres> --replicas 2
+railway postgres pgbouncer remove --service <postgres>
+```
+
+Pooling works with standalone Postgres and HA roots. Modes are `transaction`, `session`, and `statement`; choose based on the application's session/transaction requirements. Check utilization and existing limits before changing connection counts. Verify the pooler's deployment and connection endpoint before wiring the app to it; removing the pooler requires restoring a suitable application connection path.
+
+## Verify and investigate
+
+```bash
+railway postgres history --service <postgres> --limit 10 --json
+railway mysql history --service <mysql> --limit 10 --json
+railway redis history --service <redis> --limit 10 --json
+```
+
+History is a **local** operation trail, not a complete account audit log. Pair it with fresh native status, scoped deployment status, and logs. Do not infer that no changes happened just because this machine has no history. Follow [operate.md](operate.md) for deployment/log triage and [analyze-db.md](analyze-db.md) for deeper queries.
+
+## Validated against
+
+- Docs: [Postgres CLI](https://docs.railway.com/cli/postgres)
+- CLI source (v5.49.1): [postgres.rs](https://github.com/railwayapp/cli/blob/v5.49.1/src/commands/postgres.rs), [mysql.rs](https://github.com/railwayapp/cli/blob/v5.49.1/src/commands/mysql.rs), [redis.rs](https://github.com/railwayapp/cli/blob/v5.49.1/src/commands/redis.rs), [pitr.rs](https://github.com/railwayapp/cli/blob/v5.49.1/src/commands/database/pitr.rs), [ha.rs](https://github.com/railwayapp/cli/blob/v5.49.1/src/commands/database/ha.rs), [pool.rs](https://github.com/railwayapp/cli/blob/v5.49.1/src/commands/database/pool.rs), [ops_log.rs](https://github.com/railwayapp/cli/blob/v5.49.1/src/commands/database/ops_log.rs)

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

@@ -10,11 +10,11 @@ Ship code, manage releases, and configure builds.
 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.
+`--detach` (alias `--no-wait`) returns after upload without waiting for the deployment. An existing-project `up` also returns after upload when stdout is not a TTY and neither `--ci`, `--json`, nor CI environment mode is active. Do not assume omitting `--detach` makes an agent invocation wait. 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:
+A detached `up` confirms upload, not a successful deployment. Capture the deployment ID from the upload (`--detach --json` includes `deploymentId` for an authenticated deployment). Poll for that deployment's terminal state; do not mistake a concurrent newer deployment for the one just submitted:
 
 ```bash
 railway deployment list --service <service> --environment <environment> --json    # newest first; check .status
@@ -29,7 +29,7 @@ Poll with the same project, environment, and service scope used for `railway up`
 - `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.
+Observe `SUCCESS` for the submitted deployment before claiming success. Exit 0 can mean upload returned early or watch patterns skipped the build. A timeout, ended stream, or transport error without a deployment verdict leaves the outcome unknown; poll the existing deployment before deciding whether a retry is necessary.
 
 ### Watch the build
 
@@ -37,7 +37,7 @@ A non-detached `railway up` streams to completion and its exit code is authorita
 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.
+`--ci` streams build logs and waits for the deployment verdict; `--json` also enables CI behavior for authenticated deployments. On CLI 5.41+, failed build-log/status WebSocket connections fall back to HTTP status polling in CI mode. A log transport warning alone does not mean the deployment failed; let the verdict arrive or query its ID. Use a bounded process timeout because polling may outlive missing deployments or nonterminal states. `--ci` can exit 0 when no changed files match watch patterns, so report a skipped deployment accurately.
 
 ### Targeted deploy
 
@@ -222,4 +222,4 @@ railway environment edit --service-config <service> build.watchPatterns '["packa
 ## 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)
+- CLI source: [up.rs](https://github.com/railwayapp/cli/blob/v5.49.1/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

@@ -35,30 +35,37 @@ List feature flags for project 6adb5ae3-0e3a-4ead-b42c-1fd36f217ffb
 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.
+For targeting rules and rollouts, use the CLI commands below when MCP has no matching rule tool. The dashboard or GraphQL (`signalRuleSet`) remains a fallback.
 
-## CLI (when available)
+## CLI defaults, rules, and rollouts
 
-The Railway CLI exposes `railway flag` (alias `railway signal`) for registry CRUD. Upgrade the CLI if the command is missing:
+CLI 5.24+ exposes `railway flag` (alias `railway flags`). Use `--scope project:<id>` for explicit targeting; `--project` is not a flag option. On 5.26.2+, omitted scope can come from the project token or linked project.
 
 ```bash
-railway upgrade --yes
-railway flag list --project <project-id> --json
-railway flag checkout-v2 true --project <project-id>
+railway flag list --scope project:<project-id> --json
+railway flag list --scope project:<project-id> --full
+railway flag set checkout-v2 true --scope project:<project-id>
+railway flag set theme blue --type string --scope project:<project-id>
+railway flag set checkout-v2 true --scope project:<project-id> --when 'plan == "enterprise"' --rule-id enterprise
+railway flag set checkout-v2 true --scope project:<project-id> --when 'bucket(key) < 0.25' --rule-id rollout-25
+railway flag unset checkout-v2 --scope project:<project-id> --rule-id enterprise
+railway flag delete checkout-v2 --scope project:<project-id>
 ```
 
-Use `--project` (or link first) so scope is explicit in agent workflows.
+`set` changes the default unless `--when` is supplied. Rules accept a CEL expression subset or raw JSON; `bucket(key)` gives deterministic percentage targeting using the evaluation context's key. Use a stable `--rule-id` when updating a rule, and list/read back the rules afterward. `unset` removes one rule; `delete` removes the entire flag. CLI mutations target project flags; do not assume workspace mutation support.
+
+Types are inferred unless `--type bool|string|number|json` is given. `--force` permits replacing a flag's type and **clears its rules**; use it only when that replacement is intended.
 
 ## 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
+For API operations beyond these commands, inspect the public GraphQL API (`signals`, `signalCreate`, `signalDefaultSet`, `signalRuleSet`, `signalDelete`) using [request.md](request.md). Owners use `project:<projectId>` or `workspace:<workspaceId>`; access remains subject to the API's scope and permission checks.
 
 ```bash
-scripts/railway-api.sh '{"owner":"project:<projectId>"}' <<'EOF'
-query projectSignals($owner: String!) {
-  signals(owner: $owner) { name type default rules version }
-}
-EOF
+railway api \
+  'query projectSignals($owner: String!) {
+    signals(owner: $owner) { name type default rules version }
+  }' \
+  --variables '{"owner":"project:<projectId>"}'
 ```
 
 ## Runtime SDK
@@ -87,3 +94,8 @@ Poll interval defaults are suitable for most apps; flags refresh when registry v
 ## Dashboard
 
 Human-friendly CRUD: open the project → **Settings → Feature Flags**. Workspace-scoped flags appear in a read-only section when they exist.
+
+## Validated against
+
+- Docs: [Feature flags](https://docs.railway.com/feature-flags), [CLI flags](https://docs.railway.com/cli/flag)
+- CLI source (v5.49.1): [flag.rs](https://github.com/railwayapp/cli/blob/v5.49.1/src/commands/flag.rs), [signals.rs](https://github.com/railwayapp/cli/blob/v5.49.1/src/controllers/signals.rs)