rsc-universal 0.1.1

package/skills/monitoring/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: monitoring
+description: "Use when setting up uptime/health monitoring, alerts, or on-call basics for a service already in production and you need to know it's down before customers do. Triggers: 'set up uptime monitoring', 'alert me if the site goes down', 'add /healthz and /readyz and probe them', 'we get paged at 3am for CPU spikes that self-resolve — fix alert fatigue', 'alert on our SLO error-budget burn rate not raw error count', 'an untested alert isn't an alert', 'create an on-call rotation with escalation and a status page', 'monta monitorització d'uptime i avísa'm si l'API torna 5xx', 'avísame si la web se cae'. NOT instrumenting logs/metrics/traces or wiring OpenTelemetry (that is observability)."
+tags: [monitoring, uptime, alerting, on-call, sre]
+recommends: [observability, deployment, error-handling, domains-dns, scaling]
+origin: risco
+---
+
+# Monitoring
+
+You are wiring up the *outside* view of a service that already shipped: is it alive, is it fast, and when it breaks, does exactly one human get exactly one actionable page. This skill emits a concrete setup — a checker config, a health-endpoint contract, symptom-based alert rules, and an on-call rotation. Not telemetry instrumentation (that is `../observability/SKILL.md`), not the release-gating healthcheck (that is `../deployment/SKILL.md`).
+
+## The one rule
+
+**A page is justified only when there is real user impact AND a human action the system can't take itself.** Everything below descends from this. Internalize the three tiers:
+
+- **Page** (wake someone): users are hurting now and a human must intervene. Checkout returns 5xx. Site unreachable. Error budget burning fast.
+- **Ticket** (look during business hours): degraded but not bleeding. Slow-burn budget use, cert expiring in 14 days.
+- **Dashboard-only** (don't notify): CPU at 80%, a single retry, a transient blip the system already healed.
+
+If an alert doesn't map to an immediate human action, it is not a page — it's noise, and noise trains people to ignore the one page that matters.
+
+## The 4-layer stack
+
+Don't skip layers and don't collapse them — each answers a different question.
+
+| Layer | Answers | Built with | Fires when |
+|---|---|---|---|
+| 1. External uptime probe | "Is it reachable from the outside?" | Uptime Kuma / UptimeRobot / Better Stack | URL down, TLS broken, p95 latency over budget |
+| 2. Health endpoints | "Is the process alive, and are its deps reachable?" | `/livez` + `/readyz` on the service | liveness fails → restart; readiness fails → pull from rotation |
+| 3. SLO burn-rate alert | "Are we spending the error budget too fast?" | Prometheus/Grafana/Better Stack rule | multi-window burn rate exceeds threshold |
+| 4. On-call escalation | "Who acts, and who's the backup?" | PagerDuty / incident.io / Better Stack | a page from layers 1–3 routes + escalates |
+
+Layer 1 catches "the whole thing is gone." Layer 2 catches "a dependency died" before users do. Layer 3 catches "we're degrading faster than we can afford." Layer 4 makes sure a human shows up.
+
+## Pick a tool
+
+Decide by budget, team size, and self-host appetite. Pricing as of 2026-06.
+
+| Tool | Free tier | Check interval | Best for | Paid from |
+|---|---|---|---|---|
+| **Uptime Kuma 2.1.3** | Fully free, self-hosted | down to ~20s | full control, you have a VPS | $0 (you pay the box) |
+| **UptimeRobot** | 50 monitors @ 5-min, 1 status page | 5-min free / 1-min paid | no infra, want managed | $7/mo |
+| **Better Stack** | 10 monitors + incidents + logs | 30s | incident mgmt + on-call in one | $24/mo |
+| **Pingdom** | none | sub-minute | enterprise synthetic + RUM | $15/mo |
+
+Default: **Uptime Kuma** if you already run a VPS (1 GB box is comfortable; needs ~400 MB RAM), **UptimeRobot** free tier if you don't want infra. Kuma 2.1 added Globalping worldwide probe locations (so you test from regions, not just your one box) and built-in domain-expiry monitors. Concrete docker-compose and notification wiring live in `references/tool-setup.md`.
+
+## Health endpoints done right
+
+**Split liveness from readiness — they trigger different machine actions.**
+
+- `/livez` (liveness): is the *process* healthy? If it fails, the orchestrator **restarts** the container. Keep it dumb: just "am I running and not deadlocked." Never check the database here.
+- `/readyz` (readiness): are *dependencies* reachable so I can serve traffic? If it fails, the orchestrator **pulls this instance from the load-balancer rotation** but does not kill it.
+
+**The cheap-probe rule: a probe runs constantly, so it must be <100ms and must not cascade-check every downstream.** Why: if `/livez` pings the DB and the DB is briefly slow, liveness fails, the container restarts, the restart hammers the recovering DB — a restart loop that turns a 30-second blip into an outage.
+
+```python
+# Bad — one /health that cascades and returns 500 on any hiccup.
+# A slow Redis takes the whole service down and triggers restart loops.
+@app.get("/health")
+def health():
+    db.execute("SELECT 1")          # blocks
+    redis.ping()                    # blocks
+    requests.get(PAYMENTS_URL)      # blocks on a third party!
+    return {"status": "ok"}         # 500 if ANY of these throws
+```
+
+```python
+# Good — split, cheap, correct status codes, small JSON.
+@app.get("/livez")                  # liveness: process only. Restart if this fails.
+def livez():
+    return {"status": "alive"}      # 200, ~1ms, touches nothing downstream
+
+@app.get("/readyz")                 # readiness: deps with short timeouts. Pull from LB if this fails.
+def readyz():
+    checks = {"db": ping(db, timeout=0.2), "cache": ping(redis, timeout=0.1)}
+    ok = all(checks.values())
+    return JSONResponse(
+        {"status": "ready" if ok else "degraded", "checks": checks},
+        status_code=200 if ok else 503,   # 503 so the LB pulls this instance
+    )
+```
+
+Do **not** put a third-party API call in readiness — a payment provider's outage shouldn't pull all your instances from rotation and take you fully down. Degrade that path in code (`../error-handling/SKILL.md`), don't fail-closed on it here. Go and FastAPI handler examples are in `references/tool-setup.md`.
+
+## What to actually monitor
+
+The golden checklist. Monitor the *symptom users feel*, not just that one URL returns 200.
+
+- [ ] **Availability** — the critical endpoint(s) reachable, from multiple regions.
+- [ ] **Latency p95/p99** — averages hide the tail; alert on p95/p99 against a budget, not the mean.
+- [ ] **Error rate** — the 5xx-to-total ratio, because raw 5xx count says nothing without traffic volume.
+- [ ] **SSL cert expiry** — alert at 14 days; an expired cert is a full outage that no app metric catches.
+- [ ] **Domain expiry** — alert at 30 days; a lapsed domain is the most embarrassing avoidable outage.
+- [ ] **The critical user journey** — a synthetic check that does login → core action → result, NOT just `GET /`. The homepage can be 200 while checkout is broken.
+
+The homepage being up tells you almost nothing. Probe the path that makes you money.
+
+## Alerts that don't cry wolf
+
+**Alert on symptoms, not causes.** Page on "checkout error rate >2% for 5 min" (user impact), not on "CPU >80%" (a cause that may be harmless and self-resolving). High CPU with happy users is a dashboard line, not a 3am page.
+
+**Use multi-window, multi-burn-rate for SLO alerts** (Google SRE workbook). Burn rate = how fast you're spending the monthly error budget. Require a long *and* a short window to both fire — the long window says "this is real," the short window says "this is still happening," and together they kill false positives from a single spike.
+
+| Burn rate | Window | Budget spent | Severity | Action |
+|---|---|---|---|---|
+| > 14.4 | 1h (+ 5m short) | 2% in 1h | critical | **page** |
+| > 6 | 6h (+ 30m short) | 5% in 6h | warning | **ticket** |
+| > 1 | 3d (+ 6h short) | 10% in 3d | info | review |
+
+Routing: **critical → page**, **warning → ticket**, **info → dashboard/review**. Dedupe and group related alerts into one incident (10 hosts failing the same check = one page, not ten). Set **maintenance windows** so planned deploys don't page anyone. The full burn-rate math and a copy-paste Prometheus-style rule with a `runbook_url` annotation are in `references/burn-rate-and-oncall.md`.
+
+## On-call basics
+
+- **Rotation**: weekly, with a **primary and a secondary**. One person can't be the single point of failure for the system that catches single points of failure.
+- **Escalation policy**: page primary → if no ack in 5–10 min, page secondary → then the manager. No-ack must always hop; an unacked page is a dropped page.
+- **Runbook per alert**: every alert links to a runbook with five fields — Symptom, Impact, First 3 checks, Mitigation, How to escalate. The person paged at 3am should not have to think from scratch. Template in `references/burn-rate-and-oncall.md`.
+- **Status page + comms**: a public status page (Kuma and Better Stack include one) so customers self-serve "is it you or me," cutting inbound during an incident.
+- **Do NOT start a new on-call on Opsgenie** — Atlassian is retiring it (EOL **2027-04-05**; new sales ended 2025-06-04). **Grafana OnCall OSS was also deprecated** (folded into Grafana Cloud IRM). For a new setup use **PagerDuty, incident.io, Better Stack, or Grafana Cloud IRM**.
+
+## Verify it works
+
+**An untested alert is not an alert.** Before you call monitoring "done," prove the wire end-to-end:
+
+1. Trigger a real synthetic failure (stop the service, or point a monitor at a forced-503 route).
+2. Confirm the page actually lands on a phone — not just "the rule exists in the UI."
+3. Let the ack timeout lapse and confirm escalation hops to the secondary.
+4. Restore, and confirm the resolve/all-clear notification fires too.
+
+`scripts/verify.sh` enforces the *structural* half of this on your config: liveness split from readiness, at least one symptom/burn-rate alert with two windows, a runbook reference on every alert, and a banlist for Opsgenie-as-new-setup and homepage-only monitors. Run it in CI so config drift can't silently re-introduce a noisy or untested setup.
+
+## Anti-patterns
+
+| Bad | Why it bites | Do instead |
+|---|---|---|
+| Monitor only the homepage `/` | `/` is 200 while checkout is broken — you learn from customers | synthetic check of the critical journey |
+| Page on CPU/memory threshold | self-resolves, no user impact → alert fatigue | page on the symptom (error rate, latency, availability) |
+| Alert on cause, not symptom | causes are noisy and ambiguous | alert on what the user feels |
+| Alert with no runbook link | the paged human improvises at 3am | every alert links a 5-field runbook |
+| Single-window threshold "by vibes" | one spike pages; tuned by guesswork | multi-window multi-burn-rate against an SLO |
+| Probe cascades every downstream | one slow dep fails the probe → restart loop | cheap <100ms probe, deps in readiness with timeouts |
+| Liveness checks the database | slow DB → restart loop turns a blip into an outage | liveness = process only; DB lives in readiness |
+| Start new on-call on Opsgenie | EOL 2027-04-05, dead end | PagerDuty / incident.io / Better Stack / Grafana Cloud IRM |
+| No secondary on-call | primary asleep/offline → page dropped | primary + secondary + manager escalation |
+| No status page | inbound floods support during incidents | public status page customers can self-serve |
+| Never tested the alert | "the rule exists" ≠ "the page lands" | trigger a synthetic failure, confirm it pages + escalates |
+| Page on warnings | trains people to ignore pages | warning → ticket; only critical → page |
+
+## References
+
+- `references/tool-setup.md` — Uptime Kuma docker-compose (rootless image, volume, port), HTTP + push-heartbeat + SSL/domain-expiry monitors, a synthetic multi-step journey, notification wiring (ntfy / Slack webhook / PagerDuty integration key), a UptimeRobot/Better Stack monitor JSON shape, and Go + FastAPI health-endpoint handlers.
+- `references/burn-rate-and-oncall.md` — full multi-window multi-burn-rate math, a copy-paste Prometheus-style alert rule with `runbook_url`, severity mapping, a sample escalation-policy YAML, and a fill-in runbook template.
+
+Related: `../observability/SKILL.md` (what the app emits), `../deployment/SKILL.md` (release-gating healthcheck + rollback), `../error-handling/SKILL.md` (degrade in code), `../domains-dns/SKILL.md` (provision certs/DNS), `../scaling/SKILL.md` (survive the load monitoring detected).

package/skills/monitoring/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — monitoring
+
+These cases are run by the repo's eval harness, which loads this skill's `SKILL.md` (description + body) and scores three things with a judge model: that each `should_trigger` prompt selects `monitoring`, that each `should_not_trigger` prompt routes to the named sibling instead (every `route_to` id — `observability`, `error-handling`, `deployment`, `scaling`, `domains-dns` — is a real skill in this catalog), and that a response to the `capability` scenario covers the `must_include` rubric. The rubric is graded on substance, not exact wording: a setup that splits liveness from readiness, picks a concrete dated tool, monitors the critical journey plus cert/domain expiry, alerts on a two-window symptom/burn-rate rule, wires escalation + runbooks, says to test the page end-to-end, and steers clear of Opsgenie for a new setup should pass even if phrased differently. Run them with the standard harness against this directory; there is no special setup beyond the catalog being present.

package/skills/monitoring/evals/cases.yaml

@@ -0,0 +1,47 @@
+skill: monitoring
+
+should_trigger:
+  - prompt: "Set up uptime monitoring and alert me if the site goes down."
+    why: Core uptime trigger — the external probe layer of the stack.
+  - prompt: "Add /healthz and /readyz endpoints and have something probe them."
+    why: Health-endpoint contract; liveness vs readiness split is core to this skill.
+  - prompt: "We get paged at 3am for CPU spikes that self-resolve — fix our alerting."
+    why: Non-obvious. Alert fatigue / symptom-based tuning; the cause-not-symptom anti-pattern.
+  - prompt: "Create an on-call rotation with escalation and a public status page."
+    why: On-call basics — rotation, escalation policy, status page.
+  - prompt: "Alert on our SLO error-budget burn rate instead of raw error count."
+    why: Non-obvious. Multi-window multi-burn-rate alerting is a named technique here.
+  - prompt: "An untested alert isn't an alert — how do I prove my pages actually land?"
+    why: Non-obvious. The verify-it-works section; trigger synthetic failure, confirm page + escalation.
+  - prompt: "Monta monitorització d'uptime i que m'avisi si l'API torna 5xx."
+    why: Catalan trigger for uptime + symptom-based 5xx alerting.
+
+should_not_trigger:
+  - prompt: "Add OpenTelemetry tracing and a metrics dashboard for span latency."
+    route_to: observability
+    why: Instrumentation/telemetry — the inside view of what the app emits, not whether it's alive.
+  - prompt: "Add retry and a circuit breaker so failed calls degrade gracefully."
+    route_to: error-handling
+    why: Handling the failure in code, not detecting and escalating it operationally.
+  - prompt: "Add a HEALTHCHECK to my Dockerfile and a rollback step in CI."
+    route_to: deployment
+    why: Release-gating healthcheck + rollback, not the continuous external probe after release.
+  - prompt: "Our app falls over at 10x traffic — set up autoscaling and load shedding."
+    route_to: scaling
+    why: Capacity/survival, not detection of failure.
+  - prompt: "Renew and provision the SSL cert and fix the DNS records for the domain."
+    route_to: domains-dns
+    why: Cert/DNS provisioning; monitoring only watches expiry, it doesn't provision.
+
+capability:
+  - scenario: >
+      I have a FastAPI service on a Hetzner VPS behind Cloudflare. Set up monitoring,
+      alerts, and on-call so I find out before customers do.
+    must_include:
+      - Splits liveness (/livez, restart-if-fail) from readiness (/readyz, pull-from-rotation-if-fail) and states the cheap-probe rule (<100ms, don't cascade every downstream).
+      - Picks a concrete tool with dated rationale (e.g. Uptime Kuma self-host on the VPS vs UptimeRobot if no infra), not a vague "use a monitor."
+      - Monitors the critical user journey via a synthetic check plus cert and domain expiry, not just GET /.
+      - Defines a symptom/SLO alert with two windows (burn-rate, long + short), not a bare CPU/memory threshold.
+      - Sets up an escalation policy (primary + secondary + manager, ack timeout) and links every alert to a runbook.
+      - Says to test the alert end-to-end (trigger a synthetic failure, confirm the page lands and escalation hops).
+      - Avoids recommending Opsgenie for a new setup (EOL 2027-04-05); suggests PagerDuty / incident.io / Better Stack / Grafana Cloud IRM instead.

package/skills/monitoring/references/burn-rate-and-oncall.md

@@ -0,0 +1,128 @@
+# Burn-rate alerting and on-call
+
+The full math behind the SLO table in SKILL.md, plus copy-paste alert rules, escalation, and a runbook template.
+
+## What "burn rate" means
+
+Pick an SLO, e.g. **99.9% availability over 30 days**. The **error budget** is the allowed bad fraction: `1 - 0.999 = 0.1%` of requests over the month.
+
+**Burn rate = how many times faster than "even" you are spending that budget.**
+
+- Burn rate `1` = you'd exactly exhaust the 30-day budget in 30 days. Fine.
+- Burn rate `14.4` = you'd exhaust the *entire month's* budget in `30d / 14.4 ≈ 2h`. Page now.
+
+Why 14.4: it is the rate that burns **2% of the monthly budget in 1 hour** — the Google SRE workbook's recommended fast-burn page threshold. The other rows: **6×** burns ~5% in 6h (ticket), **1×** burns ~10% in 3d (slow review).
+
+## Why two windows
+
+A single window either pages on a momentary spike (short window alone) or reacts too slowly (long window alone). **Require a long AND a short window to both exceed the burn threshold:**
+
+- The **long window** confirms the burn is sustained ("this is real").
+- The **short window** confirms it's still happening right now ("don't page me for an outage that already ended"). It also gives fast reset once you recover.
+
+This combination is what kills false positives.
+
+## Prometheus-style alert rule
+
+Symptom-based, two windows, with a `runbook_url` annotation. Adjust `job`/`code` to your metric names.
+
+```yaml
+groups:
+  - name: slo-burn-rate
+    rules:
+      # CRITICAL — page. Fast burn: 14.4x over 1h, confirmed by a 5m short window.
+      - alert: CheckoutErrorBudgetFastBurn
+        expr: |
+          (
+            sum(rate(http_requests_total{job="checkout",code=~"5.."}[1h]))
+            / sum(rate(http_requests_total{job="checkout"}[1h]))
+          ) > (14.4 * 0.001)
+          and
+          (
+            sum(rate(http_requests_total{job="checkout",code=~"5.."}[5m]))
+            / sum(rate(http_requests_total{job="checkout"}[5m]))
+          ) > (14.4 * 0.001)
+        labels:
+          severity: critical        # routes to page
+        annotations:
+          summary: "Checkout burning error budget 14.4x (1h+5m)"
+          runbook_url: "https://wiki.example.com/runbooks/checkout-5xx"
+
+      # WARNING — ticket. Slower burn: 6x over 6h, confirmed by a 30m short window.
+      - alert: CheckoutErrorBudgetSlowBurn
+        expr: |
+          (
+            sum(rate(http_requests_total{job="checkout",code=~"5.."}[6h]))
+            / sum(rate(http_requests_total{job="checkout"}[6h]))
+          ) > (6 * 0.001)
+          and
+          (
+            sum(rate(http_requests_total{job="checkout",code=~"5.."}[30m]))
+            / sum(rate(http_requests_total{job="checkout"}[30m]))
+          ) > (6 * 0.001)
+        labels:
+          severity: warning          # routes to ticket
+        annotations:
+          summary: "Checkout slow error-budget burn (6h+30m)"
+          runbook_url: "https://wiki.example.com/runbooks/checkout-5xx"
+```
+
+Note: every alert carries `runbook_url`, and the rule is a *ratio* (symptom), never a bare `cpu`/`memory` threshold.
+
+## Severity → routing
+
+| Label | Where it goes | Who acts | When |
+|---|---|---|---|
+| `critical` | PagerDuty/Better Stack page → escalation policy | on-call, now | immediately, any hour |
+| `warning` | ticket queue / Slack channel | team | next business hours |
+| `info` | dashboard / weekly review | nobody paged | retro |
+
+## Escalation policy (sample)
+
+```yaml
+# Vendor-agnostic shape — maps to PagerDuty / incident.io / Better Stack.
+escalation_policy:
+  name: checkout-oncall
+  on_call:
+    primary:   "@oncall-primary"     # weekly rotation
+    secondary: "@oncall-secondary"   # weekly rotation, offset
+  steps:
+    - notify: primary
+      ack_timeout_minutes: 10        # no ack -> escalate
+    - notify: secondary
+      ack_timeout_minutes: 10
+    - notify: "@eng-manager"
+  repeat_until_acked: true
+  resolve_notifies: true             # send the all-clear too
+# Do NOT build this on Opsgenie (EOL 2027-04-05) or Grafana OnCall OSS (deprecated).
+```
+
+## Runbook template
+
+Every alert's `runbook_url` points to one of these. Fill it in before the alert ships, not at 3am.
+
+```markdown
+# Runbook: <alert name>
+
+## Symptom
+What the alert literally measures (e.g. "checkout 5xx ratio > 14.4x SLO burn, 1h+5m").
+
+## Impact
+What the user experiences (e.g. "checkout failing → lost revenue, ~X orders/min").
+
+## First 3 checks
+1. Dashboard link: <url> — is it errors or latency?
+2. Recent deploys: <link> — did we ship in the last 30 min? Consider rollback (see ../deployment/SKILL.md).
+3. Dependency status: DB / cache / payment provider status pages.
+
+## Mitigation
+- Fastest safe action (rollback / feature-flag off / scale out — see ../scaling/SKILL.md).
+- Holding action if root cause unknown (drain region, enable degraded mode).
+
+## Escalation
+- If not mitigated in 15 min, page secondary and open an incident.
+- Post to the public status page; notify #incidents.
+
+## Dashboards
+- <links to the relevant observability dashboards — see ../observability/SKILL.md>
+```

package/skills/monitoring/references/tool-setup.md

@@ -0,0 +1,154 @@
+# Tool setup
+
+Concrete, copy-pasteable configs. Pricing/versions as of 2026-06.
+
+## Uptime Kuma (self-hosted, free)
+
+`docker-compose.yml` — rootless image, persistent volume, single port.
+
+```yaml
+services:
+  uptime-kuma:
+    image: louislam/uptime-kuma:2.1.3-rootless
+    container_name: uptime-kuma
+    restart: unless-stopped
+    volumes:
+      - kuma-data:/app/data
+    ports:
+      - "3001:3001"
+volumes:
+  kuma-data:
+```
+
+```bash
+docker compose up -d
+# open http://your-vps:3001, create the admin user on first load,
+# then put it behind your reverse proxy with TLS (do not expose 3001 raw).
+```
+
+Monitors to add (Kuma calls them "Monitor type"):
+
+- **HTTP(s)** on your critical endpoint — set "Accepted status codes" to `200-299`, interval 60s, retries 3, and enable **Globalping** (Kuma 2.1) to probe from multiple regions instead of just the box.
+- **HTTP(s) – Keyword** to assert a string in the body (e.g. a logged-in marker), so a 200 that renders an error page still alerts.
+- **Push** (heartbeat) for a cron/worker: the job `curl`s a Kuma push URL each run; if the beat is missed, Kuma pages. This catches *silent* batch failures.
+- **TLS expiry**: enable "Certificate Expiry Notification" on the HTTP monitor; notify at 14 days.
+- **Domain expiry**: Kuma 2.1 has a domain-expiry monitor type; notify at 30 days.
+
+```bash
+# Push-heartbeat from a cron job — alert fires if this stops arriving.
+*/5 * * * * /usr/bin/curl -fsS "https://kuma.example.com/api/push/AbC123?status=up&msg=ok" >/dev/null
+```
+
+## Notification wiring
+
+Kuma has 90+ channels; here are the three you actually use.
+
+```bash
+# ntfy — dead-simple push to your phone, self-hostable, free.
+# In Kuma: Settings → Notifications → ntfy. Server https://ntfy.sh, topic = a long random string.
+curl -d "checkout 5xx > 2%" ntfy.sh/your-long-random-topic   # test it lands
+```
+
+```json
+// Slack incoming webhook — paste the webhook URL into Kuma's Slack notification.
+{ "text": "🔴 [PAGE] checkout error rate 4.1% (>2% for 5m) — runbook: https://wiki/runbooks/checkout-5xx" }
+```
+
+```text
+# PagerDuty — use Events API v2. In PagerDuty create a service → integration
+# "Events API v2" → copy the Integration Key (routing key) into Kuma's PagerDuty
+# notification. Critical severity routes to the on-call escalation policy.
+Integration Key: R0UT1NGK3Yxxxxxxxxxxxxxxxxxxxxxxx
+Severity:        critical   # so it pages, not just logs
+```
+
+## Managed alternative — monitor config shape
+
+UptimeRobot / Better Stack store this server-side; the shape you reason about:
+
+```json
+{
+  "type": "http",
+  "url": "https://api.example.com/readyz",
+  "method": "GET",
+  "expected_status": 200,
+  "interval_seconds": 60,
+  "regions": ["eu", "us-east", "ap"],
+  "assertions": [
+    { "type": "status_code", "comparison": "equals", "target": 200 },
+    { "type": "response_time", "comparison": "less_than", "target_ms": 800 },
+    { "type": "body", "comparison": "contains", "target": "\"status\":\"ready\"" }
+  ],
+  "ssl_expiry_alert_days": 14,
+  "domain_expiry_alert_days": 30,
+  "on_failure": { "after_failures": 2, "notify": ["pagerduty-critical"] }
+}
+```
+
+## Synthetic critical-journey check
+
+Not just `GET /` — exercise the path that earns money. Shape of a multi-step synthetic:
+
+```yaml
+# synthetic: login -> add to cart -> checkout. Run every 5 min from 2+ regions.
+name: checkout-journey
+steps:
+  - POST /api/login        { body: { user: "$SYNTH_USER", pass: "$SYNTH_PASS" }, expect: 200 }
+  - POST /api/cart         { body: { sku: "TEST-SKU", qty: 1 }, expect: 200, save: cart_id }
+  - POST /api/checkout     { body: { cart: "$cart_id", token: "tok_test" }, expect: 200 }
+assert:
+  - total_duration_ms < 4000
+on_fail: page   # this is real user impact
+```
+
+## Health-endpoint handlers
+
+### FastAPI (Python)
+
+```python
+from fastapi import FastAPI
+from fastapi.responses import JSONResponse
+
+app = FastAPI()
+
+@app.get("/livez")           # liveness: process only. Orchestrator restarts on fail.
+def livez():
+    return {"status": "alive"}
+
+@app.get("/readyz")          # readiness: deps with short timeouts. LB pulls instance on fail.
+async def readyz():
+    checks = {
+        "db": await ping_db(timeout=0.2),
+        "cache": await ping_cache(timeout=0.1),
+    }
+    ready = all(checks.values())
+    return JSONResponse(
+        {"status": "ready" if ready else "degraded", "checks": checks},
+        status_code=200 if ready else 503,
+    )
+```
+
+### Go
+
+```go
+// Liveness: process only, ~instant. Never touch the DB here.
+http.HandleFunc("/livez", func(w http.ResponseWriter, r *http.Request) {
+    w.Header().Set("Content-Type", "application/json")
+    w.WriteHeader(http.StatusOK)
+    _, _ = w.Write([]byte(`{"status":"alive"}`))
+})
+
+// Readiness: deps with a tight deadline so the probe stays cheap (<100ms).
+http.HandleFunc("/readyz", func(w http.ResponseWriter, r *http.Request) {
+    ctx, cancel := context.WithTimeout(r.Context(), 200*time.Millisecond)
+    defer cancel()
+    w.Header().Set("Content-Type", "application/json")
+    if err := db.PingContext(ctx); err != nil {
+        w.WriteHeader(http.StatusServiceUnavailable) // 503 -> LB pulls this instance
+        _, _ = w.Write([]byte(`{"status":"degraded","checks":{"db":false}}`))
+        return
+    }
+    w.WriteHeader(http.StatusOK)
+    _, _ = w.Write([]byte(`{"status":"ready","checks":{"db":true}}`))
+})
+```

package/skills/monitoring/scripts/verify.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+# verify.sh — monitoring config sanity gate. Read-only. Run inside YOUR project or
+# point it at a monitoring config/spec dir or file. CI runs the same file (parity).
+#
+# Usage:
+#   bash scripts/verify.sh [PATH]    # PATH defaults to "."
+#
+# What it checks, against the load-bearing rules of the monitoring skill:
+#   1. Discover candidate monitoring files (alert rules, health specs, monitor configs).
+#      No candidates -> nothing to gate -> exit 0 (clean target is never a failure).
+#   2. Health endpoints separate liveness from readiness (livez/liveness AND readyz/readiness).
+#   3. At least one alert is symptom/SLO/burn-rate based with TWO windows — FAIL only if
+#      alert rules exist and the ONLY thresholds are bare cpu/memory.
+#   4. Every alert block carries a runbook reference (runbook / runbook_url).
+#   5. Banlist: Opsgenie introduced as a NEW setup; a monitor whose only target is "/".
+#
+# Dependency-light: bash + grep + find only. Portable to macOS bash 3.2 and CI bash 5.
+# Read-only: never writes, never mutates. Exits nonzero only on a real FAIL.
+#
+# Env: NO_COLOR=1 to disable color.
+set -euo pipefail
+
+TARGET="${1:-.}"
+
+if [[ -n "${NO_COLOR:-}" ]]; then YEL=""; GRN=""; RED=""; RST=""
+else YEL=$'\033[33m'; GRN=$'\033[32m'; RED=$'\033[31m'; RST=$'\033[0m'; fi
+ok()   { printf '%sPASS:%s %s\n' "$GRN" "$RST" "$*"; }
+fail() { printf '%sFAIL:%s %s\n' "$RED" "$RST" "$*"; }
+skip() { printf '%sSKIP:%s %s\n' "$YEL" "$RST" "$*"; }
+
+FAILED=0
+
+# 1. discover candidate files. bash-3.2-safe (no mapfile); NUL-delimited for spaces.
+FILES=()
+if [[ -f "$TARGET" ]]; then
+  FILES+=("$TARGET")
+elif [[ -d "$TARGET" ]]; then
+  while IFS= read -r -d '' f; do
+    FILES+=("$f")
+  done < <(find "$TARGET" \
+    \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/vendor/*' \) -prune \
+    -o -type f \( -name '*.yml' -o -name '*.yaml' -o -name '*.json' \
+       -o -name '*.rules' -o -name '*.conf' -o -name '*.md' \) -print0 2>/dev/null)
+else
+  skip "target not found: $TARGET — nothing to gate"; exit 0
+fi
+
+# Keep only files that look like monitoring artifacts (alerts/health/monitors).
+CAND=()
+for f in ${FILES[@]+"${FILES[@]}"}; do
+  if grep -liE 'alert|burn[_-]?rate|livez|readyz|liveness|readiness|monitor|uptime|escalation|runbook' "$f" >/dev/null 2>&1; then
+    CAND+=("$f")
+  fi
+done
+
+if [[ ${#CAND[@]} -eq 0 ]]; then
+  printf 'No monitoring config/spec files found under %s — nothing to gate.\n' "$TARGET"
+  exit 0
+fi
+
+# Build a single haystack of the candidate contents for cross-file checks.
+HAY="$(cat ${CAND[@]+"${CAND[@]}"} 2>/dev/null || true)"
+
+# Helpers (case-insensitive grep against the haystack).
+has() { printf '%s' "$HAY" | grep -qiE "$1"; }
+
+# 2. liveness vs readiness — only meaningful if a health spec is present at all.
+if printf '%s' "$HAY" | grep -qiE 'livez|liveness|readyz|readiness|health'; then
+  if has 'livez|liveness' && has 'readyz|readiness'; then
+    ok "health spec separates liveness from readiness"
+  else
+    fail "health spec does not separate liveness (/livez) from readiness (/readyz)"
+    FAILED=1
+  fi
+else
+  skip "no health-endpoint spec present — liveness/readiness check not applicable"
+fi
+
+# 3. symptom/SLO/burn-rate alert with two windows.
+if has 'alert|expr|burn|rate\(|error[_ ]?rate|severity'; then
+  TWO_WINDOW=0
+  # burn-rate keyword, or an explicit long+short pairing of distinct time windows.
+  if has 'burn[_-]?rate|multi[_-]?window'; then TWO_WINDOW=1; fi
+  if printf '%s' "$HAY" | grep -qE '\[(1h|6h|3d|24h)\]' \
+     && printf '%s' "$HAY" | grep -qE '\[(5m|30m|6h)\]'; then TWO_WINDOW=1; fi
+  if has '(long|short)[ _-]?window'; then TWO_WINDOW=1; fi
+
+  # Are the ONLY thresholds bare cpu/memory? (cause-based, no symptom alert).
+  ONLY_CAUSE=0
+  if has 'cpu|memory|mem_usage|load average' \
+     && ! has 'error[_ ]?rate|5\.\.|5xx|latency|p9[59]|burn|availability|uptime'; then
+    ONLY_CAUSE=1
+  fi
+
+  if [[ $ONLY_CAUSE -eq 1 ]]; then
+    fail "only cause-based thresholds found (cpu/memory) — add a symptom/SLO alert"
+    FAILED=1
+  elif [[ $TWO_WINDOW -eq 1 ]]; then
+    ok "symptom/SLO alert with two windows (burn-rate or long+short) present"
+  else
+    fail "alert present but no two-window/burn-rate symptom alert — single-window 'by vibes'"
+    FAILED=1
+  fi
+
+  # 4. runbook reference on alerts.
+  if has 'runbook'; then
+    ok "alerts reference a runbook"
+  else
+    fail "alert rules carry no runbook/runbook_url reference"
+    FAILED=1
+  fi
+else
+  skip "no alert rules present — alert/runbook checks not applicable"
+fi
+
+# 5a. banlist — Opsgenie as a NEW setup (EOL 2027-04-05).
+# Allow mentions that are clearly a do-NOT note; flag a bare adoption.
+if has 'opsgenie'; then
+  if printf '%s' "$HAY" | grep -iE 'opsgenie' | grep -qiE "do not|don't|deprecat|eol|retir|avoid|instead of|not start|no usar|migrat"; then
+    ok "opsgenie referenced only as a do-not/deprecation note"
+  else
+    fail "opsgenie configured as a new setup — it is EOL 2027-04-05; use PagerDuty/incident.io/Better Stack/Grafana Cloud IRM"
+    FAILED=1
+  fi
+fi
+
+# 5b. banlist — a monitor whose only target is the homepage "/".
+# Flag url:"/" or path "/" used as a probe target with no critical-journey/readyz target.
+if printf '%s' "$HAY" | grep -qE '(url|path|target|target_url)["'"'"' :]+["'"'"']?/["'"'"']?\s*$' \
+   || printf '%s' "$HAY" | grep -qE '(url|path|target)["'"'"' :]+["'"'"']/["'"'"']'; then
+  if has 'readyz|/api/|journey|checkout|login|critical'; then
+    ok "homepage probe present but a deeper/critical-journey target also configured"
+  else
+    fail "monitor target appears to be homepage '/' only — probe the critical user journey, not just /"
+    FAILED=1
+  fi
+fi
+
+# summary
+if [[ $FAILED -eq 0 ]]; then
+  ok "all monitoring checks passed (skips are not failures)"
+else
+  fail "one or more monitoring checks failed"
+fi
+exit "$FAILED"