Conventions

Coding and repository conventions used across Core packages.

For coding standards (PSR-12, naming, git), see L4 Coding Conventions.

Documentation Layers

core.docs is organized in four layers. Each layer answers a different question and changes at a different pace. Put content in the right layer — do not duplicate across layers.

Layer	Question	Content	Changes When

L1 — Scope	What & why	Vision, service overview, ecosystem map, conventions	Rarely
L2 — Architecture	How (decisions)	Data models, flows, protocols, system contracts	Architectural decisions are made
L3 — Roadmap	What's next	Task lists, sprints, phases per module	Weekly/daily
L4 — Code	What exists	Code inventory: file structures, per-file API surface, env/config	Code changes

The rule of thumb: filesystem-level and lower-level content (file trees, functions per file, per-file functionality) belongs in L4, never in L1/L2. L2 documents decisions; L4 documents what the code looks like today.

L3 Standard Layout

Every module roadmap uses:

1. Current State — short audit: built / stubbed / not started (one paragraph + link to L4)


2. Dependencies — table of other modules this one relies on


3. Current Sprint — active tasks


4. Backlog — phased future work


5. Completed — done items (with dates when notable)

L4 Standard Layout

Each module's code reference mirrors its repository:

04-L4-code/NN-module/

  index.md            — curated overview, repo info, key usage examples

  00-init/

    structure.md      — file/folder tree, one-line purpose per node

    environment.md    — env vars, secrets locations, config files

    setup.md          — install/bootstrap steps (where relevant)

  01-files/

    <mirror of the repo source tree — one .md per file>

• index.md is curated prose (hand-written, stable).


• 00-init/structure.md is mechanically regeneratable (tree + one-liners) — refresh during any doc pass.


• 01-files/ is the systematic mirror — one doc per source file.

L4 Per-File Doc Template

---

file: src/path/to/File.php

date_updated: 2026-07-17

updated_by: Sto (model) or Olivier

lines: 110

---



# File.php



## Description

What the file does, 2–4 lines.



## Classes

- ClassName (final) — one-liner



## Functions/Methods

- methodName(signature): string — one-liner (skip if self-identifiable)



## Includes/Dependencies

- What it imports/calls



## Notes

- Gotchas only

Budget: ≤25 lines per file doc. If a file needs more, either the file is too complex or the doc is duplicating code comments.

Exclusions: mirror only hand-written source. Never document vendor/, node_modules/, .git/, generated or build output.

Grouping: trivial files of the same kind (icons, simple assets) get one grouped doc per folder instead of one doc each.

Drift management: file docs carry date_updated + updated_by (person or model). They are refreshed when the file's API surface changes (classes/functions added, removed, renamed) — not on every commit. A doc that looks stale can be flagged by comparing date_updated to the file's last git change.