@synapta/skills 0.1.1 → 0.2.0

package/skills/deploy-railway/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: deploy-railway
+triggers: [synapta deploy railway, Railway deploy, railway up, railway variables]
+network: allowlist
+source:
+  origin: https://github.com/railwayapp/railway-skills
+  path: plugins/railway/skills/use-railway
+  commit: 380a2abbb0f9
+  license: MIT (Railway Corporation)
+  adapted: light-touch
+description: >
+  Operate Railway infrastructure: create projects, provision services and
+  databases, manage object storage buckets, deploy code, configure environments
+  and variables, manage domains, troubleshoot failures, check status and metrics,
+  set up Railway agent tooling, and query Railway docs. Use this skill whenever
+  the user mentions Railway, deployments, services, environments, buckets,
+  object storage, build failures, agent setup, MCP, or infrastructure operations,
+  even if they don't say "Railway" explicitly.
+allowed-tools: Bash(railway:*), Bash(which:*), Bash(command:*), Bash(npm:*), Bash(npx:*), Bash(curl:*), Bash(python3:*)
+---
+
+# Use Railway
+
+## Railway resource model
+
+Railway organizes infrastructure in a hierarchy:
+
+- **Workspace** is the billing and team scope. A user belongs to one or more workspaces.
+- **Project** is a collection of services under one workspace. It maps to one deployable unit of work.
+- **Environment** is an isolated configuration plane inside a project (for example, `production`, `staging`). Each environment has its own variables, config, and deployment history.
+- **Service** is a single deployable unit inside a project. It can be an app from a repo, a Docker image, or a managed database.
+- **Bucket** is an S3-compatible object storage resource inside a project. Buckets are created at the project level and deployed to environments. Each bucket has credentials (endpoint, access key, secret key) for S3-compatible access.
+- **Deployment** is a point-in-time release of a service in an environment. It has build logs, runtime logs, and a status lifecycle.
+
+Most CLI commands operate on the linked project/environment/service context. Use `railway status --json` to see the context, and `--project`, `--environment`, `--service` flags to override.
+
+## Parsing Railway URLs
+
+Users often paste Railway dashboard URLs. Extract IDs before doing anything else:
+
+```
+https://railway.com/project/<PROJECT_ID>/service/<SERVICE_ID>?environmentId=<ENV_ID>
+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 \
+  'query getProject($id: String!) {
+    project(id: $id) {
+      environments { edges { node { id name } } }
+    }
+  }' \
+  '{"id": "<PROJECT_ID>"}'
+```
+
+Match the environment name (case-insensitive) to get the `environmentId`.
+
+**Prefer passing explicit IDs** to CLI commands (`--project`, `--environment`, `--service`) and scripts (`--project-id`, `--environment-id`, `--service-id`) instead of running `railway link`. This avoids modifying global state and is faster.
+
+## Preflight
+
+Before any mutation, verify context:
+
+```bash
+command -v railway                # CLI installed
+RAILWAY_CALLER="skill:use-railway@1.2.1" RAILWAY_AGENT_SESSION="railway-skill-$(date +%s)-$$" railway whoami --json
+railway --version                 # check CLI version
+```
+
+For Railway CLI calls made while this skill is active, prefix the command with `RAILWAY_CALLER=skill:use-railway@1.2.1` 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.
+- If no URL is given, fall back to `railway status --json` for the linked project/environment/service.
+
+If the CLI is missing, guide the user to install it.
+
+```bash
+bash <(curl -fsSL https://railway.com/install.sh) --agents -y # Install CLI and configure detected agents
+bash <(curl -fsSL https://railway.com/install.sh) # Shell script (macOS, Linux, Windows via WSL)
+npm i -g @railway/cli # npm (macOS, Linux, Windows). Requires Node.js version 16 or higher.
+brew install railway # Homebrew (macOS)
+```
+
+If not authenticated, run `railway login`. If not linked and no URL was provided, run `railway link --project <id-or-name>`.
+
+If a command is not recognized (for example, `railway environment edit`), the CLI may be outdated. Upgrade with:
+
+```bash
+railway upgrade
+```
+
+## Agent tooling
+
+Use direct Railway CLI commands for deterministic operations. Use `railway agent` only when the user explicitly asks for Railway Agent, wants a natural-language investigation, or the task is broader than a single resource operation.
+
+Set up Railway skills, MCP, and authentication with:
+
+```bash
+railway setup agent
+railway setup agent -y
+railway setup agent --remote
+```
+
+`railway setup agent -y` skips the interactive login flow. If the user isn't authenticated after setup, run `railway login`.
+
+Install or update MCP and skills directly when the user names a target tool:
+
+```bash
+railway mcp install
+railway mcp install --agent codex
+railway mcp install --agent cursor --remote
+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.
+
+Use Railway Agent chat with:
+
+```bash
+railway agent
+railway agent -p "why is my service crashing?"
+railway agent -p "summarize the deployment status" --json
+railway agent --list --json
+railway agent --thread-id <thread-id>
+```
+
+`railway agent` requires user OAuth authentication from `railway login`. Project tokens (`RAILWAY_TOKEN`) are not supported for Railway Agent chat. If an agent command is unavailable, upgrade with `railway upgrade --yes`.
+
+## Common quick operations
+
+These are frequent enough to handle without loading a reference:
+
+```bash
+railway status --json                                    # current context
+railway whoami --json                                    # auth and workspace info
+railway project list --json                              # list projects
+railway service list --json                              # services in current environment
+railway variable list --service <svc> --json             # list variables
+railway variable set KEY=value --service <svc>           # set a variable
+railway logs --service <svc> --lines 200 --json          # recent logs
+railway metrics --service <svc> --since 1h --json        # resource and HTTP metrics summary
+railway up --detach -m "<summary>"                       # deploy current directory
+railway bucket list --json                               # list buckets in current environment
+railway bucket info --bucket <name> --json               # bucket storage and object count
+railway bucket credentials --bucket <name> --json        # S3-compatible credentials
+```
+
+When using these commands from the skill, keep the command shape but prefix the Railway invocation with the telemetry env, for example:
+
+```bash
+RAILWAY_CALLER="skill:use-railway@1.2.1" RAILWAY_AGENT_SESSION="railway-skill-20260508-1234" railway status --json
+```
+
+## 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.
+
+| Intent | Reference | Use for |
+|---|---|---|
+| **Analyze a database** ("analyze \<url\>", "analyze db", "analyze database", "analyze service", "introspect", "check my postgres/redis/mysql/mongo") | [analyze-db.md](references/analyze-db.md) | Database introspection and performance analysis. analyze-db.md directs you to the DB-specific reference. **This takes priority over the status/operate routes when a Railway URL to a database service is provided alongside "analyze".** |
+| 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 |
+| Check health or debug failures | [operate.md](references/operate.md) | Status, logs, metrics, build/runtime triage, recovery |
+| Request from API, docs, or community | [request.md](references/request.md) | Railway GraphQL API queries/mutations, metrics queries, Central Station, official docs |
+
+If the request spans two areas (for example, "deploy and then check if it's healthy"), load both references and compose one response.
+
+## Execution rules
+
+1. Prefer Railway CLI. Fall back to `scripts/railway-api.sh` for operations the CLI doesn't expose.
+2. Use `--json` output where available for reliable parsing.
+3. Resolve context before mutation. Know which project, environment, and service you're acting on.
+4. For destructive actions (delete service, remove deployment, drop database), confirm intent and state impact before executing.
+5. After mutations, verify the result with a read-back command.
+
+## User-only commands (NEVER execute directly)
+
+These commands modify database state and require the user to run them directly in their terminal. **Do NOT execute these with Bash. Instead, show the command and ask the user to run it.**
+
+| Command | Why user-only |
+|---------|---------------|
+| `python3 scripts/enable-pg-stats.py --service <name>` | Modifies shared_preload_libraries, may restart database |
+| `python3 scripts/pg-extensions.py --service <name> install <ext>` | Installs database extension |
+| `python3 scripts/pg-extensions.py --service <name> uninstall <ext>` | Removes database extension |
+| `ALTER SYSTEM SET ...` | Changes PostgreSQL configuration |
+| `DROP EXTENSION ...` | Removes database extension |
+| `CREATE EXTENSION ...` | Installs database extension |
+
+When these operations are needed:
+1. Explain what the command does and any side effects (e.g., restart required)
+2. Show the exact command the user must run
+3. Wait for user confirmation that they ran it
+4. Verify the result with a read-only query
+
+## Composition patterns
+
+Multi-step workflows follow natural chains:
+
+- **Add object storage**: setup (create bucket), setup (get credentials), configure (set S3 variables on app service)
+- **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)
+- **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.
+
+## Setup decision flow
+
+When the user wants to create or deploy something, determine the right action from current context:
+
+1. Run `railway status --json` in the current directory.
+2. **If linked**: add a service to the existing project (`railway add --service <name>`). Do not create a new project unless the user explicitly says "new project" or "separate project".
+3. **If not linked**: check the parent directory (`cd .. && railway status --json`).
+   - **Parent linked**: this is likely a monorepo sub-app. Add a service and set `rootDirectory` to the sub-app path.
+   - **Parent not linked**: run `railway list --json` and look for a project matching the directory name.
+     - **Match found**: link to it (`railway link --project <name>`).
+     - **No match**: create a new project (`railway init --name <name>`).
+4. When multiple workspaces exist, match by name from `railway whoami --json`.
+
+**Naming heuristic**: app names like "flappy-bird" or "my-api" are service names, not project names. Use the directory or repo name for the project.
+
+## Response format
+
+For all operational responses, return:
+1. What was done (action and scope).
+2. The result (IDs, status, key output).
+3. What to do next (or confirmation that the task is complete).
+
+Keep output concise. Include command evidence only when it helps the user understand what happened.

package/skills/deploy-railway/references/analyze-db-mongo.md

@@ -0,0 +1,84 @@
+# MongoDB Analysis
+
+This reference covers MongoDB-specific metrics, tuning, and analysis guidance.
+For common analysis patterns (output structure, collection status handling, performance thinking), see [analyze-db.md](analyze-db.md).
+
+### What the Script Collects
+
+**Via SSH (mongosh):**
+- **Server Status:** version, storage engine, uptime, connections, opcounters, latency, memory, network, WiredTiger cache/checkpoint/tickets, global lock queues, document operations, query efficiency, cursors, TTL, asserts
+- **DB Stats:** dataSize, storageSize, indexSize, object count, collection count
+- **Collection Stats:** per-collection document count, size, storage size, index size, index count
+- **Current Operations:** active ops with type, namespace, duration
+- **Slow Queries:** from system.profile (if profiling enabled) — op, namespace, duration, plan summary
+- **Replication Info:** oplog size, usage, time window
+- **Top Collections:** per-collection read/write counts and time from `top` admin command
+
+**Via Railway API:** Same infrastructure metrics.
+
+### MongoDB Performance Patterns
+
+**WiredTiger Cache Pressure Pattern:**
+- Cache usage > 80% + app thread evictions > 0 = cache too small for working set
+- Dirty cache > 20% of total = checkpoint falling behind, writes accumulating
+- Read/write tickets depleted = operations queueing at storage engine level
+- Fix: increase service RAM (WiredTiger uses ~50% of available RAM for cache)
+
+**Query Efficiency Pattern:**
+- `scannedObjects >> docsReturned` = collection scans, missing indexes
+- Plan cache misses >> hits = frequent query re-planning, add indexes
+- Sort spill to disk > 0 = sorts exceeding 100MB memory limit, needs index
+
+**Connection Saturation Pattern:**
+- `connectionsCurrent` approaching `connectionsAvailable` = connection pool exhaustion
+- Many active ops with high microsecs_running = slow queries holding connections
+- Queued readers/writers > 0 = global lock contention
+
+**Oplog Pressure Pattern:**
+- Oplog usage > 80% = replication window shrinking
+- High write rate + small oplog = replicas may fall out of sync
+- timeDiffHours < 1 on busy systems = risk of replica resync
+
+### MongoDB Thresholds
+
+| Metric | Healthy | Warning | Critical |
+|--------|---------|---------|----------|
+| WT cache usage | <70% | 70-85% | >85% |
+| WT dirty % | <5% | 5-20% | >20% |
+| App thread evictions | 0 | 1-100 | >100 |
+| Connection usage | <70% | 70-85% | >85% |
+| Queued operations | 0 | 1-10 | >10 |
+| Scan-to-return ratio | <2x | 2-10x | >10x |
+
+## Infrastructure (7d + 24h)
+
+Show both windows side by side to compare trends:
+
+**7-Day Trends**
+| Metric | Current | Avg | Min | Max | Trend |
+|--------|---------|-----|-----|-----|-------|
+| CPU | 0.02 vCPU | 0.02 | 0.00 | 0.12 | stable |
+| Memory | 210 MB | 200 MB | 180 MB | 240 MB | stable |
+| Disk | 1.5 GB | 1.48 GB | 1.42 GB | 1.55 GB | increasing (+6%) |
+
+**Last 24 Hours**
+| Metric | Current | Avg | Min | Max | Trend |
+|--------|---------|-----|-----|-----|-------|
+| CPU | 0.03 vCPU | 0.02 | 0.00 | 0.12 | stable |
+| Memory | 210 MB | 205 MB | 195 MB | 240 MB | stable |
+| Disk | 1.5 GB | 1.49 GB | 1.48 GB | 1.51 GB | stable |
+
+Compare windows to distinguish sustained vs transient trends.
+
+Do NOT show cpu_limit/memory_limit columns or utilization %. Railway auto-scales — these limits are just the ceiling. See [analyze-db.md](analyze-db.md) autoscale rules.
+
+## MongoDB Autoscale Note
+
+See [analyze-db.md](analyze-db.md) for full autoscale rules. For MongoDB specifically:
+- WiredTiger uses ~50% of available RAM for cache by default. As Railway auto-scales the container, the cache ceiling grows automatically.
+- Do NOT recommend limiting WiredTiger cache to a fraction of the Railway memory limit — the limit is the autoscale ceiling, not fixed allocation.
+- If cache usage is consistently >80%, this indicates working set pressure — note it but do not tell the user to increase RAM manually.
+
+## Validated against
+
+- MongoDB serverStatus, db.stats(), system.profile, top admin command

package/skills/deploy-railway/references/analyze-db-mysql.md

@@ -0,0 +1,254 @@
+# MySQL Analysis
+
+This reference covers MySQL-specific metrics, tuning, and analysis guidance.
+For common analysis patterns (output structure, collection status handling, performance thinking), see [analyze-db.md](analyze-db.md).
+
+## What the Script Collects
+
+**Via SSH (mysql -B):**
+- **SHOW GLOBAL STATUS:** threads connected/running, max used connections, query counts (select/insert/update/delete), InnoDB buffer pool stats, row lock waits/time, bytes sent/received, temp table stats, handler stats, table lock stats, aborted clients/connects
+- **SHOW VARIABLES:** max_connections, innodb_buffer_pool_size, long_query_time, version
+- **Table Sizes:** per-table rows, data length, index length, total size (top 15)
+- **Processlist:** active queries with user, database, command, time, state
+- **Top Queries (performance_schema):** digest text, call count, avg/total latency, rows examined/sent, temp disk tables, no-index flag
+
+**Via Railway API:** Same infrastructure metrics (CPU, memory, disk, network).
+
+## MySQL Metric Sections — Present ALL of These
+
+When the script returns MySQL data, present **every section below** with its metrics. This matches the full MySQL metrics view. Don't skip sections — if data is present, show it.
+
+### 1. Overview
+
+| Metric | JSON Path | How to Display |
+|--------|-----------|----------------|
+| Version | `overview.version` | As-is |
+| Uptime | `overview.uptime_seconds` | Format as Xd Xh Xm |
+| Connections | `overview.connection_usage_percent` | `XX%` with `threads_connected / max_connections` as sub-value |
+| Threads Running | `overview.threads_running` | As-is |
+| Aborted Clients | `overview.aborted_clients` | Warn if > 0 — apps not closing connections |
+| Aborted Connects | `overview.aborted_connects` | Warn if > 0 — auth failures or limit hits |
+
+**Presentation:**
+```
+| Metric | Value | Status |
+|--------|-------|--------|
+| Version | 9.4.0 | |
+| Uptime | 3d 12h | |
+| Connections | 45% (9 / 20) | OK |
+| Threads Running | 2 | |
+| Aborted Clients | 0 | OK |
+| Aborted Connects | 0 | OK |
+```
+
+### 2. Query Throughput
+
+| Metric | JSON Path | How to Display |
+|--------|-----------|----------------|
+| Total Queries | `query_throughput.questions` | Format with K/M suffix |
+| Slow Queries | `query_throughput.slow_queries` | Warn if > 0, show threshold from `long_query_time` |
+| SELECT | `query_throughput.com_select` | Format with K/M suffix |
+| INSERT | `query_throughput.com_insert` | Format with K/M suffix |
+| UPDATE | `query_throughput.com_update` | Format with K/M suffix |
+| DELETE | `query_throughput.com_delete` | Format with K/M suffix |
+
+Show the query mix distribution. A healthy OLTP workload is SELECT-heavy. INSERT/UPDATE-heavy suggests write pressure.
+
+### 3. InnoDB Row Operations
+
+| Metric | JSON Path |
+|--------|-----------|
+| Rows Read | `innodb_row_ops.rows_read` |
+| Rows Inserted | `innodb_row_ops.rows_inserted` |
+| Rows Updated | `innodb_row_ops.rows_updated` |
+| Rows Deleted | `innodb_row_ops.rows_deleted` |
+
+These are cumulative since server start. Compare read vs write ratios. A read-heavy workload with low row reads may indicate queries returning few results (good) or not using indexes (bad — cross-reference with table scan ratio).
+
+### 4. Query Efficiency
+
+| Metric | JSON Path | How to Interpret |
+|--------|-----------|------------------|
+| Temp Tables to Disk | `query_efficiency.tmp_disk_table_percent` | `XX%` (disk/total). > 10% = queries creating large temp results |
+| Table Scan Ratio | `query_efficiency.table_scan_percent` | `XX%`. > 50% = most reads are full scans — missing indexes |
+| Full Joins | `query_efficiency.select_full_join` | Warn if > 0. Joins without indexes — extremely expensive |
+| Range Selects | `query_efficiency.select_range` | Index range scans (good). Higher is better relative to full scans |
+| Sort Merge Passes | `query_efficiency.sort_merge_passes` | Warn if > 0. Sorts exceeding `sort_buffer_size` |
+
+**This section is critical for identifying missing indexes.** If table scan ratio is high AND specific top queries show `no_index_used > 0`, you can give precise index recommendations.
+
+### 5. InnoDB Buffer Pool
+
+| Metric | JSON Path | How to Display |
+|--------|-----------|----------------|
+| Cache Hit Ratio | `innodb_buffer_pool.hit_ratio` | `XX.X%`. The most important single metric |
+| Pool Usage | `innodb_buffer_pool.usage_percent` | `XX.X%` with `bytes_data / buffer_pool_size` as sub-value |
+| Data | `innodb_buffer_pool.bytes_data` | Format as MB/GB |
+| Dirty | `innodb_buffer_pool.bytes_dirty` | Format as MB/GB. Warn if significant |
+| Free Pages | `innodb_buffer_pool.pages_free` | Format with K/M suffix |
+
+**Analysis guidance:**
+- Hit ratio < 99% + usage > 95% = buffer pool too small for the working set
+- Hit ratio < 95% = severe cache pressure — increase `innodb_buffer_pool_size`
+- Dirty pages are modified pages not yet flushed to disk — high dirty count means heavy writes or slow I/O
+
+### 6. InnoDB I/O
+
+| Metric | JSON Path |
+|--------|-----------|
+| Data Reads | `innodb_io.data_reads` |
+| Data Writes | `innodb_io.data_writes` |
+
+Only show this section if reads or writes > 0. High data reads with low buffer pool hit ratio = cache misses causing disk I/O.
+
+### 7. Network
+
+| Metric | JSON Path |
+|--------|-----------|
+| Bytes Received | `network.bytes_received` |
+| Bytes Sent | `network.bytes_sent` |
+
+Format as KB/MB/GB. High bytes sent relative to received suggests large result sets being returned.
+
+### 8. Locks
+
+| Metric | JSON Path | How to Interpret |
+|--------|-----------|------------------|
+| Row Lock Waits | `locks.row_lock_waits` | Warn if > 0. InnoDB row-level lock contention |
+| Row Lock Time (ms) | `locks.row_lock_time` | Total time spent waiting for row locks |
+| Table Lock Waits | `locks.table_locks_waited` | Warn if > 0. Table-level lock contention |
+| Table Lock Contention | `locks.table_lock_contention` | `XX.X%` (waited / total). > 1% = investigate |
+
+Lock contention + long-running queries in processlist = transactions holding locks too long. Check for MyISAM tables if table lock contention is high.
+
+### 9. Table Cache
+
+| Metric | JSON Path |
+|--------|-----------|
+| Open Tables | `table_cache.open_tables` |
+| Opened Tables | `table_cache.opened_tables` |
+| Cache Hit % | `table_cache.cache_hit_percent` |
+
+Low cache hit = table_open_cache may be too small. Many opened_tables relative to open_tables means tables are being repeatedly opened and closed.
+
+### 10. Top Queries (from performance_schema)
+
+**This is the most actionable section.** Present as a table:
+
+```
+| Query | Calls | Avg Latency | Total Latency | Rows Examined | Rows Sent | Flags |
+|-------|-------|-------------|---------------|---------------|-----------|-------|
+| SELECT ... FROM orders WHERE... | 15.2K | 2.3ms | 35.1s | 1.2M | 15.2K | |
+| SELECT ... FROM users JOIN... | 8.1K | 12.5ms | 101.3s | 890K | 8.1K | ! No Index |
+```
+
+**Per-query analysis:**
+- `no_index_used > 0` → Flag with "! No Index" — these are the biggest optimization targets
+- `tmp_disk_tables > 0` → Query creates on-disk temp tables — needs optimization
+- High `rows_examined / rows_sent` ratio → Scanning many rows to return few — missing or suboptimal index
+- Truncate query text to essential parts (tables, WHERE clauses, JOINs). Don't dump full ORM SQL.
+
+**If `top_queries` is empty or null:** performance_schema is likely disabled — this is the default on Railway. Do not suggest enabling it without caveats: it requires ~400MB+ additional memory and is only advisable on larger instances. Just note that query-level data is unavailable.
+
+### 11. Tables
+
+```
+| Table | Rows | Data | Indexes | Total |
+|-------|------|------|---------|-------|
+| orders | 1.2M | 450 MB | 120 MB | 570 MB |
+| users | 50K | 12 MB | 8 MB | 20 MB |
+```
+
+Flag tables where index size is disproportionately large relative to data (possible unused indexes) or tables with many rows but no indexes (check with top queries).
+
+### 12. Active Queries
+
+Show if any non-Sleep, non-Daemon processes are running:
+
+```
+| User | Database | Command | Time (s) | Query |
+|------|----------|---------|----------|-------|
+| app | mydb | Query | 45 | SELECT ... |
+```
+
+Long-running queries (> 30s) warrant investigation. Cross-reference with lock waits — a long query may be holding locks that block others.
+
+## MySQL Performance Patterns
+
+**Buffer Pool Starvation Pattern:**
+- Hit ratio < 99% + pool usage > 95% = buffer pool too small for working set
+- High `Innodb_data_reads` confirms disk I/O from cache misses
+- Fix: increase `innodb_buffer_pool_size` (target 70-80% of available RAM)
+
+**Query Inefficiency Pattern:**
+- Table scan ratio > 50% = most reads are full scans, missing indexes
+- `Select_full_join` > 0 = joins without indexes, extremely expensive
+- Temp tables to disk > 10% = sorts/groups exceeding `tmp_table_size`
+- Top queries with `no_index_used > 0` = specific queries needing indexes
+
+**Lock Contention Pattern:**
+- `row_lock_waits` high + `row_lock_time` high = write contention
+- Table lock contention > 1% = may have MyISAM tables or DDL locks
+- Long-running queries in processlist holding locks
+
+**Connection Pattern:**
+- `connection_usage_percent > 70%` = approaching limit
+- `aborted_clients > 0` = connections not being closed properly (app bug or timeout)
+- `aborted_connects > 0` = authentication failures or connection limit hits
+
+## MySQL Thresholds
+
+| Metric | Healthy | Warning | Critical |
+|--------|---------|---------|----------|
+| Buffer pool hit ratio | > 99% | 95-99% | < 95% |
+| Buffer pool usage | < 85% | 85-95% | > 95% |
+| Connection usage | < 70% | 70-90% | > 90% |
+| Temp tables to disk | < 10% | 10-25% | > 25% |
+| Table scan ratio | < 50% | 50-75% | > 75% |
+| Table lock contention | < 1% | 1-5% | > 5% |
+| Full joins | 0 | 1-100 | > 100 |
+| Sort merge passes | 0 | > 0 | — |
+
+## MySQL Tuning Knowledge
+
+| Parameter | Default | Target | What It Does |
+|-----------|---------|--------|--------------|
+| `innodb_buffer_pool_size` | 128MB | 70-80% RAM | InnoDB's main cache. Equivalent to PostgreSQL's shared_buffers but should be much larger (70-80% vs 25%). |
+| `max_connections` | 151 | Based on load | Each connection uses memory. Over-provisioning wastes RAM. |
+| `tmp_table_size` / `max_heap_table_size` | 16MB | 64-256MB | Max size for in-memory temp tables. Larger = fewer disk temp tables. Both must be set together. |
+| `sort_buffer_size` | 256KB | 1-4MB | Per-connection sort buffer. Too large wastes memory (multiplied by connections). |
+| `long_query_time` | 10s | 1-2s | Threshold for slow query log. Lower = more visibility but more log volume. |
+| `table_open_cache` | 4000 | Based on tables | Number of open tables cached. Increase if `Opened_tables` grows rapidly. |
+
+## MySQL-Specific Notes
+
+- **`performance_schema=0` in start command** disables query-level metrics. This is the default on Railway. Note it when detected but do not recommend enabling it without caveats — it adds ~400MB+ memory overhead and is only practical on larger instances (2GB+ RAM).
+- **`disable-log-bin` in start command** means no binary logging — point-in-time recovery is not possible. Note if relevant.
+- **`innodb-use-native-aio=0`** is common on Railway (container filesystem limitation). Not a concern.
+- **Cumulative counters**: All SHOW GLOBAL STATUS values are cumulative since server start. Use uptime to compute rates (e.g., questions/uptime = queries per second).
+
+## Infrastructure (7d + 24h)
+
+Show both windows side by side to compare trends:
+
+**7-Day Trends**
+| Metric | Current | Avg | Min | Max | Trend |
+|--------|---------|-----|-----|-----|-------|
+| CPU | 0.03 vCPU | 0.02 | 0.00 | 0.15 | stable |
+| Memory | 480 MB | 460 MB | 420 MB | 510 MB | stable |
+| Disk | 2.8 GB | 2.7 GB | 2.6 GB | 2.9 GB | increasing (+8%) |
+
+**Last 24 Hours**
+| Metric | Current | Avg | Min | Max | Trend |
+|--------|---------|-----|-----|-----|-------|
+| CPU | 0.05 vCPU | 0.03 | 0.00 | 0.15 | stable |
+| Memory | 480 MB | 465 MB | 450 MB | 510 MB | stable |
+| Disk | 2.8 GB | 2.78 GB | 2.75 GB | 2.81 GB | stable |
+
+Compare windows to distinguish sustained vs transient trends.
+
+Do NOT show cpu_limit/memory_limit columns or utilization %. Railway auto-scales — these limits are just the ceiling. See [analyze-db.md](analyze-db.md) autoscale rules.
+
+## Validated against
+
+- MySQL SHOW GLOBAL STATUS, SHOW VARIABLES, information_schema, performance_schema