Durable design documentation for Rome. For the rules used when writing docs, see CLAUDE.md.
VISION.md(repo root) — why Rome exists, posture constraints, scope.domains/— the shared language for chats, accounts, agents and connections, one file per context, with the context map. authoring/domains.md defines the family.concepts/— entity definitions outside those contexts. The single source of truth for what each remaining term means.architecture/— the components on each surface and the invariants binding them.adrs/— records of standing decisions, one file per decision keyed by filename. authoring/adrs.md defines the family.authoring/— the rulebook for each content type (docs, PRs, issues, ADRs, design tokens, code comments, CLAUDE.md files) plus the cross-cutting prose rules.northstars/— ideal-state docs, one per area: what should be true, checked against the codebase by theloop-reconcileskill.ui/— the design token docs, one directory per kind of token. authoring/ui-tokens.md holds the rules they share.
Other top-level files in docs/ are operational references paired with the surface they document — design-system.md, ui-kit.md, dashboard-mock-mode.md, concierge-eval.md, releases.md, self-hosting.md, personal-data.md, vault.md, observability/. Rome Cloud deployment operations live in the private amantru/rome-cloud repository.
In AI-coding workflows the bottleneck is the cost of communication, not the cost of producing code. The context code derives from — why Rome exists, what the system promises, what each term means — has to live in the repo, where AI reads it. Docs capture that context durably.
Docs state what is true now. ADRs record why each standing decision was made and what it rejected. Keeping the why separate keeps the load-bearing context free of stale designs.