# Documentation Freshness Guide

> "Stale docs = hallucinating AI." — Monika Voutov, BoardKit Orchestrator

VK is agent-first. When docs are wrong, agents make wrong decisions. This guide ensures project documentation stays current.

## Doc Steward Workflow

### When to Update Docs

| Trigger                      | What to Update                          |
| ---------------------------- | --------------------------------------- |
| New API endpoint added       | README API section, relevant route docs |
| Schema change (shared/types) | Type documentation, API examples        |
| New CLI command              | CLI README, help text                   |
| Config option added/changed  | Settings docs, example configs          |
| New feature shipped          | README features section, changelog      |
| Architecture change          | Architecture docs, diagrams             |
| Bug fix with user impact     | Known issues, changelog                 |
| Dependency upgrade           | Requirements section if version matters |

### Doc Update Checklist

When completing a task that changes user-facing behavior:

- [ ] README.md updated (if applicable)
- [ ] API route documented (JSDoc + route comments)
- [ ] CLI help text accurate
- [ ] Type documentation matches implementation
- [ ] CHANGELOG.md updated
- [ ] Examples/templates still work
- [ ] AGENTS-TEMPLATE.md updated (if agent-facing API changed)

### Where Docs Live

| Doc                                | Purpose                  | Owner           |
| ---------------------------------- | ------------------------ | --------------- |
| `README.md`                        | Public-facing overview   | Any contributor |
| `docs/`                            | Detailed guides & specs  | Feature author  |
| `CHANGELOG.md`                     | Release history          | Release manager |
| `docs/AGENTS-TEMPLATE.md`          | Agent integration guide  | Agent team      |
| `docs/multi-agent-git-workflow.md` | Multi-agent coordination | Agent team      |
| JSDoc in source files              | API contracts            | Feature author  |

### Freshness Indicators

Each doc should include a freshness header:

```markdown
<!-- doc-freshness: 2026-03-25 | v4.0.0 | @veritas -->
```

Format: `date | version | last-updater`

When a doc is older than the current version, it may need review.

### Last Sweep

| Date       | Scope                                                               | Agent   |
| ---------- | ------------------------------------------------------------------- | ------- |
| 2026-08-22 | v6.1.1 maintenance, dependency, release, upgrade, and evidence docs | Release |
| 2026-07-26 | v6.1.0 roadmap, harness, governance, knowledge, and release docs    | Release |
| 2026-07-24 | v6.0.2 desktop recovery, version support, release, and evidence     | Release |
| 2026-07-24 | v6.0.1 stabilization, release, upgrade, API, MCP, and evidence      | Release |
| 2026-07-24 | v6.0.0 harness, Buzz, release, upgrade, compatibility, and evidence | Release |
| 2026-07-12 | v5.2.2 UI-audit fixes, release gates, desktop state, and evidence   | Release |
| 2026-06-05 | v5.0.0 stable release docs, install paths, release assets, RC notes | Codex   |
| 2026-03-25 | Full v3→v4 version references, governance docs, CHANGELOG, examples | VERITAS |
| 2026-03-21 | v4.0 release documentation                                          | TARS    |

## Automation Plan

### Phase 1: Manual (Current)

- Doc update checklist in PR template
- Freshness headers in docs
- Agent instructions include "update docs" step

### Phase 2: Hook-Based

- Lifecycle hook on `task.done` checks for doc-related files
- If code changes but no doc changes, create a follow-up task
- Use `docs/` path detection in git diff

### Phase 3: AI-Powered Doc Steward

- Dedicated "doc steward" agent type
- Subscribes to all `task.done` events
- Reads recent commits, identifies doc gaps
- Creates tasks with specific update suggestions
- Low-priority, runs during idle time

### Hook Configuration

```bash
# Create a doc freshness hook
curl -X POST /api/hooks -d '{
  "name": "Doc freshness check on completion",
  "event": "task.done",
  "action": "custom",
  "config": {
    "customAction": "check_doc_freshness",
    "description": "Verify docs were updated if code changed"
  }
}'
```

## Repo Rules

The root `AGENTS.md` is canonical. `docs/AGENTS-TEMPLATE.md` is the reusable
project template, and harness-specific files only supplement the canonical
rules. Key rules:

1. **Always update docs alongside code** — no code-only PRs for user-facing changes
2. **Use freshness headers** — every doc starts with `<!-- doc-freshness: ... -->`
3. **JSDoc is documentation** — route handlers and services must have JSDoc
4. **Examples must work** — if you change an API, update the examples
5. **CHANGELOG is mandatory** — every release gets an entry

## Credit

This approach is inspired by [Monika Voutov's BoardKit Orchestrator](https://github.com/BoardKit/orchestrator), which emphasizes that documentation quality directly impacts AI agent reliability. Credit: @mvoutov