Plate № 43 · Foundation · scaffolding & baseline

A pattern from the gf.cx specimen book

Edit the generator, not its output

A page that's regenerated from data will overwrite anything you hand-add to it — so durable content has to come from the thing that prints the page, not the print.

The worked example → status.gf.cx/pool Kin → reconcile onto the template

The problem

status.gf.cx/pool is rendered daily by a snapshot generator (gfcx_offsite_storage_snapshot.py) from a read-only view of the box's storage. When the ask came in — document why this box runs mergerfs + SnapRAID and not ZFS — the tempting move was to paste a comparison table straight into pool/index.html. It would have looked done… and been gone by morning: the next daily render rewrites that file wholesale. The generator even carries a scar from exactly this mistake — a comment marks an earlier hand-added section (commit ead01ae) that a later rebuild silently wiped, because the rebuild was blind to anything not in the renderer.

The shape

• Put the content in the renderer, not the file. Author the section as a constant the generator emits (COMPARISON_TABLE, SOURCES_SECTION), interpolated into the page body. Now it's as durable as the page itself — and reviewable, because it lives in the script, in git.
• Gate it to its surface. One generator often prints many pages. Emit the section behind a guard — comparison_block = COMPARISON_TABLE if slug == "pool" else "" — so a shared renderer lands it on exactly one surface, not all of them.
• Make it native, not a screenshot. Rebuild the graphic with the page's own shelf primitives (here rt rt--compact) — theme-aware, selectable, responsive, reflowing to cards on mobile. A PNG survives regen but not a restyle, a dark theme, or scrutiny.
• Trace every claim to source. Generated is not the same as unaccountable. Link to the projects' own docs, cite the community, and read any verbatim quote at the source — never fabricate a testimonial to fill the space.
• Rebuild from cache, then grep the siblings. Re-render from cached data with no live collect (--rebuild-html), then prove the gate: grep -c the marker on the target page (expect 1) and on every sibling the same renderer builds (expect 0).

Why it works

The render is the source of truth. Anything not expressed in the generator is provisional — true only until the next build fires. Moving the content into the generator makes it exactly as durable, as version-controlled, and as reviewable as the page it prints; and because it's gated, it ships to one surface without leaking onto its siblings. You stop maintaining an artifact the machine is about to overwrite, and start maintaining the machine.

When it breaks

• "Just this once" by hand. The one-off edit is the trap — there's no such thing as a durable manual change to a generated file. If it's worth keeping, it's worth emitting.
• Forgetting the surface gate. An ungated add leaks onto every page the shared renderer builds. The gate and the sibling-grep are a pair; skip the grep and you won't notice the leak.
• Emitting an opaque blob. A pasted PNG or inlined image survives regeneration but defeats theming, selection, and review. Emit native markup so the durable thing is also the legible thing.
• Mirror drift. If the generator lives in an uncommitted ~/bin, mirror the edit to the committed toolkit copy — or the next machine renders the old version and your durable content quietly regresses.

Where it applies

• Use for any page produced by a renderer, generator, or static-site build from data — status and telemetry surfaces, dashboards, index and sitemap pages, anything that carries a "Generated …" timestamp at its foot.
• Use whenever you're adding narrative or reference content to an otherwise data-driven page — the content the build doesn't know to preserve.
• Skip for genuinely hand-maintained pages with no generator behind them — there the file is the source, and editing it is correct.

Reusable elements

• The rule — "the render is the source of truth; edit the press, not the print." Applies to every generated surface in the portfolio.
• The surface gate — one shared renderer, per-surface if slug == … emission, then grep the target (=1) and the siblings (=0) to prove containment.
• Native-over-image — rebuild a graphic as shelf-primitive markup, not a screenshot, so the durable content is theme-aware and reviewable.
• Rebuild-from-cache verify — --rebuild-html re-renders from cached data with no live collect, so you can prove the change before it touches production.

Reference

Worked example

status.gf.cx/pool — the mergerfs-vs-SnapRAID-vs-ZFS comparison table and "Sources & community consensus" section, both emitted from the pool renderer.

Generator

gfcx_offsite_storage_snapshot.py (mirrored in xlab-co-toolkit) — COMPARISON_TABLE / SOURCES_SECTION constants, emitted behind slug == "pool".

Origin

2026-09-04 — "Are we using ZFS?" answered with a durable on-surface explainer instead of a chat screenshot; the renderer's ead01ae scar is why.

Kin

reconcile onto the template (the generated artifact is authoritative; hand-edits are the drift) · the ledger (native shelf structure) · built-with footer (one source, every surface).