diff --git a/docs/wiki-structure-blind-prediction.md b/docs/wiki-structure-blind-prediction.md new file mode 100644 index 000000000..91e0caba1 --- /dev/null +++ b/docs/wiki-structure-blind-prediction.md @@ -0,0 +1,132 @@ +# 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// e.g. GJ-820B (hyphenated) [SEEN] + bodies// 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] + .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: + +1. **Right** — claim confirmed. +2. **Wrong** — claim contradicted. Cheap: I had a model and it was corrected. +3. **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.