jpmschweitzer/settled-reach
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(diagrams): SVG replaces PNG, and a map of the wiki generator flow

Browse Source 
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>
This commit is contained in:
jpmschweitzer
2026-08-20 01:49:19 +02:00
co-authored by Claude Opus 5
parent 34e5d7b636
commit 0817befcba
52 changed files with 3211 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/star-map-plan.md
+1 -1
View File
@@ -401,7 +401,7 @@ Consistent with existing project d2 conventions (dark background, `#1a1e24` base
| `tooling/star-map-seed.json` | JSON config | Miri | Before map generation |
| `docs/design/star-map.json` | JSON graph | Generated | Output of script |
| `docs/diagrams/design/star-map-*.d2` (×7) | d2 source | Generated | Output of script |
| `docs/diagrams/design/star-map-*.png` (×7) | PNG renders | Generated via d2 | After d2 source |
| `docs/diagrams/design/star-map-*.svg` (×7) | SVG renders | Generated via d2 (`make diagrams`) | After d2 source — done 2026-08-20 |
| Gateway system profile | Hand-authored | Miri | After name decided |
| Framework amendment: add `astronomical_id` | Edit to `systems-framework.md` | Miri | After lead sign-off |
| Naming catalog: real-star pool + fabrication rules | Embedded in this doc | Miri | Done (see naming section above) |