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

# Documentation Item Model

> Frozen contract for documentation governance execution. Classification taxonomy, naming convention, metadata specification, and enforcement model for all documentation items in this repo.

# Documentation Item Model

Frozen contract for all documentation governance execution. Do not modify without a new HUMAN REVIEW decision.

Source of truth for: classification taxonomy, naming convention, metadata specification, enforcement model.

***

## Classification Taxonomy

Every documentation item in this repo is classified with three fields: `<docType> / <concern> / <format>`.

### docType

| docType             | What it is                                                   |
| ------------------- | ------------------------------------------------------------ |
| `policy`            | Enforced rule or contract, gate-owned                        |
| `framework`         | Decision model or taxonomy, guidance-level                   |
| `catalog`           | Generated inventory of a repo surface                        |
| `feature-map`       | Narrative overview of a repo capability                      |
| `tooling-ref`       | Reference for a tool, CLI, or workflow                       |
| `contributor-guide` | Procedural guide for human contributors                      |
| `ai-adapter`        | Per-system AI instruction file                               |
| `ai-rule`           | Standalone AI protocol or safety rule                        |
| `registry`          | Machine-readable data file (consumed by automation)          |
| `secrets-ref`       | Environment variable and secrets documentation               |
| `template`          | Reusable authoring template                                  |
| `component`         | UI component, governed by component JSDoc spec (separate)    |
| `script`            | Operational script, governed by script JSDoc spec (separate) |

### concern

Inherits from the script taxonomy. Homogeneous across all item types.

| Concern      | What it covers                                                  |
| ------------ | --------------------------------------------------------------- |
| `content`    | Docs pages, copy, authoring standards, page taxonomy, veracity  |
| `components` | Component library, registry, naming, documentation              |
| `governance` | Repo structure, scripts, agent docs, manifests, catalogues      |
| `ai`         | AI tooling, agent rules, adapter files, skills, discoverability |

### format

| Format | Extension(s)    | Metadata approach                                   |
| ------ | --------------- | --------------------------------------------------- |
| `mdx`  | `.mdx`          | YAML frontmatter                                    |
| `md`   | `.md`           | YAML frontmatter                                    |
| `mdc`  | `.mdc`          | YAML frontmatter                                    |
| `json` | `.json`         | Registry-only (no inline metadata)                  |
| `yaml` | `.yml`, `.yaml` | Registry-only                                       |
| `jsx`  | `.jsx`          | Component JSDoc spec (pre-existing, not overridden) |
| `js`   | `.js`           | Script JSDoc spec (pre-existing, not overridden)    |

***

## Directory Convention

**Locked (D1):** Concern is expressed as a sub-folder within type folders, not as a file prefix.

Applies to: `policies/`, `frameworks/`, `features/`, `tooling/`

**Exception:** Catalogue files in `docs-guide/catalog/` stay flat. Concern is expressed as a filename prefix.

***

## Metadata Specification

### Required fields for MDX/MD/MDC files

```yaml theme={"theme":{"light":"github-light","dark":"dark-plus"}}
consumer: [human | agent | automation]
maintenance: generated | hand-maintained | mixed
status: active | draft | deprecated
```

### Conditional fields

```yaml theme={"theme":{"light":"github-light","dark":"dark-plus"}}
generator: path/to/script.js      # required if maintenance = generated or mixed
validator: path/to/script.js      # required if maintenance = hand-maintained or mixed
lastVerified: YYYY-MM-DD          # required if maintenance = hand-maintained
```

### JSON, YAML, ENV files

Registry-only. No inline metadata. Every file of these formats must have a corresponding entry in the governance documentation catalogue.

### JSX, JS files

Pre-existing governance specs apply (component JSDoc 7-tag, script JSDoc 11-tag). This model does not override them.

***

## Enforcement Summary

| Format                  | Gate                     | Mechanism                           |
| ----------------------- | ------------------------ | ----------------------------------- |
| `.mdx` in `docs-guide/` | `pr-changed` (soft gate) | Required fields check               |
| `.md` adapter files     | None currently           | Manual until Phase 5 validator      |
| `.mdc` Cursor rules     | None currently           | Manual until Phase 5                |
| `.json` registry files  | None currently           | Catalogue entry validator (Phase 5) |
| `.jsx` components       | `pre-commit` (existing)  | Component registry validator        |
| `.js` scripts           | `pre-commit` (existing)  | `script-docs.test.js`               |