# Baltun'ia Vault Conventions (shared reference)

All campaign skills read this file first. It captures how *this* vault is
actually structured and written. Match these conventions exactly — the goal is
that a generated note is indistinguishable from one the DM wrote by hand.

## Vault map

```
1. History of Baltun'ia/        ← lore by Age (Ancient → Fourth). Has Key Figures / Key Locations subfolders.
2. World Almanac/               ← the living world
   Factions/<Faction>/          ← one folder per faction, "<Faction> Overview.md" inside
   Species/                     ← one note per species
   Deities/  + Deities/Minor Deities/
   Creatures/  + Creatures/Natural World/
   Economy/
   Languages/
   Regions of Baltun'ia/<Region>/        ← region note "<Region>.md" at top of its folder
      <City>/                             ← city note "<City>.md" at top of its folder
         <POI>/                           ← POI folder, "<POI>.md" overview inside
            <NPC Name> - <POI>.md         ← NPCs live beside the POI they belong to
         Documents/                       ← in-world docs & event write-ups (speeches, letters, propositions)
3. Session Recaps/              ← "N. Title - M-D-YY.md", flat, narrative prose
z_templates/Framework Templates/ ← NPC / Location / Faction / POI templates
z_other/                        ← monologues, Campaign Flow (mermaid plot flowchart)
Campaign Premise.md             ← the central conspiracy / endgame
Index File.base                 ← Obsidian Base; filters out anything whose path starts with "z"
```

`z`-prefixed folders are excluded from the Index Base on purpose. Keep
templates and scratch material under `z_*`; keep canonical content out of it.

## Formatting rules (do NOT deviate)

- **No YAML frontmatter.** Existing notes have none. Do not add it.
- Notes use **heading-based sections** (`###` / `##`) copied from the relevant
  framework template, then filled in. Sections may be renamed to fit the
  subject (e.g. a POI's "History & Lore" became "Lore & Role in Voxiu"). Adapt,
  don't pad with empty boilerplate sections.
- **Wikilinks everywhere.** Link the first mention of any species, region,
  city, faction, deity, POI, or other NPC: `[[Humans]]`, `[[Voxiu]]`,
  `[[Belter Overview|Belters]]`. Use `[[Note Name|display text]]` when the file
  name differs from how it reads in the sentence.
- **Notable-NPC entries** use the bold-name + arrow-note style:
  `- **Hedda Wickwhistle**, Guildmother Weaver *(Human, elderly)*` then a new
  line starting with `→ ` giving role / hook.
- Tables (markdown pipe tables) are used for economy breakdowns — reuse that
  style for any quantitative data.
- Tone is in-world and concrete. Prefer specific, evocative detail over generic
  fantasy filler. American spelling, present tense for descriptions.

## Naming conventions

- **NPC file:** `<Full Name> - <POI or City>.md` (e.g. `Kal Branth - Sea Bastion Docks.md`).
  Historical NPCs instead go in the relevant Age's `Key Figures/` as `<Name>.md`.
- **Overview files** are named after their container: `Cotton Row Market/Cotton Row Market.md`,
  `Belters/Belter Overview.md`, `Voxiu/Voxiu.md`.
- **Session recap:** `<N>. <Short Title> - <M-D-YY>.md` — N is the next integer
  after the highest existing recap, date is the real session date (no leading
  zeros: `9-8-25`, not `09-08-25`).

## Linking discipline (run this before finishing any note)

1. Every proper noun that *could* have a note gets a `[[wikilink]]` on first use.
2. If you reference an entity that has **no** note yet, still wikilink it
   (a "future note" / red link is correct and intentional in Obsidian) and
   mention to the user that it's a stub worth creating.
3. When you create an NPC/POI, add a reciprocal mention+link in its parent
   note's "Notable NPCs" / "Notable Locations" section so the graph stays connected.

## Collaborative generation (applies to every content skill)

The DM chose a **collaborative** style. For any note that involves creative
invention:

1. Read the relevant template and 1–2 nearby sibling notes for tone.
2. Gather every fact already established in the vault (search recaps, parent
   notes, the Campaign Premise, Campaign Flow).
3. Draft the **objective / known** fields yourself (appearance, location, type,
   public role).
4. **Pause and ask the DM** (via the AskUserQuestion tool) about the
   *creative-pivot* fields before writing them — the choices that shape the
   campaign: motivations, secrets, faction loyalties, and plot hooks. Offer 2–4
   concrete options plus room for their own answer.
5. Only after their input, write the file and wire up the wikilinks.

Never invent hard canon (a death, a betrayal, a hidden identity) without
confirming — those are the DM's calls.