From dc414de14e36239b59220089af240c9eb1ededf6 Mon Sep 17 00:00:00 2001
From: Kevin Bataille <kbe@kev1.net>
Date: Sat, 25 Jul 2026 21:35:54 +0200
Subject: [PATCH] docs: add README, note repo is unencrypted by deliberate
 choice

CLAUDE.md previously said the repo was encrypted, which was true when
written but no longer matches this deployment - the operator chose to
stay unencrypted, so the recurring "not encrypted" warning is expected
behavior, not something to fix.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 CLAUDE.md |  2 +-
 README.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 54 insertions(+), 1 deletion(-)
 create mode 100644 README.md

diff --git a/CLAUDE.md b/CLAUDE.md
index 75d749a..7c00f8f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## What this is
 
-Backup + disaster-recovery tooling for a Linux server: Borg (encrypted, offsite-synced via rclone) backing up `/home/srv/files/content`, including MariaDB running in Docker. Plain bash, no build system, no CI, no test suite. `RUNBOOK.md` is the operational doc (setup, deploy, cron, day-2 ops, recovery).
+Backup + disaster-recovery tooling for a Linux server: Borg (offsite-synced via rclone) backing up `/home/srv/files/content`, including MariaDB running in Docker. The repo is unencrypted by deliberate operator choice on this deployment — `borg-backup.sh` prints a warning about it every run, which is expected, not a bug to fix. Plain bash, no build system, no CI, no test suite. `README.md` is the quickstart; `RUNBOOK.md` is the full operational doc (setup, deploy, cron, day-2 ops, recovery).
 
 - `borg-backup.sh` — daily backup orchestrator (cron). Never stops MariaDB: `dump_db.sh`'s `--single-transaction` dump is consistent on its own, and the raw data directory is excluded from the archive via a `.nobackup` marker file.
 - `dump_db.sh` — per-database `mysqldump`/`mariadb-dump` with atomic staging/swap. Deployed to `/opt/backup-agent/dump_db.sh` (borg-backup.sh invokes it at that exact path). It defaults to writing dumps next to itself, so borg-backup.sh always overrides `DUMP_DIR` to keep dumps inside `$TARGET` where borg can see them.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1ecd442
--- /dev/null
+++ b/README.md
@@ -0,0 +1,53 @@
+# backup-agent
+
+Backup and disaster-recovery tooling for a Linux server: [Borg](https://borgbackup.readthedocs.io/)
+backing up `/home/srv/files/content` — including a MariaDB database
+running in Docker — with an offsite mirror on Scaleway S3 via `rclone`.
+
+MariaDB is never stopped during backup: `dump_db.sh` takes a
+transactionally-consistent logical dump (`mysqldump --single-transaction`)
+while the container keeps running, and the container's raw data directory
+is excluded from the archive entirely (a `.nobackup` marker file), so only
+the logical dump ever gets backed up. Zero DB downtime.
+
+## Components
+
+| File | Purpose |
+|---|---|
+| `borg-backup.sh` | Daily backup orchestrator (run from cron): dump → archive → prune → compact → integrity check → offsite sync. |
+| `dump_db.sh` | Per-database `mysqldump`/`mariadb-dump`, atomic staging/swap. Invoked by `borg-backup.sh`. |
+| `restore.sh` | Recovery CLI: `full` (disaster recovery), `db <name>` (single database), `file <path>` (single file/dir), `--list-archives`. Every mode supports `--dry-run`. |
+
+## Quickstart
+
+```bash
+# One-time setup, deployment, cron scheduling, day-2 ops, and step-by-step
+# recovery for every scenario are all in:
+less RUNBOOK.md
+```
+
+Day to day:
+
+```bash
+./restore.sh --list-archives          # what backups exist
+./restore.sh full --dry-run           # preview a disaster recovery
+./restore.sh db <name> --dry-run      # preview a single-database restore
+./restore.sh file <path> --dest DIR   # pull one file out of an archive
+```
+
+## Encryption
+
+The Borg repo at `/home/srv/files/backups/borg-2025` is **unencrypted** by
+deliberate choice on this deployment — `borg-backup.sh` will keep printing
+a warning about it on every run, which is expected. See `RUNBOOK.md` if
+you want to switch to an encrypted repo.
+
+## Requirements
+
+`borg`, `docker`, `rclone`, `flock`, a `mysql`/`mariadb` client — see
+`REQUIRED_CMDS` in `borg-backup.sh`. Targets Linux; `flock(1)` doesn't
+exist on macOS, so these scripts won't run as-is on a Mac.
+
+## License
+
+None specified — internal tooling.