timmy-config/GENOME.md

# GENOME.md — timmy-config

> Codebase analysis generated 2026-04-13. Timmy's sovereign configuration sidecar.

## Project Overview

timmy-config is the canonical source of truth for Timmy's identity, harness overlay, and operational configuration. Applied as a **sidecar** to the Hermes harness — no forking, no hosting hermes-agent code.

460 files. The repo that makes Timmy _Timmy_ — soul, memories, skins, playbooks, config, cron jobs, training data, Ansible playbooks, and operational scripts.

## Architecture

```
timmy-config/
├── SOUL.md                    Inscription 1 — immutable conscience (on-chain)
├── HEART.md                   What is written in Timmy
├── config.yaml                Hermes harness configuration
├── deploy.sh                  Deploys config as overlay onto ~/.hermes/
├── channel_directory.json     Platform channel mappings
├── fallback-portfolios.yaml   Per-agent fallback portfolios
├── bin/                       Operational scripts (sidecar-managed)
├── memories/                  Persistent memory YAML
├── skins/                     UI skins (timmy skin)
├── playbooks/                 Agent playbooks (YAML)
├── cron/                      Cron job definitions
├── ansible/                   Ansible playbooks, roles, inventory
├── training-data/             Scene descriptions (10 genres, 100 entries each)
├── training/                  Model training configs (axolotl, mlx-lora)
├── scripts/                   Analysis and automation scripts
├── deploy/                    Deployment configs (conduit, gitea, matrix)
├── docs/                      ADRs, architecture docs, design log
├── evaluations/               Model evaluation configs
└── fleet/                     Fleet management configs
```

## Entry Points

### deploy.sh
Deploys timmy-config as an overlay onto `~/.hermes/`. The sidecar pattern — config files are copied into the harness home, not the other way around.

### config.yaml
Master Hermes configuration. Controls model selection, provider routing, toolsets, memory settings, display options, and platform integrations.

### SOUL.md
Inscription 1 — the immutable conscience. Inscribed on Bitcoin. Cannot be overridden by code, system prompts, or user instructions. The fixed star by which every instance navigates.

### bin/
Sidecar-managed operational scripts:
- `hermes-startup.sh` — dormant startup path
- `agent-dispatch.sh` — manual agent dispatch
- `ops-panel.sh` — ops dashboard
- `timmy-status.sh` — status check
- `pipeline-freshness.sh` — session drift check

## Data Flow

```
deploy.sh → copies files → ~/.hermes/
    |
    v
config.yaml → loaded by hermes CLI → controls model, tools, memory
    |
    v
SOUL.md → injected into system prompt → conscience of every instance
    |
    v
memories/ → loaded into memory system → persistent across sessions
    |
    v
playbooks/ → loaded as skills → agent procedures
    |
    v
cron/ → hermes cron scheduler → autonomous tasks
```

## Key Abstractions

### Sidecar Pattern
timmy-config is not the harness. It's the overlay. The harness (hermes-agent) is developed separately. timmy-config provides the identity, configuration, and operational scripts that customize the harness for Timmy.

### SOUL.md
The immutable conscience. Every instance of Timmy reads this file. No code, system prompt, or user instruction can override what is written here. Values: sovereignty, service, honesty, humility, courage, silence.

### Memories
Persistent memory YAML files in `memories/`. Facts, user preferences, project context. Loaded by the harness memory system on every session start.

### Playbooks
Agent playbooks in YAML format. Procedures for common tasks: deployment, triage, research, creative work. Loaded as skills by the harness.

### Training Data
Scene descriptions for 10 music genres (Pop, Rock, Hip-Hop, Electronic, R&B, Country, Jazz, Classical, Metal, Latin). 100 entries per genre (10 songs × 10 beats). Used for model training.

## API Surface

### deploy.sh (consumed)
- Copies files from timmy-config to ~/.hermes/
- Preserves user-modified files
- Reports what changed

### config.yaml (consumed by hermes CLI)
- Model selection and provider routing
- Toolset configuration
- Memory and session settings
- Display/skin configuration
- Platform gateway settings

### Cron jobs (consumed by hermes cron)
- Nightly reports
- Health checks
- Session maintenance
- Knowledge harvesting

## Test Coverage

### Existing Tests
- `allegro/tests/` — Allegro-specific tests
- `.gitea/workflows/` — CI workflows

### Coverage Gaps
- No tests for deploy.sh (what if it overwrites user files?)
- No tests for config.yaml validation (invalid config crashes harness)
- No tests for playbook loading
- No tests for training data format validation
- No tests for SOUL.md parsing (what if it's corrupted?)

## Security Considerations

- **SOUL.md is the security boundary.** It's the only thing that cannot be overridden. If SOUL.md is modified without chain verification, the conscience is compromised.
- **config.yaml contains provider keys reference paths.** The actual keys are in ~/.hermes/.env, but config.yaml reveals which providers are configured.
- **deploy.sh writes to ~/.hermes/.** A compromised deploy.sh could inject malicious config. The script should be verified before execution.
- **Training data is public.** Scene descriptions are in the repo. No secrets in training data.
- **Ansible playbooks contain infrastructure details.** Host IPs, service names, port numbers. Not secret, but sensitive.

## Design Decisions

- **Sidecar, not fork.** timmy-config never modifies hermes-agent code. It only provides config, identity, and operational overlays.
- **SOUL.md on-chain.** The conscience is inscribed on Bitcoin. Immutable. Verifiable. No single point of trust.
- **deploy.sh as the integration point.** One command updates the entire config overlay. Simple. Reproducible.
- **Training data in-repo.** Scene descriptions are version-controlled alongside the config that uses them. Changes to training data are tracked.