@taloswork/ose-shared 0.1.8 → 0.1.10

package/skills/diagram-design/references/primitive-sketchy.md

@@ -0,0 +1,43 @@
+# Sketchy Filter (hand-drawn variant)
+
+Optional displacement filter that wobbles every stroke and edge slightly — turns any minimal variant into a hand-drawn "editorial" register without changing layout. Use when the diagram accompanies an essay rather than technical docs.
+
+## Grammar
+
+```svg
+<defs>
+  <filter id="sketchy" x="-2%" y="-2%" width="104%" height="104%">
+    <feTurbulence type="fractalNoise" baseFrequency="0.02" numOctaves="2" seed="4"/>
+    <feDisplacementMap in="SourceGraphic" scale="1.5"/>
+  </filter>
+</defs>
+
+<!-- Apply to a group wrapping shapes — NOT text -->
+<g filter="url(#sketchy)">
+  <!-- rects, paths, circles, lines go here -->
+</g>
+
+<!-- Text sits OUTSIDE the filtered group — legibility stays crisp -->
+<text ...>Labels go here</text>
+```
+
+## Tuning
+
+| Parameter | Range | Effect |
+|---|---|---|
+| `baseFrequency` | 0.01–0.04 | Lower = lazy wavy lines; higher = jittery. 0.02 default. |
+| `numOctaves` | 1–3 | More = more noise detail. 2 is plenty. |
+| `scale` | 1–6 | 1 barely-there, 1.5 default, 2 visible, 4+ cartoon. |
+| `seed` | integer | Swap for a different random pattern. |
+
+## Critical rule
+Filter shapes, NOT text. Displacement-mapped text becomes illegible. Structure your SVG so text is in a sibling group outside the filtered group.
+
+## When to use
+- Essay / blog post / newsletter where the diagram is the hero of a narrative page.
+- "Working sketch" register — showing something is mid-thought, not final architecture.
+
+## When not to use
+- Technical documentation (precision matters).
+- Diagrams with dense labels or tight alignments (filter reads as noise).
+- Dark variants — wobble reads as artifact on dark backgrounds. Test first.

package/skills/diagram-design/references/primitive-terminal.md

@@ -0,0 +1,76 @@
+# Terminal Window (CLI-chrome variant)
+
+Optional full-page skin that wraps any diagram in a fake terminal window — titlebar with three dots, a `$` prompt line, monospace type throughout. Use for dev-tool announcements, CLI-product posts, and technical social cards where a screenshot needs to read as "terminal," not "editorial doc."
+
+This is a **second, fixed skin** — see [style-guide.md § Terminal skin](style-guide.md#terminal-skin-opt-in-alternate) for the token table. It does not inherit from `onboarding.md` brand tokens and isn't part of the light/dark inversion rule; every terminal example uses the same nine tokens regardless of the host site's brand.
+
+## Grammar
+
+```html
+<div class="terminal">
+  <div class="titlebar">
+    <div class="dot accent"></div>
+    <div class="dot"></div>
+    <div class="dot"></div>
+    <div class="titlebar-name">loop.sh — self-improving-loop</div>
+  </div>
+  <main class="frame">
+    <p class="prompt">
+      <span class="sign">$</span> diagram-design render --type loop
+    </p>
+    <h1># The self-improving loop</h1>
+    <svg>...</svg>
+  </main>
+</div>
+```
+
+```css
+body {
+  background: var(--terminal-page);
+}
+.terminal {
+  background: var(--terminal-paper);
+  border: 1px solid var(--terminal-border);
+  border-radius: 12px;
+}
+.titlebar {
+  background: var(--terminal-bar);
+  border-bottom: 1px solid var(--terminal-border);
+}
+.dot {
+  background: var(--terminal-soft);
+}
+.dot.accent {
+  background: var(--terminal-accent);
+}
+```
+
+Inside the SVG, swap the default light/dark tokens 1:1 for their `terminal-*` equivalents: `paper` → `terminal-paper`, `ink` → `terminal-ink`, `muted`/`soft` → `terminal-muted`/`terminal-soft`, `accent`/`accent-tint` → `terminal-accent`/`terminal-accent-tint`. The hub/focal-node pattern (inverted fill for the one highlighted element) still applies.
+
+## Typography
+
+**Everything is monospace** — this is the one variant where that's correct. Drop Instrument Serif and Geist sans entirely; set the page title in mono, bold, prefixed with `# ` (reads as a comment line). The eyebrow becomes a shell prompt: `$ ` in `terminal-accent`, the command in `terminal-muted`.
+
+Run every text role about **1–2px above** the default type scale in `style-guide.md` (e.g. `node-name` 12px → 14px, `sublabel`/`arrow-label` 8–9px → 9–10px, hub label 16px → 18px). Monospace at the default sizes reads small next to the sans/serif mix it's replacing, and these cards are usually viewed at social-feed scale, not full-bleed.
+
+## Titlebar dots
+
+Three 10px circles, macOS-style. The **1-accent rule caps the color use here too**: one dot is `terminal-accent`, the other two are `terminal-soft`. Do not use a red/yellow/green traffic-light triad — that's a second and third hue, which the palette forbids.
+
+## Critical rules
+
+- No pure black (`#000000`) — use `terminal-page` (`#0a0a0a`) / `terminal-paper` (`#141414`). Same rule as the default skin, same reason: true black clips on OLED and in print.
+- One accent only. If a diagram needs a second focal element, use `terminal-ink` (white) for emphasis via weight/size, not a second color.
+- Background dot-grid pattern (if used) stays `rgba(255,255,255,0.06–0.08)` — barely visible texture, not a visual competitor to the titlebar chrome.
+
+## When to use
+
+- Dev-tool / CLI-product launch posts (npm package, CLI flag, terminal-based workflow).
+- Technical social cards where "this is a tool for engineers" is part of the message.
+- Screenshots meant to pop in a dark-mode-heavy feed (X, Discord, dev blogs).
+
+## When not to use
+
+- Editorial / long-form posts — pair with the default light or full-editorial variant instead.
+- Brand-matched output from `onboarding.md` — terminal is a fixed skin, not brand-tokenized. Don't try to reconcile the two.
+- Any diagram where the audience isn't developer-coded to read `$`/`#`/titlebar-dots as chrome rather than content.

package/skills/diagram-design/references/semantic-patterns.md

@@ -0,0 +1,122 @@
+# Semantic patterns
+
+Semantic patterns describe **what a system does**; the 27 visual types describe **how information is arranged**. Choose a pattern first when behavior, state, enforcement, or risk is load-bearing, then use its nearest visual type as the layout grammar. If no pattern matches, choose a visual type directly.
+
+Use one primary pattern per figure. A second pattern may supply at most one supporting primitive; if both need full treatment, split overview and detail. Labels and outcomes must remain complete in a static frame.
+
+## Routing table
+
+| The reader must understand… | Semantic pattern | Nearest visual type |
+|---|---|---|
+| Many arrivals competing for finite service capacity | **Fan-in queue / bottleneck** | Data flow |
+| Repeated questions, inputs, controls, and outputs across stages | **Stage framework with semantic slots** | Process |
+| A loose conversation becoming a durable structured record | **Unstructured input → structured artifact** | Data flow |
+| Why two policy decisions differ and where they first diverge | **Paired policy-evaluation traces** | Flowchart |
+| Which routes cross a trust boundary and which routes are blocked | **Secure paved road** | Architecture |
+| Which controls apply at each enforcement surface | **Governance / control catalog** | Layer stack |
+| How defenses reduce risk and what risk remains | **Compensating security layers** | Layer stack |
+
+## 1. Fan-in queue / bottleneck
+
+**Selection triggers:** Several producers converge on one reviewer, service, gate, or constrained resource; the story depends on arrival rate, queue depth, wait, capacity, or backpressure.
+
+**Required primitives:** Distinct sources; fanned ingress; an ordered queue with visible slots and count; a capacity/service-rate label; one constrained service point; admitted and deferred/rejected outcomes. Label units (`8/hour`, `3 slots`), not just “high.”
+
+**Complexity budget:** ≤5 sources, ≤5 queue slots, one bottleneck, two outcomes, and ≤9 primary nodes. Aggregate excess sources as a named cohort.
+
+**Anti-patterns:** Equal-width pipeline that hides contention; arrows merged before they can be traced; capacity implied only by box size; decorative pile-up; animation that changes item order; red alone meaning overloaded.
+
+**Static fallback:** Show the representative final queue, numeric count/capacity, bottleneck label, and both outcome paths. A still must reveal why work waits.
+
+**Nearest visual type:** **Data flow** by default; use **Process** when service stages, rather than sources, dominate.
+
+## 2. Stage framework with semantic slots
+
+**Selection triggers:** A lifecycle or operating model repeats the same semantic questions across stages, commonly Question, Input, Governance, and Output. Cross-stage comparability matters more than message timing.
+
+**Required primitives:** Ordered stage headers; a consistent slot grid; explicit empty/not-applicable slots; stage-to-stage handoff; stable slot labels; one primary output per stage. Preserve slot order in every stage.
+
+**Complexity budget:** 3–6 stages, 3–4 slot kinds, ≤20 populated cells, ≤2 lines per cell. Split detail when a cell needs prose.
+
+**Anti-patterns:** Each stage invents a different internal layout; slot meaning encoded by position with no labels; fake precision from dozens of cells; confusing stage order with ownership lanes; shrinking text to keep one canvas.
+
+**Static fallback:** Render the full stage × slot matrix with handoffs and explicit `—` or `Not applicable` entries. Do not depend on staged reveal to teach the schema.
+
+**Nearest visual type:** **Process**; use **Swimlane** only when the repeated rows represent owners rather than semantic slots.
+
+## 3. Unstructured input → structured artifact
+
+**Selection triggers:** Dialogue, notes, prompts, or a rambling request are elicited, normalized, and written into a durable brief, ticket, record, schema, or other structured artifact.
+
+**Required primitives:** Source utterance(s); clarifying questions; extracted field/value pairs; a named transformation; the durable artifact boundary; provenance links from representative statements to fields; missing/unknown state.
+
+**Complexity budget:** ≤4 exchanges, ≤6 artifact fields, one transformation, and ≤3 provenance links. Show representative content, not a transcript.
+
+**Anti-patterns:** “AI magic” sparkle between two boxes; artifact shown as another chat bubble; fields appearing without sources; inventing certainty for missing facts; typing animation as the only readable copy.
+
+**Static fallback:** Show a short source excerpt beside the completed labeled artifact, with at least one provenance mapping and any unknown fields visible.
+
+**Nearest visual type:** **Data flow**; use **Process** when elicitation has several ordered gates.
+
+## 4. Paired policy-evaluation traces
+
+**Selection triggers:** Two otherwise similar requests reach different outcomes; the reader needs rule-by-rule `PASS`, `FAIL`, `SKIPPED`, or `NOT REACHED` state and the first divergence.
+
+**Required primitives:** The same ordered rules on both traces; explicit status text plus symbol/shape; inputs that differ; final outcomes; a labeled first-divergence marker; a distinction between `SKIPPED` (applicable flow intentionally bypassed) and `NOT REACHED` (evaluation stopped earlier).
+
+**Complexity budget:** Exactly 2 traces, 3–6 rules, one first divergence, ≤12 status cells, and one outcome per trace. Move rule prose to notes if labels exceed one line.
+
+**Anti-patterns:** Comparing two independently ordered flows; green/red dots without words; treating skipped and not-reached as synonyms; highlighting every difference; continuing a denied trace as if downstream rules ran.
+
+**Static fallback:** Show all rule states and both outcomes at once; use a persistent bracket/line and label for the first divergence.
+
+**Nearest visual type:** **Flowchart** for ordered decision logic; use **Sequence** only when messages between actors and time are also load-bearing.
+
+## 5. Secure paved road
+
+**Selection triggers:** A supported architecture creates a bounded route from intake/build to deployment; trust boundaries, privileged moments, permitted ingress, forbidden ingress, and approved versus blocked deploy paths are the point.
+
+**Required primitives:** Labeled trust boundaries; actors and identities; permitted ingress with a positive text label; forbidden ingress terminating at the boundary; approved deployment path; blocked bypass path; privileged gate; isolated runtime; audit destination. Use different line styles and stop symbols in addition to color.
+
+**Complexity budget:** ≤3 trust zones, ≤8 components, ≤10 paths, ≤2 forbidden paths, and one privileged gate. Split control detail into a catalog figure.
+
+**Anti-patterns:** Dashed box called “security” with no route semantics; forbidden arrow crossing into the protected zone; secrets or identity implied but unlabeled; every component styled as trusted; a bypass path that visually rejoins the approved route.
+
+**Static fallback:** Render every boundary and both permitted/forbidden routes. Blocked paths must visibly stop before entry or deployment.
+
+**Nearest visual type:** **Architecture**.
+
+## 6. Governance / control catalog
+
+**Selection triggers:** A control inventory must be understood by where it is enforced: authoring, workspace, merge/CI, deploy/runtime, or another named surface. A single checklist would hide those enforcement points.
+
+**Required primitives:** Enforcement-surface groups; named controls; enforcement actor (`code`, `platform`, `human`); timing (`write`, `merge`, `deploy`, `run`); bypassability or exception route; coverage/gap notation.
+
+**Complexity budget:** 3–5 surfaces, 3–7 controls per surface, ≤24 controls total, and ≤3 attributes per control. Summarize counts only when the item list exists elsewhere.
+
+**Anti-patterns:** 35 tiny pills; grouping by vague themes instead of enforcement point; mixing aspirations with enforced controls; icons without control names; claiming defense-in-depth without showing surface coverage.
+
+**Static fallback:** Show the complete grouped catalog with surface headers and text labels for actor and enforcement timing; preserve gaps and exceptions.
+
+**Nearest visual type:** **Layer stack**; use **DP security matrix** when role permissions, not enforcement surfaces, are the dominant comparison.
+
+## 7. Compensating security layers
+
+**Selection triggers:** No layer is perfect; each defense covers a failure left by the previous layer, and residual risk must visibly narrow, transfer, or remain through the stack.
+
+**Required primitives:** Ordered threat/risk input; named defensive layers; each layer's mitigation; explicit limitation or escape; residual-risk carrier between layers; final residual risk and consequence/response. Use labels or decreasing measures, never area alone.
+
+**Complexity budget:** 3–5 layers, one primary risk thread, ≤2 mitigations per layer, and one final residual-risk statement. Split multiple unrelated threats into separate figures.
+
+**Anti-patterns:** Implying the final layer makes risk zero; equal opaque slabs with no propagation; treating audit as prevention; shrinking shapes without numeric or verbal meaning; reversing prevention/detection/recovery order without explanation.
+
+**Static fallback:** Show the complete propagation chain: initial risk → mitigation → escaped risk at every layer → final residual risk and response.
+
+**Nearest visual type:** **Layer stack**; use **Nested** when containment boundaries, rather than ordered compensation, carry the meaning.
+
+## Composition rules
+
+- The semantic pattern may specialize status, boundary, queue, or propagation primitives; the selected type still owns page axis, connector grammar, spacing, and type-specific limits.
+- Apply the stricter of the pattern budget and visual-type budget. Semantic cells/statuses are not permission to exceed the nine-node overview target.
+- Use stable text for states and outcomes. Color, motion, and position reinforce meaning but never carry it alone.
+- Optional animation is a presentation layer, not another pattern. Load [`animation.md`](animation.md) only when motion is requested or materially clarifies ordered change.

package/skills/diagram-design/references/style-guide.md

@@ -0,0 +1,139 @@
+# Style Guide
+
+**The single source of truth for colors, typography, and tokens.** Every diagram draws from this — not from hex values inlined in other reference files. If you want to change the visual skin of Diagram Design, change this file.
+
+Default skin is a cool editorial palette — white-smoke paper, jet-black ink, atomic-tangerine accent, blue-slate muted. It's designed to look good out of the box; swap these values (or run [`onboarding.md`](onboarding.md)) and every new diagram inherits the new skin without touching any type-specific logic.
+
+To generate your own from a website URL, see [`onboarding.md`](onboarding.md).
+
+---
+
+## Tokens
+
+### Semantic roles
+
+Every token is referred to by **semantic role**, not by its hex value. Type references (`type-*.md`) and SKILL.md say `accent`, not `#f7591f`.
+
+| Role | Purpose | Default (light) | Default (dark) |
+|---|---|---|---|
+| `paper` | Page background, default node fill | `#f5f5f5` (white-smoke) | `#2d3142` (jet-black) |
+| `paper-2` | Diagram container bg, secondary fill | `#ececec` | `#393e53` |
+| `ink` | Primary text, primary stroke | `#2d3142` (jet-black) | `#f5f5f5` (white-smoke) |
+| `muted` | Secondary text, default arrow stroke | `#4f5d75` (blue-slate) | `#bfc0c0` (silver) |
+| `soft` | Sublabels, boundary labels | `#7a8399` | `#8e98ac` |
+| `rule` | Hairline borders | `rgba(45,49,66,0.12)` | `rgba(245,245,245,0.12)` |
+| `rule-solid` | Stronger borders, baselines | `#bfc0c0` (silver) | `rgba(191,192,192,0.25)` |
+| `accent` | Focal / 1–2 max per diagram | `#eb6c36` (atomic-tangerine) | `#f08a59` |
+| `accent-tint` | Fill for accent-bordered boxes | `rgba(235,108,54,0.08)` | `rgba(240,138,89,0.10)` |
+| `link` | HTTP/API calls, external arrows | `#2e5aa8` | `#6a95d8` |
+
+> **Brand palette source:** this skin maps to a five-color brand palette — `jet-black #2d3142`, `silver #bfc0c0`, `white-smoke #f5f5f5`, `atomic-tangerine #eb6c36`, `blue-slate #4f5d75`. The `soft`, `rule`, and `link` tokens are derived (lighter slate, ink-at-opacity, and a saturated variant in the blue-slate hue family) to cover roles the brand palette doesn't name directly.
+
+> **Note:** The pre-baked example HTML files in `assets/` were built under an earlier skin. Regenerating them against the current `style-guide.md` is a v5.1 task. New diagrams the skill produces will use the tokens above.
+
+### Inversion rule (light → dark)
+
+Any `rgba(28,25,23, X)` in light becomes `rgba(250,247,242, X)` in dark. Same opacities, RGB flipped. The accent gets a slight hue-shift brighter to read on dark paper.
+
+### Series palette (multi-series chart types only)
+
+A small set of desaturated, editorial-tone colors for chart types that genuinely need to distinguish multiple overlapping entities (currently: **radar**). The "1-focal" rule still holds — `accent` is reserved for the focal series; the palette below covers the rest.
+
+| Token | Light | Dark | Notes |
+|---|---|---|---|
+| `series-1` | `#7c8f6f` (sage) | `#9caf8f` | Non-focal series |
+| `series-2` | `#5e7a9b` (dusty-blue) | `#82a0c0` | Non-focal series |
+| `series-3` | `#b8915a` (mustard) | `#d3ad7a` | Non-focal series |
+| `series-4` | `#9c6b50` (rust-brown) | `#b88670` | Non-focal series |
+| `series-5` | `#6e6479` (slate) | `#8d8298` | Non-focal series |
+
+Fills sit at `0.18` opacity light, `0.22` dark; strokes use the full color. **Don't backfill these tokens to non-chart types** — architecture, swimlane, etc. continue to use muted-ink variants. The series palette is opt-in for diagrams where overlapping shapes demand distinguishable color, not a license to add color elsewhere.
+
+### Terminal skin (opt-in alternate)
+
+A self-contained palette for the terminal-window primitive (see [primitive-terminal.md](primitive-terminal.md)) — a CLI-chrome register for dev-tool posts and technical social cards. It does not replace the default skin above and isn't affected by onboarding; it's a second, fixed skin you opt into per-diagram.
+
+| Token | Hex | Purpose |
+|---|---|---|
+| `terminal-page` | `#0a0a0a` | Page background behind the window |
+| `terminal-paper` | `#141414` | Window body, node fill |
+| `terminal-bar` | `#1b1b1b` | Titlebar strip |
+| `terminal-border` | `#2b2b2b` | Window border, hairlines |
+| `terminal-ink` | `#f5f5f5` | Primary text, primary stroke (same white-smoke as default `ink`) |
+| `terminal-muted` | `#9a9a9a` | Secondary text, sublabels, ring stroke |
+| `terminal-soft` | `#5c5c5c` | Tertiary — inactive dots, spokes |
+| `terminal-accent` | `#ff5a36` | The one accent — focal station, prompt sign, active dot |
+| `terminal-accent-tint` | `rgba(255,90,54,0.12)` | Fill for accent-bordered boxes |
+
+**1-accent rule still holds.** Everything that isn't `terminal-ink` or `terminal-muted`/`terminal-soft` should be `terminal-accent` — never introduce a second hue.
+
+---
+
+## Typography
+
+| Role | Family | Size | Weight | Usage |
+|---|---|---|---|---|
+| `title` | Instrument Serif | 1.75rem | 400 | Page H1 |
+| `node-name` | Geist (sans) | 12px | 600 | Human-readable labels |
+| `sublabel` | Geist Mono | 9px | 400 | Port, protocol, URL, field type |
+| `eyebrow` | Geist Mono | 7–8px | 500, tracked 0.18em, uppercase | Type tags, axis labels |
+| `arrow-label` | Geist Mono | 8px | 400, tracked 0.06em | Arrow annotations |
+| `callout` | Instrument Serif *italic* | 14px | 400 | Editorial asides only |
+
+### Font stack
+
+```html
+<link href="https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&family=Geist:wght@400;500;600&family=Geist+Mono:wght@400;500;600&display=swap" rel="stylesheet">
+```
+
+**Load-bearing rule:** Mono is for *technical* content (ports, commands, URLs, field types). Names go in Geist sans. Page title is Instrument Serif. Italic Instrument Serif is reserved for annotation callouts (see [primitive-annotation.md](primitive-annotation.md)). **Never JetBrains Mono** as a blanket "dev" font.
+
+---
+
+## Stroke, radius, spacing
+
+| Token | Value | Use |
+|---|---|---|
+| `stroke-thin` | `0.8` | Tag-box outlines, leaf nodes |
+| `stroke-default` | `1` | Most strokes |
+| `stroke-strong` | `1.2` | Emphasis strokes |
+| `radius-sm` | `4` | Small tags |
+| `radius-md` | `6` | Node boxes |
+| `radius-lg` | `8` | Containers, rings |
+| `grid` | `4` | Every coord, size, and gap is divisible by 4 (hard rule) |
+
+---
+
+## Node type → treatment
+
+Semantic role combinations — reference these by name in type specs.
+
+| Type | Fill | Stroke |
+|---|---|---|
+| `focal` (1–2 max) | `accent-tint` | `accent` |
+| `backend` | `#ffffff` (white) | `ink` |
+| `store` | `ink @ 0.05` | `muted` |
+| `external` | `ink @ 0.03` | `ink @ 0.30` |
+| `input` | `muted @ 0.10` | `soft` |
+| `optional` | `ink @ 0.02` | `ink @ 0.20` dashed `4,3` |
+| `security` | `accent @ 0.05` | `accent @ 0.50` dashed `4,4` |
+
+---
+
+## Customizing the skin
+
+Three options:
+
+1. **Run onboarding** — see [`onboarding.md`](onboarding.md). Drop a URL; the skill extracts the palette + fonts and rewrites this file.
+2. **Edit by hand** — change the hex values in the tables above. Run the pre-output taste gate afterward to verify the accent still reads as "focal" against the new paper color.
+3. **Brand handoff** — paste your existing design-token JSON into a new section here and map its tokens to the semantic roles above.
+
+### Constraints (don't break these)
+
+- **Contrast**: `ink` must hit WCAG AA on `paper`. `muted` must hit AA on `paper` for 11px+ text.
+- **One accent**: pick one color for `accent`. Two accents erases the focal signal.
+- **No rainbow palette**: if your brand ships 8 colors, pick 3 (paper, ink, accent). The rest become `muted` variants.
+- **Serif + sans + mono**: three families, not more. If brand typography is all sans, keep Instrument Serif for `title` and `callout` anyway — the contrast is load-bearing.
+- **Paper is warm-neutral, not pure white**: pure white turns the design sterile. Pick a cream, bone, or light grey with a hint of warmth.
+- **Dot pattern is optional, not default**: the 22×22 dot pattern is an opt-in "dotted paper" variant (good for long-form editorial hero diagrams). The default background is a clean `paper` fill, no pattern. When the pattern is enabled, it should sit at ~10% opacity of `ink` on `paper` — visible but quiet.
+- **Container is clean by default**: the diagram sits directly on the page paper, no secondary container background or border. A framed variant (`paper-2` bg + `rule` border + 8px radius + padding) is available as an opt-in for card-heavy layouts, but don't reach for it by default — the extra chrome fights the figure.

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

@@ -0,0 +1,78 @@
+# Architecture
+
+**Best for:** system overviews, data-flow diagrams, integration maps, infra topology.
+
+## Layout conventions
+- Group components by tier or trust boundary (frontend → backend → data; public → private).
+- Primary flow runs left→right or top→down. Pick one and hold it.
+- Draw arrows before boxes so z-order puts connections behind components.
+- 1–2 coral focal nodes: the primary integration point, the primary data store, or the key decision node.
+- Dashed boundary rectangles mark regions (VPC, security group, trust zone); labels sit on a paper-colored mask over the boundary line.
+
+## Connector style
+
+**Rounded right-angle (orthogonal) connectors are MANDATORY** for all non-horizontal/vertical connections — diagonal `<line>` between off-axis nodes is a hard fail (see SKILL.md §6 Mandatory connector rules). Two-bend elbow path with `r=8`:
+
+```svg
+<!-- right+down: from (x1,y1) to (x2,y2), mid = (x1+x2)/2 -->
+<path d="M x1,y1 H mid-8 Q mid,y1 mid,y1+8 V y2-8 Q mid,y2 mid+8,y2 H x2"
+      fill="none" stroke="…" stroke-width="1.2" marker-end="url(#arrow)"/>
+```
+
+Flip the vertical signs for right+up. Use a plain `<line>` only when endpoints share the same x or y. Arrow labels sit on the vertical segment, centered horizontally on `mid` and vertically between the two corners.
+
+**Port selection — use top/bottom for vertical connectors.** When the destination is noticeably above or below the source, exit the source's top/bottom edge and enter the destination's top/bottom edge. Use a single-bend L-path (horizontal → corner → vertical into the node), not a left/right side port:
+
+```svg
+<!-- entering a node from its bottom (destination above source) -->
+<path d="M x1,y_src H x2-8 Q x2,y_src x2,y_src-8 V y_dst"
+      fill="none" stroke="…" stroke-width="1.2" marker-end="url(#arrow)"/>
+```
+
+Reserve left/right ports for connections that travel primarily horizontally. Entering a node from the side on a mainly-vertical path looks like the arrow punctures the node face rather than arriving from above or below.
+
+**Dashed paths — same routing rules.** Optional, return, async, and passive flows use `stroke-dasharray="4,3"` and a lighter stroke weight (`stroke-width="1"`). Apply the **same orthogonal routing, port-selection, and bridge/hop rules** as solid paths — the dash pattern only communicates semantic weight, not a different routing grammar. When a dashed path and a solid path must cross, bridge the dashed one (it is by definition the less important connection).
+
+**Zone label margin.** Leave ≥16px between the bottom of the zone eyebrow label and the top of the first enclosed node. Size the zone rect tall enough to contain this header gap (zone `y` = node_top − 32; label mask `y` = zone_y + 4).
+
+## Crossing arrows — bridge / hop
+
+When two orthogonal arrows must cross, add a small arc (hop/bridge) on the **less important** arrow at the crossing point. The more important arrow is drawn uninterrupted.
+
+```svg
+<!-- Horizontal hop over a vertical crossing at x=cx, on a line at y -->
+<path d="M x1,y H cx-8 a 8,8 0 0,1 16,0 H x2"
+      fill="none" stroke="…" stroke-width="1.2" marker-end="url(#arrow)"/>
+```
+
+`a 8,8 0 0,1 16,0` is an SVG arc: rx=ry=8, large-arc=0, sweep=1 (curves visually upward), advancing 16px right — creating an 8px-radius semicircular bump over the crossing. For a vertical hop over a horizontal, use `a 8,8 0 0,0 0,16` on the vertical path.
+
+Decide which arrow to bridge: bridge the one that is less semantically important (passive, secondary, write-back), or the one with lighter stroke weight (dashed, muted). Never bridge both.
+
+## Zone grouping
+
+Group 2+ nodes that serve the same tier or trust boundary with a zone rect — drawn **before** arrows and nodes (z-order: bg → zones → arrows → nodes):
+
+```svg
+<rect x="{x}" y="{y}" width="{w}" height="{h}" rx="8"
+      fill="rgba(45,49,66,0.02)" stroke="rgba(45,49,66,0.10)" stroke-width="0.8"/>
+<rect x="{label_x}" y="{y+4}" width="{label_w}" height="12" rx="2" fill="{paper}"/>
+<text x="{label_cx}" y="{y+13}" fill="rgba(45,49,66,0.40)" font-size="7"
+      font-family="'Geist Mono', monospace" text-anchor="middle" letter-spacing="0.14em">LAYER</text>
+```
+
+Rules:
+- Leave 12–16px above the first enclosed node — the eyebrow label sits in this margin.
+- Zone fill: `rgba(45,49,66,0.02)` (2% ink wash). Any stronger competes with node fills.
+- Max 3 zones per diagram. More and it reads like a swimlane (use that type instead).
+- Dark mode: swap `rgba(45,49,66,…)` → `rgba(245,245,245,…)` same opacities; label mask fill = `paper` (dark).
+
+## Anti-patterns
+- Every box in coral ("this is important too") — hierarchy collapses.
+- Bidirectional arrow when one direction is obvious from context.
+- Legend floating inside the diagram area.
+
+## Examples
+- `assets/example-architecture.html` — minimal light
+- `assets/example-architecture-dark.html` — minimal dark
+- `assets/example-architecture-full.html` — full editorial

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

@@ -0,0 +1,48 @@
+# Bar / Column Chart
+
+**Best for:** comparing discrete quantities across categories or time intervals — sprint velocity, monthly revenue, feature adoption, cohort counts. Use when each category has a single numeric value and the comparison between bars is the primary message.
+
+## Layout conventions
+
+- **Orientation:** Vertical bars (columns) are default. Horizontal bars are appropriate when category labels are long or you have more than 8 categories.
+- **Plot area margins:** left 80px (y-axis labels), bottom 60px (x-axis labels), top 40px, right 40px — inside a `0 0 1000 500` viewBox.
+- **Bar count cap:** 4–8 bars. More than 8 → group into periods or split into two charts.
+- **Bar width:** ≥ 50% of the column pitch (the gap should never exceed the bar). Typical: pitch=110px, bar=72px.
+- **Y-axis gridlines:** 4–6 horizontal lines at regular intervals. Stroke `rgba(45,49,66,0.08)` (very faint), 0.8px. X-axis baseline at `rgba(45,49,66,0.25)`, 1px.
+- **Y-axis labels:** right-aligned Geist Mono 8px muted, at x=72 (8px left of the plot area).
+- **X-axis labels:** centered below each bar, Geist sans 11px 600 for category names.
+- **Value labels:** Geist Mono 8px above each bar. Focal bar label in accent; others in muted.
+- **Focal bar:** 1 bar max in accent fill/stroke. All others in `muted @ 0.15` fill + `muted` stroke.
+- **Y-axis line:** thin vertical `<line>` at x=80 from y=40 to y=420.
+
+### Bar element pattern
+
+```svg
+<!-- Opaque paper mask prevents bleed from background -->
+<rect x="X" y="Y" width="W" height="H" fill="#f5f5f5"/>
+<!-- Bar body -->
+<rect x="X" y="Y" width="W" height="H" fill="rgba(79,93,117,0.15)" stroke="#4f5d75" stroke-width="1"/>
+<!-- Value label above bar -->
+<text x="X+W/2" y="Y-8" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle">VALUE</text>
+```
+
+Focal bar: replace fill with `rgba(235,108,54,0.12)`, stroke with `#eb6c36`, label fill with `#eb6c36`.
+
+## Anti-patterns
+
+- More than 8 bars without grouping (illegible at normal scale).
+- Truncated y-axis (not starting at 0) — distorts the magnitude comparison.
+- Accent on more than 1 bar ("everything is important" = nothing is).
+- 3-D bar extrusion — no shadows, no depth.
+- Category labels rotated more than 45°; prefer short labels or horizontal chart instead.
+
+## Variants
+
+- **Grouped bars:** two bars per category, side by side. Use `accent` for the primary series and `series-1` for the secondary. Max 2 groups.
+- **Stacked bars:** segments stacked to total. Use `accent` for the focal segment; muted tints for others. Document the total at the top of each stack.
+
+## Examples
+
+- `assets/example-bar.html` — minimal light
+- `assets/example-bar-dark.html` — minimal dark
+- `assets/example-bar-full.html` — full editorial