Deep dive
Write once. Generate everything.
One file holds every fact about the lab. Everything else is derived from it.
The most dangerous documentation failure is not missing docs — it is divergent ones. When the same fact lives in three places, all three drift at different rates, and eventually nobody can say which to trust. The answer in this lab is structural: one file holds every fact, and every other representation of the lab is generated from that file. Consistency is not a discipline enforced by habit; it is enforced by the pipeline.
One file, by design
inventory.yaml is the only artifact in the Describeboundary that a human hand-edits. It holds the complete factual record: every compute host, every network segment and VLAN, every service running on every container, every known issue. The scope is deliberate and the boundary is absolute — if a fact about the lab does not live here, it does not live anywhere authoritative.
Adding a host, adjusting a VLAN assignment, logging a new known issue: in each case the action is a single YAML edit. Every downstream representation updates on the next pipeline run. There is no second catalog to keep in sync, because there is no second place where the data lives.
Views, not copies
Three generated representations derive from inventory.yaml, each for a different audience and purpose.
The reference docs are human-readable markdown files: one per host, cross-referencing VLANs, containers, and issues. They carry a GENERATED FROM inventory.yaml header and are never edited by hand. They are the rendered form of the YAML, not an independent source.
The architecture diagram is a multi-frame Excalidraw scene: an overview slide, one detail slide per host, a planned-infrastructure slide, and a known-issues legend. The layout, routing, and slide count are all computed from the YAML. Add a host and a new frame appears. Fix an issue and the legend updates. The generator derives coordinates from box geometry so routes recalculate automatically when the inventory changes.
The publish projection (the structured data driving this site) is generated by an allowlist filter from the same source. Only fields explicitly marked publishable cross the boundary; everything else is private by default. The public build never touches inventory.yaml directly. It is just another generated view, produced by a stricter filter with an independent tripwire that scans output for anything secret-shaped.
Add a host once. It appears in the docs, the diagram, and the public site — or nowhere at all.
All three are outputs, not sources. Editing any of them directly is editing a shadow that will be overwritten on the next run.
Determinism is not an accident
The pipeline is deterministic by design. Generators derive IDs and ordering from the data itself, not from timestamps, random seeds, or insertion order. Two runs of the pipeline against the same inventory.yaml produce byte-identical output.
This matters for version control. A meaningful git diff in the generated files reflects a meaningful change in the underlying data. There is no noise: no float-coordinate churn from an editor reopening a file, no reordered keys from a non-stable serializer. When the diagram changes in a commit, it is because the YAML changed. The diff is readable and trustworthy because the generator is stable.
Coherence enforcement
A coherence checker enforces that every artifact has exactly one home and that generated files are never hand-edited. The generated files carry a machine-readable header. Editing one is silent until the next pipeline run, at which point the edit is overwritten. There is no warning — the consequence of working around the system is that the work disappears.
The pipeline order is fixed: validate, then render, then diagram. Each stage must pass before the next runs. A YAML change that fails the schema or cross-field checks goes nowhere.
One pipeline, one direction
Operate reads inventory.yaml through a single entry point,load_inventory(), and never forks or shadows the data. It does not maintain its own host list, its own service registry, its own issue tracker. The inventory interface is read-only by contract.
When Operate needs to record something back — a host configuration change, an issue resolved — it may only do so through the gated write pipeline: validate, render, diagram, tests, then a human commit. There is no shortcut. Operate cannot close the loop autonomously; the pipeline runs, the tests must pass, and a human makes the commit. The data flows in one direction, and the write path is gated at every step.
The payoff is simple: there is no drift, because there is no second place to drift to. There is no question of which catalog is current or which view of the infrastructure to believe. There is one place to change anything, and a mandatory downstream that keeps every view in agreement. The architecture diagram, the reference docs, the public site, and the operator's working data are all the same fact, rendered differently.