The relationship between wiki/, the generators, systems.db and the runtime is
a directed graph with two edges running opposite to the obvious direction and
one running backwards into its own producer. Prose renders that badly: every
document that has described it states a single ownership direction and is
therefore wrong about part of the tree. D-262 makes the diagram the source of
truth and points CLAUDE.md, Skill(wiki), project-structure.md and
wiki/GOVERNANCE.md at it.
The correction that matters most: body pages were described everywhere as
machine-owned and reverted on sync. They are not. scaffold_bodies.py writes
one once and never overwrites it, and import_economics then reads that
frontmatter directly as input — so a hand-edit is not reverted, it is obeyed,
and silently changes world generation. Worse than being overwritten, and the
actual reason GOVERNANCE.md forbids the edit.
New: tooling/check-dataflow-graph.py, wired into the Makefile and the pre-push
hook. It asserts every repo path named in a hand-authored diagram still
resolves — and its docstring states plainly what it cannot do: verify that an
edge still MEANS what it says. If wiki_sync.py stopped writing body pages
tomorrow, every path would still exist and the check would still pass. Edge
semantics stay a human check against the tool's source, so nobody reads a green
gate as a verified map.
Verified by breaking it: pointing one label at a moved path fails with exit 1
naming that path; restoring it passes. Building the checker also caught two
real vaguenesses in the diagram — "GJ-*/index.md" and "bodies/{id}/index.md"
were written without their wiki/star-systems/ prefix, which is precisely the
ambiguity this map exists to remove. Generated star-map .d2 files are excluded
by name; their correctness belongs to their generator under D-223.
Also files Q-124 + T-1246 (tooling): whether the 123 Python files under
tooling/ should become one Rust CLI of pql's calibre. The friction is real and
mostly not about the language — the permission gate prefix-matches whole
command strings and a blanket Bash(python3 *) grant is forbidden, so each tool
prompts near-individually, while a single binary is one allowlist entry. The
record requires pricing the cheap alternative (a Python dispatcher entrypoint)
before recommending Rust, and flags the hard constraint: import_economics is
stamped by source SHA, so any port must keep that contract intact through the
transition rather than disabled during it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
d2 emits SVG natively; its PNG path wants a ~150 MB headless-Chromium
download and prompts interactively, so every PNG here was produced by an
out-of-band magick step. There is no Chromium on this system. Dropping PNG
removes the dependency rather than trading one format for another, and cuts
docs/diagrams/ from 17 MB to 3.3 MB. SVG renders in Gitea and in clide
(`clide draw --file <path>`, which takes .d2 source directly), and diffs as
text.
One PNG is kept on purpose: design/star-map-concentric.png has no .d2 source.
Also renders the 7 star-map .d2 files for the first time. star-map-plan.md
listed their renders as a deliverable in March and the step never ran; the
new `make check-diagrams` is what surfaced it.
New: docs/diagrams/data-flow/wiki-generator-flow.d2 — which way the arrows
point for any file under wiki/. Every edge was read in the tool's own source
rather than inferred. It records the trap that keeps costing us: scaffold_bodies.py
writes a body page once and never overwrites it, and the generator then reads
that frontmatter directly — so a hand-edit there is not reverted, it is obeyed,
and silently changes world generation.
Two rendering traps found the expensive way and now written down:
- A d2 `|md` block becomes an SVG <foreignObject>. ImageMagick and flutter_svg
both silently drop it, so the legend was in the file and invisible in every
viewer except a browser. Plain labels render as real <text> everywhere.
- Container boxes fight the layout engine. Grouping nodes whose flow-depths
differ forces long edge routes; this diagram went from an unreadable 2.4:1
sprawl to a legible 0.75:1 by deleting five containers and changing nothing
else. Colour classes carry the grouping instead.
make diagrams / make check-diagrams render and gate. Repo-specific rules in
.claude/rules/diagrams.md; d2 syntax and the traps live in the user-scope
d2-diagram skill, whose PNG default was flipped to SVG to match.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
jpmschweitzerandClaude Opus 5