---
name: ttrpg-campaign-vault
description: Maintain, consolidate, simplify, and automate TTRPG campaign vaults in Obsidian. Covers two-layer index patterns, merging subfolder files into umbrella docs, fiction-first design preferences, Templater templates, scaffold scripts, Dataview dashboards, cloud sync workflows, and cron automation.
version: 2.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [obsidian, ttrpg, dnd, campaign, vault, consolidation, organization, dm-tools, automation, templates, dataview]
    related_skills: [obsidian, 5etools-query]
---

# TTRPG Campaign Vault

Maintain, consolidate, simplify, and automate TTRPG campaign vaults in Obsidian. This skill covers the full lifecycle: building content, reorganizing when the vault grows unwieldy, keeping it navigable at the table, and adding automation layers (templates, scripts, dashboards, cron jobs).

## Trigger conditions

Load this skill when the user asks to:
- Rebuild, reorganize, consolidate, or simplify their campaign vault
- "Combine similar files" or "make it easier to understand"
- Add a "quick reference" or "at a glance" layer to their vault index
- Merge subfolder files into umbrella documents
- Build or maintain a TTRPG campaign vault (D&D, Pathfinder, etc.)
- Add automation, templates, dashboards, or scripts to their vault
- "Upgrade my campaign" with organization and tooling

## Folder structure conventions

Typical top-level folders:

| Folder | Contents |
|--------|----------|
| `Adventures/` | Session plans, adventure hooks |
| `Factions/` | Organizations, NPC groups |
| `Items/` | Magic items, equipment |
| `Locations/` | Cities, dungeons, regions |
| `Monsters/` | Stat blocks, lore |
| `NPCs/` | Named characters |
| `Ships/` | Ship stats, deck plans, HTML tools |
| `Spells/` | Spell references, house rules |
| `Systems/` | Homebrew rules, combat systems |
| `Templates/` | Reusable note templates (Templater-powered) |
| `Worldbuilding/` | Lore, cosmology, player handouts |
| `scripts/` | Python automation scripts |

## Consolidation pattern (merge subfolder files into umbrella docs)

When a vault grows too many small files across subfolders, it becomes hard to navigate. The user may ask to "rebuild it, combine similar files, keep it simple, understand it in a breeze, maybe also have an extensive explanation lower on the page."

**Steps:**

1. **Read all existing files** in the vault root and subfolders to understand what exists.
2. **Group by topic** into umbrella documents at the vault root. Typical groupings:
   - Campaign concept + running-the-game rules -> `Campaign Core.md`
   - Lore + locations + factions + monsters + adventure hook summaries -> `Worldbuilding.md`
   - Items + spells + magic rules -> `Items & Spells.md`
   - Crew + morale + daily events + port generators + voyage logs -> `Crew & Voyage.md`
   - Ship tiers + naval tools + current ship -> `Ships.md` (or keep as a linking hub if stat blocks are too long)
3. **Move full content into umbrellas.** Copy the actual text, not just links. For files that are too long (adventure session plans, ASCII ship grids, HTML tools), keep them in subfolders and link from the umbrella.
4. **Rewrite `_Index.md` as a two-layer document:**
   - **Top half (breeze-read):** An "At a Glance" table telling readers which file to open based on who they are (player, DM prepping, DM at-table, content builder). Add quick links by job (combat, generation, politics, planning). List campaign arcs.
   - **Bottom half (deep-dive):** Detailed file-by-file breakdown explaining what lives in each umbrella doc, when to use it, and what got merged into it. Include a merge-mapping table showing old files -> new locations. Explain what stays in subfolders and why.
5. **Create `_Retired/`** for old files that are fully superseded (optional; user can archive later).
6. **Sync after all writes** if the vault is cloud-backed.

**Pitfall:** Do not merge files that are actively edited during sessions (e.g., `Current-Ship.md`, HTML trackers). Keep those in subfolders and link them.

**Pitfall:** If two files have conflicting information (e.g., an old `World-Ideas.md` and newer folder files), treat the newer/more focused files as canonical and note the old one as "legacy reference -- check here only if something seems missing."

## Two-layer `_Index.md` pattern

The root `_Index.md` should have two distinct halves separated by a visual break (e.g., `---` followed by `# Detailed Guide`).

**Top half structure:**
- Campaign tagline / one-sentence pitch
- "At a Glance" table: rows are reader roles (player, DM prepping, DM at-table, builder), columns are "Open this file"
- "Quick Links -- By Job" tables: combat, generating content, factions/politics, session planning
- Campaign arcs (1-4 sentences each)

**Bottom half structure:**
- Philosophy / design note (e.g., "Keep It Loose -- story-first rules")
- File-by-file breakdown with: what the file is, what sections it contains, when to use it, what it replaced
- Merge-mapping table (old files -> new locations)
- "What Stays in Subfolders" table (folder, what lives there, why it stayed)
- "How to Add Something New" checklist

## Fiction-first design preferences

When the campaign is story-first (like the Pirate Campaign vault):

- **Crew / morale:** use a single 1-6 "ship mood" rather than per-person loyalty scores, wages, and daily ledgers.
- **Random tables:** prefer 2d6 tables with flavor-first results over d20 bookkeeping tables.
- **NPCs:** keep a small "named crew" roster with trait + vibe + secret; treat the rest as atmosphere.
- **Supplies:** track in buckets (Plenty / Low / Out) rather than exact counts.
- **Inspiration:** Black Flag shanty energy and One Piece found-family/nakama energy.

When revising systems, strip math and hidden percentile checks. Replace them with dramatic scenes and narrative prompts.

## Content Maintenance: Adding External Homebrew

When the user finds a homebrew item (e.g., on Pinterest, Reddit, or a blog) and wants it added to the vault:

1. **Locate the canonical items folder.** In the Pirate Campaign vault this is `6-Rules/Items/`, with an `_Index.md` and a master summary in `2-World/Items & Spells.md`. Adapt to the user's specific vault structure.
2. **Create the item note.** Preserve the full original mechanics, credits, and fan-content disclaimers. Append a campaign-specific twist table or lore hook that ties it into the setting (e.g., Convergence timeline effects).
3. **Update the folder index.** Add a `[[Item Name]]` wikilink and bump the total count.
4. **Update the master summary.** Add a short summary entry (2-3 sentences + link to full note) in the hub document that lists all items/spells.
5. **Sync if the vault is cloud-backed.**

**Template:** See `templates/homebrew-item.md` for the standard note layout.

---

## Automation patterns for TTRPG vaults

Modern TTRPG vaults benefit from a programmable layer: templates, scripts, dashboards, and scheduled tasks.

### Templater-powered templates

Use Templater (not Obsidian's built-in Templates) for structured note creation. Templates should auto-prompt for fields using `tp.system.prompt()` and `tp.system.suggester()`. This front-loads data entry and ensures consistent frontmatter.

**Required fields pattern:**
```yaml
---
name: "<% tp.file.title %>"
role: "<% tp.system.prompt('Role') %>"
faction: "<% tp.system.suggester('Faction', ['Reef Lords', 'Silver Navy', '...']) %>"
tags: [npc, <% tp.system.suggester('Tag', ['ally', 'enemy']) %>]
status: "<% tp.system.suggester('Status', ['alive', 'dead', 'missing']) %>"
---
```

**Template types to create:** NPC, Monster, Location, Session, Item, Faction, Spell.

Store templates in `Templates/` and create a `Templates/_Index.md` explaining how to use them. Configure folder templates in Templater settings so files created in specific folders auto-apply the right template.

### Python scaffold scripts

Store automation scripts in a `scripts/` folder at the vault root. Make them executable (`chmod +x scripts/*.py`).

**`scripts/scaffold.py`** -- Create new entries from templates and auto-update the folder index:
```bash
python3 scripts/scaffold.py npc "Barnaby Salt"
python3 scripts/scaffold.py monster "Deep Horror" --cr 8
python3 scripts/scaffold.py location "Sunken Cathedral"
python3 scripts/scaffold.py session "The Sunken Cathedral"
python3 scripts/scaffold.py item "Cursed Anchor"
python3 scripts/scaffold.py faction "The Drowned Court"
python3 scripts/scaffold.py spell "Tidal Wave"
```

**`scripts/port-generator.py`** -- Roll random ports/islands from campaign tables:
```bash
python3 scripts/port-generator.py port --save 2-World/Locations
python3 scripts/port-generator.py island --save 2-World/Locations
```

**`scripts/index-generator.py`** -- Rebuild all `_Index.md` files by scanning frontmatter:
```bash
python3 scripts/index-generator.py --all
python3 scripts/index-generator.py --folder 2-World/NPCs
```

**`scripts/analyzer.py`** -- Vault health check (orphans, broken links, tag stats, word counts):
```bash
python3 scripts/analyzer.py --all
python3 scripts/analyzer.py --orphans
python3 scripts/analyzer.py --broken
python3 scripts/analyzer.py --tags
```

**`scripts/sync-wrapper.sh`** -- Safe credential-loading wrapper for iCloud sync:
```bash
bash scripts/sync-wrapper.sh  # reads ~/.hermes/.env, sets APPLE_PASSWORD
```

### Dataview dashboards

Create dashboard notes tagged with `#dashboard` for live-updating views. Dashboards use Dataview queries that auto-update when underlying notes change.

| Dashboard | File | Contents |
|-----------|------|----------|
| Master Dashboard | `1-Campaign/Dashboard.md` | Campaign status, quick links, recent activity, vault stats, automation commands, session prep checklist |
| DM Quick Screen | `1-Campaign/DM-Screen.md` | One-page quick reference -- mood tracker, supplies, daily events, situation tables, naval combat, firearms |
| NPC Directory | `2-World/NPCs/_Index.md` | NPCs by faction, status, location; recently added |
| Adventure Log | `2-World/Adventures/_Index.md` | Session archive by arc, notoriety tracker, crew mood timeline, hooks |
| Ship Tracker | `3-Ships/_Index.md` | Ship tiers, upgrade wishlist, encounter log, rival captains |

Key Dataview patterns:
```dataview
TABLE role AS "Role", faction AS "Faction", file.mtime AS "Updated"
FROM #npc
WHERE faction = "Silver Navy"
SORT file.name ASC
```

```dataviewjs
const counts = {}
for (const p of dv.pages()) {
    for (const t of p.file.tags || []) counts[t] = (counts[t] || 0) + 1
}
const sorted = Object.entries(counts).sort((a,b) => b[1]-a[1]).slice(0,20)
for (const [tag, count] of sorted) dv.paragraph(`#${tag} (${count})`)
```

### Cron jobs (Hermes scheduler)

| Task | Schedule | Command |
|------|----------|---------|
| iCloud sync | Every 2 hours | `bash scripts/sync-wrapper.sh` |
| Vault health check | Daily at 9 AM | `python3 scripts/analyzer.py --all` |
| Rebuild indexes | Every 6 hours | `python3 scripts/index-generator.py --all` |

Use the `cronjob` tool with `workdir` set to the vault path.

### Pitfall: Orphaned legacy content

When merging old files into umbrella docs, the originals remain as orphaned notes (no incoming links). They still exist for reference but clutter the vault. Run `analyzer.py --orphans` periodically and either add links to them from the new hub docs, move them to `_Archive/`, or delete them once confirmed obsolete.

### Pitfall: Broken wikilinks after reorganization

Moving files breaks `[[OldFolder/FileName]]` links. After any reorganization, run `analyzer.py --broken` and fix all broken links before syncing. The most common breakage patterns are:
- `[[Adventures/_Index]]` -> `[[2-World/Adventures/_Index]]`
- `[[Ships/Current-Ship]]` -> `[[3-Ships/Current-Ship]]`
- `[[Templates/_Index]]` -> `[[4-Tools/Templates/_Index]]`

### Pitfall: Template syntax in .md files

Templater uses `<% %>` syntax. When creating templates programmatically (via `write_file`), these markers look like HTML tags and may confuse renderers. Write them as literal strings in the file content. When Obsidian opens the file, Templater processes them interactively.

### Pitfall: Creating vault content without Obsidian-native conventions

When building campaign notes programmatically (via `write_file`), always use Obsidian-native formatting: YAML frontmatter, wikilinks (`[[Note Name]]`), and inline tags (`#tag`). Do not emit plain markdown with external-style links or heading-only structure. The user expects vault content that works with Obsidian's graph view, Dataview queries, and metadata cache. If the user says "Use your obsidian skill for this," they mean: apply the full Obsidian formatting stack, not just dump text into .md files.

---

## Cross-Cutting Theme / Inspiration Documentation

When a user asks "How does [X] influence this campaign?" or wants a dedicated file tracking a specific creative influence (Assassin's Creed, One Piece, Dark Souls, etc.), the references are usually scattered across dozens of files — mechanics in `Systems/`, story beats in `Story/`, items in `Items/`, and tone notes in `Ideas/`.

**Steps:**

1. **Search broadly with multiple patterns.** Run `search_files` with several regexes covering:
   - Direct names (`(?i)(assassin.*creed|black flag|kenway|jackdaw|edward)`)
   - Conceptual parallels (`(?i)(templar|animus|synchronization|eagle vision|haystack|leap of faith)`)
   - Mechanics (`(?i)(boarding|notoriety|wanted level|shanty|crew morale|ship capture)`)
   - Thematic echoes (`(?i)(memory|timeline|convergence|bleed|fragment|harvest)`)
   Use `context=3` or `context=5` to capture surrounding sentences.

2. **Read the primary inspiration doc.** Most vaults have a file like `Black-Flag-Inspirations.md` or `Ideas.md` that explicitly names the source. Read this first to understand the stated intent.

3. **Categorize findings into layers:**
   - **Surface mechanics** — directly stolen gameplay systems (boarding rules, shanty morale, notoriety track)
   - **System design** — how the source shaped the campaign's bones (ship-as-character, zone-based naval combat)
   - **Narrative architecture** — hidden structural parallels (the Convergence as the Animus reframed)
   - **Thematic DNA** — moral space, identity questions, cost-of-knowledge themes

4. **Write the reference file.** Create a dedicated `.md` file (e.g., `7-Reference/Assassin's-Creed-Inspirations.md`) with:
   - An overview stating the source and the depth of influence
   - One section per layer (Mechanics, Systems, Story, Themes)
   - File-by-file citations with line-number context
   - A quick-reference table mapping source concepts → campaign equivalents
   - DM guidance on how to lean in or out of the influence

5. **Update the folder index.** Patch the local `_Index.md` (e.g., `7-Reference/_Index.md`) to link the new file.

6. **Sync** if the vault is cloud-backed.

**Pitfall:** Do not stop at the explicit inspiration doc. The deepest parallels are often unstated — e.g., the Convergence-as-Animus frame is never named in `Black-Flag-Inspirations.md`, but exists in memory mechanics, timeline-bleed events, and the Kraken's memory-harvesting. Search the full vault, not just files that mention the source by name.

**Template:** See `templates/theme-inspiration-reference.md` for the standard layout.

---

## Campaign Arc Chapter Development

When a user wants to build out a full campaign story with chapters, requirements, and a trajectory document, use this pattern. It was developed for the Pirate Campaign vault and scales to any multi-arc TTRPG story.

### What to create

1. **Master trajectory document** — e.g. `2-World/Story/Story Trajectory.md` — containing:
   - Arc-level overview (4-5 arcs, with themes and level ranges)
   - Chapter flowchart (ASCII or bulleted) showing dependency chains
   - Requirements table per chapter: prerequisites, completion conditions, failure states, what unlocks next
   - Arc emotional beats and key questions
   - Flexible/branching notes for chapters that can be swapped or skipped

2. **Per-chapter files** — e.g. `2-World/Story/Chapter 01 — The Awakening.md` through `Chapter 14 — The Convergence End.md` — each following a consistent structure:
   - YAML frontmatter with `chapter`, `arc`, `level`, `prerequisites`, `next-chapter`, `tags`
   - The Pitch (read-aloud opening text)
   - Narrative Purpose (5 bullet points on what this chapter delivers)
   - Requirements to Start / Requirements to Complete (tables)
   - Acts (1-4 per chapter), each with scenes, encounters, NPCs, and read-aloud text
   - Key NPCs section with stats suggestions, motivations, and can-become notes
   - Rewards table
   - Timeline Hooks to Plant (foreshadowing for later chapters)
   - DM Notes (scaling, pacing, failure states, what-if branches)
   - Related section with wikilinks to prev/next chapters and existing vault content
   - Tags footer

3. **Folder index** — `2-World/Story/_Index.md` — tabular listing of all chapters by arc, with links and levels.

### Chapter file conventions

- Link backward and forward: `next-chapter` in YAML and a "Related" section with `[[Chapter X — Name|Display]]` and `[[Story Trajectory]]`
- Requirements should be explicit and testable: not "they need a ship" but "Have a ship: from Chapter 2 or equivalent"
- Failure states are listed with recovery paths: "Ship captured -> prisoner breakout arc"
- Each chapter connects to existing vault content: adventure summaries, locations, factions, monsters, items. Use wikilinks heavily.
- Flexible placement: note which chapters can be moved or skipped, and what alternatives exist.

### When to use this pattern

- User says: "I need to think of chapters, requirements, and create files for the story"
- User wants: "a full story trajectory with sub-files for each chapter"
- User has an existing campaign with adventure summaries but no cohesive narrative arc linking them

### How it relates to existing content

This pattern does not replace the `Adventures/` folder. `Adventures/` holds original session-plan summaries (brief overviews, objectives, complications). The `Story/` folder holds the expanded narrative arc: full acts, scenes, NPCs, read-aloud text, DM notes, and inter-chapter requirements. Both coexist — the Story files link to the Adventure summaries, and vice versa.

**Template:** See `templates/campaign-chapter.md` for the standard chapter note layout.

## Quick Rules Cheat Sheet Folder

When a campaign accumulates homebrew rules (naval combat, firearms, morale, ship stats), the full rule files become too long for at-the-table reference. Create a dedicated `0-Quick-Rules/` folder at the vault root with stripped-down cheat sheets.

### Naming convention
- Folder: `0-Quick-Rules/` (the `0-` prefix keeps it at the top of the file tree)
- Files: `{System-Name}-Quick-Ref.md` (e.g., `Naval-Combat-Quick-Ref.md`)
- Index: `0-Quick-Rules/_Index.md` listing all quick refs with links to full rules

### What goes in a quick ref
- Only tables, numbers, and die-roll procedures
- No prose, no flavor text, no philosophy
- Every file ends with a link to its full rules (e.g., `*Full rules: [[Naval Combat Quick Rules]]*`)

### What to include

| Quick Ref File | Contents |
|----------------|----------|
| Naval Combat | Initiative, zones, cannon to-hit formula, damage by type, hit location (d6), boarding grapple, sinking, ship actions, minimum crew, morale modifiers |
| Ship Stats | All ship tier blocks (AC, HP, speed, crew, cannons), NPC ship blocks, component HP |
| Morale & Events | Morale track with modifiers, where it applies, mood up/down triggers, d12 daily events table, optional weighted roll, Captain's Orders |
| Firearms | Weapon stats table, shipboard mods, misfire (d6), nat 20 options, weather effects, powder explosions |
| Crew Orders | Orders list with mood costs, hiring results, named crew template, supplies tracking |

### Integration
- Add `0-Quick-Rules/_Index` to the root `_Index.md` "At a Glance" table (row: "Needing a quick rule at the table")
- Add it to the "Running the Table" quick links section
- Update `DM-Screen.md` to point to the quick refs instead of duplicating tables
- Keep `DM-Screen.md` as the one-page summary; let `0-Quick-Rules/` be the deep-cheat-sheets

### When to create
Create this folder when the user says something like:
- "Make a folder for only quick rules which reference their respective folders"
- "I want something I can print and keep behind the screen"
- The full rules have grown past ~2,000 words and the DM needs a faster lookup

**Pitfall:** Do not duplicate the full rules. Quick refs are summaries only. If a rule is ambiguous in the quick ref, the DM opens the full file, not the quick ref.

**Pitfall:** Update quick refs when the full rules change. A stale quick ref is worse than no quick ref. After any rule revision, check whether the corresponding quick ref needs updating.

---

## Pre-Made Quests Folder

When the user wants a ready-to-grab content library for low-energy prep sessions, create a `9-Quests/` folder at the vault root with standardized templates the DM can drop into play with minimal rewriting.

### Folder structure
```
9-Quests/
  Dungeons/         -- fully mapped dungeons/ruins with room keys and loot
  Side-Quests/      -- 1-2 hour social, investigation, or bounty content
  Main-Quests/      -- multi-session campaign-driving content
  One-Shots/        -- self-contained single-session adventures
```

### Naming convention
- Files: `Descriptive-Name.md` (e.g., `The-Smugglers-Daughter.md`, `Sunken-Temple-of-the-Brine-God.md`)
- Index: `9-Quests/_Index.md` listing all quests by type and level

### Standard quest template
Every pre-made quest should follow the same layout so the DM can scan it in 30 seconds:

1. **Frontmatter:** type, level_range, estimated_playtime, difficulty, tags
2. **Hook:** one paragraph, in-world
3. **Location / Setup:** travel time, hazards, arrival
4. **Key Areas / Acts:** numbered sections with encounter, trap, loot
5. **Complications:** 1-3 twists or secondary objectives
6. **Rewards:** gp, items, favors, peaceful-resolution XP
7. **Quick Stat Blocks:** compact creature table (Name | HP | AC | Attack | Notes)
8. **Drop-In Variant:** how to reskin with existing campaign NPCs/locations
9. **Related:** wikilinks to campaign references

### Quest types and when to use them

| Subfolder | Content | When to Grab |
|-----------|---------|--------------|
| Dungeons | Mapped locations with room keys, traps, environmental mechanics | Need a mapped location for tonight's session |
| Side-Quests | Bounty hunts, missing persons, smuggling investigations, social intrigue | Need filler between arcs or a session that runs short |
| Main-Quests | Multi-session events (tournaments, sieges, heists) with branching outcomes | Need a campaign centerpiece or faction conflict |
| One-Shots | Self-contained stories with clear start/middle/end for a single session | Guest players, backup session, low-prep week |

### Integration
- Add `9-Quests/_Index` to the root `_Index.md` "At a Glance" table (row: "Needing content fast")
- Tag every quest with `#quest` and a type tag (`#dungeon`, `#bounty`, `#social`, etc.) for Dataview queries
- Link back to existing campaign content (locations, factions, NPCs) so the quest feels native, not generic

### When to create
Create this folder when the user says something like:
- "Add a folder for quick premade quests I can grab when I'm not feeling creative"
- "I want ready-to-go content for low-energy prep nights"
- The vault has plenty of rules and lore but no drop-in adventure content

**Pitfall:** Do not write generic fantasy quests. Every quest must include a "Drop-In Variant" section showing how to reskin it with the campaign's existing NPCs, factions, or locations. Generic content is useless; native-feeling content is gold.

**Pitfall:** Do not forget loot tables and quick stat blocks. The DM grabbing this at the last minute does not have time to build encounters from scratch.

**Template:** See `templates/quest-premade.md` for the standard layout.

---

## Trade Goods & Economy Reference

When the user wants a price list for commodities, equipment, supplies, and trade goods:

1. **Create a dedicated folder** under `Tools/` (e.g., `4-Tools/Trade-Goods/` or `Tools/Economy/`). Do not dump the price list into an existing umbrella doc — it will be too long and hard to reference at the table.
2. **Organize by category** with markdown tables: Spirits & Drink, Foodstuffs, Ship Supplies, Weapons & Powder, Cloth & Textiles, Metals & Ore, Luxuries & Exotics, Livestock, General & Sundry.
3. **Use standard D&D currency** (cp/sp/gp/pp) with per-unit pricing: barrel, sack, lb, oz, each, bottle, etc.
4. **Include modifiers:** remote port (+50-100%), blockaded (+200-500%), pirate/smuggler source (-40-60%), bulk purchase (-10-20%), guild monopoly (+30-50%).
5. **Add a smuggling quick reference** — highest value-to-weight goods (spices, silk, pearls, gold dust), easiest to move (rum, tobacco, sugar), riskiest (gunpowder, slaves, identifiable stolen goods).

**When to create:**
- "I need prices for rum, food, gunpowder, cloth, metal, etc."
- "Make a price list for trade goods"
- The campaign involves smuggling, trading, or port economy

**Pitfall:** Do not list prices as "per item" generically. A DM at the table needs to know "barrel of rum = 15 gp" not "rum = varies." Be specific about quantities.

**Pitfall:** Include both bulk and small-unit prices. The DM needs both: "How much for a barrel?" and "How much for one bottle in a tavern?"

---

## Rule Revision Patterns

When a user wants to rewrite existing homebrew rules — e.g., "make naval combat d20-driven with hit locations" or "simplify ship stats into premade blocks" — follow this pattern instead of treating it as a content-add:

1. **Read the current rule file(s) first.** Do not overwrite blindly. Use `read_file` to capture the existing rules, stat blocks, and any linked systems (e.g., firearms, crew morale).
2. **Identify all files that reference the old rules.** Search for the rule file name, key terms (e.g., "boarding", "grapple", "ship actions"), and linked system names. Update them if the new rules make them stale.
3. **Rewrite the core rule file** with the new mechanics. Preserve the file path if possible so existing links do not break. If you must rename, leave a stub or update all incoming links.
4. **Extract stat blocks into a dedicated template file** when the user wants "premade ships with AC, speed, cannon slots, crew." Create a `Ship-Templates.md` (or equivalent) with simple table blocks, minimum crew thresholds, and component HP. Keep the original tier files as layout/deck-plan references.
5. **Create a new morale/events file** if the user wants morale to be a single modifier applied to all ship rolls. Extract this from the old `Crew-and-Morale.md` into a focused `Ship-Morale-and-Events.md` with a d12 daily event table.
6. **Update all `_Index.md` files** in affected folders to point to the new files.
7. **Sync once** after all writes are done.

**Pitfall:** Do not create a third morale system if one already exists. Either replace the old one entirely or extend it. The user in this session had both `Crew-and-Morale.md` (1-6 track, no modifier) and the new `Ship-Morale-and-Events.md` (1-6 track with +2 to -4 modifier). The new file supersedes the old one for ship rolls; the old file stays for non-ship crew scenes.

## Cloud sync workflow

If the vault is backed by iCloud Drive on a headless Linux host:

1. Check for a vault-local sync script (e.g., `scripts/sync_to_icloud.py`).
2. Set `APPLE_PASSWORD` from the user's `.env` (note: `.env` may store `APPLE_ID_PASSWORD` or `APPLE_APP_PASSWORD`; map the correct one to `APPLE_PASSWORD` before invoking).
3. Run the sync script after all file writes.
4. If 2FA is required, the script will fail; the user must re-authenticate interactively.

### Bidirectional sync requirement

The default push-only script (local → iCloud) **will destroy edits made from other devices** (Mac, iPad, phone). When the user edits on their Mac and the server syncs later, the server overwrites the newer iCloud version with its older local copy.

**The sync script must be bidirectional:**
- **Phase 1 (Upload):** New local files → uploaded to iCloud. Files that exist on both with the same size → skipped. Files that exist on both with **different sizes** → **skipped with a warning** (never overwrite). This preserves edits from other devices.
- **Phase 2 (Download):** New iCloud files (created from Mac/iPad) → downloaded to the server.
- **Excluded directories:** Skip `.obsidian/` internals and `scripts/` — they change constantly and cause noise/conflicts.

**Implementation details:**
- pyicloud `DriveNode` objects use `.open().read()` to download content, not `.get_content()`.
- Skip files with `.obsidian` in the path during both upload and download walks.
- Skip `scripts/` during upload — the server scripts don't need to be in iCloud.
- When a conflict is detected (same file, different sizes), log `[SKIP] filename — differs from iCloud (edited elsewhere?)` and continue. Let the user resolve manually.

**Pitfall:** The terminal tool may block commands that pass env vars via shell interpolation (e.g., `APPLE_PASSWORD="$(...)" python3 scripts/sync.py`). When this happens, use `execute_code` to set env vars in Python and run the script via `subprocess.run()` instead.

**Pitfall:** Do NOT assume a sync script is safe. Always read it first. If it deletes iCloud files before re-uploading (the old pattern), patch it to the bidirectional behavior above before running it again.

See `references/icloud-bidirectional-sync.md` for the complete implementation code.

See `obsidian:references/icloud-vault-access.md` for the full pyicloud recipe.

## References

- `references/consolidation-example.md` -- Full example from the Pirate Campaign reorganization, including the exact merge-mapping table and two-layer `_Index.md` structure.
- `references/automation-scripts.md` -- Complete scaffold, generator, index, and analyzer script sources with usage patterns.
- `references/dashboard-patterns.md` -- Dataview dashboard templates for NPC directory, session log, ship tracker, and DM quick screen.
- `references/pirate-homebrew-items.md` -- Curated research bank of 50+ pirate/nautical homebrew magic items from RollDFive, LitRPG Reads, and Pinterest, with source attribution and quick-lookup tables for populating a campaign vault.
- `references/rule-revision-example.md` -- Full example of rewriting existing homebrew rules (naval combat overhaul): reading before rewriting, preserving paths, extracting stat blocks, creating focused morale/events files, and updating indexes without breaking links.
- `references/icloud-bidirectional-sync.md` -- Complete implementation of a conflict-safe bidirectional iCloud sync script (pyicloud). Uploads new local files, downloads new iCloud files, skips conflicts. Includes credential mapping and API quirks.
- `templates/theme-inspiration-reference.md` -- Standard layout for documenting a specific creative influence (e.g., Assassin's Creed, One Piece) across the vault, with sections for Surface Mechanics, System Design, Narrative Architecture, Thematic DNA, and DM lean-in/out guidance.
- `templates/campaign-chapter.md` -- Standard chapter note layout for the Campaign Arc Chapter Development pattern (YAML frontmatter, requirements tables, acts, NPCs, hooks, DM notes, prev/next links).
- `templates/quest-premade.md` -- Standard layout for pre-made drop-in quests: frontmatter, hook, key areas, complications, rewards, quick stat blocks, and drop-in variant section.
- `templates/homebrew-item.md` -- Standard layout for adding external homebrew items with mechanics, credits, campaign-specific twists, and index updates.

## Player-Facing Campaign Wiki

When the campaign vault grows rich with lore, locations, NPCs, and session history, players often ask for a wiki — a browsable, living document they can check between sessions. This is a different problem from the DM's private vault.

### The core tension

The DM vault contains secrets: future plot, monster stat blocks, hidden NPC motives, location details the players have not discovered. The player wiki must be a curated, sanitized slice. The ideal tool supports a **slow reveal** — content is written once with GM notes attached, then "unlocked" for players when they discover it in-game.

### Option comparison

| Feature | **Kanka** | **BookStack** | **Wiki.js** | **DokuWiki** | **Obsidian Publish** |
|---|---|---|---|---|---|
| Built for RPGs | **Yes** — quests, timelines, maps, dice | No — generic docs | No — generic docs | No — generic docs | No — it's a note publisher |
| Slow reveal / GM secrets | **Yes** — every entity has an "Admin Only" secrets tab | Partial — per-book permissions only | Yes — complex roles | Yes — ACL-based | **No** — published note = fully public |
| Session summaries as timeline | **Yes** — journals linked to campaign timeline | Just pages | Just pages | Just pages | Just pages |
| Interactive world map | **Yes** — clickable pins with fog-of-war | No | No plugins | No | Static images or Canvas |
| Player-friendly UI | **Excellent** — purpose-built | Good — clean | Good — modern | Poor — dated | Good — but it's your vault layout |
| Self-hosted | **Yes** (Docker) | **Yes** (Docker) | **Yes** (Docker) | **Yes** (flat files) | **No** — SaaS only (~$8/month) |
| Free | Free tier + self-hosted | Open source | Open source | Open source | Monthly subscription |
| Obsidian integration | Export API only | None | None | None | Native (same vault) |

### Why Obsidian Publish is the wrong tool for a player wiki

Obsidian Publish has no concept of a "GM-only section" within a published page. A published note is public to everyone who has the link. To use it safely, you would need to maintain a **second, sanitized vault** and manually sync curated reveals from your DM vault into it. This creates double maintenance: every NPC update, every location revision, every session summary requires copying to the player vault and toggling publish. There is no "unlock" button.

Community workarounds (Digital Garden, GitHub Pages exports) have the same problem: no inline secrets, no permission layers. They are also complex to set up and still require manual sanitization.

### Why Kanka is the best fit

Kanka is the only option where the slow-reveal workflow is first-class:
1. Write an NPC entry with the public description visible to players.
2. Add GM secrets (true motives, future plot, stat blocks) in the "Admin Only" tab.
3. After the party discovers something in-game, click "Visible to Players" on the relevant fields.
4. The players see the update organically, not through exposition.

Additional RPG-native features:
- **Quests** with statuses (Active, Completed, Failed) and requirement tracking
- **Organizations** with member hierarchies (perfect for pirate crews and factions)
- **Timelines** that players can browse to see how the story unfolded
- **Interactive maps** — upload an archipelago map, drop pins as locations are discovered
- **Journals** — session summaries that auto-link to the campaign timeline

### Recommended workflow

**Keep Obsidian as your DM Command Center.** Do not try to turn it into a player wiki.

**Deploy Kanka as the player wiki.** After each session:
1. Review what the players learned in your Obsidian session notes.
2. Open Kanka, flip visibility on newly discovered entities (locations, NPCs, lore).
3. Write a journal entry summarizing the session — this becomes the timeline.
4. Players browse between sessions.

This is a deliberate two-system architecture. The DM vault is for prep, secrets, and improvisation. The player wiki is for curated reveals and session history. The cost of maintaining both is lower than the cost of sanitizing a single vault for public consumption.

### When to choose BookStack instead

BookStack is the right choice if:
- Your players are comfortable with a wiki-style browse experience.
- You want to export content from Obsidian with minimal reformatting.
- You do not need interactive maps or timeline views.
- You prefer one simpler tool over Kanka's entity-heavy structure.

The trade-off: slow reveal is clunky. You need two books ("Known World" and "DM World") or manage per-page permissions manually.

### Setup recommendation

- Self-host Kanka on Docker (Proxmox LXC or local Linux).
- Expose via Tailscale Funnel for a clean HTTPS URL players can access without Tailscale accounts.
- Use the Kanka API or manual copy-paste to populate initial content from your Obsidian vault.

**Pitfall:** Do not try to auto-sync Obsidian vault content into Kanka bidirectionally. The two systems have different data models. Treat Kanka as a curated publication layer, not a mirror.

**Pitfall:** If players write session summaries in Kanka, remember that their perspective may contain in-character misinformation. That is a feature, not a bug — but the DM should review journals before accepting them as canon.

## Related Skills

- `obsidian` -- general Obsidian vault work, iCloud sync, wikilinks, CLI, URI scheme, plugin ecosystem, API deep dive
- `5etools-query` -- querying official D&D data for stat blocks and items