Skip to main content

​
Visual Explainer — Livepeer docs-v2 Implementation Guide

What this is: A practical guide to implementing nicobailon/visual-explainer as a developer/maintainer tooling layer for the livepeer/docs docs-v2 branch. This is not a content authoring tool — it operates alongside the docs, not inside Mintlify.

​
Pilot Scope (Current)

This workflow is currently an optional, maintainer-focused pilot.
  • It is not a required contributor gate.
  • It is not a Mintlify runtime feature.
  • It is not part of CI or GitHub Actions.
  • Generated diagram/review artifacts should remain out-of-repo during the pilot.

​
Understanding the Boundary

Visual-explainer outputs standalone HTML files to ~/.agent/diagrams/. It is a Claude Code skill — it runs in your terminal workflow, not inside Mintlify. This means:
  • It does not replace Mermaid diagrams already rendering correctly in MDX pages
  • It does not write to the repo directly
  • It does produce shareable, linked reference pages and maintainer-tooling outputs
  • It does activate automatically when you ask Claude Code for diagrams, architecture overviews, or plan comparisons
  • It uses Claude Code slash commands (for example /diff-review) and should not be treated as a Mintlify or CI command

​
Installation

# Install into Claude Code skills directory
git clone https://github.com/nicobailon/visual-explainer.git ~/.claude/skills/visual-explainer
That’s it. No restart required. Claude Code reads the SKILL.md on each session.

​
Priority 1: /plan-review on the AI-First Docs Plan

What it does: Cross-references every claim in a plan document against the actual codebase. Produces a current vs. planned architecture diagram and flags risks and gaps. Why it matters here: The livepeeraifirstdocsplan.pdf is a concrete implementation plan with sprint deliverables. Running /plan-review against docs-v2 gives you a machine-verified gap analysis — which items are landed, which are still outstanding, and where the delta lives in the file system. How to run it: 
# From the docs repo root, on the docs-v2 branch
cd ~/path/to/livepeer/docs
git checkout docs-v2

# In Claude Code
/plan-review ~/path/to/livepeeraifirstdocsplan.pdf
What to expect in the output:
  • Every sprint item mapped to a file path in v2/, ai-tools/, or operations/scripts/
  • Items flagged as not yet landed in current docs-v2 coverage (for example quickstart/tutorial gaps, migration docs, accessibility follow-ups)
  • A risk/gap matrix formatted as a visual HTML page you can share directly with stakeholders
Use this output for: Delivery reporting, handover documentation, addressing scope/completion criticism with a verifiable artifact rather than prose claims.

​
Priority 2: /diff-review on docs-v2 PRs

What it does: Generates a full visual review page for any git diff — before/after architecture diagrams, KPI dashboard, structured code review (Good/Bad/Ugly), and a decision log with confidence indicators. Why it matters here: The docs-v2 branch has deep history and broad surface area. PRs touching docs.json (navigation structure), snippets/components/ (component system), or .github/workflows/ (CI) are structurally complex and hard to reason about in GitHub’s flat diff view. How to run it: 
# Default: feature branch vs main
/diff-review

# Specific commit
/diff-review abc123

# Committed changes only (excludes staged/unstaged)
/diff-review main..HEAD

# Pull request by number
/diff-review #42
The highest-value PR types to run this on:
PR TypeWhy Visual Review Helps
docs.json changesNavigation structure changes are invisible in text diff; architecture diagram makes them obvious
snippets/components/ additionsComponent graph changes affect every page that imports them
.github/workflows/ changesCI dependency changes need a flow diagram, not line-by-line YAML review
Large v2/ restructuresSection moves affect redirect chains and cross-links non-obviously
How to integrate into workflow (pilot): Keep this optional and maintainer-led first. For now, use it before opening or reviewing structural PRs and gather evidence on review quality.

​
Priority 3: Architecture Diagrams for Commented-Out Mermaid

What it does: Generates a full-page, zoom/pan-enabled, dark/light themed diagram using ELK layout — significantly more capable than Mintlify’s inline Mermaid renderer. Why it matters here: Two substantial architecture diagrams are commented out in the existing MDX files, almost certainly because they were too complex to render cleanly in-page:
  • v2/gateways/resources/technical/technical-architecture.mdx — Marketplace Interaction Model (commented out)
  • v2/gateways/resources/technical/technical-architecture.mdx — BYOC Container Architecture (commented out)
These are exactly the diagrams that orchestrator and gateway operator audiences need most. How to rescue them: 
# Option A: Ask Claude Code to generate from the commented Mermaid source
# Open the file, then:
> generate a web diagram for the BYOC container architecture from this file

# Option B: Describe the architecture directly
> draw a diagram of the BYOC container runtime flow: developer container → 
  compliant runtime spec → gateway intake → capability validation → 
  orchestrator container runner → GPU execution
Where to link the output: The generated HTML files live at ~/.agent/diagrams/. Host them or link to them from the relevant reference pages. In the MDX, replace the commented-out Mermaid block with: 
<Note>
  View the interactive [BYOC Architecture Diagram](/path/to/hosted/diagram.html) 
  for a zoomable, full-page version of this flow.
</Note>
Or embed as an iframe if Mintlify supports it in your configuration.

​
Priority 4: /fact-check on Delivery Reports

What it does: Takes any document that makes claims about code and verifies every claim against the actual codebase. Produces a verification log as a visual HTML page. Why it matters here: The RFP delivery report and retrospective make specific claims about what was built — script/test coverage, component library work, GitHub Actions workflows, CLI tools, AI-first tooling. /fact-check produces a machine-verified evidence log. How to run it: 
# Verify the RFP delivery report
/fact-check ~/path/to/Livepeer_Docs_v2_RFP_Delivery_Report_with_Sections.docx

# Verify the retrospective
/fact-check ~/path/to/livepeer_docs_v_2_retrospective.md
What it checks against the repo:
  • Every script claimed → existence in operations/scripts/
  • Every workflow claimed → existence in .github/workflows/
  • Every component claimed → existence in snippets/components/
  • Every page structure claimed → existence in v2/
Use this output for: A timestamped, verifiable evidence artifact that can accompany delivery documentation. Share the HTML file directly with stakeholders as a supplement to the written report.

​
Priority 5: /project-recap for Contributor Onboarding

What it does: Scans recent git activity and produces an architecture snapshot, decision log, and cognitive debt hotspots — a mental model of the current project state. Why it matters here: The repo has multiple maintainers/contributors and docs-guide/ as the canonical navigation source of truth. /project-recap produces a single visual page that helps reduce orientation time. How to run it: 
# From the docs repo root
cd ~/path/to/livepeer/docs
/project-recap
What the output will surface:
  • Which areas of the repo have the most recent churn (for example v2/developers/ and adjacent docs sections)
  • The test suite structure across tests/ and .github/workflows/
  • The automation pipeline map
  • Cognitive debt hotspots — files with high change frequency and high complexity
How to integrate: Add a reference to docs-guide/contributing/contributing.mdx: 
## Getting Oriented Quickly

If you're new to the repo or returning after time away, run:

```bash
/project-recap
This generates a visual architecture snapshot of the current project state, including recent decisions and areas of active change. 

Regenerate before major handovers or when onboarding new maintainers.

---

## Priority 6: Persona Routing Matrix Table

**What it does:** Visual-explainer's HTML table renderer with KPI badges produces significantly more scannable comparison tables than MDX table syntax.

**The specific table worth generating:** A persona-to-entrypoint routing matrix — the implicit routing logic that lives in `docs.json` and the persona portal pages, surfaced as a single visual reference.

**Ask Claude Code:**

```bash
> generate a data table showing Livepeer documentation persona routing:
  columns: User Type | Primary Question | Entry Point Page | Zero-to-Hero Path | Key Reference
  rows: Developer (AI Jobs), Developer (Transcoding), Gateway Operator, 
        Orchestrator, Delegator, Community Contributor
Where to use it (pilot): Use internally first in docs-guide/frameworks/content-system.mdx and maintainer handoff docs. Delay homepage “Mission Control” placement until pilot usefulness is validated.

​
What NOT to Use Visual Explainer For

ContextWhy to Skip It
MDX content pages (end-user docs)Not Mintlify-native; breaks inline reading experience; Mermaid already renders for these
ai-tools/ directory (llms.txt, docs-index.json, JSON-LD)Machine-readable formats; visual-explainer produces human-readable HTML — no overlap
Test suite outputlpd CLI and GitHub Actions CI already provide structured output in the right channels
Automated CI pipelineVisual-explainer is interactive/agent-driven, not a headless script runner

​
4-Week Pilot Rollout

​
Week 1: Baseline

  • Keep this guide aligned with current repo paths (v2/**, not v2/pages/**).
  • Keep contributor-facing messaging optional.
  • Track pilot scope in docs-guide contributor docs, not as a required contribution gate.

​
Weeks 1-2: Operational Pilot

  • Run /diff-review on at least five structural PRs touching one or more of:
    • docs.json
    • snippets/components/**
    • .github/workflows/**
  • Run /plan-review once against the AI-first plan.
  • Use artifact naming:
    • YYYY-MM-DD_diff-review_<ref>.html
    • YYYY-MM-DD_plan-review_ai-first-plan.html

​
Week 2: Diagram Rescue Pilot

  • Generate diagram artifacts for the two commented Mermaid diagrams in:
    • v2/gateways/resources/technical/technical-architecture.mdx
  • Keep links internal during the pilot (do not publish into user-facing pages yet).

​
Weeks 3-4: Evidence and Onboarding

  • Run /fact-check on delivery and retrospective documents.
  • Run /project-recap for onboarding/handoff context.
  • Generate a persona-routing matrix as an internal artifact only.

​
End of Week 4: Decision Gate

Promote to contributor-facing recommendation only if all are true:
  • Pilot runs are repeatable by multiple maintainers.
  • Artifact quality is consistently useful.
  • No path drift or command confusion was observed.
If these conditions are not met, keep this workflow internal to maintainers.

​
Operator Runbook (Planning Only)

Use this checklist after the relocation is complete. Do not execute these commands as part of this migration change.
  1. /diff-review: run for structural PRs (docs.json, snippets/components/**, .github/workflows/**) and capture one artifact per review.
  2. /plan-review: run once against the AI-first plan document and save a single gap-analysis artifact.
  3. /fact-check: run on delivery/retrospective docs before stakeholder circulation.
  4. /project-recap: run once per onboarding/handoff cycle to generate orientation context.
Outputs should remain out-of-repo and follow the naming convention in this guide.

​
Quick Reference: Commands

CommandBest Use in This Repo
/plan-review <file>Gap analysis of AI-first docs plan vs. actual delivered state
/diff-reviewPR review for structural changes (docs.json, components, workflows)
/generate-web-diagramRescue commented-out architecture diagrams; generate new ones on demand
/project-recapContributor onboarding and maintainer context-switching
/fact-check <file>Verify delivery report claims against codebase before stakeholder communication

​
Files to Know in docs-v2

FileRelevance to Visual Explainer Use
docs.jsonNavigation structure — primary target for /diff-review on nav PRs
v2/gateways/resources/technical/technical-architecture.mdxContains commented-out BYOC and Marketplace diagrams to rescue
v2/gateways/about/architecture.mdxEnglish gateway architecture page with diagrams that may benefit from full-page outputs
operations/scripts/Target for /fact-check script claim verification
.github/workflows/Target for /fact-check workflow claim verification
docs-guide/contributing/contributing.mdxAdd /project-recap and /diff-review recommendations here
docs-guide/features/architecture-map.mdxSource material for /project-recap output context
Last modified on April 7, 2026