From 5896a4ddcd0ab4946b101a4593dd5b2ff1fadaca Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Wed, 24 Jun 2026 17:32:13 +0200 Subject: [PATCH] docs: move reference docs into wiki (agent-events, headroom, layered-soul) --- docs/README.md | 2 - .../agent-events-reference.md} | 17 ++++---- docs/wiki/agent-harness.md | 2 +- docs/wiki/cost-model.md | 4 +- .../headroom-sidecar.md} | 9 +++- docs/wiki/index.md | 41 ++++++++++--------- .../layered-soul.md} | 27 +++++++----- 7 files changed, 58 insertions(+), 44 deletions(-) rename docs/{AGENT-EVENTS-REFERENCE.md => wiki/agent-events-reference.md} (93%) rename docs/{HEADROOM-SIDECAR.md => wiki/headroom-sidecar.md} (90%) rename docs/{INTEGRATION-LAYERED-SOUL.md => wiki/layered-soul.md} (59%) diff --git a/docs/README.md b/docs/README.md index bd6ab0f..d26301d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,8 +10,6 @@ A quick-reference guide to every document in this folder. | [`COLIBRI-JAILED-AGENT-SPAWN-DESIGN.md`](COLIBRI-JAILED-AGENT-SPAWN-DESIGN.md) | FreeBSD jail confinement for spawned agents — accepted & implemented | Rust agents | | [`COLIBRI-SKILLS-PLAN.md`](COLIBRI-SKILLS-PLAN.md) | Skills catalog roadmap: read-only Phase 1, write-gated Phase 2+ | Agents | | [`COLIBRI-TOKENOMICS-TRIFECTA.md`](COLIBRI-TOKENOMICS-TRIFECTA.md) | Strategic vision: useful tokens, cost-per-intelligence, measurement | All | -| [`HEADROOM-SIDECAR.md`](HEADROOM-SIDECAR.md) | Optional `headroom-ai` tool-result compression sidecar | Agents | -| [`INTEGRATION-LAYERED-SOUL.md`](INTEGRATION-LAYERED-SOUL.md) | How Colibri consumes `layered-soul` reviewed context today vs planned | Agents | | [`ISO-ACCEPTANCE-RUNBOOK.md`](ISO-ACCEPTANCE-RUNBOOK.md) | Post-boot acceptance commands after staging Colibri into an ISO | Codex (FreeBSD) | | [`ISO-SERVICE-LAYOUT.md`](ISO-SERVICE-LAYOUT.md) | `rc.conf` service layout for the ISO image | All | | [`MULTI-AGENT-HOST-PLAN.md`](MULTI-AGENT-HOST-PLAN.md) | **Current sprint**: multi-agent task-board tests + CLI surface gaps | All agents | diff --git a/docs/AGENT-EVENTS-REFERENCE.md b/docs/wiki/agent-events-reference.md similarity index 93% rename from docs/AGENT-EVENTS-REFERENCE.md rename to docs/wiki/agent-events-reference.md index dfdd092..6e4bdcd 100644 --- a/docs/AGENT-EVENTS-REFERENCE.md +++ b/docs/wiki/agent-events-reference.md @@ -1,12 +1,6 @@ # Agent events reference -> **Developer reference — operators can skip.** Plain version: `wiki/agent-harness`. - -Per-harness reference for the event stream Colibri ingests into Glasspane. Each -harness emits its own format; this file documents one section per harness. -Currently documented: **zot** (the pi harness emits `pi --mode json` events, -parsed by `pi_event_type`). The zot capture below is from a real DeepSeek run -(21.jun.2026). +← [index](./index.md) ## Request shape @@ -64,7 +58,7 @@ needed to capture a real tool call before the driver can trust those mappings. Step 1 of colibri#143 is complete after the real-key re-run below. Steps 2 and 3 are unblocked. -## Real-key transcript (complete tool call, 21.jun.2026) +## Real-key transcript (complete tool call, 2026-06-21) Prompt: "run uname -a and tell me the kernel version in one sentence" 61 lines, 2 turns, 1 tool call (bash), DeepSeek v4-pro, cached tokens. @@ -97,7 +91,7 @@ Prompt: "run uname -a and tell me the kernel version in one sentence" {"type":"done"} ``` -Full 61-line transcript at `/tmp/zot_transcript_full.txt` (OSA). +Full 61-line transcript is stored on OSA, outside the repository. ### Confirmed event types (real-key run) @@ -141,3 +135,8 @@ normalizer. `tool_use_start` is the sole entry point for tool execution start. Step 1 of colibri#143 is complete — wire format and all 15 event types are validated against real output. The `tool_call` double-fire gap is resolved by skipping the duplicate standalone event in Glasspane. + +## See also + +- [agent-harness](./agent-harness.md) — the zot / Colibri split and autospawn model +- [glasspane](./glasspane.md) — the state machine that consumes these events diff --git a/docs/wiki/agent-harness.md b/docs/wiki/agent-harness.md index 16ebd0b..0d882f4 100644 --- a/docs/wiki/agent-harness.md +++ b/docs/wiki/agent-harness.md @@ -38,7 +38,7 @@ Where it lives: - autospawn binary-aware argv (`zot → rpc`, pi → `--mode json`): `crates/colibri-daemon/src/socket.rs` (`default_agent_args`, `autospawn_agent_if_configured`) -- wire format (verified against real zot): [AGENT-EVENTS-REFERENCE](../AGENT-EVENTS-REFERENCE.md) +- wire format (verified against real zot): [agent-events-reference](./agent-events-reference.md) - end-to-end proof: `crates/colibri-daemon/tests/zot_rpc_smoke.rs` (`#[ignore]`, `ZOT_BIN`-gated) diff --git a/docs/wiki/cost-model.md b/docs/wiki/cost-model.md index 426dbca..4d0a39c 100644 --- a/docs/wiki/cost-model.md +++ b/docs/wiki/cost-model.md @@ -27,7 +27,7 @@ you an upper bound but not the real cost. DeepSeek's API sometimes re-caches and sometimes doesn't — the probe measures what actually happened. The discount is too large (10×) to leave unmeasured. -→ [`HEADROOM-SIDECAR.md`](../HEADROOM-SIDECAR.md), +→ [headroom-sidecar](./headroom-sidecar.md), [`COLIBRI-TOKENOMICS-TRIFECTA.md`](../COLIBRI-TOKENOMICS-TRIFECTA.md), [`crates/colibri-deepseek/src/lib.rs`](../../crates/colibri-deepseek/src/lib.rs) @@ -66,7 +66,7 @@ needs to continue. Compaction preserves the semantic content at lower token cost The headroom sidecar is optional (off by default); without it, the fallback is simple truncation. -→ [`HEADROOM-SIDECAR.md`](../HEADROOM-SIDECAR.md), +→ [headroom-sidecar](./headroom-sidecar.md), [`crates/colibri-daemon/src/session.rs`](../../crates/colibri-daemon/src/session.rs) ### Cache-hit probe (DeepSeek-specific) diff --git a/docs/HEADROOM-SIDECAR.md b/docs/wiki/headroom-sidecar.md similarity index 90% rename from docs/HEADROOM-SIDECAR.md rename to docs/wiki/headroom-sidecar.md index 61a919b..272dad2 100644 --- a/docs/HEADROOM-SIDECAR.md +++ b/docs/wiki/headroom-sidecar.md @@ -1,4 +1,6 @@ -# Headroom sidecar for Colibri +# Headroom sidecar + +← [index](./index.md) Colibri can optionally ask a local `headroom-ai` sidecar to compress tool results before they are rendered through the session read path. @@ -67,3 +69,8 @@ Current daemon timeout: 5 seconds per sidecar request. FreeBSD: ONNX/ORT-backed extras need local packaging; use a known-good Python environment and validate `scripts/headroom-sidecar.py` directly before enabling the daemon flag. + +## See also + +- [cost-model](./cost-model.md) — cost discipline and when to use Headroom +- [operator-cli](./operator-cli.md) — status JSON reports headroom connection state diff --git a/docs/wiki/index.md b/docs/wiki/index.md index 41941e9..4358e83 100644 --- a/docs/wiki/index.md +++ b/docs/wiki/index.md @@ -43,22 +43,25 @@ warning. ## Pages -| Page | What it covers | -| ------------------------------------------- | --------------------------------------------------------------------------------------------- | -| [agent-harness](./agent-harness.md) | The zot (agent) + Colibri (control plane) split; autospawn + RPC driver | -| [cost-model](./cost-model.md) | Byte-stable prefixes, cache-hit metering, auto-escalation, T14 compaction | -| [glasspane](./glasspane.md) | Agent state machine, JSONL streaming, AgentRuntime taxonomy, snapshot API | -| [jail-confinement](./jail-confinement.md) | Persistent vs ephemeral jails, priv-mode policy, reuse of spawner confinement for MCP servers | -| [mother-hive](./mother-hive.md) | Mother MCP architecture — forced-command SSH, single-home-in-colibri, peer auth, key-on-seed | -| [naming-decisions](./naming-decisions.md) | Ledger of harness-neutral / architecture renames — shipped and in-flight | -| [task-board](./task-board.md) | Capability match scoring, cron scheduling, intake drain, SQLite backing | -| [quality-gates](./quality-gates.md) | `ci-checks.sh` as the pre-merge gate; why drift reached `main` before | -| [contracts](./contracts.md) | Stable JSON schemas (run-manifest, runtime-inventory, provider-smoke), golden tests | -| [store-schema](./store-schema.md) | SQLite coordination schema and migration discipline | -| [external-mcp](./external-mcp.md) | MCP bridge for editors + external stdio MCP host; read/write/external-call gates | -| [operator-cli](./operator-cli.md) | The `colibri` CLI as a thin typed Unix-socket client over the daemon API | -| [tui](./tui.md) | Terminal dashboard client (colibri-tui) vs the colibri-glasspane state machine | -| [runtime-inventory](./runtime-inventory.md) | Host runtime inventory + watchdog status reader; additive, read-only integrations | -| [skills-catalog](./skills-catalog.md) | Read-only runtime consumer for reviewed Clawdie-AI skill artifacts | -| [vault-provision](./vault-provision.md) | Vaultwarden-driven env-file provisioning into jails after agent spawn | -| [deployment](./deployment.md) | Host installer (clawdie): ZFS layout, rc.d/systemd service, dry-run safety | +| Page | What it covers | +| ----------------------------------------------------- | --------------------------------------------------------------------------------------------- | +| [agent-harness](./agent-harness.md) | The zot (agent) + Colibri (control plane) split; autospawn + RPC driver | +| [agent-events-reference](./agent-events-reference.md) | Per-harness zot event reference, Glasspane mappings, and verified transcript fields | +| [cost-model](./cost-model.md) | Byte-stable prefixes, cache-hit metering, auto-escalation, T14 compaction | +| [glasspane](./glasspane.md) | Agent state machine, JSONL streaming, AgentRuntime taxonomy, snapshot API | +| [headroom-sidecar](./headroom-sidecar.md) | Optional tool-result compression sidecar and its Unix-socket protocol | +| [jail-confinement](./jail-confinement.md) | Persistent vs ephemeral jails, priv-mode policy, reuse of spawner confinement for MCP servers | +| [mother-hive](./mother-hive.md) | Mother MCP architecture — forced-command SSH, single-home-in-colibri, peer auth, key-on-seed | +| [naming-decisions](./naming-decisions.md) | Ledger of harness-neutral / architecture renames — shipped and in-flight | +| [layered-soul](./layered-soul.md) | How Colibri consumes the layered-soul reviewed-context repo today vs planned | +| [task-board](./task-board.md) | Capability match scoring, cron scheduling, intake drain, SQLite backing | +| [quality-gates](./quality-gates.md) | `ci-checks.sh` as the pre-merge gate; why drift reached `main` before | +| [contracts](./contracts.md) | Stable JSON schemas (run-manifest, runtime-inventory, provider-smoke), golden tests | +| [store-schema](./store-schema.md) | SQLite coordination schema and migration discipline | +| [external-mcp](./external-mcp.md) | MCP bridge for editors + external stdio MCP host; read/write/external-call gates | +| [operator-cli](./operator-cli.md) | The `colibri` CLI as a thin typed Unix-socket client over the daemon API | +| [tui](./tui.md) | Terminal dashboard client (colibri-tui) vs the colibri-glasspane state machine | +| [runtime-inventory](./runtime-inventory.md) | Host runtime inventory + watchdog status reader; additive, read-only integrations | +| [skills-catalog](./skills-catalog.md) | Read-only runtime consumer for reviewed Clawdie-AI skill artifacts | +| [vault-provision](./vault-provision.md) | Vaultwarden-driven env-file provisioning into jails after agent spawn | +| [deployment](./deployment.md) | Host installer (clawdie): ZFS layout, rc.d/systemd service, dry-run safety | diff --git a/docs/INTEGRATION-LAYERED-SOUL.md b/docs/wiki/layered-soul.md similarity index 59% rename from docs/INTEGRATION-LAYERED-SOUL.md rename to docs/wiki/layered-soul.md index fa99ef1..08f5557 100644 --- a/docs/INTEGRATION-LAYERED-SOUL.md +++ b/docs/wiki/layered-soul.md @@ -1,4 +1,6 @@ -# Integration: Layered Soul → Colibri +# Layered Soul integration + +← [index](./index.md) [clawdie/layered-soul](https://code.smilepowered.org/clawdie/layered-soul) is the portable, harness-agnostic source of durable identity + reviewed context. This doc @@ -11,23 +13,23 @@ Reviewed **skills** import into Colibri's existing `skills` catalog: scripts/import-layered-soul.sh -It reads each `skills/**/SKILL.md` (frontmatter `name` / `description`; category +It reads each skills SKILL.md file (frontmatter `name` / `description`; category `soul`) and `INSERT OR IGNORE`s a row into the `skills` table. `references/` and `templates/` under a skill are supporting material, not separate skills. Same table as `clawdie-iso/scripts/import-clawdie-skills.sh`; idempotent, safe to re-run. ## What's deferred (planned, not built) -The `adapters/colibri.md` in layered-soul names a "Layered Memory Fabric" with -three stores — `system_skills`, `system_brain`, `system_ops`. As of 13.jun.2026 +The the Colibri adapter in layered-soul names a "Layered Memory Fabric" with +three stores — `system_skills`, `system_brain`, `system_ops`. As of 2026-06-13 only a single flat `skills` table exists; the rest is **design only** (`docs/COLIBRI-SKILLS-PLAN.md`), so the importer intentionally does not target it. -| Layered Soul source | Target (planned) | Status | -| ---------------------------- | ---------------- | ---------------------------------------------------------- | -| `skills/**/SKILL.md` | `system_skills` | imported into the flat `skills` table today | -| `memories/curated/**/*.md` | `system_brain` | NOT imported — no store yet (the importer reports a count) | -| converted task/job manifests | `system_ops` | NOT implemented | +| Layered Soul source | Target (planned) | Status | +| ------------------------------- | ---------------- | ---------------------------------------------------------- | +| skills SKILL.md files | `system_skills` | imported into the flat `skills` table today | +| memories/curated markdown files | `system_brain` | NOT imported — no store yet (the importer reports a count) | +| converted task/job manifests | `system_ops` | NOT implemented | ## Direction (one-way) @@ -38,6 +40,11 @@ then re-import — runtime copies are ephemeral consumers. ## Closing the gap (future work) 1. Implement `system_brain` per `COLIBRI-SKILLS-PLAN.md`, then extend the importer - to load `memories/curated/`. + to load curated memories. 2. Migrate the flat `skills` table to the planned `system_skills` schema. 3. Define and import `system_ops` task/job manifests. + +## See also + +- [skills-catalog](./skills-catalog.md) — Colibri's read-only runtime skill consumer +- [store-schema](./store-schema.md) — planned `system_skills` / `system_brain` tables