scrum-skills 0.3.2 → 0.3.4

package/.agents/skills/diagram-design/references/type-dp-security-matrix.md

@@ -0,0 +1,379 @@
+# DP security matrix
+
+**Best for:** documenting per-role / per-component access permissions for a data platform — a grid where each row is a platform component (Keycloak, MinIO bucket, Trino catalog, JupyterHub, NiFi, …) and each column is a role / AD group (Data Administrators, Data Engineers, Data Scientists, Data Consumers, …). Each intersection cell holds a permission value (Admin / Full / R/W / Read / SELECT / Login / No access) with a visual category that matches the permission level. One cell may be marked focal to flag a critical access rule (e.g., "Data Consumers can ONLY `SELECT` from the aggregated catalog — sole consumer access").
+
+Use when stakeholders need to audit *who can do what* across the platform. Prefer **DP integration** when the question is *who can talk to what* (topology/protocol) rather than *who can write/read what* (permissions).
+
+This type is **parametric** — the inputs schema in §1 drives every coordinate via the formulas in §2. The rule shape mirrors `type-medallion.md` / `type-process.md` / `type-data-flow.md` so the focal rule, color override, dark mode, and reproducibility checklist read identically across types.
+
+---
+
+## 1. Inputs — the parameter contract
+
+```yaml
+title:    "Platform Access Matrix"
+subtitle: "Four canonical groups × platform components"
+
+roles:                                  # 2..6 columns, ordered left → right
+  - { name: "Data Administrators", code: "DL-DataAdmins"      }
+  - { name: "Data Engineers",      code: "DL-DataEngineers"   }
+  - { name: "Data Scientists",     code: "DL-DataScientists"  }
+  - { name: "Data Consumers",      code: "DL-DataConsumers"   }
+
+components:                             # 2..14 rows, ordered top → bottom
+  - { name: "Keycloak",                          hint: "SSO" }   # `hint` = right-aligned aside in label cell
+  - { name: "MinIO · raw bucket" }
+  - { name: "MinIO · anon · staging · agg" }
+  - { name: "Trino · raw catalog" }
+  - { name: "Trino · anon-staging" }
+  - { name: "Trino · aggregated" }
+  - { name: "JupyterHub" }
+  - { name: "NiFi" }
+
+cells:                                  # explicit (row, col) entries; omitted → defaults to "none"
+  # value = displayed text (free-form)
+  # level = visual category: full | rw | read | none  (closed vocabulary, drives styling)
+  # focal: true (max 1)            — overrides level to focal styling
+  # sub: "second-line text"        — used inside focal cell
+  # color: "#hex"                  — optional per-cell color override (§4)
+  - { row: 0, col: 0, value: "Admin", level: "full" }
+  - { row: 0, col: 1, value: "Login", level: "read" }
+  - { row: 0, col: 2, value: "Login", level: "read" }
+  - { row: 0, col: 3, value: "Login", level: "read" }
+
+  - { row: 1, col: 0, value: "Full",       level: "full" }
+  - { row: 1, col: 1, value: "R/W",        level: "rw"   }
+  - { row: 1, col: 2, value: "No access",  level: "none" }
+  - { row: 1, col: 3, value: "No access",  level: "none" }
+
+  # ... rows 2..4 follow the same pattern ...
+
+  - { row: 5, col: 0, value: "Full",       level: "full" }
+  - { row: 5, col: 1, value: "R/W",        level: "rw"   }
+  - { row: 5, col: 2, value: "SELECT",     level: "read" }
+  - { row: 5, col: 3, value: "SELECT only", sub: "sole consumer access", focal: true }
+
+  # ... rows 6..7 ...
+
+none_label: "No access"                 # default text rendered when a cell is omitted
+dark: false
+```
+
+**Reserved field semantics:**
+- `roles[j].name` — primary role label (`node-name` role at 11px, white text on the ink banner)
+- `roles[j].code` — secondary AD-group identifier (`sublabel` role, white text at 0.85 opacity)
+- `components[i].hint` — optional right-aligned `sublabel` text in the label cell (e.g., `"SSO"`, `"S3 API"`)
+- `cells[k].level` — closed vocabulary `full | rw | read | none`. Drives fill/stroke/text-color per §2.4.
+- `cells[k].value` — free-form display text. Domain-specific labels (`"R/W"`, `"SELECT"`, `"Login"`) work without inventing new levels.
+- `cells[k].focal: true` — exactly **one** cell may declare this. Overrides `level` to focal styling.
+- `cells[k].sub` — optional 2nd-line text (used with focal). Renders in the `sublabel` role at 8px below the primary value.
+- `cells[k].color: "#hex"` — optional per-cell color override (§4).
+
+---
+
+## 2. Layout formulas — deterministic geometry
+
+```
+# Constants
+left_pad         = 12
+right_pad        = 48
+comp_col_w       = 208
+comp_role_gap    = 12
+role_col_w       = 148
+role_col_gap     = 16
+header_h         = 52
+row_h            = 36
+row_stride       = 40
+
+# Counts
+n_roles          = len(roles)        # 2..6
+n_components     = len(components)   # 2..14
+
+# Canvas
+viewBox_w        = left_pad + comp_col_w + comp_role_gap
+                   + n_roles * role_col_w + (n_roles - 1) * role_col_gap
+                   + right_pad
+                   # 4 roles → 12 + 208 + 12 + 592 + 48 + 48 = 920
+
+header_y         = 72
+row_y(k)         = 140 + k * row_stride                  # 140, 180, 220, ...
+rows_bottom      = row_y(n_components - 1) + row_h       # 8 rows → 456
+legend_y_top     = rows_bottom + 20                      # 476 for 8-row canonical
+viewBox_h        = legend_y_top + 44                     # 520 for 8-row canonical
+
+# Column positions
+comp_col_x       = left_pad                                                       # 12
+role_col_x(j)    = left_pad + comp_col_w + comp_role_gap
+                   + j * (role_col_w + role_col_gap)
+                                                                                  # 232, 396, 560, 724
+role_col_cx(j)   = role_col_x(j) + role_col_w / 2                                 # 306, 470, 634, 798
+```
+
+### 2.1 Background
+
+Solid paper fill across the full viewBox. No dot pattern.
+
+### 2.2 Header row (`y = 72, h = 52`)
+
+**Component-column header cell:**
+- Rect: `(comp_col_x, header_y, comp_col_w, header_h)`, fill white, stroke `ink @ 0.12` 0.8, `rx=6`
+- Two-line label centered at `(comp_col_x + comp_col_w/2, header_y+24)` and `(…, header_y+40)`:
+  - Line 1: `"Component"` — `node-name` role at 11px, ink
+  - Line 2: `"vs. AD group"` — `sublabel` role, muted
+
+**Role banners (one per role):**
+- Rect: `(role_col_x(j), header_y, role_col_w, header_h)`, fill `ink`, `rx=6`
+- Two-line label centered:
+  - Line 1 at `y=92`: `roles[j].name` — `node-name` role at 11px, white
+  - Line 2 at `y=108`: `roles[j].code` — `sublabel` role, white at opacity 0.85
+
+### 2.3 Data row (`y = row_y(k), h = 36`)
+
+**Component label cell:**
+- Rect: `(comp_col_x, row_y(k), comp_col_w, row_h)`, fill white, stroke `ink @ 0.12` 0.8, `rx=4`
+- Name at `(comp_col_x + 12, row_y(k) + 22)`: `node-name` role at 11px, ink, left-aligned
+- Hint (if present) at `(comp_col_x + comp_col_w − 12, row_y(k) + 22)`: `sublabel` role, muted, right-aligned
+
+**Value cells (one per role × component):**
+- Rect: `(role_col_x(j), row_y(k), role_col_w, row_h)`, `rx=4`, stroke `ink @ 0.12` 0.6
+- Fill and text-color depend on `level` (or focal flag) — see §2.4
+- Value text centered at `(role_col_cx(j), row_y(k) + 22)`: `node-name` role at 10px
+- Focal cell uses a slightly raised primary text at `y=18` and a sub-line at `y=30` (`sublabel` role at 8px)
+
+### 2.4 Cell style table
+
+| `level` | Fill | Stroke | Text color | Text weight |
+|---|---|---|---|---|
+| `full` | `ink @ 0.08` | `ink @ 0.12` | `ink` | 600 |
+| `rw` | `#FFFFFF` | `ink @ 0.12` | `ink` | 400 |
+| `read` | `muted @ 0.08` | `ink @ 0.12` | `muted` | 400 |
+| `none` | `paper` | `ink @ 0.12` | `soft` | 400 |
+| **focal** | `accent @ 0.07` | `accent` (1.4) | `accent` | 600 |
+
+The focal cell can carry a 2nd line (`sub:`) rendered in `accent` with the `sublabel` role at 8px and 0.85 opacity.
+
+### 2.5 Legend (`y_top = legend_y_top, h ≈ 30`)
+
+Hairline separator at `legend_y_top`. Below the separator, one row of style swatches with their labels — only the styles actually used in the diagram appear in the legend.
+
+- "LEGEND" eyebrow at `(left_pad, legend_y_top + 20)`: `eyebrow` role, muted, letter-spacing 0.14em
+- Each style: swatch rect (14×12 `rx=2`) followed by a `sublabel` role label
+- Item x-positions are tabulated left-to-right with ~120-px stride; legend wraps onto a second visual row only if `n_roles ≥ 6` (otherwise fits in one line)
+
+---
+
+## 3. Cells, not connectors
+
+A matrix diagram has **no connectors** — there are no arrows between cells, no flow lines. The diagram's information is entirely in the cell content + cell styling. The only "connector-like" element is the focal cell's accent border, which visually "calls out" a specific intersection.
+
+Cells emit **no edges**. Don't add arrows pointing into cells or between cells — they belong in a different diagram type.
+
+---
+
+## 4. Color overrides
+
+Three independent override axes — per-cell, per-component (row), per-role (column). All optional, all use the same `color: "#hex"` field, all draw from the same recommended palette. Mirrors §3.4 of `type-high-level.md`, §4 of `type-process.md`, §4 of `type-medallion.md`.
+
+### 4.1 Per-cell `color`
+
+Tints a specific intersection cell. Applied to:
+
+| Element | Light | Dark |
+|---|---|---|
+| Cell fill | `rgba(C, 0.08)` | `rgba(C_light, 0.12)` |
+| Cell stroke | `rgba(C, 0.45)` width 1.0 | `rgba(C_light, 0.55)` width 1.0 |
+| Value text | `C` | `C_light` |
+| Sub text (if present) | `rgba(C, 0.85)` | `rgba(C_light, 0.95)` |
+
+`C_light` = the same hex lightened ~15% for dark-mode contrast.
+
+### 4.2 Per-component `color`  (`components[i].color`)
+
+Tints the row's **label cell only** (left column). The data cells in that row keep their per-cell `level` styling — the row color flags *what* this component is, not *what permissions live in it*.
+
+| Element | Light | Dark |
+|---|---|---|
+| Label cell fill | `rgba(C, 0.06)` | `rgba(C_light, 0.10)` |
+| Label cell stroke | `rgba(C, 0.45)` width 0.8 | `rgba(C_light, 0.55)` width 0.8 |
+| Component name | `C` | `C_light` |
+| Hint text | unchanged (muted) | unchanged (muted) |
+
+### 4.3 Per-role `color`  (`roles[j].color`)
+
+Tints the **column banner only** (top row). Cells underneath keep their `level` styling. Replaces the default navy banner fill with the chosen hex.
+
+| Element | Light & Dark (banner is the same in both modes) |
+|---|---|
+| Banner fill | `C` |
+| Role name + code text | `#FFFFFF` if `C` is dark (luminance ≤ 0.5), else `ink` |
+
+If you pick a mid-luminance hex (e.g., yellow `#c9a23a`), the text auto-flips to ink for contrast. Pair `roles[j].text_color: "#hex"` to override this auto-pick.
+
+### 4.4 Rules
+
+- **Focal cell wins.** A focal cell ignores `color` overrides — accent always.
+- **Per-cell `color` overrides `level` styling** for that one cell.
+- **Per-component / per-role overrides are scoped:** component → row label only; role → banner only. They do **not** spread into the matrix body. To flag a specific intersection, use per-cell.
+- **Cap:** keep total custom-colored entities ≤ 5 per diagram (combining cells + components + roles). Above 5, the matrix reads as colored noise — split into multiple diagrams or rethink which color carries which concern.
+
+### 4.5 Recommended palette (same as the other parametric types)
+
+- `#b85450` rust-red — Security elevation / break-glass / SoX-flagged
+- `#5a7d9a` slate-blue — Quality / monitoring / observability gate
+- `#7a8c47` olive-green — Approved / governance-cleared / publication-ready
+- `#c9a23a` warm yellow — Working / sandbox / data-scientist zone
+- `#8c6d3f` warm-brown — Archive / cold / DR
+
+---
+
+## 5. Focal rule
+
+Exactly **one** focal cell per diagram (or zero). The focal cell:
+- Uses focal styling (accent fill + accent stroke 1.4 + accent text bold)
+- May carry a 2-line content: primary `value` at `y = row_y(k) + 18`, `sub` at `y = row_y(k) + 30`
+- Calls out the diagram's central security claim — the *one* access rule that distinguishes this platform's posture from a generic permissions table
+
+If zero or >1 `focal: true` cells are declared, halt and ask the user.
+
+---
+
+## 6. Dark mode
+
+| Token | Light | Dark |
+|---|---|---|
+| Paper | `paper` | `ink` |
+| Ink | `ink` | `paper` |
+| Muted | `muted` | `soft` |
+| Soft (no-access text) | `soft` | `muted` |
+| Accent | `accent` | `accent` |
+| Role-banner fill | `ink` | `ink` |
+| Header / row stroke | `ink @ 0.12` | `paper @ 0.18` |
+| Full / Admin fill | `ink @ 0.08` | `paper @ 0.10` |
+| R/W fill | `#FFFFFF` | `paper @ 0.06` |
+| Read fill | `muted @ 0.08` | `soft @ 0.12` |
+| No-access fill | `paper` | `paper @ 0.02` |
+| Focal fill | `accent @ 0.07` | `accent @ 0.12` |
+| Focal 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 via §2 (4 roles × 8 components → 920 × 520).
+2. Header row at `y=72 h=52`. Component header cell white-filled with two-line `Component / vs. AD group` label. Role banners filled `ink` with name + AD-group code in white.
+3. Data rows start at `y=140`, stride 40, height 36. `rows_bottom = 140 + (n_components−1)·40 + 36`.
+4. Component label cell `rx=4`, name left-aligned at `x=24`, optional `hint` right-aligned at `x = comp_col_x + comp_col_w − 12`.
+5. Every value cell `rx=4`, stroke `ink @ 0.12` 0.6, fill + text matching §2.4 for its `level`.
+6. Exactly **one** focal cell (or zero). Focal cell stroke `accent` width 1.4. Primary value at `y = row_y(k) + 18`; `sub` (if present) at `y = row_y(k) + 30`.
+7. Cells omitted from `cells:` render as `level: "none"` with `none_label` text (default `"No access"`).
+8. Custom-colored cells ≤ 2 (in addition to the focal cell).
+9. No connector elements anywhere in the SVG.
+10. Legend strip at `legend_y_top`, one swatch per `level` actually used, hairline separator above.
+11. `viewBox_h` grows with `n_components`; `viewBox_w` grows with `n_roles`.
+
+---
+
+## 8. Anti-patterns
+
+- **More than one focal cell** — focal exists to mark *the* critical access rule; >1 erases the signal.
+- **Connectors anywhere** — matrix is value-driven; arrows belong in DP integration / process diagrams.
+- **Freeform `level` values** — closed vocabulary is `full | rw | read | none`. Use `value` for free-form displayed text + `color` override for arbitrary tinting.
+- **Per-row or per-column color tints** — apply `color` per cell only. Whole-row or whole-column highlighting tends to over-emphasize and collapses the matrix into a list.
+- **Using `none_label` as a placeholder for "TBD"** — `none` means *no access*. If the permission is unknown, leave the cell empty in inputs but document it elsewhere; don't render an ambiguous state.
+- **More than 6 roles** — split into two matrices (e.g., human roles vs service accounts) before exceeding 6 columns.
+- **More than 14 components** — split by domain (storage / compute / observability / governance) before exceeding 14 rows.
+- **Using the matrix to document *how* permissions are granted** — that belongs in a process or sequence diagram. The matrix shows *what* each role can do, not the grant flow.
+
+---
+
+## 9. Examples
+
+- `assets/example-dp-security-matrix.html` — minimal light (NatStat canonical: 4 roles × 8 components, focal at Data Consumers × Trino aggregated). Gallery default.
+- `assets/example-dp-security-matrix-dark.html` — same, dark skin.
+- `assets/example-dp-security-matrix-full.html` — same, editorial-card frame with subtitle + summary cards.
+
+---
+
+## 10. Worked YAML — full inputs for `example-dp-security-matrix.html`
+
+The complete inputs that map to the shipped canonical example. Every coordinate in that SVG is derivable from §2 applied to these inputs.
+
+```yaml
+title:    "Platform Access Matrix"
+subtitle: "Four canonical groups × platform components"
+
+roles:
+  - { name: "Data Administrators", code: "DL-DataAdmins"      }
+  - { name: "Data Engineers",      code: "DL-DataEngineers"   }
+  - { name: "Data Scientists",     code: "DL-DataScientists"  }
+  - { name: "Data Consumers",      code: "DL-DataConsumers"   }
+
+components:
+  - { name: "Keycloak",                          hint: "SSO" }
+  - { name: "MinIO · raw bucket" }
+  - { name: "MinIO · anon · staging · agg" }
+  - { name: "Trino · raw catalog" }
+  - { name: "Trino · anon-staging" }
+  - { name: "Trino · aggregated" }
+  - { name: "JupyterHub" }
+  - { name: "NiFi" }
+
+cells:
+  # Row 0 — Keycloak
+  - { row: 0, col: 0, value: "Admin", level: "full" }
+  - { row: 0, col: 1, value: "Login", level: "read" }
+  - { row: 0, col: 2, value: "Login", level: "read" }
+  - { row: 0, col: 3, value: "Login", level: "read" }
+  # Row 1 — MinIO raw
+  - { row: 1, col: 0, value: "Full", level: "full" }
+  - { row: 1, col: 1, value: "R/W",  level: "rw"   }
+  - { row: 1, col: 2, value: "No access", level: "none" }
+  - { row: 1, col: 3, value: "No access", level: "none" }
+  # Row 2 — MinIO anon/staging/agg
+  - { row: 2, col: 0, value: "Full", level: "full" }
+  - { row: 2, col: 1, value: "R/W",  level: "rw"   }
+  - { row: 2, col: 2, value: "Read", level: "read" }
+  - { row: 2, col: 3, value: "No access", level: "none" }
+  # Row 3 — Trino raw catalog
+  - { row: 3, col: 0, value: "Full", level: "full" }
+  - { row: 3, col: 1, value: "R/W",  level: "rw"   }
+  - { row: 3, col: 2, value: "No access", level: "none" }
+  - { row: 3, col: 3, value: "No access", level: "none" }
+  # Row 4 — Trino anon-staging
+  - { row: 4, col: 0, value: "Full",   level: "full" }
+  - { row: 4, col: 1, value: "R/W",    level: "rw"   }
+  - { row: 4, col: 2, value: "SELECT", level: "read" }
+  - { row: 4, col: 3, value: "No access", level: "none" }
+  # Row 5 — Trino aggregated (focal cell at col 3)
+  - { row: 5, col: 0, value: "Full",        level: "full" }
+  - { row: 5, col: 1, value: "R/W",         level: "rw"   }
+  - { row: 5, col: 2, value: "SELECT",      level: "read" }
+  - { row: 5, col: 3, value: "SELECT only", sub: "sole consumer access", focal: true }
+  # Row 6 — JupyterHub
+  - { row: 6, col: 0, value: "Admin", level: "full" }
+  - { row: 6, col: 1, value: "R/W",   level: "rw"   }
+  - { row: 6, col: 2, value: "R/W",   level: "rw"   }
+  - { row: 6, col: 3, value: "No access", level: "none" }
+  # Row 7 — NiFi
+  - { row: 7, col: 0, value: "Admin", level: "full" }
+  - { row: 7, col: 1, value: "R/W",   level: "rw"   }
+  - { row: 7, col: 2, value: "Read",  level: "read" }
+  - { row: 7, col: 3, value: "No access", level: "none" }
+
+dark: false
+```
+
+### 10.1 What this YAML proves
+
+Run §2 with these inputs:
+- `n_roles = 4`, `n_components = 8`, no color overrides, one focal cell.
+- `viewBox_w = 12 + 208 + 12 + 4·148 + 3·16 + 48 = 920` ✓
+- `row_y(k)` produces `140, 180, 220, 260, 300, 340, 380, 420` ✓
+- `rows_bottom = 420 + 36 = 456`; `legend_y_top = 476`; `viewBox_h = 520` ✓
+- `role_col_x(j) = [232, 396, 560, 724]` ✓
+- Focal cell at `(row=5, col=3)` → rect `(724, 340, 148, 36)` with accent stroke 1.4 ✓
+
+A fresh generation from this YAML produces a diagram visually indistinguishable from the shipped `example-dp-security-matrix.html`.

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

@@ -0,0 +1,25 @@
+# ER / Data Model
+
+**Best for:** conceptual and logical data models, API resource relationships, domain models — anything where the story is *entities and cardinality*.
+
+**Not for the physical schema.** ER is entity-level: relationship lines join *boxes* and carry cardinality at each end. When the point is real tables with SQL types, constraint chips, indexes, and foreign keys that anchor **column to column**, use [`type-db-schema.md`](type-db-schema.md) instead.
+
+## Layout conventions
+- Each entity is a two-section box:
+  - **Header**: type tag (`ENTITY`) + entity name in the `node-name` role.
+  - **Body**: field list in the `sublabel` role, one per line. PK prefixed with `#`, FK prefixed with `→`.
+- Relationships: lines between entities with cardinality at each end:
+  - `1`, `N`, `0..1`, `1..*` in the `arrow-label` role, 8px, placed 10–12px from the entity edge.
+  - Optional relationship label ("has", "belongs to") centered on the line.
+- Group related entities close; lay out so most relationships are straight lines, not tangles.
+- Coral on the aggregate root or central entity of the model.
+
+## Anti-patterns
+- Drawing an arrow for every FK on a model with dozens — lay out by cluster instead.
+- Inconsistent cardinality notation between ends of the same relationship.
+- Fields padded to equal-height boxes — natural height by content is fine.
+
+## Examples
+- `assets/example-er.html` — minimal light
+- `assets/example-er-dark.html` — minimal dark
+- `assets/example-er-full.html` — full editorial

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

@@ -0,0 +1,115 @@
+# Exploded axonometric
+
+**Best for:** one object or system drawn in parallel projection with its parts pulled apart along one axis and labelled. A device teardown (what is inside a phone), an unboxing (lid, product, insert, box), assembly order, or the layers of a stack when the reader should see them as physical parts of one thing.
+
+**Not this type:**
+
+- Ordered abstraction levels with a note on each row → **layer stack** (`type-layers.md`). A layer stack is flat bands of text; an exploded view is the parts of one object. If nothing in the figure has a footprint or a thickness, use the layer stack.
+- Components and the connections between them → **architecture** (`type-architecture.md`). An exploded view has no arrows; position along the axis is the only relationship.
+- Containment without an order → **nested** (`type-nested.md`).
+- Where software runs → **deployment** (`type-deployment.md`).
+
+## Projection
+
+2:1 dimetric. The ground axes run at 26.565 degrees, so every edge lands on whole pixels when model units are multiples of 4. World x runs right and down, y runs left and down, z runs up. Project every point with one function and never place a coordinate by hand:
+
+```python
+from math import sqrt
+
+def iso(x, y, z, ox, oy):
+    """Model point to SVG point. (ox, oy) is where model (0, 0, 0) lands."""
+    return ox + x - y, oy + (x + y) / 2 - z
+```
+
+A rounded-rectangle footprint of corner radius `r` projects to straight edges joined by quarter arcs of one ellipse with `rx = r * sqrt(2)` and `ry = r / sqrt(2)`. Use that one shape for everything: `r = 0` is a box or slab, a small `r` is a product corner, and `r = w / 2 = d / 2` is a cylinder. Corner centres stay fixed when you inset an outline, so an inner rim is the same four centres at a smaller radius.
+
+Draw faces as plain SVG `<path>` and `<polygon>` elements with the projected points written in. No CSS 3D, no canvas, no WebGL, and no `transform` to place geometry. If content ever has to sit flat on a face, the matrices that agree with `iso()` are `matrix(1,0.5,-1,0.5,tx,ty)` for the top face, `matrix(1,0.5,0,-1,tx,ty)` for the left face, and `matrix(-1,0.5,0,-1,tx,ty)` for the right face. Labels never use them: labels stay horizontal.
+
+`scripts/build-exploded-examples.py` in the repository builds every shipped example from this function and is the worked reference for the helpers below.
+
+## Layout conventions
+
+- **Parts:** 2 to 5, listed bottom to top. Each part is a rounded prism (`rect`, thickness `t`) plus at most two levels of detail on its top face, because the top face is the one the reader sees.
+- **Explode axis:** Vertical by default. Parts move straight up, nothing rotates, and the bottom part stays at `z = 0`.
+- **Levels:** Parts that sit side by side in the assembled object share a level and explode together. A phone's logic board and battery sit next to each other inside the housing, so they lift as one level instead of stacking two gaps apart.
+- **Gap:** One gap between every pair of levels, `gap = max(k x top-face height, 3 x thickness of the thickest solid part)`, rounded up to a multiple of 4. `k = 0.5` is the floor; raise it to `0.75` when a tall part would hide the focal part below it. Top-face height is `(w + d) / 2` of the largest footprint. Containers (a housing, a box) do not count toward thickness.
+- **Clearance:** If a leader would cross another part, or two labels would sit closer than 36px, raise the gap in steps of 4 until neither happens. Two parts on one level that collide cannot be fixed by the gap: move one of them in plan.
+- **Paint order:** Bottom level first. Inside a level, parts farther back (smaller `x + y`) paint first. A container is split: its back half (silhouette, rim, cavity, floor) paints before the parts that sit inside it, and its outer walls and front rim paint after them. This is the only way an assembled frame shows the parts inside a tray correctly, and it stays correct throughout an explode.
+- **Frame:** The canvas is 1000 wide. The object and a 240px label column are centred together; the viewBox height follows the exploded object plus a 40px top margin. Nothing is clipped at the closed frame either, because the closed object fits inside the exploded one.
+
+### Faces and lines
+
+| Element | Light | Dark |
+|---|---|---|
+| Face base (opaque, under every face) | `#ffffff` | `paper-2` |
+| Top face | base | base + `ink @ 0.10` |
+| Left face (lit side) | base + `ink @ 0.07` | base |
+| Right face (shade side) | base + `ink @ 0.15` | base + `paper @ 0.45` |
+| Focal part, top / left / right | `accent` at 0.10 / 0.20 / 0.32 over base | `accent` at 0.18 top, neutral sides |
+| Silhouette | `ink`, 1.2 (`stroke-strong`) | `ink`, 1.2 |
+| Inner edges (top-front rim, front corner) | `ink` at 0.55, 0.8 (`stroke-thin`) | `ink` at 0.45, 0.8 |
+| Detail lines on a face | `ink` at 0.55, 0.6 to 0.8 | same |
+| Trace lines | `ink` at 0.30, 0.8, dashed `4,3` | `ink` at 0.30, 0.8, dashed `4,3` |
+
+Light comes from the top left, so the left face is lighter than the right. Always shade: an outline-only box flips between two readings like a Necker cube. Faces are an opaque base plus an `ink` overlay, never a translucent fill on its own, so parts behind never show through. Trace lines run straight up through the left and right extremes of the bottom part's outline to the underside of the top part, and paint before every part so the parts cover them.
+
+### Labels
+
+- One label per part, in one column to the right of the object. A label is the part name (`node-name` role, 600, 16px, one or two words) above a technical sublabel (`sublabel` role, 10px, `muted`, tracked 0.08em).
+- A horizontal leader (0.8px, `ink` at 0.40) runs from 6px right of a 2px dot on the part's right extreme, at mid-thickness, to 12px left of the column. Leaders never bend, never cross a part, and never cross each other; horizontal leaders from distinct heights cannot cross each other, and the gap rule above keeps them clear of parts.
+- The focal part's dot, leader, and sublabel take the accent. Its name stays `ink`.
+- No numbered callouts and no legend. The label is on the part it names.
+
+### Detail
+
+Three levels at most: the form (the rounded prism), insets on its top face (a screen, a cell outline, a moulded well), and micro detail (chips, lenses, a logo mark). A part made of many identical pieces, such as keycaps or switches, declares the envelope of its grid as its box and paints one small prism per piece instead of the envelope; the silhouette path is still there for the verifier, with no fill. Clip any inset that could reach a face edge to that face, keep it 4 units or more inside the edge, and stop at three levels. No contact shadow: shadows are out in this skin (SKILL.md §4). If the object needs grounding, the bottom part already provides it.
+
+### Focal part
+
+One part at most wears the accent, under the SKILL.md rule of 1 to 2 focal elements. The other parts stay neutral; do not fade them with opacity, because a translucent part shows the edges behind it.
+
+## Optional motion
+
+An exploded view may open as the assembled object and explode once, because watching the parts lift shows how they fit together. Use the pinned controller from `assets/template-motion.html` in `reveal` mode, per `animation.md`:
+
+- The source file is the exploded frame. Every part group carries `data-motion-item`, a `data-step` counted from the top level down (top level lifts first), and `style="--lift:Npx"` where `N` is the part's exploded `z` minus its assembled `z`. In this projection a straight-up move in model space is a straight-up move on screen, so one `translateY(var(--lift))` is the whole explode.
+- The bottom level does not move. Its label and the trace lines arrive together as the last step.
+- Each part's label hides at the closed frame and fades in after its part settles. Hide instantly and delay only the reveal, or labels pile up on the closed object for the first half second.
+- No JavaScript, `prefers-reduced-motion: reduce`, print, `?motion=static`, and export all show the exploded frame.
+- The lift is the one scoped exception to the 24px translation limit in `animation.md`, recorded in the repository as ADR 0013. Nothing else in the figure moves.
+
+## Metadata contract
+
+`scripts/verify-exploded.py` reprojects each part from what it declares:
+
+- The figure: one `<g data-exploded data-origin="ox oy" data-gap="g">` wrapping every part.
+- Each part: a `<g>` with `data-part` (key), `data-name` (the label text), `data-rect="x0 y0 x1 y1 r"`, `data-z`, `data-t`, `data-level`, optional `data-kind="housing"` for a container and `data-focal` for the focal part. Animated parts add `data-closed-z`.
+- Inside each part: the first `<path data-role="silhouette">` is the part's outline at its declared box, and a `<g data-role="label">` holds a `<line data-role="leader">` and a `<text data-role="name">`. Its complete text, including inline `<tspan>` descendants, must match the part's `data-name`.
+- Trace lines carry `data-role="trace"`.
+
+The silhouette verifier accepts signed decimal and scientific-notation coordinates within the existing absolute M/L/A/Z path contract. Every operand must be finite; projected vertices, corner radii, and arc flags are still checked. This does not add relative path commands.
+
+## Anti-patterns
+
+- Hand-placed coordinates, or a CSS `transform` standing in for geometry.
+- Outline-only parts with no face shading.
+- Parts that rotate, slide sideways, or explode along two axes in one figure.
+- Unequal gaps, or a gap shrunk to fit the canvas. Raise `k` or cut a part.
+- Labels on the parts, angled with a face, or spread across two columns.
+- Numbered callouts with a key underneath.
+- More than one part in the accent, or the other parts faded to show which one matters.
+- Blurred contact shadows, gradients on solid faces, or glow.
+- An exploded view of something with no physical sense of parts. If the layers are just a list, use the layer stack.
+
+## Examples
+
+- `assets/example-exploded.html`: app stack, minimal light
+- `assets/example-exploded-dark.html`: app stack, minimal dark
+- `assets/example-exploded-full.html`: app stack, full editorial
+- `assets/example-exploded-phone.html`, `-dark`, `-full`: phone teardown with a housing, a shared board and battery level, and a display
+- `assets/example-exploded-unboxing.html`, `-dark`, `-full`: packaging with a telescoping lid, a product and cable on one level, an insert, and a box
+- `assets/example-exploded-ai-stack.html`, `-dark`, `-full`: an AI agent stack with a secrets vault, tools, skills as small cards on one layer, the agent harness around the model, and the interface
+- `assets/example-exploded-keyboard.html`, `-dark`, `-full`: a mechanical keyboard with a case tray, PCB, plate, a grid of switches, and a grid of keycaps
+- `assets/example-exploded-phone-animated.html`: the phone assembled, then exploded once
+- `assets/example-exploded-unboxing-animated.html`: the box closed, then unpacked once
+- `assets/example-exploded-ai-stack-animated.html`, `assets/example-exploded-keyboard-animated.html`: the stack and the keyboard assembled, then exploded once

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

@@ -0,0 +1,75 @@
+# Fishbone / Ishikawa (root-cause)
+
+**Best for:** structured root-cause analysis. One observed effect, causes grouped by category, sub-causes hanging off each category. The standard artefact of an incident post-mortem — use it when a reader needs to see *what was investigated*, not just the conclusion.
+
+## Layout conventions
+
+- **Spine.** A horizontal line (`ink`, 1.2px) runs left→right at the vertical centre `CY`, terminating with an arrowhead into an **effect box** at the right head — the node-box pattern from SKILL.md §6 ([primitives-core.md](primitives-core.md#node-box--full-pattern)), the observed-effect statement inside.
+- **Bones.** Category lines are straight diagonals at a fixed **60°** to the spine, alternating above and below, evenly spaced along it. Each bone carries its category name at the outer end in a small tag-style box (`rx=4`, not a pill) — `node-name` role, 12px, weight 600.
+- **Sub-causes.** Short horizontal ticks (32px, `soft`) branch off each bone at fixed points along its length, each with a sub-cause label in the `sublabel` role at 9px sitting past the open end of the tick.
+- **Diagonal exemption.** SKILL.md §6 rule 1 (mandatory rounded right-angle elbows) does not apply to the 60° bones — they are this type's defining grammar. The exemption covers **bones and sub-cause ticks only**; any other connector in a fishbone diagram (e.g. a callout leader, a cross-reference arrow) still uses rounded right-angle elbows.
+- **Focal rule.** Exactly one bone is the confirmed root cause: its line is `accent`, and its category tag uses `accent-tint` fill + `accent` stroke. The effect box is styled the same way (`accent-tint` fill, `accent` stroke) since it's the diagram's headline. That pair — root-cause bone and effect box — is the full 2-accent budget; every other bone, tag, and tick stays `ink` / `muted` / `soft`.
+- **Drawing order:** background → spine → bones → sub-cause ticks → category tag boxes → effect box → legend. Lines before boxes, so box fills cap the line ends cleanly.
+
+## Math
+
+For a spine at `y = CY` with the effect box's left edge at `x = HEAD`, bone `k` (1-indexed, k = 1..6) attaches to the spine at:
+
+```
+attach_x(k) = HEAD - 160 - k * 160
+```
+
+Bones alternate above (`k` odd) and below (`k` even) the spine. A bone's far endpoint — where the category tag sits — is the integer-rounded 60° offset from its attach point:
+
+```
+dx = -96
+dy = ∓168        (minus = above, plus = below)
+far_x(k) = attach_x(k) + dx
+far_y(k) = CY ∓ 168
+```
+
+### Pre-computed reference (5-bone layout, HEAD=1200, CY=320)
+
+| Bone `k` | Category slot | Side | `attach_x` | `far_x, far_y` |
+|---|---|---|---|---|
+| 1 | first | above | 880 | 784, 152 |
+| 2 | second | below | 720 | 624, 488 |
+| 3 | third | above | 560 | 464, 152 |
+| 4 | fourth | below | 400 | 304, 488 |
+| 5 | fifth | above | 240 | 144, 152 |
+
+A 6th bone (below) would attach at `x=80`, far endpoint `(-16, 488)`, and its category tag would run from `x=-76` to `x=44` against a viewBox that starts at `x=-40`. It clips. **Five is the ceiling at `HEAD=1200`**: to draw a 6th, widen `HEAD` *and* the viewBox width by at least 160 each, keeping the viewBox origin at `-40`. Both have to move together — widening `HEAD` alone pushes the 200px effect box to `1360..1560` past the `1440` right edge, trading a clipped tag on the left for a clipped effect on the right. Or drop a category.
+
+**Sub-cause ticks** sit at fractions `m/6` along the bone (`m = 2, 4` for two ticks; `m = 3` for one), so their coordinates stay on the 4px grid:
+
+```
+tick_x(k, m) = attach_x(k) - 16 * m
+tick_y(k, m) = CY ∓ 28 * m
+```
+
+The tick itself is a 32px horizontal line from `(tick_x, tick_y)` to `(tick_x - 32, tick_y)`; the label sits past its open end, `text-anchor="end"` at `x = tick_x - 36`, `y = tick_y - 4` (above-bones) or `tick_y + 12` (below-bones).
+
+## Complexity budget
+
+| Limit | Rule |
+|---|---|
+| Max categories (bones) | 5 at `HEAD=1200`. A 6th requires a widened canvas — see Geometry |
+| Max sub-causes per bone | 3 |
+| Max sub-causes total | 18 |
+| Max accent elements | 2 (root-cause bone+tag, effect box) |
+
+## Anti-patterns
+
+- **More than 5 bones on the default canvas.** The 6th tag clips the viewBox. Widen `HEAD` and the viewBox width together and deliberately, or split by subsystem into two fishbones.
+- **Sub-causes that restate the category.** A "Deploy" bone with a sub-cause labeled "deployment issue" adds a node without adding information.
+- **A bone with zero sub-causes.** An empty category is a placeholder, not a finding — delete the bone or don't draw it until there's something under it.
+- **Accenting more than one root cause.** If two categories are both confirmed, that's two diagrams (or a merged cause) — not two accent bones. The 2-accent budget is load-bearing for the "this is the answer" signal.
+- **Using fishbone for a sequence of failures.** A chain of things that happened in order is a timeline or sequence diagram — fishbone is for causes of *one* effect, not a chronology.
+- **Pasting in the classic 6M template (Man/Machine/Material/Method/Measurement/Environment) with empty categories.** Name categories from the actual investigation, not a generic checklist waiting to be filled in later.
+- **Effect box phrased as a solution.** "Add a p99 alert" is a fix, not an observed effect. The box states what was seen — a symptom, a measurement, an incident — never the remedy.
+
+## Examples
+
+- `assets/example-fishbone.html` — minimal light. Checkout p99 latency incident, 5 categories, Data confirmed as root cause.
+- `assets/example-fishbone-dark.html` — minimal dark, same data.
+- `assets/example-fishbone-full.html` — full editorial: container framing + 3 summary cards of varied widths + footer.

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

@@ -0,0 +1,23 @@
+# Flowchart
+
+**Best for:** decision logic, algorithms, user-facing branching flows ("Should I…?"), onboarding routing, support-triage trees.
+
+## Layout conventions
+- Shape carries type, not color:
+  - **Oval** (`rx=20`) — start / end
+  - **Rectangle** (`rx=6`) — step / action
+  - **Diamond** — decision (≤3 exits)
+  - **Small filled ink dot** (`r=4`) — merge point where branches rejoin
+- Flow runs top→down. From a diamond, conventional exits: Yes to the right, No below — but label every outgoing arrow regardless.
+- Use coral on the happy path *or* on the single most consequential decision — never on every decision.
+- If two arrows must cross, use a small arc jump on one so the crossing is readable.
+
+## Anti-patterns
+- Using fill color to signal node type (shape does that).
+- Decision diamond with 4+ exits — refactor into nested diamonds.
+- Unlabeled decision branches.
+
+## Examples
+- `assets/example-flowchart.html` — minimal light
+- `assets/example-flowchart-dark.html` — minimal dark
+- `assets/example-flowchart-full.html` — full editorial