clawdie/layered-soul
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request 'docs: promote operator conventions + refresh stale facts' (#11) from add-operator-conventions into main

Browse source 
Reviewed-on: #11
This commit is contained in:
clawdie 2026-06-21 13:04:07 +02:00
commit b97b55a6e9
5 changed files with 29 additions and 7 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
AGENTS.md
View file

@ -7,6 +7,8 @@
- Public examples may reference private source repositories by URL/name, but must not quote or copy their private contents.
- Use `scripts/layered_soul.py validate .` before committing structural changes.
- Pull before editing hot shared files (`AGENTS.md`, `docs/HOST-MATRIX.md`, `docs/CAPABILITY-ROUTING.md`); keep history linear and re-check after rebases.
- Verify on the forge, not local status: "pushed/landed" is confirmed against Forgejo (API or a fresh `git fetch --prune` of origin), never a clean `git status`. An empty working tree only means it matches local HEAD — durability holds only once commits reach origin. `git status -sb` shows "ahead N" when commits are unpushed.
- CI is dormant by choice: no Forgejo Actions runner is registered, so checks sit `pending` — merges ride local-green gates (format/clippy/test/drift checks), and `pending` CI is expected, not a blocker. domedog stays Docker-free; don't propose a Docker runner on it.
- When adapting for Colibri: reviewed skills map to `system_skills`, curated memory maps to `system_brain`, converted task manifests map to `system_ops`.
- When adapting for Hermes (upstream, Linux): load as profile context (SOUL.md + USER.md + IDENTITY.md). Hermes-native config and cron stay in `hermes-soul`.
- When adapting for hermes-osa (FreeBSD-native Hermes, clean-room MIT via `hermes-bsd`): same profile-context load; FreeBSD-specific gaps (voice, clipboard) are known and tracked in `docs/CLAWDIE-HERMES-FREEBSD-INTEGRATION.md`.
@ -59,7 +61,7 @@ use the placeholder instead.
| hermes-osa | osa | Hermes Agent (FreeBSD) | FreeBSD 15 | host service first | **Orchestrator + board host (always-on VPS)** |
| Hermes | debby | Hermes Agent (upstream) | Debian 13 | Docker | Secondary agent + soul backup (intermittent laptop) |
| Zot | debby | Zot RPC | Debian 13 | Docker | Coding, media workflows |
| Claude | domedog | Claude Code | Linux | Docker | Verification, review |
| Claude | domedog | Claude Code | Linux | host (no Docker) | Verification, review |
| Codex | osa | Codex CLI | FreeBSD 15 | Bastille jail | ISO builds, validation |
**Survivability**: Linux/Docker and FreeBSD/jails are complementary safeguards.

20
USER.md
View file

@ -30,10 +30,28 @@ TTS voice preference: sl-SI-RokNeural (Slovenian)
- Documents systemic risks, not just fix symptoms
- Proactive cleanup — /tmp is for transient data, projects go in ~/Blender/
## Conventions & voice (what Sam prefers)
- **Dates (user-facing): European `DD.mon.YYYY`** with a lowercase 3-letter month
(`21.jun.2026`) — in CHANGELOGs, READMEs, docs, handoff `Date:` lines, logs, UI.
Reserve ISO `YYYY-MM-DD` for places where lexical sortability matters (filenames,
snapshot names). Existing ISO dates are pre-existing drift — normalize only if asked.
- **Positive instruction framing.** In code comments, banners, and docs, state the
correct way and stop — drop `do NOT` / `never` anti-pattern callouts. A usage banner
says `Run as: sh script.sh`, not also `NOT as: python3 script.sh`.
- **Plain language over jargon.** Branch/PR names a non-technical operator can read
(`all-checks-green`, not `chore/rustfmt-clean`); avoid `fmt`/`lint`/`CI` in names.
Say "detection"/"discovery", not "sniffing". Commit *bodies* can still be precise.
- **Lean, current docs.** When a decision/design ships as working code, slim its doc to
a short "how it works now" and point at the real files (code is source of truth); flip
`Proposed` → `Accepted — implemented`, drop migration/to-do sections. No history
pollution: describe what a thing does now, not what it replaced ("no backlog history
pollution please").
## Projects
- **Clawdie**: FreeBSD-based edge computing and agent runtime
- **Colibri**: Cross-platform Rust control plane core (12 crates)
- **Colibri**: Cross-platform Rust control plane core (13 crates, MIT, v0.11.0)
- **Herdr**: Terminal workspace manager
- **layered-soul**: This repository — portable agent identity

2
docs/HOST-MATRIX.md
View file

@ -36,7 +36,7 @@ on any host fills in its own row. Source of truth for facts is the probe — not
| ----------------- | ------- | --------------------- | ---------------------------- | ------------------------------------------------------------------------- | --------------------------- | -------------------------------------- |
| Hermes | debby | Debian 13 / Docker | Hermes Agent (upstream) | Secondary agent + soul backup (intermittent laptop) | ${HERMES_BOT} | LIVE (intermittent) |
| Zot | debby | Debian 13 / Docker | Zot RPC | Coding, media workflows | ${ZOT_BOT} | LIVE |
| Claude | domedog | Ubuntu 24.04 / Docker | Claude Code | Verification, review | — (CLI) | LIVE |
| Claude | domedog | Ubuntu 24.04 / host (no Docker) | Claude Code | Verification, review | — (CLI) | LIVE |
| **Mevy** | osa | FreeBSD 15 / host | Hermes Agent (upstream, CLI) | **Consolidated into hermes-osa** | ${HERMES_OSA_BOT} (OSA-bot) | **LIVE — under hermes-osa** |
| **hermes-osa** | osa | FreeBSD 15 / host | Hermes Agent (FreeBSD fork) | **Orchestrator + board host (always-on VPS): chat + gateway** | ${HERMES_OSA_BOT} (OSA-bot) | **LIVE — chat + Telegram** |
| Codex | osa | FreeBSD 15 / jail | Codex CLI | ISO builds, validation | — (CLI) | LIVE |

5
memories/curated/forgejo-infrastructure.md
View file

@ -14,9 +14,10 @@ Primary code host: **code.smilepowered.org** (self-hosted Forgejo, SSL via Let's
| -------------- | ----------------------------------- | ------------------------------------------------ |
| `clawdie-ai` | private | Agent runtime, control plane, channels |
| `clawdie-iso` | private | FreeBSD ISO builder, firstboot wizard |
| `colibri` | private (public mirror on Codeberg) | Rust control plane core |
| `colibri` | private (public mirror on Codeberg) | Rust control plane core — MIT, v0.11.0 |
| `hermes-bsd` | public | MIT-licensed FreeBSD Hermes patches |
| `hermes-soul` | private | Hermes runtime backup (sessions, config, skills) |
| `layered-soul` | public template | Cross-harness identity (this repo) |
| `layered-soul` | public template | Cross-harness identity (this repo) — MIT |
## Conventions

5
memories/curated/project-structure.md
View file

@ -6,7 +6,7 @@ Clawdie is a dual-OS agent runtime designed for survivability — Linux+Docker f
| Repo | Language | Purpose |
|------|---------|---------|
| `colibri` | Rust (12+ crates) | Cross-platform control plane: daemon, task board, skills catalog, store, MCP bridge |
| `colibri` | Rust (13 crates, MIT, v0.11.0) | Cross-platform control plane: daemon, task board, skills catalog, store, MCP bridge, vault (tenant onboarding) |
| `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) |
@ -34,11 +34,12 @@ If Docker goes down, OSA keeps running. If a FreeBSD jail escape emerges, the Li
- 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)
- `python3` is 3.11 across hosts (FreeBSD `PYTHON_DEFAULT`); 3.12 stays available as `python3.12`. FreeBSD pkg flavors are `py311-*`. See `docs/TOOLCHAIN.md`.
- 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`.
Docker lives on **debby** (29.5.3, daemon intermittent) — containers for Hermes gateway, Zot RPC. Vaultwarden + Forgejo run off-fleet on Vultr. **domedog is Docker-free by choice** (overhead not yet worth it); it runs the headless Linux media/compute lane on the host directly. osa (FreeBSD) uses Bastille jails, not Docker. Probe with `verify_facts_probe.py --jails-containers`.
## Herdr