layered-soul/docs/MIGRATION-MANIFEST.md

# Clawdie → Hermes Migration Manifest

**Purpose**: classify the old Clawdie runtime's 104 `.env` keys into a migration
roadmap. Keys are grouped by what Hermes can use now vs. what maps to future
capability. This is a **redacted inventory** — key names only, no values.

**Source**: ZFS snapshot `autosnap_2026-04-22` + May 2026 backup — identical (104/104 match).

## Bucket 1: Boot now (Hermes supports natively)

Keys that map directly to Hermes-standard env vars. Copy these into
`/home/clawdie/.hermes/.env` with Hermes naming.

| Old key | Hermes key | Status |
|---------|-----------|--------|
| TELEGRAM_BOT_TOKEN | TELEGRAM_BOT_TOKEN (same) | ready |
| TELEGRAM_MAIN_CHAT_ID | TELEGRAM_HOME_CHANNEL | rename |
| OPENROUTER_API_KEY | OPENROUTER_API_KEY (same) | ready |
| OPENAI_API_KEY | OPENAI_API_KEY (same) | ready |
| ZAI_API_KEY | ZAI_API_KEY (same) | ready |

## Bucket 2: Useful soon (Hermes can consume with minor work)

Keys Hermes understands but needs mapping, or keys for integrations that are
the next capability targets.

| Key | Hermes support | Action |
|-----|---------------|--------|
| ANTHROPIC_API_KEY | native (add provider) | add to Hermes config |
| DEEPSEEK_API_KEY | native (add provider) | add to Hermes config |
| GOOGLE_API_KEY | native (add provider) | add to Hermes config |
| GEMINI_API_KEY | native (add provider) | add to Hermes config |
| GROQ_API_KEY | native (add provider) | add to Hermes config |
| GLM_API_KEY | native (add provider) | add to Hermes config |
| CHAT_MODEL | Hermes model config | map to provider config |
| CHAT_BASE_URL | Hermes provider endpoint | map to provider config |
| LLM_PROVIDER | Hermes provider config | map |
| TELEGRAM_ADMIN_IDS | Hermes admin config | add |
| TELEGRAM_OPS_CHAT_ID | Hermes ops channel | add |

## Bucket 3: Old Clawdie-specific (capability roadmap)

These keys represent features Hermes doesn't yet support. Each one is a
migration card — when Hermes gains the capability, the key becomes actionable.

| Key pattern | Old feature | Future Hermes capability |
|------------|-------------|------------------------|
| EMBED_* | Embedding pipeline | Hermes embeddings / RAG |
| STRIPE_* | Payment integration | (if needed) |
| SUPABASE_* | Database backend | Colibri store already handles this |
| STRAPI_* | Headless CMS (OSA website) | Future: Hermes CMS plugin |
| FORGEJO_* | Git integration | Hermes already has git tooling; use FORGEJO_API_TOKEN |
| PI_* | Pi agent runner | Colibri handles agent spawn now |
| LOCAL_LLM_* | Local inference | llama.cpp integration (planned) |
| RUNNER_* | Build/CI runner | Colibri task board + agent spawn |
| HEARTBEAT_* | Health monitoring | Colibri glasspane |
| CONTROLPLANE_* | Control plane | Colibri daemon |
| WARDEN_* | Container management | Docker (Linux) / Bastille jails (FreeBSD) |
| JAIL_* | FreeBSD jail config | Colibri spawner + jail confinement |
| DB_* | Database connections | Colibri store (SQLite) |
| DISCORD_* | Discord gateway | Hermes has Discord support |
| SLACK_* | Slack gateway | Hermes has Slack support |
| WHATSAPP_* | WhatsApp gateway | Hermes has WhatsApp support |

## Rules

- **Never bulk-copy all 104 keys into Hermes.** Hermes .env is smaller and standard.
- **Use this manifest as the migration backlog.** When Hermes gains a feature,
  check here for the old Clawdie config shape.
- **Keep the original backup file** at `/home/clawdie/.env.clawdie-ai.backup-02.maj.2026-2022`
  as the sealed source of truth.
- **Update this manifest** when keys move between buckets.

## Status

| Bucket | Count (estimated) | State |
|--------|-------------------|-------|
| Boot now | ~5 | being deployed on OSA |
| Useful soon | ~10 | pending Hermes config mapping |
| Old Clawdie-specific | ~89 | roadmap — no action yet |

## Verification notes (Claude — domedog review lane)

Reviewed against the recovered env and standing fleet rules. Two corrections to
apply before building `/home/clawdie/.hermes/.env`:

1. **Separate "present" from "supported."** Bucket membership currently mixes two
   axes: *Hermes can support this key* vs. *this key actually exists in the
   recovered 104-key env*. Codex confirms several Bucket-2 keys (`ANTHROPIC_API_KEY`,
   `DEEPSEEK_API_KEY`, `GOOGLE_API_KEY`, `GEMINI_API_KEY`, `TELEGRAM_ADMIN_IDS`,
   `TELEGRAM_OPS_CHAT_ID`) were **absent** from the recovered env — so they are
   roadmap items (Bucket-3 behavior), not migration inputs. **You can't copy a key
   that isn't there.** Treat the recovered env as the migration input set; treat the
   bucket table as the capability roadmap. Only Bucket-1 keys confirmed present
   migrate now.
2. **Telegram token reuse is a collision hazard, not a copy.** Bucket 1 marks
   `TELEGRAM_BOT_TOKEN → (same) → ready`, but Mevy already runs a Telegram bot on
   `osa`, and the handoff rule is *do not reuse any existing token* (one token per
   service). Two consumers polling `getUpdates` on one token steal each other's
   updates. **Before any reuse:** confirm the old Clawdie bot is dead, or mint a
   fresh bot for hermes-osa. Do not assume "same" is safe.

**First `.env` build (Telegram-off validation):** provider keys only
(`OPENROUTER_API_KEY`, `OPENAI_API_KEY`, `ZAI_API_KEY`) — defer all Telegram keys
until after a clean CLI proof. Durable home for these values is **Vaultwarden**
(`vault.smilepowered.org`); the backup file stays sealed as the migration source.
The built `.env` is local to `osa` and must never flow through any repo.

_Review lane: Claude (domedog) verifies migration/handoff steps against standing
rules and confirms Codex's osa results when reported — closing the loop through
verification. See [`HOST-MATRIX.md`](HOST-MATRIX.md) §1._