fix: generate GENOME.md for timmy-academy (#678)

Full codebase genome analysis of timmy-academy:
- Mermaid architecture diagram
- Entry points and data flow
- Key abstractions (AuditedCharacter, Commands, World)
- API surface, test coverage, security

Closes #678

GENOME-timmy-academy.md

@@ -0,0 +1,238 @@
+# GENOME.md — timmy-academy
+
+*Auto-generated by Codebase Genome Pipeline. 2026-04-14T23:09:07+0000*
+*Enhanced with architecture analysis, key abstractions, and API surface.*
+
+## Quick Facts
+
+| Metric | Value |
+|--------|-------|
+| Source files | 48 |
+| Test files | 1 |
+| Config files | 1 |
+| Total lines | 5,353 |
+| Last commit | 395c9f7 Merge PR 'Add @who command' (#7) into master (2026-04-13) |
+| Branch | master |
+| Test coverage | 0% (35 untested modules) |
+
+## What This Is
+
+Timmy Academy is an Evennia-based MUD (Multi-User Dungeon) — a persistent text world where AI agents convene, train, and practice crisis response. It runs on Bezalel VPS (167.99.126.228) with telnet on port 4000 and web client on port 4001.
+
+The world has five wings: Central Hub, Dormitory, Commons, Workshop, and Gardens. Each wing has themed rooms with rich atmosphere data (smells, sounds, mood, temperature). Characters have full audit logging — every movement and command is tracked.
+
+## Architecture
+
+```mermaid
+graph TB
+    subgraph "Connections"
+        TELNET[Telnet :4000]
+        WEB[Web Client :4001]
+    end
+
+    subgraph "Evennia Core"
+        SERVER[Evennia Server]
+        PORTAL[Evennia Portal]
+    end
+
+    subgraph "Typeclasses"
+        CHAR[Character]
+        AUDIT[AuditedCharacter]
+        ROOM[Room]
+        EXIT[Exit]
+        OBJ[Object]
+    end
+
+    subgraph "Commands"
+        CMD_EXAM[CmdExamine]
+        CMD_ROOMS[CmdRooms]
+        CMD_STATUS[CmdStatus]
+        CMD_MAP[CmdMap]
+        CMD_ACADEMY[CmdAcademy]
+        CMD_SMELL[CmdSmell]
+        CMD_LISTEN[CmdListen]
+        CMD_WHO[CmdWho]
+    end
+
+    subgraph "World - Wings"
+        HUB[Central Hub]
+        DORM[Dormitory Wing]
+        COMMONS[Commons Wing]
+        WORKSHOP[Workshop Wing]
+        GARDENS[Gardens Wing]
+    end
+
+    subgraph "Hermes Bridge"
+        HERMES_CFG[hermes-agent/config.yaml]
+        BRIDGE[Agent Bridge]
+    end
+
+    TELNET --> SERVER
+    WEB --> PORTAL
+    PORTAL --> SERVER
+    SERVER --> CHAR
+    SERVER --> AUDIT
+    SERVER --> ROOM
+    SERVER --> EXIT
+    CHAR --> CMD_EXAM
+    CHAR --> CMD_STATUS
+    CHAR --> CMD_WHO
+    ROOM --> HUB
+    ROOM --> DORM
+    ROOM --> COMMONS
+    ROOM --> WORKSHOP
+    ROOM --> GARDENS
+    HERMES_CFG --> BRIDGE
+    BRIDGE --> SERVER
+```
+
+## Entry Points
+
+| File | Purpose |
+|------|---------|
+| `server/conf/settings.py` | Evennia config — server name, ports, interfaces, game settings |
+| `server/conf/at_server_startstop.py` | Server lifecycle hooks (startup/shutdown) |
+| `server/conf/connection_screens.py` | Login/connection screen text |
+| `commands/default_cmdsets.py` | Registers all custom commands with Evennia |
+| `world/rebuild_world.py` | Rebuilds all rooms from source |
+| `world/build_academy.ev` | Evennia batch script for initial world setup |
+
+## Data Flow
+
+```
+Player connects (telnet/web)
+  -> Evennia Portal accepts connection
+  -> Server authenticates (Account typeclass)
+  -> Player puppets a Character
+  -> Character enters world (Room typeclass)
+  -> Commands processed through Command typeclass
+  -> AuditedCharacter logs every action
+  -> World responds with rich text + atmosphere data
+```
+
+## Key Abstractions
+
+### Typeclasses (the world model)
+
+| Class | File | Purpose |
+|-------|------|---------|
+| `Character` | `typeclasses/characters.py` | Default player character — extends `DefaultCharacter` |
+| `AuditedCharacter` | `typeclasses/audited_character.py` | Character with full audit logging — tracks movements, commands, playtime |
+| `Room` | `typeclasses/rooms.py` | Default room container |
+| `Exit` | `typeclasses/exits.py` | Connections between rooms |
+| `Object` | `typeclasses/objects.py` | Base object with `ObjectParent` mixin |
+| `Account` | `typeclasses/accounts.py` | Player account (login identity) |
+| `Channel` | `typeclasses/channels.py` | In-game communication channels |
+| `Script` | `typeclasses/scripts.py` | Background/timed processes |
+
+### AuditedCharacter — the flagship typeclass
+
+The `AuditedCharacter` is the most important abstraction. It wraps every player action in logging:
+
+- `at_pre_move()` — logs departure from current room
+- `at_post_move()` — records arrival with timestamp and coordinates
+- `at_pre_cmd()` — increments command counter, logs command + args
+- `at_pre_puppet()` — starts session timer
+- `at_post_unpuppet()` — calculates session duration, updates total playtime
+- `get_audit_summary()` — returns JSON summary of all tracked metrics
+
+Audit trail keeps last 1000 movements in `db.location_history`. Sensitive commands (password) are excluded from logging.
+
+### Commands (the player interface)
+
+| Command | Aliases | Purpose |
+|---------|---------|---------|
+| `examine` | `ex`, `exam` | Inspect room or object — shows description, atmosphere, objects, contents |
+| `rooms` | — | List all rooms with wing color coding |
+| `@status` | `status` | Show agent status: location, wing, mood, online players, uptime |
+| `@map` | `map` | ASCII map of current wing |
+| `@academy` | `academy` | Full academy overview with room counts |
+| `smell` | `sniff` | Perceive room through atmosphere scent data |
+| `listen` | `hear` | Perceive room through atmosphere sound data |
+| `@who` | `who` | Show connected players with locations and idle time |
+
+### World Structure (5 wings, 21+ rooms)
+
+**Central Hub (LIMBO)** — Nexus connecting all wings. North=Dormitory, South=Workshop, East=Commons, West=Gardens.
+
+**Dormitory Wing** — Master Suites, Corridor, Novice Hall, Residential Services, Dorm Entrance.
+
+**Commons Wing** — Grand Commons Hall (main gathering, 60ft ceilings, marble columns), Hearthside Dining, Entertainment Gallery, Scholar's Corner, Upper Balcony.
+
+**Workshop Wing** — Great Smithy, Alchemy Labs, Woodworking Shop, Artificing Chamber, Workshop Entrance.
+
+**Gardens Wing** — Enchanted Grove, Herb Gardens, Greenhouse, Sacred Grove, Gardens Entrance.
+
+Each room has rich `db.atmosphere` data: mood, lighting, sounds, smells, temperature.
+
+## API Surface
+
+### Web API
+
+- `web/api/__init__.py` — Evennia REST API (Django REST Framework)
+- `web/urls.py` — URL routing for web interface
+- `web/admin/` — Django admin interface
+- `web/website/` — Web frontend
+
+### Telnet
+
+- Standard MUD protocol on port 4000
+- Supports MCCP (compression), MSDP (data), GMCP (protocol)
+
+### Hermes Bridge
+
+- `hermes-agent/config.yaml` — Configuration for AI agent connection
+- Allows Hermes agents to connect as characters and interact with the world
+
+## Dependencies
+
+No `requirements.txt` or `pyproject.toml` found. Dependencies come from Evennia:
+
+- **evennia** — MUD framework (Django-based)
+- **django** — Web framework (via Evennia)
+- **twisted** — Async networking (via Evennia)
+
+## Test Coverage Analysis
+
+| Metric | Value |
+|--------|-------|
+| Source modules | 35 |
+| Test modules | 1 |
+| Estimated coverage | 0% |
+| Untested modules | 35 |
+
+Only one test file exists: `tests/stress_test.py`. All 35 source modules are untested.
+
+### Critical Untested Paths
+
+1. **AuditedCharacter** — audit logging is the primary value-add. No tests verify movement tracking, command counting, or playtime calculation.
+2. **Commands** — no tests for any of the 8 commands. The `@map` wing detection, `@who` session tracking, and atmosphere-based commands (`smell`, `listen`) are all untested.
+3. **World rebuild** — `rebuild_world.py` and `fix_world.py` can destroy and recreate the entire world. No tests ensure they produce valid output.
+4. **Typeclass hooks** — `at_pre_move`, `at_post_move`, `at_pre_cmd` etc. are never tested in isolation.
+
+## Security Considerations
+
+- ⚠️ Uses `eval()`/`exec()` — Evennia's inlinefuncs module uses eval for dynamic command evaluation. Risk level: inherent to MUD framework.
+- ⚠️ References secrets/passwords — `settings.py` references `secret_settings.py` for sensitive config. Ensure this file is not committed.
+- ⚠️ Telnet on 0.0.0.0 — server accepts connections from any IP. Consider firewall rules.
+- ⚠️ Web client on 0.0.0.0 — same exposure as telnet. Ensure authentication is enforced.
+- ⚠️ Agent bridge (`hermes-agent/config.yaml`) — verify credentials are not hardcoded.
+
+## Configuration Files
+
+- `server/conf/settings.py` — Main Evennia settings (server name, ports, typeclass paths)
+- `hermes-agent/config.yaml` — Hermes agent bridge configuration
+- `world/build_academy.ev` — Evennia batch build script
+- `world/batch_cmds.ev` — Batch command definitions
+
+## What's Missing
+
+1. **Tests** — 0% coverage is a critical gap. Priority: AuditedCharacter hooks, command func() methods, world rebuild integrity.
+2. **CI/CD** — No automated testing pipeline. No GitHub Actions or Gitea workflows.
+3. **Documentation** — `world/BUILDER_GUIDE.md` exists but no developer onboarding docs.
+4. **Monitoring** — No health checks, no metrics export, no alerting on server crashes.
+5. **Backup** — No automated database backup for the Evennia SQLite/PostgreSQL database.
+
+---
+
+*Generated by Codebase Genome Pipeline. Review and update manually.*