feat: v0.4.1 — Mermaid TD vs LR guidance, README simplification

Mermaid layout direction:
- New 'Layout Direction: TD vs LR' section in libraries.md
- Prefer flowchart TD over LR for complex diagrams (5+ nodes)
- Updated all diagram type sections to recommend TD first

Documentation:
- Simplified README: consolidated Install, added Slide Deck Mode section
- Added /generate-visual-plan to command table

Author: nicobailon

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.4.1] - 2026-03-01
+
+### Mermaid Layout Direction
+- New "Layout Direction: TD vs LR" section in `libraries.md`
+- Prefer `flowchart TD` (top-down) over `flowchart LR` (left-to-right) for complex diagrams
+- LR spreads horizontally and makes labels unreadable with many nodes
+- Rule: use TD for 5+ nodes or any branching; LR only for simple 3-4 node linear flows
+
+### Documentation
+- Simplified README: trimmed Usage section, consolidated Install, added Slide Deck Mode section
+- Added `/generate-visual-plan` to command table
+
 ## [0.4.0] - 2026-02-28
 
 ### New Prompt Template

README.md

@@ -8,130 +8,94 @@
 
 [![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:
+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.
+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.
 
 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
+This skill fixes that. Real typography, dark/light themes, interactive Mermaid diagrams with zoom and pan. No build step, no dependencies beyond a browser.
 
-### Pi
+## 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:
-
+**Claude Code:**
 ```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 seven prompt templates:
+## Commands
 
 | Command | What it does |
 |---------|-------------|
 | `/generate-web-diagram` | Generate an HTML diagram for any topic |
 | `/generate-visual-plan` | Generate a visual implementation plan for a feature or extension |
-| `/generate-slides` | Generate a magazine-quality slide deck for any topic |
-| `/diff-review` | Visual diff review with architecture comparison, code review, decision log |
+| `/generate-slides` | Generate a magazine-quality slide deck |
+| `/diff-review` | Visual diff review with architecture comparison and code review |
 | `/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 |
+| `/fact-check` | Verify accuracy of a document 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:
+The agent 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.
 
-```
-/diff-review --slides         # slide deck version of a diff review
-/project-recap --slides 2w    # slide deck recap of last 2 weeks
-```
+## Slide Deck Mode
 
-`/diff-review` is probably the most useful. Run it with no arguments to diff against `main`, or pass any git ref:
+Any command that produces a scrollable page supports `--slides` to generate a slide deck instead:
 
 ```
-/diff-review                   # feature branch vs main (default)
-/diff-review abc123            # single commit
-/diff-review main..HEAD        # committed changes only
-/diff-review #42               # pull request
+/diff-review --slides
+/project-recap --slides 2w
 ```
 
-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.
+https://github.com/user-attachments/assets/342d3558-5fcf-4fb2-bc03-f0dd5b9e35dc
 
 ## 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)
+references/           ← agent reads before generating
+├── css-patterns.md   (layouts, animations, theming)
+├── libraries.md      (Mermaid, Chart.js, fonts)
+├── responsive-nav.md (sticky TOC for multi-section pages)
+└── slide-patterns.md (slide engine, 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)
+templates/            ← reference templates with different palettes
+├── architecture.html
+├── mermaid-flowchart.html
+├── data-table.html
+└── slide-deck.html
     ↓
 ~/.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.
+The skill routes to the right approach automatically: Mermaid for flowcharts and diagrams, CSS Grid for architecture overviews, HTML tables for data, Chart.js for dashboards.
 
 ## 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
+- Requires a browser to view
+- Switching OS theme requires a page refresh for Mermaid SVGs
+- Results vary by model capability
 
 ## 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.
+Borrows ideas from [Anthropic's frontend-design skill](https://github.com/anthropics/skills) and [interface-design](https://github.com/Dammyjay93/interface-design).
 
 ## License
 

SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: Requires a browser to view generated HTML files. Optional surf-cli for AI image generation.
 metadata:
   author: nicobailon
-  version: "0.4.0"
+  version: "0.4.1"
 ---
 
 # Visual Explainer
@@ -84,6 +84,8 @@ Vary the choice each time. If the last diagram was dark and technical, make the
 
 **Mermaid scaling:** Complex diagrams with 10+ nodes render too small by default. Increase `fontSize` in themeVariables to 18-20px (default is 16px), or apply a CSS `transform: scale(1.3)` on the SVG. Don't let diagrams float in oversized containers with unreadable text. See `./references/css-patterns.md` "Scaling Small Diagrams".
 
+**Mermaid layout direction:** Prefer `flowchart TD` (top-down) over `flowchart LR` (left-to-right) for complex diagrams. LR spreads horizontally and makes labels unreadable when there are many nodes. Use LR only for simple 3-4 node linear flows. See `./references/libraries.md` "Layout Direction: TD vs LR".
+
 **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:
@@ -183,24 +185,24 @@ 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.
+**Topology-focused diagrams** (connections matter more than card content): **Use Mermaid.** A `graph TD` (or `graph LR` for simple linear flows) 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.
+**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. Prefer `graph TD` (top-down); use `graph LR` only for simple 3-4 node linear flows. 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`.
+**Use Mermaid.** Data flow diagrams emphasize connections over boxes — exactly what Mermaid excels at. Use `graph TD` (or `graph LR` for simple linear flows) 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.
+**`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 TD` 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.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "visual-explainer",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Agent skill that generates beautiful HTML pages for diagrams, diff reviews, plan reviews, and data tables",
   "keywords": ["pi-package"],
   "license": "MIT",

prompts/generate-visual-plan.md

@@ -54,7 +54,7 @@ Verify each against the code. If something cannot be verified, mark it as uncert
 
 2. **The Problem** — side-by-side comparison panels showing current behavior vs. desired behavior. Use concrete examples, not abstract descriptions. Show what the user experiences or what the code does, step by step. *Visual treatment: two-column grid with rose-tinted "Before" header and sage-tinted "After" header. Numbered flow steps with arrows between them.*
 
-3. **State Machine** — Mermaid flowchart or stateDiagram showing the states and transitions. Label edges with the triggers (commands, events, conditions). *Wrap in `.mermaid-wrap` with zoom controls. Use `flowchart LR` instead of `stateDiagram-v2` if labels need special characters like colons or parentheses. Add explanatory caption below the diagram.*
+3. **State Machine** — Mermaid flowchart or stateDiagram showing the states and transitions. Label edges with the triggers (commands, events, conditions). *Wrap in `.mermaid-wrap` with zoom controls. Use `flowchart TD` instead of `stateDiagram-v2` if labels need special characters like colons or parentheses. Add explanatory caption below the diagram.*
 
 4. **State Variables** — card grid showing new state and existing state (if modified). Use code blocks with proper `white-space: pre-wrap`. *Visual treatment: two cards side-by-side, elevated depth, monospace labels.*
 

references/libraries.md

@@ -256,6 +256,31 @@ B->>S: POST /submit with selected indices
 
 **Don't mix diagram syntax.** Each diagram type has its own syntax. `-->` works in flowcharts but not in sequence diagrams (`->>` instead). `:::className` works in flowcharts but not in ER diagrams. When in doubt, check the examples below for correct syntax per type.
 
+### Layout Direction: TD vs LR
+
+`flowchart LR` (left-to-right) spreads horizontally. With many nodes, Mermaid scales everything down to fit the width, making text unreadable. `flowchart TD` (top-down) is almost always better.
+
+**When to use each:**
+
+| Direction | Use when | Avoid when |
+|-----------|----------|------------|
+| `TD` (top-down) | Complex diagrams, 5+ nodes, hierarchies, architecture | Simple A→B→C linear flows |
+| `LR` (left-to-right) | Simple linear flows, 3-4 nodes, pipelines | Complex graphs, many branches |
+
+**Rule of thumb:** If the diagram has more than one row of nodes or any branching, use `TD`. The extra vertical space makes labels readable.
+
+```
+%% WRONG — LR with many nodes produces wide, short, unreadable diagram
+flowchart LR
+  A --> B --> C --> D --> E
+  A --> F --> G --> H
+  
+%% RIGHT — TD uses vertical space, labels stay readable
+flowchart TD
+  A --> B --> C --> D --> E
+  A --> F --> G --> H
+```
+
 ### Diagram Type Examples
 
 **Flowchart with decisions:**