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:

```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 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:

```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/<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)
```