# 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, but must not quote or copy their private contents.
- Use `scripts/layered_soul.py validate .` before committing structural changes.
- 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: **never retry a quota-blocked task without checking whether it was
already solved.** 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=100.66.193.10, domedog=100.103.255.41, osa=100.72.229.63
- Commit identity: `hello@clawdie.si` for all project commits

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

| Agent      | Host    | Harness                 | OS         | Isolation          | Role                      |
| ---------- | ------- | ----------------------- | ---------- | ------------------ | ------------------------- |
| Hermes     | debby   | Hermes Agent (upstream) | Debian 13  | Docker             | Orchestrator, soul backup |
| Zot        | debby   | Zot RPC                 | Debian 13  | Docker             | Coding, media workflows   |
| Claude     | domedog | Claude Code             | Linux      | Docker             | Verification, review      |
| Codex      | osa     | Codex CLI               | FreeBSD 15 | Bastille jail      | ISO builds, validation    |
| hermes-osa | osa     | Hermes Agent (FreeBSD)  | FreeBSD 15 | host service first | Native FreeBSD Hermes     |

**Survivability**: Linux/Docker and FreeBSD/jails are complementary safeguards.
A vulnerability that kills one platform cannot kill the other. 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
```