clawdie-iso/AGENTS.md

# Clawdie ISO Agent Guidelines

## 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.

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

Do not hand-align Markdown tables or reflow prose manually. `.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. Do not commit, quote, summarize publicly, or copy private content
to Forgejo unless the operator explicitly approves it.

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 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.

Agents on any platform MUST NOT start a new ISO build unless 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`.
- Required by ISO preflight: `colibri-daemon`, `colibri`, `colibri-test-agent`,
  and `colibri-mcp`.
  `colibri-tui` is optional in staging code but desired for this USB target and
  should be verified alongside the required binaries.

**Invariant:** do not `cargo clean` `/home/clawdie/ai/colibri` until the ISO
preflight/build has consumed `/home/clawdie/ai/colibri/target/release`.

---

## 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 — do not treat bhyve, nested VMs, or static image
inspection as 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 must not shell out to `sudo` for privileged host changes.
- Privileged Clawdie-AI host operations go through the hostd RPC layer.

---

## 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"
```

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.

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. 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.

---

## 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). Codeberg is the public mirror only; do not treat it as the source of
truth for agent coordination or branch-state claims.

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