As-built documentation. Forward-looking specs live in
plans/; this folder records what exists and why.
History lives in git and packages/lingo/CHANGELOG.md — the wiki stays
current-state only.
- Decisions — ADR-lite ledger of consequential decisions (D-numbered, offer-gated)
- Inspiration & credits — every library and repo we learned from: what we took, its license, links. Giving props is a project value.
- Conventions — naming, coding patterns, tests, commits
- API design — how the public surface evolves + the PR checklist
- Resource design — how lingo output objects are modeled and composed
- Architecture (as built) — updated as modules land
- Performance benchmarking — how to run and read the benchmarks
- Benchmarks (captured results) — dated runs and numbers
- research/ — prior-art and ecosystem research (units, dates, masking, AI structured output, LLM failure modes, provider quirks)
- Consequential decisions get a D-entry in
decisions.mdwhen they pass the offer-gate (hard to reverse / surprising / real trade-off). - New influences get an
inspiration.mdentry the moment we borrow an idea, not at release time. - Notable changes go under
[Unreleased]inpackages/lingo/CHANGELOG.mdin the same change. - When to add a wiki page: the topic is non-obvious from the code and will be needed again (the same question has come up twice). Don't add pages for things AGENTS.md already covers or for code architecture readable from source.
- When docs contradict code, the code is truth today. Fix the doc in the same change.