Files

T

jpmschweitzerandClaude Opus 5 a1addf7e21 docs(meta): seal a blind prediction of the wiki seed structure before reading it

Written before opening wiki/, committed first so the prediction is timestamped and cannot be retrofitted once the answer is known. Contamination declared inline: paths already seen this session via generator_sources.py and visual_scenarios.gd are marked [SEEN] and discounted. Scoring rule fixed in advance, with 'load-bearing thing I did not know existed' as the bucket that decides what gets documented.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-20 00:18:07 +02:00

6.8 KiB

Raw Blame History

Blind prediction: how the wiki seed data is structured

Written 2026-08-20, BEFORE opening wiki/. Committed before the exploration pass so the prediction is timestamped and cannot be quietly retrofitted once the answer is known. The findings pass writes a separate document; this one is never edited after commit.

Why this exists

To measure what a Claude session actually knows about the wiki seed data before it starts guessing. The value is the GAP, not the write-up: wrong beliefs predict where a future session burns a day, and "didn't know it existed" predicts it better than "got it wrong". Jeroen's framing (2026-08-20): misaligned conclusions I may already have drawn are themselves valid friction, so this is written as I actually believe it, contamination and all.

Contamination declared

This is NOT a naive prediction. During this session I saw real wiki paths without opening any of them, via tooling/generator_sources.py, visual_scenarios.gd and CLAUDE.md. Claims resting on those are marked [SEEN] — they should be discounted as evidence of understanding. Everything else is inference and is marked with a confidence level.

The claims

1. Location and role

wiki/ sits at the repo root, a sibling of server/, client/, docs/, governance/. [SEEN]
It is the AUTHORED source of world content — the "Phase 1 deliverable" CLAUDE.md describes ("Wiki content complete — all planets, moons, stations, heightmaps, artwork"). High confidence.
It is a source, never an output: things are generated FROM it into server/data/systems.db, and the asset-pipeline rule ("edit sources, not the DB") means the wiki is one of those sources. High.

2. Format

Pages are markdown with YAML frontmatter — the frontmatter carries the machine-read fields, the body carries prose for humans and for in-game wiki/GTTR popups. High, because import_economics reads corp frontmatter [SEEN] and because pql is described as a markdown-vault query tool.
It is an Obsidian-style vault: [[wikilinks]] between pages, tags, and pql backlinks/related/context work over it. Medium-high — pql's vault surface exists and this repo is a pql repo, but I have not confirmed the wiki is the indexed vault rather than, say, governance/.
Alongside markdown there are TOML data files for tabular content that is awkward as prose — the economics vocabulary/bias tables. [SEEN]
And JSON for name pools (markers.json, names-only per D-223). [SEEN]

3. Directory shape (the least certain part)

Predicted top level:

wiki/
  star-systems/<SYSTEM-ID>/          e.g. GJ-820B   (hyphenated)  [SEEN]
    bodies/<BODY-ID>/                e.g. GJ820Bc   (NOT hyphenated) [SEEN]
      heightmap.png                  1024x512 16-bit elevation  [SEEN]
      reliefmap.png                  1024x512 colour biome      [SEEN]
      markers.json                   names-only city pool       [SEEN]
      <body>.md                      the authored page          (guess)
  corporations/*.md                  + index.md, skipped by the importer [SEEN]
  economics/*.toml                   vocabulary + bias tables   [SEEN]

The system-vs-body id spelling differs (GJ-820B directory, GJ820Bc body). [SEEN], and I flag it as a likely papercut: two spellings of the same identifier is exactly the kind of thing that costs an hour.
Low confidence on everything else: whether there are factions/, stations/, technology/, history/, culture/ trees; whether bodies nest under systems or are flat; whether moons are bodies or a separate kind.
I would GUESS there are more content trees than the three I have seen, because Phase 1 covers "planets, moons, stations, heightmaps, artwork" and miri's worldbuilding brief covers factions/cultures/technology/history — none of which appear in the paths I have seen. Medium.

4. How it reaches the game

One generator: import_economics (make regen-db), which shells out to generate_brands first, then reads the TOMLs, the corp pages' frontmatter, and the markers.json pool, and writes systems.db. [SEEN]
systems.db is a committed read-only snapshot the client ships with; the wiki is not read at runtime by the game. High.
The per-body PNGs are read by the SERVER at runtime (the cascade loads heightmap.png per body), not baked into systems.db. High — T-1213's work this session read reliefmap.png as the biome input, and heightmap paths resolve through a BodySourceResolver.
So there are TWO consumption paths and they behave differently: TOML/markdown → build-time → systems.db, and PNG → runtime → the cascade. If that is right it is the most important structural fact here, and I do not think it is written down in one place. Medium-high.

5. What I expect to be load-bearing but under-documented

Which frontmatter fields are READ versus decorative. My guess: a small set (corp_specialization, headquarters, headquarters_body) is load-bearing and most of the page is prose — so an author can add a field that looks meaningful and nothing consumes it. Medium.
The stamp coupling: editing a wiki page that the importer reads must flip the import_economics meta stamp, or the pre-push hook rejects. Authors of PROSE probably do not expect a content edit to require make regen-db. High — _corporation_pages() globs all corp pages into the stamped set, so editing any corp page's prose stales the DB even if the frontmatter did not change. I predict this is a real friction and possibly a real bug (prose-only edits forcing a regen).
Whether the wiki has a validation gate at all. I predict no schema validation beyond what the importer happens to require, so a typo'd frontmatter key fails silently or at regen time. Medium.

6. What I predict I will be wrong about

The directory taxonomy — I expect several trees I have not guessed.
Whether bodies have their own markdown pages at all, or exist only as DB rows plus asset files.
The relationship between wiki/ and pql's vault indexing; I may be assuming an Obsidian vault that is really just a folder of files.
Whether stations/moons are modelled like planets or differently.

Scoring rule, fixed in advance

Three buckets, and the third is the one that matters:

Right — claim confirmed.
Wrong — claim contradicted. Cheap: I had a model and it was corrected.
Absent — a load-bearing thing I did not know existed. Expensive: this is what a future session walks into blind, the same way relief_q falling off the wire cost eight days this month.

Artefacts get aimed at bucket 3 first, then at bucket 2 where the existing docs are actively WRONG rather than merely missing.

6.8 KiB Raw Blame History