# Documentation audit — 2026-07-10

Manual pass over `docs/`, all READMEs, and glossary. Goal: correct links, unify T0–T4 vocabulary, align rsync/offload wording with code, improve readability.

## Summary

| Metric | Result |
| --- | --- |
| Markdown files checked | 33 |
| Broken relative links (after fixes) | 0 |
| Glossary `###` anchors added | 15 (T0–T4, layers, bulk sync, source of truth, …) |
| Open questions added | §12–§14 (tooling, DuckLake, `schemas/`) |

## Findings fixed

### Links

- `infra/terraform/ground/README.md` pointed at non-existent `03-storage-design.md` → `03-data-platform.md`.
- `11-cicd-delivery.md` bare cross-reference to doc 05 → proper markdown link.

### Factual drift (code vs docs)

| Item | Was | Now (matches `broadcast.py`, `sim.ts`) |
| --- | --- | --- |
| Pose frame | ~40 bytes, uint16 `drone_id` | 46 bytes, 8-byte ASCII `drone_id` |

### Terminology

- Extended [00 — Glossary](../00-glossary.md) with T0–T4, architecture layers, pipeline stages, source of truth.
- Disambiguated design journey §4: pipeline stages ≠ storage floors.
- Roadmap Stage 7: rsync bulk path, not “MinIO replication”.

### rsync / rclone / offload

| Path | Canonical tool |
| --- | --- |
| Peer bulk sync | rsync over SSH |
| Dock offload | rsync or `mc mirror` |
| S3 backends (optional) | rclone |
| Sim CronJob | `cp -ru` + `mc mirror` (documented shortcut) |

### Live demos (design journey)

- [swarm.produktor.io](https://swarm.produktor.io/) — visual prototype
- [swarm-data-explorer.produktor.io](https://swarm-data-explorer.produktor.io/) — SQL explorer
- [swarm-analalytics.produktor.io](https://swarm-analalytics.produktor.io/d/swarm-fleet/swarm-fleet-e28094-generated-data?orgId=1&refresh=5s) — Grafana fleet dashboard

### README / LICENSE

- Restricted-use notice with link to [LICENSE](../../LICENSE).
- Component READMEs tightened (caveman style).

## Remaining (documented, not bugs)

| Item | Where |
| --- | --- |
| `schemas/` directory absent | OQ §14, roadmap stage 2 |
| DuckLake undecided | OQ §13 |
| rsync bulk sync not in sim code | Design only |
| Glossary table terms link to section headers, not row anchors | Optional polish |
| T4 after “Source of truth” in glossary order | Cosmetic |
| GitOps “source of truth” vs data SSOT | Different meanings in `11-cicd-delivery` |

## Suggested CI checks (for issue #1)

Implemented in [`scripts/check_docs.py`](../../scripts/check_docs.py) — see [ci-rules.md](ci-rules.md).

## Files touched

`docs/00`–`12`, `docs/adr/*`, nine READMEs, root `README.md`.