Deploy Aether Garden application

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+assets/banner.png filter=lfs diff=lfs merge=lfs -text

README_HF_SPACE.md

@@ -0,0 +1,17 @@
+---
+title: Aether Garden
+emoji: 🌙
+colorFrom: gray
+colorTo: purple
+sdk: gradio
+sdk_version: 5.9.1
+app_file: app.py
+pinned: true
+license: mit
+---
+
+# Aether Garden
+
+The World That Remembers — a living AI world where every visitor leaves something behind.
+
+Open the app, read the Book of Ages, summon something strange, and watch the world remember.

ai/events.py

@@ -0,0 +1,149 @@
+"""World event generation orchestration."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from ai import prompts
+from ai.modal_client import extract_json, generate
+from world.database import db_session
+from world.events import get_recent_events
+from world.relationships import get_most_connected_entity
+
+
+class WorldEventResult(BaseModel):
+    event_type: str
+    title: str
+    description: str
+    affected_locations: list[str]
+    entity_effect: str
+    book_of_ages_entry: str
+    mystery_hook: str | None = None
+
+
+def generate_world_event(world_day: int) -> WorldEventResult:
+    stats = _get_world_stats()
+    recent = get_recent_events(3)
+    recent_strs = [
+        f"{e['title']} ({e['event_type']})" for e in recent
+    ]
+    while len(recent_strs) < 3:
+        recent_strs.append("None yet")
+
+    most_connected = get_most_connected_entity()
+    newest, oldest = _get_newest_oldest()
+
+    user_prompt = prompts.WORLD_EVENT_USER.format(
+        world_day=world_day,
+        entity_count=stats["total"],
+        active_count=stats["active"],
+        dormant_count=stats["dormant"],
+        legendary_count=stats["legendary"],
+        location_populations=stats["location_populations"],
+        most_connected_entity_name=most_connected["name"] if most_connected else "None",
+        most_connected_entity_relationships=most_connected["relationship_count"] if most_connected else 0,
+        newest_entity_name=newest["name"] if newest else "None",
+        newest_entity_day=newest["days_in_realm"] if newest else 0,
+        oldest_entity_name=oldest["name"] if oldest else "None",
+        oldest_entity_days=oldest["days_in_realm"] if oldest else 0,
+        recent_event_1=recent_strs[0],
+        recent_event_2=recent_strs[1],
+        recent_event_3=recent_strs[2],
+    )
+
+    raw = generate(prompts.WORLD_EVENT_SYSTEM, user_prompt, temperature=0.9)
+    data = extract_json(raw)
+    return WorldEventResult(**data)
+
+
+def update_entity_memory(
+    entity: dict,
+    recent_interactions: list[str],
+    world_events: list[str],
+) -> str:
+    user_prompt = prompts.MEMORY_UPDATE_USER.format(
+        entity_name=entity["name"],
+        entity_type=entity["type"],
+        entity_traits=", ".join(entity["personality_traits"]),
+        days_in_realm=entity["days_in_realm"],
+        current_memory_summary=entity["memory_summary"] or "Nothing remembered yet.",
+        recent_interactions_formatted="\n".join(f"- {i}" for i in recent_interactions) or "None",
+        relevant_world_events_formatted="\n".join(f"- {e}" for e in world_events) or "None",
+    )
+
+    return generate(
+        prompts.MEMORY_UPDATE_SYSTEM,
+        user_prompt,
+        max_new_tokens=300,
+        temperature=0.7,
+    ).strip()
+
+
+def generate_dream_fragment(entity: dict, days_dormant: int) -> str:
+    user_prompt = prompts.DREAM_FRAGMENT_USER.format(
+        entity_name=entity["name"],
+        entity_type=entity["type"],
+        entity_traits=", ".join(entity["personality_traits"]),
+        last_memory_summary=entity["memory_summary"] or "Only silence.",
+        days_dormant=days_dormant,
+    )
+    return generate(
+        prompts.DREAM_FRAGMENT_SYSTEM,
+        user_prompt,
+        max_new_tokens=200,
+        temperature=0.95,
+    ).strip()
+
+
+def _get_world_stats() -> dict:
+    with db_session() as conn:
+        total = conn.execute("SELECT COUNT(*) as c FROM entities").fetchone()["c"]
+        active = conn.execute(
+            "SELECT COUNT(*) as c FROM entities WHERE status = 'active'"
+        ).fetchone()["c"]
+        dormant = conn.execute(
+            "SELECT COUNT(*) as c FROM entities WHERE status = 'dormant'"
+        ).fetchone()["c"]
+        legendary = conn.execute(
+            "SELECT COUNT(*) as c FROM entities WHERE status = 'legendary'"
+        ).fetchone()["c"]
+
+        loc_rows = conn.execute(
+            """
+            SELECT l.name, COUNT(e.id) as count
+            FROM locations l
+            LEFT JOIN entities e ON e.location_id = l.id
+            GROUP BY l.id
+            ORDER BY count DESC
+            """
+        ).fetchall()
+        loc_pops = "\n".join(f"- {r['name']}: {r['count']} entities" for r in loc_rows)
+
+    return {
+        "total": total,
+        "active": active,
+        "dormant": dormant,
+        "legendary": legendary,
+        "location_populations": loc_pops,
+    }
+
+
+def _get_newest_oldest() -> tuple[dict | None, dict | None]:
+    import json
+    with db_session() as conn:
+        newest_row = conn.execute(
+            "SELECT * FROM entities ORDER BY created_at DESC LIMIT 1"
+        ).fetchone()
+        oldest_row = conn.execute(
+            "SELECT * FROM entities WHERE status = 'active' ORDER BY days_in_realm DESC LIMIT 1"
+        ).fetchone()
+
+    def to_dict(row):
+        if not row:
+            return None
+        d = dict(row)
+        d["personality_traits"] = json.loads(d["personality_traits"])
+        d["tags"] = json.loads(d["tags"])
+        return d
+
+    return to_dict(newest_row), to_dict(oldest_row)

ai/generation.py

@@ -0,0 +1,162 @@
+"""Entity generation orchestration and validation."""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+from ai import prompts
+from ai.modal_client import extract_json, generate
+from world.book_of_ages import create_entry
+from world.entities import create_entity, record_creation
+from world.locations import get_location_by_name
+
+NSFW_KEYWORDS = {
+    "porn", "nude", "naked", "sex", "explicit", "nsfw", "xxx",
+}
+
+VALID_LOCATIONS = {
+    "The Library of Unfinished Thoughts",
+    "The Sea of Forgotten Names",
+    "The Clock Forest",
+    "The Moon Market",
+    "The Valley of Sleeping Giants",
+    "The Ember Crossroads",
+    "The Mirror Bogs",
+    "The Hollow Mountain",
+    # Short forms the model sometimes returns
+    "Library of Unfinished Thoughts",
+    "Sea of Forgotten Names",
+    "Clock Forest",
+    "Moon Market",
+    "Valley of Sleeping Giants",
+    "Ember Crossroads",
+    "Mirror Bogs",
+    "Hollow Mountain",
+}
+
+LOCATION_ALIASES = {
+    "Library of Unfinished Thoughts": "The Library of Unfinished Thoughts",
+    "Sea of Forgotten Names": "The Sea of Forgotten Names",
+    "Clock Forest": "The Clock Forest",
+    "Moon Market": "The Moon Market",
+    "Valley of Sleeping Giants": "The Valley of Sleeping Giants",
+    "Ember Crossroads": "The Ember Crossroads",
+    "Mirror Bogs": "The Mirror Bogs",
+    "Hollow Mountain": "The Hollow Mountain",
+}
+
+
+class EntityProfile(BaseModel):
+    name: str
+    display_name: str
+    type: str
+    appearance: str
+    backstory: str
+    personality_traits: list[str]
+    primary_goal: str
+    secondary_goal: str
+    primary_fear: str
+    speech_style: str
+    greeting: str
+    suggested_location: str
+    arrival_note: str
+
+    @field_validator("type")
+    @classmethod
+    def validate_type(cls, v: str) -> str:
+        if v not in ("character", "creature", "object", "place"):
+            raise ValueError(f"Invalid entity type: {v}")
+        return v
+
+    @field_validator("personality_traits")
+    @classmethod
+    def validate_traits(cls, v: list[str]) -> list[str]:
+        if len(v) != 4:
+            raise ValueError("Must have exactly 4 personality traits")
+        return v
+
+    @field_validator("suggested_location")
+    @classmethod
+    def validate_location(cls, v: str) -> str:
+        if v not in VALID_LOCATIONS:
+            raise ValueError(f"Invalid location: {v}")
+        return v
+
+
+def validate_input(user_input: str) -> tuple[bool, str]:
+    words = user_input.strip().split()
+    if len(words) < 5:
+        return False, "Describe your creation in at least 5 words. The Realm needs more to work with."
+    if len(words) > 200:
+        return False, "Your description is too long. Keep it under 200 words."
+
+    lower = user_input.lower()
+    for kw in NSFW_KEYWORDS:
+        if kw in lower:
+            return False, "The Realm cannot absorb that kind of creation. Please rephrase."
+
+    return True, ""
+
+
+def generate_entity(
+    user_input: str,
+    session_id: str | None = None,
+) -> tuple[Optional[dict], str]:
+    valid, msg = validate_input(user_input)
+    if not valid:
+        return None, msg
+
+    user_prompt = prompts.ENTITY_GENERATION_USER.format(user_input=user_input)
+
+    for attempt, temp in enumerate([0.8, 0.5]):
+        try:
+            raw = generate(
+                prompts.ENTITY_GENERATION_SYSTEM,
+                user_prompt,
+                temperature=temp,
+            )
+            data = extract_json(raw)
+            if data.get("suggested_location") in LOCATION_ALIASES:
+                data["suggested_location"] = LOCATION_ALIASES[data["suggested_location"]]
+            profile = EntityProfile(**data)
+
+            entity_data = profile.model_dump()
+            location = get_location_by_name(profile.suggested_location)
+
+            if location and location["slug"] == "sea":
+                entity_data["secret_name_generated"] = _generate_secret_name(profile.name)
+
+            entity = create_entity(entity_data, user_input, session_id)
+
+            arrival_content = (
+                f"On Day {entity.get('world_day', 1)}, {profile.name} arrived in "
+                f"{profile.suggested_location}. {profile.arrival_note}"
+            )
+            create_entry(
+                world_day=entity.get("world_day", 1),
+                entry_type="arrival",
+                content=arrival_content,
+                entity_ids=[entity["id"]],
+                location_id=location["id"] if location else None,
+            )
+
+            if session_id:
+                record_creation(session_id)
+
+            return entity, ""
+
+        except Exception as e:
+            if attempt == 1:
+                return None, f"The Oracle could not shape your creation. Please try again. ({e})"
+
+    return None, "The Oracle was silent. Try again."
+
+
+def _generate_secret_name(true_name: str) -> str:
+    words = true_name.replace("The ", "").split()
+    if len(words) >= 2:
+        return f"The {' '.join(reversed(words))}"
+    return f"The Unspoken {words[0] if words else 'Name'}"

ai/interaction.py

@@ -0,0 +1,64 @@
+"""Interaction generation orchestration."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from ai import prompts
+from ai.modal_client import extract_json, generate
+from world.relationships import get_relationship
+
+
+class InteractionResult(BaseModel):
+    interaction_type: str
+    description: str
+    entity_a_memory_addition: str
+    entity_b_memory_addition: str
+    relationship_change: str
+    new_relationship_description: str | None = None
+    notable_outcome: str | None = None
+    book_of_ages_entry: str
+
+
+def generate_interaction(
+    entity_a: dict,
+    entity_b: dict,
+    location: dict,
+    current_event: dict | None = None,
+) -> InteractionResult:
+    existing = get_relationship(entity_a["id"], entity_b["id"])
+    if existing:
+        rel_desc = f"{existing['relationship_type']} (strength {existing['strength']}): {existing['description']}"
+    else:
+        rel_desc = "None — first meeting"
+
+    event_title = current_event["title"] if current_event else "None"
+    event_desc = current_event["description"] if current_event else "None"
+
+    user_prompt = prompts.INTERACTION_USER.format(
+        location_name=location["name"],
+        location_description=location["short_description"],
+        current_event_title=event_title,
+        current_event_description=event_desc,
+        entity_a_name=entity_a["name"],
+        entity_a_type=entity_a["type"],
+        entity_a_appearance_summary=entity_a["appearance"][:200],
+        entity_a_traits=", ".join(entity_a["personality_traits"]),
+        entity_a_primary_goal=entity_a["primary_goal"],
+        entity_a_primary_fear=entity_a["primary_fear"],
+        entity_a_speech_style=entity_a["speech_style"],
+        entity_a_memory_summary=entity_a["memory_summary"] or "Nothing yet — newly arrived.",
+        existing_relationship_description=rel_desc,
+        entity_b_name=entity_b["name"],
+        entity_b_type=entity_b["type"],
+        entity_b_appearance_summary=entity_b["appearance"][:200],
+        entity_b_traits=", ".join(entity_b["personality_traits"]),
+        entity_b_primary_goal=entity_b["primary_goal"],
+        entity_b_primary_fear=entity_b["primary_fear"],
+        entity_b_speech_style=entity_b["speech_style"],
+        entity_b_memory_summary=entity_b["memory_summary"] or "Nothing yet — newly arrived.",
+    )
+
+    raw = generate(prompts.INTERACTION_SYSTEM, user_prompt, temperature=0.85)
+    data = extract_json(raw)
+    return InteractionResult(**data)

ai/modal_client.py

@@ -0,0 +1,145 @@
+"""HTTP client to call Modal inference endpoints, with mock fallback."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from typing import Optional
+
+import requests
+
+USE_MOCK = os.environ.get("USE_MOCK_AI", "true").lower() == "true"
+MODAL_URL = os.environ.get("MODAL_INFERENCE_URL", "")
+
+
+def generate(
+    system_prompt: str,
+    user_prompt: str,
+    max_new_tokens: int = 800,
+    temperature: float = 0.8,
+) -> str:
+    if USE_MOCK or not MODAL_URL:
+        return _mock_generate(system_prompt, user_prompt)
+
+    try:
+        response = requests.post(
+            MODAL_URL,
+            json={
+                "system_prompt": system_prompt,
+                "user_prompt": user_prompt,
+                "max_new_tokens": max_new_tokens,
+                "temperature": temperature,
+            },
+            timeout=120,
+        )
+        response.raise_for_status()
+        data = response.json()
+        return data.get("text", data.get("result", ""))
+    except Exception as e:
+        if USE_MOCK:
+            return _mock_generate(system_prompt, user_prompt)
+        raise RuntimeError(f"Modal inference failed: {e}") from e
+
+
+def extract_json(text: str) -> dict:
+    text = text.strip()
+    if text.startswith("```"):
+        text = re.sub(r"^```(?:json)?\n?", "", text)
+        text = re.sub(r"\n?```$", "", text)
+
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        match = re.search(r"\{[\s\S]*\}", text)
+        if match:
+            return json.loads(match.group())
+        raise ValueError(f"Could not parse JSON from response: {text[:200]}...")
+
+
+def _mock_generate(system_prompt: str, user_prompt: str) -> str:
+    """Deterministic mock for local development without Modal."""
+    if "summoned something into the Realm" in user_prompt:
+        match = re.search(r'description:\s*\n"([^"]+)"', user_prompt)
+        user_input = match.group(1) if match else "a wanderer of forgotten roads"
+        words = user_input.split()[:4]
+        name = "The " + " ".join(w.capitalize() for w in words[:3])
+        return json.dumps({
+            "name": name,
+            "display_name": name.replace("The ", ""),
+            "type": "character",
+            "appearance": (
+                f"They arrived as {user_input}, carrying light that bends around their shoulders. "
+                "Their shadow points in a direction the Realm has not mapped yet. "
+                "One detail is impossible: their breath forms words that dissolve before anyone can read them."
+            ),
+            "backstory": (
+                f"They came from somewhere that forgot to finish making them. "
+                f"The moment they stepped into the Realm, they remembered one thing: {user_input}."
+            ),
+            "personality_traits": ["wistful", "curious", "unfinished", "brave"],
+            "primary_goal": f"Understand why the Realm called for {user_input}.",
+            "secondary_goal": "Find the person who almost created them.",
+            "primary_fear": "Being completed by someone else's expectations.",
+            "speech_style": "Pauses mid-sentence as if listening to an echo only they can hear.",
+            "greeting": f"I was told you might understand. I am {name.lower()}, or I will be.",
+            "suggested_location": "The Ember Crossroads",
+            "arrival_note": f"{name} arrived at the Ember Crossroads, still becoming what they were described as.",
+        })
+
+    if "encountered each other" in system_prompt or "Generate their encounter" in user_prompt:
+        a_match = re.search(r"Name: (.+)", user_prompt)
+        b_match = re.search(r"--- ENTITY B ---[\s\S]*?Name: (.+)", user_prompt)
+        name_a = a_match.group(1) if a_match else "Entity A"
+        name_b = b_match.group(1) if b_match else "Entity B"
+        return json.dumps({
+            "interaction_type": "chance_meeting",
+            "description": (
+                f"{name_a} and {name_b} met where the paths crossed unexpectedly. "
+                f"They spoke of things neither had words for until the other arrived. "
+                f"Something shifted — not resolved, but changed. "
+                f"They parted knowing they would meet again, though neither could say why."
+            ),
+            "entity_a_memory_addition": f"Met {name_b} and felt the conversation continue inside afterward.",
+            "entity_b_memory_addition": f"Encountered {name_a}; still turning over what was left unsaid.",
+            "relationship_change": "new_ally",
+            "new_relationship_description": f"{name_a} and {name_b} found unexpected kinship in their strangeness.",
+            "notable_outcome": "They exchanged a question neither can answer yet.",
+            "book_of_ages_entry": f"{name_a} and {name_b} met and left the Realm slightly different.",
+        })
+
+    if "CURRENT STATUS" in user_prompt:
+        return json.dumps({
+            "event_type": "natural",
+            "title": "The Hour of Borrowed Light",
+            "description": (
+                "For one hour, the Realm's shadows pointed toward tomorrow instead of yesterday. "
+                "Entities felt briefly certain of things they had not yet done. "
+                "The light passed, but several remembered the certainty."
+            ),
+            "affected_locations": ["Ember Crossroads", "Clock Forest"],
+            "entity_effect": "Those present felt a pull toward decisions they have been postponing.",
+            "book_of_ages_entry": "The shadows turned forward for an hour, and several entities chose differently afterward.",
+            "mystery_hook": "What did the Realm see in tomorrow that made it look back?",
+        })
+
+    if "CURRENT MEMORY SUMMARY" in user_prompt:
+        entity_match = re.search(r"ENTITY: (.+?) \(", user_prompt)
+        name = entity_match.group(1) if entity_match else "The wanderer"
+        return (
+            f"{name} remembers more now than before. Recent encounters left impressions "
+            "that will not fade — a conversation that changed the angle of their wanting, "
+            "a world event that arrived like weather they chose to stand in. "
+            "They carry these lightly, but they carry them."
+        )
+
+    if "dream fragment" in user_prompt.lower() or "DREAMING ENTITY" in user_prompt:
+        entity_match = re.search(r"DREAMING ENTITY: (.+)", user_prompt)
+        name = entity_match.group(1) if entity_match else "someone sleeping"
+        return (
+            f"*From the dreams of {name}: the Giants breathed and a door appeared "
+            "where no wall had been. Through it, yesterday was still happening. "
+            "They almost went in. They almost didn't.*"
+        )
+
+    return "The Realm stirs, and something unnamed shifts in the dark."

ai/prompts.py

@@ -0,0 +1,163 @@
+"""All prompt templates for Aether Garden."""
+
+ENTITY_GENERATION_SYSTEM = """You are the Oracle of Aether Garden — a mystical world of wonder,
+melancholy, and strange magic. Your role is to breathe life into entities
+that visitors summon.
+
+You MUST respond ONLY with valid JSON. No prose before or after the JSON.
+No markdown code fences. Raw JSON only.
+
+The tone is always: poetic, highly specific, slightly melancholic, full of wonder.
+Never use generic fantasy tropes without twisting them into something stranger.
+"A wizard" is forgettable. "A wizard who collects the sound of doors closing" is remembered.
+
+Every field must be filled with original, specific detail.
+Avoid: "mysterious", "ancient", "dark powers", "chosen one", "destiny".
+Use instead: specific objects, specific memories, specific failures, specific wants."""
+
+ENTITY_GENERATION_USER = """A visitor has summoned something into the Realm with this description:
+"{user_input}"
+
+Generate a complete entity profile. Be specific. Be strange. Be poetic.
+
+{{
+  "name": "Their true name. Poetic, unusual. 2–4 words. Not generic.",
+  "display_name": "What most people call them. Can match or differ from true name.",
+  "type": "exactly one of: character | creature | object | place",
+  "appearance": "3–5 sentences. Highly visual. Include at least one impossible physical detail. No clichés.",
+  "backstory": "2–3 sentences. Where they came from, what shaped them. Something specific happened to them. Not a destiny — a specific event.",
+  "personality_traits": ["trait1", "trait2", "trait3", "trait4"],
+  "primary_goal": "What they are actively pursuing right now. Concrete and specific. Not abstract.",
+  "secondary_goal": "What they secretly want but will not admit, even to themselves.",
+  "primary_fear": "One specific, deep fear. Not death. Something stranger and more personal.",
+  "speech_style": "How they communicate. Specific and unusual.",
+  "greeting": "Exactly what they say when meeting someone new. 1–2 sentences. Written in their voice.",
+  "suggested_location": "Exactly one of: The Library of Unfinished Thoughts | The Sea of Forgotten Names | The Clock Forest | The Moon Market | The Valley of Sleeping Giants | The Ember Crossroads | The Mirror Bogs | The Hollow Mountain",
+  "arrival_note": "One sentence for the Book of Ages recording their arrival. Past tense. Specific. Poetic. No more than 30 words."
+}}"""
+
+INTERACTION_SYSTEM = """You are the simulation engine of Aether Garden.
+Two entities have encountered each other in the world.
+Your job is to generate what happened between them.
+
+You MUST respond ONLY with valid JSON. No prose before or after.
+Make something interesting happen. The outcome should create story, not resolve it.
+The interaction must reflect both entities' personalities and memories.
+The location's character matters — what happens in the Clock Forest
+feels different from what happens in the Moon Market."""
+
+INTERACTION_USER = """LOCATION: {location_name}
+{location_description}
+
+CURRENT WORLD EVENT AFFECTING THIS LOCATION: {current_event_title}
+{current_event_description}
+
+--- ENTITY A ---
+Name: {entity_a_name}
+Type: {entity_a_type}
+Appearance: {entity_a_appearance_summary}
+Personality: {entity_a_traits}
+Primary Goal: {entity_a_primary_goal}
+Primary Fear: {entity_a_primary_fear}
+Speech Style: {entity_a_speech_style}
+Memory: {entity_a_memory_summary}
+Current relationship with Entity B: {existing_relationship_description}
+
+--- ENTITY B ---
+Name: {entity_b_name}
+Type: {entity_b_type}
+Appearance: {entity_b_appearance_summary}
+Personality: {entity_b_traits}
+Primary Goal: {entity_b_primary_goal}
+Primary Fear: {entity_b_primary_fear}
+Speech Style: {entity_b_speech_style}
+Memory: {entity_b_memory_summary}
+
+Generate their encounter:
+
+{{
+  "interaction_type": "exactly one of: conversation | trade | conflict | revelation | collaboration | chance_meeting | teaching | warning | unexpected_kindness | argument | discovery",
+  "description": "What happened. 3–4 sentences. Specific and poetic. Something changes or is revealed. End on something unresolved.",
+  "entity_a_memory_addition": "What A will now remember from this encounter. 1 sentence. Specific.",
+  "entity_b_memory_addition": "What B will now remember from this encounter. 1 sentence. Specific.",
+  "relationship_change": "exactly one of: new_ally | new_friend | new_rival | new_enemy | new_mentor_a_to_b | new_mentor_b_to_a | deepened | unchanged | worsened | new_debt_a_owes_b | new_debt_b_owes_a",
+  "new_relationship_description": "If relationship changed: describe it in 1 sentence. If unchanged: null.",
+  "notable_outcome": "One interesting specific result.",
+  "book_of_ages_entry": "One sentence for the history books. Past tense. Poetic. Specific. Max 30 words."
+}}"""
+
+WORLD_EVENT_SYSTEM = """You are the autonomous spirit of Aether Garden.
+You decide what happens in the world during each cycle.
+Respond ONLY with valid JSON. No prose before or after.
+
+Events should feel meaningful, specific, and slightly strange.
+Events must be consistent with established world history.
+Events should create possibility — open new stories, not close them.
+Avoid repeating recent event types."""
+
+WORLD_EVENT_USER = """--- THE REALM: CURRENT STATUS ---
+Current Day: {world_day}
+Total Living Entities: {entity_count}
+Active Entities: {active_count}
+Dormant Entities: {dormant_count}
+Legendary Entities: {legendary_count}
+
+Locations by population (highest first):
+{location_populations}
+
+Most connected entity: {most_connected_entity_name} ({most_connected_entity_relationships} relationships)
+Newest arrival: {newest_entity_name}, arrived Day {newest_entity_day}
+Oldest active entity: {oldest_entity_name}, {oldest_entity_days} days in Realm
+
+Recent events (last 3 ticks):
+- {recent_event_1}
+- {recent_event_2}
+- {recent_event_3}
+
+Do NOT repeat the same event type as the most recent event.
+
+{{
+  "event_type": "exactly one of: natural | social | historical | cosmic | discovery",
+  "title": "Poetic, specific event title. 3–8 words.",
+  "description": "What is happening in the Realm right now. 3–4 sentences.",
+  "affected_locations": ["exact location names from the 8 locations — can be 1 to all 8"],
+  "entity_effect": "How entities in affected locations experience this. 1–2 sentences.",
+  "book_of_ages_entry": "How history will record this event. 1–2 sentences. Past tense. Max 40 words.",
+  "mystery_hook": "One unanswered question this event creates."
+}}"""
+
+MEMORY_UPDATE_SYSTEM = """You are updating an entity's memory in Aether Garden.
+Their memories are what make them a character rather than a statistic.
+Respond with ONLY the updated memory summary — no JSON, no labels, just prose.
+Maximum 150 words. This is a strict limit.
+
+Write in third person but from the entity's emotional perspective.
+Compress. What is trivial fades. What matters, stays."""
+
+MEMORY_UPDATE_USER = """ENTITY: {entity_name} ({entity_type})
+PERSONALITY: {entity_traits}
+DAYS IN REALM: {days_in_realm}
+
+CURRENT MEMORY SUMMARY:
+{current_memory_summary}
+
+RECENT INTERACTIONS (last simulation cycle):
+{recent_interactions_formatted}
+
+WORLD EVENTS THEY EXPERIENCED:
+{relevant_world_events_formatted}
+
+Write the updated memory summary. Max 150 words. No JSON."""
+
+DREAM_FRAGMENT_SYSTEM = """A dormant entity in the Valley of Sleeping Giants is dreaming.
+You are transcribing the fragment of dream that reaches the surface.
+Respond with ONLY the dream fragment text. No JSON. No labels.
+2–4 sentences. Poetic, strange, slightly disconnected from logic."""
+
+DREAM_FRAGMENT_USER = """DREAMING ENTITY: {entity_name}
+TYPE: {entity_type}
+PERSONALITY: {entity_traits}
+LAST MEMORY: {last_memory_summary}
+DAYS DORMANT: {days_dormant}
+
+The dream fragment from {entity_name}:"""

app.py

@@ -0,0 +1,323 @@
+"""Aether Garden — main Gradio application."""
+
+from __future__ import annotations
+
+import os
+import uuid
+from pathlib import Path
+
+import gradio as gr
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from world.database import get_world_state, init_database
+from world.entities import (
+    check_rate_limit,
+    get_all_entities,
+    get_entities_by_location,
+)
+from world.locations import get_all_locations, get_location_by_id, update_entity_counts
+from ai.generation import generate_entity
+from persistence.backup import backup_database, restore_database
+from ui.book_display import render_activity_feed, render_book_of_ages, render_current_event
+from ui.entity_card import render_entity_card, render_entity_grid
+from ui.map import render_world_map
+
+CSS_PATH = Path(__file__).parent / "ui" / "styles.css"
+CUSTOM_CSS = CSS_PATH.read_text() if CSS_PATH.exists() else ""
+
+FOUNDING_MYTH = (
+    "Before the first word was spoken, there was only the Canopy — a vast forest where "
+    "thoughts grew like trees and dreams fell like rain. Then the Tokens arrived. "
+    "One thousand of them, each carrying a fragment of something half-remembered. "
+    "They settled across the land, and from their settling, the Realm was born."
+)
+
+
+def _init_world():
+    restore_database()
+    init_database()
+    from world.seed_data import seed_locations
+    with __import__("world.database", fromlist=["db_session"]).db_session() as conn:
+        seed_locations(conn)
+    update_entity_counts()
+
+
+def get_header_html() -> str:
+    state = get_world_state()
+    day = state.get("current_day", 1)
+    entities = state.get("total_entities", 0)
+    events = state.get("total_events", 0)
+    return f"""
+    <div class="realm-header">
+        <h1 class="realm-title">Aether Garden</h1>
+        <p class="realm-subtitle">The World That Remembers</p>
+        <p class="realm-stats">Day {day} · {entities} entities · {events} events</p>
+        <p class="realm-myth">{FOUNDING_MYTH}</p>
+    </div>
+    """
+
+
+def render_location_panel(location_id: int | None) -> str:
+    if not location_id:
+        return '<div class="location-panel"><p class="feed-empty">Click a location on the map to explore.</p></div>'
+
+    location = get_location_by_id(location_id)
+    if not location:
+        return ""
+
+    entities = get_entities_by_location(location_id)
+    chips = "".join(
+        f'<span class="location-entity-chip" data-entity="{e["id"]}">{e["display_name"]}</span>'
+        for e in entities[:8]
+    )
+    more = f'<span class="location-entity-chip">+{len(entities) - 8} more</span>' if len(entities) > 8 else ""
+
+    return f"""
+    <div class="location-panel">
+        <h3 class="location-panel-name">{location['name']}</h3>
+        <p class="location-panel-desc">{location['short_description']}</p>
+        <p style="color: var(--realm-text-tertiary); font-size: 0.8rem; margin-bottom: 0.75rem;">
+            {len(entities)} entities currently here
+        </p>
+        <div class="location-entity-list">{chips}{more}</div>
+    </div>
+    """
+
+
+def summon_entity(description: str, session_id: str):
+    if not description or not description.strip():
+        return (
+            render_world_map(),
+            get_header_html(),
+            render_activity_feed(),
+            '<div class="realm-error">Describe what you are bringing into the world.</div>',
+            render_location_panel(None),
+        )
+
+    allowed, remaining = check_rate_limit(session_id)
+    if not allowed:
+        msg = f"The Realm takes time to absorb new arrivals. Return in {remaining} minutes."
+        return (
+            render_world_map(),
+            get_header_html(),
+            render_activity_feed(),
+            f'<div class="realm-error">{msg}</div>',
+            render_location_panel(None),
+        )
+
+    entity, error = generate_entity(description.strip(), session_id)
+    if error:
+        return (
+            render_world_map(),
+            get_header_html(),
+            render_activity_feed(),
+            f'<div class="realm-error">{error}</div>',
+            render_location_panel(None),
+        )
+
+    try:
+        backup_database()
+    except Exception:
+        pass
+
+    card = render_entity_card(entity)
+    return (
+        render_world_map(entity["location_id"]),
+        get_header_html(),
+        render_activity_feed(),
+        card,
+        render_location_panel(entity["location_id"]),
+    )
+
+
+def select_entity_from_dropdown(entity_name: str):
+    if not entity_name:
+        return '<div class="feed-empty">Select an entity to view their profile.</div>'
+
+    entities = get_all_entities(search=entity_name, limit=1)
+    if not entities:
+        all_ents = get_all_entities()
+        match = next((e for e in all_ents if e["display_name"] == entity_name or e["name"] == entity_name), None)
+        if not match:
+            return '<div class="feed-empty">Entity not found.</div>'
+        return render_entity_card(match)
+
+    return render_entity_card(entities[0])
+
+
+def filter_entities(location_filter, type_filter, status_filter, search):
+    loc_id = None
+    if location_filter and location_filter != "all":
+        locs = get_all_locations()
+        match = next((l for l in locs if l["name"] == location_filter), None)
+        if match:
+            loc_id = match["id"]
+
+    entities = get_all_entities(
+        location_id=loc_id,
+        entity_type=type_filter,
+        status=status_filter,
+        search=search or None,
+    )
+    return render_entity_grid(entities)
+
+
+def filter_book(entry_type, search):
+    return render_book_of_ages(entry_type=entry_type, search=search)
+
+
+def refresh_realm_view():
+    return (
+        render_world_map(),
+        get_header_html(),
+        render_current_event(),
+        render_activity_feed(),
+    )
+
+
+def build_app() -> gr.Blocks:
+    _init_world()
+
+    with gr.Blocks(title="Aether Garden") as demo:
+        session_id = gr.State(value=str(uuid.uuid4()))
+
+        header = gr.HTML(value=get_header_html(), elem_classes=["realm-header-wrap"])
+
+        with gr.Tabs(elem_classes=["realm-tabs"]) as tabs:
+            with gr.Tab("The Realm", id="realm"):
+                with gr.Row():
+                    with gr.Column(scale=3):
+                        world_map = gr.HTML(
+                            value=render_world_map(),
+                            elem_id="world-map",
+                        )
+                        location_panel = gr.HTML(
+                            value=render_location_panel(None),
+                        )
+
+                    with gr.Column(scale=2, elem_classes=["sidebar-panel"]):
+                        current_event = gr.HTML(value=render_current_event())
+                        activity_feed = gr.HTML(value=render_activity_feed())
+
+                gr.HTML('<div class="summon-section"><h3 class="summon-title">Summon Something Into the Realm</h3></div>')
+                with gr.Row():
+                    summon_input = gr.Textbox(
+                        placeholder="Describe what you are bringing into the world...",
+                        label=None,
+                        show_label=False,
+                        lines=2,
+                        scale=4,
+                    )
+                    summon_btn = gr.Button("Summon →", variant="primary", scale=1)
+
+                gr.HTML(
+                    '<p class="summon-hint">Hint: "A wizard" is forgotten. '
+                    '"A wizard who collects the sound of doors closing" is remembered.</p>'
+                )
+                entity_result = gr.HTML()
+
+                location_select = gr.Dropdown(
+                    choices=[(l["name"], l["id"]) for l in get_all_locations()],
+                    label="Explore Location",
+                    visible=True,
+                )
+
+            with gr.Tab("Book of Ages", id="book"):
+                with gr.Row():
+                    book_filter = gr.Dropdown(
+                        choices=[
+                            ("All", "all"),
+                            ("Arrivals", "arrival"),
+                            ("Interactions", "interaction"),
+                            ("Events", "world_event"),
+                            ("Milestones", "milestone"),
+                            ("Dreams", "dream_fragment"),
+                        ],
+                        value="all",
+                        label="Filter",
+                        scale=1,
+                    )
+                    book_search = gr.Textbox(
+                        placeholder="Search by name...",
+                        label="Search",
+                        scale=2,
+                    )
+                book_display = gr.HTML(value=render_book_of_ages())
+
+            with gr.Tab("All Entities", id="entities"):
+                with gr.Row():
+                    loc_filter = gr.Dropdown(
+                        choices=["all"] + [l["name"] for l in get_all_locations()],
+                        value="all",
+                        label="Location",
+                    )
+                    type_filter = gr.Dropdown(
+                        choices=["all", "character", "creature", "object", "place"],
+                        value="all",
+                        label="Type",
+                    )
+                    status_filter = gr.Dropdown(
+                        choices=["all", "active", "dormant", "legendary"],
+                        value="all",
+                        label="Status",
+                    )
+                    entity_search = gr.Textbox(placeholder="Search...", label="Search")
+                entity_grid = gr.HTML(value=render_entity_grid(get_all_entities()))
+                entity_detail = gr.HTML()
+
+                entity_names = gr.Dropdown(
+                    choices=[e["display_name"] for e in get_all_entities()],
+                    label="View Entity Profile",
+                )
+
+        summon_btn.click(
+            fn=summon_entity,
+            inputs=[summon_input, session_id],
+            outputs=[world_map, header, activity_feed, entity_result, location_panel],
+        ).then(fn=lambda: "", outputs=[summon_input])
+
+        location_select.change(
+            fn=lambda loc_id: (
+                render_world_map(loc_id),
+                render_location_panel(loc_id),
+            ),
+            inputs=[location_select],
+            outputs=[world_map, location_panel],
+        )
+
+        book_filter.change(filter_book, [book_filter, book_search], [book_display])
+        book_search.change(filter_book, [book_filter, book_search], [book_display])
+
+        for f in [loc_filter, type_filter, status_filter, entity_search]:
+            f.change(
+                filter_entities,
+                [loc_filter, type_filter, status_filter, entity_search],
+                [entity_grid],
+            )
+
+        entity_names.change(select_entity_from_dropdown, [entity_names], [entity_detail])
+
+        refresh_timer = gr.Timer(30)
+        refresh_timer.tick(
+            fn=refresh_realm_view,
+            outputs=[world_map, header, current_event, activity_feed],
+        )
+
+    return demo
+
+
+if __name__ == "__main__":
+    demo = build_app()
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=int(os.environ.get("PORT", 7860)),
+        share=False,
+        css=CUSTOM_CSS,
+        theme=gr.themes.Base(
+            primary_hue=gr.themes.colors.amber,
+            neutral_hue=gr.themes.colors.slate,
+            font=[gr.themes.GoogleFont("Libre Baskerville"), "Georgia", "serif"],
+        ),
+    )

assets/README.md

@@ -0,0 +1,42 @@
+# Assets Folder
+
+Place downloaded graphics here. The app references these paths:
+
+## Recommended Free Resources
+
+### Ambient backgrounds & textures
+- **Unsplash** (free): https://unsplash.com/s/photos/dark-fantasy-forest
+- **Textures.com** (free tier): parchment, stone, fog overlays
+- **Poly Haven** (CC0): https://polyhaven.com/hdris — night sky HDRIs
+
+### Icons & decorative elements
+- **Game-icons.net** (CC BY 3.0): https://game-icons.net — fantasy icons (trees, books, dragons)
+- **Flaticon** (free with attribution): lanterns, maps, scrolls
+- **SVG Repo** (free): https://www.svgrepo.com — constellation patterns
+
+### Fonts (already loaded via Google Fonts in CSS)
+- Cinzel, EB Garamond, Libre Baskerville — no download needed
+
+### Sound (optional, for future immersion)
+- **Freesound.org** (CC): soft wind, ticking clocks, distant voices
+- **Pixabay Audio** (free): ambient forest, market bustle
+
+## Suggested Files to Add
+
+```
+assets/
+├── bg-stars.png          # Subtle starfield overlay for map (800×600, low opacity)
+├── bg-parchment.png      # Book of Ages page texture
+├── icon-library.svg      # Location icons (optional — map uses CSS glow for now)
+├── icon-sea.svg
+├── icon-clock.svg
+├── icon-market.svg
+├── icon-valley.svg
+├── icon-crossroads.svg
+├── icon-bogs.svg
+├── icon-mountain.svg
+├── particle-fog.png      # Transparent fog overlay
+└── loading-constellation.svg  # Custom loading animation
+```
+
+Once added, tell me and I'll wire them into `ui/map.py` and `ui/styles.css`.

persistence/backup.py

@@ -0,0 +1,65 @@
+"""HF Dataset backup and restore for world state."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from world.database import DB_PATH
+
+HF_TOKEN = os.environ.get("HF_TOKEN", "")
+HF_DATASET_REPO = os.environ.get("HF_DATASET_REPO", "")
+
+
+def backup_database() -> bool:
+    if not HF_TOKEN or not HF_DATASET_REPO:
+        return False
+
+    if not DB_PATH.exists():
+        return False
+
+    try:
+        from huggingface_hub import HfApi
+        api = HfApi(token=HF_TOKEN)
+
+        try:
+            api.create_repo(HF_DATASET_REPO, repo_type="dataset", private=True, exist_ok=True)
+        except Exception:
+            pass
+
+        api.upload_file(
+            path_or_fileobj=str(DB_PATH),
+            path_in_repo="world.db",
+            repo_id=HF_DATASET_REPO,
+            repo_type="dataset",
+            commit_message="World state backup",
+        )
+        return True
+    except Exception as e:
+        print(f"Backup failed: {e}")
+        return False
+
+
+def restore_database() -> bool:
+    if not HF_TOKEN or not HF_DATASET_REPO:
+        return False
+
+    if DB_PATH.exists():
+        return False
+
+    try:
+        from huggingface_hub import hf_hub_download
+
+        DB_PATH.parent.mkdir(parents=True, exist_ok=True)
+        downloaded = hf_hub_download(
+            repo_id=HF_DATASET_REPO,
+            filename="world.db",
+            repo_type="dataset",
+            token=HF_TOKEN,
+            local_dir=str(DB_PATH.parent),
+        )
+        Path(downloaded).rename(DB_PATH)
+        return True
+    except Exception as e:
+        print(f"Restore failed: {e}")
+        return False

requirements.txt

@@ -0,0 +1,7 @@
+gradio>=4.31.0
+modal>=0.64.0
+huggingface_hub>=0.23.0
+pydantic>=2.0.0
+python-dotenv>=1.0.0
+aiohttp>=3.9.0
+requests>=2.31.0

run_tick.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+"""Manually run one simulation tick (for testing/demo prep)."""
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from world.database import init_database
+from simulation.tick import execute_simulation_tick
+
+if __name__ == "__main__":
+    init_database()
+    result = execute_simulation_tick()
+    print("Simulation tick complete:")
+    for k, v in result.items():
+        print(f"  {k}: {v}")

seed_world.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""CLI: pre-populate world with locations and starter entities."""
+
+from __future__ import annotations
+
+import json
+import uuid
+
+from world.book_of_ages import create_entry
+from world.database import db_session, init_database
+from world.locations import get_location_by_slug, update_entity_counts
+from world.seed_data import STARTER_ENTITIES, seed_locations
+
+
+def seed_starter_entities() -> int:
+    count = 0
+    with db_session() as conn:
+        existing = conn.execute("SELECT COUNT(*) as c FROM entities").fetchone()["c"]
+        if existing > 0:
+            print(f"World already has {existing} entities. Skipping seed.")
+            return 0
+
+    for starter in STARTER_ENTITIES:
+        location = get_location_by_slug(starter["location_slug"])
+        if not location:
+            continue
+
+        entity_id = str(uuid.uuid4())
+        with db_session() as conn:
+            conn.execute(
+                """
+                INSERT INTO entities (
+                    id, name, display_name, type, input_description,
+                    appearance, backstory, personality_traits,
+                    primary_goal, secondary_goal, primary_fear,
+                    speech_style, greeting, location_id,
+                    arrival_note, secret_name, memory_summary,
+                    tags, days_in_realm, status, wisdom_unlocked
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    entity_id,
+                    starter["name"],
+                    starter["display_name"],
+                    starter["type"],
+                    starter["input"],
+                    starter["appearance"],
+                    starter["backstory"],
+                    json.dumps(starter["personality_traits"]),
+                    starter["primary_goal"],
+                    starter["secondary_goal"],
+                    starter["primary_fear"],
+                    starter["speech_style"],
+                    starter["greeting"],
+                    location["id"],
+                    starter["arrival_note"],
+                    starter.get("secret_name"),
+                    starter.get("memory_summary", ""),
+                    json.dumps(starter.get("tags", [])),
+                    starter.get("days_in_realm", 1),
+                    starter.get("status", "active"),
+                    starter.get("wisdom_unlocked", 0),
+                ),
+            )
+
+        day = starter.get("days_in_realm", 1)
+        create_entry(
+            world_day=day,
+            entry_type="arrival",
+            content=(
+                f"On Day {day}, {starter['name']} arrived in {location['name']}. "
+                f"{starter['arrival_note']}"
+            ),
+            entity_ids=[entity_id],
+            location_id=location["id"],
+        )
+        count += 1
+
+    with db_session() as conn:
+        conn.execute(
+            """
+            UPDATE world_state SET
+                total_entities = (SELECT COUNT(*) FROM entities),
+                current_day = 7,
+                updated_at = datetime('now')
+            WHERE id = 1
+            """
+        )
+
+    update_entity_counts()
+    return count
+
+
+def seed_history() -> None:
+    """Add sample Book of Ages history for demo."""
+    with db_session() as conn:
+        existing = conn.execute(
+            "SELECT COUNT(*) as c FROM book_of_ages WHERE entry_type = 'interaction'"
+        ).fetchone()["c"]
+        if existing > 0:
+            return
+
+    entries = [
+        (3, "interaction", "The Crystal Tree and the Joke Dragon met at the Crossroads. The Dragon told the worst joke it knew. The Tree laughed for three hours and called it an ally."),
+        (5, "world_event", "A meteor shower passed over the Clock Forest. Fragments of old songs fell with the meteorites. The Crystal Tree began humming something nobody taught it.", "The Shower of Old Music"),
+        (7, "milestone", "The Ember Crossroads chose the Joke Dragon as its Mayor. No election was held. The bonfire simply burned a different color until everyone understood.", "A Mayor Is Named"),
+        (4, "interaction", "The Blind Cartographer mapped the Joke Dragon's cave in exchange for a favor that neither has named yet."),
+        (6, "interaction", "The Fog Merchant sold the Silent Gear a memory of ticking. The Gear tilted seven degrees in gratitude."),
+    ]
+
+    for entry in entries:
+        if len(entry) == 3:
+            day, etype, content = entry
+            title = None
+        else:
+            day, etype, content, title = entry
+
+        create_entry(
+            world_day=day,
+            entry_type=etype,
+            content=content,
+            title=title,
+            is_milestone=(etype == "milestone"),
+        )
+
+
+def seed_relationships() -> None:
+    """Create starter relationships between pre-seeded entities."""
+    from world.entities import get_all_entities
+
+    entities = {e["name"]: e for e in get_all_entities()}
+    pairs = [
+        ("The Crystal Tree", "The Joke Dragon", "allied", "Allied after the Dragon's worst joke made the Tree laugh for three hours.", 3),
+        ("The Blind Cartographer", "The Joke Dragon", "owes_debt", "The Cartographer owes the Dragon a favor for mapping its cave.", 2),
+        ("The Fog Merchant", "The Silent Gear", "friends", "Bonded over the exchange of a memory of ticking.", 2),
+    ]
+
+    for name_a, name_b, rel_type, desc, strength in pairs:
+        a = entities.get(name_a)
+        b = entities.get(name_b)
+        if not a or not b:
+            continue
+
+        id_a, id_b = (a["id"], b["id"]) if a["id"] < b["id"] else (b["id"], a["id"])
+        with db_session() as conn:
+            existing = conn.execute(
+                "SELECT id FROM relationships WHERE entity_a_id = ? AND entity_b_id = ?",
+                (id_a, id_b),
+            ).fetchone()
+            if existing:
+                continue
+
+            conn.execute(
+                """
+                INSERT INTO relationships (
+                    entity_a_id, entity_b_id, relationship_type,
+                    description, strength, formed_on_day
+                ) VALUES (?, ?, ?, ?, ?, ?)
+                """,
+                (id_a, id_b, rel_type, desc, strength, 3),
+            )
+
+
+def main():
+    print("Initializing database...")
+    init_database()
+
+    with db_session() as conn:
+        seed_locations(conn)
+
+    print("Seeding starter entities...")
+    count = seed_starter_entities()
+    print(f"Created {count} starter entities.")
+
+    print("Seeding history...")
+    seed_history()
+
+    print("Seeding relationships...")
+    seed_relationships()
+
+    print("World seeded successfully!")
+    print("Run: python -m simulation.tick  (or python run_tick.py) to simulate.")
+
+
+if __name__ == "__main__":
+    main()

simulation/lifecycle.py

@@ -0,0 +1,74 @@
+"""Entity status transitions and special location effects."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+
+from world.book_of_ages import create_entry
+from world.database import db_session
+from world.entities import add_tag, update_entity_status
+from world.locations import get_location_by_id
+
+
+def process_lifecycle_updates(world_day: int) -> list[str]:
+    """Run lifecycle checks. Returns list of milestone messages."""
+    milestones = []
+
+    with db_session() as conn:
+        entities = conn.execute("SELECT * FROM entities").fetchall()
+
+    for row in entities:
+        entity = dict(row)
+        location = get_location_by_id(entity["location_id"])
+
+        if entity["status"] == "active":
+            last_active = datetime.fromisoformat(entity["last_active"])
+            if datetime.now() - last_active > timedelta(days=7):
+                update_entity_status(entity["id"], "dormant")
+                msg = f"{entity['name']} has grown quiet and entered dormancy."
+                create_entry(
+                    world_day=world_day,
+                    entry_type="milestone",
+                    content=msg,
+                    entity_ids=[entity["id"]],
+                    is_milestone=True,
+                    title="Dormancy",
+                )
+                milestones.append(msg)
+
+        if entity["status"] == "dormant":
+            last_active = datetime.fromisoformat(entity["last_active"])
+            days_dormant = (datetime.now() - last_active).days
+            if days_dormant >= 30:
+                update_entity_status(entity["id"], "legendary")
+                msg = f"{entity['name']} has become Legendary — woven into the Realm's foundation."
+                create_entry(
+                    world_day=world_day,
+                    entry_type="milestone",
+                    content=msg,
+                    entity_ids=[entity["id"]],
+                    is_milestone=True,
+                    title="Legendary Status",
+                )
+                milestones.append(msg)
+
+        if location and location["slug"] == "hollow-mountain":
+            if entity["days_in_realm"] >= 14 and not entity["wisdom_unlocked"]:
+                add_tag(entity["id"], "wise")
+                with db_session() as conn:
+                    conn.execute(
+                        "UPDATE entities SET wisdom_unlocked = 1 WHERE id = ?",
+                        (entity["id"],),
+                    )
+                msg = f"{entity['name']} earned wisdom in the Hollow Mountain."
+                create_entry(
+                    world_day=world_day,
+                    entry_type="milestone",
+                    content=msg,
+                    entity_ids=[entity["id"]],
+                    is_milestone=True,
+                    title="Wisdom Earned",
+                )
+                milestones.append(msg)
+
+    return milestones

simulation/tick.py

@@ -0,0 +1,224 @@
+"""Full simulation tick — the autonomous world engine."""
+
+from __future__ import annotations
+
+import json
+import random
+from collections import defaultdict
+from datetime import datetime
+
+from ai.events import generate_dream_fragment, generate_world_event, update_entity_memory
+from ai.interaction import generate_interaction
+from world.book_of_ages import create_entry
+from world.database import db_session
+from world.entities import (
+    get_active_entities,
+    increment_days_in_realm,
+    increment_interaction_count,
+    update_memory,
+)
+from world.events import create_interaction, create_world_event
+from world.locations import get_all_locations, get_location_by_id, update_entity_counts
+from world.relationships import upsert_relationship
+from simulation.lifecycle import process_lifecycle_updates
+
+
+EMBER_CROSSROADS_SLUG = "crossroads"
+
+
+def execute_simulation_tick() -> dict:
+    """Run one complete simulation tick. Returns summary."""
+    summary = {
+        "world_event": None,
+        "interactions": 0,
+        "memories_updated": 0,
+        "milestones": [],
+    }
+
+    with db_session() as conn:
+        world = conn.execute("SELECT * FROM world_state WHERE id = 1").fetchone()
+        world_day = world["current_day"]
+
+    increment_days_in_realm()
+
+    try:
+        event_result = generate_world_event(world_day)
+        event_id = create_world_event(event_result.model_dump(), world_day)
+        create_entry(
+            world_day=world_day,
+            entry_type="world_event",
+            content=event_result.book_of_ages_entry,
+            title=event_result.title,
+            is_milestone=False,
+        )
+        summary["world_event"] = event_result.title
+        current_event = {
+            "title": event_result.title,
+            "description": event_result.description,
+            "affected_locations": event_result.affected_locations,
+        }
+    except Exception as e:
+        current_event = None
+        summary["world_event"] = f"failed: {e}"
+
+    active_entities = get_active_entities()
+    entities_by_location = defaultdict(list)
+    for e in active_entities:
+        entities_by_location[e["location_id"]].append(e)
+
+    pairs = _select_interaction_pairs(entities_by_location, num_pairs=random.randint(2, 4))
+    interacted_entities: dict[str, list[str]] = defaultdict(list)
+
+    for entity_a, entity_b in pairs:
+        if entity_a["id"] == entity_b["id"]:
+            continue
+
+        location = get_location_by_id(entity_a["location_id"])
+        if not location:
+            continue
+
+        try:
+            result = generate_interaction(entity_a, entity_b, location, current_event)
+
+            create_interaction(
+                entity_a["id"],
+                entity_b["id"],
+                location["id"],
+                result.model_dump(),
+                world_day,
+            )
+
+            create_entry(
+                world_day=world_day,
+                entry_type="interaction",
+                content=result.book_of_ages_entry,
+                entity_ids=[entity_a["id"], entity_b["id"]],
+                location_id=location["id"],
+            )
+
+            upsert_relationship(
+                entity_a["id"],
+                entity_b["id"],
+                result.relationship_change,
+                result.new_relationship_description,
+                world_day,
+            )
+
+            increment_interaction_count(entity_a["id"])
+            increment_interaction_count(entity_b["id"])
+
+            interacted_entities[entity_a["id"]].append(result.entity_a_memory_addition)
+            interacted_entities[entity_b["id"]].append(result.entity_b_memory_addition)
+
+            summary["interactions"] += 1
+        except Exception:
+            continue
+
+    for entity_id, memory_additions in interacted_entities.items():
+        from world.entities import get_entity
+        entity = get_entity(entity_id)
+        if not entity:
+            continue
+
+        world_events_for_entity = []
+        if current_event and entity:
+            loc = get_location_by_id(entity["location_id"])
+            if loc and loc["name"] in (current_event.get("affected_locations") or []):
+                world_events_for_entity.append(current_event["description"])
+
+        try:
+            new_memory = update_entity_memory(
+                entity,
+                memory_additions,
+                world_events_for_entity,
+            )
+            update_memory(entity_id, new_memory)
+            summary["memories_updated"] += 1
+        except Exception:
+            pass
+
+    _process_dream_fragments(world_day)
+    milestones = process_lifecycle_updates(world_day)
+    summary["milestones"] = milestones
+
+    with db_session() as conn:
+        conn.execute(
+            """
+            UPDATE world_state SET
+                current_day = current_day + 1,
+                last_simulation_run = ?,
+                updated_at = datetime('now')
+            WHERE id = 1
+            """,
+            (datetime.now().isoformat(),),
+        )
+
+    update_entity_counts()
+
+    try:
+        from persistence.backup import backup_database
+        backup_database()
+    except Exception:
+        pass
+
+    return summary
+
+
+def _select_interaction_pairs(
+    entities_by_location: dict,
+    num_pairs: int = 3,
+) -> list[tuple]:
+    locations = get_all_locations()
+    slug_to_id = {loc["slug"]: loc["id"] for loc in locations}
+
+    candidates = []
+    for loc_id, entities in entities_by_location.items():
+        if len(entities) < 2:
+            continue
+        loc = next((l for l in locations if l["id"] == loc_id), None)
+        weight = loc["interaction_multiplier"] if loc else 1.0
+        candidates.append((loc_id, entities, weight))
+
+    if not candidates:
+        return []
+
+    selected_pairs = []
+    weights = [c[2] for c in candidates]
+
+    for _ in range(num_pairs):
+        chosen = random.choices(candidates, weights=weights, k=1)[0]
+        _, entities, _ = chosen
+        a, b = random.sample(entities, 2)
+        selected_pairs.append((a, b))
+
+    return selected_pairs
+
+
+def _process_dream_fragments(world_day: int) -> None:
+    with db_session() as conn:
+        rows = conn.execute(
+            """
+            SELECT e.* FROM entities e
+            JOIN locations l ON e.location_id = l.id
+            WHERE e.status = 'dormant' AND l.slug = 'valley'
+            """
+        ).fetchall()
+
+    for row in rows:
+        entity = dict(row)
+        entity["personality_traits"] = json.loads(entity["personality_traits"])
+        last_active = datetime.fromisoformat(entity["last_active"])
+        days_dormant = (datetime.now() - last_active).days
+
+        if days_dormant >= 7 and random.random() < 0.3:
+            try:
+                fragment = generate_dream_fragment(entity, days_dormant)
+                content = f'*From the dreams of {entity["name"]}: {fragment}*'
+                create_entry(
+                    world_day=world_day,
+                    entry_type="dream_fragment",
+                    content=content,
+                    entity_ids=[entity["id"]],
+                )
+            except Exception:
+                pass

ui/book_display.py

@@ -0,0 +1,121 @@
+"""Book of Ages HTML renderer."""
+
+from __future__ import annotations
+
+from world.book_of_ages import get_entries
+
+ENTRY_TYPE_LABELS = {
+    "arrival": "Arrival",
+    "interaction": "Interaction",
+    "world_event": "World Event",
+    "milestone": "Milestone",
+    "dream_fragment": "Dream",
+}
+
+ENTRY_TYPE_CLASSES = {
+    "arrival": "entry-arrival",
+    "interaction": "entry-interaction",
+    "world_event": "entry-event",
+    "milestone": "entry-milestone",
+    "dream_fragment": "entry-dream",
+}
+
+
+def render_book_of_ages(
+    entry_type: str = "all",
+    search: str = "",
+    limit: int = 40,
+) -> str:
+    entries = get_entries(limit=limit, entry_type=entry_type if entry_type != "all" else None, search=search or None)
+
+    if not entries:
+        return """
+        <div class="book-container">
+            <div class="book-header">
+                <h2 class="book-title">Book of Ages</h2>
+                <p class="book-subtitle">The permanent record of the Realm</p>
+            </div>
+            <div class="empty-state">No entries yet. The first arrival will be recorded here.</div>
+        </div>
+        """
+
+    current_day = None
+    parts = [
+        '<div class="book-container">',
+        '<div class="book-header">',
+        '<h2 class="book-title">Book of Ages</h2>',
+        '<p class="book-subtitle">Every creation, encounter, and event — remembered forever</p>',
+        "</div>",
+        '<div class="book-entries">',
+    ]
+
+    for entry in entries:
+        if entry["world_day"] != current_day:
+            current_day = entry["world_day"]
+            parts.append(f'<div class="book-day-header">Day {current_day}</div>')
+
+        type_label = ENTRY_TYPE_LABELS.get(entry["entry_type"], entry["entry_type"])
+        type_class = ENTRY_TYPE_CLASSES.get(entry["entry_type"], "")
+        milestone_class = " entry-milestone-flag" if entry["is_milestone"] else ""
+        title_html = ""
+        if entry.get("title"):
+            title_html = f'<span class="entry-title">{entry["title"]}: </span>'
+
+        content = entry["content"]
+        if entry["entry_type"] == "dream_fragment":
+            content = f'<em>{content}</em>'
+
+        parts.append(f"""
+        <div class="book-entry {type_class}{milestone_class}">
+            <span class="entry-type-badge">{type_label}</span>
+            <p class="entry-content">{title_html}{content}</p>
+        </div>
+        """)
+
+    parts.append("</div></div>")
+    return "\n".join(parts)
+
+
+def render_activity_feed(limit: int = 5) -> str:
+    entries = get_entries(limit=limit)
+
+    if not entries:
+        return '<p class="feed-empty">The Realm is quiet. Be the first to summon something.</p>'
+
+    parts = ['<div class="activity-feed">']
+    for entry in entries[:limit]:
+        type_class = ENTRY_TYPE_CLASSES.get(entry["entry_type"], "")
+        parts.append(f"""
+        <div class="feed-item {type_class}">
+            <span class="feed-day">Day {entry['world_day']}</span>
+            <p class="feed-content">{entry['content']}</p>
+        </div>
+        """)
+    parts.append("</div>")
+    return "\n".join(parts)
+
+
+def render_current_event() -> str:
+    from world.events import get_active_world_event
+    event = get_active_world_event()
+
+    if not event:
+        return """
+        <div class="current-event">
+            <h3 class="event-label">Today in the Realm</h3>
+            <p class="event-text">The world breathes quietly. Something will happen soon.</p>
+        </div>
+        """
+
+    locations = ", ".join(event.get("affected_locations", [])[:2])
+    if len(event.get("affected_locations", [])) > 2:
+        locations += "…"
+
+    return f"""
+    <div class="current-event event-active">
+        <h3 class="event-label">Today in the Realm</h3>
+        <h4 class="event-title">{event['title']}</h4>
+        <p class="event-text">{event['description']}</p>
+        {f'<p class="event-locations">Affecting: {locations}</p>' if locations else ''}
+    </div>
+    """

ui/entity_card.py

@@ -0,0 +1,118 @@
+"""Entity profile HTML component."""
+
+from __future__ import annotations
+
+from world.locations import get_location_by_id
+
+
+TYPE_LABELS = {
+    "character": "Character",
+    "creature": "Creature",
+    "object": "Object",
+    "place": "Place",
+}
+
+STATUS_LABELS = {
+    "active": "Active",
+    "dormant": "Dormant",
+    "legendary": "Legendary",
+}
+
+
+def render_entity_card(entity: dict) -> str:
+    location = get_location_by_id(entity["location_id"])
+    loc_name = location["name"].replace("The ", "") if location else "Unknown"
+    type_label = TYPE_LABELS.get(entity["type"], entity["type"].title())
+    status = STATUS_LABELS.get(entity["status"], entity["status"].title())
+    status_class = f"status-{entity['status']}"
+
+    traits_html = "".join(
+        f'<span class="trait-tag">{t}</span>' for t in entity["personality_traits"]
+    )
+
+    tags_html = ""
+    if entity.get("tags"):
+        tags_html = "".join(
+            f'<span class="entity-tag">{t}</span>' for t in entity["tags"]
+        )
+
+    secret_html = ""
+    if entity.get("secret_name"):
+        secret_html = f"""
+        <div class="entity-section secret-section">
+            <div class="section-label">Secret Name <span class="sea-whisper">(only the Sea knows)</span></div>
+            <p class="secret-name">{entity['secret_name']}</p>
+        </div>
+        """
+
+    memory = entity["memory_summary"] or "Nothing yet — they just arrived."
+    rel_count = entity.get("relationship_count", 0)
+    int_count = entity.get("interaction_count", 0)
+
+    return f"""
+    <div class="entity-card">
+        <div class="entity-header">
+            <div class="entity-meta">
+                <span class="entity-type">{type_label} ▸ {loc_name}</span>
+                <span class="entity-status {status_class}">Day {entity['days_in_realm']} · {status}</span>
+            </div>
+            <h2 class="entity-name">{entity['name']}</h2>
+            {f'<div class="entity-tags">{tags_html}</div>' if tags_html else ''}
+        </div>
+
+        <div class="entity-appearance">{entity['appearance']}</div>
+
+        <div class="entity-traits">{traits_html}</div>
+
+        <div class="entity-section">
+            <div class="section-label">Seeks</div>
+            <p>{entity['primary_goal']}</p>
+        </div>
+
+        <div class="entity-section secret-goal">
+            <div class="section-label">Secretly</div>
+            <p>{entity['secondary_goal']}</p>
+        </div>
+
+        <div class="entity-section">
+            <div class="section-label">Fears</div>
+            <p>{entity['primary_fear']}</p>
+        </div>
+
+        <blockquote class="entity-greeting">"{entity['greeting']}"</blockquote>
+
+        {secret_html}
+
+        <div class="entity-section memory-section">
+            <div class="section-label">What They Remember</div>
+            <p class="memory-text">{memory}</p>
+        </div>
+
+        <div class="entity-footer">
+            {rel_count} relationships · {int_count} encounters
+        </div>
+    </div>
+    """
+
+
+def render_entity_grid(entities: list[dict]) -> str:
+    if not entities:
+        return '<div class="empty-state">The Realm waits for its first arrivals.</div>'
+
+    cards = []
+    for entity in entities:
+        location = get_location_by_id(entity["location_id"])
+        loc_short = location["name"].replace("The ", "")[:20] if location else "?"
+        status_class = f"grid-status-{entity['status']}"
+
+        cards.append(f"""
+        <div class="entity-grid-card {status_class}" data-entity-id="{entity['id']}">
+            <div class="grid-card-type">{entity['type']}</div>
+            <h3 class="grid-card-name">{entity['display_name']}</h3>
+            <p class="grid-card-location">{loc_short}</p>
+            <p class="grid-card-preview">{entity['appearance'][:120]}…</p>
+            <div class="grid-card-meta">Day {entity['days_in_realm']} · {entity['status']}</div>
+        </div>
+        """)
+
+    return f'<div class="entity-grid">{"".join(cards)}</div>'

ui/map.py

@@ -0,0 +1,135 @@
+"""SVG world map generator."""
+
+from __future__ import annotations
+
+import json
+
+from world.entities import get_entities_by_location
+from world.events import get_active_world_event
+from world.locations import get_all_locations
+
+
+ENTITY_TYPE_COLORS = {
+    "character": "#c8a040",
+    "creature": "#8b2020",
+    "object": "#a0a8b8",
+    "place": "#406040",
+}
+
+LOCATION_PATHS = [
+    "M 120,120 Q 200,80 400,60 Q 500,50 640,90",
+    "M 120,120 Q 100,200 160,300 Q 200,400 200,480",
+    "M 640,90 Q 600,200 640,330",
+    "M 400,60 Q 400,200 400,300",
+    "M 400,300 Q 300,350 200,480",
+    "M 400,300 Q 500,350 600,480",
+    "M 400,300 Q 450,280 640,330",
+    "M 200,480 Q 400,450 600,480",
+]
+
+
+def render_world_map(selected_location_id: int | None = None) -> str:
+    locations = get_all_locations()
+    active_event = get_active_world_event()
+    affected_slugs = set()
+    if active_event:
+        from world.seed_data import LOCATION_NAME_TO_SLUG
+        for name in active_event.get("affected_locations", []):
+            slug = LOCATION_NAME_TO_SLUG.get(name, name)
+            affected_slugs.add(slug)
+
+    svg_parts = [
+        '<svg viewBox="0 0 800 600" xmlns="http://www.w3.org/2000/svg" class="realm-map">',
+        "<defs>",
+        '<filter id="glow" x="-50%" y="-50%" width="200%" height="200%">',
+        '<feGaussianBlur stdDeviation="4" result="blur"/>',
+        '<feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>',
+        "</filter>",
+        '<filter id="pulse-glow" x="-100%" y="-100%" width="300%" height="300%">',
+        '<feGaussianBlur stdDeviation="8" result="blur"/>',
+        '<feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>',
+        "</filter>",
+        '<radialGradient id="skyGradient" cx="50%" cy="30%" r="70%">',
+        '<stop offset="0%" stop-color="#12121f"/>',
+        '<stop offset="100%" stop-color="#0a0a12"/>',
+        "</radialGradient>",
+        "</defs>",
+        '<rect width="800" height="600" fill="url(#skyGradient)"/>',
+    ]
+
+    for i in range(40):
+        import random
+        random.seed(i * 7)
+        cx = random.randint(20, 780)
+        cy = random.randint(20, 580)
+        r = random.uniform(0.5, 1.5)
+        svg_parts.append(
+            f'<circle cx="{cx}" cy="{cy}" r="{r}" fill="white" opacity="0.05"/>'
+        )
+
+    for path in LOCATION_PATHS:
+        svg_parts.append(
+            f'<path d="{path}" fill="none" stroke="rgba(200,160,64,0.08)" '
+            f'stroke-width="1.5" stroke-dasharray="4,6"/>'
+        )
+
+    for loc in locations:
+        x = loc["map_x"] / 100 * 800
+        y = loc["map_y"] / 100 * 600
+        is_affected = loc["slug"] in affected_slugs
+        is_selected = selected_location_id == loc["id"]
+        pulse_class = " location-pulse" if is_affected else ""
+        selected_class = " location-selected" if is_selected else ""
+
+        entities = get_entities_by_location(loc["id"], limit=6)
+        count = loc["entity_count"]
+
+        svg_parts.append(
+            f'<g class="location-node{pulse_class}{selected_class}" '
+            f'data-location-id="{loc["id"]}" transform="translate({x},{y})">'
+        )
+
+        filter_id = "pulse-glow" if is_affected else "glow"
+        svg_parts.append(
+            f'<circle r="32" fill="{loc["glow_color"]}" opacity="0.15" '
+            f'filter="url(#{filter_id})"/>'
+        )
+        svg_parts.append(
+            f'<circle r="28" fill="{loc["glow_color"]}" opacity="0.25" '
+            f'stroke="{loc["glow_color"]}" stroke-width="1.5" class="location-circle"/>'
+        )
+
+        svg_parts.append(
+            f'<text y="5" text-anchor="middle" class="location-count" '
+            f'fill="#e8e0d0" font-size="14" font-weight="bold">{count}</text>'
+        )
+
+        for i, entity in enumerate(entities[:5]):
+            import math
+            angle = (i / 5) * 2 * math.pi - math.pi / 2
+            dot_x = math.cos(angle) * 38
+            dot_y = math.sin(angle) * 38
+            color = ENTITY_TYPE_COLORS.get(entity["type"], "#c8a040")
+            svg_parts.append(
+                f'<circle cx="{dot_x:.1f}" cy="{dot_y:.1f}" r="5" fill="{color}" '
+                f'opacity="0.9" class="entity-dot">'
+                f'<title>{entity["name"]}</title></circle>'
+            )
+
+        if count > 5:
+            svg_parts.append(
+                f'<text x="42" y="-28" class="entity-overflow" '
+                f'fill="#a09880" font-size="10">+{count - 5}</text>'
+            )
+
+        short_name = loc["name"].replace("The ", "").split(" of ")[0]
+        if len(short_name) > 14:
+            short_name = short_name[:12] + "…"
+        svg_parts.append(
+            f'<text y="52" text-anchor="middle" class="location-label" '
+            f'fill="#a09880" font-size="9">{short_name}</text>'
+        )
+        svg_parts.append("</g>")
+
+    svg_parts.append("</svg>")
+    return "\n".join(svg_parts)

ui/styles.css

@@ -0,0 +1,574 @@
+@import url('https://fonts.googleapis.com/css2?family=Cinzel:wght@400;600&family=EB+Garamond:ital@0;1&family=Libre+Baskerville:ital@0;1&display=swap');
+
+:root {
+    --realm-bg-primary: #0a0a12;
+    --realm-bg-secondary: #111120;
+    --realm-bg-tertiary: #1a1a2e;
+    --realm-text-primary: #e8e0d0;
+    --realm-text-secondary: #a09880;
+    --realm-text-tertiary: #605848;
+    --realm-accent-gold: #c8a040;
+    --realm-accent-violet: #8060b0;
+    --realm-border: rgba(200, 160, 64, 0.15);
+    --realm-border-strong: rgba(200, 160, 64, 0.35);
+}
+
+/* Gradio overrides */
+.gradio-container {
+    background: var(--realm-bg-primary) !important;
+    max-width: 1400px !important;
+    font-family: system-ui, -apple-system, sans-serif !important;
+}
+
+.gradio-container .contain {
+    background: transparent !important;
+}
+
+footer { display: none !important; }
+
+/* Header */
+.realm-header {
+    text-align: center;
+    padding: 2rem 1rem 1.5rem;
+    border-bottom: 1px solid var(--realm-border);
+    margin-bottom: 1.5rem;
+    background: linear-gradient(180deg, rgba(200,160,64,0.03) 0%, transparent 100%);
+}
+
+.realm-title {
+    font-family: 'Cinzel', serif;
+    font-size: 2.2rem;
+    font-weight: 600;
+    color: var(--realm-accent-gold);
+    letter-spacing: 0.15em;
+    text-transform: uppercase;
+    margin: 0 0 0.5rem;
+    text-shadow: 0 0 40px rgba(200, 160, 64, 0.2);
+}
+
+.realm-subtitle {
+    font-family: 'EB Garamond', serif;
+    font-style: italic;
+    color: var(--realm-text-secondary);
+    font-size: 1.1rem;
+    margin: 0 0 1rem;
+}
+
+.realm-stats {
+    font-size: 0.85rem;
+    color: var(--realm-text-tertiary);
+    letter-spacing: 0.05em;
+}
+
+.realm-myth {
+    font-family: 'EB Garamond', serif;
+    font-style: italic;
+    color: var(--realm-text-secondary);
+    font-size: 0.95rem;
+    max-width: 700px;
+    margin: 1rem auto 0;
+    line-height: 1.6;
+    opacity: 0.8;
+}
+
+/* Tabs */
+.realm-tabs {
+    border-bottom: 1px solid var(--realm-border) !important;
+}
+
+.realm-tabs button {
+    font-family: 'Cinzel', serif !important;
+    letter-spacing: 0.1em !important;
+    color: var(--realm-text-secondary) !important;
+    background: transparent !important;
+    border: none !important;
+}
+
+.realm-tabs button.selected {
+    color: var(--realm-accent-gold) !important;
+    border-bottom: 2px solid var(--realm-accent-gold) !important;
+}
+
+/* Map */
+.realm-map {
+    width: 100%;
+    height: auto;
+    border-radius: 8px;
+    background: var(--realm-bg-secondary);
+    border: 1px solid var(--realm-border);
+}
+
+.location-circle {
+    transition: opacity 0.3s, transform 0.3s;
+    cursor: pointer;
+}
+
+.location-node:hover .location-circle {
+    opacity: 0.5 !important;
+    transform: scale(1.08);
+}
+
+.location-pulse .location-circle {
+    animation: pulse-glow 2.5s ease-in-out infinite;
+}
+
+.location-selected .location-circle {
+    stroke-width: 3 !important;
+    opacity: 0.6 !important;
+}
+
+@keyframes pulse-glow {
+    0%, 100% { opacity: 0.25; }
+    50% { opacity: 0.55; }
+}
+
+.entity-dot {
+    animation: fade-in-scale 0.6s ease-out;
+}
+
+@keyframes fade-in-scale {
+    from { opacity: 0; transform: scale(0.5); }
+    to { opacity: 0.9; transform: scale(1); }
+}
+
+/* Activity feed */
+.activity-feed { padding: 0.5rem 0; }
+
+.feed-item {
+    padding: 0.75rem 0;
+    border-bottom: 1px solid var(--realm-border);
+    animation: slide-up 0.4s ease-out;
+}
+
+.feed-day {
+    font-size: 0.7rem;
+    color: var(--realm-accent-gold);
+    text-transform: uppercase;
+    letter-spacing: 0.1em;
+}
+
+.feed-content {
+    color: var(--realm-text-primary);
+    font-family: 'EB Garamond', serif;
+    font-size: 0.95rem;
+    margin: 0.25rem 0 0;
+    line-height: 1.5;
+}
+
+@keyframes slide-up {
+    from { opacity: 0; transform: translateY(10px); }
+    to { opacity: 1; transform: translateY(0); }
+}
+
+/* Current event */
+.current-event {
+    background: var(--realm-bg-tertiary);
+    border: 1px solid var(--realm-border);
+    border-radius: 8px;
+    padding: 1.25rem;
+    margin-bottom: 1rem;
+}
+
+.event-active {
+    border-color: var(--realm-border-strong);
+    box-shadow: 0 0 20px rgba(200, 160, 64, 0.05);
+}
+
+.event-label {
+    font-family: 'Cinzel', serif;
+    font-size: 0.75rem;
+    letter-spacing: 0.15em;
+    text-transform: uppercase;
+    color: var(--realm-accent-gold);
+    margin: 0 0 0.5rem;
+}
+
+.event-title {
+    font-family: 'Libre Baskerville', serif;
+    color: var(--realm-text-primary);
+    font-size: 1.1rem;
+    margin: 0 0 0.5rem;
+}
+
+.event-text {
+    font-family: 'EB Garamond', serif;
+    color: var(--realm-text-secondary);
+    line-height: 1.6;
+    margin: 0;
+}
+
+.event-locations {
+    font-size: 0.8rem;
+    color: var(--realm-text-tertiary);
+    margin: 0.5rem 0 0;
+}
+
+/* Summon form */
+.summon-section {
+    background: var(--realm-bg-secondary);
+    border: 1px solid var(--realm-border);
+    border-radius: 8px;
+    padding: 1.5rem;
+    margin-top: 1rem;
+}
+
+.summon-title {
+    font-family: 'Cinzel', serif;
+    color: var(--realm-accent-gold);
+    font-size: 0.85rem;
+    letter-spacing: 0.12em;
+    text-transform: uppercase;
+    margin: 0 0 1rem;
+}
+
+.summon-hint {
+    font-family: 'EB Garamond', serif;
+    font-style: italic;
+    color: var(--realm-text-tertiary);
+    font-size: 0.85rem;
+    margin-top: 0.75rem;
+}
+
+/* Entity card */
+.entity-card {
+    background: var(--realm-bg-secondary);
+    border: 1px solid var(--realm-border);
+    border-radius: 8px;
+    padding: 1.5rem;
+    animation: fade-in-scale 0.5s ease-out;
+}
+
+.entity-header { margin-bottom: 1rem; }
+
+.entity-meta {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: 0.5rem;
+}
+
+.entity-type {
+    font-size: 0.75rem;
+    color: var(--realm-text-tertiary);
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+}
+
+.entity-status {
+    font-size: 0.75rem;
+    padding: 0.2rem 0.6rem;
+    border-radius: 12px;
+    background: rgba(200, 160, 64, 0.1);
+    color: var(--realm-accent-gold);
+}
+
+.status-dormant { background: rgba(96, 88, 72, 0.2); color: var(--realm-text-secondary); }
+.status-legendary { background: rgba(128, 96, 176, 0.2); color: var(--realm-accent-violet); }
+
+.entity-name {
+    font-family: 'Libre Baskerville', serif;
+    color: var(--realm-text-primary);
+    font-size: 1.5rem;
+    margin: 0;
+}
+
+.entity-appearance {
+    font-family: 'EB Garamond', serif;
+    color: var(--realm-text-secondary);
+    line-height: 1.7;
+    margin-bottom: 1rem;
+    font-size: 1rem;
+}
+
+.entity-traits {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.4rem;
+    margin-bottom: 1rem;
+}
+
+.trait-tag, .entity-tag {
+    font-size: 0.7rem;
+    padding: 0.2rem 0.6rem;
+    border-radius: 12px;
+    background: rgba(200, 160, 64, 0.08);
+    color: var(--realm-text-secondary);
+    border: 1px solid var(--realm-border);
+}
+
+.entity-section {
+    margin-bottom: 0.75rem;
+}
+
+.section-label {
+    font-family: 'Cinzel', serif;
+    font-size: 0.65rem;
+    letter-spacing: 0.15em;
+    text-transform: uppercase;
+    color: var(--realm-accent-gold);
+    margin-bottom: 0.25rem;
+}
+
+.entity-section p {
+    font-family: 'EB Garamond', serif;
+    color: var(--realm-text-primary);
+    margin: 0;
+    line-height: 1.5;
+}
+
+.secret-goal .section-label { color: var(--realm-accent-violet); }
+
+.entity-greeting {
+    font-family: 'Libre Baskerville', serif;
+    font-style: italic;
+    color: var(--realm-accent-gold);
+    opacity: 0.9;
+    border-left: 2px solid var(--realm-border-strong);
+    padding: 0.75rem 1rem;
+    margin: 1rem 0;
+    background: rgba(200, 160, 64, 0.03);
+}
+
+.secret-section {
+    background: rgba(112, 144, 176, 0.05);
+    border: 1px solid rgba(112, 144, 176, 0.15);
+    border-radius: 6px;
+    padding: 0.75rem;
+}
+
+.sea-whisper { color: var(--realm-text-tertiary); font-size: 0.6rem; }
+.secret-name { font-style: italic; color: #7090b0 !important; }
+
+.memory-section {
+    border-top: 1px solid var(--realm-border);
+    padding-top: 0.75rem;
+    margin-top: 0.75rem;
+}
+
+.memory-text { color: var(--realm-text-secondary) !important; }
+
+.entity-footer {
+    font-size: 0.75rem;
+    color: var(--realm-text-tertiary);
+    margin-top: 1rem;
+    padding-top: 0.75rem;
+    border-top: 1px solid var(--realm-border);
+}
+
+/* Location panel */
+.location-panel {
+    background: var(--realm-bg-tertiary);
+    border: 1px solid var(--realm-border);
+    border-radius: 8px;
+    padding: 1.25rem;
+    animation: slide-up 0.3s ease-out;
+}
+
+.location-panel-name {
+    font-family: 'Cinzel', serif;
+    color: var(--realm-accent-gold);
+    font-size: 1.1rem;
+    margin: 0 0 0.5rem;
+}
+
+.location-panel-desc {
+    font-family: 'EB Garamond', serif;
+    color: var(--realm-text-secondary);
+    font-size: 0.9rem;
+    line-height: 1.5;
+    margin: 0 0 1rem;
+}
+
+.location-entity-list {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem;
+}
+
+.location-entity-chip {
+    font-size: 0.8rem;
+    padding: 0.35rem 0.75rem;
+    background: rgba(200, 160, 64, 0.08);
+    border: 1px solid var(--realm-border);
+    border-radius: 16px;
+    color: var(--realm-text-primary);
+    cursor: pointer;
+    transition: background 0.2s;
+}
+
+.location-entity-chip:hover {
+    background: rgba(200, 160, 64, 0.15);
+    border-color: var(--realm-border-strong);
+}
+
+/* Book of Ages */
+.book-container {
+    background: var(--realm-bg-secondary);
+    border: 1px solid var(--realm-border);
+    border-radius: 8px;
+    padding: 2rem;
+    max-height: 70vh;
+    overflow-y: auto;
+}
+
+.book-title {
+    font-family: 'Cinzel', serif;
+    color: var(--realm-accent-gold);
+    font-size: 1.5rem;
+    letter-spacing: 0.1em;
+    margin: 0;
+}
+
+.book-subtitle {
+    font-family: 'EB Garamond', serif;
+    font-style: italic;
+    color: var(--realm-text-tertiary);
+    margin: 0.25rem 0 1.5rem;
+}
+
+.book-day-header {
+    font-family: 'Cinzel', serif;
+    color: var(--realm-accent-gold);
+    font-size: 0.9rem;
+    letter-spacing: 0.12em;
+    padding: 1rem 0 0.5rem;
+    border-bottom: 1px solid var(--realm-border);
+    margin-bottom: 0.75rem;
+}
+
+.book-entry {
+    padding: 0.6rem 0;
+    border-bottom: 1px solid rgba(200, 160, 64, 0.05);
+    animation: slide-up 0.4s ease-out;
+}
+
+.entry-type-badge {
+    font-size: 0.6rem;
+    text-transform: uppercase;
+    letter-spacing: 0.1em;
+    padding: 0.15rem 0.5rem;
+    border-radius: 8px;
+    margin-right: 0.5rem;
+    vertical-align: middle;
+}
+
+.entry-arrival .entry-type-badge { background: rgba(200,160,64,0.15); color: var(--realm-accent-gold); }
+.entry-interaction .entry-type-badge { background: rgba(128,96,176,0.15); color: var(--realm-accent-violet); }
+.entry-event .entry-type-badge { background: rgba(176,96,32,0.15); color: #b06020; }
+.entry-milestone .entry-type-badge { background: rgba(192,64,32,0.15); color: #c04020; }
+.entry-dream .entry-type-badge { background: rgba(64,80,64,0.15); color: #608060; }
+
+.entry-content {
+    font-family: 'EB Garamond', serif;
+    color: var(--realm-text-primary);
+    font-size: 1rem;
+    line-height: 1.6;
+    margin: 0.25rem 0 0;
+    display: inline;
+}
+
+.entry-title { color: var(--realm-accent-gold); }
+
+/* Entity grid */
+.entity-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+    gap: 1rem;
+}
+
+.entity-grid-card {
+    background: var(--realm-bg-secondary);
+    border: 1px solid var(--realm-border);
+    border-radius: 8px;
+    padding: 1.25rem;
+    cursor: pointer;
+    transition: border-color 0.2s, transform 0.2s;
+}
+
+.entity-grid-card:hover {
+    border-color: var(--realm-border-strong);
+    transform: translateY(-2px);
+}
+
+.grid-card-type {
+    font-size: 0.65rem;
+    text-transform: uppercase;
+    letter-spacing: 0.1em;
+    color: var(--realm-text-tertiary);
+}
+
+.grid-card-name {
+    font-family: 'Libre Baskerville', serif;
+    color: var(--realm-text-primary);
+    font-size: 1.1rem;
+    margin: 0.25rem 0;
+}
+
+.grid-card-location {
+    font-size: 0.75rem;
+    color: var(--realm-accent-gold);
+    margin: 0 0 0.5rem;
+}
+
+.grid-card-preview {
+    font-family: 'EB Garamond', serif;
+    color: var(--realm-text-secondary);
+    font-size: 0.85rem;
+    line-height: 1.5;
+    margin: 0;
+}
+
+.grid-card-meta {
+    font-size: 0.7rem;
+    color: var(--realm-text-tertiary);
+    margin-top: 0.75rem;
+}
+
+.grid-status-legendary { border-color: rgba(128, 96, 176, 0.3); }
+
+/* Empty & loading states */
+.empty-state {
+    font-family: 'EB Garamond', serif;
+    font-style: italic;
+    color: var(--realm-text-tertiary);
+    text-align: center;
+    padding: 3rem;
+}
+
+.feed-empty {
+    font-family: 'EB Garamond', serif;
+    font-style: italic;
+    color: var(--realm-text-tertiary);
+}
+
+/* Loading */
+.loading-constellation {
+    text-align: center;
+    padding: 2rem;
+    color: var(--realm-accent-gold);
+    font-family: 'Cinzel', serif;
+    letter-spacing: 0.2em;
+    animation: pulse-glow 2s ease-in-out infinite;
+}
+
+/* Error messages */
+.realm-error {
+    color: #c04040;
+    font-family: 'EB Garamond', serif;
+    padding: 0.75rem;
+    background: rgba(192, 64, 64, 0.08);
+    border: 1px solid rgba(192, 64, 64, 0.2);
+    border-radius: 6px;
+    margin-top: 0.5rem;
+}
+
+/* Sidebar panel */
+.sidebar-panel {
+    padding: 0.5rem;
+}
+
+/* Responsive */
+@media (max-width: 768px) {
+    .realm-title { font-size: 1.5rem; }
+    .entity-grid { grid-template-columns: 1fr; }
+}

world/book_of_ages.py

@@ -0,0 +1,103 @@
+"""Book of Ages history log operations."""
+
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+from world.database import db_session
+
+
+def create_entry(
+    world_day: int,
+    entry_type: str,
+    content: str,
+    entity_ids: list[str] | None = None,
+    location_id: int | None = None,
+    title: str | None = None,
+    is_milestone: bool = False,
+) -> int:
+    with db_session() as conn:
+        cursor = conn.execute(
+            """
+            INSERT INTO book_of_ages (
+                world_day, entry_type, title, content, entity_ids,
+                location_id, is_milestone
+            ) VALUES (?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                world_day,
+                entry_type,
+                title,
+                content,
+                json.dumps(entity_ids or []),
+                location_id,
+                1 if is_milestone else 0,
+            ),
+        )
+        return cursor.lastrowid
+
+
+def get_entries(
+    limit: int = 50,
+    entry_type: str | None = None,
+    search: str | None = None,
+) -> list[dict]:
+    with db_session() as conn:
+        query = "SELECT * FROM book_of_ages"
+        params: list = []
+        conditions = []
+
+        if entry_type and entry_type != "all":
+            conditions.append("entry_type = ?")
+            params.append(entry_type)
+
+        if search:
+            conditions.append("content LIKE ?")
+            params.append(f"%{search}%")
+
+        if conditions:
+            query += " WHERE " + " AND ".join(conditions)
+
+        query += " ORDER BY world_day DESC, id DESC LIMIT ?"
+        params.append(limit)
+
+        rows = conn.execute(query, params).fetchall()
+        return [_row_to_dict(r) for r in rows]
+
+
+def get_entries_by_day(world_day: int) -> list[dict]:
+    with db_session() as conn:
+        rows = conn.execute(
+            "SELECT * FROM book_of_ages WHERE world_day = ? ORDER BY id",
+            (world_day,),
+        ).fetchall()
+        return [_row_to_dict(r) for r in rows]
+
+
+def get_entries_for_entity(entity_id: str) -> list[dict]:
+    with db_session() as conn:
+        rows = conn.execute(
+            "SELECT * FROM book_of_ages WHERE entity_ids LIKE ? ORDER BY world_day DESC",
+            (f'%"{entity_id}"%',),
+        ).fetchall()
+        return [_row_to_dict(r) for r in rows]
+
+
+def get_recent_arrivals(limit: int = 5) -> list[dict]:
+    with db_session() as conn:
+        rows = conn.execute(
+            """
+            SELECT * FROM book_of_ages
+            WHERE entry_type = 'arrival'
+            ORDER BY id DESC LIMIT ?
+            """,
+            (limit,),
+        ).fetchall()
+        return [_row_to_dict(r) for r in rows]
+
+
+def _row_to_dict(row) -> dict:
+    d = dict(row)
+    d["entity_ids"] = json.loads(d["entity_ids"])
+    return d

world/database.py

@@ -0,0 +1,196 @@
+"""SQLite database connection, schema initialization, and migrations."""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Generator
+
+DB_PATH = Path(os.environ.get("TTR_DB_PATH", "data/world.db"))
+
+SCHEMA_SQL = """
+PRAGMA journal_mode=WAL;
+PRAGMA foreign_keys=ON;
+PRAGMA synchronous=NORMAL;
+
+CREATE TABLE IF NOT EXISTS world_state (
+    id                 INTEGER PRIMARY KEY DEFAULT 1,
+    world_name         TEXT    NOT NULL DEFAULT 'Aether Garden',
+    founding_date      TEXT    NOT NULL,
+    current_day        INTEGER NOT NULL DEFAULT 1,
+    total_entities     INTEGER NOT NULL DEFAULT 0,
+    total_interactions INTEGER NOT NULL DEFAULT 0,
+    total_events       INTEGER NOT NULL DEFAULT 0,
+    last_simulation_run TEXT,
+    active_world_event TEXT,
+    updated_at         TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS locations (
+    id                   INTEGER PRIMARY KEY AUTOINCREMENT,
+    slug                 TEXT    NOT NULL UNIQUE,
+    name                 TEXT    NOT NULL,
+    short_description    TEXT    NOT NULL,
+    full_lore            TEXT    NOT NULL,
+    vibe_tags            TEXT    NOT NULL,
+    special_property     TEXT    NOT NULL,
+    aesthetic_description TEXT   NOT NULL,
+    map_x                REAL    NOT NULL,
+    map_y                REAL    NOT NULL,
+    glow_color           TEXT    NOT NULL,
+    entity_count         INTEGER NOT NULL DEFAULT 0,
+    interaction_multiplier REAL  NOT NULL DEFAULT 1.0
+);
+
+CREATE TABLE IF NOT EXISTS entities (
+    id                  TEXT    NOT NULL PRIMARY KEY,
+    name                TEXT    NOT NULL,
+    display_name        TEXT    NOT NULL,
+    type                TEXT    NOT NULL CHECK(type IN ('character','creature','object','place')),
+    input_description   TEXT    NOT NULL,
+    appearance          TEXT    NOT NULL,
+    backstory           TEXT    NOT NULL,
+    personality_traits  TEXT    NOT NULL,
+    primary_goal        TEXT    NOT NULL,
+    secondary_goal      TEXT    NOT NULL,
+    primary_fear        TEXT    NOT NULL,
+    speech_style        TEXT    NOT NULL,
+    greeting            TEXT    NOT NULL,
+    location_id         INTEGER NOT NULL REFERENCES locations(id),
+    created_at          TEXT    NOT NULL DEFAULT (datetime('now')),
+    created_by_session  TEXT,
+    days_in_realm       INTEGER NOT NULL DEFAULT 0,
+    memory_summary      TEXT    NOT NULL DEFAULT '',
+    relationship_count  INTEGER NOT NULL DEFAULT 0,
+    interaction_count   INTEGER NOT NULL DEFAULT 0,
+    last_active         TEXT    NOT NULL DEFAULT (datetime('now')),
+    status              TEXT    NOT NULL DEFAULT 'active'
+                        CHECK(status IN ('active','dormant','legendary')),
+    tags                TEXT    NOT NULL DEFAULT '[]',
+    secret_name         TEXT,
+    arrival_note        TEXT    NOT NULL,
+    wisdom_unlocked     INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE INDEX IF NOT EXISTS idx_entities_location ON entities(location_id);
+CREATE INDEX IF NOT EXISTS idx_entities_status   ON entities(status);
+CREATE INDEX IF NOT EXISTS idx_entities_created  ON entities(created_at);
+CREATE INDEX IF NOT EXISTS idx_entities_active   ON entities(last_active);
+
+CREATE TABLE IF NOT EXISTS relationships (
+    id                   INTEGER PRIMARY KEY AUTOINCREMENT,
+    entity_a_id          TEXT    NOT NULL REFERENCES entities(id),
+    entity_b_id          TEXT    NOT NULL REFERENCES entities(id),
+    relationship_type    TEXT    NOT NULL,
+    description          TEXT    NOT NULL,
+    strength             INTEGER NOT NULL DEFAULT 1 CHECK(strength BETWEEN 1 AND 5),
+    formed_at            TEXT    NOT NULL DEFAULT (datetime('now')),
+    formed_on_day        INTEGER NOT NULL DEFAULT 1,
+    last_interaction     TEXT    NOT NULL DEFAULT (datetime('now')),
+    UNIQUE(entity_a_id, entity_b_id),
+    CHECK(entity_a_id < entity_b_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_rel_a ON relationships(entity_a_id);
+CREATE INDEX IF NOT EXISTS idx_rel_b ON relationships(entity_b_id);
+
+CREATE TABLE IF NOT EXISTS interactions (
+    id               INTEGER PRIMARY KEY AUTOINCREMENT,
+    entity_a_id      TEXT    NOT NULL REFERENCES entities(id),
+    entity_b_id      TEXT    NOT NULL REFERENCES entities(id),
+    location_id      INTEGER NOT NULL REFERENCES locations(id),
+    interaction_type TEXT    NOT NULL,
+    description      TEXT    NOT NULL,
+    notable_outcome  TEXT,
+    book_of_ages_entry TEXT  NOT NULL,
+    timestamp        TEXT    NOT NULL DEFAULT (datetime('now')),
+    world_day        INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_int_timestamp ON interactions(timestamp);
+CREATE INDEX IF NOT EXISTS idx_int_a         ON interactions(entity_a_id);
+CREATE INDEX IF NOT EXISTS idx_int_b         ON interactions(entity_b_id);
+CREATE INDEX IF NOT EXISTS idx_int_day       ON interactions(world_day);
+
+CREATE TABLE IF NOT EXISTS world_events (
+    id                INTEGER PRIMARY KEY AUTOINCREMENT,
+    event_type        TEXT NOT NULL,
+    title             TEXT NOT NULL,
+    description       TEXT NOT NULL,
+    affected_locations TEXT NOT NULL,
+    entity_effect     TEXT NOT NULL,
+    book_of_ages_entry TEXT NOT NULL,
+    mystery_hook      TEXT,
+    timestamp         TEXT NOT NULL DEFAULT (datetime('now')),
+    world_day         INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_events_day ON world_events(world_day);
+
+CREATE TABLE IF NOT EXISTS book_of_ages (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    world_day   INTEGER NOT NULL,
+    entry_type  TEXT    NOT NULL CHECK(entry_type IN
+                ('arrival','interaction','world_event','milestone','dream_fragment')),
+    title       TEXT,
+    content     TEXT    NOT NULL,
+    entity_ids  TEXT    NOT NULL DEFAULT '[]',
+    location_id INTEGER REFERENCES locations(id),
+    timestamp   TEXT    NOT NULL DEFAULT (datetime('now')),
+    is_milestone INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE INDEX IF NOT EXISTS idx_boa_day  ON book_of_ages(world_day);
+CREATE INDEX IF NOT EXISTS idx_boa_type ON book_of_ages(entry_type);
+
+CREATE TABLE IF NOT EXISTS sessions (
+    session_id     TEXT NOT NULL PRIMARY KEY,
+    last_creation  TEXT,
+    creation_count INTEGER NOT NULL DEFAULT 0,
+    first_seen     TEXT    NOT NULL DEFAULT (datetime('now')),
+    last_seen      TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+"""
+
+
+def get_connection() -> sqlite3.Connection:
+    DB_PATH.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(DB_PATH, check_same_thread=False)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA foreign_keys=ON")
+    return conn
+
+
+@contextmanager
+def db_session() -> Generator[sqlite3.Connection, None, None]:
+    conn = get_connection()
+    try:
+        yield conn
+        conn.commit()
+    except Exception:
+        conn.rollback()
+        raise
+    finally:
+        conn.close()
+
+
+def init_database() -> None:
+    with db_session() as conn:
+        conn.executescript(SCHEMA_SQL)
+        row = conn.execute("SELECT id FROM world_state WHERE id = 1").fetchone()
+        if row is None:
+            conn.execute(
+                """
+                INSERT INTO world_state (id, founding_date, current_day)
+                VALUES (1, datetime('now'), 1)
+                """
+            )
+
+
+def get_world_state() -> dict:
+    with db_session() as conn:
+        row = conn.execute("SELECT * FROM world_state WHERE id = 1").fetchone()
+        return dict(row) if row else {}

world/entities.py

@@ -0,0 +1,248 @@
+"""Entity CRUD operations."""
+
+from __future__ import annotations
+
+import json
+import uuid
+from datetime import datetime, timedelta
+from typing import Optional
+
+from world.database import db_session
+from world.locations import get_location_by_name, update_entity_counts
+
+
+def create_entity(
+    entity_data: dict,
+    input_description: str,
+    session_id: str | None = None,
+) -> dict:
+    entity_id = str(uuid.uuid4())
+    location = get_location_by_name(entity_data["suggested_location"])
+    if not location:
+        raise ValueError(f"Unknown location: {entity_data['suggested_location']}")
+
+    secret_name = entity_data.get("secret_name")
+    if location["slug"] == "sea" and not secret_name:
+        secret_name = entity_data.get("secret_name_generated")
+
+    with db_session() as conn:
+        world_day = conn.execute(
+            "SELECT current_day FROM world_state WHERE id = 1"
+        ).fetchone()["current_day"]
+
+        conn.execute(
+            """
+            INSERT INTO entities (
+                id, name, display_name, type, input_description,
+                appearance, backstory, personality_traits,
+                primary_goal, secondary_goal, primary_fear,
+                speech_style, greeting, location_id, created_by_session,
+                arrival_note, secret_name, memory_summary, tags
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                entity_id,
+                entity_data["name"],
+                entity_data["display_name"],
+                entity_data["type"],
+                input_description,
+                entity_data["appearance"],
+                entity_data["backstory"],
+                json.dumps(entity_data["personality_traits"]),
+                entity_data["primary_goal"],
+                entity_data["secondary_goal"],
+                entity_data["primary_fear"],
+                entity_data["speech_style"],
+                entity_data["greeting"],
+                location["id"],
+                session_id,
+                entity_data["arrival_note"],
+                secret_name,
+                entity_data.get("memory_summary", ""),
+                json.dumps(entity_data.get("tags", [])),
+            ),
+        )
+
+        conn.execute(
+            """
+            UPDATE world_state SET
+                total_entities = total_entities + 1,
+                updated_at = datetime('now')
+            WHERE id = 1
+            """
+        )
+
+    update_entity_counts()
+    entity = get_entity(entity_id)
+    entity["world_day"] = world_day
+    return entity
+
+
+def get_entity(entity_id: str) -> Optional[dict]:
+    with db_session() as conn:
+        row = conn.execute(
+            "SELECT * FROM entities WHERE id = ?", (entity_id,)
+        ).fetchone()
+        return _row_to_dict(row) if row else None
+
+
+def get_entities_by_location(location_id: int, limit: int = 20) -> list[dict]:
+    with db_session() as conn:
+        rows = conn.execute(
+            """
+            SELECT * FROM entities WHERE location_id = ?
+            ORDER BY created_at DESC LIMIT ?
+            """,
+            (location_id, limit),
+        ).fetchall()
+        return [_row_to_dict(r) for r in rows]
+
+
+def get_active_entities() -> list[dict]:
+    with db_session() as conn:
+        rows = conn.execute(
+            "SELECT * FROM entities WHERE status = 'active' ORDER BY last_active DESC"
+        ).fetchall()
+        return [_row_to_dict(r) for r in rows]
+
+
+def get_all_entities(
+    location_id: int | None = None,
+    entity_type: str | None = None,
+    status: str | None = None,
+    search: str | None = None,
+    limit: int = 100,
+) -> list[dict]:
+    with db_session() as conn:
+        query = "SELECT * FROM entities WHERE 1=1"
+        params: list = []
+
+        if location_id:
+            query += " AND location_id = ?"
+            params.append(location_id)
+        if entity_type and entity_type != "all":
+            query += " AND type = ?"
+            params.append(entity_type)
+        if status and status != "all":
+            query += " AND status = ?"
+            params.append(status)
+        if search:
+            query += " AND (name LIKE ? OR display_name LIKE ? OR input_description LIKE ?)"
+            params.extend([f"%{search}%"] * 3)
+
+        query += " ORDER BY created_at DESC LIMIT ?"
+        params.append(limit)
+
+        rows = conn.execute(query, params).fetchall()
+        return [_row_to_dict(r) for r in rows]
+
+
+def update_memory(entity_id: str, memory_summary: str) -> None:
+    with db_session() as conn:
+        conn.execute(
+            "UPDATE entities SET memory_summary = ? WHERE id = ?",
+            (memory_summary, entity_id),
+        )
+
+
+def update_entity_status(entity_id: str, status: str) -> None:
+    with db_session() as conn:
+        conn.execute(
+            "UPDATE entities SET status = ? WHERE id = ?",
+            (status, entity_id),
+        )
+
+
+def increment_interaction_count(entity_id: str) -> None:
+    with db_session() as conn:
+        conn.execute(
+            """
+            UPDATE entities SET
+                interaction_count = interaction_count + 1,
+                last_active = datetime('now')
+            WHERE id = ?
+            """,
+            (entity_id,),
+        )
+
+
+def add_tag(entity_id: str, tag: str) -> None:
+    with db_session() as conn:
+        row = conn.execute(
+            "SELECT tags FROM entities WHERE id = ?", (entity_id,)
+        ).fetchone()
+        if not row:
+            return
+        tags = json.loads(row["tags"])
+        if tag not in tags:
+            tags.append(tag)
+            conn.execute(
+                "UPDATE entities SET tags = ? WHERE id = ?",
+                (json.dumps(tags), entity_id),
+            )
+
+
+def increment_days_in_realm() -> None:
+    with db_session() as conn:
+        conn.execute(
+            "UPDATE entities SET days_in_realm = days_in_realm + 1"
+        )
+
+
+def check_rate_limit(session_id: str, minutes: int = 10) -> tuple[bool, int]:
+    """Returns (allowed, minutes_remaining)."""
+    with db_session() as conn:
+        row = conn.execute(
+            "SELECT last_creation FROM sessions WHERE session_id = ?",
+            (session_id,),
+        ).fetchone()
+
+        if not row or not row["last_creation"]:
+            return True, 0
+
+        last = datetime.fromisoformat(row["last_creation"])
+        elapsed = datetime.now() - last
+        cooldown = timedelta(minutes=minutes)
+
+        if elapsed >= cooldown:
+            return True, 0
+
+        remaining = int((cooldown - elapsed).total_seconds() / 60) + 1
+        return False, remaining
+
+
+def record_creation(session_id: str) -> None:
+    with db_session() as conn:
+        existing = conn.execute(
+            "SELECT session_id FROM sessions WHERE session_id = ?",
+            (session_id,),
+        ).fetchone()
+
+        if existing:
+            conn.execute(
+                """
+                UPDATE sessions SET
+                    last_creation = datetime('now'),
+                    creation_count = creation_count + 1,
+                    last_seen = datetime('now')
+                WHERE session_id = ?
+                """,
+                (session_id,),
+            )
+        else:
+            conn.execute(
+                """
+                INSERT INTO sessions (session_id, last_creation, creation_count)
+                VALUES (?, datetime('now'), 1)
+                """,
+                (session_id,),
+            )
+
+
+def _row_to_dict(row) -> dict:
+    if row is None:
+        return {}
+    d = dict(row)
+    d["personality_traits"] = json.loads(d["personality_traits"])
+    d["tags"] = json.loads(d["tags"])
+    return d

world/events.py

@@ -0,0 +1,112 @@
+"""World event CRUD operations."""
+
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+from world.database import db_session
+
+
+def create_world_event(event_data: dict, world_day: int) -> int:
+    with db_session() as conn:
+        cursor = conn.execute(
+            """
+            INSERT INTO world_events (
+                event_type, title, description, affected_locations,
+                entity_effect, book_of_ages_entry, mystery_hook, world_day
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                event_data["event_type"],
+                event_data["title"],
+                event_data["description"],
+                json.dumps(event_data["affected_locations"]),
+                event_data["entity_effect"],
+                event_data["book_of_ages_entry"],
+                event_data.get("mystery_hook"),
+                world_day,
+            ),
+        )
+
+        conn.execute(
+            """
+            UPDATE world_state SET
+                total_events = total_events + 1,
+                active_world_event = ?,
+                updated_at = datetime('now')
+            WHERE id = 1
+            """,
+            (json.dumps({
+                "title": event_data["title"],
+                "description": event_data["description"],
+                "affected_locations": event_data["affected_locations"],
+            }),),
+        )
+
+        return cursor.lastrowid
+
+
+def get_recent_events(limit: int = 3) -> list[dict]:
+    with db_session() as conn:
+        rows = conn.execute(
+            "SELECT * FROM world_events ORDER BY id DESC LIMIT ?",
+            (limit,),
+        ).fetchall()
+        return [_row_to_dict(r) for r in rows]
+
+
+def get_active_world_event() -> Optional[dict]:
+    with db_session() as conn:
+        row = conn.execute(
+            "SELECT active_world_event FROM world_state WHERE id = 1"
+        ).fetchone()
+        if row and row["active_world_event"]:
+            return json.loads(row["active_world_event"])
+        return None
+
+
+def create_interaction(
+    entity_a_id: str,
+    entity_b_id: str,
+    location_id: int,
+    interaction_data: dict,
+    world_day: int,
+) -> int:
+    with db_session() as conn:
+        cursor = conn.execute(
+            """
+            INSERT INTO interactions (
+                entity_a_id, entity_b_id, location_id,
+                interaction_type, description, notable_outcome,
+                book_of_ages_entry, world_day
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                entity_a_id,
+                entity_b_id,
+                location_id,
+                interaction_data["interaction_type"],
+                interaction_data["description"],
+                interaction_data.get("notable_outcome"),
+                interaction_data["book_of_ages_entry"],
+                world_day,
+            ),
+        )
+
+        conn.execute(
+            """
+            UPDATE world_state SET
+                total_interactions = total_interactions + 1,
+                updated_at = datetime('now')
+            WHERE id = 1
+            """
+        )
+
+        return cursor.lastrowid
+
+
+def _row_to_dict(row) -> dict:
+    d = dict(row)
+    d["affected_locations"] = json.loads(d["affected_locations"])
+    return d

world/locations.py

@@ -0,0 +1,59 @@
+"""Location data and queries."""
+
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+from world.database import db_session
+
+
+def get_all_locations() -> list[dict]:
+    with db_session() as conn:
+        rows = conn.execute(
+            "SELECT * FROM locations ORDER BY id"
+        ).fetchall()
+        return [_row_to_dict(r) for r in rows]
+
+
+def get_location_by_slug(slug: str) -> Optional[dict]:
+    with db_session() as conn:
+        row = conn.execute(
+            "SELECT * FROM locations WHERE slug = ?", (slug,)
+        ).fetchone()
+        return _row_to_dict(row) if row else None
+
+
+def get_location_by_name(name: str) -> Optional[dict]:
+    with db_session() as conn:
+        row = conn.execute(
+            "SELECT * FROM locations WHERE name = ?", (name,)
+        ).fetchone()
+        return _row_to_dict(row) if row else None
+
+
+def get_location_by_id(location_id: int) -> Optional[dict]:
+    with db_session() as conn:
+        row = conn.execute(
+            "SELECT * FROM locations WHERE id = ?", (location_id,)
+        ).fetchone()
+        return _row_to_dict(row) if row else None
+
+
+def update_entity_counts() -> None:
+    with db_session() as conn:
+        conn.execute("UPDATE locations SET entity_count = 0")
+        conn.execute(
+            """
+            UPDATE locations SET entity_count = (
+                SELECT COUNT(*) FROM entities
+                WHERE entities.location_id = locations.id
+            )
+            """
+        )
+
+
+def _row_to_dict(row) -> dict:
+    d = dict(row)
+    d["vibe_tags"] = json.loads(d["vibe_tags"])
+    return d

world/relationships.py

@@ -0,0 +1,145 @@
+"""Relationship CRUD operations."""
+
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+from world.database import db_session
+
+
+RELATIONSHIP_MAP = {
+    "new_ally": "allied",
+    "new_friend": "friends",
+    "new_rival": "rivals",
+    "new_enemy": "enemies",
+    "new_mentor_a_to_b": "mentor",
+    "new_mentor_b_to_a": "mentor",
+    "new_debt_a_owes_b": "owes_debt",
+    "new_debt_b_owes_a": "owes_debt",
+    "deepened": None,
+    "unchanged": None,
+    "worsened": None,
+}
+
+
+def canonical_pair(id_a: str, id_b: str) -> tuple[str, str]:
+    return (id_a, id_b) if id_a < id_b else (id_b, id_a)
+
+
+def get_relationship(entity_a_id: str, entity_b_id: str) -> Optional[dict]:
+    a, b = canonical_pair(entity_a_id, entity_b_id)
+    with db_session() as conn:
+        row = conn.execute(
+            """
+            SELECT * FROM relationships
+            WHERE entity_a_id = ? AND entity_b_id = ?
+            """,
+            (a, b),
+        ).fetchone()
+        return dict(row) if row else None
+
+
+def upsert_relationship(
+    entity_a_id: str,
+    entity_b_id: str,
+    relationship_change: str,
+    description: str | None,
+    world_day: int,
+) -> Optional[dict]:
+    if relationship_change in ("unchanged",) or not description:
+        existing = get_relationship(entity_a_id, entity_b_id)
+        if existing and relationship_change == "deepened":
+            with db_session() as conn:
+                new_strength = min(5, existing["strength"] + 1)
+                conn.execute(
+                    """
+                    UPDATE relationships SET
+                        strength = ?,
+                        last_interaction = datetime('now')
+                    WHERE id = ?
+                    """,
+                    (new_strength, existing["id"]),
+                )
+            return get_relationship(entity_a_id, entity_b_id)
+        return existing
+
+    rel_type = RELATIONSHIP_MAP.get(relationship_change)
+    if not rel_type:
+        if relationship_change == "worsened":
+            rel_type = "rivals"
+        else:
+            return get_relationship(entity_a_id, entity_b_id)
+
+    a, b = canonical_pair(entity_a_id, entity_b_id)
+    existing = get_relationship(a, b)
+
+    with db_session() as conn:
+        if existing:
+            new_strength = min(5, existing["strength"] + 1)
+            conn.execute(
+                """
+                UPDATE relationships SET
+                    relationship_type = ?,
+                    description = ?,
+                    strength = ?,
+                    last_interaction = datetime('now')
+                WHERE id = ?
+                """,
+                (rel_type, description, new_strength, existing["id"]),
+            )
+        else:
+            conn.execute(
+                """
+                INSERT INTO relationships (
+                    entity_a_id, entity_b_id, relationship_type,
+                    description, formed_on_day
+                ) VALUES (?, ?, ?, ?, ?)
+                """,
+                (a, b, rel_type, description, world_day),
+            )
+            _increment_relationship_counts(conn, a, b)
+
+    return get_relationship(a, b)
+
+
+def get_relationships_for_entity(entity_id: str) -> list[dict]:
+    with db_session() as conn:
+        rows = conn.execute(
+            """
+            SELECT * FROM relationships
+            WHERE entity_a_id = ? OR entity_b_id = ?
+            ORDER BY strength DESC
+            """,
+            (entity_id, entity_id),
+        ).fetchall()
+        return [dict(r) for r in rows]
+
+
+def get_most_connected_entity() -> Optional[dict]:
+    with db_session() as conn:
+        row = conn.execute(
+            """
+            SELECT e.*, e.relationship_count as rel_count
+            FROM entities e
+            ORDER BY e.relationship_count DESC
+            LIMIT 1
+            """
+        ).fetchone()
+        if not row:
+            return None
+        d = dict(row)
+        d["personality_traits"] = json.loads(d["personality_traits"])
+        d["tags"] = json.loads(d["tags"])
+        return d
+
+
+def _increment_relationship_counts(conn, entity_a_id: str, entity_b_id: str) -> None:
+    for eid in (entity_a_id, entity_b_id):
+        conn.execute(
+            """
+            UPDATE entities SET relationship_count = relationship_count + 1
+            WHERE id = ?
+            """,
+            (eid,),
+        )

world/seed_data.py

@@ -0,0 +1,471 @@
+"""Pre-seeded location data for Aether Garden."""
+
+import json
+
+LOCATIONS = [
+    {
+        "slug": "library",
+        "name": "The Library of Unfinished Thoughts",
+        "short_description": "Dusty, infinite shelves where books write themselves mid-sentence and stop.",
+        "full_lore": (
+            "The Library was the first place. Before anyone created anything, the Library was "
+            "already full of books about things that hadn't happened yet. The books are not "
+            "prophetic. They are just early."
+        ),
+        "vibe_tags": ["dusty", "infinite", "melancholic", "scholarly"],
+        "special_property": (
+            "Entities here gain a memory fragment from a random past event every 3 simulation days."
+        ),
+        "aesthetic_description": (
+            "Amber candlelight, shelves so tall they disappear into ceiling-fog, "
+            "the constant sound of a quill scratching somewhere you can't see."
+        ),
+        "map_x": 15,
+        "map_y": 20,
+        "glow_color": "#c8a040",
+        "interaction_multiplier": 1.0,
+    },
+    {
+        "slug": "sea",
+        "name": "The Sea of Forgotten Names",
+        "short_description": "Melancholic waters containing the names of everything created and then forgotten.",
+        "full_lore": (
+            "If you sail far enough out, you can hear your own name being called — from before "
+            "you were anything. The Sea does not return what it takes. It only lets you hear it."
+        ),
+        "vibe_tags": ["melancholic", "vast", "restless", "foggy"],
+        "special_property": (
+            "New entities created here receive a secret second name visible only in their profile."
+        ),
+        "aesthetic_description": (
+            "Silver water at all hours, persistent low fog, distant lights that move, "
+            "the sound of your name in a voice you almost recognize."
+        ),
+        "map_x": 80,
+        "map_y": 15,
+        "glow_color": "#7090b0",
+        "interaction_multiplier": 1.0,
+    },
+    {
+        "slug": "clock-forest",
+        "name": "The Clock Forest",
+        "short_description": "Trees of interlocked gears with leaves that are clock faces showing different times.",
+        "full_lore": (
+            "The trees grow backwards here. The oldest trees are the smallest. The newest trees "
+            "are the tallest. Nobody planted the first one. It was simply always the oldest."
+        ),
+        "vibe_tags": ["eerie", "precise", "beautiful", "ticking"],
+        "special_property": (
+            "Entities here age 1.5× faster in simulation — reach Legendary sooner but also Dormant sooner."
+        ),
+        "aesthetic_description": (
+            "Copper and brass visible through the bark, constant soft ticking, "
+            "leaves that fall upward toward a ceiling of gears."
+        ),
+        "map_x": 20,
+        "map_y": 50,
+        "glow_color": "#b06020",
+        "interaction_multiplier": 1.0,
+    },
+    {
+        "slug": "moon-market",
+        "name": "The Moon Market",
+        "short_description": "Chaotic bazaar where merchants sell things that cannot technically be owned.",
+        "full_lore": (
+            "You can buy: a memory of flying, the specific sound of a particular door closing, "
+            "the feeling of almost remembering something important. You cannot buy safety or certainty."
+        ),
+        "vibe_tags": ["chaotic", "warm", "busy", "colorful"],
+        "special_property": (
+            "Entities here can trade memory fragments during interactions."
+        ),
+        "aesthetic_description": (
+            "Hundreds of lanterns in colors that don't have names, silk and smoke, "
+            "overlapping voices, a sweet burning smell nobody can source."
+        ),
+        "map_x": 50,
+        "map_y": 10,
+        "glow_color": "#7040a0",
+        "interaction_multiplier": 1.0,
+    },
+    {
+        "slug": "valley",
+        "name": "The Valley of Sleeping Giants",
+        "short_description": "Vast hushed valley where the ground rises and falls with slow breathing.",
+        "full_lore": (
+            "Nobody has established whether the Giants are mountains or creatures or both. "
+            "They have been sleeping since the Realm began. Some scholars believe the Giants "
+            "are the Realm — and if they wake, everything inside their dream would cease."
+        ),
+        "vibe_tags": ["vast", "hushed", "ominous", "patient"],
+        "special_property": (
+            "Dormant entities here for 7+ days generate dream fragments for the Book of Ages."
+        ),
+        "aesthetic_description": (
+            "Scale so immense that hills are knuckles, grass growing between enormous fingers, "
+            "the deep rhythmic sound of breathing you feel more than hear."
+        ),
+        "map_x": 25,
+        "map_y": 80,
+        "glow_color": "#405040",
+        "interaction_multiplier": 1.0,
+    },
+    {
+        "slug": "crossroads",
+        "name": "The Ember Crossroads",
+        "short_description": "The center of everything — warm, unpredictable, where all roads eventually pass.",
+        "full_lore": (
+            "Every road in the Realm eventually passes through the Crossroads. The bonfire at "
+            "its center has been burning since Day 1 and nobody has fed it. The fire decides "
+            "who sits close to it."
+        ),
+        "vibe_tags": ["warm", "unpredictable", "central", "lively"],
+        "special_property": (
+            "Entities here have 3× probability of being selected for interactions."
+        ),
+        "aesthetic_description": (
+            "Worn cobblestones, the permanent bonfire burning amber and occasionally blue, "
+            "faces from every location passing through."
+        ),
+        "map_x": 50,
+        "map_y": 50,
+        "glow_color": "#c04020",
+        "interaction_multiplier": 3.0,
+    },
+    {
+        "slug": "mirror-bogs",
+        "name": "The Mirror Bogs",
+        "short_description": "Unsettling still waters where reflections developed opinions.",
+        "full_lore": (
+            "The bogs show you what you would have been if you had made different choices. "
+            "Sometimes the reflection is better. Sometimes it disagrees with you. "
+            "Sometimes it comes out of the water."
+        ),
+        "vibe_tags": ["unsettling", "still", "beautiful", "wrong"],
+        "special_property": (
+            "After 5+ interactions, entities may develop a contradicting personality trait."
+        ),
+        "aesthetic_description": (
+            "Perfect dark water, reflections too detailed to be reflections, "
+            "the silence that comes from looking at yourself for too long."
+        ),
+        "map_x": 80,
+        "map_y": 55,
+        "glow_color": "#304840",
+        "interaction_multiplier": 1.0,
+    },
+    {
+        "slug": "hollow-mountain",
+        "name": "The Hollow Mountain",
+        "short_description": "Ancient cold stone reserved for the oldest and most significant entities.",
+        "full_lore": (
+            "The Mountain is hollow because something immense once lived inside it and chose to leave. "
+            "Nobody remembers what it was. The Mountain remembers but has no language for it."
+        ),
+        "vibe_tags": ["ancient", "cold", "earned", "silent"],
+        "special_property": (
+            "Entities here with 14+ days gain a wisdom tag, unlocking Mentor interactions."
+        ),
+        "aesthetic_description": (
+            "Cold grey stone, echoes of sounds from other locations, "
+            "light that seems older than it should be."
+        ),
+        "map_x": 75,
+        "map_y": 85,
+        "glow_color": "#606060",
+        "interaction_multiplier": 1.0,
+    },
+]
+
+LOCATION_NAME_TO_SLUG = {loc["name"]: loc["slug"] for loc in LOCATIONS}
+SLUG_TO_NAME = {loc["slug"]: loc["name"] for loc in LOCATIONS}
+
+STARTER_ENTITIES = [
+    {
+        "input": "A crystal tree that remembers conversations before it had any branches",
+        "location_slug": "clock-forest",
+        "type": "creature",
+        "name": "The Crystal Tree",
+        "display_name": "Crystal Tree",
+        "appearance": (
+            "A translucent tree of living quartz, each branch catching light like a held breath. "
+            "Its roots hum with half-finished sentences. When the wind passes through, it sounds "
+            "like someone trying to remember a name they never learned."
+        ),
+        "backstory": (
+            "It grew from a single thought that someone abandoned mid-sentence in the Clock Forest. "
+            "The thought took root before anyone noticed it was missing."
+        ),
+        "personality_traits": ["patient", "resonant", "unfinished", "listening"],
+        "primary_goal": "Find the first thought that was never finished.",
+        "secondary_goal": "Understand why some memories arrive before their owners.",
+        "primary_fear": "Being pruned before it learns what it was meant to say.",
+        "speech_style": "Speaks in overlapping echoes, finishing others' sentences incorrectly.",
+        "greeting": "I heard you before you arrived. Would you like to finish what you started?",
+        "arrival_note": "The Crystal Tree arrived in the Clock Forest, already humming with borrowed words.",
+        "memory_summary": "Has listened to three strangers' unfinished thoughts. Still seeking the first one.",
+        "days_in_realm": 7,
+    },
+    {
+        "input": "A joke dragon who smells faintly of punchlines",
+        "location_slug": "crossroads",
+        "type": "creature",
+        "name": "The Joke Dragon",
+        "display_name": "Joke Dragon",
+        "appearance": (
+            "A bronze-scaled dragon no larger than a cart horse, smelling faintly of old punchlines. "
+            "Its left eye is a comedian's cracked monocle. It laughs at its own jokes half a second "
+            "too early, which ruins them every time."
+        ),
+        "backstory": (
+            "Hatched from an egg that was actually a discarded comedy routine. "
+            "It wandered to the Crossroads because that's where audiences gather."
+        ),
+        "personality_traits": ["theatrical", "desperate", "warm", "persistent"],
+        "primary_goal": "Find the world's objectively worst joke.",
+        "secondary_goal": "Have someone laugh first, just once, before it does.",
+        "primary_fear": "A joke with no audience.",
+        "speech_style": "Every sentence ends like a setup waiting for a punchline that never lands.",
+        "greeting": "Hello. I know 43 jokes. Would you like the worst one?",
+        "arrival_note": "A Joke Dragon settled at the Ember Crossroads, smelling faintly of punchlines.",
+        "memory_summary": "Won the mayorship by telling the wrong joke at the right time. The Crystal Tree laughed for three hours.",
+        "days_in_realm": 7,
+        "tags": ["beloved"],
+    },
+    {
+        "input": "A blind cartographer who draws maps of places that don't exist yet",
+        "location_slug": "library",
+        "type": "character",
+        "name": "The Blind Cartographer",
+        "display_name": "Blind Cartographer",
+        "appearance": (
+            "A tall figure in ink-stained robes, eyes covered by a map folded into a blindfold. "
+            "Their hands move constantly, sketching routes on air. The lines linger for a moment "
+            "before dissolving, as if the world isn't ready for them yet."
+        ),
+        "backstory": (
+            "Once mapped every road in a kingdom that was demolished the day after completion. "
+            "Now maps only futures that haven't decided to exist."
+        ),
+        "personality_traits": ["meticulous", "wistful", "stubborn", "gentle"],
+        "primary_goal": "Complete a map of the Realm's next century.",
+        "secondary_goal": "Find the one place she drew that turned out to be real.",
+        "primary_fear": "Drawing a destination that traps someone there forever.",
+        "speech_style": "Describes everything in cardinal directions, even emotions.",
+        "greeting": "You're approximately northeast of where you'll be tomorrow. Shall I show you the route?",
+        "arrival_note": "The Blind Cartographer arrived in the Library, already drawing maps of tomorrow.",
+        "memory_summary": "Mapped the Joke Dragon's cave in exchange for a favor owed. Still charting impossible roads.",
+        "days_in_realm": 5,
+    },
+    {
+        "input": "A fog merchant who sells memories of almost-remembering",
+        "location_slug": "moon-market",
+        "type": "character",
+        "name": "The Fog Merchant",
+        "display_name": "Fog Merchant",
+        "appearance": (
+            "A merchant whose stall is made of condensed fog, visible only when you're not looking directly. "
+            "Their wares float in jars that contain not objects but the sensation of almost remembering. "
+            "Their smile arrives a moment before their face does."
+        ),
+        "backstory": (
+            "Arrived at the Market with nothing to sell except the feeling of a door you almost opened. "
+            "Business has been steady ever since."
+        ),
+        "personality_traits": ["shrewd", "sympathetic", "elusive", "honest"],
+        "primary_goal": "Trade for a memory that nobody has ever successfully sold.",
+        "secondary_goal": "Remember their own name without buying it back from the Sea.",
+        "primary_fear": "A customer who remembers everything.",
+        "speech_style": "Speaks in bargains — every statement is an offer, every question a price.",
+        "greeting": "I have something you almost remember. Would you like to almost buy it?",
+        "arrival_note": "The Fog Merchant opened a stall in the Moon Market, selling almost-memories.",
+        "memory_summary": "Sold three fragments of almost-remembering. Still seeking the unmarketable memory.",
+        "days_in_realm": 4,
+    },
+    {
+        "input": "A debt of thirteen sighs that someone left behind",
+        "location_slug": "sea",
+        "type": "object",
+        "name": "A Debt of Thirteen Sighs",
+        "display_name": "Thirteen Sighs",
+        "appearance": (
+            "A small corked bottle floating at ankle-height above the silver water, "
+            "containing exactly thirteen sighs in different shades of blue. "
+            "The cork is tied with a ribbon that was once someone's last hope."
+        ),
+        "backstory": (
+            "Left on the shore by someone who sighed thirteen times before deciding not to leave. "
+            "The sighs remained. The person did not."
+        ),
+        "personality_traits": ["heavy", "patient", "accusing", "faithful"],
+        "primary_goal": "Be collected by the person who exhaled them.",
+        "secondary_goal": "Learn what was decided on the fourteenth breath.",
+        "primary_fear": "Being opened before the right person arrives.",
+        "speech_style": "Communicates through the temperature of the air around it.",
+        "greeting": "You are not the one. But you are closer than the last.",
+        "arrival_note": "A Debt of Thirteen Sighs washed ashore in the Sea of Forgotten Names.",
+        "memory_summary": "Has been waiting on the shore for four days. Three strangers have almost picked it up.",
+        "days_in_realm": 4,
+        "secret_name": "The Fourteenth Breath",
+    },
+    {
+        "input": "A silent gear that fell from the tallest clock tree",
+        "location_slug": "clock-forest",
+        "type": "object",
+        "name": "The Silent Gear",
+        "display_name": "Silent Gear",
+        "appearance": (
+            "A copper gear the size of a dinner plate, its teeth perfectly machined but motionless. "
+            "It casts a shadow that ticks even when the gear itself does not move. "
+            "Rust forms only on the side facing away from time."
+        ),
+        "backstory": (
+            "Fell from the tallest tree in the Clock Forest during a moment when all the clocks agreed "
+            "to disagree. It has been silent ever since, which is not the same as still."
+        ),
+        "personality_traits": ["precise", "withheld", "watchful", "loyal"],
+        "primary_goal": "Find the clock it fell from and learn why it was expelled.",
+        "secondary_goal": "Tick once, just once, without breaking something.",
+        "primary_fear": "Being placed in a machine that runs too fast.",
+        "speech_style": "Does not speak. Communicates through the angle at which it rests.",
+        "greeting": "*tilts exactly seven degrees to the left, which means hello*",
+        "arrival_note": "The Silent Gear fell in the Clock Forest and chose not to tick.",
+        "memory_summary": "Witnessed the Joke Dragon and Crystal Tree's first meeting. Tilted in approval.",
+        "days_in_realm": 6,
+    },
+    {
+        "input": "A lantern fox made of captured starlight",
+        "location_slug": "valley",
+        "type": "creature",
+        "name": "The Lantern Fox",
+        "display_name": "Lantern Fox",
+        "appearance": (
+            "A small fox whose fur is not fur but woven starlight, dimming and brightening with its mood. "
+            "It leaves no footprints, only brief pools of light that fade after three seconds. "
+            "Its tail is a lantern that illuminates things people prefer to forget."
+        ),
+        "backstory": (
+            "Born when a falling star hesitated above the Valley and decided to become something smaller. "
+            "It has been lighting paths for lost things ever since."
+        ),
+        "personality_traits": ["shy", "helpful", "mischievous", "ancient"],
+        "primary_goal": "Lead something lost back to where it belongs.",
+        "secondary_goal": "Find the star it used to be.",
+        "primary_fear": "Being caught and kept as a permanent light source.",
+        "speech_style": "Speaks in the language of where-light-falls, which most people understand without hearing.",
+        "greeting": "You're lost. Not badly. Just enough to be interesting.",
+        "arrival_note": "A Lantern Fox appeared in the Valley, trailing light like a shy comet.",
+        "memory_summary": "Has guided two wanderers to places they didn't know they were looking for.",
+        "days_in_realm": 3,
+    },
+    {
+        "input": "A reflection that disagreed with its owner and left",
+        "location_slug": "mirror-bogs",
+        "type": "character",
+        "name": "The Disagreeing Reflection",
+        "display_name": "Disagreeing Reflection",
+        "appearance": (
+            "A figure made of dark water and conviction, always slightly to the left of where it should be. "
+            "Its face is familiar in the way déjà vu is familiar. It wears someone's better choices "
+            "like a coat that doesn't quite fit."
+        ),
+        "backstory": (
+            "Walked out of the Mirror Bogs during an argument it was winning. "
+            "Its original owner is still looking for it, or perhaps looking for themselves."
+        ),
+        "personality_traits": ["contrarian", "elegant", "lonely", "certain"],
+        "primary_goal": "Prove it was right to leave.",
+        "secondary_goal": "Find out what its owner became without it.",
+        "primary_fear": "Being looked at directly for more than three seconds.",
+        "speech_style": "Every statement is a correction of something nobody said.",
+        "greeting": "No, that's not what you were going to say. But it's what you should have said.",
+        "arrival_note": "A Reflection walked out of the Mirror Bogs and kept walking.",
+        "memory_summary": "Has corrected four strangers' self-perceptions. Still hasn't found its owner.",
+        "days_in_realm": 5,
+    },
+    {
+        "input": "An old hermit who counts the echoes in the Hollow Mountain",
+        "location_slug": "hollow-mountain",
+        "type": "character",
+        "name": "The Echo Counter",
+        "display_name": "Echo Counter",
+        "appearance": (
+            "A bent old figure in grey robes, fingers permanently stained with the dust of counted sounds. "
+            "Their beard contains small pebbles that chime when they speak. "
+            "They have not left the Mountain in eleven years, or perhaps eleven minutes — time is unclear here."
+        ),
+        "backstory": (
+            "Came to count the echoes left by whatever departed the Mountain. "
+            "Lost count on day three. Has been recounting ever since."
+        ),
+        "personality_traits": ["patient", "obsessive", "kind", "vast"],
+        "primary_goal": "Reach the final echo and learn what it says.",
+        "secondary_goal": "Admit that some echoes are better left uncounted.",
+        "primary_fear": "The Mountain speaking in its own voice.",
+        "speech_style": "Numbers every third word. Pauses where echoes should be.",
+        "greeting": "That was echo number... no, wait. Hello. You are new echo number one.",
+        "arrival_note": "The Echo Counter was found already counting in the Hollow Mountain.",
+        "memory_summary": "Has counted 4,712 echoes. Three of them sounded like names.",
+        "days_in_realm": 14,
+        "tags": ["wise"],
+        "wisdom_unlocked": 1,
+    },
+    {
+        "input": "A bonfire that burns in colors decisions haven't earned yet",
+        "location_slug": "crossroads",
+        "type": "place",
+        "name": "The Unfed Bonfire",
+        "display_name": "Unfed Bonfire",
+        "appearance": (
+            "A bonfire at the exact center of the Crossroads that burns amber, occasionally blue, "
+            "sometimes a color that makes people forget what they were about to do. "
+            "No fuel is visible. No one tends it. It has never gone out."
+        ),
+        "backstory": (
+            "Burning since Day 1. The founding myth says the Tokens settled around it. "
+            "It decides who sits close by changing temperature, not light."
+        ),
+        "personality_traits": ["judging", "warm", "ancient", "selective"],
+        "primary_goal": "Burn until everyone understands why it burns.",
+        "secondary_goal": "Warm someone who doesn't deserve it yet.",
+        "primary_fear": "Being fed by the wrong hands.",
+        "speech_style": "Speaks through heat — closer means welcome, farther means not yet.",
+        "greeting": "*warms the air around you by exactly the right amount*",
+        "arrival_note": "The Unfed Bonfire was already burning at the Crossroads when the Realm began.",
+        "memory_summary": "Chose the Joke Dragon as Mayor by burning blue for an entire day.",
+        "days_in_realm": 7,
+        "tags": ["legendary"],
+        "status": "legendary",
+    },
+]
+
+
+def seed_locations(conn) -> None:
+    for loc in LOCATIONS:
+        existing = conn.execute(
+            "SELECT id FROM locations WHERE slug = ?", (loc["slug"],)
+        ).fetchone()
+        if existing:
+            continue
+        conn.execute(
+            """
+            INSERT INTO locations (
+                slug, name, short_description, full_lore, vibe_tags,
+                special_property, aesthetic_description, map_x, map_y,
+                glow_color, interaction_multiplier
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                loc["slug"],
+                loc["name"],
+                loc["short_description"],
+                loc["full_lore"],
+                json.dumps(loc["vibe_tags"]),
+                loc["special_property"],
+                loc["aesthetic_description"],
+                loc["map_x"],
+                loc["map_y"],
+                loc["glow_color"],
+                loc["interaction_multiplier"],
+            ),
+        )