Backup & recovery

Goal and prerequisites

Have a verified recovery path before installation, upgrades, role changes or extension updates. Close Obsidian and pause sync before copying or restoring an actively changing vault.

Make a full backup

Copy the entire vault to a separate destination, including dotfiles, .obsidian, instructions, templates, installation state and attachments. Keep it outside the working vault. Record which version and date it represents.

Open the backup as a separate vault and inspect representative notes, links and attachments. A completed copy operation alone does not prove a useful recovery snapshot. Sync is not a substitute for an independent backup.

Community recovery

Retain the extracted Starter Kit package and records under:

00 - System/Installation/kos-installation.json
00 - System/Installation/Runs/<run-id>/plan.json
00 - System/Installation/Runs/<run-id>/journal.json
00 - System/Installation/Runs/<run-id>/report.md

Starter Kit 1.2.0 does not resume interrupted writes. -Resume returns RESUME_REQUIRES_JOURNAL_REVIEW; inspect the journal and backups, recover with rollback, then replan. Confirm the original writer is stopped before handling a stale lock.

Preview rollback before approving it:

./install.ps1 -Target 'PATH-TO-TEST-COPY' -Operation rollback -RunId 'RUN-ID' -DryRun
./install.ps1 -Target 'PATH-TO-TEST-COPY' -Operation rollback -RunId 'RUN-ID' -Approve

Rollback restores only eligible unchanged outputs belonging to that run. It preserves later user edits and newly created user-owned or runtime files, including seeded configuration and knowledge. A fresh installation or enhancement can therefore return exit code 4 (incomplete rollback) even when you have made no later edits. The plan may classify those retained files as USER_MODIFIED; inspect their ownership and journal rather than assuming that label proves a post-install edit. Inspect the result instead of assuming the previous state was fully restored. Use a verified full-vault snapshot when you need to recover the complete earlier workspace.

Pro recovery

Keep the exact original package and the sibling .kos-installer-<id> control directory. From that package, set $Vault and replace TRANSACTION-ID with the recorded transaction identifier.

$Vault = 'D:\Vaults\KOS-Learning'
pwsh -NoProfile -File ./Install-KOS.ps1 -RepositoryRoot $Vault -Operation Recover -TransactionId 'TRANSACTION-ID'
pwsh -NoProfile -File ./Install-KOS.ps1 -RepositoryRoot $Vault -Operation Rollback -TransactionId 'TRANSACTION-ID'

These are alternative recovery actions, not a sequence to run automatically. Inspect the transaction state and supplied recovery guide to choose the correct action. Later edits remain conflicts; rollback may be incomplete.

Restore a complete snapshot

Restore your independently verified backup into a separate directory. Open and validate it before resuming work. Reconcile later changes deliberately; do not overwrite a live vault blindly.

Verify the recovery

Check installed identity, validation results, representative content and the fresh-session context test. Retain the failed run’s evidence until the incident is understood. Installer transaction backups cover installer changes, not the complete vault.