Add scheduled rotating local backups

man/backup.md

@@ -0,0 +1,77 @@
+# Backup Policy (QuoteForge)
+
+## Overview
+QuoteForge performs automatic backups of local runtime data on a daily schedule. Backups are stored as ZIP archives and rotated per period (daily/weekly/monthly/yearly).
+
+The policy is designed to be easily replicated across installations and user environments without additional dependencies.
+
+## What Gets Backed Up
+Each backup archive contains:
+- Local SQLite database file (`qfs.db`)
+- SQLite sidecar files (`qfs.db-wal`, `qfs.db-shm`) if present
+- Runtime config file (`config.yaml`) if present
+
+## Schedule
+Backups run once per day at a configured time.
+- Config key: `backup.time`
+- Default: `00:00`
+- Format: `HH:MM` (24-hour local time)
+
+## Storage Location
+Default location is next to the local DB:
+```
+<db dir>/backups/
+```
+Period-specific subdirectories:
+```
+backups/daily
+backups/weekly
+backups/monthly
+backups/yearly
+```
+
+Optional override:
+- `QFS_BACKUP_DIR` — absolute or relative path to the backup root
+
+## Naming Convention
+Backup files are ZIP archives named by creation date:
+```
+qfs-backp-YYYY-MM-DD.zip
+```
+Each period keeps its own copy under its directory.
+
+## Retention
+Rotation keeps a fixed number of archives per period:
+- Daily: 7 archives
+- Weekly: 4 archives
+- Monthly: 12 archives
+- Yearly: 10 archives
+
+Older archives beyond these limits are deleted automatically.
+
+## Period Dedupe
+A marker file stored inside each period directory tracks the last backup key to avoid duplicate backups within the same period.
+- File: `.period.json`
+- Content: `{ "key": "<period-key>" }`
+
+## Logs
+Successful backup creation is logged with the archive path:
+```
+local backup completed archive=/path/to/.../qfs-backp-YYYY-MM-DD.zip duration=...
+```
+
+Failures are logged with:
+```
+local backup failed error=... duration=...
+```
+
+## Disable Backups
+Set environment variable:
+```
+QFS_BACKUP_DISABLE=1
+```
+Accepted values: `1`, `true`, `yes` (case-insensitive).
+
+## Notes
+- Backups are performed on startup if the current period has no backup.
+- All paths are resolved relative to runtime DB/config paths.