Documentation is organized by responsibility: each category answers one primary class of question. When a summary disagrees with the canonical design spec, the spec wins and the summary is a bug.
| Category | Answers | Start here |
|---|---|---|
| concepts/ | What OpenStrata is and the ideas it is built on. | overview.md |
| projects/ | The reference projects (real downstream repositories) and the cross-repository ecosystem. | README.md |
| architecture/ | How the current system is structured (crates, domain model, on-disk layout). | overview.md |
| guides/ | How to accomplish a task (command tour, migrations). | examples.md |
| reference/ | Factual contracts: --json output, schemas, exit codes. |
json-output.md |
| roadmap/ | What is planned next (only incomplete work). | README.md |
| releases/ | Immutable per-version release records. | README.md |
| design/ | Why significant decisions were made (proposed / accepted / superseded). | README.md |
| reports/ | Evidence from real runs (incidents, dogfooding). | reports/ |
| contributing/ | Contributor procedures: documentation and releases. | README.md |
design/spec.md is the long-form canonical specification. The category documents above are navigable, current-state summaries that track what is actually implemented; the spec is the source of truth when they disagree.
The documentation is being reorganized in phases (see the reorg plan). Category
boundaries are established; the roadmap is decomposed into
current / backlog with per-version release records and a
delivery history holding the granular detail.
Architecture is split into overview + crates; the
reference CLI / exit-code / schema / support-matrix pages are
generated from source (ost internal docs generate) with a CI drift check; and
link, consistency (crate inventory / version / roadmap state), and hygiene checks
run in CI. Remaining: a documentation
website.