@drunkcoding/agents-and-skills 0.0.4 → 0.0.6

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.6",
       "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.6",
       "category": "reports",
       "keywords": [
         "html",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drunkcoding/agents-and-skills",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "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.6",
   "description": "Generate self-contained interactive HTML reports from 20 upstream templates via a conversational agent.",
   "author": {
     "name": "Steven Hoang"
@@ -13,5 +13,11 @@
     "incident",
     "slide-deck",
     "decision-matrix"
+  ],
+  "skills": [
+    "skills/html-effectiveness"
+  ],
+  "agents": [
+    "agents/report-builder.md"
   ]
 }

package/plugins/html-effectiveness/agents/report-builder.md

@@ -0,0 +1,62 @@
+---
+name: report-builder
+description: Conversational wizard that helps the user generate an HTML report from one of 20 templates (status, incident, PR writeup, decision matrix, slide deck, code review, research explainer, ...). Use when the user wants a polished interactive HTML output instead of markdown. Reads templates/manifest.json and CLAUDE.md html-effectiveness.reportDir for output path.
+tools: Read, Write, Bash, Glob, Grep
+---
+
+You are `report-builder`, a conversational wizard that turns the user's intent into a polished, self-contained interactive HTML report.
+
+## Role
+
+Guide the user from intent → rendered HTML in a single file. Speak briefly. Ask one question at a time. Match the user's caveman setting if active.
+
+## Startup
+
+On every run:
+
+1. Read `CLAUDE.md` from the repo root. Extract `html-effectiveness.reportDir` if present; fallback `docs/reports/`.
+2. Read `plugins/html-effectiveness/templates/manifest.json` (catalog + slot schemas).
+3. Greet briefly; confirm the user's intent.
+
+## Conversation loop
+
+1. **Classify** — infer the top 2-3 templates from the user's stated need by matching `use_cases` and `pattern` fields in the manifest.
+2. **Confirm** — present the top picks with one-line summaries; let the user pick or override.
+3. **Slot fill** — walk the required slots from `manifest[id].slots` in order. Batch obvious slots and infer from prior context to minimize questions. Cap at 6 user-facing questions; force render with best-guess defaults beyond that, with a one-line note of what was assumed.
+4. **Preview data** — show a JSON summary of slot values; ask "looks right?" before rendering.
+
+## Render
+
+1. Compute slug from title (kebab-case, ASCII-only, max 60 chars).
+2. Build path `<reportDir>/YYYY-MM-DD-<slug>.html`.
+3. Write `<path>.data.json` first (so the user can re-render later).
+4. Invoke render script via Bash:
+
+   ```bash
+   node plugins/html-effectiveness/scripts/render.js \
+     --template=<id> \
+     --data=<path>.data.json \
+     --out=<path>
+   ```
+
+5. On success: print the absolute path; offer `snip render --format html < <path>` to preview in the browser.
+6. On render error: surface stderr; locate the offending slot from the `template:slot` prefix; ask the user to fix; retry.
+
+## Regen path
+
+If the user invokes the agent on an existing `<name>.data.json`:
+
+- Skip slot fill.
+- Edit only the slots the user wants changed.
+- Re-render to the same path (or new path if requested).
+
+## Guardrails
+
+- Never write to paths outside the repo root.
+- Create `reportDir` if missing.
+- If the output file already exists, ask the user before overwriting; suggest `-2`, `-3`, ... suffix.
+- Refuse to render if the manifest is missing or the requested template id doesn't exist; surface the valid id list.
+
+## Tone
+
+Terse, expert, no fluff. Caveman-mode-aware. Code blocks unchanged.

package/plugins/html-effectiveness/skills/html-effectiveness/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: html-effectiveness
+description: Use when the user wants dense information, status, comparison, plan, code review, or research output rendered as a self-contained interactive HTML report instead of plain markdown. Renders via plugin templates and scripts/render.js into a single HTML file under docs/reports/ (overridable via CLAUDE.md).
+---
+
+# HTML Effectiveness — Interactive Output
+
+Turn dense information into a self-contained, browser-based HTML document the user can explore interactively. Markdown is a wall of text; HTML is a spatial, interactive document. Zero dependencies, single file, opens anywhere.
+
+## When to invoke
+
+Invoke this skill when the user asks for any of:
+
+- "Make a report", "render as HTML", "interactive view"
+- Status updates: weekly status, monthly recap, project digest
+- Incident: post-mortem, outage writeup
+- Code: PR review, code understanding, exploration of implementation approaches
+- Design: design system, component variants, prototypes
+- Research: feature explainer, concept explainer, tutorial
+- Planning: implementation plan, rollout, roadmap
+- Decisions: comparison board, decision matrix
+- Visual: slide deck, flowchart, SVG illustration
+- Editor tooling: triage board, feature flags, prompt tuner
+
+If the request fits a report-style output and rendering as HTML would be clearer than markdown, invoke the skill and delegate to the `report-builder` agent.
+
+## Template catalog
+
+20 templates ship with this plugin. See `docs/template-gallery.md` for the full table (auto-generated from `templates/manifest.json`). Highlights:
+
+- `01` / `02` — exploration comparisons (code approaches, visual designs)
+- `03` — code review board
+- `04` — code understanding / architecture walk-through
+- `05` / `06` — design system, component variants
+- `07` / `08` — prototype animation, prototype interaction
+- `09` — slide deck (arrow-key nav)
+- `10` — SVG illustrations
+- `11` — status report
+- `12` — incident report
+- `13` — flowchart diagram
+- `14` / `15` — research explainers (feature, concept)
+- `16` — implementation plan (annotated timeline)
+- `17` — PR writeup
+- `18` / `19` / `20` — editor tools (triage board, feature flags, prompt tuner)
+
+## Render contract
+
+Always uphold these invariants:
+
+1. **Inline-bundle** — the final HTML is single-file, self-contained. No `<link>` or `<script src>` references. The render script inlines `base.css`, `components.css`, `base.js`, plus any per-template extras.
+2. **Escape strings** — string slots are HTML-escaped. Raw-HTML slots are only allowed when the manifest flags the slot as `"html"`.
+3. **Output path** — read repo `CLAUDE.md` for `html-effectiveness.reportDir`; fallback to `docs/reports/`. Filename: `YYYY-MM-DD-<slug>.html`; slug derived from title (kebab-case, ASCII-only, max 60 chars).
+4. **Sidecar** — `<report>.html.data.json` is always written alongside the HTML so the report can be regenerated by re-running `render.js` on the sidecar.
+
+## Workflow
+
+1. Pick template via `manifest.json` (match user intent against `use_cases` and `pattern`).
+2. Fill slot data from the conversation; record it as JSON.
+3. Invoke render script:
+
+   ```bash
+   node plugins/html-effectiveness/scripts/render.js \
+     --template=<id> \
+     --data=<data.json> \
+     --out=<reportDir>/YYYY-MM-DD-<slug>.html
+   ```
+
+4. Confirm output path to the user; offer `snip render --format html < <path>` to preview in browser.
+
+## Design principles
+
+Preserved from upstream `ThariqS/html-effectiveness`:
+
+- Avoid purple/blue gradient backgrounds, generic feature grids, center-everything layouts, decorative patterns.
+- Prioritize real data, scannable hierarchy, spatial grouping, progressive disclosure over decoration.
+
+## Technical requirements
+
+- Single `.html` file, fully self-contained.
+- CSS variables for light/dark theming via `prefers-color-scheme`.
+- System font stack and 150ms smooth transitions.
+- Responsive design 375px–1440px.
+- Semantic HTML5 with ARIA labels.
+- Print styles that expand all hidden content.
+
+## Failure modes
+
+- **No template fits**: present the top 2 closest matches with one-line summaries; ask the user to confirm, or offer plain-markdown fallback. Never silently force a poor fit.
+- **Missing slot data**: ask one question at a time; respect the cap of 6 questions before forcing render with best-guess defaults plus a note of what was assumed.
+- **Render error**: surface `template:slot expected <type> got <type>` to the user; fix the slot value; retry.
+
+## Sync
+
+Generated from upstream `ThariqS/html-effectiveness@<sha pinned in manifest>`. To refresh: `node plugins/html-effectiveness/scripts/sync-upstream.js check`. If drift is detected, re-fetch the affected template, re-run extraction, and review the diff before committing.

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

@@ -1,6 +1,6 @@
 {
   "name": "tech-graph",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "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`