/backup-setup

name: backup-setup
description: "Set up automatic vault backups to a synced folder or a cloud provider, with verified archives and tiered retention. Use when the user says 'back up my vault', 'set up backups', 'where are my backups going', or asks about losing their notes. Not for restoring or testing a restore (`backup-restore`); not for a one-off backup right now (`backup-now`)."
integration:
  id: vault-backup
  name: Vault Backup
  mcp_server: null
  auth: none

Backup Setup

Set up (or change) automatic backups of the whole vault: notes, projects, people, tasks, settings, and the vault's own version history. Runs on a schedule in the background, keeps a sensible ladder of older copies, and tells you loudly if it ever stops working.

What a backup contains

Every run writes a **set** of three files, stamped with the date and time:

| File | What it is | |------|-----------| | `dex-vault-<stamp>.tar.gz` | The whole vault as one compressed archive | | `dex-vault-<stamp>.bundle` | The vault's version history, individually verified so a restore is provable rather than hoped for | | `dex-vault-<stamp>.sha256` | Fingerprints of both, so damage in storage is detectable |

Secrets are deliberately left out: the `.env` file holding AI keys, generated tool configuration that can reference credentials, saved sign-in tokens (`*token.json`), the `System/credentials` folder, any `.key` or `.pem` file, virtual environments, and caches. Never store those in a synced folder. Keys live in the system keychain or get re-entered on restore. See `docs/backup-restore.md` for what a full rebuild needs beyond these files.

Step 1: Where should backups go?

Ask which destination suits them, in plain terms:

1. **A synced folder** (default, simplest): OneDrive, iCloud Drive, Dropbox, Google Drive, or a plugged-in external disk. Anything that looks like a folder on their Mac. The file-sync app carries copies off the machine. 2. **A cloud storage provider directly**: Amazon S3, Backblaze B2, Google Drive proper, and around seventy others, using a tool called rclone. Choose this when they want backups genuinely off their machine rather than mirrored by a sync app, or their vault is large enough that a sync folder is awkward.

For option 1 ask for the folder path. Offer to detect likely candidates:

ls -d ~/Library/CloudStorage/* ~/Dropbox ~/Google\ Drive 2>/dev/null

For option 2, check whether rclone is present and configured:

rclone listremotes

If they choose rclone, use a named remote they created with `rclone config` (for example `b2:dex-backups`). Never put an inline connection string carrying a key or secret into `backup.remote`: it would be written to the local run record and archived inside the backup itself.

If rclone is missing, say so plainly and give them the choice: install it (`brew install rclone`, then `rclone config` to add their provider) or start with a synced folder now and switch later. Do not attempt to configure their cloud credentials for them; rclone's own setup handles that interactively and safely.

Step 2: How many copies to keep?

Explain the default in one line: **7 daily, 4 weekly, 3 monthly**. Recent copies for accidents, older copies for problems noticed late (a bad edit that spread quietly, a file corrupted weeks ago). Roughly fourteen sets, which for a typical vault is a couple of gigabytes.

Accept a different ladder if they want one. The newest set is never deleted, whatever the ladder says.

Step 3: Save the settings

Write to `System/integrations/config.yaml` under `backup:`:

backup:
  enabled: true
  backend: folder          # folder | rclone
  destination: /path/to/folder    # folder backend
  remote: ""                      # rclone backend, e.g. "b2:dex-backups"
  retention:
    daily: 7
    weekly: 4
    monthly: 3

Step 4: Schedule it

Install the background job (daily, 12:30 by default; ask if they'd prefer another time, and pick a time their machine is usually awake):

python3 core/backup/install_backup_job.py --hour 12 --minute 30

On macOS this schedules the job so missed runs fire when the machine wakes. On other platforms the installer does not pretend: it prints the exact line to schedule the same command with the platform's own scheduler, and installs nothing.

Step 5: Prove it works

Do not tell them backups are set up until one has actually run. Run one now:

python3 core/backup/backup_vault.py

Then show them the real result from `System/.dex/backup-last-run.json`: the set name, size, and destination. If it failed, show the recorded error and fix the cause before declaring success.

Finish by telling them three things: where backups are going, how to get one on demand (`/backup-now`), and that `/backup-restore` in test mode proves a restore works without touching anything.

If backups stop working

`/dex-doctor` checks the last-run record and flags it when the newest successful backup is more than two days old. That check exists because a backup can fail silently for weeks and look identical to a healthy one. If they ask why a warning appeared, read `System/.dex/backup-last-run.json` and report the recorded error verbatim rather than guessing.