jpmschweitzerandClaude Opus 5.5
4537b71b92
`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>
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/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 `<!-- 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
|