@pageai/ralph-loop 1.8.0 → 1.10.0

package/.agent/PROMPT.md

@@ -34,10 +34,11 @@ Tasks are listed in @.agent/tasks.json
 
 ## Rules
 
-- **IMPORTANT**: only work on one task at a time and **exit closing all background processes**. **DO NOT** start another task.
+- **CRITICAL**: Only work on **ONE task per invocation**. After committing the task, output `<promise>TASK-{ID}:DONE</promise>` and **STOP immediately**. Do NOT read the next task. Do NOT continue working. Your response **must END** after the promise tag. Any output after it is a violation.
+- Kill all background processes (dev server, etc.) before outputting the promise tag.
 - No git init/remote changes. **No git push**.
 - Check the last 5 tasks in `.agent/logs/LOG.md` for past work
-- **CRITICAL**: When ALL tasks pass → output `<promise>COMPLETE</promise>` and **nothing else**.
+- **CRITICAL**: When **ALL** tasks pass → output `<promise>COMPLETE</promise>` and **nothing else**.
 
 ## Help Tags
 

package/.agents/skills/mysql/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: mysql
+description: Plan and review MySQL/InnoDB schema, indexing, query tuning, transactions, and operations. Use when creating or modifying MySQL tables, indexes, or queries; diagnosing slow/locking behavior; planning migrations; or troubleshooting replication and connection issues. Load when using a MySQL database.
+---
+
+# MySQL
+
+Use this skill to make safe, measurable MySQL/InnoDB changes.
+
+## Workflow
+1. Define workload and constraints (read/write mix, latency target, data volume, MySQL version, hosting platform).
+2. Read only the relevant reference files linked in each section below.
+3. Propose the smallest change that can solve the problem, including trade-offs.
+4. Validate with evidence (`EXPLAIN`, `EXPLAIN ANALYZE`, lock/connection metrics, and production-safe rollout steps).
+5. For production changes, include rollback and post-deploy verification.
+
+## Schema Design
+- Prefer narrow, monotonic PKs (`BIGINT UNSIGNED AUTO_INCREMENT`) for write-heavy OLTP tables.
+- Avoid random UUID values as clustered PKs; if external IDs are required, keep UUID in a secondary unique column.
+- Always `utf8mb4` / `utf8mb4_0900_ai_ci`. Prefer `NOT NULL`, `DATETIME` over `TIMESTAMP`.
+- Lookup tables over `ENUM`. Normalize to 3NF; denormalize only for measured hot paths.
+
+References:
+- [primary-keys](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/mysql/references/primary-keys.md)
+- [data-types](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/mysql/references/data-types.md)
+- [character-sets](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/mysql/references/character-sets.md)
+- [json-column-patterns](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/mysql/references/json-column-patterns.md)
+
+## Indexing
+- Composite order: equality first, then range/sort (leftmost prefix rule).
+- Range predicates stop index usage for subsequent columns.
+- Secondary indexes include PK implicitly. Prefix indexes for long strings.
+- Audit via `performance_schema` — drop indexes with `count_read = 0`.
+
+References:
+- [composite-indexes](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/mysql/references/composite-indexes.md)
+- [covering-indexes](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/mysql/references/covering-indexes.md)
+- [fulltext-indexes](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/mysql/references/fulltext-indexes.md)
+- [index-maintenance](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/mysql/references/index-maintenance.md)
+
+## Partitioning
+- Partition time-series (>50M rows) or large tables (>100M rows). Plan early — retrofit = full rebuild.
+- Include partition column in every unique/PK. Always add a `MAXVALUE` catch-all.
+
+References:
+- [partitioning](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/mysql/references/partitioning.md)
+
+## Query Optimization
+- Check `EXPLAIN` — red flags: `type: ALL`, `Using filesort`, `Using temporary`.
+- Cursor pagination, not `OFFSET`. Avoid functions on indexed columns in `WHERE`.
+- Batch inserts (500–5000 rows). `UNION ALL` over `UNION` when dedup unnecessary.
+
+References:
+- [explain-analysis](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/mysql/references/explain-analysis.md)
+- [query-optimization-pitfalls](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/mysql/references/query-optimization-pitfalls.md)
+- [n-plus-one](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/mysql/references/n-plus-one.md)
+
+## Transactions & Locking
+- Default: `REPEATABLE READ` (gap locks). Use `READ COMMITTED` for high contention.
+- Consistent row access order prevents deadlocks. Retry error 1213 with backoff.
+- Do I/O outside transactions. Use `SELECT ... FOR UPDATE` sparingly.
+
+References:
+- [isolation-levels](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/mysql/references/isolation-levels.md)
+- [deadlocks](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/mysql/references/deadlocks.md)
+- [row-locking-gotchas](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/mysql/references/row-locking-gotchas.md)
+
+## Operations
+- Use online DDL (`ALGORITHM=INPLACE`) when possible; test on replicas first.
+- Tune connection pooling — avoid `max_connections` exhaustion under load.
+- Monitor replication lag; avoid stale reads from replicas during writes.
+
+References:
+- [online-ddl](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/mysql/references/online-ddl.md)
+- [connection-management](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/mysql/references/connection-management.md)
+- [replication-lag](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/mysql/references/replication-lag.md)
+
+## Guardrails
+- Prefer measured evidence over blanket rules of thumb.
+- Note MySQL-version-specific behavior when giving advice.
+- Ask for explicit human approval before destructive data operations (drops/deletes/truncates).

package/.agents/skills/mysql/references/character-sets.md

@@ -0,0 +1,66 @@
+---
+title: Character Sets and Collations
+description: Charset config guide
+tags: mysql, character-sets, utf8mb4, collation, encoding
+---
+
+# Character Sets and Collations
+
+## Always Use utf8mb4
+MySQL's `utf8` = `utf8mb3` (3-byte only, no emoji/many CJK). Always `utf8mb4`.
+
+```sql
+CREATE DATABASE myapp DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
+```
+
+## Collation Quick Reference
+| Collation | Behavior | Use for |
+|---|---|---|
+| `utf8mb4_0900_ai_ci` | Case-insensitive, accent-insensitive | Default |
+| `utf8mb4_0900_as_cs` | Case/accent sensitive | Exact matching |
+| `utf8mb4_bin` | Byte-by-byte comparison | Tokens, hashes |
+
+`_0900_` = Unicode 9.0 (preferred over older `_unicode_` variants).
+
+## Collation Behavior
+
+Collations affect string comparisons, sorting (`ORDER BY`), and pattern matching (`LIKE`):
+
+- **Case-insensitive (`_ci`)**: `'A' = 'a'` evaluates to true, `LIKE 'a%'` matches 'Apple'
+- **Case-sensitive (`_cs`)**: `'A' = 'a'` evaluates to false, `LIKE 'a%'` matches only lowercase
+- **Accent-insensitive (`_ai`)**: `'e' = 'é'` evaluates to true
+- **Accent-sensitive (`_as`)**: `'e' = 'é'` evaluates to false
+- **Binary (`_bin`)**: strict byte-by-byte comparison (most restrictive)
+
+You can override collation per query:
+
+```sql
+SELECT * FROM users
+WHERE name COLLATE utf8mb4_0900_as_cs = 'José';
+```
+
+## Migrating from utf8/utf8mb3
+
+```sql
+-- Find columns still using utf8
+SELECT table_name, column_name FROM information_schema.columns
+WHERE table_schema = 'mydb' AND character_set_name = 'utf8';
+-- Convert
+ALTER TABLE users CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
+```
+
+**Warning**: index key length limits depend on InnoDB row format:
+- DYNAMIC/COMPRESSED: 3072 bytes max (≈768 chars with utf8mb4)
+- REDUNDANT/COMPACT: 767 bytes max (≈191 chars with utf8mb4)
+
+`VARCHAR(255)` with utf8mb4 = up to 1020 bytes (4×255). That's safe for DYNAMIC/COMPRESSED but exceeds REDUNDANT/COMPACT limits.
+
+## Connection
+Ensure client uses `utf8mb4`: `SET NAMES utf8mb4;` (most modern drivers default to this).
+
+`SET NAMES utf8mb4` sets three session variables:
+- `character_set_client` (encoding for statements sent to server)
+- `character_set_connection` (encoding for statement processing)
+- `character_set_results` (encoding for results sent to client)
+
+It also sets `collation_connection` to the default collation for utf8mb4.

package/.agents/skills/mysql/references/composite-indexes.md

@@ -0,0 +1,59 @@
+---
+title: Composite Index Design
+description: Multi-column indexes
+tags: mysql, indexes, composite, query-optimization, leftmost-prefix
+---
+
+# Composite Indexes
+
+## Leftmost Prefix Rule
+Index `(a, b, c)` is usable for:
+- `WHERE a` (uses column `a`)
+- `WHERE a AND b` (uses columns `a`, `b`)
+- `WHERE a AND b AND c` (uses all columns)
+- `WHERE a AND c` (uses only column `a`; `c` can't filter without `b`)
+
+NOT usable for `WHERE b` alone or `WHERE b AND c` (the search must start from the leftmost column).
+
+## Column Order: Equality First, Then Range/Sort
+
+```sql
+-- Query: WHERE tenant_id = ? AND status = ? AND created_at > ?
+CREATE INDEX idx_orders_tenant_status_created ON orders (tenant_id, status, created_at);
+```
+
+**Critical**: Range predicates (`>`, `<`, `BETWEEN`, `LIKE 'prefix%'`, and sometimes large `IN (...)`) stop index usage for filtering subsequent columns. However, columns after a range predicate can still be useful for:
+- Covering index reads (avoid table lookups)
+- `ORDER BY`/`GROUP BY` in some cases, when the ordering/grouping matches the usable index prefix
+
+## Sort Order Must Match Index
+
+```sql
+-- Index: (status, created_at)
+ORDER BY status ASC, created_at ASC   -- ✓ matches (optimal)
+ORDER BY status DESC, created_at DESC -- ✓ full reverse OK (reverse scan)
+ORDER BY status ASC, created_at DESC  -- ⚠️ mixed directions (may use filesort)
+
+-- MySQL 8.0+: descending index components
+CREATE INDEX idx_orders_status_created ON orders (status ASC, created_at DESC);
+```
+
+## Composite vs Multiple Single-Column Indexes
+MySQL can merge single-column indexes (`index_merge` union/intersection) but a composite index is typically faster. Index merge is useful when queries filter on different column combinations that don't share a common prefix, but it adds overhead and may not scale well under load.
+
+## Selectivity Considerations
+Within equality columns, place higher-cardinality (more selective) columns first when possible. However, query patterns and frequency usually matter more than pure selectivity.
+
+## GROUP BY and Composite Indexes
+`GROUP BY` can benefit from composite indexes when the GROUP BY columns match the index prefix. MySQL may use the index to avoid sorting.
+
+## Design for Multiple Queries
+
+```sql
+-- One index covers: WHERE user_id=?, WHERE user_id=? AND status=?,
+--   and WHERE user_id=? AND status=? ORDER BY created_at DESC
+CREATE INDEX idx_orders_user_status_created ON orders (user_id, status, created_at DESC);
+```
+
+## InnoDB Secondary Index Behavior
+InnoDB secondary indexes implicitly store the primary key value with each index entry. This means a secondary index can sometimes "cover" primary key lookups without adding the PK columns explicitly.

package/.agents/skills/mysql/references/connection-management.md

@@ -0,0 +1,70 @@
+---
+title: Connection Pooling and Limits
+description: Connection management best practices
+tags: mysql, connections, pooling, max-connections, performance
+---
+
+# Connection Management
+
+Every MySQL connection costs memory (~1–10 MB depending on buffers). Unbounded connections cause OOM or `Too many connections` errors.
+
+## Sizing `max_connections`
+Default is 151. Don't blindly raise it — more connections = more memory + more contention.
+
+```sql
+SHOW VARIABLES LIKE 'max_connections';         -- current limit
+SHOW STATUS LIKE 'Max_used_connections';        -- high-water mark
+SHOW STATUS LIKE 'Threads_connected';           -- current count
+```
+
+## Pool Sizing Formula
+A good starting point for OLTP: **pool size = (CPU cores * N)** where N is typically 2-10. This is a baseline — tune based on:
+- Query characteristics (I/O-bound queries may benefit from more connections)
+- Actual connection usage patterns (monitor `Threads_connected` vs `Max_used_connections`)
+- Application concurrency requirements
+
+More connections beyond CPU-bound optimal add context-switch overhead without improving throughput.
+
+## Timeout Tuning
+
+### Idle Connection Timeouts
+```sql
+-- Kill idle connections after 5 minutes (default is 28800 seconds / 8 hours — way too long)
+SET GLOBAL wait_timeout = 300;         -- Non-interactive connections (apps)
+SET GLOBAL interactive_timeout = 300;  -- Interactive connections (CLI)
+```
+
+**Note**: These are server-side timeouts. The server closes idle connections after this period. Client-side connection timeouts (e.g., `connectTimeout` in JDBC) are separate and control connection establishment.
+
+### Active Query Timeouts
+```sql
+-- Increase for bulk operations or large result sets (default: 30 seconds)
+SET GLOBAL net_read_timeout = 60;      -- Time server waits for data from client
+SET GLOBAL net_write_timeout = 60;     -- Time server waits to send data to client
+```
+
+These apply to active data transmission, not idle connections. Increase if you see errors like `Lost connection to MySQL server during query` during bulk inserts or large SELECTs.
+
+## Thread Handling
+MySQL uses a **one-thread-per-connection** model by default: each connection gets its own OS thread. This means `max_connections` directly impacts thread count and memory usage.
+
+MySQL also caches threads for reuse. If connections fluctuate frequently, increase `thread_cache_size` to reduce thread creation overhead.
+
+## Common Pitfalls
+- **ORM default pools too large**: Rails default is 5 per process — 20 Puma workers = 100 connections from one app server. Multiply by app server count.
+- **No pool at all**: PHP/CGI models open a new connection per request. Use persistent connections or ProxySQL.
+- **Connection storms on deploy**: All app servers reconnect simultaneously when restarted, potentially exhausting `max_connections`. Mitigations: stagger deployments, use connection pool warm-up (gradually open connections), or use a proxy layer.
+- **Idle transactions**: Connections with open transactions (`BEGIN` without `COMMIT`/`ROLLBACK`) are **not** closed by `wait_timeout` and hold locks. This causes deadlocks and connection leaks. Always commit or rollback promptly, and use application-level transaction timeouts.
+
+## Prepared Statements
+Use prepared statements with connection pooling for performance and safety:
+- **Performance**: reduces repeated parsing for parameterized queries
+- **Security**: helps prevent SQL injection
+
+Note: prepared statements are typically connection-scoped; some pools/drivers provide statement caching.
+
+## When to Use a Proxy
+Use **ProxySQL** or **PlanetScale connection pooling** when: multiple app services share a DB, you need query routing (read/write split), or total connection demand exceeds safe `max_connections`.
+
+## Vitess / PlanetScale Note
+If running on **PlanetScale** (or Vitess), connection pooling is handled at the Vitess `vtgate` layer. This means your app can open many connections to vtgate without each one mapping 1:1 to a MySQL backend connection. Backend connection issues are minimized under this architecture.

package/.agents/skills/mysql/references/covering-indexes.md

@@ -0,0 +1,47 @@
+---
+title: Covering Indexes
+description: Index-only scans
+tags: mysql, indexes, covering-index, query-optimization, explain
+---
+
+# Covering Indexes
+
+A covering index contains all columns a query needs — InnoDB satisfies it from the index alone (`Using index` in EXPLAIN Extra).
+
+```sql
+-- Query: SELECT user_id, status, total FROM orders WHERE user_id = 42
+-- Covering index (filter columns first, then included columns):
+CREATE INDEX idx_orders_cover ON orders (user_id, status, total);
+```
+
+## InnoDB Implicit Covering
+Because InnoDB secondary indexes store the primary key value with each index entry, `INDEX(status)` already covers `SELECT id FROM t WHERE status = ?` (where `id` is the PK).
+
+## ICP vs Covering Index
+- **ICP (`Using index condition`)**: engine filters at the index level before accessing table rows, but still requires table lookups.
+- **Covering index (`Using index`)**: query is satisfied entirely from the index, with no table lookups.
+
+## EXPLAIN Signals
+Look for `Using index` in the `Extra` column:
+
+```sql
+EXPLAIN SELECT user_id, status, total FROM orders WHERE user_id = 42;
+-- Extra: Using index ✓
+```
+
+If you see `Using index condition` instead, the index is helping but not covering — you may need to add selected columns to the index.
+
+## When to Use
+- High-frequency reads selecting few columns from wide tables.
+- Not worth it for: wide result sets (TEXT/BLOB), write-heavy tables, low-frequency queries.
+
+## Tradeoffs
+- **Write amplification**: every INSERT/UPDATE/DELETE must update all relevant indexes.
+- **Index size**: wide indexes consume more disk and buffer pool memory.
+- **Maintenance**: larger indexes take longer to rebuild during `ALTER TABLE`.
+
+## Guidelines
+- Add columns to existing indexes rather than creating new ones.
+- Order: filter columns first, then additional covered columns.
+- Verify `Using index` appears in EXPLAIN after adding the index.
+- **Pitfall**: `SELECT *` defeats covering indexes — select only the columns you need.

package/.agents/skills/mysql/references/data-types.md

@@ -0,0 +1,69 @@
+---
+title: MySQL Data Type Selection
+description: Data type reference
+tags: mysql, data-types, numeric, varchar, datetime, json
+---
+
+# Data Types
+
+Choose the smallest correct type — more rows per page, better cache, faster queries.
+
+## Numeric Sizes
+| Type | Bytes | Unsigned Max |
+|---|---|---|
+| `TINYINT` | 1 | 255 |
+| `SMALLINT` | 2 | 65,535 |
+| `MEDIUMINT` | 3 | 16.7M |
+| `INT` | 4 | 4.3B |
+| `BIGINT` | 8 | 18.4 quintillion |
+
+Use `BIGINT UNSIGNED` for PKs — `INT` exhausts at ~4.3B rows. Use `DECIMAL(19,4)` for money, never `FLOAT`.
+
+## Strings
+- `VARCHAR(N)` over `TEXT` when bounded — can be indexed directly.
+- **`N` matters**: `VARCHAR(255)` vs `VARCHAR(50)` affects memory allocation for temp tables and sorts.
+
+## TEXT/BLOB Indexing
+- You generally can't index `TEXT`/`BLOB` fully; use prefix indexes: `INDEX(text_col(255))`.
+- Prefix length limits depend on InnoDB row format:
+  - DYNAMIC/COMPRESSED: 3072 bytes max (≈768 chars with utf8mb4)
+  - REDUNDANT/COMPACT: 767 bytes max (≈191 chars with utf8mb4)
+- For keyword search, consider `FULLTEXT` indexes instead of large prefix indexes.
+
+## Date/Time
+- `TIMESTAMP`: 4 bytes, auto-converts timezone, but **2038 limit**. Use `DATETIME` for dates beyond 2038.
+
+```sql
+created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+```
+
+## JSON
+Use for truly dynamic data only. Index JSON values via generated columns:
+
+```sql
+ALTER TABLE products
+  ADD COLUMN color VARCHAR(50) GENERATED ALWAYS AS (attributes->>'$.color') STORED,
+  ADD INDEX idx_color (color);
+```
+
+Prefer simpler types like integers and strings over JSON.
+
+## Generated Columns
+Use generated columns for computed values, JSON extraction, or functional indexing:
+
+```sql
+-- VIRTUAL (default): computed on read, no storage
+ALTER TABLE orders
+  ADD COLUMN total_cents INT GENERATED ALWAYS AS (price_cents * quantity) VIRTUAL;
+
+-- STORED: computed on write, can be indexed
+ALTER TABLE products
+  ADD COLUMN name_lower VARCHAR(255) GENERATED ALWAYS AS (LOWER(name)) STORED,
+  ADD INDEX idx_name_lower (name_lower);
+```
+
+Choose **VIRTUAL** for simple expressions when space matters. Choose **STORED** when indexing is required or the expression is expensive.
+
+## ENUM/SET
+Prefer lookup tables — `ENUM`/`SET` changes require `ALTER TABLE`, which can be slow on large tables.

package/.agents/skills/mysql/references/deadlocks.md

@@ -0,0 +1,72 @@
+---
+title: InnoDB Deadlock Resolution
+description: Deadlock diagnosis
+tags: mysql, deadlocks, innodb, transactions, locking, concurrency
+---
+
+# Deadlocks
+
+InnoDB auto-detects deadlocks and rolls back one transaction (the "victim").
+
+## Common Causes
+1. **Opposite row ordering** — Transactions accessing the same rows in different order can deadlock. Fix: always access rows in a consistent order (typically by primary key or a common index) so locks are acquired in the same sequence.
+2. **Next-key lock conflicts** (REPEATABLE READ) — InnoDB uses next-key locks (row + gap) to prevent phantoms. Fix: use READ COMMITTED (reduces gap locking) or narrow lock scope.
+3. **Missing index on WHERE column** — UPDATE/DELETE without an index may require a full table scan, locking many rows unnecessarily and increasing deadlock risk.
+4. **AUTO_INCREMENT lock contention** — Concurrent INSERT patterns can deadlock while contending on the auto-inc lock. Fix: use `innodb_autoinc_lock_mode=2` (interleaved) for better concurrency when safe for your workload, or batch inserts.
+
+Note: SERIALIZABLE also uses gap/next-key locks. READ COMMITTED reduces some gap-lock deadlocks but doesn't eliminate deadlocks from opposite ordering or missing indexes.
+
+## Diagnosing
+
+```sql
+-- Last deadlock details
+SHOW ENGINE INNODB STATUS\G
+-- Look for "LATEST DETECTED DEADLOCK" section
+
+-- Current lock waits (MySQL 8.0+)
+SELECT object_name, lock_type, lock_mode, lock_status, lock_data
+FROM performance_schema.data_locks WHERE lock_status = 'WAITING';
+
+-- Lock wait relationships (MySQL 8.0+)
+SELECT
+  w.requesting_thread_id,
+  w.requested_lock_id,
+  w.blocking_thread_id,
+  w.blocking_lock_id,
+  l.lock_type,
+  l.lock_mode,
+  l.lock_data
+FROM performance_schema.data_lock_waits w
+JOIN performance_schema.data_locks l ON w.requested_lock_id = l.lock_id;
+```
+
+## Prevention
+- Keep transactions short. Do I/O outside transactions.
+- Ensure WHERE columns in UPDATE/DELETE are indexed.
+- Use `SELECT ... FOR UPDATE` sparingly. Batch large updates with `LIMIT`.
+- Access rows in a consistent order (by PK or index) across all transactions.
+
+## Retry Pattern (Error 1213)
+
+In applications, retries are a common workaround for occasional deadlocks.
+
+**Important**: ensure the operation is idempotent (or can be safely retried) before adding automatic retries, especially if there are side effects outside the database.
+
+```pseudocode
+def execute_with_retry(db, fn, max_retries=3):
+    for attempt in range(max_retries):
+        try:
+            with db.begin():
+                return fn()
+        except OperationalError as e:
+            if e.args[0] == 1213 and attempt < max_retries - 1:
+                time.sleep(0.05 * (2 ** attempt))
+                continue
+            raise
+```
+
+## Common Misconceptions
+- **"Deadlocks are bugs"** — deadlocks are a normal part of concurrent systems. The goal is to minimize frequency, not eliminate them entirely.
+- **"READ COMMITTED eliminates deadlocks"** — it reduces gap/next-key lock deadlocks, but deadlocks still happen from opposite ordering, missing indexes, and lock contention.
+- **"All deadlocks are from gap locks"** — many are caused by opposite row ordering even without gap locks.
+- **"Victim selection is random"** — InnoDB generally chooses the transaction with lower rollback cost (fewer rows changed).

package/.agents/skills/mysql/references/explain-analysis.md

@@ -0,0 +1,66 @@
+---
+title: EXPLAIN Plan Analysis
+description: EXPLAIN output guide
+tags: mysql, explain, query-plan, performance, indexes
+---
+
+# EXPLAIN Analysis
+
+```sql
+EXPLAIN SELECT ...;                    -- estimated plan
+EXPLAIN FORMAT=JSON SELECT ...;        -- detailed with cost estimates
+EXPLAIN FORMAT=TREE SELECT ...;        -- tree format (8.0+)
+EXPLAIN ANALYZE SELECT ...;            -- actual execution (8.0.18+, runs the query, uses TREE format)
+```
+
+## Access Types (Best → Worst)
+`system` → `const` → `eq_ref` → `ref` → `range` → `index` (full index scan) → `ALL` (full table scan)
+
+Target `ref` or better. `ALL` on >1000 rows almost always needs an index.
+
+## Key Extra Flags
+| Flag | Meaning | Action |
+|---|---|---|
+| `Using index` | Covering index (optimal) | None |
+| `Using filesort` | Sort not via index | Index the ORDER BY columns |
+| `Using temporary` | Temp table for GROUP BY | Index the grouped columns |
+| `Using join buffer` | No index on join column | Add index on join column |
+| `Using index condition` | ICP — engine filters at index level | Generally good |
+
+## key_len — How Much of Composite Index Is Used
+Byte sizes: `TINYINT`=1, `INT`=4, `BIGINT`=8, `DATE`=3, `DATETIME`=5, `VARCHAR(N)` utf8mb4: N×4+1 (or +2 when N×4>255). Add 1 byte per nullable column.
+
+```sql
+-- Index: (status TINYINT, created_at DATETIME)
+-- key_len=2 → only status (1+1 null). key_len=8 → both columns used.
+```
+
+## rows vs filtered
+- `rows`: estimated rows examined after index access (before additional WHERE filtering)
+- `filtered`: percent of examined rows expected to pass the full WHERE conditions
+- Rough estimate of rows that satisfy the query: `rows × filtered / 100`
+- Low `filtered` often means additional (non-indexed) predicates are filtering out lots of rows
+
+## Join Order
+Row order in EXPLAIN output reflects execution order: the first row is typically the first table read, and subsequent rows are joined in order. Use this to spot suboptimal join ordering (e.g., starting with a large table when a selective table could drive the join).
+
+## EXPLAIN ANALYZE
+**Availability:** MySQL 8.0.18+
+
+**Important:** `EXPLAIN ANALYZE` actually executes the query (it does not return the result rows). It uses `FORMAT=TREE` automatically.
+
+**Metrics (TREE output):**
+- `actual time`: milliseconds (startup → end)
+- `rows`: actual rows produced by that iterator
+- `loops`: number of times the iterator ran
+
+Compare estimated vs actual to find optimizer misestimates. Large discrepancies often improve after refreshing statistics:
+
+```sql
+ANALYZE TABLE your_table;
+```
+
+**Limitations / pitfalls:**
+- Adds instrumentation overhead (measurements are not perfectly "free")
+- Cost units (arbitrary) and time (ms) are different; don't compare them directly
+- Results reflect real execution, including buffer pool/cache effects (warm cache can hide I/O problems)

package/.agents/skills/mysql/references/fulltext-indexes.md

@@ -0,0 +1,28 @@
+---
+title: Fulltext Search Indexes
+description: Fulltext index guide
+tags: mysql, fulltext, search, indexes, boolean-mode
+---
+
+# Fulltext Indexes
+
+Fulltext indexes are useful for keyword text search in MySQL. For advanced ranking, fuzzy matching, or complex document search, prefer a dedicated search engine.
+
+```sql
+ALTER TABLE articles ADD FULLTEXT INDEX ft_title_body (title, body);
+
+-- Natural language (default, sorted by relevance)
+SELECT *, MATCH(title, body) AGAINST('database performance') AS score
+FROM articles WHERE MATCH(title, body) AGAINST('database performance');
+
+-- Boolean mode: + required, - excluded, * suffix wildcard, "exact phrase"
+WHERE MATCH(title, body) AGAINST('+mysql -postgres +optim*' IN BOOLEAN MODE);
+```
+
+## Key Gotchas
+- **Min word length**: default 3 chars (`innodb_ft_min_token_size`). Shorter words are ignored. Changing this requires rebuilding the FULLTEXT index (drop/recreate) to take effect.
+- **Stopwords**: common words excluded. Control stopwords with `innodb_ft_enable_stopword` and customize via `innodb_ft_user_stopword_table` / `innodb_ft_server_stopword_table` (set before creating the index, then rebuild to apply changes).
+- **No partial matching**: unlike `LIKE '%term%'`, requires whole tokens (except `*` in boolean mode).
+- **MATCH() columns must correspond to an index definition**: `MATCH(title, body)` needs a FULLTEXT index that covers the same column set (e.g. `(title, body)`).
+- Boolean mode without required terms (no leading `+`) can match a very large portion of the index and be slow.
+- Fulltext adds write overhead — consider Elasticsearch/Meilisearch for complex search needs.