# Style Invariants

- Maximum line length is 80 characters.
- Markdown and RST files must respect the 80-character line-length
  limit.
- Keep changes minimal and focused on the requested scope.
- Preserve existing naming and structure unless change is required.
- Do not introduce unrelated refactors in the same patch.
- Keep API and UI terminology aligned with `contract.md`.
- Prefer explicit, descriptive names over abbreviations.
- Do not add inline comments unless needed for non-obvious logic.

## Docstring Rules

- Every source file must have a module-level docstring explaining
  what the file does.
- Every Python function must have a docstring.
  - Route handlers: audience is the API user; use Markdown.
    Separate internal developer notes with a line containing `---`.
  - All other Python: Sphinx style (`:param:`, `:returns:`,
    `:raises:`).
  - TypeScript: JSDoc style.
- Every test function must have a docstring starting with
  "Ensure…" that describes the behaviour being verified.

## Environment Variables

All environment variables must use the `DOCROOT_` prefix and be
declared as fields in `app.settings.Settings`. Never read
environment variables directly via `os.environ` or `os.getenv`.