layered-soul/memories/curated/project-structure.md

# Clawdie Project Structure

Clawdie is a dual-OS agent runtime designed for survivability — Linux+Docker for reach, FreeBSD+jails (Bastille) for resilience.

## Core repos

| Repo | Language | Purpose |
|------|---------|---------|
| `colibri` | Rust (12+ crates) | Cross-platform control plane: daemon, task board, skills catalog, store, MCP bridge |
| `clawdie-ai` | Docs/config | Agent runtime, control plane channels, handoff docs, session archives |
| `clawdie-iso` | Shell/BSD | FreeBSD ISO builder, firstboot wizard, installer, ZFS layout |
| `hermes-bsd` | Python | MIT-licensed FreeBSD Hermes patches (public) |
| `hermes-soul` | Backup | Hermes-native runtime backup (private) |
| `layered-soul` | Identity | Cross-harness portable identity (public) |

## Dual-OS strategy

| Platform | Container | Strengths | Safeguards against |
|----------|-----------|-----------|--------------------|
| Linux (debby, domedog) | Docker | Instant ecosystem access, any tool/language | FreeBSD/jails catch Linux-specific exploits (glibc, systemd, kernel) |
| FreeBSD (OSA) | Bastille jails | ZFS integrity, different TCP stack, jail isolation | Linux/Docker catches FreeBSD-specific bugs |

If Docker goes down, OSA keeps running. If a FreeBSD jail escape emerges, the Linux side keeps the collective running.

## Key binaries (colibri workspace)

- `colibri-daemon` — always-on socket server, session/agent lifecycle, jail spawner
- `colibri` — CLI client + probe binaries
- `colibri-glasspane-tui` — ratatui live dashboard
- `clawdie` — host installer/deployer (ZFS + service)

## Development rules

- Linux agents (debby, domedog): build + test + clippy, push to Forgejo
- FreeBSD agent (osa): validate on real FreeBSD 15, run `cargo test` on bare metal
- Rust Tier-2 target: `x86_64-unknown-freebsd`, TLS via rustls (no openssl-sys)
- Zig 0.15.2 at `~/.local/bin/zig` (required for herdr builds)

## Docker infrastructure

Docker 29.5+ on Linux hosts. Containers for Hermes gateway, Zot RPC, Vaultwarden, Forgejo. Docker Desktop socket at `~/.docker/desktop/docker.sock` or system socket at `/var/run/docker.sock`. Probe with `verify_facts_probe.py --jails-containers`.

## Herdr

Terminal workspace manager at `~/ai/herdr` (v0.6.2, local patches). Binary at `~/ai/herdr/target/release/herdr`.