From 278ea10c6313e76d5dcee907bcb2d872778a9ebb Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Sun, 21 Jun 2026 14:26:52 +0200 Subject: [PATCH] =?UTF-8?q?docs(plan):=20replace=20Track=20C=20with=203=20?= =?UTF-8?q?USB=E2=86=92disk=20deploy=20strategies?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Track C rewritten: old TS tarball-deploy plumbing replaced with the clawdie Rust binary strategies (C1: CLI, C2: wizard, C3: declarative). References the existing clawdie crate in Colibri (discover → plan → apply). C1 is zero new code — needs only 1 destructive validation test. --- PLAN-OPERATOR-USB-NEXT.md | 87 +++++++++++++++++++++++++++------------ 1 file changed, 61 insertions(+), 26 deletions(-) diff --git a/PLAN-OPERATOR-USB-NEXT.md b/PLAN-OPERATOR-USB-NEXT.md index d1a3743f..076301a7 100644 --- a/PLAN-OPERATOR-USB-NEXT.md +++ b/PLAN-OPERATOR-USB-NEXT.md @@ -124,39 +124,74 @@ hook so regressions are caught on the next build. later round once the data is in. - VSCode / Cursor. Stay off the live image — see project memory. -### Track C — Disk deployment progression (first step) +### Track C — Disk deployment: USB → bare metal -**Goal:** unblock the disk-install path so it can consume -`pkg-list-disk-install-extras.txt`. Per `AGENTS.md`: "The disk-install path -does not consume `pkg-list-disk-install-extras.txt` yet." +**Goal:** deploy the Clawdie service from a booted operator USB onto bare +FreeBSD hardware. -This round does **not** ship a full installer. It sets up the plumbing. +The `clawdie` binary (Rust, in `crates/clawdie` in Colibri) already does +`discover` → `plan` → `apply` for ZFS layout + rc.d service + clawdie user. +What's missing is the USB → disk workflow. Three strategies, ascending in +automation: -**Steps:** +#### Strategy C1: Direct CLI (validate now, ship immediately) -1. **Profile selection scaffold.** `firstboot/shell-desktop.sh` (or a new - `shell-profile.sh`) reads a `CLAWDIE_PROFILE` value with three valid - options: `xfce` (default), `kde`, `headless`. Wire from - `/tmp/clawdie-install.conf` for now — no GUI surface yet. -2. **Disk-install pkg step.** New function - `clawdie_shell_pkg_install_disk_extras` in `firstboot/shell-pkg.sh` - that installs every package in `packages/pkg-list-disk-install-extras.txt` - from the bundled offline repo, gated by profile (the `kde` profile - will later pull `pkg-list-kde.txt`; not creating that file yet). -3. **Hook from `firstboot.sh`.** Call the new function after base - firstboot completes, before `clawdie_shell_deploy_*` runs. -4. **Bhyve validation test.** A shell script under `scripts/` that boots the - built image in bhyve, runs the disk-install path with - `CLAWDIE_PROFILE=xfce`, and asserts `blender` (the roadmap-essential - member of disk-install-extras) ends up installed on the target disk. - Bhyve is suitable for plumbing verification; use real hardware for - graphical validation — leave that for Track A/E on real hardware. +``` +clawdie discover # see pools, confirm target +clawdie plan --pool tank # review ZFS layout, datasets, rc.d +clawdie apply --pool tank --yes # provision: datasets, user, rc.d service +``` + +**What exists:** `discover`, `plan`, and `apply --yes` are built and +unit-tested. `plan` + dry-run `apply` validated on FreeBSD host (osa). +**Gap:** `apply --yes` has not been run destructively on a scratch pool. +**Effort:** 1 destructive test on a VM/scratch pool. Zero new code. + +#### Strategy C2: Guided firstboot wizard + +A `/usr/local/sbin/clawdie-setup` shell script (or firstboot hook): +1. Run `clawdie discover`, show available pools +2. Prompt: "Which pool?" +3. Show `clawdie plan --pool ` for review +4. Prompt: "Deploy? [y/N]" +5. Run `clawdie apply --pool --yes` +6. Print success, point at `service clawdie start` + +**Effort:** ~60 lines shell script + firstboot wiring. A day's work. +**Depends on:** C1 validated first. + +#### Strategy C3: Declarative config (repeatable, auto-deploy) + +A `/etc/clawdie/deploy.toml` on the USB's FAT32 partition (editable from +any OS before boot): + +```toml +[host] +hostname = "clawdie-host" +pool = "tank" + +[zfs] +raid = "mirror" +disks = ["da0", "da1"] # only if creating a new pool + +[services] +postgresql = true # install + enable PostgreSQL + pgvector +bhyve = true # install bhyve + vm-bhyve +``` + +Boot behavior: +- If `/etc/clawdie/deploy.toml` present → `clawdie apply --config …` runs on boot +- If absent → boots to desktop (operator USB mode) + +**Effort:** Config schema + parser in `clawdie` crate (~120 lines Rust). +Firstboot auto-detect (~15 lines shell). A week of work. +**Depends on:** C1 validated first. **Definition of done:** -- One commit per step. Each step compiles and passes existing tests - before the next is added. -- A documented "what happens on disk install" paragraph in `FIRSTBOOT.md`. +- [ ] C1: `apply --yes` tested on scratch pool. `FIRSTBOOT.md` documents the CLI path. +- [ ] C2: `clawdie-setup` script exists, wired into firstboot, tested in bhyve. +- [ ] C3: `deploy.toml` schema defined, parser in `clawdie`, auto-detect on boot. ### Track D — Hardware detection pipeline refinement -- 2.45.3