Problem
The repository has extensive feature documentation, but breadth makes it difficult for contributors to determine authoritative modules, runtime boundaries, data ownership, supported paths, and the tests required for a change. Stale or aspirational statements can look equivalent to implemented contracts.
Scope
- Create a concise system map covering runtimes, data/control flow, trust boundaries, authoritative stores, schemas, and sibling repositories.
- Add task-oriented change maps: where to modify ingestion, features, models, APIs, contracts, configuration, migrations, and deployment.
- Mark documentation as implemented, experimental, planned, or deprecated and link planned work to issues.
- Generate API/config/schema sections where possible and validate links/code snippets.
- Add architecture decision record conventions and ownership/reviewer guidance.
- Provide contributor journeys for a first fix, new detector, schema change, migration, and production-affecting feature.
Acceptance criteria
- A new contributor can identify code, tests, docs, and compatibility checks for each journey without tribal knowledge.
- Diagrams are source-controlled and checked for stale paths.
- CI fails on broken links, invalid snippets, schema drift, and undocumented public configuration.
- Roadmap claims link to current issues and shipped work links to releases.
- Maintainers identify one canonical document per architecture/configuration/operations topic.
Problem
The repository has extensive feature documentation, but breadth makes it difficult for contributors to determine authoritative modules, runtime boundaries, data ownership, supported paths, and the tests required for a change. Stale or aspirational statements can look equivalent to implemented contracts.
Scope
Acceptance criteria