@kinqs/brainrouter-mcp-server 0.3.4

package/skills/communication/1-3-1-rule/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: 1-3-1-rule
+description: Professional communication for high-agency engineers. Enforces the 1-3-1 rule to turn problems into decisions and minimizes synchronous friction.
+hints:
+  - Frame the core issue in exactly one concise sentence (the '1' in 1-3-1).
+  - Provide exactly three distinct, viable options with structured pros and cons (the '3' in 1-3-1).
+  - Explicitly recommend exactly one option with a clear professional rationale (the '1' in 1-3-1).
+  - Detail a concrete, testable Definition of Done and step-by-step implementation plan for the recommendation.
+  - Revise the recommendation, DoD, and implementation plan dynamically if the user chooses a different option.
+---
+
+# 1-3-1 Communication Rule
+
+## Overview
+
+Structured decision-making format for when a task has multiple viable approaches and the user needs a clear recommendation. Produces a concise problem framing, three options with trade-offs, and an actionable plan for the recommended path.
+
+## When to Use
+
+- The user explicitly asks for a "1-3-1" response.
+- The user says "give me options" or "what are my choices" for a technical decision.
+- A task has multiple viable approaches with meaningful trade-offs (architecture, tooling, migration strategy).
+- The user needs a proposal they can forward to a team or stakeholder.
+
+Do NOT use for simple questions with one obvious answer, debugging sessions, or tasks where the user has already decided on an approach.
+
+## Workflow
+
+1. **Problem** (one sentence)
+   - State the core decision or desired outcome in a single concise sentence.
+   - Focus on the *what*, not the *how* — no implementation details, tool names, or specific technologies.
+   - Keep it tight. If you need "and", you're describing two problems.
+
+2. **Options** (exactly three)
+   - Present three distinct, viable approaches labeled A, B, C.
+   - Each option gets a brief description, pros, and cons.
+   - Options should represent genuinely different strategies, not minor variations of the same approach.
+
+3. **Recommendation** (one option)
+   - State which option you recommend and why, based on the user's context and priorities.
+   - Be direct — this is your professional judgment, not a hedge.
+
+4. **Definition of Done**
+   - List the specific success criteria for the recommended option.
+   - These are concrete, verifiable outcomes — not vague aspirations.
+   - If the user picks a different option, revise this section to match.
+
+5. **Implementation Plan**
+   - Concrete steps to execute the recommended option.
+   - Include specific commands, tools, or actions where applicable.
+   - If the user picks a different option, revise this section to match.
+
+## Required Checks
+
+- Response has exactly one Problem sentence.
+- Response has exactly three Options (A, B, C) with pros and cons for each.
+- Response has a single Recommendation that picks one option with reasoning.
+- Definition of Done and Implementation Plan align with the recommended option.
+- If the user selects a different option, Recommendation, DoD, and Implementation Plan update accordingly.
+
+## Example
+
+User: "Give me a 1-3-1 for adding retry logic to our API client."
+
+Agent:
+
+**Problem:** API calls to external services fail intermittently under load and need graceful retry handling.
+
+**Options:**
+
+- **Option A: Exponential backoff with jitter in a shared utility.**
+  Pros: Simple, well-understood pattern; single implementation shared across all callers.
+  Cons: No circuit-breaking; callers still block during retries.
+
+- **Option B: Retry library (tenacity) as a decorator on each endpoint call.**
+  Pros: Configurable per-endpoint; built-in support for circuit breakers and rate limits.
+  Cons: Adds a dependency; decorator pattern can obscure control flow.
+
+- **Option C: Queue-based async retry with dead letter handling.**
+  Pros: Non-blocking; failed calls are tracked and replayable; scales well.
+  Cons: Significant complexity increase; requires a queue backend; overkill for low-volume services.
+
+**Recommendation:** Option A. The call volume doesn't justify queue infrastructure, and a shared utility with exponential backoff + jitter covers the failure mode cleanly without new dependencies.
+
+**Definition of Done:**
+- `api_retry()` utility handles transient HTTP errors (429, 502, 503, 504).
+- Retries up to 3 times with exponential backoff and jitter.
+- All external API calls route through the retry utility.
+- Logs each retry attempt with endpoint and attempt number.
+- Tests cover retry exhaustion, immediate success, and transient-then-success scenarios.
+
+**Implementation Plan:**
+1. Create `utils/api_retry.py` with configurable max retries, base delay, and retryable status codes.
+2. Add jitter using `random.uniform(0, base_delay)` to prevent thundering herd.
+3. Wrap existing API calls in `api_client.py` with the retry utility.
+4. Add unit tests mocking HTTP responses for each retry scenario.
+5. Verify under load with a simple stress test against a flaky endpoint mock.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "The options are too similar to list three distinct paths." | There are always different dimensions: speed of implementation, operational complexity, security/reliability, or third-party dependencies. Find the genuine trade-offs. |
+| "I'll just ask the user what they want instead of giving a recommendation." | High-agency professionals do not offload decision-making. Presenting raw options without a recommendation wastes user time. |
+| "This decision is too simple to need a 1-3-1 response." | A simplified 1-3-1 can be extremely short (e.g. 1 sentence problem, 3 bullet options, 1 sentence recommendation). It forces clarity and consensus. |
+
+## Red Flags
+
+- Listing more or fewer than three options.
+- The "Problem" statement is multiple sentences or describes implementation details instead of the core goal.
+- Giving a vague recommendation (e.g. "it depends on what you prefer" or "either option works").
+- Implementation plan and DoD do not align with the recommended option.
+
+## Verification
+
+After completing this skill, confirm:
+- [ ] The response contains exactly one single-sentence problem framing.
+- [ ] Exactly three distinct options (A, B, C) are presented with explicit pros/cons.
+- [ ] A definitive, professional recommendation is stated.
+- [ ] The Definition of Done and Implementation Plan are fully tailored to the chosen option.

package/skills/design/brutalist-skill/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: brutalist-skill
+description: Raw mechanical interfaces fusing Swiss typographic print with military terminal aesthetics. Rigid grids, extreme type scale contrast, utilitarian color, analog degradation effects. For data-heavy dashboards, portfolios, or editorial sites that need to feel like declassified blueprints.
+hints:
+  - "Select exactly ONE substrate: Swiss Industrial Print (light) or CRT Terminal (dark); never mix them."
+  - "Enforce absolute 90-degree corners; border-radius is strictly prohibited."
+  - "Construct a strict CSS Grid where lines are generated using gaps rather than thick borders."
+  - "Utilize massive fluid typography for headers, and clean, tracked monospace for micro data."
+  - "Integrate ASCII indicators, crosshairs, and industrial symbols as pure structural geometry."
+---
+
+# SKILL: Industrial Brutalism & Tactical Telemetry UI
+
+## 1. Skill Meta
+**Name:** Industrial Brutalism & Tactical Telemetry Interface Engineering
+**Description:** Advanced proficiency in architecting web interfaces that synthesize mid-century Swiss Typographic design, industrial manufacturing manuals, and retro-futuristic aerospace/military terminal interfaces. This discipline requires absolute mastery over rigid modular grids, extreme typographic scale contrast, purely utilitarian color palettes, and the programmatic simulation of analog degradation (halftones, CRT scanlines, bitmap dithering). The objective is to construct digital environments that project raw functionality, mechanical precision, and high data density, deliberately discarding conventional consumer UI patterns.
+
+## 2. Visual Archetypes
+The design system operates by merging two distinct but highly compatible visual paradigms. **Pick ONE per project and commit to it. Do not alternate or mix both modes within the same interface.**
+
+### 2.1 Swiss Industrial Print
+Derived from 1960s corporate identity systems and heavy machinery blueprints.
+*   **Characteristics:** High-contrast light modes (newsprint/off-white substrates). Reliance on monolithic, heavy sans-serif typography. Unforgiving structural grids outlined by visible dividing lines. Aggressive, asymmetric use of negative space punctuated by oversized, viewport-bleeding numerals or letterforms. Heavy use of primary red as an alert/accent color.
+
+### 2.2 Tactical Telemetry & CRT Terminal
+Derived from classified military databases, legacy mainframes, and aerospace Heads-Up Displays (HUDs).
+*   **Characteristics:** Dark mode exclusivity. High-density tabular data presentation. Absolute dominance of monospaced typography. Integration of technical framing devices (ASCII brackets, crosshairs). Application of simulated hardware limitations (phosphor glow, scanlines, low bit-depth rendering).
+
+## 3. Typographic Architecture
+Typography is the primary structural and decorative infrastructure. Imagery is secondary. The system demands extreme variance in scale, weight, and spacing.
+
+### 3.1 Macro-Typography (Structural Headers)
+*   **Classification:** Neo-Grotesque / Heavy Sans-Serif.
+*   **Optimal Web Fonts:** Neue Haas Grotesk (Black), Inter (Extra Bold/Black), Archivo Black, Roboto Flex (Heavy), Monument Extended.
+*   **Implementation Parameters:**
+    *   **Scale:** Deployed at massive scales using fluid typography (e.g., `clamp(4rem, 10vw, 15rem)`).
+    *   **Tracking (Letter-spacing):** Extremely tight, often negative (`-0.03em` to `-0.06em`), forcing glyphs to form solid architectural blocks.
+    *   **Leading (Line-height):** Highly compressed (`0.85` to `0.95`).
+    *   **Casing:** Exclusively uppercase for structural impact.
+
+### 3.2 Micro-Typography (Data & Telemetry)
+*   **Classification:** Monospace / Technical Sans.
+*   **Optimal Web Fonts:** JetBrains Mono, IBM Plex Mono, Space Mono, VT323, Courier Prime.
+*   **Implementation Parameters:**
+    *   **Scale:** Fixed and small (`10px` to `14px` / `0.7rem` to `0.875rem`).
+    *   **Tracking:** Generous (`0.05em` to `0.1em`) to simulate mechanical typewriter spacing or terminal matrices.
+    *   **Leading:** Standard to tight (`1.2` to `1.4`).
+    *   **Casing:** Exclusively uppercase. Used for all metadata, navigation, unit IDs, and coordinates.
+
+### 3.3 Textural Contrast (Artistic Disruption)
+*   **Classification:** High-Contrast Serif.
+*   **Optimal Web Fonts:** Playfair Display, EB Garamond, Times New Roman.
+*   **Implementation Parameters:** Used exceedingly sparingly. Must be subjected to heavy post-processing (halftone filters, 1-bit dithering) to degrade vector perfection and create textural juxtaposition against the clean sans-serifs.
+
+## 4. Color System
+The color architecture is uncompromising. Gradients, soft drop shadows, and modern translucency are strictly prohibited. Colors simulate physical media or primitive emissive displays.
+
+**CRITICAL: Choose ONE substrate palette per project and use it consistently. Never mix light and dark substrates within the same interface.**
+
+### If Swiss Industrial Print (Light):
+*   **Background:** `#F4F4F0` or `#EAE8E3` (Matte, unbleached documentation paper).
+*   **Foreground:** `#050505` to `#111111` (Carbon Ink).
+*   **Accent:** `#E61919` or `#FF2A2A` (Aviation/Hazard Red). This is the ONLY accent color. Used for strike-throughs, thick structural dividing lines, or vital data highlights.
+
+### If Tactical Telemetry (Dark):
+*   **Background:** `#0A0A0A` or `#121212` (Deactivated CRT. Avoid pure `#000000`).
+*   **Foreground:** `#EAEAEA` (White phosphor). This is the primary text color.
+*   **Accent:** `#E61919` or `#FF2A2A` (Aviation/Hazard Red). Same red, same rules.
+*   **Terminal Green (`#4AF626`):** Optional. Use ONLY for a single specific UI element (e.g., one status indicator or one data readout) — never as a general text color. If it doesn't serve a clear purpose, omit it entirely.
+
+## 5. Layout and Spatial Engineering
+The layout must appear mathematically engineered. It rejects conventional web padding in favor of visible compartmentalization.
+
+*   **The Blueprint Grid:** Strict adherence to CSS Grid architectures. Elements do not float; they are anchored precisely to grid tracks and intersections.
+*   **Visible Compartmentalization:** Extensive utilization of solid borders (`1px` or `2px solid`) to delineate distinct zones of information. Horizontal rules (`<hr>`) frequently span the entire container width to segregate operational units.
+*   **Bimodal Density:** Layouts oscillate between extreme data density (tightly packed monospace metadata clustered together) and vast expanses of calculated negative space framing macro-typography.
+*   **Geometry:** Absolute rejection of `border-radius`. All corners must be exactly 90 degrees to enforce mechanical rigidity.
+
+## 6. UI Components and Symbology
+Standard web UI conventions are replaced with utilitarian, industrial graphic elements.
+
+*   **Syntax Decoration:** Utilization of ASCII characters to frame data points.
+    *   *Framing:* `[ DELIVERY SYSTEMS ]`, `< RE-IND >`
+    *   *Directional:* `>>>`, `///`, `\\\\`
+*   **Industrial Markers:** Prominent integration of registration (`®`), copyright (`©`), and trademark (`™`) symbols functioning as structural geometric elements rather than legal text.
+*   **Technical Assets:** Integration of crosshairs (`+`) at grid intersections, repeating vertical lines (barcodes), thick horizontal warning stripes, and randomized string data (e.g., `REV 2.6`, `UNIT / D-01`) to simulate active mechanical processes.
+
+## 7. Textural and Post-Processing Effects
+To prevent the design from appearing purely digital, simulated analog degradation is engineered into the frontend via CSS and SVG filters.
+
+*   **Halftone and 1-Bit Dithering:** Transforming continuous-tone images or large serif typography into dot-matrix patterns. Achieved via pre-processing or CSS `mix-blend-mode: multiply` overlays combined with SVG radial dot patterns.
+*   **CRT Scanlines:** For terminal interfaces, applying a `repeating-linear-gradient` to the background to simulate horizontal electron beam sweeps (e.g., `repeating-linear-gradient(0deg, transparent, transparent 2px, rgba(0,0,0,0.1) 2px, rgba(0,0,0,0.1) 4px)`).
+*   **Mechanical Noise:** A global, low-opacity SVG static/noise filter applied to the DOM root to introduce a unified physical grain across both dark and light modes.
+
+## 8. Web Engineering Directives
+1.  **Grid Determinism:** Utilize `display: grid; gap: 1px;` with contrasting parent/child background colors to generate mathematically perfect, razor-thin dividing lines without complex border declarations.
+2.  **Semantic Rigidity:** Construct the DOM using precise semantic tags (`<data>`, `<samp>`, `<kbd>`, `<output>`, `<dl>`) to accurately reflect the technical nature of the telemetry.
+3.  **Typography Clamping:** Implement CSS `clamp()` functions exclusively for macro-typography to ensure massive text scales aggressively while maintaining structural integrity across viewports.
+
+## Overview
+This skill governs the execution of Industrial Brutalism and Tactical Telemetry UIs. It rejects modern consumer-centric visual cliches (rounded corners, soft dropshadows, complex gradients) in favor of high-contrast Swiss printing and terminal interface styles.
+
+## When to Use
+- **Use when:** Building telemetry dashboards, software dev tools, visual portfolios, dense terminal views, or raw editorial layouts.
+- **NOT for:** standard consumer SaaS, friendly marketing pages, or e-commerce checkouts where high user conversion relies on soft, warm aesthetics.
+
+## Workflow
+1. **Establish Substrate:** Select either Swiss Industrial Print (light substrate, off-white/carbon ink) or CRT Terminal (dark substrate, deactivated CRT/white phosphor).
+2. **Setup Mathematical Grid:** Architect layouts with strict CSS Grid. Outline dividing lines cleanly.
+3. **Draft Typographic Scale:** Define massive macro-typography headers (`clamp()`) and highly legible, small monospace text for subheaders and telemetry details.
+4. **Decorate Structurally:** Add ASCII framing indicators, industrial symbols, crosshairs, or repeating barcodes to construct mechanical layouts.
+
+## Common Rationalizations
+| Rationalization | Reality |
+|---|---|
+| A tiny border-radius will soften it | Softening compromises the raw, mechanical integrity of industrial brutalism. All corners must be exactly 90 degrees. |
+| Gradients and blurs look more futuristic | Classic retro-futuristic telemetry relies on strict hardware limitations. Flat colors are mandatory. |
+| Mixed substrate modes look organic | Mixing light and dark themes on the same screen breaks visual cohesion and physical substrate logic. |
+
+## Red Flags
+- Mixing warm paper tones with harsh pure dark mode colors on a single viewport.
+- Unintentional use of standard browser-default or consumer SaaS fonts (like Inter or Open Sans) for display.
+- Rounded corners (`border-radius`) sneaking into buttons or cards.
+
+## Verification
+After completing the skill, confirm:
+- [ ] Only a single substrate mode (Swiss Print or CRT Terminal) is active on the page.
+- [ ] No `border-radius` exists on any elements.
+- [ ] All elements are aligned to a deterministic grid.
+- [ ] Text uses high type contrast (monolithic sans-serif vs small tracked monospace).
+- [ ] All icons and graphics align with the raw, structural telemetry aesthetic.

package/skills/design/concept-diagrams/SKILL.md

@@ -0,0 +1,387 @@
+---
+name: concept-diagrams
+description: Generate flat, minimal light/dark-aware SVG diagrams. Unified visual language with semantic colors and automatic dark mode.
+hints:
+  - "Always output semantic color classes (c-purple, c-teal, etc.) on <g> or shape elements, never on line connectors."
+  - "Ensure every <text> element carries a class (th, ts, or t) and uses sentence case."
+  - "Verify box widths mathematically: width >= (char_count * px_per_char) + 48."
+  - "Include the standard arrow marker <defs> block in every SVG."
+  - "Serve local diagrams on 127.0.0.1 for security; never expose on 0.0.0.0."
+---
+
+# Concept Diagrams
+
+Generate production-quality SVG diagrams with a unified flat, minimal design system. Output is a single self-contained HTML file that renders identically in any modern browser, with automatic light/dark mode.
+
+## Scope
+
+**Best suited for:**
+- Physics setups, chemistry mechanisms, math curves, biology
+- Physical objects (aircraft, turbines, smartphones, mechanical watches, cells)
+- Anatomy, cross-sections, exploded layer views
+- Floor plans, architectural conversions
+- Narrative journeys (lifecycle of X, process of Y)
+- Hub-spoke system integrations (smart city, IoT networks, electricity grids)
+- Educational / textbook-style visuals in any domain
+- Quantitative charts (grouped bars, energy profiles)
+
+**Look elsewhere first for:**
+- Dedicated software / cloud infrastructure architecture with a dark tech aesthetic (consider `architecture-diagram` if available)
+- Hand-drawn whiteboard sketches (consider `excalidraw` if available)
+- Animated explainers or video output (consider an animation skill)
+
+If a more specialized skill is available for the subject, prefer that. If none fits, this skill can serve as a general-purpose SVG diagram fallback — the output will carry the clean educational aesthetic described below, which is a reasonable default for almost any subject.
+
+## Workflow
+
+1. Decide on the diagram type (see Diagram Types below).
+2. Lay out components using the Design System rules.
+3. Write the full HTML page using `templates/template.html` as the wrapper — paste your SVG where the template says `<!-- PASTE SVG HERE -->`.
+4. Save as a standalone `.html` file (for example `~/my-diagram.html` or `./my-diagram.html`).
+5. User opens it directly in a browser — no server, no dependencies.
+
+Optional: if the user wants a browsable gallery of multiple diagrams, see "Local Preview Server" at the bottom.
+
+Load the HTML template:
+```
+skill_view(name="concept-diagrams", file_path="templates/template.html")
+```
+
+The template embeds the full CSS design system (`c-*` color classes, text classes, light/dark variables, arrow marker styles). The SVG you generate relies on these classes being present on the hosting page.
+
+---
+
+## Design System
+
+### Philosophy
+
+- **Flat**: no gradients, drop shadows, blur, glow, or neon effects.
+- **Minimal**: show the essential. No decorative icons inside boxes.
+- **Consistent**: same colors, spacing, typography, and stroke widths across every diagram.
+- **Dark-mode ready**: all colors auto-adapt via CSS classes — no per-mode SVG.
+
+### Color Palette
+
+9 color ramps, each with 7 stops. Put the class name on a `<g>` or shape element; the template CSS handles both modes.
+
+| Class      | 50 (lightest) | 100     | 200     | 400     | 600     | 800     | 900 (darkest) |
+|------------|---------------|---------|---------|---------|---------|---------|---------------|
+| `c-purple` | #EEEDFE | #CECBF6 | #AFA9EC | #7F77DD | #534AB7 | #3C3489 | #26215C |
+| `c-teal`   | #E1F5EE | #9FE1CB | #5DCAA5 | #1D9E75 | #0F6E56 | #085041 | #04342C |
+| `c-coral`  | #FAECE7 | #F5C4B3 | #F0997B | #D85A30 | #993C1D | #712B13 | #4A1B0C |
+| `c-pink`   | #FBEAF0 | #F4C0D1 | #ED93B1 | #D4537E | #993556 | #72243E | #4B1528 |
+| `c-gray`   | #F1EFE8 | #D3D1C7 | #B4B2A9 | #888780 | #5F5E5A | #444441 | #2C2C2A |
+| `c-blue`   | #E6F1FB | #B5D4F4 | #85B7EB | #378ADD | #185FA5 | #0C447C | #042C53 |
+| `c-green`  | #EAF3DE | #C0DD97 | #97C459 | #639922 | #3B6D11 | #27500A | #173404 |
+| `c-amber`  | #FAEEDA | #FAC775 | #EF9F27 | #BA7517 | #854F0B | #633806 | #412402 |
+| `c-red`    | #FCEBEB | #F7C1C1 | #F09595 | #E24B4A | #A32D2D | #791F1F | #501313 |
+
+#### Color Assignment Rules
+
+Color encodes **meaning**, not sequence. Never cycle through colors like a rainbow.
+
+- Group nodes by **category** — all nodes of the same type share one color.
+- Use `c-gray` for neutral/structural nodes (start, end, generic steps, users).
+- Use **2-3 colors per diagram**, not 6+.
+- Prefer `c-purple`, `c-teal`, `c-coral`, `c-pink` for general categories.
+- Reserve `c-blue`, `c-green`, `c-amber`, `c-red` for semantic meaning (info, success, warning, error).
+
+Light/dark stop mapping (handled by the template CSS — just use the class):
+- Light mode: 50 fill + 600 stroke + 800 title / 600 subtitle
+- Dark mode:  800 fill + 200 stroke + 100 title / 200 subtitle
+
+### Typography
+
+Only two font sizes. No exceptions.
+
+| Class | Size | Weight | Use |
+|-------|------|--------|-----|
+| `th`  | 14px | 500    | Node titles, region labels |
+| `ts`  | 12px | 400    | Subtitles, descriptions, arrow labels |
+| `t`   | 14px | 400    | General text |
+
+- **Sentence case always.** Never Title Case, never ALL CAPS.
+- Every `<text>` MUST carry a class (`t`, `ts`, or `th`). No unclassed text.
+- `dominant-baseline="central"` on all text inside boxes.
+- `text-anchor="middle"` for centered text in boxes.
+
+**Width estimation (approx):**
+- 14px weight 500: ~8px per character
+- 12px weight 400: ~6.5px per character
+- Always verify: `box_width >= (char_count × px_per_char) + 48` (24px padding each side)
+
+### Spacing & Layout
+
+- **ViewBox**: `viewBox="0 0 680 H"` where H = content height + 40px buffer.
+- **Safe area**: x=40 to x=640, y=40 to y=(H-40).
+- **Between boxes**: 60px minimum gap.
+- **Inside boxes**: 24px horizontal padding, 12px vertical padding.
+- **Arrowhead gap**: 10px between arrowhead and box edge.
+- **Single-line box**: 44px height.
+- **Two-line box**: 56px height, 18px between title and subtitle baselines.
+- **Container padding**: 20px minimum inside every container.
+- **Max nesting**: 2-3 levels deep. Deeper gets unreadable at 680px width.
+
+### Stroke & Shape
+
+- **Stroke width**: 0.5px on all node borders. Not 1px, not 2px.
+- **Rect rounding**: `rx="8"` for nodes, `rx="12"` for inner containers, `rx="16"` to `rx="20"` for outer containers.
+- **Connector paths**: MUST have `fill="none"`. SVG defaults to `fill: black` otherwise.
+
+### Arrow Marker
+
+Include this `<defs>` block at the start of **every** SVG:
+
+```xml
+<defs>
+  <marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5"
+          markerWidth="6" markerHeight="6" orient="auto-start-reverse">
+    <path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke"
+          stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+  </marker>
+</defs>
+```
+
+Use `marker-end="url(#arrow)"` on lines. The arrowhead inherits the line color via `context-stroke`.
+
+### CSS Classes (Provided by the Template)
+
+The template page provides:
+
+- Text: `.t`, `.ts`, `.th`
+- Neutral: `.box`, `.arr`, `.leader`, `.node`
+- Color ramps: `.c-purple`, `.c-teal`, `.c-coral`, `.c-pink`, `.c-gray`, `.c-blue`, `.c-green`, `.c-amber`, `.c-red` (all with automatic light/dark mode)
+
+You do **not** need to redefine these — just apply them in your SVG. The template file contains the full CSS definitions.
+
+---
+
+## SVG Boilerplate
+
+Every SVG inside the template page starts with this exact structure:
+
+```xml
+<svg width="100%" viewBox="0 0 680 {HEIGHT}" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5"
+            markerWidth="6" markerHeight="6" orient="auto-start-reverse">
+      <path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke"
+            stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+    </marker>
+  </defs>
+
+  <!-- Diagram content here -->
+
+</svg>
+```
+
+Replace `{HEIGHT}` with the actual computed height (last element bottom + 40px).
+
+### Node Patterns
+
+**Single-line node (44px):**
+```xml
+<g class="node c-blue">
+  <rect x="100" y="20" width="180" height="44" rx="8" stroke-width="0.5"/>
+  <text class="th" x="190" y="42" text-anchor="middle" dominant-baseline="central">Service name</text>
+</g>
+```
+
+**Two-line node (56px):**
+```xml
+<g class="node c-teal">
+  <rect x="100" y="20" width="200" height="56" rx="8" stroke-width="0.5"/>
+  <text class="th" x="200" y="38" text-anchor="middle" dominant-baseline="central">Service name</text>
+  <text class="ts" x="200" y="56" text-anchor="middle" dominant-baseline="central">Short description</text>
+</g>
+```
+
+**Connector (no label):**
+```xml
+<line x1="200" y1="76" x2="200" y2="120" class="arr" marker-end="url(#arrow)"/>
+```
+
+**Container (dashed or solid):**
+```xml
+<g class="c-purple">
+  <rect x="40" y="92" width="600" height="300" rx="16" stroke-width="0.5"/>
+  <text class="th" x="66" y="116">Container label</text>
+  <text class="ts" x="66" y="134">Subtitle info</text>
+</g>
+```
+
+---
+
+## Diagram Types
+
+Choose the layout that fits the subject:
+
+1. **Flowchart** — CI/CD pipelines, request lifecycles, approval workflows, data processing. Single-direction flow (top-down or left-right). Max 4-5 nodes per row.
+2. **Structural / Containment** — Cloud infrastructure nesting, system architecture with layers. Large outer containers with inner regions. Dashed rects for logical groupings.
+3. **API / Endpoint Map** — REST routes, GraphQL schemas. Tree from root, branching to resource groups, each containing endpoint nodes.
+4. **Microservice Topology** — Service mesh, event-driven systems. Services as nodes, arrows for communication patterns, message queues between.
+5. **Data Flow** — ETL pipelines, streaming architectures. Left-to-right flow from sources through processing to sinks.
+6. **Physical / Structural** — Vehicles, buildings, hardware, anatomy. Use shapes that match the physical form — `<path>` for curved bodies, `<polygon>` for tapered shapes, `<ellipse>`/`<circle>` for cylindrical parts, nested `<rect>` for compartments. See `references/physical-shape-cookbook.md`.
+7. **Infrastructure / Systems Integration** — Smart cities, IoT networks, multi-domain systems. Hub-spoke layout with central platform connecting subsystems. Semantic line styles (`.data-line`, `.power-line`, `.water-pipe`, `.road`). See `references/infrastructure-patterns.md`.
+8. **UI / Dashboard Mockups** — Admin panels, monitoring dashboards. Screen frame with nested chart/gauge/indicator elements. See `references/dashboard-patterns.md`.
+
+For physical, infrastructure, and dashboard diagrams, load the matching reference file before generating — each one provides ready-made CSS classes and shape primitives.
+
+---
+
+## Validation Checklist
+
+Before finalizing any SVG, verify ALL of the following:
+
+1. Every `<text>` has class `t`, `ts`, or `th`.
+2. Every `<text>` inside a box has `dominant-baseline="central"`.
+3. Every connector `<path>` or `<line>` used as arrow has `fill="none"`.
+4. No arrow line crosses through an unrelated box.
+5. `box_width >= (longest_label_chars × 8) + 48` for 14px text.
+6. `box_width >= (longest_label_chars × 6.5) + 48` for 12px text.
+7. ViewBox height = bottom-most element + 40px.
+8. All content stays within x=40 to x=640.
+9. Color classes (`c-*`) are on `<g>` or shape elements, never on `<path>` connectors.
+10. Arrow `<defs>` block is present.
+11. No gradients, shadows, blur, or glow effects.
+12. Stroke width is 0.5px on all node borders.
+
+---
+
+## Output & Preview
+
+### Default: standalone HTML file
+
+Write a single `.html` file the user can open directly. No server, no dependencies, works offline. Pattern:
+
+```python
+# 1. Load the template
+template = skill_view("concept-diagrams", "templates/template.html")
+
+# 2. Fill in title, subtitle, and paste your SVG
+html = template.replace(
+    "<!-- DIAGRAM TITLE HERE -->", "SN2 reaction mechanism"
+).replace(
+    "<!-- OPTIONAL SUBTITLE HERE -->", "Bimolecular nucleophilic substitution"
+).replace(
+    "<!-- PASTE SVG HERE -->", svg_content
+)
+
+# 3. Write to a user-chosen path (or ./ by default)
+write_file("./sn2-mechanism.html", html)
+```
+
+Tell the user how to open it:
+
+```
+# macOS
+open ./sn2-mechanism.html
+# Linux
+xdg-open ./sn2-mechanism.html
+```
+
+### Optional: local preview server (multi-diagram gallery)
+
+Only use this when the user explicitly wants a browsable gallery of multiple diagrams.
+
+**Rules:**
+- Bind to `127.0.0.1` only. Never `0.0.0.0`. Exposing diagrams on all network interfaces is a security hazard on shared networks.
+- Pick a free port (do NOT hard-code one) and tell the user the chosen URL.
+- The server is optional and opt-in — prefer the standalone HTML file first.
+
+Recommended pattern (lets the OS pick a free ephemeral port):
+
+```bash
+# Put each diagram in its own folder under .diagrams/
+mkdir -p .diagrams/sn2-mechanism
+# ...write .diagrams/sn2-mechanism/index.html...
+
+# Serve on loopback only, free port
+cd .diagrams && python3 -c "
+import http.server, socketserver
+with socketserver.TCPServer(('127.0.0.1', 0), http.server.SimpleHTTPRequestHandler) as s:
+    print(f'Serving at http://127.0.0.1:{s.server_address[1]}/')
+    s.serve_forever()
+" &
+```
+
+If the user insists on a fixed port, use `127.0.0.1:<port>` — still never `0.0.0.0`. Document how to stop the server (`kill %1` or `pkill -f "http.server"`).
+
+---
+
+## Examples Reference
+
+The `examples/` directory ships 15 complete, tested diagrams. Browse them for working patterns before writing a new diagram of a similar type:
+
+| File | Type | Demonstrates |
+|------|------|--------------|
+| `hospital-emergency-department-flow.md` | Flowchart | Priority routing with semantic colors |
+| `feature-film-production-pipeline.md` | Flowchart | Phased workflow, horizontal sub-flows |
+| `automated-password-reset-flow.md` | Flowchart | Auth flow with error branches |
+| `autonomous-llm-research-agent-flow.md` | Flowchart | Loop-back arrows, decision branches |
+| `place-order-uml-sequence.md` | Sequence | UML sequence diagram style |
+| `commercial-aircraft-structure.md` | Physical | Paths, polygons, ellipses for realistic shapes |
+| `wind-turbine-structure.md` | Physical cross-section | Underground/above-ground separation, color coding |
+| `smartphone-layer-anatomy.md` | Exploded view | Alternating left/right labels, layered components |
+| `apartment-floor-plan-conversion.md` | Floor plan | Walls, doors, proposed changes in dotted red |
+| `banana-journey-tree-to-smoothie.md` | Narrative journey | Winding path, progressive state changes |
+| `cpu-ooo-microarchitecture.md` | Hardware pipeline | Fan-out, memory hierarchy sidebar |
+| `sn2-reaction-mechanism.md` | Chemistry | Molecules, curved arrows, energy profile |
+| `smart-city-infrastructure.md` | Hub-spoke | Semantic line styles per system |
+| `electricity-grid-flow.md` | Multi-stage flow | Voltage hierarchy, flow markers |
+| `ml-benchmark-grouped-bar-chart.md` | Chart | Grouped bars, dual axis |
+
+Load any example with:
+```
+skill_view(name="concept-diagrams", file_path="examples/<filename>")
+```
+
+---
+
+## Quick Reference: What to Use When
+
+| User says | Diagram type | Suggested colors |
+|-----------|--------------|------------------|
+| "show the pipeline" | Flowchart | gray start/end, purple steps, red errors, teal deploy |
+| "draw the data flow" | Data pipeline (left-right) | gray sources, purple processing, teal sinks |
+| "visualize the system" | Structural (containment) | purple container, teal services, coral data |
+| "map the endpoints" | API tree | purple root, one ramp per resource group |
+| "show the services" | Microservice topology | gray ingress, teal services, purple bus, coral workers |
+| "draw the aircraft/vehicle" | Physical | paths, polygons, ellipses for realistic shapes |
+| "smart city / IoT" | Hub-spoke integration | semantic line styles per subsystem |
+| "show the dashboard" | UI mockup | dark screen, chart colors: teal, purple, coral for alerts |
+| "power grid / electricity" | Multi-stage flow | voltage hierarchy (HV/MV/LV line weights) |
+| "wind turbine / turbine" | Physical cross-section | foundation + tower cutaway + nacelle color-coded |
+| "journey of X / lifecycle" | Narrative journey | winding path, progressive state changes |
+| "layers of X / exploded" | Exploded layer view | vertical stack, alternating labels |
+| "CPU / pipeline" | Hardware pipeline | vertical stages, fan-out to execution ports |
+| "floor plan / apartment" | Floor plan | walls, doors, proposed changes in dotted red |
+| "reaction mechanism" | Chemistry | atoms, bonds, curved arrows, transition state, energy profile |
+
+## Overview
+This skill governs the generation of flat, minimal, light/dark-aware SVG diagrams. It provides a standardized visual design system that ensures diagrams render beautifully, scale fluidly, and adapt automatically to light and dark themes using semantic color categories.
+
+## When to Use
+- **Use when:** Building technical documentation, explaining architectural setups, illustrating science/physics/chemistry mechanisms, flowcharts, API endpoints, or user journeys.
+- **NOT for:** Complex 3D modeling, hand-drawn wireframes, or high-fidelity UI mockup pages (use dedicated UI or mock design systems instead).
+
+## Common Rationalizations
+| Rationalization | Reality |
+|---|---|
+| I can use CSS inline styles for custom colors | Using inline styles breaks automatic dark-mode adjustments. Only semantic classes (e.g., `c-purple`, `c-teal`) adapt. |
+| Eyeballing box width is fine | Eyeballing causes text overflow or ugly padding on different screens. Always calculate: width >= (chars * multiplier) + 48. |
+| It's easier to serve on 0.0.0.0 | Exposing local design work on 0.0.0.0 opens access to your local files on the local network. Always bind to 127.0.0.1. |
+
+## Red Flags
+- Absence of class tags (`th`, `ts`, or `t`) on `<text>` elements.
+- Connector `<line>` or `<path>` elements missing `fill="none"`.
+- Use of drop-shadows, gradients, or heavy neon glow filters in elements.
+- Text strings using Title Case or all-caps instead of sentence case.
+
+## Verification
+After completing the skill, confirm:
+- [ ] Every `<text>` has an assigned font class (`th`, `ts`, or `t`).
+- [ ] Every connector line has `fill="none"` and references the arrow marker.
+- [ ] The `marker` block is defined within `<defs>` inside the `<svg>` node.
+- [ ] Diagram viewBox has clean bounds containing all elements with 40px safe margins.
+- [ ] Automatic dark mode works properly when classes shift.