rdfitted/restore

Restore (Kopia)

Opinionated restore workflows that complement the backup (write) and backup-ops (verify/maintain/mirror/interactive-restore) skills.

Modes

| User says... | Mode | |---|---| | "restore wikis", "sync wikis", "pull the .ai-docs", "I plugged in the drive", "update wikis from backup" | wikis (default) | | "rebuild this machine", "greenfield restore", "restore everything to original locations", "full restore" | full |

Default to wikis if unclear — it's the frequent path and is safer (creates .bak backups before overwriting).

Prerequisites (both modes)

1. ~/.claude/backup-config.json exists (the backup skill writes this during setup)
2. Kopia CLI on PATH — if missing, install via winget install --id Kopia.KopiaUI then add %LOCALAPPDATA%\Programs\KopiaUI\resources\server to user PATH
3. Backup drive plugged in — detected by drive_label from config (volume label, NOT drive letter)
4. Connected to repo — if not, run:

   kopia repository connect filesystem --path "<drive-letter>:\KopiaRepo"
   

   On first connect on a new machine: prompts for password, stores in Windows Credential Manager. Subsequent runs: silent.

Workflow: shared startup

1. Load config — ~/.claude/backup-config.json. Bail if missing.
2. Detect drive by drive_label:

   $vol = Get-Volume -FileSystemLabel $config.repo.drive_label -ErrorAction Stop
   $drive = "$($vol.DriveLetter):"
   

   If not mounted, stop with a clear error.
3. Ensure Kopia is reachable:

   $env:Path = "$env:Path;C:\Users\USERNAME\AppData\Local\Programs\KopiaUI\resources\server"
   kopia --version  # bail if this fails
   

4. Connect to repo (idempotent — kopia repository status succeeds if already connected):

   $status = & kopia repository status 2>&1
   if ($LASTEXITCODE -ne 0) {
       & kopia repository connect filesystem --path "$drive\$($config.repo.repo_subdir)"
       # will prompt for password if not in credential manager
   }
   

5. Open log: ~/.claude/backup-logs/restore-<ISO timestamp>.log. Tee everything.

Mode: wikis

Purpose: Sync each project's .ai-docs/ directory from the latest backup snapshot to the local project tree. This is how compound-knowledge wikis move between machines.

Assumption: User runs /backup on the source machine first, plugs in the drive, runs /restore wikis on the target machine.

Cross-machine name mapping (restore_mappings)

In single-machine restores (same machine for both backup and restore), source and target paths are identical and project folder names match — the auto-walk just works. Cross-machine restores routinely hit two mismatches:

1. Source path != target path. The backup was created from D:\Code Projects on the source machine, but on the target machine the cloned projects live under C:\Users\USERNAME\Code Projects.
2. Source project name != target project name. Conventions drift — e.g. D:\Code Projects\GVB ERP on the source corresponds to Code Projects\gvb on the target (GitHub-derived kebab-case repo names).

Without explicit mapping, the auto-walk silently skips everything because no local path matches the source layout. The fix is an optional restore_mappings block in ~/.claude/backup-config.json:

"restore_mappings": {
  "source_paths": [
    {
      "source": "D:\\Code Projects",
      "target": "C:\\Users\\RDuff\\Code Projects",
      "project_name_map": {
        "GVB ERP":                  "gvb",
        "Ultra Building Solutions": "ultrabuildingsolutions",
        "TOG - ERP":                "tog-erp",
        "the og main brain":        "ogmainbrain",
        "TOG PM Assistant":         "ogpmbrain"
      }
    }
  ]
}

Each entry says: "snapshots whose source path is <source> get restored under <target> on this machine, with these per-project renames." Names not in project_name_map fall through to the source name verbatim. Projects with no local target directory are skipped as usual.

If restore_mappings.source_paths is empty or absent, the skill falls back to legacy auto-walk (uses the local config's sources list, expects exact name matches).

Workflow

1. Determine source roots to consider:

   • If restore_mappings.source_paths is non-empty: use each entry's explicit source (the snapshot path on the originating machine), target (local path), and optional project_name_map.
   • Else (legacy): enumerate Code Projects entries from local sources config — typically C:\Users\USERNAME\Code Projects, D:\Code Projects. Source path = target path. No name remapping.

2. For each source root, get the latest snapshot ID:

   $latestSnap = & kopia snapshot list "<source-path>" --max-results 1 | <parse ID>
   

   Note: the snapshot path is the path that was backed up on the source machine — it does not need to exist on the local machine. Kopia stores it as metadata.

3. Find all .ai-docs/ subtrees within that snapshot:

   # Walk the snapshot tree
   & kopia ls "k<snapshot-id>" --recursive | Select-String "\\.ai-docs$"
   

   This returns a list of subpaths like <source-project-name>/.ai-docs.

4. For each found .ai-docs/ subtree:

   • Resolve local project name: look up <source-project-name> in this entry's project_name_map; if absent, use the source name unchanged.
   • Compute local target: <target>\<local-project-name>\.ai-docs (using target from the mapping entry, or source-path in legacy mode).
   • If local project doesn't exist (Test-Path "<target>\<local-project-name>" is false): SKIP and log as "project not on this machine — source=<source-name> resolved=<local-name>". Logging both names lets the user decide whether to clone the project or fix a missing mapping entry.
   • If local .ai-docs/ exists: rename to .ai-docs.bak.<ISO-timestamp>:

     Rename-Item "<local>\.ai-docs" "<local>\.ai-docs.bak.$(Get-Date -Format 'yyyyMMddTHHmmss')"
     

   • Restore the snapshot subpath to the resolved local target:

     kopia snapshot restore "k<snapshot-id>/<source-project-name>/.ai-docs" "<target>\<local-project-name>\.ai-docs"
     

5. Report:

   • N .ai-docs/ synced (with project names)
   • M skipped because project not on this machine (list them — user may want to clone)
   • K .bak directories created (with paths)
   • Total bytes written + duration

Hard rules for wikis mode

• Always rename existing .ai-docs/ to .ai-docs.bak.<timestamp> before overwriting — never destroy in place. The .bak is cheap insurance against the case where the backup was stale (e.g. user edited locally on this machine without syncing first).
• Skip projects that don't exist locally — do NOT create new project directories. The .ai-docs/ belongs to a project; if the project isn't here, the wiki shouldn't be either.
• Do not touch global ~/.ai-docs/ — that's the mainbrain wiki, git-tracked in rdfitted/mainbrain_fitted. Recovery path for that is git pull, not this skill.
• Be loud about .bak paths — print every .bak directory created so the user can verify they didn't lose unsynced work. Recommend deleting .bak folders after confirming the synced version is good.

Mode: full

Purpose: Greenfield restoration onto a new/empty machine. Restores every source in backup-config.json to its original path.

Assumption: This is a fresh machine. No safety net — restores overwrite whatever's there (which should be nothing or near-nothing).

Workflow

1. List all sources from config.
2. For each source:
   • Find latest snapshot ID
   • Ensure parent directory exists (create if needed):

     $parent = Split-Path "<source-path>" -Parent
     if (-not (Test-Path $parent)) { New-Item -ItemType Directory -Path $parent -Force }
     

   • Refuse to overwrite if target exists and is non-empty unless user explicitly passes --force. Print a warning showing what's at the path, ask user to confirm or pass --force.
   • Restore latest snapshot to original path:

     kopia snapshot restore "<snapshot-id>" "<source-path>"
     

3. Report per-source: bytes restored, duration, success/failure.

Hard rules for full mode

• Refuse to overwrite non-empty targets by default — full mode assumes greenfield; if the path has content, that's likely a mistake. Require --force to proceed.
• Don't run on the current daily-driver machine without --force — easy way to clobber live state.
• Restore special files (.gitconfig, CLAUDE.md, etc.) last — these are single files and least disruptive; restoring them after dirs prevents partial-state issues.

Output format (both modes)

After the run, print a tight summary:

restore [wikis|full] complete — <ISO timestamp>
  sources processed: N
  bytes restored:    X.X GB
  duration:          M min Ss
  .bak directories:  K (paths listed above)
  skipped:           Y (reasons listed above)
  log:               C:\Users\USERNAME\.claude\backup-logs\restore-<ISO>.log

If any errors: print them prominently, don't bury.

Cross-references

• backup — primary write workflow
• backup-ops — verify, maintain, mirror, ad-hoc interactive restore
• ~/.claude/skills/backup-ops/RESTORE.md — manual Kopia CLI reference (open/browse/pull/full-restore commands)
• ~/.claude/backup-config.json — source list and drive label
• Wiki: if user reports a pattern from running this skill repeatedly (e.g. specific projects always missing, or .bak cleanup workflow), curate via /curate-learnings → ~/.ai-docs/wiki/practices/

What this skill is NOT for

• Single-file ad-hoc restore ("I need just one file back") → use backup-ops restore or mount the repo (kopia mount all Z:)
• Browsing history without writing → use kopia mount all Z: and Explorer
• Restoring to a non-original target for testing → use backup-ops restore or raw kopia snapshot restore <id> <target>
• Syncing global ~/.ai-docs/ → that's git-tracked in rdfitted/mainbrain_fitted; use git pull instead