jpmschweitzerandClaude Opus 5
6949f800dc
The relationship between wiki/, the generators, systems.db and the runtime is
a directed graph with two edges running opposite to the obvious direction and
one running backwards into its own producer. Prose renders that badly: every
document that has described it states a single ownership direction and is
therefore wrong about part of the tree. D-262 makes the diagram the source of
truth and points CLAUDE.md, Skill(wiki), project-structure.md and
wiki/GOVERNANCE.md at it.
The correction that matters most: body pages were described everywhere as
machine-owned and reverted on sync. They are not. scaffold_bodies.py writes
one once and never overwrites it, and import_economics then reads that
frontmatter directly as input — so a hand-edit is not reverted, it is obeyed,
and silently changes world generation. Worse than being overwritten, and the
actual reason GOVERNANCE.md forbids the edit.
New: tooling/check-dataflow-graph.py, wired into the Makefile and the pre-push
hook. It asserts every repo path named in a hand-authored diagram still
resolves — and its docstring states plainly what it cannot do: verify that an
edge still MEANS what it says. If wiki_sync.py stopped writing body pages
tomorrow, every path would still exist and the check would still pass. Edge
semantics stay a human check against the tool's source, so nobody reads a green
gate as a verified map.
Verified by breaking it: pointing one label at a moved path fails with exit 1
naming that path; restoring it passes. Building the checker also caught two
real vaguenesses in the diagram — "GJ-*/index.md" and "bodies/{id}/index.md"
were written without their wiki/star-systems/ prefix, which is precisely the
ambiguity this map exists to remove. Generated star-map .d2 files are excluded
by name; their correctness belongs to their generator under D-223.
Also files Q-124 + T-1246 (tooling): whether the 123 Python files under
tooling/ should become one Rust CLI of pql's calibre. The friction is real and
mostly not about the language — the permission gate prefix-matches whole
command strings and a blanket Bash(python3 *) grant is forbidden, so each tool
prompts near-individually, while a single binary is one allowlist entry. The
record requires pricing the cheap alternative (a Python dispatcher entrypoint)
before recommending Rust, and flags the hard constraint: import_economics is
stamped by source SHA, so any port must keep that contract intact through the
transition rather than disabled during it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
160 lines
6.8 KiB
Markdown
160 lines
6.8 KiB
Markdown
# Wiki Governance
|
|
|
|
**Owner:** Miri (structure and worldbuilding)
|
|
**Contributors:** Anyone on the team, following templates
|
|
|
|
---
|
|
|
|
## Two Ownership Models
|
|
|
|
> **The canonical map of this is a diagram (D-262):**
|
|
> `docs/diagrams/data-flow/wiki-generator-flow.d2`. Every edge in it was read in
|
|
> the generator's own source. The two models below are a summary; the diagram
|
|
> also records the parts that do not fit a two-way split — `wiki_sync.py` runs
|
|
> in **both** directions, and body pages are read back into the generator as
|
|
> input. Where this text and the diagram disagree, the diagram is right.
|
|
|
|
The wiki has two kinds of content with different sources of truth (see
|
|
`tooling/db/wiki_sync.py`):
|
|
|
|
- **DB owns structured fields, wiki owns prose** (`star-systems/`): identity,
|
|
gates, history, economy, factions, and culture live in `server/data/systems.db`
|
|
and are rendered into READ-ONLY page sections. Authored prose sections
|
|
(Supply Dependency, Faction Notes, Silence Topic, Narrative Hook, Calibration
|
|
Note) are written in the wiki and preserved across regeneration. Never edit a
|
|
section marked `<!-- READ-ONLY -->` — it will be overwritten by the next sync.
|
|
- **Wiki is truth** (flat categories): `corporations/`, `factions/`,
|
|
`contraband/`, `economics/`, etc. are authored markdown (plus TOML in
|
|
`economics/`). Where machine-readable, the generators import FROM the wiki
|
|
(e.g. corporation frontmatter → `systems.db` per D-182).
|
|
|
|
---
|
|
|
|
## Status Lifecycle
|
|
|
|
Authored flat-category entries (corporations, factions, contraband, concepts,
|
|
triangles, …) carry a `status` field in their YAML frontmatter:
|
|
|
|
| Status | Meaning | Who Can Set |
|
|
|--------|---------|-------------|
|
|
| `proposed` | Under consideration, not yet reviewed | Anyone |
|
|
| `draft` | In review, content being refined | Author + reviewer |
|
|
| `canonical` | Confirmed setting truth, safe to reference | Miri or project lead |
|
|
|
|
**Progression:** `proposed` → `draft` → `canonical`
|
|
|
|
**Demotion:** A `canonical` entry can be demoted to `draft` if a decision changes its foundation. Only Miri or the project lead can demote canonical entries.
|
|
|
|
**Out of scope:** generated `star-systems/` pages have no status field. System
|
|
pages carry no frontmatter at all; body pages carry frontmatter that IS the
|
|
body definition (machine-owned, see below), not an editorial status.
|
|
|
|
---
|
|
|
|
## Creating New Entries
|
|
|
|
For **flat-category** entries:
|
|
|
|
1. Copy the appropriate template from `_templates/`
|
|
2. Fill in the YAML frontmatter (all fields)
|
|
3. Write a concise `description` — one line that captures what makes this entry distinct. This field enables context-aware loading (agents filter by description before loading full files).
|
|
4. Set `status: proposed`
|
|
5. Write the content following the template structure
|
|
6. Submit for review
|
|
|
|
**Templates available:** `star-system`, `station`, `district`, `location`, `character`, `faction`, `technology`, `cultural-group`, `contraband`, `institution`, `species`, `lore`, `concept`, `triangle`
|
|
|
|
**Do not hand-create** system or body pages under `star-systems/` — they are
|
|
produced by the generator pipeline (`wiki_sync.py`, the atlas sync, and
|
|
`scaffold_bodies.py`). Authoring happens inside the designated prose sections
|
|
of generated pages, or in the GTTR files alongside them.
|
|
|
|
---
|
|
|
|
## Directory Rules
|
|
|
|
### Spatial Hierarchy (`star-systems/`) — generated
|
|
|
|
```
|
|
star-systems/
|
|
index.md # Sector/hop navigation (companions as unlinked text)
|
|
catalog.md # Full table of all systems by GJ designation
|
|
gttr-{corridor}.md # Corridor-level Drifter's Guide prose (core, east, …)
|
|
GJ-{id}/
|
|
index.md # System page — NO frontmatter:
|
|
# title block + System Profile (READ-ONLY, systems.db)
|
|
# + authored prose sections (Supply Dependency,
|
|
# Faction Notes, Silence Topic, Narrative Hook,
|
|
# Calibration Note)
|
|
# + Topology (READ-ONLY, star-map.json)
|
|
# + Celestial Bodies / Stations & Facilities tables
|
|
# (READ-ONLY, systems.db via atlas sync)
|
|
# + Stations GTTR link line
|
|
gttr.md # System-level Drifter's Guide prose (→ gttr_hook)
|
|
gttr-{location}.md # Station/settlement-level Guide prose, flat per system
|
|
bodies/
|
|
{body_id}/
|
|
index.md # Body page — YAML frontmatter IS the body definition
|
|
# (generator input; e.g. axial_tilt feeds
|
|
# import_economics). Prose below the frontmatter.
|
|
globe.png # Rendered globe (all bodies)
|
|
reliefmap.png # Color hypsometric render (non-gas bodies)
|
|
heightmap.png # 16-bit canonical elevation — inhabited bodies only
|
|
terrain.npz # Simulation grids
|
|
markers.json # Names-only city markers (D-223) → atlas_city_names
|
|
```
|
|
|
|
- **Stations and districts have no wiki directories.** They are rows in
|
|
`systems.db`, rendered into each system page's Stations & Facilities table.
|
|
Station-level prose lives in flat `gttr-{slug}.md` files in the system dir.
|
|
- Body directories are keyed by body id (e.g. `GJ71d-1`), not by display-name slug.
|
|
- Never edit READ-ONLY sections or `bodies/*/index.md` frontmatter by hand —
|
|
regenerate from sources instead.
|
|
|
|
### Flat Categories
|
|
|
|
All other categories use flat file structure:
|
|
|
|
```
|
|
{category}/
|
|
{entry-slug}.md
|
|
```
|
|
|
|
No nesting within flat categories. Use `cross_refs` in frontmatter for relationships.
|
|
|
|
---
|
|
|
|
## Cross-Referencing
|
|
|
|
- Use `cross_refs` in YAML frontmatter for machine-readable references (slugs only)
|
|
- Use markdown links in body text for human-readable navigation
|
|
- Use `decision_refs` for links to `governance/decisions/*.md` entries (e.g., `[D-036]`)
|
|
|
|
---
|
|
|
|
## Scale Considerations
|
|
|
|
The generated spatial model already covers the full Reach (~301 systems, ~2,600
|
|
body pages):
|
|
|
|
- Each system is a self-contained generated directory tree; adding systems means
|
|
adding rows to the sources (`systems.db` pipeline + `star-map.json`), not
|
|
hand-building directories
|
|
- Cross-system references in prose use relative links to `GJ-{id}/index.md`
|
|
- Characters, factions, and other flat categories remain at wiki root — they are
|
|
not nested per system
|
|
|
|
---
|
|
|
|
## Naming Conventions
|
|
|
|
- **File slugs:** lowercase, hyphenated (e.g., `vuurkloof.md`, `freight-exchange.md`)
|
|
- **System directories:** GJ designation with hyphen (e.g., `GJ-71/`, `GJ-820B/`)
|
|
- **Body directories:** body id from the Celestial Bodies table (e.g., `GJ71d-1/`)
|
|
- **Canonical IDs:** match content schema format (e.g., `npc:{character-slug}`)
|
|
- **Display names:** title case, as they appear in-game
|
|
|
|
---
|
|
|
|
**Last updated:** 2026-06-12
|