@mohammadhprp/system-prompt 0.10.1

package/framework/skills/diagram-design/references/type-loop.md

@@ -0,0 +1,223 @@
+# Loop
+
+**Best for:** reinforcing cycles, flywheels, feedback loops, and operating loops — anything where the last step feeds the first and a shared hub accumulates state. Use Loop when the reader must see both motions at once: work advances clockwise around the ring, while each pass writes durable state back to one common center.
+
+Prefer **Flowchart** when the path ends, branches toward an outcome, or never truly returns to its first step. Prefer **Cycle** when the center does not accumulate shared state. The dashed write-back spokes are the defining signal here: remove them and the figure is only a circular process.
+
+This type is **parametric**. The inputs in §1 determine station count, angles, edge intersections, connector paths, and viewBox bounds. Identical inputs should produce identical geometry.
+
+---
+
+## 1. Inputs — the parameter contract
+
+```yaml
+title: "The self-improving loop"
+subtitle: "Every pass improves the shared operating record"
+
+hub:                                  # exactly one
+  name: "Shared memory"
+  sublabel: "one record, every loop"
+
+stations:                             # 5..8, clockwise from top
+  - { name: "Capture",  sublabel: "signals in",       spoke_label: "SIGNALS" }
+  - { name: "Research", sublabel: "evidence pulled" }
+  - { name: "Decide",   sublabel: "human approves",   focal: true }
+  - { name: "Act",      sublabel: "work ships",        spoke_label: "OUTCOMES" }
+  - { name: "Measure",  sublabel: "outcomes logged" }
+  - { name: "Learn",    sublabel: "playbook updated" }
+
+station_w: 160
+station_h: 64
+hub_w: 200
+hub_h: 104
+radius: 240
+margin: 64
+dark: false
+```
+
+**Budget (hard):** **5–8 stations plus exactly one hub.** Above 8 stations, split the subject into an overview Loop and one or more detail diagrams. Exactly one hub — a loop with two hubs is two diagrams. At most one station may set `focal: true`; zero is allowed when no editorial gate deserves emphasis.
+
+Station order is semantic. `stations[0]` is the top station, then entries proceed clockwise. The last station always connects back to station 0; if that return would be false, use a Flowchart instead.
+
+---
+
+## 2. Layout math — deterministic geometry
+
+Use SVG coordinates, where positive y points downward. Let the hub center be `C = (cx, cy)`, station count be `N`, station ring radius be `R`, station half-size be `a = station_w/2`, `b = station_h/2`, and hub half-size be `A = hub_w/2`, `B = hub_h/2`.
+
+### 2.1 Station centers
+
+For zero-indexed station `k`:
+
+```text
+theta_k = -90deg + k * (360deg / N)
+u_k     = (cos(theta_k), sin(theta_k))
+P_k     = C + R * u_k
+
+station_center_x(k) = cx + R * cos(theta_k)
+station_center_y(k) = cy + R * sin(theta_k)
+station_x(k)        = station_center_x(k) - station_w/2
+station_y(k)        = station_center_y(k) - station_h/2
+```
+
+Thus station 1 sits at the top, and increasing `k` moves clockwise. Round station rectangles to the nearest 4px grid point after computing the ideal geometry; preserve symmetry when rounding paired stations. Keep ring-circle intersection points to three decimal places so every arc remains on the same circle.
+
+### 2.2 Solid ring-flow endpoints
+
+Ring connectors travel from station `k` to station `j = (k + 1) mod N` as circular SVG arcs on the station circle itself. Every segment uses the same center `C`, radius `R`, and clockwise sweep. The station boxes interrupt the circle; connectors begin at the circle's clockwise exit from the source box and end just before its counterclockwise entry into the destination box, so the marker tip lands on the destination stroke.
+
+Find the circle/rectangle intersections against all four edges of station `k`. For vertical edge `x = x_e`:
+
+```text
+y = cy +/- sqrt(R^2 - (x_e - cx)^2)
+```
+
+Keep only candidates whose `y` lies within the edge. For horizontal edge `y = y_e`:
+
+```text
+x = cx +/- sqrt(R^2 - (y_e - cy)^2)
+```
+
+Keep only candidates whose `x` lies within the edge. The two surviving points are classified by their normalized polar angles around `C`:
+
+```text
+q_entry(k) = circle/box intersection immediately before theta_k clockwise
+q_exit(k)  = circle/box intersection immediately after  theta_k clockwise
+```
+
+Compensate for the marker tip before emitting the destination endpoint. With the canonical marker (`refX=7`, polygon tip at `x=8`) and ring stroke width `1.2`, `marker_overhang = 1.2`:
+
+```text
+phi_entry = atan2(q_entry(j).y - cy, q_entry(j).x - cx)
+phi_end   = phi_entry - marker_overhang / R
+q_end     = C + R * (cos(phi_end), sin(phi_end))
+
+M q_exit(k).x q_exit(k).y
+A R R 0 0 1 q_end.x q_end.y
+```
+
+The large-arc flag is `0` because adjacent-station gaps are less than 180 degrees; the sweep flag is always `1` for clockwise motion in SVG coordinates. The arrowhead overhang completes the final 1.2px to `q_entry(j)`, landing on the box edge without crossing its stroke. The closing connector from station `N-1` to station 0 uses the identical formula.
+
+Loop's circular ring arcs are a documented type-specific exception to SKILL.md §6 rule 1, following the same precedent as Medallion's promotion arcs. A Loop never mixes cubic, straight, or rounded-orthogonal segments into its ring: the six visible gaps must read as pieces of one continuous circle.
+
+### 2.3 Dashed write-back spoke endpoints
+
+Each spoke runs inward from the station edge toward the hub. Use the same ray/box intersection formula, now on the radial vector `u_k`:
+
+```text
+box_distance(v, half_w, half_h) = min(half_w / abs(v.x), half_h / abs(v.y))
+                                        # ignore a term whose denominator is zero
+
+d_station = box_distance(u_k, a, b)
+d_hub     = box_distance(u_k, A, B)
+marker_gap = 6                         # 4..8px; 6px canonical
+
+spoke_start(k) = P_k - d_station * u_k
+hub_edge(k)    = C   + d_hub     * u_k
+spoke_end(k)   = C   + (d_hub + marker_gap) * u_k
+```
+
+Because the arrow travels from the station toward `C`, adding `marker_gap` leaves the endpoint just outside the hub boundary. The lighter arrowhead stops before the hub stroke instead of colliding with it. Radial spokes are the type-specific exception to the general ban on slanted straight connectors; they must remain true radii, must not cross one another, and may touch only their source station and the hub.
+
+Labels are optional when the station sublabel already names the write-back. When used, they follow the `arrow-label` role, stay to one side of the spoke, and receive an opaque `paper` mask with a visible 6–10px gap from the stroke. Label a curated subset rather than forcing six labels into the hub halo.
+
+### 2.4 ViewBox sizing
+
+The viewBox must include the full station rectangles, outer ring curves, arrowheads, and at least `margin` breathing room:
+
+```text
+left   <= cx - R - station_w/2 - margin
+right  >= cx + R + station_w/2 + margin
+top    <= cy - R - station_h/2 - margin
+bottom >= cy + R + station_h/2 + margin
+
+viewBox_w = right - left
+viewBox_h = bottom - top
+```
+
+Include the full circle extrema `cx +/- R`, `cy +/- R` plus station bounds and marker clearance when checking these limits. Never shrink the canvas until a station stroke, marker, or ring arc clips. For the six-station canonical example, `viewBox="0 0 1040 680"`, `C=(520,340)`, `R=240`, station size `160×64`, and hub size `200×104` leave generous outer clearance.
+
+---
+
+## 3. Visual grammar
+
+| Element | Treatment |
+|---|---|
+| Station | Standard node: `paper` fill, `ink` stroke, `radius-md`; name in `node-name`, sublabel in `sublabel` |
+| Hub | The one dark element: `ink` fill, `paper` text; slightly larger than a station |
+| Focal station | At most one: `accent-tint` fill, `accent` stroke; station name may use `accent` |
+| Ring flow | Circular `A R R 0 0 1` arcs on the station circle, solid `muted` stroke, default arrowhead at the destination; clockwise only |
+| Write-back spoke | Dashed `soft` stroke at reduced emphasis, `stroke-dasharray="5,4"`, with a `soft` arrowhead |
+| Spoke label | `arrow-label` role, `soft`, uppercase, paper mask, 6–10px clear of the connector |
+
+Draw in this order: paper or optional dot grid → ring arrows → dashed spokes → spoke-label masks and labels → station boxes → hub → text. The nodes mask microscopic connector overshoot, while every intended endpoint still lands on an edge.
+
+The hub is not a seventh process step. It is accumulated state: memory, standards, evidence, policy, or a shared operating record. Keep its copy to one name plus one short sublabel.
+
+---
+
+## 4. Connector rules (mandatory)
+
+SKILL.md §6 applies in full except for the two Loop-specific connector primitives: circular ring arcs (§2.2) and straight radial spokes (§2.3). Like Medallion's promotion arcs, these replace §6 rule 1 for this diagram type:
+
+- Ring arrows are same-radius circular arcs, solid, and clockwise. Every path uses `A R R 0 0 1`; destination markers land on station edges and no connector ends at a center point.
+- Spokes are dashed and point inward. A solid spoke destroys the visual distinction between operating flow and write-back.
+- Labels use opaque masks and maintain a visible 6–10px connector gap. Never place text on the stroke.
+- No ring connector or spoke may overlap another connector. Ring paths remain outside the hub; spokes occupy distinct radial routes.
+- When two spokes must leave the same station edge, fan their attach points by the §6 formula with at least 12px separation. The normal Loop has one spoke per station; use a second only when the semantics cannot be merged.
+- If a ring route would cross the hub, increase `R` or split the diagram. Do not thread flow through shared state or substitute an orthogonal route.
+
+---
+
+## 5. Dark variant — token swap
+
+Apply the style-guide inversion rule; do not invent a second palette.
+
+| Role | Light | Dark |
+|---|---|---|
+| Canvas and station fill | `paper` | dark `paper` |
+| Primary text and station stroke | `ink` | inverted `ink` |
+| Hub fill / hub text | `ink` / `paper` | inverted `ink` / dark `paper` |
+| Ring flow | `muted` | dark `muted` |
+| Write-back spokes and labels | `soft` | dark `soft` |
+| Focal fill / stroke | `accent-tint` / `accent` | dark `accent-tint` / brighter dark `accent` |
+| Rule and dot grid | `rule` | inverted `rule` at the same opacity |
+
+The semantic relationship stays unchanged in dark mode: one `ink`-filled hub, one optional `accent` station, neutral solid ring arrows, and lighter dashed write-backs.
+
+---
+
+## 6. Reproducibility checklist
+
+1. Station count is 5–8 and hub count is exactly one.
+2. Station 0 is at `-90deg`; all others use equal `360/N` steps clockwise.
+3. Every solid ring arrow connects adjacent stations with `A R R 0 0 1`, using the same `R`; the last returns to the first.
+4. Every ring marker lands on a station edge, not its center.
+5. Every dashed spoke begins on a station's inner edge and stops `marker_gap` before the hub stroke.
+6. Ring connectors stay outside the hub; spokes do not cross or overlap.
+7. At most one station uses `accent-tint` + `accent`; the hub alone uses the dark `ink` fill.
+8. Spoke labels, if present, use `arrow-label`, an opaque mask, and a 6–10px gap.
+9. The viewBox includes station boxes, strokes, curves, markers, and margins without clipping.
+
+---
+
+## 7. Anti-patterns
+
+| Anti-pattern | Why it fails / correction |
+|---|---|
+| Two hubs | Two accumulated states create two systems. Draw two diagrams. |
+| Solid spokes | They look like primary flow and kill the dashed return signal. Use dashed `soft` write-backs. |
+| Stations at uneven angles without reason | The ring stops reading as one operating cadence. Use equal `360/N` spacing unless a documented phase grouping requires a deliberate gap. |
+| Mixed arc + orthogonal ring segments | The ring becomes a rounded rectangle. Every segment must be a circular arc of the same radius so the ring reads as one continuous circle. |
+| Connectors crossing the hub | Flow becomes confused with state. Route the ring outside or enlarge the radius. |
+| Accent on multiple stations | The editorial gate disappears. Keep one focal station at most. |
+| More than 8 stations | Labels and spokes crowd the hub. Split into overview + detail. |
+| A cycle that never actually returns | That is a Flowchart arranged in a circle. Use Flowchart and show the real endpoint. |
+
+---
+
+## 8. Examples
+
+- `assets/example-loop.html` — minimal light: six-station self-improving operating loop.
+- `assets/example-loop-dark.html` — the same geometry under the dark token inversion.
+- `assets/example-loop-full.html` — editorial page with the flagship loop, three summary cards, and colophon.

package/framework/skills/diagram-design/references/type-medallion.md

@@ -0,0 +1,356 @@
+# Medallion
+
+**Best for:** documenting a multi-tier data-storage layout where each tier is a distinct *quality / access level* of the same dataset — typically raw landing zone, anonymised, staging/cleaned, aggregated business indicators, and cold archive. Used when the reader needs to see at a glance *what each bucket contains*, *who writes it*, *with what tool and format*, and *how data is promoted between tiers*.
+
+Prefer **Process** if the subject is a workflow with role lanes. Prefer **High-Level** if the subject is the cluster architecture rather than the storage tier organisation.
+
+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. The rule shapes mirror `type-process.md` and `type-data-flow.md` so color override, focal rule, and reproducibility checklist read identically across types.
+
+---
+
+## 1. Inputs — the parameter contract
+
+```yaml
+title:    "Five-Tier Medallion Architecture"
+subtitle: "Quarterly survey through Raw → Anonymized → Staging → Aggregated → Archive"
+
+tiers:                                # 3..6 tier columns, ordered left → right
+  - { name: "Raw",        bucket: "raw-bucket",        style: "outer",
+      fields: { tool: "NiFi · raw write",          format: "CSV · Parquet · JSON", writer: "Data Engineer",
+                example: ["Q1 dump · w/ PII", "verbatim CAPI export"] } }
+  - { name: "Anonymized", bucket: "anon-bucket",       style: "default",
+      fields: { tool: "Trino INSERT",              format: "Iceberg · partitioned", writer: "Data Engineer",
+                example: ["no name · address", "stable household ID"] } }
+  - { name: "Staging",    bucket: "staging-bucket",    style: "default",  color: "#c9a23a",   # warm yellow — analytical working zone
+      fields: { tool: "Trino · JupyterHub",        format: "Iceberg · cleaned",     writer: "Data Scientist",
+                example: ["weighted records", "harmonised codings"] } }
+  - { name: "Aggregated", bucket: "aggregated-bucket", style: "focal",  focal: true,
+      fields: { tool: "Trino INSERT · SAS JDBC",   format: "Iceberg · indicators",  writer: "Data Scientist",
+                example: ["unemployment rate", "labour participation"] } }
+  - { name: "Archive",    bucket: "archive-bucket",    style: "cold",
+      fields: { tool: "MinIO lifecycle",           format: "cold tier · immutable", writer: "Data Administrator",
+                example: ["historical Q1–Q4 sets", "5+ years retained"] } }
+
+example_label: "Quarterly survey example" # bottom field label (varies per domain)
+
+promotions:                           # adjacent-tier arrows; len = n_tiers - 1
+  - { from: 0, to: 1, label: "PII REMOVE",    style: "normal"    }
+  - { from: 1, to: 2, label: "CLEAN+WEIGHT",  style: "normal"    }
+  - { from: 2, to: 3, label: "AGGREGATE",     style: "focal"     }    # auto-accent because target is focal
+  - { from: 3, to: 4, label: "LIFECYCLE",     style: "lifecycle" }    # dashed
+
+paths:                                # 0..2 write-method cards at the bottom (optional)
+  - { tag: "SQL PATH",      title: "Trino INSERT INTO … SELECT",
+      sub: "filter · reshape · join · aggregate — set-based transforms" }
+  - { tag: "NOTEBOOK PATH", title: "DuckDB + Python/R in JupyterHub",
+      sub: "stats · ML · interactive analysis — row-iterative work" }
+
+dark: false
+```
+
+**Reserved field semantics:**
+- `tiers[i].style` — one of `outer`, `default`, `focal`, `cold`. Drives the card's fill/stroke palette (§2.4).
+- `tiers[i].focal: true` — exactly **one** tier may declare this. Overrides `style` to `focal` and switches the promotion arrow *into* this tier to `focal` automatically.
+- `tiers[i].fields` — `{tool, format, writer, example}`. `example` is a 1- or 2-item list; the section heading uses `example_label`.
+- `tiers[i].color` — optional `"#hex"` per-tier color override. See §4.
+- `promotions[].style` — `normal` | `focal` | `lifecycle`. The connector rule (§3) binds each style to fixed stroke / dash / marker.
+- `paths` — 0–2 entries. When 0 entries, the bottom row is omitted and `viewBox_h` shrinks accordingly.
+
+---
+
+## 2. Layout formulas — deterministic geometry
+
+```
+# Tier dimensions
+tier_w           = 172
+tier_h           = 380
+tier_gap         = 16
+left_pad         = 16
+right_pad        = 100
+n_tiers          = len(tiers)
+
+# Canvas
+viewBox_w        = left_pad + n_tiers * tier_w + (n_tiers - 1) * tier_gap + right_pad
+                                                    # 5 tiers → 16 + 860 + 64 + 100 = 1040
+arc_band_h       = 80                               # space above tiers reserved for promotion arcs
+path_h           = 56
+path_gap         = 16                               # gap between tier row and path row
+bottom_pad       = 16
+viewBox_h        = arc_band_h + tier_h + (path_gap + path_h if paths else 0) + bottom_pad
+                                                    # with paths → 80+380+72+16 = 548
+                                                    # without paths → 80+380+16 = 476
+
+# Tier positions
+tier_x(i)        = left_pad + i * (tier_w + tier_gap)    # 16, 204, 392, 580, 768
+tier_y           = arc_band_h                            # 80 — tier tops sit just below the arc band
+tier_cx(i)       = tier_x(i) + tier_w/2                  # 102, 290, 478, 666, 854
+
+# Promotion arcs (between adjacent tiers — over the top, anchored at tier top-centers)
+arc_src_x(i)     = tier_cx(i)                            # top-center of tier i      (102, 290, 478, 666)
+arc_dst_x(i)     = tier_cx(i+1)                          # top-center of tier i+1    (290, 478, 666, 854)
+arc_peak_x(i)    = (arc_src_x(i) + arc_dst_x(i)) / 2     # midpoint                  (196, 384, 572, 760)
+arc_label_y      = 50                                    # label sits inside the arc, 30px below tier top
+
+# Path row (bottom)
+path_y           = tier_y + tier_h + path_gap            # 476
+path_w           = (viewBox_w - 2*left_pad - path_gap) / 2 if len(paths) == 2 else (viewBox_w - 2*left_pad)
+                                                          # Canonical 5-tier shape uses path_w=460 explicitly (see §2.5)
+```
+
+### 2.1 Background
+
+Solid paper fill across the full viewBox. No dot pattern.
+
+### 2.2 Tier card (172 × 380)
+
+Each tier renders as a rounded-rect card with a tinted header band, a centered bucket name, four labeled field rows, and a separated `example_label` section near the bottom.
+
+```
+tier_x(i),  tier_y       =  card top-left  (tier_y = 80, just below the arc band)
+header_band_h            = 40            # band from y=tier_y to y=tier_y+40 (i.e., 80..120)
+header_band_extra        = 10            # 10-px extension below band, same tint
+
+# Inside the card (absolute y; tier_y = 80):
+title_text            at (tier_cx(i), 106)                # node-name role, 13px, weight 700, ink
+bucket_text           at (tier_cx(i), 144)                # sublabel role, muted (accent on focal tier)
+
+field_x               = tier_x(i) + 16                    # 16-px left inset for field text
+field_w               = 140                               # 172-px tier_w minus two 16-px insets
+field rows (absolute y):
+  tool_label  at 180,    tool_value  at 186 (foreignObject, height 24)
+  format_label at 220,   format_value at 226 (foreignObject, height 24)
+  writer_label at 260,   writer_value at 266 (foreignObject, height 24)
+  # gap (open whitespace below writer row, above the example section)
+  example_label_text at 360,  example_line_0 at 374,  example_line_1 at 388
+```
+
+**Field-value wrapping rule:** field values (tool / format / writer) render inside an SVG `<foreignObject>` with an HTML `<div>` so they auto-wrap when text exceeds 140 px. Each `foreignObject` is 140 wide × 24 tall (fits 2 lines in the `sublabel` role at 1.25 line-height). The 26-px gap to the next field's label absorbs the second line cleanly.
+
+```svg
+<foreignObject x="{field_x}" y="{value_top}" width="140" height="24">
+  <div xmlns="http://www.w3.org/1999/xhtml"
+       style="font-family: {sublabel}; color: {muted}; line-height: 1.25;">
+    {field_value}
+  </div>
+</foreignObject>
+```
+
+The HTML namespace declaration on the `<div>` is required for SVG to render the inline content. Browsers and Playwright/Chromium render this faithfully; if your export target doesn't support `<foreignObject>` (some older Inkscape builds), hand-split long values into two `<tspan>` lines instead.
+
+Field labels use the `node-name` role at 11px in ink. Field values use the `sublabel` role in muted. Bucket and field values can be retinted by `color` override (§4).
+
+### 2.3 Tier styles
+
+Four canonical styles, picked per tier via `tiers[i].style`. Default mapping if `style` is omitted: tier 0 → `outer`, last tier → `cold`, focal tier (if any) → `focal`, others → `default`.
+
+| `style` | Card fill | Card stroke | Header band fill | Bucket text | Example value text |
+|---|---|---|---|---|---|
+| `outer` | `#FFFFFF` | `muted` 1.0 solid | `muted @ 0.10` | `muted` | `muted` |
+| `default` | `#FFFFFF` | `ink` 1.0 solid | `ink @ 0.06` | `muted` | `muted` |
+| `focal` | `accent @ 0.07` | `accent` 1.6 solid | `accent @ 0.14` | `accent` | `accent` |
+| `cold` | `paper-2` | `muted` 1.0 dashed `5,3` | `muted @ 0.18` | `muted` | `muted` |
+
+`rx = 6` on all card rects.
+
+**Focal styling note:** the focal tier's accent treatment cascades — its bucket text and its example-value lines render in accent. Other field values (tool/format/writer) stay muted; only the bucket name and the example payload carry the focal signal so the tier card doesn't fully drown in coral.
+
+### 2.4 Promotion arcs (over the top of the tiers)
+
+Each promotion is a **cubic Bézier arc** anchored at the **top-center** of each adjacent tier — `(tier_cx(i), tier_y)` to `(tier_cx(i+1), tier_y)`. The arc rises into the 80-px `arc_band` above the cards, peaking at y ≈ 20. Both the connector and its label remain fully visible — no paper masks, no overlap with card content.
+
+```svg
+<path d="M {tier_cx(i)},{tier_y} C {tier_cx(i)},0 {tier_cx(i+1)},0 {tier_cx(i+1)},{tier_y}"
+      fill="none" stroke="…" stroke-width="…" marker-end="…"/>
+```
+
+Concrete for the canonical 5-tier shape (`tier_y = 80`, tier centers at x = 102, 290, 478, 666, 854):
+- 0→1: `M 102,80 C 102,0 290,0 290,80`
+- 1→2: `M 290,80 C 290,0 478,0 478,80`
+- 2→3: `M 478,80 C 478,0 666,0 666,80`  (focal — accent)
+- 3→4: `M 666,80 C 666,0 854,0 854,80`  (lifecycle — dashed)
+
+The cubic geometry: anchor y = 80 (tier top), control y = 0 (top of viewBox). Curve peak at t=0.5 sits at y ≈ 20 (computed from `0.125·80 + 0.375·0 + 0.375·0 + 0.125·80 = 20`). Each arc spans one full tier-stride (188 px on the canonical layout), giving the connector a clearly visible vertical excursion.
+
+**Marker orientation:** `marker-end` with `orient="auto"` rotates the arrow to match the path tangent at the endpoint. The control point sits directly above the anchor so the tangent at landing is straight **down** — the arrowhead enters the top-center of tier *i+1* cleanly, pointing into the header band.
+
+**Chained anchors:** consecutive arcs share their meeting points (arc 0→1 ends at the same `(tier_cx(1), 80)` where arc 1→2 begins). Visually each tier's top-center acts as a "joint" — data arrives at the top of the card, gets transformed inside, and leaves out the top toward the next tier. The arrow-head plunge plus the next arc's straight-up emergence read as a single payload-handoff motion.
+
+| `style` | Stroke | Width | Dash | Marker |
+|---|---|---|---|---|
+| `normal` | `muted` | 1.4 | — | `arrow` |
+| `focal` | `accent` | 1.6 | — | `arrow-accent` |
+| `lifecycle` | `muted` | 1.4 | `4,3` | `arrow` |
+
+**Auto-style rules:**
+- If `promotions[k].to` references the **focal tier**, the style auto-promotes to `focal` (accent, width 1.6, `arrow-accent` marker).
+- If `promotions[k].to` references a tier with a **`color` override** (§4), the arrow inherits that hex — stroke = `C`, label fill = `C`, marker-end uses a color-matched marker (e.g., `arrow-yellow` for `#c9a23a`). Width stays at 1.4 — the color override is a "concern" signal, not a focal promotion. Lifecycle/dashed arrows keep their dash but adopt the color.
+- Focal wins if both apply (a colored tier marked focal still uses accent).
+
+**Label inside the arc:**
+- Anchored at `(arc_peak_x(k), arc_label_y)` = `((arc_src_x + arc_dst_x) / 2, 50)`.
+- `arrow-label` role at 10px with `letter-spacing=0.08em`, uppercase. Color matches the arrow stroke.
+- **No mask rect needed** — the cubic curve peaks at y ≈ 20 and the label sits at y=50, well below the curve. The label floats inside the open space *enclosed* by the arc, reading "X transforms into Y" with the arc itself as the visual frame.
+
+For shorter inter-tier gaps (if `tier_gap` is overridden below the default 16 px), the arc anchors `arc_inset` may need to shrink correspondingly to keep the arc visible.
+
+### 2.5 Path row (bottom, optional)
+
+Up to **2** write-method cards. The canonical 5-tier shape (with `arc_band_h = 80`):
+
+```
+path_y      = 476       # tier_y + tier_h + path_gap = 80 + 380 + 16
+path_h      = 56
+path_x[0]   = 16
+path_w[0]   = 460
+path_x[1]   = 16 + 460 + 16 = 492
+path_w[1]   = 460
+```
+
+(Both paths land 460-wide despite the viewBox being 1040 — the right pad is taken from the card's tier strip, not the path strip. Keep `path_w=460` for the canonical 5-tier shape. For other tier counts, derive `path_w = (viewBox_w - 2*left_pad - path_gap) / 2`.)
+
+Per-card content:
+- Container rect: white fill, `ink @ 0.20` stroke width 1, `rx=6`.
+- Tag chip: rect at `(path_x + 8, path_y + 6)`, `h=12 rx=2`, fill transparent, stroke `ink @ 0.30` width 0.8. Tag text centered inside in the `eyebrow` role with letter-spacing 0.08em, ink.
+- Title at `(path_x + 80, path_y + 30)`: `node-name` role at 11px, ink.
+- Sub at `(path_x + 80, path_y + 46)`: `sublabel` role, muted.
+
+---
+
+## 3. Connector rules (mandatory)
+
+Three styles, bound to topology. Mirror §3 of `type-process.md` so the rule reads identically.
+
+```svg
+<defs>
+  <marker id="arrow"        markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0, 8 3, 0 6" fill="{muted}"/></marker>
+  <marker id="arrow-accent" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0, 8 3, 0 6" fill="{accent}"/></marker>
+  <!-- Per-color markers: declare one per custom tier color in use. -->
+  <marker id="arrow-yellow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0, 8 3, 0 6" fill="#c9a23a"/></marker>
+</defs>
+```
+
+Add a new `<marker>` for each `color` override used in the diagram. Naming convention: `arrow-{semantic}` (e.g., `arrow-yellow`, `arrow-slate`, `arrow-red`) — matches the recommended palette so the marker id reads cleanly in source.
+
+**Z-order:** promotion arcs draw **before** any tier card rect, so the cards layer on top and any arc overshoot is masked inside the cards.
+
+**Arc shape rule:** medallion promotions are always **cubic arcs over the top** of the tier strip, anchored at the **top-center** of source and target tiers; control points directly above anchors at y=0. No horizontal "through the gap" lines — the arc-over-top is what makes connector + label both clearly visible.
+
+---
+
+## 4. Component color override
+
+Any tier or path entry accepts an optional `color: "#hex"`. Mirrors `type-process.md` §4 / `type-data-flow.md` §4.
+
+### 4.1 Per-tier `color`
+
+Applied to:
+
+| Element | Light | Dark |
+|---|---|---|
+| Card fill | `rgba(C, 0.07)` | `rgba(C_light, 0.10)` |
+| Card stroke | `C` (width 1.4) | `C_light` (width 1.4) |
+| Header band fill | `rgba(C, 0.14)` | `rgba(C_light, 0.18)` |
+| Title text | ink (unchanged — title stays readable) | ink (unchanged) |
+| Bucket text | `C` | `C_light` |
+| Example values | `C` | `C_light` |
+| Field labels / field values | **unchanged** (ink / muted) | **unchanged** |
+| Connectors touching this tier | **unchanged** — topology-driven | **unchanged** |
+
+`C_light` = the same hex lightened ~15% for dark-mode contrast.
+
+### 4.2 Per-path `color`
+
+Replaces the path card's stroke with `rgba(C, 0.45)` and the tag chip stroke with `rgba(C, 0.55)`. Tag text and title text use `C`. Sub stays muted.
+
+### 4.3 Rules
+
+- **Never on focal tiers.** The accent already carries that signal — a `color` on the focal tier is ignored.
+- **Never on the `cold` tier in addition to its dashed treatment.** Pick either dashed-cold or a custom color, not both.
+- **Cap at 2 custom-colored elements** per diagram (tier or path), in addition to the focal tier.
+- **Promotion arrows inherit the target tier's color** (§3 auto-style rule). A `color: "#c9a23a"` on the Staging tier means the CLEAN+WEIGHT arc landing in Staging is also rendered in yellow — connector, label, and arrowhead match. This keeps visual coherence: the colored tier and its incoming flow read as a single "concern" group. Arrows do **not** inherit color from the source tier — only the target — so the arc *out of* a colored tier reverts to muted (or to the next target's color/style).
+
+### 4.4 Semantic palette (recommended)
+
+Same palette as the other parametric types so a reader scanning multiple diagrams sees the same colors meaning the same thing:
+
+- `#b85450` rust-red — Security / Identity / Governance (PII-bearing tiers, audit tiers)
+- `#5a7d9a` slate-blue — Observability / Quality (validated tiers, monitored zones)
+- `#7a8c47` olive-green — Data Products / Publication (consumer-facing aggregates, public-release tiers)
+- `#c9a23a` warm yellow / gold — Analytical / Working zones (staging tier, scientist sandbox, intermediate computation surface)
+- `#8c6d3f` warm-brown — Backup / DR / Archive (alternative cold-tier styling)
+
+---
+
+## 5. Focal rule
+
+Exactly **one** focal tier per diagram. Defaults to the tier marked `focal: true` in inputs; if none is marked, defaults to the analytical pivot tier (typically `Aggregated` or whichever tier downstream consumers query).
+
+The focal tier:
+- Uses `style: focal` (accent fill + stroke 1.6 + accent header band).
+- Renders bucket text and example-value lines in accent.
+- Has its **incoming** promotion arrow auto-promoted to `style: focal` (accent).
+- Has its **outgoing** promotion arrow (if any) — typically into the cold archive — kept at the user-declared style (usually `lifecycle` dashed).
+
+If zero or >1 tiers carry `focal: true`, halt and ask the user.
+
+---
+
+## 6. Dark mode
+
+| Token | Light | Dark |
+|---|---|---|
+| Paper | `paper` | `ink` |
+| Ink | `ink` | `paper` |
+| Muted | `muted` | `soft` |
+| Accent | `accent` | `accent` |
+| Fog (cold tier fill) | `paper-2` | `paper @ 0.06` |
+| White (default card fill) | `#FFFFFF` | `paper @ 0.04` |
+| Card stroke ink (default style) | `ink` | `paper @ 0.30` |
+| Header band ink-tint | `ink @ 0.06` | `paper @ 0.08` |
+| Header band muted-tint | `muted @ 0.10` | `soft @ 0.16` |
+| Header band cold-tint | `muted @ 0.18` | `soft @ 0.24` |
+| Header band accent-tint | `accent @ 0.14` | `accent @ 0.20` |
+| 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 (5 tiers + 2 paths → 1040 × 548).
+2. Each tier card at `(tier_x(i), 80)` size `172 × 380`, `rx=6`.
+3. Tier header band fills `(tier_x(i), 80, 172, 40)` plus a 10-px extension under the band.
+4. Exactly **one** focal tier; its incoming arc auto-styled to `focal`.
+5. Promotion arcs render as cubic Béziers over the top of adjacent tiers; anchors at `(tier_cx(i), 80)` → `(tier_cx(i+1), 80)`, controls at y=0. Label inside the arc at `(arc_peak_x, 50)`, no mask.
+6. Bottom path row only present when `len(paths) > 0`. Cards at `y=476`, height 56.
+7. Custom component colors ≤ 2 in addition to the focal tier. Never on arrows.
+8. All promotion arrows + label masks emitted **before** any tier rect (z-order rule — cards mask the line ends inside the cards).
+9. The focal tier's bucket text and example values render in accent; the rest stay muted.
+10. `rx=6` on every tier and path card; `rx=2` on tag chips.
+
+---
+
+## 8. Anti-patterns
+
+- **More than one focal tier** — focal exists to mark the central analytical surface; >1 erases the signal.
+- **Cold styling on a non-archive tier** — the dashed fog look is reserved for retention/archive tiers.
+- **Bidirectional promotion arrows** — promotions always flow left → right. Backflow (e.g., an aggregate writing back to raw) is wrong for this type; use a different diagram.
+- **Custom-colored arrows** — connectors are topology-driven; color on a tier never spreads to its edges.
+- **Path cards explaining tier semantics** — paths describe *write methods* (how data moves between tiers), not what each tier holds. If you find yourself writing "Raw stores …" in a path card, that content belongs in the Raw tier's fields.
+- **Missing `example_label` content** — every tier should show a concrete example payload (quarterly survey rows, customer records, claims, …). Without it the diagram becomes abstract and stops earning its space.
+- **Promotion arrow label longer than the tier-gap label mask** — keep labels to ≤ 14 chars in the uppercase `arrow-label` role. Long verbs ("CALCULATE & SUMMARIZE") break the rhythm; shorten to "AGGREGATE" or split into two diagrams.
+
+---
+
+## 9. Examples
+
+- `assets/example-medallion.html` — minimal light (NatStat quarterly survey: 5 tiers, 2 path cards, Aggregated focal). Gallery default.
+- `assets/example-medallion-dark.html` — same, dark skin.
+- `assets/example-medallion-full.html` — same, editorial-card frame with subtitle + summary cards.
+
+---
+
+## 10. Worked YAML
+
+The YAML in §1 is the **complete** inputs definition for the shipped `example-medallion.html`. Every coordinate in that file's SVG is derivable from §2 applied to those inputs. The same YAML is embedded as a top-of-file HTML comment inside `example-medallion.html` so source view shows the parametric inputs immediately above the SVG.

package/framework/skills/diagram-design/references/type-nested.md

@@ -0,0 +1,22 @@
+# Nested Containment
+
+**Best for:** hierarchy through containment — scope boundaries, CLAUDE.md cascade, trust zones, folder nesting, blast radius. Outer = broader, inner = more specific.
+
+## Layout conventions
+- 3–5 rounded rectangles (`rx=8`), nested with consistent inset padding (24–32px horizontal, 32–36px vertical recommended).
+- Each level labeled at the top-left in Geist Mono eyebrow style (7–8px, letter-spacing 0.14em). Labels sit on a paper-colored mask rect over the ring's top border.
+- Stroke hierarchy: outer rings faint (`rgba(..,0.30–0.45)`), progressing to muted, to ink, to coral at the innermost focal.
+- Fills step up in opacity from outer to inner: `rgba(..,0.015)` → `rgba(..,0.025)` → accent-tint on the innermost.
+- Optional file-icon glyph (folded-corner rect) inside each level hints at scope content.
+- Italic Instrument Serif callouts (see `references/primitive-annotation.md`) — 1–2 max.
+
+## Anti-patterns
+- More than 6 levels (information disappears inward).
+- Irregular padding between levels — unaligned nesting looks accidental.
+- Content inside rings that isn't part of the hierarchy — use a sibling diagram.
+- Coral on multiple levels — hierarchy collapses.
+
+## Examples
+- `assets/example-nested.html` — minimal light
+- `assets/example-nested-dark.html` — minimal dark
+- `assets/example-nested-full.html` — full editorial

package/framework/skills/diagram-design/references/type-org-chart.md

@@ -0,0 +1,44 @@
+# Org Chart / Responsibility Map
+
+**Best for:** human teams, agent teams, support escalation maps, role ownership, routing maps, and any hierarchy where the reader needs to know *who owns what* rather than just parent → child structure.
+
+Use **Org Chart** instead of **Tree** when the nodes are people, agents, teams, roles, or accountable owners. A tree shows generic hierarchy. An org chart shows responsibility, invocation paths, and coverage gaps.
+
+## Layout conventions
+- Root owner or front door at top center. Use one coral focal node for the person/team/agent that receives ambiguous work.
+- Tier 1 nodes are departments, pods, queues, or primary routing buckets. Keep them horizontally aligned.
+- Tier 2 nodes are responsible owners or specialists. If there are more than 8 specialists, group them under pod nodes instead of making one giant row.
+- Use orthogonal connectors: vertical drop from parent → horizontal bus → vertical drops to children. No diagonal lines.
+- Each node should answer three questions when space allows:
+  1. **Name** — human-readable role/person/agent in Geist sans.
+  2. **How to invoke** — Slack handle, queue, issue prefix, or trigger in Geist Mono.
+  3. **Scope** — 2–4 terse ownership words, not a paragraph.
+- Show non-Slack / not-yet-live owners with dashed optional styling rather than hiding them. Missing routes are operationally important.
+- Put escalation / approval rules in a small side callout or footer strip, not as extra org nodes.
+
+## Node treatments
+- **Front door / command center:** focal treatment (`accent-tint` + `accent`).
+- **Team / pod / department:** backend treatment (white + `ink`).
+- **Individual agent / owner:** store or external treatment depending on whether it is active in the system.
+- **Gap / needs setup:** optional dashed treatment.
+- **Approval gate:** security treatment, separate from reporting hierarchy.
+
+## Complexity budget
+- Max visible org nodes: 12. If more, create an overview org chart plus separate detail charts per pod.
+- Max depth: 4 tiers.
+- Max direct reports under one parent: 5. If there are more, introduce grouping nodes.
+- Max coral nodes: 1. The org chart's job is clarity, not highlighting everything.
+- Max side callouts: 2.
+
+## Anti-patterns
+- Using a swimlane when the user's real question is "who does what?" Swimlanes explain process; org charts explain ownership.
+- Drawing every person/agent as an identical box. It hides the front door, specialists, gaps, and escalation paths.
+- Cramming full job descriptions into nodes. Keep scope phrases short and move detail to summary cards below.
+- Showing unavailable / not-yet-wired agents as normal active owners. Use dashed optional styling so gaps are visible.
+- Repeating Slack handles in body paragraphs when a node sublabel can carry the invocation path.
+- Floating legends in the org area. Use the standard bottom legend strip.
+
+## Examples
+- `assets/example-org-chart.html` — minimal light
+- `assets/example-org-chart-dark.html` — minimal dark
+- `assets/example-org-chart-full.html` — full editorial