feat: GENOME.md for evennia-local-world (#677)

Full codebase analysis:
- Architecture diagram (Mermaid)
- Entry points and data flow
- Key abstractions (6 typeclasses, commands, scripts)
- API surface
- Test coverage gaps (8 critical paths identified)
- Security considerations (6 risks)
- Integration points (Timmy AI, Hermes, Federation)

Closes #677

evennia/timmy_world/GENOME.md

@@ -0,0 +1,242 @@
+# GENOME.md: evennia-local-world
+
+> Codebase Genome — Auto-generated analysis of the timmy_world Evennia project.
+
+## Project Overview
+
+**Name:** timmy_world
+**Framework:** Evennia 6.0 (MUD/MUSH engine)
+**Purpose:** Tower MUD world with spatial memory. A persistent text-based world where AI agents and humans interact through rooms, objects, and commands.
+**Language:** Python 3.11
+**Lines of Code:** ~40 files, ~2,500 lines
+
+This is a custom Evennia game world built for the Timmy Foundation fleet. It provides a text-based multiplayer environment where AI agents (Timmy instances) can operate as NPCs, interact with players, and maintain spatial memory of the world state.
+
+## Architecture
+
+```
+timmy_world/
++-- server/
+|   +-- conf/
+|       +-- settings.py          # Server configuration
+|       +-- at_initial_setup.py  # First-run setup hook
+|       +-- at_server_startstop.py
+|       +-- inputfuncs.py        # Client input handlers
+|       +-- lockfuncs.py         # Permission lock functions
+|       +-- cmdparser.py         # Command parsing overrides
+|       +-- connection_screens.py # Login/creation screens
+|       +-- serversession.py     # Session management
+|       +-- web_plugins.py       # Web client plugins
++-- typeclasses/
+|   +-- characters.py            # Player/NPC characters
+|   +-- rooms.py                 # Room containers
+|   +-- objects.py               # Items and world objects (218 lines, key module)
+|   +-- exits.py                 # Room connectors
+|   +-- accounts.py              # Player accounts (149 lines)
+|   +-- channels.py              # Communication channels
+|   +-- scripts.py               # Persistent background scripts (104 lines)
++-- commands/
+|   +-- command.py               # Base command class (188 lines)
+|   +-- default_cmdsets.py       # Command set definitions
++-- world/
+|   +-- prototypes.py            # Object spawn templates
+|   +-- help_entries.py          # File-based help system
++-- web/
+    +-- urls.py                  # Web URL routing
+    +-- api/                     # REST API endpoints
+    +-- webclient/               # Web client interface
+    +-- website/                 # Web site views
+    +-- admin/                   # Django admin
+```
+
+## Mermaid Architecture Diagram
+
+```mermaid
+graph TB
+    subgraph "Entry Points"
+        Telnet[Telnet:4000]
+        Web[Web Client:4001]
+        API[REST API]
+    end
+
+    subgraph "Evennia Core"
+        Portal[Portal - Connection Handler]
+        Server[Server - Game Logic]
+    end
+
+    subgraph "timmy_world"
+        TC[Typeclasses]
+        CMD[Commands]
+        WORLD[World]
+        CONF[Config]
+    end
+
+    subgraph "Typeclasses"
+        Char[Character]
+        Room[Room]
+        Obj[Object]
+        Exit[Exit]
+        Acct[Account]
+        Script[Script]
+    end
+
+    subgraph "External"
+        Timmy[Timmy AI Agent]
+        Humans[Human Players]
+    end
+
+    Telnet --> Portal
+    Web --> Portal
+    API --> Server
+    Portal --> Server
+    Server --> TC
+    Server --> CMD
+    Server --> WORLD
+    Server --> CONF
+
+    Timmy -->|Telnet/Script| Portal
+    Humans -->|Telnet/Web| Portal
+
+    Char --> Room
+    Room --> Exit
+    Exit --> Room
+    Obj --> Room
+    Acct --> Char
+    Script --> Room
+```
+
+## Entry Points
+
+| Entry Point | Port | Protocol | Purpose |
+|-------------|------|----------|---------|
+| Telnet | 4000 | MUD protocol | Primary game connection |
+| Web Client | 4001 | HTTP/WebSocket | Browser-based play |
+| REST API | 4001 | HTTP | External integrations |
+
+**Server Start:**
+```bash
+evennia migrate
+evennia start
+```
+
+**AI Agent Connection (Timmy):**
+AI agents connect via Telnet on port 4000, authenticating as scripted accounts. The `Script` typeclass handles persistent NPC behavior.
+
+## Data Flow
+
+```
+Player/AI Input
+    |
+    v
+Portal (connection handling, Telnet/Web)
+    |
+    v
+Server (game logic, session management)
+    |
+    v
+Command Parser (cmdparser.py)
+    |
+    v
+Command Execution (commands/command.py)
+    |
+    v
+Typeclass Methods (characters.py, objects.py, etc.)
+    |
+    v
+Database (Django ORM)
+    |
+    v
+Output back through Portal to Player/AI
+```
+
+## Key Abstractions
+
+### Object (typeclasses/objects.py) — 218 lines
+The core world entity. Everything in the game world inherits from Object:
+- **ObjectParent**: Mixin class for shared behavior across all object types
+- **Object**: Concrete game items, furniture, tools, NPCs without scripts
+
+Key methods: `at_init()`, `at_object_creation()`, `return_appearance()`, `at_desc()`
+
+### Character (typeclasses/characters.py)
+Puppetable entities. What players and AI agents control.
+- Inherits from Object and DefaultCharacter
+- Has location (Room), can hold objects, can execute commands
+
+### Room (typeclasses/rooms.py)
+Spatial containers. No location of their own.
+- Contains Characters, Objects, and Exits
+- `return_appearance()` generates room descriptions
+
+### Exit (typeclasses/exits.py)
+Connectors between Rooms. Always has a `destination` property.
+- Generates a command named after the exit
+- Moving through an exit = executing that command
+
+### Account (typeclasses/accounts.py) — 149 lines
+The persistent player identity. Survives across sessions.
+- Can puppet one Character at a time
+- Handles channels, tells, who list
+- Guest class for anonymous access
+
+### Script (typeclasses/scripts.py) — 104 lines
+Persistent background processes. No in-game existence.
+- Timers, periodic events, NPC AI loops
+- Key for AI agent integration
+
+### Command (commands/command.py) — 188 lines
+User input handlers. MUX-style command parsing.
+- `at_pre_cmd()` → `parse()` → `func()` → `at_post_cmd()`
+- Supports switches (`/flag`), left/right sides (`lhs = rhs`)
+
+## API Surface
+
+| Endpoint | Type | Purpose |
+|----------|------|---------|
+| Telnet:4000 | MUD Protocol | Game connection |
+| /api/ | REST | Web API (Evennia default) |
+| /webclient/ | WebSocket | Browser game client |
+| /admin/ | HTTP | Django admin panel |
+
+## Test Coverage Gaps
+
+**Current State:** No custom tests found.
+
+**Missing Tests:**
+1. **Object lifecycle**: `at_object_creation`, `at_init`, `delete`
+2. **Room navigation**: Exit creation, movement between rooms
+3. **Command parsing**: Switch handling, lhs/rhs splitting
+4. **Account authentication**: Login flow, guest creation
+5. **Script persistence**: Start, stop, timer accuracy
+6. **Lock function evaluation**: Permission checks
+7. **AI agent integration**: Telnet connection, command execution as NPC
+8. **Spatial memory**: Room state tracking, object location queries
+
+**Recommended:** Add `tests/` directory with pytest-compatible Evennia tests.
+
+## Security Considerations
+
+1. **Telnet is unencrypted** — All MUD traffic is plaintext. Consider SSH tunneling for production or limiting to local connections.
+2. **Lock functions** — Custom lockfuncs.py defines permission checks. Review for bypass vulnerabilities.
+3. **Web API** — Ensure Django admin is restricted to trusted IPs.
+4. **Guest accounts** — Guest class exists. Limit permissions to prevent abuse.
+5. **Script execution** — Scripts run server-side Python. Arbitrary script creation is a security risk if not locked down.
+6. **AI agent access** — Timmy connects as a regular account. Ensure agent accounts have appropriate permission limits.
+
+## Dependencies
+
+- **Evennia 6.0** — MUD/MUSH framework (Django + Twisted)
+- **Python 3.11+**
+- **Django** (bundled with Evennia)
+- **Twisted** (bundled with Evennia)
+
+## Integration Points
+
+- **Timmy AI Agent** — Connects via Telnet, interacts as NPC
+- **Hermes** — Orchestrates Timmy instances that interact with the world
+- **Spatial Memory** — Room/object state tracked for AI context
+- **Federation** — Multiple Evennia worlds can be bridged (see evennia-federation skill)
+
+---
+
+*Generated: Codebase Genome for evennia-local-world (timmy_home #677)*