# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

This is **not a code project.** It is the **Obsidian vault for a homebrew D&D campaign set in the world of Baltun'ia.** "Working in this repository" means reading, writing, and cross-linking Markdown lore notes — there is no build, lint, or test step. The user is the **DM**; the central plot is in `Campaign Premise.md` (a conspiracy drilling into the mountains to fracture and choke the **ley lines** that carry magic, to revive Rangrim's imperial ideology and enslave the automatons).

Obsidian-specific files: `Index File.base` is an Obsidian **Bases** view (filters out anything whose path starts with `z`). Active community plugins are **Smart Connections** (the `.smart-env/`, `.smtcmp_*` directories — vector index, do not hand-edit) and **Text Format**.

## Vault architecture (the "big picture")

The world is a graph held together by `[[wikilinks]]`, organized into a deliberate hierarchy:

```
1. History of Baltun'ia/   Lore by Age (Ancient → Fourth). Each Age has Key Figures/ and Key Locations/.
2. World Almanac/          The living present world:
   Factions/<Faction>/<Faction> Overview.md   — political/criminal/guild power blocs
   Regions of Baltun'ia/<Region>/<Region>.md
      <City>/<City>.md
         <POI>/<POI>.md                         — a visitable site (tavern, market, theater…)
            <NPC Name> - <POI>.md               — NPCs live BESIDE the POI they belong to
         Documents/                             — in-world handouts (speeches, letters, propositions)
   Species/ · Deities/(+ Minor Deities/) · Creatures/(+ Natural World/) · Economy/ · Languages/
3. Session Recaps/         "N. Title - M-D-YY.md", flat, narrative prose of what happened in play
z_templates/Framework Templates/  NPC / Location / Faction / POI templates (filled-in copies become real notes)
z_other/                   Monologues; Campaign Flow.md (a mermaid flowchart of the live plot)
```

Two things make this navigable and must be preserved when adding content:

1. **Containment = folders.** A region contains cities contain POIs contain NPCs. Placement *is* meaning — put a note in the wrong folder and it's lost.
2. **The link graph.** Lore in a written note and what happened *in a Session Recap* are equally canonical; recaps are where new NPCs/places first appear before they get their own note. When adding an entity, also add a reciprocal `[[link]]` from its parent (NPC → parent POI's "Notable NPCs"; POI → city's "Notable Features"; city → region's "Notable Cities"; faction → `Faction Relationships.md`).

## Note conventions (non-negotiable — match hand-written notes exactly)

- **No YAML frontmatter.** Existing notes have none; do not add it.
- Notes are **heading-based** (`###`/`##`), filled from the relevant `z_templates/Framework Templates/` file. **Rename/drop sections to fit the subject** rather than leaving empty boilerplate (e.g. a POI's "History & Lore" became "Lore & Role in Voxiu").
- **Wikilink the first mention** of any species, region, city, faction, deity, POI, or NPC. Use `[[Note Name|display text]]` when the filename differs from the prose (e.g. `[[Belter Overview|Belters]]`, `[[House of Suits Overview|the Suits]]`). A `[[Red Link]]` to a not-yet-written note is **intentional and correct** — it marks a future stub; flag these to the DM.
- **Notable-NPC entries:** bold name + role + `*(race)*`, then a `→` line with the hook. (Some folders use an em-dash variant — match the local file's style.)
- **Naming:** NPC files are `<Full Name> - <POI or City>.md`; historical figures go in an Age's `Key Figures/<Name>.md`; overview files are named for their container (`Belters/Belter Overview.md`). Session recaps: next integer `N`, real date with no leading zeros (`9-8-25`).
- Keep canonical content **out of `z_*`** folders (they're excluded from the Index Base on purpose).
- Note files contain unicode punctuation (curly quotes `" "`, en-dashes `–`, non-breaking hyphens `‑`). When using the Edit tool, anchor on plain-ASCII substrings to avoid match failures.

## Generation style: collaborative

The DM has chosen a **collaborative** workflow for invented content (see `.claude/skills/_shared/vault-conventions.md` and the `dm-collaborative-style` memory). Draft the *objective* fields yourself (appearance, location, type, public role), but **pause and ask** (AskUserQuestion) before inventing the *creative pivots* — motivations, secrets, faction loyalties, plot hooks. **Never invent hard canon** (a death, betrayal, hidden identity) without confirmation; those are the DM's calls. When the DM supplies a full brief, build it faithfully instead of re-asking.

## Campaign skills (in `.claude/skills/`)

Invoke these instead of working from scratch — each reads `_shared/vault-conventions.md` first:

- **`/create-npc`**, **`/create-location`** (region/city), **`/create-poi`**, **`/create-faction`** — create entities from the templates, correctly placed, wikilinked, and back-linked.
- **`/session-recap`** — turn raw session notes into a numbered/dated narrative recap, then propagate changes to the entities that appeared.
- **`/session-prep`** — assemble a DM brief (scenes, NPCs, faction agendas, open hooks) for wherever the party is.
- **`/lore-lookup`** — answer in-world/continuity questions with citations to source notes and recaps.
- **`/lore-audit`** — find broken/typo wikilinks, orphans, missing reciprocal links, entities mentioned in play but never written up, and contradictions.