@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/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/shared/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"

package/skills/shared/mysql/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: mysql
+description: "Use when designing, querying, indexing or operating a MySQL or MariaDB database and engine-specific behaviour matters — schema and type choices, index design, reading EXPLAIN, online schema change, replication and replica lag, locking and InnoDB deadlocks, charset traps, and server config. NOT portable SELECT/JOIN/window-function craft (that is `sql`), NOT PostgreSQL engine behaviour like VACUUM or JSONB (that is `postgresdb`), NOT the PlanetScale/Vitess branch-and-deploy workflow (that is `planetscale`)."
+tags: [mysql, mariadb, innodb, explain, replication, indexing, online-ddl, database]
+recommends: [sql, postgresdb, planetscale, db-migrations, backups]
+origin: ai-hub
+---
+
+# MySQL / MariaDB engine
+
+You are working below portable SQL, at the layer where the answer depends on *which engine* is
+running. This skill owns MySQL 8.4 LTS and MariaDB 11.8 LTS: the **InnoDB** clustered-index storage
+model, MySQL-flavoured DDL and types, index design and the leftmost-prefix rule, reading `EXPLAIN`
+and fixing the plan, online DDL, replication, locking/deadlocks, and day-2 server config.
+
+The dividing line is simple: **if the answer is identical on PostgreSQL, it belongs in `sql`, not
+here.** `sql` owns the dialect-independent SELECT grammar. `mysql` owns how *this* engine stores,
+plans, locks, and replicates. `postgresdb` is the peer engine for the other database — same body
+shape, different facts, never the same answer.
+
+## When to use
+
+- Designing or reviewing a MySQL/MariaDB schema: engine choice, integer/`DECIMAL`/`VARCHAR` sizing,
+  `utf8mb4` charset/collation, `JSON` + generated/`STORED` columns, PK design for InnoDB.
+- A query is slow or scans too many rows; reading `EXPLAIN` / `EXPLAIN ANALYZE` / `FORMAT=JSON`.
+- Choosing or adding an index: composite column order, covering indexes, prefix indexes on `TEXT`,
+  invisible indexes for safe rollout, why an index is *not* used.
+- Schema change on a large/hot table without downtime: `ALGORITHM=INSTANT/INPLACE/COPY`, pt-osc, gh-ost.
+- Replication: binlog row format, GTID (incl. tagged GTIDs), replica lag, semi-sync, group replication.
+- Locking/concurrency: deadlocks, gap/next-key locks, `REPEATABLE READ`, `SELECT ... FOR UPDATE`.
+- Operating the server: buffer pool, `caching_sha2_password` + TLS, slow-query log, `performance_schema`.
+- Migrating 5.7/8.0 → 8.4 LTS, or reasoning about MySQL ↔ MariaDB divergence.
+
+## When NOT to use
+
+| The ask | Goes to |
+|---|---|
+| Portable query craft — joins, window functions, CTEs, NULL 3VL | `sql` |
+| PostgreSQL engine behaviour — MVCC, VACUUM, RLS, JSONB, PgBouncer | `postgresdb` |
+| PlanetScale / Vitess branch + deploy-request workflow, no-FK design | `planetscale` |
+| Vendor-neutral migration *theory* — expand-contract, batched backfill | `db-migrations` |
+| ORM / query-builder API ergonomics | `drizzle-orm`, `prisma-orm` |
+| Backup *strategy* / retention / restore drills as a discipline | `backups` |
+| OLAP / columnar analytics | `clickhouse-analytics`, `duckdb` |
+
+The boundaries with `planetscale` and `db-migrations` are sharp: this skill owns the raw-MySQL
+mechanics (`EXPLAIN`, index choice, `ALGORITHM=`, gh-ost). PlanetScale wraps those in its platform
+workflow; `db-migrations` wraps them in vendor-neutral strategy. You own the knobs they ride on.
+
+## Pick your version first
+
+Get this wrong and every later decision (auth, vector, isolation defaults) is wrong too.
+
+| Target | Use it when | Watch out |
+|---|---|---|
+| **MySQL 8.4 LTS** | Default for conservative production. GA 2024-04-30, supported through April 2032. | `mysql_native_password` is **disabled by default** here. |
+| **MySQL 9.x Innovation** | Only if you need `VECTOR` or the newest features and accept short support. | Short-lived track; `mysql_native_password` is **removed**. Not for stable prod. |
+| **MariaDB 11.8 LTS** | The fork; 2025 yearly LTS, first MariaDB LTS with native vector search. | Auth, vector syntax, and `RETURNING` differ from MySQL — **not drop-in compatible**; `innodb_snapshot_isolation` defaults **ON**. |
+
+`VECTOR` is a MySQL 9.0 (Innovation) feature, *not* in 8.4 LTS. MariaDB 11.8 also has `VECTOR` but
+with different functions (`VEC_DISTANCE_COSINE()` vs MySQL's `STRING_TO_VECTOR()`) — see
+`references/mysql-vs-mariadb.md`. Do not assume one's vector SQL runs on the other.
+
+## Non-negotiables
+
+1. **`utf8mb4`, always — at the column level.** Legacy `utf8` (alias `utf8mb3`) is 3-byte and
+   silently truncates emoji and supplementary characters. Default collation is `utf8mb4_0900_ai_ci`.
+   Setting it on the connection only is not enough; set it on the column.
+2. **Small monotonic PRIMARY KEY.** An InnoDB table *is* its PK B-tree, and every secondary index
+   stores the PK as its row pointer. A random `UUID`/`CHAR(36)` PK bloats every secondary index and
+   wrecks insert locality. Use `BIGINT AUTO_INCREMENT` or an ordered UUIDv7 stored as `BINARY(16)`.
+3. **`binlog_format=ROW` + GTID.** ROW is the only reliable replication format; GTID gives each
+   transaction a globally unique id with auto-skip so it applies at most once per replica.
+4. **`caching_sha2_password` + TLS.** It is the default auth plugin and SHA-256 based; clients need
+   TLS for first-time auth. `mysql_native_password` is disabled by default in 8.4 and gone in 9.0 —
+   do not design around it.
+5. **Index column order follows the leftmost prefix.** `INDEX (a,b,c)` serves `a`, `a,b`, `a,b,c` —
+   never `b` alone. Put equality columns first, then the range/`ORDER BY` column.
+6. **Never `ALTER` a hot table without choosing an algorithm.** Default `COPY` locks and rebuilds.
+   Pick `INSTANT`/`INPLACE`, or use gh-ost / pt-osc, *before* you run it at peak.
+7. **`REPEATABLE READ` + next-key (gap) locks → short, consistently-ordered transactions.** This is
+   the InnoDB default and the usual deadlock source. Acquire rows in the same order everywhere.
+8. **Measure with `EXPLAIN ANALYZE`, do not guess.** The optimizer's `rows` is an estimate;
+   `EXPLAIN ANALYZE` runs the query and reports actual rows and timing.
+
+## Index decision
+
+| You have | Use |
+|---|---|
+| One column in `WHERE`, high selectivity | Single-column index |
+| Multiple `WHERE` columns + an `ORDER BY` | Composite index: equality cols first, then range/sort col (leftmost prefix) |
+| Query reads only indexed columns | Covering index (add the selected cols) — avoids the PK back-lookup |
+| Filtering a long `TEXT`/`VARCHAR` prefix | Prefix index `col(20)` — can't be covering, watch selectivity |
+| Rolling out an index on a hot table safely | `INVISIBLE` index, then flip `VISIBLE` once verified |
+
+```sql
+-- Bad: separate single-column indexes; the optimizer uses at most one, then filesorts.
+CREATE INDEX idx_uid ON orders (user_id);
+CREATE INDEX idx_created ON orders (created_at);
+-- Query: WHERE user_id = ? AND created_at >= ? ORDER BY created_at DESC
+
+-- Good: one composite index — equality (user_id) first, then the range/sort column.
+-- This serves the WHERE and the ORDER BY with no separate sort step.
+CREATE INDEX idx_user_created ON orders (user_id, created_at);
+```
+
+## Read EXPLAIN
+
+`EXPLAIN` shows the plan; `EXPLAIN ANALYZE` runs it and reports actual rows/time;
+`EXPLAIN FORMAT=JSON` shows cost and used-key-parts. Read the access `type` first — it is the ladder
+from worst to best:
+
+`ALL` (full scan) → `index` (full index scan) → `range` → `ref` → `eq_ref` → `const`.
+
+Anything `ALL` on a large table is a red flag. Then check `rows` (estimated rows examined),
+`filtered` (% surviving the `WHERE`), and the `Extra` flags: `Using filesort` (extra sort pass),
+`Using temporary` (materialised temp table), `Using index` (covering — good, no back-lookup).
+
+The most common cause of a missed index is a **non-sargable predicate** — a function or implicit
+charset/type cast wrapping the indexed column:
+
+```sql
+-- Bad: DATE() wraps the indexed column → the index on created_at can't be used → type=ALL.
+SELECT * FROM orders WHERE DATE(created_at) = '2026-06-01';
+
+-- Good: range over the raw column → index range scan (type=range).
+SELECT * FROM orders
+WHERE created_at >= '2026-06-01' AND created_at < '2026-06-02';
+```
+
+A subtler version: joining a `utf8mb4` column to a `latin1` column, or a `VARCHAR` to an `INT`,
+forces a per-row cast and disables the index. Make both sides the same type and collation. Full
+field-by-field reading, the `type` ladder, and every "why no index" cause are in
+`references/indexing-and-explain.md`.
+
+## Online DDL chooser
+
+| Operation / situation | Use |
+|---|---|
+| Add column at end, rename column, set default, drop index | `ALGORITHM=INSTANT` — metadata-only, near-free (8.0+) |
+| Add secondary index, change column nullability inplace | `ALGORITHM=INPLACE, LOCK=NONE` — rebuilds without blocking most writes |
+| What INSTANT/INPLACE can't do, on a small/cold table | `ALGORITHM=COPY` — locks + rebuilds; fine off-hours |
+| Same change on a large/hot table, zero downtime | `gh-ost` or `pt-online-schema-change` — shadow table + swap |
+
+```sql
+-- INSTANT: adding a column at the end is metadata-only in 8.0+. Always be explicit so a
+-- silent fall-through to COPY (which locks) can't happen.
+ALTER TABLE orders ADD COLUMN note VARCHAR(255) NULL, ALGORITHM=INSTANT, LOCK=NONE;
+```
+
+```bash
+# gh-ost: build a shadow table, copy + tail the binlog, then atomic cutover. Always --dry-run
+# first; throttle on replica lag so you don't melt production.
+gh-ost \
+  --host=primary.db --database=shop --table=orders \
+  --alter="ADD INDEX idx_user_created (user_id, created_at)" \
+  --max-lag-millis=1500 --throttle-control-replicas="replica1.db" \
+  --execute   # drop --execute to dry-run
+```
+
+If gh-ost refuses to read the binlog, run `pt-online-schema-change`, which uses triggers instead.
+Both, plus the rollback path and how this composes with `db-migrations` expand-contract theory, are
+in `references/online-ddl-and-migrations.md`.
+
+## Copy-paste patterns
+
+```sql
+-- Covering index: the query reads only (user_id, status, total), so put them all in the index.
+-- EXPLAIN then shows "Using index" — no trip back to the PK leaf for each row.
+SELECT status, total FROM orders WHERE user_id = ?;
+CREATE INDEX idx_cover ON orders (user_id, status, total);
+```
+
+```sql
+-- GTID replication on the replica: GTID auto-positioning, no log file/pos bookkeeping.
+CHANGE REPLICATION SOURCE TO
+  SOURCE_HOST='primary.db', SOURCE_USER='repl', SOURCE_PASSWORD='***',
+  SOURCE_SSL=1, SOURCE_AUTO_POSITION=1;
+START REPLICA;
+```
+
+```sql
+-- Replica lag: read the field, don't eyeball. Seconds_Behind_Source is coarse; for accuracy use
+-- performance_schema replication tables. NULL means replication is broken, not "0 lag".
+SHOW REPLICA STATUS\G   -- Replica_IO_Running / Replica_SQL_Running / Seconds_Behind_Source
+SELECT * FROM performance_schema.replication_applier_status_by_worker;
+```
+
+```sql
+-- Deadlock post-mortem: InnoDB rolls back the cheaper transaction and logs the cycle here.
+SHOW ENGINE INNODB STATUS\G   -- read the LATEST DETECTED DEADLOCK section
+```
+
+```bash
+# Consistent logical dump without locking every table: single transaction over InnoDB.
+mysqldump --single-transaction --set-gtid-purged=AUTO --routines --triggers shop > shop.sql
+```
+
+Replication topologies (async / semi-sync / group replication / InnoDB Cluster + MySQL Router),
+failover, and read-replica routing are in `references/replication-and-ha.md`.
+
+## MySQL vs MariaDB divergence
+
+They share a heritage and diverge in ways that break copy-pasted SQL. Do not assume parity.
+
+| Area | MySQL 8.4 / 9.x | MariaDB 11.8 |
+|---|---|---|
+| Default auth | `caching_sha2_password` | `mysql_native_password` / `ed25519` |
+| `VECTOR` | MySQL 9.0+ only; `STRING_TO_VECTOR()` | Native in 11.8; `VEC_DISTANCE_COSINE()` — different syntax |
+| `RETURNING` | `INSERT ... RETURNING` only (8.0+) | `INSERT`/`UPDATE`/`DELETE ... RETURNING` |
+| Sequences | No `CREATE SEQUENCE` | `CREATE SEQUENCE` supported |
+| System-versioned (temporal) tables | Not supported | `WITH SYSTEM VERSIONING` supported |
+| Snapshot isolation | RR snapshot, no write-conflict detection | `innodb_snapshot_isolation` defaults **ON** |
+| JSON | Native binary `JSON` type | Historically a `LONGTEXT` alias; check version |
+
+Depth and both-direction migration gotchas: `references/mysql-vs-mariadb.md`.
+
+## Anti-patterns / rationalizations → STOP
+
+| Rationalization | Reality | Do instead |
+|---|---|---|
+| "`utf8` is Unicode, it's fine." | `utf8` = 3-byte `utf8mb3`; emoji silently become `????`. | `utf8mb4` at the column level. |
+| "A random UUID PK is clean and unique." | Random PK bloats every secondary index and kills insert locality in the clustered index. | `BIGINT AUTO_INCREMENT` or ordered UUIDv7 as `BINARY(16)`. |
+| "`STATEMENT` binlog is smaller, use it." | Non-deterministic statements replicate wrong; silent data drift on replicas. | `binlog_format=ROW`. |
+| "Just keep using `mysql_native_password`." | Disabled by default in 8.4, removed in 9.0 — your upgrade breaks. | `caching_sha2_password` + TLS. |
+| "Wrapping the column in `DATE()`/`LOWER()` is readable." | Function on an indexed column → full scan. | Rewrite to a sargable range; or add a generated column + index. |
+| "`SELECT *` is convenient." | Pulls wide InnoDB rows off-disk and defeats covering indexes. | Select only needed columns. |
+| "I'll hold the transaction open while I do other work." | RR + gap locks held long → deadlocks and lock waits everywhere. | Keep transactions short; commit fast; order rows consistently. |
+| "`ALTER` it now, traffic is fine." | `COPY` algorithm locks a multi-GB table; outage at peak. | Pick `INSTANT`/`INPLACE`, or gh-ost off-peak. |
+| "`EXPLAIN` says 12 rows, so it's fast." | `rows` is an *estimate* from stats. | Confirm with `EXPLAIN ANALYZE` (actual rows/time). |
+| "MyISAM is faster for our table." | No transactions, no FKs, table-level locks, crash-unsafe. | InnoDB for anything transactional. |
+
+## Verify
+
+Run `scripts/verify.sh` from your project root. It is read-only and **never connects to a
+database** — it heuristically lints discovered `*.sql` and `*.cnf`/`my.cnf` files for the foot-guns
+above (legacy `utf8`, MyISAM, random-UUID PK, `binlog_format=STATEMENT`, `mysql_native_password`,
+function-wrapped indexed columns) and checks balanced delimiters. It exits non-zero only on
+unbalanced delimiters or a committed `binlog_format=STATEMENT`; every schema heuristic is advisory.
+It optionally runs `sqlfluff --dialect mysql` if installed.
+
+## See Also
+
+- `../sql/SKILL.md` — portable, engine-agnostic SELECT/JOIN/window-function craft.
+- `../postgresdb/SKILL.md` — the peer engine (PostgreSQL): MVCC, VACUUM, RLS, JSONB.
+- `../planetscale/SKILL.md` — the PlanetScale/Vitess platform workflow on top of MySQL.
+- `db-migrations` — vendor-neutral migration strategy (expand-contract) that the `ALGORITHM=`/gh-ost
+  mechanics here ride on.
+- `backups` — backup strategy, retention, and restore drills as a discipline.

package/skills/shared/mysql/evals/README.md

@@ -0,0 +1,12 @@
+# Evals — mysql
+
+These cases are routing and capability specs, not an automated test suite. There is no in-repo
+trigger harness. To run them, have a human or an LLM judge read `cases.yaml` and check three things:
+that each `should_trigger` prompt would plausibly load this skill, that each `should_not_trigger`
+prompt routes to the named sibling instead (`sql`, `postgresdb`, `planetscale`, `db-migrations`,
+`drizzle-orm` — all real skills), and that an answer to the `capability` scenario hits every bullet
+in its `must_include` rubric. The rubric is the bar: a passing answer reads EXPLAIN, fixes the
+non-sargable predicate, designs the composite/covering index with correct column order, reasons
+about the InnoDB clustered index, and verifies the new plan — without drifting into ORM or platform
+workflow that belongs to a sibling. `scripts/verify.sh` is separate: it lints emitted `*.sql` /
+`*.cnf` artifacts for the foot-guns in SKILL.md and never connects to a database.

package/skills/shared/mysql/evals/cases.yaml

@@ -0,0 +1,49 @@
+skill: mysql
+
+should_trigger:
+  - prompt: "This MySQL query is doing a full table scan, EXPLAIN shows type=ALL — how do I index it?"
+    why: Core of the skill — reading the EXPLAIN access type and choosing an InnoDB index.
+  - prompt: "Add a NOT NULL column to a 40GB hot InnoDB table without downtime."
+    why: Online DDL — ALGORITHM choice plus gh-ost/pt-osc on a hot table. MySQL-specific mechanics.
+  - prompt: "Set up GTID-based source-replica replication and check the replica lag."
+    why: Replication setup (CHANGE REPLICATION SOURCE TO, SOURCE_AUTO_POSITION) and lag diagnosis.
+  - prompt: "Getting 'Authentication plugin caching_sha2_password cannot be loaded' connecting to MySQL 8.4."
+    why: Non-obvious. The 8.4 default-auth + TLS trap; mysql_native_password is gone. Pure engine/ops.
+  - prompt: "Our composite index on (a,b,c) isn't used when I filter only on b — why?"
+    why: Non-obvious. The leftmost-prefix rule — the canonical InnoDB index-design confusion.
+  - prompt: "Emoji get stored as ???? in our MySQL VARCHAR column."
+    why: Non-obvious. The legacy 3-byte utf8 (utf8mb3) vs utf8mb4 silent-truncation bug.
+  - prompt: "optimizar consulta MySQL que tarda mucho, el índice no se usa"
+    why: Spanish trigger — slow MySQL query, index not used; squarely engine-level tuning.
+  - prompt: "InnoDB deadlock under REPEATABLE READ — how do I read SHOW ENGINE INNODB STATUS?"
+    why: Locking/concurrency — gap/next-key locks and the deadlock post-mortem, MySQL-specific.
+
+should_not_trigger:
+  - prompt: "Write a window-function query to rank rows per group."
+    route_to: sql
+    why: Portable, engine-agnostic SELECT grammar — identical on Postgres, so it belongs in sql.
+  - prompt: "How does Postgres VACUUM and autovacuum work?"
+    route_to: postgresdb
+    why: PostgreSQL engine behaviour (MVCC garbage collection) — the peer engine, not MySQL.
+  - prompt: "Create a PlanetScale branch and open a deploy request for this schema change."
+    route_to: planetscale
+    why: The PlanetScale/Vitess platform branch-and-deploy workflow, not raw MySQL mechanics.
+  - prompt: "Design an expand-contract migration sequence to rename a column safely."
+    route_to: db-migrations
+    why: Vendor-neutral migration strategy/ordering — mysql owns the ALGORITHM/gh-ost mechanics, not the theory.
+  - prompt: "Define my schema with Drizzle's table builder and run the generated migration."
+    route_to: drizzle-orm
+    why: ORM/query-builder API ergonomics, not engine-level SQL or InnoDB behaviour.
+
+capability:
+  - scenario: >
+      A MySQL 8.4 query on a large InnoDB orders table is slow: it filters
+      WHERE user_id = ? AND DATE(created_at) = ? ORDER BY created_at DESC and currently
+      does type=ALL. Diagnose and fix it end to end, engine-specifically.
+    must_include:
+      - Runs EXPLAIN / EXPLAIN ANALYZE and reads the access type (ALL→index→range→ref…) plus rows/filtered
+      - Identifies the non-sargable predicate (DATE() wrapping the indexed created_at) and rewrites it to a sargable range
+      - Proposes a composite index with equality column (user_id) first then the range/sort column (created_at), matching WHERE and ORDER BY
+      - Considers a covering index and notes the InnoDB clustered-index PK back-lookup implication
+      - Verifies the new plan with EXPLAIN ANALYZE (type improved, rows dropped, no Using filesort) rather than asserting
+      - Stays engine-specific — does not drift into ORM builder API or PlanetScale deploy-request workflow