> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livepeer.org/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](./features/automations.mdx#locked-decisions-18).
***
## Pick your path
Onboarding, local preview, git hooks. Start in `contributing/`, then jump to the framework for the surface you are editing.
Agent governance + adapter contract. Then read the [Decision rules](#decision-rules-before-doing-x) for the kind of file you are touching.
Quality gates + governance approval + Required Reading. The PR template auto-fills citations from changed paths.
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](./features/ai-features.mdx) | `llms.txt`, hosted MCP, Mintlify chat assistant, 6 native agent adapters, 34 local skills + 53 portable templates, AI registry |
| UI system | [UI System](./features/ui-system.mdx) | 132 component registry exports, 37 templates, 8 Tier-1 composables, design tokens, 312 VS Code snippets |
| Automations | [Automations](./features/automations.mdx) | 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](./features/data-integrations.mdx) | 11 integration families: contracts gold-standard, OpenAPI, releases, exchanges, social feeds, glossary, reference maps |
| Adaptive architecture | [Adaptive Architecture](./features/adaptive-architecture.mdx) | 4-part ownerless contract, 5-stage control loop, 49 validators + 37 remediators + 31 generators + 25 audits |
| Contributor tools | [Contributor Tools](./features/contributor-tools.mdx) | `lpd` CLI (13 subcommands + 5 group shorthands), 4 in-repo VS Code extensions, scoped preview, `.githooks/` |
| Content writing pipeline | [Content Writing](./frameworks/content-writing.mdx) | 9-stage project pipeline + page taxonomy + voice rules; 0 of 5 tabs has IA Approved |
| Checks framework | [Checks Framework](./frameworks/checks-framework.mdx) | 11-phase per-page review + 9 universal check categories + per-pageType + per-tab variation |
| Gap analysis | [Gap Analysis](./features/gap-analysis.mdx) | Implementation-ready backlog with P0/P1/P2 priorities, file paths, acceptance criteria |
Cross-domain spine: [Feature Map](./features/feature-map.mdx) – 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`](./decisions/registry.md) cross-references all three.
| Registry | Lives at | Count | Coverage |
| --------------------------- | -------------------------------------------------------------------------- | -----------------------------------: | ----------------------------------------------------------------------------------------------------- |
| Docs-guide structure | [`decisions/docs-guide-structure.md`](./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](./frameworks/content-writing.mdx); 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](./frameworks/checks-framework.mdx); 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](./frameworks/component-framework-canonical.mdx) – 6-category taxonomy + 7-tag JSDoc
2. [File placement](./frameworks/file-placement.mdx) – folder placement rules
3. [Mintlify constraints](./contributing/mintlify.mdx) – platform restrictions
### Before writing a script
1. [Script framework](./frameworks/script-framework.mdx) – type/concern/niche taxonomy + 11-tag JSDoc
2. [File placement](./frameworks/file-placement.mdx)
3. [Script governance policy](./policies/script-governance.mdx) – retired-tag list (lines 195-205)
### Before writing a docs page
1. [Content Writing Pipeline](./frameworks/content-writing.mdx) – page taxonomy + voice rules + the 9-stage project pipeline
2. [Checks Framework](./frameworks/checks-framework.mdx) – the 11-phase per-page review pipeline + Cat 1-9
3. [Voice and copy standards](./standards/voice-and-copy.mdx) – banned words, UK English, per-audience extensions, heading rules
4. [Frontmatter spec](./standards/frontmatter.mdx) – required minimum
### Before writing a workflow
1. [GitHub Actions framework](./frameworks/github-actions.mdx) – 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](./frameworks/repo-structure.mdx) – root folder structure (LOCKED)
2. [File placement](./frameworks/file-placement.mdx)
3. [Docs-guide structure policy](./policies/docs-guide-structure-policy.mdx)
4. Run the `/propagate` skill for any file with more than five incoming references
### Before adding or changing a decision
1. [Decisions registry](./decisions/registry.md) – unified index of all 32 locked decisions
2. [Docs-guide structure decision log](./decisions/docs-guide-structure.md) – 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`](./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](./standards/authoring-standard.mdx) | Page composition, structure, headings, sections |
| [Voice and copy](./standards/voice-and-copy.mdx) | Per-audience voice, banned words/phrases, UK English, heading rules, brand voice |
| [Naming conventions](./standards/naming-conventions.mdx) | File, folder, component, script, workflow naming |
| [Frontmatter spec](./standards/frontmatter.mdx) | 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](./features/gap-analysis.mdx). **Last refreshed 2026-05-25 after the consolidation pass – see [Gap Analysis § Resolved 2026-05-25](./features/gap-analysis.mdx#resolved-2026-05-25-consolidation-pass) 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](./features/gap-analysis.mdx#resolved-2026-05-25-consolidation-pass)):
* 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:
```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
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`.
```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
bash lpd setup --yes
```
Installs git hooks, dependencies, optionally puts the CLI on `$PATH`. Non-interactive when `--yes` is set.
```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
lpd doctor
```
Reports Node / PATH / Mintlify / Puppeteer / hooks status. Fails fast if anything is missing.
```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
lpd dev --scoped --scope-tab Developers
```
Filtered Mintlify dev server against a 1,128-page nav boots in \~2 seconds instead of \~10 minutes.
```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
git checkout -b docs/
# edit your MDX or JSX file
lpd test --staged
git commit -m ": "
git push origin docs/
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](./contributing/contributing.mdx).
***
## Related
* [Feature Map](./features/feature-map.mdx) – full inventory snapshot + system map
* [Gap Analysis](./features/gap-analysis.mdx) – actionable backlog with P0/P1/P2 priorities
* [Decisions Registry](./decisions/registry.md) – unified index of all 32 locked decisions
* [Governance Index](./policies/governance-index.mdx) – every governed surface with canonical framework, root path, status
* [Source-of-Truth Policy](./policies/source-of-truth-policy.mdx) – canonical boundaries per surface
* [Community Help](./contributing/community-help.mdx) – 80+ specific OSS opportunities with file paths + acceptance criteria
* [README](/README) – root orientation
* Public docs guide for site visitors: `v2/resources/documentation-guide/`