Visual Explainer

Produce an editable MDX/TSX source, export it to self-contained HTML, and verify the result. Use HTML instead of ASCII for substantial diagrams and tables.

Resolve the runtime

Set REPO to the Artifacture checkout before authoring:

1. If ../../visual-explainer-mdx/components.tsx exists relative to this file, use the repository two directories above this file.
2. Otherwise, use ~/.artifacture when it contains visual-explainer-mdx/components.tsx and package.json.
3. If neither exists, clone https://github.com/theclaymethod/artifacture to ~/.artifacture and run npm install --prefix ~/.artifacture, then resume. Require Node 22 or newer. Do not update an existing runtime as a side effect of generation.

Run every npm run ve:* command from REPO. Sources may live elsewhere; pass absolute paths.

Execute the flow

1. Select one route below and read its card. Covered flows need this file and that card only until a conditional pointer fires.
2. Author .mdx by default. Use .tsx only for local state, generated/custom SVG, or video. Import shared components from REPO/visual-explainer-mdx/components.tsx as the card shows.
3. Export with npm --prefix REPO run ve:export -- <abs-source> --out <abs-output>. For static video, use npm --prefix REPO run ve:export-static -- <abs-source.tsx> --out <abs-output>. Fix strict-export failures in the source.
4. Read [verification.md](references/verification.md), execute its routed checks, open the artifact, and report the source, HTML, report JSON, and any incomplete verification.

Completion requires an editable source, a successful export, and evidence for every required verification pass. Apply feedback to the source and re-export.

Route

For point-and-click annotation, read [annotate.md](commands/annotate.md). If the request lacks a material choice that cannot be inferred, read [clarify.md](references/clarify.md). For a component API not shown by the selected card, read [mdx-components.md](references/mdx-components.md). For poster, video, brand-heavy, or bespoke HTML work, read [legacy-html.md](references/legacy-html.md) and only the branch it selects.

Shared contracts

• Keep MDX/TSX as the source of truth; generated HTML is disposable output.
• Prefer shared components, semantic content, and tokens over hand-authored coordinates or page CSS.
• Use DiagramCanvas for ordinary diagrams. Use Mermaid only when automatic graph layout is materially better and the result retains zoom, pan, reset, and expand controls.
• Treat facts, labels, and visual encodings as claims. Keep them traceable to the user brief or inspected sources; mark uncertainty instead of inventing rationale.
• Preserve accessibility, responsive containment, and reduced-motion behavior.

Use [delegated-skills.md](references/delegated-skills.md) only when its delegated visual/prose checks are available. Use [model-routing.md](references/model-routing.md) only when dispatching visual-review passes. The main thread orchestrates those passes and consumes their evidence; a visual-capable reviewer judges screenshots.