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

docs(meta): make the wiki seed reachable — blind-prediction experiment and its fix

Browse Source 
An experiment, at Jeroen's request: predict how the wiki seed data is structured
WITHOUT reading it, seal the prediction, then score it. The prediction is
a1addf7e2, committed before wiki/ was opened so it could not be retrofitted.

The score, against a rule fixed in advance:

RIGHT — markdown + YAML frontmatter, TOML for economics tables, the body path
shape, more trees than the three I had seen.

WRONG — "a source, never an output". That holds for 253 pages and is backwards
for 3,262: star-systems/ is GENERATED from systems.db by tooling/db/wiki_sync.py,
its <!-- READ-ONLY --> blocks are renders, and body frontmatter IS the body
definition rather than a description of one. Also wrong: "probably no schema
docs" — there are 17 templates, ten authoring guides, economics/schema.md and a
GOVERNANCE.md that states the ownership models plainly.

ABSENT (the expensive bucket) — the two ownership models running in OPPOSITE
directions; the GTTR prose channel; terrain.npz/globe.png; that stations and
districts have NO wiki directories; that `description` frontmatter exists so
agents can filter before loading; and the scale, 11,864 files.

ROOT CAUSE, and it is not missing documentation. The wiki documents itself well.
It was unreachable: wiki/ appears in NEITHER CLAUDE.md's Project Structure block
NOR .claude/rules/project-structure.md, the annotated tree whose entire job is
orienting an agent. The largest tree in the repo — the seed for the whole Reach —
was invisible from both files a session reads first. Every item in the absent
bucket follows from that one omission. The proof is this session: it spent three
days fixing Ferrath's terrain rendering and never once saw
wiki/star-systems/GJ-820B/bodies/GJ820Bc/index.md, the file that defines Ferrath.

Fixed here: wiki/ enters both structure documents with the ownership split stated
where it will be read, and Skill(wiki) carries the traps — never hand-edit a
READ-ONLY block or body frontmatter, stations have no directories, the id is
spelled two ways, editing corp PROSE stales systems.db, and absent variance is
often deliberate rather than a gap.

That last point cost two false findings in one measurement and is worth the
warning: chemosynthetic:false on every body is a namespace reservation for
dextro-DNA-style biochemistry once geology and nature spawn to the 1x1m pixel,
and enabled:false on ~65% is staged rollout — clean planet types first, generator
scripts for the rest after. Both read as defects without the roadmap.

Also measured, since the seed's job is to supply variance: continuous axes are
rich (unique seed per body, 460-716 distinct values across orbit/tilt/ice/land)
while the categoricals that gate morphology are concentrated (68% tectonics low,
51% planet_class frozen). Filed as T-1244 with the design question stated first —
whether the distribution is intended — rather than as a defect.

Method caveat recorded in the findings: the aggregator reads scalar frontmatter
only, and atmosphere_color's "100% null" was a parser artefact, not a finding.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
jpmschweitzer
2026-08-20 00:31:06 +02:00
co-authored by Claude Opus 5
parent a1addf7e21
commit c25af8d753
6 changed files with 409 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/rules/project-structure.md
+29
View File
@@ -1,6 +1,35 @@
# Project Structure (detailed)
```
wiki/ # THE SEED (11,864 files, the largest tree here). Authored
# world content the generator varies from — NOT a
# reference work, and mostly NOT hand-written.
# See Skill(wiki) before editing anything below.
index.md # the map: 301 systems, 220 named
GOVERNANCE.md # ownership models, status lifecycle, directory rules
_templates/ # 17 templates, one per entity kind — copy to author
authoring/ # 10 guides (monologue, culture, dual-lens, line-id…)
economics/ # INPUT. TOML vocabularies + schema.md. Seeds systems.db
# AND, from Phase 4 on, world content generation
star-systems/ # OUTPUT, 93% of the wiki. Generated by
# tooling/db/wiki_sync.py FROM systems.db + star-map.json
GJ-{id}/ # system dir (hyphenated id)
index.md # no frontmatter; <!-- READ-ONLY --> blocks are
# regenerated — authored prose lives in the named
# sections between them
gttr*.md # Drifter's Guide prose (corridor/system/location)
bodies/{id}/ # body dir (UN-hyphenated id, e.g. GJ820Bc)
index.md # frontmatter IS the body definition: seed,
# land_fraction, axial_tilt_deg — generator INPUT,
# machine-owned, never hand-edited
*.png, *.npz # globe/relief/heightmap renders + terrain grids
markers.json # names-only city pool (D-223)
corporations/ factions/ contraband/ concepts/ triangles/ species/
institutions/ cultural-groups/ lore/ technology/ glossary.md
# INPUT, flat, wiki-is-truth. YAML frontmatter carries
# status (proposed|draft|canonical), cross_refs,
# decision_refs, and `description` — which exists so
# AGENTS can filter before loading whole files
client/ # Godot 4 client
ui/
implant/ # Implant UI component library (D-169): ImplantPanel, ImplantHeader,
.claude/skills/wiki/SKILL.md
+152
View File
@@ -0,0 +1,152 @@
---
name: wiki
description: Read or edit the wiki seed data — world content, star systems, bodies, corporations, factions, economics vocabularies, GTTR prose. Use when the task touches wiki/ at all: authoring lore or corp/faction pages, changing a body definition, adding a system, editing economics TOMLs, or answering "where does this world fact live". Also use before assuming a wiki page is hand-written — most are generated and hand-edits are silently reverted.
---
# The wiki is a seed, and it is mostly generated
`wiki/` is the authored input the world generator varies from — written once at
dev time, then read by the cascade. It is not a reference work to maintain, and
it is not hand-written throughout: **3,262 of its 3,515 pages are generated**.
Everything below is the part that bites. The wiki documents itself well and you
should read its own docs for detail:
- `wiki/GOVERNANCE.md` — ownership, status lifecycle, directory rules
- `wiki/index.md` — the map
- `wiki/_templates/` — 17 templates, one per entity kind
- `wiki/authoring/` — 10 guides (monologue, culture, dual-lens, line-id, …)
- `wiki/economics/schema.md` — the economics TOML spec
## The one rule: which direction does truth run?
Two ownership models, running OPPOSITE ways. Get this wrong and your work
vanishes on the next sync, without an error.
### `star-systems/` — DB owns structure, wiki owns prose (OUTPUT)
3,262 pages, 93% of the wiki. Generated FROM `server/data/systems.db` and
`star-map.json` by `tooling/db/wiki_sync.py`, with `scaffold_bodies.py` and the
atlas sync alongside.
**Never hand-edit:**
- anything inside a `<!-- READ-ONLY -->` block (System Profile, Topology,
Celestial Bodies, Stations & Facilities)
- `bodies/*/index.md` frontmatter — it IS the body definition and it is
machine-owned
**Do author**, in place, and it survives regeneration:
- the named prose sections of a system page: Supply Dependency, Faction Notes,
Silence Topic, Narrative Hook, Calibration Note
- `gttr.md` (system), `gttr-{location}.md` (station/settlement),
`gttr-{corridor}.md` (corridor) — the Drifter's Guide channel
To change a generated fact, change the SOURCE and regenerate. Editing the page
is editing a render.
### Flat categories — wiki is truth (INPUT)
Authored markdown plus TOML. Generators import FROM these. What is actually
there, counted 2026-08-20 — the distribution is lopsided and four categories are
empty scaffolding:
| category | files | note |
|---|---|---|
| `corporations/` | 156 | the authored mass; frontmatter feeds systems.db |
| `economics/` | 17 entries | the economic MODEL — see below |
| `factions/` | 9 | Assembly, Commission, Institute, Syndics, Guardians, Unbound |
| `technology/` | 7 | |
| `contraband/`, `concepts/` | 4 each | |
| `triangles/` | 2 | relationship structures |
| `institutions/`, `species/`, `cultural-groups/`, `lore/` | **0** | templates exist, no content yet |
To add one: copy the matching `_templates/` file, fill ALL frontmatter, write a
one-line `description`, set `status: proposed`, follow the template's structure.
Real corp frontmatter is richer than it looks — `title, description, slug,
category, status, created, updated, scope, faction_type, headquarters,
corp_specialization, tags, decision_refs, cross_refs`. Only some is machine-read
(`corp_specialization` keys HQ placement via `corp_hq_placement.toml`), but the
whole file is in the importer's stamped set.
### `wiki/economics/` is the economic model, not a lookup table
This is the tree that will generate WORLD CONTENT once geology and nature spawn
to the 1×1 m pixel — production chains decide what is physically present on the
ground, so it is a seed one tier above the body definitions.
```
economics/
schema.md the spec — read this first
commodities.toml + commodities/ (37 authored commodity pages)
production_chains.toml real recipes: 2t metallic_ore + 0.3 fusion_fuel
-> 1t refined_metals, location_bound flags
currency_zones.toml shadow_economy.toml
specialization_vocabulary.toml system_specialization.toml
corp_hq_placement.toml settlement_name_locked.toml
architecture_trait_catalog.toml / _bias.toml / architecture_zone_bias.toml
color_register_bands.toml object_tag_vocabulary.toml
archetypes/ behavioral.toml, brand_templates.toml, lore.toml
corporations/ brands.toml, generated_brands.toml, tier1.toml
```
`specialization_vocabulary.toml` is a shared id-space read by TWO axes:
`system_economy.economic_specialization` (per system) and
`corporations.corp_specialization` (per corp, authored in the corp page's
frontmatter, NOT in a per-corp TOML). Change a value and both move.
`generated_brands.toml` is OUTPUT — written by the `generate_brands` binary that
`import_economics` shells out to; do not hand-edit it.
## Traps
**Stations and districts have no directories.** They are `systems.db` rows
rendered into each system page's table. Their prose lives in flat
`gttr-{slug}.md` files in the system dir. Do not create `wiki/stations/`.
**Two spellings of one id.** System dirs hyphenate (`GJ-820B/`), body dirs do
not (`GJ820Bc/`). Body dirs key on body id, never on a display-name slug.
**Editing corp PROSE stales systems.db.** `_corporation_pages()` globs every
`wiki/corporations/*.md` (except `index.md`) into `import_economics`' stamped
source set, so a typo fix in body text trips the pre-push stamp check. Run
`make regen-db` and stage `server/data/systems.db`.
**`description` exists for you.** GOVERNANCE.md: "agents filter by description
before loading full files". Read frontmatter descriptions and load selectively —
this tree is 11,864 files and will eat a context window whole.
**Absent variance is often deliberate.** Fields can be forward-reservations or
staged gates, not gaps. `chemosynthetic: false` on every body reserves the
namespace for dextro-DNA-style biochemistry once geology and nature spawn to the
1×1 m pixel. `enabled: false` on ~65% is staged rollout — clean planet types are
learned first, then generator scripts follow and the playable count rises. Do
not populate or delete a zero-variance field without asking why it is empty.
## What the seed actually supplies
Measured over 2,625 body definitions (2026-08-20):
- **Rich**: `seed` unique per body; `distance_au` 716 distinct, `polar_ice_lat`
691, `axial_tilt_deg` 578, `land_fraction` 460.
- **Concentrated**: `tectonics` 68% `low`, `atmosphere` 66% `none`,
`planet_class` 51% `frozen`, `substrate` 51% `ice`.
The categorical fields gate morphology and biome branches, so a mostly-`low`
tectonics world is mostly flat BY THE SEED. Before treating flat terrain as a
rendering bug, check what the body was authored as — that mistake cost a full
session once already.
## Tooling
| tool | does |
|---|---|
| `tooling/db/wiki_sync.py` | systems.db → star-system page sections |
| `tooling/planet-gen/scaffold_bodies.py` | creates body dirs/pages |
| `tooling/planet-gen/body_definition_parser.py` | reads body frontmatter |
| `tooling/db/populate_gttr_hook.py` | GTTR prose → `gttr_hook` |
| `tooling/planet-gen/populate_terrain_reference.py` | terrain asset paths |
| `tooling/planet-gen/atlas_cohesion_audit.py` | audits atlas coherence |
| `make regen-db` | economics TOML + corp frontmatter → systems.db |
`pql` queries the vault: `pql search`, `pql backlinks`, `pql related`,
`pql context` — prefer these over grepping 11,864 files.
.pql/changelog/ticket_idmap/2026-08.sql
+1
View File
@@ -3,3 +3,4 @@ INSERT INTO ticket_idmap (record_id, ticket_id, created_at, updated_at, deleted_
INSERT INTO ticket_idmap (record_id, ticket_id, created_at, updated_at, deleted_at, hash, canonical_version) VALUES ('06G0495WRHF8ADK82VR8CH1J8R', 'T-1241', '2026-08-14 21:19:17.192', '2026-08-14 21:19:17.192', NULL, '0374016de542b027720ca7a45d39f385', 2) ON CONFLICT(record_id) DO UPDATE SET ticket_id=excluded.ticket_id, updated_at=excluded.updated_at, deleted_at=excluded.deleted_at, hash=excluded.hash, canonical_version=excluded.canonical_version WHERE excluded.updated_at >= ticket_idmap.updated_at;
INSERT INTO ticket_idmap (record_id, ticket_id, created_at, updated_at, deleted_at, hash, canonical_version) VALUES ('06G04975H3S7GRVQXHKYCR7BKR', 'T-1242', '2026-08-14 21:19:27.624', '2026-08-14 21:19:27.624', NULL, '410d294a5da4ba7435bc3fd4d1e08c95', 2) ON CONFLICT(record_id) DO UPDATE SET ticket_id=excluded.ticket_id, updated_at=excluded.updated_at, deleted_at=excluded.deleted_at, hash=excluded.hash, canonical_version=excluded.canonical_version WHERE excluded.updated_at >= ticket_idmap.updated_at;
INSERT INTO ticket_idmap (record_id, ticket_id, created_at, updated_at, deleted_at, hash, canonical_version) VALUES ('06G0P0F9C3RKKK23ZHHTANCPZW', 'T-1243', '2026-08-16 14:37:49.794', '2026-08-16 14:37:49.794', NULL, '0dbba61f1c75851f6e0cca78402da745', 2) ON CONFLICT(record_id) DO UPDATE SET ticket_id=excluded.ticket_id, updated_at=excluded.updated_at, deleted_at=excluded.deleted_at, hash=excluded.hash, canonical_version=excluded.canonical_version WHERE excluded.updated_at >= ticket_idmap.updated_at;
INSERT INTO ticket_idmap (record_id, ticket_id, created_at, updated_at, deleted_at, hash, canonical_version) VALUES ('06G1R8WZ987YCP1ARANSA70R0W', 'T-1244', '2026-08-19 22:28:11.726', '2026-08-19 22:28:11.726', NULL, 'fd1f9d38036692125ba7c7de0198bfc8', 2) ON CONFLICT(record_id) DO UPDATE SET ticket_id=excluded.ticket_id, updated_at=excluded.updated_at, deleted_at=excluded.deleted_at, hash=excluded.hash, canonical_version=excluded.canonical_version WHERE excluded.updated_at >= ticket_idmap.updated_at;
.pql/changelog/tickets/2026-08.sql
+1
View File
@@ -852,3 +852,4 @@ LEFT OPEN, not part of this ticket: Quarter''s contour banding (the stipple
lattice quantising the hillshade into dotted rings), and MIN_WL_BANDS_M itself,
which remains stale for the legacy layer_proxy district-window consumer. Neither
blocks the ladder.', 'done', 'medium', NULL, 'server', 'D-255', '2026-08-07 13:26:56.703', '2026-08-18 18:49:07.176', NULL, 'b79d8865e3da7d586bf8c724de2d34b2', 2) ON CONFLICT(record_id) DO UPDATE SET type=excluded.type, parent_record_id=excluded.parent_record_id, title=excluded.title, description=excluded.description, status=excluded.status, priority=excluded.priority, assigned_to=excluded.assigned_to, team=excluded.team, decision_ref=excluded.decision_ref, updated_at=excluded.updated_at, deleted_at=excluded.deleted_at, hash=excluded.hash, canonical_version=excluded.canonical_version WHERE excluded.updated_at >= tickets.updated_at;
INSERT INTO tickets (record_id, type, parent_record_id, title, description, status, priority, assigned_to, team, decision_ref, created_at, updated_at, deleted_at, hash, canonical_version) VALUES ('06G1R8WZ987YCP1ARANSA70R0W', 'story', '06FB0TNSRZXCHGS16BFHSSGSV4', 'Seed variance: 68% of bodies are tectonics:low — is the categorical monoculture intended?', 'Measured 2026-08-20 over all 2,625 body definitions in wiki/star-systems/*/bodies/*/index.md. The seed''s CONTINUOUS axes vary richly: seed is unique per body, distance_au 716 distinct values, polar_ice_lat 691, axial_tilt_deg 578, land_fraction 460. The CATEGORICAL axes do not: tectonics 4 values with 67.8% ''low'', atmosphere 4 with 66.3% ''none'', planet_class 13 with 51.1% ''frozen'', substrate 3 with 51.1% ''ice'', geothermal_flux 3 with 91.2% ''low''. Those categoricals are what gate the morphology and biome branches, so a mostly-low-tectonics world is mostly FLAT BY THE SEED, before any rendering question. This matters because a full session (2026-08-16..18) went into making the Atlas render terrain legibly at the deep rungs, and composition.rs already states the honest position: ''where the terrain is flat, flat is the honest answer, and the morphology variety visible at Global comes from places that actually have slope''. If two thirds of bodies genuinely have no slope, there is a ceiling on what renderer work can deliver and it is set in the seed. QUESTION TO ANSWER FIRST, before any change: is the distribution intended? A galaxy where most worlds are dull and the interesting ones stand out is a legitimate and probably good design; an authoring pass that defaulted tectonics to ''low'' and moved on is not. Check how the values were produced (scaffold_bodies.py / the authoring pass) before touching them. NOT a defect report -- two things that looked like defects in the same measurement turned out deliberate (chemosynthetic:false is a namespace reservation for dextro-DNA biochemistry once geology and nature spawn to the 1x1m pixel; enabled:false on ~65% is staged rollout, clean planet types first then generator scripts for the others). Method caveat: the aggregator reads scalar frontmatter only, so list-valued fields are unreliable -- atmosphere_color first read as ''100% null'' and that was a parser artefact. Full measurement and method: docs/wiki-structure-findings.md.', 'backlog', 'medium', NULL, 'server', NULL, '2026-08-19 22:28:11.722', '2026-08-19 22:28:11.722', NULL, 'd5f89318c9d9845ae46aa165a731821f', 2) ON CONFLICT(record_id) DO UPDATE SET type=excluded.type, parent_record_id=excluded.parent_record_id, title=excluded.title, description=excluded.description, status=excluded.status, priority=excluded.priority, assigned_to=excluded.assigned_to, team=excluded.team, decision_ref=excluded.decision_ref, updated_at=excluded.updated_at, deleted_at=excluded.deleted_at, hash=excluded.hash, canonical_version=excluded.canonical_version WHERE excluded.updated_at >= tickets.updated_at;
CLAUDE.md
+14
View File
@@ -9,6 +9,7 @@ A top-down life-sim — asymmetric information, occlusion-based perception, sing
## Project Structure
```
wiki/ # THE SEED — authored world content that the generator varies from
client/ # Godot 4 client
server/ # Rust/bevy_ecs simulation server
tooling/ # Build tools, scripts, asset pipelines
@@ -21,6 +22,19 @@ governance/ # Decision records — decisions/ questions/ rejected/ per
Full annotated tree: `.claude/rules/project-structure.md`
**`wiki/` is the seed, and it is mostly generated.** 11,864 files — the largest
tree in the repo. Two ownership models run in OPPOSITE directions, and mixing
them up costs work: `star-systems/` (3,262 pages, 93% of the wiki) is produced
FROM `systems.db` by `tooling/db/wiki_sync.py`, so its `<!-- READ-ONLY -->`
sections and body-page frontmatter are OUTPUT — hand-edits are silently reverted
on the next sync. The flat categories (`corporations/`, `factions/`, `economics/`,
…, 253 pages) are INPUT the generators read. Body frontmatter IS the body
definition (`seed`, `land_fraction`, `axial_tilt_deg`); `wiki/economics/` seeds
world content generation, not just DB rows. Read `Skill(wiki)` before touching
any of it — the wiki documents itself well (`wiki/GOVERNANCE.md`,
`wiki/_templates/`, `wiki/authoring/`, `wiki/economics/schema.md`), it was simply
unreachable from here until 2026-08-20.
## DevOps
See [docs/DEVOPS.md](docs/DEVOPS.md) for build, test, lint, and CI procedures. All development operations go through the top-level `Makefile` — run `make` for a summary of targets.
docs/wiki-structure-findings.md
+212
View File
@@ -0,0 +1,212 @@
# 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.