Source of truth for how this project is structured, named, and decided. Code is the source of truth for behavior — these docs only capture what isn't obvious from reading src/.
| Path | Contains |
|---|---|
| architecture/ | What the system IS now — stack, components, data pipeline |
| concepts/ | Vocabulary — vehicle, buckets, confidence, feeds, prediction |
| standards/ | MUST / MUST NOT rules — short, enforceable |
| specs/ | Contracts where the reasoning isn't in the code |
| plan/ | Roadmap and in-flight design — short-lived |
| investigation/ | Historical analyses and the frozen v1 docs |
- Every directory has a
README.mdthat links its contents. - Files use lowercase kebab-case;
README.mdis the only uppercase file. - Cross-references use relative paths to the smallest useful target.
- Anything that becomes obvious from code or grows stale is deleted, not preserved.
- See standards/documentation.md for the placement rules.
Start at ../AGENTS.md for the canonical agent guide, then:
- architecture/system-overview.md — what does the system do.
- concepts/ — what does this term mean.
- standards/ — what is the rule.
- plan/ — what are we building next.
- The actual code — specs only exist where reasoning isn't there.