clawdie-iso/AGENTS.md

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:

./scripts/check-format.sh

If it fails, format only the touched markdown files, then rerun the check:

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 sample-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 <command>.
• 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:

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/<FEATURE>-HANDOFF.md or <FEATURE>-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)