# Findings: how the wiki seed data is actually structured

**2026-08-20.** Scored against `wiki-structure-blind-prediction.md`, which was
committed before `wiki/` was opened. Scoring rule was fixed in advance: **right**,
**wrong**, **absent** — with *absent* (a load-bearing thing I did not know
existed) treated as the expensive bucket, because that is what a future session
walks into blind.

## The one-line version

The wiki is **93% machine-generated and 7% authored**, and for the generated 93%
the direction of truth runs **DB → wiki**, which is the opposite of what the
prediction assumed. The single most useful sentence for a new session is: *most
of the wiki is an OUTPUT you must not hand-edit; a small flat set is an INPUT
that generators read.*

## Scored

### Right

- `wiki/` is the authored world-content root; `systems.db` is a build artefact.
  (True for the flat categories only — see Wrong.)
- Markdown + YAML frontmatter, with the frontmatter carrying machine-read fields.
- TOML for tabular economics data; JSON (`markers.json`) for name pools.
- `star-systems/GJ-{id}/bodies/{body_id}/` with `heightmap.png`,
  `reliefmap.png`, `markers.json`. (All `[SEEN]`, so no credit.)
- System dirs hyphenate (`GJ-820B`), body dirs do not (`GJ820Bc`). `[SEEN]`
- More content trees than the three I had seen. There are 16.
- Frontmatter is partly load-bearing and partly decorative, with no strong
  schema gate on the authored side.

### Wrong

1. **"A source, never an output."** Wrong for 93% of the wiki. `star-systems/`
   pages are GENERATED and carry `<!-- READ-ONLY -->` sections rendered from
   `systems.db` and `star-map.json` by `tooling/db/wiki_sync.py`. Authored prose
   lives in designated sections that survive regeneration. Hand-editing a
   read-only section is silently reverted on the next sync.
2. **"Bodies may not have their own pages."** They do — ~2,600 of them — and
   their frontmatter IS the body definition, i.e. generator INPUT rather than
   description. `wiki/star-systems/GJ-820B/bodies/GJ820Bc/index.md` carries
   `seed: 3669559456`, `land_fraction`, `axial_tilt_deg`, star type. This is the
   file that defines Ferrath, the body whose Atlas rendering this session spent
   its entire length fixing, and the session never knew it existed.
3. **"Probably no schema documentation."** There is `wiki/GOVERNANCE.md`,
   `wiki/_templates/` (17 templates, one per entity kind), ten authoring guides
   under `wiki/authoring/`, and `wiki/economics/schema.md`. The documentation is
   not missing. It is unreachable from where an agent starts.
4. **"One generator (`import_economics`)."** At least six touch the wiki:
   `wiki_sync.py`, `scaffold_bodies.py`, `body_definition_parser.py`,
   `populate_gttr_hook.py`, `populate_terrain_reference.py`, plus the atlas sync,
   with `atlas_cohesion_audit.py` auditing.

### Absent — the expensive bucket

Things that are load-bearing and that I had no model of at all:

1. **The two ownership models, and that they run in opposite directions.**
   `wiki/GOVERNANCE.md` states it plainly; nothing an agent reads at session
   start points there. This is the fact most likely to cause damage: an agent
   "fixing" a system page edits a read-only block and the work vanishes.
2. **The GTTR prose layer** — `gttr.md` per system, `gttr-{location}.md` per
   station, `gttr-{corridor}.md` per corridor, feeding `gttr_hook` via
   `populate_gttr_hook.py`. An entire authored content channel, invisible to me.
3. **`terrain.npz` and `globe.png` per body**, alongside the two PNGs I knew.
4. **Stations and districts have NO wiki directories** — they are `systems.db`
   rows rendered into each system page's table, with prose in flat
   `gttr-{slug}.md`. I would have gone looking for `wiki/stations/`.
5. **The `description` frontmatter field exists for AGENTS**: GOVERNANCE.md says
   "agents filter by description before loading full files". There is a designed
   affordance for context-aware loading, and no agent-facing doc mentions it.
6. **Scale**: 301 systems, ~2,600 body pages, 11,864 files. The prediction had no
   sense of magnitude, which matters because it decides whether you grep or
   query.

## A second-order finding: I documented a tree I had not opened

Jeroen, mid-pass: *"did you scan the organizations economics and corporations
dirs and such? do you know what is in it or do you have statistical scans of
it?"*

Statistical scans. At that point I had read `index.md`, `GOVERNANCE.md`,
directory listings, one body page and a scalar aggregate over 2,625 body files —
and had opened **zero** corporation, faction, economics, concept or triangle
files. Everything written above about the flat categories came from GOVERNANCE.md
DESCRIBING them. I was one commit from shipping a skill instructing others how to
work in trees I had never looked inside.

Reading them changed material facts:

- **Four categories are empty scaffolding.** `institutions/`, `species/`,
  `cultural-groups/`, `lore/` hold 0 files while having templates. The
  distribution is lopsided: `corporations/` 156, `economics/` 17, `factions/` 9,
  `technology/` 7, `contraband/` and `concepts/` 4, `triangles/` 2.
- **Corp frontmatter carries 14 fields**, not the 3 the prediction guessed —
  including `scope`, `faction_type`, `tags`, `cross_refs`, `decision_refs`.
- **`economics/` is an economic MODEL**, not a set of lookup vocabularies: 37
  authored commodity pages, `production_chains.toml` with real recipes
  (`2t metallic_ore + 0.3 fusion_fuel -> 1t refined_metals`), currency zones,
  shadow economy, behavioural/lore archetypes, and brand generation. The earlier
  draft of the skill called it "TOML vocabularies + schema.md", which is wrong in
  a way that would mislead.
- **`specialization_vocabulary.toml` is a shared id-space** read by both
  `system_economy.economic_specialization` and `corporations.corp_specialization`
  — the latter authored in corp page frontmatter, not in a TOML.

The lesson generalises past this experiment: a statistical scan tells you the
SHAPE of a tree and nothing about its CONTENT, and the two are easy to conflate
when the statistics are detailed enough to feel like knowledge. The check that
catches it is the one Jeroen applied — "have you opened one?"

## Root cause of the gap

Not missing documentation — **missing reachability**. The wiki documents itself
well (GOVERNANCE.md, templates, authoring guides, economics/schema.md). But:

- `wiki/` does not appear in **CLAUDE.md**'s Project Structure block.
- `wiki/` does not appear in **`.claude/rules/project-structure.md`**, the
  detailed annotated tree that exists precisely to orient an agent. Its only
  match for "wiki" is the parenthetical in `db/  # Asset/connector scripts
  (audio, image, trellis, wiki)`.

So the single largest content tree in the repo — 11,864 files, the seed data for
the entire Reach — is absent from both documents an agent reads first. Everything
in the *absent* bucket follows from that one omission.

## The seed is a parameter space, not a reference work

Jeroen's framing (2026-08-20), which corrects the emphasis above: most of this is
**written once at dev time**, and its job is to be **the seed for variance in the
generator**. Not documentation to maintain — the authored input the cascade
varies from. Read that way, "is the wiki well documented" is the wrong question;
"does the seed supply variance, and does an agent know it IS a seed" is the right
one.

### Measured variance across 2,625 body definitions

Continuous axes are genuinely rich:

| field | distinct values |
|---|---|
| `seed` | 2,625 — unique per body |
| `distance_au` | 716 |
| `polar_ice_lat` | 691 |
| `axial_tilt_deg` | 578 |
| `land_fraction` | 460 |

Categorical axes — the ones that gate morphology and biome branches — are
heavily concentrated:

| field | distinct | dominant value |
|---|---|---|
| `tectonics` | 4 | **67.8% `low`** |
| `atmosphere` | 4 | 66.3% `none` |
| `planet_class` | 13 | 51.1% `frozen` |
| `substrate` | 3 | 51.1% `ice` |
| `geothermal_flux` | 3 | 91.2% `low` |

`name: null` on ~89% of bodies is real (531 of 600 sampled), consistent with
"220 named" of 301 systems.

**Method caveat, stated because the number was wrong once:** the aggregator reads
scalar frontmatter only. `atmosphere_color` first read as "100% null", which was a
PARSER ARTEFACT — it is a YAML list, and the scalar regex matched only its key
line. Ferrath carries a real colour triple. Any list-valued field in that table
would be similarly wrong; the scalar rows are sound.

### Two readings that looked like defects and are not

Both were flagged on first pass and both are deliberate. They are recorded
because the mistake is the point: an agent lacking the roadmap reads a
zero-variance field as a bug, and may "helpfully" populate or delete it.

- **`chemosynthetic: false` on 100% of bodies** is a NAMESPACE RESERVATION for
  dextro-DNA-style biochemistry, for when geology and nature spawn down to the
  1×1 m pixel. It is not meant to vary yet.
- **`enabled: false` on ~65%** is staged rollout, not dead content: the clean
  planet types are learned first, then generator scripts are added for the other
  types and the playable count rises.

### What the economics tree is actually for

The economics TOMLs are not merely DB rows for a trade sim. When geology and
nature spawn to the 1×1 m pixel, **the economics information generates world
content** — production chains and specializations decide what is physically
there. That makes `wiki/economics/` a seed for the same generator, one tier up
from the body definitions, and raises the stakes on its vocabularies.

### The open question this leaves

A 68%-`low`-tectonics world is mostly flat BY THE SEED. This session spent its
full length making the Atlas render terrain legibly, and `composition.rs` already
says "where the terrain is flat, flat is the honest answer". So there is a
ceiling on what renderer work can deliver, and it is set here rather than in the
client. Whether that distribution is intended (most worlds ARE dull; the
interesting ones stand out) or an artefact of the authoring pass is a question
for the seed, not the renderer. Ticketed separately.

## What this predicts

A session asked to change world content will, with no prompting otherwise:

- assume the wiki is hand-authored throughout, and hand-edit a generated page;
- not know `wiki_sync.py` exists, so not know the edit is reverted rather than
  wrong;
- go looking for stations under `wiki/stations/`;
- miss the GTTR channel entirely when asked for location prose;
- and read whole files instead of filtering on `description`, burning context the
  wiki was explicitly designed to save.

That is the same shape as this month's expensive bugs: the information existed,
nothing pointed at it, and the failure was silent.