@drunkcoding/agents-and-skills 0.0.4 → 0.0.5

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "tech-graph",
       "source": "./plugins/tech-graph",
       "description": "6-step wizard for technical diagrams (SVG/PNG) via fireworks-tech-graph",
-      "version": "0.0.4",
+      "version": "0.0.5",
       "category": "diagram",
       "keywords": [
         "diagram",
@@ -26,7 +26,7 @@
       "name": "html-effectiveness",
       "source": "./plugins/html-effectiveness",
       "description": "Generate self-contained interactive HTML reports from 20 upstream templates via a conversational agent.",
-      "version": "0.0.4",
+      "version": "0.0.5",
       "category": "reports",
       "keywords": [
         "html",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drunkcoding/agents-and-skills",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Personal collection of Claude Code skills and agents, installable via `npx skills`.",
   "keywords": [
     "claude-code",

package/plugins/html-effectiveness/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "html-effectiveness",
   "displayName": "HTML Effectiveness Reports",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Generate self-contained interactive HTML reports from 20 upstream templates via a conversational agent.",
   "author": {
     "name": "Steven Hoang"

package/plugins/tech-graph/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tech-graph",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Step-by-step wizard for generating technical diagrams as SVG+PNG.",
   "author": {
     "name": "steven"

package/plugins/tech-graph/skills/tech-graph/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: fireworks-tech-graph
+name: tech-graph
 description: >-
   Use when the user wants to create any technical diagram - architecture, data
   flow, flowchart, sequence, agent/memory, or concept map - and export as
@@ -8,32 +8,10 @@ description: >-
   system/flow description the user wants illustrated.
 ---
 
-# Fireworks Tech Graph
+# Tech Graph
 
 Generate production-quality SVG technical diagrams exported as PNG via `cairosvg` (recommended), `rsvg-convert`, or `puppeteer`.
 
-## Install Source
-
-Install this skill from GitHub:
-
-```bash
-npx skills add yizhiyanhua-ai/fireworks-tech-graph
-```
-
-Public package page:
-
-```text
-https://www.npmjs.com/package/@yizhiyanhua-ai/fireworks-tech-graph
-```
-
-Do not pass `@yizhiyanhua-ai/fireworks-tech-graph` directly to `skills add`, because the CLI expects a GitHub or local repository source.
-
-Update command:
-
-```bash
-npx skills add yizhiyanhua-ai/fireworks-tech-graph --force -g -y
-```
-
 ## Helper Scripts (Recommended)
 
 Four helper scripts in `scripts/` directory provide stable SVG generation and validation:
@@ -87,9 +65,9 @@ python3 ./scripts/generate-from-template.py architecture ./output/arch.svg '{"ti
 1. **Classify** the diagram type (see Diagram Types below)
 2. **Extract structure** — identify layers, nodes, edges, flows, and semantic groups from user description
 3. **Plan layout** — apply the layout rules for the diagram type
-4. **Load style reference** — always load `references/style-1-flat-icon.md` unless user specifies another; load the matching `references/style-N.md` for exact color tokens and SVG patterns
+4. **Load style reference** — always load [style-1-flat-icon](references/style-1-flat-icon.md) unless user specifies another; load the matching style-N file (e.g. [style-2-dark-terminal](references/style-2-dark-terminal.md), [style-3-blueprint](references/style-3-blueprint.md), [style-4-notion-clean](references/style-4-notion-clean.md), [style-5-glassmorphism](references/style-5-glassmorphism.md), [style-6-claude-official](references/style-6-claude-official.md), [style-7-openai](references/style-7-openai.md)) for exact color tokens and SVG patterns
 5. **Map nodes to shapes** — use Shape Vocabulary below
-6. **Check icon needs** — load `references/icons.md` for known products
+6. **Check icon needs** — load [icons](references/icons.md) for known products
 7. **Write SVG** with adaptive strategy (see SVG Generation Strategy below)
 8. **Validate**: Run `python3 -c "import xml.etree.ElementTree as ET; ET.parse('file.svg')"` to check XML syntax
 9. **Export PNG**: Use `cairosvg` (recommended). See **SVG → PNG Conversion** section below for full method comparison
@@ -105,175 +83,7 @@ python3 ./scripts/generate-from-template.py architecture ./output/arch.svg '{"ti
 
 ## Diagram Types & Layout Rules
 
-### Architecture Diagram
-Nodes = services/components. Group into **horizontal layers** (top→bottom or left→right).
-- Typical layers: Client → Gateway/LB → Services → Data/Storage
-- Use `<rect>` dashed containers to group related services in the same layer
-- Arrow direction follows data/request flow
-- ViewBox: `0 0 960 600` standard, `0 0 960 800` for tall stacks
-
-### Data Flow Diagram
-Emphasizes **what data moves where**. Focus on data transformation.
-- Label every arrow with the data type (e.g., "embeddings", "query", "context")
-- Use wider arrows (`stroke-width: 2.5`) for primary data paths
-- Dashed arrows for control/trigger flows
-- Color arrows by data category (not just Agent/RAG — use semantics)
-
-### Flowchart / Process Flow
-Sequential decision/process steps.
-- Top-to-bottom preferred; left-to-right for wide flows
-- Diamond shapes for decisions, rounded rects for processes, parallelograms for I/O
-- Keep node labels short (≤3 words); put detail in sub-labels
-- Align nodes on a grid: x positions snap to 120px intervals, y to 80px
-
-### Agent Architecture Diagram
-Shows how an AI agent reasons, uses tools, and manages memory.
-Key conceptual layers to always consider:
-- **Input layer**: User, query, trigger
-- **Agent core**: LLM, reasoning loop, planner
-- **Memory layer**: Short-term (context window), Long-term (vector/graph DB), Episodic
-- **Tool layer**: Tool calls, APIs, search, code execution
-- **Output layer**: Response, action, side-effects
-Use cyclic arrows (loop arcs) to show iterative reasoning. Separate memory types visually.
-
-### Memory Architecture Diagram (Mem0, MemGPT-style)
-Specialized agent diagram focused on memory operations.
-- Show memory **write path** and **read path** separately (different arrow colors)
-- Memory tiers: Working Memory → Short-term → Long-term → External Store
-- Label memory operations: `store()`, `retrieve()`, `forget()`, `consolidate()`
-- Use stacked rects or layered cylinders for storage tiers
-
-### Sequence Diagram
-Time-ordered message exchanges between participants.
-- Participants as vertical **lifelines** (top labels + vertical dashed lines)
-- Messages as horizontal arrows between lifelines, top-to-bottom time order
-- Activation boxes (thin filled rects on lifeline) show active processing
-- Group with `<rect>` loop/alt frames with label in top-left corner
-- ViewBox height = 80 + (num_messages × 50)
-
-### Comparison / Feature Matrix
-Side-by-side comparison of approaches, systems, or components.
-- Column headers = systems, row headers = attributes
-- Row height: 40px; column width: min 120px; header row height: 50px
-- Checked cell: tinted background (e.g. `#dcfce7`) + `✓` checkmark; unsupported: `#f9fafb` fill
-- Alternating row fills (`#f9fafb` / `#ffffff`) for readability
-- Max readable columns: 5; beyond that, split into two diagrams
-
-### Timeline / Gantt
-Horizontal time axis showing durations, phases, and milestones.
-- X-axis = time (weeks/months/quarters); Y-axis = items/tasks/phases
-- Bars: rounded rects, colored by category, labeled inside or beside
-- Milestone markers: diamond or filled circle at specific x position with label above
-- ViewBox: `0 0 960 400` typical; wider for many time periods: `0 0 1200 400`
-
-### Mind Map / Concept Map
-Radial layout from central concept.
-- Central node at `cx=480, cy=280`
-- First-level branches: evenly distributed around center (360/N degrees)
-- Second-level branches: branch off first-level at 30-45° offset
-- Use curved `<path>` with cubic bezier for branches, not straight lines
-
-### Class Diagram (UML)
-Static structure showing classes, attributes, methods, and relationships.
-- **Class box**: 3-compartment rect (name / attributes / methods), min width 160px
-  - Top compartment: class name, bold, centered (abstract = *italic*)
-  - Middle: attributes with visibility (`+` public, `-` private, `#` protected)
-  - Bottom: method signatures, same visibility notation
-- **Relationships**:
-  - Inheritance (extends): solid line + hollow triangle arrowhead, child → parent
-  - Implementation (interface): dashed line + hollow triangle, class → interface
-  - Association: solid line + open arrowhead, label with multiplicity (1, 0..*, 1..*)
-  - Aggregation: solid line + hollow diamond on container side
-  - Composition: solid line + filled diamond on container side
-  - Dependency: dashed line + open arrowhead
-- **Interface**: `<<interface>>` stereotype above name, or circle/lollipop notation
-- **Enum**: compartment rect with `<<enumeration>>` stereotype, values in bottom
-- Layout: parent classes top, children below; interfaces to the left/right of implementors
-- ViewBox: `0 0 960 600` standard; `0 0 960 800` for deep hierarchies
-
-### Use Case Diagram (UML)
-System functionality from user perspective.
-- **Actor**: stick figure (circle head + body line) placed outside system boundary
-  - Label below figure, 13-14px
-  - Primary actors on left, secondary/supporting on right
-- **Use case**: ellipse with label centered inside, min 140×60px
-  - Keep names verb phrases: "Create Order", "Process Payment"
-- **System boundary**: large rect with dashed border + system name in top-left
-- **Relationships**:
-  - Include: dashed arrow `<<include>>` from base to included use case
-  - Extend: dashed arrow `<<extend>>` from extension to base use case
-  - Generalization: solid line + hollow triangle (specialized → general)
-- Layout: system boundary centered, actors outside, use cases inside
-- ViewBox: `0 0 960 600` standard
-
-### State Machine Diagram (UML)
-Lifecycle states and transitions of an entity.
-- **State**: rounded rect with state name, min 120×50px
-  - Internal activities: small text `entry/ action`, `exit/ action`, `do/ activity`
-  - **Initial state**: filled black circle (r=8), one outgoing arrow
-  - **Final state**: filled circle (r=8) inside hollow circle (r=12)
-  - **Choice**: small hollow diamond, guard labels on outgoing arrows `[condition]`
-- **Transition**: arrow with optional label `event [guard] / action`
-  - Guard conditions in square brackets
-  - Actions after `/`
-- **Composite/nested state**: larger rect containing sub-states, with name tab
-- **Fork/join**: thick horizontal or vertical black bar (synchronization)
-- Layout: initial state top-left, final state bottom-right, flow top-to-bottom
-- ViewBox: `0 0 960 600` standard
-
-### ER Diagram (Entity-Relationship)
-Database schema and data relationships.
-- **Entity**: rect with entity name in header (bold), attributes below
-  - Primary key attribute: underlined
-  - Foreign key: italic or marked with (FK)
-  - Min width: 160px; attribute font-size: 12px
-- **Relationship**: diamond shape on connecting line
-  - Label inside diamond: "has", "belongs to", "enrolls in"
-  - Cardinality labels near entity: `1`, `N`, `0..1`, `0..*`, `1..*`
-- **Weak entity**: double-bordered rect with double diamond relationship
-- **Associative entity**: diamond + rect hybrid (rect with diamond inside)
-- Line style: solid for identifying relationships, dashed for non-identifying
-- Layout: entities in 2-3 rows, relationships between related entities
-- ViewBox: `0 0 960 600` standard; wider `0 0 1200 600` for many entities
-
-### Network Topology
-Physical or logical network infrastructure.
-- **Devices**: icon-like rects or rounded rects
-  - Router: circle with cross arrows
-  - Switch: rect with arrow grid
-  - Server: stacked rect (rack icon)
-  - Firewall: brick-pattern rect or shield shape
-  - Load Balancer: horizontal split rect with arrows
-  - Cloud: cloud path (overlapping arcs)
-- **Connections**: lines between device centers
-  - Ethernet/wired: solid line, label bandwidth
-  - Wireless: dashed line with WiFi symbol
-  - VPN: dashed line with lock icon
-- **Subnets/Zones**: dashed rect containers with zone label (DMZ, Internal, External)
-- **Labels**: device hostname + IP below, 12-13px
-- Layout: tiered top-to-bottom (Internet → Edge → Core → Access → Endpoints)
-- ViewBox: `0 0 960 600` standard
-
-## UML Coverage Map
-
-Full mapping of UML 14 diagram types to supported diagram types:
-
-| UML Diagram | Supported As | Notes |
-|-------------|-------------|-------|
-| Class | Class Diagram | Full UML notation |
-| Component | Architecture Diagram | Use colored fills per component type |
-| Deployment | Architecture Diagram | Add node/instance labels |
-| Package | Architecture Diagram | Use dashed grouping containers |
-| Composite Structure | Architecture Diagram | Nested rects within components |
-| Object | Class Diagram | Instance boxes with underlined name |
-| Use Case | Use Case Diagram | Full actor/ellipse/relationship |
-| Activity | Flowchart / Process Flow | Add fork/join bars |
-| State Machine | State Machine Diagram | Full UML notation |
-| Sequence | Sequence Diagram | Add alt/opt/loop frames |
-| Communication | — | Approximate with Sequence (swap axes) |
-| Timing | Timeline | Adapt time axis |
-| Interaction Overview | Flowchart | Combine activity + sequence fragments |
-| ER Diagram | ER Diagram | Chen/Crow's foot notation |
+Per-type layout rules + UML coverage map: see [diagram-types](references/diagram-types.md). Covers Architecture, Data Flow, Flowchart, Agent, Memory, Sequence, Comparison, Timeline, Mind Map, Class (UML), Use Case (UML), State Machine (UML), ER, Network Topology, plus full UML-14 mapping.
 
 ## Shape Vocabulary
 
@@ -416,119 +226,13 @@ python3 -c "import cairosvg; cairosvg.svg2png(url='file.svg', write_to='/tmp/tes
 
 ## SVG → PNG Conversion
 
-### Method Comparison
-
-| Tool | Install | Render Quality | Notes |
-|------|---------|----------------|-------|
-| `rsvg-convert` | System (often preinstalled) | ⚠️ Fair | Drops some CSS styles and `<foreignObject>` elements — missing borders/text on complex SVGs |
-| **`cairosvg` (recommended)** | `pip install cairosvg` | ✅ Good | Solid CSS support; clearly better than rsvg-convert |
-| `puppeteer` (headless Chrome) | `npm install puppeteer` | ✅✅ Best | Real browser engine; 100% fidelity but heavy (Node + Chromium) |
-
-### Recommended: cairosvg (Python one-liner)
+Default `cairosvg` one-liner:
 
 ```bash
-# Single file (2x resolution for retina/docs)
 python3 -c "import cairosvg; cairosvg.svg2png(url='input.svg', write_to='output.png', scale=2)"
-
-# Batch convert all SVGs in a directory
-python3 -c "
-import cairosvg, os, glob
-d = 'docs/00-core'
-for svg in sorted(glob.glob(os.path.join(d, '*.svg'))):
-    png = svg.replace('.svg', '.png')
-    cairosvg.svg2png(url=svg, write_to=png, scale=2)
-    print(f'Done: {os.path.basename(svg)} -> {os.path.basename(png)}')
-"
 ```
 
-> `scale=2` produces 2x resolution PNG, ideal for high-DPI screens and embedded docs.
-
-### Fallback: rsvg-convert (simple but may drop styles)
-
-```bash
-# Single file
-rsvg-convert -w 1920 file.svg -o file.png
-
-# Batch (not recommended — complex SVGs may lose elements)
-for f in docs/00-core/*.svg; do rsvg-convert -o "${f%.svg}.png" "$f"; done
-
-# 2x resolution
-for f in docs/00-core/*.svg; do rsvg-convert -z 2 -o "${f%.svg}.png" "$f"; done
-```
-
-### Highest Fidelity: puppeteer (headless Chrome)
-
-```bash
-npm install puppeteer  # auto-downloads Chromium
-node svg2png.js [directory]
-```
-
-<details>
-<summary>svg2png.js — full puppeteer script</summary>
-
-```javascript
-const puppeteer = require('puppeteer');
-const fs = require('fs');
-const path = require('path');
-
-(async () => {
-  const dir = process.argv[2] || '.';
-  const svgFiles = fs.readdirSync(dir).filter(f => f.endsWith('.svg'));
-
-  const browser = await puppeteer.launch({
-    headless: 'new',
-    args: ['--no-sandbox', '--disable-setuid-sandbox']
-  });
-
-  for (const file of svgFiles) {
-    const svgPath = path.resolve(dir, file);
-    const pngPath = svgPath.replace(/\.svg$/, '.png');
-    const svgContent = fs.readFileSync(svgPath, 'utf-8');
-
-    const wMatch = svgContent.match(/width="(\d+)/);
-    const hMatch = svgContent.match(/height="(\d+)/);
-    const vbMatch = svgContent.match(/viewBox="[^"]*\s(\d+)\s(\d+)"/);
-
-    let width = wMatch ? parseInt(wMatch[1]) : (vbMatch ? parseInt(vbMatch[1]) : 1200);
-    let height = hMatch ? parseInt(hMatch[1]) : (vbMatch ? parseInt(vbMatch[2]) : 800);
-
-    const scale = 2;
-    const page = await browser.newPage();
-    await page.setViewport({ width, height, deviceScaleFactor: scale });
-
-    const html = `<!DOCTYPE html>
-<html><head><style>
-  body { margin: 0; padding: 0; background: transparent; }
-  img { display: block; }
-</style></head>
-<body>
-  <img src="data:image/svg+xml;base64,${Buffer.from(svgContent).toString('base64')}" width="${width}" height="${height}" />
-</body></html>`;
-
-    await page.setContent(html, { waitUntil: 'networkidle0' });
-    await page.screenshot({ path: pngPath, type: 'png', omitBackground: true });
-    await page.close();
-
-    console.log(`Done: ${file} -> ${path.basename(pngPath)} (${width}x${height} @${scale}x)`);
-  }
-
-  await browser.close();
-})();
-```
-
-</details>
-
-### Gotchas (lessons learned)
-
-- `rsvg-convert` renders SVGs containing `<foreignObject>`, CSS `filter`, or complex `<style>` blocks **incompletely** — missing borders / missing text are the typical symptoms
-- `cairosvg` (built on Cairo) has much better CSS support than rsvg and is sufficient for most cases
-- If the SVG was generated by a browser (D3.js, Mermaid, etc.), only headless Chrome (puppeteer) renders it 100% faithfully
-
-### Picking a Method
-
-1. **Default** → `cairosvg` (pip install once, one-line conversion, good fidelity)
-2. **No Python available** → `rsvg-convert` (acceptable for simple flat-color diagrams)
-3. **Browser-generated SVG or pixel-perfect required** → `puppeteer`
+Full method comparison (cairosvg / rsvg-convert / puppeteer), batch scripts, puppeteer renderer, and gotchas: see [svg-to-png](references/svg-to-png.md).
 
 ## Styles
 
@@ -537,16 +241,16 @@ const path = require('path');
 | 1 | **Flat Icon** (default) | White | Blogs, docs, presentations |
 | 2 | **Dark Terminal** | `#0f0f1a` | GitHub, dev articles |
 | 3 | **Blueprint** | `#0a1628` | Architecture docs |
-| 4 | **Notion Clean** | White, minimal | Notionnce |
+| 4 | **Notion Clean** | White, minimal | Notion |
 | 5 | **Glassmorphism** | Dark gradient | Product sites, keynotes |
 | 6 | **Claude Official** | Warm cream `#f8f6f3` | Anthropic-style diagrams |
 | 7 | **OpenAI Official** | Pure white `#ffffff` | OpenAI-style diagrams |
 
-Load `references/style-N.md` for exact color tokens and SVG patterns.
+Load the matching style-N file in [references/](references/) for exact color tokens and SVG patterns.
 
 ## Style Selection
 
-**Default**: Style 1 (Flat Icon) for most diagrams. Load `references/style-diagram-matrix.md` for detailed style-to-diagram-type recommendations.
+**Default**: Style 1 (Flat Icon) for most diagrams. Load [style-diagram-matrix](references/style-diagram-matrix.md) for detailed style-to-diagram-type recommendations.
 
 These patterns appear frequently — internalize them:
 

package/plugins/tech-graph/skills/tech-graph/references/diagram-types.md

@@ -0,0 +1,171 @@
+# Diagram Types & Layout Rules
+
+## Architecture Diagram
+Nodes = services/components. Group into **horizontal layers** (top→bottom or left→right).
+- Typical layers: Client → Gateway/LB → Services → Data/Storage
+- Use `<rect>` dashed containers to group related services in the same layer
+- Arrow direction follows data/request flow
+- ViewBox: `0 0 960 600` standard, `0 0 960 800` for tall stacks
+
+## Data Flow Diagram
+Emphasizes **what data moves where**. Focus on data transformation.
+- Label every arrow with the data type (e.g., "embeddings", "query", "context")
+- Use wider arrows (`stroke-width: 2.5`) for primary data paths
+- Dashed arrows for control/trigger flows
+- Color arrows by data category (not just Agent/RAG — use semantics)
+
+## Flowchart / Process Flow
+Sequential decision/process steps.
+- Top-to-bottom preferred; left-to-right for wide flows
+- Diamond shapes for decisions, rounded rects for processes, parallelograms for I/O
+- Keep node labels short (≤3 words); put detail in sub-labels
+- Align nodes on a grid: x positions snap to 120px intervals, y to 80px
+
+## Agent Architecture Diagram
+Shows how an AI agent reasons, uses tools, and manages memory.
+Key conceptual layers to always consider:
+- **Input layer**: User, query, trigger
+- **Agent core**: LLM, reasoning loop, planner
+- **Memory layer**: Short-term (context window), Long-term (vector/graph DB), Episodic
+- **Tool layer**: Tool calls, APIs, search, code execution
+- **Output layer**: Response, action, side-effects
+Use cyclic arrows (loop arcs) to show iterative reasoning. Separate memory types visually.
+
+## Memory Architecture Diagram (Mem0, MemGPT-style)
+Specialized agent diagram focused on memory operations.
+- Show memory **write path** and **read path** separately (different arrow colors)
+- Memory tiers: Working Memory → Short-term → Long-term → External Store
+- Label memory operations: `store()`, `retrieve()`, `forget()`, `consolidate()`
+- Use stacked rects or layered cylinders for storage tiers
+
+## Sequence Diagram
+Time-ordered message exchanges between participants.
+- Participants as vertical **lifelines** (top labels + vertical dashed lines)
+- Messages as horizontal arrows between lifelines, top-to-bottom time order
+- Activation boxes (thin filled rects on lifeline) show active processing
+- Group with `<rect>` loop/alt frames with label in top-left corner
+- ViewBox height = 80 + (num_messages × 50)
+
+## Comparison / Feature Matrix
+Side-by-side comparison of approaches, systems, or components.
+- Column headers = systems, row headers = attributes
+- Row height: 40px; column width: min 120px; header row height: 50px
+- Checked cell: tinted background (e.g. `#dcfce7`) + `✓` checkmark; unsupported: `#f9fafb` fill
+- Alternating row fills (`#f9fafb` / `#ffffff`) for readability
+- Max readable columns: 5; beyond that, split into two diagrams
+
+## Timeline / Gantt
+Horizontal time axis showing durations, phases, and milestones.
+- X-axis = time (weeks/months/quarters); Y-axis = items/tasks/phases
+- Bars: rounded rects, colored by category, labeled inside or beside
+- Milestone markers: diamond or filled circle at specific x position with label above
+- ViewBox: `0 0 960 400` typical; wider for many time periods: `0 0 1200 400`
+
+## Mind Map / Concept Map
+Radial layout from central concept.
+- Central node at `cx=480, cy=280`
+- First-level branches: evenly distributed around center (360/N degrees)
+- Second-level branches: branch off first-level at 30-45° offset
+- Use curved `<path>` with cubic bezier for branches, not straight lines
+
+## Class Diagram (UML)
+Static structure showing classes, attributes, methods, and relationships.
+- **Class box**: 3-compartment rect (name / attributes / methods), min width 160px
+  - Top compartment: class name, bold, centered (abstract = *italic*)
+  - Middle: attributes with visibility (`+` public, `-` private, `#` protected)
+  - Bottom: method signatures, same visibility notation
+- **Relationships**:
+  - Inheritance (extends): solid line + hollow triangle arrowhead, child → parent
+  - Implementation (interface): dashed line + hollow triangle, class → interface
+  - Association: solid line + open arrowhead, label with multiplicity (1, 0..*, 1..*)
+  - Aggregation: solid line + hollow diamond on container side
+  - Composition: solid line + filled diamond on container side
+  - Dependency: dashed line + open arrowhead
+- **Interface**: `<<interface>>` stereotype above name, or circle/lollipop notation
+- **Enum**: compartment rect with `<<enumeration>>` stereotype, values in bottom
+- Layout: parent classes top, children below; interfaces to the left/right of implementors
+- ViewBox: `0 0 960 600` standard; `0 0 960 800` for deep hierarchies
+
+## Use Case Diagram (UML)
+System functionality from user perspective.
+- **Actor**: stick figure (circle head + body line) placed outside system boundary
+  - Label below figure, 13-14px
+  - Primary actors on left, secondary/supporting on right
+- **Use case**: ellipse with label centered inside, min 140×60px
+  - Keep names verb phrases: "Create Order", "Process Payment"
+- **System boundary**: large rect with dashed border + system name in top-left
+- **Relationships**:
+  - Include: dashed arrow `<<include>>` from base to included use case
+  - Extend: dashed arrow `<<extend>>` from extension to base use case
+  - Generalization: solid line + hollow triangle (specialized → general)
+- Layout: system boundary centered, actors outside, use cases inside
+- ViewBox: `0 0 960 600` standard
+
+## State Machine Diagram (UML)
+Lifecycle states and transitions of an entity.
+- **State**: rounded rect with state name, min 120×50px
+  - Internal activities: small text `entry/ action`, `exit/ action`, `do/ activity`
+  - **Initial state**: filled black circle (r=8), one outgoing arrow
+  - **Final state**: filled circle (r=8) inside hollow circle (r=12)
+  - **Choice**: small hollow diamond, guard labels on outgoing arrows `[condition]`
+- **Transition**: arrow with optional label `event [guard] / action`
+  - Guard conditions in square brackets
+  - Actions after `/`
+- **Composite/nested state**: larger rect containing sub-states, with name tab
+- **Fork/join**: thick horizontal or vertical black bar (synchronization)
+- Layout: initial state top-left, final state bottom-right, flow top-to-bottom
+- ViewBox: `0 0 960 600` standard
+
+## ER Diagram (Entity-Relationship)
+Database schema and data relationships.
+- **Entity**: rect with entity name in header (bold), attributes below
+  - Primary key attribute: underlined
+  - Foreign key: italic or marked with (FK)
+  - Min width: 160px; attribute font-size: 12px
+- **Relationship**: diamond shape on connecting line
+  - Label inside diamond: "has", "belongs to", "enrolls in"
+  - Cardinality labels near entity: `1`, `N`, `0..1`, `0..*`, `1..*`
+- **Weak entity**: double-bordered rect with double diamond relationship
+- **Associative entity**: diamond + rect hybrid (rect with diamond inside)
+- Line style: solid for identifying relationships, dashed for non-identifying
+- Layout: entities in 2-3 rows, relationships between related entities
+- ViewBox: `0 0 960 600` standard; wider `0 0 1200 600` for many entities
+
+## Network Topology
+Physical or logical network infrastructure.
+- **Devices**: icon-like rects or rounded rects
+  - Router: circle with cross arrows
+  - Switch: rect with arrow grid
+  - Server: stacked rect (rack icon)
+  - Firewall: brick-pattern rect or shield shape
+  - Load Balancer: horizontal split rect with arrows
+  - Cloud: cloud path (overlapping arcs)
+- **Connections**: lines between device centers
+  - Ethernet/wired: solid line, label bandwidth
+  - Wireless: dashed line with WiFi symbol
+  - VPN: dashed line with lock icon
+- **Subnets/Zones**: dashed rect containers with zone label (DMZ, Internal, External)
+- **Labels**: device hostname + IP below, 12-13px
+- Layout: tiered top-to-bottom (Internet → Edge → Core → Access → Endpoints)
+- ViewBox: `0 0 960 600` standard
+
+## UML Coverage Map
+
+Full mapping of UML 14 diagram types to supported diagram types:
+
+| UML Diagram | Supported As | Notes |
+|-------------|-------------|-------|
+| Class | Class Diagram | Full UML notation |
+| Component | Architecture Diagram | Use colored fills per component type |
+| Deployment | Architecture Diagram | Add node/instance labels |
+| Package | Architecture Diagram | Use dashed grouping containers |
+| Composite Structure | Architecture Diagram | Nested rects within components |
+| Object | Class Diagram | Instance boxes with underlined name |
+| Use Case | Use Case Diagram | Full actor/ellipse/relationship |
+| Activity | Flowchart / Process Flow | Add fork/join bars |
+| State Machine | State Machine Diagram | Full UML notation |
+| Sequence | Sequence Diagram | Add alt/opt/loop frames |
+| Communication | — | Approximate with Sequence (swap axes) |
+| Timing | Timeline | Adapt time axis |
+| Interaction Overview | Flowchart | Combine activity + sequence fragments |
+| ER Diagram | ER Diagram | Chen/Crow's foot notation |

package/plugins/tech-graph/skills/tech-graph/references/svg-to-png.md

@@ -0,0 +1,115 @@
+# SVG → PNG Conversion
+
+## Method Comparison
+
+| Tool | Install | Render Quality | Notes |
+|------|---------|----------------|-------|
+| `rsvg-convert` | System (often preinstalled) | ⚠️ Fair | Drops some CSS styles and `<foreignObject>` elements — missing borders/text on complex SVGs |
+| **`cairosvg` (recommended)** | `pip install cairosvg` | ✅ Good | Solid CSS support; clearly better than rsvg-convert |
+| `puppeteer` (headless Chrome) | `npm install puppeteer` | ✅✅ Best | Real browser engine; 100% fidelity but heavy (Node + Chromium) |
+
+## Recommended: cairosvg (Python one-liner)
+
+```bash
+# Single file (2x resolution for retina/docs)
+python3 -c "import cairosvg; cairosvg.svg2png(url='input.svg', write_to='output.png', scale=2)"
+
+# Batch convert all SVGs in a directory
+python3 -c "
+import cairosvg, os, glob
+d = 'docs/00-core'
+for svg in sorted(glob.glob(os.path.join(d, '*.svg'))):
+    png = svg.replace('.svg', '.png')
+    cairosvg.svg2png(url=svg, write_to=png, scale=2)
+    print(f'Done: {os.path.basename(svg)} -> {os.path.basename(png)}')
+"
+```
+
+> `scale=2` produces 2x resolution PNG, ideal for high-DPI screens and embedded docs.
+
+## Fallback: rsvg-convert (simple but may drop styles)
+
+```bash
+# Single file
+rsvg-convert -w 1920 file.svg -o file.png
+
+# Batch (not recommended — complex SVGs may lose elements)
+for f in docs/00-core/*.svg; do rsvg-convert -o "${f%.svg}.png" "$f"; done
+
+# 2x resolution
+for f in docs/00-core/*.svg; do rsvg-convert -z 2 -o "${f%.svg}.png" "$f"; done
+```
+
+## Highest Fidelity: puppeteer (headless Chrome)
+
+```bash
+npm install puppeteer  # auto-downloads Chromium
+node svg2png.js [directory]
+```
+
+<details>
+<summary>svg2png.js — full puppeteer script</summary>
+
+```javascript
+const puppeteer = require('puppeteer');
+const fs = require('fs');
+const path = require('path');
+
+(async () => {
+  const dir = process.argv[2] || '.';
+  const svgFiles = fs.readdirSync(dir).filter(f => f.endsWith('.svg'));
+
+  const browser = await puppeteer.launch({
+    headless: 'new',
+    args: ['--no-sandbox', '--disable-setuid-sandbox']
+  });
+
+  for (const file of svgFiles) {
+    const svgPath = path.resolve(dir, file);
+    const pngPath = svgPath.replace(/\.svg$/, '.png');
+    const svgContent = fs.readFileSync(svgPath, 'utf-8');
+
+    const wMatch = svgContent.match(/width="(\d+)/);
+    const hMatch = svgContent.match(/height="(\d+)/);
+    const vbMatch = svgContent.match(/viewBox="[^"]*\s(\d+)\s(\d+)"/);
+
+    let width = wMatch ? parseInt(wMatch[1]) : (vbMatch ? parseInt(vbMatch[1]) : 1200);
+    let height = hMatch ? parseInt(hMatch[1]) : (vbMatch ? parseInt(vbMatch[2]) : 800);
+
+    const scale = 2;
+    const page = await browser.newPage();
+    await page.setViewport({ width, height, deviceScaleFactor: scale });
+
+    const html = `<!DOCTYPE html>
+<html><head><style>
+  body { margin: 0; padding: 0; background: transparent; }
+  img { display: block; }
+</style></head>
+<body>
+  <img src="data:image/svg+xml;base64,${Buffer.from(svgContent).toString('base64')}" width="${width}" height="${height}" />
+</body></html>`;
+
+    await page.setContent(html, { waitUntil: 'networkidle0' });
+    await page.screenshot({ path: pngPath, type: 'png', omitBackground: true });
+    await page.close();
+
+    console.log(`Done: ${file} -> ${path.basename(pngPath)} (${width}x${height} @${scale}x)`);
+  }
+
+  await browser.close();
+})();
+```
+
+</details>
+
+## Gotchas (lessons learned)
+
+- `rsvg-convert` renders SVGs containing `<foreignObject>`, CSS `filter`, or complex `<style>` blocks **incompletely** — missing borders / missing text are the typical symptoms
+- `cairosvg` (built on Cairo) has much better CSS support than rsvg and is sufficient for most cases
+- If the SVG was generated by a browser (D3.js, Mermaid, etc.), only headless Chrome (puppeteer) renders it 100% faithfully
+
+## Picking a Method
+
+1. **Default** → `cairosvg` (pip install once, one-line conversion, good fidelity)
+2. **No Python available** → `rsvg-convert` (acceptable for simple flat-color diagrams)
+3. **Browser-generated SVG or pixel-perfect required** → `puppeteer`