# Wiki Governance

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

---

## Status Lifecycle

Every wiki entry has a `status` field in its 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.

---

## Creating New 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`

---

## Directory Rules

### Spatial Hierarchy (`star-systems/`)

```
star-systems/
  {system-slug}/
    index.md                    # System overview
    {station-slug}/
      index.md                  # Station overview
      {district-slug}/
        index.md                # District overview
        {location-slug}.md      # Location files (flat within district)
```

- Systems contain stations (nested directories)
- Stations contain districts (nested directories)
- Districts contain locations (flat files, no subdirectory)
- Each directory level has an `index.md` with that entity's overview
- Slugs are lowercase, hyphenated, unique within their parent

### 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 `decisions/*.md` entries (e.g., `[D-036]`)

---

## Scale Considerations

The spatial hierarchy is designed to scale from 1 star system (v0.1) to 500+ (full game):

- Each system is a self-contained directory tree
- Cross-system references use full slug paths (e.g., `star-systems/van-maanens-star/sova/transit`)
- Characters, factions, and other flat categories remain at wiki root — they are not nested per system
- Characters reference their home district via `home_district` frontmatter field

---

## Naming Conventions

- **File slugs:** lowercase, hyphenated (e.g., `kael-davan.md`, `the-last-shift.md`)
- **Directory slugs:** lowercase, hyphenated (e.g., `van-maanens-star/`, `sova/`, `transit/`)
- **Canonical IDs:** match content schema format (e.g., `npc:kael-davan`)
- **Display names:** title case, as they appear in-game

---

**Last updated:** 2026-02-13