# Worked Example: Pirate Campaign Vault Reorganization

This is a concrete record of how the Pirate Campaign vault was reorganized from a flat, messy structure into a clean numbered-hub layout. Use it as a reference when doing similar work.

## The Problem

Before reorganization, the vault had:
- 80+ files in the root and subfolders
- Competing overview files: `Ideas.md`, `World-Ideas.md`, `Black-Flag-Inspirations.md`
- 11 subfolders with unclear hierarchy (`Locations/`, `Factions/`, `Monsters/`, `Items/`, `Spells/`, `Systems/`, `Ships/`, `Adventures/`, `NPCs/`, `Templates/`, `Worldbuilding/`)
- User complaint: "Theres to many files in the root of the project, ogonize them in folders, even folders in folders"

## The Solution

### Merge Map

| Old File(s) | Merged Into | Section |
|---|---|---|
| `Ideas.md` + `Black-Flag-Inspirations.md` + `Systems/*.md` | `1-Campaign/Campaign Core.md` | Pitch, themes, naval combat, firearms, notoriety, rivals |
| `World-Ideas.md` + `Worldbuilding/*.md` + `Locations/*.md` + `Factions/*.md` + `Monsters/*.md` + `Adventures/_Index.md` | `2-World/Worldbuilding.md` | Lore, locations, factions, monsters, adventure hooks, primer |
| `Items/*.md` + `Spells/*.md` + `Items/Firearms.md` | `2-World/Items & Spells.md` | Magic items with twists, spell variants |
| `Systems/Crew-*.md` + `Systems/Daily-*.md` + `Systems/Port-Island-Generator.md` | `1-Campaign/Crew & Voyage.md` | Morale, daily events, port generators, ship log |
| `Ships/*.md` (living files) | `3-Ships/Ships.md` + `3-Ships/Current-Ship.md` + tier stat blocks | Ship hub and current vessel |

### Folder Structure After

```
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/           (12 full session plans)
    NPCs/                 (empty, grows as campaign runs)
  3-Ships/
    Ships.md              (tier summaries + tool links)
    Current-Ship.md       (living vessel tracker)
    Ship-Tier-1-Keelboat.md
    Ship-Tier-2-Longship.md
    Ship-Tier-3-Sailing-Ship.md
    Ship-Tier-4-Warship.md
    Ship-Tier-5-Galley.md
  4-Tools/
    HTML/
      campaign-hub.html
      crew-morale-tracker.html
      naval-combat-tracker.html
      sea-encounter-generator.html
      ship-grid-viewer.html
    Templates/
      Adventure.md
      Faction.md
      Item.md
      Location.md
      Monster.md
      NPC.md
      Spell.md
      _Index.md
  _Archive/
    5-Retired/            (old pre-merge files)
    6-Meta/               (website build plans)
  scripts/
    sync_to_icloud.py
```

### Wikilink Migration

All internal wikilinks had to be updated. The most common patterns:
- Bare file names like `[[Campaign Core]]` -> `[[1-Campaign/Campaign Core]]`
- Old folder paths like `[[Ships/Current-Ship]]` -> `[[Current-Ship]]` (when in same folder) or `[[3-Ships/Current-Ship]]` (when cross-folder)
- `[[Adventures/_Index]]` -> `[[2-World/Adventures/_Index]]`
- `[[Templates/_Index]]` -> `[[4-Tools/Templates/_Index]]`

HTML internal links (`href="crew-morale-tracker.html"`) did NOT need updating because the HTML files were moved together into `4-Tools/HTML/` and their relative paths to each other stayed the same.

### Root `_Index.md` Pattern

The root `_Index.md` was rewritten with two layers:
1. **At a Glance (top):** A table mapping user roles to the correct hub file
2. **Detailed Guide (bottom):** File-by-file breakdown, merge history table, and "what stays in subfolders" table

This two-layer pattern is the key to making a reorganized vault usable immediately.

## Key Lessons

1. **Numbered hubs work.** The `1-Campaign`, `2-World`, `3-Ships`, `4-Tools` pattern forces a reading order and keeps the root clean.
2. **Merge aggressively, but not everything.** Full session plans and ASCII grids are too bulky for hub docs. Summarize them and link to the full file.
3. **Wikilinks are the fragile part.** Moving files without updating links is worse than not moving them. Search all `.md` files for `[[OldFolder/` patterns before declaring done.
4. **Archive, don't delete.** Move old files to `_Archive/` rather than deleting. The user may need to recover something.
5. **The root should only contain `_Index.md`.** Any stray `.md` in the root after reorganization is a bug.