# Agent Documentation Standard

This document describes the frontmatter schema for agent documentation files in `docs/agent/`.

## Overview

Agent documentation files use YAML frontmatter to enable tooling-based discovery and routing. This standard is enforced by `dot-agent docs validate`.

## Frontmatter Schema (v1)

Every markdown file in `docs/agent/` (except `index.md` files) must have frontmatter with these fields:

```yaml
---
title: Document Title
read_when:
  - "condition when agent should read this"
  - "another condition"
---
```

### Required Fields

| Field       | Type         | Description                                   |
| ----------- | ------------ | --------------------------------------------- |
| `title`     | string       | Human-readable document title                 |
| `read_when` | list[string] | Conditions when an agent should read this doc |

### Example

```yaml
---
title: Plan Lifecycle
read_when:
  - "creating a plan"
  - "closing a plan"
  - "understanding plan states"
---
# Plan Lifecycle

Content goes here...
```

## Directory Structure

```
docs/agent/
├── index.md              # Auto-generated, lists categories + uncategorized
├── glossary.md           # Uncategorized until siblings exist
├── planning/
│   ├── index.md          # Auto-generated when 2+ docs
│   ├── lifecycle.md
│   └── enrichment.md
└── cli/
    ├── index.md
    └── output-styling.md
```

### Principles

- **Categories emerge, not prescribed** - Create subdirectory when 3+ related docs exist
- **Uncategorized docs allowed** - `docs/agent/*.md` is valid until categorization is clear
- **Relative links within docs/agent/** - Resilient to reorganization
- **No `category` field** - Directory location IS the category (single source of truth)

## Commands

### Validate

Check all docs have valid frontmatter:

```bash
dot-agent docs validate
dot-agent docs validate --verbose  # Show all files, not just errors
```

### Sync (Future)

Regenerate index files from frontmatter:

```bash
dot-agent docs sync
```

## Index Files

Index files (`index.md`) are auto-generated and should not be manually edited. They are:

- Skipped during validation
- Generated by `dot-agent docs sync`
- Contain tables built from frontmatter `read_when` fields

### Root Index Format

```markdown
# Agent Documentation

| Category               | Documents                       |
| ---------------------- | ------------------------------- |
| [planning/](planning/) | lifecycle, enrichment, workflow |
| [cli/](cli/)           | output-styling, script-mode     |

## Uncategorized

| Document                   | Read when...              |
| -------------------------- | ------------------------- |
| [glossary.md](glossary.md) | understanding terminology |
```

### Category Index Format

```markdown
# Planning Documentation

| Document                       | Read when...                    |
| ------------------------------ | ------------------------------- |
| [lifecycle.md](lifecycle.md)   | creating a plan, closing a plan |
| [enrichment.md](enrichment.md) | enriching a plan                |
```
