From 3da596d5b97465c2b3b517fa259acf8290e09b8f Mon Sep 17 00:00:00 2001
From: Hermes & Sam <hello@clawdie.si>
Date: Sun, 14 Jun 2026 01:09:36 +0200
Subject: [PATCH] docs: add headroom compression plan (3.4), update status
 post-PR#53 review

- Phase 3.4: headroom Unix socket sidecar integration for Colibri
- Confirmed clawdie installer hardening (PR #53) is orthogonal
- Updated status table: layered-soul content now populated, headroom installed
- FreeBSD: zero blockers, Python 3 in base, daemon runs unprivileged
---
 docs/PLAN-CONFIGURE-PRIVATE-REPO.md | 53 +++++++++++++++++++++++++----
 1 file changed, 46 insertions(+), 7 deletions(-)

diff --git a/docs/PLAN-CONFIGURE-PRIVATE-REPO.md b/docs/PLAN-CONFIGURE-PRIVATE-REPO.md
index 5271516..d597ccd 100644
--- a/docs/PLAN-CONFIGURE-PRIVATE-REPO.md
+++ b/docs/PLAN-CONFIGURE-PRIVATE-REPO.md
@@ -6,13 +6,15 @@
 
 | Component | Status | Details |
 |-----------|--------|---------|
-| `hermes-soul` | ✅ Working | Private backup on code.smilepowered.org/clawdie/hermes-soul — 539 skills, 136 sessions, 2 memories, config all backed up and sanitized |
-| `layered-soul` scaffolding | ✅ Complete | Schema, validation script, 6 adapters, private-source planner, docs — all functional |
-| `layered-soul` content | ❌ Empty | SOUL.md and IDENTITY.md are 0 bytes, only 1 sample skill, no curated memories, USER.md is placeholders |
-| Colibri skills import | ✅ Working | `scripts/import-layered-soul.sh` imports `skills/**/*.md` into Colibri's flat `skills` SQLite table |
-| Colibri system_brain | ❌ Not built | `memories/curated/` detected but no DB table — concept only |
+| `hermes-soul` | ✅ Working | Private backup — 539 skills, 136 sessions, 2 memories, config sanitized |
+| `layered-soul` scaffolding | ✅ Complete | Schema, validation, 6 adapters, private-source planner |
+| `layered-soul` content | ✅ Populated | SOUL/IDENTITY/USER/AGENTS.md filled, 5 curated memories, 9 skills |
+| Colibri skills import | ✅ Working | `import-layered-soul.sh` imports skills into flat `skills` table |
+| Colibri system_brain | ❌ Not built | `memories/curated/` detected but no DB table |
 | Colibri system_ops | ❌ Not built | No schema, no manifest format |
-| Colibri system_skills (full) | 📋 Planned | Schema designed in docs/COLIBRI-SKILLS-PLAN.md but Phase 2-7 not implemented |
+| Colibri system_skills (full) | 📋 Planned | Schema designed, Phase 2-7 not implemented |
+| Headroom-ai | ✅ Installed | 0.25.0 on debby, 40%+ savings, integration planned in 3.4 |
+| Clawdie installer hardening | ✅ Merged PR #53 | Non-root daemon, ownership enforcement, pool validation |
 
 ### Architecture
 
@@ -117,7 +119,44 @@ Design `system_ops` for task/job manifests:
 - `op_id`, `manifest_path`, `manifest_hash`, `op_type`, `title`, `schedule`, `status`, `created_at`
 - Import script: converted cron/task manifests
 
-### 3.4 Test end-to-end
+### 3.4 Headroom compression middleware (NEW — 2026-06-11)
+
+Headroom-ai (0.25.0) is installed on debby — 40%+ token savings on tool outputs.
+Integrate as a Colibri Unix socket sidecar that compresses tool outputs before
+they enter agent context. Works identically on Linux and FreeBSD.
+
+**Architecture:**
+```
+tool output → session.rs:build_prompt_messages()
+  → headroom_compress(raw)          ← NEW
+  → compressed output → LLM prompt
+```
+
+**Files to modify (colibri-daemon):**
+
+| File | Change |
+|------|--------|
+| `cost.rs` | Add `HeadroomSidecar` struct + `headroom_compress()` fn |
+| `daemon.rs` | Spawn sidecar on startup (`DaemonState`) |
+| `session.rs:557` | Call `headroom_compress()` on tool results before prompt assembly |
+| `config.rs` | `COLIBRI_HEADROOM_ENABLED` env toggle (disabled by default) |
+
+**Sidecar**: Python script at `/usr/local/bin/headroom-sidecar.py` — simple loop:
+read JSON line from Unix socket → `compress()` → write compressed JSON back.
+
+**Installer impact**: `ServiceSpec` in crates/clawdie extended with optional
+`sidecar: Option<SidecarSpec>` — same pattern already used for colibri-daemon.
+The installer creates the sidecar user/unit, but the daemon manages lifecycle.
+
+**FreeBSD**: zero blockers. Python 3 in base, headroom pure Python, Unix sockets
+identical semantics. Daemon runs as unprivileged `clawdie` (hardened in PR #53)
+— sidecar inherits same security posture.
+
+**Clawdie installer hardening (PR #53) — confirmed orthogonal**: the installer
+creates the service user, ZFS datasets, and rc.d script. It never touches prompts,
+tool outputs, or compression. No adjustment needed to headroom plan.
+
+### 3.5 Test end-to-end
 1. Run hermes-soul-backup.sh → hermes-soul updated
 2. Run private-source planner → see what's new
 3. Import skills into Colibri → verify in DB