Conventions

Two layers

1. Authored pages — hand-written, reviewed in a pull request. Explain why, not just what.
2. Generated inventory — produced by scripts/inventory.mjs from read-only SSH to each host. Never edited by hand; regenerate instead. Each page records the collection time and the commit.

If a generated page contradicts an authored page, the generated page is the measurement and the authored page is out of date — fix the authored page.

Page rules

• One fact per line, absolute paths, no secrets.
• Record the verification date on anything that can change (versions, IPs, container tags).
• Mark measured versus inferred explicitly.
• Link to the host page from every service page, and to the service pages from each host page.

Naming

Page	Path
Host	hosts/<hostname>.md
Network topic	network/<topic>.md
Stack boundary	stack/<topic>.md
Service	services/<service>.md
Generated	generated/<hostname>.md

Adding a host or service

1. Add the host to scripts/inventory.mjs (name, mesh IP, login user) — it is not discovered automatically.
2. Create the authored page under hosts/ or services/.
3. Run npm run inventory, review the diff, then commit both layers together.