@taloswork/ose-shared 0.1.7 → 0.1.9

package/skills/diagram-design/references/type-radar.md

@@ -0,0 +1,80 @@
+# Radar / Spider
+
+**Best for:** comparing 3–5 entities across 3–5 quantitative criteria on a single normalized 0–N scale. Capability matrices, product or backend evaluations, framework/team scorecards. Where a comparison table starts running out of horizontal room, radar makes the shape of each option legible at a glance.
+
+## Layout conventions
+
+- **N axes (3–5).** Equally spaced on a regular polygon-N. First axis at the top (`-90°`), going clockwise. **Above 5 → split or use a comparison table.**
+- **Five concentric grid rings** at fractions `0.2 / 0.4 / 0.6 / 0.8 / 1.0` of the radius. Drawn as closed polygons connecting the axis vertices at that fraction. Inner four at `rule` 0.10 opacity, outer ring at `rule-solid` 0.20 (a hint stronger to anchor the chart).
+- **Axis spokes** from center to each outer vertex. `rule-solid` 0.20 opacity. **No arrowheads.**
+- **Axis labels:** one word per spoke (Jobs-minimal). Geist sans 11px weight 600. Place 16px outside the outer ring along the axis vector. Top/bottom = `text-anchor="middle"`; right side = `start`; left side = `end`.
+- **Scale ticks** (e.g. `2 4 6 8 10`) only on the **first (top) axis** — putting numbers on every spoke clutters the chart fast. Geist Mono 8px, `muted`, anchored end at `cx − 6`.
+- **Series polygon:** stroke 1.5px at the series color, fill the same color at `0.18` opacity (`0.22` in dark). Stroke 1.8px on the focal series — a subtle weight bump.
+- **Vertex dots:** **only on the focal series**, `r=4` filled with the series color. Non-focal series are stroke-and-fill only. This is the load-bearing rule that keeps the chart readable at 4–5 series.
+- **Drawing order:** dots-pattern bg → grid rings → axis spokes → axis labels → scale ticks → non-focal series (smallest area first) → focal series → focal vertex dots → legend.
+- **Legend:** horizontal strip at the bottom (per the global rule). Swatch is a 16×8 rectangle (matches the polygon stroke+fill, not a circle), then the entity name. ~140px between entries. Optional italic tail on the right with the rationale (`"One coral. Position is the signal — color reserved for the recommended option."`).
+
+## Math
+
+For axis `i` (0-indexed) of `N`, value `v` on scale `S`, center `(cx, cy)`, outer radius `R`:
+
+```
+angle = -π/2 + 2π · i / N
+x = cx + (v / S) · R · cos(angle)
+y = cy + (v / S) · R · sin(angle)
+```
+
+A series with values `[v0, v1, ..., v(N-1)]` becomes a `<polygon>` with `points="x0,y0 x1,y1 ..."`.
+
+### Pre-computed reference (N=5, cx=500, cy=240, R=160, S=10, integer-rounded)
+
+| Fraction `f` | i=0 (top) | i=1 | i=2 | i=3 | i=4 |
+|---|---|---|---|---|---|
+| 0.2 | 500,208 | 530,230 | 519,266 | 481,266 | 470,230 |
+| 0.4 | 500,176 | 561,220 | 538,292 | 462,292 | 439,220 |
+| 0.6 | 500,144 | 591,211 | 556,317 | 444,317 | 409,211 |
+| 0.8 | 500,112 | 622,201 | 575,343 | 425,343 | 378,201 |
+| 1.0 | 500,80  | 652,191 | 594,369 | 406,369 | 348,191 |
+
+For an arbitrary value `v` on axis `i`, take the unit offset from the row above for that axis (e.g. axis 1: offset `(152, -49)` from center) and scale by `v/S`. **Drop coords as integers — fractional pixels in SVG render fine, but integers keep the file scannable.**
+
+### Worked example (N=5)
+
+Series `[9, 8, 9, 9, 9]` on a 0–10 scale becomes:
+
+```svg
+<polygon points="500,96 622,201 585,356 415,356 363,196"
+         fill="rgba(235,108,54,0.18)" stroke="#eb6c36" stroke-width="1.8"/>
+```
+
+Each vertex: `center + (v/10) · (outer_i − center)`, rounded to the nearest pixel.
+
+## Series palette
+
+The skill's "1-focal" rule still holds: `accent` is reserved for the focal series, and a small editorial palette (`series-1` through `series-5`, defined in [`style-guide.md`](style-guide.md)) covers the non-focal series. Don't reach for free-form colors.
+
+| Slot | Token | Light | Dark |
+|---|---|---|---|
+| Focal | `accent` | `#eb6c36` | `#f08a59` |
+| 1 | `series-1` (sage) | `#7c8f6f` | `#9caf8f` |
+| 2 | `series-2` (dusty-blue) | `#5e7a9b` | `#82a0c0` |
+| 3 | `series-3` (mustard) | `#b8915a` | `#d3ad7a` |
+| 4 | `series-4` (rust-brown) | `#9c6b50` | `#b88670` |
+| 5 | `series-5` (slate) | `#6e6479` | `#8d8298` |
+
+## Anti-patterns
+
+- **More than 5 series** → mush. Split into two charts (e.g. "best by latency" + "best by ops") or switch to a comparison table.
+- **Axes on inconsistent native scales** (one 0–100, another 0–1) without normalization. **Always normalize to 0–N first** — radar polygons compare *shapes*, not absolute values.
+- **Zero-baseline tricks** — starting the inner ring at v=5 to amplify differences. The grid starts at 0; if differences look small, that's the truthful reading.
+- **Dots on every series.** Only the focal carries dots. Adding them to all 4–5 series turns the chart into a bead curtain.
+- **Radar with 2 series** — a comparison bar chart or a 2-row table is clearer.
+- **Non-quantitative axes.** All axes must be measurable on the same normalized scale. "Speed" + "color" + "year" mixes don't belong on a radar.
+- **Mono-font axis labels.** Names go in Geist sans (the global rule). Mono is for technical sublabels only.
+- **Rainbow palette.** Even with the new `series-*` tokens, you don't need all 5 in one chart — use only as many as you have non-focal entities.
+
+## Examples
+
+- `assets/example-radar.html` — minimal light. 4 storage backends × 5 workload dimensions, MinIO focal.
+- `assets/example-radar-dark.html` — minimal dark, same data.
+- `assets/example-radar-full.html` — full editorial: container framing + 4 cards (one per backend) with varied widths + footer.

package/skills/diagram-design/references/type-scatter.md

@@ -0,0 +1,39 @@
+# Scatter Plot
+
+**Best for:** correlation and distribution — two continuous variables plotted against each other. Use when the relationship (or lack of one) between variables is the message, or when you need to identify clusters, outliers, and high/low performers.
+
+## Layout conventions
+
+- **Plot area margins:** left 80px, bottom 60px, top 40px, right 40px — inside `0 0 1000 500` viewBox.
+- **Point count:** 5–30 points. Fewer → just describe the relationship in prose; more → bin into a density contour.
+- **Axes:** X at y=420 (baseline), Y at x=80. Both use Geist Mono 8px gridline labels. Gridlines 4–6 per axis at equal intervals.
+- **Point shape:** `<circle>` r=5 for standard points, r=6 for focal. Focal point in `accent` fill. Others in `muted @ 0.20` fill + `muted` stroke.
+- **Labels on points (optional):** Geist Mono 8px next to a point. Use a paper-fill rect mask behind the label. Label at most 2–3 points; not all.
+- **Trend line (optional):** `<line>` from lower-left to upper-right, stroke `rgba(45,49,66,0.25)` dashed 4,3. Never force a perfect fit — only add if the trend is visually obvious.
+- **Quadrant dividers (optional):** light dashed lines at the median x and y to split into quadrants. Label each quadrant in Geist Mono 8px, muted.
+
+### Point pattern
+
+```svg
+<!-- Non-focal point — paper mask + circle -->
+<circle cx="X" cy="Y" r="5" fill="#f5f5f5"/>
+<circle cx="X" cy="Y" r="5" fill="rgba(79,93,117,0.20)" stroke="#4f5d75" stroke-width="1"/>
+
+<!-- Focal point -->
+<circle cx="X" cy="Y" r="6" fill="#f5f5f5"/>
+<circle cx="X" cy="Y" r="6" fill="rgba(235,108,54,0.15)" stroke="#eb6c36" stroke-width="1.2"/>
+```
+
+## Anti-patterns
+
+- More than 30 points without clustering (jitter/mush).
+- Forced trend line when the data is genuinely scattered — dishonest.
+- Point labels on every point (label the focal and 1–2 notable outliers only).
+- Bubble size encoding (use a third axis label or color instead; bubble area perception is unreliable).
+- Axes that don't include zero when the absolute position matters; axes that do include zero when the range is tiny and far from zero.
+
+## Examples
+
+- `assets/example-scatter.html` — minimal light
+- `assets/example-scatter-dark.html` — minimal dark
+- `assets/example-scatter-full.html` — full editorial

package/skills/diagram-design/references/type-sequence.md

@@ -0,0 +1,130 @@
+# Sequence
+
+**Best for:** request/response flows, protocol exchanges, multi-actor interactions over time, API call traces, incident reconstructions, auth/token refresh paths with branching.
+
+## Layout conventions
+- Actors as boxes in a horizontal row at the top.
+- **Lifelines**: dashed vertical lines descending from each actor to the bottom.
+- Messages: horizontal arrows between lifelines; time flows top→down.
+- **Activation bar**: narrow rectangle (`w=8`, muted fill, 0.8 hairline stroke) on a lifeline spanning the interval that actor holds control. Stack for nested calls.
+- Self-messages: short U-shaped loop returning to the same lifeline; label right of the loop.
+- Return messages: **dashed** stroke + **filled** marker (never open). Prefer muted; optionally match the originating call color when pairing multi-hop stacks. Headline success may use solid coral (see Message kinds).
+- Coral on the primary success response or headline message — one, maybe two. Actor focal strokes do not count toward the coral message budget.
+- When the flow **branches** (valid vs invalid token, retry, optional step), draw a **combined fragment** frame — do not invent free-floating if/else arrow clusters.
+
+## Message kinds
+
+| Kind | Stroke | Marker | When |
+|---|---|---|---|
+| Call (sync) | solid muted or link-blue | filled | Request that expects a reply |
+| Return | **dashed** muted (or match call color) | filled | Reply to a sync call — never solid |
+| Async / fire-and-forget | dashed muted | **open** arrowhead | Beacons, events, one-way notify |
+| Headline success | solid accent (≤1–2 messages) | accent filled | Primary happy-path response only |
+
+### Open arrowhead (async)
+
+Define once in `<defs>` and use for fire-and-forget only:
+
+```svg
+<marker id="arrow-open" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
+  <polyline points="0 0, 8 3, 0 6" fill="none" stroke="#4f5d75" stroke-width="1.2"/>
+</marker>
+```
+
+Dark mode: stroke `#bfc0c0` (muted on dark paper). Do not fill the open marker — the hollow head is the async signal. Return messages keep the **filled** marker even when dashed.
+
+## Combined fragments (`alt` / `opt` / `loop`)
+
+Use a rectangular **frame** that spans only the lifelines participating in the branch. Operator label is Geist Mono, uppercase, in a small tab at the top-left of the frame. Time still flows top→down inside the frame.
+
+### Frame primitive (shared)
+
+```svg
+<!-- Frame: light ink wash + hairline. Label tab top-left. -->
+<rect x="X" y="Y" width="W" height="H" rx="4"
+      fill="rgba(45,49,66,0.02)" stroke="rgba(45,49,66,0.22)" stroke-width="1"/>
+<!-- Operator tab -->
+<rect x="X" y="Y" width="40" height="16" rx="2"
+      fill="#f5f5f5" stroke="rgba(45,49,66,0.22)" stroke-width="1"/>
+<text x="X+20" y="Y+12" fill="#4f5d75" font-size="8"
+      font-family="'Geist Mono', monospace" text-anchor="middle"
+      letter-spacing="0.12em">ALT</text>
+```
+
+Dark mode: frame fill `rgba(245,245,245,0.04)`, stroke `rgba(245,245,245,0.22)`, tab fill = dark `paper` (`#2d3142`), tab text = dark `muted` (`#bfc0c0`).
+
+### Operators
+
+| Operator | Regions | Divider | Guard label |
+|---|---|---|---|
+| `opt` | 1 | none | `[if condition]` under the tab (Geist Mono 8px) |
+| `alt` | **2 max** | dashed horizontal hairline across the frame | `[guard]` on region 1; `[else]` (or a second guard) on region 2 |
+| `loop` | 1 | none | `[for each item]` or `[retry ≤ 3]` under the tab |
+
+### Guard + divider primitives
+
+```svg
+<!-- Guard: left-aligned inside the frame, mono -->
+<text x="X+12" y="GUARD_Y" fill="#4f5d75" font-size="8"
+      font-family="'Geist Mono', monospace" letter-spacing="0.04em">[token valid]</text>
+
+<!-- alt region divider -->
+<line x1="X+8" y1="DIV_Y" x2="X+W-8" y2="DIV_Y"
+      stroke="rgba(45,49,66,0.20)" stroke-width="1" stroke-dasharray="4,3"/>
+```
+
+### Fragment layout rules
+- Frame left/right inset ≥12px from the outermost participating lifeline centers (so activation bars stay inside the frame).
+- ≥24px between consecutive message y-levels inside a region (4px grid).
+- Guard sits in the first ~20px under the tab; first message in that region is ≥24px below the guard baseline.
+- Divider y on the 4px grid; ≥16px clear of messages above and below.
+- Nested fragments: **max 1 level**. Prefer two separate diagrams over deep nesting.
+- Default: **one** fragment per diagram. A second only if both stay under the complexity budget.
+- Coral stays on **one** headline success message across the whole diagram (usually the happy-path return inside the first `alt` region, or the final success outside a loop). Do not coral both `alt` branches.
+
+### Out of scope (do not invent)
+- `par`, `critical`, `break`, `ref`, and other UML operators — second PR if needed.
+- Participant create/destroy, found/lost messages, duration timing bars.
+
+## Complexity budget (sequence-specific)
+- Max lifelines: 5 (same as SKILL.md §7).
+- Max messages (arrows): 12.
+- Max combined fragments: 1 (hard default); 2 only if each is a single-region `opt`/`loop`.
+- Max `alt` regions: 2.
+- Max fragment nesting depth: 1.
+- Max coral elements: 2 (prefer 1 for fragment diagrams).
+
+If you exceed, split: overview (happy path) + detail (failure / refresh path).
+
+## Lifeline primitive
+```svg
+<line x1="CX" y1="TOP" x2="CX" y2="BOTTOM"
+      stroke="rgba(45,49,66,0.20)" stroke-width="1" stroke-dasharray="3,3"/>
+```
+
+## Activation bar primitive
+```svg
+<rect x="CX-4" y="TOP" width="8" height="H"
+      fill="rgba(45,49,66,0.06)" stroke="#4f5d75" stroke-width="0.8"/>
+```
+
+## Anti-patterns
+- Message arrow pointing *upward* (reverses time — never).
+- Activation bars that never close.
+- Labels sitting over another lifeline — shorten or shift y into a gap.
+- Swimlane-style lanes instead of lifelines (different grammar).
+- Drawing `if/else` as two free-floating arrow clusters with **no** fragment frame.
+- Nested `alt` inside `alt` (split into two diagrams).
+- Fragment operator label in Geist sans — must be mono: `ALT` / `OPT` / `LOOP`.
+- Coral on both `alt` branches.
+- Frame that covers actors with no messages inside the fragment.
+- Filled arrowhead on async fire-and-forget (use open marker).
+- Open arrowhead on return messages (returns stay filled + dashed).
+
+## Examples
+- `assets/example-sequence.html` — minimal light (cold-cache happy path)
+- `assets/example-sequence-dark.html` — minimal dark
+- `assets/example-sequence-full.html` — full editorial
+- `assets/example-sequence-oauth.html` — special: bearer call + `alt` refresh (light)
+- `assets/example-sequence-oauth-dark.html` — same special, dark
+- `assets/example-sequence-oauth-full.html` — same special, full editorial

package/skills/diagram-design/references/type-state.md

@@ -0,0 +1,21 @@
+# State Machine
+
+**Best for:** finite state logic — order status, auth state, connection lifecycle, form wizard, job queue status.
+
+## Layout conventions
+- States are rounded rectangles (`rx=8`), labeled in Geist.
+- **Start**: filled ink dot (`r=6`). **End**: ringed dot (outer `r=8` outline, inner filled `r=5`).
+- Transitions: curved arrows labeled in Geist Mono as `event [guard] / action` (omit sections you don't need).
+- Self-loops curve above the state.
+- Orient along the dominant flow direction (left→right or top→down); rearrange before crossing transitions.
+- Coral on the state the reader should notice — typically the error state, or "happy completion".
+
+## Anti-patterns
+- More transitions than states × 2 → likely two state machines.
+- "From any state" transitions drawn from every state — use a single annotation (`* → Error on timeout`) instead.
+- Unlabeled transitions (the whole point is *what triggers this*).
+
+## Examples
+- `assets/example-state.html` — minimal light
+- `assets/example-state-dark.html` — minimal dark
+- `assets/example-state-full.html` — full editorial

package/skills/diagram-design/references/type-swimlane.md

@@ -0,0 +1,20 @@
+# Swimlane
+
+**Best for:** cross-functional processes, RACI-style flows, vendor handoffs, multi-team shipping workflows.
+
+## Layout conventions
+- Horizontal lanes (or vertical columns) — one per actor/team. Label each lane in the left margin (or top) with a Geist Mono eyebrow.
+- Lane dividers: 1px hairlines.
+- Process steps are rectangles placed inside the lane of the actor performing them; arrows show flow.
+- Handoffs (arrows crossing lane boundaries) are the most important edges — consider coral on the handoff that introduces the most coupling or latency.
+- Don't force equal step count per lane; a lane with one step is fine.
+
+## Anti-patterns
+- Lanes without labels.
+- A step drawn across two lanes (pick one owner).
+- Arrows that snake back and forth — reorder steps so the flow is mostly straight.
+
+## Examples
+- `assets/example-swimlane.html` — minimal light
+- `assets/example-swimlane-dark.html` — minimal dark
+- `assets/example-swimlane-full.html` — full editorial

package/skills/diagram-design/references/type-timeline.md

@@ -0,0 +1,20 @@
+# Timeline
+
+**Best for:** release history, project milestones, incident timelines, roadmaps, changelog visualizations.
+
+## Layout conventions
+- Horizontal hairline baseline across the middle (`stroke-width=1`).
+- Tick marks at time boundaries (quarters, months, sprints) with date labels below in Geist Mono.
+- Events: small filled circles (`r=4`) on the baseline. Labels alternate above and below to prevent collision, connected to the circle with a 1px hairline drop.
+- Major milestones: coral circle (`r=6`) + bold Geist label.
+- Time scale must be honest: if intervals are non-equal, space the circles non-equally. Don't fake linear spacing for aesthetics. Break the axis visibly if a region is too dense.
+
+## Anti-patterns
+- Equal-spacing events that aren't equally spaced in time.
+- Missing axis labels ("what unit is this?").
+- Crowded labels without vertical offset — illegible.
+
+## Examples
+- `assets/example-timeline.html` — minimal light
+- `assets/example-timeline-dark.html` — minimal dark
+- `assets/example-timeline-full.html` — full editorial

package/skills/diagram-design/references/type-tree.md

@@ -0,0 +1,24 @@
+# Tree / Hierarchy
+
+**Best for:** org charts, dependency trees, taxonomy, file trees, decision breakdowns, skill trees.
+
+## Layout conventions
+- Root at top, children fan out below (or root at left, children to right).
+- Nodes are small labeled rectangles (`rx=6`), Geist 12px 600 name + optional Geist Mono 9px sublabel. Width 120–180px, height 40–52px.
+- **Connectors are orthogonal (elbow-style), never diagonal.** Parent drops a short vertical line, then a horizontal bus connects siblings, then each child has a short vertical drop into its top edge. 1px muted stroke.
+- Leaf indicator: thinner stroke (0.8) or different fill — OR let terminal position do the work.
+- Max depth: 4 (root + 3 tiers). Max breadth per level: 5.
+- Coral on **one** node: root OR critical leaf. Not both.
+- Draw connectors before nodes.
+
+## Anti-patterns
+- Tree 5+ levels deep on a single page (illegible — split).
+- Nodes of wildly varying widths — pick 2 widths max.
+- Diagonal connector lines.
+- Skipped levels (parent connected to grandchild with no middle).
+- Coral on root AND a leaf.
+
+## Examples
+- `assets/example-tree.html` — minimal light
+- `assets/example-tree-dark.html` — minimal dark
+- `assets/example-tree-full.html` — full editorial

package/skills/diagram-design/references/type-venn.md

@@ -0,0 +1,26 @@
+# Venn / Set Overlap
+
+**Best for:** intersection of concepts/domains, shared attributes between categories, "where A meets B", ikigai-style frames (desirable × feasible × viable).
+
+## Layout conventions
+- **Prefer 2 or 3 circles.** Avoid 4+ (unreadable — use a matrix instead).
+- Circle stroke: 1px hairline, color per-set (ink, muted, soft).
+- Circle fill: very low-opacity tint — `rgba(45,49,66,0.04)` for ink set, `rgba(79,93,117,0.05)` for muted. Tints compound naturally in overlap regions.
+- Radii: equal when sets are comparable in size; proportional when sets are meaningfully different. Don't fake equal sizes for aesthetics.
+- **Set labels** placed outside the circle, NEVER crossing the stroke. Geist 12–14px 600 for the set name, optional Geist Mono 9px sublabel.
+- **Intersection labels** placed inside the overlap region, Geist 12px 600, centered. For small overlaps, use a leader line to a label in clear space.
+- **Coral accent** on the ONE focal intersection — the "sweet spot". Either coral label stroke OR clipPath-bounded coral fill tint (`rgba(235,108,54,0.10)`).
+- Circle centers and radii divisible by 4.
+
+## Anti-patterns
+- Unlabeled regions — reader can't tell which set is which.
+- Circles that don't overlap when overlap is the point.
+- Equal-sized circles when sets are obviously different (dishonest).
+- Coral on multiple overlap regions (focal signal dies).
+- Labels sitting on top of circle strokes (illegible).
+- 4+ circles where 2–3 would do.
+
+## Examples
+- `assets/example-venn.html` — minimal light
+- `assets/example-venn-dark.html` — minimal dark
+- `assets/example-venn-full.html` — full editorial