docs: RUNBOOK result — USB enrollment on pool-scoped ACL (residual CLOSED)

Live supervised validation on felhom-pve: NO 403 on drive management under the
scoped token (agent has no storage-registration/pvesm path — all host-ops +
Datastore.Audit which is now box-wide). 3b-fix confirmed in the real UI (drives
Regisztrálva, no detach alert). A full physical wizard enroll couldn't complete
because a raw new device (SD-card reader, no PVE-storage entry) doesn't surface
in the init wizard (Observe() lists PVE storages only) — ACL-independent; flagged
as a separate new-drive-registration follow-up. No code change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

documentation/audits/RUNBOOK-usb-enrollment-3bfix-2026-07-01.md

@@ -0,0 +1,74 @@
+# RUNBOOK result — physical USB enrollment validation on the pool-scoped ACL (3b-fix closure)
+
+**Date:** 2026-07-01 · **Host:** felhom-pve (192.168.0.162, node demo-felhom) · **Class:** live
+supervised validation, **no code change, no version bump**. Baseline: script v1.7.0, agent v0.53.0,
+controller v0.94.0 — all reconfirmed.
+
+## Verdict
+
+**The ACL residual is CLOSED: drive enrollment / management needs NO `Datastore.Allocate` and hits NO
+403 under the pool-scoped token.** The v1.7.0 layout (`Datastore.Audit` box-wide in Base; write privs
+`Datastore.Allocate`/`AllocateSpace` per-storage) is complete for storage/drive operations.
+
+A full physical wizard enrollment could **not be completed**, but for a reason that is **ACL-independent
+and not a permission failure**: the plugged-in test device is an SD-card reader that does not surface as
+a wizard candidate (details below). Per the runbook's own decision branch, that is a "note it — separate
+follow-up, NOT a permission issue" outcome, not the STOP condition (which is a 403).
+
+## What was validated
+
+- **Baseline (reconfirmed):** roles `Base=Sys.Audit SDN.Use Datastore.Audit`, `Store=Datastore.Allocate
+  Datastore.AllocateSpace`, `Guest=VM.* + Pool.Allocate`. Agent v0.53.0 active. felhom-usb + felhom-flash
+  enrolled, mounted, untouched.
+- **New device identified unambiguously:** `/dev/sdd`, 59.5 GiB, `SD/MMC/MS PRO` card reader, by-id
+  `usb-Generic-_SD_MMC_MS_PRO_20120926571200000-0:0`, ntfs factory partition, **unmounted**. Distinct
+  from felhom-usb (sdc) + felhom-flash (sdb). Nothing was formatted (the wizard never offered it).
+- **S1 (drive visibility — the 3b-fix) — PASS, in the real UI:** the controller agent-view (Meghajtók
+  ügynök nézet) shows both felhom-usb + felhom-flash as **Regisztrálva** with full metadata and **no
+  "Meghajtó leválasztva" (detached) alert**. `felhom-agent --selftest=read` sees all **5** storages.
+- **No 403 anywhere:** the agent log across the whole interaction window (13:44→) shows zero pve-token
+  permission failures. (The only "permission denied" is the PRE-EXISTING, unrelated non-root PBS
+  key-file read — `/etc/pve/priv/storage/felhom-pbs.pw` — used for PBS *datastore metrics*, not for
+  backup; a known root→non-root fs-permission gap, see [[bundle-slice-day0-selfinstall]].)
+- **Write-containment intact (re-confirmed):** vzdump→felhom-usb → 403 (`Datastore.AllocateSpace`
+  per-storage); out-of-pool guest ops → 403.
+
+## Why the new drive did not appear in the wizard (root cause; ACL-independent)
+
+Confirmed at agent source:
+- The controller's drive list (`/settings/storage/init` wizard + agent-view) is served by the agent's
+  `GET /disks` (`internal/localapi/disks.go` `handleDisks`), which iterates **`storage.Observe()`**.
+- `Observe()` (`internal/storage/observe.go` `snapshot()`) enumerates **only PVE storages** via
+  `ListStorage`/`NodeStorage` (both `Datastore.Audit` — now granted box-wide). It does **not** enumerate
+  raw/unregistered block devices.
+- The agent has **no storage-registration path at all**: its disk endpoints are `assign` (host mount),
+  `eject`, `decommission`, `format` (mkfs), `guest-attach` (bind), `netstorage` (host mount) — all
+  **host-ops via sudo**. There is **no `pvesm add` / `POST /storage` / storage.cfg writer** anywhere in
+  the agent. So the agent never creates a PVE dir-storage (which is exactly why enrollment needs no
+  `Datastore.Allocate` — confirming the fix).
+
+Consequence: a **brand-new raw device that is not yet a registered PVE dir-storage never surfaces in the
+init wizard** — regardless of the token ACL (it would be equally absent under the old broad token). The
+existing `dir: felhom-usb` / `dir: felhom-flash` entries in `storage.cfg` were created out-of-band
+(operator/manual during initial setup), not by the agent. The SD-card reader used here (HOTPLUG=0, an
+ntfs partition) is simply one instance of "raw device with no PVE-storage entry."
+
+## Follow-up flagged (NOT a permission issue, NOT this task)
+
+**New-drive registration gap:** there is no self-serve path to turn a freshly-plugged raw drive into a
+Felhom-managed dir-storage — the init wizard only offers drives that are *already* PVE dir-storages. A
+colleague plugging in a genuinely new USB would need the operator to `pvesm add dir …` first (or a new
+controller/agent feature to register a raw device). Worth a design decision:
+- Option A: agent gains a `register-raw-drive` step (host-op `pvesm add` via sudo → still no token priv;
+  keeps the ACL as-is), fed by a raw-block-device candidate list (host-ops `lsblk`, not `Observe()`).
+- Option B: document that new-drive registration is an operator step.
+
+This is independent of the pool-scoped ACL and does not block it.
+
+## NOT done
+
+- A completed physical format→mount→enroll of a genuinely new drive (blocked by the registration gap
+  above, not the ACL). If desired, provide a drive that is already a PVE dir-storage (or add the entry
+  out-of-band) and re-run the wizard — the ACL will not block it (host-ops + Datastore.Audit only).
+- Cleanup: the SD-card stick was never touched (no format); it can be unplugged. felhom-usb/felhom-flash
+  + guest 9201 untouched and healthy throughout.