> ## 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

Single source of truth for working in this repo. Read the section that matches what you are doing, then follow the pointer to the named framework, policy, or decision.

<CustomDivider />

## Pick your path

<CardGroup cols={3}>
  <Card title="I am a human contributor" href="/docs-guide/contributing/contributing">
    Onboarding, local preview, git hooks, and procedures. Start at contributing, then read the framework for the surface you are editing.
  </Card>

  <Card title="I am an AI agent" href="/docs-guide/contributing/agent-instructions">
    Agent governance and adapter contract. Then read the decision rules below for the kind of file you are touching.
  </Card>

  <Card title="I am reviewing a PR" href="/docs-guide/policies/quality-gates">
    Quality gates, governance approval, and Required Reading. The PR template auto-fills citations from changed paths.
  </Card>
</CardGroup>

<CustomDivider />

## Authority tiers

Files in `docs-guide/` follow a six-tier precedence model. When two governance docs disagree, the higher tier wins. Every file declares its tier in the `authority:` frontmatter field.

| Tier | Folder                   | What it holds                                                  | Example                                                                                                                   |
| ---- | ------------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| T0   | `decisions/`             | Locked precedent with IDs and supersession chains              | [D-DG-01..13: docs-guide structure](/docs-guide/decisions/docs-guide-structure)                                           |
| T1   | `policies/`              | Enforced rules; each policy declares consumers and a validator | [Source-of-truth policy](/docs-guide/policies/source-of-truth-policy)                                                     |
| T2   | `frameworks/`            | Subject models, taxonomies, lifecycles                         | [Component framework](/docs-guide/frameworks/component-framework-canonical)                                               |
| T3   | `standards/`             | Rules about form (voice, frontmatter, naming)                  | [Voice rules](/docs-guide/standards/voice-rules)                                                                          |
| T4   | `contributing/`          | Procedures (how to do work)                                    | [Contributing](/docs-guide/contributing/contributing)                                                                     |
| T5   | `reference/`, `catalog/` | Look-up only, never normative                                  | [Feature map](/docs-guide/features/feature-map) (currently under `features/`; moves to `reference/features/` per D-DG-03) |

Adapter files (`AGENTS.md`, `.claude/CLAUDE.md`, `.github/AGENTS.md`, `.cursor/rules/`, `.windsurf/rules/`, `.augment/rules/`) point UP into `docs-guide/`. They surface canonical truth for specific consumers but hold no authority. Any rule stated only in an adapter file is invalid and must canonicalise into a T0–T3 source. Locked by [D-DG-11](/docs-guide/decisions/docs-guide-structure).

<CustomDivider />

## Source-of-truth model

Where each kind of truth lives. Read [the policy](/docs-guide/policies/source-of-truth-policy) for the full boundaries.

| Surface                                 | Source of truth                                                                                                                                                                                      |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Runtime behaviour                       | Code and tests under `operations/`, `snippets/`, `tools/`                                                                                                                                            |
| Repo features and operations navigation | This `docs-guide/` section                                                                                                                                                                           |
| Public docs UX and content              | Mintlify pages under `v2/`                                                                                                                                                                           |
| Generated catalogs and indexes          | Generator scripts under `operations/scripts/generators/`; outputs are read-only                                                                                                                      |
| Decisions registries                    | `docs-guide/decisions/` (master index) plus per-domain logs cross-referenced from it                                                                                                                 |
| Glossary                                | `operations/scripts/generators/content/data/glossary-terms.json` is the corpus; both internal (`reference/internal-glossary.mdx`) and public (`v2/resources/glossary.mdx`) glossaries derive from it |

<CustomDivider />

## Frameworks and standards by concern

The most-referenced surfaces, organised by what you are about to do. Citation counts will be auto-injected once the index generator lands; for now, this list is curated.

| Surface                                                                     | Authority   | Read before                                                                           |
| --------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------- |
| [Source-of-truth policy](/docs-guide/policies/source-of-truth-policy)       | T1          | Editing any cross-cutting boundary; deciding what "canonical" means for a new surface |
| [Content system](/docs-guide/frameworks/content-system)                     | T2          | Adding or restructuring content sections                                              |
| [Component framework](/docs-guide/frameworks/component-framework-canonical) | T2          | Writing or moving any component under `snippets/components/`                          |
| [Page taxonomy framework](/docs-guide/frameworks/page-taxonomy-framework)   | T2          | Adding a new page; choosing pageType, pagePurpose, audience tokens                    |
| [Authoring standard](/docs-guide/standards/authoring-standard)              | T3          | Authoring any MDX page                                                                |
| [Script framework](/docs-guide/frameworks/script-framework)                 | T2          | Adding a new script under `operations/scripts/`                                       |
| [Repo structure](/docs-guide/frameworks/repo-structure)                     | T2 (LOCKED) | Adding a top-level folder; restructuring root                                         |
| [Voice rules](/docs-guide/standards/voice-rules)                            | T3          | Writing or rewriting prose; per-audience voice rules; banned phrases                  |
| [Frontmatter spec](/docs-guide/standards/frontmatter)                       | T3          | Authoring or migrating any frontmatter                                                |
| [File placement](/docs-guide/frameworks/file-placement)                     | T2          | Moving files; deciding where a new file belongs                                       |

<CustomDivider />

## Decision rules – read before doing X

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

### Before writing a component

1. [Component framework](/docs-guide/frameworks/component-framework-canonical) – category taxonomy, 7-tag JSDoc header
2. [File placement](/docs-guide/frameworks/file-placement) – folder placement rules
3. `docs-guide/canonical/collation-data/Mintlify/mintlify-repo-best-practices.md` – platform constraints

### Before writing a script

1. [Script framework](/docs-guide/frameworks/script-framework) – type, concern, niche taxonomy; 11-tag JSDoc header
2. [File placement](/docs-guide/frameworks/file-placement) – folder placement rules

### Before writing a docs page

1. [Content writing pipeline](/docs-guide/frameworks/content-writing) – pipeline phases, page taxonomy
2. [Voice rules](/docs-guide/standards/voice-rules) – per-audience voice rules
3. [Frontmatter spec](/docs-guide/standards/frontmatter) – required frontmatter fields
4. `docs-guide/canonical/collation-data/Mintlify/mintlify-repo-best-practices.md` – Mintlify platform constraints

### Before writing a workflow

1. [GitHub Actions framework](/docs-guide/frameworks/github-actions) – type, concern taxonomy; naming convention; pipeline tags
2. `.github/workspace/decisions-log.mdx` – locked decisions D-ACT-01 through D-ACT-10
3. `operations/governance/config/governance-approval-policy.json` – required approval labels

### Before moving files

1. [Repo structure](/docs-guide/frameworks/repo-structure) – root folder structure (LOCKED)
2. [File placement](/docs-guide/frameworks/file-placement) – component and script placement
3. [Docs guide structure policy](/docs-guide/policies/docs-guide-structure-policy) – docs-guide folder rules
4. Run the `/propagate` skill for any file with more than five incoming references

### Before adding or changing a decision

1. [Decisions registry](/docs-guide/decisions/registry) – master index of all decision logs
2. [Docs guide structure decision log](/docs-guide/decisions/docs-guide-structure) – 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

<CustomDivider />

## Governed surfaces

Major areas of this repo are governed. Each has a canonical framework, a root path, and a freshness status. The full live count is auto-generated at [repo-governance-map](/docs-guide/repo-ops/config/repo-governance-map).

| #  | Area                          | Root path                                                  | Framework                                                                      | Status           |
| -- | ----------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------ | ---------------- |
| 1  | Components                    | `snippets/components/`                                     | [Component framework](/docs-guide/frameworks/component-framework-canonical)    | Current          |
| 2  | Scripts                       | `operations/scripts/`                                      | [Script framework](/docs-guide/frameworks/script-framework)                    | Current          |
| 3  | AI tools and skills           | `ai-tools/ai-skills/`                                      | [AI tools framework](/docs-guide/frameworks/ai-tools-governance)               | Current          |
| 4  | Repo structure                | Root folders                                               | [Repo structure](/docs-guide/frameworks/repo-structure)                        | Current (LOCKED) |
| 5  | Content writing               | `v2/`                                                      | [Content writing](/docs-guide/frameworks/content-writing)                      | Active           |
| 6  | Documentation                 | `docs-guide/`                                              | [Doc item model](/docs-guide/frameworks/doc-item-model)                        | Locked           |
| 7  | Snippets root governance      | `snippets/`                                                | `snippets/guide.mdx`                                                           | Current          |
| 8  | Mintlify platform constraints | Platform-wide                                              | `docs-guide/canonical/collation-data/Mintlify/mintlify-repo-best-practices.md` | Current          |
| 9  | File placement                | Cross-cutting                                              | [File placement](/docs-guide/frameworks/file-placement)                        | Current          |
| 10 | GitHub Actions                | `.github/workflows/`                                       | [GitHub Actions framework](/docs-guide/frameworks/github-actions)              | Current          |
| 11 | Styles governance             | `style.css`, `v2/**/*.mdx`, `snippets/components/**/*.jsx` | [Styles engineering guide](/docs-guide/frameworks/styles-engineering-guide)    | Current          |

The full governance map is auto-generated at [repo-governance-map](/docs-guide/repo-ops/config/repo-governance-map). Run `node operations/scripts/generators/governance/generate-governance-map.js --check` to verify all folders are governed and no frameworks are stale.

<CustomDivider />

## Did you mean

Common misroutes. If you landed here looking for one of these, follow the pointer.

| You wanted                                | Go to                                                                                           |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Public protocol or product docs           | `v2/` (under `docs.livepeer.org` nav)                                                           |
| Component source code                     | `snippets/components/`                                                                          |
| Script source code                        | `operations/scripts/`                                                                           |
| AI skills source                          | `ai-tools/ai-skills/`                                                                           |
| Public glossary                           | [v2/resources/glossary](/v2/resources/glossary)                                                 |
| Internal contributor or agent terminology | [Internal glossary](/docs-guide/reference/internal-glossary)                                    |
| In-flight working specs and plans         | `workspace/plan/active/`                                                                        |
| Archived working specs                    | `workspace/plan/archive/`                                                                       |
| Mintlify platform notes                   | [Mintlify best practices](/docs-guide/reference/external/mintlify/mintlify-repo-best-practices) |
| Generated catalogs                        | `docs-guide/catalog/` (do not edit; regenerated from source)                                    |
| Configuration registries                  | `operations/governance/config/`                                                                 |

<CustomDivider />

## 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/governance/catalogs/generate-docs-guide-pages-index.js --write`
   * `node operations/scripts/generators/governance/catalogs/generate-docs-guide-components-index.js --write`
   * `node operations/scripts/generators/components/library/generate-ui-templates.js --write`
   * `node operations/tests/unit/script-docs.test.js --write --rebuild-indexes`
   * `node operations/scripts/validators/content/structure/enforce-generated-file-banners.js --check`
3. Re-run the docs audit pipeline when docs, scripts, reports, or routing paths change:
   * `node operations/scripts/dispatch/governance/repo/repo-audit-orchestrator.js --mode static --scope full`
   * `node operations/scripts/integrators/ai/agents/cross-agent-packager.js --agent-pack all`
4. Keep `README.md` high-level. Link to canonical docs-guide pages for deep detail.
5. Keep generator scripts, generated outputs, and downstream consumers in sync whenever a catalog path or title changes. Use the `/propagate` skill on any move or rename of a file with more than five incoming references.

<CustomDivider />

## Standards index

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

| Standard                                                       | What it covers                                              |
| -------------------------------------------------------------- | ----------------------------------------------------------- |
| [Authoring standard](/docs-guide/standards/authoring-standard) | Page composition, structure, headings, sections             |
| [Voice rules](/docs-guide/standards/voice-rules)               | Per-audience voice, banned words and phrases, UK English    |
| [Voice and copy](/docs-guide/standards/voice-and-copy)         | Copy patterns, brand voice across audiences                 |
| [Naming conventions](/docs-guide/standards/naming-conventions) | File, folder, component, script, workflow naming            |
| [Frontmatter spec](/docs-guide/standards/frontmatter)          | Required and optional frontmatter fields per authority tier |

<CustomDivider />

## Decision registry

All decision registries are indexed at [decisions/registry](/docs-guide/decisions/registry). Per-domain registries live under `workspace/plan/active/<DOMAIN>/decisions/` and are cross-referenced from the master index. The decisions pipeline (D-DG-01 ID grammar plus generator and validator) is documented in [decisions/docs-guide-structure](/docs-guide/decisions/docs-guide-structure).

<CustomDivider />

## Related

* Root orientation: [`README.md`](/README)
* Public docs guide: [`v2/resources/documentation-guide/`](/v2/resources/documentation-guide)
* Contributor procedures: [`docs-guide/contributing/`](/docs-guide/contributing/contributing)
* Test matrices and CI behaviour: `operations/tests/README.md`
* Approved redesign plan: `~/.claude/plans/hmm-so-there-needs-tender-valley.md`