| name | vc:preview |
| description | Use when you need to inspect files or generate visual explanations, slides, diagrams, or HTML recaps. |
| argument-hint | [path] OR [--html] --explain|--slides|--diagram|--ascii [topic] OR --html --diff|--plan-review|--recap |
| metadata | {"author":"claudekit","version":"1.1.0"} |
Preview
Universal viewer + visual generator. View existing content OR generate new visual explanations.
Diagram Boundary
Use preview as the companion and review surface.
- Use
preview --diagram or preview --html --diagram for explanation-first visuals, Mermaid-oriented flows, and review-friendly diagram pages.
- Use
tech-graph first when the task needs a durable publish-grade SVG or PNG artifact under process/general-plans/references/, process/general-plans/reports/visuals/, or the matching feature-scoped equivalents.
- After
tech-graph generation, preview is still the right place for explanation, comparison, HTML framing, or self-review of the generated artifact.
Default (No Arguments)
If invoked without arguments, use AskUserQuestion to present available preview operations:
| Operation | Description |
|---|
(view) | View a file or directory |
--explain | Generate visual explanation |
--slides | Generate presentation slides |
--diagram | Generate architecture diagram |
--ascii | Terminal-friendly diagram |
--stop | Stop preview server |
--html --explain | Self-contained HTML explanation (opens in browser) |
--html --diagram | Self-contained HTML diagram with zoom controls |
--html --slides | Magazine-quality HTML slide deck |
--html --diff | Visual diff review (HTML) |
--html --plan-review | Plan vs codebase comparison (HTML) |
--html --recap | Project context snapshot (HTML) |
Present as options via AskUserQuestion with header "Preview Operation", question "What would you like to do?".
Usage
View Mode
/vc:preview <file.md> - View markdown file in novel-reader UI/vc:preview <directory/> - Browse directory contents/vc:preview --stop - Stop running server
Generation Mode (Markdown)
/vc:preview --explain <topic> - Generate visual explanation (ASCII + Mermaid + prose)/vc:preview --slides <topic> - Generate presentation slides (one concept per slide)/vc:preview --diagram <topic> - Generate focused diagram (ASCII + Mermaid)/vc:preview --ascii <topic> - Generate ASCII-only diagram (terminal-friendly)
Generation Mode (HTML)
/vc:preview --html --explain <topic> - Self-contained HTML explanation/vc:preview --html --slides <topic> - Magazine-quality HTML slide deck/vc:preview --html --diagram <topic> - HTML diagram with zoom controls/vc:preview --html --diff [ref] - Visual diff review/vc:preview --html --plan-review [plan-file] - Plan vs codebase comparison/vc:preview --html --recap [timeframe] - Project context snapshot
Argument Resolution
When processing arguments, follow this priority order:
--stop → Stop server (exit)--html flag present → Set HTML output mode flag (continues to next step)- Generation flags (
--explain, --slides, --diagram, --ascii) → Generation mode. Load references/generation-modes.md
- HTML-only flags (
--diff, --plan-review, --recap) → Auto-set HTML mode, then generation mode. Load references/generation-modes.md
- Resolve path from argument:
- If argument is an explicit path → use directly
- If argument is a contextual reference → resolve from recent conversation context
- Resolved path exists on filesystem → View mode. Load
references/view-mode.md
- Path doesn't exist or can't resolve → Ask user to clarify
Topic-to-slug conversion:
- Lowercase the topic
- Replace spaces/special chars with hyphens
- Remove non-alphanumeric except hyphens
- Collapse multiple hyphens → single hyphen
- Trim leading/trailing hyphens
- Max 80 chars - truncate at word boundary if longer
Multiple flags: If multiple generation flags provided, use first one; remaining treated as topic.
Placeholder {topic}: Replaced with original user input in title case (not the slug).
Error Handling
| Error | Action |
|---|
| Invalid topic (empty) | Ask user to provide a topic |
| Flag without topic | Ask user: "Please provide a topic: /vc:preview --explain <topic>" |
| Topic becomes empty after sanitization | Ask for topic with alphanumeric characters |
| File write failure | Report error, suggest checking disk space and permissions |
| Server startup failure | Check if port in use, try /vc:preview --stop first |
| No generation flag + unresolvable reference | Ask user to clarify which file they meant |
| Existing file at output path | Overwrite with new content (no prompt) |
| Server already running | Reuse existing server instance, just open new URL |
| Parent output directory missing | Create directories recursively before write |
--diff without git context | Explain: "No git repo detected. Run inside a git repository." |
--plan-review without plan file or active plan | Explain: "Provide a plan file path or run from a session with an active plan." |
--recap without git history | Explain: "No git history found. Run inside a git repository with commits." |
--html --ascii combination | Not supported — --ascii is terminal-only by design. Suggest --html --diagram instead |
--diff with PR number but gh unavailable | Explain: "GitHub CLI (gh) is required for PR diffs. Install from https://cli.github.com/" |
HTML Output Mode (--html)
Adding --html to any generation flag switches output from Markdown to a self-contained HTML file.
Output: Single .html file with all CSS/JS inline. Opens directly in browser — no server needed.
Location: If an explicit plan file path is provided, write to its sibling visuals/ directory. Otherwise write to process/general-plans/reports/visuals/ or the current feature's process/features/{feature}/reports/visuals/ when feature scope is explicit.
Browser open: open (macOS) / xdg-open (Linux) / start (Windows)
MANDATORY — Theme Toggle: Every HTML page MUST include a light/dark theme toggle button. See html-css-patterns.md → "Theme Toggle Button" for the exact CSS, HTML, and JS to include. Pages without the toggle are considered incomplete.
Reference Loading (HTML mode)
Before generating, agent MUST read these references:
| Mode | Always read | Mode-specific |
|---|
| All HTML modes | html-design-guidelines.md | — |
--explain | html-css-patterns.md, html-libraries.md | Template: architecture.html |
--diagram | html-css-patterns.md, html-libraries.md | Template: mermaid-flowchart.html or architecture.html |
--slides | html-slide-patterns.md, html-css-patterns.md, html-libraries.md | Template: slide-deck.html |
--diff | html-css-patterns.md, html-libraries.md | Templates: data-table.html, architecture.html |
--plan-review | html-css-patterns.md, html-libraries.md | Templates: architecture.html, data-table.html |
--recap | html-css-patterns.md, html-libraries.md | Templates: architecture.html, data-table.html |
Multi-section pages (--explain, --diff, --plan-review, --recap): also read html-responsive-nav.md.
HTML-Only Modes
--diff [ref] (implies --html)
Visual diff review. Scope detection: branch name, commit hash, HEAD, PR number, commit range, default=main.
Data: git diff --stat, --name-status, changed files, new API surface, CHANGELOG.
Output: executive summary, KPI dashboard, module architecture (Mermaid), feature comparisons (side-by-side), flow diagrams, file map, test coverage, code review cards (Good/Bad/Ugly/Questions), decision log, re-entry context.
--plan-review [plan-file] (implies --html)
Plan vs codebase comparison. Input: explicit plan file path by default. Only fall back to active-plan context when exactly one active plan artifact is unambiguous.
Data: read plan, read all referenced files, map blast radius, cross-reference assumptions.
Output: plan summary, impact dashboard, current vs planned architecture (paired Mermaid), change breakdown (side-by-side), dependency analysis, risk assessment, review cards, understanding gaps.
Visual language: blue=current, green=planned, amber=concern, red=gap.
--recap [timeframe] (implies --html)
Project context snapshot. Time window: shorthand (2w, 30d, 3m) or default 2w.
Data: project identity, git log, git status, decision context, architecture scan.
Output: project identity, architecture snapshot (Mermaid), recent activity, decision log, state KPI cards, mental model essentials, cognitive debt hotspots, next steps.
Style Strategy
- Default: static anti-slop rules from
html-design-guidelines.md (6 curated presets)
- For
--slides: consider invoking the frontend-design skill for richer style selection
- Agent must vary aesthetics between consecutive HTML outputs (different font pair, palette)
