From 09632c16e79280087f2c36972c22968e3eadc043 Mon Sep 17 00:00:00 2001
From: Sam & Claude <hello@clawdie.si>
Date: Thu, 25 Jun 2026 13:10:41 +0200
Subject: [PATCH] skill(freebsd): add .pkgnew merge, service health check, pkg
 autoremove
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three additions from pre-merge review:

1. .pkgnew config merge — pkgbase drops updated configs as /etc/*.pkgnew.
   Find and merge them before rebooting so the 15.1 system boots with its
   own configs, not 15.0-era ones.

2. Service health check — post-reboot verification now includes explicit
   checks: colibri_daemon, postgresql, tailscaled, bastille jails, pfctl.
   Version numbers matching is not enough — services must be running.

3. pkg autoremove — clean up orphaned packages the upgrade leaves behind.
   Dry-run first, then remove.
---
 skills/freebsd-os-upgrade/SKILL.md | 27 +++++++++++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)

diff --git a/skills/freebsd-os-upgrade/SKILL.md b/skills/freebsd-os-upgrade/SKILL.md
index 0255ad6..450de5c 100644
--- a/skills/freebsd-os-upgrade/SKILL.md
+++ b/skills/freebsd-os-upgrade/SKILL.md
@@ -118,17 +118,40 @@ pkg update -f && pkg upgrade      # ports packages (separate from base here)
    - **freebsd-update**: `freebsd-update -r <target> upgrade` then
      `freebsd-update install`.
    Either way the new kernel is staged; the system runs the old one until reboot.
+
+   **After the upgrade, before rebooting** — pkgbase drops updated config files
+   as `/etc/*.pkgnew`. Find and merge them now so the 15.1 system boots with
+   its own configs, not 15.0-era ones:
+
+   ```sh
+   find /etc -name '*.pkgnew' -type f
+   # For each relevant file: diff old new, then mv .pkgnew over the original
+   ```
+
 4. **Confirm a reboot is needed**: `freebsd-version -k` newer than `uname -r`
    means staged-not-active. State that plainly and **reboot only on explicit
    operator go-ahead** — never reboot the always-on board host autonomously.
 5. **After reboot**: on freebsd-update hosts, run `freebsd-update install` again
    to finish userland. Then the *Post-reboot verification* block — `-k`/`-u`/
-   `uname -r` must all match, and the app-readiness checks (Clawdie control
-   plane, Forgejo, jails, PF, Tailscale) must pass.
+   `uname -r` must all match. Verify services came up on the new kernel:
+
+   ```sh
+   service colibri_daemon status
+   service postgresql status
+   service tailscaled status
+   bastille list               # jails running
+   pfctl -s info               # firewall active
+   ```
 6. **Packages**: same-major ABI (`FreeBSD:15:amd64`) is unchanged, so this is a
    freshness refresh, not a rebuild — pkgbase already covered it in step 3;
    freebsd-update hosts do `pkg update -f && pkg upgrade`. A same-major
    PostgreSQL bump needs no dump/restore (restart/reboot to load new binaries).
+   After the package refresh, clean up orphans the upgrade left behind:
+
+   ```sh
+   pkg autoremove -n          # preview
+   pkg autoremove             # remove orphaned packages
+   ```
 7. **Upgrade the jails** — the host upgrade does NOT touch them. Do this after
    the host is on the new kernel. See *Jails* below.
 8. **Re-register with mother** — the node's OS version changed. Re-run the