@caddis/cli 0.3.0 → 0.4.0

package/bundles/codex/.codex/skills/coding/sql/SKILL.md

@@ -0,0 +1,321 @@
+---
+name: sql
+description: Write high-quality, optimized SQL with best practices for performance, NULL handling, security, and readability. Database-agnostic patterns with dialect-specific notes.
+---
+
+# SQL Expert Skill
+
+Write high-quality, optimized SQL for enterprise environments. Covers performance, edge cases, and real-world gotchas.
+
+## When to Use
+
+- Writing new SQL queries
+- Optimizing existing queries
+- Handling large datasets (100K+ rows)
+- Creating stored procedures or views
+- Debugging slow queries
+
+---
+
+## SQL Quality Standards
+
+### 1. Always Include Comments
+
+```sql
+-- Get open orders with SLA breach risk
+-- Filters: Last 7 days, excludes test data
+-- Expected rows: ~500-2000
+SELECT
+    OrderID,
+    CustomerName,
+    DATEDIFF(HOUR, CreatedAt, GETDATE()) AS hours_open
+FROM Orders
+WHERE CreatedAt >= DATEADD(DAY, -7, GETDATE())
+    AND Status = 'Open'
+ORDER BY hours_open DESC;
+```
+
+### 2. Readable Formatting
+
+```sql
+SELECT
+    o.OrderID,
+    o.CustomerName,
+    o.Status,
+    COUNT(i.ItemID) AS item_count
+FROM Orders o
+LEFT JOIN OrderItems i ON o.OrderID = i.OrderID
+WHERE o.Status = 'Open'
+GROUP BY o.OrderID, o.CustomerName, o.Status
+HAVING COUNT(i.ItemID) > 0
+ORDER BY item_count DESC;
+```
+
+---
+
+## Large Dataset Patterns
+
+### Pagination
+
+```sql
+-- OFFSET-FETCH (SQL Server 2012+ / PostgreSQL)
+SELECT OrderID, CustomerName, Status
+FROM Orders
+WHERE Status = 'Open'
+ORDER BY CreatedAt DESC
+OFFSET 50 ROWS FETCH NEXT 25 ROWS ONLY;
+
+-- Keyset pagination (faster for deep pages)
+SELECT TOP 25 OrderID, CustomerName, CreatedAt
+FROM Orders
+WHERE CreatedAt < @lastSeenDate AND Status = 'Open'
+ORDER BY CreatedAt DESC;
+```
+
+### Batching Large Operations
+
+```sql
+DECLARE @BatchSize INT = 5000;
+DECLARE @RowsAffected INT = 1;
+
+WHILE @RowsAffected > 0
+BEGIN
+    UPDATE TOP (@BatchSize) Orders
+    SET ProcessedFlag = 1
+    WHERE Status = 'Closed' AND ProcessedFlag = 0;
+    SET @RowsAffected = @@ROWCOUNT;
+    WAITFOR DELAY '00:00:00.100';
+END
+```
+
+---
+
+## NULL Handling
+
+```sql
+-- Use IS NULL (not = NULL)
+SELECT * FROM Orders WHERE Category IS NULL;
+
+-- ISNULL (SQL Server) vs COALESCE (ANSI standard)
+SELECT ISNULL(Category, 'Unknown') FROM Orders;
+SELECT COALESCE(Category, SubCategory, 'Unknown') FROM Orders;
+
+-- NULL in aggregations: COUNT(*) counts all, COUNT(col) excludes NULLs
+SELECT COUNT(*) AS total, COUNT(Category) AS non_null FROM Orders;
+SELECT ISNULL(SUM(Amount), 0) AS total FROM Orders;
+```
+
+---
+
+## Performance Killers to Avoid
+
+1. **Implicit type conversions** -- match parameter types to column types
+2. **Functions on indexed columns** -- rewrite `WHERE YEAR(date) = 2026` as range
+3. **OR conditions** -- consider UNION ALL for index use
+4. **SELECT DISTINCT on large sets** -- use GROUP BY or EXISTS
+5. **UNION vs UNION ALL** -- use UNION ALL when duplicates are OK
+
+---
+
+## Window Functions
+
+```sql
+-- Running totals
+SELECT OrderID, CreatedAt,
+    COUNT(*) OVER (ORDER BY CreatedAt) AS running_count,
+    SUM(Amount) OVER (ORDER BY CreatedAt) AS running_total
+FROM Orders;
+
+-- Latest record per group
+WITH ranked AS (
+    SELECT *, ROW_NUMBER() OVER (PARTITION BY CustomerID ORDER BY CreatedAt DESC) AS rn
+    FROM Orders
+)
+SELECT * FROM ranked WHERE rn = 1;
+```
+
+---
+
+## Error Handling
+
+```sql
+BEGIN TRY
+    BEGIN TRANSACTION;
+    UPDATE Orders SET Status = 'Processed' WHERE OrderID = @OrderID;
+    IF @@ROWCOUNT = 0 THROW 50001, 'Order not found', 1;
+    COMMIT;
+END TRY
+BEGIN CATCH
+    IF @@TRANCOUNT > 0 ROLLBACK;
+    DECLARE @ErrorMsg NVARCHAR(4000) = ERROR_MESSAGE();
+    RAISERROR(@ErrorMsg, ERROR_SEVERITY(), ERROR_STATE());
+END CATCH;
+```
+
+---
+
+## Security (CRITICAL)
+
+```sql
+-- NEVER concatenate user input
+-- Always use parameterized queries
+EXEC sp_executesql N'SELECT * FROM Orders WHERE OrderID = @id',
+    N'@id UNIQUEIDENTIFIER', @id = @orderId;
+```
+
+```python
+# Python: always parameterized
+query = "SELECT * FROM Orders WHERE Status = ?"
+result = adapter.fetch_dataframe(query, (user_input,))
+```
+
+---
+
+## EXISTS vs IN vs JOIN
+
+```sql
+-- EXISTS: Best for "does any match exist?" - stops at first match
+SELECT * FROM Customers c
+WHERE EXISTS (SELECT 1 FROM Orders WHERE CustomerID = c.CustomerID);
+
+-- IN: Good for small lists, can be slow with NULLs in subquery
+SELECT * FROM Orders WHERE CustomerID IN ('CUST001', 'CUST002', 'CUST003');
+
+-- ⚠️ IN with subquery containing NULLs can return unexpected results
+SELECT * FROM Orders 
+WHERE CustomerID IN (SELECT CustomerID FROM FlaggedCustomers);  -- If NULL in subquery, watch out!
+
+-- JOIN: Best when you need columns from both tables
+SELECT c.*, o.OrderID
+FROM Customers c
+INNER JOIN Orders o ON c.CustomerID = o.CustomerID;
+```
+
+---
+
+## Concurrency & Locking
+
+### Read Patterns
+
+```sql
+-- For reports/dashboards (OK with slightly stale data)
+SELECT * FROM Orders WITH (NOLOCK)  -- Dirty reads, but no blocking
+WHERE Status = 'Open';
+
+-- ⚠️ NOLOCK risks:
+-- - Can read uncommitted data (that might roll back)
+-- - Can read rows twice or skip rows during scans
+-- Only use for approximate counts, dashboards, reports
+
+-- For accurate reads that shouldn't block
+SET TRANSACTION ISOLATION LEVEL READ COMMITTED SNAPSHOT;
+-- Requires database setting: ALTER DATABASE [DB] SET READ_COMMITTED_SNAPSHOT ON;
+```
+
+### Deadlock Prevention
+
+```sql
+-- ✅ Always access tables in same order across all processes
+-- ✅ Keep transactions short
+
+BEGIN TRANSACTION;
+    UPDATE Orders SET Status = 'Processed' WHERE OrderID = @id;
+COMMIT;
+```
+
+---
+
+## Temp Tables vs Table Variables
+
+```sql
+-- TEMP TABLES: Better for large datasets (has statistics)
+CREATE TABLE #TempOrders (
+    OrderID VARCHAR(50),
+    CustomerID VARCHAR(50),
+    INDEX IX_Temp_CustomerID (CustomerID)
+);
+INSERT INTO #TempOrders SELECT OrderID, CustomerID FROM Orders WHERE Status = 'Open';
+SELECT * FROM #TempOrders t JOIN Customers c ON t.CustomerID = c.CustomerID;
+DROP TABLE #TempOrders;
+
+-- TABLE VARIABLES: Better for small datasets (<1000 rows)
+DECLARE @Orders TABLE (OrderID VARCHAR(50), CustomerID VARCHAR(50));
+INSERT INTO @Orders SELECT OrderID, CustomerID FROM Orders WHERE Status = 'Closed';
+-- ⚠️ Table variables assume 1 row for optimization - bad for large sets
+```
+
+---
+
+## Date/Time Gotchas
+
+```sql
+-- ❌ BAD: String comparison for dates (locale issues)
+SELECT * FROM Orders WHERE CreatedAt > '01/02/2026';  -- Jan 2 or Feb 1?
+
+-- ✅ GOOD: Use unambiguous ISO format
+SELECT * FROM Orders WHERE CreatedAt > '2026-01-02';
+
+-- Date range queries (include full day)
+-- ❌ WRONG: BETWEEN misses end-of-day records
+SELECT * FROM Orders WHERE CreatedAt BETWEEN '2026-01-01' AND '2026-01-31';
+
+-- ✅ CORRECT: Use < next day
+SELECT * FROM Orders 
+WHERE CreatedAt >= '2026-01-01' AND CreatedAt < '2026-02-01';
+
+-- Get date part only (for grouping)
+SELECT CAST(CreatedAt AS DATE) AS created_date, COUNT(*) AS daily_count
+FROM Orders GROUP BY CAST(CreatedAt AS DATE);
+```
+
+---
+
+## Query Complexity Guidelines
+
+| Guideline | Threshold | If Exceeded |
+|-----------|-----------|-------------|
+| Max JOINs | 3-4 | Create VIEW or break into CTEs |
+| Max subqueries | 2 levels | Use CTEs instead |
+| Max CASE statements | 3-4 | Move logic to application layer |
+| Max columns | 15-20 | Consider if all are needed |
+
+### CTEs for Complex Logic
+
+```sql
+WITH open_orders AS (
+    SELECT OrderID, CustomerID, CreatedAt FROM Orders WHERE Status = 'Open'
+),
+order_metrics AS (
+    SELECT o.OrderID, COUNT(i.ItemID) AS item_count, MAX(i.UpdatedAt) AS last_update
+    FROM open_orders o
+    LEFT JOIN OrderItems i ON o.OrderID = i.OrderID
+    GROUP BY o.OrderID
+)
+SELECT * FROM order_metrics WHERE item_count > 5;
+```
+
+---
+
+## Execution Plan Red Flags
+
+| Warning | Meaning | Fix |
+|---------|---------|-----|
+| Table Scan | No index used | Add index or fix WHERE clause |
+| Key Lookup | Extra I/O for non-covered columns | Add columns to index or use covering index |
+| CONVERT_IMPLICIT | Type mismatch causing conversion | Match parameter types to column types |
+| Sort (high cost) | Sorting large dataset | Add index that matches ORDER BY |
+| Hash Match | Large join, possibly missing index | Add indexes on join columns |
+| Parallelism | Query is complex/large | May be OK, but check if needed |
+
+---
+
+## Performance Checklist
+
+- [ ] Only selecting needed columns (no SELECT *)
+- [ ] Filtering in WHERE, not application code
+- [ ] JOINs on indexed columns
+- [ ] No functions on indexed columns in WHERE
+- [ ] Types match (no implicit conversions)
+- [ ] Parameterized (no string concatenation)
+- [ ] Pagination for large result sets
+- [ ] Comments explain purpose and expected volume

package/bundles/codex/.codex/skills/data/database-design/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: database-design
+description: Database schema design, optimization, and migration patterns for PostgreSQL, MySQL, and NoSQL databases. Use for designing schemas, writing migrations, or optimizing queries.
+source: wshobson/agents
+license: MIT
+---
+
+# Database Design
+
+## Schema Design Principles
+
+### Normalization Guidelines
+```sql
+-- 1NF: Atomic values, no repeating groups
+-- 2NF: No partial dependencies on composite keys
+-- 3NF: No transitive dependencies
+
+-- Users table (normalized)
+CREATE TABLE users (
+  id SERIAL PRIMARY KEY,
+  email VARCHAR(255) UNIQUE NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Addresses table (separate entity)
+CREATE TABLE addresses (
+  id SERIAL PRIMARY KEY,
+  user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
+  street VARCHAR(255),
+  city VARCHAR(100),
+  country VARCHAR(100),
+  is_primary BOOLEAN DEFAULT false
+);
+```
+
+### Denormalization for Performance
+```sql
+-- When read performance matters more than write consistency
+CREATE TABLE order_summaries (
+  id SERIAL PRIMARY KEY,
+  order_id INTEGER REFERENCES orders(id),
+  customer_name VARCHAR(255),  -- Denormalized from customers
+  total_amount DECIMAL(10,2),
+  item_count INTEGER,
+  last_updated TIMESTAMPTZ DEFAULT NOW()
+);
+```
+
+## Index Design
+
+### Common Index Patterns
+```sql
+-- B-tree (default) for equality and range queries
+CREATE INDEX idx_users_email ON users(email);
+
+-- Composite index (order matters!)
+CREATE INDEX idx_orders_user_date ON orders(user_id, created_at DESC);
+
+-- Partial index for specific conditions
+CREATE INDEX idx_active_users ON users(email) WHERE deleted_at IS NULL;
+
+-- GIN index for array/JSONB columns
+CREATE INDEX idx_posts_tags ON posts USING GIN(tags);
+
+-- Covering index (includes additional columns)
+CREATE INDEX idx_orders_covering ON orders(user_id) INCLUDE (total, status);
+```
+
+### Index Analysis
+```sql
+-- Check index usage
+SELECT
+  schemaname, tablename, indexname,
+  idx_scan, idx_tup_read, idx_tup_fetch
+FROM pg_stat_user_indexes
+ORDER BY idx_scan DESC;
+
+-- Find missing indexes
+SELECT
+  relname, seq_scan, seq_tup_read,
+  idx_scan, idx_tup_fetch
+FROM pg_stat_user_tables
+WHERE seq_scan > idx_scan
+ORDER BY seq_tup_read DESC;
+```
+
+## Migration Patterns
+
+### Safe Migration Template
+```sql
+-- Always use transactions
+BEGIN;
+
+-- Add column with default (non-blocking in PG 11+)
+ALTER TABLE users ADD COLUMN status VARCHAR(20) DEFAULT 'active';
+
+-- Create index concurrently (doesn't lock table)
+CREATE INDEX CONCURRENTLY idx_users_status ON users(status);
+
+-- Backfill data in batches
+UPDATE users SET status = 'active' WHERE status IS NULL AND id BETWEEN 1 AND 10000;
+
+COMMIT;
+```
+
+### Zero-Downtime Migrations
+```
+1. Add new column (nullable)
+2. Deploy code that writes to both columns
+3. Backfill old data
+4. Deploy code that reads from new column
+5. Remove old column
+```
+
+## Query Optimization
+
+### EXPLAIN Analysis
+```sql
+-- Always use EXPLAIN ANALYZE
+EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
+SELECT * FROM orders WHERE user_id = 123 AND status = 'pending';
+
+-- Key metrics to watch:
+-- - Seq Scan vs Index Scan
+-- - Actual rows vs Estimated rows
+-- - Buffers: shared hit vs read
+```
+
+### Common Optimizations
+```sql
+-- Use EXISTS instead of IN for large sets
+SELECT * FROM users u
+WHERE EXISTS (SELECT 1 FROM orders o WHERE o.user_id = u.id);
+
+-- Pagination with keyset (cursor) instead of OFFSET
+SELECT * FROM posts
+WHERE created_at < '2024-01-01'
+ORDER BY created_at DESC
+LIMIT 20;
+
+-- Use CTEs for complex queries
+WITH active_users AS (
+  SELECT id FROM users WHERE last_login > NOW() - INTERVAL '30 days'
+)
+SELECT * FROM orders WHERE user_id IN (SELECT id FROM active_users);
+```
+
+## Constraints & Data Integrity
+
+```sql
+-- Primary key
+ALTER TABLE users ADD PRIMARY KEY (id);
+
+-- Foreign key with cascade
+ALTER TABLE orders ADD CONSTRAINT fk_orders_user
+  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE;
+
+-- Check constraint
+ALTER TABLE products ADD CONSTRAINT chk_price_positive
+  CHECK (price >= 0);
+
+-- Unique constraint
+ALTER TABLE users ADD CONSTRAINT uniq_users_email UNIQUE (email);
+
+-- Exclusion constraint (no overlapping ranges)
+ALTER TABLE reservations ADD CONSTRAINT excl_no_overlap
+  EXCLUDE USING gist (room_id WITH =, tsrange(start_time, end_time) WITH &&);
+```
+
+## Best Practices
+
+- Use UUIDs for public-facing IDs, SERIAL/BIGSERIAL for internal
+- Always add `created_at` and `updated_at` timestamps
+- Use soft deletes (`deleted_at`) for important data
+- Design for eventual consistency in distributed systems
+- Document schema decisions in migration files
+- Test migrations on production-size data before deploying

package/bundles/codex/.codex/skills/data/db-diagram/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: db-diagram
+context: fork
+description: Turn a SQL artifact — a stored procedure, view, query, .sql file, or table name — into a diagram that explains it to a human. Use when the user says "diagram this query/proc/view/schema", "explain this SQL visually", "draw the ER diagram", "show me the data flow of this stored proc", "/mermaid-db", or "/excalidraw-db". Produces Mermaid (default, git-diffable) or Excalidraw (for design reviews). Read-only — never touches the database.
+---
+
+# db-diagram — explain SQL as a diagram
+
+Take a SQL artifact and produce a diagram that explains it to a human. Two output formats, one shared
+extraction: **Mermaid** (default — plain text, diffs cleanly, renders in VS Code/Gitea, regenerable) and
+**Excalidraw** (for a design review / ARB pack / slide — someone drags boxes around).
+
+The structure is extracted **deterministically** by `scripts/sql_to_graph.py` (a real sqlglot-based
+parser); you (the model) add the **business narration** on top. Never hand-derive the node graph when the
+script can run — its whole value is reproducibility.
+
+## Two non-negotiable safety rules
+
+1. **Never write to the database.** Read-only by definition — no DDL, no DML, not even in a rolled-back
+   transaction. The extractor only ever parses SQL *text*.
+2. **Never guess schema.** Inspect the actual tables/columns before diagramming. If you can't reach the
+   database, diagram only what's provable from the SQL text and **mark inferred elements clearly**.
+
+## Step 1 — get the SQL
+
+Resolve the argument:
+- **A file path** → read that file.
+- **A database object name** (proc/view/table) → look it up. Prefer a registered DB **MCP tool** if one
+  is available in the session; else `sqlcmd`/`psql` **read-only**; else ask the user to paste it. Never
+  guess an object's body.
+- **No argument** → operate on the SQL in the current file/context, or ask.
+- **Multiple objects** → diagram the **relationships between them**, in ONE diagram — not one diagram each.
+
+## Step 2 — run the deterministic extractor
+
+```bash
+python <skill-dir>/scripts/sql_to_graph.py --file <path>                       # Mermaid block (default)
+python <skill-dir>/scripts/sql_to_graph.py --file <path> --format excalidraw   # native .excalidraw JSON
+python <skill-dir>/scripts/sql_to_graph.py --file <path> --format html --title "..."   # self-contained page
+python <skill-dir>/scripts/sql_to_graph.py --file <path> --format svg          # self-contained .svg
+python <skill-dir>/scripts/sql_to_graph.py --sql "<SELECT ...>" --json         # full graph JSON
+```
+All five formats (`mermaid` | `excalidraw` | `svg` | `html` | `json`) come from **one deterministic layout**
+— same SQL always produces byte-identical output, boxes are grid-aligned, and every label is wrapped to fit
+*inside* its box.
+
+**Notation (relational algebra — keep it when narrating):** operations carry the professional symbols
+DB engineers already read — `σ` selection (WHERE), `Σ` aggregation (GROUP BY/HAVING, its own pipeline
+stage), `π` projection (TOP/ORDER BY), `⋈` join (in the joined table's box), `ρ` rename (a CTE),
+`∪`/`∩`/`∖` set operations (annotated on the result). Tables stay symbol-free — the name is the star.
+Palette is the skill's own "jewel on ivory" identity (harbor teal / plum / saffron / madder / ink-blue /
+viridian) — don't restyle it per diagram.
+
+`--dialect` defaults to `tsql`; pass `postgres`/`mysql`/etc. for other engines. Requires `sqlglot`
+(`pip install sqlglot` — pure-Python, no DB driver). **If sqlglot is absent** the script exits with an
+actionable message; then hand-parse the SQL yourself and mark every inferred element (per safety rule 2).
+
+The extractor classifies the input and picks the diagram type:
+
+| Input | Diagram type | Extractor emits |
+|---|---|---|
+| `CREATE TABLE` / schema DDL | `erDiagram` | entities, columns, PK/FK, FK relationships |
+| A query, proc, or CTE chain | `flowchart LR` | a strict pipeline: tables `[(T)]` / CTEs `{{CTE: name}}` → ONE `WHERE` box (all ANDed predicates, one per line) → `result` → projection `[/…/]`; join type+key labels ride on the source edges |
+| An API/service path ending in a DB call | `sequenceDiagram` | *not structural — you build this from the code path; the extractor won't* |
+| A status/lifecycle column | `stateDiagram-v2` | *not structural — you build this from the state values* |
+
+The `sequenceDiagram`/`stateDiagram-v2` cases are judgement, not parsing — build those yourself and say so.
+For the two structural cases, **trust the extractor's graph**; your job is narration, not re-deriving nodes.
+
+The extractor returns `confidence` (`high` | `partial`) and an `inferred` list. If `partial`, the SQL
+couldn't be fully parsed — surface the `inferred` notes in the output and mark those parts.
+
+## Step 3 — wrap it with narration (your job)
+
+Around the extractor's Mermaid block, add:
+- **Above the diagram**: one paragraph explaining what the query/proc is *for* in **business terms** (not
+  a restatement of the SQL — the *why*).
+- **Below the diagram**: a bulleted list of every source table with a **one-line description** of what it
+  holds and why this query touches it. Inspect the real table (MCP/`sqlcmd`) for this — don't invent.
+- **Traceability**: the source file path or object name, and a **generation date**.
+- **This caveat, verbatim:**
+
+  > This diagram shows the SQL as written, not the execution plan. For performance analysis use the
+  > actual execution plan (SSMS Ctrl+M), which reflects what the optimiser actually chose — the two
+  > diverge frequently.
+
+## Step 4 — validate before saving
+
+Malformed Mermaid renders as an error block — worse than no diagram. Before writing:
+- Confirm the diagram **parses** (the extractor already sanitizes labels — no unescaped `"`/`[`/`]` — but
+  if you hand-edited or hand-built the diagram, re-check).
+- Common breakages: unescaped parentheses, quotes, and square brackets inside node labels.
+
+## Output rules — `/mermaid-db` (the default)
+
+- Save as a **`.md`** file. Default path `docs/diagrams/<object-name>.md`, overridable by an argument.
+- **If the file already exists**, diff against it and tell the user *what changed* — don't silently
+  overwrite. (Regenerating on a schema change and showing the delta is the point of Mermaid-as-text.)
+
+## Output rules — `/excalidraw-db` (for human conversation)
+
+Use for a design review / ARB / slide deck. **The extractor emits the `.excalidraw` JSON directly** — run
+`--format excalidraw` and save the output as a `.excalidraw` file. No separate drawing skill, no MCP server.
+The generator already guarantees what a hand-drawn diagram gets wrong.
+
+**Flowchart (query / proc):**
+- **Layout**: a strict left-to-right pipeline — sources → `WHERE` → `result` → projection — on a
+  deterministic grid (same-column boxes share an x; columns balanced on one mid-line). **Edges connect
+  adjacent stages only**, so an arrow can never cross a box; fan-in arrows land on distinct anchor
+  points (never one pile-up).
+- **Arrows carry no text**: each join condition is a `⋈ …` sub-line INSIDE the joined table's box —
+  in a converging fan a floating label always ends up covering some arrow, so text never floats.
+- **One WHERE box**: all ANDed predicates in a single box, one per line — stacked filter boxes read as
+  alternative paths, which is wrong.
+- **Containment**: every label is a container-**bound** text element that auto-wraps and stays vertically
+  centred *inside* its box; box heights are computed from the wrapped line count, so text never overflows.
+
+**ER diagram (schema DDL):**
+- **Header + bullet columns**: each entity renders its name as a distinct **header** (bold, larger, in the
+  role colour, with a divider rule) and every column as a **bullet-list** item (`•  col  type · PK/FK`) —
+  the title never reads as just another column.
+- **Arrows never cross a box**: entities are stacked in one column and every FK is routed as an
+  **orthogonal elbow through a left-side channel** (out the child's edge → down/up its own lane → into
+  the parent's edge). Every segment lives left of the boxes, so on a hub / chain / self-reference the FK
+  arrows can never run through — or hide behind — an intervening box (the old grid+straight-arrow bug).
+  Arrows are painted **on top** so every FK is unmistakably visible.
+
+- **Canvas**: pure white (`#ffffff`) by default, both outputs.
+- **Theme**: Excalidraw `appState.theme` is `"light"` (it re-tints for dark itself if toggled).
+- **Determinism**: fixed ids/seeds — regenerating on a schema change produces a clean diff, not a reshuffle.
+
+Then add the narration around it (business context + per-table descriptions + the execution-plan caveat).
+If someone wants a **shareable, no-app preview**, `--format html` produces a self-contained page (the SVG
+inline + a light/dark toggle) and `--format svg` a standalone SVG. The HTML theme is **fully
+attribute-driven**: an inline head script seeds light/dark from the OS once, both themes are defined under
+`:root[data-theme=…]` with the full variable set, and there is **no `@media` rule** to fight the toggle —
+so the toggle always applies cleanly (no half-applied / black-page state). Zero external requests.
+
+- **Do not maintain both formats for the same artifact.** If a Mermaid diagram already exists for an
+  object and the user runs `/excalidraw-db` on it, say so and ask: a one-off review copy, or a replacement?
+
+## The read-only, never-guess discipline (restated because it matters)
+
+- Never run anything that mutates the DB.
+- Never assert a table's columns or relationships you haven't verified against the real schema; mark
+  anything inferred-from-SQL-text-only.
+- If the extractor's `confidence` is `partial` or sqlglot is unavailable, the diagram is best-effort —
+  say so in the output, don't present it as authoritative.