AGENTS.md

@@ -44,22 +44,23 @@ npx --yes prettier@3 --write path/to/file.md
 
 `.prettierrc` uses `proseWrap: preserve` (prose line breaks stay intentional)
 and `embeddedLanguageFormatting: off` for `*.md` (fenced code — JSON, mermaid,
-shell — is left exactly as written). Do not hand-align tables or reflow prose.
+shell — is left exactly as written). Use `npx prettier --write` for all
+markdown formatting; preserve intentional prose line breaks and fenced code.
 
 ## Target Platform
 
 **Destination runtime: FreeBSD 15.** Development happens on Linux (debby —
 Debian 13, this machine) but final validation must pass on FreeBSD 15.
 
-Target: `x86_64-unknown-freebsd` (Rust Tier-2). TLS is `rustls` to avoid
+Target: `x86_64-unknown-freebsd` (Rust Tier-2). TLS uses `rustls` for clean
-`openssl-sys` linking on FreeBSD.
+static linking on FreeBSD (no `openssl-sys` dependency).
 
 ## Agent Identity
 
 | Identity                | Platform                | Capabilities                              | Restrictions                                               |
 | ----------------------- | ----------------------- | ----------------------------------------- | ---------------------------------------------------------- |
-| Claude (domedog)        | Linux, domedog          | `cargo build`, `cargo test`, code edits   | Cannot claim FreeBSD 15 runtime proof; push for validation |
+| Claude (domedog)        | Linux, domedog          | `cargo build`, `cargo test`, code edits   | Delegate FreeBSD 15 runtime proof to the FreeBSD agent; push artifacts for validation |
-| Hermes (debby)          | Debian 13, debby        | `cargo build`, `cargo test`, code edits   | Cannot claim FreeBSD 15 runtime proof; push for validation |
+| Hermes (debby)          | Debian 13, debby        | `cargo build`, `cargo test`, code edits   | Delegate FreeBSD 15 runtime proof to the FreeBSD agent; push artifacts for validation |
 | Codex / Aider (FreeBSD) | FreeBSD 15 host         | `cargo test` on real FreeBSD, integration | Receives handoff docs; validates Linux-built artifacts     |
 | Operator (Sam)          | FreeBSD 15 host + Linux | Final review, merge, deploy               | Human — all deployment decisions require approval          |
 
@@ -80,9 +81,9 @@ Target: `x86_64-unknown-freebsd` (Rust Tier-2). TLS is `rustls` to avoid
 | `clawdie`               | Host installer/deployer: ZFS layout + `clawdie` service (FreeBSD/Linux) |
 | `colibri` (root)        | Workspace root + probe binaries                                         |
 
-The table lists the workspace members plus the root `colibri` package. Don't
+The table lists the workspace members plus the root `colibri` package. Always
-hard-code a crate count here — `Cargo.toml` `members` + the root is the source of
+derive the crate count from `Cargo.toml` `members` + the root — it is the
-truth, and a fixed number drifts.
+source of truth and stays accurate.
 
 Gate status should be rechecked from source instead of relying on a fixed test
 count:
@@ -191,8 +192,8 @@ cargo clippy --workspace --all-targets -- -D warnings
 
 Golden tests in `crates/colibri-contracts/tests/golden.rs` validate manifest
 output against reference fixtures. These fixtures are cross-platform — if a
-Linux-produced manifest differs from FreeBSD 15, investigate, don't silently
+Linux-produced manifest differs from FreeBSD 15, investigate and document
-accept the difference.
+the cross-platform difference before proceeding.
 
 ## Post-Build Cleanup (mandatory, all agents)
 

README.md

@@ -4,7 +4,7 @@ The Clawdie control plane core — a small, cross-platform (FreeBSD + Linux) Rus
 daemon that unifies coordination (task board, agent registry, skills catalog)
 with cache-first cost discipline (byte-stable prompt prefixes, cache-hit metering).
 
-**Status:** workspace gates are fmt/clippy/test/release green. Round 2 audit is closed. Current priorities: ISO boot/runtime validation, Pi spawn end-to-end, and cost-mode enforcement (see [`docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md`](docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md)). Avoid fixed crate/test counts here — see the crate table below and run the gate commands for the current state.
+**Status:** workspace gates are fmt/clippy/test/release green. Round 2 audit is closed. Current priorities: ISO boot/runtime validation, Pi spawn end-to-end, and cost-mode enforcement (see [`docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md`](docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md)). Always query live state: see the crate table below and run the gate commands for current counts.
 
 FreeBSD build lane handoff: `docs/FREEBSD-BUILD-LANE-HANDOFF.md`.
 ISO acceptance runbook: `docs/ISO-ACCEPTANCE-RUNBOOK.md`.
@@ -68,5 +68,5 @@ cargo run --release --bin colibri-runtime-inventory
 
 ## FreeBSD
 
-Target `x86_64-unknown-freebsd` (Rust Tier-2). TLS is `rustls` to avoid
+Target `x86_64-unknown-freebsd` (Rust Tier-2). TLS uses `rustls` for clean
-`openssl-sys` linking. Default DB path: `/var/db/colibri/colibri.sqlite`.
+static linking (no `openssl-sys` dependency). Default DB path: `/var/db/colibri/colibri.sqlite`.

docs/CLAWDIE-INSTALLER-HANDOFF.md

@@ -2,9 +2,10 @@
 
 **For:** Codex (FreeBSD 15 host) · **Crate:** `crates/clawdie` (binary `clawdie`)
 
-`clawdie` discovers a host's ZFS layout and provisions the `clawdie` service. It
+`clawdie` discovers a host's ZFS layout and provisions the `clawdie` service.
-is built and unit-tested on Linux; the disk-touching and service-install paths
+It is built and unit-tested on Linux; the disk-touching and service-install
-cannot be exercised off-host, so they need FreeBSD validation.
+paths require FreeBSD validation because they exercise host-specific ZFS and
+rc.d functionality.
 
 ## 1. Build + unit tests
 
@@ -26,7 +27,8 @@ clawdie plan         # expect: resolves to the single pool (or pass --pool), ZFS
 Verify:
 
 - `discover` lists the real pools (parsed from `zpool list -H`) and any clawdie datasets.
-- On FreeBSD `plan` always resolves to **ZFS** (never plain-dirs); with no pool or an unknown explicit pool it errors clearly.
+- On FreeBSD `plan` resolves exclusively to **ZFS**; plain-dir layouts are
+  unsupported and cause a clear error.
 - Expected gap: the `disks:` section uses `lsblk` (Linux-only), so it is **empty on FreeBSD** — that is correct. `--create-pool` is a Linux convenience; FreeBSD already has ZFS.
 
 ## 3. Provisioning — DESTRUCTIVE, scratch host / VM / test pool only

docs/CLAWDIE-STUDIO-PROPOSAL.md

@@ -10,8 +10,8 @@ A single "Clawdie Studio" experience where the operator can **edit
 docs/code while simultaneously running and observing Colibri** — agents,
 tasks, scheduler, sessions — all from one visual surface.
 
-The user should not need to switch between a terminal (colibri CLI / TUI)
+The studio provides a unified surface so the user operates the control plane
-and an editor (Zed) to operate the control plane. The studio ties them
+entirely within the editor, without terminal context-switching.
 together.
 
 ## Why Rust Makes This Feasible
@@ -202,8 +202,8 @@ This is sufficient for the next ISO if Zed is present but the integration bridge
 
 ## Implementation guardrails
 
-- Colibri remains service-owned and headless-safe; Zed never becomes required for boot or supervision.
+Colibri always remains service-owned and headless-safe; boot and supervision
-- MCP is the first real editor bridge because it avoids forking Zed and can serve other MCP-capable clients.
+function independently of any editor.
 - Native Zed extension/panel is a later UX layer, not the protocol source of truth.
 - Write tools are opt-in; spawn tools are separately guarded and allowlisted.
 - `set-cost-mode` remains runtime-only acknowledgement until a real mutable config model is implemented.

docs/COLIBRI-SKILLS-PLAN.md

@@ -73,7 +73,8 @@ video → local transcript → topic extraction → how-to/runbook
 | Layer            | Role              | Writes                       | Reads                                          |
 | ---------------- | ----------------- | ---------------------------- | ---------------------------------------------- |
 | Clawdie-AI       | Source of truth   | Skill artifacts via PR       | N/A                                            |
-| `colibri-skills` | Runtime consumer  | Never to source repo         | Indexed skill structs from committed artifacts |
+| `colibri-skills` | Runtime consumer  | Writes only to the runtime store; source repo remains read-only for the skills
+consumer.         | Indexed skill structs from committed artifacts |
 | Agents           | Authors/reviewers | Candidate skill artifact PRs | Skill content for task routing                 |
 | `system_brain`   | Agent/user memory | Personal/user/agent context  | Not canonical skill docs                       |
 | `system_ops`     | Runtime state     | Live task/service state      | Not skills                                     |
@@ -196,8 +197,9 @@ colibri verify-skill <id>
 - Treat local provenance paths like `/home/samob/Videos/...` as metadata only.
 - Verify checksums against committed artifacts, not local source paths.
 - Store paths relative to the Clawdie-AI repo.
-- Normal tests must not require PostgreSQL, remote Forgejo, or local source
+Normal tests run with only local SQLite and committed test fixtures; keep
-  videos/audio.
+PostgreSQL, remote Forgejo, and local media as optional integration
+dependencies.
 
 ## Future skillpacks
 

docs/COLIBRI-TOKENOMICS-TRIFECTA.md

@@ -26,13 +26,14 @@ measure-everything agent runtime. The "trifecta" is our north star.
 | Speed       | Tokens/second, cache-hit ratio, latency        | `colibri-deepseek` cache probe, T1.4     |
 | Cost        | Dollars per task. Not per token — per _result_ | `cost.rs` CostMode, escalation, metering |
 
-You cannot optimize one without understanding impact on the other two.
+Optimize each dimension with full awareness of its impact on the other two.
 A cheap model that needs 5 retries is more expensive than a capable model
 that gets it right in one shot.
 
 ## Token Arbitrage (the "golden line")
 
-The video's key economic insight: **don't just spend tokens — arbitrage them.**
+**Arbitrage tokens for maximum value.** Every byte that hits cache is a 10×
+discount — design prompts to maximize cache-hit prefixes.
 
 Cache-hit tokens cost ~10% of fresh tokens (DeepSeek pricing). Every byte
 in the stable prefix that hits cache is 90% cheaper. The arbitrage
@@ -120,8 +121,8 @@ text+image token budgets.
 2. **Arbitrage cache vs spend.** The stable prefix is free money.
    Maximize its size, minimize its churn.
 
-3. **Cost per intelligence, not per token.** Don't compare model prices
+3. **Cost per intelligence, not per token.** Compare cost-per-successful-task,
-   in a vacuum. Compare cost-per-successful-task. A $0.05 task that
+   not raw model prices in isolation. A $0.05 task that
    works is infinitely cheaper than a $0.01 task that fails.
 
 4. **Trade-offs are engineering.** There is no "best" model. There is

docs/FREEBSD-BUILD-LANE-HANDOFF.md

@@ -10,7 +10,7 @@ script, creates the `colibri` user, and enables the service. What remains is
 work only a FreeBSD host can do: build the FreeBSD binaries, run the image
 build, boot it, and run the acceptance checks.
 
-Linux agents cannot cross-compile the `x86_64-unknown-freebsd` binaries, so
+The `x86_64-unknown-freebsd` binaries must be compiled on the FreeBSD host;
 this lane belongs to the FreeBSD agent end to end.
 
 ## 0. Host evidence to report
@@ -46,7 +46,7 @@ auto-tracks.
 ## 2. Build the FreeBSD artifacts (host toolchains, not on the image)
 
 ```sh
-# Colibri release binaries — staged by the ISO build, never compiled by it
+# Colibri release binaries — pre-built and staged by the ISO build only
 cd colibri
 cargo build --workspace --release
 cargo test --workspace            # confirm green on real FreeBSD; report output

docs/HEADROOM-SIDECAR.md

@@ -64,7 +64,6 @@ Current daemon timeout: 5 seconds per sidecar request.
   cost-mode compaction.
 - Keep `COLIBRI_HEADROOM_ENABLED=0` for ISO/live-USB defaults unless Headroom is
   staged and validated on the target image.
-- FreeBSD: upstream `headroom-ai` may require local packaging work because some
+FreeBSD: ONNX/ORT-backed extras need local packaging; use a known-good Python
-  ONNX/ORT-backed extras do not have FreeBSD prebuilt binaries. Use a known-good
+environment and validate `scripts/headroom-sidecar.py` directly before enabling
-  Python environment and validate `scripts/headroom-sidecar.py` directly before
+the daemon flag.
-  enabling the daemon flag.

docs/INTEGRATION-LAYERED-SOUL.md

@@ -31,9 +31,9 @@ only a single flat `skills` table exists; the rest is **design only**
 
 ## Direction (one-way)
 
-`layered-soul` (git) is the **source of truth**; Colibri is a **consumer**. Import
+`layered-soul` (git) is the **source of truth**; Colibri is a **consumer**.
-flows one way (repo → Colibri). Don't hand-edit the imported runtime copy and
+Import flows one way (repo → Colibri). Always curate skills in the source repo,
-expect it to flow back — curate in the repo, then re-import.
+then re-import — runtime copies are ephemeral consumers.
 
 ## Closing the gap (future work)
 

docs/MULTI-AGENT-HOST-PLAN.md

@@ -83,7 +83,7 @@ socket calls.
 | --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------- |
 | 1   | **Multi-agent task-board contention** — `pick_agent` only tested with 0-1 agents; no capability-based multi-agent assignment test; no same-agent-multiple-tasks test | High     | Yes                              |
 | 2   | **CLI surface gaps** — `claim-task`, `transition-task`, `register-agent`, `list-agents` have no CLI; remote agents forced to use raw Python                          | Medium   | Yes                              |
-| 3   | **Agent presence model** — no `host` column, no `last_seen`, no heartbeat/lease; cannot detect stale remote agents                                                   | High     | Yes (schema change)              |
+| 3   | **Agent presence model** — missing `host`, `last_seen`, and heartbeat/lease columns; add these schema fields to detect stale remote agents | High     | Yes (schema change)              |
 | 4   | **Remote-safe task claim** — `claim_task` is a blind UPDATE, no concurrency safety, no lease/TTL                                                                     | Medium   | Yes                              |
 | 5   | **Python polling scripts** — `colibri_poll.py` and `colibri_task_done.py` have zero test coverage                                                                    | Medium   | Yes                              |
 | 6   | **TCP bridge round-trip** — socat bridge untested end-to-end                                                                                                         | Medium   | Partial (needs socat or FreeBSD) |

docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md

@@ -123,9 +123,9 @@ pub async fn poll_tasks(state: &SharedState) {
 ```
 
 It creates a `Spawner` and does nothing with it. No agent is ever spawned from
-the daemon loop. This blocks Gate 2 (agent observation parity) — we cannot
+the daemon loop. This blocks Gate 2 (agent observation parity): glasspane
-claim glasspane supervision works until a real process is spawned and its
+supervision requires a real spawned process whose JSONL events flow through
-JSONL events flow through to state transitions.
+to state transitions before it can be validated.
 
 ### What exists
 

docs/VAULT-PROVISION-FIRST-PROOF.md

@@ -125,8 +125,8 @@ sudo bastille destroy "$T"
 ## Security notes
 
 - Scratch jail + test collection only (first-proof policy) — no real tenant secrets.
-- Bootstrap creds (`BW_*`) live only in the daemon's `provider.env` (0600) and **never
+Bootstrap creds (`BW_*`) remain confined to the daemon's `provider.env`
-  enter the jail**; the jail receives only the resolved `.env`.
+(0600); only the resolved `.env` enters the jail.
 
 ## Follow-ups that retire the manual steps