forge-server 0.1.0

package/plugin/skills/visual-explainer/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Changelog
+
+## [0.3.0] - 2026-02-26
+
+### Anti-Slop Guardrails
+- Added explicit "Anti-Patterns (AI Slop)" section to SKILL.md with forbidden patterns
+- Removed "Neon dashboard" and "Gradient mesh" from allowed aesthetics — they always produce generic output
+- Categorized aesthetics as "Constrained" (safer) vs "Flexible" (use with caution)
+- Explicit forbidden fonts: Inter, Roboto, Arial, Helvetica, system-ui as primary
+- Explicit forbidden colors: indigo/violet range (`#8b5cf6`, `#7c3aed`, `#a78bfa`), cyan-magenta-pink combination
+- Explicit forbidden effects: gradient text on headings, animated glowing box-shadows, emoji section headers
+- Added "The Slop Test" — 7-point checklist to catch AI-generated patterns before delivery
+- Strengthened typography guidance with 5 explicit good pairings to use
+- Strengthened color guidance with 5 explicit good palettes to use
+- Referenced `websocket-implementation-plan.html` as positive example of Blueprint aesthetic
+
+### Template Fixes
+- Replaced violet secondary colors in `mermaid-flowchart.html` with sky blue to match anti-slop guidelines
+- Updated Mermaid themeVariables example in `libraries.md` to use teal/slate palette instead of violet
+
+## [0.2.0] - 2026-02-25
+
+### Slide Deck Mode
+- New output format: magazine-quality slide deck presentations as self-contained HTML files
+- 10 slide types: Title, Section Divider, Content, Split, Diagram, Dashboard, Table, Code, Quote, Full-Bleed
+- SlideEngine JS: keyboard/touch/wheel navigation, progress bar, nav dots, slide counter, keyboard hints with auto-fade
+- Cinematic transitions: fade + translateY + scale on slide entrance, staggered child reveals via IntersectionObserver
+- 4 curated presets: Midnight Editorial, Warm Signal, Terminal Mono, Swiss Clean (each with full light/dark palette)
+- Event delegation: Mermaid zoom, scrollable code/tables don't trigger slide navigation
+- Responsive height breakpoints (700px, 600px, 500px) for projection and small viewports
+- Typography scale 2–3× larger than scrollable pages (80–120px display, 28–48px headings, 16–24px body)
+- Per-slide background variation, SVG decorative accents, compositional variety rules
+- Proactive imagery: surf-cli integration for title/full-bleed backgrounds, inline sparklines, mini-charts
+- New `/generate-slides` prompt template; existing prompts support `--slides` flag via SKILL.md workflow
+- Unified `autoFit()` post-render function: auto-scales Mermaid SVGs, KPI values, and long blockquotes to fit their containers
+- Fix Mermaid diagrams rendering tiny in slide containers (flex shrink-wrap + inline max-width)
+- Fix KPI card overflow for text values (white-space + transform scale)
+- Fix quote slides with long text (proportional font-size reduction)
+
+### Files
+- `references/slide-patterns.md` — slide engine CSS, all 10 type layouts, transitions, nav chrome, content density limits, presets
+- `templates/slide-deck.html` — reference template demonstrating all 10 types in Midnight Editorial preset
+- `prompts/generate-slides.md` — slash command for generating slide decks
+- `SKILL.md` — new "Slide Deck Mode" section with slide routing, `--slides` flag detection, visual richness guidance
+
+## [0.1.4] - 2026-02-24
+
+- Removed Mermaid `handDrawn` mode — Rough.js hachure fills are hardcoded and render unreadable diagonal scribbles inside nodes with no user-facing override. All diagrams now use `look: 'classic'` with custom `themeVariables` for visual distinction.
+- Added `package.json` for `pi install` support — installs the skill and all slash commands in one step instead of `git clone` + manual `cp`
+
+## [0.1.3] - 2026-02-24
+
+- Extended `classDef` color warning to also cover per-node `style` directives — both hardcode text color that breaks in the opposite color scheme
+- Renamed `.node` card classes to `.ve-card` to fix CSS collision with Mermaid's internal `.node` class that broke diagram layout (PR #7)
+
+## [0.1.2] - 2026-02-19
+
+- Added sequence diagram syntax guidance to "Writing Valid Mermaid" — curly braces, brackets, and ampersands in message labels silently break rendering
+
+## [0.1.1] - 2026-02-19
+
+- Prompts no longer require the `pi-prompt-template-model` extension — each prompt now explicitly loads the skill itself
+- Added "Writing Valid Mermaid" section to `libraries.md` (quoting special chars, simple IDs, max node count, arrow styles, pipe escaping)
+- Fixed mobile scroll offset in `responsive-nav.md` — section headings now clear the sticky nav bar via `scroll-margin-top`
+- Added video preview to README
+
+## [0.1.0] - 2026-02-16
+
+Initial release.
+
+### Skill
+- Core workflow: Think (pick aesthetic) → Structure (read template) → Style (apply design) → Deliver (write + open)
+- 11 diagram types with rendering approach routing (Mermaid, CSS Grid, HTML tables, Chart.js)
+- 9 aesthetic directions (monochrome terminal, editorial, blueprint, neon, paper/ink, sketch, IDE-inspired, data-dense, gradient mesh)
+- Mermaid deep theming with `theme: 'base'` + `themeVariables`, hand-drawn mode, ELK layout
+- Zoom controls (buttons, scroll-to-zoom, drag-to-pan) required on all Mermaid containers
+- Proactive table rendering — agent generates HTML instead of ASCII for complex tables
+- Optional AI-generated illustrations via surf-cli + Gemini Nano Banana Pro
+- Both light and dark themes via CSS custom properties and `prefers-color-scheme`
+- Quality checks: squint test, swap test, overflow protection, zoom controls verification
+
+### References
+- `css-patterns.md` — theme setup, depth tiers, node cards, grid layouts, data tables, status badges, KPI cards, before/after panels, connectors, animations (fadeUp, fadeScale, drawIn, countUp), collapsible sections, overflow protection, generated image containers
+- `libraries.md` — Mermaid (CDN, ELK, deep theming, hand-drawn mode, CSS overrides, diagram examples), Chart.js, anime.js, Google Fonts with 13 font pairings
+- `responsive-nav.md` — sticky sidebar TOC on desktop, horizontal scrollable bar on mobile, scroll spy
+
+### Templates
+- `architecture.html` — CSS Grid card layout, terracotta/sage palette, depth tiers, flow arrows, pipeline with parallel branches
+- `mermaid-flowchart.html` — Mermaid flowchart with ELK + handDrawn mode, teal/cyan palette, zoom controls
+- `data-table.html` — HTML table with KPI cards, status badges, collapsible details, rose/cranberry palette
+
+### Prompt Templates
+- `/generate-web-diagram` — generate a diagram for any topic
+- `/diff-review` — visual diff review with architecture comparison, KPI dashboard, code review, decision log
+- `/plan-review` — plan vs. codebase with current/planned architecture, risk assessment, understanding gaps
+- `/project-recap` — project mental model snapshot for context-switching
+- `/fact-check` — verify factual accuracy of review pages and plan docs against actual code

package/plugin/skills/visual-explainer/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nico Bailon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/plugin/skills/visual-explainer/README.md

@@ -0,0 +1,137 @@
+<p>
+  <img src="banner.png" alt="visual-explainer" width="1100">
+</p>
+
+# visual-explainer
+
+**An agent skill that turns complex terminal output into styled HTML pages you actually want to read.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](LICENSE)
+
+Ask your agent to explain a system architecture, review a diff, or compare requirements against a plan. Instead of ASCII art and box-drawing tables, it generates a self-contained HTML page and opens it in your browser:
+
+```
+> draw a diagram of our authentication flow
+> /diff-review
+> /plan-review ~/docs/refactor-plan.md
+```
+
+Each one produces a single `.html` file with real typography, dark/light theme support, and interactive Mermaid diagrams with zoom and pan. No build step, no dependencies beyond a browser.
+
+https://github.com/user-attachments/assets/55ebc81b-8732-40f6-a4b1-7c3781aa96ec
+
+## Why
+
+Every coding agent defaults to ASCII art when you ask for a diagram. Box-drawing characters, monospace alignment hacks, text arrows. It works for trivial cases, but anything beyond a 3-box flowchart turns into an unreadable mess that nobody would put in a presentation or share with a team.
+
+Tables are worse. Ask the agent to compare 15 requirements against a plan and you get a wall of pipes and dashes that wraps and breaks in the terminal. The data is there but it's painful to read.
+
+## Install
+
+### Pi
+
+```bash
+# Installs the skill and all slash commands in one step
+pi install https://github.com/nicobailon/visual-explainer
+```
+
+If you prefer a manual install, clone the repo and copy the prompts:
+
+```bash
+git clone https://github.com/nicobailon/visual-explainer.git ~/.pi/agent/skills/visual-explainer
+mkdir -p ~/.pi/agent/prompts
+cp ~/.pi/agent/skills/visual-explainer/prompts/*.md ~/.pi/agent/prompts/
+```
+
+### Claude Code
+
+Clone the skill, then copy the prompt templates so they register as slash commands:
+
+```bash
+git clone https://github.com/nicobailon/visual-explainer.git ~/.claude/skills/visual-explainer
+mkdir -p ~/.claude/commands
+cp ~/.claude/skills/visual-explainer/prompts/*.md ~/.claude/commands/
+```
+
+If you have [surf-cli](https://github.com/nicobailon/surf-cli) installed, the skill can also generate illustrations via Gemini and embed them in pages. The agent detects surf automatically and skips image generation if it's not there.
+
+## Usage
+
+The agent loads the skill when you mention diagrams, architecture, flowcharts, schemas, or visualizations. It also kicks in automatically when it's about to dump a complex table in the terminal (4+ rows or 3+ columns) — it renders HTML instead and opens it in the browser. Output goes to `~/.agent/diagrams/`.
+
+The skill ships with six prompt templates:
+
+| Command | What it does |
+|---------|-------------|
+| `/generate-web-diagram` | Generate an HTML diagram for any topic |
+| `/generate-slides` | Generate a magazine-quality slide deck for any topic |
+| `/diff-review` | Visual diff review with architecture comparison, code review, decision log |
+| `/plan-review` | Compare a plan against the codebase with risk assessment |
+| `/project-recap` | Mental model snapshot for context-switching back to a project |
+| `/fact-check` | Verify accuracy of a review page or plan doc against actual code |
+
+https://github.com/user-attachments/assets/342d3558-5fcf-4fb2-bc03-f0dd5b9e35dc
+
+Any prompt that produces a scrollable page also supports a `--slides` flag to generate a slide deck instead:
+
+```
+/diff-review --slides         # slide deck version of a diff review
+/project-recap --slides 2w    # slide deck recap of last 2 weeks
+```
+
+`/diff-review` is probably the most useful. Run it with no arguments to diff against `main`, or pass any git ref:
+
+```
+/diff-review                   # feature branch vs main (default)
+/diff-review abc123            # single commit
+/diff-review main..HEAD        # committed changes only
+/diff-review #42               # pull request
+```
+
+It generates a full page with before/after architecture diagrams, KPI dashboard, structured Good/Bad/Ugly code review, decision log with confidence indicators, and re-entry context for your future self.
+
+`/plan-review` does something similar but for implementation plans — pass it a plan file and it cross-references every claim against the actual codebase, produces current vs. planned architecture diagrams, and flags risks and gaps:
+
+```
+/plan-review ~/docs/refactor-plan.md
+```
+
+`/project-recap` is designed for context-switching back to a project after days away. It scans recent git activity and produces an architecture snapshot, decision log, and cognitive debt hotspots. `/fact-check` takes any document that makes claims about code and verifies every one of them.
+
+## How It Works
+
+```
+SKILL.md (workflow + design principles)
+    ↓
+references/           ← agent reads before each generation
+├── css-patterns.md   (layouts, animations, theming, depth tiers)
+├── libraries.md      (Mermaid theming, Chart.js, anime.js, font pairings)
+├── responsive-nav.md (sticky sidebar TOC for multi-section pages)
+└── slide-patterns.md (slide engine, 10 slide types, transitions, presets)
+    ↓
+templates/            ← agent reads the matching reference template
+├── architecture.html (CSS Grid cards — terracotta/sage palette)
+├── mermaid-flowchart.html (Mermaid + ELK — teal/cyan palette)
+├── data-table.html   (tables with KPIs and badges — rose/cranberry palette)
+└── slide-deck.html   (viewport-fit slides — midnight editorial palette)
+    ↓
+~/.agent/diagrams/filename.html → opens in browser
+```
+
+The agent picks an aesthetic direction, reads the right reference template, generates a self-contained HTML file with both light and dark themes, and opens it. The four templates use deliberately different palettes so the agent learns variety rather than defaulting to one look. The skill handles 11 diagram types — Mermaid for anything with connections (flowcharts, sequences, ER, state machines, mind maps), CSS Grid for text-heavy architecture overviews, HTML tables for data, Chart.js for dashboards — and routes to the right approach automatically.
+
+To customize the output directory, browser command, or add your own diagram types and CSS patterns, edit the files directly. The agent reads them fresh each time.
+
+## Limitations
+
+- Requires a browser to view — no inline terminal rendering
+- Switching OS theme requires a page refresh for Mermaid SVGs (CSS-styled elements respond instantly)
+- Results vary by model capability — the skill provides design guidance, not pixel-perfect specs
+
+## Credits
+
+Borrows ideas from [Anthropic's frontend-design skill](https://github.com/anthropics/skills) and [interface-design](https://github.com/Dammyjay93/interface-design), adapted for one-shot diagram generation.
+
+## License
+
+MIT

package/plugin/skills/visual-explainer/SKILL.md

@@ -0,0 +1,352 @@
+---
+name: visual-explainer
+description: Generate beautiful, self-contained HTML pages that visually explain systems, code changes, plans, and data. Use when the user asks for a diagram, architecture overview, diff review, plan review, project recap, comparison table, or any visual explanation of technical concepts. Also use proactively when you are about to render a complex ASCII table (4+ rows or 3+ columns) — present it as a styled HTML page instead.
+license: MIT
+compatibility: Requires a browser to view generated HTML files. Optional surf-cli for AI image generation.
+metadata:
+  author: nicobailon
+  version: "0.2.0"
+---
+
+# Visual Explainer
+
+Generate self-contained HTML files for technical diagrams, visualizations, and data tables. Always open the result in the browser. Never fall back to ASCII art when this skill is loaded.
+
+**Proactive table rendering.** When you're about to present tabular data as an ASCII box-drawing table in the terminal (comparisons, audits, feature matrices, status reports, any structured rows/columns), generate an HTML page instead. The threshold: if the table has 4+ rows or 3+ columns, it belongs in the browser. Don't wait for the user to ask — render it as HTML automatically and tell them the file path. You can still include a brief text summary in the chat, but the table itself should be the HTML page. Store the resulting page in the local project documentation if you have that context.
+
+## Workflow
+
+### 1. Think (5 seconds, not 5 minutes)
+
+Before writing HTML, commit to a direction. Don't default to "dark theme with blue accents" every time.
+
+**Who is looking?** A developer understanding a system? A PM seeing the big picture? A team reviewing a proposal? This shapes information density and visual complexity.
+
+**What type of diagram?** Architecture, flowchart, sequence, data flow, schema/ER, state machine, mind map, data table, timeline, or dashboard. Each has distinct layout needs and rendering approaches (see Diagram Types below).
+
+**What aesthetic?** Pick one and commit. The constrained aesthetics (Blueprint, Editorial, Paper/ink) are safer — they have specific requirements that prevent generic output. The flexible ones (IDE-inspired) require more discipline.
+
+**Constrained aesthetics (prefer these):**
+- Blueprint (technical drawing feel, subtle grid background, deep slate/blue palette, monospace labels, precise borders) — see `websocket-implementation-plan.html` for reference
+- Editorial (serif headlines like Instrument Serif or Crimson Pro, generous whitespace, muted earth tones or deep navy + gold)
+- Paper/ink (warm cream `#faf7f5` background, terracotta/sage accents, informal feel)
+- Monochrome terminal (green/amber on near-black, monospace everything, CRT glow optional)
+
+**Flexible aesthetics (use with caution):**
+- IDE-inspired (borrow a real, named color scheme: Dracula, Nord, Catppuccin Mocha/Latte, Solarized Dark/Light, Gruvbox, One Dark, Rosé Pine) — commit to the actual palette, don't approximate
+- Data-dense (small type, tight spacing, maximum information, muted colors)
+
+**Explicitly forbidden:**
+- Neon dashboard (cyan + magenta + purple on dark) — always produces AI slop
+- Gradient mesh (pink/purple/cyan blobs) — too generic
+- Any combination of Inter font + violet/indigo accents + gradient text
+
+Vary the choice each time. If the last diagram was dark and technical, make the next one light and editorial. The swap test: if you replaced your styling with a generic dark theme and nobody would notice the difference, you haven't designed anything.
+
+### 2. Structure
+
+**Read the reference template** before generating. Don't memorize it — read it each time to absorb the patterns.
+- For text-heavy architecture overviews (card content matters more than topology): read `./templates/architecture.html`
+- For flowcharts, sequence diagrams, ER, state machines, mind maps: read `./templates/mermaid-flowchart.html`
+- For data tables, comparisons, audits, feature matrices: read `./templates/data-table.html`
+- For slide deck presentations (when `--slides` flag is present or `/generate-slides` is invoked): read `./templates/slide-deck.html` and `./references/slide-patterns.md`
+
+**For CSS/layout patterns and SVG connectors**, read `./references/css-patterns.md`.
+
+**For pages with 4+ sections** (reviews, recaps, dashboards), also read `./references/responsive-nav.md` for section navigation with sticky sidebar TOC on desktop and horizontal scrollable bar on mobile.
+
+**Choosing a rendering approach:**
+
+| Diagram type | Approach | Why |
+|---|---|---|
+| Architecture (text-heavy) | CSS Grid cards + flow arrows | Rich card content (descriptions, code, tool lists) needs CSS control |
+| Architecture (topology-focused) | **Mermaid** | Visible connections between components need automatic edge routing |
+| Flowchart / pipeline | **Mermaid** | Automatic node positioning and edge routing |
+| Sequence diagram | **Mermaid** | Lifelines, messages, and activation boxes need automatic layout |
+| Data flow | **Mermaid** with edge labels | Connections and data descriptions need automatic edge routing |
+| ER / schema diagram | **Mermaid** | Relationship lines between many entities need auto-routing |
+| State machine | **Mermaid** | State transitions with labeled edges need automatic layout |
+| Mind map | **Mermaid** | Hierarchical branching needs automatic positioning |
+| Data table | HTML `<table>` | Semantic markup, accessibility, copy-paste behavior |
+| Timeline | CSS (central line + cards) | Simple linear layout doesn't need a layout engine |
+| Dashboard | CSS Grid + Chart.js | Card grid with embedded charts |
+
+**Mermaid theming:** Always use `theme: 'base'` with custom `themeVariables` so colors match your page palette. Use `layout: 'elk'` for complex graphs (requires the `@mermaid-js/layout-elk` package — see `./references/libraries.md` for the CDN import). Override Mermaid's SVG classes with CSS for pixel-perfect control. See `./references/libraries.md` for full theming guide.
+
+**Mermaid zoom controls:** Always add zoom controls (+/−/reset buttons) to every `.mermaid-wrap` container. Complex diagrams render at small sizes and need zoom to be readable. Include Ctrl/Cmd+scroll zoom on the container. See the zoom controls pattern in `./references/css-patterns.md` and the reference template at `./templates/mermaid-flowchart.html`.
+
+**Mermaid CSS class collision constraint:** Never define `.node` as a page-level CSS class. Mermaid.js uses `.node` internally on SVG `<g>` elements with `transform: translate(x, y)` for positioning. Page-level `.node` styles (hover transforms, box-shadows) leak into diagrams and break layout. Use the namespaced `.ve-card` class for card components instead. The only safe way to style Mermaid's `.node` is scoped under `.mermaid` (e.g., `.mermaid .node rect`).
+
+**AI-generated illustrations (optional).** If [surf-cli](https://github.com/nicobailon/surf-cli) is available, you can generate images via Gemini and embed them in the page for creative, illustrative, explanatory, educational, or decorative purposes. Check availability with `which surf`. If available:
+
+```bash
+# Generate to a temp file (use --aspect-ratio for control)
+surf gemini "descriptive prompt" --generate-image /tmp/ve-img.png --aspect-ratio 16:9
+
+# Base64 encode for self-containment (macOS)
+IMG=$(base64 -i /tmp/ve-img.png)
+# Linux: IMG=$(base64 -w 0 /tmp/ve-img.png)
+
+# Embed in HTML and clean up
+# <img src="data:image/png;base64,${IMG}" alt="descriptive alt text">
+rm /tmp/ve-img.png
+```
+
+See `./references/css-patterns.md` for image container styles (hero banners, inline illustrations, captions).
+
+**When to use:** Hero banners that establish the page's visual tone. Conceptual illustrations for abstract systems that Mermaid can't express (physical infrastructure, user journeys, mental models). Educational diagrams that benefit from artistic or photorealistic rendering. Decorative accents that reinforce the aesthetic.
+
+**When to skip:** Anything Mermaid or CSS handles well. Generic decoration that doesn't convey meaning. Data-heavy pages where images would distract. Always degrade gracefully — if surf isn't available, skip images without erroring. The page should stand on its own with CSS and typography alone.
+
+**Prompt craft:** Match the image to the page's palette and aesthetic direction. Specify the style (3D render, technical illustration, watercolor, isometric, flat vector, etc.) and mention dominant colors from your CSS variables. Use `--aspect-ratio 16:9` for hero banners, `--aspect-ratio 1:1` for inline illustrations. Keep prompts specific — "isometric illustration of a message queue with cyan nodes on dark navy background" beats "a diagram of a queue."
+
+### 3. Style
+
+Apply these principles to every diagram:
+
+**Typography is the diagram.** Pick a distinctive font pairing from the list in `./references/libraries.md`. Every page should use a different pairing from recent generations.
+
+**Forbidden as `--font-body`:** Inter, Roboto, Arial, Helvetica, system-ui alone. These are AI slop signals.
+
+**Good pairings (use these):**
+- DM Sans + Fira Code (technical, precise)
+- Instrument Serif + JetBrains Mono (editorial, refined)
+- IBM Plex Sans + IBM Plex Mono (reliable, readable)
+- Bricolage Grotesque + Fragment Mono (bold, characterful)
+- Plus Jakarta Sans + Azeret Mono (rounded, approachable)
+
+Load via `<link>` in `<head>`. Include a system font fallback in the `font-family` stack for offline resilience.
+
+**Color tells a story.** Use CSS custom properties for the full palette. Define at minimum: `--bg`, `--surface`, `--border`, `--text`, `--text-dim`, and 3-5 accent colors. Each accent should have a full and a dim variant (for backgrounds). Name variables semantically when possible (`--pipeline-step` not `--blue-3`). Support both themes.
+
+**Forbidden accent colors:** `#8b5cf6` `#7c3aed` `#a78bfa` (indigo/violet), `#d946ef` (fuchsia), the cyan-magenta-pink combination. These are Tailwind defaults that signal zero design intent.
+
+**Good accent palettes (use these):**
+- Terracotta + sage (`#c2410c`, `#65a30d`) — warm, earthy
+- Teal + slate (`#0891b2`, `#0369a1`) — technical, precise
+- Rose + cranberry (`#be123c`, `#881337`) — editorial, refined
+- Amber + emerald (`#d97706`, `#059669`) — data-focused
+- Deep blue + gold (`#1e3a5f`, `#d4a73a`) — premium, sophisticated
+
+Put your primary aesthetic in `:root` and the alternate in the media query:
+
+```css
+/* Light-first (editorial, paper/ink, blueprint): */
+:root { /* light values */ }
+@media (prefers-color-scheme: dark) { :root { /* dark values */ } }
+
+/* Dark-first (neon, IDE-inspired, terminal): */
+:root { /* dark values */ }
+@media (prefers-color-scheme: light) { :root { /* light values */ } }
+```
+
+**Surfaces whisper, they don't shout.** Build depth through subtle lightness shifts (2-4% between levels), not dramatic color changes. Borders should be low-opacity rgba (`rgba(255,255,255,0.08)` in dark mode, `rgba(0,0,0,0.08)` in light) — visible when you look, invisible when you don't.
+
+**Backgrounds create atmosphere.** Don't use flat solid colors for the page background. Subtle gradients, faint grid patterns via CSS, or gentle radial glows behind focal areas. The background should feel like a space, not a void.
+
+**Visual weight signals importance.** Not every section deserves equal visual treatment. Executive summaries and key metrics should dominate the viewport on load (larger type, more padding, subtle accent-tinted background zone). Reference sections (file maps, dependency lists, decision logs) should be compact and stay out of the way. Use `<details>/<summary>` for sections that are useful but not primary — the collapsible pattern is in `./references/css-patterns.md`.
+
+**Surface depth creates hierarchy.** Vary card depth to signal what matters. Hero sections get elevated shadows and accent-tinted backgrounds (`ve-card--hero` pattern). Body content stays flat (default `.ve-card`). Code blocks and secondary content feel recessed (`ve-card--recessed`). See the depth tiers in `./references/css-patterns.md`. Don't make everything elevated — when everything pops, nothing does.
+
+**Animation earns its place.** Staggered fade-ins on page load are almost always worth it — they guide the eye through the diagram's hierarchy. Mix animation types by role: `fadeUp` for cards, `fadeScale` for KPIs and badges, `drawIn` for SVG connectors, `countUp` for hero numbers. Hover transitions on interactive-feeling elements make the diagram feel alive. Always respect `prefers-reduced-motion`. CSS transitions and keyframes handle most cases. For orchestrated multi-element sequences, anime.js via CDN is available (see `./references/libraries.md`).
+
+**Forbidden animations:**
+- Animated glowing box-shadows (`@keyframes glow { box-shadow: 0 0 20px... }`) — this is AI slop
+- Pulsing/breathing effects on static content
+- Continuous animations that run after page load (except for progress indicators)
+
+Keep animations purposeful: entrance reveals, hover feedback, and user-initiated interactions. Nothing should glow or pulse on its own.
+
+### 4. Deliver
+
+**Output location:** Write to `~/.agent/diagrams/`. Use a descriptive filename based on content: `modem-architecture.html`, `pipeline-flow.html`, `schema-overview.html`. The directory persists across sessions.
+
+**Open in browser:**
+- macOS: `open ~/.agent/diagrams/filename.html`
+- Linux: `xdg-open ~/.agent/diagrams/filename.html`
+
+**Tell the user** the file path so they can re-open or share it.
+
+## Diagram Types
+
+### Architecture / System Diagrams
+Two approaches depending on what matters more:
+
+**Text-heavy overviews** (card content matters more than connections): CSS Grid with explicit row/column placement. Sections as rounded cards with colored borders and monospace labels. Vertical flow arrows between sections. Nested grids for subsystems. The reference template at `./templates/architecture.html` demonstrates this pattern. Use when cards need descriptions, code references, tool lists, or other rich content that Mermaid nodes can't hold.
+
+**Topology-focused diagrams** (connections matter more than card content): **Use Mermaid.** A `graph TD` or `graph LR` with custom `themeVariables` produces proper diagrams with automatic edge routing. Use when the point is showing how components connect rather than describing what each component does in detail.
+
+### Flowcharts / Pipelines
+**Use Mermaid.** Automatic node positioning and edge routing produces proper diagrams with connecting lines, decision diamonds, and parallel branches — dramatically better than CSS flexbox with arrow characters. Use `graph TD` for top-down or `graph LR` for left-right. Color-code node types with Mermaid's `classDef` or rely on `themeVariables` for automatic styling.
+
+### Sequence Diagrams
+**Use Mermaid.** Lifelines, messages, activation boxes, notes, and loops all need automatic layout. Use Mermaid's `sequenceDiagram` syntax. Style actors and messages via CSS overrides on `.actor`, `.messageText`, `.activation` classes.
+
+### Data Flow Diagrams
+**Use Mermaid.** Data flow diagrams emphasize connections over boxes — exactly what Mermaid excels at. Use `graph LR` or `graph TD` with edge labels for data descriptions. Thicker, colored edges for primary flows. Source/sink nodes styled differently from transform nodes via Mermaid's `classDef`.
+
+### Schema / ER Diagrams
+**Use Mermaid.** Relationship lines between entities need automatic routing. Use Mermaid's `erDiagram` syntax with entity attributes. Style via `themeVariables` and CSS overrides on `.er.entityBox` and `.er.relationshipLine`.
+
+### State Machines / Decision Trees
+**Use Mermaid.** Use `stateDiagram-v2` for states with labeled transitions. Supports nested states, forks, joins, and notes. Decision trees can use `graph TD` with diamond decision nodes.
+
+**`stateDiagram-v2` label caveat:** Transition labels have a strict parser — colons, parentheses, `<br/>`, HTML entities, and most special characters cause silent parse failures ("Syntax error in text"). If your labels need any of these (e.g., `cancel()`, `curate: true`, multi-line labels), use `flowchart LR` instead with rounded nodes and quoted edge labels (`|"label text"|`). Flowcharts handle all special characters and support `<br/>` for line breaks. Reserve `stateDiagram-v2` for simple single-word or plain-text labels.
+
+### Mind Maps / Hierarchical Breakdowns
+**Use Mermaid.** Use `mindmap` syntax for hierarchical branching from a root node. Mermaid handles the radial layout automatically. Style with `themeVariables` to control node colors at each depth level.
+
+### Data Tables / Comparisons / Audits
+Use a real `<table>` element — not CSS Grid pretending to be a table. Tables get accessibility, copy-paste behavior, and column alignment for free. The reference template at `./templates/data-table.html` demonstrates all patterns below.
+
+**Use proactively.** Any time you'd render an ASCII box-drawing table in the terminal, generate an HTML table instead. This includes: requirement audits (request vs plan), feature comparisons, status reports, configuration matrices, test result summaries, dependency lists, permission tables, API endpoint inventories — any structured rows and columns.
+
+Layout patterns:
+- Sticky `<thead>` so headers stay visible when scrolling long tables
+- Alternating row backgrounds via `tr:nth-child(even)` (subtle, 2-3% lightness shift)
+- First column optionally sticky for wide tables with horizontal scroll
+- Responsive wrapper with `overflow-x: auto` for tables wider than the viewport
+- Column width hints via `<colgroup>` or `th` widths — let text-heavy columns breathe
+- Row hover highlight for scanability
+
+Status indicators (use styled `<span>` elements, never emoji):
+- Match/pass/yes: colored dot or checkmark with green background
+- Gap/fail/no: colored dot or cross with red background
+- Partial/warning: amber indicator
+- Neutral/info: dim text or muted badge
+
+Cell content:
+- Wrap long text naturally — don't truncate or force single-line
+- Use `<code>` for technical references within cells
+- Secondary detail text in `<small>` with dimmed color
+- Keep numeric columns right-aligned with `tabular-nums`
+
+### Timeline / Roadmap Views
+Vertical or horizontal timeline with a central line (CSS pseudo-element). Phase markers as circles on the line. Content cards branching left/right (alternating) or all to one side. Date labels on the line. Color progression from past (muted) to future (vivid).
+
+### Dashboard / Metrics Overview
+Card grid layout. Hero numbers large and prominent. Sparklines via inline SVG `<polyline>`. Progress bars via CSS `linear-gradient` on a div. For real charts (bar, line, pie), use **Chart.js via CDN** (see `./references/libraries.md`). KPI cards with trend indicators (up/down arrows, percentage deltas).
+
+## Slide Deck Mode
+
+An alternative output format for presenting content as a magazine-quality slide presentation instead of a scrollable page. **Opt-in only** — the agent generates slides when the user invokes `/generate-slides`, passes `--slides` to an existing prompt (e.g., `/diff-review --slides`), or explicitly asks for a slide deck. Never auto-select slide format.
+
+**Before generating slides**, read `./references/slide-patterns.md` (engine CSS, slide types, transitions, nav chrome, presets) and `./templates/slide-deck.html` (reference template showing all 10 types). Also read `./references/css-patterns.md` for shared patterns and `./references/libraries.md` for Mermaid/Chart.js theming.
+
+**Slides are not pages reformatted.** They're a different medium. Each slide is exactly one viewport tall (100dvh) with no scrolling. Typography is 2–3× larger. Compositions are bolder. The agent composes a narrative arc (impact → context → deep dive → resolution) rather than mechanically paginating the source.
+
+**Content completeness.** Changing the medium does not mean dropping content. Follow the "Planning a Deck from a Source Document" process in `slide-patterns.md` before writing any HTML: inventory the source, map every item to slides, verify coverage. Every section, decision, data point, specification, and collapsible detail from the source must appear in the deck. If a plan has 7 sections, the deck covers all 7. If there are 6 decisions, present all 6 — not the 2 that fit on one slide. Collapsible details in the source become their own slides. Add more slides rather than cutting content. A 22-slide deck that covers everything beats a 13-slide deck that looks polished but is missing 40% of the source.
+
+**Slide types (10):** Title, Section Divider, Content, Split, Diagram, Dashboard, Table, Code, Quote, Full-Bleed. Each has a defined layout in `slide-patterns.md`. Content that exceeds a slide's density limit splits across multiple slides — never scrolls within a slide.
+
+**Visual richness:** Check `which surf` at the start. If surf-cli is available, generate 2–4 images (title slide background, full-bleed background, optional content illustrations) before writing HTML — see the Proactive Imagery section in `slide-patterns.md` for the workflow. Also use SVG decorative accents, per-slide background gradients, inline sparklines, and small Mermaid diagrams. Visual-first, text-second.
+
+**Compositional variety:** Consecutive slides must vary spatial approach — centered, left-heavy, right-heavy, split, edge-aligned, full-bleed. Three centered slides in a row means push one off-axis.
+
+**Curated presets:** Four slide-specific presets as starting points (Midnight Editorial, Warm Signal, Terminal Mono, Swiss Clean) plus the existing 8 aesthetic directions adapted for slides. Pick one and commit. See `slide-patterns.md` for preset CSS values.
+
+**`--slides` flag on existing prompts:** When a user passes `--slides` to `/diff-review`, `/plan-review`, `/project-recap`, or other prompts, the agent gathers data using the prompt's normal data-gathering instructions, then presents the content as a slide deck instead of a scrollable page. The slide version tells the same story with different structure and pacing — but the same breadth of coverage. Don't use the slide format as an excuse to summarize or skip sections that the scrollable version would have included.
+
+## File Structure
+
+Every diagram is a single self-contained `.html` file. No external assets except CDN links (fonts, optional libraries). Structure:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Descriptive Title</title>
+  <link href="https://fonts.googleapis.com/css2?family=...&display=swap" rel="stylesheet">
+  <style>
+    /* CSS custom properties, theme, layout, components — all inline */
+  </style>
+</head>
+<body>
+  <!-- Semantic HTML: sections, headings, lists, tables, inline SVG -->
+  <!-- No script needed for static CSS-only diagrams -->
+  <!-- Optional: <script> for Mermaid, Chart.js, or anime.js when used -->
+</body>
+</html>
+```
+
+## Quality Checks
+
+Before delivering, verify:
+- **The squint test**: Blur your eyes. Can you still perceive hierarchy? Are sections visually distinct?
+- **The swap test**: Would replacing your fonts and colors with a generic dark theme make this indistinguishable from a template? If yes, push the aesthetic further.
+- **Both themes**: Toggle your OS between light and dark mode. Both should look intentional, not broken.
+- **Information completeness**: Does the diagram actually convey what the user asked for? Pretty but incomplete is a failure.
+- **No overflow**: Resize the browser to different widths. No content should clip or escape its container. Every grid and flex child needs `min-width: 0`. Side-by-side panels need `overflow-wrap: break-word`. Never use `display: flex` on `<li>` for marker characters — it creates anonymous flex items that can't shrink, causing lines with many inline `<code>` badges to overflow. Use absolute positioning for markers instead. See the Overflow Protection section in `./references/css-patterns.md`.
+- **Mermaid zoom controls**: Every `.mermaid-wrap` container must have zoom controls (+/−/reset buttons), Ctrl/Cmd+scroll zoom, and click-and-drag panning. Complex diagrams render too small without them. The cursor should change to `grab` when zoomed in and `grabbing` while dragging. See `./references/css-patterns.md` for the full pattern.
+- **File opens cleanly**: No console errors, no broken font loads, no layout shifts.
+
+## Anti-Patterns (AI Slop)
+
+These patterns are explicitly forbidden. They signal "AI-generated template" and undermine the skill's purpose of producing distinctive, high-quality diagrams. Review every generated page against this list.
+
+### Typography
+
+**Forbidden fonts as primary `--font-body`:**
+- Inter — the single most overused AI default
+- Roboto, Arial, Helvetica — generic system fallbacks promoted to primary
+- system-ui, sans-serif alone — no character, no intent
+
+**Required:** Pick from the font pairings in `./references/libraries.md`. Every generation should use a different pairing from the last.
+
+### Color Palette
+
+**Forbidden accent colors:**
+- Indigo-500/violet-500 (`#8b5cf6`, `#7c3aed`, `#a78bfa`) — Tailwind's default purple range
+- The cyan + magenta + pink neon gradient combination (`#06b6d4` → `#d946ef` → `#f472b6`)
+- Any palette that could be described as "Tailwind defaults with purple/pink/cyan accents"
+
+**Forbidden color effects:**
+- Gradient text on headings (`background: linear-gradient(...); background-clip: text;`) — this screams AI-generated
+- Animated glowing box-shadows on cards (`box-shadow: 0 0 20px var(--glow); animation: glow 2s...`)
+- Multiple overlapping radial glows in accent colors creating a "neon haze"
+
+**Required:** Build palettes from the reference templates (terracotta/sage, teal/cyan, rose/cranberry, slate/blue) or derive from real IDE themes (Dracula, Nord, Solarized, Gruvbox, Catppuccin). Accents should feel intentional, not default.
+
+### Section Headers
+
+**Forbidden:**
+- Emoji icons in section headers (🏗️, ⚙️, 📁, 💻, 📅, 🔗, ⚡, 🔧, 📦, 🚀, etc.)
+- Section headers that all use the same icon-in-rounded-box pattern
+
+**Required:** Use styled monospace labels with colored dot indicators (see `.section-label` in templates), numbered badges (`section__num` pattern), or asymmetric section dividers. If an icon is genuinely needed, use an inline SVG that matches the palette — not emoji.
+
+### Layout & Hierarchy
+
+**Forbidden:**
+- Perfectly centered everything with uniform padding
+- All cards styled identically with the same border-radius, shadow, and spacing
+- Every section getting equal visual treatment — no hero/primary vs. secondary distinction
+- Symmetric layouts where left and right halves mirror each other
+
+**Required:** Vary visual weight. Hero sections should dominate (larger type, more padding, accent-tinted background). Reference sections should feel compact. Use the depth tiers (hero → elevated → default → recessed). Asymmetric layouts create interest.
+
+### Template Patterns
+
+**Forbidden:**
+- Three-dot window chrome (red/yellow/green dots) on code blocks — this is a cliché
+- KPI cards where every metric has identical gradient text treatment
+- "Neon Dashboard" as an aesthetic choice — it always produces generic results
+- Gradient meshes with pink/purple/cyan blobs in the background
+
+**Required:** Code blocks use a simple header with filename or language label. KPI cards vary by importance — hero numbers for the primary metric, subdued treatment for supporting metrics. Pick aesthetics with natural constraints: Blueprint (must feel technical/precise), Editorial (must have generous whitespace and serif typography), Paper/ink (must feel warm and informal).
+
+### The Slop Test
+
+Before delivering, apply this test: **Would a developer looking at this page immediately think "AI generated this"?** The telltale signs:
+
+1. Inter or Roboto font with purple/violet gradient accents
+2. Every heading has `background-clip: text` gradient
+3. Emoji icons leading every section
+4. Glowing cards with animated shadows
+5. Cyan-magenta-pink color scheme on dark background
+6. Perfectly uniform card grid with no visual hierarchy
+7. Three-dot code block chrome
+
+If two or more of these are present, the page is slop. Regenerate with a different aesthetic direction — Editorial, Blueprint, Paper/ink, or a specific IDE theme. These constrained aesthetics are harder to mess up because they have specific visual requirements that prevent defaulting to generic patterns.

package/plugin/skills/visual-explainer/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "visual-explainer",
+  "version": "0.3.0",
+  "description": "Agent skill that generates beautiful HTML pages for diagrams, diff reviews, plan reviews, and data tables",
+  "keywords": ["pi-package"],
+  "license": "MIT",
+  "pi": {
+    "skills": ["./"],
+    "prompts": ["./prompts"]
+  }
+}