From 8b9cc4effd011913d06fb6b15226682085bd83ab Mon Sep 17 00:00:00 2001
From: Erich Blume <blume.erich@gmail.com>
Date: Wed, 11 Mar 2026 18:17:45 -0700
Subject: [PATCH] Add how-to card for running 1Password backup

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../+run-1password-backup-howto.doc.md        |  1 +
 .../operations/restore-1password-backup.md    |  1 +
 .../how-to/operations/run-1password-backup.md | 74 +++++++++++++++++++
 docs/reference/services/1password.md          |  3 +-
 4 files changed, 78 insertions(+), 1 deletion(-)
 create mode 100644 docs/changelog.d/+run-1password-backup-howto.doc.md
 create mode 100644 docs/how-to/operations/run-1password-backup.md

diff --git a/docs/changelog.d/+run-1password-backup-howto.doc.md b/docs/changelog.d/+run-1password-backup-howto.doc.md
new file mode 100644
index 0000000..907d9eb
--- /dev/null
+++ b/docs/changelog.d/+run-1password-backup-howto.doc.md
@@ -0,0 +1 @@
+Add how-to card for running the 1Password backup (`mise run op-backup`), with bidirectional links to restore procedure and service reference.
diff --git a/docs/how-to/operations/restore-1password-backup.md b/docs/how-to/operations/restore-1password-backup.md
index 325f468..b839b10 100644
--- a/docs/how-to/operations/restore-1password-backup.md
+++ b/docs/how-to/operations/restore-1password-backup.md
@@ -95,6 +95,7 @@ The borg repo uses `repokey` encryption — the key is stored in the repo itself
 
 ## Related
 
+- [[run-1password-backup]] - How to create the backup (export + encrypt + transfer)
 - [[borgmatic]] - Backup system
 - [[1password]] - Credential management
 - [[backups]] - Backup policy and schedule
diff --git a/docs/how-to/operations/run-1password-backup.md b/docs/how-to/operations/run-1password-backup.md
new file mode 100644
index 0000000..bbed3ab
--- /dev/null
+++ b/docs/how-to/operations/run-1password-backup.md
@@ -0,0 +1,74 @@
+---
+title: Run 1Password Backup
+modified: 2026-03-11
+tags:
+  - how-to
+  - operations
+  - backup
+---
+
+# Run 1Password Backup
+
+How to export and encrypt your 1Password vaults for inclusion in [[borgmatic]] backups. Run this periodically from your local machine (Gilbert).
+
+## Prerequisites
+
+- 1Password desktop app running (for the vault export)
+- `op`, `age`, `openssl`, `ssh`, and `scp` installed locally
+- SSH access to [[indri]]
+- The `op` CLI signed in (biometric unlock)
+
+## Procedure
+
+### 1. Export Vaults From 1Password
+
+1. Open the 1Password desktop app
+2. **File > Export > All Vaults**
+3. Choose **1PUX** format
+4. Save to `~/Documents/1Password-export.1pux`
+
+### 2. Run the Backup Task
+
+```fish
+mise run op-backup
+```
+
+Or, if you saved the export to a non-default location:
+
+```fish
+mise run op-backup ~/path/to/export.1pux
+```
+
+The task will:
+
+1. Prompt for the `.1pux` path if not provided
+2. Fetch your master password and secret key from 1Password (triggers biometric)
+3. Generate a temporary age key pair
+4. Encrypt the `.1pux` with the age public key
+5. Encrypt the age private key with OpenSSL AES-256-CBC (passphrase: `{master_password}:{secret_key}`)
+6. SCP both encrypted files to `indri:/Users/erichblume/Documents/1password-backup/`
+7. Clean up old backups on indri (keeps last 3 sets)
+8. **Delete the plaintext `.1pux` from Gilbert**
+
+No cleanup needed — the script automatically deletes the plaintext `.1pux` from Gilbert and shreds the temporary encryption keys.
+
+### 3. Verify
+
+After the script completes, confirm the files landed on indri:
+
+```fish
+ssh indri 'ls -lh /Users/erichblume/Documents/1password-backup/'
+```
+
+You should see a `.age` file (~30-45 MB) and a `.key.enc` file (~200 bytes) with today's timestamp.
+
+## What Happens Next
+
+Borgmatic picks up the encrypted files during its daily 2:00 AM backup run, archiving them to both [[sifaka]] (local NAS) and BorgBase (offsite). No further action needed.
+
+## Related
+
+- [[restore-1password-backup]] - Disaster recovery: how to decrypt and restore
+- [[1password]] - 1Password service overview
+- [[borgmatic]] - Backup system
+- [[backups]] - Backup policy and schedule
diff --git a/docs/reference/services/1password.md b/docs/reference/services/1password.md
index 4d3d5a1..4489194 100644
--- a/docs/reference/services/1password.md
+++ b/docs/reference/services/1password.md
@@ -37,11 +37,12 @@ Services reference 1Password items via `ExternalSecret` manifests.
 
 ## Disaster Recovery Backup
 
-The `mise run op-backup` task encrypts a `.1pux` vault export and transfers it to [[indri]] for inclusion in [[borgmatic]] backups. See [[restore-1password-backup]] for the full recovery procedure.
+The `mise run op-backup` task encrypts a `.1pux` vault export and transfers it to [[indri]] for inclusion in [[borgmatic]] backups. See [[run-1password-backup]] for the step-by-step procedure and [[restore-1password-backup]] for disaster recovery.
 
 ## Related
 
 - [[argocd]] - Uses secrets for git access
 - [[postgresql]] - Database credentials
+- [[run-1password-backup]] - Periodic backup procedure
 - [[restore-1password-backup]] - Recovery from backup
 - [[borgmatic]] - Backup system