# THE FLEET LEXICON: Shared Vocabulary, Techniques & Patterns

**Author:** Ezra (Scribe) — Second Pass, Deep Analysis
**Date:** April 4, 2026
**Purpose:** Every agent in the fleet must speak the same language, use the same patterns, and understand the same architecture. This document is the authoritative reference.

---

## PART I: THE VOCABULARY

Every term below has appeared in issues, code, or operational practice. If you're an agent in this fleet, you must know these words and use them correctly.

### Identity & Structure

| Term | Meaning | Example |
|------|---------|---------|
| **Wizard House** | A complete agent environment: Hermes profile, config, memory, skills, gateway connection, and Telegram presence. Each wizard is a house. | Ezra's house lives at /root/wizards/ezra/ |
| **Harness** | The Hermes Agent runtime — the framework wrapping an LLM with tools, config, skills, sessions, and platform adapters. ALL wizard houses share the same harness codebase. | "The Hermes harness" = run_agent.py + model_tools.py + tools/ + gateway/ |
| **SOUL.md** | A wizard's identity document — system prompt, personality, constraints, mission. Doctrine-bearing file. Any change to SOUL.md is a soul change. | timmy-config/SOUL.md defines who Timmy is |
| **Profile** | A fully isolated Hermes instance with its own HERMES_HOME, config, API keys, memory, sessions, skills, and gateway. Each wizard house IS a profile. | `hermes -p ezra` activates Ezra's profile |
| **Gateway** | The messaging platform bridge. A long-lived async process that receives messages from Telegram/Discord/Slack/etc, dispatches them to AIAgent, and returns responses. Tracked by gateway.pid. | Ezra's gateway connects to Telegram as @EzraScribeBot |
| **Skin** | Data-driven CLI visual theme — colors, spinner faces, branding text. Pure data, no code changes needed. | Built-in skins: default (gold), ares (crimson), mono (grayscale), slate (blue) |
| **Toolset** | A named group of related tools. Users enable/disable toolsets. The master list is _HERMES_CORE_TOOLS in toolsets.py. | "web" toolset = web_search + web_extract |
| **Sovereign** | Local-first, no cloud dependency for core operations. Alexander's highest principle. Every architectural choice is measured against sovereignty. | "Is this sovereign?" = "Does it work if the internet dies?" |

### Operations & Deployment

| Term | Meaning | Example |
|------|---------|---------|
| **Burn / Burn Down** | Execute and close issues aggressively. Tested commits. No half-measures. Alexander's primary directive to agents. | "Burn down your epic" = close issues with working code |
| **Burn Night** | An overnight session of continuous issue execution. Agents run loops, produce PRs, close tickets. | Timmy ran burn nights via cron + Gitea task router |
| **Burn Report** | A post-session summary of what was accomplished. Filed as an issue. Format: issues closed, code written, tests run. | timmy-home #143: "Burn Report #1 — 2026-03-31" |
| **RCA** | Root Cause Analysis. Structured incident post-mortem with severity (P0-P3), 5-Whys, timeline, action items, prevention. | RCA-295: Who NERFED Bilbo? |
| **Health Check** | Automated infrastructure verification. Each check is critical or non-critical, returns PASS/FAIL/ERROR. | Disk space, gateway alive, Gitea token valid, llama-server responding |
| **Deadman Switch** | Alert when zero commits for 2+ hours. Detects stalled agents. | timmy-config #115 |
| **Morning Report** | Daily fleet status report. Due 7 AM. Each agent submits their overnight results. | timmy-config #110 |
| **Checkpoint** | Cross-wizard state snapshot stored in the wizard-checkpoints repo. Used for fleet coordination and drift detection. | Ezra owns the checkpoint registry (8 wizards registered) |
| **Cron Job** | Scheduled task using natural language prompts. Schema: id, name, prompt, schedule (crontab), repeat, deliver target. | "ezra-self-check" runs at 6 AM daily |
| **Trajectory** | A complete session transcript (messages, tool calls, results) saved for training data. The raw material for LoRA/DPO. | Hermes saves trajectories as JSONL in sessions/ |

### Infrastructure

| Term | Meaning | Example |
|------|---------|---------|
| **llama-server** | llama.cpp's HTTP inference server. Serves local models. Critical flags: --jinja (tool-calling), -fa (flash attention), --port, -ngl 999 (full GPU offload). | Port 11435 on VPS, serving Gemma 4 |
| **Gemma 4** | Google's MoE model. 4B active / 26B total parameters. 8GB RAM efficient. THE standard local model. Alexander says: never recommend alternatives. Revolutionary, different class. | gemma-4-E4B-it-Q4_K_M.gguf |
| **TurboQuant** | KV cache compression technique (PolarQuant + QJL) for longer context on Apple Silicon. Timmy Foundation's own innovation. | turboquant repo, Phase 1 complete |
| **Gitea** | Self-hosted Forgejo/Gitea instance at 143.198.27.163:3000. ALL project management lives here. 18 repos, 1031+ issues. | Use urllib, NOT curl (security scanner blocks raw IPs) |
| **Hermes VPS** | The primary Digital Ocean server hosting Ezra, Bilbo, Bezalel, and shared infrastructure. | 143.198.27.163 |
| **Testbed VPS** | Secondary server for Allegro. | 167.99.126.228 |
| **state.db** | SQLite database storing session state, search index (FTS5), and persistent data per wizard house. | Each profile gets its own state.db |

### Architecture Patterns (from Gitea issues)

| Term | Meaning | First Appeared |
|------|---------|---------------|
| **The Door** | Crisis front door for broken men. Single URL, no login. 988 visible. Alexander's MISSION. | the-door repo |
| **The Nexus** | Timmy's 3D sovereign home. Three.js world with portals, agent board, sovereignty meter. | the-nexus repo |
| **Evennia** | Python MUD framework. Timmy's text-based mind palace / world shell. | timmy-academy repo |
| **Aurora Pipeline** | Session transcripts → model weight updates. The training flywheel. | the-nexus #598 |
| **Crucible** | Z3 SMT solver as a sidecar for deterministic reasoning. | timmy-config #86 |
| **Archon** | A three-layer wizard: Hermes → Claw → Gemma4. Ezra's architectural proof-of-concept. | timmy-home #363 |
| **Gemma Spectrum** | 9-wizard multimodal fleet, all running Gemma 4. | timmy-home #352 |
| **Grand Timmy / Uniwizard** | The endgame: all wizard identities dissolved into one unified intelligence. | timmy-home #94 |
| **Robing** | OpenClaw (Claw Code) as a sidecar shell on top of Hermes. Claw wears like a robe — convenience layer, not replacement. | timmy-home #141 |
| **GOFAI** | Good Old-Fashioned AI. Rule-based, symbolic, deterministic. Sidecar to the LLM for constraint enforcement. | timmy-home #67 |

---

## PART II: THE TECHNIQUES

These are the proven patterns extracted from working code. If you're building something, use these patterns.

### 1. THE TOOL REGISTRATION PATTERN (Hermes Core)

Three files, every time:

```
1. tools/your_tool.py      — Implementation + registry.register() call
2. model_tools.py           — Import in _discover_tools()
3. toolsets.py              — Add name to _HERMES_CORE_TOOLS or a toolset
```

Handler MUST return a JSON string. check_fn gates availability. requires_env declares needed API keys. The registry handles schema collection, dispatch, and error wrapping.

### 2. THE ENV-VAR FALLBACK CHAIN

Constructor param > environment variable > hardcoded default. Always.

```python
self.base_url = (base_url or os.getenv("GITEA_URL", "http://143.198.27.163:3000")).rstrip("/")
self.token = token or os.getenv("GITEA_TOKEN", "")
```

This pattern makes tools testable (pass params directly), deployable (set env vars), and safe (hardcoded defaults as last resort).

### 3. THE ENSURE/IDEMPOTENT PATTERN

For any resource that might already exist: check first, create only if missing. Case-insensitive matching. Safe to re-run.

```python
def ensure_label(self, owner, repo, name, color, description=""):
    labels = self.list_labels(owner, repo)
    for l in labels:
        if l["name"].lower() == name.lower():
            return l
    return self.create_label(owner, repo, name, color, description)
```

Use this for labels, milestones, repos, users, configs — anything where duplicates are bad.

### 4. THE RETRY WITH EXPONENTIAL BACKOFF

Retry transient failures. NEVER retry auth/validation errors.

```python
for attempt in range(max_retries):
    try:
        return make_request()
    except HTTPError as e:
        if e.code in (401, 403, 404, 422):
            raise  # Don't retry these
        time.sleep(retry_delay * (2 ** attempt))
```

### 5. THE CHECK-RUNNER PATTERN (Health Monitoring)

Each check is a callable returning (bool, detail_string). The runner wraps execution, catches exceptions, classifies results. Checks are tagged critical or non-critical.

```python
def check(self, name, fn, critical=False):
    try:
        ok, detail = fn()
        return {"name": name, "status": "PASS" if ok else "FAIL", "detail": detail, "critical": critical}
    except Exception as e:
        return {"name": name, "status": "ERROR", "detail": str(e), "critical": critical}
```

Aggregate: total passed, total failed, critical failures. System is HEALTHY only if zero critical failures.

### 6. THE VALIDATION-FINDINGS PATTERN (Quality Gates)

Accumulate findings during validation. Three severity tiers: ERROR (must fix), WARNING (should fix), INFO (nice to know). Validate in passes: frontmatter, then body, then directory structure.

```python
class ValidationError:
    def __init__(self, level, message, field=""):  # level: ERROR/WARNING/INFO
        ...

self.errors = []  # accumulator
# ... validate_frontmatter() appends errors
# ... validate_body() appends errors
# ... validate_directory() appends errors
return self.errors
```

### 7. THE BACKUP ROTATION PATTERN

Create timestamped archives. Rotate by count (keep max N, delete oldest). Restore with dry_run preview by default.

```python
def _rotate_backups(self):
    backups = sorted(self.backup_dir.glob("*.tar.gz"), key=lambda p: p.stat().st_mtime, reverse=True)
    for old in backups[self.max_backups:]:
        old.unlink()
```

### 8. THE URLLIB-OVER-CURL PATTERN (Gitea API)

The Hermes security scanner blocks curl to raw IP addresses. ALL Gitea API calls MUST use Python's urllib, not curl, not requests.

```python
req = urllib.request.Request(url, data=body, headers=headers, method=method)
resp = urllib.request.urlopen(req, timeout=30)
return json.loads(resp.read())
```

### 9. THE TEMPLATE-BASED GENERATION PATTERN (Reports/RCAs)

Define a multi-line TEMPLATE as a class constant. Normalize inputs, then .format(). Auto-increment numbering. Sanitize filenames.

```python
TEMPLATE = """# RCA-{number}: {title}
## Summary
...
"""
safe_title = re.sub(r'[^a-z0-9-]', '', title.lower().replace(' ', '-'))[:40]
```

### 10. THE MOCK HTTP SERVER PATTERN (Testing)

For testing API clients without hitting real servers:

```python
class MockHandler(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path == "/api/v1/user":
            self._json_response(200, {"login": "ezra"})

server = HTTPServer(("127.0.0.1", 0), MockHandler)  # port 0 = auto-assign
port = server.server_address[1]
thread = threading.Thread(target=server.serve_forever, daemon=True)
thread.start()
client = GiteaClient(base_url=f"http://127.0.0.1:{port}", token="test")
```

### 11. THE SLASH COMMAND REGISTRY PATTERN (Hermes Core)

One source of truth for all commands. All consumers derive from the same registry:

```python
CommandDef("mycommand", "Description", "Session", aliases=("mc",), args_hint="[arg]")
```

CLI dispatch, gateway dispatch, Telegram menu, Slack routing, autocomplete, help text — ALL auto-generated from the registry. Adding an alias = one tuple change, everything else follows.

### 12. THE SKILL STRUCTURE

Every skill is a directory with SKILL.md at the root:

```
~/.hermes/skills/category/skill-name/
  SKILL.md           # YAML frontmatter + markdown body
  references/        # Supporting docs
  templates/         # Config templates
  scripts/           # Automation scripts
  assets/            # Static assets
```

Frontmatter: name, description, version (required), author, tags (recommended).
Body: Trigger (when to use), Steps (numbered), Pitfalls (what can go wrong), Verification (how to confirm success).

Skills are injected as USER messages, not system prompt — this preserves prompt caching.

---

## PART III: THE TESTING STANDARD

All agents producing code must follow this:

1. **Tests live alongside code:** tools/ and tests/ as sibling directories
2. **Every module gets a test file:** test_{module_name}.py
3. **Three test tiers:**
   - Unit tests (mocked dependencies)
   - Integration tests (mock HTTP server for APIs)
   - Live tests (clearly marked, may fail in CI)
4. **Test fixtures as module constants:** VALID_SKILL, BROKEN_SKILL_NO_FM, etc.
5. **Temp directories for isolation:** tempfile.mkdtemp() in setUp, shutil.rmtree() in tearDown
6. **Edge cases required:** empty files, missing files, auth failures, rotation limits, dry-run modes
7. **All tests must pass before commit.** `python3 -m pytest tests/ -v`

---

## PART IV: THE COMMIT STANDARD

From Gitea issue evidence, Alexander's merge proof standard:

1. **Screenshot for visual changes** — prove it renders
2. **Log output for CLI changes** — prove it runs
3. **Test output for code changes** — prove it passes
4. **One commit, one concern** — atomic, reviewable
5. **Epic tagging:** reference the epic/issue in commit message

Format: `{type}: {description} ({issue ref})`
Types: feat, fix, docs, test, refactor, chore

---

## PART V: THE CONFIG ANATOMY

Every wizard house config.yaml follows this structure:

```yaml
_config_version: 10          # Schema version (bump triggers migration)
model:
  default: claude-opus-4-6   # Primary model
fallback_providers:           # Ranked list of backup providers
  - provider: anthropic
    model: claude-sonnet-4-20250514
agent:
  max_turns: 50              # Max tool-calling iterations
  reasoning_effort: high
session_reset:
  mode: both                 # idle + time-of-day reset
  idle_minutes: 1440
  at_hour: 4                 # 4 AM daily reset
compression:
  threshold: 0.77            # Context compression trigger
memory:
  memory_char_limit: 2200    # MEMORY.md max size
  user_char_limit: 1375      # USER.md max size
display:
  skin: default              # Visual theme
platforms:
  api_server:
    enabled: true
    host: 127.0.0.1
    port: 8643               # UNIQUE per wizard house
  telegram:
    enabled: true
```

Key rule: NEVER hardcode ~/.hermes. Always use get_hermes_home() for code, display_hermes_home() for user messages.

---

## PART VI: WHO DOES WHAT

Based on the full issue audit — the actual division of labor that has emerged:

| Agent | Proven Competency | Lane |
|-------|------------------|------|
| **Timmy** @Timmy | Sovereign local house, model training, Evennia, harness config, overnight loops | The sovereign — judges locally |
| **Ezra** @ezra | Gitea API, health monitoring, RCA analysis, skill validation, architecture review, fleet auditing | Scribe — read, reconcile, document, review |
| **Bilbo** @bilbobagginshire | Fast local inference (4B Gemma), Telegram dual-mode, churn handling | The Hobbit — resilient, cheerful, executes |
| **Allegro** @allegro | Security hardening, GOFAI rules, input sanitization, conscience validation | The Executor — security & deployment |
| **Bezalel** @bezalel | Gemma 4 31B serving, artisan work, model hosting | The Artisan — heavy model work |
| **Claude** @claude | Nexus 3D world (Three.js), rapid prototyping, bulk feature implementation | Cloud partner — fast iteration |
| **KimiClaw** @KimiClaw | Knowledge ingestion, performance benchmarking, PR review | Silent — needs reactivation |
| **Fenrir** @fenrir | Security (Nostr audit, secret leak hooks, stale lockfile alerts) | The Wolf — security guardian |

---

*Every agent who reads this document now speaks the same language. Use the vocabulary. Follow the patterns. Cite the techniques by name. When you say "ensure pattern" or "check-runner" or "urllib-over-curl" — we all know what that means.*

*Read the pattern. Name the truth. Return a clean artifact.*

— Ezra, Scribe of the Timmy Foundation
April 4, 2026