# Migration Runbook

One-time procedure. Migrates an existing Obsidian vault to the
four-folder flat structure defined in `CLAUDE.md`. After
migration, normal compile/lint operations take over.

## Pre-flight

1. Read `<vault-root>/CLAUDE.md`
2. Confirm the vault is in a clean git state. If not, stop and
   ask user to commit or stash.
3. Confirm with the user that this is a migration run, not a
   compile run. Migration is destructive (file moves) and
   one-shot.
4. Confirm the vault has not already been migrated (check for
   existence of `Dev/`, `Content/`, `Homelab/`, `Reference/`
   folders at root with the expected structure). If already
   migrated, stop and report.

## Phase 1: Survey

Walk the entire vault. Produce a survey report.

For each existing file:

- Current path
- Filename
- Detected `type:` (from frontmatter, or inferred from
  content/path if frontmatter is absent)
- Inferred ownership domain: Dev, Content, Homelab, or Reference
- Proposed new path under the four-folder structure
- Proposed new filename (apply naming conventions: project pages
  as `<slug>.md`, sessions as `YYYY-MM-DD-<slug>.md`)
- Any concerns: ambiguous ownership, missing frontmatter,
  unclear type, etc.

Group the report:

- **By proposed domain** — easy review of "is everything in Dev
  actually Dev?"
- **Concerns** — separate section listing every file that needs
  user judgment
- **Wikilinks affected** — count of internal links that will
  need rewriting

Save the survey report as `<vault-root>/migration-survey.md`.

### Stop condition: present survey, await user approval

Do not proceed to Phase 2 until the user has reviewed the
survey and given explicit go-ahead. Allow the user to correct
specific entries; re-survey if they do.

## Phase 2: Move

Once survey is approved:

### Pre-move commit

```
git add -A
git commit -m "pre-migration: vault state before move" || true
```

(`|| true` because the vault may already be clean.)

### Create the four-folder structure

```
<vault-root>/Dev/
<vault-root>/Content/
<vault-root>/Homelab/
<vault-root>/Reference/
```

If any of these already exist, leave them alone.

### Move files

For each file in the survey:

1. `git mv <old-path> <new-path>` — preserves history
2. If the filename changed, the `git mv` reflects that
3. If the file's frontmatter has a `path:` field, update it to
   the new domain
4. If the file is a session note and lacks `created:` /
   `updated:` dates, infer from filename (if date-prefixed) or
   git history

### Rewrite wikilinks

Walk every file in the migrated vault. For every wikilink:

- If the target moved or was renamed, update the wikilink to
  point at the new name
- Use Obsidian's wikilink resolution rules (filename-based, not
  path-based, so most wikilinks won't need rewriting unless
  files were renamed)

### Post-move commit

```
git add -A
git commit -m "migration: moved <N> files to four-folder structure" \
           -m "<short summary of what moved where>"
```

### Stop condition: present post-move state, await user approval

Report:

- Files moved: <count>
- Files renamed: <count>
- Wikilinks rewritten: <count>
- Concerns or skipped files: <list>

Do not proceed to Phase 3 until user confirms the post-move
state is correct.

## Phase 3: Initial compile

Run the compile procedure (see `compile.md`) with one
modification: this is a first-run compile against a freshly-
migrated vault, so:

- Generate `index.md`, `Dev/index.md`, `Content/index.md`,
  `Homelab/index.md`, `Reference/index.md` from scratch
- Generate `log.md` if absent, with a single initial entry:
  `## [YYYY-MM-DD HH:MM] migration | initial migration complete`
- Promote obvious entities (Lovebug, OB1, herbydev, Sunnie,
  Jenny, etc.) automatically — these are known to clear the
  promotion threshold
- Generate at most one synthesis page if a clear cross-cutting
  pattern is present in existing content; otherwise none

### Stop condition: present compile output, await user approval

Standard compile reporting plus a "first-run" callout
highlighting:

- Entities auto-promoted (with rationale)
- Initial topic landings created
- Any pages where the agent's categorization felt uncertain

User reviews. Iterate if needed. Migration is done when user
confirms.

## Final commit

After user approval of the initial compile output:

```
git commit --allow-empty -m "migration: complete"
```

This marker commit is the boundary between migration and
steady-state operations. Future compile runs treat any change
after this commit as in-scope.

## Stop conditions (any phase)

Stop and report if:

- Git operations fail
- A user-confirmed move would overwrite an existing file
- A wikilink rewrite is ambiguous (multiple plausible targets)
- The vault is in an unexpected state at any phase boundary

## What this procedure does not do

- Run as part of a normal compile cycle
- Re-run automatically after completion
- Modify content beyond moves, renames, and wikilink rewrites
- Generate aggressive synthesis at first-run (one max)
- Delete files (skipped or unclear files stay where they are
  with a flag)