# docs/ File Schema

Every file in `docs/` must have YAML frontmatter. This is enforced by `validate_doc.py`.

## Frontmatter Fields

```yaml
---
title: Human Readable Title          # required — clear, descriptive
scope: kebab-case-identifier         # required — unique slug for this doc
category: reference                  # required — see valid values below
version: 1.0.0                       # required — semver (x.y.z)
updated: 2026-03-18                  # required — ISO date of last update
description: "One-line summary"      # optional
source_of_truth_for:                 # optional — glob patterns this doc describes
  - "hooks/**/*.mjs"
  - "policies/*.json"
domain: [hooks, claude, policy]      # optional — cross-cutting tags
---
```

## Required Fields

| Field | Type | Description | Example |
|-------|------|-------------|---------|
| `title` | string | Clear, descriptive title | "Hooks Reference" |
| `scope` | string | Unique kebab-case slug | "hooks" |
| `category` | enum | Document type | "reference" |
| `version` | semver | x.y.z — bump on every update | "1.2.0" |
| `updated` | date | YYYY-MM-DD of last change | "2026-03-18" |

## Category Values

| Value | Purpose |
|---|---|
| `reference` | Look-up table, cheat sheet, technical spec |
| `guide` | Step-by-step how-to documentation |
| `architecture` | System design and component overview |
| `api` | API contracts, interfaces, schemas |
| `plan` | Implementation plan or roadmap |
| `overview` | Summary introduction to a subsystem |

## Optional Fields

### source_of_truth_for
A list of glob patterns (fnmatch syntax) pointing to the source files this doc describes. Used by `drift_detector.py` and `doc_structure_analyzer.py` to detect when the source changed but the doc wasn't updated.

```yaml
source_of_truth_for:
  - "hooks/**/*.mjs"
  - "policies/*.json"
  - "packages/pi-extensions/extensions/**/*.ts"
```

### domain
Tags for cross-cutting concerns. Useful for searching related docs.

```yaml
domain: [hooks, claude, pi, enforcement]
```

## Version Bumping Rules

| Change | Bump |
|---|---|
| Fix a typo or outdated detail | `patch` (1.0.0 → 1.0.1) |
| Add a new section | `minor` (1.0.0 → 1.1.0) |
| Full rewrite or restructure | `major` (1.0.0 → 2.0.0) |

Always update `updated:` to today's date alongside the version bump.

## INDEX Block

`validate_doc.py` auto-generates a navigation table from `##` headings:

```markdown
<!-- INDEX: auto-generated by validate_doc.py — do not edit manually -->
| Section | Summary |
|---|---|
| [Overview](#overview) | ... |
| [Hook Events](#hook-events) | ... |
<!-- END INDEX -->
```

This block is regenerated every time `validate_doc.py` runs on the file. Do not edit it manually.

## Complete Example

```yaml
---
title: Hooks Reference
scope: hooks
category: reference
version: 1.1.0
updated: 2026-03-18
description: "All hook events, scripts, and behavior for the xtrm plugin"
source_of_truth_for:
  - "hooks/**/*.mjs"
  - "policies/beads.json"
  - "policies/main-guard.json"
domain: [hooks, claude, enforcement]
---
```
