From beedca0412ccaa96c095c5a44f3611f68ed4a53c Mon Sep 17 00:00:00 2001
From: Paul Buetow <paul@buetow.org>
Date: Sun, 3 May 2026 20:10:27 +0300
Subject: Document zrepl snapshot retention

---
 prompts/skills/f3s/references/freebsd-setup.md | 50 +++++++++++++++++---------
 prompts/skills/f3s/references/storage.md       | 20 ++++++++---
 2 files changed, 49 insertions(+), 21 deletions(-)

diff --git a/prompts/skills/f3s/references/freebsd-setup.md b/prompts/skills/f3s/references/freebsd-setup.md
index d98e1e1..343af0a 100644
--- a/prompts/skills/f3s/references/freebsd-setup.md
+++ b/prompts/skills/f3s/references/freebsd-setup.md
@@ -118,28 +118,44 @@ doas pkg install wireguard-tools           # Part 5 - WireGuard
 doas pkg install git go                    # Part 4 - benchmarking
 ```
 
-## ZFS Snapshot Policy (zfs-periodic)
+## ZFS Snapshot Policy
 
-Configured in `/etc/periodic.conf` for the `zroot` pool:
+Snapshot creation and retention should be managed by zrepl, not `zfs-periodic`,
+on the f0-f3 FreeBSD hosts. Do not configure `zfs-periodic` and `zrepl` to
+snapshot the same ZFS filesystem.
+
+`zfs-periodic` snapshot creation is disabled in `/etc/periodic.conf` on hosts
+that previously used it:
+
+```sh
+daily_zfs_snapshot_enable="NO"
+weekly_zfs_snapshot_enable="NO"
+monthly_zfs_snapshot_enable="NO"
+```
+
+Local non-replicated datasets are covered by a zrepl `snap` job:
 
 ```sh
-# Daily: 7 snapshots kept
-daily_zfs_snapshot_enable="YES"
-daily_zfs_snapshot_pools="zroot"
-daily_zfs_snapshot_keep="7"
-
-# Weekly: 5 snapshots kept
-weekly_zfs_snapshot_enable="YES"
-weekly_zfs_snapshot_pools="zroot"
-weekly_zfs_snapshot_keep="5"
-
-# Monthly: 6 snapshots kept
-monthly_zfs_snapshot_enable="YES"
-monthly_zfs_snapshot_pools="zroot"
-monthly_zfs_snapshot_keep="6"
+  - name: local_zfs_snapshots
+    type: snap
+    snapshotting:
+      type: cron
+      prefix: zrepl_local_
+      cron: "0 3 * * *"
+    pruning:
+      keep:
+        - type: regex
+          regex: "^(daily|weekly|monthly)-.*"
+        - type: regex
+          regex: "^pre-.*"
+        - type: grid
+          grid: 14x1d | 6x30d
+          regex: "^zrepl_local_.*"
 ```
 
-Note: `zdata` pool (for NFS storage) is managed by `zrepl`, not `zfs-periodic`.
+The regex keep rules preserve older `zfs-periodic` and pre-upgrade snapshots
+during the migration. zrepl-managed replication datasets are excluded from these
+local snap jobs and remain owned by their push jobs.
 
 ## uptimed
 
diff --git a/prompts/skills/f3s/references/storage.md b/prompts/skills/f3s/references/storage.md
index ebe749a..ea77260 100644
--- a/prompts/skills/f3s/references/storage.md
+++ b/prompts/skills/f3s/references/storage.md
@@ -126,13 +126,13 @@ jobs:
         - type: last_n
           count: 10
         - type: grid
-          grid: 4x7d | 6x30d
+          grid: 24x1h | 14x1d | 6x30d
           regex: "^zrepl_.*"
       keep_receiver:
         - type: last_n
           count: 10
         - type: grid
-          grid: 4x7d | 6x30d
+          grid: 24x1h | 14x1d | 6x30d
           regex: "^zrepl_.*"
 
   # Note: f0_to_f1_freebsd job removed — the FreeBSD VM was migrated to f3.
@@ -167,13 +167,13 @@ jobs:
         - type: last_n
           count: 10
         - type: grid
-          grid: 4x7d
+          grid: 24x1h | 14x1d
           regex: "^zrepl_.*"
       keep_receiver:
         - type: last_n
           count: 10
         - type: grid
-          grid: 4x7d
+          grid: 24x1h | 14x1d
           regex: "^zrepl_.*"
 ```
 
@@ -210,6 +210,18 @@ jobs:
 
 Replicated path: `zroot/bhyve/freebsd` → `zroot/sink/f3/zroot/bhyve/freebsd`
 
+Important: do not let `zfs-periodic` snapshot zrepl-managed sender or receiver
+datasets. Snapshot creation should be owned by zrepl. On f2,
+`/etc/periodic.conf` disables `zfs-periodic` snapshot creation:
+
+```sh
+daily_zfs_snapshot_enable="NO"
+weekly_zfs_snapshot_enable="NO"
+monthly_zfs_snapshot_enable="NO"
+```
+
+The local zrepl `snap` job on f2 also explicitly excludes `zroot/sink<`.
+
 ### f1 configuration (sink)
 
 ```sh
-- 
cgit v1.2.3