@synapta/skills 0.1.0 → 0.1.2

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

@@ -0,0 +1,214 @@
+# Operate
+
+Check health, read logs, query metrics, and troubleshoot failures.
+
+## Health snapshot
+
+Start broad, then narrow:
+
+```bash
+railway status --json                                    # linked context
+railway service list --json                              # services in current environment
+railway deployment list --limit 10 --json                # recent deployments
+```
+
+Deployment statuses: `SUCCESS`, `BUILDING`, `DEPLOYING`, `FAILED`, `CRASHED`, `REMOVED`.
+
+For projects with buckets, include bucket status:
+
+```bash
+railway bucket list --json                                       # buckets in current environment
+railway bucket info --bucket <name> --json                       # storage size, object count, region
+```
+
+If everything looks healthy, return a summary and stop. If something is degraded or failing, continue to log inspection.
+
+## Logs
+
+### Recent logs
+
+```bash
+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.
+
+### Time-bounded queries
+
+```bash
+railway logs --service <service> --since 1h --lines 400 --json
+railway logs --service <service> --since 30m --until 10m --lines 400 --json
+```
+
+### Filtered queries
+
+Use `--filter` to narrow logs without scanning everything manually:
+
+```bash
+railway logs --service <service> --lines 200 --filter "@level:error" --json
+railway logs --service <service> --lines 200 --filter "@level:warn AND timeout" --json
+railway logs --service <service> --lines 200 --filter "connection refused" --json
+```
+
+Filter syntax supports text search (`"error message"`), attribute filters (`@level:error`, `@level:warn`), and boolean operators (`AND`, `OR`, `-` for negation). Full syntax: https://docs.railway.com/guides/logs
+
+### Scoped by environment
+
+```bash
+railway logs --service <service> --environment <env> --lines 200 --json
+```
+
+### HTTP logs
+
+Use HTTP logs when a service responds with errors, latency spikes, or routing problems:
+
+```bash
+railway logs --service <service> --http --status ">=400" --lines 100 --json
+railway logs --service <service> --http --method POST --path /api/users --lines 100 --json
+railway logs --service <service> --http --request-id <request-id> --lines 20 --json
+railway logs --service <service> --http --filter "@totalDuration:>=1000" --lines 100 --json
+```
+
+HTTP filter fields include `@method`, `@path`, `@host`, `@requestId`, `@srcIp`, `@edgeRegion`, `@httpStatus`, `@totalDuration`, `@responseTime`, `@txBytes`, and `@rxBytes`.
+
+## Metrics
+
+Use `railway metrics` for resource and HTTP metrics. It summarizes CPU, memory, network, volume, and HTTP data for the linked service by default.
+
+```bash
+railway metrics --service <service> --since 1h --json
+railway metrics --service <service> --since 6h --cpu --memory --json
+railway metrics --service <service> --http --method POST --path /api/users --json
+railway metrics --all --environment production --json
+```
+
+Use `--raw` for time-series data points:
+
+```bash
+railway metrics --service <service> --raw --cpu --json
+```
+
+Metric flags can be combined: `--cpu`, `--memory`, `--network`, `--volume`, and `--http`. Use `--watch` only in an interactive terminal; it opens a live TUI and conflicts with `--json` and `--raw`.
+
+For custom grouping or measurements the CLI doesn't expose, use the GraphQL fallback in [request.md](request.md).
+
+## SSH
+
+Use SSH when logs and metrics don't expose enough state and the user needs shell-level inspection inside a running service.
+
+```bash
+railway ssh --service <service> --environment <env>
+railway ssh --service <service> --environment <env> -- "printenv | sort"
+railway ssh --service <service> --environment <env> --session railway-debug
+railway ssh --service <service> --environment <env> --identity-file ~/.ssh/id_ed25519_railway
+```
+
+Manage Railway SSH keys with:
+
+```bash
+railway ssh keys list
+railway ssh keys add --key ~/.ssh/id_ed25519.pub --name <key-name>
+railway ssh keys github
+railway ssh keys remove <key-id> --2fa-code <code>
+```
+
+Workspace-owned keys use `--workspace <workspace-id>` and require workspace Admin access. SSH key management doesn't work with project tokens (`RAILWAY_TOKEN`); use `railway login` or a workspace-scoped `RAILWAY_API_TOKEN`.
+
+## Database inspection
+
+For database-level metrics and introspection, use the analysis scripts. `railway metrics` can provide infrastructure metrics and supported database summaries, while the scripts provide deeper engine-level analysis. See [analyze-db.md](analyze-db.md) for comprehensive database analysis including:
+
+- Deep Postgres analysis (pg_stat_statements, vacuum health, index health, cache hit ratios)
+- HA cluster checks (Patroni, etcd, HAProxy)
+- Redis, MySQL, and MongoDB introspection
+- Combined analysis via `scripts/analyze-<type>.py` (postgres, mysql, redis, mongo)
+
+## Failure triage
+
+When something is broken, classify the failure first. The fix depends on the class.
+
+### Build failures
+
+The service failed to build. Look at build logs:
+
+```bash
+railway logs --latest --build --lines 400 --json
+```
+
+Common causes and fixes:
+- **Missing dependencies**: check lockfiles, verify package manager detection
+- **Wrong build command**: override with `railway environment edit --service-config <service> build.buildCommand "<command>"`
+- **Builder mismatch**: switch builders with `railway environment edit --service-config <service> build.builder RAILPACK`
+- **Wrong root directory** (monorepo): set `source.rootDirectory` to the correct package path
+
+### Runtime failures
+
+The build succeeded but the service crashes or misbehaves:
+
+```bash
+railway logs --latest --lines 400 --json
+railway logs --service <service> --since 1h --lines 400 --json
+```
+
+Common causes and fixes:
+- **Bad start command**: override with `railway environment edit --service-config <service> deploy.startCommand "<command>"`
+- **Missing runtime variable**: check `railway variable list --service <service> --json` and set missing values
+- **Port mismatch**: the service must listen on `$PORT` (Railway injects this). Verify with logs.
+- **Upstream dependency down**: check other services' status and logs
+
+### Config-driven failures
+
+Something worked before and broke after a config change:
+
+```bash
+railway environment config --json
+railway variable list --service <service> --json
+```
+
+Compare the config against expected values. Look for changes that may have introduced the regression.
+
+### Networking failures
+
+Domain returns errors, or service-to-service calls fail:
+
+```bash
+railway domain --service <service> --json
+railway logs --service <service> --lines 200 --json
+railway logs --service <service> --http --status ">=400" --lines 100 --json
+```
+
+Check: target port matches what the service listens on, domain status is healthy, private domain variable references are correct.
+
+## Recovery
+
+After identifying the cause, fix and verify:
+
+```bash
+# Fix (examples)
+railway environment edit --service-config <service> deploy.startCommand "<correct-command>"
+railway variable set MISSING_VAR=value --service <service>
+
+# Redeploy
+railway redeploy --service <service> --yes
+
+# Verify
+railway service status --service <service> --json
+railway logs --service <service> --lines 200 --json
+```
+
+Always verify after fixing. Don't assume the redeploy succeeded.
+
+## Troubleshoot common blockers
+
+- **Unlinked context**: `railway link --project <id-or-name>`
+- **Missing service scope for logs**: pass `--service` and `--environment` explicitly
+- **No deployments found**: the service exists but has never deployed, create an initial deploy first
+- **Metrics return empty**: check the time window, service scope, and whether the service has active deployments
+- **Config patch type error**: check the typed paths in [configure.md](configure.md), for example, `numReplicas` is an integer, not a string
+
+## Validated against
+
+- Docs: [status.md](https://docs.railway.com/cli/status), [service.md](https://docs.railway.com/cli/service), [logs.md](https://docs.railway.com/cli/logs), [metrics.md](https://docs.railway.com/cli/metrics), [ssh.md](https://docs.railway.com/cli/ssh), [observability/logs.md](https://docs.railway.com/observability/logs), [observability/metrics.md](https://docs.railway.com/observability/metrics)
+- CLI source: [status.rs](https://github.com/railwayapp/cli/blob/v4.58.0/src/commands/status.rs), [service.rs](https://github.com/railwayapp/cli/blob/v4.58.0/src/commands/service.rs), [logs.rs](https://github.com/railwayapp/cli/blob/v4.58.0/src/commands/logs.rs), [metrics.rs](https://github.com/railwayapp/cli/blob/v4.58.0/src/commands/metrics.rs), [ssh/mod.rs](https://github.com/railwayapp/cli/blob/v4.58.0/src/commands/ssh/mod.rs), [deployment.rs](https://github.com/railwayapp/cli/blob/v4.58.0/src/commands/deployment.rs), [redeploy.rs](https://github.com/railwayapp/cli/blob/v4.58.0/src/commands/redeploy.rs)

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

@@ -0,0 +1,248 @@
+# Request
+
+Official documentation and community endpoints. GraphQL operations for things the CLI doesn't expose.
+
+## Official documentation
+
+Primary sources for authoritative Railway information:
+
+- **Full LLM docs**: `https://docs.railway.com/api/llms-docs.md`
+- **LLM summary**: `https://railway.com/llms.txt`
+- **Templates**: `https://railway.com/llms-templates.md`
+- **Changelog**: `https://railway.com/llms-changelog.md`
+- **Blog**: `https://blog.railway.com/llms-blog.md`
+- **Direct doc pages**: `https://docs.railway.com/<path>` (for example, `cli/up`, `networking/domains`, `observability/logs`)
+
+Tip: append `.md` to any `docs.railway.com` page URL to get a markdown version suitable for LLM consumption.
+
+Common doc paths:
+
+| Topic | Path |
+|---|---|
+| Projects | `guides/projects` |
+| Deployments | `guides/deployments` |
+| Volumes | `guides/volumes` |
+| Variables | `guides/variables` |
+| CLI reference | `reference/cli-api` |
+| Pricing | `reference/pricing` |
+| Public networking | `networking/public-networking` |
+| Private networking | `networking/private-networking` |
+
+Fetch official docs first for product behavior questions. Use Central Station only when you need community evidence, prior incidents, or implementation anecdotes.
+
+
+## Central Station (community)
+
+Search and browse Railway's community platform for prior discussions, issue patterns, and field solutions.
+
+### Recent threads
+
+```bash
+curl -s 'https://station-server.railway.com/gql' \
+  -H 'content-type: application/json' \
+  -d '{"query":"{ threads(first: 10, sort: recent_activity) { edges { node { slug subject status upvoteCount createdAt topic { slug displayName } } } } }"}'
+```
+
+Filter by topic with the `topic` parameter (`"questions"`, `"feedback"`, `"community"`, `"billing"`):
+
+```bash
+curl -s 'https://station-server.railway.com/gql' \
+  -H 'content-type: application/json' \
+  -d '{"query":"{ threads(first: 10, sort: recent_activity, topic: \"questions\") { edges { node { slug subject status topic { displayName } upvoteCount } } } }"}'
+```
+
+Sort options: `recent_activity` (default), `newest`, `highest_votes`.
+
+### Search threads
+
+```bash
+curl -s 'https://station-server.railway.com/gql' \
+  -H 'content-type: application/json' \
+  -d '{"query":"{ threads(first: 10, search: \"<search-term>\") { edges { node { slug subject status } } } }"}'
+```
+
+### LLM data export
+
+Bulk search alternative, fetches all public threads with full content:
+
+```bash
+curl -s 'https://station-server.railway.com/api/llms-station'
+```
+
+### Read a full thread
+
+```bash
+curl -s 'https://station-server.railway.com/api/threads/<slug>?format=md'
+```
+
+Thread URLs follow the format: `https://station.railway.com/{topic_slug}/{thread_slug}`
+
+Community threads are anecdotal. Always pair with official docs when the answer informs an operational decision.
+
+
+## GraphQL helper
+
+All GraphQL operations use the API helper script, which handles authentication automatically:
+
+```bash
+scripts/railway-api.sh '<query>' '<variables-json>'
+```
+
+The script reads the API token from `~/.railway/config.json` and sends requests to `https://backboard.railway.com/graphql/v2`.
+
+For the full API schema, see: https://docs.railway.com/api/llms-docs.md
+
+## Project mutations
+
+The CLI doesn't expose project setting updates (rename, PR deploys, visibility). Use GraphQL:
+
+```bash
+scripts/railway-api.sh \
+  'mutation updateProject($id: String!, $input: ProjectUpdateInput!) {
+    projectUpdate(id: $id, input: $input) { id name isPublic prDeploys botPrEnvironments }
+  }' \
+  '{"id":"<project-id>","input":{"name":"new-name","prDeploys":true}}'
+```
+
+Common `ProjectUpdateInput` fields: `name`, `isPublic`, `prDeploys`, `botPrEnvironments`.
+
+
+## Service mutations
+
+The CLI can create services (`railway add`) but cannot rename them or change icons. Use GraphQL:
+
+```bash
+scripts/railway-api.sh \
+  'mutation updateService($id: String!, $input: ServiceUpdateInput!) {
+    serviceUpdate(id: $id, input: $input) { id name icon }
+  }' \
+  '{"id":"<service-id>","input":{"name":"new-name"}}'
+```
+
+`ServiceUpdateInput` fields: `name`, `icon` (image URL, animated GIF, or devicons URL like `https://devicons.railway.app/postgres`).
+
+Get the service ID from `railway service list --json`.
+
+
+## Service creation via GraphQL
+
+Prefer `railway add` for most cases. Use GraphQL for programmatic or advanced use:
+
+```bash
+scripts/railway-api.sh \
+  'mutation createService($input: ServiceCreateInput!) {
+    serviceCreate(input: $input) { id name }
+  }' \
+  '{"input":{"projectId":"<project-id>","name":"my-service","source":{"image":"nginx:latest"}}}'
+```
+
+`ServiceCreateInput` fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `projectId` | String! | Target project (required) |
+| `name` | String | Service name (auto-generated if omitted) |
+| `source.image` | String | Docker image (for example, `nginx:latest`) |
+| `source.repo` | String | GitHub repo (for example, `user/repo`) |
+| `branch` | String | Git branch for repo source |
+| `environmentId` | String | Create only in a specific environment |
+
+After creating a service via GraphQL, configure it with a JSON config patch including `isCreated: true` (see [configure.md](configure.md)).
+
+
+## Metrics queries
+
+Use `railway metrics` for routine metric checks. Use GraphQL only when you need custom measurements, grouping, sample rates, or averaging windows that the CLI doesn't expose.
+
+```bash
+scripts/railway-api.sh \
+  'query metrics($environmentId: String!, $serviceId: String, $startDate: DateTime!, $endDate: DateTime, $sampleRateSeconds: Int, $averagingWindowSeconds: Int, $groupBy: [MetricTag!], $measurements: [MetricMeasurement!]!) {
+    metrics(environmentId: $environmentId, serviceId: $serviceId, startDate: $startDate, endDate: $endDate, sampleRateSeconds: $sampleRateSeconds, averagingWindowSeconds: $averagingWindowSeconds, groupBy: $groupBy, measurements: $measurements) {
+      measurement tags { serviceId deploymentId region } values { ts value }
+    }
+  }' \
+  '{"environmentId":"<env-id>","serviceId":"<service-id>","startDate":"2026-02-19T00:00:00Z","measurements":["CPU_USAGE","MEMORY_USAGE_GB"]}'
+```
+
+Available `MetricMeasurement` values: `CPU_USAGE`, `CPU_LIMIT`, `MEMORY_USAGE_GB`, `MEMORY_LIMIT_GB`, `NETWORK_RX_GB`, `NETWORK_TX_GB`, `DISK_USAGE_GB`, `EPHEMERAL_DISK_USAGE_GB`, `BACKUP_USAGE_GB`.
+
+Optional parameters: `endDate` (defaults to now), `sampleRateSeconds`, `averagingWindowSeconds`. Use `groupBy: ["SERVICE_ID"]` without `serviceId` to query all services in an environment at once. Valid `MetricTag` values for `groupBy`: `SERVICE_ID`, `DEPLOYMENT_ID`, `DEPLOYMENT_INSTANCE_ID`, `REGION`.
+
+Get the environment ID from `railway status --json`. Get service IDs from `railway service list --json`.
+
+## Template search
+
+Use the CLI for template search:
+
+```bash
+railway templates search redis --verified true --json
+railway templates search --category database --limit 10 --json
+railway templates search --after <cursor> --json
+```
+
+The CLI search command doesn't require authentication and supports pagination with `pageInfo.endCursor`.
+
+Use GraphQL only when the CLI output isn't enough for the workflow:
+
+```bash
+scripts/railway-api.sh \
+  'query templates($query: String!, $verified: Boolean, $recommended: Boolean) {
+    templates(query: $query, verified: $verified, recommended: $recommended) {
+      edges { node { code name description category } }
+    }
+  }' \
+  '{"query":"redis","verified":true}'
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `query` | String | Search term |
+| `verified` | Boolean | Only verified templates |
+| `recommended` | Boolean | Only recommended templates |
+| `first` | Int | Number of results |
+
+Common template codes: `ghost`, `strapi`, `minio`, `n8n`, `uptime-kuma`, `umami`, `postgres`, `redis`, `mysql`, `mongodb`.
+
+Deploy a found template via CLI:
+
+```bash
+railway deploy --template <template-code>
+```
+
+### GraphQL template deployment
+
+For deploying into a specific environment or tracking the workflow, use the two-step GraphQL flow:
+
+**Step 1**: Fetch the template config:
+
+```bash
+scripts/railway-api.sh \
+  'query template($code: String!) {
+    template(code: $code) { id serializedConfig }
+  }' \
+  '{"code":"postgres"}'
+```
+
+**Step 2**: Deploy with `templateDeployV2`:
+
+```bash
+scripts/railway-api.sh \
+  'mutation deploy($input: TemplateDeployV2Input!) {
+    templateDeployV2(input: $input) { projectId workflowId }
+  }' \
+  '{"input":{
+    "templateId":"<id-from-step-1>",
+    "serializedConfig":<config-object-from-step-1>,
+    "projectId":"<project-id>",
+    "environmentId":"<env-id>",
+    "workspaceId":"<workspace-id>"
+  }}'
+```
+
+`serializedConfig` is the raw JSON object from the template query, not a string. Get `workspaceId` via `scripts/railway-api.sh 'query { project(id: "<project-id>") { workspaceId } }' '{}'`.
+
+
+## Validated against
+
+- Docs: [api docs](https://docs.railway.com/api/llms-docs.md), [community.md](https://docs.railway.com/community), [cli/docs.md](https://docs.railway.com/cli/docs), [templates.md](https://docs.railway.com/cli/templates), [metrics.md](https://docs.railway.com/cli/metrics)
+- CLI source: [docs.rs](https://github.com/railwayapp/cli/blob/v4.58.0/src/commands/docs.rs), [templates.rs](https://github.com/railwayapp/cli/blob/v4.58.0/src/commands/templates.rs), [metrics.rs](https://github.com/railwayapp/cli/blob/v4.58.0/src/commands/metrics.rs)