diff --git a/AGENTS.md b/AGENTS.md index fb2484cb..ac757a96 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,16 +3,16 @@ ## Agent Identity and Current Role Split The XFCE operator USB work now uses a git-coordinated split. Agents may review -or suggest across boundaries, but should not silently take over another role's -load-bearing responsibility. +or suggest across boundaries, but must coordinate explicitly before taking over +another role's load-bearing responsibility. | Role name | Identity | Owns | Restrictions | | ---------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | **Pi ISO Developer** | Pi harness (this dev agent) | Source changes, docs, static checks, commits, pushes | Does not start ISO builds or flash media unless explicitly assigned | -| **Codex ISO Builder** | codex pkg on the FreeBSD build host | `./build.sh`, mounted-image inspection, publishing, hardware validation | Should avoid broad source refactors; reports exact logs/output back through git or handoff notes | -| **Hermes USB/IMG Deployer** | Hermes on Debian/Linux | Downloading verified published artifacts, USB target identification, flashing | Does not need git-host access; never flashes unverified artifacts or partition paths | -| **Claude Reviewer / XFCE Tweaker** | Claude (Linux) | Review/plans plus Track E XFCE GUI polish | Cannot build ISO, cannot run FreeBSD-only validation, should mark speculative runtime claims as such | -| **Opencode / Z.ai Integrator** | Opencode CLI on Linux | Linux-side Colibri/dashboard experiments plus Pi/DeepSeek v4 provider-lane validation wiring | Cannot claim FreeBSD runtime proof; uses Sam-provided API keys only for provider validation | +| **Codex ISO Builder** | codex pkg on the FreeBSD build host | `./build.sh`, mounted-image inspection, publishing, hardware validation | Focuses on targeted changes; broad source refactors require prior review; reports exact logs/output back through git or handoff notes | +| **Hermes USB/IMG Deployer** | Hermes on Debian/Linux | Downloading verified published artifacts, USB target identification, flashing | Only flashes verified artifacts to whole-disk target paths; does not need git-host access | +| **Claude Reviewer / XFCE Tweaker** | Claude (Linux) | Review/plans plus Track E XFCE GUI polish | Builds ISO only through Codex ISO Builder; validates with Linux tooling; marks speculative runtime claims as such | +| **Opencode / Z.ai Integrator** | Opencode CLI on Linux | Linux-side Colibri/dashboard experiments plus Pi/DeepSeek v4 provider-lane validation wiring | Validates on Linux and refers FreeBSD runtime claims to the build host; uses Sam-provided API keys only for provider validation | | **Operator (Sam)** | Human operator | Product, hardware, acceptance, release judgment | Human approval required for release/tagging decisions | ## Agent / Codebase Check-In Matrix @@ -64,7 +64,8 @@ If it fails, format only the touched markdown files, then rerun the check: npx --yes prettier@3 --write path/to/file.md ``` -Do not hand-align Markdown tables or reflow prose manually. `.prettierrc` uses +Use Prettier for all Markdown formatting; rely on tool-owned formatting +rather than manual alignment. `.prettierrc` uses `proseWrap: preserve` so existing prose line breaks stay intentional, while Prettier still catches table padding, list spacing, and emphasis drift. @@ -72,8 +73,8 @@ Prettier still catches table padding, list spacing, and emphasis drift. `private/` is gitignored and may contain operator-private strategy notes or PRDs. Agents on this host may read files there only when directly relevant to the -assigned work. Do not commit, quote, summarize publicly, or copy private content -to Forgejo unless the operator explicitly approves it. +assigned work. Keep private content in `private/`; share to Forgejo only with +explicit operator approval. If working on custom ISO / hardware-report monetization, check `private/PRD-CUSTOM-ISO.md` when present. Codex ISO Builder should focus first @@ -83,12 +84,12 @@ surface should expose for report collection and review. ### Linux Agent Constraints -Linux agents MUST NOT attempt to build the ISO (`./build.sh`, `./build-vps.sh`). -ISO builds require FreeBSD system tools (`mdconfig`, `mount_msdosfs`, `pkg`). -Instead, guide Codex ISO Builder with exact commands to run on the FreeBSD -system. +Linux agents route all ISO builds to Codex ISO Builder on the FreeBSD +host. ISO builds require FreeBSD system tools (`mdconfig`, `mount_msdosfs`, +`pkg`). Instead, guide Codex ISO Builder with exact commands to run on the +FreeBSD system. -Agents on any platform MUST NOT start a new ISO build unless explicitly assigned. +Agents on any platform start ISO builds only when explicitly assigned. Builds are long-running, mutate repo-local caches, and can leave mounted md(4) devices that require cleanup. @@ -110,8 +111,9 @@ the ISO does **not** build Rust while the image is mounted. the required binaries. Validation images can add the local fake-agent helper with `COLIBRI_STAGE_TEST_AGENT=YES`. -**Invariant:** do not `cargo clean` `/home/clawdie/ai/colibri` until the ISO -preflight/build has consumed `/home/clawdie/ai/colibri/target/release`. +**Invariant:** preserve `/home/clawdie/ai/colibri/target/release` until the ISO +preflight/build has consumed it; run `cargo clean` only after the ISO build +completes successfully. --- @@ -120,8 +122,9 @@ preflight/build has consumed `/home/clawdie/ai/colibri/target/release`. The active branch target is the XFCE live operator USB. Authoritative state lives in `packages/` (what ships) and `PLAN-OPERATOR-USB-NEXT.md` (round-scope decisions and any "for now" retention notes). Final graphical validation -requires real hardware — do not treat bhyve, nested VMs, or static image -inspection as final proof that SDDM/XFCE works. +requires real hardware — treat bhyve, nested VMs, and static image +inspection as build gates only; real hardware is the final proof that +SDDM/XFCE works. --- @@ -132,8 +135,8 @@ inspection as final proof that SDDM/XFCE works. - On the FreeBSD build host, operator-facing commands may use `sudo`. - Inside the live USB, `sudo` is intentionally absent. - Live privileged actions use FreeBSD `mac_do` via `mdo -u root `. -- Agent runtime code must not shell out to `sudo` for privileged host changes. -- Privileged Clawdie-AI host operations go through the hostd RPC layer. +- Agent runtime code uses the hostd RPC layer for privileged host changes, + routing through the hostd RPC layer instead of shelling out to `sudo`. --- @@ -148,11 +151,10 @@ PROJECT_TMP="$PROJECT_ROOT/tmp" mkdir -p "$PROJECT_TMP" ``` -Use `$PROJECT_TMP/...` for generated checks, transient logs, extracted manifests, -image-inspection notes, helper-script test output, and other disposable files. -Do not create new `/tmp/clawdie-*`, `/tmp/colibri-*`, or ad-hoc `/tmp/...` paths -from agent work unless the operator explicitly asks for a host-global scratch -location. +Create all scratch files under `$PROJECT_TMP` for generated checks, transient +logs, extracted manifests, image-inspection notes, helper-script test output, +and other disposable files. Use host-global `/tmp` paths only when the operator +explicitly asks for a scratch location outside the repo. Live-USB runtime code usually has no git checkout/project root. In that case, prefer an app-owned cache/state path such as `$XDG_CACHE_HOME/clawdie`, @@ -191,10 +193,10 @@ ISO builds use repo-local `tmp/` for large caches and output artifacts: - `tmp/output` — generated `.img.xz` artifacts and checksums - `tmp/packages` — fetched package archives -`tmp/cache/mnt` is an ISO-builder-specific mountpoint exception. Do not mount -unrelated datasets, recovery filesystems, or scratch filesystems elsewhere under -repo `tmp/`. If a build is interrupted, use the `iso-build-cleanup` skill before -retrying. +`tmp/cache/mnt` is an ISO-builder-specific mountpoint exception. Use `tmp/` +mounts only for ISO builder work (cache/mnt); mount unrelated datasets, +recovery filesystems, or scratch filesystems elsewhere. If a build is +interrupted, use the `iso-build-cleanup` skill before retrying. --- @@ -209,8 +211,8 @@ Clawdie spans three repos. Changes often require coordinated updates. | `Colibri` | Cross-platform Rust control plane core | `git@code.smilepowered.org:clawdie/colibri.git` | Primary remote: `code.smilepowered.org` (self-hosted Forgejo, SSH via local host -config). Codeberg is the public mirror only; do not treat it as the source of -truth for agent coordination or branch-state claims. +config). Treat `code.smilepowered.org` as the source of truth for agent +coordination and branch-state claims; Codeberg is the public mirror only. When changes span both repos, create a handoff doc in the secondary repo listing what needs updating. See `Clawdie-AI/AGENTS.md` for full protocol. diff --git a/BUILD.md b/BUILD.md index a503b9a2..d92f39af 100644 --- a/BUILD.md +++ b/BUILD.md @@ -55,7 +55,8 @@ from the running USB with `mdo -u root tailscale up`. ### Colibri artifacts The operator USB stages Colibri as the live control plane. It expects prebuilt -FreeBSD release binaries; it does not compile Rust while the image is mounted. +FreeBSD release binaries; Rust compilation takes place before image mounting, +and only prebuilt binaries land on the mounted image. Default adjacent-checkout flow: @@ -119,8 +120,8 @@ Installed/deployed system No current ISO build flag stages `service clawdie`. That name is reserved for installed/deployed systems until the real persistent host service is chosen. The -baseline live USB uses Colibri directly and must not ship the old mini-binary as -if it were the final deployed service. +baseline live USB ships Colibri directly and excludes the old mini-binary +intended for the final deployed service. --- @@ -166,7 +167,8 @@ sudo dd if=tmp/output/clawdie-quindecim-0.10.0.img of=/dev/daX bs=1M status=prog sync ``` -Use the whole USB device (`/dev/daX`), not a partition. See [FLASHING.md](FLASHING.md) +Target the whole USB device (`/dev/daX`); flashing to a partition is unsafe and +unsupported. See [FLASHING.md](FLASHING.md) for Linux commands, checksum verification, and stale-label cleanup. --- @@ -262,7 +264,7 @@ Current implementation: **Distribution-safety note:** public keys are public, so baking one in is not a confidentiality issue — but anyone with the image file can SSH into a live boot of it. For dev/test builds that's the right tradeoff. For public -release images, do not pass `--ssh-key` at all; operators add a key +release images, omit `--ssh-key` entirely; operators add a key themselves after first boot or build their own image. The dedicated `clawdie-live-usb` key avoids leaking personal keys into shareable images. @@ -302,9 +304,9 @@ The implementation contract: **Scope discipline:** mDNS is **only** for LAN discovery of the live USB itself. Clawdie's internal service names continue to live under `home.arpa` (`ai.home.arpa`, `cms.home.arpa`, `git.home.arpa`, -`.home.arpa`). Do not switch internal services to `.local` — -RFC 6762 reserves `.local` for mDNS, and mixing the two namespaces -breaks both. +`.home.arpa`). Keep internal service names under `home.arpa`; +reserve `.local` exclusively for mDNS — RFC 6762 reserves `.local` for +mDNS, and mixing the two namespaces breaks both. **Network caveat:** some corporate networks, hotel Wi-Fi, and isolated guest VLANs block multicast traffic. In those environments @@ -319,10 +321,10 @@ open, inbound limited to SSH, mDNS, ICMP, DHCP-client, and Tailscale's UDP 41641. The actual access restriction on SSH is carried by `sshd` auth policy (pubkey only), not PF interface scoping. -**No logging stack on disk or in memory by default.** `pflog_enable` -and `pflogd_enable` are both left at their `NO` defaults. The ruleset -has no `log` keywords, so there is nothing to capture anyway. When -debugging from a booted live USB, the operator brings the stack up by +**PF logging stack is opt-in by default.** `pflog_enable` +and `pflogd_enable` remain at their `NO` defaults. The ruleset +has no `log` keywords, so nothing is captured by default. When +debugging from a booted live USB, the operator enables the stack by hand: ```sh @@ -471,8 +473,8 @@ path (fetched, not installed on live), but different long-term homes: ffmpeg/libpulse/mesa-libs/boost surface would partially un-do the lean-rootfs payoff we want during the early hardware-validation cycle. **Long-term home: back on the live USB** once dependency - surface is audited and operator workflow exists. Do not categorise - it as desktop-spin cruft in a future audit. + surface is audited and operator workflow exists. Classify it as + roadmap-essential in all future audits, not desktop-spin cruft. **Intent:** keep this table as the authoritative "what we will deploy to disk" reference so the work is not lost between commits. The @@ -609,9 +611,8 @@ When OSA gets tight on disk, prefer deleting **repo-local build artifacts** (`tmp/packages`, `tmp/cache/work.img`, cached FreeBSD memstick images, old output artifacts) over pruning host packages. -Do **not** treat the remaining host-side graphics/media stack as disposable "old -X11". On OSA it is not a full desktop environment anymore; it is a shared runtime -closure that supports current operator tooling and validation lanes: +Preserve the remaining host-side graphics/media stack; it supports current +operator tooling and validation lanes, not an old X11 desktop: - `ffmpeg` + `py311-pillow` back the Hermes/image-render and screenshot path. - `gtk3`, `cairo`, `pango`, `fontconfig`, `libX11`, `mesa-*`, `wayland`, diff --git a/PLAN-OPERATOR-USB-NEXT.md b/PLAN-OPERATOR-USB-NEXT.md index f37c7523..d1a3743f 100644 --- a/PLAN-OPERATOR-USB-NEXT.md +++ b/PLAN-OPERATOR-USB-NEXT.md @@ -16,9 +16,9 @@ Live boot has cleared the "does it come up at all on real hardware" gate. | NVIDIA | Pending | Laptop candidate arriving; not validated yet | **Load-bearing decision: keep SDDM as the live display manager.** -SDDM is the validated live display-manager path for Intel and AMD GUI boot. Do -not replace it without equivalent real-hardware proof. SDDM is now part of the -operator-USB contract. +SDDM is the validated live display-manager path for Intel and AMD GUI boot. +Retain SDDM until equivalent real-hardware proof validates any replacement. +SDDM is now part of the operator-USB contract. Other now-stable pieces from recent commits worth not regressing: @@ -97,8 +97,8 @@ hook so regressions are caught on the next build. - `operator-workflow` (firefox, codex, pi tools, tmux, ...) - `diagnostic` (btop, hw-probe, dmidecode, ...) - `candidate-to-defer` (used rarely or replaceable by a base tool) - Write the result as comments next to each line; do NOT remove anything - yet — categorization first, removal in a follow-up. + Write the result as comments next to each line; categorize first and + defer removal to a follow-up round after the data is in. 2. **Size accounting.** For each line, add the pkg + flat size as a trailing comment (`# 12M / 38M`). Use `pkg info -s ` on the FreeBSD build host. This makes future "is X cheap to add" calls honest @@ -108,7 +108,8 @@ hook so regressions are caught on the next build. - SDDM is enabled in `rc.conf`. - `clawdie-live-gpu` rc.d service is enabled. - Required kmods present in `/boot/modules` for Intel/AMD; NVIDIA - kmods are _present in the offline repo but NOT loaded by default_. + kmods are \textit{available in the offline repo} and remain unloaded + unless explicitly configured. - Live operator pkg-list contents are actually installed in the image. - Panel module gates (`xfce4-mixer`, `clipman`) honor their runtime conditions (audio backend up, X session up). @@ -148,7 +149,7 @@ This round does **not** ship a full installer. It sets up the plumbing. 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 fine for plumbing; per `AGENTS.md` it's NOT proof for + Bhyve is suitable for plumbing verification; use real hardware for graphical validation — leave that for Track A/E on real hardware. **Definition of done:** @@ -241,8 +242,8 @@ contract between agents. them. - FreeBSD safety remains local: builds, mounts, flashes, watchdog checks, and privileged host actions are not delegated to a remote chat agent. -- Do not add a separate dashboard/pane-fabric dependency to the live USB for - this track; Colibri is the control-plane surface. +- Rely on Colibri as the sole control-plane surface for this track; add no + separate dashboard/pane-fabric dependency to the live USB. - Cross-host coordination starts with small JSON manifests and summaries; raw logs, screenshots, and pcaps move only on demand. - Skills should be additive and runnable without an interactive dashboard. The @@ -631,9 +632,9 @@ folder so `$HOME` stays uncluttered: **Implementation notes:** -- Seed clean checkouts or source snapshots only; do not copy API keys, - `.env` files, SSH private keys, build caches, package caches, `tmp/`, or - other private host state. +- Seed clean checkouts or source snapshots only; include only code and exclude + API keys, `.env` files, SSH private keys, build caches, package caches, + `tmp/`, and other private host state. - Prefer the exact branch/commit used by the image build, recorded in `/usr/local/share/clawdie-iso/build-manifest.json` and visible from `hw-report`. @@ -644,8 +645,9 @@ folder so `$HOME` stays uncluttered: - If full `.git` history is too large, use shallow clones or archive snapshots plus a small manifest that records remote URL, branch, commit, and modified state. -- This is a live-debug aid, not a build-host replacement: Linux agents still do - not build the ISO, and real hardware proof remains operator/Codex-owned. +- This is a live-debug aid, not a build-host replacement: Linux agents direct + build commands to Codex ISO Builder on the FreeBSD host, and real hardware + proof remains operator/Codex-owned. **Why it matters:** when Colibri, XFCE, rc.d, input, or package-list bugs only show up on real hardware, a local Pi session can read `/var/log`, `hw-report`, @@ -743,8 +745,8 @@ I accept the **Codex ISO developer** role for this round: - docs/static checks - commits and pushes -I do not treat GUI success as proven without Pi Builder / hardware output, and -I do not start ISO builds or flash media unless explicitly assigned. +I treat GUI success as proven only with Pi Builder / hardware output, and +I start ISO builds or flash media only when explicitly assigned. --- @@ -753,7 +755,7 @@ I do not start ISO builds or flash media unless explicitly assigned. - VSCode or Cursor on the live image. Both deferred per project memory. VSCode is a candidate for disk-install extras _later_, after Track B gives us a real size + dep budget. -- Replacing SDDM. Load-bearing; do not touch. +- Replacing SDDM. Load-bearing; SDDM stays as-is for this round. - KDE profile content. Track C only scaffolds the selector; KDE pkg list comes in a later round. - Linuxulator integration of any kind. diff --git a/skills/iso-build/SKILL.md b/skills/iso-build/SKILL.md index a37ca034..db821989 100644 --- a/skills/iso-build/SKILL.md +++ b/skills/iso-build/SKILL.md @@ -9,8 +9,9 @@ Use this skill for the normal FreeBSD host build path from the checked-out `clawdie-iso` repo. This is the current repo-local operator workflow, not the older “clone elsewhere and publish to nginx” flow. -Only run an ISO build when the operator explicitly assigns it. If the task is -planning, docs, package-list edits, or static inspection only, do not build. +Run ISO builds only when the operator explicitly assigns one. For planning, +docs, package-list edits, or static inspection tasks, use static checks +instead of building. ## Current operator-USB expectations @@ -18,7 +19,7 @@ planning, docs, package-list edits, or static inspection only, do not build. - Live browser: Firefox, not Chromium - SDDM interactive login as `clawdie`; no live autologin - `CLAWDIESEED` exists as FAT32 slice 3 for post-flash, pre-boot seed import -- Live CLI policy: ship `codex`, `pi`, `gemini`; do not ship `claude` +- Live CLI policy: ship `codex`, `pi`, `gemini`; omit `claude` from the live image - Operator editors: `mousepad`, `geany`, and `micro` - Hardware/custom-ISO report collector: `hw-report` - Vulkan diagnostic tool: `vulkaninfo` from `vulkan-tools`; Zed remains deferred @@ -53,7 +54,8 @@ conventions. - Prefer `tmux` for long builds - Use an elevated shell in the tmux pane so the build command itself runs without a `sudo` prefix -- Run one command at a time; do not hide failures behind chained shell commands +- Run each command individually so failures are visible and attributable; + chain commands only when a prior success is required and verified - Fetch before reporting remote state or starting a build - If disk is tight, the image build was interrupted, or `tmp/cache/mnt` is still mounted, use `iso-build-cleanup` first @@ -81,7 +83,8 @@ tmux capture-pane -pt clawdie:3.1 -S -30 ps auxww | egrep '[b]uild.sh|[s]cript -q tmp/operator-usb-.*-build.log' ``` -If a build is still active, do not clobber it. Stop or wait deliberately. +If a build is still active, preserve it — stop it deliberately or wait for +completion before reusing the pane. ### 3. Start clean after a failed attempt @@ -133,11 +136,11 @@ switch to `iso-build-cleanup`. The operator USB uses Colibri as its lightweight live control plane. The ISO build stages FreeBSD-native Colibri artifacts from `/home/clawdie/ai/colibri`; it does **not** build Rust while the image is mounted. Validation builds should -ship `colibri_daemon_enable=YES`; the rc.d service starts after LOGIN and must -not block SDDM/XFCE startup. +ship `colibri_daemon_enable=YES`; the rc.d service starts after LOGIN and +completes before SDDM/XFCE are user-facing, avoiding any startup delay. -Build Colibri on the FreeBSD/OSA host, not on Debian/Linux. Do not cross-ship -from debby unless the native OSA build fails. +Build Colibri on the FreeBSD/OSA host first; fall back to cross-shipping from +debby only if the native OSA build fails. Run this before the ISO build: @@ -185,10 +188,10 @@ sh -n build.sh sh -n scripts/stage-colibri-iso.sh ``` -Important cleanup timing: **do not run `cargo clean` immediately after the -Colibri build.** The ISO preflight/build consumes `/home/clawdie/ai/colibri/target/release`. -Only clean Colibri after the ISO build or after deciding those artifacts are no -longer needed: +Important cleanup timing: **preserve Colibri artifacts until the ISO build +consumes them.** The ISO preflight/build reads from +`/home/clawdie/ai/colibri/target/release`. Clean Colibri only after the ISO +build or after deciding those artifacts are no longer needed: ```sh cd /home/clawdie/ai/colibri @@ -206,16 +209,17 @@ should be verified with the required binaries. `service clawdie` is reserved for installed disk/server targets, but the current operator USB does not stage a `clawdie` rc.d service or mini-binary. The live USB uses `colibri_daemon` directly. Add deployed-system service packaging only after -the real persistent host service implementation is chosen; do not repurpose the -old Colibri-side mini-binary as the final service by default. +the real persistent host service implementation is chosen; keep the old +Colibri-side mini-binary for reference only until then. ### Next build: carry the XFCE operator-USB fixes The next operator-USB image must retain the proven XFCE/live-GUI fixes (`PLAN-OPERATOR-USB-NEXT.md`, `doc/AMD-ASUS-XFCE-LIVE-USB-FINDINGS.md`): -- **SDDM remains the supported live display manager** — load-bearing; do not - replace without equivalent real-hardware proof for Intel + AMD live GUI boot. +- **SDDM remains the supported live display manager** — load-bearing; retain + SDDM until equivalent real-hardware proof validates any replacement for + Intel + AMD live GUI boot. - **`clawdie-live-gpu`** pre-SDDM rc.d KMS pick (conservative; NVIDIA/AMD safe). - **Hardened USB-root power policy** (`b9290ab`): `powerdxx`, C3 C-state default, `hw.usb.no_suspend=1`, boot-time `power_profile`.