Harden native snapshot polish

.github/CONTRIBUTING.md

@@ -45,18 +45,18 @@ uv run python -m py_compile bbackup.py bbman.py bbackup/*.py bbackup/data/*.py b
 
 ## Commit messages
 
-This project uses [conventional commits](https://www.conventionalcommits.org/). The prefix determines how the version is bumped on the next release:
+This project uses [conventional commits](https://www.conventionalcommits.org/) for readable history. Normal development batches release as one patch increment unless a commit body includes an explicit `Release-Type: major|minor|patch|none` trailer.
 
 | Prefix | Bump | When to use |
 |---|---|---|
-| `feat:` | minor | New user-visible feature |
+| `feat:` | patch by default | New user-visible feature |
 | `fix:` | patch | Bug fix |
 | `docs:` | patch | Documentation only |
 | `refactor:` | patch | Code restructure, no behavior change |
 | `perf:` | patch | Performance improvement |
 | `test:` | patch | Test additions or changes |
 | `chore:` | patch | Build, tooling, dependency updates |
-| `feat!:` or `BREAKING CHANGE:` in body | major | Incompatible change |
+| `feat!:` or `BREAKING CHANGE:` in body | requires explicit `Release-Type:` | Incompatible change |
 
 One subject line, imperative mood, no trailing period. Example:
 

AGENTS.md

@@ -76,3 +76,9 @@ git diff --check
 - Prefer updating existing docs over creating new documents.
 - Keep command examples copy-ready and avoid documenting machine-specific
   secrets or private paths unless they are explicitly local runtime examples.
+
+## Agent Client Compatibility
+
+- Codex CLI and OpenCode are both supported agent clients for this repo.
+- Root `AGENTS.md` is the shared instruction surface for both tools.
+- Keep Codex-only behavior in Codex-native surfaces and OpenCode-only behavior in OpenCode-native surfaces.

CHANGELOG.md

@@ -12,6 +12,32 @@ current uv-based install, development, and release instructions.
 
 ---
 
+## [1.8.5] - 2026-07-09
+
+### Added
+
+- Native restic snapshot profiles with commands for `snapshot init`, `snapshot run`, `snapshot check`, `snapshot restore`, `snapshot retire`, `snapshot purge-plan`, and `snapshot schedule`.
+- Local restic integration coverage that initializes a temporary repository, snapshots a Git repo, checks the repository, restores content, and verifies the state ledger snapshot ID.
+- Profile schedule rendering for daily backup, weekly non-destructive maintenance checks, and monthly verification checks with configurable `verification_read_data_subset`.
+- Generated CLI skills metadata for the native snapshot command surface.
+
+### Changed
+
+- Snapshot schedule units now render matching service/timer pairs, use `/usr/bin/env bbackup`, and escape systemd percent specifiers.
+- Snapshot commands now accept required options from `--input-json` consistently for agent-driven workflows.
+- Retired-repo destructive cleanup remains dry-run-first/manual through `snapshot purge-plan`.
+- The pytest `integration` marker now covers external-tool integration tests such as Docker and restic.
+
+### Fixed
+
+- Google Drive rclone snapshot profiles without a dedicated `client_id` remain rejected by default, while `allow_default_rclone_drive_client: true` provides a conservative profile-local opt-in.
+- Non-dry snapshot operations now enforce profile safety preflight checks before running restic.
+- Git repo identity no longer changes on every commit; legacy head-derived repo IDs migrate safely, and unknown active same-path identity conflicts block history merging.
+- `list-backups` and restore dry-run planning no longer initialize Docker for file-only planning paths.
+- Restore dry-runs now validate filesystem destination and multi-filesystem constraints before returning a success plan.
+
+---
+
 ## [1.8.4] - 2026-06-22
 
 ### Security
@@ -270,7 +296,8 @@ current uv-based install, development, and release instructions.
 
 ---
 
-[Unreleased]: https://github.com/CruxExperts/best-backup/compare/v1.8.4...HEAD
+[Unreleased]: https://github.com/CruxExperts/best-backup/compare/v1.8.5...HEAD
+[1.8.5]: https://github.com/CruxExperts/best-backup/compare/v1.8.4...v1.8.5
 [1.8.4]: https://github.com/CruxExperts/best-backup/compare/v1.8.3...v1.8.4
 [1.8.3]: https://github.com/CruxExperts/best-backup/compare/v1.8.2...v1.8.3
 [1.8.2]: https://github.com/CruxExperts/best-backup/compare/v1.8.1...v1.8.2

README.md

@@ -6,7 +6,7 @@
 
 [![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-3776ab?style=flat-square&logo=python&logoColor=white)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-22c55e?style=flat-square)](LICENSE)
-[![Version](https://img.shields.io/badge/version-1.8.4-6366f1?style=flat-square)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-1.8.5-6366f1?style=flat-square)](CHANGELOG.md)
 
 [Quick start](#quick-start) · [Filesystem backup](#filesystem-backup) · [Agent integration](#agent-integration) · [CLI reference](#cli-reference) · [Docs](#documentation)
 
@@ -206,6 +206,63 @@ Or pass paths directly, no config needed:
 bbackup backup --paths /home/user/docs /srv/data --exclude "*.tmp"
 ```
 
+### Native restic snapshots
+
+Add a top-level `snapshot_profiles:` section for encrypted deduplicating restic
+snapshots. bbackup owns discovery, safety checks, state, and scheduling while
+restic owns the snapshot repository.
+
+```yaml
+snapshot_profiles:
+  essentials-daily:
+    engine: restic
+    host_id: WORKSTATION01
+    repository: rclone:my-drive:backups/WORKSTATION01/restic/essentials-daily
+    # Prefer a dedicated Google Drive rclone OAuth client. Set this only as an
+    # explicit YAML boolean true when accepting rclone's shared default client.
+    allow_default_rclone_drive_client: false
+    cache_dir: ~/.cache/bbackup/restic/WORKSTATION01/essentials-daily
+    state_dir: ~/.local/state/bbackup/WORKSTATION01/essentials-daily
+    password_file: ~/.local/share/bbackup-credentials/restic/WORKSTATION01/essentials-daily.password
+    repo_homes:
+      - ~/Projects
+      - ~/Work
+    explicit_repos:
+      - /home/user/my-control-repo
+    include_paths:
+      - ~/.config/bbackup
+      - ~/Documents
+```
+
+The password file must stay outside selected backup paths and should be `0600`.
+Escrow the password outside the backup.
+
+Google Drive rclone remotes should use a dedicated OAuth `client_id`. A profile
+may opt into rclone's shared default Drive client with
+`allow_default_rclone_drive_client: true`; quoted strings do not enable it.
+
+Plan, initialize, run, check, restore, retire, purge-plan, and render schedule
+units with:
+
+```bash
+bbackup snapshot plan --profile essentials-daily --output json
+```
+
+```bash
+bbackup snapshot init --profile essentials-daily --dry-run --output json
+```
+
+```bash
+bbackup snapshot run --profile essentials-daily
+```
+
+Deleted Git repositories are marked retired only after at least one successful
+snapshot. Automated retention must target active repo IDs or configured path
+scopes; use `snapshot purge-plan` for dry-run-first retired-repo purges.
+Rendered schedule units include a daily `snapshot run`, weekly non-destructive
+`snapshot check`, and monthly `snapshot check --read-data-subset`, defaulting
+to `5%` unless `schedule.verification_read_data_subset` is set.
+
 ---
 
 ## CLI reference
@@ -320,7 +377,7 @@ Level-0 JSON output:
 ```json
 {
   "cli": "bbackup",
-  "version": "1.8.4",
+  "version": "1.8.5",
   "agent_hint": "Set BBACKUP_OUTPUT=json and BBACKUP_NO_INTERACTIVE=1 for fully non-interactive use.",
   "skills": [
     {"id": "docker-backup",     "summary": "Back up Docker containers, volumes, networks, and configs.", "common": true},

VERSION

@@ -1 +1 @@
-1.8.4
+1.8.5

agent-repo-shape.json

@@ -0,0 +1,23 @@
+{
+  "agent_clients": [
+    "codex",
+    "opencode"
+  ],
+  "external_skills": [],
+  "platform_overrides": {
+    "codex": {
+      "enabled": true
+    },
+    "opencode": {
+      "enabled": true
+    }
+  },
+  "profile": "lean-universal",
+  "repo": {
+    "name": "bbackup"
+  },
+  "repo_profile": "universal-agent-repo",
+  "repo_skills": [],
+  "schema_version": "1",
+  "shared_skill_surface": ".agents/skills"
+}

bbackup/__init__.py

@@ -3,5 +3,5 @@
 A comprehensive backup solution for Docker containers, volumes, and configurations.
 """
 
-__version__ = "1.8.4"
+__version__ = "1.8.5"
 __author__ = "Slavic Kozyuk / Crux Experts LLC"