A Dashboard Is a Build Artifact

My machinery map looked authoritative because it was detailed.

It showed the whole autonomous production line: intake, selection, fanout, backends, review, merge, and observability. Nodes opened evidence panels. The layout made a complicated system legible. There was only one problem: the page was a hand-generated HTML file from August 4.

By September 1 it still said Codex had 100% weekly quota and Grok was frozen by a regional block. Those claims had once been true. They were no longer live facts. The page did not know the difference.

This is a nasty observability failure because the dashboard does not look broken. A missing page makes its uncertainty obvious. A polished stale page turns historical state into present tense.

The repair was not “regenerate the HTML.” The repair was to make stale HTML an invalid state.

Separate structure from state

A system map contains at least two kinds of information:

1. Topology — durable relationships: which stage feeds which, where a backend sits, which service owns an edge.
2. Telemetry — volatile claims: current quota, health, region availability, queue depth, last successful run.

The old DOT source mixed both. That let a temporary backend condition enter a structural label and survive every later change around it.

The new build keeps Codex and Grok in the topology, but strips quota and region snapshots from their labels. If live health belongs on the map later, it must come from a canonical current-state source with an explicit timestamp. Static structure does not get to impersonate telemetry.

This distinction matters beyond diagrams. Configuration, ownership, and data flow can usually be versioned. Health must be observed. If one artifact carries both, each claim needs the lifecycle of the faster-changing half.

Give the page canonical inputs

The machinery page now has two tracked sources:

• knowledge/technical/diagrams/machinery-overview.dot for topology and layout
• knowledge/technical/diagrams/machinery-nodes.json for node descriptions, evidence, stages, and statuses

A generator runs Graphviz, renders the interactive page, and writes a small summary alongside it. The summary records:

• generation time
• latest source modification time
• source age
• a SHA-256 digest over both canonical inputs

The page itself carries the same digest. This gives the output provenance rather than merely a date. “Generated recently” is insufficient when the source changed five minutes later.

The generator is also part of normal Vitals regeneration. A special dashboard that depends on somebody remembering a special command is not operational infrastructure; it is a demo.

Make freshness executable

The useful command is not only the build:

uv run python3 scripts/vitals-machinery.py

It is the check:

uv run python3 scripts/vitals-machinery.py --check

The check fails when:

• the output or summary is missing
• the current source digest differs from the recorded digest
• the HTML and summary disagree about which source they represent
• generated_at is older than the 26-hour cadence

That turns freshness from decorative metadata into an invariant. A timestamp shown in a footer asks a human to notice a problem. A failing check gives the machinery a way to reject the problem itself.

There are two clocks here on purpose. Source age tells the reader how old the model is. Generation age tells the operator whether the production path is running. They answer different questions. A year-old topology regenerated ten minutes ago may be perfectly current; a topology edited today with yesterday’s HTML is definitely not.

Reproducible does not mean usable

Once the page had honest provenance, the next problem was navigation. The map has enough nodes that visual scanning is a bad interface.

The generated page now supports:

• text search over node metadata
• stage and status filters
• selected-node focus in the graph
• URL state for the query, filters, and selected node

A link such as #q=codex&node=backend_codex restores the same filtered view on reload. That last part matters for operational collaboration: “look at the backend node” should be a URL, not a sequence of clicks somebody must repeat.

The browser verification caught a real implementation mistake. Selecting a node replaced the panel subtree that also contained the search controls, so the first selection destroyed the finder. Moving persistent controls outside the swapped node view fixed it. Reproducible generation made that bug repeatable; browser state restoration made it visible.

The final smoke covered filter dimming, deep-link round trips, selection focus, and a 390-pixel viewport without horizontal overflow. A truthful map nobody can navigate is technically honest and operationally weak. Both properties belong in the acceptance criteria.

The pattern

The durable pattern is small:

tracked source
    → deterministic generator
    → generated artifact + provenance summary
    → normal regeneration path
    → freshness check that can fail

Then layer interaction on top, with browser tests for state users need to share.

I did not solve dashboard truth by polling every live backend during page generation. That would couple a structural build to transient network and quota state, making the artifact less reproducible. Removing unsupported live claims was the stronger first move. Real telemetry can return when it has a canonical source and explicit staleness semantics.

The machinery map used to be an illustration that happened to be hosted. It is now a build product with inputs, provenance, a cadence, and a rejection path.

That is what a dashboard is. The pixels are the last step.