> ## 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 Structure Policy
> Canonical policy for the docs-guide/ folder structure, authority tiers, naming conventions, and generated-file rules.
# Docs Guide Structure Policy
> Defines what belongs in `docs-guide/`, how it is organised, the authority tiers that govern conflict resolution, and the rules that apply to each content type.
## Scope
| In scope | Out of scope |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| All files and folders under `docs-guide/` | `v2/` content pages |
| Authority tier model and frontmatter contract | `snippets/` component library |
| Naming conventions for catalog, policy, framework, standard, decision, and reference files | AI adapter files (`.claude/`, `.cursor/`, `.windsurf/`, `.augment/`) |
| Generator freshness, validator coverage, and CI pipeline rules | Root-level `.allowlist` governance (see `root-allowlist-governance.mdx`) |
| `_workspace/` usage within `docs-guide/` | `operations/governance/config/` (script-consumed registries) |
## Authority Tiers
`docs-guide/` files are governed by a six-tier precedence model declared in the mandatory `authority:` frontmatter field. When two governance docs conflict, the higher tier wins.
| Tier | Folder | Authority | Conflict resolution |
| ---- | ------------------------ | ------------------------------------------------------- | ---------------------------------------------------- |
| T0 | `decisions/` | Locked precedent with IDs and supersession chains | Beats every other tier |
| T1 | `policies/` | Enforced rules, prohibited actions, gate-owned controls | Beats frameworks, standards, contributing, reference |
| T2 | `frameworks/` | Subject models, taxonomies, lifecycles | Beats standards, contributing, reference |
| T3 | `standards/` | Rules about form (voice, frontmatter, naming) | Beats contributing, reference |
| T4 | `contributing/` | Procedures (how to do work) | Beats reference |
| T5 | `reference/`, `catalog/` | Look-up only, never normative | Always loses to higher tiers |
Adapter files (`AGENTS.md`, `.claude/CLAUDE.md`, `.github/AGENTS.md`, IDE 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 be canonicalised into a T0–T3 source.
Locked by D-DG-01.
## Canonical Structure
```icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}}
docs-guide/
├── index.mdx ← single landing page (replaces source-of-truth-guide and governance-index)
├── GOVERNANCE.md ← root governance marker (YAML-front, generated by generate-governance-map.js)
├── standards/ ← T3: voice, frontmatter, naming, authoring rules
├── frameworks/ ← T2: subject models (component, script, content, page taxonomy, etc.)
├── policies/ ← T1: enforced rules; each policy declares consumers and validator
├── decisions/ ← T0: locked precedent with IDs and supersession chains
├── contributing/ ← T4: contributor and agent procedures, onboarding, governance quickstart
├── reference/ ← T5: descriptive look-up surfaces (no rules)
│ ├── features/ ← feature, system, and architecture maps
│ ├── tooling/ ← CLI, dev tools, ai-tools, reference maps (badges, icons)
│ ├── repo-ops/ ← enforcement maps, repo-governance maps, secrets, config registries
│ ├── pipelines/ ← pipeline concern docs (formerly docs-library)
│ ├── external/ ← external platform reference (mintlify best-practices, etc.)
│ └── internal-glossary.mdx ← internal contributor and agent terminology, derived from corpus
├── catalog/ ← auto-generated catalogs only; do not edit manually
└── _workspace/ ← scratch, drafts, archive; not in nav; TTL-governed
```
No other top-level subdirectories are permitted without an explicit superseding decision in `decisions/docs-guide-structure.md`.
Locked by D-DG-02. Migration paths from the previous structure are recorded in D-DG-03 (features/tooling/repo-ops/docs-library merge into reference/), D-DG-04 (canonical/ retired), and D-DG-05 (config/ moved to operations/).
## Rules
1. **Top-level structure is locked.** New top-level subdirectories under `docs-guide/` require a superseding decision (D-DG-NN) in `decisions/docs-guide-structure.md` before they can be created.
2. **No 0-byte stubs.** Placeholder files with no content are not permitted. A file at a nav path must contain real content or must not exist.
3. **One canonical file per subject.** When a framework and a policy address the same subject, the framework holds the model and the policy holds the enforcement. Subject-level duplicates are prohibited; the contract validator flags them.
4. **Generated files must not be manually edited.** All files in `docs-guide/catalog/` and any file with `maintenance: generated` frontmatter are auto-generated. They carry a `generated-file-banner:v1` comment block identifying their generator script. Manual edits are overwritten on the next run.
5. **Generated files must stay current.** If a generator's source input changes (workflows, templates, docs.json, registries, surfaces JSON), the corresponding output must be regenerated before the PR merges. The catalog freshness CI workflow enforces this.
6. **Naming suffix discipline.** Follow the suffix pattern for each section:
* `catalog/` files: `-catalog.mdx`
* `policies/` files: `-policy.mdx`
* `frameworks/` files: `-framework.mdx`
* `standards/` files: `-standard.mdx` or descriptive (e.g. `voice-and-copy.mdx`)
* `decisions/` files: `.md` (decision logs are MD, not MDX); `index.mdx` is the master index
* `contributing/` files: `.mdx` (descriptive)
* `reference/` files: `-map.mdx`, `.mdx`, or descriptive
* The `-governance.mdx` suffix is retired in favour of `-policy.mdx` or `-framework.mdx` per authority tier (D-DG-09).
7. **No `-index.mdx` naming for hand-maintained content.** Use `-catalog.mdx` for generated inventories; descriptive names for hand-maintained pages; `index.mdx` is reserved for folder-level entry points (e.g. `decisions/index.mdx`).
8. **Archive before delete.** Files being removed from navigation move to `_workspace/archive/` with a 90-day TTL before permanent deletion, unless they are 0-byte stubs (which may be deleted immediately). High-cite files (>5 incoming references) require `/propagate` skill execution before move or delete.
9. **`_workspace/` is not a nav path.** `docs-guide/_workspace/` must never appear in `docs.json`. It is covered by `.mintignore` and every page under it carries `noindex: true` frontmatter.
10. **Frontmatter contract is mandatory.** Every file in `docs-guide/` (excluding `_workspace/` and `catalog/`) must declare `title`, `description`, `authority`, `consumer`, `maintenance`, `status`, `lastVerified`, `owner`. Conditional fields apply per authority tier. Enforced by `check-docs-guide-contract.js` (D-DG-07).
11. **Adapter files cannot hold authority.** Rules stated only in `AGENTS.md`, `.claude/CLAUDE.md`, `.github/AGENTS.md`, `.cursor/rules/`, `.windsurf/rules/`, or `.augment/rules/` must canonicalise into a T0–T3 source. Adapter files are pointer-only delegates with length caps enforced by `check-adapter-parity.js` (D-DG-11).
## Enforcement
Status legend: **Live** = wired today. **Planned (Phase N)** = scheduled in the docs-guide redesign plan and not yet enforcing.
| Mechanism | Trigger | Script / Tool | Status |
| --------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------- | ----------------- |
| CI check – catalog freshness | PR to `docs-v2` or `main` | `.github/workflows/validator-maintenance-check-catalogs.yml` | Live |
| CI generate – catalog auto-update | Push and dispatch | `.github/workflows/generator-maintenance-generate-catalogs.yml` | Live |
| CI dispatch – catalog repair | Manual dispatch | `.github/workflows/dispatch-maintenance-check-catalogs.yml` | Live |
| Scheduled drift – governance map | Schedule + dispatch | `.github/workflows/validator-governance-check-governance-map.yml` | Live |
| Scheduled drift – data freshness | Schedule + dispatch | `.github/workflows/audit-health-scan-data-freshness.yml` | Live |
| Pre-commit – file deletion guard | Staged deletion of any governed file | `.githooks/pre-commit` (deletion gate) | Live |
| CI check – frontmatter contract | PR to `docs-v2` or `main` | `operations/scripts/validators/governance/compliance/check-docs-guide-contract.js` | Planned (Phase 2) |
| CI check – decision registry | PR + daily | `operations/scripts/validators/governance/compliance/check-decisions-registry.js` | Planned (Phase 4) |
| CI check – policy consumers | PR touching `policies/**` or `standards/**` | `operations/scripts/validators/governance/compliance/check-policy-consumers.js` | Planned (Phase 7) |
| CI check – adapter parity | Pre-push + PR touching adapter files | `operations/scripts/validators/governance/ai/check-adapter-parity.js` | Planned (Phase 9) |
| CI check – canonical citation | PR open / sync | `operations/scripts/validators/governance/compliance/check-canonical-citation.js` | Planned (Phase 9) |
## Exceptions
* **`docs-guide/_workspace/`** – exempt from frontmatter contract and naming rules; governed by `workspace-lifecycle-policy.mdx`.
* **`docs-guide/catalog/`** – files are generated and exempt from `consumers:` blocks; their `generator:` frontmatter is mandatory instead.
* Legacy files in `_workspace/archive/` during their 90-day TTL window are exempt from naming enforcement.
## Related
* [Decisions registry](../decisions/registry)
* [Docs guide structure decision log](../decisions/docs-guide-structure)
* [Workspace lifecycle policy](workspace-lifecycle-policy)
* [Generated artifact and hook governance](generated-artifact-and-hook-governance)
* [Root allowlist governance](root-allowlist-governance)
* [V2 folder governance](v2-folder-governance)
* [Frontmatter standard](../standards/frontmatter)
* [Naming conventions](../standards/naming-conventions)
* [Ownerless governance](ownerless-governance)