wiki-context/skill/migration.md

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:
• Files renamed:
• Wikilinks rewritten:
• Concerns or skipped files:

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)