One file. Everything else generated.

The Describe boundary is the most constrained of the three. It touches no infrastructure. It holds no credentials. It does not deploy, configure, or change anything. What it does is draw the shape of the lab with enough precision that every other boundary can reason about it confidently — and then it enforces that shape so aggressively that the drawing never drifts.

One file holds the facts

A single YAML file, inventory.yaml, is the canonical record of the lab: every compute host, every network segment and VLAN, every service, every routing decision, every known issue. Nothing else holds this data. If a host is added, it is added there. If a service changes, the YAML changes. If something breaks in a documented way, the issue is recorded there with an integer identifier and referenced by the artifacts that depend on it.

The file is the authoritative answer to "what does the lab look like right now?" — and the rest of this boundary exists solely to render that answer into forms people and tools can consume. There is no second database, no wiki table to keep in sync, no diagram someone updates by hand after the fact.

Generated views, not authored documents

Everything downstream of inventory.yaml is generated. Human-readable reference documentation is produced by a renderer that walks the YAML and emits Markdown files — one per host, one per logical grouping. The architecture diagram is a multi-frame Excalidraw scene: an overview frame, one detail frame per compute host, a planned-state frame, and a known-issues legend. All computed from the same source file, in the same pass, without additional authoring.

A deterministic pipeline

The pipeline runs in three steps. Validate loads the YAML against its schema and runs cross-field checks: dangling issue references, invalid cross-links, structural constraints the schema alone cannot express. Render walks the validated data and writes the reference Markdown. Diagram consumes the same data and emits the full Excalidraw scene.

Determinism is not incidental here — it is a constraint. IDs and layout seeds are derived, not random. Two runs on the same input produce byte-identical output. Generated files therefore yield clean diffs: any change in the output corresponds exactly to a change in the YAML, and nothing else. A commit that touches only generated files, with no upstream YAML change, is a sign that something went wrong.

Two runs, same input, byte-identical output.

Coherence by construction

The hardest property to maintain in a documentation system is not accuracy at creation time; it is coherence over time. Describe addresses this structurally rather than by convention. Generated files carry a "GENERATED FROM inventory.yaml" header at the top. A coherence checker enforces that every artifact has exactly one home and that no file has drifted outside that expectation. Any hand-edit to a generated file is silently overwritten the next time the pipeline runs. The rule is not something you might forget; it is a mechanism.

The result is a system where the question "is the documentation accurate?" collapses into a simpler question: "is inventory.yaml accurate?" There is no delta to chase, no stale copy to reconcile, no second source that might contradict the first.

Data flows outward from this boundary, not inward. The Operate boundary reads inventory.yaml through a defined entry point and never shadows or forks the data. Describe does not receive writes from Operate directly — any update Operate makes flows back through the same gated pipeline: validate, render, diagram, tests, commit. Thedeep dive into the source of truth unpacks the full schema and what each section contains.