visual-explainer

What this skill does

# Visual Explainer

Create self-contained HTML pages that explain complex material faster than a
terminal wall of prose or ASCII tables.

This skill is optimized for mixed audiences by default:
- stakeholder updates
- architecture explainers
- plan and diff walkthroughs
- audits, comparisons, and status reviews
- customer, IT, or security reassurance docs

If the user explicitly asks for a deeper technical explainer, include more code
and implementation detail. Otherwise, keep the page accessible and
presentation-ready.

## Prerequisites

- Local HTML generation needs no extra setup.
- Publish mode is opt-in and requires environment variables, not hardcoded
  secrets.
- The publish helper reads secrets from the current runtime environment. It does
  not read `~/.zshrc` or other shell startup files directly.
- Store only env-var names in `~/.config/visual-explainer/global.json`.
- Create `~/.agent/diagrams/` and `~/.config/visual-explainer/` if they are
  missing.
- When publish mode is requested, read:
  - `references/netlify-publishing.md`
  - `references/config-layout.md`
  - `references/error-handling.md`

## Core Rules

1. Default to HTML, not ASCII art
   - If you are about to produce a table with 4+ rows or 3+ columns, generate an
     HTML page instead.
   - Prefer real diagrams, structured cards, or semantic tables over dense text.

2. Validate before explaining
   - Read the actual source material first.
   - Validate the current state before making claims.
   - Separate what is confirmed, what is inferred, and what still needs
     verification.

3. Ask only for missing required inputs
   - Required inputs are:
     - topic
     - audience
     - goal
     - source material
   - Infer them from the request and local context when safe.
   - If anything required is still missing, ask one concise follow-up covering
     only the missing items.

4. Keep the tone audience-correct
   - Default: plain language, smart-but-busy audience, low jargon.
   - Do not sound like an engineering memo unless the user asks for that.
   - Avoid file paths, code references, and test commands in stakeholder mode.
   - Use direct current-state wording only when the evidence supports it.

5. Keep secrets out of repo content
   - Never store literal Netlify tokens in repo files, prompt files, receipts,
     or committed JSON.
   - Resolve real secret values from environment variables at runtime only.
   - Config files may store env-var names such as
     `NETLIFY_VISUAL_EXPLAINER_TOKEN`, never the token itself.

6. Deliver a shareable artifact
   - Always write the final HTML to `~/.agent/diagrams/` with a descriptive
     filename.
   - Attempt to open the local HTML in the browser.
   - Tell the user the local file path.
   - If useful or explicitly requested, also write a Markdown summary to
     `~/Downloads/`.
   - If publish mode is explicitly requested, publish the local HTML after it is
     written and return the deploy URL as well.

7. Keep publish mode explicit
   - Publish only when the user explicitly asks to publish or the wrapper passes
     `--publish`.
   - Use a fresh Netlify preview site for every publish. Do not reuse sites.
   - Verify the required `NETLIFY_VISUAL_EXPLAINER_*` variables are available in
     the current process before running the publish helper.
   - If the user just added or changed shell exports, tell them to restart
     the current tool session or retry from a shell session that actually
     inherited those exports.
   - If publishing fails, preserve the local HTML and report the actionable
     error.

## Intake Protocol

Follow this order:

1. Read the request and any provided files, notes, plans, or diffs.
2. Resolve the minimum viable brief:
   - topic
   - audience
   - goal
   - source material
3. Collect optional preferences only when they materially affect output:
   - non-technical vs technical
   - include Markdown summary
   - include reply draft
   - slide deck instead of scrollable page
   - publish the explainer
   - open the deployed URL after publish
4. If source material is referenced but not yet read, read it before making
   structural decisions.

## Verification Model

Before writing HTML, build a compact fact sheet for yourself:
- confirmed facts
- reasonable inferences
- items still needing external verification

Use that split in the page whenever it helps the reader trust the document.

If the request depends on unstable external facts and browsing is available,
verify them before presenting them as current.

## Page Structure

For the default stakeholder explainer flow, read:
- `references/stakeholder-explainer.md`

For layout, styling, and reusable UI patterns, read:
- `references/css-patterns.md`
- `references/libraries.md`
- `references/responsive-nav.md` for pages with 4+ sections

If publish mode is requested, also read:
- `references/netlify-publishing.md`
- `references/config-layout.md`
- `references/error-handling.md`

For reference templates, read only the relevant files:
- text-heavy architecture overviews:
  `templates/architecture.html`
- flowcharts, sequences, ER diagrams, state machines, mind maps:
  `templates/mermaid-flowchart.html`
- audits, comparisons, and structured tables:
  `templates/data-table.html`
- slide decks only when the user explicitly wants slides:
  `references/slide-patterns.md`
  `templates/slide-deck.html`

## Visual Taste

Apply these constraints consistently:

- Avoid generic AI styling.
- Do not default to Inter plus purple/indigo accents.
- Use a distinct palette and intentional typography.
- Prefer side-by-side comparison cards when "before vs after" matters.
- Use Mermaid when topology or flow matters more than rich card text.
- Use real HTML tables for audits and comparisons.
- Make the page easy to skim in under two minutes unless the user asks for a
  deeper technical artifact.

## Default Deliverable

Unless the user asks for a different structure, the HTML should usually include:

1. Short headline summary
2. Confirmed vs inferred vs still-unverified view
3. Before vs after explanation when relevant
4. How it works
5. Why this approach is better
6. What is already done
7. What is left
8. Key caveats or risks
9. Recommended next step
10. Reply draft when the audience is customer, IT, security, or leadership

Use 2-5 concrete examples where they improve clarity.

## Publish Mode

Publish mode is opt-in.

Use it only when:
- the user explicitly asks for a hosted preview
- the wrapper includes `--publish`

When publish mode is enabled:
- always write the local HTML first
- ensure `~/.config/visual-explainer/` exists
- bootstrap `global.json` with env-var names only if it does not exist yet
- verify the required environment variables are visible to the current runtime
  before invoking the helper script
- run `scripts/publish_netlify_preview.py` against the generated HTML
- pass `--open-url` only when the user asked to open the deploy URL
- return:
  - local HTML path
  - deploy URL
  - publish receipt path
  - any important unverified points

When publish mode is disabled:
- local HTML delivery remains the default
- manual Netlify Drop remains an optional suggestion only

## Slide Deck Mode

Slides are opt-in only.

Use slide mode only when:
- the user explicitly asks for slides
- a command wrapper explicitly requests slides

When slide mode is requested:
- read `references/slide-patterns.md`
- read `templates/slide-deck.html`
- preserve the same factual coverage, not a watered-down summary

## Final Step

After delivery:

- if publish mode was used, report the deploy URL and receipt path
- if publish mode was not used and sharing would help, you may suggest Netlify
  Drop as a manual option

Do not imply that Netlify Drop itself is password-protected by default, and do
not suggest it as though it replaced automated publish mode.

## References

- `references/stakeholder-explainer.md`
  - default mixed-audience workflow, content shape, and tone
- `refere