Docs Guide

Internal source of truth for repository features, rules, and decisions. Single front door for humans and AI agents working in the Livepeer Docs v2 repo.

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

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

Before writing a script

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

Before writing a docs page

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

Before writing a workflow

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

Before moving files

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

Before adding or changing a decision

1. Decisions registry – unified index of all 32 locked decisions
2. Docs-guide structure decision log – example of the locked format
3. 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

1. Update manual docs when behaviour, process, canonical boundaries, or architecture changes. Bump lastVerified on save.
2. 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
3. Run /propagate on any file move or rename with more than five incoming references.
4. Keep README high-level. Link to canonical docs-guide pages for detail.

---

Quickstart

Five steps from clone to first PR:

1. 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.

2. Run setup

   bash lpd setup --yes
   

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

3. Confirm your environment

   lpd doctor
   

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

4. 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.

5. 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.

---

Related

• 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/