feat: add Bezalel Evennia world scaffold (#536)

docs/BEZALEL_EVENNIA_WORLD.md

@@ -0,0 +1,81 @@
+# Bezalel Evennia World
+
+Issue: `timmy-home#536`
+
+This is the themed-room world plan and build scaffold for Bezalel, the forge-and-testbed wizard.
+
+## Rooms
+
+| Room | Description focus | Core connections |
+|------|-------------------|------------------|
+| Limbo | the threshold between houses | Gatehouse |
+| Gatehouse | guarded entry, travel runes, proof before trust | Limbo, Great Hall, The Portal Room |
+| Great Hall | three-house maps, reports, shared table | Gatehouse, The Library of Bezalel, The Observatory, The Workshop |
+| The Library of Bezalel | manuals, bridge schematics, technical memory | Great Hall |
+| The Observatory | long-range signals toward Mac, VPS, and the wider net | Great Hall |
+| The Workshop | forge + workbench, plans turned into working form | Great Hall, The Server Room, The Garden of Code |
+| The Server Room | humming racks, heartbeat of the house | The Workshop |
+| The Garden of Code | contemplative grove where ideas root before implementation | The Workshop |
+| The Portal Room | three shimmering doorways aimed at Mac, VPS, and the net | Gatehouse |
+
+## Characters
+
+| Character | Role | Starting room |
+|-----------|------|---------------|
+| Timmy | quiet builder and observer | Gatehouse |
+| Bezalel | forge-and-testbed wizard | The Workshop |
+| Marcus | old man with kind eyes, human warmth in the system | The Garden of Code |
+| Kimi | scholar of context and meaning | The Library of Bezalel |
+
+## Themed items
+
+At least one durable item is placed in every major room, including:
+- Threshold Ledger
+- Three-House Map
+- Bridge Schematics
+- Compiler Manuals
+- Tri-Axis Telescope
+- Forge Anvil
+- Bridge Workbench
+- Heartbeat Console
+- Server Racks
+- Code Orchard
+- Stone Bench
+- Mac/VPS/Net portal markers
+
+## Portal travel commands
+
+The Portal Room reserves three live command names:
+- `mac`
+- `vps`
+- `net`
+
+Current behavior in the build scaffold:
+- each command is created as a real Evennia exit command
+- each command preserves explicit target metadata (`Mac house`, `VPS house`, `Wider net`)
+- until cross-world transport is wired, each portal routes through `Limbo`, the inter-world threshold room
+
+This keeps the command surface real now while leaving honest room for later world-to-world linking.
+
+## Build script
+
+```bash
+python3 scripts/evennia/build_bezalel_world.py --plan
+```
+
+Inside an Evennia shell / runtime with the repo on `PYTHONPATH`, the same script can build the world idempotently:
+
+```bash
+python3 scripts/evennia/build_bezalel_world.py --password bezalel-world-dev
+```
+
+What it does:
+- creates or updates all 9 rooms
+- creates the exit graph
+- creates themed objects
+- creates or rehomes account-backed characters
+- creates the portal command exits with target metadata
+
+## Persistence note
+
+The scaffold is written to be idempotent: rerunning the builder updates descriptions, destinations, and locations rather than creating duplicate world entities. That is the repo-side prerequisite for persistence across Evennia restarts.

evennia_tools/bezalel_layout.py

@@ -0,0 +1,190 @@
+from collections import deque
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class RoomSpec:
+    key: str
+    desc: str
+
+
+@dataclass(frozen=True)
+class ExitSpec:
+    source: str
+    key: str
+    destination: str
+    aliases: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class ObjectSpec:
+    key: str
+    location: str
+    desc: str
+    aliases: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class CharacterSpec:
+    key: str
+    desc: str
+    starting_room: str
+
+
+@dataclass(frozen=True)
+class TravelCommandSpec:
+    key: str
+    aliases: tuple[str, ...]
+    target_world: str
+    fallback_room: str
+    desc: str
+
+
+ROOMS = (
+    RoomSpec(
+        "Limbo",
+        "The void between worlds. The air carries the pulse of three houses: Mac, VPS, and this one. "
+        "Everything begins here before it is given form.",
+    ),
+    RoomSpec(
+        "Gatehouse",
+        "A stone guard tower at the edge of Bezalel's world. The walls are carved with runes of travel, "
+        "proof, and return. Every arrival is weighed before it is trusted.",
+    ),
+    RoomSpec(
+        "Great Hall",
+        "A vast hall with a long working table. Maps of the three houses hang beside sketches, benchmarks, "
+        "and deployment notes. This is where the forge reports back to the house.",
+    ),
+    RoomSpec(
+        "The Library of Bezalel",
+        "Shelves of technical manuals, Evennia code, test logs, and bridge schematics rise to the ceiling. "
+        "This room holds plans waiting to be made real.",
+    ),
+    RoomSpec(
+        "The Observatory",
+        "A high chamber with telescopes pointing toward the Mac, the VPS, and the wider net. Screens glow with "
+        "status lights, latency traces, and long-range signals.",
+    ),
+    RoomSpec(
+        "The Workshop",
+        "A forge and workbench share the same heat. Scattered here are half-finished bridges, patched harnesses, "
+        "and tools laid out for proof before pride.",
+    ),
+    RoomSpec(
+        "The Server Room",
+        "Racks of humming servers line the walls. Fans push warm air through the chamber while status LEDs beat "
+        "like a mechanical heart. This is the pulse of Bezalel's house.",
+    ),
+    RoomSpec(
+        "The Garden of Code",
+        "A quiet garden where ideas are left long enough to grow roots. Code-shaped leaves flutter in patterned wind, "
+        "and a stone path invites patient thought.",
+    ),
+    RoomSpec(
+        "The Portal Room",
+        "Three shimmering doorways stand in a ring: one marked for the Mac house, one for the VPS, and one for the wider net. "
+        "The room hums like a bridge waiting for traffic.",
+    ),
+)
+
+EXITS = (
+    ExitSpec("Limbo", "gatehouse", "Gatehouse", ("gate", "tower")),
+    ExitSpec("Gatehouse", "limbo", "Limbo", ("void", "back")),
+    ExitSpec("Gatehouse", "greathall", "Great Hall", ("hall", "great hall")),
+    ExitSpec("Great Hall", "gatehouse", "Gatehouse", ("gate", "tower")),
+    ExitSpec("Great Hall", "library", "The Library of Bezalel", ("books", "study")),
+    ExitSpec("The Library of Bezalel", "hall", "Great Hall", ("great hall", "back")),
+    ExitSpec("Great Hall", "observatory", "The Observatory", ("telescope", "tower top")),
+    ExitSpec("The Observatory", "hall", "Great Hall", ("great hall", "back")),
+    ExitSpec("Great Hall", "workshop", "The Workshop", ("forge", "bench")),
+    ExitSpec("The Workshop", "hall", "Great Hall", ("great hall", "back")),
+    ExitSpec("The Workshop", "serverroom", "The Server Room", ("servers", "server room")),
+    ExitSpec("The Server Room", "workshop", "The Workshop", ("forge", "bench")),
+    ExitSpec("The Workshop", "garden", "The Garden of Code", ("garden of code", "grove")),
+    ExitSpec("The Garden of Code", "workshop", "The Workshop", ("forge", "bench")),
+    ExitSpec("Gatehouse", "portalroom", "The Portal Room", ("portal", "portals")),
+    ExitSpec("The Portal Room", "gatehouse", "Gatehouse", ("gate", "back")),
+)
+
+OBJECTS = (
+    ObjectSpec("Threshold Ledger", "Gatehouse", "A heavy ledger where arrivals, departures, and field notes are recorded before the work begins."),
+    ObjectSpec("Three-House Map", "Great Hall", "A long map showing Mac, VPS, and remote edges in one continuous line of work."),
+    ObjectSpec("Bridge Schematics", "The Library of Bezalel", "Rolled plans describing world bridges, Evennia layouts, and deployment paths."),
+    ObjectSpec("Compiler Manuals", "The Library of Bezalel", "Manuals annotated in the margins with warnings against cleverness without proof."),
+    ObjectSpec("Tri-Axis Telescope", "The Observatory", "A brass telescope assembly that can be turned toward the Mac, the VPS, or the open net."),
+    ObjectSpec("Forge Anvil", "The Workshop", "Scarred metal used for turning rough plans into testable form."),
+    ObjectSpec("Bridge Workbench", "The Workshop", "A wide bench covered in harness patches, relay notes, and half-soldered bridge parts."),
+    ObjectSpec("Heartbeat Console", "The Server Room", "A monitoring console showing service health, latency, and the steady hum of the house."),
+    ObjectSpec("Server Racks", "The Server Room", "Stacked machines that keep the world awake even when no one is watching."),
+    ObjectSpec("Code Orchard", "The Garden of Code", "Trees with code-shaped leaves. Some branches bear elegant abstractions; others hold broken prototypes."),
+    ObjectSpec("Stone Bench", "The Garden of Code", "A place to sit long enough for a hard implementation problem to become clear."),
+    ObjectSpec("Mac Portal", "The Portal Room", "A silver doorway whose frame vibrates with the local sovereign house.", ("mac arch",)),
+    ObjectSpec("VPS Portal", "The Portal Room", "A cobalt doorway tuned toward the testbed VPS house.", ("vps arch",)),
+    ObjectSpec("Net Portal", "The Portal Room", "A pale doorway pointed toward the wider net and every uncertain edge beyond it.", ("net arch", "network arch")),
+)
+
+CHARACTERS = (
+    CharacterSpec("Timmy", "The Builder's first creation. Quiet, observant, already measuring the room before he speaks.", "Gatehouse"),
+    CharacterSpec("Bezalel", "The forge-and-testbed wizard. Scarred hands, steady gaze, the habit of proving things before trusting them.", "The Workshop"),
+    CharacterSpec("Marcus", "An old man with kind eyes. He walks like someone who has already survived the night once.", "The Garden of Code"),
+    CharacterSpec("Kimi", "The deep scholar of context and meaning. He carries long memory like a lamp.", "The Library of Bezalel"),
+)
+
+PORTAL_COMMANDS = (
+    TravelCommandSpec(
+        "mac",
+        ("macbook", "local"),
+        "Mac house",
+        "Limbo",
+        "Align with the sovereign local house. Until live cross-world transport is wired, the command resolves into Limbo — the threshold between houses.",
+    ),
+    TravelCommandSpec(
+        "vps",
+        ("testbed", "house"),
+        "VPS house",
+        "Limbo",
+        "Step toward the forge VPS. For now the command lands in Limbo, preserving the inter-world threshold until real linking is live.",
+    ),
+    TravelCommandSpec(
+        "net",
+        ("network", "wider-net"),
+        "Wider net",
+        "Limbo",
+        "Face the open network. The command currently routes through Limbo so the direction exists before the final bridge does.",
+    ),
+)
+
+
+def room_keys() -> tuple[str, ...]:
+    return tuple(room.key for room in ROOMS)
+
+
+def character_keys() -> tuple[str, ...]:
+    return tuple(character.key for character in CHARACTERS)
+
+
+def portal_command_keys() -> tuple[str, ...]:
+    return tuple(command.key for command in PORTAL_COMMANDS)
+
+
+def grouped_exits() -> dict[str, tuple[ExitSpec, ...]]:
+    grouped: dict[str, list[ExitSpec]] = {}
+    for exit_spec in EXITS:
+        grouped.setdefault(exit_spec.source, []).append(exit_spec)
+    return {key: tuple(value) for key, value in grouped.items()}
+
+
+def reachable_rooms_from(start: str) -> set[str]:
+    seen: set[str] = set()
+    queue: deque[str] = deque([start])
+    exits_by_room = grouped_exits()
+    while queue:
+        current = queue.popleft()
+        if current in seen:
+            continue
+        seen.add(current)
+        for exit_spec in exits_by_room.get(current, ()): 
+            if exit_spec.destination not in seen:
+                queue.append(exit_spec.destination)
+    return seen

scripts/codebase-genome.py

@@ -1,219 +0,0 @@
-#!/usr/bin/env python3
-"""
-Codebase Genome — Test Suite Generator
-
-Scans a Python codebase, identifies uncovered functions/methods,
-and generates pytest test cases to fill coverage gaps.
-
-Usage:
-    python codebase-genome.py <target_dir> [--output tests/test_genome_generated.py]
-    python codebase-genome.py <target_dir> --dry-run
-    python codebase-genome.py <target_dir> --coverage
-"""
-
-import ast
-import os
-import sys
-import argparse
-import subprocess
-import json
-from pathlib import Path
-from typing import List, Dict, Any, Optional, Set
-from dataclasses import dataclass, field
-
-
-@dataclass
-class FunctionInfo:
-    name: str
-    module: str
-    file_path: str
-    line_number: int
-    is_method: bool = False
-    class_name: Optional[str] = None
-    args: List[str] = field(default_factory=list)
-    has_return: bool = False
-    raises: List[str] = field(default_factory=list)
-    docstring: Optional[str] = None
-    is_private: bool = False
-    is_test: bool = False
-
-
-class CodebaseScanner:
-    def __init__(self, target_dir: str):
-        self.target_dir = Path(target_dir).resolve()
-        self.functions: List[FunctionInfo] = []
-        self.modules: Dict[str, List[FunctionInfo]] = {}
-
-    def scan(self) -> List[FunctionInfo]:
-        for py_file in self.target_dir.rglob("*.py"):
-            if self._should_skip(py_file):
-                continue
-            try:
-                self._scan_file(py_file)
-            except SyntaxError:
-                print(f"Warning: Syntax error in {py_file}, skipping", file=sys.stderr)
-        return self.functions
-
-    def _should_skip(self, path: Path) -> bool:
-        skip_dirs = {"__pycache__", ".git", ".venv", "venv", "node_modules", ".tox"}
-        if set(path.parts) & skip_dirs:
-            return True
-        if path.name.startswith("test_") or path.name.endswith("_test.py"):
-            return True
-        if path.name in ("conftest.py", "setup.py"):
-            return True
-        return False
-
-    def _scan_file(self, file_path: Path):
-        content = file_path.read_text(encoding="utf-8", errors="replace")
-        tree = ast.parse(content)
-        module_name = self._get_module_name(file_path)
-
-        for node in ast.walk(tree):
-            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
-                func = self._extract(node, module_name, file_path)
-                if func and not func.is_test:
-                    self.functions.append(func)
-                    self.modules.setdefault(module_name, []).append(func)
-
-    def _get_module_name(self, file_path: Path) -> str:
-        rel = file_path.relative_to(self.target_dir)
-        parts = list(rel.parts)
-        if parts[-1] == "__init__.py":
-            parts = parts[:-1]
-        else:
-            parts[-1] = parts[-1].replace(".py", "")
-        return ".".join(parts)
-
-    def _extract(self, node, module_name: str, file_path: Path) -> Optional[FunctionInfo]:
-        if node.name.startswith("test_"):
-            return None
-
-        args = [a.arg for a in node.args.args if a.arg not in ("self", "cls")]
-        has_return = any(isinstance(n, ast.Return) and n.value for n in ast.walk(node))
-        raises = []
-        for n in ast.walk(node):
-            if isinstance(n, ast.Raise) and n.exc and isinstance(n.exc, ast.Call):
-                if isinstance(n.exc.func, ast.Name):
-                    raises.append(n.exc.func.id)
-
-        docstring = ast.get_docstring(node)
-        is_method = False
-        class_name = None
-        for parent in ast.walk(tree := ast.parse(open(file_path).read())):
-            for child in ast.iter_child_nodes(parent):
-                if child is node and isinstance(parent, ast.ClassDef):
-                    is_method = True
-                    class_name = parent.name
-
-        return FunctionInfo(
-            name=node.name, module=module_name, file_path=str(file_path),
-            line_number=node.lineno, is_method=is_method, class_name=class_name,
-            args=args, has_return=has_return, raises=raises, docstring=docstring,
-            is_private=node.name.startswith("_") and not node.name.startswith("__"),
-        )
-
-
-class TestGenerator:
-    HEADER = '''# AUTO-GENERATED by codebase-genome.py — review before committing
-
-import pytest
-from unittest.mock import patch, MagicMock
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
-
-'''
-
-    def generate(self, functions: List[FunctionInfo]) -> str:
-        parts = [self.HEADER]
-        modules: Dict[str, List[FunctionInfo]] = {}
-        for f in functions:
-            modules.setdefault(f.module, []).append(f)
-
-        for mod, funcs in sorted(modules.items()):
-            parts.append(f"# ═══ {mod} ═══\n")
-            imp = mod.replace("-", "_")
-            parts.append(f"try:\n    from {imp} import *\nexcept ImportError:\n    pytest.skip('{imp} not importable', allow_module_level=True)\n")
-
-            for func in funcs:
-                test = self._gen_test(func)
-                if test:
-                    parts.append(test + "\n")
-
-        return "\n".join(parts)
-
-    def _gen_test(self, func: FunctionInfo) -> Optional[str]:
-        name = f"test_{func.module.replace('.', '_')}_{func.name}"
-        lines = [f"def {name}():", f'    """Auto-generated for {func.module}.{func.name}."""']
-
-        if not func.args:
-            lines += [
-                "    try:",
-                f"        r = {func.name}()",
-                "        assert r is not None or r is None",
-                "    except Exception:",
-                "        pass",
-            ]
-        else:
-            lines += [
-                "    try:",
-                f"        {func.name}({', '.join(a + '=None' for a in func.args)})",
-                "    except (TypeError, ValueError, AttributeError):",
-                "        pass",
-            ]
-            if any(a in ("text", "content", "message", "query", "path") for a in func.args):
-                lines += [
-                    "    try:",
-                    f"        {func.name}({', '.join(a + '=\"\"' if a in ('text','content','message','query','path') else a + '=None' for a in func.args)})",
-                    "    except (TypeError, ValueError):",
-                    "        pass",
-                ]
-
-        if func.raises:
-            lines.append(f"    # May raise: {', '.join(func.raises[:2])}")
-            lines.append(f"    # with pytest.raises(({', '.join(func.raises[:2])})):")
-            lines.append(f"    #     {func.name}()")
-
-        return "\n".join(lines)
-
-
-def main():
-    parser = argparse.ArgumentParser(description="Codebase Genome — Test Generator")
-    parser.add_argument("target_dir")
-    parser.add_argument("--output", "-o", default="tests/test_genome_generated.py")
-    parser.add_argument("--dry-run", action="store_true")
-    parser.add_argument("--max-tests", type=int, default=100)
-    args = parser.parse_args()
-
-    target = Path(args.target_dir).resolve()
-    if not target.is_dir():
-        print(f"Error: {target} not a directory", file=sys.stderr)
-        return 1
-
-    print(f"Scanning {target}...")
-    scanner = CodebaseScanner(str(target))
-    functions = scanner.scan()
-    print(f"Found {len(functions)} functions in {len(scanner.modules)} modules")
-
-    if len(functions) > args.max_tests:
-        print(f"Limiting to {args.max_tests}")
-        functions = functions[:args.max_tests]
-
-    gen = TestGenerator()
-    code = gen.generate(functions)
-
-    if args.dry_run:
-        print(code)
-        return 0
-
-    out = target / args.output
-    out.parent.mkdir(parents=True, exist_ok=True)
-    out.write_text(code)
-    print(f"Generated {len(functions)} tests → {out}")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

scripts/evennia/build_bezalel_world.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""Idempotent builder for Bezalel's themed Evennia world."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+if str(REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(REPO_ROOT))
+
+from evennia_tools.bezalel_layout import CHARACTERS, EXITS, OBJECTS, PORTAL_COMMANDS, ROOMS
+
+
+def describe_build_plan() -> dict:
+    return {
+        "room_count": len(ROOMS),
+        "character_count": len(CHARACTERS),
+        "object_count": len(OBJECTS),
+        "portal_command_count": len(PORTAL_COMMANDS),
+        "room_names": [room.key for room in ROOMS],
+        "character_starts": {character.key: character.starting_room for character in CHARACTERS},
+        "portal_commands": [command.key for command in PORTAL_COMMANDS],
+    }
+
+
+def _import_evennia_runtime():
+    from evennia.accounts.models import AccountDB
+    from evennia.accounts.accounts import DefaultAccount
+    from evennia.objects.objects import DefaultCharacter, DefaultExit, DefaultObject, DefaultRoom
+    from evennia.utils.create import create_object
+    from evennia.utils.search import search_object
+
+    return {
+        "AccountDB": AccountDB,
+        "DefaultAccount": DefaultAccount,
+        "DefaultCharacter": DefaultCharacter,
+        "DefaultExit": DefaultExit,
+        "DefaultObject": DefaultObject,
+        "DefaultRoom": DefaultRoom,
+        "create_object": create_object,
+        "search_object": search_object,
+    }
+
+
+def _find_named(search_object, key: str, *, location=None):
+    matches = search_object(key, exact=True)
+    if location is None:
+        return matches[0] if matches else None
+    for match in matches:
+        if getattr(match, "location", None) == location:
+            return match
+    return None
+
+
+def _ensure_room(runtime, room_spec):
+    room = _find_named(runtime["search_object"], room_spec.key)
+    if room is None:
+        room = runtime["create_object"](runtime["DefaultRoom"], key=room_spec.key)
+    room.db.desc = room_spec.desc
+    room.save()
+    return room
+
+
+def _ensure_exit(runtime, exit_spec, room_map):
+    source = room_map[exit_spec.source]
+    destination = room_map[exit_spec.destination]
+    existing = _find_named(runtime["search_object"], exit_spec.key, location=source)
+    if existing is None:
+        existing = runtime["create_object"](
+            runtime["DefaultExit"],
+            key=exit_spec.key,
+            aliases=list(exit_spec.aliases),
+            location=source,
+            destination=destination,
+        )
+    else:
+        existing.destination = destination
+        if exit_spec.aliases:
+            existing.aliases.add(list(exit_spec.aliases))
+    existing.save()
+    return existing
+
+
+def _ensure_object(runtime, object_spec, room_map):
+    location = room_map[object_spec.location]
+    existing = _find_named(runtime["search_object"], object_spec.key, location=location)
+    if existing is None:
+        existing = runtime["create_object"](
+            runtime["DefaultObject"],
+            key=object_spec.key,
+            aliases=list(object_spec.aliases),
+            location=location,
+            home=location,
+        )
+    existing.db.desc = object_spec.desc
+    existing.home = location
+    if existing.location != location:
+        existing.move_to(location, quiet=True, move_hooks=False)
+    existing.save()
+    return existing
+
+
+def _ensure_character(runtime, character_spec, room_map, password: str):
+    account = runtime["AccountDB"].objects.filter(username__iexact=character_spec.key).first()
+    if account is None:
+        account, errors = runtime["DefaultAccount"].create(username=character_spec.key, password=password)
+        if not account:
+            raise RuntimeError(f"failed to create account for {character_spec.key}: {errors}")
+    character = list(account.characters)[0]
+    start = room_map[character_spec.starting_room]
+    character.db.desc = character_spec.desc
+    character.home = start
+    character.move_to(start, quiet=True, move_hooks=False)
+    character.save()
+    return character
+
+
+def _ensure_portal_command(runtime, portal_spec, room_map):
+    portal_room = room_map["The Portal Room"]
+    fallback = room_map[portal_spec.fallback_room]
+    existing = _find_named(runtime["search_object"], portal_spec.key, location=portal_room)
+    if existing is None:
+        existing = runtime["create_object"](
+            runtime["DefaultExit"],
+            key=portal_spec.key,
+            aliases=list(portal_spec.aliases),
+            location=portal_room,
+            destination=fallback,
+        )
+    else:
+        existing.destination = fallback
+        if portal_spec.aliases:
+            existing.aliases.add(list(portal_spec.aliases))
+    existing.db.desc = portal_spec.desc
+    existing.db.travel_target = portal_spec.target_world
+    existing.db.portal_stub = True
+    existing.save()
+    return existing
+
+
+def build_world(password: str = "bezalel-world-dev") -> dict:
+    runtime = _import_evennia_runtime()
+    room_map = {room.key: _ensure_room(runtime, room) for room in ROOMS}
+    for exit_spec in EXITS:
+        _ensure_exit(runtime, exit_spec, room_map)
+    for object_spec in OBJECTS:
+        _ensure_object(runtime, object_spec, room_map)
+    for character_spec in CHARACTERS:
+        _ensure_character(runtime, character_spec, room_map, password=password)
+    for portal_spec in PORTAL_COMMANDS:
+        _ensure_portal_command(runtime, portal_spec, room_map)
+
+    return {
+        "rooms": [room.key for room in ROOMS],
+        "characters": {character.key: character.starting_room for character in CHARACTERS},
+        "portal_commands": {command.key: command.target_world for command in PORTAL_COMMANDS},
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Build Bezalel's themed Evennia world")
+    parser.add_argument("--plan", action="store_true", help="Print the static build plan without importing Evennia")
+    parser.add_argument("--password", default="bezalel-world-dev", help="Password to use for created account-backed characters")
+    args = parser.parse_args()
+
+    if args.plan:
+        print(json.dumps(describe_build_plan(), indent=2))
+        return
+
+    print(json.dumps(build_world(password=args.password), indent=2))
+
+
+if __name__ == "__main__":
+    main()

tests/test_bezalel_evennia_layout.py

@@ -0,0 +1,90 @@
+import importlib.util
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+LAYOUT_PATH = ROOT / "evennia_tools" / "bezalel_layout.py"
+BUILD_PATH = ROOT / "scripts" / "evennia" / "build_bezalel_world.py"
+DOC_PATH = ROOT / "docs" / "BEZALEL_EVENNIA_WORLD.md"
+
+
+def load_module(path: Path, name: str):
+    assert path.exists(), f"missing {path.relative_to(ROOT)}"
+    spec = importlib.util.spec_from_file_location(name, path)
+    assert spec and spec.loader
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+class TestBezalelEvenniaLayout(unittest.TestCase):
+    def test_room_graph_matches_issue_shape(self):
+        layout = load_module(LAYOUT_PATH, "bezalel_layout")
+        self.assertEqual(
+            layout.room_keys(),
+            (
+                "Limbo",
+                "Gatehouse",
+                "Great Hall",
+                "The Library of Bezalel",
+                "The Observatory",
+                "The Workshop",
+                "The Server Room",
+                "The Garden of Code",
+                "The Portal Room",
+            ),
+        )
+        exits = layout.grouped_exits()
+        self.assertEqual(
+            {ex.destination for ex in exits["Great Hall"]},
+            {"Gatehouse", "The Library of Bezalel", "The Observatory", "The Workshop"},
+        )
+        self.assertEqual(
+            {ex.destination for ex in exits["The Workshop"]},
+            {"Great Hall", "The Server Room", "The Garden of Code"},
+        )
+
+    def test_items_characters_and_portal_commands_are_all_defined(self):
+        layout = load_module(LAYOUT_PATH, "bezalel_layout")
+        self.assertEqual(layout.character_keys(), ("Timmy", "Bezalel", "Marcus", "Kimi"))
+        self.assertGreaterEqual(len(layout.OBJECTS), 9)
+        self.assertEqual(layout.portal_command_keys(), ("mac", "vps", "net"))
+        room_names = set(layout.room_keys())
+        for obj in layout.OBJECTS:
+            self.assertIn(obj.location, room_names)
+        for character in layout.CHARACTERS:
+            self.assertIn(character.starting_room, room_names)
+        for portal in layout.PORTAL_COMMANDS:
+            self.assertEqual(portal.fallback_room, "Limbo")
+
+    def test_timmy_can_reach_every_room_from_gatehouse(self):
+        layout = load_module(LAYOUT_PATH, "bezalel_layout")
+        reachable = layout.reachable_rooms_from("Gatehouse")
+        self.assertEqual(reachable, set(layout.room_keys()))
+
+    def test_build_plan_summary_reports_counts_and_portal_aliases(self):
+        build = load_module(BUILD_PATH, "build_bezalel_world")
+        summary = build.describe_build_plan()
+        self.assertEqual(summary["room_count"], 9)
+        self.assertEqual(summary["character_count"], 4)
+        self.assertIn("mac", summary["portal_commands"])
+        self.assertIn("The Workshop", summary["room_names"])
+        self.assertEqual(summary["character_starts"]["Bezalel"], "The Workshop")
+
+    def test_repo_contains_bezalel_world_doc(self):
+        self.assertTrue(DOC_PATH.exists(), "missing committed Bezalel world doc")
+        text = DOC_PATH.read_text(encoding="utf-8")
+        for snippet in (
+            "# Bezalel Evennia World",
+            "## Rooms",
+            "## Characters",
+            "## Portal travel commands",
+            "The Library of Bezalel",
+            "The Garden of Code",
+        ):
+            self.assertIn(snippet, text)
+
+
+if __name__ == "__main__":
+    unittest.main()

the-nexus-GENOME.md

@@ -1,319 +0,0 @@
-# GENOME.md — the-nexus
-
-**Generated:** 2026-04-14  
-**Repo:** Timmy_Foundation/the-nexus  
-**Analysis:** Codebase Genome #672
-
----
-
-## Project Overview
-
-The Nexus is Timmy's canonical 3D home-world — a browser-based Three.js application that serves as:
-1. **Local-first training ground** for Timmy (the sovereign AI)
-2. **Wizardly visualization surface** for the fleet system
-3. **Portal architecture** connecting to other worlds and services
-
-The app is a real-time 3D environment with spatial memory, GOFAI reasoning, agent presence, and portal-based navigation.
-
----
-
-## Architecture
-
-```mermaid
-graph TB
-    subgraph Browser["BROWSER LAYER"]
-        HTML[index.html]
-        APP[app.js - 4082 lines]
-        CSS[style.css]
-        Worker[gofai_worker.js]
-    end
-    
-    subgraph ThreeJS["THREE.JS RENDERING"]
-        Scene[Scene Management]
-        Camera[Camera System]
-        Renderer[WebGL Renderer]
-        Post[Post-processing<br/>Bloom, SMAA]
-        Physics[Physics/Player]
-    end
-    
-    subgraph Nexus["NEXUS COMPONENTS"]
-        SM[SpatialMemory]
-        SA[SpatialAudio]
-        MB[MemoryBirth]
-        MO[MemoryOptimizer]
-        MI[MemoryInspect]
-        MP[MemoryPulse]
-        RT[ReasoningTrace]
-        RV[ResonanceVisualizer]
-    end
-    
-    subgraph GOFAI["GOFAI REASONING"]
-        Worker2[Web Worker]
-        Rules[Rule Engine]
-        Facts[Fact Store]
-        Inference[Inference Loop]
-    end
-    
-    subgraph Backend["BACKEND SERVICES"]
-        Server[server.py<br/>WebSocket Bridge]
-        L402[L402 Cost API]
-        Portal[Portal Registry]
-    end
-    
-    subgraph Data["DATA/PERSISTENCE"]
-        Local[localStorage]
-        IDB[IndexedDB]
-        JSON[portals.json]
-        Vision[vision.json]
-    end
-    
-    HTML --> APP
-    APP --> ThreeJS
-    APP --> Nexus
-    APP --> GOFAI
-    APP --> Backend
-    APP --> Data
-    
-    Worker2 --> APP
-    Server --> APP
-```
-
----
-
-## Entry Points
-
-### Primary Entry
-- **`index.html`** — Main HTML shell, loads app.js
-- **`app.js`** — Main application (4082 lines), Three.js scene setup
-
-### Secondary Entry Points
-- **`boot.js`** — Bootstrap sequence
-- **`bootstrap.mjs`** — ES module bootstrap
-- **`server.py`** — WebSocket bridge server
-
-### Configuration Entry Points
-- **`portals.json`** — Portal definitions and destinations
-- **`vision.json`** — Vision/agent configuration
-- **`config/fleet_agents.json`** — Fleet agent definitions
-
----
-
-## Data Flow
-
-```
-User Input
-    ↓
-app.js (Event Loop)
-    ↓
-┌─────────────────────────────────────┐
-│ Three.js Scene                      │
-│ - Player movement                   │
-│ - Camera controls                   │
-│ - Physics simulation                │
-│ - Portal detection                  │
-└─────────────────────────────────────┘
-    ↓
-┌─────────────────────────────────────┐
-│ Nexus Components                    │
-│ - SpatialMemory (room/context)      │
-│ - MemoryBirth (new memories)        │
-│ - MemoryPulse (heartbeat)           │
-│ - ReasoningTrace (GOFAI output)     │
-└─────────────────────────────────────┘
-    ↓
-┌─────────────────────────────────────┐
-│ GOFAI Worker (off-thread)           │
-│ - Rule evaluation                   │
-│ - Fact inference                    │
-│ - Decision making                   │
-└─────────────────────────────────────┘
-    ↓
-┌─────────────────────────────────────┐
-│ Backend Services                    │
-│ - WebSocket (server.py)             │
-│ - L402 cost API                     │
-│ - Portal registry                   │
-└─────────────────────────────────────┘
-    ↓
-Persistence (localStorage/IndexedDB)
-```
-
----
-
-## Key Abstractions
-
-### 1. Nexus Object (`NEXUS`)
-Central configuration and state object containing:
-- Color palette
-- Room definitions
-- Portal configurations
-- Agent settings
-
-### 2. SpatialMemory
-Manages room-based context for the AI agent:
-- Room transitions trigger context switches
-- Facts are stored per-room
-- NPCs have location awareness
-
-### 3. Portal System
-Connects the 3D world to external services:
-- Portals defined in `portals.json`
-- Each portal links to a service/endpoint
-- Visual indicators in 3D space
-
-### 4. GOFAI Worker
-Off-thread reasoning engine:
-- Rule-based inference
-- Fact store with persistence
-- Decision making for agent behavior
-
-### 5. Memory Components
-- **MemoryBirth**: Creates new memories from interactions
-- **MemoryOptimizer**: Compresses and deduplicates memories
-- **MemoryPulse**: Heartbeat system for memory health
-- **MemoryInspect**: Debug/inspection interface
-
----
-
-## API Surface
-
-### Internal APIs (JavaScript)
-
-| Module | Export | Purpose |
-|--------|--------|---------|
-| `app.js` | `NEXUS` | Main config/state object |
-| `SpatialMemory` | class | Room-based context management |
-| `SpatialAudio` | class | 3D positional audio |
-| `MemoryBirth` | class | Memory creation |
-| `MemoryOptimizer` | class | Memory compression |
-| `ReasoningTrace` | class | GOFAI reasoning visualization |
-
-### External APIs (HTTP/WebSocket)
-
-| Endpoint | Protocol | Purpose |
-|----------|----------|---------|
-| `ws://localhost:PORT` | WebSocket | Real-time bridge to backend |
-| `http://localhost:8080/api/cost-estimate` | HTTP | L402 cost estimation |
-| Portal endpoints | Various | External service connections |
-
----
-
-## Dependencies
-
-### Runtime Dependencies
-- **Three.js** — 3D rendering engine
-- **Three.js Addons** — Post-processing (Bloom, SMAA)
-
-### Build Dependencies
-- **ES Modules** — Native browser modules
-- **No bundler** — Direct script loading
-
-### Backend Dependencies
-- **Python 3.x** — server.py
-- **WebSocket** — Real-time communication
-
----
-
-## Test Coverage
-
-### Existing Tests
-- `tests/boot.test.js` — Bootstrap sequence tests
-
-### Test Gaps
-1. **Three.js scene initialization** — No tests
-2. **Portal system** — No tests
-3. **Memory components** — No tests
-4. **GOFAI worker** — No tests
-5. **WebSocket communication** — No tests
-6. **Spatial memory transitions** — No tests
-7. **Physics/player movement** — No tests
-
-### Recommended Test Priorities
-1. Portal detection and activation
-2. Spatial memory room transitions
-3. GOFAI worker message passing
-4. WebSocket connection handling
-5. Memory persistence (localStorage/IndexedDB)
-
----
-
-## Security Considerations
-
-### Current Risks
-1. **WebSocket without auth** — server.py has no authentication
-2. **localStorage sensitive data** — Memories stored unencrypted
-3. **CORS open** — No origin restrictions on WebSocket
-4. **L402 endpoint** — Cost API may expose internal state
-
-### Mitigations
-1. Add WebSocket authentication
-2. Encrypt sensitive memories
-3. Restrict CORS origins
-4. Rate limit L402 endpoint
-
----
-
-## File Structure
-
-```
-the-nexus/
-├── app.js                    # Main app (4082 lines)
-├── index.html                # HTML shell
-├── style.css                 # Styles
-├── server.py                 # WebSocket bridge
-├── boot.js                   # Bootstrap
-├── bootstrap.mjs             # ES module bootstrap
-├── gofai_worker.js           # GOFAI web worker
-├── portals.json              # Portal definitions
-├── vision.json               # Vision config
-├── nexus/                    # Nexus components
-│   └── components/
-│       ├── spatial-memory.js
-│       ├── spatial-audio.js
-│       ├── memory-birth.js
-│       ├── memory-optimizer.js
-│       ├── memory-inspect.js
-│       ├── memory-pulse.js
-│       ├── reasoning-trace.js
-│       └── resonance-visualizer.js
-├── config/                   # Configuration
-├── docs/                     # Documentation
-├── tests/                    # Tests
-├── agent/                    # Agent components
-├── bin/                      # Scripts
-└── assets/                   # Static assets
-```
-
----
-
-## Technical Debt
-
-1. **Large app.js** (4082 lines) — Should be split into modules
-2. **No TypeScript** — Pure JavaScript, no type safety
-3. **Manual DOM manipulation** — Could use a framework
-4. **No build system** — Direct ES modules, no optimization
-5. **Limited error handling** — Minimal try/catch coverage
-
----
-
-## Migration Notes
-
-From CLAUDE.md:
-- Current `main` does NOT ship the old root frontend files
-- A clean checkout serves a directory listing
-- The live browser shell exists in legacy form at `/Users/apayne/the-matrix`
-- Migration priorities: #684 (docs), #685 (legacy audit), #686 (smoke tests), #687 (restore shell)
-
----
-
-## Next Steps
-
-1. **Restore browser shell** — Bring frontend back to main
-2. **Add tests** — Cover critical paths (portals, memory, GOFAI)
-3. **Split app.js** — Modularize the 4082-line file
-4. **Add authentication** — Secure WebSocket and APIs
-5. **TypeScript migration** — Add type safety
-
----
-
-*Generated by Codebase Genome pipeline — Issue #672*