From f7942c61d12e287b0c59609dc1e5e42ae7b72e56 Mon Sep 17 00:00:00 2001
From: Sam & Claude <samo.blatnik@gmail.com>
Date: Sun, 14 Jun 2026 00:35:01 +0200
Subject: [PATCH] docs: FreeBSD validation handoff for the clawdie installer

Codex validates the disk-touching + service-install paths (zfs/zpool create,
pw/rc.d service) that can't be exercised off-host. Includes read-only checks,
destructive provisioning steps for a scratch pool, teardown, and acceptance
criteria.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/CLAWDIE-INSTALLER-HANDOFF.md | 73 +++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 docs/CLAWDIE-INSTALLER-HANDOFF.md

diff --git a/docs/CLAWDIE-INSTALLER-HANDOFF.md b/docs/CLAWDIE-INSTALLER-HANDOFF.md
new file mode 100644
index 0000000..23fd621
--- /dev/null
+++ b/docs/CLAWDIE-INSTALLER-HANDOFF.md
@@ -0,0 +1,73 @@
+# Clawdie Installer — FreeBSD Validation Handoff
+
+**For:** Codex (FreeBSD 15 host) · **Crate:** `crates/clawdie` (binary `clawdie`)
+
+`clawdie` discovers a host's ZFS layout and provisions the `clawdie` service. It
+is built and unit-tested on Linux; the disk-touching and service-install paths
+cannot be exercised off-host, so they need FreeBSD validation.
+
+## 1. Build + unit tests
+
+```sh
+cargo build -p clawdie --release
+cargo test -p clawdie
+cargo clippy -p clawdie --all-targets -- -D warnings
+```
+
+Report: full `cargo test` output, `rustc --version`, `freebsd-version`.
+
+## 2. Read-only checks (safe on any host)
+
+```sh
+clawdie discover     # expect: os=FreeBsd, zfs available=true, real pools, clawdie datasets
+clawdie plan         # expect: resolves to the single pool (or pass --pool), ZFS dataset steps
+```
+
+Verify:
+
+- `discover` lists the real pools (parsed from `zpool list -H`) and any clawdie datasets.
+- On FreeBSD `plan` always resolves to **ZFS** (never plain-dirs); with no pool it errors clearly.
+- Expected gap: the `disks:` section uses `lsblk` (Linux-only), so it is **empty on FreeBSD** — that is correct. `--create-pool` is a Linux convenience; FreeBSD already has ZFS.
+
+## 3. Provisioning — DESTRUCTIVE, scratch host / VM / test pool only
+
+```sh
+clawdie apply --pool <testpool>         # dry-run: prints the plan, writes nothing
+clawdie apply --pool <testpool> --yes   # provisions
+```
+
+Validate after `--yes`:
+
+1. **Datasets** (`zfs list`): `<testpool>/clawdie` (canmount=off), `…/db` → `/var/db/clawdie`, `…/log` → `/var/log/clawdie`.
+2. **Service user** (`pw usershow clawdie`): nologin, home `/var/db/clawdie`.
+3. **rc.d service**: `/usr/local/etc/rc.d/clawdie` (mode 0555) and `clawdie_enable=YES` (`sysrc`). Check `service clawdie enabled` / `rcvar`.
+   - The script execs `/usr/local/bin/colibri-daemon`; if that binary isn't staged, `service clawdie start` will fail on the missing exec — expected. Confirm the script + enable are correct regardless.
+4. **Teardown** to reset:
+   ```sh
+   service clawdie stop 2>/dev/null; sysrc -x clawdie_enable
+   rm -f /usr/local/etc/rc.d/clawdie; pw userdel clawdie
+   zfs destroy -r <testpool>/clawdie
+   ```
+
+## 4. Optional — Linux `--create-pool` path (if a Linux host + spare disk exists)
+
+```sh
+clawdie discover                                       # spare disk shows "spare (usable…)"
+clawdie apply --pool tank --create-pool /dev/sdX --yes # DESTROYS /dev/sdX
+```
+
+Verify `zpool create` + datasets + systemd unit (`systemctl status clawdie`). Confirm
+the guard: `--create-pool` on a **non-empty** disk is refused without `--force`.
+
+## 5. Acceptance — delete this doc when all are true
+
+- [ ] `cargo test -p clawdie` passes on FreeBSD 15 (output + versions reported).
+- [ ] `discover` + `plan` correct against a real FreeBSD ZFS host.
+- [ ] `apply --yes` on a scratch pool creates the datasets, user, and rc.d service as specified; teardown verified.
+- [ ] (if tested) Linux `--create-pool` works on a spare disk and the empty-disk guard refuses non-empty disks.
+- [ ] Any FreeBSD-specific differences from the Linux-built behavior are filed as a PR and reported back.
+
+## Platform notes
+
+- Disk candidacy (`lsblk`) is Linux-only; FreeBSD relies on its existing pool.
+- `apply` writes only with `--yes`; `discover`, `plan`, and bare `apply` are read-only/dry-run.