Files

T

jpmschweitzerandClaude Opus 5.5 4537b71b92 refactor(tooling): T-1290 — the wiki domain, and the renderer that must not run

`reach wiki stats` and `reach wiki gttr-hook` replace tooling/db/wiki_sync.py
and populate_gttr_hook.py. Both are output-identical to the originals:
`stats` byte-for-byte, and all 301 extracted GTTR hooks line-for-line.

wiki_sync.py moved whole, but generate_wiki() and import_from_wiki() are NOT
verbs. Before porting, the old `--generate` was run against a clean tree to get
a parity baseline. It changed all 301 system pages, +940 / -10,761, and was
reverted at once. It deletes the Celestial Bodies / Stations blocks (owned by
the Rust atlas sync, which it does not know about), deletes the
Industries / Exports / Imports rows (nothing writes those any more), and
rewrites star types where systems.db and the pages disagree. D-262, CLAUDE.md
and the wiki skill all described it as the routine, prose-preserving render.
CLAUDE.md and the skill now say not to run it; D-262 needs amending — T-1292.

Provenance moves to tooling/archive/, with a README naming what each script
did and why it is not run:

- pql-migrate/ (the T-1271 ruling)
- wiki-bootstrap/: assign-astro-ids + its catalog, migrate-s-to-gj,
  patch-core-sector (hardcodes a dead path), fill-missing-globes,
  generate-stubs and find-stubs (finds 0 stubs — Phase 1 is done),
  backfill_cultural_corridor (a raw systems.db patch script, outside D-262),
  and process-wiki-system-changes, whose last step is the destructive render

Also:

- stats() printed "run import first" and exited 0 when a table was missing;
  it now fails with a remedy. generate_wiki() counted created pages after
  writing them, so `created` was always 0.
- tooling/godot-cold-parse and godot-parse-sweep were never retired after
  T-1283, and the pr-process skill still told agents to run them. Removed;
  the skill and parse_sweep.gd now name the reach verbs.
- systems.db re-stamped: schema comments changed, and the stamp records the
  schema file's SHA for tamper detection.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2026-09-23 16:25:51 +02:00

6.8 KiB

Raw Blame History

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/domains/wiki/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  — 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:

Copy the appropriate template from _templates/
Fill in the YAML frontmatter (all fields)
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).
Set status: proposed
Write the content following the template structure
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

6.8 KiB Raw Blame History