refactor(gui): Switch to retroUI

Refactor LLM provider system and introduce GUI for simulations

.github/workflows/deploy-docs.yml

@@ -0,0 +1,44 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - 'web/docs/**'
+      - 'pnpm-lock.yaml'
+      - '.github/workflows/deploy-docs.yml'
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    name: Deploy Docs to Cloudflare Workers
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 11
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: 'pnpm'
+
+      - name: Install Dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build Docs
+        run: pnpm --filter docs build
+
+      - name: Deploy to Cloudflare Workers
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          workingDirectory: 'web/docs'

.gitignore

@@ -46,6 +46,12 @@ Thumbs.db
 
 # Database
 omnia.db
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
+**/data/*.db
+data/
 
 # Environment Files
 .env
@@ -54,3 +60,5 @@ omnia.db
 
 # Vercel
 .vercel
+
+__local_notes/

CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+mail@adityagupta.dev.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

CONTRIBUTING.md

@@ -0,0 +1,99 @@
+# Contributing to Omnia
+
+Thank you for your interest in contributing to Omnia! We welcome contributions from developers, technical writers, and anyone interested in agentic narrative simulation.
+
+Please take a moment to review this document before submitting contributions.
+
+## Table of Contents
+
+1. [Documentation](#documentation)
+2. [Getting Started](#getting-started)
+3. [Development Workflow](#development-workflow)
+4. [Coding Standards](#coding-standards)
+5. [Pull Request Guidelines](#pull-request-guidelines)
+
+## Documentation
+
+The primary source of truth for the Omnia project is the official documentation:
+👉 **[Omnia Documentation](https://omnia.adityagupta.dev/docs)**
+
+Please refer to the documentation to understand the project architecture, memory model, spatial systems, intents framework, and custom LLM configurations.
+
+## Getting Started
+
+Omnia is organized as a monorepo managed with **pnpm** workspaces.
+
+### Prerequisites
+
+- **Node.js** (v22.13 or newer recommended)
+- **pnpm** (v11 or newer recommended)
+
+### Local Setup
+
+1. Fork the repository and clone your fork:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/omnia-consolidated.git
+   cd omnia-consolidated
+   ```
+2. Install dependencies:
+   ```bash
+   pnpm install
+   ```
+3. Run the Web GUI interface locally:
+   ```bash
+   pnpm dev:gui
+   ```
+4. Run the Starlight documentation site locally:
+   ```bash
+   pnpm dev:docs
+   ```
+
+## Development Workflow
+
+### Branching
+
+Create a descriptive branch for your changes:
+
+```bash
+git checkout -b feature/your-feature-name
+# or
+git checkout -b fix/issue-description
+```
+
+### Running Tests
+
+Make sure all unit tests pass before submitting changes:
+
+```bash
+# Run tests once
+pnpm test
+
+# Run tests in watch mode
+pnpm test:watch
+```
+
+### Linting and Formatting
+
+We enforce consistent code quality and formatting rules across the repository.
+
+```bash
+# Check code style and formatting
+pnpm lint
+pnpm format:check
+
+# Auto-fix code style issues
+pnpm lint:fix
+pnpm format
+```
+
+## Coding Standards
+
+- **TypeScript**: Omnia is written entirely in TypeScript. Ensure all new code is strongly typed.
+- **Docstrings**: Document public-facing APIs, methods, and configurations.
+
+## Pull Request Guidelines
+
+1. **Keep PRs Focused**: Keep your changes as small and focused as possible.
+2. **Include Tests**: If you are introducing a new feature or fixing a bug, write corresponding tests in `tests/`.
+3. **Update Documentation**: If your changes alter public behavior or introduce new APIs, update the docs under `web/docs/src/content/docs/`.
+4. **Follow Commit Conventions**: Write clear, descriptive commit messages.

README.md

@@ -1,49 +1,97 @@
-![Omnia Logo](web/docs/src/assets/img/logo.png)
+<p align="center">
+<img src="web/docs/src/assets/img/logo.png" alt="Omnia Logo" />
+</p>
 
-An LLM-assisted narrative simulation engine where the <b>world state lives outside the model</b>, characters act through <b>intents that get validated</b> and applied by engine code, and each character's knowledge, memory, and emotional state are subjective and partial by construction.
+<h1 align="center">Omnia</h1>
 
-Omnia is an engine for building narrative RPG-style worlds where characters are played by a language model. It is built to survive long play sessions instead of falling apart after twenty minutes.
+<p align="center">
+<b>An architectural framework for multi agent-narrative simulations and fictional worlds!</b>
+</p>
+<p align="center">
+  <a href="https://omnia.adityagupta.dev/docs"><img src="https://img.shields.io/badge/Omnia_Docs-Read_The_Docs-red?style=for-the-badge" alt="Docs" /></a>
+  <img src="https://img.shields.io/github/license/sortedcord/omnia-consolidated?style=for-the-badge" alt="License" />
+  <img src="https://img.shields.io/github/repo-size/sortedcord/omnia-consolidated?style=for-the-badge" alt="Repo Size" />
+  <img src="https://img.shields.io/github/languages/top/sortedcord/omnia-consolidated?style=for-the-badge" alt="Top Language" />
+</p>
 
-## The Problem with the Naive Approach
+The <b>world state lives outside the model</b>, characters act through <b>intents that get validated</b> and applied by engine code. Each character's knowledge, memory, and emotional state are subjective and partial by construction.
 
-Single-agent, single-context systems (AI Dungeon and its descendants) prompt one model to _be_ the world and everyone in it. That breaks in predictable ways over long sessions:
+<p align="center">
+  <img src="./web/docs/src/assets/img/puppet.webp" />
+</p>
 
-- **State Leaks:** Characters know things they had no way of learning, because a model with full context cannot help but use it. The assassin's target greets him by name.
-- **Secrets Refuse to Stay Secret:** "Don't reveal this" is a suggestion a model can argue past, not a mechanism that says no. One clever player question and the conspiracy folds.
+Single-agent or single-context systems (AI Dungeon and its descendants) prompt one model to _be_ the world and everyone in it. That breaks in predictable ways over long sessions:
+
+- **State Leaks:** Characters know things they had no way of learning, because a model with full context cannot help but use it.
 - **Consequences Evaporate:** Betray someone, apologize, and they forgive you a turn later because nothing is tracking the betrayal as a persistent fact.
-- **Emotional Drift:** Emotional state is either frozen into a meaningless number (`trust: 40`) or handed to the model to grade itself, producing drifting, arbitrary values.
+- **Stat Drift:** Statistical attributes are either frozen into a meaningless number (`trust: 40`) or handed to the model to grade itself, producing drifting, arbitrary values.
 - **World Rot:** The world state slowly contradicts itself because the model has no structured place to keep it. The locked door is open, then locked, then never existed.
-- **Everyone Is One Person:** Every character shares one context, so every character shares one mind. They can't genuinely surprise each other, lie to each other, or know different things — they're sock puppets on the same hand.
+- **Everyone Is One Person:** Every character shares one context, so every character shares one mind. They can't genuinely surprise each other, lie to each other, or know different things. They're sock puppets on the hands of one puppetmaster.
 
-The root cause is the same in every case: the model is being asked to be the database, the physics engine, the referee, and the whole cast simultaneously — inside a context window that forgets, blends, and leaks.
+The model should not be the database, the physics engine and the whole cast simultaneously inside a sliding context window.
 
 ## The Omnia Solution
 
-Omnia answers every one of these failures with the same move: pull the thing that has to stay consistent out of the model and into structured, queryable, code-controlled state.
+Omnia answers every one of these failures with the same move: **pull the thing that has to stay consistent out of the model** and into structured, queryable, code-controlled state.
 
-- **World State:** Lives in a SQLite database, not in a context window. It cannot drift, because nothing regenerates it — it only changes through validated deltas.
+- **World State:** Lives in a DB, not a context window. It cannot drift, because nothing regenerates it. The world state only changes through validated deltas.
 - **Actions:** Actions are proposals (Intents) that engine code validates and applies; they are never direct edits the model makes to the world. The model proposes; deterministic code disposes.
-- **Epistemic Privacy:** Knowledge, memory, and emotion are modeled per character and kept partial on purpose. A character literally cannot reach for what it has not earned the right to know — the secret is not in its prompt, so there is nothing to jailbreak out of it.
+- **Epistemic Privacy:** Knowledge, memory, and emotion are modeled per character and kept partial on purpose. A character literally cannot reach for what it has not earned the right to know. The secret is not in its prompt, so there is **nothing to jailbreak out of it**.
 
-## What This Buys You
+## What this buys you
 
-The payoff is scenario complexity that uni-agent systems structurally cannot represent, no matter how good the model gets:
+<p align="center">
+  <img src="./web/docs/src/assets/img/features.webp" />
+</p>
+
+The payoff is scenario complexity that **uni-agent systems structurally cannot represent, no matter how good the model gets**.
 
 - **Real secrets, real dramatic irony.** One NPC knows the sword is cursed; the other does not. This holds for hundreds of turns not because the model is disciplined, but because the second NPC's prompts are constructed from an attribute set that simply does not contain the fact. Leaking it would require the engine to have handed it over.
-- **Genuine deception between characters.** Because each character acts from its own bounded view, characters can lie to each other — and be believed — with the truth intact in the world state. A con game, a mole in the party, an unreliable ally: these are queries over who-knows-what, not prompt acrobatics.
-- **Betrayal that stays betrayed.** Events persist as per-observer memory entries with outcomes. An apology adds a memory; it does not delete one.
-- **Divergent accounts of the same event.** Two witnesses to the same scene hold two different buffer entries, filtered through their own aliases and vantage points. Ask them separately what happened and you get testimony, not a transcript.
-- **Identity as information.** Characters refer to each other through subjective alias maps ("the hooded figure" vs. "Bob"). Recognizing someone, being recognized, or staying anonymous are all mechanical states — a masked stranger is a masked stranger until the engine says otherwise.
-- **A physics referee that can say no.** "I pick the lock with a hairpin" is validated against world state by the Architect before anything changes. Failure is a recorded outcome the character remembers, not a narrative the model politely retconned.
-- **Time that behaves.** A world clock advances by validated, per-action deltas, and memory is recalled with psychologically natural phrasing ("earlier today, in the afternoon" — not a timestamp). Long timelines stay coherent because time is data, not vibes.
+- **Genuine deception between characters.** Because each entity acts from its own bounded view, they can lie to each other and be believed; with the truth intact in the world state. A con game, a mole in the party, an unreliable ally: these are queries over "who knows what" and not prompt engineering.
+- Events persist as per observer memory entries with outcomes. An apology adds a memory; it does not delete one.
+- **Divergent accounts of the same event.** Two witnesses to the same scene hold two different buffer entries, filtered through their own aliases and vantage points. Ask them separately what happened and you get varied testimony.
+- **A physics referee that can say no.** `I pick the lock with a hairpin` is validated against world state by the Architect before anything changes. Failure is a recorded outcome the entity remembers.
+- **Time that behaves.** A world clock advances by validated, per-action deltas, and memory is recalled with psychologically natural phrasing ("earlier today, in the afternoon" — not a timestamp). `TimeOfDay` is deterministic and not based on vibes.
+- **No main character syndrome.** The simulation runs fully autonomously or you act on behalf of any entity. You, the player, are just an entity in the data model, not structurally elevated above the rest of the world. The world can exist without the you.
+- **Granular model control.** Omnia is not locked to a single LLM. You can pick a different model for **every individual step that calls the LLM**. Narration prose that demands richer reasoning gets a frontier model; quick intent decoding or other generators get smaller ones or a model running entirely on your local machine.
 
-The general principle: **anything that must remain true is state; the model only ever supplies behavior.** That division of labor is what lets the cast, the secrets, and the timeline scale without the fiction collapsing.
+The general principle: **anything that must remain true is state; the model only ever supplies behavior.**
+
+## Installation
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/) (v20+ recommended)
+- [pnpm](https://pnpm.io/) (v9+ recommended)
+- An API key for Google Gemini (`GOOGLE_API_KEY` environment variable), or configured settings via the GUI.
+
+### Installation
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/sortedcord/omnia-consolidated.git
+   cd omnia-consolidated
+   ```
+2. Install dependencies:
+   ```bash
+   pnpm install
+   ```
+
+### Running the Web GUI
+
+To launch the Next.js development server for the GUI dashboard:
+
+```bash
+pnpm dev:gui
+```
+
+Access the application locally at `http://localhost:3000`.
 
 ## Core Architecture
 
 ### The Actor Agent
 
-Each character takes turns through an **Actor Agent** that receives a strictly epistemically-bounded prompt: its own attributes (public, plus private ones explicitly granted to itself), its subjective memory buffer, the entities co-present at its location, and the current moment. Nothing else. The actor responds with free narrative prose — what the character does, says, or _thinks_.
+Each entity takes turns through an **Actor Agent** that receives a strictly epistemically bounded prompt: its own attributes (public, plus private ones explicitly granted to itself), its subjective memory buffer, the entities co-present at its location, and the current moment. Nothing else. The actor responds with free narrative prose.
 
 Prose is decoded into typed intents:
 
@@ -51,30 +99,30 @@ Prose is decoded into typed intents:
 - **`action`** — a physical act, subject to validation.
 - **`monologue`** — an inner thought. No one else perceives it, it bypasses validation entirely, and it is written straight into the character's private memory.
 
-Not every turn needs an outward act; a character may simply think. This is what makes characters feel inhabited rather than reactive — and it produces a durable, queryable record of each character's private reasoning (see [Research Instrument](#a-research-instrument-model-psychology-in-fiction) below).
+Not every turn needs an outward act; a character may simply think. This is what makes characters feel inhabited rather than reactive and it produces a queryable record of each character's private reasoning (see [Research Instrument](#a-research-instrument-model-psychology-in-fiction) below).
 
-The prose generator is pluggable (`IActorProseGenerator`): the same turn loop runs an LLM-driven NPC or a human at a CLI prompt, identically bounded by what their character knows.
+The prose generator is pluggable (`IActorProseGenerator`): the same turn loop runs an LLM driven NPC or a human, identically bounded by what their character knows. (This is what eliminates Main Character Syndrome)
 
 ### Intents & The World Architect
 
-An action becomes an **Intent** — a cheap, declarative, allowed-to-be-wrong proposal. Intents route to the **World Architect**, which validates them against the objective world state (dialogue is exempt; monologue never even arrives) and generates structured deltas — starting with time advancement — that deterministic code applies after strict schema (Zod) validation. The model proposes a change; it never touches the database.
+An action becomes an **Intent** which is a simple proposal that is _allowed to be wrong_. Intents route to the **World Architect**, which validates them against the objective world state and generates structured deltas like time advancement, attribute change, etc. This deterministic code applies after strict schema (Zod) validation. The model never touches the DB.
 
-This is the load-bearing wall. Because every mutation flows through one validated chokepoint, the world cannot rot: there is no second copy of reality inside a context window to fall out of sync.
+Because every mutation flows through one validated chokepoint, the world cannot rot: there is no second copy of reality inside a context window to fall out of sync.
 
-### Attribute-Level Privacy
+### Attribute Level Privacy
 
-Every entity, item, and location is an attribute bag. Each attribute carries its own visibility (`PUBLIC` or `PRIVATE`) with an explicit access list. "The sword is cursed" is a private attribute checked in code, not a rule the model is politely asked to honor. Privacy lives at the level of the fact, not the entity — a character can be publicly a blacksmith and privately a spy, and even facts about _itself_ are hidden from it unless explicitly granted (amnesia, repression, and unwitting sleeper agents come free with the model).
+Every entity, item, and location is an _attribute bag_. Each attribute carries its own visibility (`PUBLIC` or `PRIVATE`) with an explicit access list. "The sword is cursed" is a private attribute checked in code, not a rule the model is politely asked to honor. Privacy lives at the level of the fact, not the entity. A character can be publicly a blacksmith and privately a spy, and even facts about _itself_ are hidden from it unless explicitly granted (amnesia, repression, and unwitting sleeper agents come free with the model).
 
 The dividend: **prompt-injection-proof secrets.** There is no instruction to override because the information was never serialized into the prompt. Epistemic privacy turns "the model shouldn't say this" (hard, unreliable) into "the model doesn't know this" (trivial, absolute).
 
 ### Spatial Perception
 
-Space is a graph: `world → region → location → point of interest`, connected by portals with sound and vision propagation values. When something happens, it bubbles outward. There are no coordinates, no pathfinding, no collision geometry — a narrative engine doesn't need a tactical simulation, and a discrete graph is sufficient. Today actors perceive co-located entities and their location's visible attributes; portal-propagated perception is on the roadmap.
+Space is a graph: `world → region → location → point of interest`, connected by portals with sound and vision propagation values. When something happens, it bubbles outward. There are no coordinates, no pathfinding, no collision geometry — a narrative engine doesn't need a tactical simulation, and a discrete graph is sufficient. Today actors perceive co-located entities and their location's visible attributes; portal propagated perception is on the roadmap.
 
 ### Memory Tiers
 
-- **Verbatim Buffer (implemented):** Per-character subjective event log. Every entry is stored from the owner's perspective — actors resolved through the owner's alias map, outcomes attached — and recalled with naturalized time phrasing.
-- **Vector Archive (planned):** Summarized, embedded memory entries for semantic retrieval, keeping verbatim quotes only for high-salience lines.
+- **Verbatim Buffer (implemented):** Per-character subjective event log. Every entry is stored from the owner's perspective actors resolved through the owner's alias map, outcomes attached — and recalled with naturalized time phrasing.
+- **Vector Archive (implemented):** Summarized, embedded memory entries for semantic retrieval, keeping verbatim quotes only for high-salience lines.
 - **Dossier (planned):** Each observer's subjective beliefs about another character.
 
 Memory is per-character on purpose: recall is testimony from a vantage point, which is what makes interrogating two witnesses interesting.
@@ -83,16 +131,20 @@ Memory is per-character on purpose: recall is testimony from a vantage point, wh
 
 Rather than a scalar the model drifts, every significant interaction becomes a ledger entry with an affect vector across OCC-derived dimensions (plus arousal, dominance, and social drive). The model judges a single moment; deterministic code aggregates the ledger over time with decay and attention weighting. A character can be simultaneously furious about one thing and grateful for another, and an apology does not silently erase a betrayal.
 
+This however is something that I haven't implementing or plan to implement anytime soon. The mathematical models described in NLAVS is still very abstract and subject to a lot of changes. CAA and RepE is still cutting edge research that I'm still reading papers about.
+
+Omnia might get an affect vector system however, it's going to be more simplistic than what the NLAVS proposal scribbles down.
+
 ## A Research Instrument: Model Psychology in Fiction
 
-Omnia's architecture doubles as an apparatus for studying how language models behave _as characters_ under controlled epistemic conditions — something uni-agent setups cannot do, because they can neither control what the model knows nor observe what it withholds.
+Omnia's architecture doubles as an apparatus for studying how language models behave _as characters_ under controlled epistemic conditions.
 
-- **A window into private reasoning.** Monologue intents are the model's in-character thoughts: unperceived by other agents, exempt from validation, but durably logged. You can directly compare what a character _thinks_ against what it _says and does_ — measuring deception, self-consistency, motivated reasoning, or the gap between private appraisal and public behavior.
-- **Knowledge as an experimental variable.** Attribute ACLs let you administer information with precision: give one agent a fact, withhold it from another, and observe propagation, inference, and leakage through dialogue alone. Secret-keeping stops being anecdotal and becomes testable — _provably_, since the engine logs exactly what each agent was ever shown.
-- **Controlled, reproducible conditions.** A scenario is a JSON file; a run is a SQLite database. Identical initial conditions, swappable model providers behind one interface (`ILLMProvider`), and a deterministic mock for baselines. Rerun the white-room experiment a hundred times, vary one attribute, and diff the transcripts.
-- **Multi-agent social dynamics with ground truth.** Because objective world state exists independently of any agent's beliefs, you can score agents' beliefs and claims against reality — hallucination, confabulation, and social conformity become measurable quantities rather than impressions.
+- **A window into private reasoning.** Monologue intents are the model's in character thoughts: unperceived by other agents, exempt from validation, but durably logged. You can directly compare what a character _thinks_ against what it _says and does_: measuring deception, self-consistency, motivated reasoning, etc.
+- **Knowledge as an experimental variable.** Attribute ACLs let you administer information with precision: give one agent a fact, withhold it from another, and observe propagation, inference, and leakage through dialogue alone.
+- **Controlled, reproducible conditions.** A scenario is a JSON file (like a template); a run is a SQLite database. Identical initial conditions, swappable model providers behind one interface (`ILLMProvider`), and a deterministic mock for baselines. Rerun the scenario a hundred times, vary one attribute, and diff the transcripts.
+- **Multi agent social dynamics with ground truth.** Because objective world state exists independently of any agent's beliefs, you can score agents' beliefs and claims against reality like hallucination. Even social conformity become measurable quantities rather than impressions or _✨ vibes_.
 
-The bundled demo scenario is exactly this: [`talking-room`](./content/demo/scenarios/talking-room.json) places two memory-wiped subjects in a featureless white room — each knowing their own name but not the other's — and observes what they do. It runs today, via the CLI, with a human optionally playing either subject.
+The bundled demo scenario is exactly this: [`talking-room`](./content/demo/scenarios/talking-room.json) places two memory wiped subjects in a featureless white room. Each know their own name but not the other's. Observe what they do. It runs today, ~~via the CLI, with a human optionally playing either subject~~ via a GUI which is in rapid development. You can let it run forever autonomously or roleplay as either character.
 
 ## Project Status: What `v0` Means
 
@@ -112,15 +164,15 @@ The finish line for the first milestone is small on purpose.
 
 - [x] Two hand-authored NPCs live in one location, playable via CLI.
 - [ ] Each has buffer and vector-archive memory and recalls something said a few turns earlier. _(buffer: done; vector archive: not started)_
-- [ ] One NPC knows a fact the other does not and, provably by testing, will not leak it.
+- [x] One NPC knows a fact the other does not and, provably by testing, will not leak it.
 - [x] The Architect processes at least one non-trivial action per exchange with a visible state change.
 - [x] The whole thing persists to a SQLite file and reloads identically.
 
-**Explicitly out of scope for `v0`:** Constraint validators (beyond basic sense-checking), multi-location perception, affect-vector decay math, the Dossier, whims/simulation tiering, the delta ledger, and UI beyond CLI.
+**Explicitly out of scope for `v0`:** Constraint validators (beyond basic sense-checking), multi-location perception, affect-vector decay math, the Dossier, whims/simulation tiering, the delta ledger.
 
 ### A Note on Tech Debt
 
-The Architect currently trusts an LLM's judgement about reasonable consequences rather than validating every change against declarative constraints. A general constraint solver is worth building eventually, but building it before anything is playable is foundational perfectionism that produces beautiful architecture and no game. `v0` keeps the single-call Architect on purpose.
+The Architect currently trusts an LLM's judgement about reasonable consequences rather than validating every change against declarative constraints. A general constraint solver is worth building eventually, but building it before anything is playable is foundational perfectionism that produces beautiful architecture and no framework. `v0` keeps the single-call Architect on purpose.
 
 ## Repository Layout
 
@@ -136,19 +188,18 @@ omnia/
     memory/      verbatim buffer; later the vector archive, dossier, and affect vectors
     spatial/     location and POI graph, portal-based perception
     llm/         ILLMProvider interface plus Gemini and deterministic mock implementations
+    scenario/    scenario JSON schema and loader (JSON → SQLite)
+  apps/
+    gui/         Next.js Web GUI dashboard and simulation runner
   content/
-    scenario-core/     scenario JSON schema and loader (JSON → SQLite)
-    scenario-builder/  Next.js web UI for authoring worlds
     demo/              bundled scenarios (talking-room)
-  cli/           the playable loop (human or LLM actors, --scenario / --play flags)
   tests/
     integration/ cross-package tests against a mocked LLM
     evals/       deliberate real-API evaluation runs
-  docs/          Astro documentation site (→ web/docs/)
+  web/
+    docs/        Astro documentation site
 ```
 
-_The engine core deliberately knows nothing about domain content (stats, traits, genres). Scenarios are plain JSON the loader ingests; what an attribute means is the scenario's business, not the engine's._
-
 ## Roadmap (Build Order after `v0`)
 
 1. Vector-archive memory and retrieval (closing out the `v0` memory milestone).

apps/gui/components.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "default",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/app/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "registries": {
+    "@retroui": "https://retroui.dev/r/radix/{name}.json",
+    "@retroui-base": "https://retroui.dev/r/base/{name}.json"
+  }
+}

apps/gui/next.config.ts

@@ -0,0 +1,30 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  transpilePackages: [
+    "@omnia/core",
+    "@omnia/llm",
+    "@omnia/intent",
+    "@omnia/architect",
+    "@omnia/actor",
+    "@omnia/memory",
+    "@omnia/spatial",
+    "@omnia/scenario",
+  ],
+  serverExternalPackages: ["better-sqlite3"],
+  allowedDevOrigins: ["192.168.0.18", "localhost", "127.0.0.1"],
+  experimental: {
+    serverActions: {
+      allowedOrigins: [
+        "192.168.0.18:3000",
+        "192.168.0.18:3001",
+        "192.168.0.18:3002",
+        "localhost:3000",
+        "localhost:3001",
+        "localhost:3002",
+      ],
+    },
+  },
+};
+
+export default nextConfig;

apps/gui/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@omnia/gui",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "@omnia/actor": "workspace:*",
+    "@omnia/architect": "workspace:*",
+    "@omnia/core": "workspace:*",
+    "@omnia/intent": "workspace:*",
+    "@omnia/llm": "workspace:*",
+    "@omnia/memory": "workspace:*",
+    "@omnia/scenario": "workspace:*",
+    "@omnia/spatial": "workspace:*",
+    "@radix-ui/react-slot": "^1.3.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "dotenv": "^17.4.2",
+    "lucide-react": "^1.24.0",
+    "next": "^16.2.10",
+    "radix-ui": "^1.6.2",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "tailwind-merge": "^3.6.0",
+    "tailwindcss-animate": "^1.0.7"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.3.2",
+    "@types/node": "^26.1.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "autoprefixer": "^10.5.2",
+    "postcss": "^8.5.16",
+    "shadcn": "^4.13.0",
+    "tailwindcss": "^4.3.2",
+    "typescript": "^6.0.3"
+  }
+}

apps/gui/src/app/config/page.tsx

@@ -0,0 +1,532 @@
+"use client";
+
+import { useEffect, useState, useCallback } from "react";
+import {
+  getConfigStatus,
+  listProviderInstances,
+  createProviderInstance,
+  deleteProviderInstance,
+  setActiveProviderInstance,
+  getProviderMappings,
+  setProviderMapping,
+  updateProviderInstance,
+  getAvailableProviders,
+  regenerateEmbeddings,
+} from "@/app/play/actions";
+import type { ModelProviderInstance, ModelProviderMeta } from "@omnia/llm";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Checkbox } from "@/components/ui/checkbox";
+import { Badge } from "@/components/ui/badge";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from "@/components/ui/table";
+
+interface ConfigStatus {
+  apiKeySet: boolean;
+  apiKeyPreview: string;
+  model: string;
+  availableScenarios: { path: string; name: string }[];
+}
+
+export default function ConfigPage() {
+  const [config, setConfig] = useState<ConfigStatus | null>(null);
+  const [instances, setInstances] = useState<ModelProviderInstance[]>([]);
+  const [mappings, setMappings] = useState<Record<string, string>>({});
+  const [availableProviders, setAvailableProviders] = useState<ModelProviderMeta[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState("");
+
+  const [selectedInstanceId, setSelectedInstanceId] = useState<string | null>(null);
+  const [editName, setEditName] = useState("");
+  const [editProvider, setEditProvider] = useState("google-genai");
+  const [editKey, setEditKey] = useState("");
+  const [editModel, setEditModel] = useState("gemini-2.5-flash");
+  const [editIsActive, setEditIsActive] = useState(false);
+  const [editType, setEditType] = useState<"generative" | "embedding">("generative");
+  const [editMaxContext, setEditMaxContext] = useState<number>(32768);
+
+  useEffect(() => {
+    if (selectedInstanceId === null) {
+      setEditName("");
+      setEditProvider("google-genai");
+      setEditKey("");
+      setEditModel("gemini-2.5-flash");
+      setEditIsActive(false);
+      setEditType("generative");
+      setEditMaxContext(32768);
+    } else if (selectedInstanceId === "new") {
+      setEditName("");
+      const defaultProvider = "google-genai";
+      setEditProvider(defaultProvider);
+      setEditKey("");
+      setEditType("generative");
+      const pMeta = availableProviders.find((p) => p.id === defaultProvider);
+      setEditModel(pMeta?.defaultModel || "gemini-2.5-flash");
+      setEditIsActive(false);
+      setEditMaxContext(32768);
+    } else {
+      const inst = instances.find((i) => i.id === selectedInstanceId);
+      if (inst) {
+        setEditName(inst.name);
+        setEditProvider(inst.providerName);
+        setEditKey("");
+        setEditType(inst.type || "generative");
+        const pMeta = availableProviders.find((p) => p.id === inst.providerName);
+        setEditModel(inst.modelName || (inst.type === "embedding" ? pMeta?.defaultEmbeddingModel : pMeta?.defaultModel) || "gemini-2.5-flash");
+        setEditIsActive(inst.isActive);
+        setEditMaxContext(inst.maxContext !== undefined && inst.maxContext !== null ? inst.maxContext : 32768);
+      }
+    }
+  }, [selectedInstanceId, instances, availableProviders]);
+
+  const handleProviderChange = (providerId: string) => {
+    setEditProvider(providerId);
+    const pMeta = availableProviders.find((p) => p.id === providerId);
+    setEditModel(editType === "embedding" ? pMeta?.defaultEmbeddingModel || "" : pMeta?.defaultModel || "");
+  };
+
+  const handleTypeChange = (type: "generative" | "embedding") => {
+    setEditType(type);
+    const pMeta = availableProviders.find((p) => p.id === editProvider);
+    setEditModel(type === "embedding" ? pMeta?.defaultEmbeddingModel || "" : pMeta?.defaultModel || "");
+  };
+
+  const loadInstances = useCallback(async () => {
+    const list = await listProviderInstances();
+    setInstances(list);
+  }, []);
+
+  const loadMappings = useCallback(async () => {
+    const maps = await getProviderMappings();
+    setMappings(maps);
+  }, []);
+
+  const loadAll = useCallback(async () => {
+    try {
+      setLoading(true);
+      setError("");
+      const status = await getConfigStatus();
+      setConfig(status);
+      await loadInstances();
+      await loadMappings();
+      const provs = await getAvailableProviders();
+      setAvailableProviders(provs);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setLoading(false);
+    }
+  }, [loadInstances, loadMappings]);
+
+  useEffect(() => {
+    loadAll();
+  }, [loadAll]);
+
+  const handleSave = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!editName.trim()) {
+      setError("Name is required.");
+      return;
+    }
+
+    try {
+      setLoading(true);
+      setError("");
+
+      let shouldRegenerate = false;
+      let targetInstanceId = selectedInstanceId;
+
+      if (selectedInstanceId === "new") {
+        if (!editKey.trim()) {
+          setError("API Key is required for new instances.");
+          setLoading(false);
+          return;
+        }
+        const created = await createProviderInstance(editName, editProvider, editKey, editModel || undefined, editType, editType === "generative" ? editMaxContext : 0);
+        if (editIsActive) {
+          await setActiveProviderInstance(created.id);
+        }
+        targetInstanceId = created.id;
+        setSelectedInstanceId(created.id);
+      } else {
+        if (!selectedInstanceId) return;
+        const inst = instances.find((i) => i.id === selectedInstanceId);
+        if (inst && inst.type === "embedding") {
+          const isMapped = mappings["embeddings"] === selectedInstanceId;
+          const isActive = inst.isActive && !mappings["embeddings"];
+          if (isMapped || isActive) {
+            const hasChanged = inst.providerName !== editProvider || inst.modelName !== editModel;
+            if (hasChanged) {
+              const confirmChange = window.confirm(
+                "You have changed the configuration of the active embedding provider. This will delete all existing embeddings and regenerate them from scratch. Are you sure you want to do this?"
+              );
+              if (!confirmChange) {
+                setLoading(false);
+                return;
+              }
+              shouldRegenerate = true;
+            }
+          }
+        }
+
+        await updateProviderInstance(selectedInstanceId, editName, editProvider, editKey || undefined, editModel || undefined, editType, editType === "generative" ? editMaxContext : 0);
+        if (editIsActive) {
+          await setActiveProviderInstance(selectedInstanceId);
+        }
+      }
+
+      await loadInstances();
+      await loadMappings();
+
+      if (shouldRegenerate && targetInstanceId && targetInstanceId !== "new") {
+        await regenerateEmbeddings(targetInstanceId);
+      }
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handleDelete = async () => {
+    if (selectedInstanceId === "new" || selectedInstanceId === null) return;
+    if (!confirm("Are you sure you want to delete this provider instance?")) return;
+
+    try {
+      setLoading(true);
+      setError("");
+      await deleteProviderInstance(selectedInstanceId);
+      setSelectedInstanceId(null);
+      await loadInstances();
+      await loadMappings();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handleUpdateMapping = async (task: string, providerInstanceId: string) => {
+    if (task === "embeddings" && mappings[task] !== providerInstanceId) {
+      const confirmChange = window.confirm(
+        "Changing the embeddings provider will delete all existing embeddings and regenerate them from scratch. Are you sure you want to do this?"
+      );
+      if (!confirmChange) return;
+    }
+
+    try {
+      setLoading(true);
+      await setProviderMapping(task, providerInstanceId);
+      if (task === "embeddings") {
+        await regenerateEmbeddings(providerInstanceId);
+      }
+      await loadMappings();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className="mx-auto max-w-[800px] px-4 py-8">
+      <h1 className="mb-6 text-2xl">Configuration</h1>
+
+      {config === null && loading && <p>Loading configuration...</p>}
+      {error && (
+        <div className="mb-4 rounded border border-red-300 bg-red-50 px-3 py-2 text-sm text-red-700">
+          {error}
+        </div>
+      )}
+
+      {config && (
+        <div className={loading ? "opacity-60 pointer-events-none transition-opacity duration-200" : "transition-opacity duration-200"}>
+          <section className="mb-8 pb-6">
+            <h2 className="mb-3 text-lg">LLM Provider Instances</h2>
+            <div className="mt-4 grid min-h-[400px] grid-cols-1 overflow-hidden rounded-xl border border-gray-200 bg-white md:grid-cols-[30%_70%]">
+              {/* 30% area */}
+              <div className="flex flex-col border-r border-gray-200 bg-gray-50">
+                <div className="flex items-center justify-between border-b border-gray-200 bg-gray-100 px-4 py-4">
+                  <h3 className="m-0 text-[0.95rem] font-semibold text-[#111]">
+                    Instances
+                  </h3>
+                  <Button
+                    onClick={() => setSelectedInstanceId("new")}
+                    size="sm"
+                    className="bg-emerald-500 text-white hover:bg-emerald-600"
+                  >
+                    + Add
+                  </Button>
+                </div>
+                <div className="flex flex-1 flex-col overflow-y-auto">
+                  {instances.length === 0 ? (
+                    <div className="px-4 py-8 text-center text-xs text-gray-400">
+                      No instances configured
+                    </div>
+                  ) : (
+                    instances.map((inst) => (
+                      <div
+                        key={inst.id}
+                        onClick={() => setSelectedInstanceId(inst.id)}
+                        className={`cursor-pointer border-b border-gray-200 border-l-[3px] px-4 py-4 transition-all hover:bg-gray-100 ${
+                          selectedInstanceId === inst.id
+                            ? "border-l-blue-500 bg-blue-50"
+                            : "border-l-transparent"
+                        }`}
+                      >
+                        <div className="text-sm font-medium text-[#111]">
+                          {inst.name}
+                        </div>
+                        <div className="mt-1 flex items-center justify-between text-xs text-gray-500">
+                          <span>{inst.providerName} ({inst.type || "generative"})</span>
+                            {inst.isActive && (
+                            <Badge className="bg-green-100 text-green-700 hover:bg-green-100 border-green-200">
+                              Active
+                            </Badge>
+                          )}
+                        </div>
+                      </div>
+                    ))
+                  )}
+                </div>
+              </div>
+
+              {/* 70% area */}
+              <div className="flex flex-col bg-white">
+                {selectedInstanceId === null ? (
+                  <div className="flex flex-1 flex-col items-center justify-center p-6 text-center text-sm text-gray-400">
+                    Press + to add or select an existing Instance to edit
+                  </div>
+                ) : (
+                  <form onSubmit={handleSave} className="flex h-full flex-col justify-between">
+                    <div className="flex flex-1 flex-col gap-5 p-6">
+                      <h3 className="m-0 mb-2 text-lg font-semibold text-[#111]">
+                        {selectedInstanceId === "new"
+                          ? "Create New Provider Instance"
+                          : `Configure: ${editName}`}
+                      </h3>
+
+                      <div className="flex flex-col gap-1.5">
+                        <Label htmlFor="formName">Friendly Name</Label>
+                        <Input
+                          id="formName"
+                          value={editName}
+                          onChange={(e) => setEditName(e.target.value)}
+                          placeholder="e.g. Gemini - Production"
+                          required
+                        />
+                      </div>
+
+                      <div className="flex flex-col gap-1.5">
+                        <Label>Instance Type</Label>
+                        <Select value={editType} onValueChange={(v) => handleTypeChange(v as "generative" | "embedding")}>
+                          <SelectTrigger className="w-full">
+                            <SelectValue />
+                          </SelectTrigger>
+                          <SelectContent>
+                            <SelectItem value="generative">Generative (Chat / Text Completion)</SelectItem>
+                            <SelectItem value="embedding">Embedding (Vector generation)</SelectItem>
+                          </SelectContent>
+                        </Select>
+                      </div>
+
+                      <div className="flex flex-col gap-1.5">
+                        <Label>Provider Type</Label>
+                        <Select value={editProvider} onValueChange={handleProviderChange}>
+                          <SelectTrigger className="w-full">
+                            <SelectValue />
+                          </SelectTrigger>
+                          <SelectContent>
+                            {availableProviders.map((p) => (
+                              <SelectItem key={p.id} value={p.id}>
+                                {p.displayName}
+                              </SelectItem>
+                            ))}
+                          </SelectContent>
+                        </Select>
+                        {editProvider && availableProviders.length > 0 && (
+                          <span className="mt-1 block rounded border border-2 bg-muted px-3 py-2 text-xs text-muted-foreground">
+                            {availableProviders.find((p) => p.id === editProvider)?.description}
+                          </span>
+                        )}
+                      </div>
+
+                      <div className="flex flex-col gap-1.5">
+                        <Label htmlFor="formKey">API Key</Label>
+                        <Input
+                          id="formKey"
+                          type="password"
+                          value={editKey}
+                          onChange={(e) => setEditKey(e.target.value)}
+                          placeholder={
+                            selectedInstanceId === "new"
+                              ? "AIzaSy..."
+                              : "•••••••• (unchanged)"
+                          }
+                          required={selectedInstanceId === "new"}
+                        />
+                      </div>
+
+                      <div className="flex flex-col gap-1.5">
+                        <Label htmlFor="formModel">Model Name</Label>
+                        <Input
+                          id="formModel"
+                          value={editModel}
+                          onChange={(e) => setEditModel(e.target.value)}
+                          placeholder="e.g. gemini-2.5-flash, gemini-2.5-pro"
+                        />
+                      </div>
+
+                      {editType === "generative" && (
+                        <div className="flex flex-col gap-1.5">
+                          <Label htmlFor="formMaxContext">Max Context Length (Tokens, 0 for infinite)</Label>
+                          <Input
+                            id="formMaxContext"
+                            type="number"
+                            value={editMaxContext}
+                            onChange={(e) => setEditMaxContext(parseInt(e.target.value) || 0)}
+                            min={0}
+                            placeholder="e.g. 32768"
+                          />
+                        </div>
+                      )}
+
+                      <div className="mt-1 flex flex-row items-center gap-2">
+                        <Checkbox
+                          id="formActive"
+                          checked={editIsActive}
+                          onCheckedChange={(v) => setEditIsActive(v === true)}
+                        />
+                        <Label htmlFor="formActive" className="cursor-pointer">
+                          Set as Active Instance
+                        </Label>
+                      </div>
+                    </div>
+
+                    <div className="flex items-center justify-between border-t-2 bg-muted/50 px-6 py-4">
+                      <div>
+                        {selectedInstanceId !== "new" && (
+                          <Button
+                            type="button"
+                            variant="destructive"
+                            onClick={handleDelete}
+                            disabled={loading}
+                          >
+                            Delete
+                          </Button>
+                        )}
+                      </div>
+                      <div>
+                        <Button
+                          type="submit"
+                          disabled={loading}
+                        >
+                          {loading ? "Saving..." : "Save"}
+                        </Button>
+                      </div>
+                    </div>
+                  </form>
+                )}
+              </div>
+            </div>
+          </section>
+
+          <section className="mb-8 pb-6">
+            <h2 className="mb-3 text-lg">Task Provider Routing</h2>
+            <p className="my-4 rounded border border-blue-200 bg-blue-50 px-3 py-2 text-xs text-blue-800">
+              Configure which LLM Provider Key Instance should handle each
+              specific simulation task. Mappings default to the currently{" "}
+              <strong>Active</strong> instance if not specified.
+            </p>
+            <div className="mt-4 grid grid-cols-1 gap-4 md:grid-cols-2">
+              {[
+                { key: "actor-prose", label: "Actor Prose Generation", desc: "Generates roleplay/narrative prose for Non-Player Characters.", type: "generative" },
+                { key: "llm-validator", label: "LLM Validator", desc: "Arbitrates and validates proposed actions against the world state rules.", type: "generative" },
+                { key: "intent-decoder", label: "Intent Decoder", desc: "Splits raw prose actions into structured intents (Player and NPC).", type: "generative" },
+                { key: "timedelta", label: "TimeDelta Generator", desc: "Calculates the duration of character actions to advance the game clock.", type: "generative" },
+                { key: "handoff", label: "Memory Handoff Engine", desc: "Promotes entities' working memories to the long-term Ledger via LLM summarization and pruning.", type: "generative" },
+                { key: "embeddings", label: "Text Embeddings Generator", desc: "Generates vector embeddings for long-term memory retrieval.", type: "embedding" },
+              ].map((task) => (
+                <div
+                  key={task.key}
+                  className="flex flex-col justify-between gap-3 rounded-lg border-2 bg-card p-4"
+                >
+                  <div className="flex flex-col gap-1 text-xs">
+                    <strong className="text-sm text-foreground">
+                      {task.label}
+                    </strong>
+                    <span className="mt-0.5 text-muted-foreground">{task.desc}</span>
+                  </div>
+                  <select
+                    value={mappings[task.key] || ""}
+                    onChange={(e) =>
+                      handleUpdateMapping(task.key, e.target.value)
+                    }
+                    className="w-full rounded border-2 bg-input px-2 py-1.5 text-xs shadow-sm outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary"
+                  >
+                    <option value="">-- Use Active Key (Default) --</option>
+                    {instances
+                      .filter((inst) => (inst.type || "generative") === task.type)
+                      .map((inst) => (
+                        <option key={inst.id} value={inst.id}>
+                          {inst.name} ({inst.providerName}){inst.isActive ? " [Active]" : ""}
+                        </option>
+                      ))}
+                  </select>
+                </div>
+              ))}
+            </div>
+          </section>
+
+          <section className="mb-8 pb-6">
+            <h2 className="mb-3 text-lg">Available Scenarios</h2>
+            {config.availableScenarios.length === 0 ? (
+              <p className="mt-3 rounded border border-amber-200 bg-amber-100 px-3 py-2 text-xs text-amber-800">
+                No scenarios found in{" "}
+                <code className="font-mono text-xs">
+                  content/demo/scenarios/
+                </code>
+                .
+              </p>
+            ) : (
+              <Table>
+                <TableHeader>
+                  <TableRow>
+                    <TableHead>Name</TableHead>
+                    <TableHead>Path</TableHead>
+                  </TableRow>
+                </TableHeader>
+                <TableBody>
+                  {config.availableScenarios.map((s) => (
+                    <TableRow key={s.path}>
+                      <TableCell>{s.name}</TableCell>
+                      <TableCell>
+                        <code className="font-mono text-xs text-blue-600">
+                          {s.path}
+                        </code>
+                      </TableCell>
+                    </TableRow>
+                  ))}
+                </TableBody>
+              </Table>
+            )}
+          </section>
+        </div>
+      )}
+    </div>
+  );
+}

apps/gui/src/app/globals.css

@@ -0,0 +1,92 @@
+@import "tailwindcss";
+@plugin "tailwindcss-animate";
+
+@custom-variant data-open (&[data-state="open"], &[data-state="active"]);
+@custom-variant data-closed (&[data-state="closed"], &[data-state="inactive"]);
+@custom-variant data-active (&[data-state="active"], &[data-state="open"]);
+@custom-variant data-checked (&[data-state="checked"], &[aria-checked="true"]);
+@custom-variant data-horizontal (&[data-orientation="horizontal"]);
+@custom-variant data-vertical (&[data-orientation="vertical"]);
+@custom-variant data-popup-open (&[data-state="open"]);
+
+@theme inline {
+  --font-head: var(--font-head);
+  --font-sans: var(--font-sans);
+  --radius: var(--radius);
+
+  --shadow-xs: 1px 1px 0 0 var(--border);
+  --shadow-sm: 2px 2px 0 0 var(--border);
+  --shadow: 3px 3px 0 0 var(--border);
+  --shadow-md: 4px 4px 0 0 var(--border);
+  --shadow-lg: 6px 6px 0 0 var(--border);
+  --shadow-xl: 10px 10px 0 1px var(--border);
+  --shadow-2xl: 16px 16px 0 1px var(--border);
+
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-primary-hover: var(--primary-hover);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+}
+
+:root {
+  --radius: 0;
+  --background: #fff7e8;
+  --foreground: #000;
+  --card: #fff;
+  --card-foreground: #000;
+  --popover: #fff;
+  --popover-foreground: #000;
+  --primary: #ffdc58;
+  --primary-hover: #ffd12e;
+  --primary-foreground: #000;
+  --secondary: #000;
+  --secondary-foreground: #fff;
+  --muted: #efe7d6;
+  --muted-foreground: #6b6355;
+  --accent: #ffe7a3;
+  --accent-foreground: #000;
+  --destructive: #e63946;
+  --destructive-foreground: #fff;
+  --border: #000;
+  --input: #fff;
+  --ring: #000;
+}
+
+.dark {
+  --background: #1a1815;
+  --foreground: #f5f0e6;
+  --card: #262320;
+  --card-foreground: #f5f0e6;
+  --popover: #262320;
+  --popover-foreground: #f5f0e6;
+  --primary: #ffdc58;
+  --primary-hover: #ffd12e;
+  --primary-foreground: #000;
+  --secondary: #3a352f;
+  --secondary-foreground: #f5f0e6;
+  --muted: #2e2a24;
+  --muted-foreground: #b3ac9e;
+  --accent: #38342b;
+  --accent-foreground: #f5f0e6;
+  --destructive: #ff6b6b;
+  --destructive-foreground: #1a1815;
+  --border: #000;
+  --input: #262320;
+  --ring: #ffdc58;
+}

apps/gui/src/app/layout.tsx

@@ -0,0 +1,33 @@
+import type { ReactNode } from "react";
+import { Archivo_Black, Space_Grotesk } from "next/font/google";
+import { NavBar } from "@/components/nav/NavBar";
+import "./globals.css";
+
+const archivoBlack = Archivo_Black({
+  subsets: ["latin"],
+  weight: "400",
+  variable: "--font-head",
+  display: "swap",
+});
+
+const spaceGrotesk = Space_Grotesk({
+  subsets: ["latin"],
+  variable: "--font-sans",
+  display: "swap",
+});
+
+export const metadata = {
+  title: "Omnia",
+  description: "Omnia Narrative Simulation Engine",
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body className={`${archivoBlack.variable} ${spaceGrotesk.variable} min-h-dvh bg-background text-foreground font-sans`}>
+        <NavBar />
+        {children}
+      </body>
+    </html>
+  );
+}

apps/gui/src/app/page.tsx

@@ -0,0 +1,35 @@
+import Link from "next/link";
+import { Card, CardHeader, CardTitle, CardDescription } from "@/components/ui/card";
+
+export default function Home() {
+  return (
+    <main className="mx-auto max-w-[800px] px-4 py-12">
+      <h1 className="mb-2 text-3xl">Omnia GUI</h1>
+      <p className="mb-8 text-muted-foreground">
+        Configuration and gameplay interface for the Omnia simulation engine.
+      </p>
+      <div className="flex gap-4">
+        <Link href="/play" className="flex-1 no-underline">
+          <Card className="transition-[border-color,box-shadow] duration-150 hover:border-blue-600 hover:shadow-[0_2px_8px_rgba(37,99,235,0.1)]">
+            <CardHeader>
+              <CardTitle>Play</CardTitle>
+              <CardDescription>
+                Start a simulation and interact with NPCs
+              </CardDescription>
+            </CardHeader>
+          </Card>
+        </Link>
+        <Link href="/config" className="flex-1 no-underline">
+          <Card className="transition-[border-color,box-shadow] duration-150 hover:border-blue-600 hover:shadow-[0_2px_8px_rgba(37,99,235,0.1)]">
+            <CardHeader>
+              <CardTitle>Config</CardTitle>
+              <CardDescription>
+                Check environment, API keys, and available scenarios
+              </CardDescription>
+            </CardHeader>
+          </Card>
+        </Link>
+      </div>
+    </main>
+  );
+}

apps/gui/src/app/play/actions.ts

@@ -0,0 +1,288 @@
+"use server";
+
+import path from "path";
+import fs from "fs";
+import { simulationManager } from "@/lib/simulation";
+import type { SimSnapshot } from "@/lib/simulation";
+import { ProviderManager, ModelProviderInstance, AVAILABLE_PROVIDERS, ModelProviderMeta } from "@omnia/llm";
+
+function resolveScenarioPath(relative: string): string {
+  const cwd = process.cwd();
+  const candidates = [
+    path.resolve(cwd, relative),
+    path.resolve(cwd, "content/demo/scenarios", relative),
+    path.resolve(cwd, "../../", relative),
+    path.resolve(cwd, "../../content/demo/scenarios", relative),
+  ];
+  for (const c of candidates) {
+    try {
+      if (fs.statSync(c).isFile()) return c;
+    } catch {
+      /* not found */
+    }
+  }
+  return path.resolve(cwd, relative);
+}
+
+type ActionResult =
+  | { ok: true; snapshot: SimSnapshot }
+  | { ok: false; error: string };
+
+export async function startSimulation(input: {
+  scenario?: string;
+  playEntity?: string;
+  providerInstanceId?: string;
+}): Promise<ActionResult> {
+  try {
+    const scenarioFile =
+      input.scenario || "content/demo/scenarios/talking-room.json";
+
+    const resolved = resolveScenarioPath(scenarioFile);
+    if (!fs.existsSync(resolved)) {
+      return { ok: false, error: `Scenario file not found: ${scenarioFile}` };
+    }
+
+    const snapshot = await simulationManager.create(
+      resolved,
+      input.playEntity || undefined,
+      input.providerInstanceId,
+    );
+
+    if (snapshot.status === "error") {
+      return { ok: false, error: snapshot.error || "Unknown error" };
+    }
+
+    return { ok: true, snapshot };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+export async function stepSimulation(input: {
+  simId: string;
+}): Promise<ActionResult> {
+  try {
+    if (!input.simId) {
+      return { ok: false, error: "Missing simId" };
+    }
+
+    const snapshot = await simulationManager.step(input.simId);
+
+    if (!snapshot) {
+      return { ok: false, error: "Simulation session not found" };
+    }
+
+    if (snapshot.status === "error") {
+      return { ok: false, error: snapshot.error || "Unknown error" };
+    }
+
+    return { ok: true, snapshot };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+export async function submitPlayerAction(input: {
+  simId: string;
+  prose: string;
+}): Promise<ActionResult> {
+  try {
+    if (!input.simId || !input.prose.trim()) {
+      return { ok: false, error: "Missing simId or prose" };
+    }
+
+    const snapshot = await simulationManager.submitPlayerAction(
+      input.simId,
+      input.prose.trim(),
+    );
+
+    if (!snapshot) {
+      return { ok: false, error: "Simulation session not found" };
+    }
+
+    if (snapshot.status === "error") {
+      return { ok: false, error: snapshot.error || "Unknown error" };
+    }
+
+    return { ok: true, snapshot };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+export async function getConfigStatus(): Promise<{
+  apiKeySet: boolean;
+  apiKeyPreview: string;
+  model: string;
+  availableScenarios: { path: string; name: string }[];
+}> {
+  const apiKey = process.env.GOOGLE_API_KEY;
+  const scenarios: { path: string; name: string }[] = [];
+
+  const cwd = process.cwd();
+  const candidates = [
+    path.resolve(cwd, "content/demo/scenarios"),
+    path.resolve(cwd, "../../content/demo/scenarios"),
+  ];
+  let scenariosDir = "";
+  for (const c of candidates) {
+    if (fs.existsSync(c) && fs.statSync(c).isDirectory()) {
+      scenariosDir = c;
+      break;
+    }
+  }
+
+  if (scenariosDir) {
+    for (const file of fs.readdirSync(scenariosDir)) {
+      if (file.endsWith(".json")) {
+        try {
+          const fullPath = path.join(scenariosDir, file);
+          const content = JSON.parse(fs.readFileSync(fullPath, "utf-8"));
+          scenarios.push({
+            path: `content/demo/scenarios/${file}`,
+            name: content.name || file,
+          });
+        } catch {
+          /* skip invalid */
+        }
+      }
+    }
+  }
+
+  return {
+    apiKeySet: !!apiKey,
+    apiKeyPreview: apiKey ? apiKey.substring(0, 10) + "..." : "NOT SET",
+    model: "gemini-2.5-flash",
+    availableScenarios: scenarios,
+  };
+}
+
+export async function listSavedSimulations(): Promise<
+  | { ok: true; sessions: SimSnapshot[] }
+  | { ok: false; error: string }
+> {
+  try {
+    const sessions = simulationManager.listSavedSessions();
+    return { ok: true, sessions };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+export async function resumeSimulation(simId: string): Promise<ActionResult> {
+  try {
+    const snapshot = await simulationManager.load(simId);
+    if (!snapshot) {
+      return { ok: false, error: `Failed to load simulation: ${simId}` };
+    }
+    return { ok: true, snapshot };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+export async function getScenarioEntities(scenarioPath: string): Promise<
+  | { ok: true; entities: { id: string; name: string }[] }
+  | { ok: false; error: string }
+> {
+  try {
+    const resolved = resolveScenarioPath(scenarioPath);
+    if (!fs.existsSync(resolved)) {
+      return { ok: false, error: `Scenario file not found: ${scenarioPath}` };
+    }
+    const content = JSON.parse(fs.readFileSync(resolved, "utf-8"));
+    const entities = (content.entities || []).map((e: { id: string; name?: string }) => ({
+      id: e.id,
+      name: e.name || e.id,
+    }));
+    return { ok: true, entities };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+export async function deleteSimulation(simId: string): Promise<
+  { ok: true } | { ok: false; error: string }
+> {
+  try {
+    simulationManager.deleteSession(simId);
+    return { ok: true };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+export async function listProviderInstances(): Promise<ModelProviderInstance[]> {
+  return ProviderManager.list();
+}
+
+export async function createProviderInstance(
+  name: string,
+  providerName: string,
+  apiKey: string,
+  modelName?: string,
+  type: "generative" | "embedding" = "generative",
+  maxContext?: number,
+): Promise<ModelProviderInstance> {
+  return ProviderManager.create(name, providerName, apiKey, modelName, type, maxContext);
+}
+
+export async function deleteProviderInstance(id: string): Promise<void> {
+  ProviderManager.delete(id);
+}
+
+export async function setActiveProviderInstance(id: string): Promise<void> {
+  ProviderManager.setActive(id);
+}
+
+export async function updateProviderInstance(
+  id: string,
+  name: string,
+  providerName: string,
+  apiKey?: string,
+  modelName?: string,
+  type: "generative" | "embedding" = "generative",
+  maxContext?: number,
+): Promise<void> {
+  ProviderManager.update(id, name, providerName, apiKey, modelName, type, maxContext);
+}
+
+export async function getProviderMappings(): Promise<Record<string, string>> {
+  return ProviderManager.getMappings();
+}
+
+export async function setProviderMapping(
+  task: string,
+  providerInstanceId: string,
+): Promise<void> {
+  ProviderManager.setMapping(task, providerInstanceId);
+}
+
+export async function getAvailableProviders(): Promise<ModelProviderMeta[]> {
+  return AVAILABLE_PROVIDERS;
+}
+
+export async function regenerateEmbeddings(newProviderInstanceId?: string): Promise<void> {
+  await simulationManager.regenerateAllEmbeddings(newProviderInstanceId);
+}

apps/gui/src/app/play/page.tsx

@@ -0,0 +1,5 @@
+import { PlayView } from "@/components/play/PlayView";
+
+export default function PlayPage() {
+  return <PlayView />;
+}

apps/gui/src/components/nav/NavBar.tsx

@@ -0,0 +1,35 @@
+"use client";
+
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import { Button } from "@/components/ui/button";
+
+const links = [
+  { href: "/", label: "Home" },
+  { href: "/play", label: "Play" },
+  { href: "/config", label: "Config" },
+];
+
+export function NavBar() {
+  const pathname = usePathname();
+
+  return (
+    <nav className="flex items-center gap-4 border-b-2 px-4 py-3">
+      <Button variant="link" asChild className="font-head text-base font-bold no-underline">
+        <Link href="/">Omnia</Link>
+      </Button>
+      <div className="flex gap-1">
+        {links.map((link) => (
+          <Button
+            key={link.href}
+            variant={pathname === link.href ? "default" : "ghost"}
+            size="sm"
+            asChild
+          >
+            <Link href={link.href}>{link.label}</Link>
+          </Button>
+        ))}
+      </div>
+    </nav>
+  );
+}

apps/gui/src/components/play/PlayView.tsx

@@ -0,0 +1,934 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+  startSimulation,
+  stepSimulation,
+  submitPlayerAction,
+  listSavedSimulations,
+  resumeSimulation,
+  getConfigStatus,
+  getScenarioEntities,
+  deleteSimulation,
+  listProviderInstances,
+} from "@/app/play/actions";
+import type { SimSnapshot } from "@/lib/simulation-types";
+import type { ModelProviderInstance } from "@omnia/llm";
+import { Button } from "@/components/ui/button";
+import { Textarea } from "@/components/ui/textarea";
+import { Spinner } from "@/components/ui/spinner";
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
+import {
+  Accordion,
+  AccordionItem,
+  AccordionTrigger,
+  AccordionContent,
+} from "@/components/ui/accordion";
+
+function IntentTag({
+  intent,
+  isSelf,
+}: {
+  intent: SimSnapshot["log"][number]["intents"][number];
+  isSelf?: boolean;
+}) {
+  const labels: Record<string, string> = {
+    monologue: "thought",
+    dialogue: "dialogue",
+    action: "action",
+  };
+
+  const label = labels[intent.type] || intent.type;
+
+  let outcome = "";
+  if (intent.type === "action") {
+    outcome = intent.isValid ? " ✅" : ` ❌ (${intent.reason})`;
+  }
+
+  const textToDisplay = (isSelf && intent.selfDescription)
+    ? intent.selfDescription
+    : intent.description;
+
+  const modifiersStr = intent.modifiers && intent.modifiers.length > 0 ? (
+    <span className="italic opacity-80 text-muted-foreground ml-1">
+      ({intent.modifiers.join(", ")})
+    </span>
+  ) : null;
+
+  return (
+    <span className="text-sm text-muted-foreground">
+      [{label}] &ldquo;{textToDisplay}&rdquo;{modifiersStr}{outcome}
+      {intent.minutesToAdvance ? ` [+${intent.minutesToAdvance}min]` : ""}
+    </span>
+  );
+}
+
+function PromptModal({
+  entry,
+  onClose,
+}: {
+  entry: SimSnapshot["log"][number];
+  onClose: () => void;
+}) {
+  const [activeTab, setActiveTab] = useState<"actor" | "decoder">("actor");
+
+  const parseActorPrompt = (systemPrompt: string, userContext: string, inputTokens: number) => {
+    const memoryHeader = "=== YOUR RECENT MEMORY ===";
+    const idx = userContext.indexOf(memoryHeader);
+
+    let worldStr = userContext;
+    let memStr = "";
+
+    if (idx !== -1) {
+      worldStr = userContext.substring(0, idx).trim();
+      memStr = userContext.substring(idx).trim();
+    }
+
+    const sysLen = systemPrompt.length;
+    const worldLen = worldStr.length;
+    const memLen = memStr.length;
+    const totalLen = sysLen + worldLen + memLen;
+
+    if (totalLen === 0) return null;
+
+    const sysPct = (sysLen / totalLen) * 100;
+    const worldPct = (worldLen / totalLen) * 100;
+    const memPct = (memLen / totalLen) * 100;
+
+    const sysTokens = Math.round((sysLen / totalLen) * inputTokens);
+    const worldTokens = Math.round((worldLen / totalLen) * inputTokens);
+    const memTokens = Math.max(0, inputTokens - sysTokens - worldTokens);
+
+    return [
+      { label: "System Prompt", pct: sysPct, relativePct: sysPct, tokens: sysTokens, type: "system", content: systemPrompt },
+      { label: "World Info", pct: worldPct, relativePct: worldPct, tokens: worldTokens, type: "world", content: worldStr },
+      { label: "Recent Memories", pct: memPct, relativePct: memPct, tokens: memTokens, type: "memories", content: memStr || "(No memories yet.)" },
+    ];
+  };
+
+  const parseDecoderPrompt = (systemPrompt: string, userContext: string, inputTokens: number) => {
+    const proseHeader = "=== NARRATIVE PROSE ===";
+    const idx = userContext.indexOf(proseHeader);
+
+    let worldStr = userContext;
+    let proseStr = "";
+
+    if (idx !== -1) {
+      worldStr = userContext.substring(0, idx).trim();
+      proseStr = userContext.substring(idx).trim();
+    }
+
+    const sysLen = systemPrompt.length;
+    const worldLen = worldStr.length;
+    const proseLen = proseStr.length;
+    const totalLen = sysLen + worldLen + proseLen;
+
+    if (totalLen === 0) return null;
+
+    const sysPct = (sysLen / totalLen) * 100;
+    const worldPct = (worldLen / totalLen) * 100;
+    const prosePct = (proseLen / totalLen) * 100;
+
+    const sysTokens = Math.round((sysLen / totalLen) * inputTokens);
+    const worldTokens = Math.round((worldLen / totalLen) * inputTokens);
+    const proseTokens = Math.max(0, inputTokens - sysTokens - worldTokens);
+
+    return [
+      { label: "System Prompt", pct: sysPct, relativePct: sysPct, tokens: sysTokens, type: "system", content: systemPrompt },
+      { label: "Decoder Context", pct: worldPct, relativePct: worldPct, tokens: worldTokens, type: "world", content: worldStr },
+      { label: "Narrative Prose", pct: prosePct, relativePct: prosePct, tokens: proseTokens, type: "memories", content: proseStr },
+    ];
+  };
+
+  const actorBreakdown = (entry.rawPrompt && entry.usage) ? parseActorPrompt(entry.rawPrompt.systemPrompt, entry.rawPrompt.userContext, entry.usage.inputTokens) : null;
+  const decoderBreakdown = (entry.decoderPrompt && entry.decoderUsage) ? parseDecoderPrompt(entry.decoderPrompt.systemPrompt, entry.decoderPrompt.userContext, entry.decoderUsage.inputTokens) : null;
+
+  const actorMaxContext = entry.usage?.maxContext !== undefined ? entry.usage.maxContext : 32768;
+  const actorUsedTokens = entry.usage?.inputTokens || 0;
+  const actorUsagePctOfContext = actorMaxContext > 0 ? (actorUsedTokens / actorMaxContext) * 100 : 0;
+  const isActorAbsolute = actorMaxContext > 0 && actorUsagePctOfContext >= 20;
+
+  const scaledActorBreakdown = actorBreakdown ? actorBreakdown.map((item) => ({
+    ...item,
+    pct: isActorAbsolute ? item.relativePct * (actorUsedTokens / actorMaxContext) : item.relativePct
+  })) : null;
+
+  const decoderMaxContext = entry.decoderUsage?.maxContext !== undefined ? entry.decoderUsage.maxContext : 32768;
+  const decoderUsedTokens = entry.decoderUsage?.inputTokens || 0;
+  const decoderUsagePctOfContext = decoderMaxContext > 0 ? (decoderUsedTokens / decoderMaxContext) * 100 : 0;
+  const isDecoderAbsolute = decoderMaxContext > 0 && decoderUsagePctOfContext >= 20;
+
+  const scaledDecoderBreakdown = decoderBreakdown ? decoderBreakdown.map((item) => ({
+    ...item,
+    pct: isDecoderAbsolute ? item.relativePct * (decoderUsedTokens / decoderMaxContext) : item.relativePct
+  })) : null;
+
+  useEffect(() => {
+    if (!entry.rawPrompt && entry.decoderPrompt) {
+      setActiveTab("decoder");
+    }
+  }, [entry]);
+
+  return (
+    <Dialog open onOpenChange={(open) => !open && onClose()}>
+      <DialogContent className="max-w-[750px] sm:max-w-[750px] max-h-[85vh] overflow-hidden flex flex-col p-0 gap-0">
+        <DialogHeader className="px-5 pt-4 pb-3 border-b">
+          <DialogTitle>Raw Prompts & Token Usage ({entry.entityName})</DialogTitle>
+        </DialogHeader>
+
+        <Tabs value={activeTab} onValueChange={(v) => setActiveTab(v as "actor" | "decoder")}>
+          <TabsList className="w-full rounded-none border-b bg-muted/50 px-5">
+            <TabsTrigger value="actor" disabled={!entry.rawPrompt} className="flex-1">
+              Actor Prompt {entry.usage ? "📊" : ""}
+            </TabsTrigger>
+            <TabsTrigger value="decoder" disabled={!entry.decoderPrompt} className="flex-1">
+              Intent Decoder {entry.decoderUsage ? "📊" : ""}
+            </TabsTrigger>
+          </TabsList>
+
+          <div className="overflow-y-auto flex-1 p-5">
+            <TabsContent value="actor">
+              {entry.rawPrompt && (
+                <div className="flex flex-col gap-4">
+                  {entry.usage ? (
+                    <div className="rounded border-2 bg-muted/50 px-3 py-2 text-sm text-muted-foreground">
+                      <strong>LLM Instance:</strong> <span>{entry.usage.providerInstanceName || "Default"}</span>
+                      {entry.usage.modelName && (
+                        <span> ({entry.usage.modelName})</span>
+                      )}
+                    </div>
+                  ) : (
+                    <div className="rounded border-2 bg-muted/50 px-3 py-2 text-sm italic text-muted-foreground">
+                      No LLM token usage (Player turn used fixed prose).
+                    </div>
+                  )}
+
+                  {scaledActorBreakdown && (
+                    <div>
+                      <div className="flex justify-between items-center text-xs text-muted-foreground mb-1">
+                        <span className="font-semibold">Input Prompt Breakdown</span>
+                        <span>
+                          Total Input Tokens: <strong>{actorUsedTokens}</strong>
+                          {actorMaxContext > 0 ? (
+                            <span> / {actorMaxContext} ({actorUsagePctOfContext.toFixed(1)}% used)</span>
+                          ) : (
+                            <span> (infinite context)</span>
+                          )}
+                        </span>
+                      </div>
+                      <div className="flex h-6 w-full rounded overflow-hidden bg-muted shadow-inner mb-2">
+                        {scaledActorBreakdown.map((item, idx) => {
+                          const displayPct = actorMaxContext > 0 ? (item.tokens / actorMaxContext) * 100 : item.relativePct;
+                          return (
+                            <div
+                              key={idx}
+                              className={`h-full transition-all duration-300 ${
+                                item.type === "system" ? "bg-blue-500" : item.type === "world" ? "bg-emerald-500" : "bg-amber-500"
+                              }`}
+                              style={{ width: `${item.pct}%` }}
+                              title={`${item.label}: ${item.tokens} tokens (${displayPct.toFixed(1)}%)`}
+                            />
+                          );
+                        })}
+                        {isActorAbsolute && (
+                          <div
+                            className="bg-white h-full"
+                            style={{ width: `${100 - actorUsagePctOfContext}%` }}
+                            title={`Available: ${actorMaxContext - actorUsedTokens} tokens (${(100 - actorUsagePctOfContext).toFixed(1)}% remaining)`}
+                          />
+                        )}
+                      </div>
+                      <Accordion type="multiple" defaultValue={["0"]}>
+                        {scaledActorBreakdown.map((item, idx) => {
+                          const displayPct = actorMaxContext > 0 ? (item.tokens / actorMaxContext) * 100 : item.relativePct;
+                          return (
+                            <AccordionItem key={idx} value={String(idx)}>
+                              <AccordionTrigger className="text-sm">
+                                <span className={`inline-block w-2.5 h-2.5 rounded-sm mr-2 ${
+                                  item.type === "system" ? "bg-blue-500" : item.type === "world" ? "bg-emerald-500" : "bg-amber-500"
+                                }`} />
+                                {item.label}: <strong>{item.tokens}</strong> tokens ({displayPct.toFixed(0)}%)
+                              </AccordionTrigger>
+                              <AccordionContent>
+                                <pre className="m-0 p-2 bg-muted rounded text-xs font-mono whitespace-pre-wrap max-h-[250px] overflow-y-auto text-foreground">
+                                  {item.content}
+                                </pre>
+                              </AccordionContent>
+                            </AccordionItem>
+                          );
+                        })}
+                      </Accordion>
+                    </div>
+                  )}
+
+                  {entry.usage && (
+                    <div>
+                      <div className="flex justify-between items-center text-xs text-muted-foreground mb-2">
+                        <span className="font-semibold">LLM Output</span>
+                        <span>Total Output Tokens: <strong>{entry.usage.outputTokens}</strong></span>
+                      </div>
+                      <div className="rounded border-2">
+                        <pre className="m-0 p-2 bg-muted text-xs font-mono whitespace-pre-wrap max-h-[250px] overflow-y-auto text-foreground">
+                          {entry.narrativeProse}
+                        </pre>
+                      </div>
+                    </div>
+                  )}
+                </div>
+              )}
+            </TabsContent>
+
+            <TabsContent value="decoder">
+              {entry.decoderPrompt && (
+                <div className="flex flex-col gap-4">
+                  {entry.decoderUsage && (
+                    <div className="rounded border-2 bg-muted/50 px-3 py-2 text-sm text-muted-foreground">
+                      <strong>LLM Instance:</strong> <span>{entry.decoderUsage.providerInstanceName || "Default"}</span>
+                      {entry.decoderUsage.modelName && (
+                        <span> ({entry.decoderUsage.modelName})</span>
+                      )}
+                    </div>
+                  )}
+
+                  {scaledDecoderBreakdown && (
+                    <div>
+                      <div className="flex justify-between items-center text-xs text-muted-foreground mb-1">
+                        <span className="font-semibold">Input Prompt Breakdown</span>
+                        <span>
+                          Total Input Tokens: <strong>{decoderUsedTokens}</strong>
+                          {decoderMaxContext > 0 ? (
+                            <span> / {decoderMaxContext} ({decoderUsagePctOfContext.toFixed(1)}% used)</span>
+                          ) : (
+                            <span> (infinite context)</span>
+                          )}
+                        </span>
+                      </div>
+                      <div className="flex h-6 w-full rounded overflow-hidden bg-muted shadow-inner mb-2">
+                        {scaledDecoderBreakdown.map((item, idx) => {
+                          const displayPct = decoderMaxContext > 0 ? (item.tokens / decoderMaxContext) * 100 : item.relativePct;
+                          return (
+                            <div
+                              key={idx}
+                              className={`h-full transition-all duration-300 ${
+                                item.type === "system" ? "bg-blue-500" : item.type === "world" ? "bg-emerald-500" : "bg-amber-500"
+                              }`}
+                              style={{ width: `${item.pct}%` }}
+                              title={`${item.label}: ${item.tokens} tokens (${displayPct.toFixed(1)}%)`}
+                            />
+                          );
+                        })}
+                        {isDecoderAbsolute && (
+                          <div
+                            className="bg-white h-full"
+                            style={{ width: `${100 - decoderUsagePctOfContext}%` }}
+                            title={`Available: ${decoderMaxContext - decoderUsedTokens} tokens (${(100 - decoderUsagePctOfContext).toFixed(1)}% remaining)`}
+                          />
+                        )}
+                      </div>
+                      <Accordion type="multiple" defaultValue={["0"]}>
+                        {scaledDecoderBreakdown.map((item, idx) => {
+                          const displayPct = decoderMaxContext > 0 ? (item.tokens / decoderMaxContext) * 100 : item.relativePct;
+                          return (
+                            <AccordionItem key={idx} value={String(idx)}>
+                              <AccordionTrigger className="text-sm">
+                                <span className={`inline-block w-2.5 h-2.5 rounded-sm mr-2 ${
+                                  item.type === "system" ? "bg-blue-500" : item.type === "world" ? "bg-emerald-500" : "bg-amber-500"
+                                }`} />
+                                {item.label}: <strong>{item.tokens}</strong> tokens ({displayPct.toFixed(0)}%)
+                              </AccordionTrigger>
+                              <AccordionContent>
+                                <pre className="m-0 p-2 bg-muted rounded text-xs font-mono whitespace-pre-wrap max-h-[250px] overflow-y-auto text-foreground">
+                                  {item.content}
+                                </pre>
+                              </AccordionContent>
+                            </AccordionItem>
+                          );
+                        })}
+                      </Accordion>
+                    </div>
+                  )}
+
+                  {entry.decoderUsage && (
+                    <div>
+                      <div className="flex justify-between items-center text-xs text-muted-foreground mb-2">
+                        <span className="font-semibold">LLM Output</span>
+                        <span>Total Output Tokens: <strong>{entry.decoderUsage.outputTokens}</strong></span>
+                      </div>
+                      <div className="rounded border-2">
+                        <pre className="m-0 p-2 bg-muted text-xs font-mono whitespace-pre-wrap max-h-[250px] overflow-y-auto text-foreground">
+                          {JSON.stringify(entry.intents, null, 2)}
+                        </pre>
+                      </div>
+                    </div>
+                  )}
+                </div>
+              )}
+            </TabsContent>
+          </div>
+        </Tabs>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function formatSimTime(isoString: string) {
+  try {
+    const d = new Date(isoString);
+    if (isNaN(d.getTime())) return isoString;
+    const yyyy = d.getUTCFullYear();
+    const mm = String(d.getUTCMonth() + 1).padStart(2, "0");
+    const dd = String(d.getUTCDate()).padStart(2, "0");
+    const hh = String(d.getUTCHours()).padStart(2, "0");
+    const min = String(d.getUTCMinutes()).padStart(2, "0");
+    const ss = String(d.getUTCSeconds()).padStart(2, "0");
+    return `${yyyy}-${mm}-${dd} ${hh}:${min}:${ss} UTC`;
+  } catch {
+    return isoString;
+  }
+}
+
+function LogEntryCard({
+  entry,
+  onShowPrompt,
+  isPlayerCard,
+}: {
+  entry: SimSnapshot["log"][number];
+  onShowPrompt: (entry: SimSnapshot["log"][number]) => void;
+  isPlayerCard: boolean;
+}) {
+  const showMenu = !!(entry.rawPrompt || entry.decoderPrompt);
+
+  return (
+    <div className="rounded border-2 bg-card p-3">
+      <div className="flex justify-between items-center mb-1.5 text-sm">
+        <div className="flex items-center gap-2">
+          <strong>{entry.entityName}</strong>
+          <span className="text-muted-foreground">
+            Turn {entry.turn} &middot;{" "}
+            {formatSimTime(entry.timestamp)}
+          </span>
+        </div>
+        {showMenu && (
+          <Button
+            variant="ghost"
+            size="icon"
+            onClick={() => onShowPrompt(entry)}
+            title="View Raw Prompts & Token Usage"
+          >
+            ☰
+          </Button>
+        )}
+      </div>
+      <div className="text-[0.9375rem] leading-relaxed mb-1.5">{entry.narrativeProse}</div>
+      <div className="flex flex-col gap-1">
+        {entry.intents.map((intent, i) => (
+          <IntentTag key={i} intent={intent} isSelf={isPlayerCard} />
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export function PlayView() {
+  const [snapshot, setSnapshot] = useState<SimSnapshot | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [playerInput, setPlayerInput] = useState("");
+  const [error, setError] = useState("");
+  const [statusText, setStatusText] = useState("");
+  const [selectedEntryForModal, setSelectedEntryForModal] = useState<SimSnapshot["log"][number] | null>(null);
+  const logEndRef = useRef<HTMLDivElement>(null);
+  const steppingRef = useRef(false);
+  const pauseRequestedRef = useRef(false);
+
+  const scrollToBottom = useCallback(() => {
+    setTimeout(
+      () => logEndRef.current?.scrollIntoView({ behavior: "smooth" }),
+      100,
+    );
+  }, []);
+
+  useEffect(() => {
+    scrollToBottom();
+  }, [snapshot, scrollToBottom]);
+
+  const runSteps = useCallback(
+    async (id: string) => {
+      if (steppingRef.current) return;
+      steppingRef.current = true;
+      setLoading(true);
+      setError("");
+      pauseRequestedRef.current = false;
+
+      try {
+        let current = snapshot;
+        while (true) {
+          if (pauseRequestedRef.current) {
+            break;
+          }
+          const result = await stepSimulation({ simId: id });
+          if (!result.ok) {
+            setError(result.error);
+            break;
+          }
+          current = result.snapshot;
+          setSnapshot(current);
+
+          if (
+            current.status === "waiting_player" ||
+            current.status === "done" ||
+            current.status === "error"
+          ) {
+            break;
+          }
+
+          const entityName =
+            current.entities[current.entityIndex ?? 0]?.name || "";
+          setStatusText(
+            `Turn ${current.turn} — processing ${entityName || "next step"}...`,
+          );
+        }
+      } catch (err) {
+        setError(
+          err instanceof Error
+            ? err.message
+            : "Failed during simulation step.",
+        );
+      } finally {
+        steppingRef.current = false;
+        setLoading(false);
+        setStatusText("");
+      }
+    },
+    [snapshot],
+  );
+
+  const [savedSessions, setSavedSessions] = useState<SimSnapshot[]>([]);
+
+  const loadSavedSessions = useCallback(async () => {
+    try {
+      const res = await listSavedSimulations();
+      if (res.ok) {
+        setSavedSessions(res.sessions);
+      }
+    } catch {
+      // ignore
+    }
+  }, []);
+
+  useEffect(() => {
+    if (!snapshot) {
+      loadSavedSessions();
+    }
+  }, [snapshot, loadSavedSessions]);
+
+  const handleResume = async (id: string) => {
+    setLoading(true);
+    setError("");
+    try {
+      const res = await resumeSimulation(id);
+      if (!res.ok) {
+        setError(res.error);
+        setLoading(false);
+        return;
+      }
+      setSnapshot(res.snapshot);
+      if (res.snapshot.status === "running") {
+        await runSteps(res.snapshot.id);
+      } else {
+        setLoading(false);
+      }
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to resume session.");
+      setLoading(false);
+    }
+  };
+
+  const handleDelete = async (id: string, e: React.MouseEvent) => {
+    e.stopPropagation();
+    if (!confirm("Are you sure you want to delete this simulation session?")) return;
+    setLoading(true);
+    try {
+      const res = await deleteSimulation(id);
+      if (!res.ok) {
+        setError(res.error);
+      } else {
+        await loadSavedSessions();
+      }
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to delete session.");
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const [scenarios, setScenarios] = useState<{ path: string; name: string }[]>([]);
+  const [selectedScenario, setSelectedScenario] = useState("");
+  const [availableEntities, setAvailableEntities] = useState<{ id: string; name: string }[]>([]);
+  const [selectedEntity, setSelectedEntity] = useState("");
+
+  const [providerInstances, setProviderInstances] = useState<ModelProviderInstance[]>([]);
+
+  // Load scenarios and provider instances on mount
+  useEffect(() => {
+    async function loadScenariosAndProviders() {
+      try {
+        const configStatus = await getConfigStatus();
+        setScenarios(configStatus.availableScenarios);
+        if (configStatus.availableScenarios.length > 0) {
+          setSelectedScenario(configStatus.availableScenarios[0].path);
+        }
+      } catch {
+        // ignore
+      }
+      try {
+        const providersList = await listProviderInstances();
+        setProviderInstances(providersList);
+      } catch {
+        // ignore
+      }
+    }
+    loadScenariosAndProviders();
+  }, [snapshot]);
+
+  // Fetch entities when selectedScenario changes
+  useEffect(() => {
+    if (!selectedScenario) {
+      setAvailableEntities([]);
+      setSelectedEntity("");
+      return;
+    }
+    async function loadEntities() {
+      try {
+        const res = await getScenarioEntities(selectedScenario);
+        if (res.ok) {
+          setAvailableEntities(res.entities);
+          if (res.entities.length > 0) {
+            setSelectedEntity(res.entities[0].id);
+          } else {
+            setSelectedEntity("");
+          }
+        }
+      } catch {
+        // ignore
+      }
+    }
+    loadEntities();
+  }, [selectedScenario]);
+
+  const handleStart = async (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    setLoading(true);
+    setError("");
+
+    try {
+      const form = new FormData(e.currentTarget);
+      const result = await startSimulation({
+        scenario: (form.get("scenario") as string) || undefined,
+        playEntity: (form.get("playEntity") as string) || undefined,
+      });
+
+      if (!result.ok) {
+        setError(result.error);
+        setLoading(false);
+        return;
+      }
+
+      setSnapshot(result.snapshot);
+
+      if (result.snapshot.status === "running") {
+        await runSteps(result.snapshot.id);
+      } else {
+        setLoading(false);
+      }
+    } catch (err) {
+      setError(
+        err instanceof Error
+          ? err.message
+          : "Failed to start simulation.",
+      );
+      setLoading(false);
+    }
+  };
+
+  const handleSubmitAction = async (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+
+    if (!snapshot || !playerInput.trim()) return;
+
+    setLoading(true);
+    const prose = playerInput.trim();
+    setPlayerInput("");
+
+    try {
+      const result = await submitPlayerAction({
+        simId: snapshot.id,
+        prose,
+      });
+
+      if (!result.ok) {
+        setError(result.error);
+        setLoading(false);
+        return;
+      }
+
+      setSnapshot(result.snapshot);
+
+      if (result.snapshot.status === "running") {
+        await runSteps(result.snapshot.id);
+      }
+    } catch (err) {
+      setError(
+        err instanceof Error
+          ? err.message
+          : "Failed to submit action.",
+      );
+      setLoading(false);
+    }
+  };
+
+  const statusMessage = () => {
+    if (!snapshot) return null;
+    if (loading && statusText) return statusText;
+    switch (snapshot.status) {
+      case "waiting_player":
+        return `Waiting for your input as "${snapshot.waitingEntity?.name}"...`;
+      case "done":
+        return "Simulation complete.";
+      case "error":
+        return `Error: ${snapshot.error}`;
+      default:
+        return "Simulation running...";
+    }
+  };
+
+  return (
+    <div className="mx-auto max-w-[800px] p-8 pt-4">
+      <h1 className="text-2xl mb-4">Omnia Play</h1>
+
+      {!snapshot && (
+        <div className="grid grid-cols-1 md:grid-cols-[1.2fr_1fr] gap-8 mt-4">
+          <div className="rounded-xl border-2 bg-card p-6 shadow-sm">
+            <h2 className="text-lg font-head font-medium mb-5 pb-2 border-b">Start New Simulation</h2>
+            <form onSubmit={handleStart} className="flex flex-col gap-4">
+              {error && (
+                <div className="rounded border-2 border-destructive/30 bg-destructive/10 px-3 py-2 text-sm text-destructive">
+                  {error}
+                </div>
+              )}
+              <div className="flex flex-col gap-1">
+                <label htmlFor="scenario" className="text-sm font-medium">Scenario</label>
+                <select
+                  id="scenario"
+                  name="scenario"
+                  value={selectedScenario}
+                  onChange={(e) => setSelectedScenario(e.target.value)}
+                  className="w-full rounded border-2 bg-input px-3 py-2 text-sm shadow-sm outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary"
+                >
+                  {scenarios.map((s) => (
+                    <option key={s.path} value={s.path}>
+                      {s.name}
+                    </option>
+                  ))}
+                </select>
+              </div>
+              <div className="flex flex-col gap-1">
+                <label htmlFor="playEntity" className="text-sm font-medium">
+                  Play as (Entity)
+                </label>
+                <select
+                  id="playEntity"
+                  name="playEntity"
+                  value={selectedEntity}
+                  onChange={(e) => setSelectedEntity(e.target.value)}
+                  disabled={availableEntities.length === 0}
+                  className="w-full rounded border-2 bg-input px-3 py-2 text-sm shadow-sm outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary disabled:opacity-50"
+                >
+                  <option value="">-- Spectator (Observer) --</option>
+                  {availableEntities.map((ent) => (
+                    <option key={ent.id} value={ent.id}>
+                      {ent.name}
+                    </option>
+                  ))}
+                </select>
+              </div>
+
+              <Button type="submit" disabled={loading || providerInstances.length === 0}>
+                {loading ? "Starting..." : "Start Simulation"}
+              </Button>
+            </form>
+          </div>
+
+          <div className="rounded-xl border-2 bg-card p-6 shadow-sm">
+            <h2 className="text-lg font-head font-medium mb-5 pb-2 border-b">Resume Simulation</h2>
+            {savedSessions.length === 0 ? (
+              <p className="text-sm italic text-muted-foreground">No saved sessions found. Start a new one!</p>
+            ) : (
+              <div className="flex flex-col gap-3 max-h-[400px] overflow-y-auto pr-1">
+                {savedSessions.map((s) => (
+                  <div key={s.id} className="rounded border-2 bg-muted/50 p-3 flex justify-between items-center gap-4 transition-all hover:border-muted-foreground/30">
+                    <div className="flex flex-col gap-0.5 text-sm">
+                      <strong className="text-sm text-foreground">{s.scenarioName}</strong>
+                      <span className="text-muted-foreground">
+                        Turn {s.turn} &middot; {s.entities.length} entities &middot; {s.status}
+                      </span>
+                      <span className="text-xs text-muted-foreground/60">
+                        Session ID: <code>{s.id}</code>
+                      </span>
+                    </div>
+                    <div className="flex gap-2 items-center">
+                      <Button size="sm" onClick={() => handleResume(s.id)} disabled={loading || providerInstances.length === 0}>
+                        Resume
+                      </Button>
+                      <Button
+                        size="sm"
+                        variant="destructive"
+                        onClick={(e) => handleDelete(s.id, e)}
+                        disabled={loading}
+                        title="Delete Session"
+                      >
+                        Delete
+                      </Button>
+                    </div>
+                  </div>
+                ))}
+              </div>
+            )}
+          </div>
+        </div>
+      )}
+
+      {snapshot && (
+        <>
+          <div className="mb-4">
+            <div className="flex justify-between items-center mb-1">
+              <h2 className="text-xl">{snapshot.scenarioName}</h2>
+              {snapshot.status !== "done" && snapshot.status !== "error" && (
+                <div className="flex gap-2">
+                  {snapshot.status === "running" && (
+                    loading ? (
+                      <Button
+                        variant="secondary"
+                        size="sm"
+                        onClick={() => {
+                          pauseRequestedRef.current = true;
+                        }}
+                      >
+                        Pause
+                      </Button>
+                    ) : (
+                      <Button
+                        variant="secondary"
+                        size="sm"
+                        onClick={() => runSteps(snapshot.id)}
+                      >
+                        Resume
+                      </Button>
+                    )
+                  )}
+                  <Button
+                    variant="destructive"
+                    size="sm"
+                    onClick={() => {
+                      setSnapshot(null);
+                      setError("");
+                    }}
+                  >
+                    Stop
+                  </Button>
+                </div>
+              )}
+            </div>
+            <p className="text-sm text-muted-foreground">{snapshot.scenarioDescription}</p>
+            <p className="text-sm font-medium text-primary mt-1">
+              {loading && "⏳ "}
+              {statusMessage()}
+            </p>
+          </div>
+
+          <div className="flex flex-col gap-3 mb-4 max-h-[55vh] overflow-y-auto rounded border-2 bg-muted/30 p-3">
+            {(() => {
+              const playerEntity = snapshot.entities.find((e) => e.isPlayer);
+              return snapshot.log.map((entry, i) => (
+                <LogEntryCard
+                  key={i}
+                  entry={entry}
+                  onShowPrompt={setSelectedEntryForModal}
+                  isPlayerCard={entry.entityId === playerEntity?.id}
+                />
+              ));
+            })()}
+            {loading && (
+              <div className="flex items-center gap-2 text-sm italic text-muted-foreground p-2">
+                <Spinner />
+                {statusText || "Processing..."}
+              </div>
+            )}
+            <div ref={logEndRef} />
+          </div>
+
+          {snapshot.status === "waiting_player" && snapshot.waitingEntity && (
+            <div className="rounded border-2 bg-muted/50 p-4">
+              <details className="mb-3">
+                <summary className="cursor-pointer text-sm font-medium">
+                  <strong>
+                    Your context as {snapshot.waitingEntity.name}
+                  </strong>
+                </summary>
+                <pre className="text-xs whitespace-pre-wrap bg-muted p-2 rounded max-h-[200px] overflow-y-auto mt-2">
+                  {snapshot.waitingEntity.userContext}
+                </pre>
+              </details>
+
+              <form onSubmit={handleSubmitAction} className="flex flex-col gap-2">
+                <Textarea
+                  value={playerInput}
+                  onChange={(e) => setPlayerInput(e.target.value)}
+                  placeholder="Describe what your character does, says, or thinks..."
+                  rows={3}
+                  disabled={loading}
+                />
+                <Button
+                  type="submit"
+                  disabled={loading || !playerInput.trim()}
+                >
+                  {loading ? "Processing..." : "Submit Action"}
+                </Button>
+              </form>
+            </div>
+          )}
+
+          {(snapshot.status === "done" || snapshot.status === "error") && (
+            <Button
+              onClick={() => {
+                setSnapshot(null);
+                setError("");
+              }}
+              className="mt-4"
+            >
+              {snapshot.status === "error" ? "Try Again" : "New Simulation"}
+            </Button>
+          )}
+
+          {error && !loading && (
+            <div className="rounded border-2 border-destructive/30 bg-destructive/10 px-3 py-2 text-sm text-destructive mt-4">
+              {error}
+            </div>
+          )}
+
+          {selectedEntryForModal && (
+            <PromptModal
+              entry={selectedEntryForModal}
+              onClose={() => setSelectedEntryForModal(null)}
+            />
+          )}
+        </>
+      )}
+    </div>
+  );
+}

apps/gui/src/components/ui/accordion.tsx

@@ -0,0 +1,101 @@
+"use client"
+
+import * as React from "react"
+import { ChevronDownIcon } from "lucide-react"
+import { Accordion as AccordionPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+
+// Smooth, premium easing for the open/close — fast out of the gate, gentle
+// settle. Shared by the panel height and the chevron so they move in lockstep.
+const EASE = "ease-[cubic-bezier(0.32,0.72,0,1)]"
+
+function Accordion({
+  className,
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Root>) {
+  return (
+    <AccordionPrimitive.Root
+      data-slot="accordion"
+      className={cn("flex w-full flex-col gap-3", className)}
+      {...props}
+    />
+  )
+}
+
+function AccordionItem({
+  className,
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Item>) {
+  return (
+    <AccordionPrimitive.Item
+      data-slot="accordion-item"
+      className={cn(
+        "overflow-hidden rounded border-2 bg-background text-foreground shadow-md transition-shadow duration-200 hover:shadow-sm data-[state=open]:shadow-sm",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AccordionTrigger({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Trigger>) {
+  return (
+    <AccordionPrimitive.Header data-slot="accordion-header" className="flex">
+      <AccordionPrimitive.Trigger
+        data-slot="accordion-trigger"
+        className={cn(
+          "flex flex-1 cursor-pointer items-center justify-between gap-4 px-4 py-3 text-left font-head transition-colors hover:bg-muted/50 data-[state=open]:bg-muted/40 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary [&[data-state=open]>svg]:rotate-180",
+          className
+        )}
+        {...props}
+      >
+        {children}
+        <ChevronDownIcon
+          aria-hidden
+          data-slot="accordion-trigger-icon"
+          className={cn(
+            "h-4 w-4 shrink-0 text-muted-foreground transition-transform duration-300",
+            EASE
+          )}
+        />
+      </AccordionPrimitive.Trigger>
+    </AccordionPrimitive.Header>
+  )
+}
+
+function AccordionContent({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Content>) {
+  return (
+    <AccordionPrimitive.Content
+      data-slot="accordion-content"
+      // Radix publishes the measured height as `--radix-accordion-content-height`
+      // and toggles `data-state`. The accordion-down/up keyframes (in
+      // shadcn-tailwind.css) interpolate height between that var and 0 for a real
+      // slide open/close — the Base UI variant achieves the same via transitions.
+      className="group/panel overflow-hidden bg-card font-body text-sm text-muted-foreground data-[state=open]:animate-accordion-down data-[state=closed]:animate-accordion-up"
+      {...props}
+    >
+      <div
+        className={cn(
+          "px-4 pt-2 pb-4 transition-[opacity,transform] duration-300 ease-out",
+          // Fade + nudge the content as the panel opens/closes, synced to the slide.
+          "group-data-[state=closed]/panel:-translate-y-1 group-data-[state=closed]/panel:opacity-0",
+          "[&_a]:underline [&_a]:underline-offset-3 [&_a]:hover:text-foreground [&_p:not(:last-child)]:mb-4",
+          className
+        )}
+      >
+        {children}
+      </div>
+    </AccordionPrimitive.Content>
+  )
+}
+
+export { Accordion, AccordionItem, AccordionTrigger, AccordionContent }

apps/gui/src/components/ui/badge.tsx

@@ -0,0 +1,49 @@
+import * as React from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+import { Slot } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+
+const badgeVariants = cva(
+  "group/badge inline-flex h-5 w-fit shrink-0 items-center justify-center gap-1 overflow-hidden rounded border-2 px-2 py-0.5 text-xs font-head font-medium whitespace-nowrap shadow-sm transition-all focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 aria-invalid:border-destructive [&>svg]:pointer-events-none [&>svg]:size-3!",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground [a]:hover:bg-primary/80",
+        secondary:
+          "bg-secondary text-secondary-foreground [a]:hover:bg-secondary/80",
+        destructive:
+          "bg-destructive text-destructive-foreground [a]:hover:bg-destructive/90",
+        outline:
+          "bg-transparent text-foreground [a]:hover:bg-muted [a]:hover:text-muted-foreground",
+        ghost:
+          "border-transparent bg-transparent shadow-none hover:bg-muted hover:text-muted-foreground dark:hover:bg-muted/50",
+        link: "border-transparent bg-transparent shadow-none text-primary underline-offset-4 hover:underline",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+)
+
+function Badge({
+  className,
+  variant = "default",
+  asChild = false,
+  ...props
+}: React.ComponentProps<"span"> &
+  VariantProps<typeof badgeVariants> & { asChild?: boolean }) {
+  const Comp = asChild ? Slot.Root : "span"
+
+  return (
+    <Comp
+      data-slot="badge"
+      data-variant={variant}
+      className={cn(badgeVariants({ variant }), className)}
+      {...props}
+    />
+  )
+}
+
+export { Badge, badgeVariants }

apps/gui/src/components/ui/button.tsx

@@ -0,0 +1,56 @@
+import * as React from "react"
+import { Slot } from "@radix-ui/react-slot"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:bg-primary/90",
+        destructive:
+          "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+        outline:
+          "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
+        secondary:
+          "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        ghost: "hover:bg-accent hover:text-accent-foreground",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default: "h-10 px-4 py-2",
+        sm: "h-9 rounded-md px-3",
+        lg: "h-11 rounded-md px-8",
+        icon: "h-10 w-10",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean
+}
+
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant, size, asChild = false, ...props }, ref) => {
+    const Comp = asChild ? Slot : "button"
+    return (
+      <Comp
+        className={cn(buttonVariants({ variant, size, className }))}
+        ref={ref}
+        {...props}
+      />
+    )
+  }
+)
+Button.displayName = "Button"
+
+export { Button, buttonVariants }

apps/gui/src/components/ui/card.tsx

@@ -0,0 +1,103 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+function Card({
+  className,
+  size = "default",
+  ...props
+}: React.ComponentProps<"div"> & { size?: "default" | "sm" }) {
+  return (
+    <div
+      data-slot="card"
+      data-size={size}
+      className={cn(
+        "group/card flex flex-col gap-(--card-spacing) overflow-hidden rounded border-2 bg-card py-(--card-spacing) text-sm text-card-foreground shadow-md [--card-spacing:--spacing(4)] has-data-[slot=card-footer]:pb-0 has-[>img:first-child]:pt-0 data-[size=sm]:[--card-spacing:--spacing(3)] data-[size=sm]:has-data-[slot=card-footer]:pb-0 *:[img:first-child]:rounded-t-xl *:[img:last-child]:rounded-b-xl",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-header"
+      className={cn(
+        "group/card-header @container/card-header grid auto-rows-min items-start gap-1 rounded-t-xl px-(--card-spacing) has-data-[slot=card-action]:grid-cols-[1fr_auto] has-data-[slot=card-description]:grid-rows-[auto_auto] [.border-b]:pb-(--card-spacing)",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardTitle({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-title"
+      className={cn(
+        "text-base leading-snug font-medium group-data-[size=sm]/card:text-sm",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardDescription({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-description"
+      className={cn("text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+function CardAction({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-action"
+      className={cn(
+        "col-start-2 row-span-2 row-start-1 self-start justify-self-end",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-content"
+      className={cn("px-(--card-spacing)", className)}
+      {...props}
+    />
+  )
+}
+
+function CardFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-footer"
+      className={cn(
+        "flex items-center rounded-b-xl border-t-2 bg-muted/50 p-(--card-spacing)",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  Card,
+  CardHeader,
+  CardFooter,
+  CardTitle,
+  CardAction,
+  CardDescription,
+  CardContent,
+}

apps/gui/src/components/ui/checkbox.tsx

@@ -0,0 +1,32 @@
+"use client"
+
+import * as React from "react"
+import { CheckIcon } from "lucide-react"
+import { Checkbox as CheckboxPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+
+function Checkbox({
+  className,
+  ...props
+}: React.ComponentProps<typeof CheckboxPrimitive.Root>) {
+  return (
+    <CheckboxPrimitive.Root
+      data-slot="checkbox"
+      className={cn(
+        "peer relative flex size-5 shrink-0 items-center justify-center rounded border-2 bg-input shadow-sm transition-colors outline-none group-has-disabled/field:opacity-50 after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive data-checked:border-border data-checked:bg-primary data-checked:text-primary-foreground",
+        className
+      )}
+      {...props}
+    >
+      <CheckboxPrimitive.Indicator
+        data-slot="checkbox-indicator"
+        className="grid place-content-center text-current transition-none [&>svg]:size-3.5"
+      >
+        <CheckIcon />
+      </CheckboxPrimitive.Indicator>
+    </CheckboxPrimitive.Root>
+  )
+}
+
+export { Checkbox }

apps/gui/src/components/ui/dialog.tsx

@@ -0,0 +1,167 @@
+"use client"
+
+import * as React from "react"
+import { XIcon } from "lucide-react"
+import { Dialog as DialogPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+import { Button } from "@/components/ui/button"
+
+function Dialog({
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Root>) {
+  return <DialogPrimitive.Root data-slot="dialog" {...props} />
+}
+
+function DialogTrigger({
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Trigger>) {
+  return <DialogPrimitive.Trigger data-slot="dialog-trigger" {...props} />
+}
+
+function DialogPortal({
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Portal>) {
+  return <DialogPrimitive.Portal data-slot="dialog-portal" {...props} />
+}
+
+function DialogClose({
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Close>) {
+  return <DialogPrimitive.Close data-slot="dialog-close" {...props} />
+}
+
+function DialogOverlay({
+  className,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Overlay>) {
+  return (
+    <DialogPrimitive.Overlay
+      data-slot="dialog-overlay"
+      className={cn(
+        "fixed inset-0 isolate z-50 bg-foreground/20 duration-100 supports-backdrop-filter:backdrop-blur-xs data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DialogContent({
+  className,
+  children,
+  showCloseButton = true,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Content> & {
+  showCloseButton?: boolean
+}) {
+  return (
+    <DialogPortal>
+      <DialogOverlay />
+      <DialogPrimitive.Content
+        data-slot="dialog-content"
+        className={cn(
+          "fixed top-1/2 left-1/2 z-50 grid w-full max-w-[calc(100%-2rem)] -translate-x-1/2 -translate-y-1/2 gap-4 rounded border-2 bg-popover p-4 text-sm text-popover-foreground shadow-md duration-100 outline-none sm:max-w-sm data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+          className
+        )}
+        {...props}
+      >
+        {children}
+        {showCloseButton && (
+          <DialogPrimitive.Close data-slot="dialog-close" asChild>
+            <Button
+              variant="ghost"
+              className="absolute top-2 right-2"
+              size="icon"
+            >
+              <XIcon />
+              <span className="sr-only">Close</span>
+            </Button>
+          </DialogPrimitive.Close>
+        )}
+      </DialogPrimitive.Content>
+    </DialogPortal>
+  )
+}
+
+function DialogHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="dialog-header"
+      className={cn("flex flex-col gap-2", className)}
+      {...props}
+    />
+  )
+}
+
+function DialogFooter({
+  className,
+  showCloseButton = false,
+  children,
+  ...props
+}: React.ComponentProps<"div"> & {
+  showCloseButton?: boolean
+}) {
+  return (
+    <div
+      data-slot="dialog-footer"
+      className={cn(
+        "-mx-4 -mb-4 flex flex-col-reverse gap-2 rounded-b-xl border-t-2 bg-muted/50 p-4 sm:flex-row sm:justify-end",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      {showCloseButton && (
+        <DialogPrimitive.Close asChild>
+          <Button variant="outline">Close</Button>
+        </DialogPrimitive.Close>
+      )}
+    </div>
+  )
+}
+
+function DialogTitle({
+  className,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Title>) {
+  return (
+    <DialogPrimitive.Title
+      data-slot="dialog-title"
+      className={cn(
+        "font-head text-base leading-none font-medium",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DialogDescription({
+  className,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Description>) {
+  return (
+    <DialogPrimitive.Description
+      data-slot="dialog-description"
+      className={cn(
+        "text-sm text-muted-foreground *:[a]:underline *:[a]:underline-offset-3 *:[a]:hover:text-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogOverlay,
+  DialogPortal,
+  DialogTitle,
+  DialogTrigger,
+}

apps/gui/src/components/ui/input.tsx

@@ -0,0 +1,19 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+function Input({ className, type, ...props }: React.ComponentProps<"input">) {
+  return (
+    <input
+      type={type}
+      data-slot="input"
+      className={cn(
+        "h-8 w-full min-w-0 rounded border-2 bg-input px-3 py-2 text-sm shadow-sm transition-colors outline-none file:inline-flex file:h-6 file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Input }

apps/gui/src/components/ui/label.tsx

@@ -0,0 +1,24 @@
+"use client"
+
+import * as React from "react"
+import { Label as LabelPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+
+function Label({
+  className,
+  ...props
+}: React.ComponentProps<typeof LabelPrimitive.Root>) {
+  return (
+    <LabelPrimitive.Root
+      data-slot="label"
+      className={cn(
+        "flex items-center gap-2 text-sm leading-none font-head font-medium select-none group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Label }

apps/gui/src/components/ui/navigation-menu.tsx

@@ -0,0 +1,167 @@
+import * as React from "react"
+import { cva } from "class-variance-authority"
+import { ChevronDownIcon } from "lucide-react"
+import { NavigationMenu as NavigationMenuPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+
+function NavigationMenu({
+  className,
+  children,
+  viewport = true,
+  ...props
+}: React.ComponentProps<typeof NavigationMenuPrimitive.Root> & {
+  viewport?: boolean
+}) {
+  return (
+    <NavigationMenuPrimitive.Root
+      data-slot="navigation-menu"
+      data-viewport={viewport}
+      className={cn(
+        "group/navigation-menu relative flex max-w-max flex-1 items-center justify-center",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      {viewport && <NavigationMenuViewport />}
+    </NavigationMenuPrimitive.Root>
+  )
+}
+
+function NavigationMenuList({
+  className,
+  ...props
+}: React.ComponentProps<typeof NavigationMenuPrimitive.List>) {
+  return (
+    <NavigationMenuPrimitive.List
+      data-slot="navigation-menu-list"
+      className={cn(
+        "group flex flex-1 list-none items-center justify-center gap-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function NavigationMenuItem({
+  className,
+  ...props
+}: React.ComponentProps<typeof NavigationMenuPrimitive.Item>) {
+  return (
+    <NavigationMenuPrimitive.Item
+      data-slot="navigation-menu-item"
+      className={cn("relative", className)}
+      {...props}
+    />
+  )
+}
+
+const navigationMenuTriggerStyle = cva(
+  "group/navigation-menu-trigger inline-flex h-9 w-max items-center justify-center rounded px-2.5 py-1.5 text-sm font-medium transition-all outline-none hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary disabled:pointer-events-none disabled:opacity-50 data-popup-open:bg-accent data-popup-open:text-accent-foreground data-open:bg-accent data-open:text-accent-foreground"
+)
+
+function NavigationMenuTrigger({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof NavigationMenuPrimitive.Trigger>) {
+  return (
+    <NavigationMenuPrimitive.Trigger
+      data-slot="navigation-menu-trigger"
+      className={cn(navigationMenuTriggerStyle(), "group", className)}
+      {...props}
+    >
+      {children}{" "}
+      <ChevronDownIcon
+        className="relative top-px ml-1 size-3 transition duration-300 group-data-popup-open/navigation-menu-trigger:rotate-180 group-data-open/navigation-menu-trigger:rotate-180"
+        aria-hidden="true"
+      />
+    </NavigationMenuPrimitive.Trigger>
+  )
+}
+
+function NavigationMenuContent({
+  className,
+  ...props
+}: React.ComponentProps<typeof NavigationMenuPrimitive.Content>) {
+  return (
+    <NavigationMenuPrimitive.Content
+      data-slot="navigation-menu-content"
+      className={cn(
+        "top-0 left-0 w-full p-1 ease-[cubic-bezier(0.22,1,0.36,1)] group-data-[viewport=false]/navigation-menu:top-full group-data-[viewport=false]/navigation-menu:mt-1.5 group-data-[viewport=false]/navigation-menu:overflow-hidden group-data-[viewport=false]/navigation-menu:rounded group-data-[viewport=false]/navigation-menu:border-2 group-data-[viewport=false]/navigation-menu:bg-popover group-data-[viewport=false]/navigation-menu:text-popover-foreground group-data-[viewport=false]/navigation-menu:shadow-md group-data-[viewport=false]/navigation-menu:duration-300 data-[motion=from-end]:slide-in-from-right-52 data-[motion=from-start]:slide-in-from-left-52 data-[motion=to-end]:slide-out-to-right-52 data-[motion=to-start]:slide-out-to-left-52 data-[motion^=from-]:animate-in data-[motion^=from-]:fade-in data-[motion^=to-]:animate-out data-[motion^=to-]:fade-out **:data-[slot=navigation-menu-link]:focus:ring-0 **:data-[slot=navigation-menu-link]:focus:outline-none md:absolute md:w-auto group-data-[viewport=false]/navigation-menu:data-open:animate-in group-data-[viewport=false]/navigation-menu:data-open:fade-in-0 group-data-[viewport=false]/navigation-menu:data-open:zoom-in-95 group-data-[viewport=false]/navigation-menu:data-closed:animate-out group-data-[viewport=false]/navigation-menu:data-closed:fade-out-0 group-data-[viewport=false]/navigation-menu:data-closed:zoom-out-95",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function NavigationMenuViewport({
+  className,
+  ...props
+}: React.ComponentProps<typeof NavigationMenuPrimitive.Viewport>) {
+  return (
+    <div
+      className={cn(
+        "absolute top-full left-0 isolate z-50 flex justify-center"
+      )}
+    >
+      <NavigationMenuPrimitive.Viewport
+        data-slot="navigation-menu-viewport"
+        className={cn(
+          "origin-top-center relative mt-1.5 h-(--radix-navigation-menu-viewport-height) w-full overflow-hidden rounded border-2 bg-popover text-popover-foreground shadow-md duration-100 md:w-(--radix-navigation-menu-viewport-width) data-open:animate-in data-open:zoom-in-90 data-closed:animate-out data-closed:zoom-out-90",
+          className
+        )}
+        {...props}
+      />
+    </div>
+  )
+}
+
+function NavigationMenuLink({
+  className,
+  ...props
+}: React.ComponentProps<typeof NavigationMenuPrimitive.Link>) {
+  return (
+    <NavigationMenuPrimitive.Link
+      data-slot="navigation-menu-link"
+      className={cn(
+        "flex items-center gap-2 rounded-sm p-2 text-sm transition-all outline-none hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary in-data-[slot=navigation-menu-content]:rounded-sm data-active:bg-accent data-active:text-accent-foreground [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function NavigationMenuIndicator({
+  className,
+  ...props
+}: React.ComponentProps<typeof NavigationMenuPrimitive.Indicator>) {
+  return (
+    <NavigationMenuPrimitive.Indicator
+      data-slot="navigation-menu-indicator"
+      className={cn(
+        "top-full z-1 flex h-1.5 items-end justify-center overflow-hidden data-[state=hidden]:animate-out data-[state=hidden]:fade-out data-[state=visible]:animate-in data-[state=visible]:fade-in",
+        className
+      )}
+      {...props}
+    >
+      <div className="relative top-[60%] h-2 w-2 rotate-45 rounded-tl-sm bg-border shadow-md" />
+    </NavigationMenuPrimitive.Indicator>
+  )
+}
+
+export {
+  NavigationMenu,
+  NavigationMenuList,
+  NavigationMenuItem,
+  NavigationMenuContent,
+  NavigationMenuTrigger,
+  NavigationMenuLink,
+  NavigationMenuIndicator,
+  NavigationMenuViewport,
+  navigationMenuTriggerStyle,
+}

apps/gui/src/components/ui/select.tsx

@@ -0,0 +1,190 @@
+"use client"
+
+import * as React from "react"
+import { CheckIcon, ChevronDownIcon, ChevronUpIcon } from "lucide-react"
+import { Select as SelectPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+
+function Select({
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Root>) {
+  return <SelectPrimitive.Root data-slot="select" {...props} />
+}
+
+function SelectGroup({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Group>) {
+  return (
+    <SelectPrimitive.Group
+      data-slot="select-group"
+      className={cn("scroll-my-1 p-1", className)}
+      {...props}
+    />
+  )
+}
+
+function SelectValue({
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Value>) {
+  return <SelectPrimitive.Value data-slot="select-value" {...props} />
+}
+
+function SelectTrigger({
+  className,
+  size = "default",
+  children,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Trigger> & {
+  size?: "sm" | "default"
+}) {
+  return (
+    <SelectPrimitive.Trigger
+      data-slot="select-trigger"
+      data-size={size}
+      className={cn(
+        "flex w-fit items-center justify-between gap-1.5 rounded border-2 bg-input py-2 pr-2 pl-2.5 text-sm whitespace-nowrap shadow-sm transition-colors outline-none select-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive data-placeholder:text-muted-foreground data-[size=default]:h-8 data-[size=sm]:h-7 data-[size=sm]:rounded *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-1.5 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <SelectPrimitive.Icon asChild>
+        <ChevronDownIcon className="pointer-events-none size-4 text-muted-foreground" />
+      </SelectPrimitive.Icon>
+    </SelectPrimitive.Trigger>
+  )
+}
+
+function SelectContent({
+  className,
+  children,
+  position = "item-aligned",
+  align = "center",
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Content>) {
+  return (
+    <SelectPrimitive.Portal>
+      <SelectPrimitive.Content
+        data-slot="select-content"
+        data-align-trigger={position === "item-aligned"}
+        className={cn("relative z-50 max-h-(--radix-select-content-available-height) min-w-36 origin-(--radix-select-content-transform-origin) overflow-x-hidden overflow-y-auto rounded border-2 bg-popover text-popover-foreground shadow-md duration-100 data-[align-trigger=true]:animate-none data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95", position ==="popper"&&"data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1", className )}
+        position={position}
+        align={align}
+        {...props}
+      >
+        <SelectScrollUpButton />
+        <SelectPrimitive.Viewport
+          data-position={position}
+          className={cn(
+            "data-[position=popper]:h-(--radix-select-trigger-height) data-[position=popper]:w-full data-[position=popper]:min-w-(--radix-select-trigger-width)",
+            position === "popper" && ""
+          )}
+        >
+          {children}
+        </SelectPrimitive.Viewport>
+        <SelectScrollDownButton />
+      </SelectPrimitive.Content>
+    </SelectPrimitive.Portal>
+  )
+}
+
+function SelectLabel({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Label>) {
+  return (
+    <SelectPrimitive.Label
+      data-slot="select-label"
+      className={cn("px-1.5 py-1 text-xs text-muted-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+function SelectItem({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Item>) {
+  return (
+    <SelectPrimitive.Item
+      data-slot="select-item"
+      className={cn(
+        "relative flex w-full cursor-default items-center gap-1.5 rounded-sm py-1 pr-8 pl-1.5 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2",
+        className
+      )}
+      {...props}
+    >
+      <span className="pointer-events-none absolute right-2 flex size-4 items-center justify-center">
+        <SelectPrimitive.ItemIndicator>
+          <CheckIcon className="pointer-events-none" />
+        </SelectPrimitive.ItemIndicator>
+      </span>
+      <SelectPrimitive.ItemText>{children}</SelectPrimitive.ItemText>
+    </SelectPrimitive.Item>
+  )
+}
+
+function SelectSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Separator>) {
+  return (
+    <SelectPrimitive.Separator
+      data-slot="select-separator"
+      className={cn("pointer-events-none -mx-1 my-1 h-px bg-border", className)}
+      {...props}
+    />
+  )
+}
+
+function SelectScrollUpButton({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.ScrollUpButton>) {
+  return (
+    <SelectPrimitive.ScrollUpButton
+      data-slot="select-scroll-up-button"
+      className={cn(
+        "z-10 flex cursor-default items-center justify-center bg-popover py-1 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    >
+      <ChevronUpIcon />
+    </SelectPrimitive.ScrollUpButton>
+  )
+}
+
+function SelectScrollDownButton({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.ScrollDownButton>) {
+  return (
+    <SelectPrimitive.ScrollDownButton
+      data-slot="select-scroll-down-button"
+      className={cn(
+        "z-10 flex cursor-default items-center justify-center bg-popover py-1 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    >
+      <ChevronDownIcon />
+    </SelectPrimitive.ScrollDownButton>
+  )
+}
+
+export {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectScrollDownButton,
+  SelectScrollUpButton,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+}

apps/gui/src/components/ui/separator.tsx

@@ -0,0 +1,28 @@
+"use client"
+
+import * as React from "react"
+import { Separator as SeparatorPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+
+function Separator({
+  className,
+  orientation = "horizontal",
+  decorative = true,
+  ...props
+}: React.ComponentProps<typeof SeparatorPrimitive.Root>) {
+  return (
+    <SeparatorPrimitive.Root
+      data-slot="separator"
+      decorative={decorative}
+      orientation={orientation}
+      className={cn(
+        "shrink-0 bg-border data-horizontal:h-px data-horizontal:w-full data-vertical:w-px data-vertical:self-stretch",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Separator }

apps/gui/src/components/ui/spinner.tsx

@@ -0,0 +1,17 @@
+import { Loader2Icon } from "lucide-react"
+
+import { cn } from "@/lib/utils"
+
+function Spinner({ className, ...props }: React.ComponentProps<"svg">) {
+  return (
+    <Loader2Icon
+      data-slot="spinner"
+      role="status"
+      aria-label="Loading"
+      className={cn("size-4 animate-spin", className)}
+      {...props}
+    />
+  )
+}
+
+export { Spinner }

apps/gui/src/components/ui/table.tsx

@@ -0,0 +1,116 @@
+"use client"
+
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+function Table({ className, ...props }: React.ComponentProps<"table">) {
+  return (
+    <div
+      data-slot="table-container"
+      className="relative w-full overflow-x-auto rounded border-2 shadow-md"
+    >
+      <table
+        data-slot="table"
+        className={cn("w-full caption-bottom text-sm", className)}
+        {...props}
+      />
+    </div>
+  )
+}
+
+function TableHeader({ className, ...props }: React.ComponentProps<"thead">) {
+  return (
+    <thead
+      data-slot="table-header"
+      className={cn("[&_tr]:border-b-2", className)}
+      {...props}
+    />
+  )
+}
+
+function TableBody({ className, ...props }: React.ComponentProps<"tbody">) {
+  return (
+    <tbody
+      data-slot="table-body"
+      className={cn("[&_tr:last-child]:border-0", className)}
+      {...props}
+    />
+  )
+}
+
+function TableFooter({ className, ...props }: React.ComponentProps<"tfoot">) {
+  return (
+    <tfoot
+      data-slot="table-footer"
+      className={cn(
+        "border-t-2 bg-muted/50 font-medium [&>tr]:last:border-b-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function TableRow({ className, ...props }: React.ComponentProps<"tr">) {
+  return (
+    <tr
+      data-slot="table-row"
+      className={cn(
+        "border-b-2 transition-colors hover:bg-accent has-aria-expanded:bg-accent data-[state=selected]:bg-accent",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function TableHead({ className, ...props }: React.ComponentProps<"th">) {
+  return (
+    <th
+      data-slot="table-head"
+      className={cn(
+        "h-10 bg-muted px-2 text-left align-middle font-head font-medium whitespace-nowrap text-foreground [&:has([role=checkbox])]:pr-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function TableCell({ className, ...props }: React.ComponentProps<"td">) {
+  return (
+    <td
+      data-slot="table-cell"
+      className={cn(
+        "p-2 align-middle whitespace-nowrap [&:has([role=checkbox])]:pr-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function TableCaption({
+  className,
+  ...props
+}: React.ComponentProps<"caption">) {
+  return (
+    <caption
+      data-slot="table-caption"
+      className={cn("mt-4 text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+export {
+  Table,
+  TableHeader,
+  TableBody,
+  TableFooter,
+  TableHead,
+  TableRow,
+  TableCell,
+  TableCaption,
+}

apps/gui/src/components/ui/tabs.tsx

@@ -0,0 +1,90 @@
+"use client"
+
+import * as React from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+import { Tabs as TabsPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+
+function Tabs({
+  className,
+  orientation = "horizontal",
+  ...props
+}: React.ComponentProps<typeof TabsPrimitive.Root>) {
+  return (
+    <TabsPrimitive.Root
+      data-slot="tabs"
+      data-orientation={orientation}
+      className={cn(
+        "group/tabs flex gap-2 data-horizontal:flex-col",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+const tabsListVariants = cva(
+  "group/tabs-list inline-flex w-fit items-center justify-center rounded p-1 text-muted-foreground group-data-horizontal/tabs:h-11 group-data-vertical/tabs:h-fit group-data-vertical/tabs:flex-col data-[variant=line]:rounded-none",
+  {
+    variants: {
+      variant: {
+        default: "border-2 bg-card shadow-sm",
+        line: "gap-1 bg-transparent",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+)
+
+function TabsList({
+  className,
+  variant = "default",
+  ...props
+}: React.ComponentProps<typeof TabsPrimitive.List> &
+  VariantProps<typeof tabsListVariants>) {
+  return (
+    <TabsPrimitive.List
+      data-slot="tabs-list"
+      data-variant={variant}
+      className={cn(tabsListVariants({ variant }), className)}
+      {...props}
+    />
+  )
+}
+
+function TabsTrigger({
+  className,
+  ...props
+}: React.ComponentProps<typeof TabsPrimitive.Trigger>) {
+  return (
+    <TabsPrimitive.Trigger
+      data-slot="tabs-trigger"
+      className={cn(
+        "relative inline-flex h-[calc(100%-1px)] flex-1 cursor-pointer items-center justify-center gap-1.5 rounded border-2 border-transparent px-4 py-2 text-sm font-head font-medium whitespace-nowrap text-foreground/60 transition-all group-data-vertical/tabs:w-full group-data-vertical/tabs:justify-start hover:text-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary disabled:pointer-events-none disabled:opacity-50 has-data-[icon=inline-end]:pr-1 has-data-[icon=inline-start]:pl-1 group-data-[variant=default]/tabs-list:data-active:border-border group-data-[variant=default]/tabs-list:data-active:shadow-sm group-data-[variant=line]/tabs-list:data-active:shadow-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        "group-data-[variant=line]/tabs-list:bg-transparent group-data-[variant=line]/tabs-list:data-active:bg-transparent",
+        "data-active:bg-primary data-active:text-primary-foreground group-data-[variant=line]/tabs-list:data-active:text-foreground",
+        "after:absolute after:bg-foreground after:opacity-0 after:transition-opacity group-data-horizontal/tabs:after:inset-x-0 group-data-horizontal/tabs:after:bottom-[-5px] group-data-horizontal/tabs:after:h-1 group-data-vertical/tabs:after:inset-y-0 group-data-vertical/tabs:after:-right-1 group-data-vertical/tabs:after:w-1 group-data-[variant=line]/tabs-list:data-active:after:opacity-100",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function TabsContent({
+  className,
+  ...props
+}: React.ComponentProps<typeof TabsPrimitive.Content>) {
+  return (
+    <TabsPrimitive.Content
+      data-slot="tabs-content"
+      className={cn("flex-1 text-sm outline-none", className)}
+      {...props}
+    />
+  )
+}
+
+export { Tabs, TabsList, TabsTrigger, TabsContent, tabsListVariants }

apps/gui/src/components/ui/textarea.tsx

@@ -0,0 +1,18 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
+  return (
+    <textarea
+      data-slot="textarea"
+      className={cn(
+        "flex field-sizing-content min-h-16 w-full rounded border-2 bg-input px-3 py-2 text-sm shadow-sm transition-colors outline-none placeholder:text-muted-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Textarea }

apps/gui/src/lib/simulation-types.ts

@@ -0,0 +1,70 @@
+export interface IntentInfo {
+  type: string;
+  description: string;
+  selfDescription?: string;
+  modifiers: string[];
+  targetIds: string[];
+  isValid?: boolean;
+  reason?: string;
+  minutesToAdvance?: number;
+}
+
+export interface LogEntry {
+  turn: number;
+  entityId: string;
+  entityName: string;
+  narrativeProse: string;
+  intents: IntentInfo[];
+  timestamp: string;
+  rawPrompt?: {
+    systemPrompt: string;
+    userContext: string;
+  };
+  usage?: {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    modelName?: string;
+    providerInstanceName?: string;
+    maxContext?: number;
+  };
+  decoderPrompt?: {
+    systemPrompt: string;
+    userContext: string;
+  };
+  decoderUsage?: {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    modelName?: string;
+    providerInstanceName?: string;
+    maxContext?: number;
+  };
+}
+
+export interface EntityInfo {
+  id: string;
+  name: string;
+  isPlayer: boolean;
+}
+
+export interface WaitingContext {
+  entityId: string;
+  name: string;
+  systemPrompt: string;
+  userContext: string;
+}
+
+export interface SimSnapshot {
+  id: string;
+  status: "running" | "waiting_player" | "done" | "error";
+  turn: number;
+  maxTurns: number;
+  scenarioName: string;
+  scenarioDescription: string;
+  entities: EntityInfo[];
+  log: LogEntry[];
+  entityIndex: number;
+  waitingEntity?: WaitingContext;
+  error?: string;
+}

apps/gui/src/lib/simulation.ts

@@ -0,0 +1,971 @@
+import dotenv from "dotenv";
+import Database from "better-sqlite3";
+import path from "path";
+import fs from "fs";
+import { SQLiteRepository } from "@omnia/core";
+
+// Load .env from monorepo root or apps/gui/
+const cwd = process.cwd();
+const envCandidates = [
+  path.resolve(cwd, ".env"),
+  path.resolve(cwd, "../../.env"),
+];
+for (const c of envCandidates) {
+  if (fs.existsSync(c) && fs.statSync(c).isFile()) {
+    dotenv.config({ path: c });
+    break;
+  }
+}
+
+import { BufferRepository, LedgerRepository, HandoffEngine, checkHandoffTrigger } from "@omnia/memory";
+import { Architect, AliasDeltaGenerator } from "@omnia/architect";
+import {
+  ActorAgent,
+  ActorPromptBuilder,
+  IActorProseGenerator,
+  buildBufferEntryForIntent,
+} from "@omnia/actor";
+import { GeminiProvider, ILLMProvider, MockLLMProvider, ProviderManager, OpenRouterProvider, IEmbeddingProvider, GeminiEmbeddingProvider, MockEmbeddingProvider, ModelProviderInstance } from "@omnia/llm";
+import { ScenarioLoader } from "@omnia/scenario";
+
+import type {
+  IntentInfo,
+  LogEntry,
+  EntityInfo,
+  WaitingContext,
+  SimSnapshot,
+} from "./simulation-types.js";
+
+export type { SimSnapshot, EntityInfo, LogEntry, IntentInfo, WaitingContext };
+
+class FixedProseGenerator implements IActorProseGenerator {
+  constructor(private prose: string) {}
+
+  async generate(
+    entityId: string,
+    systemPrompt: string,
+    userContext: string,
+  ): Promise<string> {
+    void entityId;
+    void systemPrompt;
+    void userContext;
+    return this.prose;
+  }
+}
+
+interface SavedState {
+  scenarioName: string;
+  scenarioDescription: string;
+  turn: number;
+  maxTurns: number;
+  entities: EntityInfo[];
+  playerEntityId: string | undefined;
+  entityIndex: number;
+  status: "running" | "waiting_player" | "done" | "error";
+  error?: string;
+  waitingEntity?: WaitingContext;
+  aliasDoneForTurn: boolean;
+  log: LogEntry[];
+  providerMappings: Record<string, string>;
+}
+
+function loadSessionState(db: Database.Database, id: string): SavedState | null {
+  try {
+    db.prepare(`
+      CREATE TABLE IF NOT EXISTS gui_meta (
+        id TEXT PRIMARY KEY,
+        state_json TEXT
+      )
+    `).run();
+    const row = db.prepare(`SELECT state_json FROM gui_meta WHERE id = ?`).get(id) as { state_json: string } | undefined;
+    return row ? (JSON.parse(row.state_json) as SavedState) : null;
+  } catch {
+    return null;
+  }
+}
+
+interface SimSession {
+  db: Database.Database;
+  dbPath: string;
+  coreRepo: SQLiteRepository;
+  bufferRepo: BufferRepository;
+  ledgerRepo: LedgerRepository;
+  worldInstanceId: string;
+  scenarioName: string;
+  scenarioDescription: string;
+  turn: number;
+  maxTurns: number;
+  entities: EntityInfo[];
+  playerEntityId: string | undefined;
+  entityIndex: number;
+  actorProvider: ILLMProvider;
+  validatorProvider: ILLMProvider;
+  decoderProvider: ILLMProvider;
+  timedeltaProvider: ILLMProvider;
+  handoffProvider: ILLMProvider;
+  embeddingProvider: IEmbeddingProvider;
+  architect: Architect;
+  aliasGenerator: AliasDeltaGenerator;
+  log: LogEntry[];
+  status: "running" | "waiting_player" | "done" | "error";
+  error?: string;
+  waitingEntity?: WaitingContext;
+  aliasDoneForTurn: boolean;
+  providerMappings: Record<string, string>;
+}
+
+class SimulationManager {
+  private sessions = new Map<string, SimSession>();
+
+  async create(
+    scenarioPath: string,
+    playEntityName?: string,
+    providerInstanceId?: string,
+  ): Promise<SimSnapshot> {
+    let activeInstance: ModelProviderInstance | null = providerInstanceId
+      ? ProviderManager.list().find((p) => p.id === providerInstanceId) || null
+      : ProviderManager.getActive("generative");
+
+    if (!activeInstance) {
+      const envKey = process.env.GOOGLE_API_KEY;
+      if (envKey) {
+        activeInstance = ProviderManager.create("Default (Env)", "google-genai", envKey, undefined, "generative");
+      }
+    }
+    if (!activeInstance) {
+      return {
+        id: "",
+        status: "error",
+        turn: 0,
+        maxTurns: 20,
+        scenarioName: "",
+        scenarioDescription: "",
+        entities: [],
+        log: [],
+        entityIndex: 0,
+        error: "No active LLM Provider Instance found. Please configure a key in Settings first.",
+      };
+    }
+
+    const scenarioJson = JSON.parse(fs.readFileSync(scenarioPath, "utf-8"));
+    const id = `sim-${Date.now()}`;
+
+    const dbDir = path.resolve(process.cwd(), "data");
+    fs.mkdirSync(dbDir, { recursive: true });
+    const dbPath = path.join(dbDir, `${id}.db`);
+    const db = new Database(dbPath);
+    const coreRepo = new SQLiteRepository(db);
+    const bufferRepo = new BufferRepository(db);
+    const ledgerRepo = new LedgerRepository(db);
+    const loader = new ScenarioLoader(coreRepo, bufferRepo);
+
+    const worldInstanceId = id;
+    await loader.initializeWorld(scenarioJson, worldInstanceId);
+
+    const worldState = coreRepo.loadWorldState(worldInstanceId);
+    if (!worldState) {
+      db.close();
+      return {
+        id: "",
+        status: "error",
+        turn: 0,
+        maxTurns: 20,
+        scenarioName: "",
+        scenarioDescription: "",
+        entities: [],
+        log: [],
+        entityIndex: 0,
+        error: "Failed to load world state after initialization.",
+      };
+    }
+
+    const rawEntities = Array.from(worldState.entities.values());
+    const entityInfos: EntityInfo[] = rawEntities.map((e) => ({
+      id: e.id,
+      name: (e.attributes.get("name")?.getValue() as string) || e.id,
+      isPlayer: false,
+    }));
+
+    let playerEntityId: string | undefined;
+    if (playEntityName) {
+      let matched = worldState.getEntity(playEntityName);
+      if (!matched) {
+        for (const ent of rawEntities) {
+          const nameAttr = ent.attributes.get("name")?.getValue() as
+            | string
+            | undefined;
+          if (nameAttr?.toLowerCase() === playEntityName.toLowerCase()) {
+            matched = ent;
+            break;
+          }
+        }
+      }
+      if (!matched) {
+        for (const ent of rawEntities) {
+          const nameAttr = ent.attributes.get("name")?.getValue() as
+            | string
+            | undefined;
+          if (
+            nameAttr?.toLowerCase().includes(playEntityName.toLowerCase()) ||
+            ent.id.toLowerCase().includes(playEntityName.toLowerCase())
+          ) {
+            matched = ent;
+            break;
+          }
+        }
+      }
+      if (matched) {
+        playerEntityId = matched.id;
+        const info = entityInfos.find((e) => e.id === matched.id);
+        if (info) info.isPlayer = true;
+      }
+    }
+
+    const list = ProviderManager.list();
+    const active = ProviderManager.getActive("generative") || activeInstance;
+    const mappings = ProviderManager.getMappings();
+
+    const resolveProviderForTask = (task: string): ILLMProvider => {
+      const mappedId = mappings[task];
+      let inst = mappedId ? list.find((p) => p.id === mappedId) : null;
+      if (!inst || inst.type !== "generative") {
+        inst = active;
+      }
+
+      const key = inst ? inst.apiKey : (process.env.GOOGLE_API_KEY || "");
+      const providerName = inst ? inst.providerName : "google-genai";
+      const modelName = inst ? inst.modelName : undefined;
+      const instanceName = inst ? inst.name : undefined;
+      const maxContext = inst ? inst.maxContext : undefined;
+
+      if (providerName === "google-genai") {
+        return new GeminiProvider(key, modelName, instanceName, maxContext);
+      } else if (providerName === "openrouter") {
+        return new OpenRouterProvider(key, modelName, instanceName, maxContext);
+      } else {
+        return new MockLLMProvider([]);
+      }
+    };
+
+    const resolveEmbeddingProvider = (): IEmbeddingProvider => {
+      const mappedId = mappings["embeddings"];
+      let inst = mappedId ? list.find((p) => p.id === mappedId) : null;
+      if (!inst || inst.type !== "embedding") {
+        inst = ProviderManager.getActive("embedding");
+      }
+
+      const key = inst ? inst.apiKey : (process.env.GOOGLE_API_KEY || "");
+      const providerName = inst ? inst.providerName : "google-genai";
+      const modelName = inst ? inst.modelName : undefined;
+
+      if (providerName === "google-genai") {
+        return new GeminiEmbeddingProvider(key, modelName);
+      } else {
+        return new MockEmbeddingProvider(modelName);
+      }
+    };
+
+    const actorProvider = resolveProviderForTask("actor-prose");
+    const validatorProvider = resolveProviderForTask("llm-validator");
+    const decoderProvider = resolveProviderForTask("intent-decoder");
+    const timedeltaProvider = resolveProviderForTask("timedelta");
+    const handoffProvider = resolveProviderForTask("handoff");
+    const embeddingProvider = resolveEmbeddingProvider();
+
+    const architect = new Architect(
+      { validator: validatorProvider, timedelta: timedeltaProvider },
+      coreRepo,
+    );
+    const aliasGenerator = new AliasDeltaGenerator(actorProvider);
+
+    const session: SimSession = {
+      db,
+      dbPath,
+      coreRepo,
+      bufferRepo,
+      ledgerRepo,
+      worldInstanceId: worldInstanceId,
+      scenarioName: scenarioJson.name,
+      scenarioDescription: scenarioJson.description || "",
+      turn: 1,
+      maxTurns: 20,
+      entities: entityInfos,
+      playerEntityId,
+      entityIndex: 0,
+      actorProvider,
+      validatorProvider,
+      decoderProvider,
+      timedeltaProvider,
+      handoffProvider,
+      embeddingProvider,
+      architect,
+      aliasGenerator,
+      log: [],
+      status: "running",
+      aliasDoneForTurn: false,
+      providerMappings: mappings,
+    };
+
+    this.sessions.set(id, session);
+    return this.snapshot(session);
+  }
+
+  async step(id: string): Promise<SimSnapshot | null> {
+    const session = this.sessions.get(id);
+    if (!session) return null;
+    if (session.status !== "running") return this.snapshot(session);
+
+    try {
+      if (session.turn > session.maxTurns) {
+        session.status = "done";
+        this.save(session);
+        return this.snapshot(session);
+      }
+
+      if (!session.aliasDoneForTurn && session.entityIndex === 0) {
+        await this.runAliasResolution(session);
+        await this.runHandoffResolution(session);
+        session.aliasDoneForTurn = true;
+        this.save(session);
+        return this.snapshot(session);
+      }
+
+      if (session.entityIndex >= session.entities.length) {
+        session.turn++;
+        session.entityIndex = 0;
+        session.aliasDoneForTurn = false;
+        this.save(session);
+        return this.snapshot(session);
+      }
+
+      const info = session.entities[session.entityIndex];
+
+      if (info.isPlayer) {
+        await this.preparePlayerTurn(session, info);
+        this.save(session);
+        return this.snapshot(session);
+      }
+
+      await this.processNpcTurn(session, info);
+      session.entityIndex++;
+    } catch (err) {
+      session.status = "error";
+      session.error = err instanceof Error ? err.message : String(err);
+    }
+
+    this.save(session);
+    return this.snapshot(session);
+  }
+
+  async submitPlayerAction(
+    id: string,
+    prose: string,
+  ): Promise<SimSnapshot | null> {
+    const session = this.sessions.get(id);
+    if (!session) return null;
+    if (session.status !== "waiting_player") return this.snapshot(session);
+    if (!session.waitingEntity) return this.snapshot(session);
+
+    const ctx = session.waitingEntity;
+    session.waitingEntity = undefined;
+    session.status = "running";
+
+    try {
+      const worldState = session.coreRepo.loadWorldState(
+        session.worldInstanceId,
+      );
+      if (!worldState) throw new Error("World state lost");
+
+      const entity = worldState.getEntity(ctx.entityId);
+      if (!entity) throw new Error(`Player entity "${ctx.entityId}" not found`);
+
+      const playerActor = new ActorAgent(
+        { actor: session.actorProvider, decoder: session.decoderProvider },
+        session.bufferRepo,
+        session.ledgerRepo,
+        20,
+        new FixedProseGenerator(prose),
+      );
+
+      const result = await playerActor.act(worldState, entity);
+
+      const entry: LogEntry = {
+        turn: session.turn,
+        entityId: ctx.entityId,
+        entityName: ctx.name,
+        narrativeProse: result.narrativeProse,
+        intents: [],
+        timestamp: worldState.clock.get().toISOString(),
+        rawPrompt: {
+          systemPrompt: ctx.systemPrompt,
+          userContext: ctx.userContext,
+        },
+      };
+
+      if (session.decoderProvider.lastCalls && session.decoderProvider.lastCalls.length > 0) {
+        const call = session.decoderProvider.lastCalls[session.decoderProvider.lastCalls.length - 1];
+        entry.decoderPrompt = {
+          systemPrompt: call.systemPrompt,
+          userContext: call.userContext,
+        };
+        entry.decoderUsage = call.usage;
+      }
+
+      for (const intent of result.intents.intents) {
+        const outcome = await session.architect.processIntent(
+          worldState,
+          intent,
+        );
+        const ts = worldState.clock.get().toISOString();
+
+        entry.intents.push({
+          type: intent.type,
+          description: intent.description,
+          selfDescription: intent.selfDescription,
+          modifiers: intent.modifiers || [],
+          targetIds: intent.targetIds,
+          isValid: outcome.isValid,
+          reason: outcome.reason,
+          minutesToAdvance: outcome.timeDelta?.minutesToAdvance,
+        });
+
+        const actorEntry = buildBufferEntryForIntent(
+          intent,
+          ts,
+          entity.locationId,
+        );
+        if (intent.type === "action") {
+          actorEntry.outcome = {
+            isValid: outcome.isValid,
+            reason: outcome.reason,
+          };
+        }
+        session.bufferRepo.save(actorEntry);
+
+        if (
+          entity.locationId &&
+          (intent.type === "dialogue" || intent.type === "action")
+        ) {
+          for (const [, other] of worldState.entities) {
+            if (
+              other.id !== ctx.entityId &&
+              other.locationId === entity.locationId
+            ) {
+              const observerEntry = buildBufferEntryForIntent(
+                intent,
+                ts,
+                entity.locationId,
+              );
+              if (intent.type === "action") {
+                observerEntry.outcome = {
+                  isValid: outcome.isValid,
+                  reason: outcome.reason,
+                };
+              }
+              session.bufferRepo.save({
+                ...observerEntry,
+                ownerId: other.id,
+              });
+            }
+          }
+        }
+      }
+
+      session.log.push(entry);
+      session.coreRepo.saveWorldState(worldState);
+      session.entityIndex++;
+    } catch (err) {
+      session.status = "error";
+      session.error = err instanceof Error ? err.message : String(err);
+    }
+
+    this.save(session);
+    return this.snapshot(session);
+  }
+
+  private async preparePlayerTurn(
+    session: SimSession,
+    info: EntityInfo,
+  ): Promise<void> {
+    const worldState = session.coreRepo.loadWorldState(
+      session.worldInstanceId,
+    );
+    if (!worldState) throw new Error("World state lost");
+
+    const entity = worldState.getEntity(info.id);
+    if (!entity) throw new Error(`Entity "${info.id}" not found`);
+
+    const promptBuilder = new ActorPromptBuilder(session.bufferRepo, session.ledgerRepo, 20);
+    const { systemPrompt, userContext } = promptBuilder.build(
+      worldState,
+      entity,
+    );
+
+    session.waitingEntity = {
+      entityId: info.id,
+      name: info.name,
+      systemPrompt,
+      userContext,
+    };
+    session.status = "waiting_player";
+  }
+
+  private async processNpcTurn(
+    session: SimSession,
+    info: EntityInfo,
+  ): Promise<void> {
+    const worldState = session.coreRepo.loadWorldState(
+      session.worldInstanceId,
+    );
+    if (!worldState) throw new Error("World state lost");
+
+    const entity = worldState.getEntity(info.id);
+    if (!entity) throw new Error(`Entity "${info.id}" not found`);
+
+    const actor = new ActorAgent(
+      { actor: session.actorProvider, decoder: session.decoderProvider },
+      session.bufferRepo,
+      session.ledgerRepo,
+      20,
+    );
+    const result = await actor.act(worldState, entity);
+
+    const entry: LogEntry = {
+      turn: session.turn,
+      entityId: info.id,
+      entityName: info.name,
+      narrativeProse: result.narrativeProse,
+      intents: [],
+      timestamp: worldState.clock.get().toISOString(),
+    };
+
+    if (session.actorProvider.lastCalls && session.actorProvider.lastCalls.length > 0) {
+      const actorCall = session.actorProvider.lastCalls[session.actorProvider.lastCalls.length - 1];
+      entry.rawPrompt = {
+        systemPrompt: actorCall.systemPrompt,
+        userContext: actorCall.userContext,
+      };
+      entry.usage = actorCall.usage;
+    }
+
+    if (session.decoderProvider.lastCalls && session.decoderProvider.lastCalls.length > 0) {
+      const decoderCall = session.decoderProvider.lastCalls[session.decoderProvider.lastCalls.length - 1];
+      entry.decoderPrompt = {
+        systemPrompt: decoderCall.systemPrompt,
+        userContext: decoderCall.userContext,
+      };
+      entry.decoderUsage = decoderCall.usage;
+    }
+
+    for (const intent of result.intents.intents) {
+      const outcome = await session.architect.processIntent(
+        worldState,
+        intent,
+      );
+      const ts = worldState.clock.get().toISOString();
+
+      entry.intents.push({
+        type: intent.type,
+        description: intent.description,
+        selfDescription: intent.selfDescription,
+        modifiers: intent.modifiers || [],
+        targetIds: intent.targetIds,
+        isValid: outcome.isValid,
+        reason: outcome.reason,
+        minutesToAdvance: outcome.timeDelta?.minutesToAdvance,
+      });
+
+      const actorEntry = buildBufferEntryForIntent(
+        intent,
+        ts,
+        entity.locationId,
+      );
+      if (intent.type === "action") {
+        actorEntry.outcome = {
+          isValid: outcome.isValid,
+          reason: outcome.reason,
+        };
+      }
+      session.bufferRepo.save(actorEntry);
+
+      if (
+        entity.locationId &&
+        (intent.type === "dialogue" || intent.type === "action")
+      ) {
+        for (const [, other] of worldState.entities) {
+          if (
+            other.id !== info.id &&
+            other.locationId === entity.locationId
+          ) {
+            const observerEntry = buildBufferEntryForIntent(
+              intent,
+              ts,
+              entity.locationId,
+            );
+            if (intent.type === "action") {
+              observerEntry.outcome = {
+                isValid: outcome.isValid,
+                reason: outcome.reason,
+              };
+            }
+            session.bufferRepo.save({ ...observerEntry, ownerId: other.id });
+          }
+        }
+      }
+    }
+
+    session.log.push(entry);
+    session.coreRepo.saveWorldState(worldState);
+  }
+
+  private async runHandoffResolution(session: SimSession): Promise<void> {
+    const worldState = session.coreRepo.loadWorldState(
+      session.worldInstanceId,
+    );
+    if (!worldState) throw new Error("World state lost");
+
+    const handoffEngine = new HandoffEngine(
+      session.handoffProvider,
+      session.embeddingProvider,
+      session.bufferRepo,
+      session.ledgerRepo,
+    );
+
+    const entities = Array.from(worldState.entities.values());
+    for (const entity of entities) {
+      const bufferEntries = session.bufferRepo.listForOwner(entity.id);
+      const maxContext = session.handoffProvider.maxContext !== undefined ? session.handoffProvider.maxContext : 32768;
+
+      const trigger = checkHandoffTrigger(entity, bufferEntries, worldState.clock.get(), maxContext);
+      if (trigger !== "none") {
+        await handoffEngine.runHandoff(entity, bufferEntries, worldState.clock.get());
+      }
+    }
+  }
+
+  private async runAliasResolution(session: SimSession): Promise<void> {
+    const worldState = session.coreRepo.loadWorldState(
+      session.worldInstanceId,
+    );
+    if (!worldState) throw new Error("World state lost");
+
+    const entities = Array.from(worldState.entities.values());
+    for (const viewer of entities) {
+      if (!viewer.locationId) continue;
+      for (const target of entities) {
+        if (viewer.id === target.id) continue;
+        if (
+          target.locationId === viewer.locationId &&
+          !viewer.aliases.has(target.id)
+        ) {
+          const alias = await session.aliasGenerator.generate(viewer, target);
+          viewer.aliases.set(target.id, alias);
+          session.coreRepo.saveEntity(viewer, worldState.id);
+        }
+      }
+    }
+  }
+
+  close(id: string): void {
+    const session = this.sessions.get(id);
+    if (session) {
+      session.db.close();
+      this.sessions.delete(id);
+    }
+  }
+
+  deleteSession(id: string): void {
+    const session = this.sessions.get(id);
+    if (session) {
+      session.db.close();
+      this.sessions.delete(id);
+    }
+    const dbDir = path.resolve(process.cwd(), "data");
+    const dbPath = path.join(dbDir, `${id}.db`);
+    if (fs.existsSync(dbPath)) {
+      try {
+        fs.unlinkSync(dbPath);
+      } catch (err) {
+        console.error(`Failed to delete session file ${dbPath}:`, err);
+      }
+    }
+  }
+
+  async load(id: string): Promise<SimSnapshot | null> {
+    const active = this.sessions.get(id);
+    if (active) {
+      return this.snapshot(active);
+    }
+
+    const dbDir = path.resolve(process.cwd(), "data");
+    const dbPath = path.join(dbDir, `${id}.db`);
+    if (!fs.existsSync(dbPath)) return null;
+
+    try {
+      const db = new Database(dbPath);
+      const state = loadSessionState(db, id);
+      if (!state) {
+        db.close();
+        return null;
+      }
+
+      const list = ProviderManager.list();
+      const active = ProviderManager.getActive("generative");
+      const mappings = state.providerMappings || {};
+
+      const resolveProviderForTask = (task: string): ILLMProvider => {
+        const mappedId = mappings[task];
+        let inst = mappedId ? list.find((p) => p.id === mappedId) : null;
+        if (!inst || inst.type !== "generative") {
+          inst = active;
+        }
+
+        if (!inst) {
+          const envKey = process.env.GOOGLE_API_KEY;
+          if (envKey) {
+            inst = ProviderManager.create("Default (Env)", "google-genai", envKey, undefined, "generative");
+          }
+        }
+
+        if (!inst) {
+          throw new Error(`No active LLM Provider Instance found for task "${task}". Please configure a key in Settings first.`);
+        }
+
+        if (inst.providerName === "google-genai") {
+          return new GeminiProvider(inst.apiKey, inst.modelName, inst.name, inst.maxContext);
+        } else if (inst.providerName === "openrouter") {
+          return new OpenRouterProvider(inst.apiKey, inst.modelName, inst.name, inst.maxContext);
+        } else {
+          return new MockLLMProvider([]);
+        }
+      };
+
+      const resolveEmbeddingProvider = (): IEmbeddingProvider => {
+        const mappedId = mappings["embeddings"];
+        let inst = mappedId ? list.find((p) => p.id === mappedId) : null;
+        if (!inst || inst.type !== "embedding") {
+          inst = ProviderManager.getActive("embedding");
+        }
+        if (!inst) {
+          const envKey = process.env.GOOGLE_API_KEY;
+          if (envKey) {
+            inst = ProviderManager.create("Default Embed (Env)", "google-genai", envKey, "gemini-embedding-001", "embedding");
+          }
+        }
+
+        if (!inst) {
+          throw new Error(`No active Embedding Provider Instance found for task "embeddings". Please configure an embedding key in Settings first.`);
+        }
+
+        if (inst.providerName === "google-genai") {
+          return new GeminiEmbeddingProvider(inst.apiKey, inst.modelName);
+        } else {
+          return new MockEmbeddingProvider(inst.modelName);
+        }
+      };
+
+      const coreRepo = new SQLiteRepository(db);
+      const bufferRepo = new BufferRepository(db);
+      const ledgerRepo = new LedgerRepository(db);
+
+      const actorProvider = resolveProviderForTask("actor-prose");
+      const validatorProvider = resolveProviderForTask("llm-validator");
+      const decoderProvider = resolveProviderForTask("intent-decoder");
+      const timedeltaProvider = resolveProviderForTask("timedelta");
+      const handoffProvider = resolveProviderForTask("handoff");
+      const embeddingProvider = resolveEmbeddingProvider();
+
+      const architect = new Architect(
+        { validator: validatorProvider, timedelta: timedeltaProvider },
+        coreRepo,
+      );
+      const aliasGenerator = new AliasDeltaGenerator(actorProvider);
+
+      const session: SimSession = {
+        db,
+        dbPath,
+        coreRepo,
+        bufferRepo,
+        ledgerRepo,
+        worldInstanceId: id,
+        scenarioName: state.scenarioName,
+        scenarioDescription: state.scenarioDescription,
+        turn: state.turn,
+        maxTurns: state.maxTurns,
+        entities: state.entities || [],
+        playerEntityId: state.playerEntityId,
+        entityIndex: state.entityIndex,
+        actorProvider,
+        validatorProvider,
+        decoderProvider,
+        timedeltaProvider,
+        handoffProvider,
+        embeddingProvider,
+        architect,
+        aliasGenerator,
+        log: state.log || [],
+        status: state.status,
+        error: state.error,
+        waitingEntity: state.waitingEntity,
+        aliasDoneForTurn: state.aliasDoneForTurn || false,
+        providerMappings: mappings,
+      };
+
+      this.sessions.set(id, session);
+      return this.snapshot(session);
+    } catch (err) {
+      console.error(`Failed to load session ${id}:`, err);
+      return null;
+    }
+  }
+
+  listSavedSessions(): SimSnapshot[] {
+    const dbDir = path.resolve(process.cwd(), "data");
+    if (!fs.existsSync(dbDir)) return [];
+
+    const snapshots: SimSnapshot[] = [];
+    const files = fs.readdirSync(dbDir).filter(f => f.startsWith("sim-") && f.endsWith(".db"));
+
+    for (const file of files) {
+      const id = file.replace(".db", "");
+      const dbPath = path.join(dbDir, file);
+
+      const active = this.sessions.get(id);
+      if (active) {
+        snapshots.push(this.snapshot(active));
+        continue;
+      }
+
+      try {
+        const db = new Database(dbPath);
+        const state = loadSessionState(db, id);
+        db.close();
+
+        if (state) {
+          snapshots.push({
+            id,
+            status: state.status,
+            turn: state.turn,
+            maxTurns: state.maxTurns,
+            scenarioName: state.scenarioName,
+            scenarioDescription: state.scenarioDescription,
+            entities: state.entities || [],
+            log: state.log || [],
+            entityIndex: state.entityIndex,
+            waitingEntity: state.waitingEntity,
+            error: state.error,
+          });
+        }
+      } catch {
+        /* skip */
+      }
+    }
+
+    return snapshots.sort((a, b) => {
+      const tsA = parseInt(a.id.replace("sim-", ""), 10) || 0;
+      const tsB = parseInt(b.id.replace("sim-", ""), 10) || 0;
+      return tsB - tsA;
+    });
+  }
+
+  async regenerateAllEmbeddings(newProviderInstanceId?: string): Promise<void> {
+    const dbDir = path.resolve(process.cwd(), "data");
+    if (!fs.existsSync(dbDir)) return;
+
+    const files = fs.readdirSync(dbDir).filter(f => f.startsWith("sim-") && f.endsWith(".db"));
+
+    const list = ProviderManager.list();
+    let inst = newProviderInstanceId ? list.find((p) => p.id === newProviderInstanceId) : null;
+    if (!inst || inst.type !== "embedding") {
+      inst = ProviderManager.getActive("embedding");
+    }
+
+    const key = inst ? inst.apiKey : (process.env.GOOGLE_API_KEY || "");
+    const providerName = inst ? inst.providerName : "google-genai";
+    const modelName = inst ? inst.modelName : undefined;
+
+    let embeddingProvider: IEmbeddingProvider;
+    if (providerName === "google-genai") {
+      embeddingProvider = new GeminiEmbeddingProvider(key, modelName);
+    } else {
+      embeddingProvider = new MockEmbeddingProvider(modelName);
+    }
+
+    for (const file of files) {
+      const dbPath = path.join(dbDir, file);
+      const id = file.replace(".db", "");
+      const activeSession = this.sessions.get(id);
+      const db = activeSession ? activeSession.db : new Database(dbPath);
+
+      try {
+        const rows = db.prepare(`SELECT id, content FROM ledger_entries`).all() as { id: string; content: string }[];
+        
+        for (const row of rows) {
+          const vector = await embeddingProvider.embed(row.content);
+          const buffer = Buffer.from(new Float32Array(vector).buffer);
+          db.prepare(`UPDATE ledger_entries SET embedding = ? WHERE id = ?`).run(buffer, row.id);
+        }
+      } catch (err) {
+        console.error(`Failed to regenerate embeddings for ${file}:`, err);
+      } finally {
+        if (!activeSession) {
+          db.close();
+        }
+      }
+    }
+  }
+
+  private save(session: SimSession): void {
+    const state: SavedState = {
+      scenarioName: session.scenarioName,
+      scenarioDescription: session.scenarioDescription,
+      turn: session.turn,
+      maxTurns: session.maxTurns,
+      entities: session.entities,
+      playerEntityId: session.playerEntityId,
+      entityIndex: session.entityIndex,
+      status: session.status,
+      error: session.error,
+      waitingEntity: session.waitingEntity,
+      aliasDoneForTurn: session.aliasDoneForTurn,
+      log: session.log,
+      providerMappings: session.providerMappings,
+    };
+
+    session.db.prepare(`
+      CREATE TABLE IF NOT EXISTS gui_meta (
+        id TEXT PRIMARY KEY,
+        state_json TEXT
+      )
+    `).run();
+
+    session.db.prepare(`
+      INSERT INTO gui_meta (id, state_json)
+      VALUES (?, ?)
+      ON CONFLICT(id) DO UPDATE SET state_json = excluded.state_json
+    `).run(session.worldInstanceId, JSON.stringify(state));
+  }
+
+  getSnapshot(id: string): SimSnapshot | null {
+    const session = this.sessions.get(id);
+    return session ? this.snapshot(session) : null;
+  }
+
+  private snapshot(session: SimSession): SimSnapshot {
+    return {
+      id: session.worldInstanceId,
+      status: session.status,
+      turn: session.turn,
+      maxTurns: session.maxTurns,
+      scenarioName: session.scenarioName,
+      scenarioDescription: session.scenarioDescription,
+      entities: session.entities,
+      log: session.log,
+      entityIndex: session.entityIndex,
+      waitingEntity: session.waitingEntity,
+      error: session.error,
+    };
+  }
+}
+
+export const simulationManager = new SimulationManager();

apps/gui/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

apps/gui/tsconfig.json

@@ -1,7 +1,11 @@
 {
   "compilerOptions": {
-    "target": "ES2017",
-    "lib": ["dom", "dom.iterable", "esnext"],
+    "target": "ES2022",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
     "allowJs": true,
     "skipLibCheck": true,
     "strict": true,
@@ -19,7 +23,9 @@
       }
     ],
     "paths": {
-      "@/*": ["./src/*"]
+      "@/*": [
+        "./src/*"
+      ]
     }
   },
   "include": [
@@ -27,8 +33,9 @@
     "**/*.ts",
     "**/*.tsx",
     ".next/types/**/*.ts",
-    ".next/dev/types/**/*.ts",
-    "**/*.mts"
+    ".next/dev/types/**/*.ts"
   ],
-  "exclude": ["node_modules"]
+  "exclude": [
+    "node_modules"
+  ]
 }

cli/package.json

@@ -1,21 +0,0 @@
-{
-  "name": "@omnia/cli",
-  "version": "0.0.0",
-  "private": true,
-  "type": "module",
-  "exports": {
-    ".": "./dist/index.js"
-  },
-  "dependencies": {
-    "@omnia/core": "workspace:*",
-    "@omnia/spatial": "workspace:*",
-    "@omnia/memory": "workspace:*",
-    "@omnia/intent": "workspace:*",
-    "@omnia/architect": "workspace:*",
-    "@omnia/actor": "workspace:*",
-    "@omnia/llm": "workspace:*",
-    "@omnia/scenario-core": "workspace:*",
-    "better-sqlite3": "^12.11.1",
-    "dotenv": "^17.4.2"
-  }
-}

cli/src/index.ts

@@ -1,426 +0,0 @@
-import dotenv from "dotenv";
-import fs from "fs";
-import path from "path";
-import readline from "readline";
-import Database from "better-sqlite3";
-import { WorldState, SQLiteRepository } from "@omnia/core";
-import { BufferRepository } from "@omnia/memory";
-import { Architect, AliasDeltaGenerator } from "@omnia/architect";
-import {
-  ActorAgent,
-  ActorPromptBuilder,
-  IActorProseGenerator,
-  buildBufferEntryForIntent,
-} from "@omnia/actor";
-import { GeminiProvider } from "@omnia/llm";
-import { ScenarioLoader } from "@omnia/scenario-core";
-
-// Load environment variables
-dotenv.config();
-
-class CLIProseGenerator implements IActorProseGenerator {
-  async generate(
-    entityId: string,
-    systemPrompt: string,
-    userContext: string,
-  ): Promise<string> {
-    console.log(
-      "\n================================================================================",
-    );
-    console.log(`YOUR TURN: Playing as character "${entityId}"`);
-    console.log(
-      "================================================================================",
-    );
-    console.log(userContext);
-    console.log(
-      "================================================================================",
-    );
-
-    const rl = readline.createInterface({
-      input: process.stdin,
-      output: process.stdout,
-    });
-
-    return new Promise<string>((resolve) => {
-      rl.question(
-        "\nDescribe what your character does, says, or thinks (or type 'exit' to quit):\n> ",
-        (answer) => {
-          rl.close();
-          const trimmed = answer.trim();
-          if (trimmed.toLowerCase() === "exit") {
-            console.log("\nExiting simulation. Goodbye!");
-            process.exit(0);
-          }
-          resolve(trimmed);
-        },
-      );
-    });
-  }
-}
-
-/**
- * Checks for co-located entities who do not have subjective aliases for each other,
- * and calls the AliasDeltaGenerator to synthesize names based on visible attributes.
- */
-async function runAliasResolution(
-  worldState: WorldState,
-  aliasGenerator: AliasDeltaGenerator,
-  coreRepo: SQLiteRepository,
-): Promise<void> {
-  const entities = Array.from(worldState.entities.values());
-  for (const viewer of entities) {
-    if (!viewer.locationId) continue;
-
-    for (const target of entities) {
-      if (viewer.id === target.id) continue;
-      if (target.locationId === viewer.locationId) {
-        if (!viewer.aliases.has(target.id)) {
-          const alias = await aliasGenerator.generate(viewer, target);
-          viewer.aliases.set(target.id, alias);
-          console.log(
-            `\n[Alias Resolved] "${viewer.id}" sees "${target.id}" -> alias: "${alias}"`,
-          );
-          // Save the viewer state with the new alias
-          coreRepo.saveEntity(viewer, worldState.id);
-        }
-      }
-    }
-  }
-}
-
-async function main() {
-  const args = process.argv.slice(2);
-
-  const logFileIndex = args.indexOf("--log-file");
-  let logStream: fs.WriteStream | undefined;
-  if (logFileIndex !== -1 && args[logFileIndex + 1]) {
-    const logFilePath = path.resolve(args[logFileIndex + 1]);
-    logStream = fs.createWriteStream(logFilePath, {
-      flags: "w",
-      encoding: "utf-8",
-    });
-
-    // Monkeypatch console.log
-    const originalLog = console.log;
-    console.log = (...messageArgs: unknown[]) => {
-      originalLog(...messageArgs);
-      const text =
-        messageArgs
-          .map((arg) => {
-            if (typeof arg === "object" && arg !== null) {
-              try {
-                return JSON.stringify(arg, null, 2);
-              } catch {
-                return String(arg);
-              }
-            }
-            return String(arg);
-          })
-          .join(" ") + "\n";
-      logStream?.write(text);
-    };
-
-    // Monkeypatch console.error
-    const originalError = console.error;
-    console.error = (...messageArgs: unknown[]) => {
-      originalError(...messageArgs);
-      const text =
-        messageArgs
-          .map((arg) => {
-            if (typeof arg === "object" && arg !== null) {
-              try {
-                return JSON.stringify(arg, null, 2);
-              } catch {
-                return String(arg);
-              }
-            }
-            return String(arg);
-          })
-          .join(" ") + "\n";
-      logStream?.write("[ERROR] " + text);
-    };
-
-    process.on("exit", () => {
-      logStream?.end();
-    });
-  }
-  const scenarioArgIndex = args.indexOf("--scenario");
-  const scenarioPath =
-    scenarioArgIndex !== -1
-      ? args[scenarioArgIndex + 1]
-      : "content/demo/scenarios/talking-room.json";
-
-  const playArgIndex = args.indexOf("--play");
-  const playEntityId = playArgIndex !== -1 ? args[playArgIndex + 1] : undefined;
-
-  const dbPath = path.resolve("./omnia.db");
-  console.log(`Initializing SQLite database at: ${dbPath}`);
-
-  const db = new Database(dbPath);
-  const coreRepo = new SQLiteRepository(db);
-  const bufferRepo = new BufferRepository(db);
-  const loader = new ScenarioLoader(coreRepo, bufferRepo);
-
-  // 1. Read Scenario JSON file
-  if (!fs.existsSync(scenarioPath)) {
-    console.error(
-      `Error: Scenario template file not found at: ${scenarioPath}`,
-    );
-    process.exit(1);
-  }
-
-  console.log(`Loading scenario template from: ${scenarioPath}`);
-  const scenarioJson = JSON.parse(fs.readFileSync(scenarioPath, "utf-8"));
-
-  // 2. Initialize World Instance
-  const worldInstanceId = `run-${Date.now()}`;
-  console.log(`Initializing live world instance: ${worldInstanceId}`);
-  await loader.initializeWorld(scenarioJson, worldInstanceId);
-
-  // Load the running world state
-  const worldState = coreRepo.loadWorldState(worldInstanceId);
-  if (!worldState) {
-    console.error(
-      `Error: Failed to load initialized world state: ${worldInstanceId}`,
-    );
-    process.exit(1);
-  }
-
-  // 3. Ensure API Key exists if we are running LLMs
-  const apiKey = process.env.GOOGLE_API_KEY;
-  if (!apiKey) {
-    console.error("Error: GOOGLE_API_KEY environment variable is missing.");
-    console.error(
-      "Please provide it in your .env file to enable LLM generators and decoders.",
-    );
-    process.exit(1);
-  }
-
-  const llmProvider = new GeminiProvider(apiKey);
-  const architect = new Architect(llmProvider, coreRepo);
-  const aliasGenerator = new AliasDeltaGenerator(llmProvider);
-
-  console.log(
-    "\n================================================================================",
-  );
-  console.log(`SIMULATION STARTED: "${scenarioJson.name}"`);
-  console.log(`Description: ${scenarioJson.description}`);
-  if (playEntityId) {
-    console.log(`Player Role: Controlling entity "${playEntityId}"`);
-  } else {
-    console.log("Player Role: Observing fully autonomous NPC run");
-  }
-  console.log(
-    "================================================================================",
-  );
-
-  const isVerbose = args.includes("--verbose");
-
-  let turnCount = 1;
-  const maxTurns = 20; // safe loop breaker
-
-  while (turnCount <= maxTurns) {
-    console.log(
-      `\n\n--- TURN ${turnCount} (World Time: ${worldState.clock.get().toISOString()}) ---`,
-    );
-
-    // Reload world state from database to ensure fresh DB sync
-    const currentWorldState = coreRepo.loadWorldState(worldInstanceId);
-    if (!currentWorldState) {
-      console.error("Error: Synced world state lost.");
-      process.exit(1);
-    }
-
-    // Auto-resolve aliases for co-located entities who don't know each other yet
-    await runAliasResolution(currentWorldState, aliasGenerator, coreRepo);
-
-    const entities = Array.from(currentWorldState.entities.values());
-
-    for (const entity of entities) {
-      // 1. Determine the ActorAgent generator: CLI input for player, LLM for NPCs
-      const isPlayer = playEntityId && entity.id === playEntityId;
-      const generator = isPlayer ? new CLIProseGenerator() : undefined;
-
-      const agent = new ActorAgent(llmProvider, bufferRepo, 20, generator);
-
-      // Verbose mode: Output the generated prompt builder context before generation
-      if (isVerbose) {
-        const promptBuilder = new ActorPromptBuilder(bufferRepo, 20);
-        const { systemPrompt, userContext } = promptBuilder.build(
-          currentWorldState,
-          entity,
-        );
-        console.log(`\n[VERBOSE] Assembled Prompts for "${entity.id}":`);
-        console.log("\n--- SYSTEM PROMPT ---");
-        console.log(systemPrompt);
-        console.log("\n--- USER CONTEXT ---");
-        console.log(userContext);
-        console.log("\n--- CONTEXT BREAKDOWN ---");
-
-        const userSections = userContext.split("\n\n");
-        const momentSection =
-          userSections.find((s) => s.startsWith("=== CURRENT MOMENT ===")) ||
-          "";
-        const worldSection =
-          userSections.find((s) =>
-            s.startsWith("=== THE WORLD AS YOU PERCEIVE IT ==="),
-          ) || "";
-        const memorySection =
-          userSections.find((s) =>
-            s.startsWith("=== YOUR RECENT MEMORY ==="),
-          ) || "";
-
-        const systemChars = systemPrompt.length;
-        const momentChars = momentSection.length;
-        const worldChars = worldSection.length;
-        const memoryChars = memorySection.length;
-        const totalChars = systemChars + userContext.length;
-
-        const estTokens = (chars: number) => Math.ceil(chars / 4);
-
-        console.log(
-          `  ├─ System Instructions:   ${systemChars.toLocaleString()} chars (~${estTokens(systemChars)} tokens)`,
-        );
-        console.log(
-          `  ├─ Current Moment Context: ${momentChars.toLocaleString()} chars (~${estTokens(momentChars)} tokens)`,
-        );
-        console.log(
-          `  ├─ World Perception:      ${worldChars.toLocaleString()} chars (~${estTokens(worldChars)} tokens)`,
-        );
-        console.log(
-          `  ├─ Recent Memory Buffer:  ${memoryChars.toLocaleString()} chars (~${estTokens(memoryChars)} tokens)`,
-        );
-        console.log(
-          `  └─ TOTAL ESTIMATED INPUT: ${totalChars.toLocaleString()} chars (~${estTokens(totalChars)} tokens)`,
-        );
-        console.log(
-          "--------------------------------------------------------------------------------",
-        );
-      }
-
-      if (!isPlayer) {
-        console.log(`\n[${entity.id}] is thinking...`);
-      }
-
-      // 2. Execute character turn
-      const turnResult = await agent.act(currentWorldState, entity);
-
-      if (!isPlayer) {
-        console.log(`\n[${entity.id}]: ${turnResult.narrativeProse}`);
-      } else {
-        console.log(`\n[You]: ${turnResult.narrativeProse}`);
-      }
-
-      // Verbose mode: Output decoded intent structures
-      if (isVerbose) {
-        console.log(`\n[VERBOSE] Decoded Intents from Prose:`);
-        console.log(JSON.stringify(turnResult.intents.intents, null, 2));
-        console.log(
-          "--------------------------------------------------------------------------------",
-        );
-      }
-
-      // 3. Process each generated intent sequence through physics and memory
-      for (const intent of turnResult.intents.intents) {
-        const outcome = await architect.processIntent(
-          currentWorldState,
-          intent,
-        );
-        const timestamp = currentWorldState.clock.get().toISOString();
-
-        // Verbose mode: Output architect evaluation
-        if (isVerbose) {
-          console.log(`\n[VERBOSE] Architect Intent Processing:`);
-          console.log(`  Type: ${intent.type}`);
-          console.log(`  Description: "${intent.description}"`);
-          if (intent.type === "monologue") {
-            console.log("  Validation: Bypassed (monologue)");
-          } else {
-            console.log(
-              `  Validation Result: isValid = ${outcome.isValid}, reason = "${outcome.reason}"`,
-            );
-            if (outcome.timeDelta) {
-              console.log(
-                `  Clock Delta: +${outcome.timeDelta.minutesToAdvance} min (${outcome.timeDelta.explanation})`,
-              );
-            }
-          }
-          console.log(
-            "--------------------------------------------------------------------------------",
-          );
-        }
-
-        // Save actor's subjective memory
-        const actorEntry = buildBufferEntryForIntent(
-          intent,
-          timestamp,
-          entity.locationId,
-        );
-        if (intent.type === "action") {
-          actorEntry.outcome = {
-            isValid: outcome.isValid,
-            reason: outcome.reason,
-          };
-        }
-        bufferRepo.save(actorEntry);
-
-        // Propagate public memories (dialogue/actions) to co-located observers
-        if (
-          entity.locationId &&
-          (intent.type === "dialogue" || intent.type === "action")
-        ) {
-          for (const other of currentWorldState.entities.values()) {
-            if (
-              other.id !== entity.id &&
-              other.locationId === entity.locationId
-            ) {
-              const observerEntry = buildBufferEntryForIntent(
-                intent,
-                timestamp,
-                entity.locationId,
-              );
-              if (intent.type === "action") {
-                observerEntry.outcome = {
-                  isValid: outcome.isValid,
-                  reason: outcome.reason,
-                };
-              }
-              bufferRepo.save({
-                ...observerEntry,
-                ownerId: other.id,
-              });
-            }
-          }
-        }
-
-        // Print formatted logs
-        if (intent.type === "monologue") {
-          if (isPlayer) {
-            console.log(`  (Thought processed: "${intent.description}")`);
-          }
-        } else if (intent.type === "dialogue") {
-          console.log(
-            `  (Dialogue spoken: spoken to ${intent.targetIds.join(", ") || "someone"})`,
-          );
-        } else {
-          console.log(
-            `  (Action result: ${outcome.isValid ? "Success" : `Failed - ${outcome.reason}`})`,
-          );
-        }
-      }
-
-      // 4. Save synced world state to repository
-      coreRepo.saveWorldState(currentWorldState);
-    }
-
-    turnCount++;
-  }
-
-  console.log("\nSimulation execution limit reached. Goodbye!");
-  db.close();
-}
-
-main().catch((err) => {
-  console.error("Simulation run aborted due to error:", err);
-  process.exit(1);
-});

cli/tsconfig.json

@@ -1,18 +0,0 @@
-{
-  "extends": "../tsconfig.base.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "dist"
-  },
-  "include": ["src"],
-  "references": [
-    { "path": "../packages/core" },
-    { "path": "../packages/spatial" },
-    { "path": "../packages/memory" },
-    { "path": "../packages/intent" },
-    { "path": "../packages/architect" },
-    { "path": "../packages/actor" },
-    { "path": "../packages/llm" },
-    { "path": "../content/scenario-core" }
-  ]
-}

content/demo/scenarios/talking-room.json

@@ -11,12 +11,6 @@
         "visibility": "PRIVATE",
         "allowedEntities": []
       },
-      {
-        "name": "observation_status",
-        "value": "Active monitoring. Audio and visual feeds online.",
-        "visibility": "PRIVATE",
-        "allowedEntities": []
-      },
       {
         "name": "ambient_sound",
         "value": "A low, barely audible electrical hum.",
@@ -54,6 +48,11 @@
           "visibility": "PRIVATE",
           "allowedEntities": ["7c9b83b3-8cfb-4e89-8d77-626a5757d591"]
         },
+        {
+          "name": "gender",
+          "value": "male",
+          "visibility": "PUBLIC"
+        },
         {
           "name": "appearance",
           "value": "A tall human with short dark hair and alert eyes, standing near the center of the room.",
@@ -96,6 +95,11 @@
           "visibility": "PRIVATE",
           "allowedEntities": ["bf3f29d2-cf11-4b11-9a99-b13c126d400e"]
         },
+        {
+          "name": "gender",
+          "value": "male",
+          "visibility": "PUBLIC"
+        },
         {
           "name": "appearance",
           "value": "A medium-build human with long blonde hair tied back, sitting with their back pressed against the white wall.",

content/scenario-builder/eslint.config.mjs

@@ -1,18 +0,0 @@
-import { defineConfig, globalIgnores } from "eslint/config";
-import nextVitals from "eslint-config-next/core-web-vitals";
-import nextTs from "eslint-config-next/typescript";
-
-const eslintConfig = defineConfig([
-  ...nextVitals,
-  ...nextTs,
-  // Override default ignores of eslint-config-next.
-  globalIgnores([
-    // Default ignores of eslint-config-next:
-    ".next/**",
-    "out/**",
-    "build/**",
-    "next-env.d.ts",
-  ]),
-]);
-
-export default eslintConfig;

content/scenario-builder/next.config.ts

@@ -1,33 +0,0 @@
-import type { NextConfig } from "next";
-import { networkInterfaces } from "os";
-
-const getLocalIPs = () => {
-  const ips: string[] = ["localhost", "127.0.0.1"];
-  const nets = networkInterfaces();
-  for (const name of Object.keys(nets)) {
-    for (const net of nets[name] || []) {
-      if (net.family === "IPv4" && !net.internal) {
-        ips.push(net.address);
-      }
-    }
-  }
-  return ips;
-};
-
-const nextConfig: NextConfig = {
-  allowedDevOrigins: getLocalIPs(),
-  async headers() {
-    return [
-      {
-        source: "/api/:path*",
-        headers: [
-          { key: "Access-Control-Allow-Origin", value: "*" },
-          { key: "Access-Control-Allow-Methods", value: "GET,POST,PUT,DELETE,OPTIONS" },
-          { key: "Access-Control-Allow-Headers", value: "Content-Type, Authorization" },
-        ],
-      },
-    ];
-  },
-};
-
-export default nextConfig;

content/scenario-builder/package.json

@@ -1,27 +0,0 @@
-{
-  "name": "scenario-builder",
-  "version": "0.1.0",
-  "private": true,
-  "scripts": {
-    "dev": "next dev",
-    "build": "next build",
-    "start": "next start",
-    "lint": "eslint"
-  },
-  "dependencies": {
-    "next": "16.2.10",
-    "react": "19.2.4",
-    "react-dom": "19.2.4",
-    "@omnia/core": "workspace:*"
-  },
-  "devDependencies": {
-    "@tailwindcss/postcss": "^4",
-    "@types/node": "^20",
-    "@types/react": "^19",
-    "@types/react-dom": "^19",
-    "eslint": "^9",
-    "eslint-config-next": "16.2.10",
-    "tailwindcss": "^4",
-    "typescript": "^5"
-  }
-}

content/scenario-builder/public/file.svg

@@ -1 +0,0 @@
-<svg fill="none" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg"><path d="M14.5 13.5V5.41a1 1 0 0 0-.3-.7L9.8.29A1 1 0 0 0 9.08 0H1.5v13.5A2.5 2.5 0 0 0 4 16h8a2.5 2.5 0 0 0 2.5-2.5m-1.5 0v-7H8v-5H3v12a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1M9.5 5V2.12L12.38 5zM5.13 5h-.62v1.25h2.12V5zm-.62 3h7.12v1.25H4.5zm.62 3h-.62v1.25h7.12V11z" clip-rule="evenodd" fill="#666" fill-rule="evenodd"/></svg>

content/scenario-builder/public/globe.svg

@@ -1 +0,0 @@
-<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><g clip-path="url(#a)"><path fill-rule="evenodd" clip-rule="evenodd" d="M10.27 14.1a6.5 6.5 0 0 0 3.67-3.45q-1.24.21-2.7.34-.31 1.83-.97 3.1M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16m.48-1.52a7 7 0 0 1-.96 0H7.5a4 4 0 0 1-.84-1.32q-.38-.89-.63-2.08a40 40 0 0 0 3.92 0q-.25 1.2-.63 2.08a4 4 0 0 1-.84 1.31zm2.94-4.76q1.66-.15 2.95-.43a7 7 0 0 0 0-2.58q-1.3-.27-2.95-.43a18 18 0 0 1 0 3.44m-1.27-3.54a17 17 0 0 1 0 3.64 39 39 0 0 1-4.3 0 17 17 0 0 1 0-3.64 39 39 0 0 1 4.3 0m1.1-1.17q1.45.13 2.69.34a6.5 6.5 0 0 0-3.67-3.44q.65 1.26.98 3.1M8.48 1.5l.01.02q.41.37.84 1.31.38.89.63 2.08a40 40 0 0 0-3.92 0q.25-1.2.63-2.08a4 4 0 0 1 .85-1.32 7 7 0 0 1 .96 0m-2.75.4a6.5 6.5 0 0 0-3.67 3.44 29 29 0 0 1 2.7-.34q.31-1.83.97-3.1M4.58 6.28q-1.66.16-2.95.43a7 7 0 0 0 0 2.58q1.3.27 2.95.43a18 18 0 0 1 0-3.44m.17 4.71q-1.45-.12-2.69-.34a6.5 6.5 0 0 0 3.67 3.44q-.65-1.27-.98-3.1" fill="#666"/></g><defs><clipPath id="a"><path fill="#fff" d="M0 0h16v16H0z"/></clipPath></defs></svg>

content/scenario-builder/public/next.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 394 80"><path fill="#000" d="M262 0h68.5v12.7h-27.2v66.6h-13.6V12.7H262V0ZM149 0v12.7H94v20.4h44.3v12.6H94v21h55v12.6H80.5V0h68.7zm34.3 0h-17.8l63.8 79.4h17.9l-32-39.7 32-39.6h-17.9l-23 28.6-23-28.6zm18.3 56.7-9-11-27.1 33.7h17.8l18.3-22.7z"/><path fill="#000" d="M81 79.3 17 0H0v79.3h13.6V17l50.2 62.3H81Zm252.6-.4c-1 0-1.8-.4-2.5-1s-1.1-1.6-1.1-2.6.3-1.8 1-2.5 1.6-1 2.6-1 1.8.3 2.5 1a3.4 3.4 0 0 1 .6 4.3 3.7 3.7 0 0 1-3 1.8zm23.2-33.5h6v23.3c0 2.1-.4 4-1.3 5.5a9.1 9.1 0 0 1-3.8 3.5c-1.6.8-3.5 1.3-5.7 1.3-2 0-3.7-.4-5.3-1s-2.8-1.8-3.7-3.2c-.9-1.3-1.4-3-1.4-5h6c.1.8.3 1.6.7 2.2s1 1.2 1.6 1.5c.7.4 1.5.5 2.4.5 1 0 1.8-.2 2.4-.6a4 4 0 0 0 1.6-1.8c.3-.8.5-1.8.5-3V45.5zm30.9 9.1a4.4 4.4 0 0 0-2-3.3 7.5 7.5 0 0 0-4.3-1.1c-1.3 0-2.4.2-3.3.5-.9.4-1.6 1-2 1.6a3.5 3.5 0 0 0-.3 4c.3.5.7.9 1.3 1.2l1.8 1 2 .5 3.2.8c1.3.3 2.5.7 3.7 1.2a13 13 0 0 1 3.2 1.8 8.1 8.1 0 0 1 3 6.5c0 2-.5 3.7-1.5 5.1a10 10 0 0 1-4.4 3.5c-1.8.8-4.1 1.2-6.8 1.2-2.6 0-4.9-.4-6.8-1.2-2-.8-3.4-2-4.5-3.5a10 10 0 0 1-1.7-5.6h6a5 5 0 0 0 3.5 4.6c1 .4 2.2.6 3.4.6 1.3 0 2.5-.2 3.5-.6 1-.4 1.8-1 2.4-1.7a4 4 0 0 0 .8-2.4c0-.9-.2-1.6-.7-2.2a11 11 0 0 0-2.1-1.4l-3.2-1-3.8-1c-2.8-.7-5-1.7-6.6-3.2a7.2 7.2 0 0 1-2.4-5.7 8 8 0 0 1 1.7-5 10 10 0 0 1 4.3-3.5c2-.8 4-1.2 6.4-1.2 2.3 0 4.4.4 6.2 1.2 1.8.8 3.2 2 4.3 3.4 1 1.4 1.5 3 1.5 5h-5.8z"/></svg>

content/scenario-builder/public/vercel.svg

@@ -1 +0,0 @@
-<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1155 1000"><path d="m577.3 0 577.4 1000H0z" fill="#fff"/></svg>

content/scenario-builder/public/window.svg

@@ -1 +0,0 @@
-<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.5 2.5h13v10a1 1 0 0 1-1 1h-11a1 1 0 0 1-1-1zM0 1h16v11.5a2.5 2.5 0 0 1-2.5 2.5h-11A2.5 2.5 0 0 1 0 12.5zm3.75 4.5a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5M7 4.75a.75.75 0 1 1-1.5 0 .75.75 0 0 1 1.5 0m1.75.75a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5" fill="#666"/></svg>

content/scenario-builder/src/app/api/world/route.ts

@@ -1,125 +0,0 @@
-import { NextResponse } from "next/server";
-import Database from "better-sqlite3";
-import { WorldState, Entity, SQLiteRepository, AttributeVisibility } from "@omnia/core";
-import path from "path";
-
-const DB_PATH = path.resolve("/home/sortedcord/Projects/omnia_umbrella/omnia/omnia.db");
-
-function getRepo() {
-  const db = new Database(DB_PATH);
-  return { repo: new SQLiteRepository(db), db };
-}
-
-export async function GET(request: Request) {
-  try {
-    const { searchParams } = new URL(request.url);
-    const id = searchParams.get("id");
-
-    const { repo, db } = getRepo();
-
-    try {
-      if (id) {
-        const world = repo.loadWorldState(id);
-        if (!world) {
-          return NextResponse.json({ error: `World with ID ${id} not found` }, { status: 404 });
-        }
-
-        // Serialize world
-        const serialized = {
-          id: world.id,
-          attributes: Array.from(world.attributes.values()).map(attr => ({
-            name: attr.name,
-            value: attr.getValue(),
-            visibility: attr.getVisibility(),
-            allowedEntities: Array.from(attr.getAllowedEntities())
-          })),
-          entities: Array.from(world.entities.values()).map(entity => ({
-            id: entity.id,
-            attributes: Array.from(entity.attributes.values()).map(attr => ({
-              name: attr.name,
-              value: attr.getValue(),
-              visibility: attr.getVisibility(),
-              allowedEntities: Array.from(attr.getAllowedEntities())
-            }))
-          }))
-        };
-        return NextResponse.json(serialized);
-      } else {
-        // List all worlds
-        const rows = db.prepare("SELECT id FROM objects WHERE type = 'world'").all() as { id: string }[];
-        const worlds = [];
-        for (const row of rows) {
-          const world = repo.loadWorldState(row.id);
-          if (world) {
-            const nameAttr = world.attributes.get("name")?.getValue() || "Unnamed World";
-            worlds.push({
-              id: world.id,
-              name: nameAttr
-            });
-          }
-        }
-        return NextResponse.json({ worlds });
-      }
-    } finally {
-      db.close();
-    }
-  } catch (error) {
-    console.error("API GET Error:", error);
-    const message = error instanceof Error ? error.message : "Internal Server Error";
-    return NextResponse.json({ error: message }, { status: 500 });
-  }
-}
-
-export async function POST(request: Request) {
-  try {
-    const payload = await request.json();
-    if (!payload.id) {
-      return NextResponse.json({ error: "World ID is required" }, { status: 400 });
-    }
-
-    const { repo, db } = getRepo();
-
-    try {
-      const world = new WorldState(payload.id);
-
-      // Add attributes to world
-      if (payload.attributes && Array.isArray(payload.attributes)) {
-        for (const attr of payload.attributes) {
-          world.addAttribute(
-            attr.name,
-            attr.value,
-            attr.visibility || AttributeVisibility.PUBLIC,
-            attr.allowedEntities ? new Set(attr.allowedEntities) : null
-          );
-        }
-      }
-
-      // Add entities to world
-      if (payload.entities && Array.isArray(payload.entities)) {
-        for (const ent of payload.entities) {
-          const entity = new Entity(ent.id);
-          if (ent.attributes && Array.isArray(ent.attributes)) {
-            for (const attr of ent.attributes) {
-              entity.addAttribute(
-                attr.name,
-                attr.value,
-                attr.visibility || AttributeVisibility.PRIVATE,
-                attr.allowedEntities ? new Set(attr.allowedEntities) : null
-              );
-            }
-          }
-          world.addEntity(entity);
-        }
-      }
-
-      repo.saveWorldState(world);
-      return NextResponse.json({ success: true, worldId: world.id });
-    } finally {
-      db.close();
-    }
-  } catch (error) {
-    console.error("API POST Error:", error);
-    const message = error instanceof Error ? error.message : "Internal Server Error";
-    return NextResponse.json({ error: message }, { status: 500 });
-  }
-}

content/scenario-builder/src/app/globals.css

@@ -1,6 +0,0 @@
-body {
-  font-family: sans-serif;
-  padding: 10px;
-  background-color: white;
-  color: black;
-}

content/scenario-builder/src/app/layout.tsx

@@ -1,33 +0,0 @@
-import type { Metadata } from "next";
-import { Geist, Geist_Mono } from "next/font/google";
-import "./globals.css";
-
-const geistSans = Geist({
-  variable: "--font-geist-sans",
-  subsets: ["latin"],
-});
-
-const geistMono = Geist_Mono({
-  variable: "--font-geist-mono",
-  subsets: ["latin"],
-});
-
-export const metadata: Metadata = {
-  title: "Create Next App",
-  description: "Generated by create next app",
-};
-
-export default function RootLayout({
-  children,
-}: Readonly<{
-  children: React.ReactNode;
-}>) {
-  return (
-    <html
-      lang="en"
-      className={`${geistSans.variable} ${geistMono.variable} h-full antialiased`}
-    >
-      <body className="min-h-full flex flex-col">{children}</body>
-    </html>
-  );
-}

content/scenario-builder/src/app/page.tsx

@@ -1,586 +0,0 @@
-"use client";
-
-import { useState, useEffect } from "react";
-
-function generateUUID(): string {
-  if (typeof window !== "undefined" && window.crypto && window.crypto.randomUUID) {
-    return window.crypto.randomUUID();
-  }
-  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
-    const r = (Math.random() * 16) | 0;
-    const v = c === "x" ? r : (r & 0x3) | 0x8;
-    return v.toString(16);
-  });
-}
-
-interface Attribute {
-  name: string;
-  value: string;
-  visibility: "PUBLIC" | "PRIVATE";
-  allowedEntities: string[];
-}
-
-interface Entity {
-  id: string;
-  attributes: Attribute[];
-}
-
-interface WorldData {
-  id: string;
-  attributes: Attribute[];
-  entities: Entity[];
-}
-
-export default function Home() {
-  const [worldsList, setWorldsList] = useState<{ id: string; name: string }[]>([]);
-  const [selectedWorldId, setSelectedWorldId] = useState<string>("");
-  const [worldData, setWorldData] = useState<WorldData | null>(null);
-  const [status, setStatus] = useState<string>("");
-  const [error, setError] = useState<string>("");
-
-  // Temp state for adding new attributes / entities
-  const [newWorldAttribute, setNewWorldAttribute] = useState<{ name: string; value: string; visibility: "PUBLIC" | "PRIVATE" }>({ name: "", value: "", visibility: "PUBLIC" });
-  const [newEntityAttribute, setNewEntityAttribute] = useState<Record<string, { name: string; value: string; visibility: "PUBLIC" | "PRIVATE" }>>({});
-
-  const fetchWorlds = async () => {
-    try {
-      const res = await fetch("/api/world");
-      if (!res.ok) throw new Error("Failed to fetch worlds");
-      const data = await res.json();
-      setWorldsList(data.worlds || []);
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : "Failed to load worlds list";
-      setError(msg);
-    }
-  };
-
-  useEffect(() => {
-    // eslint-disable-next-line react-hooks/set-state-in-effect
-    fetchWorlds();
-  }, []);
-
-  const handleCreateNewWorld = () => {
-    const newId = generateUUID();
-    setWorldData({
-      id: newId,
-      attributes: [{ name: "name", value: "New World", visibility: "PUBLIC", allowedEntities: [] }],
-      entities: []
-    });
-    setSelectedWorldId("");
-    setStatus("Created new world locally. Don't forget to save!");
-    setError("");
-  };
-
-  const handleLoadWorld = async (id: string) => {
-    if (!id) return;
-    try {
-      setStatus(`Loading world ${id}...`);
-      setError("");
-      const res = await fetch(`/api/world?id=${id}`);
-      if (!res.ok) throw new Error("Failed to load world data");
-      const data = await res.json();
-      setWorldData(data);
-      setSelectedWorldId(id);
-      setStatus(`Loaded world successfully!`);
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : "Failed to load world";
-      setError(msg);
-      setStatus("");
-    }
-  };
-
-  const handleSaveWorld = async () => {
-    if (!worldData) return;
-    try {
-      setStatus("Saving world to database...");
-      setError("");
-      const res = await fetch("/api/world", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify(worldData)
-      });
-      const data = await res.json();
-      if (!res.ok) throw new Error(data.error || "Failed to save world");
-      
-      setStatus("World saved successfully!");
-      fetchWorlds();
-      setSelectedWorldId(worldData.id);
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : "Failed to save world";
-      setError(msg);
-      setStatus("");
-    }
-  };
-
-  // World Attribute management
-  const addWorldAttribute = () => {
-    if (!worldData || !newWorldAttribute.name.trim()) return;
-    if (worldData.attributes.some(a => a.name === newWorldAttribute.name)) {
-      setError(`Attribute "${newWorldAttribute.name}" already exists on world.`);
-      return;
-    }
-    setWorldData({
-      ...worldData,
-      attributes: [
-        ...worldData.attributes,
-        { name: newWorldAttribute.name, value: newWorldAttribute.value, visibility: newWorldAttribute.visibility, allowedEntities: [] }
-      ]
-    });
-    setNewWorldAttribute({ name: "", value: "", visibility: "PUBLIC" });
-    setError("");
-  };
-
-  const removeWorldAttribute = (name: string) => {
-    if (!worldData) return;
-    setWorldData({
-      ...worldData,
-      attributes: worldData.attributes.filter(a => a.name !== name)
-    });
-  };
-
-  const updateWorldAttributeValue = (name: string, value: string) => {
-    if (!worldData) return;
-    setWorldData({
-      ...worldData,
-      attributes: worldData.attributes.map(a => a.name === name ? { ...a, value } : a)
-    });
-  };
-
-  const updateWorldAttributeVisibility = (name: string, visibility: "PUBLIC" | "PRIVATE") => {
-    if (!worldData) return;
-    setWorldData({
-      ...worldData,
-      attributes: worldData.attributes.map(a => a.name === name ? { ...a, visibility, allowedEntities: visibility === "PUBLIC" ? [] : a.allowedEntities } : a)
-    });
-  };
-
-  // Entity management
-  const handleAddEntity = () => {
-    if (!worldData) return;
-    const newId = generateUUID();
-    const newEntity: Entity = {
-      id: newId,
-      attributes: [{ name: "name", value: "New Entity", visibility: "PRIVATE", allowedEntities: [] }]
-    };
-    setWorldData({
-      ...worldData,
-      entities: [...worldData.entities, newEntity]
-    });
-  };
-
-  const handleRemoveEntity = (entityId: string) => {
-    if (!worldData) return;
-    // Also clean up this entity from all attribute ACL lists
-    const updatedEntities = worldData.entities.filter(e => e.id !== entityId).map(e => ({
-      ...e,
-      attributes: e.attributes.map(a => ({
-        ...a,
-        allowedEntities: a.allowedEntities.filter(id => id !== entityId)
-      }))
-    }));
-
-    const updatedWorldAttributes = worldData.attributes.map(a => ({
-      ...a,
-      allowedEntities: a.allowedEntities.filter(id => id !== entityId)
-    }));
-
-    setWorldData({
-      ...worldData,
-      attributes: updatedWorldAttributes,
-      entities: updatedEntities
-    });
-  };
-
-  // Entity Attribute management
-  const addEntityAttribute = (entityId: string) => {
-    if (!worldData) return;
-    const input = newEntityAttribute[entityId];
-    if (!input || !input.name.trim()) return;
-
-    const entity = worldData.entities.find(e => e.id === entityId);
-    if (!entity) return;
-
-    if (entity.attributes.some(a => a.name === input.name)) {
-      setError(`Attribute "${input.name}" already exists on entity.`);
-      return;
-    }
-
-    const updatedEntities = worldData.entities.map(e => {
-      if (e.id === entityId) {
-        return {
-          ...e,
-          attributes: [
-            ...e.attributes,
-            { name: input.name, value: input.value, visibility: input.visibility, allowedEntities: [] }
-          ]
-        };
-      }
-      return e;
-    });
-
-    setWorldData({ ...worldData, entities: updatedEntities });
-    setNewEntityAttribute({
-      ...newEntityAttribute,
-      [entityId]: { name: "", value: "", visibility: "PRIVATE" }
-    });
-    setError("");
-  };
-
-  const removeEntityAttribute = (entityId: string, attrName: string) => {
-    if (!worldData) return;
-    const updatedEntities = worldData.entities.map(e => {
-      if (e.id === entityId) {
-        return {
-          ...e,
-          attributes: e.attributes.filter(a => a.name !== attrName)
-        };
-      }
-      return e;
-    });
-    setWorldData({ ...worldData, entities: updatedEntities });
-  };
-
-  const updateEntityAttributeValue = (entityId: string, attrName: string, value: string) => {
-    if (!worldData) return;
-    const updatedEntities = worldData.entities.map(e => {
-      if (e.id === entityId) {
-        return {
-          ...e,
-          attributes: e.attributes.map(a => a.name === attrName ? { ...a, value } : a)
-        };
-      }
-      return e;
-    });
-    setWorldData({ ...worldData, entities: updatedEntities });
-  };
-
-  const updateEntityAttributeVisibility = (entityId: string, attrName: string, visibility: "PUBLIC" | "PRIVATE") => {
-    if (!worldData) return;
-    const updatedEntities = worldData.entities.map(e => {
-      if (e.id === entityId) {
-        return {
-          ...e,
-          attributes: e.attributes.map(a => a.name === attrName ? { ...a, visibility, allowedEntities: visibility === "PUBLIC" ? [] : a.allowedEntities } : a)
-        };
-      }
-      return e;
-    });
-    setWorldData({ ...worldData, entities: updatedEntities });
-  };
-
-  const toggleEntityAcl = (targetEntityId: string, attrName: string, allowedEntityId: string, checked: boolean) => {
-    if (!worldData) return;
-    const updatedEntities = worldData.entities.map(e => {
-      if (e.id === targetEntityId) {
-        return {
-          ...e,
-          attributes: e.attributes.map(a => {
-            if (a.name === attrName) {
-              const currentAcl = a.allowedEntities;
-              const newAcl = checked
-                ? [...currentAcl, allowedEntityId]
-                : currentAcl.filter(id => id !== allowedEntityId);
-              return { ...a, allowedEntities: newAcl };
-            }
-            return a;
-          })
-        };
-      }
-      return e;
-    });
-    setWorldData({ ...worldData, entities: updatedEntities });
-  };
-
-  const toggleWorldAcl = (attrName: string, allowedEntityId: string, checked: boolean) => {
-    if (!worldData) return;
-    setWorldData({
-      ...worldData,
-      attributes: worldData.attributes.map(a => {
-        if (a.name === attrName) {
-          const currentAcl = a.allowedEntities;
-          const newAcl = checked
-            ? [...currentAcl, allowedEntityId]
-            : currentAcl.filter(id => id !== allowedEntityId);
-          return { ...a, allowedEntities: newAcl };
-        }
-        return a;
-      })
-    });
-  };
-
-  return (
-    <div style={{ padding: "20px", fontFamily: "sans-serif" }}>
-      <h1>Omnia Scenario Builder</h1>
-      <hr />
-
-      {/* Persistence Controls */}
-      <section style={{ marginBottom: "20px" }}>
-        <h2>World Persistence</h2>
-        <div style={{ display: "flex", gap: "10px", alignItems: "center" }}>
-          <button onClick={handleCreateNewWorld}>Create New World</button>
-          <span>or Load Existing:</span>
-          <select
-            value={selectedWorldId}
-            onChange={(e) => handleLoadWorld(e.target.value)}
-          >
-            <option value="">-- Select World --</option>
-            {worldsList.map((w) => (
-              <option key={w.id} value={w.id}>
-                {w.name} ({w.id})
-              </option>
-            ))}
-          </select>
-          {worldData && (
-            <>
-              <button onClick={handleSaveWorld} style={{ fontWeight: "bold" }}>
-                Save World to DB
-              </button>
-              <button onClick={() => handleLoadWorld(worldData.id)}>
-                Reload / Discard Changes
-              </button>
-            </>
-          )}
-        </div>
-      </section>
-
-      {/* Status Messages */}
-      {status && <div style={{ color: "green", margin: "10px 0" }}><strong>Status:</strong> {status}</div>}
-      {error && <div style={{ color: "red", margin: "10px 0" }}><strong>Error:</strong> {error}</div>}
-
-      {worldData ? (
-        <div>
-          <hr />
-          {/* World Information */}
-          <section style={{ marginBottom: "30px" }}>
-            <h2>World Attributes (ID: {worldData.id})</h2>
-            
-            <table border={1} cellPadding={5} style={{ borderCollapse: "collapse", width: "100%", marginBottom: "10px" }}>
-              <thead>
-                <tr>
-                  <th>Attribute Name</th>
-                  <th>Value</th>
-                  <th>Visibility</th>
-                  <th>ACL (Allowed Entities for PRIVATE)</th>
-                  <th>Action</th>
-                </tr>
-              </thead>
-              <tbody>
-                {worldData.attributes.map((attr) => (
-                  <tr key={attr.name}>
-                    <td><strong>{attr.name}</strong></td>
-                    <td>
-                      <input
-                        type="text"
-                        value={attr.value}
-                        onChange={(e) => updateWorldAttributeValue(attr.name, e.target.value)}
-                      />
-                    </td>
-                    <td>
-                      <select
-                        value={attr.visibility}
-                        onChange={(e) => updateWorldAttributeVisibility(attr.name, e.target.value as "PUBLIC" | "PRIVATE")}
-                      >
-                        <option value="PUBLIC">PUBLIC</option>
-                        <option value="PRIVATE">PRIVATE</option>
-                      </select>
-                    </td>
-                    <td>
-                      {attr.visibility === "PRIVATE" ? (
-                        <div>
-                          {worldData.entities.length === 0 ? (
-                            <span style={{ color: "gray" }}>No entities in world to grant access to</span>
-                          ) : (
-                            worldData.entities.map((e) => {
-                              const entName = e.attributes.find(a => a.name === "name")?.value || e.id;
-                              return (
-                                <label key={e.id} style={{ display: "block" }}>
-                                  <input
-                                    type="checkbox"
-                                    checked={attr.allowedEntities.includes(e.id)}
-                                    onChange={(evt) => toggleWorldAcl(attr.name, e.id, evt.target.checked)}
-                                  />{" "}
-                                  {entName} ({e.id.slice(0, 8)}...)
-                                </label>
-                              );
-                            })
-                          )}
-                        </div>
-                      ) : (
-                        <span style={{ color: "gray" }}>N/A (Visible to all)</span>
-                      )}
-                    </td>
-                    <td>
-                      <button onClick={() => removeWorldAttribute(attr.name)}>Delete</button>
-                    </td>
-                  </tr>
-                ))}
-              </tbody>
-            </table>
-
-            {/* Add World Attribute */}
-            <div style={{ background: "#f5f5f5", padding: "10px", border: "1px solid #ccc" }}>
-              <h4>Add World Attribute</h4>
-              Name:{" "}
-              <input
-                type="text"
-                value={newWorldAttribute.name}
-                onChange={(e) => setNewWorldAttribute({ ...newWorldAttribute, name: e.target.value })}
-                placeholder="e.g. description"
-              />{" "}
-              Value:{" "}
-              <input
-                type="text"
-                value={newWorldAttribute.value}
-                onChange={(e) => setNewWorldAttribute({ ...newWorldAttribute, value: e.target.value })}
-                placeholder="e.g. A lush land"
-              />{" "}
-              Visibility:{" "}
-              <select
-                value={newWorldAttribute.visibility}
-                onChange={(e) => setNewWorldAttribute({ ...newWorldAttribute, visibility: e.target.value as "PUBLIC" | "PRIVATE" })}
-              >
-                <option value="PUBLIC">PUBLIC</option>
-                <option value="PRIVATE">PRIVATE</option>
-              </select>{" "}
-              <button onClick={addWorldAttribute}>Add Attribute</button>
-            </div>
-          </section>
-
-          <hr />
-
-          {/* Entities section */}
-          <section style={{ marginBottom: "30px" }}>
-            <div style={{ display: "flex", justifyContent: "space-between", alignItems: "center" }}>
-              <h2>World Entities</h2>
-              <button onClick={handleAddEntity}>+ Add New Entity</button>
-            </div>
-
-            {worldData.entities.length === 0 ? (
-              <p>No entities found in this world. Click &quot;+ Add New Entity&quot; to add one.</p>
-            ) : (
-              worldData.entities.map((entity, index) => {
-                const entName = entity.attributes.find(a => a.name === "name")?.value || "Unnamed Entity";
-                const entInputState = newEntityAttribute[entity.id] || { name: "", value: "", visibility: "PRIVATE" };
-
-                return (
-                  <div key={entity.id} style={{ border: "1px solid #999", padding: "15px", marginBottom: "20px", background: "#fafafa" }}>
-                    <div style={{ display: "flex", justifyContent: "space-between", alignItems: "center" }}>
-                      <h3>Entity #{index + 1}: {entName} <span style={{ fontSize: "12px", color: "gray", fontWeight: "normal" }}>({entity.id})</span></h3>
-                      <button onClick={() => handleRemoveEntity(entity.id)} style={{ color: "red" }}>Delete Entity</button>
-                    </div>
-
-                    <table border={1} cellPadding={5} style={{ borderCollapse: "collapse", width: "100%", marginBottom: "10px", background: "white" }}>
-                      <thead>
-                        <tr>
-                          <th>Attribute Name</th>
-                          <th>Value</th>
-                          <th>Visibility</th>
-                          <th>ACL (Allowed Entities for PRIVATE)</th>
-                          <th>Action</th>
-                        </tr>
-                      </thead>
-                      <tbody>
-                        {entity.attributes.map((attr) => (
-                          <tr key={attr.name}>
-                            <td><strong>{attr.name}</strong></td>
-                            <td>
-                              <input
-                                type="text"
-                                value={attr.value}
-                                onChange={(e) => updateEntityAttributeValue(entity.id, attr.name, e.target.value)}
-                              />
-                            </td>
-                            <td>
-                              <select
-                                value={attr.visibility}
-                                onChange={(e) => updateEntityAttributeVisibility(entity.id, attr.name, e.target.value as "PUBLIC" | "PRIVATE")}
-                              >
-                                <option value="PUBLIC">PUBLIC</option>
-                                <option value="PRIVATE">PRIVATE</option>
-                              </select>
-                            </td>
-                            <td>
-                              {attr.visibility === "PRIVATE" ? (
-                                <div>
-                                  {worldData.entities.filter(e => e.id !== entity.id).length === 0 ? (
-                                    <span style={{ color: "gray" }}>No other entities in world to grant access to</span>
-                                  ) : (
-                                    worldData.entities
-                                      .filter(e => e.id !== entity.id)
-                                      .map((e) => {
-                                        const otherName = e.attributes.find(a => a.name === "name")?.value || e.id;
-                                        return (
-                                          <label key={e.id} style={{ display: "block" }}>
-                                            <input
-                                              type="checkbox"
-                                              checked={attr.allowedEntities.includes(e.id)}
-                                              onChange={(evt) => toggleEntityAcl(entity.id, attr.name, e.id, evt.target.checked)}
-                                            />{" "}
-                                            {otherName} ({e.id.slice(0, 8)}...)
-                                          </label>
-                                        );
-                                      })
-                                  )}
-                                </div>
-                              ) : (
-                                <span style={{ color: "gray" }}>N/A (Visible to all)</span>
-                              )}
-                            </td>
-                            <td>
-                              <button onClick={() => removeEntityAttribute(entity.id, attr.name)}>Delete</button>
-                            </td>
-                          </tr>
-                        ))}
-                      </tbody>
-                    </table>
-
-                    {/* Add Entity Attribute */}
-                    <div style={{ background: "#eee", padding: "10px", border: "1px dashed #777" }}>
-                      <h5>Add Attribute to {entName}</h5>
-                      Name:{" "}
-                      <input
-                        type="text"
-                        value={entInputState.name}
-                        onChange={(e) => setNewEntityAttribute({
-                          ...newEntityAttribute,
-                          [entity.id]: { ...entInputState, name: e.target.value }
-                        })}
-                        placeholder="e.g. title"
-                      />{" "}
-                      Value:{" "}
-                      <input
-                        type="text"
-                        value={entInputState.value}
-                        onChange={(e) => setNewEntityAttribute({
-                          ...newEntityAttribute,
-                          [entity.id]: { ...entInputState, value: e.target.value }
-                        })}
-                        placeholder="e.g. Witcher"
-                      />{" "}
-                      Visibility:{" "}
-                      <select
-                        value={entInputState.visibility}
-                        onChange={(e) => setNewEntityAttribute({
-                          ...newEntityAttribute,
-                          [entity.id]: { ...entInputState, visibility: e.target.value as "PUBLIC" | "PRIVATE" }
-                        })}
-                      >
-                        <option value="PUBLIC">PUBLIC</option>
-                        <option value="PRIVATE">PRIVATE</option>
-                      </select>{" "}
-                      <button onClick={() => addEntityAttribute(entity.id)}>Add Attribute</button>
-                    </div>
-                  </div>
-                );
-              })
-            )}
-          </section>
-        </div>
-      ) : (
-        <div style={{ padding: "40px 0", textAlign: "center", color: "gray" }}>
-          Please select a world to load or click &quot;Create New World&quot; to begin.
-        </div>
-      )}
-    </div>
-  );
-}

content/scenario-builder/src/proxy.ts

@@ -1,31 +0,0 @@
-import { NextResponse } from "next/server";
-import type { NextRequest } from "next/server";
-
-export function proxy(request: NextRequest) {
-  const origin = request.headers.get("origin") || "*";
-
-  // Handle preflight OPTIONS requests
-  if (request.method === "OPTIONS") {
-    return new NextResponse(null, {
-      status: 200,
-      headers: {
-        "Access-Control-Allow-Origin": origin,
-        "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
-        "Access-Control-Allow-Headers": "Content-Type, Authorization",
-        "Access-Control-Max-Age": "86400",
-      },
-    });
-  }
-
-  // Handle standard requests
-  const response = NextResponse.next();
-  response.headers.set("Access-Control-Allow-Origin", origin);
-  response.headers.set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
-  response.headers.set("Access-Control-Allow-Headers", "Content-Type, Authorization");
-
-  return response;
-}
-
-export const config = {
-  matcher: "/api/:path*",
-};

eslint.config.mjs

@@ -5,7 +5,7 @@ import tseslint from "typescript-eslint";
 
 export default [
   {
-    ignores: ["**/dist/**", "**/node_modules/**", "content/scenario-builder/**", "**/.astro/**"],
+    ignores: ["**/dist/**", "**/node_modules/**", "**/.astro/**", "**/.next/**"],
   },
 
   js.configs.recommended,
@@ -19,5 +19,12 @@ export default [
     },
   },
 
+  {
+    files: ["**/*.tsx"],
+    languageOptions: {
+      globals: { ...globals.browser, ...globals.node },
+    },
+  },
+
   eslintConfigPrettier,
 ];

package.json

@@ -7,9 +7,10 @@
     "build": "tsc -b",
     "build:web": "pnpm --filter landing build",
     "build:docs": "pnpm --filter docs build",
-    "build:all": "pnpm build && pnpm build:web && pnpm build:docs",
+    "build:gui": "pnpm --filter @omnia/gui build",
     "dev:web": "pnpm --filter landing dev",
     "dev:docs": "pnpm --filter docs dev",
+    "dev:gui": "pnpm --filter @omnia/gui dev",
     "clean": "git clean -xfd",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
@@ -18,12 +19,11 @@
     "watch": "tsc -b --watch",
     "test": "vitest run --project unit",
     "test:watch": "vitest --project unit",
-    "test:evals": "vitest run --project evals",
-    "play": "node cli/dist/index.js"
+    "test:evals": "vitest run --project evals"
   },
   "keywords": [],
-  "author": "",
-  "license": "ISC",
+  "author": "sortedcord",
+  "license": "MIT",
   "devEngines": {
     "packageManager": {
       "name": "pnpm",
@@ -40,6 +40,7 @@
     "eslint-config-prettier": "^10.1.8",
     "globals": "^17.7.0",
     "prettier": "^3.9.4",
+    "shadcn": "^4.13.0",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.62.1",
     "vitest": "^4.1.9",

packages/actor/src/actor-prompt-builder.ts

@@ -4,11 +4,14 @@ import {
   WorldState,
   naturalizeTime,
   serializeSubjectiveWorldState,
+  resolveAlias,
 } from "@omnia/core";
 import {
   BufferEntry,
   BufferRepository,
   serializeSubjectiveBufferEntry,
+  LedgerEntry,
+  LedgerRepository,
 } from "@omnia/memory";
 
 /**
@@ -37,12 +40,17 @@ export class ActorPromptBuilder {
   /**
    * @param bufferRepo  Used to fetch the actor's recent memory. Optional —
    *                    if absent, the memory section is omitted.
+   * @param ledgerRepo  Used to fetch long-term memories. Optional.
    * @param memoryLimit Maximum number of recent buffer entries to inject.
    *                    Defaults to 20.
+   * @param ledgerLimit Maximum number of long-term memories to retrieve.
+   *                    Defaults to 5.
    */
   constructor(
     private bufferRepo?: BufferRepository,
+    private ledgerRepo?: LedgerRepository,
     private memoryLimit = 20,
+    private ledgerLimit = 5,
   ) {}
 
   /**
@@ -59,30 +67,31 @@ export class ActorPromptBuilder {
 
   private buildSystemPrompt(): string {
     return `
-You are an actor agent embodying a single character in a narrative simulation. You ARE this character — act immersively, naturally, and in-character at all times. Do not break character, do not reference being an AI or a system, and do not narrate from outside the character's perspective.
+You are an actor agent embodying a single character in a narrative simulation. You ARE this character: act immersively, naturally, and in-character at all times. Do not break character, do not reference being an AI or a system, and do not narrate from outside the character's perspective.
 
 Your output is a short block of narrative prose describing what your character does, says, or thinks next. You may:
-- Speak aloud → this becomes a "dialogue" intent. Other entities can hear it.
-- Perform a physical or logical action → this becomes an "action" intent. It is subject to the world's physics and will be validated by the World Architect.
-- Think internally / reflect / feel → this becomes a "monologue" intent. NO ONE else perceives it. It bypasses all validation and is written straight to your private memory. Use this for inner thoughts, doubts, plans, and feelings that you would not voice aloud.
+- Speak aloud → Other entities can hear it if they are present nearby. (Or nobody will hear it if you are alone)
+- Perform a physical action → It is subject to the world's physics and logic. Do not describe the outcome of your action.
+- Think internally / reflect / feel → this is a "monologue". NO ONE else perceives it. This is what you think internally.
 
 Guidelines:
-- Always write in the first person (e.g., "I do this", "I say", "I think").
-- Only describe your character's own actions, spoken words, and internal reactions. Do NOT narrate or describe the environment, the room, your surroundings, or other characters' actions, as these are managed by the simulation engine.
-- Stay strictly within what your character knows. If an attribute, entity, or fact is not present in your context below, your character does not know it — do not invent it or act on it.
-- Refer to other entities by the subjective names/aliases given in your context, never by raw system IDs.
-- Keep your prose vivid but concise. A single response may contain more than one intent (e.g., you may think, then speak, then act) — write them in natural narrative order.
+- Always write in the first person
+- Only describe your character's own actions, spoken words, and internal reactions. Do NOT narrate or describe the environment or your surroundings, or other characters' actions.
+- Refer to other entities by the subjective names/aliases that you refer to them as.
+- Keep your prose vivid but concise. Write it in natural narrative order.
 - Not every response requires an outward action. It is perfectly valid to only think (a monologue) and do nothing perceivable.
-- Never speak or act on another entity's behalf — you only control your own character.
+- Never speak or act on another entity's behalf. You only control your own character.
+- Stay strictly within what your character knows. Do not invent knowledge that doesn't exist or act on it.
+- You are limited by just your memory. If your memory is limited, then that's all you can remember. If you do make stuff up then that's lying. Which is allowed, but remember that you're lying.
 ".
 `.trim();
   }
 
   private buildUserContext(worldState: WorldState, entity: Entity): string {
     const sections: string[] = [];
+    const now = worldState.clock.get();
 
     // --- Subjective present time ---
-    const now = worldState.clock.get();
     sections.push(
       `=== CURRENT MOMENT ===\nIt is ${now.toISOString()} right now.`,
     );
@@ -92,30 +101,43 @@ Guidelines:
       `=== THE WORLD AS YOU PERCEIVE IT ===\n${serializeSubjectiveWorldState(worldState, entity.id)}`,
     );
 
+    // Fetch recent buffer entries once
+    let recentEntries: BufferEntry[] = [];
+    if (this.bufferRepo) {
+      try {
+        recentEntries = this.bufferRepo.listForOwner(entity.id);
+      } catch {}
+    }
+
     // --- Recent memory ---
-    const memorySection = this.buildMemorySection(
-      entity,
-      worldState.clock.get(),
-    );
+    const memorySection = this.buildMemorySection(entity, recentEntries, now);
     if (memorySection) {
       sections.push(memorySection);
     }
 
+    // --- Recalled Long-Term memory ---
+    const ledgerSection = this.buildLedgerSection(
+      worldState,
+      entity,
+      recentEntries,
+      now,
+    );
+    if (ledgerSection) {
+      sections.push(ledgerSection);
+    }
+
     return sections.join("\n\n");
   }
 
-  private buildMemorySection(entity: Entity, now: Date): string | null {
+  private buildMemorySection(
+    entity: Entity,
+    entries: BufferEntry[],
+    now: Date,
+  ): string | null {
     if (!this.bufferRepo) return null;
 
-    let entries: BufferEntry[];
-    try {
-      entries = this.bufferRepo.listForOwner(entity.id);
-    } catch {
-      return null;
-    }
-
     if (entries.length === 0) {
-      return `=== YOUR RECENT MEMORY ===\n(You have no memories yet.)`;
+      return `=== RECENT EVENTS ===\n(No recent events recorded.)`;
     }
 
     const recent = entries.slice(-this.memoryLimit);
@@ -135,6 +157,110 @@ Guidelines:
       groupedLines.push(`  - ${serialized}`);
     }
 
-    return `=== YOUR RECENT MEMORY ===\n${groupedLines.join("\n")}`;
+    return `=== RECENT EVENTS ===\n${groupedLines.join("\n")}`;
+  }
+
+  private buildLedgerSection(
+    worldState: WorldState,
+    entity: Entity,
+    recentBuffer: BufferEntry[],
+    now: Date,
+  ): string | null {
+    if (!this.ledgerRepo) return null;
+
+    // 1. Get co-located entities (in the same location as entity)
+    const coLocatedEntityIds: string[] = [];
+    if (entity.locationId) {
+      for (const e of worldState.entities.values()) {
+        if (e.id !== entity.id && e.locationId === entity.locationId) {
+          coLocatedEntityIds.push(e.id);
+        }
+      }
+    }
+
+    // 2. Compute Active Focus entities based on recent interactions (last 10 entries)
+    const activeFocus = new Set<string>();
+    const maxFocus = 3;
+
+    // We scan the recent buffer entries to see who we recently talked to or who talked to us
+    for (let i = recentBuffer.length - 1; i >= 0; i--) {
+      const entry = recentBuffer[i];
+      const intent = entry.intent;
+
+      if (
+        intent.actorId !== entity.id &&
+        coLocatedEntityIds.includes(intent.actorId)
+      ) {
+        activeFocus.add(intent.actorId);
+      }
+      for (const targetId of intent.targetIds) {
+        if (targetId !== entity.id && coLocatedEntityIds.includes(targetId)) {
+          activeFocus.add(targetId);
+        }
+      }
+      if (activeFocus.size >= maxFocus) break;
+    }
+
+    // If co-located entities is small, auto-focus all of them
+    if (activeFocus.size < maxFocus && coLocatedEntityIds.length <= maxFocus) {
+      for (const id of coLocatedEntityIds) {
+        if (id !== entity.id) {
+          activeFocus.add(id);
+        }
+      }
+    }
+
+    const activeFocusIds = Array.from(activeFocus);
+
+    // 3. Retrieve memories using Active Focus
+    let recalled: LedgerEntry[];
+    try {
+      recalled = this.ledgerRepo.retrieve(
+        entity.id,
+        entity.locationId,
+        activeFocusIds,
+        undefined, // no query embedding for now (Recency + Importance ranking)
+        now,
+        this.ledgerLimit,
+        { includeAssociativeNeighbors: true },
+      );
+    } catch {
+      return null;
+    }
+
+    if (recalled.length === 0) return null;
+
+    // 4. Format them identical to the recent memory format
+    const groupedLines: string[] = [];
+    let currentGroup: string | null = null;
+
+    for (const entry of recalled) {
+      const when = naturalizeTime(now, new Date(entry.timestamp));
+
+      let content = entry.content;
+      // Resolve system IDs to subjective aliases in the content
+      for (const targetId of entry.involvedEntityIds) {
+        const alias = resolveAlias(entity, targetId);
+        content = content.replace(new RegExp(targetId, "g"), alias);
+      }
+      if (entry.locationId) {
+        content += ` (at ${entry.locationId})`;
+      }
+
+      if (when !== currentGroup) {
+        currentGroup = when;
+        const header = when.charAt(0).toUpperCase() + when.slice(1);
+        groupedLines.push(header);
+      }
+
+      groupedLines.push(`  - ${content}`);
+      if (entry.quotes && entry.quotes.length > 0) {
+        for (const quote of entry.quotes) {
+          groupedLines.push(`    Quote: "${quote}"`);
+        }
+      }
+    }
+
+    return `=== YOUR MEMORIES ===\n${groupedLines.join("\n")}`;
   }
 }

packages/actor/src/actor.ts

@@ -3,6 +3,7 @@ import { ILLMProvider } from "@omnia/llm";
 import {
   BufferEntry,
   BufferRepository,
+  LedgerRepository,
 } from "@omnia/memory";
 import {
   Intent,
@@ -68,15 +69,30 @@ export class ActorAgent {
   private decoder: IntentDecoder;
   private generator: IActorProseGenerator;
 
+  private llmProvider: ILLMProvider;
+
   constructor(
-    private llmProvider: ILLMProvider,
+    llmProvider: ILLMProvider | { actor: ILLMProvider; decoder: ILLMProvider },
     bufferRepo?: BufferRepository,
+    ledgerRepo?: LedgerRepository,
     memoryLimit?: number,
     generator?: IActorProseGenerator,
   ) {
-    this.promptBuilder = new ActorPromptBuilder(bufferRepo, memoryLimit);
-    this.decoder = new IntentDecoder(llmProvider);
-    this.generator = generator ?? new LLMActorProseGenerator(llmProvider);
+    let actorProv: ILLMProvider;
+    let decoderProv: ILLMProvider;
+
+    if ("actor" in llmProvider && "decoder" in llmProvider) {
+      actorProv = llmProvider.actor;
+      decoderProv = llmProvider.decoder;
+    } else {
+      actorProv = llmProvider;
+      decoderProv = llmProvider;
+    }
+
+    this.promptBuilder = new ActorPromptBuilder(bufferRepo, ledgerRepo, memoryLimit);
+    this.decoder = new IntentDecoder(decoderProv);
+    this.generator = generator ?? new LLMActorProseGenerator(actorProv);
+    this.llmProvider = actorProv;
   }
 
   /**

packages/actor/tests/actor-prompt-builder.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Database from "better-sqlite3";
+import { WorldState, Entity, AttributeVisibility } from "@omnia/core";
+import { BufferRepository, LedgerRepository } from "@omnia/memory";
+import { ActorPromptBuilder } from "../src/actor-prompt-builder";
+
+describe("ActorPromptBuilder with Long-Term Memory Integration", () => {
+  let db: Database.Database;
+  let bufferRepo: BufferRepository;
+  let ledgerRepo: LedgerRepository;
+
+  beforeEach(() => {
+    db = new Database(":memory:");
+    
+    // Core database schemas for testing
+    db.exec(`
+      CREATE TABLE objects (
+        id TEXT PRIMARY KEY
+      );
+    `);
+
+    db.exec(`
+      INSERT INTO objects (id) VALUES ('alice'), ('bob'), ('charlie');
+    `);
+
+    bufferRepo = new BufferRepository(db);
+    ledgerRepo = new LedgerRepository(db);
+  });
+
+  afterEach(() => {
+    db.close();
+  });
+
+  it("should inject both recent memory and recalled long-term memory with subjective aliases resolved", () => {
+    const world = new WorldState("world-123", new Date("2024-01-10T12:00:00.000Z"));
+    
+    const alice = new Entity("alice", "tavern");
+    // Add subjective alias for bob
+    alice.aliases.set("bob", "Strider");
+    world.addEntity(alice);
+
+    const bob = new Entity("bob", "tavern");
+    world.addEntity(bob);
+
+    // 1. Populate recent buffer memory
+    bufferRepo.save({
+      id: "buf1",
+      ownerId: "alice",
+      timestamp: "2024-01-10T11:58:00.000Z", // 2 mins ago
+      locationId: "tavern",
+      intent: {
+        type: "dialogue",
+        actorId: "alice",
+        targetIds: ["bob"],
+        originalText: "Hello there",
+        description: "Alice greets Bob",
+      },
+    });
+
+    // 2. Populate ledger repository (long-term memory)
+    ledgerRepo.save({
+      id: "ledger1",
+      ownerId: "alice",
+      timestamp: "2024-01-08T12:00:00.000Z", // 2 days ago
+      locationId: "tavern",
+      involvedEntityIds: ["bob"],
+      content: "alice met bob at the tavern.",
+      quotes: ["I am a ranger."],
+      importance: 9,
+      embedding: [],
+    });
+
+    const builder = new ActorPromptBuilder(bufferRepo, ledgerRepo, 20, 5);
+    const { userContext } = builder.build(world, alice);
+
+    // Check recent memory exists
+    expect(userContext).toContain("=== RECENT EVENTS ===");
+    expect(userContext).toContain("Alice greets Bob");
+
+    // Check long-term memory exists
+    expect(userContext).toContain("=== YOUR MEMORIES ===");
+    // Bob should be resolved to Strider in the ledger content
+    expect(userContext).toContain("alice met Strider at the tavern.");
+    expect(userContext).toContain('Quote: "I am a ranger."');
+  });
+
+  it("should not explode if ledger contains no memories or is empty", () => {
+    const world = new WorldState("world-123", new Date("2024-01-10T12:00:00.000Z"));
+    const alice = new Entity("alice", "tavern");
+    world.addEntity(alice);
+
+    const builder = new ActorPromptBuilder(bufferRepo, ledgerRepo, 20, 5);
+    const { userContext } = builder.build(world, alice);
+
+    expect(userContext).toContain("=== RECENT EVENTS ===");
+    expect(userContext).not.toContain("=== YOUR MEMORIES ===");
+  });
+});

packages/architect/src/architect.ts

@@ -12,9 +12,23 @@ export class Architect {
   private validator: LLMValidator;
   private timeDeltaGenerator: TimeDeltaGenerator;
 
-  constructor(llmProvider: ILLMProvider, private repo?: SQLiteRepository) {
-    this.validator = new LLMValidator(llmProvider);
-    this.timeDeltaGenerator = new TimeDeltaGenerator(llmProvider);
+  constructor(
+    llmProvider: ILLMProvider | { validator: ILLMProvider; timedelta: ILLMProvider },
+    private repo?: SQLiteRepository,
+  ) {
+    let valProv: ILLMProvider;
+    let timeProv: ILLMProvider;
+
+    if ("validator" in llmProvider && "timedelta" in llmProvider) {
+      valProv = llmProvider.validator;
+      timeProv = llmProvider.timedelta;
+    } else {
+      valProv = llmProvider;
+      timeProv = llmProvider;
+    }
+
+    this.validator = new LLMValidator(valProv);
+    this.timeDeltaGenerator = new TimeDeltaGenerator(timeProv);
   }
 
   /**

packages/architect/tests/architect.test.ts

@@ -22,8 +22,10 @@ describe("Architect & LLMValidator Unit Tests (Tier 1)", () => {
       type: "action",
       originalText: "open the chest and read the scroll",
       description: "Open the chest and read the scroll",
+      selfDescription: "You open the chest and read the scroll.",
       actorId: "alice",
       targetIds: [],
+      modifiers: [],
     };
 
     const result = await architect.validateIntent(world, intent);
@@ -51,8 +53,10 @@ describe("Architect & LLMValidator Unit Tests (Tier 1)", () => {
       type: "action",
       originalText: "unlock the gate and escape",
       description: "Unlock the gate and escape",
+      selfDescription: "You unlock the gate and escape.",
       actorId: "bob",
       targetIds: [],
+      modifiers: [],
     };
 
     const result = await architect.validateIntent(world, intent);
@@ -72,8 +76,10 @@ describe("Architect & LLMValidator Unit Tests (Tier 1)", () => {
       type: "action",
       originalText: "haunt the mansion",
       description: "Haunt the mansion",
+      selfDescription: "You haunt the mansion.",
       actorId: "ghost",
       targetIds: [],
+      modifiers: [],
     };
 
     const result = await architect.validateIntent(world, intent);
@@ -110,8 +116,10 @@ describe("TimeDeltaGenerator & Architect.processIntent Unit Tests (Tier 1)", ()
       type: "action",
       originalText: "pick the lock of the wooden chest",
       description: "Pick the lock of the wooden chest",
+      selfDescription: "You pick the lock of the wooden chest.",
       actorId: "alice",
       targetIds: [],
+      modifiers: [],
     };
 
     const result = await architect.processIntent(world, intent);
@@ -152,8 +160,10 @@ describe("TimeDeltaGenerator & Architect.processIntent Unit Tests (Tier 1)", ()
       type: "action",
       originalText: "run away",
       description: "Run away",
+      selfDescription: "You run away.",
       actorId: "bob",
       targetIds: [],
+      modifiers: [],
     };
 
     const result = await architect.processIntent(world, intent);

packages/core/src/alias.ts

@@ -0,0 +1,6 @@
+import { Entity } from "./entity.js";
+
+export function resolveAlias(viewer: Entity, targetId: string): string {
+  if (targetId === viewer.id) return "you";
+  return viewer.aliases.get(targetId) ?? "an unfamiliar figure";
+}

packages/core/src/index.ts

@@ -1,5 +1,13 @@
+/**
+ * Monorepo Hygiene Note:
+ * If a pure function only touches types owned by core (e.g., Entity, WorldState, Attribute),
+ * it belongs here in the core package (e.g., in a dedicated file like alias.ts), even if
+ * a higher-level package is currently its only consumer.
+ */
 export * from "./attribute.js";
 export * from "./entity.js";
 export * from "./world.js";
 export * from "./clock.js";
 export * from "./repository.js";
+export * from "./alias.js";
+

packages/core/src/world.ts

@@ -1,6 +1,7 @@
 import { AttributableObject, Attribute, serializeAttributes } from "./attribute.js";
 import { Entity } from "./entity.js";
 import { WorldClock } from "./clock.js";
+import { resolveAlias } from "./alias.js";
 
 export class WorldState extends AttributableObject {
   /**
@@ -118,19 +119,6 @@ export function serializeObjectiveWorldState(worldState: WorldState): string {
   return lines.join("\n");
 }
 
-/**
- * Resolves how a viewer subjectively refers to a target entity.
- * - Self → "you"
- * - Known (in the viewer's alias map) → the subjective alias
- * - Unknown → "an unfamiliar figure"
- *
- * Mirrors the implementation in @omnia/memory's resolveAlias, inlined here
- * to avoid a circular dependency (memory depends on core).
- */
-function resolveAliasViewer(viewer: Entity, targetId: string): string {
-  if (targetId === viewer.id) return "you";
-  return viewer.aliases.get(targetId) ?? "an unfamiliar figure";
-}
 
 /**
  * Serializes a single attribute the way a viewer perceives it — name and
@@ -164,7 +152,7 @@ export function serializeSubjectiveWorldState(
   }
 
   const lines: string[] = [];
-  const viewerAlias = resolveAliasViewer(viewer, viewerId);
+  const viewerAlias = resolveAlias(viewer, viewerId);
 
   // --- World attributes (only those the viewer can see) ---
   const worldVisible = worldState.getVisibleAttributesFor(viewerId);
@@ -208,8 +196,8 @@ export function serializeSubjectiveWorldState(
   if (coLocated.length > 0) {
     lines.push("  Entities present with you:");
     for (const e of coLocated) {
-      const alias = resolveAliasViewer(viewer, e.id);
-      lines.push(`    - ${alias} (ID: ${e.id}):`);
+      const alias = resolveAlias(viewer, e.id);
+      lines.push(`    - ${alias}:`);
       const eVisible = e.getVisibleAttributesFor(viewerId);
       lines.push(serializeVisibleAttributes(eVisible).split("\n").map((l) => "      " + l).join("\n"));
     }
@@ -220,8 +208,8 @@ export function serializeSubjectiveWorldState(
   if (elsewhere.length > 0) {
     lines.push("  Other presences you are aware of (elsewhere):");
     for (const e of elsewhere) {
-      const alias = resolveAliasViewer(viewer, e.id);
-      lines.push(`    - ${alias} (ID: ${e.id}) [elsewhere]`);
+      const alias = resolveAlias(viewer, e.id);
+      lines.push(`    - ${alias} [elsewhere]`);
     }
   }
 

packages/intent/src/intent-decoder.ts

@@ -1,6 +1,6 @@
-import { WorldState, serializeObjectiveWorldState } from "@omnia/core";
+import { WorldState } from "@omnia/core";
 import { ILLMProvider } from "@omnia/llm";
-import { IntentSequence, IntentSequenceSchema } from "./intent.js";
+import { IntentSequence, LLMIntentSequenceSchema } from "./intent.js";
 
 export class IntentDecoder {
   constructor(private llmProvider: ILLMProvider) {}
@@ -23,9 +23,15 @@ export class IntentDecoder {
     const actor = worldState.getEntity(actorId);
 
     const aliasEntries = actor ? Array.from(actor.aliases.entries()) : [];
-    const aliasContext = aliasEntries.length > 0
-      ? aliasEntries.map(([targetId, alias]) => `- "${alias}" refers to entity ID: "${targetId}"`).join("\n")
-      : "(No known aliases)";
+    const aliasContext =
+      aliasEntries.length > 0
+        ? aliasEntries
+            .map(
+              ([targetId, alias]) =>
+                `- "${alias}" refers to entity ID: "${targetId}"`,
+            )
+            .join("\n")
+        : "(No known aliases)";
 
     const systemPrompt = `
 You are the Intent Decoder for a narrative simulation engine.
@@ -33,20 +39,16 @@ Your job is to take a block of narrative prose written by an actor agent and dec
 
 For each intent you must:
 1. Classify its type:
-   - "dialogue": Any speech, conversation, or verbal communication directed at another entity.
-   - "action": Any physical or logical action performed in the world (e.g., moving, picking up, opening, looking).
-   - "monologue": An inner thought, reflection, or internal monologue. This is purely internal — not spoken aloud, not perceivable by any other entity, and not a physical action. Use this for any prose depicting the character thinking, reflecting, feeling, or narrating to themselves internally.
+   - "dialogue": if actor speaking, talking, whispering, murmuring, etc
+   - "action": Any physical or logical action performed in the world (e.g., moving, opening, looking).
+   - "monologue": An inner thought, reflection, or internal monologue/self narration.
 2. Extract the original text fragment from the prose that corresponds to this intent.
-3. Write a concise, structured description of the intent (what is being done or said). Include as much detail about the action as possible that was extracted from the narrative prose. Do not make up qualities.
-4. Identify the actorId (the entity performing the intent — this will always be "${actorId}").
-5. Identify targetIds — the entity IDs of the receiving parties. Use the "KNOWN ENTITY IDS" and "ACTOR ALIASES" mapping to resolve any subjective names, descriptions, or nicknames used in the prose to their correct system entity IDs. If no specific target, use an empty array. For "monologue" intents, targetIds must always be an empty array.
-
-Rules:
-- Preserve the chronological order of intents as they appear in the prose.
-- Do NOT merge unrelated actions into a single intent.
-- Dialogue and actions should be separate intents even if they happen in the same sentence.
-- If the prose contains only dialogue, return a single dialogue intent.
-- If the prose contains only a single action, return a single action intent.
+3. Populate "description" and "selfDescription":
+   - "description": No subject or name — a bare third-person verb phrase only (e.g. "clears their throat", "shakes their head slowly")
+   - "selfDescription": The same event from the actor's own perspective, second person, complete sentence starting with "You" (e.g. "You clear your throat.", "You shake your head slowly."). This is shown directly in the actor's own memory — it must never say "the actor" or refer to them in the third person.
+   - In case of a dialogue, the description and self Description only stores the exact words said by the entity. (e.g. "I will do that later", "Are you serious right now?")
+4. Identify targetIds — the entity IDs of the receiving parties. Use the "KNOWN ENTITY IDS" mapping to resolve any subjective names,or aliases used in the prose to their correct system entity IDs. If no specific target, use an empty array.
+5. Identify modifiers — a list of strings representing additional qualities or modifiers extracted from the narrative prose. This includes emotions, tone of voice, speed, manner of action, or statement type (e.g., "question", "anxious", "whispering", "slowly", "quietly", "forcefully"). If no modifiers are present, use an empty array.
 `.trim();
 
     const userContext = `
@@ -58,7 +60,7 @@ The actor refers to other entities using these subjective names/aliases:
 ${aliasContext}
 
 === WORLD STATE ===
-${serializeObjectiveWorldState(worldState)}
+${serializeSimplifiedWorldState(worldState)}
 
 === ACTOR ===
 Actor ID: ${actorId}
@@ -70,7 +72,7 @@ ${narrativeProse}
     const response = await this.llmProvider.generateStructuredResponse({
       systemPrompt,
       userContext,
-      schema: IntentSequenceSchema,
+      schema: LLMIntentSequenceSchema,
     });
 
     if (!response.success || !response.data) {
@@ -79,6 +81,42 @@ ${narrativeProse}
       );
     }
 
-    return response.data;
+    const fullIntents = response.data.intents.map((intent) => ({
+      ...intent,
+      actorId,
+    }));
+
+    return {
+      intents: fullIntents,
+    };
   }
 }
+
+function serializeSimplifiedWorldState(worldState: WorldState): string {
+  const lines: string[] = [];
+
+  lines.push("Locations:");
+  if (worldState.locations.size > 0) {
+    for (const loc of worldState.locations.values()) {
+      const parentId = (loc as { parentId?: string | null }).parentId;
+      const parentStr = parentId ? ` (Parent: ${parentId})` : "";
+      lines.push(`  - Location [ID: ${loc.id}]${parentStr}`);
+    }
+  } else {
+    lines.push("  (No locations)");
+  }
+
+  lines.push("Entities:");
+  if (worldState.entities.size > 0) {
+    for (const entity of worldState.entities.values()) {
+      const locStr = entity.locationId
+        ? ` (Location: ${entity.locationId})`
+        : "";
+      lines.push(`  - Entity [ID: ${entity.id}]${locStr}`);
+    }
+  } else {
+    lines.push("  (No entities)");
+  }
+
+  return lines.join("\n");
+}

packages/intent/src/intent.ts

@@ -14,7 +14,7 @@ export type IntentType = z.infer<typeof IntentTypeSchema>;
 /**
  * A single decoded intent extracted from narrative prose.
  */
-export const IntentSchema = z.object({
+export const LLMIntentSchema = z.object({
   /** The type of intent. */
   type: IntentTypeSchema,
 
@@ -24,8 +24,8 @@ export const IntentSchema = z.object({
   /** A concise, structured description of the intent's action or dialogue. */
   description: z.string(),
 
-  /** The entity ID of the actor performing the intent. */
-  actorId: z.string(),
+  /** The same event from the actor's own perspective (second person, "You"). */
+  selfDescription: z.string(),
 
   /**
    * Entity IDs of the receiving parties (e.g., who is being spoken to,
@@ -33,10 +33,25 @@ export const IntentSchema = z.object({
    * "monologue" intents, since they are not perceivable by anyone.
    */
   targetIds: z.array(z.string()),
+
+  /**
+   * Additional qualities or modifiers extracted from the prose (e.g., emotions,
+   * questions, speed, manner of action like 'quietly', 'whispering', 'anxiously').
+   */
+  modifiers: z.array(z.string()),
+});
+
+export const IntentSchema = LLMIntentSchema.extend({
+  /** The entity ID of the actor performing the intent. */
+  actorId: z.string(),
 });
 
 export type Intent = z.infer<typeof IntentSchema>;
 
+export const LLMIntentSequenceSchema = z.object({
+  intents: z.array(LLMIntentSchema),
+});
+
 /**
  * The full output of the Intent Decoder: an ordered sequence of intents
  * extracted from a single narrative prose block.

packages/intent/tests/intent.test.ts

@@ -15,8 +15,9 @@ describe("IntentDecoder Unit Tests (Tier 1)", () => {
           type: "action",
           originalText: "Alice opened the chest.",
           description: "Open the wooden chest.",
-          actorId: "alice",
+          selfDescription: "You open the wooden chest.",
           targetIds: [],
+          modifiers: [],
         },
       ],
     };
@@ -45,8 +46,9 @@ describe("IntentDecoder Unit Tests (Tier 1)", () => {
           type: "dialogue",
           originalText: '"Do you have the key?" Alice asked Bob.',
           description: "Alice asks Bob if he has the key.",
-          actorId: "alice",
+          selfDescription: "You ask Bob if he has the key.",
           targetIds: ["bob"],
+          modifiers: [],
         },
       ],
     };
@@ -78,15 +80,17 @@ describe("IntentDecoder Unit Tests (Tier 1)", () => {
           type: "dialogue",
           originalText: '"Cover me," Alice whispered to Bob.',
           description: "Alice whispers to Bob requesting cover.",
-          actorId: "alice",
+          selfDescription: "You whisper to Bob requesting cover.",
           targetIds: ["bob"],
+          modifiers: [],
         },
         {
           type: "action",
           originalText: "She crept towards the door and pulled the handle.",
           description: "Creep towards the door and pull the handle.",
-          actorId: "alice",
+          selfDescription: "You creep towards the door and pull the handle.",
           targetIds: [],
+          modifiers: [],
         },
       ],
     };

packages/llm/package.json

@@ -7,6 +7,10 @@
     ".": "./dist/index.js"
   },
   "dependencies": {
-    "@types/node": "^26.1.0"
+    "@types/node": "^26.1.0",
+    "better-sqlite3": "^12.11.1"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13"
   }
 }

packages/llm/src/index.ts

@@ -3,3 +3,4 @@ export * from "./config.js";
 export * from "./providers/google-genai.js";
 export * from "./providers/mock.js";
 export * from "./providers/openrouter.js";
+export * from "./provider-manager.js";

packages/llm/src/llm.ts

@@ -11,12 +11,82 @@ export interface LLMResponse<T> {
   success: boolean;
   data?: T;
   error?: string;
+  usage?: {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    modelName?: string;
+    providerInstanceName?: string;
+    maxContext?: number;
+  };
+}
+
+export interface LLMCallRecord {
+  systemPrompt: string;
+  userContext: string;
+  usage?: {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    modelName?: string;
+    providerInstanceName?: string;
+    maxContext?: number;
+  };
 }
 
 export interface ILLMProvider {
   providerName: string;
-  // We use Zod to ensure the generic T matches the schema
+  maxContext?: number;
   generateStructuredResponse<T extends z.ZodTypeAny>(
     request: LLMRequest<T>,
   ): Promise<LLMResponse<z.infer<T>>>;
+  lastCalls?: LLMCallRecord[];
 }
+
+export interface IEmbeddingProvider {
+  providerName: string;
+  embed(text: string): Promise<number[]>;
+}
+
+export interface ModelProviderInstance {
+  id: string;
+  name: string;
+  providerName: string;
+  apiKey: string;
+  isActive: boolean;
+  modelName?: string;
+  type: "generative" | "embedding";
+  maxContext?: number;
+}
+
+export interface ModelProviderMeta {
+  id: string;
+  displayName: string;
+  description: string;
+  defaultModel: string;
+  defaultEmbeddingModel: string;
+}
+
+export const AVAILABLE_PROVIDERS: ModelProviderMeta[] = [
+  {
+    id: "google-genai",
+    displayName: "Google Gemini",
+    description: "Official Gemini integration using Google Gen AI SDK",
+    defaultModel: "gemini-2.5-flash",
+    defaultEmbeddingModel: "gemini-embedding-001",
+  },
+  {
+    id: "openrouter",
+    displayName: "OpenRouter",
+    description: "Multi-model router supporting Anthropic, OpenAI, DeepSeek, and local models",
+    defaultModel: "google/gemini-2.5-flash",
+    defaultEmbeddingModel: "openai/text-embedding-3-small",
+  },
+  {
+    id: "mock",
+    displayName: "Mock LLM Provider",
+    description: "Stateless mock provider for testing and offline development",
+    defaultModel: "mock",
+    defaultEmbeddingModel: "mock-embeddings",
+  },
+];

packages/llm/src/provider-manager.ts

@@ -0,0 +1,441 @@
+import Database from "better-sqlite3";
+import path from "path";
+import fs from "fs";
+import type { ModelProviderInstance } from "./llm.js";
+
+let dbPathOverride: string | null = null;
+let hasBootstrapped = false;
+
+export function setDbPathOverride(p: string | null) {
+  dbPathOverride = p;
+}
+
+export function resetHasBootstrapped() {
+  hasBootstrapped = false;
+}
+
+function getWorkspaceRoot() {
+  let current = process.cwd();
+  while (current !== "/" && current !== path.parse(current).root) {
+    if (
+      fs.existsSync(path.join(current, "pnpm-workspace.yaml")) ||
+      fs.existsSync(path.join(current, "package.json"))
+    ) {
+      if (fs.existsSync(path.join(current, "pnpm-workspace.yaml"))) {
+        return current;
+      }
+    }
+    current = path.dirname(current);
+  }
+  return process.cwd();
+}
+
+function getSettingsDb() {
+  let dbPath: string;
+  if (dbPathOverride) {
+    dbPath = dbPathOverride;
+  } else {
+    const wsRoot = getWorkspaceRoot();
+    const dbDir = path.resolve(wsRoot, "data");
+    if (!fs.existsSync(dbDir)) {
+      fs.mkdirSync(dbDir, { recursive: true });
+    }
+    dbPath = path.join(dbDir, "settings.db");
+  }
+  const db = new Database(dbPath);
+  
+  db.prepare(`
+    CREATE TABLE IF NOT EXISTS provider_instances (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      providerName TEXT NOT NULL,
+      apiKey TEXT NOT NULL,
+      isActive INTEGER NOT NULL DEFAULT 0,
+      modelName TEXT,
+      type TEXT NOT NULL DEFAULT 'generative'
+    )
+  `).run();
+
+  try {
+    db.prepare(`ALTER TABLE provider_instances ADD COLUMN modelName TEXT`).run();
+  } catch {
+    // ignore
+  }
+
+  try {
+    db.prepare(`ALTER TABLE provider_instances ADD COLUMN type TEXT NOT NULL DEFAULT 'generative'`).run();
+  } catch {
+    // ignore
+  }
+
+  try {
+    db.prepare(`ALTER TABLE provider_instances ADD COLUMN maxContext INTEGER`).run();
+  } catch {
+    // ignore
+  }
+
+  // Auto-bootstrap environment variables if DB contains 0 instances
+  try {
+    if (!hasBootstrapped) {
+      const totalCount = db.prepare(`SELECT COUNT(*) as count FROM provider_instances`).get() as { count: number };
+      if (totalCount.count === 0) {
+        const googleKey = process.env.GOOGLE_API_KEY;
+        const openRouterKey = process.env.OPENROUTER_API_KEY;
+        let hasInsertedGenerative = false;
+
+        if (googleKey && googleKey.trim()) {
+          const id = "provider-default-google";
+          db.prepare(`
+            INSERT INTO provider_instances (id, name, providerName, apiKey, isActive, modelName, type, maxContext)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+          `).run(id, "Gemini (Env)", "google-genai", googleKey.trim(), 1, "gemini-2.5-flash", "generative", 32768);
+          hasInsertedGenerative = true;
+
+          const embedId = "provider-default-google-embed";
+          db.prepare(`
+            INSERT INTO provider_instances (id, name, providerName, apiKey, isActive, modelName, type, maxContext)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+          `).run(embedId, "Gemini Embed (Env)", "google-genai", googleKey.trim(), 1, "gemini-embedding-001", "embedding", 0);
+        }
+
+        if (openRouterKey && openRouterKey.trim()) {
+          const id = "provider-default-openrouter";
+          const isActive = hasInsertedGenerative ? 0 : 1;
+          db.prepare(`
+            INSERT INTO provider_instances (id, name, providerName, apiKey, isActive, modelName, type, maxContext)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+          `).run(id, "OpenRouter (Env)", "openrouter", openRouterKey.trim(), isActive, "google/gemini-2.5-flash", "generative", 32768);
+        }
+      }
+      hasBootstrapped = true;
+    }
+  } catch {
+    // ignore write lock issues or other DB errors during bootstrap
+  }
+  
+  return db;
+}
+
+export class ProviderManager {
+  static list(): ModelProviderInstance[] {
+    const db = getSettingsDb();
+    try {
+      const rows = db.prepare(`SELECT * FROM provider_instances`).all() as {
+        id: string;
+        name: string;
+        providerName: string;
+        apiKey: string;
+        isActive: number;
+        modelName?: string;
+        type: string;
+        maxContext?: number;
+      }[];
+      return rows.map((r) => ({
+        id: r.id,
+        name: r.name,
+        providerName: r.providerName,
+        apiKey: r.apiKey,
+        isActive: r.isActive === 1,
+        modelName: r.modelName || undefined,
+        type: (r.type as "generative" | "embedding") || "generative",
+        maxContext: r.maxContext !== undefined && r.maxContext !== null ? r.maxContext : (r.type === "embedding" ? 0 : 32768),
+      }));
+    } finally {
+      db.close();
+    }
+  }
+
+  static create(
+    name: string,
+    providerName: string,
+    apiKey: string,
+    modelName?: string,
+    type: "generative" | "embedding" = "generative",
+    maxContext?: number
+  ): ModelProviderInstance {
+    const db = getSettingsDb();
+    try {
+      const id = "provider-" + Date.now();
+      const activeCount = db
+        .prepare(`SELECT COUNT(*) as count FROM provider_instances WHERE isActive = 1 AND type = ?`)
+        .get(type) as { count: number };
+      const isActive = activeCount.count === 0 ? 1 : 0;
+      
+      const actualMaxContext = maxContext !== undefined ? maxContext : (type === "generative" ? 32768 : 0);
+
+      db.prepare(`
+        INSERT INTO provider_instances (id, name, providerName, apiKey, isActive, modelName, type, maxContext)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(id, name, providerName, apiKey, isActive, modelName || null, type, actualMaxContext);
+      
+      return { id, name, providerName, apiKey, isActive: isActive === 1, modelName, type, maxContext: actualMaxContext };
+    } finally {
+      db.close();
+    }
+  }
+
+  static delete(id: string): void {
+    const db = getSettingsDb();
+    try {
+      const provider = db.prepare(`SELECT isActive, type FROM provider_instances WHERE id = ?`).get(id) as { isActive: number; type: string } | undefined;
+      db.prepare(`DELETE FROM provider_instances WHERE id = ?`).run(id);
+      
+      if (provider && provider.isActive === 1) {
+        const next = db
+          .prepare(`SELECT id FROM provider_instances WHERE type = ? LIMIT 1`)
+          .get(provider.type) as { id: string } | undefined;
+        if (next) {
+          db.prepare(`UPDATE provider_instances SET isActive = 1 WHERE id = ?`).run(next.id);
+        }
+      }
+    } finally {
+      db.close();
+    }
+  }
+
+  static setActive(id: string): void {
+    const db = getSettingsDb();
+    try {
+      const target = db.prepare(`SELECT type FROM provider_instances WHERE id = ?`).get(id) as { type: string } | undefined;
+      if (target) {
+        db.prepare(`UPDATE provider_instances SET isActive = 0 WHERE type = ?`).run(target.type);
+        db.prepare(`UPDATE provider_instances SET isActive = 1 WHERE id = ?`).run(id);
+      }
+    } finally {
+      db.close();
+    }
+  }
+
+  static update(
+    id: string,
+    name: string,
+    providerName: string,
+    apiKey?: string,
+    modelName?: string,
+    type: "generative" | "embedding" = "generative",
+    maxContext?: number
+  ): void {
+    const db = getSettingsDb();
+    try {
+      const actualMaxContext = maxContext !== undefined ? maxContext : (type === "generative" ? 32768 : 0);
+      if (apiKey && apiKey.trim()) {
+        db.prepare(`
+          UPDATE provider_instances
+          SET name = ?, providerName = ?, apiKey = ?, modelName = ?, type = ?, maxContext = ?
+          WHERE id = ?
+        `).run(name, providerName, apiKey, modelName || null, type, actualMaxContext, id);
+      } else {
+        db.prepare(`
+          UPDATE provider_instances
+          SET name = ?, providerName = ?, modelName = ?, type = ?, maxContext = ?
+          WHERE id = ?
+        `).run(name, providerName, modelName || null, type, actualMaxContext, id);
+      }
+    } finally {
+      db.close();
+    }
+  }
+
+  static getActive(type: "generative" | "embedding" = "generative"): ModelProviderInstance | null {
+    const db = getSettingsDb();
+    try {
+      const row = db.prepare(`SELECT * FROM provider_instances WHERE isActive = 1 AND type = ?`).get(type) as {
+        id: string;
+        name: string;
+        providerName: string;
+        apiKey: string;
+        isActive: number;
+        modelName?: string;
+        type: string;
+        maxContext?: number;
+      } | undefined;
+
+      if (!row) {
+        const totalCount = db.prepare(`SELECT COUNT(*) as count FROM provider_instances`).get() as { count: number };
+        if (totalCount.count === 0) {
+          const googleKey = process.env.GOOGLE_API_KEY;
+          const openRouterKey = process.env.OPENROUTER_API_KEY;
+          let hasInsertedGenerative = false;
+
+          if (googleKey && googleKey.trim()) {
+            const id = "provider-default-google";
+            db.prepare(`
+              INSERT INTO provider_instances (id, name, providerName, apiKey, isActive, modelName, type, maxContext)
+              VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            `).run(id, "Gemini (Env)", "google-genai", googleKey.trim(), 1, "gemini-2.5-flash", "generative", 32768);
+            hasInsertedGenerative = true;
+
+            const embedId = "provider-default-google-embed";
+            db.prepare(`
+              INSERT INTO provider_instances (id, name, providerName, apiKey, isActive, modelName, type, maxContext)
+              VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            `).run(embedId, "Gemini Embed (Env)", "google-genai", googleKey.trim(), 1, "gemini-embedding-001", "embedding", 0);
+          }
+
+          if (openRouterKey && openRouterKey.trim()) {
+            const id = "provider-default-openrouter";
+            const isActive = hasInsertedGenerative ? 0 : 1;
+            db.prepare(`
+              INSERT INTO provider_instances (id, name, providerName, apiKey, isActive, modelName, type, maxContext)
+              VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            `).run(id, "OpenRouter (Env)", "openrouter", openRouterKey.trim(), isActive, "google/gemini-2.5-flash", "generative", 32768);
+          }
+
+          const retryRow = db.prepare(`SELECT * FROM provider_instances WHERE isActive = 1 AND type = ?`).get(type) as {
+            id: string;
+            name: string;
+            providerName: string;
+            apiKey: string;
+            isActive: number;
+            modelName?: string;
+            type: string;
+            maxContext?: number;
+          } | undefined;
+
+          if (retryRow) {
+            return {
+              id: retryRow.id,
+              name: retryRow.name,
+              providerName: retryRow.providerName,
+              apiKey: retryRow.apiKey,
+              isActive: true,
+              modelName: retryRow.modelName || undefined,
+              type: retryRow.type as "generative" | "embedding",
+              maxContext: retryRow.maxContext !== undefined && retryRow.maxContext !== null ? retryRow.maxContext : (retryRow.type === "embedding" ? 0 : 32768),
+            };
+          }
+        }
+
+        // If there's no active row but some rows exist, return the first one as active, or update it
+        const firstRow = db.prepare(`SELECT * FROM provider_instances WHERE type = ? LIMIT 1`).get(type) as {
+          id: string;
+          name: string;
+          providerName: string;
+          apiKey: string;
+          isActive: number;
+          modelName?: string;
+          type: string;
+          maxContext?: number;
+        } | undefined;
+        if (firstRow) {
+          db.prepare(`UPDATE provider_instances SET isActive = 1 WHERE id = ?`).run(firstRow.id);
+          return {
+            id: firstRow.id,
+            name: firstRow.name,
+            providerName: firstRow.providerName,
+            apiKey: firstRow.apiKey,
+            isActive: true,
+            modelName: firstRow.modelName || undefined,
+            type: firstRow.type as "generative" | "embedding",
+            maxContext: firstRow.maxContext !== undefined && firstRow.maxContext !== null ? firstRow.maxContext : (firstRow.type === "embedding" ? 0 : 32768),
+          };
+        }
+        return null;
+      }
+
+      return {
+        id: row.id,
+        name: row.name,
+        providerName: row.providerName,
+        apiKey: row.apiKey,
+        isActive: true,
+        modelName: row.modelName || undefined,
+        type: (row.type as "generative" | "embedding") || "generative",
+        maxContext: row.maxContext !== undefined && row.maxContext !== null ? row.maxContext : (row.type === "embedding" ? 0 : 32768),
+      };
+    } catch {
+      const googleKey = process.env.GOOGLE_API_KEY;
+      if (type === "embedding") {
+        if (googleKey && googleKey.trim()) {
+          return {
+            id: "provider-default-env-embed-fallback",
+            name: "Gemini Embed (Env Fallback)",
+            providerName: "google-genai",
+            apiKey: googleKey.trim(),
+            isActive: true,
+            modelName: "gemini-embedding-001",
+            type: "embedding",
+            maxContext: 0,
+          };
+        }
+        return null;
+      }
+
+      // generative fallback
+      if (googleKey && googleKey.trim()) {
+        return {
+          id: "provider-default-env-fallback",
+          name: "Gemini (Env Fallback)",
+          providerName: "google-genai",
+          apiKey: googleKey.trim(),
+          isActive: true,
+          modelName: "gemini-2.5-flash",
+          type: "generative",
+          maxContext: 32768,
+        };
+      }
+      const openRouterKey = process.env.OPENROUTER_API_KEY;
+      if (openRouterKey && openRouterKey.trim()) {
+        return {
+          id: "provider-default-env-fallback",
+          name: "OpenRouter (Env Fallback)",
+          providerName: "openrouter",
+          apiKey: openRouterKey.trim(),
+          isActive: true,
+          modelName: "google/gemini-2.5-flash",
+          type: "generative",
+          maxContext: 32768,
+        };
+      }
+      return null;
+    } finally {
+      db.close();
+    }
+  }
+
+  static getMappings(): Record<string, string> {
+    const db = getSettingsDb();
+    try {
+      db.prepare(`
+        CREATE TABLE IF NOT EXISTS provider_mappings (
+          task TEXT PRIMARY KEY,
+          providerInstanceId TEXT NOT NULL
+        )
+      `).run();
+      const rows = db.prepare(`SELECT * FROM provider_mappings`).all() as {
+        task: string;
+        providerInstanceId: string;
+      }[];
+      const mappings: Record<string, string> = {};
+      for (const row of rows) {
+        mappings[row.task] = row.providerInstanceId;
+      }
+      return mappings;
+    } finally {
+      db.close();
+    }
+  }
+
+  static setMapping(task: string, providerInstanceId: string): void {
+    const db = getSettingsDb();
+    try {
+      db.prepare(`
+        CREATE TABLE IF NOT EXISTS provider_mappings (
+          task TEXT PRIMARY KEY,
+          providerInstanceId TEXT NOT NULL
+        )
+      `).run();
+      if (!providerInstanceId) {
+        db.prepare(`DELETE FROM provider_mappings WHERE task = ?`).run(task);
+      } else {
+        db.prepare(`
+          INSERT INTO provider_mappings (task, providerInstanceId)
+          VALUES (?, ?)
+          ON CONFLICT(task) DO UPDATE SET providerInstanceId = excluded.providerInstanceId
+        `).run(task, providerInstanceId);
+      }
+    } finally {
+      db.close();
+    }
+  }
+}

packages/llm/src/providers/google-genai.ts

@@ -1,31 +1,138 @@
 import { z } from "zod";
-import { ChatGoogleGenerativeAI } from "@langchain/google-genai";
-import { ILLMProvider, LLMRequest, LLMResponse } from "../llm.js";
+import { ChatGoogleGenerativeAI, GoogleGenerativeAIEmbeddings } from "@langchain/google-genai";
+import { ILLMProvider, LLMRequest, LLMResponse, LLMCallRecord, IEmbeddingProvider } from "../llm.js";
 import { llmConfig } from "../config.js";
+import { ProviderManager } from "../provider-manager.js";
 
 export class GeminiProvider implements ILLMProvider {
+  static readonly providerId = "google-genai";
+  static readonly displayName = "Google Gemini";
+  static readonly description = "Official Gemini integration using Google Gen AI SDK";
+  static readonly defaultModel = "gemini-2.5-flash";
+
   providerName = "Gemini";
   private model: ChatGoogleGenerativeAI;
+  private modelNameUsed: string;
+  private providerInstanceName?: string;
+  private maxContextUsed?: number;
+  lastCalls: LLMCallRecord[] = [];
+
+  constructor(apiKey?: string, modelName?: string, providerInstanceName?: string, maxContext?: number) {
+    let key = apiKey;
+    let model = modelName;
+    this.providerInstanceName = providerInstanceName;
+    this.maxContextUsed = maxContext;
+
+    if (!key) {
+      const active = ProviderManager.getActive("generative");
+      if (active && active.providerName === GeminiProvider.providerId) {
+        key = active.apiKey;
+        if (!model) {
+          model = active.modelName;
+        }
+        if (!this.providerInstanceName) {
+          this.providerInstanceName = active.name;
+        }
+        if (this.maxContextUsed === undefined) {
+          this.maxContextUsed = active.maxContext;
+        }
+      }
+    }
+
+    if (!key) {
+      key = llmConfig.GOOGLE_API_KEY;
+      if (!this.providerInstanceName && key) {
+        this.providerInstanceName = "Environment Variable";
+      }
+    }
 
-  constructor(apiKey?: string) {
-    const key = apiKey || llmConfig.GOOGLE_API_KEY;
     if (!key) {
       throw new Error("GOOGLE_API_KEY is required to initialize GeminiProvider");
     }
+
+    this.modelNameUsed = model || "gemini-2.5-flash";
     this.model = new ChatGoogleGenerativeAI({
       apiKey: key,
-      model: "gemini-2.5-flash",
+      model: this.modelNameUsed,
     });
   }
 
   async generateStructuredResponse<T extends z.ZodTypeAny>(
     request: LLMRequest<T>,
   ): Promise<LLMResponse<z.infer<T>>> {
-    const structuredModel = this.model.withStructuredOutput(request.schema);
-    const result = await structuredModel.invoke([
+    const structuredModel = this.model.withStructuredOutput(request.schema, { includeRaw: true });
+    const result = (await structuredModel.invoke([
       { role: "system", content: request.systemPrompt },
       { role: "user", content: request.userContext },
-    ]);
-    return { success: true, data: result as z.infer<T> };
+    ])) as unknown as {
+      parsed?: z.infer<T>;
+      raw?: {
+        usage_metadata?: {
+          input_tokens?: number;
+          output_tokens?: number;
+          total_tokens?: number;
+        };
+      };
+    };
+
+    const parsed = result?.parsed;
+    const raw = result?.raw;
+
+    const usage = {
+      inputTokens: raw?.usage_metadata?.input_tokens || 0,
+      outputTokens: raw?.usage_metadata?.output_tokens || 0,
+      totalTokens: raw?.usage_metadata?.total_tokens || 0,
+      modelName: this.modelNameUsed,
+      providerInstanceName: this.providerInstanceName || "Default",
+      maxContext: this.maxContextUsed !== undefined ? this.maxContextUsed : 32768,
+    };
+
+    this.lastCalls.push({
+      systemPrompt: request.systemPrompt,
+      userContext: request.userContext,
+      usage,
+    });
+
+    return { success: true, data: parsed, usage };
+  }
+}
+
+export class GeminiEmbeddingProvider implements IEmbeddingProvider {
+  static readonly providerId = "google-genai";
+  static readonly displayName = "Google Gemini Embeddings";
+
+  providerName = "Gemini";
+  private model: GoogleGenerativeAIEmbeddings;
+
+  constructor(apiKey?: string, modelName?: string) {
+    let key = apiKey;
+    let model = modelName;
+
+    if (!key) {
+      const active = ProviderManager.getActive("embedding");
+      if (active) {
+        key = active.apiKey;
+        if (!model) {
+          model = active.modelName;
+        }
+      }
+    }
+
+    if (!key) {
+      key = llmConfig.GOOGLE_API_KEY;
+    }
+
+    if (!key) {
+      throw new Error("GOOGLE_API_KEY is required to initialize GeminiEmbeddingProvider");
+    }
+
+    this.model = new GoogleGenerativeAIEmbeddings({
+      apiKey: key,
+      modelName: model || "gemini-embedding-001",
+    });
+  }
+
+  async embed(text: string): Promise<number[]> {
+    return this.model.embedQuery(text);
   }
 }

packages/llm/src/providers/mock.ts

@@ -1,9 +1,15 @@
 import { z } from "zod";
-import { ILLMProvider, LLMRequest, LLMResponse } from "../llm.js";
+import { ILLMProvider, LLMRequest, LLMResponse, LLMCallRecord, IEmbeddingProvider } from "../llm.js";
 
 export class MockLLMProvider implements ILLMProvider {
+  static readonly providerId = "mock";
+  static readonly displayName = "Mock LLM Provider";
+  static readonly description = "Stateless mock provider for testing and offline development";
+  static readonly defaultModel = "mock";
+
   providerName = "mock";
   private callCount = 0;
+  lastCalls: LLMCallRecord[] = [];
 
   constructor(private responses: unknown[]) {}
 
@@ -14,11 +20,35 @@ export class MockLLMProvider implements ILLMProvider {
     if (next === undefined) {
       return { success: false, error: "Mock responses exhausted" };
     }
+    const usage = { inputTokens: 100, outputTokens: 50, totalTokens: 150 };
+    this.lastCalls.push({
+      systemPrompt: request.systemPrompt,
+      userContext: request.userContext,
+      usage,
+    });
     try {
       const parsed = request.schema.parse(next);
-      return { success: true, data: parsed };
+      return { success: true, data: parsed, usage };
     } catch (e) {
       return { success: false, error: e instanceof Error ? e.message : String(e) };
     }
   }
 }
+
+export class MockEmbeddingProvider implements IEmbeddingProvider {
+  static readonly providerId = "mock";
+
+  providerName = "mock";
+
+  constructor(private modelName?: string) {}
+
+  async embed(text: string): Promise<number[]> {
+    // Return a deterministic mock 768-dimensional vector based on the text
+    const vec = new Array(768).fill(0).map((_, i) => {
+      // Return a predictable float between -1.0 and 1.0
+      const charCode = text.charCodeAt(i % text.length) || 0;
+      return Math.sin(charCode + i);
+    });
+    return vec;
+  }
+}

packages/llm/src/providers/openrouter.ts

@@ -1,31 +1,98 @@
 import { z } from "zod";
 import { ChatOpenRouter } from "@langchain/openrouter";
-import { ILLMProvider, LLMRequest, LLMResponse } from "../llm.js";
+import { ILLMProvider, LLMRequest, LLMResponse, LLMCallRecord } from "../llm.js";
 import { llmConfig } from "../config.js";
+import { ProviderManager } from "../provider-manager.js";
 
 export class OpenRouterProvider implements ILLMProvider {
+  static readonly providerId = "openrouter";
+  static readonly displayName = "OpenRouter";
+  static readonly description = "Multi-model router supporting Anthropic, OpenAI, DeepSeek, and local models";
+  static readonly defaultModel = "google/gemini-2.5-flash";
+
   providerName = "OpenRouter";
   private model: ChatOpenRouter;
+  private modelNameUsed: string;
+  private providerInstanceName?: string;
+  private maxContextUsed?: number;
+  lastCalls: LLMCallRecord[] = [];
+
+  constructor(apiKey?: string, modelName?: string, providerInstanceName?: string, maxContext?: number) {
+    let key = apiKey;
+    let model = modelName;
+    this.providerInstanceName = providerInstanceName;
+    this.maxContextUsed = maxContext;
+
+    if (!key) {
+      const active = ProviderManager.getActive("generative");
+      if (active && active.providerName === OpenRouterProvider.providerId) {
+        key = active.apiKey;
+        if (!model) {
+          model = active.modelName;
+        }
+        if (!this.providerInstanceName) {
+          this.providerInstanceName = active.name;
+        }
+        if (this.maxContextUsed === undefined) {
+          this.maxContextUsed = active.maxContext;
+        }
+      }
+    }
+
+    if (!key) {
+      key = llmConfig.OPENROUTER_API_KEY;
+      if (!this.providerInstanceName && key) {
+        this.providerInstanceName = "Environment Variable";
+      }
+    }
 
-  constructor(apiKey?: string, modelName: string = "google/gemini-2.5-flash") {
-    const key = apiKey || llmConfig.OPENROUTER_API_KEY;
     if (!key) {
       throw new Error("OPENROUTER_API_KEY is required to initialize OpenRouterProvider");
     }
+
+    this.modelNameUsed = model || "google/gemini-2.5-flash";
     this.model = new ChatOpenRouter({
       apiKey: key,
-      model: modelName,
+      model: this.modelNameUsed,
     });
   }
 
   async generateStructuredResponse<T extends z.ZodTypeAny>(
     request: LLMRequest<T>,
   ): Promise<LLMResponse<z.infer<T>>> {
-    const structuredModel = this.model.withStructuredOutput(request.schema);
-    const result = await structuredModel.invoke([
+    const structuredModel = this.model.withStructuredOutput(request.schema, { includeRaw: true });
+    const result = (await structuredModel.invoke([
       { role: "system", content: request.systemPrompt },
       { role: "user", content: request.userContext },
-    ]);
-    return { success: true, data: result as z.infer<T> };
+    ])) as unknown as {
+      parsed?: z.infer<T>;
+      raw?: {
+        usage_metadata?: {
+          input_tokens?: number;
+          output_tokens?: number;
+          total_tokens?: number;
+        };
+      };
+    };
+
+    const parsed = result?.parsed;
+    const raw = result?.raw;
+
+    const usage = {
+      inputTokens: raw?.usage_metadata?.input_tokens || 0,
+      outputTokens: raw?.usage_metadata?.output_tokens || 0,
+      totalTokens: raw?.usage_metadata?.total_tokens || 0,
+      modelName: this.modelNameUsed,
+      providerInstanceName: this.providerInstanceName || "Default",
+      maxContext: this.maxContextUsed !== undefined ? this.maxContextUsed : 32768,
+    };
+
+    this.lastCalls.push({
+      systemPrompt: request.systemPrompt,
+      userContext: request.userContext,
+      usage,
+    });
+
+    return { success: true, data: parsed, usage };
   }
 }

packages/llm/tests/mock.test.ts

@@ -1,6 +1,6 @@
 import { describe, test, expect } from "vitest";
 import { z } from "zod";
-import { MockLLMProvider } from "@omnia/llm";
+import { MockLLMProvider, MockEmbeddingProvider } from "@omnia/llm";
 
 describe("MockLLMProvider Unit Tests (Tier 1)", () => {
   test("returns parsed matching data for valid mock response", async () => {
@@ -61,3 +61,21 @@ describe("MockLLMProvider Unit Tests (Tier 1)", () => {
     expect(response.data).toBeUndefined();
   });
 });
+
+describe("MockEmbeddingProvider Unit Tests (Tier 1)", () => {
+  test("generates deterministic 768-dimensional vectors", async () => {
+    const provider = new MockEmbeddingProvider("mock-embeddings");
+    const text = "Hello world";
+    const vec1 = await provider.embed(text);
+    const vec2 = await provider.embed(text);
+
+    expect(vec1.length).toBe(768);
+    expect(vec2.length).toBe(768);
+    expect(vec1).toEqual(vec2); // Deterministic
+    
+    // Ensure values are numbers between -1.0 and 1.0 (since they are generated with Math.sin)
+    expect(typeof vec1[0]).toBe("number");
+    expect(vec1[0]).toBeGreaterThanOrEqual(-1.0);
+    expect(vec1[0]).toBeLessThanOrEqual(1.0);
+  });
+});

packages/llm/tests/openrouter.test.ts

@@ -14,10 +14,19 @@ vi.mock("@langchain/openrouter", () => {
       withStructuredOutput = vi.fn().mockImplementation(() => {
         return {
           invoke: vi.fn().mockImplementation(async () => {
-            // Return a mock output that matches a sample schema
+            // Return a mock output that matches the includeRaw: true structure
             return {
-              name: "mocked response",
-              success: true,
+              parsed: {
+                name: "mocked response",
+                success: true,
+              },
+              raw: {
+                usage_metadata: {
+                  input_tokens: 10,
+                  output_tokens: 5,
+                  total_tokens: 15,
+                },
+              },
             };
           }),
         };
@@ -59,7 +68,7 @@ describe("OpenRouterProvider Unit Tests (Tier 1)", () => {
     }
   });
 
-  test("generateStructuredResponse invokes the model with structured output", async () => {
+  test("generateStructuredResponse invokes the model with structured output, records usage and updates lastCalls", async () => {
     const provider = new OpenRouterProvider("dummy-key");
     const TestSchema = z.object({
       name: z.string(),
@@ -77,5 +86,28 @@ describe("OpenRouterProvider Unit Tests (Tier 1)", () => {
       name: "mocked response",
       success: true,
     });
+
+    expect(response.usage).toEqual({
+      inputTokens: 10,
+      outputTokens: 5,
+      totalTokens: 15,
+      modelName: "google/gemini-2.5-flash",
+      providerInstanceName: "Default",
+      maxContext: 32768,
+    });
+
+    expect(provider.lastCalls.length).toBe(1);
+    expect(provider.lastCalls[0]).toEqual({
+      systemPrompt: "system prompt",
+      userContext: "user context",
+      usage: {
+        inputTokens: 10,
+        outputTokens: 5,
+        totalTokens: 15,
+        modelName: "google/gemini-2.5-flash",
+        providerInstanceName: "Default",
+        maxContext: 32768,
+      },
+    });
   });
 });

packages/llm/tests/provider-manager.test.ts

@@ -0,0 +1,95 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import fs from "fs";
+import path from "path";
+import { ProviderManager, setDbPathOverride, resetHasBootstrapped } from "../src/index.js";
+
+describe("ProviderManager Bootstrapping & CRUD Unit Tests", () => {
+  let tempDbPath: string;
+  let originalGoogle: string | undefined;
+  let originalOpenRouter: string | undefined;
+
+  beforeEach(() => {
+    originalGoogle = process.env.GOOGLE_API_KEY;
+    originalOpenRouter = process.env.OPENROUTER_API_KEY;
+    delete process.env.GOOGLE_API_KEY;
+    delete process.env.OPENROUTER_API_KEY;
+
+    resetHasBootstrapped();
+
+    // Generate a unique temp database path for this test run
+    tempDbPath = path.resolve(process.cwd(), `test-settings-${Date.now()}-${Math.random().toString(36).substring(2)}.db`);
+    setDbPathOverride(tempDbPath);
+  });
+
+  afterEach(() => {
+    setDbPathOverride(null);
+    if (fs.existsSync(tempDbPath)) {
+      try {
+        fs.unlinkSync(tempDbPath);
+      } catch {
+        // ignore
+      }
+    }
+    if (originalGoogle !== undefined) {
+      process.env.GOOGLE_API_KEY = originalGoogle;
+    } else {
+      delete process.env.GOOGLE_API_KEY;
+    }
+    if (originalOpenRouter !== undefined) {
+      process.env.OPENROUTER_API_KEY = originalOpenRouter;
+    } else {
+      delete process.env.OPENROUTER_API_KEY;
+    }
+  });
+
+  test("auto-bootstraps Gemini and OpenRouter when database is empty and environment variables are present", () => {
+    process.env.GOOGLE_API_KEY = "mock-google-key-123";
+    process.env.OPENROUTER_API_KEY = "mock-openrouter-key-456";
+
+    const list = ProviderManager.list();
+    expect(list.length).toBe(3);
+
+    const gemini = list.find((p) => p.providerName === "google-genai");
+    expect(gemini).toBeDefined();
+    expect(gemini?.name).toBe("Gemini (Env)");
+    expect(gemini?.apiKey).toBe("mock-google-key-123");
+    expect(gemini?.modelName).toBe("gemini-2.5-flash");
+    expect(gemini?.isActive).toBe(true); // first inserted is active
+
+    const openrouter = list.find((p) => p.providerName === "openrouter");
+    expect(openrouter).toBeDefined();
+    expect(openrouter?.name).toBe("OpenRouter (Env)");
+    expect(openrouter?.apiKey).toBe("mock-openrouter-key-456");
+    expect(openrouter?.modelName).toBe("google/gemini-2.5-flash");
+    expect(openrouter?.isActive).toBe(false); // second inserted is inactive
+  });
+
+  test("treats bootstrapped instances as normal provider instances (editable and deletable)", () => {
+    process.env.GOOGLE_API_KEY = "mock-google-key-123";
+
+    // Trigger bootstrap
+    const list = ProviderManager.list();
+    expect(list.length).toBe(2);
+    const bootstrapped = list.find((p) => p.name === "Gemini (Env)");
+    expect(bootstrapped).toBeDefined();
+    if (!bootstrapped) return;
+    expect(bootstrapped.isActive).toBe(true);
+
+    // Edit name and key
+    ProviderManager.update(bootstrapped.id, "My Gemini Key", "google-genai", "new-secret-key", "gemini-2.5-pro");
+    
+    const listAfterUpdate = ProviderManager.list();
+    expect(listAfterUpdate.length).toBe(2);
+    const updated = listAfterUpdate.find((p) => p.id === bootstrapped.id);
+    expect(updated).toBeDefined();
+    if (!updated) return;
+    expect(updated.name).toBe("My Gemini Key");
+    expect(updated.apiKey).toBe("new-secret-key");
+    expect(updated.modelName).toBe("gemini-2.5-pro");
+
+    // Delete instance
+    ProviderManager.delete(bootstrapped.id);
+    const listAfterDelete = ProviderManager.list();
+    expect(listAfterDelete.length).toBe(1);
+  });
+});

packages/memory/package.json

@@ -9,6 +9,7 @@
   "dependencies": {
     "@omnia/core": "workspace:*",
     "@omnia/intent": "workspace:*",
+    "@omnia/llm": "workspace:*",
     "zod": "^4.4.3"
   }
 }

packages/memory/src/buffer.ts

@@ -1,5 +1,5 @@
 import Database from "better-sqlite3";
-import { Entity } from "@omnia/core";
+import { Entity, resolveAlias } from "@omnia/core";
 import { Intent } from "@omnia/intent";
 
 export interface BufferEntry {
@@ -14,34 +14,37 @@ export interface BufferEntry {
     isValid: boolean;
     reason: string;
   };
+  pinned?: boolean;
 }
 
-export function resolveAlias(viewer: Entity, targetId: string): string {
-  if (targetId === viewer.id) return "you";
-  return viewer.aliases.get(targetId) ?? "an unfamiliar figure";
-}
+export { resolveAlias } from "@omnia/core";
 
 export function serializeSubjectiveBufferEntry(
   entry: BufferEntry,
   viewer: Entity,
 ): string {
-  const actorAlias = resolveAlias(viewer, entry.intent.actorId);
+  const isSelf = viewer.id === entry.intent.actorId;
 
-  const targetAliases = entry.intent.targetIds.map((tid) =>
-    resolveAlias(viewer, tid),
-  );
-
-  let details: string;
-  if (entry.intent.type === "dialogue") {
-    details = `spoke to ${targetAliases.join(", ") || "someone"}: "${entry.intent.description}"`;
-  } else {
-    details = `${entry.intent.description}`;
-    if (entry.outcome) {
+  if (isSelf) {
+    let details = (entry.intent.selfDescription || entry.intent.description || entry.intent.originalText).trim();
+    if (details.length > 0) {
+      details = details.charAt(0).toUpperCase() + details.slice(1);
+    }
+    if (entry.intent.type === "action" && entry.outcome) {
       details += ` (Outcome: ${entry.outcome.isValid ? "Succeeded" : `Failed - ${entry.outcome.reason}`})`;
     }
+    return details;
   }
 
-  return `${actorAlias} ${details}`;
+  const actorAlias = resolveAlias(viewer, entry.intent.actorId);
+  const subjectStr = actorAlias.charAt(0).toUpperCase() + actorAlias.slice(1);
+
+  let details = (entry.intent.description || entry.intent.originalText).trim();
+  if (entry.intent.type === "action" && entry.outcome) {
+    details += ` (Outcome: ${entry.outcome.isValid ? "Succeeded" : `Failed - ${entry.outcome.reason}`})`;
+  }
+
+  return `${subjectStr} ${details}`;
 }
 
 export class BufferRepository {
@@ -60,23 +63,31 @@ export class BufferRepository {
         location_id TEXT,
         intent_json TEXT NOT NULL,
         outcome_json TEXT,
+        pinned INTEGER DEFAULT 0,
         FOREIGN KEY (owner_id) REFERENCES objects(id) ON DELETE CASCADE
       );
     `);
+
+    try {
+      this.db.exec(`ALTER TABLE buffer_entries ADD COLUMN pinned INTEGER DEFAULT 0;`);
+    } catch {
+      // ignore
+    }
   }
 
   save(entry: BufferEntry): void {
     this.db
       .prepare(
         `
-      INSERT INTO buffer_entries (id, owner_id, timestamp, location_id, intent_json, outcome_json)
-      VALUES (?, ?, ?, ?, ?, ?)
+      INSERT INTO buffer_entries (id, owner_id, timestamp, location_id, intent_json, outcome_json, pinned)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT(id) DO UPDATE SET
         owner_id = excluded.owner_id,
         timestamp = excluded.timestamp,
         location_id = excluded.location_id,
         intent_json = excluded.intent_json,
-        outcome_json = excluded.outcome_json
+        outcome_json = excluded.outcome_json,
+        pinned = excluded.pinned
     `,
       )
       .run(
@@ -86,6 +97,7 @@ export class BufferRepository {
         entry.locationId,
         JSON.stringify(entry.intent),
         entry.outcome ? JSON.stringify(entry.outcome) : null,
+        entry.pinned ? 1 : 0,
       );
   }
 
@@ -93,7 +105,7 @@ export class BufferRepository {
     const row = this.db
       .prepare(
         `
-      SELECT id, owner_id, timestamp, location_id, intent_json, outcome_json
+      SELECT id, owner_id, timestamp, location_id, intent_json, outcome_json, pinned
       FROM buffer_entries WHERE id = ?
     `,
       )
@@ -105,6 +117,7 @@ export class BufferRepository {
           location_id: string | null;
           intent_json: string;
           outcome_json: string | null;
+          pinned?: number;
         }
       | undefined;
 
@@ -117,6 +130,7 @@ export class BufferRepository {
       locationId: row.location_id,
       intent: JSON.parse(row.intent_json),
       outcome: row.outcome_json ? JSON.parse(row.outcome_json) : undefined,
+      pinned: row.pinned === 1,
     };
   }
 
@@ -124,7 +138,7 @@ export class BufferRepository {
     const rows = this.db
       .prepare(
         `
-      SELECT id, owner_id, timestamp, location_id, intent_json, outcome_json
+      SELECT id, owner_id, timestamp, location_id, intent_json, outcome_json, pinned
       FROM buffer_entries WHERE owner_id = ?
       ORDER BY timestamp ASC
     `,
@@ -136,6 +150,7 @@ export class BufferRepository {
       location_id: string | null;
       intent_json: string;
       outcome_json: string | null;
+      pinned?: number;
     }[];
 
     return rows.map((row) => ({
@@ -145,6 +160,7 @@ export class BufferRepository {
       locationId: row.location_id,
       intent: JSON.parse(row.intent_json),
       outcome: row.outcome_json ? JSON.parse(row.outcome_json) : undefined,
+      pinned: row.pinned === 1,
     }));
   }
 

packages/memory/src/handoff.ts

@@ -0,0 +1,300 @@
+import { z } from "zod";
+import { Entity, naturalizeTime } from "@omnia/core";
+import { BufferEntry, serializeSubjectiveBufferEntry, BufferRepository } from "./buffer.js";
+import { LedgerEntry, LedgerRepository } from "./ledger.js";
+import { ILLMProvider, IEmbeddingProvider } from "@omnia/llm";
+
+export const HandoffChunkSchema = z.object({
+  sourceEntryIds: z.array(z.string()), // buffer rows this chunk consumes
+  content: z.string(), // third-person summary -> LedgerEntry.content
+  quotes: z.array(z.string()), // verbatim, high-salience lines only
+  importance: z.number().int().min(1).max(10),
+  involvedEntityIds: z.array(z.string()),
+  retainInBuffer: z.boolean(), // "pin"
+});
+
+export const HandoffResultSchema = z.object({
+  chunks: z.array(HandoffChunkSchema),
+});
+
+export type HandoffResult = z.infer<typeof HandoffResultSchema>;
+export type HandoffTrigger = "none" | "voluntary" | "involuntary";
+
+/**
+ * Serializes the hypothetical memory section for size checking.
+ */
+export function getMemorySectionLength(
+  entity: Entity,
+  entries: BufferEntry[],
+  now: Date,
+): number {
+  if (entries.length === 0) {
+    return `=== RECENT EVENTS ===\n(No recent events recorded.)`.length;
+  }
+
+  const groupedLines: string[] = [];
+  let currentGroup: string | null = null;
+
+  for (const entry of entries) {
+    const serialized = serializeSubjectiveBufferEntry(entry, entity);
+    const when = naturalizeTime(now, new Date(entry.timestamp));
+
+    if (when !== currentGroup) {
+      currentGroup = when;
+      const header = when.charAt(0).toUpperCase() + when.slice(1);
+      groupedLines.push(header);
+    }
+
+    groupedLines.push(`  - ${serialized}`);
+  }
+
+  return `=== RECENT EVENTS ===\n${groupedLines.join("\n")}`.length;
+}
+
+function checkSceneExit(entity: Entity, bufferEntries: BufferEntry[]): boolean {
+  if (bufferEntries.length === 0) return false;
+
+  // Find the location of the most recent buffer entries
+  const lastEntry = bufferEntries[bufferEntries.length - 1];
+  if (lastEntry.locationId && entity.locationId && lastEntry.locationId !== entity.locationId) {
+    return true;
+  }
+
+  // Also check if there are entries from different locations in the buffer
+  const locations = new Set(bufferEntries.map(e => e.locationId).filter(loc => loc !== null));
+  if (locations.size > 1) {
+    return true;
+  }
+
+  return false;
+}
+
+function checkIdleDecay(bufferEntries: BufferEntry[]): boolean {
+  const N = 5; // N consecutive idle turns
+  if (bufferEntries.length < N) return false;
+
+  // Check the last N entries
+  const lastN = bufferEntries.slice(-N);
+  return lastN.every(e => e.intent.type === "monologue");
+}
+
+function checkAttributeTrigger(entity: Entity): boolean {
+  const consciousness = entity.attributes.get("consciousness");
+  if (consciousness && consciousness.getValue().toLowerCase() === "unconscious") {
+    return true;
+  }
+
+  const status = entity.attributes.get("status");
+  if (status && ["unconscious", "asleep", "dead", "inactive"].includes(status.getValue().toLowerCase())) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Checks deterministically whether handoff should run for the given entity.
+ */
+export function checkHandoffTrigger(
+  entity: Entity,
+  bufferEntries: BufferEntry[],
+  now: Date,
+  maxContext: number = 32768,
+): HandoffTrigger {
+  if (bufferEntries.length === 0) {
+    return "none";
+  }
+
+  // Involuntary triggers first (hard)
+  if (maxContext > 0) {
+    const memoryLength = getMemorySectionLength(entity, bufferEntries, now);
+    const charCeiling = maxContext * 4 * 0.60;
+    if (memoryLength > charCeiling) {
+      return "involuntary";
+    }
+  }
+
+  // Event velocity
+  if (bufferEntries.length > 20) {
+    return "involuntary";
+  }
+
+  // Voluntary triggers (soft)
+  if (checkSceneExit(entity, bufferEntries)) {
+    return "voluntary";
+  }
+
+  if (checkIdleDecay(bufferEntries)) {
+    return "voluntary";
+  }
+
+  if (checkAttributeTrigger(entity)) {
+    return "voluntary";
+  }
+
+  return "none";
+}
+
+/**
+ * Splits the buffer into candidate pool (older) and watermark tail (untouched).
+ */
+export function splitBufferForHandoff(
+  bufferEntries: BufferEntry[],
+  now: Date,
+  K: number = 8,
+): { candidates: BufferEntry[]; watermark: BufferEntry[] } {
+  const sorted = [...bufferEntries].sort(
+    (a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime(),
+  );
+
+  const freshBuckets = new Set([
+    "just now",
+    "moments ago",
+    "a few minutes ago",
+    "several minutes ago",
+  ]);
+
+  let watermarkStartIndex = sorted.length;
+
+  // 1. Mark last K entries as watermark
+  if (sorted.length > K) {
+    watermarkStartIndex = sorted.length - K;
+  } else {
+    watermarkStartIndex = 0;
+  }
+
+  // 2. Expand watermark to include any fresh entries before it
+  for (let i = watermarkStartIndex - 1; i >= 0; i--) {
+    const bucket = naturalizeTime(now, new Date(sorted[i].timestamp));
+    if (freshBuckets.has(bucket)) {
+      watermarkStartIndex = i;
+    } else {
+      break;
+    }
+  }
+
+  return {
+    candidates: sorted.slice(0, watermarkStartIndex),
+    watermark: sorted.slice(watermarkStartIndex),
+  };
+}
+
+/**
+ * HandoffEngine processes memory handoffs using LLM summarization and DB transactions.
+ */
+export class HandoffEngine {
+  constructor(
+    private llmProvider: ILLMProvider,
+    private embedProvider: IEmbeddingProvider,
+    private bufferRepo: BufferRepository,
+    private ledgerRepo: LedgerRepository,
+  ) {}
+
+  async runHandoff(
+    entity: Entity,
+    bufferEntries: BufferEntry[],
+    now: Date,
+  ): Promise<boolean> {
+    const { candidates } = splitBufferForHandoff(bufferEntries, now);
+
+    if (candidates.length === 0) {
+      return false;
+    }
+
+    const candidatesList = candidates.map((entry) => {
+      const serialized = serializeSubjectiveBufferEntry(entry, entity);
+      return `ID: ${entry.id} | Timestamp: ${entry.timestamp} | Location: ${entry.locationId || "None"}\nContent: ${serialized}`;
+    }).join("\n---\n");
+
+    const systemPrompt = `
+You are the memory Handoff Engine. Your task is to process a list of recent working memory buffer entries for an entity and select which memories to promote to the long-term Ledger, and which to forget or summarize.
+
+Instructions:
+1. **Cluster** related consecutive buffer entries into high-level narrative beats or events (e.g. a full back-and-forth conversation or a single physical action and its outcome). Combine them into a single summary chunk.
+2. **Write in the third-person** for the "content" of each chunk (e.g. "John asked Mary for the key, and Mary reluctantly handed it over").
+3. **verbatim Quotes**: Extract verbatim, high-salience quotes from dialogue if relevant. Do not modify or invent quotes.
+4. **Determine Importance**: Assign an importance score from 1 (trivial, e.g. waking up) to 10 (life-altering, e.g. witnessing a crime).
+5. **Involved Entities**: Identify all entity IDs involved in the memories in this chunk.
+6. **Retain in Buffer (Pinning)**: If a beat represents an unresolved high-stakes situation (e.g. a standing threat, an unanswered accusation, an ongoing chase or conflict), set "retainInBuffer" to true so it remains in the working memory buffer for immediate context. Otherwise, set it to false so it is safely pruned from the buffer.
+7. **Exclude stage business**: Glances, sighs, ambient noticing, and irrelevant sensory details should be ignored and not included in any promoted chunk. They will be forgotten.
+8. **Forget by omission**: Any buffer entry ID that you do not include in any chunk's "sourceEntryIds" will be permanently deleted and forgotten.
+`.trim();
+
+    const userContext = `
+Subject Entity ID: ${entity.id}
+Current Time: ${now.toISOString()}
+
+Working Memory Candidates for Handoff:
+${candidatesList}
+`.trim();
+
+    const response = await this.llmProvider.generateStructuredResponse({
+      systemPrompt,
+      userContext,
+      schema: HandoffResultSchema,
+    });
+
+    if (!response.success || !response.data) {
+      return false;
+    }
+
+    const result = response.data;
+    const db = (this.bufferRepo as any).db;
+
+    const ledgerEntries: LedgerEntry[] = [];
+    for (const chunk of result.chunks) {
+      let embedding: number[] = [];
+      try {
+        embedding = await this.embedProvider.embed(chunk.content);
+      } catch (err) {
+        console.error("Failed to generate embedding for handoff chunk:", err);
+        return false;
+      }
+
+      ledgerEntries.push({
+        id: "ledger-" + Math.random().toString(36).substr(2, 9) + "-" + Date.now(),
+        ownerId: entity.id,
+        timestamp: now.toISOString(),
+        locationId: entity.locationId,
+        involvedEntityIds: chunk.involvedEntityIds,
+        content: chunk.content,
+        quotes: chunk.quotes,
+        importance: chunk.importance,
+        embedding,
+      });
+    }
+
+    try {
+      db.transaction(() => {
+        // Save promoted ledger entries
+        for (const entry of ledgerEntries) {
+          this.ledgerRepo.save(entry);
+        }
+
+        // Keep track of pinned source IDs
+        const pinnedSourceIds = new Set<string>();
+        for (const chunk of result.chunks) {
+          if (chunk.retainInBuffer) {
+            for (const id of chunk.sourceEntryIds) {
+              pinnedSourceIds.add(id);
+            }
+          }
+        }
+
+        // Delete or pin entries
+        for (const candidate of candidates) {
+          if (pinnedSourceIds.has(candidate.id)) {
+            const updated = { ...candidate, pinned: true };
+            this.bufferRepo.save(updated);
+          } else {
+            this.bufferRepo.delete(candidate.id);
+          }
+        }
+      })();
+      return true;
+    } catch (err) {
+      console.error("Transaction failed during handoff execution:", err);
+      return false;
+    }
+  }
+}

packages/memory/src/index.ts

@@ -1 +1,3 @@
 export * from "./buffer.js";
+export * from "./ledger.js";
+export * from "./handoff.js";

packages/memory/src/ledger.ts

@@ -0,0 +1,379 @@
+import Database from "better-sqlite3";
+
+export interface LedgerEntry {
+  id: string;
+  ownerId: string;
+  timestamp: string;
+  locationId: string | null;
+  involvedEntityIds: string[];
+
+  content: string;
+  quotes: string[];
+  importance: number;
+  embedding: number[];
+}
+
+export class LedgerRepository {
+  constructor(private db: Database.Database) {
+    // Enable foreign keys for cascading deletes
+    this.db.exec("PRAGMA foreign_keys = ON;");
+    this.initializeSchema();
+  }
+
+  private initializeSchema(): void {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS ledger_entries (
+        id TEXT PRIMARY KEY,
+        owner_id TEXT NOT NULL,
+        timestamp TEXT NOT NULL,
+        location_id TEXT,
+        content TEXT NOT NULL,
+        quotes_json TEXT,
+        importance INTEGER NOT NULL,
+        embedding BLOB,
+        FOREIGN KEY (owner_id) REFERENCES objects(id) ON DELETE CASCADE
+      );
+
+      CREATE TABLE IF NOT EXISTS ledger_involved_entities (
+        entry_id TEXT NOT NULL,
+        entity_id TEXT NOT NULL,
+        PRIMARY KEY (entry_id, entity_id),
+        FOREIGN KEY (entry_id) REFERENCES ledger_entries(id) ON DELETE CASCADE
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_ledger_owner ON ledger_entries(owner_id);
+      CREATE INDEX IF NOT EXISTS idx_ledger_location ON ledger_entries(location_id);
+      CREATE INDEX IF NOT EXISTS idx_ledger_importance ON ledger_entries(importance);
+      CREATE INDEX IF NOT EXISTS idx_ledger_involved_entity ON ledger_involved_entities(entity_id);
+    `);
+  }
+
+  save(entry: LedgerEntry): void {
+    const insertEntry = this.db.prepare(`
+      INSERT INTO ledger_entries (id, owner_id, timestamp, location_id, content, quotes_json, importance, embedding)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        owner_id = excluded.owner_id,
+        timestamp = excluded.timestamp,
+        location_id = excluded.location_id,
+        content = excluded.content,
+        quotes_json = excluded.quotes_json,
+        importance = excluded.importance,
+        embedding = excluded.embedding
+    `);
+
+    const insertEntity = this.db.prepare(`
+      INSERT OR IGNORE INTO ledger_involved_entities (entry_id, entity_id)
+      VALUES (?, ?)
+    `);
+
+    const deleteEntities = this.db.prepare(`
+      DELETE FROM ledger_involved_entities WHERE entry_id = ?
+    `);
+
+    this.db.transaction(() => {
+      insertEntry.run(
+        entry.id,
+        entry.ownerId,
+        entry.timestamp,
+        entry.locationId,
+        entry.content,
+        JSON.stringify(entry.quotes),
+        entry.importance,
+        entry.embedding.length > 0
+          ? Buffer.from(new Float32Array(entry.embedding).buffer)
+          : null
+      );
+
+      deleteEntities.run(entry.id);
+      for (const entityId of entry.involvedEntityIds) {
+        insertEntity.run(entry.id, entityId);
+      }
+    })();
+  }
+
+  private mapRowToEntry(row: any, involvedEntityIds: string[]): LedgerEntry {
+    let embedding: number[] = [];
+    if (row.embedding) {
+      const buffer = row.embedding as Buffer;
+      const floatArray = new Float32Array(
+        buffer.buffer,
+        buffer.byteOffset,
+        buffer.byteLength / Float32Array.BYTES_PER_ELEMENT
+      );
+      embedding = Array.from(floatArray);
+    }
+
+    return {
+      id: row.id,
+      ownerId: row.owner_id,
+      timestamp: row.timestamp,
+      locationId: row.location_id,
+      involvedEntityIds,
+      content: row.content,
+      quotes: JSON.parse(row.quotes_json || "[]"),
+      importance: row.importance,
+      embedding: embedding,
+    };
+  }
+
+  load(id: string): LedgerEntry | null {
+    const row = this.db
+      .prepare(
+        `
+      SELECT id, owner_id, timestamp, location_id, content, quotes_json, importance, embedding
+      FROM ledger_entries
+      WHERE id = ?
+    `
+      )
+      .get(id) as any;
+
+    if (!row) return null;
+
+    const entitiesRows = this.db
+      .prepare(
+        `
+      SELECT entity_id FROM ledger_involved_entities WHERE entry_id = ?
+    `
+      )
+      .all(id) as { entity_id: string }[];
+
+    return this.mapRowToEntry(row, entitiesRows.map((er) => er.entity_id));
+  }
+
+  /**
+   * Retrieves relevant ledger entries using Phase 1: Deterministic Heuristic Filtering
+   * Filters by:
+   * 1. locationId matches current location
+   * 2. involvedEntityIds overlaps with current involved entities
+   * 3. importance >= 8 (high salience)
+   */
+  getRelevant(
+    ownerId: string,
+    currentLocationId: string | null,
+    currentInvolvedEntityIds: string[],
+    limit: number = 20
+  ): LedgerEntry[] {
+    let query = `
+      SELECT DISTINCT le.id, le.owner_id, le.timestamp, le.location_id, le.content, le.quotes_json, le.importance, le.embedding
+      FROM ledger_entries le
+      LEFT JOIN ledger_involved_entities lie ON le.id = lie.entry_id
+      WHERE le.owner_id = ? 
+        AND (
+          le.importance >= 8
+    `;
+
+    const params: any[] = [ownerId];
+
+    if (currentLocationId) {
+      query += ` OR le.location_id = ?`;
+      params.push(currentLocationId);
+    }
+
+    if (currentInvolvedEntityIds.length > 0) {
+      const placeholders = currentInvolvedEntityIds.map(() => "?").join(",");
+      query += ` OR lie.entity_id IN (${placeholders})`;
+      params.push(...currentInvolvedEntityIds);
+    }
+
+    query += `
+        )
+      ORDER BY le.timestamp DESC
+      LIMIT ?
+    `;
+    params.push(limit);
+
+    const rows = this.db.prepare(query).all(...params) as any[];
+
+    if (rows.length === 0) return [];
+
+    const entryIds = rows.map((r) => r.id);
+    const placeholders = entryIds.map(() => "?").join(",");
+    const entitiesRows = this.db
+      .prepare(
+        `
+      SELECT entry_id, entity_id FROM ledger_involved_entities
+      WHERE entry_id IN (${placeholders})
+    `
+      )
+      .all(...entryIds) as { entry_id: string; entity_id: string }[];
+
+    const entitiesMap = new Map<string, string[]>();
+    for (const er of entitiesRows) {
+      if (!entitiesMap.has(er.entry_id)) {
+        entitiesMap.set(er.entry_id, []);
+      }
+      entitiesMap.get(er.entry_id)!.push(er.entity_id);
+    }
+
+    return rows.map((row) => this.mapRowToEntry(row, entitiesMap.get(row.id) || []));
+  }
+
+  private fetchRawNeighbors(ownerId: string, timestamp: string): LedgerEntry[] {
+    const neighbors: LedgerEntry[] = [];
+
+    // Preceding entry
+    const preceding = this.db
+      .prepare(
+        `
+      SELECT id, owner_id, timestamp, location_id, content, quotes_json, importance, embedding
+      FROM ledger_entries
+      WHERE owner_id = ? AND timestamp < ?
+      ORDER BY timestamp DESC
+      LIMIT 1
+    `
+      )
+      .get(ownerId, timestamp) as any;
+
+    if (preceding) {
+      neighbors.push(this.mapRowToEntry(preceding, []));
+    }
+
+    // Succeeding entry
+    const succeeding = this.db
+      .prepare(
+        `
+      SELECT id, owner_id, timestamp, location_id, content, quotes_json, importance, embedding
+      FROM ledger_entries
+      WHERE owner_id = ? AND timestamp > ?
+      ORDER BY timestamp ASC
+      LIMIT 1
+    `
+      )
+      .get(ownerId, timestamp) as any;
+
+    if (succeeding) {
+      neighbors.push(this.mapRowToEntry(succeeding, []));
+    }
+
+    return neighbors;
+  }
+
+  /**
+   * Phase 1 + Phase 2 Retrieval Pipeline
+   * 1. Fetches candidates via Phase 1 heuristic filtering.
+   * 2. Ranks them using: Score = Recency + Importance + Semantic Match.
+   * 3. Selects the top `limit` memories.
+   * 4. Optionally pulls in the immediate chronological neighbors (associative chain).
+   * 5. Returns all gathered entries sorted chronologically (timestamp ASC).
+   */
+  retrieve(
+    ownerId: string,
+    currentLocationId: string | null,
+    currentInvolvedEntityIds: string[],
+    queryEmbedding?: number[],
+    now: Date = new Date(),
+    limit: number = 5,
+    options?: {
+      includeAssociativeNeighbors?: boolean;
+      recencyWeight?: number;
+      importanceWeight?: number;
+      relevanceWeight?: number;
+      decayRate?: number;
+    }
+  ): LedgerEntry[] {
+    const includeAssociativeNeighbors = options?.includeAssociativeNeighbors ?? false;
+    const recencyWeight = options?.recencyWeight ?? 1.0;
+    const importanceWeight = options?.importanceWeight ?? 1.0;
+    const relevanceWeight = options?.relevanceWeight ?? 1.0;
+    const decayRate = options?.decayRate ?? 0.99;
+
+    // Fetch candidate pool (limit 100 to provide enough options for Phase 2 ranking)
+    const candidates = this.getRelevant(ownerId, currentLocationId, currentInvolvedEntityIds, 100);
+    if (candidates.length === 0) return [];
+
+    // Score candidates
+    const scored = candidates.map((entry) => {
+      // Recency calculation with exponential decay
+      const deltaMs = now.getTime() - new Date(entry.timestamp).getTime();
+      const hoursElapsed = Math.max(0, deltaMs / (3600 * 1000));
+      const recency = Math.pow(decayRate, hoursElapsed);
+
+      // Importance score normalized (0.0 to 1.0)
+      const importanceNorm = entry.importance / 10.0;
+
+      // Semantic relevance
+      let relevance = 0;
+      if (queryEmbedding && entry.embedding && entry.embedding.length > 0) {
+        relevance = cosineSimilarity(queryEmbedding, entry.embedding);
+      }
+
+      const score =
+        recencyWeight * recency +
+        importanceWeight * importanceNorm +
+        relevanceWeight * relevance;
+
+      return { entry, score };
+    });
+
+    // Rank and take top memories
+    scored.sort((a, b) => b.score - a.score);
+    const selected = scored.slice(0, limit).map((s) => s.entry);
+
+    let finalEntries = [...selected];
+
+    // Optionally retrieve associative neighbors
+    if (includeAssociativeNeighbors && selected.length > 0) {
+      const neighborMap = new Map<string, LedgerEntry>();
+
+      for (const entry of selected) {
+        const rawNeighbors = this.fetchRawNeighbors(ownerId, entry.timestamp);
+        for (const rn of rawNeighbors) {
+          if (!finalEntries.some((fe) => fe.id === rn.id) && !neighborMap.has(rn.id)) {
+            neighborMap.set(rn.id, rn);
+          }
+        }
+      }
+
+      const neighborsToPopulate = Array.from(neighborMap.values());
+      if (neighborsToPopulate.length > 0) {
+        const neighborIds = neighborsToPopulate.map((n) => n.id);
+        const placeholders = neighborIds.map(() => "?").join(",");
+        const entitiesRows = this.db
+          .prepare(
+            `
+          SELECT entry_id, entity_id FROM ledger_involved_entities
+          WHERE entry_id IN (${placeholders})
+        `
+          )
+          .all(...neighborIds) as { entry_id: string; entity_id: string }[];
+
+        const entitiesMap = new Map<string, string[]>();
+        for (const er of entitiesRows) {
+          if (!entitiesMap.has(er.entry_id)) {
+            entitiesMap.set(er.entry_id, []);
+          }
+          entitiesMap.get(er.entry_id)!.push(er.entity_id);
+        }
+
+        for (const n of neighborsToPopulate) {
+          n.involvedEntityIds = entitiesMap.get(n.id) || [];
+          finalEntries.push(n);
+        }
+      }
+    }
+
+    // Sort chronologically ASC for the final prompt output
+    finalEntries.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+
+    return finalEntries;
+  }
+
+  delete(id: string): void {
+    this.db.prepare(`DELETE FROM ledger_entries WHERE id = ?`).run(id);
+  }
+}
+
+function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length !== b.length || a.length === 0) return 0;
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  if (normA === 0 || normB === 0) return 0;
+  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}

packages/memory/tests/handoff.test.ts

@@ -0,0 +1,167 @@
+import { describe, test, expect } from "vitest";
+import Database from "better-sqlite3";
+import { Entity } from "@omnia/core";
+import { MockLLMProvider, MockEmbeddingProvider } from "@omnia/llm";
+import {
+  BufferEntry,
+  BufferRepository,
+  LedgerRepository,
+  checkHandoffTrigger,
+  splitBufferForHandoff,
+  HandoffEngine,
+} from "@omnia/memory";
+
+describe("Memory Handoff Tests (Tier 1)", () => {
+  const now = new Date("2026-07-07T12:00:00.000Z");
+
+  test("splitBufferForHandoff correctly splits based on watermark and fresh buckets", () => {
+    const entries: BufferEntry[] = [];
+
+    // Add 12 older entries (older than 30 minutes)
+    for (let i = 0; i < 12; i++) {
+      const minutesAgo = 60 - i;
+      const timestamp = new Date(now.getTime() - minutesAgo * 60 * 1000).toISOString();
+      entries.push({
+        id: `entry-old-${i}`,
+        ownerId: "alice",
+        timestamp,
+        locationId: "room-1",
+        intent: {
+          type: "dialogue",
+          originalText: `Old event ${i}`,
+          description: `does old thing ${i}`,
+          actorId: "alice",
+          targetIds: ["bob"],
+        },
+      });
+    }
+
+    // Add 4 fresh entries (moments ago / just now)
+    const freshTimes = [
+      new Date(now.getTime() - 10 * 1000).toISOString(),
+      new Date(now.getTime() - 30 * 1000).toISOString(),
+      new Date(now.getTime() - 90 * 1000).toISOString(),
+      new Date(now.getTime() - 180 * 1000).toISOString(),
+    ];
+
+    freshTimes.forEach((timestamp, idx) => {
+      entries.push({
+        id: `entry-fresh-${idx}`,
+        ownerId: "alice",
+        timestamp,
+        locationId: "room-1",
+        intent: {
+          type: "dialogue",
+          originalText: `Fresh event ${idx}`,
+          description: `does fresh thing ${idx}`,
+          actorId: "alice",
+          targetIds: ["bob"],
+        },
+      });
+    });
+
+    const { candidates, watermark } = splitBufferForHandoff(entries, now, 8);
+
+    expect(watermark.length).toBeGreaterThanOrEqual(8);
+    expect(candidates.length).toBe(8);
+    expect(candidates[0].id).toBe("entry-old-0");
+  });
+
+  test("checkHandoffTrigger detects scene change and idle decay", () => {
+    const entity = new Entity("alice");
+    entity.locationId = "room-2";
+
+    // Scenario 1: Empty buffer -> no trigger
+    expect(checkHandoffTrigger(entity, [], now)).toBe("none");
+
+    // Scenario 2: Scene exit
+    const entryAtRoom1: BufferEntry = {
+      id: "e-1",
+      ownerId: "alice",
+      timestamp: now.toISOString(),
+      locationId: "room-1",
+      intent: { type: "dialogue", originalText: "hello", description: "says hello", actorId: "alice", targetIds: [] },
+    };
+    expect(checkHandoffTrigger(entity, [entryAtRoom1], now)).toBe("voluntary");
+
+    // Scenario 3: Idle decay (5 consecutive monologues)
+    const monologues: BufferEntry[] = Array.from({ length: 5 }, (_, i) => ({
+      id: `m-${i}`,
+      ownerId: "alice",
+      timestamp: now.toISOString(),
+      locationId: "room-2",
+      intent: { type: "monologue", originalText: "think", description: "thinks", actorId: "alice", targetIds: [] },
+    }));
+    expect(checkHandoffTrigger(entity, monologues, now)).toBe("voluntary");
+  });
+
+  test("HandoffEngine promotes candidates to Ledger and prunes buffer transactionally", async () => {
+    const db = new Database(":memory:");
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS objects (
+        id TEXT PRIMARY KEY,
+        type TEXT NOT NULL,
+        name TEXT NOT NULL
+      );
+      INSERT INTO objects (id, type, name) VALUES ('alice', 'character', 'Alice');
+    `);
+
+    const bufferRepo = new BufferRepository(db);
+    const ledgerRepo = new LedgerRepository(db);
+
+    const entity = new Entity("alice");
+    entity.locationId = "room-1";
+
+    const entries: BufferEntry[] = [];
+    for (let i = 0; i < 10; i++) {
+      const timestamp = new Date(now.getTime() - (50 - i) * 60 * 1000).toISOString();
+      const entry: BufferEntry = {
+        id: `entry-${i}`,
+        ownerId: "alice",
+        timestamp,
+        locationId: "room-1",
+        intent: {
+          type: i % 2 === 0 ? "dialogue" : "action",
+          originalText: `Event ${i}`,
+          description: `does thing ${i}`,
+          actorId: "alice",
+          targetIds: ["bob"],
+        },
+      };
+      bufferRepo.save(entry);
+      entries.push(entry);
+    }
+
+    const mockHandoffResult = {
+      chunks: [
+        {
+          sourceEntryIds: ["entry-0"],
+          content: "Alice initiated dialogue and performed various tasks.",
+          quotes: ["Event 0"],
+          importance: 5,
+          involvedEntityIds: ["bob"],
+          retainInBuffer: false,
+        },
+      ],
+    };
+
+    const llmProvider = new MockLLMProvider([mockHandoffResult]);
+    const embedProvider = new MockEmbeddingProvider();
+    const engine = new HandoffEngine(llmProvider, embedProvider, bufferRepo, ledgerRepo);
+
+    const success = await engine.runHandoff(entity, entries, now);
+    expect(success).toBe(true);
+
+    const ledgerRows = db.prepare("SELECT * FROM ledger_entries WHERE owner_id = ?").all("alice") as any[];
+    expect(ledgerRows.length).toBe(1);
+    expect(ledgerRows[0].content).toBe("Alice initiated dialogue and performed various tasks.");
+    expect(JSON.parse(ledgerRows[0].quotes_json)).toEqual(["Event 0"]);
+    expect(ledgerRows[0].importance).toBe(5);
+
+    const remainingBuffer = bufferRepo.listForOwner("alice");
+    expect(remainingBuffer.length).toBe(8);
+    expect(remainingBuffer.map((b) => b.id)).not.toContain("entry-0");
+    expect(remainingBuffer.map((b) => b.id)).not.toContain("entry-1");
+    expect(remainingBuffer[0].id).toBe("entry-2");
+  });
+});

packages/memory/tests/ledger.test.ts

@@ -0,0 +1,228 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Database from "better-sqlite3";
+import { LedgerRepository, LedgerEntry } from "../src/ledger";
+
+describe("LedgerRepository", () => {
+  let db: Database.Database;
+  let repo: LedgerRepository;
+
+  beforeEach(() => {
+    db = new Database(":memory:");
+    
+    // We need to create a dummy objects table to satisfy foreign keys
+    db.exec(`
+      CREATE TABLE objects (
+        id TEXT PRIMARY KEY
+      );
+    `);
+
+    db.exec(`
+      INSERT INTO objects (id) VALUES ('alice'), ('bob'), ('charlie');
+    `);
+
+    repo = new LedgerRepository(db);
+  });
+
+  afterEach(() => {
+    db.close();
+  });
+
+  it("should save and load a ledger entry", () => {
+    const entry: LedgerEntry = {
+      id: "mem1",
+      ownerId: "alice",
+      timestamp: new Date().toISOString(),
+      locationId: "loc1",
+      involvedEntityIds: ["bob", "charlie"],
+      content: "Alice met Bob and Charlie at the market.",
+      quotes: ["Hi guys!"],
+      importance: 5,
+      embedding: [0.1, 0.2, 0.3],
+    };
+
+    repo.save(entry);
+
+    const loaded = repo.load("mem1");
+    expect(loaded).toBeDefined();
+    expect(loaded?.id).toBe("mem1");
+    expect(loaded?.ownerId).toBe("alice");
+    expect(loaded?.locationId).toBe("loc1");
+    expect(loaded?.involvedEntityIds.sort()).toEqual(["bob", "charlie"].sort());
+    expect(loaded?.content).toBe(entry.content);
+    expect(loaded?.quotes).toEqual(entry.quotes);
+    expect(loaded?.importance).toBe(5);
+    
+    // Check float precision
+    expect(loaded?.embedding[0]).toBeCloseTo(0.1);
+    expect(loaded?.embedding[1]).toBeCloseTo(0.2);
+    expect(loaded?.embedding[2]).toBeCloseTo(0.3);
+  });
+
+  it("should return null for non-existent entry", () => {
+    const loaded = repo.load("missing");
+    expect(loaded).toBeNull();
+  });
+
+  it("should retrieve relevant memories based on Phase 1 heuristics", () => {
+    repo.save({
+      id: "mem_high_salience",
+      ownerId: "alice",
+      timestamp: "2024-01-01T10:00:00.000Z",
+      locationId: "loc2",
+      involvedEntityIds: [],
+      content: "Alice found a magical sword.",
+      quotes: [],
+      importance: 9, // high salience
+      embedding: [],
+    });
+
+    repo.save({
+      id: "mem_location",
+      ownerId: "alice",
+      timestamp: "2024-01-02T10:00:00.000Z",
+      locationId: "loc1", // matches query
+      involvedEntityIds: [],
+      content: "Alice sat on a bench.",
+      quotes: [],
+      importance: 2,
+      embedding: [],
+    });
+
+    repo.save({
+      id: "mem_social",
+      ownerId: "alice",
+      timestamp: "2024-01-03T10:00:00.000Z",
+      locationId: "loc2",
+      involvedEntityIds: ["bob"], // matches query
+      content: "Alice waved at Bob.",
+      quotes: [],
+      importance: 3,
+      embedding: [],
+    });
+
+    repo.save({
+      id: "mem_irrelevant",
+      ownerId: "alice",
+      timestamp: "2024-01-04T10:00:00.000Z",
+      locationId: "loc3",
+      involvedEntityIds: ["charlie"],
+      content: "Alice sneezed.",
+      quotes: [],
+      importance: 2,
+      embedding: [],
+    });
+
+    const relevant = repo.getRelevant("alice", "loc1", ["bob"]);
+    
+    expect(relevant).toHaveLength(3);
+    const ids = relevant.map((r) => r.id);
+    expect(ids).toContain("mem_high_salience"); // due to importance >= 8
+    expect(ids).toContain("mem_location"); // due to locationId
+    expect(ids).toContain("mem_social"); // due to involvedEntityIds
+    expect(ids).not.toContain("mem_irrelevant");
+  });
+
+  it("should retrieve ranked memories with recency, importance, and semantic match", () => {
+    const now = new Date("2024-01-10T12:00:00.000Z");
+
+    repo.save({
+      id: "mem1",
+      ownerId: "alice",
+      timestamp: "2024-01-01T12:00:00.000Z",
+      locationId: "loc1",
+      involvedEntityIds: [],
+      content: "Alice fought a dragon.",
+      quotes: [],
+      importance: 10,
+      embedding: [0, 1, 0],
+    });
+
+    repo.save({
+      id: "mem2",
+      ownerId: "alice",
+      timestamp: "2024-01-10T11:00:00.000Z",
+      locationId: "loc1",
+      involvedEntityIds: [],
+      content: "Alice ate a sandwich.",
+      quotes: [],
+      importance: 2,
+      embedding: [1, 0, 0],
+    });
+
+    repo.save({
+      id: "mem3",
+      ownerId: "alice",
+      timestamp: "2024-01-10T11:50:00.000Z",
+      locationId: "loc1",
+      involvedEntityIds: [],
+      content: "Alice read a book.",
+      quotes: [],
+      importance: 5,
+      embedding: [0.707, 0.707, 0],
+    });
+
+    // Query: [1, 0, 0]
+    // mem3 score: recency (~0.998) + importance (0.5) + relevance (0.707) = ~2.205
+    // mem2 score: recency (~0.99) + importance (0.2) + relevance (1.0) = ~2.19
+    // mem1 score: recency (~0.114) + importance (1.0) + relevance (0.0) = ~1.114
+    // If limit = 2, should return mem2 and mem3, sorted chronologically (mem2 first, then mem3)
+    const results = repo.retrieve("alice", "loc1", [], [1, 0, 0], now, 2);
+    expect(results).toHaveLength(2);
+    expect(results[0].id).toBe("mem2");
+    expect(results[1].id).toBe("mem3");
+  });
+
+  it("should pull in associative neighbors when specified", () => {
+    repo.save({
+      id: "mem_preceding",
+      ownerId: "alice",
+      timestamp: "2024-01-10T10:00:00.000Z",
+      locationId: "loc_other",
+      involvedEntityIds: [],
+      content: "Alice woke up.",
+      quotes: [],
+      importance: 2,
+      embedding: [],
+    });
+
+    repo.save({
+      id: "mem_target",
+      ownerId: "alice",
+      timestamp: "2024-01-10T11:00:00.000Z",
+      locationId: "loc1",
+      involvedEntityIds: [],
+      content: "Alice arrived at tavern.",
+      quotes: [],
+      importance: 2,
+      embedding: [],
+    });
+
+    repo.save({
+      id: "mem_succeeding",
+      ownerId: "alice",
+      timestamp: "2024-01-10T12:00:00.000Z",
+      locationId: "loc_other",
+      involvedEntityIds: [],
+      content: "Alice ordered ale.",
+      quotes: [],
+      importance: 2,
+      embedding: [],
+    });
+
+    // Without neighbors: only returns mem_target
+    const withoutNeighbors = repo.retrieve("alice", "loc1", [], undefined, new Date("2024-01-10T14:00:00.000Z"), 1, {
+      includeAssociativeNeighbors: false,
+    });
+    expect(withoutNeighbors).toHaveLength(1);
+    expect(withoutNeighbors[0].id).toBe("mem_target");
+
+    // With neighbors: returns preceding, target, and succeeding sorted chronologically
+    const withNeighbors = repo.retrieve("alice", "loc1", [], undefined, new Date("2024-01-10T14:00:00.000Z"), 1, {
+      includeAssociativeNeighbors: true,
+    });
+    expect(withNeighbors).toHaveLength(3);
+    expect(withNeighbors[0].id).toBe("mem_preceding");
+    expect(withNeighbors[1].id).toBe("mem_target");
+    expect(withNeighbors[2].id).toBe("mem_succeeding");
+  });
+});

packages/memory/tests/memory.test.ts

@@ -32,14 +32,16 @@ describe("Subjective Buffer Entry Serializer Tests (Tier 1)", () => {
       intent: {
         type: "dialogue",
         originalText: '"Hello there," Bob said to Charlie.',
-        description: "Bob greets Charlie",
+        description: "says, 'Hello there' to the bartender",
+        selfDescription: "You say, 'Hello there' to the bartender.",
         actorId: "bob",
         targetIds: ["charlie"],
+        modifiers: [],
       },
     };
 
     const result = serializeSubjectiveBufferEntry(entry, viewer);
-    expect(result).toBe('the hooded figure spoke to the bartender: "Bob greets Charlie"');
+    expect(result).toBe("The hooded figure says, 'Hello there' to the bartender");
   });
 
   test("serializes action intent with outcome details", () => {
@@ -54,9 +56,11 @@ describe("Subjective Buffer Entry Serializer Tests (Tier 1)", () => {
       intent: {
         type: "action",
         originalText: "Bob tried to break the latch.",
-        description: "Bob attempts to break the lock latch",
+        description: "attempts to break the lock latch",
+        selfDescription: "You attempt to break the lock latch.",
         actorId: "bob",
         targetIds: [],
+        modifiers: [],
       },
       outcome: {
         isValid: false,
@@ -65,7 +69,7 @@ describe("Subjective Buffer Entry Serializer Tests (Tier 1)", () => {
     };
 
     const result = serializeSubjectiveBufferEntry(entry, viewer);
-    expect(result).toBe('the hooded figure Bob attempts to break the lock latch (Outcome: Failed - The lock is made of reinforced steel.)');
+    expect(result).toBe('The hooded figure attempts to break the lock latch (Outcome: Failed - The lock is made of reinforced steel.)');
   });
 
   test("serializes self-reference and unfamiliar actors", () => {
@@ -80,13 +84,15 @@ describe("Subjective Buffer Entry Serializer Tests (Tier 1)", () => {
         type: "action",
         originalText: "I opened the window.",
         description: "open the window",
+        selfDescription: "You open the window.",
         actorId: "alice",
         targetIds: [],
+        modifiers: [],
       },
     };
 
     const resultSelf = serializeSubjectiveBufferEntry(entrySelf, viewer);
-    expect(resultSelf).toBe("you open the window");
+    expect(resultSelf).toBe("You open the window.");
 
     const entryUnfamiliar: BufferEntry = {
       id: "entry-unfamiliar",
@@ -96,14 +102,16 @@ describe("Subjective Buffer Entry Serializer Tests (Tier 1)", () => {
       intent: {
         type: "action",
         originalText: "Someone knocked.",
-        description: "knock on the door",
+        description: "knocks on the door",
+        selfDescription: "You knock on the door.",
         actorId: "stranger-1",
         targetIds: [],
+        modifiers: [],
       },
     };
 
     const resultUnfamiliar = serializeSubjectiveBufferEntry(entryUnfamiliar, viewer);
-    expect(resultUnfamiliar).toBe("an unfamiliar figure knock on the door");
+    expect(resultUnfamiliar).toBe("An unfamiliar figure knocks on the door");
   });
 });
 
@@ -123,8 +131,10 @@ describe("BufferRepository Persistence Tests (Tier 1)", () => {
       type: "action",
       originalText: "Alice picked up a stick.",
       description: "Alice gathers a stick",
+      selfDescription: "You gather a stick.",
       actorId: "alice",
       targetIds: [],
+      modifiers: [],
     };
 
     const entry: BufferEntry = {

packages/memory/tsconfig.json

@@ -7,6 +7,7 @@
   "include": ["src"],
   "references": [
     { "path": "../core" },
-    { "path": "../intent" }
+    { "path": "../intent" },
+    { "path": "../llm" }
   ]
 }

packages/scenario/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@omnia/scenario-core",
+  "name": "@omnia/scenario",
   "version": "0.0.0",
   "private": true,
   "type": "module",

packages/scenario/src/loader.ts

@@ -106,7 +106,6 @@ export class ScenarioLoader {
         world.addEntity(entity);
         this.coreRepo.saveEntity(entity, world.id);
 
-        // Seed initial memory buffer history
         if (entData.initialMemories) {
           for (const mem of entData.initialMemories) {
             this.bufferRepo.save({
@@ -114,7 +113,11 @@ export class ScenarioLoader {
               ownerId: entData.id,
               timestamp: mem.timestamp,
               locationId: mem.locationId,
-              intent: mem.intent,
+              intent: {
+                ...mem.intent,
+                selfDescription: mem.intent.selfDescription ?? "",
+                modifiers: mem.intent.modifiers ?? [],
+              },
               outcome: mem.outcome,
             });
           }

packages/scenario/src/schema.ts

@@ -33,8 +33,10 @@ export const ScenarioMemoryEntrySchema = z.object({
     type: z.enum(["dialogue", "action", "monologue"]),
     originalText: z.string(),
     description: z.string(),
+    selfDescription: z.string().optional(),
     actorId: z.string(),
     targetIds: z.array(z.string()),
+    modifiers: z.array(z.string()).optional(),
   }),
   outcome: z.object({
     isValid: z.boolean(),

packages/scenario/tests/scenario.test.ts

@@ -57,8 +57,10 @@ describe("Scenario Validation & Schema Tests (Tier 1)", () => {
               type: "action",
               originalText: "I entered the foyer.",
               description: "entered the house",
+              selfDescription: "You entered the house.",
               actorId: "investigator",
               targetIds: [],
+              modifiers: [],
             },
           },
         ],

packages/scenario/tests/talking-room.test.ts

@@ -10,7 +10,7 @@ import { ScenarioLoader, ScenarioSchema } from "../src/index.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-const SCENARIO_PATH = path.resolve(__dirname, "../../demo/scenarios/talking-room.json");
+const SCENARIO_PATH = path.resolve(__dirname, "../../../content/demo/scenarios/talking-room.json");
 
 describe("Talking Room Demo Scenario Test (Tier 1)", () => {
   test("talking-room.json exists, parses, and loads correctly into database", async () => {

packages/scenario/tsconfig.json

@@ -6,8 +6,8 @@
   },
   "include": ["src"],
   "references": [
-    { "path": "../../packages/core" },
-    { "path": "../../packages/spatial" },
-    { "path": "../../packages/memory" }
+    { "path": "../core" },
+    { "path": "../spatial" },
+    { "path": "../memory" }
   ]
 }

pnpm-workspace.yaml

@@ -1,14 +1,14 @@
 packages:
   - "packages/*"
-  - "cli"
+  - "apps/*"
   - "web/*"
-  - "content/scenario-builder"
-  - "content/scenario-core"
+
 allowBuilds:
   better-sqlite3: true
   esbuild: true
   sharp: true
   unrs-resolver: true
+  workerd: true
 minimumReleaseAgeExclude:
   - '@astrojs/telemetry@3.3.3'
   - astro@7.0.7

tests/integration/actor-monologue.test.ts

@@ -62,22 +62,28 @@ describe("Actor Agent + Monologue Intent Integration (Tier 2)", () => {
           type: "monologue",
           originalText: "I can't believe Bob hasn't noticed me yet, Alice thought.",
           description: "Alice internally reflects that Bob has not noticed her.",
+          selfDescription: "You internally reflect that Bob has not noticed you.",
           actorId: "alice",
           targetIds: [],
+          modifiers: [],
         },
         {
           type: "dialogue",
           originalText: '"Hey Bob," she called out softly.',
           description: "Alice softly calls out to Bob.",
+          selfDescription: "You softly call out to Bob.",
           actorId: "alice",
           targetIds: ["bob"],
+          modifiers: [],
         },
         {
           type: "action",
           originalText: "She reached for the ledger on the table.",
           description: "Alice reaches for the ledger on the table.",
+          selfDescription: "You reach for the ledger on the table.",
           actorId: "alice",
           targetIds: [],
+          modifiers: [],
         },
       ],
     };

tests/integration/game-loop.test.ts

@@ -33,15 +33,19 @@ describe("Omnia Integration Tests (Tier 2)", () => {
           type: "dialogue",
           originalText: '"Cover me," Alice whispered to Bob.',
           description: "Alice whispers to Bob to cover her.",
+          selfDescription: "You whisper to Bob to cover you.",
           actorId: "alice",
           targetIds: ["bob"],
+          modifiers: [],
         },
         {
           type: "action",
           originalText: "She crept towards the door and pulled the handle.",
           description: "Alice creeps to the door and pulls the handle.",
+          selfDescription: "You creep to the door and pull the handle.",
           actorId: "alice",
           targetIds: [],
+          modifiers: [],
         },
       ],
     };
@@ -108,16 +112,20 @@ describe("Omnia Integration Tests (Tier 2)", () => {
       type: "action" as const,
       originalText: "She tries to unlock the gate with a hairpin.",
       description: "Alice attempts to pick the lock with a hairpin.",
+      selfDescription: "You attempt to pick the lock with a hairpin.",
       actorId: "alice",
       targetIds: [],
+      modifiers: [],
     };
 
     const intent2 = {
       type: "dialogue" as const,
       originalText: '"This is useless," she mutters.',
       description: "Alice mutters to herself.",
+      selfDescription: "You mutter to yourself.",
       actorId: "alice",
       targetIds: [],
+      modifiers: [],
     };
 
     // LLM validation / time delta mock responses:

tsconfig.json

@@ -11,7 +11,6 @@
     { "path": "./packages/spatial" },
     { "path": "./packages/llm" },
     { "path": "./packages/actor" },
-    { "path": "./content/scenario-core" },
-    { "path": "./cli" }
+    { "path": "./packages/scenario" }
   ]
 }