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, 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.
• 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=${DEBBY_TS_IP}, domedog=${DOMEDOG_TS_IP}, osa=${OSA_TS_IP}
• Commit identity: hello@clawdie.si for all project commits

Topology & channel masking (do not commit real values)

Real Tailscale IPs and Telegram bot handles never go into committed files — 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	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

# 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