docs: warn against bare mermaid pre tags without diagram-shell pattern

Added explicit warning to SKILL.md that bare <pre class="mermaid"> tags
render but produce tiny unusable diagrams. Users must use the full
diagram-shell pattern from templates/mermaid-flowchart.html which
includes zoom/pan controls.

Author: nicobailon

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [0.6.3] - 2026-03-09
+
+### Documentation
+- Added explicit warning against using bare `<pre class="mermaid">` tags — they render but produce tiny unusable diagrams without zoom/pan controls. Updated SKILL.md to point to the full `diagram-shell` pattern from `templates/mermaid-flowchart.html`.
+
 ## [0.6.2] - 2026-03-08
 
 ### Bug Fixes

package.json

@@ -1,6 +1,6 @@
 {
   "name": "visual-explainer",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "Agent skill that generates beautiful HTML pages for diagrams, diff reviews, plan reviews, and data tables",
   "keywords": [
     "claude-code-plugin",

plugins/visual-explainer/SKILL.md

@@ -99,6 +99,8 @@ Vary the choice each time. If the last diagram was dark and technical, make the
 
 **Mermaid containers:** Always center Mermaid diagrams with `display: flex; justify-content: center;`. Add zoom controls (+/−/reset/expand) to every `.mermaid-wrap` container. Include the click-to-expand JavaScript so clicking the diagram (or the ⛶ button) opens it full-size in a new tab.
 
+**⚠️ Never use bare `<pre class="mermaid">`.** It renders but has no zoom/pan controls — diagrams become tiny and unusable. Always use the full `diagram-shell` pattern from `templates/mermaid-flowchart.html`: the HTML structure (`.diagram-shell` > `.mermaid-wrap` > `.zoom-controls` + `.mermaid-viewport` > `.mermaid-canvas`), the CSS, and the ~200-line JS module for zoom/pan/fit. Copy it wholesale.
+
 **Mermaid scaling:** Diagrams with 10+ nodes render too small by default. For 10-12 nodes, increase `fontSize` in themeVariables to 18-20px and set `INITIAL_ZOOM` to 1.5-1.6. For 15+ elements, don't try to scale — use the hybrid pattern instead (simple Mermaid overview + CSS Grid cards). See "Architecture / System Diagrams" below.
 
 **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".