Docs Guide

Livepeer Docs is a self-remediating, ownerless documentation operating system built on Mintlify. Three product layers run on top of the publishing platform: a self-governing repo (11 workflows + 321 scripts + 4 of 5 unified ownerless-ready surfaces post-D-ACT-10); an AI-native distribution layer (llms.txt, hosted MCP, 6 native agent adapters, 34 skills); and a contributor toolchain (lpd CLI + scoped Mintlify preview + 4 in-repo VS Code extensions + 312 governed snippets). This page is the orient surface. Every claim, count, and contract on this page traces to a canonical doc one click away. Live counts verified 2026-05-25. Honest framing: “ownerless” covers routine drift, not policy authorship or destructive operations. 4 of 5 unified governance surfaces formally ownerless-ready today (1 advisory: github-workspace-governance); legacy 8-entry ownerless-governance-surfaces.json superseded per D-ACT-10.

Pick your path

Contributor

Onboarding, local preview, git hooks. Start in contributing/, then jump to the framework for the surface you are editing.

AI agent

Agent governance + adapter contract. Then read the Decision rules for the kind of file you are touching.

PR reviewer

Quality gates + governance approval + Required Reading. The PR template auto-fills citations from changed paths.

Maintainer

The 4-part ownerless contract + promotion ladder. Eight surfaces in production; twenty more advisory.

What this repo ships (9 feature domains)

Domain	Canonical page	What it covers
AI features	AI Features	`llms.txt`, hosted MCP, Mintlify chat assistant, 6 native agent adapters, 34 local skills + 53 portable templates, AI registry
UI system	UI System	132 component registry exports, 37 templates, 8 Tier-1 composables, design tokens, 312 VS Code snippets
Automations	Automations	11 active workflows (post-2026-05-22 4-tier refactor), 321 scripts, hook pipeline, 18 locked D-ACT + D-GOV decisions
Data integrations	Data Integrations	11 integration families: contracts gold-standard, OpenAPI, releases, exchanges, social feeds, glossary, reference maps
Adaptive architecture	Adaptive Architecture	4-part ownerless contract, 5-stage control loop, 49 validators + 37 remediators + 31 generators + 25 audits
Contributor tools	Contributor Tools	`lpd` CLI (13 subcommands + 5 group shorthands), 4 in-repo VS Code extensions, scoped preview, `.githooks/`
Content writing pipeline	Content Writing	9-stage project pipeline + page taxonomy + voice rules; 0 of 5 tabs has IA Approved
Checks framework	Checks Framework	11-phase per-page review + 9 universal check categories + per-pageType + per-tab variation
Gap analysis	Gap Analysis	Implementation-ready backlog with P0/P1/P2 priorities, file paths, acceptance criteria

Cross-domain spine: Feature Map – system layers (navigation, content, components, data, operations, governance, AI agent, content writing) with canonical sources + derived outputs + primary gates per layer.

The three locked-decision registries

The repo carries 32 locked structural decisions across three ID-prefixed registries. The unified index at decisions/registry.md cross-references all three.

Registry	Lives at	Count	Coverage
Docs-guide structure	`decisions/docs-guide-structure.md`	13 (D-DG-01..13)	IA migration; standards/frameworks/policies/decisions/contributing tiers; thin-adapter rule (D-DG-11)
GitHub Actions + governance	`.github/workspace/decisions-log.mdx`	18 (D-ACT-01..10 + D-GOV-01..08)	Workflow architecture, 4-tier composable, taxonomy, pipeline tags, dispatcher model
Content writing	`workspace/plan/active/CONTENT-WRITING/decisions/decision-registry.md`	1 (D-NAV-01)	Cross-tab navigation pattern for multi-path tabs

The rule: decisions made in chat that are not written to a registry do not exist. Phases may not consume a decision that is not in its registry.

Two interlocking pipelines

The page-authoring + checks system is two pipelines that interlock at three points:

Pipeline	Scope	Phases	Source
Project pipeline	A whole tab (or section) – from “audience defined” to “all pages drafted”	9 stages, each with a human gate	Content Writing Pipeline; canonical at `workspace/plan/active/_MY_PROCESS/my-process.mdx`
Per-page review pipeline	A single page – from “drafted” to “approved for publication”	11 phases (Phase 0..10) + 9 universal Cat 1-9 + per-pageType + per-tab variation	Checks Framework; canonical at `workspace/plan/active/master-checks.mdx` (882 lines)

The two interlock at project-pipeline Stage 7 (Phases 0-6 of per-page review), Stage 8 (Phase 7), and Stage 9 (Phase 10). As of 2026-05-23, 0 of 5 tabs has IA Approved (gate 1) – the project pipeline is stalled across the entire docs estate.

Decision rules – before doing X

Before writing or moving any governed file, read the listed documents.

Before writing a component

Component framework – 6-category taxonomy + 7-tag JSDoc
File placement – folder placement rules
Mintlify constraints – platform restrictions

Before writing a script

Script framework – type/concern/niche taxonomy + 11-tag JSDoc
File placement
Script governance policy – retired-tag list (lines 195-205)

Before writing a docs page

Content Writing Pipeline – page taxonomy + voice rules + the 9-stage project pipeline
Checks Framework – the 11-phase per-page review pipeline + Cat 1-9
Voice and copy standards – banned words, UK English, per-audience extensions, heading rules
Frontmatter spec – required minimum

Before writing a workflow

GitHub Actions framework – type/concern taxonomy + naming convention + pipeline tags
.github/workspace/decisions-log.mdx – D-ACT-01..10 + D-GOV-01..08 (18 locked decisions)
operations/governance/config/governance-approval-policy.json – required approval labels

Before moving files

Repo structure – root folder structure (LOCKED)
File placement
Docs-guide structure policy
Run the /propagate skill for any file with more than five incoming references

Before adding or changing a decision

Decisions registry – unified index of all 32 locked decisions
Docs-guide structure decision log – example of the locked format
ID grammar: D-{SCOPE}-{NN} where SCOPE is one of NAV, ACT, GOV, SCRIPT, OWN, CONTENT, ORCH, GW, DG, GLOS

Canonical source map

Every governed surface in this repo declares canonical source · validator · repair path · single gate layer (the 4-part ownerless contract). Full enumeration at policies/governance-index.mdx.

Surface	Source of truth	Authority tier
Runtime behaviour	Code and tests under `operations/`, `snippets/`, `tools/`	runtime
Repo features + governance	This `docs-guide/` tree	T0..T5 (per D-DG-11)
Public docs UX + content	Mintlify pages under `v2/`	runtime
Generated catalogs + indexes	Generator scripts under `operations/scripts/generators/`; outputs are read-only	derived
Decision registries	`docs-guide/decisions/registry.md` (unified) + 2 per-domain registries (see above)	T0
Glossary	`operations/scripts/generators/content/data/glossary-terms.json` (corpus); internal + public glossaries derive from it	derived

Per locked D-DG-11: adapter files point UP into docs-guide. Any rule stated only in an adapter is invalid and must canonicalise into a T0–T3 source. The 6 native adapters (AGENTS.md, .claude/CLAUDE.md, .cursor/rules/, .windsurf/rules/, .augment/rules/, .github/AGENTS.md, .github/copilot-instructions.md, .mintlify/Assistant.md) surface canonical truth for specific consumers but hold no authority of their own.

Standards index

Published authoring and style standards in docs-guide/standards/.

Standard	What it covers
Authoring standard	Page composition, structure, headings, sections
Voice and copy	Per-audience voice, banned words/phrases, UK English, heading rules, brand voice
Naming conventions	File, folder, component, script, workflow naming
Frontmatter spec	Required and optional frontmatter fields per authority tier

What’s stale today

The honest snapshot. Full backlog with P0/P1/P2 priorities + file paths + acceptance criteria at Gap Analysis. Last refreshed 2026-05-25 after the consolidation pass – see Gap Analysis § Resolved 2026-05-25 for the items just closed. Open:

P0 OpenAPI specs 67 days stale. All 5 specs in api/ last touched 2026-03-18; fetcher covers 2 of 5; no scheduled workflow.
P0 docs.json default version is v1, not v2. Visitors land on v1 by default unless Mintlify dashboard overrides.
P0 Stale governance map. Self-detected by generate-repo-governance-status.js --check. The cron-is-dry-run fix (shipped 2026-05-25) should trigger regeneration on the next scheduled run after merge to docs-v2. Verify after merge.
P1 Gateways _workspace/canonical/ is byte-identical to orchestrators’s. Gateways imports the IA wholesale; REVIEW-REGISTRY.md literally opens # Orchestrators Tab Page Inventory.
P1 0 of 5 content tabs has IA Approved. Project pipeline stalled at Phase 2 across the entire docs estate.
P1 4-surface component count drift. Feature page 59 / public overview 117 / framework table 118 / registry 132 – no source agrees. Generator-source every count.
P1 307-row v2 cleanup matrix needs execution (235 _workspace candidates + 72 x-deprecated candidates; gateways carries 199 of 307).
P1 18 of 35 local skills in status: draft with empty test logs. Session-lifecycle backbone (thread, research, design, build, iterate, close) never validated in production.

Recently closed 2026-05-25 (full detail in Gap Analysis § Resolved):

P0 cron-is-dry-run bug – fixed in commit e42946cdf, pending merge to docs-v2
P1 decisions-log “lags” false flag – verified all 18 decisions present, split across 2 files
P1 .github/scripts/ “empty=gap” framing – clarified as locked decision D-ACT-06
P1 ownerless framing refresh post-D-ACT-10 – corrected “8 of 28” to live “4 of 5 unified surfaces” across 6 pages
P3 frameworks/github-actions.mdx synced to v2.2
P4 documented 3 new veracity dispatchers + local social-feed dispatcher
Frontmatter compliance: all 16 frameworks + 17 policies brought to canonical (pageType/audience/purpose/status/lastVerified) – 0 blocking lint errors across both folders

Update rules

Update manual docs when behaviour, process, canonical boundaries, or architecture changes. Bump lastVerified on save.
Regenerate generated catalogs when scripts, workflows, or templates change:
- node operations/scripts/generators/governance/catalogs/generate-docs-guide-indexes.js --write
- node operations/scripts/generators/components/library/generate-ui-templates.js --write
- node operations/scripts/generators/governance/reports/generate-repo-governance-status.js --write
Run /propagate on any file move or rename with more than five incoming references.
Keep README high-level. Link to canonical docs-guide pages for detail.

Quickstart

Five steps from clone to first PR:

Clone + switch to the production branch

git clone https://github.com/livepeer/docs.git
cd docs
git checkout docs-v2

Public contributors branch from and PR against docs-v2. Internal in-flight work lives on docs-v2-dev.

Run setup

bash lpd setup --yes

Installs git hooks, dependencies, optionally puts the CLI on $PATH. Non-interactive when --yes is set.

Confirm your environment

lpd doctor

Reports Node / PATH / Mintlify / Puppeteer / hooks status. Fails fast if anything is missing.

Boot a scoped preview

lpd dev --scoped --scope-tab Developers

Filtered Mintlify dev server against a 1,128-page nav boots in ~2 seconds instead of ~10 minutes.

Edit, validate, commit, PR

git checkout -b docs/<descriptive-slug>
# edit your MDX or JSX file
lpd test --staged
git commit -m "<scope>: <change>"
git push origin docs/<descriptive-slug>
gh pr create --base docs-v2

Pre-commit hooks run MDX render checks, allowlist guards, redirect integrity, and no-deletion enforcement in ≤60 seconds. PR CI re-runs blocking checks against changed files.

Full contributor flow with branching conventions, override trailers, governance approval labels, and the canonical PR template: contributing/contributing.mdx.

Feature Map – full inventory snapshot + system map
Gap Analysis – actionable backlog with P0/P1/P2 priorities
Decisions Registry – unified index of all 32 locked decisions
Governance Index – every governed surface with canonical framework, root path, status
Source-of-Truth Policy – canonical boundaries per surface
Community Help – 80+ specific OSS opportunities with file paths + acceptance criteria
README – root orientation
Public docs guide for site visitors: v2/resources/documentation-guide/

Technical References

Compendium

Knowledge Hub

Changelogs

Documentation Guide

Docs Guide

Docs Guide

Pick your path

Contributor

AI agent

PR reviewer

Maintainer

What this repo ships (9 feature domains)

The three locked-decision registries

Two interlocking pipelines

Decision rules – before doing X

Before writing a component

Before writing a script

Before writing a docs page

Before writing a workflow

Before moving files

Before adding or changing a decision

Canonical source map

Standards index

What’s stale today

Update rules

Quickstart

​Docs Guide

​Pick your path

Contributor

AI agent

PR reviewer

Maintainer

​What this repo ships (9 feature domains)

​The three locked-decision registries

​Two interlocking pipelines

​Decision rules – before doing X

​Before writing a component

​Before writing a script

​Before writing a docs page

​Before writing a workflow

​Before moving files

​Before adding or changing a decision

​Canonical source map

​Standards index

​What’s stale today

​Update rules

​Quickstart

​Related

Docs Guide

Pick your path

What this repo ships (9 feature domains)

The three locked-decision registries

Two interlocking pipelines

Decision rules – before doing X

Before writing a component

Before writing a script

Before writing a docs page

Before writing a workflow

Before moving files

Before adding or changing a decision

Canonical source map

Standards index

What’s stale today

Update rules

Quickstart

Related