P0: first-run path fix, trigger-optimized description, Pages live demo

README.md

@@ -4,6 +4,8 @@ A Claude Code skill that turns hierarchical Markdown into an **interactive SVG m
 
 ![Install the skill, ask Claude to turn an outline into a mind map, and open the interactive result](assets/demo.gif)
 
+**[▶ Live demo](https://jaderson-bit.github.io/mindmap-markmap-viewer/)** — an actual generated map, in your browser: pan, zoom, fold branches, export SVG/PNG. The page is one self-contained HTML file, exactly what the skill produces.
+
 ## Why this exists
 
 markmap renders a Markdown outline as a zoomable mind map, but three things need a layer on top to be genuinely usable:
@@ -42,10 +44,14 @@ cp -r mindmap-markmap-viewer ~/.claude/skills/
 ## Usage
 
 ```python
-import sys; sys.path.insert(0, "scripts")
+import sys
+from pathlib import Path
+
+SKILL = Path.home() / ".claude" / "skills" / "mindmap-markmap-viewer"  # wherever you cloned it
+sys.path.insert(0, str(SKILL / "scripts"))
 from render_markmap import build_html, set_expand_level, filter_markmap
 
-src = open("assets/example.md", encoding="utf-8").read()
+src = (SKILL / "assets" / "example.md").read_text(encoding="utf-8")   # or your own outline
 # optional: src, n = filter_markmap(src, "branch b")   # search + keep context
 # optional: src = set_expand_level(src, -1)             # expand all
 open("mindmap.html", "w", encoding="utf-8").write(build_html(src, height=850))
@@ -54,7 +60,7 @@ open("mindmap.html", "w", encoding="utf-8").write(build_html(src, height=850))
 Inside Streamlit:
 
 ```python
-import sys; sys.path.insert(0, "scripts")
+sys.path.insert(0, str(SKILL / "scripts"))             # SKILL as above
 from render_markmap import render_markmap, set_expand_level
 render_markmap(set_expand_level(src, 2), height=850)
 ```

SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mindmap-markmap-viewer
-description: Generate and render interactive mind maps from hierarchical Markdown using markmap.js (white font, search that filters the tree to matches + ancestors + descendants, expand-by-level control). Use when the user wants to turn outline/hierarchical content into a navigable mind map, or asks for a "markmap"/"mindmap" view, optionally embedded in Streamlit.
+description: Turn Markdown outlines, notes, docs, or plans into an interactive mind map — a single self-contained HTML file that opens offline anywhere (markmap.js, white-on-dark, zoom/expand/export toolbar, search that keeps matches in context). Use whenever the user asks for a mind map, markmap, or concept map, wants to visualize or diagram the structure of a document or topic, summarize notes as a navigable tree, make an outline clickable or explorable, or embed such a map in Streamlit — even when they don't literally say 'mind map'.
 ---
 
 # Mindmap (markmap) Skill
@@ -14,6 +14,14 @@ source.md  ──►  filter / set expand level (Python)  ──►  build_html(
 
 Helper functions live in `scripts/render_markmap.py`; a minimal source file is in `assets/example.md`; regression tests are in `evals/`. Deeper docs: [`references/internals.md`](references/internals.md) (how the helpers work) and [`references/lessons.md`](references/lessons.md) (real-world lessons + the adversarial counter-review behind the current code).
 
+## When to use this skill
+
+- The user asks for a mind map, markmap, or concept map of anything.
+- Hierarchical content — an outline, notes, a plan, a document's structure, a taxonomy — should become navigable, scannable, or shareable.
+- A map must be sent to someone or opened with no setup: the output is one self-contained `.html` that works offline.
+- A mind map should be embedded in a Streamlit app.
+- An existing markmap renders blank, white-on-white, or truncated — this skill carries the known fixes (§2).
+
 ---
 
 ## 1. Source format
@@ -93,15 +101,24 @@ When there is a query, keep only nodes that **match** + their **path to the root
 
 ## 5. Minimal usage
 
-The helpers live in `scripts/`, so put that directory on the import path first (point it at this skill's `scripts/` folder).
+The helpers live in this skill's `scripts/` directory — and the working directory is
+normally the **user's project, not this folder**, so a bare `"scripts"` on `sys.path`
+won't resolve. Build paths from the skill's base directory (the path announced when
+this skill loaded):
 
-Single self-contained file (recommended) — writes the `.md` source of truth and a
-fully **inlined** `.html` that opens offline anywhere, with no sibling `vendor/`:
 ```python
-import sys; sys.path.insert(0, "scripts")
+import sys
+from pathlib import Path
+
+SKILL_DIR = Path(r"<this skill's base directory>")   # announced when the skill loaded
+sys.path.insert(0, str(SKILL_DIR / "scripts"))
 from render_markmap import write_mindmap, apply_presets, set_expand_level, filter_markmap
+```
 
-src = open("assets/example.md", encoding="utf-8").read()
+Single self-contained file (recommended) — writes the `.md` source of truth and a
+fully **inlined** `.html` that opens offline anywhere, with no sibling `vendor/`:
+```python
+src = Path("outline.md").read_text(encoding="utf-8")  # the user's outline (sample: SKILL_DIR / "assets/example.md")
 src = apply_presets(src)                       # fill default markmap options (no override)
 # optional: src, n = filter_markmap(src, "branch b")   # search + keep context
 # optional: src = set_expand_level(src, -1)             # expand all
@@ -118,7 +135,7 @@ open("mindmap.html", "w", encoding="utf-8").write(build_html(src, height=850))
 
 Inside Streamlit:
 ```python
-import sys; sys.path.insert(0, "scripts")
+sys.path.insert(0, str(SKILL_DIR / "scripts"))       # SKILL_DIR as in the setup above
 from render_markmap import render_markmap, set_expand_level
 render_markmap(set_expand_level(src, level), height=850)
 ```

docs/demo.md

@@ -0,0 +1,57 @@
+---
+markmap:
+  colorFreezeLevel: 2
+  initialExpandLevel: 2
+  maxWidth: 380
+---
+
+# mindmap-markmap-viewer
+
+## What it is
+
+- Markdown outline
+  - becomes an interactive mind map
+- One self-contained HTML file
+  - opens offline anywhere
+  - no CDN, no sibling files
+- Built on markmap.js
+  - vendored, pinned versions
+
+## Toolbar
+
+- Zoom in / out
+- Fit to window
+- Expand all / collapse all
+- Export
+  - SVG (vector)
+  - PNG (2x raster)
+
+## Search in context
+
+- Keeps the match
+- Plus ancestors
+  - the path that explains where it lives
+- Plus descendants
+  - the whole matched subtree
+- Accent-insensitive
+
+## Authoring rules
+
+- 5-8 branches off the root
+- 3-6 children per branch
+- Labels of 1-3 words
+  - details go on child nodes
+- apply_presets
+  - fills the frontmatter for you
+
+## Try it here
+
+- Drag to pan, scroll to zoom
+- Click a circle to fold a branch
+- Toolbar is bottom-right
+
+## Get it
+
+- github.com/Jaderson-bit/mindmap-markmap-viewer
+- Ask Claude Code
+  - "Install this skill from the repo URL"