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

package/skills/shared/mysql/references/indexing-and-explain.md

@@ -0,0 +1,161 @@
+# Indexing and EXPLAIN (InnoDB)
+
+Everything here is MySQL 8.4 / MariaDB 11.8 InnoDB behaviour. If the same advice would hold on
+PostgreSQL, it belongs in `sql`, not here.
+
+## The clustered-index model — why PK choice is everything
+
+An InnoDB table *is* its primary-key B-tree. The full row lives in the leaf of the PK index; there
+is no separate heap. Two consequences drive almost every indexing decision:
+
+1. **Every secondary index stores the PK value as its row pointer**, not a physical address. So a
+   wide PK is paid for once per secondary index, per row. A `CHAR(36)` random UUID PK on a table
+   with five secondary indexes carries 36 bytes × 5 copies of the key for every row, on top of the
+   clustered copy. A `BIGINT` PK is 8 bytes.
+2. **Insert locality follows PK order.** A monotonic PK (`BIGINT AUTO_INCREMENT`, ordered UUIDv7)
+   appends to the rightmost leaf — tight, sequential, cache-friendly. A random UUID v4 scatters
+   inserts across the whole B-tree, causing page splits and buffer-pool churn.
+
+```sql
+-- Bad: random UUID as a human-readable CHAR(36) PK.
+CREATE TABLE orders (
+  id CHAR(36) PRIMARY KEY,          -- 36 bytes, random → page splits + fat secondary indexes
+  user_id BIGINT NOT NULL
+) ENGINE=InnoDB;
+
+-- Good: small monotonic surrogate PK; store a public UUID as BINARY(16) if you need one.
+CREATE TABLE orders (
+  id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+  public_id BINARY(16) NOT NULL,    -- UUIDv7 packed; ordered, 16 bytes
+  user_id BIGINT NOT NULL,
+  UNIQUE KEY uq_public (public_id)
+) ENGINE=InnoDB;
+```
+
+If you must use a UUID PK, use a time-ordered one (UUIDv7) stored as `BINARY(16)`, never a random
+v4 as `CHAR(36)`.
+
+## The leftmost-prefix rule, worked through
+
+A composite index `INDEX (a, b, c)` is a single sorted B-tree keyed on the tuple `(a, b, c)`. It can
+satisfy a predicate only by reading a *contiguous left prefix* of that tuple:
+
+| Query predicate | Uses the index? | Why |
+|---|---|---|
+| `WHERE a = 1` | Yes (prefix `a`) | leftmost column present |
+| `WHERE a = 1 AND b = 2` | Yes (prefix `a,b`) | contiguous prefix |
+| `WHERE a = 1 AND b = 2 AND c = 3` | Yes (full key) | full prefix |
+| `WHERE a = 1 ORDER BY b` | Yes — sort comes free | `b` is the next key column after the `a` equality |
+| `WHERE b = 2` | No | skips the leftmost column `a` |
+| `WHERE a = 1 AND c = 3` | Partial — only `a` | `b` is missing, so `c` can't be a seek key (used as a filter) |
+| `WHERE a > 1 AND b = 2` | Range on `a` only | a range on an earlier column stops the next column from being a seek key |
+
+The design rule that falls out: **equality columns first, then the single range or `ORDER BY`
+column.** A range predicate "uses up" the index — no column after it can be a seek key, only a
+filter.
+
+```sql
+-- Query: WHERE user_id = ? AND status = ? AND created_at >= ? ORDER BY created_at DESC
+-- Good: two equalities first, then the range/sort column last.
+CREATE INDEX idx_u_s_c ON orders (user_id, status, created_at);
+```
+
+## Covering, prefix, invisible, and functional indexes
+
+**Covering index** — if every column a query touches (SELECT list + WHERE + ORDER BY) is in one
+index, InnoDB answers from the index alone and never walks back to the clustered PK leaf. `EXPLAIN`
+shows `Using index`.
+
+```sql
+SELECT status, total FROM orders WHERE user_id = ?;
+-- Good: index covers the filter AND the selected columns → no PK back-lookup.
+CREATE INDEX idx_cover ON orders (user_id, status, total);
+```
+
+**Prefix index** — index the first N characters of a long `VARCHAR`/`TEXT`. Required for `TEXT`
+(which can't be indexed whole) and useful to shrink a fat key. It can never be a covering index, and
+N must be long enough for selectivity.
+
+```sql
+CREATE INDEX idx_email_prefix ON users (email(20));   -- first 20 chars
+-- Pick N from selectivity: SELECT COUNT(DISTINCT LEFT(email,20))/COUNT(*) FROM users;
+```
+
+**Invisible index** (`INVISIBLE`) — the optimizer ignores it but maintains it. Use it to stage a new
+index on a hot table, or to test "would dropping this index hurt?" without actually dropping it.
+
+```sql
+ALTER TABLE orders ALTER INDEX idx_cover INVISIBLE;   -- test impact; ALTER ... VISIBLE to restore
+```
+
+**Functional / multi-valued index** (8.0.13+) — index an expression so a non-sargable predicate
+becomes sargable without a generated column.
+
+```sql
+CREATE INDEX idx_lower_email ON users ((LOWER(email)));   -- query must use LOWER(email) too
+CREATE INDEX idx_tags ON docs ((CAST(meta->'$.tags' AS UNSIGNED ARRAY)));  -- multi-valued, for JSON arrays
+```
+
+## Reading EXPLAIN field by field
+
+Three forms:
+- `EXPLAIN <q>` — the chosen plan, no execution.
+- `EXPLAIN ANALYZE <q>` — actually runs the query, reports *actual* rows and timing per node.
+- `EXPLAIN FORMAT=JSON <q>` — full cost model, `used_key_parts`, `filtered`, attached conditions.
+
+The **access `type`** is the first thing to read — worst to best:
+
+| `type` | Meaning | Verdict |
+|---|---|---|
+| `ALL` | Full table scan | Bad on a large table |
+| `index` | Full index scan (whole index read) | Usually still too much |
+| `range` | Index range scan (`>`, `BETWEEN`, `IN`) | Good |
+| `ref` | Non-unique index lookup by equality | Good |
+| `eq_ref` | Unique/PK lookup, one row per join row | Great (joins) |
+| `const` / `system` | At most one row, resolved as a constant | Best |
+
+Then read:
+- **`rows`** — *estimated* rows examined at this node. An estimate from stats, not truth — confirm
+  with `EXPLAIN ANALYZE`.
+- **`filtered`** — estimated % of `rows` surviving the `WHERE`. Low `filtered` × high `rows` = the
+  index gets you to the neighbourhood but the predicate isn't selective in the index.
+- **`key`** / **`key_len`** — the chosen index and how many bytes of it were used. A short `key_len`
+  on a composite index means only a prefix was usable.
+- **`Extra`** flags: `Using index` (covering — good), `Using filesort` (a separate sort pass — the
+  index didn't satisfy `ORDER BY`), `Using temporary` (a materialised temp table, common with
+  `GROUP BY`/`DISTINCT` that can't use an index), `Using where` (post-filter after the index).
+
+## Every common "why no index" cause, with the fix
+
+```sql
+-- 1. Function on the indexed column → index unusable.
+-- Bad:
+SELECT * FROM orders WHERE DATE(created_at) = '2026-06-01';
+-- Good (sargable range):
+SELECT * FROM orders WHERE created_at >= '2026-06-01' AND created_at < '2026-06-02';
+
+-- 2. Implicit type cast: VARCHAR column compared to a number → per-row cast, no index.
+-- Bad (phone is VARCHAR):
+SELECT * FROM users WHERE phone = 6041234567;
+-- Good:
+SELECT * FROM users WHERE phone = '6041234567';
+
+-- 3. Charset/collation mismatch on a JOIN key → per-row conversion, no index on the joined side.
+-- Bad: a.code is utf8mb4, b.code is latin1.
+-- Good: make both columns the same charset+collation (ALTER one side), then the join uses the index.
+
+-- 4. Leading wildcard LIKE → no prefix to seek.
+-- Bad:
+SELECT * FROM products WHERE name LIKE '%phone%';
+-- Good (prefix only):
+SELECT * FROM products WHERE name LIKE 'phone%';   -- or a FULLTEXT index for substring search
+
+-- 5. OR across different columns → often defeats a single index.
+-- Bad:
+SELECT * FROM t WHERE a = 1 OR b = 2;
+-- Good: UNION two index-friendly halves, or an index_merge the optimizer can use.
+SELECT * FROM t WHERE a = 1 UNION SELECT * FROM t WHERE b = 2;
+```
+
+After every fix, re-run `EXPLAIN ANALYZE` and confirm the `type` improved and `rows` dropped — the
+plan is the proof, not the rewrite.

package/skills/shared/mysql/references/mysql-vs-mariadb.md

@@ -0,0 +1,78 @@
+# MySQL vs MariaDB divergence
+
+MariaDB began as a MySQL fork and the two have diverged enough that copy-pasted SQL, auth setup, and
+operational assumptions break across them. Always know *which* engine the project runs before you
+answer. This is the depth behind the small table in `SKILL.md`.
+
+## Versions and support
+
+| | MySQL | MariaDB |
+|---|---|---|
+| Current LTS | **8.4 LTS** (GA 2024-04-30, supported through April 2032) | **11.8 LTS** (2025 yearly LTS) |
+| Innovation / short-cycle | **9.x** (9.0 GA 2024-07-01, …, 9.4.0 2025-07-22) | rolling releases between LTS years |
+| Owner | Oracle | MariaDB Foundation / MariaDB plc |
+
+MariaDB version numbers do **not** track MySQL's — MariaDB 11.8 is not "MySQL 11". Feature parity is
+partial and one-directional in places (MariaDB has features MySQL lacks and vice versa).
+
+## Authentication
+
+| | MySQL 8.4 / 9.x | MariaDB 11.8 |
+|---|---|---|
+| Default plugin | `caching_sha2_password` (SHA-256, server-side cache; TLS for first auth) | `mysql_native_password` and `ed25519` |
+| `mysql_native_password` | Disabled by default in 8.4, **removed in 9.0** | Still a first-class plugin |
+
+This is the most common cross-engine connection failure: a client/driver configured for MariaDB's
+native auth hits a MySQL 8.4 server and gets *"Authentication plugin caching_sha2_password cannot be
+loaded"* — fix is a `caching_sha2_password`-aware client over TLS, not re-enabling the old plugin.
+
+## Vector search — NOT drop-in compatible
+
+Both engines added native vector search, but with **incompatible syntax**:
+
+| | MySQL 9.0+ (Innovation only) | MariaDB 11.8 (LTS) |
+|---|---|---|
+| Type | `VECTOR(n)` — 4-byte floats, default max 2048, max 16383 entries | `VECTOR(n)` |
+| Parse / format | `STRING_TO_VECTOR()` / `TO_VECTOR()`, `VECTOR_TO_STRING()` / `FROM_VECTOR()` | `VEC_FromText()` / `VEC_ToText()` |
+| Distance | distance functions per the 9.x line | `VEC_DISTANCE_EUCLIDEAN()`, `VEC_DISTANCE_COSINE()`, `VEC_DISTANCE()` |
+| Acceleration | — | SIMD (AVX2/AVX512/ARM/Power10) |
+| Key constraint | A `VECTOR` column **cannot be any kind of key** (no PK/FK/UK/partition) | indexable for approximate search |
+| LTS availability | **Not in 8.4 LTS** — Innovation 9.x only | In the 11.8 LTS line |
+
+If a project needs vector search on a conservative LTS today, MariaDB 11.8 has it in LTS; MySQL only
+has it on the short-lived 9.x Innovation track. The SQL is not portable between them — pick one and
+write to its functions.
+
+## Snapshot isolation
+
+MariaDB 11.8 ships `innodb_snapshot_isolation` defaulting **ON**, which makes a `REPEATABLE READ`
+transaction *detect write conflicts* (raising an error instead of silently applying a stale-snapshot
+write). Stock MySQL `REPEATABLE READ` does **not** do this — it gives a consistent snapshot but no
+write-conflict detection. Code that relies on MariaDB raising a conflict error will silently succeed
+(and possibly lose an update) on MySQL, and vice versa code that doesn't expect the error will fail
+on MariaDB.
+
+## Other SQL surface divergences
+
+| Feature | MySQL | MariaDB |
+|---|---|---|
+| `RETURNING` | `INSERT ... RETURNING` only (8.0+) | `INSERT` / `UPDATE` / `DELETE ... RETURNING` |
+| Sequences | No `CREATE SEQUENCE` (use `AUTO_INCREMENT`) | `CREATE SEQUENCE` supported |
+| System-versioned (temporal) tables | Not supported | `WITH SYSTEM VERSIONING` + `FOR SYSTEM_TIME` queries |
+| `JSON` type | Native binary `JSON` | Historically a `LONGTEXT` alias with JSON functions; check the version — behaviour and storage differ |
+| Optimizer / hints | Oracle-style optimizer, `/*+ HINT */` hint syntax, hypergraph optimizer in newer Innovation | Different optimizer, different hint set and defaults; plans differ for the same query |
+| Storage engines | InnoDB-centric | InnoDB plus Aria, ColumnStore, Spider, etc. |
+
+## Migration gotchas, both directions
+
+- **MariaDB → MySQL**: drop reliance on sequences, system-versioned tables, multi-statement
+  `RETURNING`, and the snapshot-isolation conflict behaviour. Re-check JSON columns. Re-key any
+  vector columns and rewrite vector SQL.
+- **MySQL → MariaDB**: auth changes (native/ed25519 vs caching_sha2_password); rewrite MySQL 9
+  vector SQL to `VEC_*`; expect `innodb_snapshot_isolation=ON` to start raising conflict errors your
+  app didn't see before; verify optimizer-hint syntax and re-test query plans.
+- **Don't trust `mysqldump` round-trips blindly** across engines — types, charsets, and engine
+  clauses can differ. Dump, then read the DDL before loading into the other engine.
+
+Bottom line: treat MySQL and MariaDB as two different databases that happen to share a wire protocol
+and a lot of grammar. Confirm the engine, then write to its specifics.

package/skills/shared/mysql/references/online-ddl-and-migrations.md

@@ -0,0 +1,120 @@
+# Online DDL and migrations (the MySQL mechanics)
+
+This file owns the MySQL-only knobs — `ALGORITHM=`, `LOCK=`, pt-online-schema-change, gh-ost — that
+make a schema change run without an outage. The vendor-neutral *strategy* (expand-contract, batched
+backfill, dual-write) lives in `db-migrations`; this is the InnoDB machinery that strategy rides on.
+
+## ALGORITHM / LOCK matrix per operation
+
+Every `ALTER TABLE` resolves to one of three algorithms. **Always state it explicitly** — if you
+omit `ALGORITHM=`, MySQL silently picks the cheapest one that works, and "cheapest that works" can
+quietly be `COPY`, which locks and rebuilds a multi-GB table.
+
+| Operation | Best algorithm | Notes |
+|---|---|---|
+| Add column at the end | `INSTANT` | metadata-only since 8.0.12; near-free |
+| Add column in the middle | `INSTANT` (8.0.29+) | older versions fall back to INPLACE/COPY |
+| Drop a column | `INSTANT` (8.0.29+) | else INPLACE |
+| Rename a column | `INSTANT` | metadata-only |
+| Set / drop a column DEFAULT | `INSTANT` | metadata-only |
+| Add a secondary index | `INPLACE, LOCK=NONE` | rebuilds the index without blocking writes |
+| Drop an index | `INPLACE` (often INSTANT) | metadata change |
+| Change column NULL → NOT NULL | `INPLACE` | requires the data to already satisfy it |
+| Change column data type / charset | `COPY` | full table rebuild — this is the dangerous one |
+| Add / drop a PRIMARY KEY | `COPY` (usually) | rebuilds the clustered index and every secondary |
+| Change ROW_FORMAT / KEY_BLOCK_SIZE | `INPLACE` (rebuild) | not blocking but rewrites the table |
+
+```sql
+-- Always be explicit. If the operation can't be done with the algorithm you named, the statement
+-- FAILS LOUDLY instead of silently degrading to a locking COPY.
+ALTER TABLE orders ADD COLUMN note VARCHAR(255) NULL, ALGORITHM=INSTANT, LOCK=NONE;
+
+-- Adding a secondary index on a live table: rebuild without blocking writes.
+ALTER TABLE orders ADD INDEX idx_user_created (user_id, created_at),
+  ALGORITHM=INPLACE, LOCK=NONE;
+```
+
+There is a hard limit on `INSTANT` add-column: each `INSTANT` add increments a row-version counter,
+and after a number of them the table needs a rebuild before more `INSTANT` adds are allowed. Check
+`information_schema.INNODB_TABLES.INSTANT_COLS` / row-version columns if `INSTANT` starts refusing.
+
+## When INSTANT/INPLACE can't do it non-blockingly → gh-ost or pt-osc
+
+For a `COPY`-only change on a large *hot* table (type change, PK change, charset migration), don't
+run it in place at peak. Use an external tool that builds a shadow table, copies rows in chunks,
+keeps it in sync, and swaps atomically.
+
+### gh-ost (GitHub) — binlog-based, triggerless
+
+gh-ost reads the binlog to keep the shadow table in sync, so it adds no triggers to your hot table
+and throttles cleanly on replica lag.
+
+```bash
+# Always --dry-run (omit --execute) first; read the plan, then add --execute.
+gh-ost \
+  --host=primary.db --database=shop --table=orders \
+  --alter="MODIFY COLUMN total DECIMAL(19,4) NOT NULL" \
+  --max-load="Threads_running=25" \
+  --critical-load="Threads_running=100" \
+  --max-lag-millis=1500 \
+  --throttle-control-replicas="replica1.db,replica2.db" \
+  --chunk-size=1000 \
+  --cut-over=default \
+  --postpone-cut-over-flag-file=/tmp/ghost.postpone \
+  --execute
+# Touch/remove the postpone file to control exactly when the atomic cutover happens.
+```
+
+gh-ost needs `binlog_format=ROW` and either a connection to a replica or `--allow-on-master` with
+binlog access. It can't follow a table that already has triggers.
+
+### pt-online-schema-change (Percona) — trigger-based
+
+Use pt-osc when gh-ost can't read the binlog (no replica, restricted binlog). It installs AFTER
+INSERT/UPDATE/DELETE triggers on the original table to mirror writes into the shadow copy.
+
+```bash
+pt-online-schema-change \
+  --alter "MODIFY COLUMN total DECIMAL(19,4) NOT NULL" \
+  --max-lag=1.5 --check-slave-lag replica1.db \
+  --chunk-time=0.5 \
+  --dry-run \
+  D=shop,t=orders
+# Replace --dry-run with --execute once the dry run is clean.
+```
+
+Caveat: pt-osc's triggers conflict with any pre-existing triggers on the table, and foreign keys
+referencing the table need `--alter-foreign-keys-method` chosen deliberately (rebuild_constraints
+vs drop_swap) — a wrong choice can briefly break FK integrity at cutover.
+
+### Choosing between them
+
+| Situation | Tool |
+|---|---|
+| You have a replica and ROW binlog, no existing triggers | gh-ost (lighter, no triggers on hot table) |
+| No replica / restricted binlog access | pt-osc (triggers) |
+| Table already has triggers | pt-osc with care, or refactor first |
+| Foreign keys point at the table | pt-osc with an explicit `--alter-foreign-keys-method` |
+
+## Rollback
+
+- An `INSTANT`/`INPLACE` `ALTER` is a single transaction-like operation: if it fails it leaves the
+  table unchanged. There is no half-applied state to clean up.
+- gh-ost / pt-osc: before cutover, the original table is untouched — abort freely (gh-ost: remove
+  the panic flag or kill it; the `_gho`/`_new` shadow + `_del` old table are left for you to drop).
+  *After* cutover, "rollback" means running the reverse `ALTER` as a new migration. Design the
+  reverse step before you cut over.
+
+## How this composes with db-migrations expand-contract
+
+The vendor-neutral pattern from `db-migrations` is: **expand** (add the new column/index, both old
+and new readable), **migrate** (backfill + dual-write), **contract** (drop the old). Each phase maps
+to a specific MySQL mechanic here:
+
+- *Expand* = an `ALGORITHM=INSTANT` add-column / `INPLACE` add-index — cheap, non-blocking.
+- *Backfill* = chunked `UPDATE ... WHERE id BETWEEN ? AND ?` in small batches (never one giant
+  `UPDATE` that holds gap locks across the whole table); or let gh-ost do it for a type change.
+- *Contract* = an `INSTANT` drop-column once nothing reads the old one.
+
+Keep each phase a separate, forward-only migration so the reverse is always a clean step.
+`db-migrations` owns *why* and *in what order*; this skill owns *which `ALGORITHM=` / which tool*.

package/skills/shared/mysql/references/replication-and-ha.md

@@ -0,0 +1,115 @@
+# Replication and HA
+
+MySQL 8.4 / MariaDB 11.8 replication mechanics: binlog formats, GTID, the topologies, lag diagnosis,
+and failover. Backup *strategy* as a discipline lives in `backups`; this owns the binlog/PITR and
+replication-setup mechanics.
+
+## Binlog format — ROW, and why
+
+| Format | What it logs | Verdict |
+|---|---|---|
+| `ROW` | The actual before/after row images | **The only safe default.** Deterministic; replicas apply exactly what happened. |
+| `STATEMENT` | The literal SQL text | Non-deterministic statements (`NOW()`, `UUID()`, `LIMIT` without `ORDER BY`, triggers) replicate *differently* on the replica → silent data drift. |
+| `MIXED` | STATEMENT, switching to ROW when it detects non-determinism | Better than STATEMENT but the detection is imperfect; prefer ROW outright. |
+
+```ini
+# my.cnf — the replication baseline.
+[mysqld]
+server_id              = 1            # unique per host in the topology
+log_bin                = mysql-bin
+binlog_format          = ROW
+gtid_mode              = ON
+enforce_gtid_consistency = ON
+binlog_expire_logs_seconds = 604800   # 7 days of binlog retained for replicas/PITR
+```
+
+## GTID-based replication, end to end
+
+A GTID (Global Transaction ID) tags every committed transaction with `source_uuid:sequence`. The
+replica records which GTIDs it has applied, so with `SOURCE_AUTO_POSITION=1` it requests exactly the
+transactions it's missing — no manual log-file/position bookkeeping, and each transaction applies
+**at most once** (auto-skip on reconnect/failover).
+
+**MySQL 8.4 adds tagged GTIDs**: an optional third, colon-separated component
+(`source_uuid:tag:sequence`) that groups related transactions — useful to mark, filter, or
+selectively skip a logical batch.
+
+```sql
+-- On the replica (8.4 syntax: CHANGE REPLICATION SOURCE TO, not the old CHANGE MASTER TO).
+CHANGE REPLICATION SOURCE TO
+  SOURCE_HOST='primary.db',
+  SOURCE_USER='repl',
+  SOURCE_PASSWORD='***',
+  SOURCE_SSL=1,                 -- caching_sha2_password needs TLS
+  SOURCE_AUTO_POSITION=1;       -- GTID auto-positioning
+START REPLICA;
+SHOW REPLICA STATUS\G
+```
+
+The replication user authenticates with `caching_sha2_password` by default, so the channel must use
+`SOURCE_SSL=1` or the first-time auth fails.
+
+## Topology chooser
+
+| Topology | Durability on primary loss | Use when |
+|---|---|---|
+| **Async** (default) | Can lose the last un-replicated transactions | Read scaling, geo replicas, where small data-loss-on-failover is acceptable |
+| **Semi-synchronous** | Primary waits for ≥1 replica to *receive* (not apply) each commit | You need "committed means at least one replica has it" without full consensus cost |
+| **Group Replication / InnoDB Cluster** | Quorum-committed (Paxos-style); automatic failover | You need automatic failover and a single logical primary with managed membership |
+
+InnoDB Cluster = Group Replication + MySQL Shell (`dba.createCluster()`) for orchestration + **MySQL
+Router** as the connection front-end that routes writes to the primary and reads to replicas. Apps
+connect to the Router's port (6446 read-write / 6447 read-only), never directly to a node, so a
+failover is transparent to the application.
+
+```ini
+# Semi-sync (loadable component in 8.4): primary waits for one replica to ACK receipt.
+[mysqld]
+rpl_semi_sync_source_enabled  = 1
+rpl_semi_sync_source_timeout  = 1000   # ms before falling back to async if no ACK
+rpl_semi_sync_replica_enabled = 1
+```
+
+## Replica-lag diagnosis — read the field, don't eyeball
+
+```sql
+SHOW REPLICA STATUS\G
+-- Read in this order:
+--   Replica_IO_Running  / Replica_SQL_Running  → both must be 'Yes'
+--   Last_IO_Error / Last_SQL_Error             → why it stopped
+--   Seconds_Behind_Source                      → coarse; NULL means BROKEN, not "0 lag"
+```
+
+`Seconds_Behind_Source` is a blunt instrument (it's relative to the SQL thread's current event, and
+goes NULL the moment a thread stops). For real, per-worker lag use performance_schema:
+
+```sql
+SELECT WORKER_ID,
+       LAST_APPLIED_TRANSACTION,
+       APPLYING_TRANSACTION,
+       APPLYING_TRANSACTION_ORIGINAL_COMMIT_TIMESTAMP
+FROM performance_schema.replication_applier_status_by_worker;
+
+-- End-to-end lag = now() - the original commit timestamp of the transaction being applied.
+```
+
+If lag is structural, enable multi-threaded apply (`replica_parallel_workers > 0`,
+`replica_parallel_type = LOGICAL_CLOCK`) so the replica applies independent transactions in parallel.
+
+## Failover
+
+- **Async/semi-sync, manual**: pick the most-caught-up replica (highest applied GTID set), point the
+  other replicas and the app at it, `RESET REPLICA ALL` on the new primary. GTID auto-positioning
+  means surviving replicas resync from exactly where they were.
+- **InnoDB Cluster**: failover is automatic — the group elects a new primary; MySQL Router redirects
+  writes. Your job is to monitor `cluster.status()` and re-add the recovered node with
+  `cluster.rejoinInstance()`.
+- Always confirm the old primary is truly down (fenced) before promoting — a split brain where two
+  nodes both accept writes is the worst outcome, far worse than a few seconds of downtime.
+
+## Read-replica routing
+
+Route reads to replicas but **never read your own just-written row from a lagging async replica** —
+that's the read-after-write consistency trap. Either route a user's reads to the primary for a short
+window after their write, or use `WAIT_FOR_EXECUTED_GTID_SET()` on the replica to block until it has
+caught up to the GTID your write produced. InnoDB Cluster's Router can be configured for this.

package/skills/shared/mysql/scripts/verify.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — mysql skill gate. Run from your PROJECT root.
+#
+# What it does (read-only, idempotent, never writes, NEVER connects to a database):
+#   Discovers *.sql and *.cnf / my.cnf files and heuristically lints them for the MySQL/InnoDB
+#   foot-guns this skill warns about:
+#     - CHARACTER SET utf8 / CHARSET=utf8 that is not utf8mb4 (silent emoji truncation)   [warn]
+#     - ENGINE=MyISAM on CREATE TABLE (no transactions/FKs)                               [warn]
+#     - likely random-UUID / CHAR(36) PRIMARY KEY (InnoDB clustered-index bloat)          [warn]
+#     - default_authentication_plugin = mysql_native_password in config                   [warn]
+#     - an indexed column wrapped in a function in WHERE (DATE(col)/LOWER(col), non-sargable) [warn]
+#     - binlog_format = STATEMENT in a committed config                                   [FAIL]
+#     - unbalanced parens/single-quotes in a SQL statement                                [FAIL]
+#   Optionally runs `sqlfluff --dialect mysql` if sqlfluff is installed.
+#
+# Exit code: non-zero ONLY on (a) unbalanced delimiters, (b) a committed binlog_format=STATEMENT,
+# or (c) a real sqlfluff lint error. Every schema heuristic is advisory [warn], never a failure.
+# An empty/clean target exits 0 with no false failure.
+#
+# Portability: stock macOS bash 3.2 — no mapfile, no associative arrays. Arrays are initialised so
+# they are safe to expand under `set -u`. Pure grep/awk; no network, no mysql client.
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+note() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+ROOT="$(pwd)"
+
+# --- discover files (exclude vendor dirs) -----------------------------------------------------
+SQL_FILES=()
+while IFS= read -r -d '' f; do SQL_FILES+=("$f"); done < <(
+  find "$ROOT" \
+    \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/vendor/*' -o -path '*/.venv/*' \) -prune -o \
+    -type f -name '*.sql' -print0 2>/dev/null
+)
+
+CNF_FILES=()
+while IFS= read -r -d '' f; do CNF_FILES+=("$f"); done < <(
+  find "$ROOT" \
+    \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/vendor/*' -o -path '*/.venv/*' \) -prune -o \
+    -type f \( -name '*.cnf' -o -name 'my.cnf' \) -print0 2>/dev/null
+)
+
+if [ "${#SQL_FILES[@]}" -eq 0 ] && [ "${#CNF_FILES[@]}" -eq 0 ]; then
+  ok "no *.sql or *.cnf files found — nothing to lint"
+  exit 0
+fi
+
+# --- strip comments + string literals for the balance heuristic -------------------------------
+# Pure awk so it behaves identically on BSD (macOS) and GNU awk. Removes -- line comments,
+# /* */ block comments, and '...' single-quoted literals (handling '' escapes) so the
+# paren/quote balance check does not trip on legitimate content.
+strip_sql() {
+  awk '
+    BEGIN { inblock = 0; instr = 0 }
+    {
+      line = $0; out = ""; i = 1; n = length(line)
+      while (i <= n) {
+        ch  = substr(line, i, 1)
+        ch2 = substr(line, i, 2)
+        if (inblock) { p = index(substr(line,i), "*/"); if (p==0){i=n+1;continue} i+=p+1; inblock=0; continue }
+        if (instr)   {
+          if (ch == "\x27") {
+            if (substr(line,i,2) == "\x27\x27") { i+=2; continue }   # escaped quote
+            instr = 0; i++; continue
+          }
+          i++; continue
+        }
+        if (ch2 == "--") { i = n + 1; continue }
+        if (ch2 == "/*") { inblock = 1; i += 2; continue }
+        if (ch == "\x27") { instr = 1; i++; continue }
+        out = out ch; i++
+      }
+      print out
+    }
+  ' "$1"
+}
+
+# --- per-SQL-file checks ----------------------------------------------------------------------
+for f in ${SQL_FILES[@]+"${SQL_FILES[@]}"}; do
+  # legacy utf8 (not utf8mb4)
+  if grep -Eiq '(CHARACTER[[:space:]]+SET|CHARSET[[:space:]]*=)[[:space:]]*utf8([^m]|$|mb3)' "$f"; then
+    note "$f: legacy 'utf8' (utf8mb3) charset — silently truncates emoji. Use utf8mb4."
+  fi
+  # MyISAM
+  if grep -Eiq 'ENGINE[[:space:]]*=[[:space:]]*MyISAM' "$f"; then
+    note "$f: ENGINE=MyISAM — no transactions/FKs, crash-unsafe. Use InnoDB."
+  fi
+  # likely random-UUID / CHAR(36) PK
+  if grep -Eiq 'CHAR\(36\)[^,)]*PRIMARY[[:space:]]+KEY|PRIMARY[[:space:]]+KEY[^,)]*CHAR\(36\)' "$f"; then
+    note "$f: CHAR(36) PRIMARY KEY — likely a random UUID PK; bloats InnoDB secondary indexes. Prefer BIGINT AUTO_INCREMENT or UUIDv7 as BINARY(16)."
+  fi
+  # function-wrapped indexed column in WHERE (non-sargable)
+  if grep -Eiq 'WHERE[[:space:]].*(DATE|LOWER|UPPER|YEAR|MONTH|CAST|CONVERT)[[:space:]]*\([[:alnum:]_.`]+\)[[:space:]]*=' "$f"; then
+    note "$f: a function-wrapped column in WHERE (e.g. WHERE DATE(col)=...) is non-sargable — the index can't be used. Rewrite to a range, or add a functional/generated-column index."
+  fi
+  # balance check on comment/literal-stripped SQL
+  stripped="$(strip_sql "$f")"
+  opens="$(printf '%s' "$stripped" | tr -cd '(' | wc -c | tr -d ' ')"
+  closes="$(printf '%s' "$stripped" | tr -cd ')' | wc -c | tr -d ' ')"
+  quotes="$(printf '%s' "$stripped" | tr -cd "\047" | wc -c | tr -d ' ')"
+  if [ "$opens" != "$closes" ]; then
+    err "$f: unbalanced parentheses ($opens '(' vs $closes ')')."
+  fi
+  if [ $(( quotes % 2 )) -ne 0 ]; then
+    err "$f: unbalanced single-quotes after stripping comments/literals."
+  fi
+done
+
+# --- per-config-file checks -------------------------------------------------------------------
+for f in ${CNF_FILES[@]+"${CNF_FILES[@]}"}; do
+  if grep -Eiq '^[[:space:]]*binlog_format[[:space:]]*=[[:space:]]*STATEMENT' "$f"; then
+    err "$f: binlog_format = STATEMENT — non-deterministic statements drift on replicas. Use ROW."
+  fi
+  if grep -Eiq '^[[:space:]]*default_authentication_plugin[[:space:]]*=[[:space:]]*mysql_native_password' "$f"; then
+    note "$f: default_authentication_plugin = mysql_native_password — disabled by default in 8.4, removed in 9.0. Use caching_sha2_password + TLS."
+  fi
+done
+
+# --- optional sqlfluff --------------------------------------------------------------------------
+if [ "${#SQL_FILES[@]}" -gt 0 ]; then
+  if command -v sqlfluff >/dev/null 2>&1; then
+    if sqlfluff lint --dialect mysql ${SQL_FILES[@]+"${SQL_FILES[@]}"} >/dev/null 2>&1; then
+      ok "sqlfluff (dialect mysql): no lint errors"
+    else
+      err "sqlfluff (dialect mysql) reported lint errors — run: sqlfluff lint --dialect mysql <file>"
+    fi
+  else
+    skip "sqlfluff not installed — skipping SQL lint (advisory)"
+  fi
+fi
+
+if [ "$EXIT" -eq 0 ]; then
+  ok "verify passed (advisory warnings, if any, are non-blocking)"
+fi
+exit "$EXIT"