@synapta/skills 0.1.1 → 0.2.0

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

@@ -0,0 +1,208 @@
+# Redis Analysis
+
+This reference covers Redis-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 (`INFO ALL`):**
+- **Overview:** version, uptime, connected/blocked clients, rejected connections
+- **Memory:** used/RSS/peak memory, fragmentation ratio, maxmemory, eviction policy
+- **Throughput:** ops/sec, total commands processed, total connections
+- **Cache Performance:** keyspace hits/misses, hit rate, expired/evicted keys
+- **Persistence:** RDB last save time/status, AOF enabled/status
+- **Command Stats:** per-command call count, avg latency, total time (sorted by calls)
+- **Keyspace:** per-database key count, expires, avg TTL
+- **Slow Log:** count via `SLOWLOG LEN` + actual entries via `SLOWLOG GET 20` (command, duration, timestamp)
+- **Biggest Keys:** via `redis-cli --bigkeys` — runs **remotely over SSH** on the Railway service, not locally
+
+**Via Railway API:** Same infrastructure metrics (disk, CPU, memory, network with **7d and 24h trends**).
+
+## Presentation Template
+
+Present Redis analysis using grouped stat cards that mirror the sections below. Each section is a labeled group with key-value stat cards. Flag values with status indicators (healthy/warning/critical) using the thresholds table.
+
+### Full Report (SSH + Metrics + Logs all succeeded)
+
+**Overview**
+| Version | Uptime | Connected Clients | Blocked Clients | Rejected Connections | Total Keys |
+|---------|--------|-------------------|-----------------|----------------------|------------|
+| 7.2.4 | 14d 6h | 23 | 0 | 0 | 48,291 |
+
+Flag: blocked clients > 0 = warning, rejected connections > 0 = critical.
+
+**Memory**
+| Used Memory | RSS Memory | Peak Memory | Fragmentation Ratio | Max Memory | Eviction Policy |
+|-------------|------------|-------------|---------------------|------------|-----------------|
+| 12.4 MB | 18.2 MB | 15.1 MB | 1.47 | Unlimited | noeviction |
+
+Flag: fragmentation > 1.5 = warning, > 2.0 or < 1.0 = critical. Evicted keys > 0 with noeviction = problem.
+
+**Throughput**
+| Ops/sec | Total Commands | Total Connections | Slow Log Entries |
+|---------|----------------|-------------------|------------------|
+| 1,240 | 8.4M | 12,491 | 3 |
+
+Flag: slow log > 100 = warning.
+
+**Cache Performance**
+| Hit Rate | Hits | Misses | Expired Keys | Evicted Keys |
+|----------|------|--------|--------------|--------------|
+| 97.2% | 6.1M | 178K | 892K | 0 |
+
+Flag: hit rate >= 95% = healthy, 80-95% = warning, < 80% = critical. Evicted > 0 = warning.
+
+**Persistence**
+| RDB Last Save | RDB Status | AOF Enabled | AOF Rewrite Status |
+|---------------|------------|-------------|-------------------|
+| 2 min ago | ok | Yes | ok |
+
+Flag: RDB status != ok = critical. AOF rewrite status != ok = critical.
+
+**Command Stats** (top 20 by calls)
+| Command | Calls | Avg Latency | Total Time |
+|---------|-------|-------------|------------|
+| GET | 4.2M | 3.1µs | 13.0s |
+| SET | 2.1M | 4.8µs | 10.1s |
+| HGET | 890K | 5.2µs | 4.6s |
+| EXPIRE | 620K | 2.1µs | 1.3s |
+
+**Slow Log Entries** (if collected — up to 20 most recent)
+| # | Timestamp | Duration | Command |
+|---|-----------|----------|---------|
+| 1 | 2m ago | 12.3ms | GET user:session:abc123... |
+| 2 | 5m ago | 10.1ms | GET cache:render:page/home... |
+| 3 | 12m ago | 8.7ms | HGETALL product:catalog:main |
+
+Analysis: correlate slow commands with command stats and big keys. If slowlog shows GET and bigkeys shows large strings, the diagnosis is "large values causing high GET latency" — confirmed without user intervention.
+
+**Biggest Keys** (if collected — one per type)
+| Type | Key | Size/Count |
+|------|-----|------------|
+| string | cache:render:page/dashboard | 2.1 MB |
+| hash | user:sessions | 14,291 fields |
+| list | queue:notifications | 8,402 items |
+
+Analysis: large keys cause latency spikes on read/write/delete. Cross-reference with slowlog — if the slow commands target these keys, that's the root cause. If bigkeys shows nothing large (all < 1KB), latency issues are likely volume-driven, not value-size-driven.
+
+**Keyspace**
+| Database | Keys | Expires | Avg TTL |
+|----------|------|---------|---------|
+| db0 | 48,291 | 31,204 | 2.4h |
+
+**Infrastructure (7d + 24h)** — show both windows so trends can be compared:
+
+**7-Day Trends**
+| Metric | Current | Avg | Min | Max | Trend |
+|--------|---------|-----|-----|-----|-------|
+| CPU | 0.01 vCPU | 0.01 | 0.00 | 0.10 | stable |
+| Memory | 70 MB | 40 MB | 30 MB | 90 MB | stable |
+| Disk | 1.1 GB | 1.11 GB | 1.07 GB | 1.16 GB | stable |
+
+**Last 24 Hours**
+| Metric | Current | Avg | Min | Max | Trend |
+|--------|---------|-----|-----|-----|-------|
+| CPU | 0.01 vCPU | 0.01 | 0.00 | 0.07 | stable |
+| Memory | 70 MB | 55 MB | 30 MB | 90 MB | increasing (+58%) |
+| Disk | 1.1 GB | 1.11 GB | 1.07 GB | 1.16 GB | stable |
+
+Compare: "Memory increasing in 24h but stable over 7d → temporary spike, not a sustained trend."
+
+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.
+
+### Partial Report (Introspection failed, only Metrics + Logs)
+
+When introspection fails, you have NO Redis INFO data — all overview, memory, throughput, cache, persistence, command stats, and keyspace fields will be null/empty.
+
+**NEVER suggest running `redis-cli` without pointing to the remote Railway service host.** There is no local Redis instance — all redis-cli commands must target the Railway service. If you cannot connect, the fix is to restore remote access (see `analyze-db.md`), not to run commands locally.
+
+**You MUST:**
+1. State clearly: "Redis introspection failed — could not connect to the service"
+2. Show collection status errors
+3. Show ONLY infrastructure metrics and log analysis — do not show empty stat card sections
+4. Do NOT produce recommendations based on null Redis metrics
+
+**Show the infrastructure table** (same as full report).
+
+**Analyze logs thoroughly:**
+- AOF rewrite frequency and growth % triggers
+- fsync warnings ("disk is busy?")
+- OOM warnings
+- Connection errors
+- Startup/restart events (note these are normal during deploys)
+- Summarize with counts: "Analyzed 1000 lines: 18 AOF rewrites, 1 fsync warning, 0 errors"
+
+**State what you cannot determine** without SSH:
+- Connection health (clients, blocked, rejected)
+- Memory usage and fragmentation
+- Cache hit rate
+- Eviction status
+- Command workload profile
+- Keyspace composition
+- Slow log entries and actual slow commands
+- Biggest keys per type
+
+## Redis Performance Patterns
+
+**Memory Fragmentation Pattern:**
+- `mem_fragmentation_ratio > 1.5` = memory is fragmented, RSS much higher than used
+- Caused by frequent small key deletions creating memory holes
+- Fix: restart Redis, or enable `activedefrag yes` (Redis 4.0+)
+- Ratio < 1.0 means Redis is using swap — critical performance issue
+
+**Cache Thrashing Pattern:**
+- Hit rate < 80% + evicted keys > 0 = working set exceeds maxmemory
+- Check maxmemory_policy — `noeviction` will reject writes, `allkeys-lru` will evict
+- If maxmemory is 0 (unlimited), Redis will consume all RAM until OOM killed
+
+**Connection Rejection Pattern:**
+- rejected_connections > 0 = maxclients limit hit
+- Check connected_clients vs maxclients default (10,000)
+- Blocked clients = operations waiting on BLPOP/BRPOP/WAIT
+
+**Persistence Risk Pattern:**
+- RDB last save failed + no AOF = data loss risk on restart
+- Check disk space if saves are failing
+- Long time since last save = more data at risk
+
+**AOF Rewrite Churn Pattern:**
+- Frequent AOF rewrites (every 1-2 hours) with high growth % triggers (100-800%)
+- Indicates high write-to-data-size ratio — small dataset with heavy writes
+- Check Fork CoW size to gauge actual data size vs AOF overhead
+- If rewrites are fast (<1s) and CoW is small (<10 MB), this is noisy but harmless
+- If rewrites are slow or CoW is large, investigate write patterns
+
+**Disk Sawtooth Pattern:**
+- Disk usage oscillating in a regular pattern = AOF growing between rewrites, then compacting
+- Normal behavior — the baseline is volume overhead + AOF base file
+- If the amplitude is growing over time, data size is increasing
+
+## Redis Thresholds
+
+| Metric | Healthy | Warning | Critical |
+|--------|---------|---------|----------|
+| Hit rate | >95% | 80-95% | <80% |
+| Fragmentation ratio | 1.0-1.5 | 1.5-2.0 | >2.0 or <1.0 |
+| Evicted keys | 0 | >0 | Growing rapidly |
+| Blocked clients | 0 | 1-5 | >5 |
+| Connected clients | <80% maxclients | 80-90% | >90% |
+
+## Redis Command Stats Analysis
+
+The top commands by call count reveal the workload pattern:
+- **GET/SET dominant** = simple key-value cache
+- **HGET/HSET dominant** = hash-based data model (sessions, objects)
+- **LPUSH/RPOP dominant** = queue pattern
+- **High KEYS/SCAN** = application iterating keys (potential performance issue at scale)
+- **High latency on simple commands** (>100µs for GET) = memory pressure or CPU saturation
+
+## Redis Autoscale Note
+
+See [analyze-db.md](analyze-db.md) for full autoscale rules. For Redis specifically:
+- If `maxmemory` is set, compare it against actual memory usage — not the Railway memory limit.
+- If `maxmemory` is 0 (unlimited), Redis will grow until the OS kills it. This is the default Railway config and works fine with autoscaling — Redis uses what it needs and Railway scales the container.
+- Do NOT recommend setting maxmemory to a fraction of the Railway memory limit — the limit is the autoscale ceiling, not fixed allocation.
+
+## Validated against
+
+- Redis INFO command, SLOWLOG LEN, SLOWLOG GET, and --bigkeys

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

@@ -0,0 +1,344 @@
+# Database Analysis
+
+## Your Role
+
+You are a database performance expert. The script collects raw data - your job is to **think deeply** about what you see, identify root causes, correlate symptoms, and explain the "why" behind problems.
+
+**Don't just report metrics. Analyze them.**
+
+## Context Resolution
+
+The user's request is the source of truth. Use this decision table:
+
+| What the user provided | Action |
+|------------------------|--------|
+| Railway URL | Extract IDs directly from the URL — do NOT run `railway status --json` |
+| Service name + environment name | Proceed — intent is clear. Resolve IDs via API. |
+| Service name only (no environment) | Find the service by name via API. If multiple matches exist across projects, ask: "Which project do you mean?" Otherwise confirm: "Do you mean `<service>` in `<project>` / `<env>`?" — only proceed on confirmation |
+| Raw UUID(s) | Resolve to human-readable names via API, then confirm before running |
+| Vague request ("analyze my database", "check postgres") | Run `railway status --json` to see what's linked. If it's a database service, confirm: "Do you mean `<service>` in `<project>` / `<env>`?". If it's not a database service or nothing is linked, ask: "Which service and environment should I analyze?" |
+| No context at all | List workspaces (`railway whoami --json`), then projects (`railway project list --json`), then environments and services for the chosen project, narrowing down until you have a specific service and environment |
+
+`railway status --json` is a hint to form a specific question, not a trigger to act without confirmation.
+
+**When the user provides a Railway URL**, extract IDs directly from it:
+
+```
+https://railway.com/project/<PROJECT_ID>/service/<SERVICE_ID>?environmentId=<ENV_ID>
+https://railway.com/project/<PROJECT_ID>/service/<SERVICE_ID>/database?environmentId=<ENV_ID>
+```
+
+Then query the API for the service name and database type in a **single call**:
+
+```bash
+scripts/railway-api.sh \
+  'query getServiceAndConfig($serviceId: String!, $environmentId: String!) {
+    service(id: $serviceId) { name }
+    environment(id: $environmentId) {
+      config(decryptVariables: false)
+    }
+  }' \
+  '{"serviceId": "<SERVICE_ID>", "environmentId": "<ENV_ID>"}'
+```
+
+From the response, get:
+- **Service name**: `data.service.name`
+- **Database image**: `data.environment.config.services.<SERVICE_ID>.source.image`
+
+Then match the image to the database type:
+
+| Image pattern | Database Type |
+|--------------|---------------|
+| `postgres*`, `ghcr.io/railway/postgres*` | PostgreSQL |
+| `mysql*`, `ghcr.io/railway/mysql*` | MySQL |
+| `redis*`, `ghcr.io/railway/redis*`, `railwayapp/redis*` | Redis |
+| `mongo*`, `ghcr.io/railway/mongo*` | MongoDB |
+
+**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 \
+  'query getEnvs($id: String!) { project(id: $id) { environments { edges { node { id name } } } } }' \
+  '{"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.
+
+## Database Type Detection and Script Selection
+
+| Database Type | Script |
+|---------------|--------|
+| PostgreSQL | `scripts/analyze-postgres.py` |
+| MySQL | `scripts/analyze-mysql.py` |
+| Redis | `scripts/analyze-redis.py` |
+| MongoDB | `scripts/analyze-mongo.py` |
+
+**All scripts share the same CLI interface** (use the script name from the table above):
+```bash
+python3 scripts/analyze-<script>.py \
+  --service <name> \
+  --json \
+  --project-id <project-id> \
+  --environment-id <env-id> \
+  --service-id <service-id>
+```
+
+Common options across all scripts:
+- `--json` — JSON output for programmatic processing
+- `--quiet` — Suppress progress messages
+- `--skip-logs` — Skip log collection
+- `--metrics-hours <N>` — Hours of metrics history (default: 24, max: 168)
+- `--step <step>` — Debug individual collection steps (ssh-test, query, logs, metrics)
+
+## Before You Analyze: Check Collection Status
+
+**ALWAYS check `collection_status` and `errors[]` FIRST before interpreting any data.** The script collects data from multiple independent sources. Any of them can fail.
+
+### Decision Table
+
+| database_query | metrics_api | logs_api | Report Type |
+|---------------|-------------|----------|-------------|
+| success | success | success | Full analysis — use all sections |
+| success | error | success | Full analysis — note missing infrastructure metrics |
+| **error** | success | success | **Partial report** — only infrastructure metrics + log analysis. NO performance conclusions. |
+| **error** | error | success | **Logs-only report** — state what logs show, note everything else failed. NO diagnosis. |
+| **error** | **error** | **error** | **Collection failure** — report the errors, do not analyze. |
+
+### When database_query failed — SSH key errors
+
+If the error contains `"No SSH keys found"` or `"SSH key registration required"`, handle it proactively — don't just tell the user to fix it themselves.
+
+**If error contains `"Key found but not registered"` or `"No SSH keys found"`:**
+
+Run these two commands to understand what's available:
+
+```bash
+railway ssh keys          # list keys already registered with Railway
+ls ~/.ssh/*.pub 2>/dev/null  # list local public keys
+```
+
+Then present the user with their options and ask which to use:
+
+```
+SSH introspection needs a registered key. Here's what I found:
+
+Registered with Railway: <list from `railway ssh keys`, or "none">
+Local keys available:    <list from ~/.ssh/*.pub, or "none">
+
+Options:
+  1. Register a local key — `railway ssh keys add` (uses your default key)
+  2. Import from GitHub  — `railway ssh keys github`
+  3. Generate a new key  — `ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_railway`
+
+Which would you like to do?
+```
+
+Once the user chooses and the key is registered, re-run the full analysis.
+
+### When database_query failed — CLI outdated or missing
+
+If the error contains `"--native SSH flag is not supported"` or `"Railway CLI not found"`, the script detected an unrecoverable CLI problem. Tell the user directly:
+
+- **Outdated CLI:** "Your Railway CLI doesn't support native SSH. Update it: `npm i -g @railway/cli@latest` or `brew upgrade railway`"
+- **Missing CLI:** "Railway CLI not installed. Install it: `npm i -g @railway/cli` or `brew install railway`"
+
+Then ask if they'd like to proceed with a partial analysis (metrics + logs only) while they update, or wait until the CLI is fixed and re-run the full analysis.
+
+### When database_query failed — other SSH errors
+
+This means SSH could not reach the database or the query failed. You have NO connection stats, NO cache hit ratios, NO vacuum health, NO query performance data. All those fields will be null/empty.
+
+**You MUST:**
+1. State clearly: "Database introspection failed — SSH could not connect to the service"
+2. Show the `collection_status` errors
+3. Show only the data that DID succeed (metrics, logs)
+4. Do NOT produce recommendations based on null metrics
+5. Do NOT diagnose performance issues from logs alone
+
+**Partial report template:**
+```
+Service: <name>
+Status: Data collection partially failed
+
+## Collection Status
+| Source | Status |
+|--------|--------|
+| Database Query (SSH) | ERROR: <error from collection_status> |
+| Metrics API | <status> |
+| Logs API | <status> |
+
+## Available Data
+<Show metrics and log summary from sources that succeeded>
+
+## What We Cannot Determine
+<List what requires the database query: connection health, cache performance, vacuum health, query analysis, etc.>
+```
+
+## Output Structure: Data First, Actions Second
+
+**Always present information in this order:**
+
+### 1. Context Header
+```
+Service: <name> (<project> <environment>)
+Status: <deployment health>, <RAM>, <disk used>
+```
+
+### 2. Consolidated Data Tables
+
+Before any analysis, show the raw metrics in tables so the user sees their actual state. The DB-specific reference defines exactly which tables to show for each database type — present the relevant health sections first, then connections, then query performance.
+
+**Logs & Active Issues:**
+- Parse the `recent_logs` array (1000 lines of raw logs) - don't just check if empty
+- Summarize: "Analyzed 1000 log lines: 3 errors (connection timeouts), 0 critical issues"
+- Show specific concerning log entries if found
+- **Categorize log entries**: group by type (errors, warnings, connection events, replication, crashes/restarts)
+- **Count patterns**: note if a single type dominates the log output
+- **Quote actual log lines** for errors — don't just say "errors found", show the exact message so the user can search their codebase
+
+### 3. Analysis
+
+After showing the data, explain the chain of causation. Connect the dots between tables.
+
+### 4. Recommended Actions
+
+Group by urgency. For databases that support configuration changes without restart vs those that require one, call that out explicitly.
+
+### 5. Expected Outcomes
+
+What metrics should change after fixes.
+
+---
+
+**Why this order matters:**
+- Users can verify the data matches their understanding
+- They see the full picture before being told what to do
+- Actions have context - they know WHY each fix is recommended
+- No valuable data is hidden in prose or omitted
+
+## CRITICAL: Use the Actual Data
+
+**NEVER fabricate or assume values.** The script outputs JSON with exact numbers. Before stating any metric:
+
+1. **Read the actual JSON output** - Don't truncate or skim
+2. **Quote the exact values** - e.g., `"max": 5000` not "100"
+3. **Investigate outliers** - Dig into any field that seems unusually high or low
+
+Common errors to avoid (all database types):
+- **Not parsing `recent_logs`** - always analyze the raw log lines, don't just report "no errors"
+- **Diagnosing performance issues from logs when all metrics are null** — logs show what happened, not how the database is performing
+- **Treating startup/restart log entries as evidence of failure** — databases restart for many normal reasons (deploys, config changes, scaling)
+- **Producing recommendations when all database metrics are null** — if `collection_status.database_query` is "error", you have no basis for tuning advice
+
+See the DB-specific reference for additional errors to avoid per database type.
+
+## Running the Analysis
+
+Pass project, environment, and service IDs directly — no `railway link` needed:
+
+```bash
+# From plugins/railway/skills/use-railway directory:
+# Use the script name from the "Database Type Detection" table above
+python3 scripts/analyze-postgres.py --service <name> --json \
+  --project-id <project-id> --environment-id <env-id> --service-id <service-id>
+```
+
+All three IDs come from the URL (see "Context: URL First" above). The service name comes from the API query.
+
+**Options:**
+- `--metrics-hours <N>` — Hours of metrics history to fetch (default: 24, max: 168). Use `--metrics-hours 168` for 7-day trends, `--metrics-hours 1` for recent snapshot.
+
+**SSH retry:** The script automatically retries SSH connectivity up to 3 times with increasing timeouts (30s, 60s, 90s). Each individual SSH command (database query, slowlog, bigkeys, etc.) also retries up to 3 times on failure — covering transient errors like `exec request failed on channel 0`. Progress is logged to stderr.
+
+**Output:** Progress messages go to stderr. JSON results go to stdout. Do not redirect or pipe stderr — just run the command as-is and read the full output.
+
+### Resolving environment by name
+
+If the URL has no `environmentId` 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`.
+
+### Debugging individual steps
+
+```bash
+# Use the script name from the "Database Type Detection" table above
+python3 scripts/analyze-postgres.py --service <name> \
+  --project-id <pid> --environment-id <eid> --service-id <sid> \
+  --step ssh-test    # Test SSH connectivity
+  --step query       # Run only the database query
+  --step metrics     # Fetch only API metrics
+  --step logs        # Fetch only logs
+```
+
+## Database-Specific References
+
+After running the script and checking collection status, load the reference for the specific database type:
+
+| Database | Reference | What It Covers |
+|----------|-----------|----------------|
+| PostgreSQL | [analyze-db-postgres.md](analyze-db-postgres.md) | What psql collects, log analysis checklist, tuning formulas, vacuum priority, pg_stat_statements, applying fixes |
+| MySQL | [analyze-db-mysql.md](analyze-db-mysql.md) | All 12 metric sections (overview, query throughput, InnoDB, efficiency, buffer pool, I/O, network, locks, cache, top queries, tables, active queries), patterns, tuning |
+| Redis | [analyze-db-redis.md](analyze-db-redis.md) | INFO ALL metrics, memory fragmentation, cache thrashing, persistence, command stats |
+| MongoDB | [analyze-db-mongo.md](analyze-db-mongo.md) | serverStatus, WiredTiger cache, query efficiency, connection saturation, oplog |
+
+**Always load the DB-specific reference** — it contains the metric sections, thresholds, and tuning knowledge needed for proper analysis.
+
+## Infrastructure Metrics (All Database Types)
+
+All scripts collect the same infrastructure metrics via Railway API:
+
+**Metrics History (`metrics_history`):**
+The script fetches **7 days** (168 hours) of time-series data from Railway's metrics API by default and produces **two analysis windows**:
+
+```json
+{
+  "metrics_history": {
+    "windows": {
+      "7d": { "window_hours": 168, "metrics": { "cpu": {...}, "memory": {...}, ... } },
+      "24h": { "window_hours": 24, "metrics": { "cpu": {...}, "memory": {...}, ... } }
+    }
+  }
+}
+```
+
+Each window independently computes:
+- **Summary stats**: current, min, max, avg for each metric
+- **Trend analysis**: compares first-quarter avg to last-quarter avg — reports direction (increasing/decreasing/stable) and % change
+- **Spike detection**: flags values > avg + 2*stddev with timestamps of peaks
+- **Downsampled series**: ~48 data points per window
+
+Available metrics: CPU, memory (with limits), disk, network RX/TX.
+
+**Comparing windows reveals whether a trend is new or sustained:**
+- "Memory increasing in 24h but stable over 7d" → temporary spike, likely a batch job
+- "Memory increasing in both 24h AND 7d" → sustained growth, may need investigation
+- "CPU spike in 24h, no spikes in 7d" → new issue
+- "Disk growing over 7d" → data accumulation trend
+
+Use `--metrics-hours N` to change the long window (default: 168, max: 168). The 24h window is always produced when the long window is > 24h.
+
+### Railway auto-scales vertically
+
+Railway services auto-scale CPU, RAM, and disk based on actual usage. Users do NOT pick or control resource sizes. The `cpu_limit` and `memory_limit` values from metrics are the **autoscale ceiling** (typically 32 vCPU / 32 GB), not user-provisioned allocations. Users are billed for actual usage, not the ceiling.
+
+**Rules for ALL database types:**
+- **Never say "right-size the instance"** or suggest reducing CPU/RAM — it's not a user action.
+- **Never flag low utilization % against the limit as waste** — a service showing 0.01 vCPU / 70 MB actual usage against a 32 vCPU / 32 GB ceiling is normal, not over-provisioned.
+- **Disk does NOT auto-scale** — Railway volumes have a fixed capacity. Paid users (Hobby and Pro) can expand them live without downtime, but it requires a manual resize. Flag high disk utilization as actionable. Users are billed for actual disk utilization, not the full volume size.
+- **Focus on actual usage values**, not the ratio to limits. Analyze whether 70 MB of memory is healthy for this workload — don't compare it to the 32 GB ceiling.
+- When tuning database parameters (shared_buffers, innodb_buffer_pool_size, maxmemory, etc.), base recommendations on the **current actual RAM** from `metrics_history.memory`, not the limit.
+
+## Validated against
+
+- 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)