--- name: ttrpg-vault-organization description: "Consolidate and reorganize sprawling TTRPG campaign Obsidian vaults into clean, numbered hub-folder structures. Covers merging files, updating wikilinks, archiving retired content, and maintaining the new layout." version: 1.0.0 author: Hermes Agent license: MIT platforms: [linux, macos, windows] metadata: hermes: tags: [Obsidian, TTRPG, Campaign, Vault, Organization, Consolidation, Reorganization, Markdown] related_skills: [obsidian, 5etools-query] --- # TTRPG Vault Organization Use this skill when a TTRPG campaign vault has grown unwieldy: too many files in the root, duplicate `_Index.md` files, confusion about which file is canonical, or the user says "there are too many files" / "this is messy" / "I can't find things." The goal: a clean, numbered hub-folder structure with a single root `_Index.md` that acts as the navigation hub. --- ## When to Reorganize Reorganize when any of these are true: - 20+ files in the vault root - Multiple "index" or "overview" files competing for attention - The user explicitly says the vault is hard to navigate - Content is scattered across duplicate or near-duplicate files (e.g., `Ideas.md` and `World-Ideas.md`) - Subfolders exist but their purpose is unclear --- ## The Consolidated Hub Structure Replace flat folders with numbered hubs. The number prefix forces a logical reading order and keeps the root clean. | Hub | Contents | Example | |-----|----------|---------| | `1-Campaign/` | Core docs: pitch, themes, arcs, running-the-game rules, session-zero material | `Campaign Core.md`, `Crew & Voyage.md` | | `2-World/` | Lore, locations, factions, monsters, adventure summaries, items/spells, NPCs, full adventures | `Worldbuilding.md`, `Items & Spells.md`, `Adventures/`, `NPCs/` | | `3-Ships/` | Vessel stats, deck plans, current-ship tracker | `Ships.md`, `Current-Ship.md`, `Ship-Tier-*.md` | | `4-Tools/` | Templates and browser-based session aids | `Templates/`, `HTML/` | | `_Archive/` | Retired old files and meta project plans | Old merged folders, website build plans, pre-merge originals | **Root contents:** `_Index.md` only (plus the numbered hubs and any utility folders like `scripts/`). --- ## The Hub Document Pattern Each hub contains **one or two large consolidated `.md` files** that merge the content of many smaller files. **Example merges:** - `1-Campaign/Campaign Core.md` absorbs `Ideas.md` + `Black-Flag-Inspirations.md` + all `Systems/*.md` rules into a single DM reference. - `2-World/Worldbuilding.md` absorbs `Locations/` + `Factions/` + `Monsters/` + `Adventures/_Index.md` hook summaries. - `2-World/Items & Spells.md` absorbs all `Items/*.md` and `Spells/*.md` files. - `1-Campaign/Crew & Voyage.md` absorbs `Systems/Crew-*` + `Daily-*` + `Port-Island-Generator`. **What stays in subfolders:** - Full session plans (too long to merge) -> `2-World/Adventures/` - Named NPC files (grow as campaign progresses) -> `2-World/NPCs/` - Ship stat blocks with ASCII grids (too bulky) -> `3-Ships/` - HTML browser tools -> `4-Tools/HTML/` - Blank templates -> `4-Tools/Templates/` --- ## Step-by-Step Reorganization ### 1. Inventory Everything List every file in the vault (excluding `.obsidian/` and utility scripts). Identify: - **Canonical content files** -- the ones that matter - **Duplicates or near-duplicates** -- merge these - **Old / retired files** -- move to `_Archive/` - **HTML tools** -- keep them, but group them ### 2. Plan the Merges Decide which files will be absorbed into hub documents. Read each file first to understand its content. Create a mapping table: | Old File(s) | New Hub Document | Section | |---|---|---| | `Ideas.md` + `Black-Flag-Inspirations.md` | `1-Campaign/Campaign Core.md` | Pitch, themes, running rules | | `Locations/*.md` (4 files) | `2-World/Worldbuilding.md` | Locations section | | `Items/*.md` (6 files) | `2-World/Items & Spells.md` | Magic Items section | ### 3. Create Hub Documents Write each hub document using `write_file`. Include: - A top-level summary / "at a glance" table - All merged content, organized by section - Links to subfolder files that were NOT merged ### 4. Create the New Folder Structure ```bash cd ~/obsidian-vault/Campaign-Name mkdir -p 1-Campaign 2-World/Adventures 2-World/NPCs 3-Ships 4-Tools/HTML 4-Tools/Templates _Archive ``` ### 5. Move Files ```bash mv "Campaign Core.md" "1-Campaign/" mv "Worldbuilding.md" "2-World/" mv "Adventures/" "2-World/" mv "Current-Ship.md" "Ship-Tier-*.md" "3-Ships/" mv "Templates/" "4-Tools/" mv Old-Duplicate.md Old-Retired-Folder/ _Archive/ ``` ### 6. Update Wikilinks **This is critical.** Moving files breaks every `[[OldFolder/FileName]]` wikilink. Search all `.md` files for broken links: ```bash grep -r "\[\[Ships/\|\[\[Templates/\|\[\[Adventures/\|\[\[Items/\|\[\[Spells/\|\[\[Locations/\|\[\[Factions/\|\[\[Monsters/\|\[\[Systems/\|\[\[Worldbuilding/" --include="*.md" . ``` Update each link to point to the new location. Examples: - `[[Ships/Current-Ship]]` -> `[[Current-Ship]]` (if in same folder) or `[[3-Ships/Current-Ship]]` (if cross-hub) - `[[Adventures/_Index]]` -> `[[2-World/Adventures/_Index]]` - `[[Templates/_Index]]` -> `[[4-Tools/Templates/_Index]]` - Bare file references like `[[Campaign Core]]` -> `[[1-Campaign/Campaign Core]]` ### 7. Update the Root `_Index.md` Rewrite the root `_Index.md` to reflect the new structure: - **Top half (breeze):** An "At a Glance" table mapping user roles to hub files - **Bottom half (deep dive):** File-by-file breakdown of each hub, a "What Got Merged" table, and a "What Stays in Subfolders" table ### 8. Archive the Old Files Move the old pre-merge files and folders into `_Archive/`. Do not delete them immediately -- the user may want to recover something. After a week or two, the `_Archive/` folder can be deleted if the user confirms everything is working. ### 9. Clean Empty Directories Remove empty folders left behind after moving: ```bash find . -type d -empty -delete ``` ### 10. Sync Run the vault's sync script (e.g., `python3 scripts/sync_to_icloud.py`) to push the reorganized structure to all devices. --- ## Pitfalls - **Forgetting wikilinks:** The most common failure mode. Always search for `[[OldFolder/` after moving files. - **Moving HTML tools without updating their internal links:** HTML files often link to each other with relative paths (`href="crew-morale-tracker.html"`). These are NOT wikilinks and do not break when the `.md` files move, but they do break if the HTML files themselves are moved. Update relative paths in HTML if needed. - **Leaving the root messy:** After moving, the root should contain only `_Index.md`, the numbered hubs, `_Archive/`, and utility folders (e.g., `scripts/`). Any stray `.md` files in the root are a bug. - **Over-merging:** Don't merge full session plans or ASCII deck grids into hub docs. They make the file unwieldy. Summarize them in the hub and link to the full file. - **Breaking the sync script:** If the sync script references specific paths, verify it still works after reorganization. --- ## Example: Before and After ### Before (messy) ``` Pirate-Campain/ _Index.md Ideas.md World-Ideas.md Black-Flag-Inspirations.md Session-Zero-Reality-Options.md Adventures/ Locations/ Factions/ Monsters/ Items/ Spells/ Systems/ Ships/ Templates/ NPCs/ Website-Campaign-Ideas.md website-building-plan/ ``` ### After (clean) ``` Pirate-Campain/ _Index.md 1-Campaign/ Campaign Core.md Crew & Voyage.md Session-Zero-Reality-Options.md 2-World/ Worldbuilding.md Items & Spells.md Adventures/ NPCs/ 3-Ships/ Ships.md Current-Ship.md Ship-Tier-1-Keelboat.md ... 4-Tools/ HTML/ Templates/ _Archive/ Ideas.md World-Ideas.md ... scripts/ sync_to_icloud.py ``` --- ## Tags #obsidian #ttrpg #campaign #vault #organization #consolidation