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