settled-reach/wiki/GOVERNANCE.md

Wiki Governance

Owner: Miri (structure and worldbuilding) Contributors: Anyone on the team, following templates

---

Two Ownership Models

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