The gate caught its own case. tooling/atlas moved into the reach CLI in
T-1285, and wiki-generator-flow.d2 still named it as the bodies catalog
origin — exactly the silent staleness D-262 exists to prevent, found by the
check rather than by a reader months later.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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>
Architecture diagram for D-239: inputs -> three-carrier refinement chain
(RegionProfile -> ChunkContext -> VoxelColumn), the district-temperature
climate primitive + derived freeze/snow, the 8 gated morphology families
over the frozen 17-zone vocabulary, and the anti-squaring domain warp.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add D-237: each inhabited system carries three authored, static (t=0),
deterministic per-system identity fields sourced from
wiki/economics/system_specialization.toml — economic_specialization
(27-value vocabulary, scale encoded in the value), cultural_specialization
(unified activity + heritage vocabulary), and dominant_faction (populate
the existing system_factions column, 8 values, lattice_commission dropped).
Authored lore wins; a deterministic-varied seed-hashed weighted draw is the
fallback for unnamed systems so they don't read identically.
Re-amend D-233 to source dominant_bulk_class x dominant_production_ubiquity
from this authored layer (heuristic becomes fallback). Groombridge encodes
as a financial_hub Specialist district with the GSH clearing house as a
D-222/D-232 landmark rather than a composite vocabulary value.
Add the specialization-layer d2 diagram (3 fields -> D-233/D-232/D-214
consumers). Produced by the system-economic-specialization workshop.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Two star map visualizations: topology view (hop-based layout)
and real-coordinate view (spatial positions).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Canvas now 16:9 with circle filling height. Radial fade gradient uses
userSpaceOnUse for true circular shape. Hop 15+ folded into final ring.
Margins trimmed to fit content.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Script now auto-converts to PNG after generating SVG. Tries magick,
convert, or rsvg-convert in order.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Reproducible concentric-ring star map: Gateway at center, hop rings
radiating outward, sectors in cardinal wedges (N/E/S/W), alternating
band colors per sector, hop 15+ folded into final ring with fade-out
zone. Sol pinned due west.
Run: python3 tooling/generate-star-map-svg.py
Output: docs/diagrams/design/star-map-concentric.svg
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Six sector maps (core, N/S/E/W reach, deep frontier) plus overview.
Generated from star-map.json — currently stale after topology tuning,
will be regenerated once naming pass is complete.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
D2 source + PNG render showing all zone connections, access tiers,
z-levels, maintenance corridor routing, and dual entry vectors.
Vertical layout with color-coded access tiers per D-093.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
16 d2 diagrams covering architecture (IPC bridge, system tiers,
testability, audio bus), data flow (perception, dialogue, eavesdrop
pipelines), entity (knowledge graph, NPC generation, dialogue tags),
state (simulation tiers, movement stances, knowledge confidence), and
UI (HUD layout, interaction flow, fog layers). PNG output for universal
viewer compatibility. Removes test SVG from font debugging.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
jpmschweitzerandClaude Opus 5