Artefacts and authority

Every project uses the same documentation architecture. The names are plain; the boundaries are strict. A reader should know where a fact belongs before reading the fact itself.

The documentation set

The brief becomes non-normative when accepted rules exist. The product reference then becomes the front door. It points to module references for detail, module work registers for progress, and decision records for technical means.

Product, module, delivery

product reference             what the whole product is
  └─ module reference         what one module means and must do
       └─ work register       what is planned, active or shipped

The split prevents the most common documentation failure: changing a requirement because a story shipped, or reading a planned story as though it were already a business rule.

Repository shape

Use the repository's existing module boundary. Do not create a second module tree merely for documentation.

docs/
  index.html                  canonical product reference
  delivery-plan.md            cross-module sequence, gates and demonstrations
  scenarios/                  end-to-end cross-module narratives
  decisions/                  architecture decision records

<module>/docs/
  index.html                  module reference and functional requirements
  work-register.md            WBS epics, requirement links and delivery status

CONTRIBUTING.md               repository mechanics and coding conventions

index.html is the published form used by the reference implementation. A project may author Markdown or MDX and generate it. The authority role matters; the source extension does not.

Root and module indexes have stable shapes

The product reference always presents:

1. Overview
2. Actors
3. Domain model
4. Modules
5. Architecture
6. Journeys
7. Open questions
8. Vocabulary

Each module reference always presents:

1. Overview
2. Actors
3. Domain model
4. Open questions or decisions
5. Functional requirements

Stable reading order is a developer-experience feature. A developer moving from one project or module to another should not have to rediscover where requirements or unresolved decisions live.

Assign authority once

Every other document links to the owner. It does not paraphrase it. A copied enumeration, actor, status or rule is already a second authority.

Installing into an existing repository

1. Scan for documents already doing one of these jobs.
2. Adopt the existing owner or write a migration proposal; never create a rival.
3. Add only missing structure, initially as headings and authority links.
4. Make each new document authored immediately; no generator rewrites accepted product rules.
5. Run the documentation checks after changing the set.