Doc Visual

doc-visual

Read a markdown document and write a visual report with diagrams that match each section's meaning. Output is HTML (default) or markdown. You write the output directly — no templates, no intermediate JSON, no agent chains.

Why this matters

A pipeline of agents that each see only the previous stage's output compresses the content into summaries of summaries. You see the original document in full — that's the core advantage. If you find yourself writing "this section discusses X" instead of explaining X, that's compression, and it's the failure this skill exists to prevent.

Input

Argument = single markdown file path. Directories, URLs, stdin not supported.

1. Validate file exists + markdown extension (.md, .markdown, .txt)
2. Missing/no permission → abort immediately
3. Read the full file content

Format detection

The report language must match the source document's language.

Channel, flags, and config follow ${CLAUDE_PLUGIN_ROOT}/references/design-system/channel-decision.md — read it before writing. In short: capable HTML publishes to a claude.ai Artifact; --local (or "keep it local", "don't publish") forces the local file; md stays local unless this turn asks to publish it. Stored config: node ${CLAUDE_PLUGIN_ROOT}/scripts/config.js get --data-dir "${CLAUDE_PLUGIN_DATA}".

Writing the report

You write the output yourself. No template files, no assembly scripts, no intermediate formats.

Output paths

All under ${CLAUDE_PLUGIN_DATA}/reports/:

The HTML is one file you write yourself; on the local channel it embeds diagrams as <pre class="mermaid"> blocks. The md report uses ```mermaid fences, footer links to the source path, and no CSS or <script>. The saved md copy lets report-manager list and refine it later.

Modes

Decide which mode fits the source document:

If the document mixes both (e.g., a spec with a narrative intro), use structural as the base and apply explainer treatment to narrative sections.

Section-to-diagram mapping

For each section in the source document, decide whether a diagram adds value. Not every section needs one — if a table or list says it better, use that.

Read ${CLAUDE_PLUGIN_ROOT}/references/design-system/diagram-type-selection.md to choose the right type from the 13-type menu. The mapping priority section tells you which keywords suggest which types.

When no diagram fits, skip it. A section with good prose and no diagram beats a section with a forced diagram.

Component menu

These are the building blocks. Mix them as the content demands:

Content integrity — the cardinal rule

The source document's substance must survive intact in the report. This means:

• Specific numbers, names, dates from the source → appear in the report
• Technical details (configs, commands, parameters) → preserved verbatim
• Reasoning and nuance → kept, not flattened to bullet points
• Code examples → reproduced in full

If you're writing "this section covers X" or "the document describes Y" — stop. That's a summary of the content, not the content. Include the actual content.

This cardinal rule is summary-leak, one of the reflexes in ${CLAUDE_PLUGIN_ROOT}/references/design-system/anti-slop-tells.md that pass every gate and still flatten the output — read it while shaping the content.

Short documents (<500 chars) get 1 section + 1 hero diagram. Long documents get proper sectioning but still preserve all substance.

Validate and deliver

Artifact channel (HTML default):

1. node ${CLAUDE_PLUGIN_ROOT}/scripts/artifact-gate.js <output-path> --content-only — fix and re-run, max 2 retries.
2. Publish the file with the Artifact tool, description = one sentence on what the page is.
3. node ${CLAUDE_PLUGIN_ROOT}/scripts/write-artifact-sidecar.js --report <output-path> --url <artifact-url> --title <title>
4. Reply with the URL and the publish notice (channel-decision.md "Artifact channel").

Local channel (--local / non-capable fallback):

1. node ${CLAUDE_PLUGIN_ROOT}/scripts/artifact-gate.js <output-path>
2. node ${CLAUDE_PLUGIN_ROOT}/scripts/render-report.js <output-path> --data-dir "${CLAUDE_PLUGIN_DATA}", then read the PNG and check density, hierarchy, Mermaid integrity, and overflow (visual-self-audit.md).
3. open <output-path>

md: deliver in the response body. On a publish request, publish the .artifact.md with steps 2–3 above and no gate — see "Markdown on request" in channel-decision.md.

Publish unavailable or failed: HTML → regenerate as the local report at its local path, don't open the Artifact file; md → deliver in the chat body. Say so in one line, don't ask.

Error handling

Reference files

Read these during report generation (not upfront — read the relevant one when you need it):