Documentation #

Start with DESIGN.md: what the suite is, what it promises, how it is built, and a map of every other document.

Directory	What is in it
design/	Suite-wide design: rules and mechanisms every part obeys (storage, identity, sharing, JMAP, DAV, web apps, …).
areas/	What users get, end to end, across services and web apps: mail, calendar, contacts, files, accounts, administration, migration.
engineering/	How the code is written, built and tested.
operations/	How an install is stood up, upgraded and run.
developers/	The guide for people who write applications against an install: discovery, registration, sign-in and the files and photos JMAP API, with executed examples and JSON Schemas. Standalone: it links no other document.
specs/	Pinned texts of the standards the design depends on.

What is still missing lives outside docs/: NEXT.md.

Rules for these documents #

• One fact, one home. Documents are organised by what the suite does, not by service, application or package. A document says how another document's rule applies and links to it; it does not restate it.
• Present tense, the system as it is and as decided. Decided but unbuilt work is marked (decided, not built). No status lines, dates, correction notes, branch names or work-item ids. Git keeps the history.
• A correction rewrites the text. Nothing is struck through or annotated.
• Code never cites these documents. Source comments cite standards texts only (conventions).
• Packages each have one README.md beside the code: purpose and API.