mindforge-cc 11.5.0 → 11.6.0

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

@@ -0,0 +1,355 @@
+---
+name: concept-diagrams
+description: Generate flat, minimal light/dark-aware SVG diagrams as standalone HTML files, using a unified educational visual language with 9 semantic color ramps, sentence-case typography, and automatic dark mode. Best suited for educational and non-software visuals — physics setups, chemistry mechanisms, math curves, physical objects (aircraft, turbines, smartphones, mechanical watches), anatomy, floor plans, cross-sections, narrative journeys (lifecycle of X, process of Y), hub-spoke system integrations (smart city, IoT), and exploded layer views. If a more specialized skill exists for the subject (dedicated software/cloud architecture, hand-drawn sketches, animated explainers, etc.), prefer that — otherwise this skill can also serve as a general-purpose SVG diagram fallback with a clean educational look. Ships with 15 example diagrams.
+version: 0.1.0
+dependencies: []
+---
+
+# 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 |

package/.agent/skills/concept-diagrams/references/dashboard-patterns.md

@@ -0,0 +1,43 @@
+# Dashboard Patterns
+
+Building blocks for UI/dashboard mockups inside a concept diagram — admin panels, monitoring dashboards, control interfaces, status displays.
+
+## Pattern
+
+A "screen" is a rounded dark rect inside a lighter "frame" rect, with chart/gauge/indicator elements nested on top.
+
+```xml
+<!-- Monitor frame -->
+<rect class="dashboard" x="0" y="0" width="200" height="120" rx="8"/>
+<!-- Screen -->
+<rect class="screen" x="10" y="10" width="180" height="85" rx="4"/>
+<!-- Mini bar chart -->
+<rect class="screen-content" x="18" y="18" width="50" height="35" rx="2"/>
+<rect class="screen-chart" x="22" y="38" width="8" height="12"/>
+<rect class="screen-chart" x="33" y="32" width="8" height="18"/>
+<!-- Gauge -->
+<circle class="screen-bar" cx="100" cy="35" r="12"/>
+<text x="100" y="39" text-anchor="middle" fill="#E8E6DE" style="font-size:8px">78%</text>
+<!-- Status indicators -->
+<circle cx="35" cy="74" r="6" fill="#97C459"/> <!-- green = ok -->
+<circle cx="75" cy="74" r="6" fill="#EF9F27"/> <!-- amber = warning -->
+<circle cx="115" cy="74" r="6" fill="#E24B4A"/> <!-- red = alert -->
+```
+
+## CSS
+
+```css
+.dashboard      { fill: #F1EFE8; stroke: #5F5E5A; stroke-width: 1.5; }
+.screen         { fill: #1a1a18; }
+.screen-content { fill: #2C2C2A; }
+.screen-chart   { fill: #5DCAA5; }
+.screen-bar     { fill: #7F77DD; }
+.screen-alert   { fill: #E24B4A; }
+```
+
+## Tips
+
+- Dashboard screens stay dark in both light and dark mode — they represent actual monitor glass.
+- Keep on-screen text small (`font-size:8px` or `10px`) and high-contrast (near-white fill on dark).
+- Use the status triad green/amber/red consistently — OK / warning / alert.
+- A single dashboard usually sits on top of an infrastructure hub diagram as a unified view (see `examples/smart-city-infrastructure.md`).

package/.agent/skills/concept-diagrams/references/infrastructure-patterns.md

@@ -0,0 +1,144 @@
+# Infrastructure Patterns
+
+Reusable shapes and line styles for infrastructure / systems-integration diagrams (smart cities, IoT networks, industrial systems, multi-domain architectures).
+
+## Layout pattern: hub-spoke
+
+- **Central hub**: Hexagon or circle representing the integration platform
+- **Radiating connections**: Data lines from hub to each subsystem with connection dots
+- **Subsystem sections**: Each system (power, water, transport) in its own region
+- **Dashboard on top**: Optional UI mockup showing a unified view (see `dashboard-patterns.md`)
+
+```xml
+<!-- Central hub (hexagon) -->
+<polygon class="iot-hex" points="0,-45 39,-22 39,22 0,45 -39,22 -39,-22"/>
+
+<!-- Data lines with connection dots -->
+<path class="data-line" d="M 321 248 L 200 248 L 120 380" stroke-dasharray="4 3"/>
+<circle cx="321" cy="248" r="4" fill="#7F77DD"/>
+```
+
+## Semantic line styles
+
+Use a dedicated CSS class per subsystem so every diagram reads the same way:
+
+```css
+.data-line  { stroke: #7F77DD; stroke-width: 2; fill: none; stroke-dasharray: 4 3; }
+.power-line { stroke: #EF9F27; stroke-width: 2; fill: none; }
+.water-pipe { stroke: #378ADD; stroke-width: 4; stroke-linecap: round; fill: none; }
+.road       { stroke: #888780; stroke-width: 8; stroke-linecap: round; fill: none; }
+```
+
+## Power systems
+
+**Solar panel (angled):**
+```xml
+<polygon class="solar-panel" points="0,25 35,8 38,12 3,29"/>
+<line class="solar-frame" x1="12" y1="22" x2="24" y2="13"/>
+```
+
+**Wind turbine:**
+```xml
+<polygon class="wind-tower" points="20,70 30,70 28,25 22,25"/>
+<circle class="wind-hub" cx="25" cy="18" r="5"/>
+<ellipse class="wind-blade" cx="25" cy="5" rx="3" ry="13"/>
+<ellipse class="wind-blade" cx="14" cy="26" rx="3" ry="13" transform="rotate(-120, 25, 18)"/>
+<ellipse class="wind-blade" cx="36" cy="26" rx="3" ry="13" transform="rotate(120, 25, 18)"/>
+```
+
+**Battery with charge level:**
+```xml
+<rect class="battery" x="0" y="0" width="45" height="65" rx="5"/>
+<rect x="10" y="-6" width="10" height="8" rx="2" fill="#27500A"/> <!-- terminal -->
+<rect class="battery-level" x="5" y="12" width="35" height="48" rx="3"/> <!-- fill level -->
+```
+
+**Power pylon:**
+```xml
+<polygon class="pylon" points="30,0 35,0 40,60 25,60"/>
+<line x1="15" y1="10" x2="45" y2="10" stroke="#5F5E5A" stroke-width="3"/>
+<circle cx="18" cy="10" r="3" fill="#FAEEDA" stroke="#854F0B"/> <!-- insulator -->
+```
+
+## Water systems
+
+**Reservoir/dam:**
+```xml
+<polygon class="reservoir-wall" points="0,60 10,0 70,0 80,60"/>
+<polygon class="water" points="12,10 68,10 68,55 75,55 75,58 5,58 5,55 12,55"/>
+<!-- Wave effect -->
+<path d="M 15 25 Q 25 22 35 25 Q 45 28 55 25" fill="none" stroke="#378ADD" opacity="0.5"/>
+```
+
+**Treatment tank:**
+```xml
+<ellipse class="treatment-tank" cx="35" cy="45" rx="30" ry="18"/>
+<rect class="treatment-tank" x="5" y="20" width="60" height="25"/>
+<!-- Bubbles -->
+<circle cx="20" cy="32" r="2" fill="#378ADD" opacity="0.6"/>
+```
+
+**Pipe with joint and valve:**
+```xml
+<path class="pipe" d="M 80 85 L 110 85"/>
+<circle class="pipe-joint" cx="110" cy="85" r="8"/>
+<circle class="valve" cx="95" cy="85" r="6"/>
+```
+
+## Transport systems
+
+**Road with lane markings:**
+```xml
+<line class="road" x1="0" y1="50" x2="170" y2="50"/>
+<line class="road-mark" x1="10" y1="50" x2="160" y2="50"/>
+```
+
+**Traffic light:**
+```xml
+<rect class="traffic-light" x="0" y="0" width="14" height="32" rx="3"/>
+<circle class="light-red" cx="7" cy="8" r="4"/>
+<circle class="light-off" cx="7" cy="16" r="4"/>
+<circle class="light-green" cx="7" cy="24" r="4"/>
+```
+
+**Bus:**
+```xml
+<rect class="bus" x="0" y="0" width="55" height="28" rx="6"/>
+<rect class="bus-window" x="5" y="5" width="12" height="12" rx="2"/>
+<circle cx="14" cy="30" r="6" fill="#2C2C2A"/> <!-- wheel -->
+<circle cx="14" cy="30" r="3" fill="#5F5E5A"/> <!-- hubcap -->
+```
+
+## Full CSS block (add to the host page or inline <style>)
+
+```css
+/* Power */
+.solar-panel   { fill: #3C3489; stroke: #534AB7; stroke-width: 0.5; }
+.wind-tower    { fill: #B4B2A9; stroke: #5F5E5A; stroke-width: 1; }
+.wind-blade    { fill: #F1EFE8; stroke: #888780; stroke-width: 0.5; }
+.battery       { fill: #27500A; stroke: #3B6D11; stroke-width: 1.5; }
+.battery-level { fill: #97C459; }
+.power-line    { stroke: #EF9F27; stroke-width: 2; fill: none; }
+
+/* Water */
+.reservoir-wall { fill: #B4B2A9; stroke: #5F5E5A; stroke-width: 1; }
+.water          { fill: #85B7EB; stroke: #378ADD; stroke-width: 0.5; }
+.pipe           { fill: none; stroke: #378ADD; stroke-width: 4; stroke-linecap: round; }
+.pipe-joint     { fill: #185FA5; stroke: #0C447C; stroke-width: 1; }
+.valve          { fill: #0C447C; stroke: #185FA5; stroke-width: 1; }
+
+/* Transport */
+.road          { stroke: #888780; stroke-width: 8; fill: none; stroke-linecap: round; }
+.road-mark     { stroke: #F1EFE8; stroke-width: 1; stroke-dasharray: 6 4; fill: none; }
+.traffic-light { fill: #444441; stroke: #2C2C2A; stroke-width: 0.5; }
+.light-red     { fill: #E24B4A; }
+.light-green   { fill: #97C459; }
+.light-off     { fill: #2C2C2A; }
+.bus           { fill: #E1F5EE; stroke: #0F6E56; stroke-width: 1.5; }
+```
+
+## Reference examples
+
+- `examples/smart-city-infrastructure.md` — hub-spoke with multiple subsystems
+- `examples/electricity-grid-flow.md` — voltage hierarchy, flow markers
+- `examples/wind-turbine-structure.md` — cross-section with legend

package/.agent/skills/concept-diagrams/references/physical-shape-cookbook.md

@@ -0,0 +1,42 @@
+# Physical Shape Cookbook
+
+Guidance for drawing physical objects (vehicles, buildings, hardware, mechanical systems, anatomy) — when rectangles aren't enough.
+
+## Shape selection
+
+| Physical form | SVG element | Example use |
+|---------------|-------------|-------------|
+| Curved bodies | `<path>` with Q/C curves | Fuselage, tanks, pipes |
+| Tapered/angular shapes | `<polygon>` | Wings, fins, wedges |
+| Cylindrical/round | `<ellipse>`, `<circle>` | Engines, wheels, buttons |
+| Linear structures | `<line>` | Struts, beams, connections |
+| Internal sections | `<rect>` inside parent | Compartments, rooms |
+| Dashed boundaries | `stroke-dasharray` | Hidden parts, fuel tanks |
+
+## Layering approach
+
+1. Draw outer structure first (fuselage, frame, hull)
+2. Add internal sections on top (cabins, compartments)
+3. Add detail elements (engines, wheels, controls)
+4. Add leader lines with labels
+
+## Semantic CSS classes (instead of c-* ramps)
+
+For physical diagrams, define component-specific classes directly rather than applying `c-*` color classes. This makes each part self-documenting and lets you keep a restrained palette:
+
+```css
+.fuselage { fill: #F1EFE8; stroke: #5F5E5A; stroke-width: 1; }
+.wing     { fill: #E6F1FB; stroke: #185FA5; stroke-width: 1; }
+.engine   { fill: #FAECE7; stroke: #993C1D; stroke-width: 1; }
+```
+
+Add these to a local `<style>` inside the SVG (or extend the host page's `<style>` block). The light-mode/dark-mode pattern still works — use the CSS variables from the template (`var(--bg-secondary)`, `var(--border)`, `var(--text-primary)`) if you want dark-mode awareness.
+
+## Reference examples
+
+Look at these example files for working physical-diagram patterns:
+
+- `examples/commercial-aircraft-structure.md` — fuselage curves + tapered wings + ellipse engines
+- `examples/wind-turbine-structure.md` — underground foundation, tubular tower, nacelle cutaway
+- `examples/smartphone-layer-anatomy.md` — exploded-view stack with alternating labels
+- `examples/apartment-floor-plan-conversion.md` — walls, doors, windows, proposed changes