cos: Skill for Claude Code

Backup & Recovery

The board (board/data/), guard (guard/data/), config (config/), and vault (vault/<VAULT_NAME> — the active vault from config/cos.env) are real, live data. The local rolling snapshots in board/data/backups/ are crash-safety only — count-pruned, same-disk, deletable. This skill operates the durable layer: daily AES-256-GCM-encrypted snapshots in a private GitHub repo (backup/), where git history is immutable, off-site, and versioned.

Implementation lives in backup/ (see backup/README.md). This skill is the operator runbook. Golden rule: never run a bulk or destructive operation on live data without a fresh, VERIFIED backup first (Backup now below). The data-loss incident that motivated this skill happened because live data was edited and the only backups were local + count-pruned.

0. Concepts (read once)

• Recovery key — one high-entropy passphrase; the ONLY way to decrypt. Stored in the macOS login Keychain (security item cos-backup-key) AND an offline copy in your password manager. Never in any repo, never logged. Lose it → backups are unrecoverable.
• Backup repo — a PRIVATE GitHub repo (local clone at $BACKUP_REPO). Holds snapshots/cos-backup-<ts>.enc + per-device manifests manifests/<deviceId>.json (one per producing machine — the deviceId is COS_DEVICE_ID from config/cos.env, else a sanitized hostname; a legacy single MANIFEST.json from before the split is still READ, never written). Private and encrypted = a repo leak exposes nothing. Its location is config-driven: config/cos.env BACKUP_REPO (the loader exports it as $BACKUP_REPO), defaulting to ~/.cos-backups when unset. This config value is the EXPECTED repo; backup.mjs refuses to run against any other effective path (see §6 Relocating + the fail-closed guard). Multiple machines may produce into ONE archive: each run converges with the remote first (fetch + rebase), and a machine's FIRST run must decrypt-verify the newest existing snapshot with its local key (producer admission) — a wrong key is refused before it can split the archive.
• Scope — backup/config.mjs SCOPE: board data, guard data, config, the vault. The vault entry is resolved from config/cos.env VAULT_NAME (vault/<VAULT_NAME>, the same active vault setup-vault records), so a renamed/relocated vault is always captured — never silently dropped. If the configured vault dir is missing at backup time, backup.mjs logs a loud WARN (visible in the /backups log tails) rather than omitting it quietly. Falls back to vault/my-personal-thoughts-vault when VAULT_NAME is unset (a slug guard rejects any name with a path separator).
• Three triggers, one floor — the launchd 03:30 agent is the GUARANTEED DAILY FLOOR. While the board is running it ADDS two more triggers of the SAME backup/backup.mjs: an opportunistic top-up (fires non-blocking from hot read routes when the newest snapshot is >12h old) and the "Back up now" button on the board's /backups surface. All three callers are serialized by a single-flight lock inside backup.mjs (see §3 + §6) and share the same exit codes.
• Board /backups surface — a READ-ONLY health UI (board sidebar → Review → Backups; the Backups item sits next to Security/Trash/Activity, it is NOT nested under Security). The new at-a-glance health check: a healthy/warning/error verdict, last-run time/size/store-count, push-state, snapshot history, log tails, the repo-path provenance, and a Setup & Diagnostics readiness card. Look here FIRST; the CLI below is the headless fallback. See §4.