layered-soul/AGENTS.md

# Layered Soul Agent Rules

- Do not commit secrets, API keys, auth tokens, browser profiles, or raw credential files.
- Do not import raw sessions into another harness by default.
- Curate memories before adding them under `memories/curated/`.
- Keep Hermes-native runtime configuration in `hermes-soul`; this repository is the cross-harness contract.
- Public examples may reference private source repositories by URL/name. Keep private contents in their own repositories.
- 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`.
- When adapting for Pi/Codex/Claude Code/Zot: render the prompt bundle (`render-prompt`) and inject as task-scoped context. Durable findings flow back through reviewed commits.

## Quota exhaustion policy (cross-harness)

When any agent hits an API quota limit (429 / rate-limit):

1. **Calculate reset time** with `scripts/quota_reset_eta.py` — parses provider error
   messages and converts to UTC/CEST correctly. Handles Beijing time (Z.AI/DeepSeek),
   UTC (OpenRouter), and PDT (Anthropic/OpenAI).

2. **Check if task already resolved** with `scripts/task_dedup_before_retry.py` —
   queries Colibri task board, checks git activity since block time. Skips retry
   if another agent or operator already completed the work.

3. **Schedule retry** — create a one-shot cron at reset time + 60s buffer.
   Never retry immediately (429 means quota, not transient).

4. **Report** — log to glasspane: provider, reset time, task status, action taken.

Rule: **always verify task resolution** (via `scripts/task_dedup_before_retry.py`) before retrying a quota-blocked task. Tokens are money. A solved task retried is waste.

## Active infrastructure

- Forgejo: code.smilepowered.org (SSH port 2222)
- Vaultwarden: vault.smilepowered.org (SSL)
- Tailscale: debby=${DEBBY_TS_IP}, domedog=${DOMEDOG_TS_IP}, osa=${OSA_TS_IP}
- Commit identity: `hello@clawdie.si` for all project commits

### Topology & channel masking (use placeholder variables only in commits)

Real Tailscale IPs and Telegram bot handles **stay out of committed files** — reference them by variable name. They
were leaked once; not again. Committed docs reference variable names only
(`${OSA_TS_IP}`, `${HERMES_BOT}`, …). To resolve them:

- **IPs** are live-discoverable any time with `tailscale status`.
- **Handles + IPs** are stored in `fleet.env` (gitignored). Copy `fleet.env.example` →
  `fleet.env` and fill from `tailscale status` / Vaultwarden, then `source fleet.env`.

When editing docs: if you're about to paste a `100.x` IP or an `@…_bot` handle, stop and
use the placeholder instead.

## Agent matrix (5 agents across 3 hosts, 2 OS families)

| Agent      | Host    | Harness                 | OS         | Isolation          | Role                      |
| ---------- | ------- | ----------------------- | ---------- | ------------------ | ------------------------- |
| 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      | 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.
A vulnerability that kills one platform leaves the other intact, preserving fleet survivability. Agents can be
relocated across platforms in minutes via layered-soul identity injection.

## Private sources

- `hermes-soul`: git@code.smilepowered.org:clawdie/hermes-soul.git (private, operator access only)
- `hermes-bsd`: git@code.smilepowered.org:clawdie/hermes-bsd.git (public, MIT-licensed FreeBSD patches)
- `clawdie-ai`: git@code.smilepowered.org:clawdie/clawdie-ai.git (private)
- `clawdie-iso`: git@code.smilepowered.org:clawdie/clawdie-iso.git (private)

## Quick reference

```sh
# Validate
python3 scripts/layered_soul.py validate .

# See what's available from hermes-soul
python3 scripts/layered_soul.py plan-private-source \
  examples/private-sources/hermes-soul.example.json \
  --source-root ~/hermes-soul

# Render for a harness
python3 scripts/layered_soul.py render-prompt . --output /tmp/soul-prompt.md
```