# Clawdie ISO Agent Guidelines ## Project Identity **clawdie-iso** builds the operator USB image — a live FreeBSD 15 XFCE environment that serves two roles: - **Development surface** for Colibri: build, validate, and iterate on the control plane from a bootable USB without touching the host OS. - **Installer** for the **Clawdie service**: deploys Colibri as an rc.d service on bare FreeBSD hardware (ZFS RAID1 mirror, PostgreSQL + pgvector, bhyve VMs, Bastille jails). The USB is the swiss-army knife — the bare-metal install is the production target. ## Versioning & Release The image carries its **own product version**, not one borrowed from a component. `ISO_VERSION` is set explicitly in `build.cfg` (currently `0.11.0`, unified with Colibri); a build with no version fails fast. The image name derives from the FreeBSD codename and this version — e.g. `clawdie-quindecim-0.11.0.img` (`quindecim` = FreeBSD 15, `build.sh:146`). Component versions (clawdie-iso, clawdie-ai, colibri, zot) are **provenance**: recorded in `build-manifest.json` as `version_scheme: "product"`. They describe what went into the artifact; they are not its identity. `BUILD_CHANNEL` selects the build mode: - `dev` (default) — iteration builds; staged repos may be dirty. - `release` — the published-artifact gate. `build.sh:check_release_gate` requires every staged source (clawdie-iso, clawdie-ai, colibri, zot) to be a clean tree (`git status --porcelain`, so untracked files also fail) so the manifest's recorded commits fully describe the build. This is reproducibility-by-record, and is separate from any future package-repo channel (latest/quarterly/signed). ## 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 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 | 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 Use this as the lightweight "who checks in where" matrix while work spans multiple repos. Pushed commits, mounted-image reports, manifests, or explicit handoff docs are the expected check-in surface. | Agent lane / identity | Primary codebase(s) | Typical check-in artifact | | ------------------------------ | ---------------------------------------------------------- | ------------------------------------------------------------------ | | **Pi ISO Developer** | `clawdie-iso` | Small pushed commit on active branch plus static-check result | | **Codex ISO Builder** | `/home/clawdie/ai/clawdie-iso`, `/home/clawdie/ai/colibri` | Build log, mounted-image sweep, publish manifest, validation notes | | **Hermes USB/IMG Deployer** | published ISO artifacts | Checksum/manifest verification plus flash-target confirmation | | **Claude Reviewer / Tweaker** | `clawdie-iso` | Review/GUI-polish commit or explicit handoff note | | **Opencode / Z.ai Integrator** | `clawdie-ai`, `colibri` | Provider validation output, small manifest, or handoff doc | | **Operator (Sam)** | all three repos | Final acceptance note, branch choice, release/publish approval | ### Git Coordination Rules - Coordinate through git: fetch before commenting on remote state, push small reviewable commits, and include test/build status in commit messages. - Claude may push critique/suggestion commits, but Pi ISO Developer should re-check and adjust implementation details before the next build target is treated as final. - Codex ISO Builder consumes pushed build targets, builds/publishes artifacts, and reports hardware findings with exact commands and output. - Hermes USB/IMG Deployer consumes published artifact URLs/manifests, verifies checksums on Linux, identifies the USB target, and owns the final image-to-USB deployment handoff. - Opencode / Z.ai Integrator owns Linux-side Colibri/dashboard experiments and the Pi/DeepSeek v4 validation lane when Sam provides a `ZAI_API_KEY`; findings should come back as exact commands, output, provider/version notes, and small manifests/summaries that Colibri can ingest. - If a change needs a long ISO build, USB flash, or real hardware proof, hand it to the owning role instead of running it opportunistically. ### Markdown Formatting Gate Markdown formatting is tool-owned, not taste-owned. Before pushing any commit that edits `*.md`, run: ```sh ./scripts/check-format.sh ``` If it fails, format only the touched markdown files, then rerun the check: ```sh npx --yes prettier@3 --write path/to/file.md ``` 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. ### Private Planning Workspace `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. 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 on the local-only `hw-report` feasibility path and, after analysis, return concise action notes for Claude Reviewer / XFCE Tweaker on what GUI surface should expose for report collection and review. ### Linux Agent Constraints 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 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. ### Colibri Dependency The ISO build stages FreeBSD-native Colibri control-plane artifacts from the canonical `/home/clawdie/ai/colibri` checkout (`FEATURE_COLIBRI=YES` is the default lane). The staging is wired into `build.sh` and `scripts/stage-colibri-iso.sh`; the ISO does **not** build Rust while the image is mounted. - Build Colibri release artifacts on the FreeBSD/OSA host, not on Debian/Linux. - Build order, binary verification, and cleanup timing live in the `iso-build` skill (§Colibri artifact preflight). - Staging layout (installed paths, rc.d, directory ownership) is owned by Colibri `docs/ISO-INTEGRATION-PLAN.md`. - Production-image preflight requires the core Colibri set: `colibri-daemon`, `colibri`, and `colibri-mcp`. `colibri-tui` is optional in staging code but desired for this USB target and should be verified alongside the required binaries. Validation images can add the local fake-agent helper with `COLIBRI_STAGE_TEST_AGENT=YES`. **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. --- ## Current XFCE Operator USB Baseline 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 — treat bhyve, nested VMs, and static image inspection as build gates only; real hardware is the final proof that SDDM/XFCE works. --- ## System Configuration **Privilege model:** distinguish build-host administration from live-USB runtime. - 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 uses the hostd RPC layer for privileged host changes, routing through the hostd RPC layer instead of shelling out to `sudo`. --- ## Scratch / Temporary Files Policy Agents must use the project-local scratch workspace for repo work instead of system-global `/tmp` paths. Treat the repo root as `$PROJECT_ROOT` and use: ```sh PROJECT_ROOT=$(git rev-parse --show-toplevel) PROJECT_TMP="$PROJECT_ROOT/tmp" mkdir -p "$PROJECT_TMP" ``` 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`, `$HOME/.cache/clawdie`, `/var/cache/clawdie`, or `/var/db/clawdie` rather than `/tmp`. If a runtime helper supports both modes, it should use `$PROJECT_ROOT/tmp` when a project root is detectable and fall back to the app-owned live path. Known platform/tooling exceptions should stay narrow and documented: Xorg's standard `/tmp/.X11-unix` / `/tmp/.X*-lock`, bsdinstall handoff files, and the installer handoff below. ### Installer Temp Files Exception The GUI installer uses `/tmp/clawdie-install.conf` to pass wizard values to `firstboot.sh`. This is the narrow historical exemption from the project-local `tmp/` rule. **Rationale:** - Live ISO has no project root during the installer handoff - Single-user install phase (no other users on the system) - File is consumed once by `firstboot.sh` then deleted on reboot - PF firewall is not yet running during install **Applies only to:** - `/tmp/clawdie-install.conf` — GUI wizard config output - `/tmp/clawdie-firstboot.*` — firstboot progress and log (written by rc.d) ## Repo-local ISO Build Workspace ISO builds use repo-local `tmp/` for large caches and output artifacts: - `tmp/cache` — build cache - `tmp/cache/mnt` — temporary md(4) work-image mountpoint - `tmp/output` — generated `.img.xz` artifacts and checksums - `tmp/packages` — fetched package archives `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. --- ## Cross-Repo Coordination Clawdie spans three repos. Changes often require coordinated updates. | Repo | Purpose | Remote | | ------------- | ---------------------------------------- | --------------------------------------------------- | | `Clawdie-AI` | Agent runtime, control plane, channels | `git@code.smilepowered.org:clawdie/clawdie-ai.git` | | `clawdie-iso` | ISO builder, firstboot wizard, installer | `git@code.smilepowered.org:clawdie/clawdie-iso.git` | | `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). 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. --- ## Agent Handoff Documents Use ephemeral handoff files to transfer context between agents. - **Name:** `doc/-HANDOFF.md` or `-HANDOFF.md` (repo root) - **Lifecycle:** Create when handing off, delete when complete - **Structure:** Must include task checklist, deletion criteria, results section See `Clawdie-AI/AGENTS.md` for the full handoff template and protocol. --- ## Attribution in Commit History Use attribution in commit messages, not in code comments. Labels: - `Sam & Codex` — changes made by Sam and Codex - `Sam & Claude` — changes made by Sam and Claude - `C&C` — joint change with equal credit for Claude and Codex Add the label to the commit subject or body. Example: ``` Fix bhyve preflight checks (C&C) ```