scrum-skills 0.3.2 → 0.3.3

package/.agents/skills/diagram-design/references/type-data-flow.md

@@ -0,0 +1,371 @@
+# Data Flow
+
+**Best for:** visualising how data moves through a pipeline *across organisational roles* — who initiates, who processes, who publishes, and who consumes. The canonical use case is a multi-role data platform (Admin → Engineers → Scientists → Consumers) with 4–6 process steps. Use when the reader needs to understand **who does what at each stage**, not just the technical components.
+
+Prefer standard **Swimlane** for cross-functional business processes (HR approvals, support tickets). Use **Data flow** when the subject is a data pipeline with typed payloads (raw files, tables, reports) and role-scoped access boundaries.
+
+This type is **parametric** — the inputs schema in §1 drives every coordinate via the formulas in §2. Two generations from the same inputs must produce visually identical SVG.
+
+---
+
+## 1. Inputs — the parameter contract
+
+```yaml
+lanes:                              # 1..4 horizontal swimlanes (top to bottom)
+  - { name: ["DATA", "ADMINS"],     key: "ADM" }
+  - { name: ["DATA", "ENGINEERS"],  key: "ENG" }
+  - { name: ["DATA", "SCIENTISTS"], key: "SCI" }
+  - { name: ["DATA", "CONSUMERS"],  key: "CON" }
+
+steps:                              # 1..6 columns (left to right)
+  - { number: "01", label: "COLLECT" }
+  - { number: "02", label: "STORE" }
+  - { number: "03", label: "TRANSFORM" }
+  - { number: "04", label: "ANALYZE",  focal: true }   # focal step header chip — accent fill
+  - { number: "05", label: "PUBLISH" }
+
+nodes:                              # explicit per-cell entries; empty cells render nothing
+  - { lane: "ADM", step: 0, title: "Project Setup",   sub: "create · assign roles",     tool: "Platform console" }
+  - { lane: "ADM", step: 1, title: "Access Control",  sub: "bucket policies · LDAP",    tool: "MinIO · LDAP console",
+      color: "#b85450" }            # tinted rust-red to flag governance/identity concern
+  - { lane: "ENG", step: 0, title: "Source Ingest",   sub: "ext. sources → raw",        tool: "NiFi · API · SFTP",
+      chips: {in: "WB", out: "DB"} }                    # web payload in, dataset out
+  - { lane: "ENG", step: 1, title: "Raw Store",       sub: "raw landing zones",         tool: "MinIO raw",
+      chips: {in: "DB", out: "DB"} }                    # raw stays raw inside the landing zone
+  - { lane: "ENG", step: 2, title: "Clean & Stage",   sub: "raw → staging → anon",      tool: "NiFi · Trino",
+      chips: {in: "DB", out: "TB"} }                    # raw dataset → analysis-ready table
+  - { lane: "SCI", step: 3, title: "Explore & Model", sub: "anon data → insights",      tool: "JupyterHub · Trino",
+      chips: {in: "TB", out: "FL"}, focal: true }       # focal — table in, file/report out
+  - { lane: "SCI", step: 4, title: "Publish Findings", sub: "models → dashboards",      tool: "Superset · Reports",
+      chips: {in: "FL", out: "FL"} }                    # report in, report out (pass-through to publish)
+  - { lane: "CON", step: 4, title: "Query Insights",   sub: "aggregated views",         tool: "Trino (read-only)",
+      chips: {in: "TB", out: "TB"} }                    # consumers read tables, hand off tables
+
+arrows:                             # explicit edges; styles bind to topology (see §3)
+  - { from: {lane: "ADM", step: 0}, to: {lane: "ADM", step: 1}, style: "muted" }
+  - { from: {lane: "ADM", step: 0}, to: {lane: "ENG", step: 0}, style: "trigger" }   # dashed governance
+  - { from: {lane: "ADM", step: 1}, to: {lane: "ENG", step: 1}, style: "trigger" }
+  - { from: {lane: "ENG", step: 0}, to: {lane: "ENG", step: 1}, style: "muted" }
+  - { from: {lane: "ENG", step: 1}, to: {lane: "ENG", step: 2}, style: "muted" }
+  - { from: {lane: "ENG", step: 2}, to: {lane: "SCI", step: 3}, style: "accent",     # focal cross-role
+      label: "anon data" }
+  - { from: {lane: "SCI", step: 3}, to: {lane: "SCI", step: 4}, style: "muted" }
+  - { from: {lane: "SCI", step: 4}, to: {lane: "CON", step: 4}, style: "link" }     # teal: published
+
+dark: false
+```
+
+**Reserved field semantics:**
+- `lanes[k].key` — the 3-letter role chip text (e.g., `ADM`, `ENG`, `SCI`, `CON`). Used inside every node in that lane.
+- `lanes[k].name` — two-line lane label; both lines use the uppercase `eyebrow` role.
+- `steps[j].focal: true` — exactly **one** step may declare this. Header chip renders in accent.
+- `nodes[i].focal: true` — exactly **one** node may declare this. Renders with accent border (§5).
+- `nodes[i].chips` — data-type chips for the node. Either form accepted:
+  - **Object form (preferred):** `{in: "<CODE>", out: "<CODE>"}` — explicit input/output semantic. Either side optional.
+  - **Array form:** `["<INPUT_CODE>", "<OUTPUT_CODE>"]` — first item is input, second is output.
+  - Codes from §8 (`WB`, `DB`, `TB`, `FL`, `LS`). Position is **fixed**: input chip on the node's bottom-**left**, output chip on the bottom-**right**.
+- `nodes[i].color` — optional **per-node color override**. Any valid `"#hex"` string is accepted; the §4 palette is recommended for cross-diagram consistency but not required. Every node can carry its own color independently of others.
+
+---
+
+## 2. Layout formulas — deterministic geometry
+
+```
+label_col_w      = 140
+step_slot_w      = 112
+right_pad        = 28
+n_steps          = len(steps)
+n_lanes          = len(lanes)
+
+# Canvas
+viewBox_w        = label_col_w + n_steps * step_slot_w + right_pad   # 5 steps → 728
+header_h         = 36
+lane_h           = 80
+has_color_row    = any(node.color or step.color or lane.color in inputs)
+legend_h         = 100 if has_color_row else 80                      # 4 rows when colors are present
+viewBox_h        = header_h + n_lanes * lane_h + legend_h            # 4 lanes, no colors → 436; with colors → 456
+
+# Header strip (top)
+header_y         = 0                                                  # ends at header_h = 36
+step_chip_y      = 6                                                  # 16-px chip at y=6..22
+step_label_y     = 29                                                 # text line below chip
+
+# Lane positions
+lane_y_top(k)    = header_h + k * lane_h                              # 36, 116, 196, 276
+lane_y_mid(k)    = lane_y_top(k) + lane_h/2                           # 76, 156, 236, 316
+lane_label_x     = label_col_w / 2                                    # 70
+
+# Step / node center x
+step_cx(j)       = label_col_w + j * step_slot_w + step_slot_w/2      # 196, 308, 420, 532, 644
+
+# Nodes
+node_w           = 100
+node_h           = 64
+node_x(j)        = step_cx(j) - node_w/2                              # 146, 258, 370, 482, 594
+node_y(k)        = lane_y_top(k) + 8                                  # 44, 124, 204, 284
+
+# Legend strip (bottom)
+legend_y_top     = header_h + n_lanes * lane_h                        # 356
+legend_row_y     = [legend_y_top + 16, legend_y_top + 37, legend_y_top + 59]
+                                                                      # 372, 393, 415
+```
+
+### 2.1 Background structure
+
+- Paper fill across full viewBox.
+- Dot pattern: 22×22 grid, `circle r=0.8`, `fill ink @ 0.10`.
+- Alternating lane tints: odd-indexed lanes (0, 2, …) receive `ink @ 0.018` fill.
+- Lane dividers: horizontal hairlines at every `lane_y_top(k)` and at `legend_y_top`, stroke `ink @ 0.12` width 0.8.
+- Label column right border: vertical hairline at `x = label_col_w`, from `y = header_h` to `y = legend_y_top`.
+
+### 2.2 Step header chip
+
+Per step `j`:
+
+```
+chip_x(j)        = step_cx(j) - 16        # 16×16 chip
+chip_y           = 6
+chip_w           = 32
+chip_h           = 16
+chip_rx          = 8                       # pill-shaped
+number_anchor    = (step_cx(j), 14)
+label_anchor     = (step_cx(j), 29)
+```
+
+Default fill: `ink @ 0.12`, number text ink, label text muted.
+Focal fill: `accent @ 0.20`, number + label text accent.
+Per-step `color` override (§4): replaces the fill with `rgba(C, 0.20)` and the text fill with `C`.
+
+### 2.3 Lane labels
+
+Two-line `eyebrow` role label, both lines uppercase, fill muted:
+- Line 1 at `(lane_label_x, lane_y_mid(k) - 4)`
+- Line 2 at `(lane_label_x, lane_y_mid(k) + 8)`
+
+Per-lane `color` override (§4): replaces the label fill with `C` and the lane tint with `rgba(C, 0.04)` (instead of the default `ink @ 0.018`).
+
+### 2.4 Node content layout (inside the 100×64 rect)
+
+```
+role_chip          rect 18×10 at (node_x+4, node_y+4),  rx=3
+role_chip_text     centered at (node_x+13, node_y+9), eyebrow role, font-size=6, weight=600
+title              centered at (step_cx(j), node_y+23), node-name role, font-size=9
+sub                centered at (step_cx(j), node_y+35), sublabel role, font-size=6.5, muted
+tool               centered at (step_cx(j), node_y+47), sublabel role, font-size=6.5, soft
+data chip IN       rect 16×8 at (node_x+4,   node_y+54), rx=3      # payload type entering the node
+data chip OUT      rect 16×8 at (node_x+80,  node_y+54), rx=3      # payload type leaving the node
+```
+
+Empty cells (no node entry) render **nothing**. No placeholder rect, no role chip, no label — the cell is invisible.
+
+---
+
+## 3. Arrow rules (mandatory)
+
+Four styles, bound to topology. Connectors are drawn **before** all node rects (z-order rule).
+
+| `style` | Stroke | Width | Dash | Marker | When required |
+|---|---|---|---|---|---|
+| `muted` | `muted` | 1.0 | — | `arr-muted` | Standard data hand-off between steps or within a lane. |
+| `trigger` | `muted` | 1.0 | `4,3` | `arr-muted` | Governance trigger — an admin action enables downstream work. Unlabelled. |
+| `accent` | `accent` | 1.2 | — | `arr-accent` | Focal cross-role handoff. **Exactly one per diagram**, labeled. |
+| `link` | `link` | 1.0 | — | `arr-link` | Published / externally-consumed output. |
+
+**Defs block** (required, three markers):
+
+```svg
+<defs>
+  <pattern id="dots" width="22" height="22" patternUnits="userSpaceOnUse">
+    <circle cx="11" cy="11" r="0.8" fill="{ink @ 0.10}"/>
+  </pattern>
+  <marker id="arr-muted"  markerWidth="6" markerHeight="6" refX="5" refY="3" orient="auto"><path d="M0,0 L6,3 L0,6 Z" fill="{muted}"/></marker>
+  <marker id="arr-accent" markerWidth="6" markerHeight="6" refX="5" refY="3" orient="auto"><path d="M0,0 L6,3 L0,6 Z" fill="{accent}"/></marker>
+  <marker id="arr-link"   markerWidth="6" markerHeight="6" refX="5" refY="3" orient="auto"><path d="M0,0 L6,3 L0,6 Z" fill="{link}"/></marker>
+</defs>
+```
+
+### 3.1 Routing rules (non-negotiable)
+
+- **Single-bend routing:** horizontal-first, then vertical. Exit a node from the **right edge**; enter from the **left** (same-lane horizontal) or **top/bottom** (cross-lane vertical).
+- **No diagonals.** Bends use an 8-px Q-bezier corner.
+- **Same-step cross-lane (vertical)**: line directly between `(step_cx(j), lane_y_top(k_to)−12)` and `(step_cx(j), lane_y_top(k_to))`. Used for admin → engineers triggers under the same step.
+- **Cross-lane cross-step (focal)**: exit right, run horizontal past the source node's right edge to a corridor x just before the target's step, then drop vertically.
+- **Labels:** only the `accent` arrow gets a label. Use a paper-filled rect mask (opaque) 6 px behind the text. Other arrows are unlabelled.
+- **Z-order:** all arrows emitted before any node rect (the rect fills mask the line ends inside the node).
+
+---
+
+## 4. Component color override
+
+Any node, lane, or step may declare an optional `color: "#hex"`. Mirrors high-level §3.4 and dp-integration §4 so the rule reads identically across types.
+
+### 4.1 Per-node `color`
+
+Applied to:
+
+| Element | Light | Dark |
+|---|---|---|
+| Container fill (`rect`) | `rgba(C, 0.06)` | `rgba(C_light, 0.10)` |
+| Container stroke | `rgba(C, 0.35)` (stroke-width 1) | `rgba(C_light, 0.45)` |
+| Role chip fill | `rgba(C, 0.18)` | `rgba(C_light, 0.22)` |
+| Role chip text | `C` | `C_light` |
+| Title text | `C` | `C_light` |
+| Sub-label | **unchanged** (muted) | **unchanged** (muted) |
+| Tool label | **unchanged** (soft) | **unchanged** (soft) |
+| Data-type chips | **unchanged** | **unchanged** |
+| Arrows touching this node | **unchanged** — topology-driven | **unchanged** |
+
+`C_light` = the same hex lightened ~15% for dark-mode contrast (e.g., `#b85450` → `#d97a78`).
+
+### 4.2 Per-step `color`
+
+Replaces the step header chip's fill with `rgba(C, 0.20)` and the chip's number + label text fill with `C`. The legend's matching step entry uses the same colors.
+
+### 4.3 Per-lane `color`
+
+Replaces the lane stripe tint with `rgba(C, 0.04)` (only for odd-indexed lanes that receive a tint by default — or extend to all lanes if explicitly chosen) and the lane label text fill with `C`. Use sparingly; lane tints are easy to over-apply.
+
+### 4.4 Rules
+
+- **Never on focal nodes / focal steps.** The accent already carries that signal. A `color` on a focal element is ignored.
+- **Never on arrows.** Arrows are topology-driven. If you want a colored edge, pick a different `style` from §3, not a color override.
+- **Cap at 3 custom-colored elements** per diagram (nodes + lanes + steps combined), in addition to the focal pair (focal node + focal step header). Above 3 the visual signal starts to fragment — if you need more, split the diagram or rethink whether each color carries distinct meaning.
+- **Subtitles and tool labels stay muted.** Only the primary identity (border + role chip + title + icon) carries the color signal.
+
+### 4.5 Semantic palette (recommended)
+
+Same palette as high-level / dp-integration so a reader scanning multiple diagrams sees the same colors meaning the same thing:
+
+- `#b85450` rust-red — Security / Identity / Governance (admin nodes, LDAP, access control)
+- `#5a7d9a` slate-blue — Observability / Quality (monitoring, data-quality gates, lineage)
+- `#7a8c47` olive-green — Governance / Lineage (catalog, metadata)
+- `#8c6d3f` warm-brown — Backup / DR / Archive
+
+---
+
+## 5. Focal rule
+
+The data-flow diagram is built around **one cross-role handoff** that defines its central claim. Three focal slots, exactly one entry each:
+
+- **One focal step** (`steps[j].focal: true`) — typically the analytical pivot (Analyze, Model, …). Header chip and legend chip both render in accent.
+- **One focal node** (`nodes[i].focal: true`) — the node that *receives* the focal handoff. Accent border + accent role chip + ink title.
+- **One focal arrow** (`arrows[i].style: "accent"`) — the cross-role handoff into the focal node. Solid accent stroke + labeled with a short payload descriptor (e.g., `anon data`).
+
+If zero or >1 of any focal slot are declared, halt and ask the user.
+
+---
+
+## 6. Dark mode
+
+| Token | Light | Dark |
+|---|---|---|
+| Paper | `paper` | `ink` |
+| Ink | `ink` | `paper` |
+| Muted | `muted` | `soft` |
+| Soft | `soft` | `rule-solid` |
+| Accent | `accent` | `accent` |
+| Link | `link` | `link` |
+| Dot pattern | `ink @ 0.10` | `paper @ 0.10` |
+| Lane tint | `ink @ 0.018` | `paper @ 0.025` |
+| Dividers | `ink @ 0.12` | `paper @ 0.12` |
+| Default chip fill | `ink @ 0.12` | `paper @ 0.12` |
+| Focal chip fill | `accent @ 0.20` | `accent @ 0.22` |
+| Default node fill | `paper` | `paper @ 0.04` |
+| Default node stroke | `ink @ 0.25` | `paper @ 0.20` |
+| Focal node fill | `accent @ 0.07` | `accent @ 0.12` |
+| Focal node stroke | `accent` | `accent` |
+| Custom component colors | `C` | `C_light` (lighten ~15%) |
+
+---
+
+## 7. Reproducibility checklist (taste gate)
+
+Before emitting SVG, verify **every** item:
+
+1. `viewBox = "0 0 {viewBox_w} {viewBox_h}"` derived from `n_steps` and `n_lanes` via §2.
+2. Header strip at `y=0..36`; legend strip at `y=legend_y_top..viewBox_h` (`legend_y_top = 36 + n_lanes * 80`).
+3. Every node at `(step_cx(j) - 50, lane_y_top(k) + 8)` size `100×64`.
+4. Empty cells render nothing — no placeholder rect, no text.
+5. Exactly **one** focal step (`steps[j].focal: true`).
+6. Exactly **one** focal node (`nodes[i].focal: true`).
+7. Exactly **one** focal arrow (`style: accent`). Labeled, with a paper-masked rect behind the label.
+8. All other arrows unlabelled.
+9. All arrows emitted before any node rect (z-order rule).
+10. Single-bend routing only — no diagonals. Q-bezier `r=8` at each bend.
+11. Custom component colors ≤ 3 (in addition to the focal pair). Arrows never recolored by component `color`.
+12. Subtitle and tool labels stay muted regardless of any component `color`.
+
+---
+
+## 8. Data-type chips reference (input + output)
+
+Small `16×8 rx=3` badges at the bottom of each node, one for input and one for output. Position is **non-negotiable**:
+
+- **Input chip** at `(node_x+4, node_y+54)` — bottom-**left** of the node. Represents the payload format *entering* the node from upstream.
+- **Output chip** at `(node_x+80, node_y+54)` — bottom-**right** of the node. Represents the payload format *leaving* the node toward downstream.
+
+Either chip may be omitted (e.g., a sink node has only an input chip; a source-only node has only an output chip). Reading the diagram becomes a payload-transformation trace: scan a row, read each node's input → output, and you see exactly what shape the data takes at each hand-off.
+
+### Chip codes
+
+| Code | Color | Meaning |
+|------|-------|---------|
+| `WB` | `#6e6479` (mauve) | Web / Public data |
+| `DB` | `#5e7a9b` (steel-blue) | Dataset / Raw file |
+| `TB` | `#b8915a` (amber) | Table / Analysis-ready |
+| `FL` | `#9c6b50` (sienna) | File / Report / Export |
+| `LS` | `#4a7c59` (forest) | Live stream / Event |
+
+Text inside chip: white, `eyebrow` role at 5px, weight 700.
+
+Data-type chip colors are a **separate semantic axis** from the per-node color override (§4). The chip colors describe *payload format*; the node color override describes *concern type* (governance, observability, …). Don't conflate them — a node can have both an `out: TB` amber chip and a rust-red border color simultaneously.
+
+---
+
+## 9. Legend (3- or 4-row strip)
+
+Each row introduced by a category label at `x=144`. The default legend has **3 rows** (`STEPS` / `DATA TYPE` / `FLOW`); when one or more nodes carry a `color` override (§4), add a 4th `CONCERN` row and grow `legend_h` to 100 (so `viewBox_h = header_h + n_lanes·80 + 100`).
+
+- **Row 1 — `STEPS`** at `y = legend_y_top + 16`: repeat the header chips with their labels. Focal step keeps accent fill.
+- **Row 2 — `DATA TYPE`** at `y = legend_y_top + 37`: one swatch per chip type actually used in the diagram. **Append a small sub-hint** in the muted `sublabel` role after the chips: `left chip = input · right chip = output`. This makes the position-based input/output convention explicit for first-time readers.
+- **Row 3 — `CONCERN`** (only when color overrides are present) at `y = legend_y_top + 58`: one mini-rect per custom color used, with its semantic label (e.g., `Identity · Governance`, `Data Quality · Observability`). The focal accent swatch is also shown here so the reader sees all three colored axes side-by-side.
+- **Row 4 — `FLOW`** (last row, position depends on whether `CONCERN` row exists): short line segments with their marker + text label, one per arrow style actually used.
+
+All legend items align on a single horizontal strip per row. Do not stack vertically inside a box.
+
+---
+
+## 10. Complexity budget
+
+| Dimension | Max |
+|---|---|
+| Lanes (roles) | 4 |
+| Steps | 6 |
+| Nodes per lane | Nodes = active steps only — empty cells are invisible (no placeholder box) |
+| Labelled arrows | 1 (focal accent only) |
+| Data-type chips per node | 2 |
+| Custom-colored elements (§4) | 3 (in addition to focal node + focal step) |
+
+Above 4 lanes or 6 steps: split into two diagrams (e.g., ingestion pipeline / analytics pipeline).
+
+---
+
+## 11. Anti-patterns
+
+- **Placeholder empty cells** — if a role doesn't participate in a step, leave the cell empty (no box, no text).
+- **More than one labelled arrow** — only the focal cross-role handoff gets a label.
+- **Diagonal arrows** — always horizontal-first, then vertical; single right-angle bend.
+- **`title` role for node titles** — node titles use the `node-name` role (technical context). Only the page `<h1>` uses `title`.
+- **Accent on more than one node, one step, one arrow** — focal = one node + one step + one arrow, max.
+- **`node-name` role for role labels** — lane labels always use the uppercase `eyebrow` role (they are identifiers, not prose).
+- **`color` override on a focal element** — ignored. Accent always wins.
+- **Custom-colored arrows** — arrows are topology-driven. Color on a node never spreads to its edges.
+- **Lane tints over-applied** — a tint on every lane reads as decoration, not signal. Apply to ≤1 lane.
+
+---
+
+## 12. Examples
+
+- `assets/example-data-flow.html` — minimal light (the platform, 4-role × 5-step: Admin, Engineers, Scientists, Consumers). Gallery default.
+- `assets/example-data-flow-dark.html` — same, dark skin.
+- `assets/example-data-flow-full.html` — same, editorial-card frame.

package/.agents/skills/diagram-design/references/type-db-schema.md

@@ -0,0 +1,48 @@
+# Database Schema
+
+**Best for:** the *physical* schema — real tables, real SQL types, real constraints, real indexes, and foreign keys that connect one column to another column. It's the DDL made legible: migrations, review of a real database, and anything where the column type or the `ON DELETE` behavior is the point.
+
+**Not for domain modeling.** [ER / data model](type-er.md) is entity-level: relationship lines join *boxes* and carry cardinality, fields are a plain list, and it's the right tool for a conceptual or domain conversation. Database schema is column-level: the FK connector anchors to the specific column row on both ends — the one capability ER doesn't have, and the reason this type exists. If you're discussing what an Order *is*, use ER. If you're discussing what happens when a row is deleted, use this.
+
+## Layout conventions
+
+### Table box
+
+- **Header band** — `schema.table` (e.g. `public.orders`) in the `node-name` role, 12px, weight 600, with a rectangular type tag (`rx=2`, NOT a pill) reading `TABLE`. A hairline separates it from the body.
+- **Column rows** — fixed 24px row height so connectors can anchor predictably. Each row: column name in the `node-name` family at 12px anchored left, SQL type in the `sublabel` role 9px `muted` anchored right (`uuid`, `text`, `numeric(12,2)`, `timestamptz`), and constraint chips between them as small `rx=2` tags in the `eyebrow` role at 8px: `PK`, `FK`, `UQ`, `NN`. Alternate row background `ink @ 0.02` on even rows for scannability.
+- **Overflow row** — when a table has more columns than the budget allows, the last row is a `sublabel`-role 9px `muted` line: `+ N more columns`. Never silently truncate a table without saying so.
+- **Index compartment** — an optional final compartment separated by a hairline, labelled with an `eyebrow`-role 8px uppercase `INDEXES` eyebrow, listing index names in the `sublabel` role at 9px (`idx_orders_customer_id`, `uq_products_sku`). List only the indexes that matter to the story, not every index on the table.
+
+### Foreign-key connectors — the defining rule
+
+Each FK edge starts at the **vertical centre of its source column row** and ends at the **vertical centre of the referenced column row**, routed with orthogonal rounded elbows (see SKILL.md §6 and [type-architecture.md](type-architecture.md) for the elbow formula and bridge/hop primitive). Label each edge in the `arrow-label` role at 8px with its referential action — `ON DELETE CASCADE`, `ON DELETE RESTRICT`, `ON DELETE SET NULL` — masked with the standard 6–10px gap. Fixed 24px row height guarantees ≥12px separation only when two FKs attach to *different* rows on the same table edge — the row spacing itself is the fan. When two or more FKs attach to the *same* row on the same edge (e.g. two child tables both referencing the same parent's primary key), anchoring all of them at the exact row centre would collide at a single point, which SKILL.md §6 rule 4 forbids. Offset each attach point symmetrically around the row's vertical centre instead — ±8px for two edges, keeping every point inside the row's 24px band and ≥12px from its neighbor — so each connector still reads as attaching to that row while remaining independently traceable.
+
+### Schema grouping
+
+Tables in a non-default schema sit inside a containment rect (`rx=8`, `ink @ 0.02` fill, `ink @ 0.20` stroke dashed `4,4`) with an `eyebrow`-role 8px uppercase tracked schema label in its top-left corner. Draw the group rect first so tables paint over it.
+
+### Focal rule
+
+The 2 accent elements are: (1) the one destructive FK (`ON DELETE CASCADE`) — the edge and its label count together, since a labelled edge is one thing; and (2) the table that FK cascades into, carrying `accent-tint` on its **header band only**, never on the whole box. Nothing else on the diagram is `accent`.
+
+If a schema has no destructive FK, it has no focal element. Leave it unaccented rather than promoting an arbitrary table.
+
+## Complexity budget
+
+Max 5 tables, max 8 column rows shown per table, max 6 FK edges, max 2 accent elements. Over budget → show the subsystem, not the database, and say so in a caption.
+
+## Anti-patterns
+
+- Drawing every column of every table — a schema diagram is an argument about a subsystem, not a `\d+` dump.
+- FK lines that connect box to box instead of column to column — that's ER, use ER instead.
+- Missing SQL types — the type is half the content.
+- Unlabelled FK edges — the `ON DELETE` behavior is what a reviewer is looking for.
+- Constraint chips on every row until the chips are the noise.
+- Index compartments listing every index rather than the ones that matter to the story.
+- Mixing conceptual entity names with physical table names in one diagram.
+
+## Examples
+
+- `assets/example-db-schema.html` — minimal light
+- `assets/example-db-schema-dark.html` — minimal dark
+- `assets/example-db-schema-full.html` — full editorial

package/.agents/skills/diagram-design/references/type-dependency.md

@@ -0,0 +1,44 @@
+# Dependency Graph
+
+**Best for:** what depends on what, across packages, modules, or services — specifically to show two things a **tree** cannot structurally express: (a) a node with **more than one parent** (a shared dependency that several things converge on), and (b) a **cycle**. If neither appears in the data — every node has exactly one parent and nothing points backward — use [Tree](type-tree.md) instead; say so explicitly rather than forcing a graph layout on tree-shaped data.
+
+## Layout conventions
+
+- **Ranked layers.** Nodes sit in horizontal rank rows by dependency depth: rank 0 (entry points nothing depends on) at the top, deeper ranks below. Forward edges point downward across ranks, or run horizontal within a single rank row when a dependency compresses to the same depth as its dependent (e.g. a shallow sibling dependency) — never upward outside the one marked cycle. Rank rows are 120px apart.
+- Nodes are the standard node-box pattern (§6, [primitives-core.md](primitives-core.md#node-box--full-pattern)): `rx=6`, 160px wide, 56px tall.
+- **Fan-in badge.** Every node carries an `eyebrow`-role 8px badge in its top-right corner, inside a small `rx=2` box, showing how many nodes depend on it (`4 in`). A mask fully inside a node is a badge chip, not a label — legitimate under §6 rule 6. The node with the highest fan-in is the diagram's structural story; size nothing else to compete with it.
+- **Node treatments** ([style-guide.md § Node type → treatment](style-guide.md#node-type--treatment)):
+  - Internal package/service → white fill + `ink` stroke.
+  - External / third-party → `ink @ 0.03` fill + `ink @ 0.30` stroke (the External/Cloud treatment).
+  - Leaf with no outgoing edges → `ink @ 0.05` fill + `muted` stroke.
+- **The cycle.** At most one back-edge points upward against rank order. It is the editorial point of the diagram: `accent` stroke, dashed `5,4`, `marker-end="url(#arrow-accent)"`, routed **around the outside** of the node stack — never straight through the middle, and never behind a node it doesn't connect to — with a masked `arrow-label`-role 8px `CYCLE` label at its visible end. The two nodes the cycle touches stay in their normal node treatment (§5) — no accent stroke or fill on the nodes themselves, or the 2-accent budget is blown on the wrong elements.
+- **Focal rule:** the 2 accent elements permitted per diagram are the back-edge and its `CYCLE` label. Nothing else in a dependency graph is accent.
+- All six §6 Mandatory connector rules apply in full, no exemptions: rounded right-angle elbows (`r=8`) between off-axis nodes, 6–10px label-margin, no overlapping connectors (bridge/hop at crossings), fanned attach points (≥12px apart) where multiple edges share a box edge, no connector passing behind a non-endpoint box, no label mask clipped by a later-painted node.
+
+## Complexity budget
+
+| Limit | Rule |
+|---|---|
+| Max nodes | 9 |
+| Max edges | 14 |
+| Max rank layers | 4 |
+| Max highlighted cycles | 1 |
+| Max accent elements | 2 |
+
+Over budget: collapse a leaf cluster into one aggregate node labelled with its count (e.g. `+6 leaves`), and say so in a caption — don't silently drop nodes.
+
+## Anti-patterns
+
+- Drawing a dependency graph when the data is actually a tree (single parent everywhere, no cycles) — use Tree instead.
+- Forward edges that point upward without being the one marked cycle.
+- A hairball layout with no rank ordering — rank first, always; ranking is what makes the graph readable, not an optional polish pass.
+- One node per file instead of per package/module/service — the graph is about dependency structure, not the filesystem.
+- Unlabelled external dependencies — version or registry belongs in the `sublabel` (`v3.23 · npm`), not left implicit.
+- Highlighting more than one cycle in a single diagram — pick the one that matters editorially; a second cycle competes with the first and neither reads.
+- Omitting the fan-in badges — without them the reader can't see at a glance where dependencies concentrate, which is the entire reason this type exists over a plain tree.
+
+## Examples
+
+- `assets/example-dependency.html` — minimal light
+- `assets/example-dependency-dark.html` — minimal dark
+- `assets/example-dependency-full.html` — full editorial

package/.agents/skills/diagram-design/references/type-deployment.md

@@ -0,0 +1,45 @@
+# Deployment
+
+**Best for:** where the software actually *runs* — hosts, VMs, pods, and managed services placed inside environment or network-boundary zones, with replica counts and versioned artifacts called out. Architecture answers "what talks to what"; deployment answers "what is installed on which host, in which environment, behind which network boundary, at how many replicas." If the diagram has no physical-placement decision to show — no zone boundary, no replica count, no version that matters — use `type-architecture.md` instead; redrawing the logical architecture with hostnames bolted on is the most common deployment anti-pattern.
+
+## Layout conventions
+
+Three nesting levels, outermost to innermost — reuses the containment grammar from `type-nested.md`, specialized for infrastructure:
+
+1. **Zone** — an environment or network boundary (`edge`, `prod / eu-west-1`, `data`). A large rect, `rx=8`, fill `ink @ 0.02`, stroke `ink @ 0.20` dashed `4,4`. An `eyebrow`-role 8px (or 7px for tight layouts) uppercase tracked label sits inside the top-left corner, on a paper-colored mask over the border. Zones are drawn **first** — before arrows and nodes — so labels and boxes paint over them (z-order: bg → zones → arrows → labels → nodes).
+2. **Infrastructure node** — a host, VM, pod, or managed service inside a zone. The §6 node-box pattern (SKILL.md; markup in [primitives-core.md](primitives-core.md#node-box--full-pattern)) at `rx=6`, with a rectangular type tag (`rx=2`, **not** a pill) carrying `POD` / `VM` / `MANAGED` / `CDN` in the top-left corner.
+3. **Artifact chip** — what is deployed onto that node. A small 24px-tall rect `rx=4`, fill `ink @ 0.05`, stroke `muted`, holding the image or service name in the `node-name` family at 12px (left-aligned) plus a `sublabel`-role 9px version tag (right-aligned, e.g. `v2.4.1`). A node can carry more than one chip (stacked with an 8px gap) when more than one artifact is co-located (a sidecar, for example).
+
+**Replica badge.** A node running N copies carries a right-aligned `eyebrow`-role 8px badge (`x3`) inside its own small `rx=2` box in the node's top-right corner. A mask fully inside a node is a badge chip and is a legitimate exception to the "mask must not overlap a later node" rule (SKILL.md §6 rule 6) — it's part of that same node.
+
+**Network paths.** Orthogonal elbows between nodes (SKILL.md §6, elbow formula and port-selection rules in `type-architecture.md`), labelled with protocol and port in the `arrow-label` role at 8px (`HTTPS:443`, `TLS:5432`). A path that crosses a zone boundary is `link`-blue; a path that stays inside one zone is `muted`. Async or replication paths are dashed `5,4`.
+
+**Focal rule.** The 2 accent elements are the single-point-of-failure or the newly-introduced piece — never more than 2. In the canonical example: the RDS primary (accent-tint fill, accent stroke) and the replication path to its standby (accent, dashed).
+
+## Complexity budget
+
+| Limit | Rule |
+|---|---|
+| Max zones | 3 |
+| Max infrastructure nodes | 6 |
+| Max artifact chips | 9 |
+| Max network paths | 8 |
+| Max accent elements | 2 |
+
+Over budget → split into one deployment diagram per environment.
+
+## Anti-patterns
+
+- Redrawing the logical architecture with hostnames bolted on. If no placement decision is visible (which host, which zone, how many replicas), use `type-architecture.md` instead.
+- Zones that are just visual grouping with no boundary meaning — a zone must be a real environment or network boundary, not a layout convenience.
+- Artifact chips without a version tag. The version is why the diagram exists; an unversioned chip is a wasted box.
+- One node drawn per replica instead of a single node with a replica badge.
+- Cloud-vendor icon soup standing in for named nodes — name the host or service, don't decorate it.
+- Unlabelled network paths. Protocol and port are the content of a deployment diagram, not decoration.
+- Mixing two environments in one diagram (e.g. staging and production nodes side by side without a zone boundary that actually separates them).
+
+## Examples
+
+- `assets/example-deployment.html` — minimal light
+- `assets/example-deployment-dark.html` — minimal dark
+- `assets/example-deployment-full.html` — full editorial