Livepeer Documentation v2 is Live
Hello to the Livepeer community.
The v2 documentation overhaul is live at docs.livepeer.org, against the brief in Documentation Restructure RFP. Multilingual translations are in pipeline.
This post covers what shipped, the design philosophy that guided it, and the systems that keep it self-maintaining. It is long because the surface is large. Skim the headings.
What v2 actually is
v2 is not a rewrite. It is a documentation operating system.
The previous site was a Mintlify instance with hand-maintained pages. The new site is the same Mintlify instance sitting on top of a governance layer of 366 governed scripts, 49 GitHub Actions workflows, a unified contributor CLI, a generated component library, an AI agent toolchain, and a manifest-driven self-validating governance contract.
The brief asked for stakeholder-focused, AI-first, future-proofed docs. We treated that as three product requirements and built the infrastructure each one needed.
Three principles that drove every decision
1. Documentation is not static. It is infrastructure.
Editorial output degrades. Infrastructure is maintained under load, tested, versioned, and governed. Every script, every hook, every workflow in this repo exists to make the documentation behave like infrastructure rather than like a website that someone has to remember to update.
2. AI is the new search.
For a decade, SEO was the discoverability lever. That is being displaced. Developers begin product research with ChatGPT, Claude, Perplexity, or Gemini. Documentation is now read, evaluated, and cited by machines before it reaches humans.
This shifts what “good docs” means. Semantic headings, stable canonical URLs, machine-readable frontmatter, OpenAPI integration, AEO (Answer Engine Optimization), AI-integrated pipelines, and llms.txt are no longer nice to have. They are the new minimum viable distribution layer.
3. Agents are the new docs consumers.
The next wave is automated systems that query docs to generate code, configure infrastructure, or build integrations. These agents need pages with explicit preconditions, invariants, verification steps, and failure modes. The repo serves agents alongside humans on equal terms.
The page at /v2/gateways/quickstart/AI-prompt is a direct instantiation. It is written for AI agents, not human reading.
These three principles are codified at docs.livepeer.org/v2/internal/overview/docs-philosophy.
The D.O.C.S. System™
The strategic operating model that frames the whole engagement:
Below is what each of those looks like as concrete repo surfaces.
Stakeholder portals: the human-facing surface
Every persona has a zero-to-hero journey. No-one should need Discord intervention to get started.
-
Developers at docs.livepeer.org/v2/developers covering AI Jobs, transcoding, livestream, SDKs, CLI/HTTP reference
-
GPU operators at docs.livepeer.org/v2/orchestrators covering on-chain registration, off-chain discovery, transcoding setup, AI orchestrator setup, payment modes, BYOC, troubleshooting
-
Gateways at docs.livepeer.org/v2/gateways covering deposit flows, ticket broker, marketplace interaction, BYOC architecture, AI Jobs gateway setup
-
Delegators at docs.livepeer.org/v2/delegators covering staking, rewards, fee cuts, reward cuts, active set mechanics
-
Community participants at docs.livepeer.org/v2/community covering contribution paths, ecosystem, showcase
-
Solutions at docs.livepeer.org/v2/solutions covering ecosystem integrations and changelogs
-
Resource Hub at docs.livepeer.org/v2/resources covering canonical references, glossary, troubleshooting
Each portal lands on a frame-mode hero, routes to start-here cards and key-path cards, then opens into structured tutorials, how-tos, references, and explanations following the Diátaxis framework.
Ownerless governance: the design philosophy that makes it sustainable
This is the bit that matters most for sustainability.
Most documentation projects rot because they depend on a standing human owner to interpret failures, route fixes, and approve repairs. The moment that person rotates off, drift starts.
This repo is built so that no governed surface depends on a standing human owner.
Every governed surface in the repo must declare four things:
-
One canonical source. The file or path that defines truth.
-
One deterministic validator. A script that detects drift.
-
One exact repair path. A repo-backed command that any contributor or AI agent can run directly.
-
One primary gate layer. Either pre-commit, PR-changed, scheduled, or manual.
If any of those is missing, the surface is not ownerless-ready and stays advisory.
The contributor loop is then mechanical: change the canonical source, run the validator, read the exact repair output, run the repair command, re-run the validator, merge once green. No private context required. No DM to a maintainer required. Available to OSS contributors and AI agents on equal terms.
The full contract lives at docs.livepeer.org/docs-guide/policies/ownerless-governance. The machine-readable manifest is at operations/governance/config/ownerless-governance-surfaces.json.
Rollout states are advisory, autofix, blocking, or migrating. Promotion to blocking requires a clean baseline run, changed-file PR simulation, and exact repair output for every blocking failure mode.
Infrastructure first principles: the gate-layer model
Five tenets:
-
Single responsibility per layer. Each gate owns one class of risk.
-
Fast local feedback. Pre-commit is local, offline, and bounded under 60 seconds.
-
Governance at branch and CI boundaries. Contract checks run at pre-push and CI.
-
One canonical policy source. Operational docs link, not copy.
-
Measurable SLOs. Runtime budgets are enforced, not aspirational.
Severity is graded P0 (merge/deploy safety), P1 (correctness/governance), P2 (quality drift), P3 (advisory debt).
Every check declares its primary gate layer. Pre-commit owns staged structure and style. Pre-push owns codex contract and issue readiness. PR CI owns blocking changed-file checks. Full sweeps own browser, link, OpenAPI, and WCAG checks.
Contract is at docs.livepeer.org/docs-guide/policies/infrastructure-principles.
The lpd CLI: one command surface for the entire system
Contributors interact with the docs operating system through a single CLI: lpd.
lpd standardises every contributor workflow:
lpd setup # bootstrap dependencies, hooks, optional PATH install, Codex skill sync
lpd doctor # check repo readiness, dependencies, Mint, hook state
lpd dev # local Mint dev server, scoped or full
lpd test # staged or full tests, browser, domain, WCAG, external link audits
lpd ci # local CI-like validation
lpd move-page # governed page move with docs.json sync
lpd ai-sitemap # generate or validate sitemap-ai.xml
lpd hooks # install, status, verify, run .githooks scripts
lpd scripts # list and run any of the 366 governed scripts by group
lpd dev defaults to port 3333. Scoped mode lets you run Mint against a single tab, version, language, or route prefix:
lpd dev --scoped --scope-tab Developers
lpd dev --scoped --scope-prefix v2/orchestrators
lpd dev --scoped --docs-config docs-orch-work.json
Tab matching is fuzzy. Resources resolves to Resource HUB, Orch resolves to Orchestrators, LP resolves to LP Token. Scope inputs are validated before any setup work runs so bad tab names fail immediately.
lpd scripts run exposes the full governed script library by group: tools, tasks, tests, v2, hooks. Risk is graded low for tests, medium for tools and hooks, high for tasks and v2. High-risk groups prompt for confirmation unless --yes is supplied.
Every command supports a JSON envelope for agent and CI consumption: { ok, command, message, exit_code, repo_root }.
Reference at docs.livepeer.org/docs-guide/tooling/lpd-cli.
What the 366 scripts actually do
The catalog at docs.livepeer.org/docs-guide/catalog/scripts-catalog is generated from the JSDoc headers of every script. It groups scripts by type and names every pipeline gate they belong to.
Top-level types:
-
Audits – component usage, copy patterns, glossary gaps, icon usage, media assets, script categories, tasks folders, v2 usefulness, content freshness, page research, terminology coverage
-
Generators – AI sitemap, llms.txt, OG images, SEO, glossary companions, component registry, component docs, UI templates, docs index, repo governance map, root governance artifacts, script registry, snippets registry, AI tools registry artifacts
-
Validators – page imports, page links, anchor usage, MDX safety, frontmatter taxonomy, description quality, double headers, page endings, component docs, component CSS, component health, component immutability, naming conventions, MDX component scope, EN-GB grammar, proper nouns, governance approvals, repo governance sync, root governance sync, codex task contract, codex locks, OpenAPI reference, page rendering, agent docs freshness, AI tools registry coverage
-
Remediators – page imports, page links, MDX-safe markdown, ownerless language, spelling, docs paths, Mintlify canonical consumers, component metadata, asset migration to branch, JSDoc headers, framework headers, page-type assignment, purpose metadata, SEO generation, WCAG common fixes, callout insertion
-
Dispatchers – page integrity dispatch, governance pipeline orchestration, repo audit orchestrator, sync generated files, run-all, run-pr-checks, headless batch executor, session state, cross-agent packager, post-merge sync
-
Library modules – 57 internal shared modules covering MDX parsing, frontmatter, providers, scoring, glossary, journey checking, file walking, generated artifact policy, Mintignore handling, path utilities, repo governance, root governance, scoped docs config resolution
Pipeline phases are explicit. P1 commit gate (49 scripts), P2 push gate (13 scripts), P3 PR gate (45 scripts), P5/P6 scheduled (16 scripts).
Auto-remediation: the repair surface
This is where docs-as-infrastructure stops being a slogan.
When a validator finds drift, it does not just report. It points to a repair command that any contributor or agent can run.
Concrete examples:
-
repair-mdx-safe-markdown.js rewrites deterministic MDX-unsafe patterns
-
repair-page-imports.js removes safe unused page-reachable React runtime imports
-
repair-page-links.js rewrites safe relative internal href literals to canonical root-level routes
-
repair-spelling.js applies cspell-driven safe corrections
-
style-and-language-homogenizer-en-gb.js and the EN-GB grammar checker fix US-to-UK spelling and approved style guide drift
-
repair-ownerless-language.js removes human-owner dependencies from governed surfaces
-
repair-component-metadata.js auto-repairs derived JSDoc metadata fields from repo state
-
sync-docs-paths.js applies governed docs.json and reference rewrites for moved pages
-
sync-mintlify-canonical-consumers.js applies canonical-path rewrites for registered consumers
-
quarantine-manager.js classifies and (with --apply) moves files to safe quarantine paths
-
migrate-assets-to-branch.js migrates flagged assets to docs-v2-assets and rewrites references to raw GitHub URLs
-
wcag-repair-common.js applies conservative WCAG source autofixes for common raw-tag issues
-
governance-pipeline.js chains audit, safe repair, verification, and reporting into a single self-healing pipeline
-
The OpenAPI reference workflow autofixes method case, METHOD/path spacing, and leading slash in non-PR runs
Every remediator is dual-mode: --check to detect, --write to apply. Most are wired into pre-commit or scheduled CI so drift gets corrected automatically where deterministic.
Unresolved findings are tracked through rolling marker issues with idempotent labels (docs-v2, help wanted, status: needs-routing, type: bug, area: ci-cd). Clean runs close the issue with a resolution comment.
Generated artifacts: the parts that maintain themselves
Generated files are rebuilt from source, never hand-edited. They carry an enforced banner, validated by enforce-generated-file-banners.js. Any drift between the canonical source and the derived output is detected and repaired by sync-generated-files.js.
Generated surfaces include:
-
docs-index.json – the route and frontmatter index, the most-called artifact in the repo
-
sitemap-ai.xml – AI-optimised sitemap, generated by generate-ai-sitemap.js, refreshed on schedule
-
llms.txt – AI-first root contract, generated from docs navigation
-
docs-guide/catalog/components-catalog.mdx – the component inventory
-
docs-guide/catalog/scripts-catalog.mdx – the 366-script inventory itself
-
docs-guide/catalog/pages-catalog.mdx – the v2 page inventory
-
docs-guide/catalog/workflows-catalog.mdx – the GitHub Actions inventory
-
docs-guide/catalog/templates-catalog.mdx – the UI template inventory
-
tools/config/registry/script-registry.json – derived from JSDoc across all governed scripts
-
.vscode/templates.code-snippets and .vscode/components.code-snippets – authoring snippets
Generated artefact policy is at docs.livepeer.org/docs-guide/policies/generated-artifact-and-hook-governance.
AI features at three levels
Reader assistants
The Mintlify AI assistant is built into docs.livepeer.org. It uses agentic RAG with tool-calling against the published docs. Conversation analytics surface unanswered questions as content gap signals.
llms.txt is governed as an AI-first public root artefact, generated from the navigation by operations/scripts/generators/ai/llm/generate-llms-files.js.
The Mintlify-hosted MCP server lets Claude, Cursor, Windsurf, or any MCP client query the published docs in real time:
npx mcp add livepeer
Agent adapters
AGENTS.md is the baseline instruction set. Every agent reads it first, then loads its native adapter:
| Agent |
Adapter |
Scope |
| Claude Code |
.claude/CLAUDE.md |
Full project context, session management, co-work skills |
| Cursor |
.cursor/rules/ |
Governance rules, deletion guards |
| Windsurf |
.windsurf/rules/ |
Governance rules |
| GitHub Copilot |
.github/copilot-instructions.md |
Inline code suggestions |
| Augment Code |
.augment/rules/ |
Governance, git safety, deletion guards |
| Codex |
.github/AGENTS.md |
Task isolation, checkpoints, lock contracts |
Codex branch contract
AI agent implementation branches use codex/<issue-id>-<slug> naming. These branches are hook-enforced with a task contract file at .codex/task-contract.yaml, pre-push validation, and templated PR body generation by create-codex-pr.js.
28 AI skills
Skills provide structured workflows for both humans and agents. Invoke with /skill-name in Claude Code.
-
9 co-work and process skills: /thread, /pm, /research, /design, /build, /iterate, /dispatch, /agent-brief, /diagnose
-
4 content-pipeline skills: pass A, pass B, tab map, page authoring
-
8 audit and governance skills: repo audit orchestrator, docs coverage, docs quality and freshness, script footprint, component layout, generated banners, cleanup quarantine, cross-agent packaging
-
7 review and specialised skills: review packet generation, fix execution, rubric static review, copy editing, EN-GB style, product thinking, skill docs
10 portable templates live in ai-tools/ai-skills/templates/ and sync to Codex via sync-codex-skills.js or bash tools/lpd setup --yes.
Skills chain in a standard workflow: /thread (anchor), /pm (plan), /research (investigate), /design (architect), /build (execute), /iterate (review).
AI-powered pipelines
-
Glossary companion generation: extracts SearchTable item lists from MDX glossary pages and writes companion JSON for AI and crawler discoverability
-
Content health automation: weekly scheduled scan for stale pages, broken links, and content drift, with reports under workspace/reports/
-
Language translation: OpenRouter-driven pipeline for multi-locale content, with frontmatter taxonomy validation enforcing valid locale values
Reference at docs.livepeer.org/docs-guide/features/ai-features.
Claude Code hooks
The repo ships native Claude Code hook integrations covering PreToolUse (destructive git block, public-post block, unconfirmed-write block), PostToolUse (Edit/Write blast-radius scanner, MDX validation, Bash move-detect, Read logger, phase-gate), UserPromptSubmit (MDX-constraints injection, message backup, friction logger), and PreCompact (checkpoint), plus session register and session state.
UI system: governed components and template scaffolding
Components live in snippets/components/ under JSDoc-driven governance. Validators enforce JSDoc coverage, prop documentation, CSS variable rules, file naming, PascalCase exports, MDX-facing scope, and component immutability in PR context.
The component inventory at docs.livepeer.org/docs-guide/catalog/components-catalog is generated from the registry.
Templates are governed and generated. Page templates live at snippets/templates/pages/** and produce one direct preview route each:
-
FAQ page, how-to page, landing-frame page, overview page, reference page, troubleshooting page, tutorial page
-
Landing-and-navigation: navigation page, portal page
-
Reference-and-API: OpenAPI endpoint page
-
Setup-and-code-layouts: multi-view page
Block templates live at snippets/templates/blocks/**: comparison matrix, comparison table, related pages cards, related pages CTA.
Templates auto-generate VS Code snippets at .vscode/templates.code-snippets and .vscode/components.code-snippets via generate-ui-templates.js. Authoring with lp-overview, lp-howto, lp-tutorial, lp-reference, lp-landing-frame, template-faq-page, template-troubleshooting-page, template-openapi-endpoint-page is one keystroke in VS Code.
UI system reference at docs.livepeer.org/docs-guide/features/ui-system.
Automations and live data
Three core pipelines
1. Quality and CI
-
test-suite.yml runs changed-file checks plus browser test
-
test-v2-pages.yml runs the v2 browser sweep with artifacts and PR comments
-
broken-links.yml runs the advisory link checker
-
validator-health-check-openapi-reference.yml runs blocking OpenAPI endpoint integrity checks for v2 plus locales, with conservative autofix on non-PR runs (method case, METHOD/path spacing, leading slash). Failures track through a single rolling marker issue. Clean runs close it.
2. Data refresh
-
audit-health-scan-data-freshness.yml runs the advisory daily freshness report
-
integrator-maintenance-update-release-version.yml updates global release data from update-livepeer-release.js
-
update-forum-data.yml, update-ghost-blog-data.yml, update-youtube-data.yml refresh community feeds
-
integrator-copy-update-showcase-submissions.yml refreshes the showcase pipeline
-
integrator-maintenance-update-config-flags.yml, integrator-maintenance-update-exchanges-data.yml, integrator-maintenance-update-large-assets.yml, integrator-maintenance-update-contract-addresses.yml refresh the rest
3. Governance and intake
-
interface-governance-intake-discord-issues.yml and interface-governance-label-issues.yml handle issue intake
-
interface-governance-assign-reviewers.yml, interface-governance-index-issues.yml, interface-governance-close-linked-issues.yml handle review automation
-
dispatch-governance-post-merge-sync.yml runs post-merge sync
-
validator-governance-check-codex-compliance.yml, validator-governance-check-governance-map.yml, validator-governance-check-workflow-governance.yml enforce governance contracts
Reference at docs.livepeer.org/docs-guide/features/automations.
Live data ingestion
Forum, blog, YouTube, GitHub Releases, GitHub Discussions, Discord announcements, Ghost RSS, generic RSS, LPT exchanges, OpenAPI specs, and on-chain contract addresses all flow into the docs through dedicated fetcher scripts.
Ingestion outputs are committed under snippets/data/social-feeds/, snippets/data/globals/, snippets/data/showcase-feed/. The chain-first contracts pipeline pulls verified addresses from on-chain sources and renders them through Playwright-tested reference pages.
n8n pipeline assets live at snippets/assets/data/n8n/. Active pipelines: project showcase application workflow, Showcase project pipeline, Discord announce to Mintlify, Luma to Mintlify. Superseded n8n definitions are mirrored to tasks/staging/deprecated-n8n/ for deprecation tracking.
Data integrations and OpenAPI
Canonical API specs live in api/:
Generation helpers fetch-openapi-specs.sh and generate-api-docs.sh regenerate reference pages from the specs. The OpenAPI reference audit runs daily plus on every PR plus on push.
Internal data layers cover route/link maps at snippets/data/*/hrefs.jsx, domain data modules at snippets/data/**/*.jsx, and the AI sitemap at sitemap-ai.xml.
Reference at docs.livepeer.org/docs-guide/features/data-integrations.
Content veracity and research
Content correctness is treated as a first-class governed surface, not a review step.
-
docs-page-research.js extracts factual claims from docs pages, checks evidence sources, and detects contradictions across related pages
-
docs-research-adjudication.js records measured review outcomes so trust decisions are based on real usage
-
docs-research-packet.js derives nav, manifest, or path scope and runs the research stack tranche-by-tranche
-
docs-page-research-pr-report.js runs the fact-check runner on changed docs pages and emits an advisory PR artefact summarising claim families, contradictions, unresolved factual risk, and propagation follow-up
-
audit-v2-usefulness.js scores v2 pages on human and agent usefulness with source-weighted 2026 accuracy verification
-
docs-quality-and-freshness-audit.js checks for TODO/TBD/Coming Soon markers, thin pages, and stale content
-
audit-glossary-gaps.js finds terminology candidates not yet defined
-
generate-content-gap-reconciliation.js compares blueprint coverage against shipped MDX
The quality gate map is at docs.livepeer.org/docs-guide/policies/quality-gates.
Translations
The translation pipeline is wired and operational.
-
translate-docs.js translates v2 MDX pages to target languages via OpenRouter
-
generate-localized-docs-json.js produces locale-specific docs.json from the route map
-
validate-generated.js checks generated MDX and route-map outputs for integrity
-
The Mintlify version and language toggle is wired through the audit at test-mintlify-version-language-toggle.js
-
Frontmatter taxonomy enforcement at frontmatter-taxonomy.js blocks invalid locale values at commit
-
Translation provenance is tracked in provenance.js
Generated locale files carry the same banner enforcement as English originals. The enforce-generated-file-banners.js validator includes i18n parity checks. Live Pioneers and AI-assisted translations flow through the same pipeline.
Workflow at .github/workflows/integrator-copy-update-translations.yml.
Accessibility
The v2 WCAG audit (v2-wcag-audit.js) runs WCAG 2.2 AA conformance checks across docs.json navigation pages with deterministic reports and conservative source autofixes. Common raw-tag issues (iframe titles, img alt, icon-only anchor aria-label) are auto-repaired through wcag-repair-common.js.
lpd test --staged --wcag runs the audit locally on staged files. lpd test --full runs it across the full v2 surface.
Visual Explainer (maintainer pilot)
A pilot Claude Code skill, nicobailon/visual-explainer, is available for maintainers as an out-of-repo tooling layer. It is not in CI, not in Mintlify, not a contributor gate.
Six maintainer use cases:
-
/plan-review for cross-referencing plan documents against actual codebase
-
/diff-review for visual review of structural PRs touching docs.json, snippets/components/, .github/workflows/
-
/generate-web-diagram for rescuing commented-out architecture diagrams (BYOC and Marketplace Interaction Model in v2/gateways/resources/technical/technical-architecture.mdx)
-
/fact-check for verifying delivery report claims against the codebase
-
/project-recap for contributor onboarding and maintainer context-switching
-
Persona routing matrix as an internal artefact
Outputs land in ~/.agent/diagrams/ and stay out of the repo during pilot. 4-week rollout. Reference at docs.livepeer.org/docs-guide/features/visual-explainer-workflows.
Internal hub
The Internal tab at docs.livepeer.org/v2/internal hosts the philosophy, the RFP traceability, the delivery reports, and the operational reports against the brief. This is where stakeholders can audit what was built against what was committed.
It includes:
-
The docs philosophy page citing Diátaxis, Docs as Code, and the D.O.C.S. principles
-
The 21 AI-First Docs items in the AI-First Report
-
Delivery reports, retrospectives, and audit outputs published from the governed report pipeline (publish-v2-internal-reports.js)
-
The full v2 internal reports tree under v2/internal/reports/
How a contributor adds a page today
-
bash lpd setup --yes once, to install dependencies, hooks, and Codex skill sync
-
lpd dev --scoped --scope-tab Developers to preview just the Developers tab
-
In VS Code, type lp-howto (or lp-overview, lp-tutorial, lp-reference) and a fully scaffolded page appears with canonical frontmatter, prerequisites, steps, validation, and a next-step CTA
-
Write the content
-
Commit. The pre-commit hook runs tests/run-all.js --staged --skip-browser which validates style, MDX, links, imports, frontmatter, descriptions, double headers, page endings, anchors, naming, generated artefact sync, EN-GB grammar and proper nouns, banned words and patterns, MDX-safe markdown, component scope, and codex task contract if on a codex/ branch. Anything deterministic that drifted is offered an exact repair command.
-
Push. The pre-push hook runs codex contract and issue-readiness checks.
-
Open PR. CI runs the changed-file blocking suite plus the broad sweeps. Governance approval labels gate any governance-sensitive PR.
-
Merge. Post-merge sync runs catalog regeneration, AI sitemap regeneration, OG image regeneration, llms.txt regeneration, and component registry regeneration.
The contributor never has to remember to do any of it.
Why we built it this way
The v2 brief had three asks: stakeholder-focused, AI-first, future-proofed.
Stakeholder-focused without a governance layer means the docs degrade the first time a contributor leaves. AI-first without a generation layer means llms.txt and AI sitemap are stale within a sprint. Future-proofed without ownerless governance means future-proofing depends on a future human who may not exist.
So the answer to all three asks was the same: build the documentation as infrastructure, with deterministic validators, exact repair paths, and gate-layer ownership baked in. Do that, and the rest follows.
The 366 scripts, the 49 workflows, the lpd CLI, the 28 AI skills, the agent adapters, the component library, the auto-remediation surface, the live data ingestion, and the ownerless governance contract are all that answer in concrete form.
The site is live at docs.livepeer.org. Translations are in pipeline.
Thanks to Rick (technical direction and engineering), Rich (executive), j0sh (SDK and remote signers), Peter (AI SPE), Mehrdad (protocol), and the Cloud SPE, Titan Node, and DeFine teams for review cycles. Thanks to the Foundation for backing the brief, and to the community for showing up to help wire it through.
-- Wonderland (docs lead, Livepeer Foundation)