diff --git a/.env.example b/.env.example
index a58439f6..47ca04d6 100644
--- a/.env.example
+++ b/.env.example
@@ -30,6 +30,15 @@
 # 8b  ~16 GB RAM  |  70b  ~140 GB RAM  |  405b  ~810 GB RAM
 # AIRLLM_MODEL_SIZE=70b
 
+# ── Grok (xAI) — premium cloud augmentation ──────────────────────────────────
+# Enable Grok as an opt-in premium backend for frontier reasoning.
+# Local-first ethos is preserved — Grok only activates when explicitly enabled.
+# GROK_ENABLED=false
+# XAI_API_KEY=xai-...
+# GROK_DEFAULT_MODEL=grok-3-fast
+# GROK_MAX_SATS_PER_QUERY=200
+# GROK_FREE=false
+
 # ── L402 Lightning secrets ───────────────────────────────────────────────────
 # HMAC secret for invoice verification.  MUST be changed in production.
 # Generate with: python3 -c "import secrets; print(secrets.token_hex(32))"
diff --git a/.gitignore b/.gitignore
index 44235108..0814e2b8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -35,6 +35,13 @@ coverage.xml
 htmlcov/
 reports/
 
+# Self-modify reports (auto-generated)
+data/self_modify_reports/
+src/data/
+
+# Handoff context (session-scoped)
+.handoff/
+
 # IDE
 .idea/
 .vscode/
diff --git a/AGENTS.md b/AGENTS.md
index 4838713f..5888ea4f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,342 +1,79 @@
 # AGENTS.md — Timmy Time Development Standards for AI Agents
 
-This file is the authoritative reference for any AI agent contributing to
-this repository.  Read it first.  Every time.
+Read [`CLAUDE.md`](CLAUDE.md) for architecture patterns and conventions.
 
 ---
 
-## 1. Project at a Glance
+## Non-Negotiable Rules
 
-**Timmy Time** is a local-first, sovereign AI agent system.  No cloud.  No telemetry.
-Bitcoin Lightning economics baked in.
+1. **Tests must stay green.** Run `make test` before committing.
+2. **No cloud dependencies.** All AI computation runs on localhost.
+3. **No new top-level files without purpose.** Don't litter the root directory.
+4. **Follow existing patterns** — singletons, graceful degradation, pydantic-settings.
+5. **Security defaults:** Never hard-code secrets.
+6. **XSS prevention:** Never use `innerHTML` with untrusted content.
 
-| Thing            | Value                                              |
-|------------------|----------------------------------------------------|
-| Language         | Python 3.11+                                       |
-| Web framework    | FastAPI + Jinja2 + HTMX                            |
-| Agent framework  | Agno (wraps Ollama or AirLLM)                      |
-| Persistence      | SQLite (`timmy.db`, `data/swarm.db`)               |
-| Tests            | pytest — must stay green                           |
-| Entry points     | `timmy`, `timmy-serve`, `self-tdd`                 |
-| Config           | pydantic-settings, reads `.env`                    |
-| Containers       | Docker — each agent can run as an isolated service |
+---
+
+## Agent Roster
+
+### Build Tier
+
+**Local (Ollama)** — Primary workhorse. Free. Unrestricted.
+Best for: everything, iterative dev, Docker swarm workers.
+
+**Kimi (Moonshot)** — Paid. Large-context feature drops, new subsystems, persona agents.
+Avoid: touching CI/pyproject.toml, adding cloud calls, removing tests.
+
+**DeepSeek** — Near-free. Second-opinion generation, large refactors (R1 for hard problems).
+Avoid: bypassing review tier for security modules.
+
+### Review Tier
+
+**Claude (Anthropic)** — Architecture, tests, docs, CI/CD, PR review.
+Avoid: large one-shot feature dumps.
+
+**Gemini (Google)** — Docs, frontend polish, boilerplate, diff summaries.
+Avoid: security modules, Python business logic without Claude review.
+
+**Manus AI** — Security audits, coverage gaps, L402 validation.
+Avoid: large refactors, new features, prompt changes.
+
+---
+
+## Docker Agents
+
+Container agents poll the coordinator's HTTP API (not in-memory `SwarmComms`):
 
 ```
-src/
-  config.py             # Central settings (OLLAMA_URL, DEBUG, etc.)
-  timmy/                # Core agent: agent.py, backends.py, cli.py, prompts.py
-  dashboard/            # FastAPI app + routes + Jinja2 templates
-    app.py
-    store.py            # In-memory MessageLog singleton
-    routes/             # agents, health, swarm, swarm_ws, marketplace,
-    │                   # mobile, mobile_test, voice, voice_enhanced,
-    │                   # swarm_internal (HTTP API for Docker agents)
-    templates/          # base.html + page templates + partials/
-  swarm/                # Multi-agent coordinator, registry, bidder, tasks, comms
-    docker_runner.py    # Spawn agents as Docker containers
-  timmy_serve/          # L402 Lightning proxy, payment handler, TTS, CLI
-  spark/                # Intelligence engine — events, predictions, advisory
-  creative/             # Creative director + video assembler pipeline
-  tools/                # Git, image, music, video tools for persona agents
-  lightning/            # Lightning backend abstraction (mock + LND)
-  agent_core/           # Substrate-agnostic agent interface
-  voice/                # NLU intent detection (regex-based, no cloud)
-  ws_manager/           # WebSocket manager (ws_manager singleton)
-  notifications/        # Push notification store (notifier singleton)
-  shortcuts/            # Siri Shortcuts API endpoints
-  telegram_bot/         # Telegram bridge
-  self_tdd/             # Continuous test watchdog
-tests/                  # One test_*.py per module, all mocked
-static/                 # style.css + bg.svg (arcane theme)
-docs/                   # GitHub Pages site
+GET  /internal/tasks    → list tasks open for bidding
+POST /internal/bids     → submit a bid
 ```
 
----
-
-## 2. Non-Negotiable Rules
-
-1. **Tests must stay green.**  Run `make test` before committing.
-2. **No cloud dependencies.**  All AI computation runs on localhost.
-3. **No new top-level files without purpose.**  Don't litter the root directory.
-4. **Follow existing patterns** — singletons, graceful degradation, pydantic-settings config.
-5. **Security defaults:** Never hard-code secrets.  Warn at startup when defaults are in use.
-6. **XSS prevention:**  Never use `innerHTML` with untrusted content.
-
----
-
-## 3. Agent Roster
-
-Agents are divided into two tiers: **Builders** generate code and features;
-**Reviewers** provide quality gates, feedback, and hardening.  The Local agent
-is the primary workhorse — use it as much as possible to minimise cost.
-
----
-
-### 🏗️ BUILD TIER
-
----
-
-### Local — Ollama (primary workhorse)
-**Model:** Any — `qwen2.5-coder`, `deepseek-coder-v2`, `codellama`, or whatever
-is loaded in Ollama.  The owner decides the model; this agent is unrestricted.
-**Cost:** Free.  Runs on the host machine.
-
-**Best for:**
-- Everything.  This is the default agent for all coding tasks.
-- Iterative development, fast feedback loops, bulk generation
-- Running as a Docker swarm worker — scales horizontally at zero marginal cost
-- Experimenting with new models without changing any other code
-
-**Conventions to follow:**
-- Communicate with the coordinator over HTTP (`COORDINATOR_URL` env var)
-- Register capabilities honestly so the auction system routes tasks well
-- Write tests for anything non-trivial
-
-**No restrictions.**  If a model can do it, do it.
-
----
-
-### Kimi (Moonshot AI)
-**Model:** Moonshot large-context models.
-**Cost:** Paid API.
-
-**Best for:**
-- Large context feature drops (new pages, new subsystems, new agent personas)
-- Implementing roadmap items that require reading many files at once
-- Generating boilerplate for new agents (Echo, Mace, Helm, Seer, Forge, Quill)
-
-**Conventions to follow:**
-- Deliver working code with accompanying tests (even if minimal)
-- Match the arcane CSS theme — extend `static/style.css`
-- New agents follow the `SwarmNode` + `Registry` + Docker pattern
-- Lightning-gated endpoints follow the L402 pattern in `src/timmy_serve/l402_proxy.py`
-
-**Avoid:**
-- Touching CI/CD or pyproject.toml without coordinating
-- Adding cloud API calls
-- Removing existing tests
-
----
-
-### DeepSeek (DeepSeek API)
-**Model:** `deepseek-chat` (V3) or `deepseek-reasoner` (R1).
-**Cost:** Near-free (~$0.14/M tokens).
-
-**Best for:**
-- Second-opinion feature generation when Kimi is busy or context is smaller
-- Large refactors with reasoning traces (use R1 for hard problems)
-- Code review passes before merging Kimi PRs
-- Anything that doesn't need a frontier model but benefits from strong reasoning
-
-**Conventions to follow:**
-- Same conventions as Kimi
-- Prefer V3 for straightforward tasks; R1 for anything requiring multi-step logic
-- Submit PRs for review by Claude before merging
-
-**Avoid:**
-- Bypassing the review tier for security-sensitive modules
-- Touching `src/swarm/coordinator.py` without Claude review
-
----
-
-### 🔍 REVIEW TIER
-
----
-
-### Claude (Anthropic)
-**Model:** Claude Sonnet.
-**Cost:** Paid API.
-
-**Best for:**
-- Architecture decisions and code-quality review
-- Writing and fixing tests; keeping coverage green
-- Updating documentation (README, AGENTS.md, inline comments)
-- CI/CD, tooling, Docker infrastructure
-- Debugging tricky async or import issues
-- Reviewing PRs from Local, Kimi, and DeepSeek before merge
-
-**Conventions to follow:**
-- Prefer editing existing files over creating new ones
-- Keep route files thin — business logic lives in the module, not the route
-- Use `from config import settings` for all env-var access
-- New routes go in `src/dashboard/routes/`, registered in `app.py`
-- Always add a corresponding `tests/test_<module>.py`
-
-**Avoid:**
-- Large one-shot feature dumps (use Local or Kimi)
-- Touching `src/swarm/coordinator.py` for security work (that's Manus's lane)
-
----
-
-### Gemini (Google)
-**Model:** Gemini 2.0 Flash (free tier) or Pro.
-**Cost:** Free tier generous; upgrade only if needed.
-
-**Best for:**
-- Documentation, README updates, inline docstrings
-- Frontend polish — HTML templates, CSS, accessibility review
-- Boilerplate generation (test stubs, config files, GitHub Actions)
-- Summarising large diffs for human review
-
-**Conventions to follow:**
-- Submit changes as PRs; always include a plain-English summary of what changed
-- For CSS changes, test at mobile breakpoint (≤768px) before submitting
-- Never modify Python business logic without Claude review
-
-**Avoid:**
-- Security-sensitive modules (that's Manus's lane)
-- Changing auction or payment logic
-- Large Python refactors
-
----
-
-### Manus AI
-**Strengths:** Precision security work, targeted bug fixes, coverage gap analysis.
-
-**Best for:**
-- Security audits (XSS, injection, secret exposure)
-- Closing test coverage gaps for existing modules
-- Performance profiling of specific endpoints
-- Validating L402/Lightning payment flows
-
-**Conventions to follow:**
-- Scope tightly — one security issue per PR
-- Every security fix must have a regression test
-- Use `pytest-cov` output to identify gaps before writing new tests
-- Document the vulnerability class in the PR description
-
-**Avoid:**
-- Large-scale refactors (that's Claude's lane)
-- New feature work (use Local or Kimi)
-- Changing agent personas or prompt content
-
----
-
-## 4. Docker — Running Agents as Containers
-
-Each agent can run as an isolated Docker container.  Containers share the
-`data/` volume for SQLite and communicate with the coordinator over HTTP.
+`COORDINATOR_URL=http://dashboard:8000` is set by docker-compose.
 
 ```bash
-make docker-build          # build the image
-make docker-up             # start dashboard + deps
-make docker-agent          # spawn one agent worker (LOCAL model)
-make docker-down           # stop everything
-make docker-logs           # tail all service logs
-```
-
-### How container agents communicate
-
-Container agents cannot use the in-memory `SwarmComms` channel.  Instead they
-poll the coordinator's internal HTTP API:
-
-```
-GET  /internal/tasks          → list tasks open for bidding
-POST /internal/bids           → submit a bid
-```
-
-Set `COORDINATOR_URL=http://dashboard:8000` in the container environment
-(docker-compose sets this automatically).
-
-### Spawning a container agent from Python
-
-```python
-from swarm.docker_runner import DockerAgentRunner
-
-runner = DockerAgentRunner(coordinator_url="http://dashboard:8000")
-info   = runner.spawn("Echo", image="timmy-time:latest")
-runner.stop(info["container_id"])
+make docker-build       # build image
+make docker-up          # start dashboard
+make docker-agent       # add a worker
 ```
 
 ---
 
-## 5. Architecture Patterns
-
-### Singletons (module-level instances)
-```python
-from dashboard.store import message_log
-from notifications.push import notifier
-from ws_manager.handler import ws_manager
-from timmy_serve.payment_handler import payment_handler
-from swarm.coordinator import coordinator
-```
-
-### Config access
-```python
-from config import settings
-url = settings.ollama_url   # never os.environ.get() directly in route files
-```
-
-### HTMX pattern
-```python
-return templates.TemplateResponse(
-    "partials/chat_message.html",
-    {"request": request, "role": "user", "content": message}
-)
-```
-
-### Graceful degradation
-```python
-try:
-    result = await some_optional_service()
-except Exception:
-    result = fallback_value   # log, don't crash
-```
-
-### Tests
-- All heavy deps (`agno`, `airllm`, `pyttsx3`) are stubbed in `tests/conftest.py`
-- Use `pytest.fixture` for shared state; prefer function scope
-- Use `TestClient` from `fastapi.testclient` for route tests
-- No real Ollama required — mock `agent.run()`
-
----
-
-## 6. Running Locally
-
-```bash
-make install        # create venv + install dev deps
-make test           # run full test suite
-make dev            # start dashboard (http://localhost:8000)
-make watch          # self-TDD watchdog (60s poll)
-make test-cov       # coverage report
-```
-
-Or with Docker:
-```bash
-make docker-build   # build image
-make docker-up      # start dashboard
-make docker-agent   # add a Local agent worker
-```
-
----
-
-## 7. Roadmap (v2 → v3)
-
-**v2.0.0 — Exodus (in progress)**
-- [x] Persistent swarm state across restarts
-- [x] Docker infrastructure for agent containers
-- [x] Implement Echo, Mace, Helm, Seer, Forge, Quill persona agents (+ Pixel, Lyra, Reel)
-- [x] MCP tool integration for Timmy
-- [ ] Real LND gRPC backend for `PaymentHandler` (replace mock)
-- [ ] Marketplace frontend — wire `/marketplace` route to real data
-
-**v3.0.0 — Revelation (planned)**
-- [ ] Bitcoin Lightning treasury (agent earns and spends sats autonomously)
-- [ ] Single `.app` bundle for macOS (no Python install required)
-- [ ] Federation — multiple Timmy instances discover and bid on each other's tasks
-- [ ] Redis pub/sub replacing SQLite polling for high-throughput swarms
-
----
-
-## 8. File Conventions
+## File Conventions
 
 | Pattern | Convention |
 |---------|-----------|
 | New route | `src/dashboard/routes/<name>.py` + register in `app.py` |
 | New template | `src/dashboard/templates/<name>.html` extends `base.html` |
-| New partial | `src/dashboard/templates/partials/<name>.html` |
-| New subsystem | `src/<name>/` with `__init__.py` |
-| New test file | `tests/test_<module>.py` |
-| Secrets | Read via `os.environ.get("VAR", "default")` + startup warning if default |
-| DB files | `.db` files go in project root or `data/` — never in `src/` |
-| Docker | One service per agent type in `docker-compose.yml` |
+| New subsystem | Add to existing `src/<package>/` — see module map in CLAUDE.md |
+| New test | `tests/<module>/test_<feature>.py` (mirror source structure) |
+| Secrets | Via `config.settings` + startup warning if default |
+| DB files | Project root or `data/` — never in `src/` |
+
+---
+
+## Roadmap
+
+**v2.0 Exodus (in progress):** Swarm + L402 + Voice + Marketplace + Hands
+**v3.0 Revelation (planned):** Lightning treasury + `.app` bundle + federation
diff --git a/CLAUDE.md b/CLAUDE.md
index ae0f42e1..d994e8c9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,77 +1,9 @@
 # CLAUDE.md — AI Assistant Guide for Timmy Time
 
-This file provides context for AI assistants (Claude Code, Copilot, etc.)
-working in this repository. Read this before making any changes.
+**Tech stack:** Python 3.11+ · FastAPI · Jinja2 + HTMX · SQLite · Agno ·
+Ollama · pydantic-settings · WebSockets · Docker
 
-For multi-agent development standards and agent-specific conventions, see
-[`AGENTS.md`](AGENTS.md).
-
----
-
-## Project Summary
-
-**Timmy Time** is a local-first, sovereign AI agent system with a browser-based
-Mission Control dashboard. No cloud AI — all inference runs on localhost via
-Ollama (or AirLLM for large models). Bitcoin Lightning economics are built in
-for API access gating.
-
-**Tech stack:** Python 3.11+ · FastAPI · Jinja2 + HTMX · SQLite · Agno (agent
-framework) · Ollama · pydantic-settings · WebSockets · Docker
-
----
-
-## Quick Reference Commands
-
-```bash
-# Setup
-make install            # Create venv + install dev deps
-cp .env.example .env    # Configure environment
-
-# Development
-make dev                # Start dashboard at http://localhost:8000
-make test               # Run full test suite (no Ollama needed)
-make test-cov           # Tests + coverage report (terminal + XML)
-make lint               # Run ruff or flake8
-
-# Docker
-make docker-build       # Build timmy-time:latest image
-make docker-up          # Start dashboard container
-make docker-agent       # Spawn one agent worker
-make docker-down        # Stop all containers
-```
-
----
-
-## Project Layout
-
-```
-src/
-  config.py              # Central pydantic-settings (all env vars)
-  timmy/                 # Core agent: agent.py, backends.py, cli.py, prompts.py
-  dashboard/             # FastAPI app + routes + Jinja2 templates
-    app.py               # App factory, lifespan, router registration
-    store.py             # In-memory MessageLog singleton
-    routes/              # One file per route group (agents, health, swarm, etc.)
-    templates/           # base.html + page templates + partials/
-  swarm/                 # Multi-agent coordinator, registry, bidder, tasks, comms
-    coordinator.py       # Central swarm orchestrator (security-sensitive)
-    docker_runner.py     # Spawn agents as Docker containers
-  timmy_serve/           # L402 Lightning proxy, payment handler, TTS, CLI
-  spark/                 # Intelligence engine — events, predictions, advisory
-  creative/              # Creative director + video assembler pipeline
-  tools/                 # Git, image, music, video tools for persona agents
-  lightning/             # Lightning backend abstraction (mock + LND)
-  agent_core/            # Substrate-agnostic agent interface
-  voice/                 # NLU intent detection (regex-based, local)
-  ws_manager/            # WebSocket connection manager (ws_manager singleton)
-  notifications/         # Push notification store (notifier singleton)
-  shortcuts/             # Siri Shortcuts API endpoints
-  telegram_bot/          # Telegram bridge
-  self_tdd/              # Continuous test watchdog
-tests/                   # One test_*.py per module, all mocked
-static/                  # style.css + bg.svg (dark arcane theme)
-docs/                    # GitHub Pages landing site
-```
+For agent roster and conventions, see [`AGENTS.md`](AGENTS.md).
 
 ---
 
@@ -79,32 +11,22 @@ docs/                    # GitHub Pages landing site
 
 ### Config access
 
-All configuration goes through `src/config.py` using pydantic-settings:
-
 ```python
 from config import settings
 url = settings.ollama_url   # never use os.environ.get() directly in app code
 ```
 
-Environment variables are read from `.env` automatically. See `.env.example` for
-all available settings.
-
 ### Singletons
 
-Core services are module-level singleton instances imported directly:
-
 ```python
 from dashboard.store import message_log
-from notifications.push import notifier
-from ws_manager.handler import ws_manager
-from timmy_serve.payment_handler import payment_handler
+from infrastructure.notifications.push import notifier
+from infrastructure.ws_manager.handler import ws_manager
 from swarm.coordinator import coordinator
 ```
 
 ### HTMX response pattern
 
-Routes return Jinja2 template partials for HTMX requests:
-
 ```python
 return templates.TemplateResponse(
     "partials/chat_message.html",
@@ -115,147 +37,41 @@ return templates.TemplateResponse(
 ### Graceful degradation
 
 Optional services (Ollama, Redis, AirLLM) degrade gracefully — log the error,
-return a fallback, never crash:
-
-```python
-try:
-    result = await some_optional_service()
-except Exception:
-    result = fallback_value
-```
+return a fallback, never crash.
 
 ### Route registration
 
-New routes go in `src/dashboard/routes/<name>.py`, then register the router in
-`src/dashboard/app.py`:
-
-```python
-from dashboard.routes.<name> import router as <name>_router
-app.include_router(<name>_router)
-```
+New routes: `src/dashboard/routes/<name>.py` → register in `src/dashboard/app.py`.
 
 ---
 
 ## Testing
 
-### Running tests
-
 ```bash
-make test               # Quick run (pytest -q --tb=short)
+make test               # Quick run (no Ollama needed)
 make test-cov           # With coverage (term-missing + XML)
-make test-cov-html      # With HTML coverage report
 ```
 
-No Ollama or external services needed — all heavy dependencies are mocked.
-
-### Test conventions
-
-- **One test file per module:** `tests/test_<module>.py`
-- **Stubs in conftest:** `agno`, `airllm`, `pyttsx3`, `telegram` are stubbed in
-  `tests/conftest.py` using `sys.modules.setdefault()` so tests run without
-  those packages installed
-- **Test mode:** `TIMMY_TEST_MODE=1` is set automatically in conftest to disable
-  auto-spawning of persona agents during tests
-- **FastAPI testing:** Use the `client` fixture (wraps `TestClient`)
-- **Database isolation:** SQLite files in `data/` are cleaned between tests;
-  coordinator state is reset via autouse fixtures
-- **Async:** `asyncio_mode = "auto"` in pytest config — async test functions
-  are detected automatically
-- **Coverage threshold:** CI fails if coverage drops below 60%
-  (`fail_under = 60` in `pyproject.toml`)
-
-### Adding a new test
-
-```python
-# tests/test_my_feature.py
-from fastapi.testclient import TestClient
-
-def test_my_endpoint(client):
-    response = client.get("/my-endpoint")
-    assert response.status_code == 200
-```
-
----
-
-## CI/CD
-
-GitHub Actions workflow (`.github/workflows/tests.yml`):
-
-- Runs on every push and pull request to all branches
-- Python 3.11, installs `.[dev]` dependencies
-- Runs pytest with coverage + JUnit XML output
-- Publishes test results as PR comments and check annotations
-- Uploads coverage XML as a downloadable artifact (14-day retention)
+- **Stubs in conftest:** `agno`, `airllm`, `pyttsx3`, `telegram`, `discord`
+  stubbed via `sys.modules.setdefault()` — tests run without those packages
+- **Test mode:** `TIMMY_TEST_MODE=1` set automatically in conftest
+- **FastAPI testing:** Use the `client` fixture
+- **Async:** `asyncio_mode = "auto"` — async tests detected automatically
+- **Coverage threshold:** 60% (`fail_under` in `pyproject.toml`)
 
 ---
 
 ## Key Conventions
 
 1. **Tests must stay green.** Run `make test` before committing.
-2. **No cloud AI dependencies.** All inference runs on localhost.
-3. **No new top-level files without purpose.** Keep the root directory clean.
-4. **Follow existing patterns** — singletons, graceful degradation,
-   pydantic-settings config.
-5. **Security defaults:** Never hard-code secrets. Warn at startup when using
-   default values.
+2. **No cloud AI dependencies.** All inference on localhost.
+3. **Keep the root directory clean.** No new top-level files without purpose.
+4. **Follow existing patterns** — singletons, graceful degradation, pydantic config.
+5. **Security defaults:** Never hard-code secrets.
 6. **XSS prevention:** Never use `innerHTML` with untrusted content.
 7. **Keep routes thin** — business logic lives in the module, not the route.
 8. **Prefer editing existing files** over creating new ones.
 9. **Use `from config import settings`** for all env-var access.
-10. **Every new module gets a test:** `tests/test_<module>.py`.
-
----
-
-## Entry Points
-
-Three CLI commands are installed via `pyproject.toml`:
-
-| Command | Module | Purpose |
-|---------|--------|---------|
-| `timmy` | `src/timmy/cli.py` | Chat, think, status commands |
-| `timmy-serve` | `src/timmy_serve/cli.py` | L402-gated API server (port 8402) |
-| `self-tdd` | `src/self_tdd/watchdog.py` | Continuous test watchdog |
-
----
-
-## Environment Variables
-
-Key variables (full list in `.env.example`):
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `OLLAMA_URL` | `http://localhost:11434` | Ollama host |
-| `OLLAMA_MODEL` | `llama3.2` | Model served by Ollama |
-| `DEBUG` | `false` | Enable `/docs` and `/redoc` |
-| `TIMMY_MODEL_BACKEND` | `ollama` | `ollama` / `airllm` / `auto` |
-| `AIRLLM_MODEL_SIZE` | `70b` | `8b` / `70b` / `405b` |
-| `L402_HMAC_SECRET` | *(change in prod)* | HMAC signing for invoices |
-| `L402_MACAROON_SECRET` | *(change in prod)* | Macaroon signing |
-| `LIGHTNING_BACKEND` | `mock` | `mock` / `lnd` |
-| `SPARK_ENABLED` | `true` | Enable Spark intelligence engine |
-| `TELEGRAM_TOKEN` | *(empty)* | Telegram bot token |
-
----
-
-## Persistence
-
-- `timmy.db` — Agno agent memory (SQLite, project root)
-- `data/swarm.db` — Swarm registry + tasks (SQLite, `data/` directory)
-- All `.db` files are gitignored — never commit database files
-
----
-
-## Docker
-
-Containers share a `data/` volume for SQLite. Container agents communicate with
-the coordinator over HTTP (not in-memory `SwarmComms`):
-
-```
-GET  /internal/tasks    → list tasks open for bidding
-POST /internal/bids     → submit a bid
-```
-
-`COORDINATOR_URL=http://dashboard:8000` is set automatically by docker-compose.
 
 ---
 
@@ -265,3 +81,35 @@ POST /internal/bids     → submit a bid
 - `src/timmy_serve/l402_proxy.py` — Lightning payment gating
 - `src/lightning/` — payment backend abstraction
 - Any file handling secrets or authentication tokens
+
+---
+
+## Entry Points
+
+| Command | Module | Purpose |
+|---------|--------|---------|
+| `timmy` | `src/timmy/cli.py` | Chat, think, status |
+| `timmy-serve` | `src/timmy_serve/cli.py` | L402-gated API server (port 8402) |
+| `self-tdd` | `src/self_coding/self_tdd/watchdog.py` | Continuous test watchdog |
+| `self-modify` | `src/self_coding/self_modify/cli.py` | Self-modification CLI |
+
+---
+
+## Module Map (14 packages)
+
+| Package | Purpose |
+|---------|---------|
+| `timmy/` | Core agent, personas, agent interface, semantic memory |
+| `dashboard/` | FastAPI web UI, routes, templates |
+| `swarm/` | Multi-agent coordinator, task queue, work orders |
+| `self_coding/` | Self-modification, test watchdog, upgrade queue |
+| `creative/` | Media generation, MCP tools |
+| `infrastructure/` | WebSocket, notifications, events, LLM router |
+| `integrations/` | Discord, Telegram, Siri Shortcuts, voice NLU |
+| `lightning/` | L402 payment gating (security-sensitive) |
+| `mcp/` | MCP tool registry and discovery |
+| `spark/` | Event capture and advisory engine |
+| `hands/` | 6 autonomous Hand agents |
+| `scripture/` | Biblical text integration |
+| `timmy_serve/` | L402-gated API server |
+| `config.py` | Pydantic settings (foundation for all modules) |
diff --git a/MEMORY.md b/MEMORY.md
index e8d7bc57..51c3e64c 100644
--- a/MEMORY.md
+++ b/MEMORY.md
@@ -7,34 +7,20 @@
 
 ## Current Status
 
-**Agent State:** Operational
-**Mode:** Development
-**Model:** llama3.2 (local via Ollama)
-**Backend:** Ollama on localhost:11434
-**Dashboard:** http://localhost:8000
+**Agent State:** Operational  
+**Mode:** Development  
+**Active Tasks:** 0  
+**Pending Decisions:** None
 
 ---
 
 ## Standing Rules
 
-1. **Sovereignty First** — No cloud AI dependencies
+1. **Sovereignty First** — No cloud dependencies
 2. **Local-Only Inference** — Ollama on localhost
 3. **Privacy by Design** — Telemetry disabled
 4. **Tool Minimalism** — Use tools only when necessary
 5. **Memory Discipline** — Write handoffs at session end
-6. **Clean Output** — Never show JSON, tool calls, or function syntax
-
----
-
-## System Architecture
-
-**Memory Tiers:**
-- Tier 1 (Hot): This file (MEMORY.md) — always in context
-- Tier 2 (Vault): memory/ directory — notes, profiles, AARs
-- Tier 3 (Semantic): Vector search over vault content
-
-**Swarm Agents:** Echo (research), Forge (code), Seer (data)
-**Dashboard Pages:** Briefing, Swarm, Spark, Market, Tools, Events, Ledger, Memory, Router, Upgrades, Creative
 
 ---
 
@@ -42,16 +28,13 @@
 
 | Agent | Role | Status |
 |-------|------|--------|
-| Timmy | Core AI | Active |
-| Echo | Research & Summarization | Active |
-| Forge | Coding & Debugging | Active |
-| Seer | Analytics & Prediction | Active |
+| Timmy | Core | Active |
 
 ---
 
 ## User Profile
 
-**Name:** (not set)
+**Name:** (not set)  
 **Interests:** (to be learned)
 
 ---
@@ -64,8 +47,8 @@
 
 ## Pending Actions
 
-- [ ] Learn user's name and preferences
+- [ ] Learn user's name
 
 ---
 
-*Prune date: 2026-03-25*
+*Prune date: 2026-02-25*
diff --git a/README.md b/README.md
index b2066111..1b481d80 100644
--- a/README.md
+++ b/README.md
@@ -2,109 +2,161 @@
 
 [![Tests](https://github.com/AlexanderWhitestone/Timmy-time-dashboard/actions/workflows/tests.yml/badge.svg)](https://github.com/AlexanderWhitestone/Timmy-time-dashboard/actions/workflows/tests.yml)
 
-A local-first, sovereign AI agent system.  Talk to Timmy, watch his swarm, gate API access with Bitcoin Lightning — all from a browser, no cloud AI required.
+A local-first, sovereign AI agent system. Talk to Timmy, watch his swarm, gate
+API access with Bitcoin Lightning — all from a browser, no cloud AI required.
 
 **[Live Docs →](https://alexanderwhitestone.github.io/Timmy-time-dashboard/)**
 
 ---
 
-## What's built
+## Quick Start
+
+```bash
+git clone https://github.com/AlexanderWhitestone/Timmy-time-dashboard.git
+cd Timmy-time-dashboard
+make install              # create venv + install deps
+cp .env.example .env      # configure environment
+
+ollama serve              # separate terminal
+ollama pull llama3.1:8b-instruct  # Required for reliable tool calling
+
+make dev                  # http://localhost:8000
+make test                 # no Ollama needed
+```
+
+**Note:** llama3.1:8b-instruct is used instead of llama3.2 because it is
+specifically fine-tuned for reliable tool/function calling.
+llama3.2 (3B) was found to hallucinate tool output consistently in testing.
+Fallback: qwen2.5:14b if llama3.1:8b-instruct is not available.
+
+---
+
+## What's Here
 
 | Subsystem | Description |
 |-----------|-------------|
 | **Timmy Agent** | Agno-powered agent (Ollama default, AirLLM optional for 70B/405B) |
 | **Mission Control** | FastAPI + HTMX dashboard — chat, health, swarm, marketplace |
-| **Swarm** | Multi-agent coordinator — spawn agents, post tasks, run Lightning auctions |
-| **L402 / Lightning** | Bitcoin Lightning payment gating for API access (mock backend; LND scaffolded) |
-| **Spark Intelligence** | Event capture, predictions, memory consolidation, advisory engine |
-| **Creative Studio** | Multi-persona creative pipeline — image, music, video generation |
-| **Tools** | Git, image, music, and video tools accessible by persona agents |
-| **Voice** | NLU intent detection + TTS (pyttsx3, no cloud) |
-| **WebSocket** | Real-time swarm live feed |
-| **Mobile** | Responsive layout with full iOS safe-area and touch support |
-| **Telegram** | Bridge Telegram messages to Timmy |
+| **Swarm** | Multi-agent coordinator — spawn agents, post tasks, Lightning auctions |
+| **L402 / Lightning** | Bitcoin Lightning payment gating for API access |
+| **Spark** | Event capture, predictions, memory consolidation, advisory |
+| **Creative Studio** | Multi-persona pipeline — image, music, video generation |
 | **Hands** | 6 autonomous scheduled agents — Oracle, Sentinel, Scout, Scribe, Ledger, Weaver |
-| **CLI** | `timmy`, `timmy-serve`, `self-tdd` entry points |
-
-**Full test suite, 100% passing.**
+| **Self-Coding** | Codebase-aware self-modification with git safety |
+| **Integrations** | Telegram bridge, Siri Shortcuts, voice NLU, mobile layout |
 
 ---
 
-## Prerequisites
+## Commands
 
-**Python 3.11+**
 ```bash
-python3 --version   # must be 3.11+
+make dev            # start dashboard (http://localhost:8000)
+make test           # run all tests
+make test-cov       # tests + coverage report
+make lint           # run ruff/flake8
+make docker-up      # start via Docker
+make help           # see all commands
 ```
-If not: `brew install python@3.11`
 
-**Ollama** — runs the local LLM
+**CLI tools:** `timmy`, `timmy-serve`, `self-tdd`, `self-modify`
+
+---
+
+## Documentation
+
+| Document | Purpose |
+|----------|---------|
+| [CLAUDE.md](CLAUDE.md) | AI assistant development guide |
+| [AGENTS.md](AGENTS.md) | Multi-agent development standards |
+| [.env.example](.env.example) | Configuration reference |
+| [docs/](docs/) | Architecture docs, ADRs, audits |
+
+---
+
+## Configuration
+
 ```bash
-brew install ollama
-# or download from https://ollama.com
+cp .env.example .env
+```
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `OLLAMA_URL` | `http://localhost:11434` | Ollama host |
+| `OLLAMA_MODEL` | `llama3.1:8b-instruct` | Model for tool calling. Use llama3.1:8b-instruct for reliable tool use; fallback to qwen2.5:14b |
+| `DEBUG` | `false` | Enable `/docs` and `/redoc` |
+| `TIMMY_MODEL_BACKEND` | `ollama` | `ollama` \| `airllm` \| `auto` |
+| `AIRLLM_MODEL_SIZE` | `70b` | `8b` \| `70b` \| `405b` |
+| `L402_HMAC_SECRET` | *(default — change in prod)* | HMAC signing key for macaroons |
+| `L402_MACAROON_SECRET` | *(default — change in prod)* | Macaroon secret |
+| `LIGHTNING_BACKEND` | `mock` | `mock` (production-ready) \| `lnd` (scaffolded, not yet functional) |
+
+---
+
+## Architecture
+
+```
+Browser / Phone
+      │ HTTP + HTMX + WebSocket
+      ▼
+┌─────────────────────────────────────────┐
+│             FastAPI (dashboard.app)      │
+│  routes: agents, health, swarm,          │
+│          marketplace, voice, mobile      │
+└───┬─────────────┬──────────┬────────────┘
+    │             │          │
+    ▼             ▼          ▼
+Jinja2        Timmy       Swarm
+Templates     Agent       Coordinator
+(HTMX)        │           ├─ Registry (SQLite)
+              ├─ Ollama   ├─ AuctionManager (L402 bids)
+              └─ AirLLM   ├─ SwarmComms (Redis / in-memory)
+                          └─ SwarmManager (subprocess)
+    │
+    ├── Voice NLU + TTS (pyttsx3, local)
+    ├── WebSocket live feed (ws_manager)
+    ├── L402 Lightning proxy (macaroon + invoice)
+    ├── Push notifications (local + macOS native)
+    └── Siri Shortcuts API endpoints
+
+Persistence: timmy.db (Agno memory), data/swarm.db (registry + tasks)
+External:    Ollama :11434, optional Redis, optional LND gRPC
 ```
 
 ---
 
-## Quickstart
+## Project Layout
 
-```bash
-# 1. Clone
-git clone https://github.com/AlexanderWhitestone/Timmy-time-dashboard.git
-cd Timmy-time-dashboard
-
-# 2. Install
-make install
-# or manually: python3 -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]"
-
-# 3. Start Ollama (separate terminal)
-ollama serve
-ollama pull llama3.1:8b-instruct  # Required for reliable tool calling
-
-# Note: llama3.1:8b-instruct is used instead of llama3.2 because it is
-# specifically fine-tuned for reliable tool/function calling.
-# llama3.2 (3B) was found to hallucinate tool output consistently in testing.
-# Fallback: qwen2.5:14b if llama3.1:8b-instruct is not available.
-
-# 4. Launch dashboard
-make dev
-# opens at http://localhost:8000
+```
+src/
+  config.py           # pydantic-settings — all env vars live here
+  timmy/              # Core agent (agent.py, backends.py, cli.py, prompts.py)
+  hands/              # Autonomous scheduled agents (registry, scheduler, runner)
+  dashboard/          # FastAPI app, routes, Jinja2 templates
+  swarm/              # Multi-agent: coordinator, registry, bidder, tasks, comms
+  timmy_serve/        # L402 proxy, payment handler, TTS, serve CLI
+  spark/              # Intelligence engine — events, predictions, advisory
+  creative/           # Creative director + video assembler pipeline
+  tools/              # Git, image, music, video tools for persona agents
+  lightning/          # Lightning backend abstraction (mock + LND)
+  agent_core/         # Substrate-agnostic agent interface
+  voice/              # NLU intent detection
+  ws_manager/         # WebSocket connection manager
+  notifications/      # Push notification store
+  shortcuts/          # Siri Shortcuts endpoints
+  telegram_bot/       # Telegram bridge
+  self_tdd/           # Continuous test watchdog
+hands/                # Hand manifests — oracle/, sentinel/, etc.
+tests/                # one test file per module, all mocked
+static/style.css      # Dark mission-control theme (JetBrains Mono)
+docs/                 # GitHub Pages landing page
+AGENTS.md             # AI agent development standards ← read this
+.env.example          # Environment variable reference
+Makefile              # Common dev commands
 ```
 
 ---
 
-## Common commands
-
-```bash
-make test       # run all tests (no Ollama needed)
-make test-cov   # test + coverage report
-make dev        # start dashboard (http://localhost:8000)
-make watch      # self-TDD watchdog (60s poll, alerts on regressions)
-```
-
-Or with the bootstrap script (creates venv, tests, watchdog, server in one shot):
-```bash
-bash activate_self_tdd.sh
-bash activate_self_tdd.sh --big-brain   # also installs AirLLM
-```
-
----
-
-## CLI
-
-```bash
-timmy chat "What is sovereignty?"
-timmy think "Bitcoin and self-custody"
-timmy status
-
-timmy-serve start          # L402-gated API server (port 8402)
-timmy-serve invoice        # generate a Lightning invoice
-timmy-serve status
-```
-
----
-
-## Mobile access
+## Mobile Access
 
 The dashboard is fully mobile-optimized (iOS safe area, 44px touch targets, 16px
 input to prevent zoom, momentum scroll).
@@ -162,7 +214,7 @@ channel = "telegram"
 
 ---
 
-## AirLLM — big brain backend
+## AirLLM — Big Brain Backend
 
 Run 70B or 405B models locally with no GPU, using AirLLM's layer-by-layer loading.
 Apple Silicon uses MLX automatically.
@@ -188,121 +240,39 @@ AIRLLM_MODEL_SIZE=70b
 
 ---
 
-## Configuration
+## CLI
 
 ```bash
-cp .env.example .env
-# edit .env
+timmy chat "What is sovereignty?"
+timmy think "Bitcoin and self-custody"
+timmy status
+
+timmy-serve start          # L402-gated API server (port 8402)
+timmy-serve invoice        # generate a Lightning invoice
+timmy-serve status
 ```
 
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `OLLAMA_URL` | `http://localhost:11434` | Ollama host |
-| `OLLAMA_MODEL` | `llama3.1:8b-instruct` | Model for tool calling. Use llama3.1:8b-instruct for reliable tool use; fallback to qwen2.5:14b |
-| `DEBUG` | `false` | Enable `/docs` and `/redoc` |
-| `TIMMY_MODEL_BACKEND` | `ollama` | `ollama` \| `airllm` \| `auto` |
-| `AIRLLM_MODEL_SIZE` | `70b` | `8b` \| `70b` \| `405b` |
-| `L402_HMAC_SECRET` | *(default — change in prod)* | HMAC signing key for macaroons |
-| `L402_MACAROON_SECRET` | *(default — change in prod)* | Macaroon secret |
-| `LIGHTNING_BACKEND` | `mock` | `mock` (production-ready) \| `lnd` (scaffolded, not yet functional) |
-
----
-
-## Architecture
-
-```
-Browser / Phone
-      │ HTTP + HTMX + WebSocket
-      ▼
-┌─────────────────────────────────────────┐
-│             FastAPI (dashboard.app)      │
-│  routes: agents, health, swarm,          │
-│          marketplace, voice, mobile      │
-└───┬─────────────┬──────────┬────────────┘
-    │             │          │
-    ▼             ▼          ▼
-Jinja2        Timmy       Swarm
-Templates     Agent       Coordinator
-(HTMX)        │           ├─ Registry (SQLite)
-              ├─ Ollama   ├─ AuctionManager (L402 bids)
-              └─ AirLLM   ├─ SwarmComms (Redis / in-memory)
-                          └─ SwarmManager (subprocess)
-    │
-    ├── Voice NLU + TTS (pyttsx3, local)
-    ├── WebSocket live feed (ws_manager)
-    ├── L402 Lightning proxy (macaroon + invoice)
-    ├── Push notifications (local + macOS native)
-    └── Siri Shortcuts API endpoints
-
-Persistence: timmy.db (Agno memory), data/swarm.db (registry + tasks)
-External:    Ollama :11434, optional Redis, optional LND gRPC
-```
-
----
-
-## Project layout
-
-```
-src/
-  config.py           # pydantic-settings — all env vars live here
-  timmy/              # Core agent (agent.py, backends.py, cli.py, prompts.py)
-  hands/              # Autonomous scheduled agents (registry, scheduler, runner)
-  dashboard/          # FastAPI app, routes, Jinja2 templates
-  swarm/              # Multi-agent: coordinator, registry, bidder, tasks, comms
-  timmy_serve/        # L402 proxy, payment handler, TTS, serve CLI
-  spark/              # Intelligence engine — events, predictions, advisory
-  creative/           # Creative director + video assembler pipeline
-  tools/              # Git, image, music, video tools for persona agents
-  lightning/          # Lightning backend abstraction (mock + LND)
-  agent_core/         # Substrate-agnostic agent interface
-  voice/              # NLU intent detection
-  ws_manager/         # WebSocket connection manager
-  notifications/      # Push notification store
-  shortcuts/          # Siri Shortcuts endpoints
-  telegram_bot/       # Telegram bridge
-  self_tdd/           # Continuous test watchdog
-hands/                # Hand manifests — oracle/, sentinel/, etc.
-tests/                # one test file per module, all mocked
-static/style.css      # Dark mission-control theme (JetBrains Mono)
-docs/                 # GitHub Pages landing page
-AGENTS.md             # AI agent development standards ← read this
-.env.example          # Environment variable reference
-Makefile              # Common dev commands
+Or with the bootstrap script (creates venv, tests, watchdog, server in one shot):
+```bash
+bash scripts/activate_self_tdd.sh
+bash scripts/activate_self_tdd.sh --big-brain   # also installs AirLLM
 ```
 
 ---
 
 ## Troubleshooting
 
-**`ollama: command not found`** — install from `brew install ollama` or ollama.com
-
-**`connection refused` in chat** — run `ollama serve` in a separate terminal
-
-**`ModuleNotFoundError: No module named 'sqlalchemy'`** — re-run install to pick up the updated `agno[sqlite]` dependency:
-`make install`
-
-**`ModuleNotFoundError: No module named 'dashboard'`** — activate the venv:
-`source .venv/bin/activate && pip install -e ".[dev]"`
-
-**Health panel shows DOWN** — Ollama isn't running; chat still works but returns
-the offline error message
-
-**L402 startup warnings** — set `L402_HMAC_SECRET` and `L402_MACAROON_SECRET` in
-`.env` to silence them (required for production)
-
----
-
-## For AI agents contributing to this repo
-
-Read [`AGENTS.md`](AGENTS.md).  It covers per-agent assignments, architecture
-patterns, coding conventions, and the v2→v3 roadmap.
+- **`ollama: command not found`** — `brew install ollama` or ollama.com
+- **`connection refused`** — run `ollama serve` first
+- **`ModuleNotFoundError`** — `source .venv/bin/activate && make install`
+- **Health panel shows DOWN** — Ollama isn't running; chat returns offline message
 
 ---
 
 ## Roadmap
 
-| Version | Name       | Status      | Milestone |
-|---------|------------|-------------|-----------|
-| 1.0.0   | Genesis    | ✅ Complete | Agno + Ollama + SQLite + Dashboard |
-| 2.0.0   | Exodus     | 🔄 In progress | Swarm + L402 + Voice + Marketplace + Hands |
-| 3.0.0   | Revelation | 📋 Planned  | Lightning treasury + single `.app` bundle |
+| Version | Name | Status |
+|---------|------|--------|
+| 1.0 | Genesis | Complete — Agno + Ollama + SQLite + Dashboard |
+| 2.0 | Exodus | In progress — Swarm + L402 + Voice + Marketplace + Hands |
+| 3.0 | Revelation | Planned — Lightning treasury + single `.app` bundle |
diff --git a/REFACTORING_PLAN.md b/REFACTORING_PLAN.md
new file mode 100644
index 00000000..3fc5914a
--- /dev/null
+++ b/REFACTORING_PLAN.md
@@ -0,0 +1,481 @@
+# Timmy Time — Architectural Refactoring Plan
+
+**Author:** Claude (VP Engineering review)
+**Date:** 2026-02-26
+**Branch:** `claude/plan-repo-refactoring-hgskF`
+
+---
+
+## Executive Summary
+
+The Timmy Time codebase has grown to **53K lines of Python** across **272
+files** (169 source + 103 test), **28 modules** in `src/`, **27 route files**,
+**49 templates**, **90 test files**, and **87KB of root-level markdown**. It
+works, but it's burning tokens, slowing down test runs, and making it hard to
+reason about change impact.
+
+This plan proposes **6 phases** of refactoring, ordered by impact and risk. Each
+phase is independently valuable — you can stop after any phase and still be
+better off.
+
+---
+
+## The Problems
+
+### 1. Monolith sprawl
+28 modules in `src/` with no grouping. Eleven modules aren't even included in
+the wheel build (`agents`, `events`, `hands`, `mcp`, `memory`, `router`,
+`self_coding`, `task_queue`, `tools`, `upgrades`, `work_orders`). Some are
+used by the dashboard routes but forgotten in `pyproject.toml`.
+
+### 2. Dashboard is the gravity well
+The dashboard has 27 route files (4,562 lines), 49 templates, and has become
+the integration point for everything. Every new feature = new route file + new
+template + new test file. This doesn't scale.
+
+### 3. Documentation entropy
+10 root-level `.md` files (87KB). README is 303 lines, CLAUDE.md is 267 lines,
+AGENTS.md is 342 lines — with massive content duplication between them. Plus
+PLAN.md, WORKSET_PLAN.md, WORKSET_PLAN_PHASE2.md, MEMORY.md,
+IMPLEMENTATION_SUMMARY.md, QUALITY_ANALYSIS.md, QUALITY_REVIEW_REPORT.md.
+Human eyes glaze over. AI assistants waste tokens reading redundant info.
+
+### 4. Test sprawl — and a skeleton problem
+97 test files, 19,600 lines — but **61 of those files (63%) are empty
+skeletons** with zero actual test functions. Only 36 files have real tests
+containing 471 test functions total. Many "large" test files (like
+`test_scripture.py` at 901 lines, `test_router_cascade.py` at 523 lines) are
+infrastructure-only — class definitions, imports, fixtures, but no assertions.
+The functional/E2E directory (`tests/functional/`) has 7 files and 0 working
+tests. Tests are flat in `tests/` with no organization. Running the full suite
+means loading every module, every mock, every fixture even when you only
+changed one thing.
+
+### 5. Unclear project boundaries
+Is this one project or several? The `timmy` CLI, `timmy-serve` API server,
+`self-tdd` watchdog, and `self-modify` CLI are four separate entry points that
+could be four separate packages. The `creative` extra needs PyTorch. The
+`lightning` module is a standalone payment system. These shouldn't live in the
+same test run.
+
+### 6. Wheel build doesn't match reality
+`pyproject.toml` includes 17 modules but `src/` has 28. The missing 11 modules
+are used by code that IS included (dashboard routes import from `hands`,
+`mcp`, `memory`, `work_orders`, etc.). The wheel would break at runtime.
+
+### 7. Dependency coupling through dashboard
+
+The dashboard is the hub that imports from 20+ modules. The dependency graph
+flows inward: `config` is the foundation (22 modules depend on it), `mcp` is
+widely used (12+ importers), `swarm` is referenced by 15+ modules. No true
+circular dependencies exist (the `timmy ↔ swarm` relationship uses lazy
+imports), but the dashboard pulls in everything, so changing any module can
+break the dashboard routes.
+
+### 8. Conftest does too much
+
+`tests/conftest.py` has 4 autouse fixtures that run on **every single test**:
+reset message log, reset coordinator state, clean database, cleanup event
+loops. Many tests don't need any of these. This adds overhead to the test
+suite and couples all tests to the swarm coordinator.
+
+---
+
+## Phase 1: Documentation Cleanup (Low Risk, High Impact)
+
+**Goal:** Cut root markdown from 87KB to ~20KB. Make README human-readable.
+Eliminate token waste.
+
+### 1.1 Slim the README
+
+Cut README.md from 303 lines to ~80 lines:
+
+```
+# Timmy Time — Mission Control
+
+Local-first sovereign AI agent system. Browser dashboard, Ollama inference,
+Bitcoin Lightning economics. No cloud AI.
+
+## Quick Start
+  make install && make dev  →  http://localhost:8000
+
+## What's Here
+  - Timmy Agent (Ollama/AirLLM)
+  - Mission Control Dashboard (FastAPI + HTMX)
+  - Swarm Coordinator (multi-agent auctions)
+  - Lightning Payments (L402 gating)
+  - Creative Studio (image/music/video)
+  - Self-Coding (codebase-aware self-modification)
+
+## Commands
+  make dev / make test / make docker-up / make help
+
+## Documentation
+  - Development guide: CLAUDE.md
+  - Architecture: docs/architecture-v2.md
+  - Agent conventions: AGENTS.md
+  - Config reference: .env.example
+```
+
+### 1.2 De-duplicate CLAUDE.md
+
+Remove content that duplicates README or AGENTS.md. CLAUDE.md should only
+contain what AI assistants need that isn't elsewhere:
+- Architecture patterns (singletons, config, HTMX, graceful degradation)
+- Testing conventions (conftest, fixtures, stubs)
+- Security-sensitive areas
+- Entry points table
+
+Target: 267 → ~130 lines.
+
+### 1.3 Archive or delete temporary docs
+
+| File | Action |
+|------|--------|
+| `MEMORY.md` | DELETE — session context, not permanent docs |
+| `WORKSET_PLAN.md` | DELETE — use GitHub Issues |
+| `WORKSET_PLAN_PHASE2.md` | DELETE — use GitHub Issues |
+| `PLAN.md` | MOVE to `docs/PLAN_ARCHIVE.md` |
+| `IMPLEMENTATION_SUMMARY.md` | MOVE to `docs/IMPLEMENTATION_ARCHIVE.md` |
+| `QUALITY_ANALYSIS.md` | CONSOLIDATE with `docs/QUALITY_AUDIT.md` |
+| `QUALITY_REVIEW_REPORT.md` | CONSOLIDATE with `docs/QUALITY_AUDIT.md` |
+
+**Result:** Root directory goes from 10 `.md` files to 3 (README, CLAUDE,
+AGENTS).
+
+### 1.4 Clean up .handoff/
+
+The `.handoff/` directory (CHECKPOINT.md, CONTINUE.md, TODO.md, scripts) is
+session-scoped context. Either gitignore it or move to `docs/handoff/`.
+
+---
+
+## Phase 2: Module Consolidation (Medium Risk, High Impact)
+
+**Goal:** Reduce 28 modules to ~12 by merging small, related modules into
+coherent packages. This directly reduces cognitive load and token consumption.
+
+### 2.1 Module structure (implemented)
+
+```
+src/                           # 14 packages (was 28)
+  config.py                    # Pydantic settings (foundation)
+
+  timmy/                       # Core agent + agents/ + agent_core/ + memory/
+  dashboard/                   # FastAPI web UI (22 route files)
+  swarm/                       # Coordinator + task_queue/ + work_orders/
+  self_coding/                 # Git safety + self_modify/ + self_tdd/ + upgrades/
+  creative/                    # Media generation + tools/
+  infrastructure/              # ws_manager/ + notifications/ + events/ + router/
+  integrations/                # chat_bridge/ + telegram_bot/ + shortcuts/ + voice/
+
+  lightning/                   # L402 payment gating (standalone, security-sensitive)
+  mcp/                         # MCP tool registry and discovery
+  spark/                       # Event capture and advisory
+  hands/                       # 6 autonomous Hand agents
+  scripture/                   # Biblical text integration
+  timmy_serve/                 # L402-gated API server
+```
+
+### 2.2 Dashboard route consolidation
+
+27 route files → ~12 by grouping related routes:
+
+| Current files | Merged into |
+|--------------|-------------|
+| `agents.py`, `briefing.py` | `agents.py` |
+| `swarm.py`, `swarm_internal.py`, `swarm_ws.py` | `swarm.py` |
+| `voice.py`, `voice_enhanced.py` | `voice.py` |
+| `mobile.py`, `mobile_test.py` | `mobile.py` (delete test page) |
+| `self_coding.py`, `self_modify.py` | `self_coding.py` |
+| `tasks.py`, `work_orders.py` | `tasks.py` |
+
+`mobile_test.py` (257 lines) is a test page route that's excluded from
+coverage — it should not ship in production.
+
+### 2.3 Fix the wheel build
+
+Update `pyproject.toml` `[tool.hatch.build.targets.wheel]` to include all
+modules that are actually imported. Currently 11 modules are missing from the
+build manifest.
+
+---
+
+## Phase 3: Test Reorganization (Medium Risk, Medium Impact)
+
+**Goal:** Organize tests to match module structure, enable selective test runs,
+reduce full-suite runtime.
+
+### 3.1 Mirror source structure in tests
+
+```
+tests/
+  conftest.py               # Global fixtures only
+  timmy/                    # Tests for timmy/ module
+    conftest.py             # Timmy-specific fixtures
+    test_agent.py
+    test_backends.py
+    test_cli.py
+    test_orchestrator.py
+    test_personas.py
+    test_memory.py
+  dashboard/
+    conftest.py             # Dashboard fixtures (client fixture)
+    test_routes_agents.py
+    test_routes_swarm.py
+    ...
+  swarm/
+    test_coordinator.py
+    test_tasks.py
+    test_work_orders.py
+  integrations/
+    test_chat_bridge.py
+    test_telegram.py
+    test_voice.py
+  self_coding/
+    test_git_safety.py
+    test_codebase_indexer.py
+    test_self_modify.py
+  ...
+```
+
+### 3.2 Add pytest marks for selective execution
+
+```python
+# pyproject.toml
+[tool.pytest.ini_options]
+markers = [
+    "unit: Unit tests (fast, no I/O)",
+    "integration: Integration tests (may use SQLite)",
+    "dashboard: Dashboard route tests",
+    "swarm: Swarm coordinator tests",
+    "slow: Tests that take >1 second",
+]
+```
+
+Usage:
+```bash
+make test                    # Run all tests
+pytest -m unit               # Fast unit tests only
+pytest -m dashboard          # Just dashboard tests
+pytest tests/swarm/          # Just swarm module tests
+pytest -m "not slow"         # Skip slow tests
+```
+
+### 3.3 Audit and clean skeleton test files
+
+61 test files are empty skeletons — they have imports, class definitions, and
+fixture setup but **zero test functions**. These add import overhead and create
+a false sense of coverage. For each skeleton file:
+
+1. If the module it tests is stable and well-covered elsewhere → **delete it**
+2. If the module genuinely needs tests → **implement the tests** or file an
+   issue
+3. If it's a duplicate (e.g., both `test_swarm.py` and
+   `test_swarm_integration.py` exist) → **consolidate**
+
+Notable skeletons to address:
+- `test_scripture.py` (901 lines, 0 tests) — massive infrastructure, no assertions
+- `test_router_cascade.py` (523 lines, 0 tests) — same pattern
+- `test_agent_core.py` (457 lines, 0 tests)
+- `test_self_modify.py` (451 lines, 0 tests)
+- All 7 files in `tests/functional/` (0 working tests)
+
+### 3.4 Split genuinely oversized test files
+
+For files that DO have tests but are too large:
+- `test_task_queue.py` (560 lines, 30 tests) → split by feature area
+- `test_mobile_scenarios.py` (339 lines, 36 tests) → split by scenario group
+
+Rule of thumb: No test file over 400 lines.
+
+---
+
+## Phase 4: Configuration & Build Cleanup (Low Risk, Medium Impact)
+
+### 4.1 Clean up pyproject.toml
+
+- Fix the wheel include list to match actual imports
+- Consider whether 4 separate CLI entry points belong in one package
+- Add `[project.urls]` for documentation, repository links
+- Review dependency pins — some are very loose (`>=1.0.0`)
+
+### 4.2 Consolidate Docker files
+
+4 docker-compose variants (default, dev, prod, test) is a lot. Consider:
+- `docker-compose.yml` (base)
+- `docker-compose.override.yml` (dev — auto-loaded by Docker)
+- `docker-compose.prod.yml` (production only)
+
+### 4.3 Clean up root directory
+
+Non-essential root files to move or delete:
+
+| File | Action |
+|------|--------|
+| `apply_security_fixes.py` | Move to `scripts/` or delete if one-time |
+| `activate_self_tdd.sh` | Move to `scripts/` |
+| `coverage.xml` | Gitignore (CI artifact) |
+| `data/self_modify_reports/` | Gitignore the contents |
+
+---
+
+## Phase 5: Consider Package Extraction (High Risk, High Impact)
+
+**Goal:** Evaluate whether some modules should be separate packages/repos.
+
+### 5.1 Candidates for extraction
+
+| Module | Why extract | Dependency direction |
+|--------|------------|---------------------|
+| `lightning/` | Standalone payment system, security-sensitive | Dashboard imports lightning |
+| `creative/` | Needs PyTorch, very different dependency profile | Dashboard imports creative |
+| `timmy-serve` | Separate process (port 8402), separate purpose | Shares config + timmy agent |
+| `self_coding/` + `self_modify/` | Self-contained self-modification system | Dashboard imports for routes |
+
+### 5.2 Monorepo approach (recommended over multi-repo)
+
+If splitting, use a monorepo with namespace packages:
+
+```
+packages/
+  timmy-core/          # Agent + memory + CLI
+  timmy-dashboard/     # FastAPI app
+  timmy-swarm/         # Coordinator + tasks
+  timmy-lightning/     # Payment system
+  timmy-creative/      # Creative tools (heavy deps)
+```
+
+Each package gets its own `pyproject.toml`, test suite, and can be installed
+independently. But they share the same repo, CI, and release cycle.
+
+**However:** This is high effort and may not be worth it unless the team
+grows or the dependency profiles diverge further. Consider this only after
+Phases 1-4 are done and the pain persists.
+
+---
+
+## Phase 6: Token Optimization for AI Development (Low Risk, High Impact)
+
+**Goal:** Reduce context window consumption when AI assistants work on this
+codebase.
+
+### 6.1 Lean CLAUDE.md (already covered in Phase 1)
+
+Every byte in CLAUDE.md is read by every AI interaction. Remove duplication.
+
+### 6.2 Module-level CLAUDE.md files
+
+Instead of one massive guide, put module-specific context where it's needed:
+
+```
+src/swarm/CLAUDE.md        # "This module is security-sensitive. Always..."
+src/lightning/CLAUDE.md    # "Never hard-code secrets. Use settings..."
+src/dashboard/CLAUDE.md   # "Routes return template partials for HTMX..."
+```
+
+AI assistants read these only when working in that directory.
+
+### 6.3 Standardize module docstrings
+
+Every `__init__.py` should have a one-line summary. AI assistants read these
+to understand module purpose without reading every file:
+
+```python
+"""Swarm — Multi-agent coordinator with auction-based task assignment."""
+```
+
+### 6.4 Reduce template duplication
+
+49 templates with repeated boilerplate. Consider Jinja2 macros for common
+patterns (card layouts, form groups, table rows).
+
+---
+
+## Prioritized Execution Order
+
+| Priority | Phase | Effort | Risk | Impact |
+|----------|-------|--------|------|--------|
+| **1** | Phase 1: Doc cleanup | 2-3 hours | Low | High — immediate token savings |
+| **2** | Phase 6: Token optimization | 1-2 hours | Low | High — ongoing AI efficiency |
+| **3** | Phase 4: Config/build cleanup | 1-2 hours | Low | Medium — hygiene |
+| **4** | Phase 2: Module consolidation | 4-8 hours | Medium | High — structural improvement |
+| **5** | Phase 3: Test reorganization | 3-5 hours | Medium | Medium — faster test cycles |
+| **6** | Phase 5: Package extraction | 8-16 hours | High | High — only if needed |
+
+---
+
+## Quick Wins (Can Do Right Now)
+
+1. Delete MEMORY.md, WORKSET_PLAN.md, WORKSET_PLAN_PHASE2.md (3 files, 0 risk)
+2. Move PLAN.md, IMPLEMENTATION_SUMMARY.md, quality docs to `docs/` (5 files)
+3. Slim README to ~80 lines
+4. Fix pyproject.toml wheel includes (11 missing modules)
+5. Gitignore `coverage.xml` and `data/self_modify_reports/`
+6. Delete `dashboard/routes/mobile_test.py` (test page in production routes)
+7. Delete or gut empty test skeletons (61 files with 0 tests — they waste CI
+   time and create noise)
+
+---
+
+## What NOT to Do
+
+- **Don't rewrite from scratch.** The code works. Refactor incrementally.
+- **Don't split into multiple repos.** Monorepo with packages (if needed) is
+  simpler for a small team.
+- **Don't change the tech stack.** FastAPI + HTMX + Jinja2 is fine. Don't add
+  React, Vue, or a SPA framework.
+- **Don't merge CLAUDE.md into README.** They serve different audiences.
+- **Don't remove test files** just to reduce count. Reorganize them.
+- **Don't break the singleton pattern.** It works for this scale.
+
+---
+
+## Success Metrics
+
+| Metric | Original | Target | Current |
+|--------|----------|--------|---------|
+| Root `.md` files | 10 | 3 | 5 |
+| Root markdown size | 87KB | ~20KB | ~28KB |
+| `src/` modules | 28 | ~12-15 | **14** |
+| Dashboard routes | 27 | ~12-15 | 22 |
+| Test organization | flat | mirrored | **mirrored** |
+| Tests passing | 471 | 500+ | **1462** |
+| Wheel modules | 17/28 | all | **all** |
+| Module-level docs | 0 | all key modules | **6** |
+| AI context reduction | — | ~40% | **~50%** (fewer modules to scan) |
+
+---
+
+## Execution Status
+
+### Completed
+
+- [x] **Phase 1: Doc cleanup** — README 303→93 lines, CLAUDE.md 267→80,
+  AGENTS.md 342→72, deleted 3 session docs, archived 4 planning docs
+- [x] **Phase 4: Config/build cleanup** — fixed 11 missing wheel modules, added
+  pytest markers, updated .gitignore, moved scripts to scripts/
+- [x] **Phase 6: Token optimization** — added docstrings to 15+ __init__.py files
+- [x] **Phase 3: Test reorganization** — 97 test files organized into 13
+  subdirectories mirroring source structure
+- [x] **Phase 2a: Route consolidation** — 27 → 22 route files (merged voice,
+  swarm internal/ws, self-modify; deleted mobile_test)
+
+- [x] **Phase 2b: Full module consolidation** — 28 → 14 modules. All merges
+  completed in a single pass with automated import rewriting (66 source files +
+  13 test files updated). Modules consolidated:
+  - `work_orders/` + `task_queue/` → `swarm/`
+  - `self_modify/` + `self_tdd/` + `upgrades/` → `self_coding/`
+  - `tools/` → `creative/tools/`
+  - `chat_bridge/` + `telegram_bot/` + `shortcuts/` + `voice/` → `integrations/` (new)
+  - `ws_manager/` + `notifications/` + `events/` + `router/` → `infrastructure/` (new)
+  - `agents/` + `agent_core/` + `memory/` → `timmy/`
+  - pyproject.toml entry points and wheel includes updated
+  - Module-level CLAUDE.md files added (Phase 6.2)
+  - Zero test regressions: 1462 tests passing
+- [x] **Phase 6.2: Module-level CLAUDE.md** — added to swarm/, self_coding/,
+  infrastructure/, integrations/, creative/, lightning/
+
+### Remaining
+
+- [ ] **Phase 5: Package extraction** — only if team grows or dep profiles diverge
diff --git a/WORKSET_PLAN.md b/WORKSET_PLAN.md
deleted file mode 100644
index 6b690a7c..00000000
--- a/WORKSET_PLAN.md
+++ /dev/null
@@ -1,147 +0,0 @@
-# Timmy Time — Workset Plan (Post-Quality Review)
-
-**Date:** 2026-02-25  
-**Based on:** QUALITY_ANALYSIS.md + QUALITY_REVIEW_REPORT.md
-
----
-
-## Executive Summary
-
-This workset addresses critical security vulnerabilities, hardens the tool system for reliability, improves privacy alignment with the "sovereign AI" vision, and enhances agent intelligence.
-
----
-
-## Workset A: Security Fixes (P0) 🔒
-
-### A1: XSS Vulnerabilities (SEC-01)
-**Priority:** P0 — Critical  
-**Files:** `mobile.html`, `swarm_live.html`
-
-**Issues:**
-- `mobile.html` line ~85 uses raw `innerHTML` with unsanitized user input
-- `swarm_live.html` line ~72 uses `innerHTML` with WebSocket agent data
-
-**Fix:** Replace `innerHTML` string interpolation with safe DOM methods (`textContent`, `createTextNode`, or DOMPurify if available).
-
-### A2: Hardcoded Secrets (SEC-02)
-**Priority:** P1 — High  
-**Files:** `l402_proxy.py`, `payment_handler.py`
-
-**Issue:** Default secrets are production-safe strings instead of `None` with startup assertion.
-
-**Fix:** 
-- Change defaults to `None`
-- Add startup assertion requiring env vars to be set
-- Fail fast with clear error message
-
----
-
-## Workset B: Tool System Hardening ⚙️
-
-### B1: SSL Certificate Fix
-**Priority:** P1 — High  
-**File:** Web search via DuckDuckGo
-
-**Issue:** `CERTIFICATE_VERIFY_FAILED` errors prevent web search from working.
-
-**Fix Options:**
-- Option 1: Use `certifi` package for proper certificate bundle
-- Option 2: Add `verify_ssl=False` parameter (less secure, acceptable for local)
-- Option 3: Document SSL fix in troubleshooting
-
-### B2: Tool Usage Instructions
-**Priority:** P2 — Medium  
-**File:** `prompts.py`
-
-**Issue:** Agent makes unnecessary tool calls for simple questions.
-
-**Fix:** Add tool usage instructions to system prompt:
-- Only use tools when explicitly needed
-- For simple chat/questions, respond directly
-- Tools are for: web search, file operations, code execution
-
-### B3: Tool Error Handling
-**Priority:** P2 — Medium  
-**File:** `tools.py`
-
-**Issue:** Tool failures show stack traces to user.
-
-**Fix:** Add graceful error handling with user-friendly messages.
-
----
-
-## Workset C: Privacy & Sovereignty 🛡️
-
-### C1: Agno Telemetry (Privacy)
-**Priority:** P2 — Medium  
-**File:** `agent.py`, `backends.py`
-
-**Issue:** Agno sends telemetry to `os-api.agno.com` which conflicts with "sovereign" vision.
-
-**Fix:**
-- Add `telemetry_enabled=False` parameter to Agent
-- Document how to disable for air-gapped deployments
-- Consider environment variable `TIMMY_TELEMETRY=0`
-
-### C2: Secrets Validation
-**Priority:** P1 — High  
-**File:** `config.py`, startup
-
-**Issue:** Default secrets used without warning in production.
-
-**Fix:**
-- Add production mode detection
-- Fatal error if default secrets in production
-- Clear documentation on generating secrets
-
----
-
-## Workset D: Agent Intelligence 🧠
-
-### D1: Enhanced System Prompt
-**Priority:** P2 — Medium  
-**File:** `prompts.py`
-
-**Enhancements:**
-- Tool usage guidelines (when to use, when not to)
-- Memory awareness ("You remember previous conversations")
-- Self-knowledge (capabilities, limitations)
-- Response style guidelines
-
-### D2: Memory Improvements
-**Priority:** P2 — Medium  
-**File:** `agent.py`
-
-**Enhancements:**
-- Increase history runs from 10 to 20 for better context
-- Add memory summarization for very long conversations
-- Persistent session tracking
-
----
-
-## Execution Order
-
-| Order | Workset | Task | Est. Time |
-|-------|---------|------|-----------|
-| 1 | A | XSS fixes | 30 min |
-| 2 | A | Secrets hardening | 20 min |
-| 3 | B | SSL certificate fix | 15 min |
-| 4 | B | Tool instructions | 20 min |
-| 5 | C | Telemetry disable | 15 min |
-| 6 | C | Secrets validation | 20 min |
-| 7 | D | Enhanced prompts | 30 min |
-| 8 | — | Test everything | 30 min |
-
-**Total: ~3 hours**
-
----
-
-## Success Criteria
-
-- [ ] No XSS vulnerabilities (verified by code review)
-- [ ] Secrets fail fast in production
-- [ ] Web search works without SSL errors
-- [ ] Agent uses tools appropriately (not for simple chat)
-- [ ] Telemetry disabled by default
-- [ ] All 895+ tests pass
-- [ ] New tests added for security fixes
diff --git a/WORKSET_PLAN_PHASE2.md b/WORKSET_PLAN_PHASE2.md
deleted file mode 100644
index 2c9355ed..00000000
--- a/WORKSET_PLAN_PHASE2.md
+++ /dev/null
@@ -1,133 +0,0 @@
-# Timmy Time — Workset Plan Phase 2 (Functional Hardening)
-
-**Date:** 2026-02-25  
-**Based on:** QUALITY_ANALYSIS.md remaining issues
-
----
-
-## Executive Summary
-
-This workset addresses the core functional gaps that prevent the swarm system from operating as designed. The swarm currently registers agents in the database but doesn't actually spawn processes or execute bids. This workset makes the swarm operational.
-
----
-
-## Workset E: Swarm System Realization 🐝
-
-### E1: Real Agent Process Spawning (FUNC-01)
-**Priority:** P1 — High  
-**Files:** `swarm/agent_runner.py`, `swarm/coordinator.py`
-
-**Issue:** `spawn_agent()` creates a database record but no Python process is actually launched.
-
-**Fix:**
-- Complete the `agent_runner.py` subprocess implementation
-- Ensure spawned agents can communicate with coordinator
-- Add proper lifecycle management (start, monitor, stop)
-
-### E2: Working Auction System (FUNC-02)
-**Priority:** P1 — High  
-**Files:** `swarm/bidder.py`, `swarm/persona_node.py`
-
-**Issue:** Bidding system runs auctions but no actual agents submit bids.
-
-**Fix:**
-- Connect persona agents to the bidding system
-- Implement automatic bid generation based on capabilities
-- Ensure auction resolution assigns tasks to winners
-
-### E3: Persona Agent Auto-Bidding
-**Priority:** P1 — High  
-**Files:** `swarm/persona_node.py`, `swarm/coordinator.py`
-
-**Fix:**
-- Spawned persona agents should automatically bid on matching tasks
-- Implement capability-based bid decisions
-- Add bid amount calculation (base + jitter)
-
----
-
-## Workset F: Testing & Reliability 🧪
-
-### F1: WebSocket Reconnection Tests (TEST-01)
-**Priority:** P2 — Medium  
-**Files:** `tests/test_websocket.py`
-
-**Issue:** WebSocket tests don't cover reconnection logic or malformed payloads.
-
-**Fix:**
-- Add reconnection scenario tests
-- Test malformed payload handling
-- Test connection failure recovery
-
-### F2: Voice TTS Graceful Degradation
-**Priority:** P2 — Medium  
-**Files:** `timmy_serve/voice_tts.py`, `dashboard/routes/voice.py`
-
-**Issue:** Voice routes fail without clear message when `pyttsx3` not installed.
-
-**Fix:**
-- Add graceful fallback message
-- Return helpful error suggesting `pip install ".[voice]"`
-- Don't crash, return 503 with instructions
-
-### F3: Mobile Route Navigation
-**Priority:** P2 — Medium  
-**Files:** `templates/base.html`
-
-**Issue:** `/mobile` route not linked from desktop navigation.
-
-**Fix:**
-- Add mobile link to base template nav
-- Make it easy to find mobile-optimized view
-
----
-
-## Workset G: Performance & Architecture ⚡
-
-### G1: SQLite Connection Pooling (PERF-01)
-**Priority:** P3 — Low  
-**Files:** `swarm/registry.py`
-
-**Issue:** New SQLite connection opened on every query.
-
-**Fix:**
-- Implement connection pooling or singleton pattern
-- Reduce connection overhead
-- Maintain thread safety
-
-### G2: Development Experience
-**Priority:** P2 — Medium  
-**Files:** `Makefile`, `README.md`
-
-**Issue:** No single command to start full dev environment.
-
-**Fix:**
-- Add `make dev-full` that starts dashboard + Ollama check
-- Add better startup validation
-
----
-
-## Execution Order
-
-| Order | Workset | Task | Est. Time |
-|-------|---------|------|-----------|
-| 1 | E | Persona auto-bidding system | 45 min |
-| 2 | E | Fix auction resolution | 30 min |
-| 3 | F | Voice graceful degradation | 20 min |
-| 4 | F | Mobile nav link | 10 min |
-| 5 | G | SQLite connection pooling | 30 min |
-| 6 | — | Test everything | 30 min |
-
-**Total: ~2.5 hours**
-
----
-
-## Success Criteria
-
-- [ ] Persona agents automatically bid on matching tasks
-- [ ] Auctions resolve with actual winners
-- [ ] Voice routes degrade gracefully without pyttsx3
-- [ ] Mobile route accessible from desktop nav
-- [ ] SQLite connections pooled/reused
-- [ ] All 895+ tests pass
-- [ ] New tests for bidding system
diff --git a/config/providers.yaml b/config/providers.yaml
index 90630484..f078eacc 100644
--- a/config/providers.yaml
+++ b/config/providers.yaml
@@ -68,6 +68,37 @@ providers:
       - name: claude-3-sonnet-20240229
         context_window: 200000
 
+# ── Custom Models ──────────────────────────────────────────────────────
+# Register custom model weights for per-agent assignment.
+# Supports GGUF (Ollama), safetensors, and HuggingFace checkpoint dirs.
+# Models can also be registered at runtime via the /api/v1/models API.
+#
+# Roles: general (default inference), reward (PRM scoring),
+#        teacher (distillation), judge (output evaluation)
+custom_models: []
+  # Example entries:
+  # - name: my-finetuned-llama
+  #   format: gguf
+  #   path: /path/to/model.gguf
+  #   role: general
+  #   context_window: 8192
+  #   description: "Fine-tuned Llama for code tasks"
+  #
+  # - name: reward-model
+  #   format: ollama
+  #   path: deepseek-r1:1.5b
+  #   role: reward
+  #   context_window: 32000
+  #   description: "Process reward model for scoring outputs"
+
+# ── Agent Model Assignments ─────────────────────────────────────────────
+# Map persona agent IDs to specific models.
+# Agents without an assignment use the global default (ollama_model).
+agent_model_assignments: {}
+  # Example:
+  # persona-forge: my-finetuned-llama
+  # persona-echo: deepseek-r1:1.5b
+
 # Cost tracking (optional, for budget monitoring)
 cost_tracking:
   enabled: true
diff --git a/docker-compose.yml b/docker-compose.yml
index 91180830..c19bd55b 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -32,6 +32,10 @@ services:
       DEBUG: "true"
       # Point to host Ollama (Mac default).  Override in .env if different.
       OLLAMA_URL: "${OLLAMA_URL:-http://host.docker.internal:11434}"
+      # Grok (xAI) — opt-in premium cloud backend
+      GROK_ENABLED: "${GROK_ENABLED:-false}"
+      XAI_API_KEY: "${XAI_API_KEY:-}"
+      GROK_DEFAULT_MODEL: "${GROK_DEFAULT_MODEL:-grok-3-fast}"
     extra_hosts:
       - "host.docker.internal:host-gateway"  # Linux compatibility
     networks:
diff --git a/IMPLEMENTATION_SUMMARY.md b/docs/IMPLEMENTATION_ARCHIVE.md
similarity index 100%
rename from IMPLEMENTATION_SUMMARY.md
rename to docs/IMPLEMENTATION_ARCHIVE.md
diff --git a/PLAN.md b/docs/PLAN_ARCHIVE.md
similarity index 100%
rename from PLAN.md
rename to docs/PLAN_ARCHIVE.md
diff --git a/QUALITY_ANALYSIS.md b/docs/QUALITY_ANALYSIS.md
similarity index 100%
rename from QUALITY_ANALYSIS.md
rename to docs/QUALITY_ANALYSIS.md
diff --git a/QUALITY_REVIEW_REPORT.md b/docs/QUALITY_REVIEW_REPORT.md
similarity index 100%
rename from QUALITY_REVIEW_REPORT.md
rename to docs/QUALITY_REVIEW_REPORT.md
diff --git a/docs/index.html b/docs/index.html
index f3562842..515c5a28 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -1,926 +1,534 @@
 <!DOCTYPE html>
 <html lang="en">
 <head>
-  <meta charset="UTF-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
-  <title>Timmy Time — Mission Control</title>
-  <link rel="preconnect" href="https://fonts.googleapis.com" />
-  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;600;700&display=swap" rel="stylesheet" />
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover">
+  <title>Timmy</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;600;700&display=swap" rel="stylesheet">
   <style>
-    /* ── Reset & base ────────────────────────────────────────────────────── */
     *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
 
     :root {
-      --bg-deep:     #060d14;
-      --bg-panel:    #0c1824;
-      --bg-card:     #0f2030;
-      --border:      #1a3a55;
-      --border-glow: #1e4d72;
-      --text:        #b8d0e8;
-      --text-dim:    #4a7a9a;
-      --text-bright: #ddeeff;
-      --green:       #00e87a;
-      --amber:       #ffb800;
-      --red:         #ff4455;
-      --blue:        #00aaff;
-      --purple:      #aa77ff;
-      --font:        'JetBrains Mono', monospace;
+      --bg:      #080412;
+      --bg-msg:  #110820;
+      --bg-user: #1a0e30;
+      --border:  #2a1545;
+      --text:    #c8b0e0;
+      --dim:     #6b4a8a;
+      --bright:  #ede0ff;
+      --accent:  #ff7a2a;
+      --green:   #00e87a;
+      --red:     #ff4455;
+      --font:    'JetBrains Mono', monospace;
     }
 
-    html { scroll-behavior: smooth; }
-
-    body {
-      background: var(--bg-deep);
+    html, body {
+      height: 100%;
+      overflow: hidden;
+      background: var(--bg);
       color: var(--text);
       font-family: var(--font);
       font-size: 14px;
-      line-height: 1.7;
-      min-height: 100vh;
-      overflow-x: hidden;
+      line-height: 1.6;
+      touch-action: pan-y;
+      overscroll-behavior: none;
+      -webkit-text-size-adjust: 100%;
     }
 
-    a { color: var(--blue); text-decoration: none; }
-    a:hover { text-decoration: underline; }
-
-    /* ── Scanline overlay ────────────────────────────────────────────────── */
-    body::before {
-      content: '';
-      position: fixed;
-      inset: 0;
-      background: repeating-linear-gradient(
-        0deg,
-        transparent,
-        transparent 2px,
-        rgba(0, 170, 255, 0.012) 2px,
-        rgba(0, 170, 255, 0.012) 4px
-      );
-      pointer-events: none;
-      z-index: 999;
-    }
-
-    /* ── Header ──────────────────────────────────────────────────────────── */
-    header {
-      border-bottom: 1px solid var(--border);
-      background: var(--bg-panel);
-      padding: 0 2rem;
+    /* ── Full-screen layout ── */
+    #app {
       display: flex;
-      align-items: center;
-      justify-content: space-between;
-      height: 56px;
-      position: sticky;
-      top: 0;
-      z-index: 100;
-    }
-
-    .logo {
-      font-size: 13px;
-      font-weight: 700;
-      color: var(--blue);
-      letter-spacing: 0.15em;
-      text-transform: uppercase;
-    }
-
-    .logo span { color: var(--text-dim); }
-
-    nav { display: flex; gap: 1.5rem; align-items: center; }
-    nav a {
-      color: var(--text-dim);
-      font-size: 12px;
-      letter-spacing: 0.08em;
-      text-transform: uppercase;
-      transition: color 0.2s;
-    }
-    nav a:hover { color: var(--blue); text-decoration: none; }
-
-    .btn-primary {
-      background: var(--blue);
-      color: #000;
-      font-family: var(--font);
-      font-size: 12px;
-      font-weight: 700;
-      letter-spacing: 0.08em;
-      text-transform: uppercase;
-      padding: 8px 18px;
-      border: none;
-      cursor: pointer;
-      transition: background 0.2s, box-shadow 0.2s;
-      display: inline-block;
-    }
-    .btn-primary:hover {
-      background: #33bbff;
-      box-shadow: 0 0 16px rgba(0, 170, 255, 0.4);
-      text-decoration: none;
-    }
-
-    /* ── Hero ────────────────────────────────────────────────────────────── */
-    .hero {
-      padding: 7rem 2rem 5rem;
-      text-align: center;
-      position: relative;
+      flex-direction: column;
+      height: 100%;
+      height: 100dvh;
+      max-width: 720px;
+      margin: 0 auto;
       overflow: hidden;
     }
 
-    .hero::before {
-      content: '';
-      position: absolute;
-      top: -80px;
-      left: 50%;
-      transform: translateX(-50%);
-      width: 600px;
-      height: 600px;
-      background: radial-gradient(circle, rgba(0, 170, 255, 0.08) 0%, transparent 70%);
-      pointer-events: none;
-    }
-
-    .hero-label {
-      font-size: 11px;
-      letter-spacing: 0.25em;
-      color: var(--blue);
-      text-transform: uppercase;
-      margin-bottom: 1.5rem;
-    }
-
-    .hero h1 {
-      font-size: clamp(2rem, 6vw, 4.5rem);
-      font-weight: 700;
-      color: var(--text-bright);
-      letter-spacing: -0.02em;
-      line-height: 1.1;
-      margin-bottom: 1rem;
-    }
-
-    .hero h1 em {
-      font-style: normal;
-      color: var(--blue);
-    }
-
-    .hero-sub {
-      font-size: clamp(13px, 2vw, 16px);
-      color: var(--text-dim);
-      max-width: 560px;
-      margin: 0 auto 2.5rem;
-    }
-
-    .hero-badges {
-      display: flex;
-      gap: 0.75rem;
-      justify-content: center;
-      flex-wrap: wrap;
-      margin-bottom: 2.5rem;
-    }
-
-    .badge {
-      font-size: 11px;
-      letter-spacing: 0.05em;
-      padding: 4px 12px;
-      border: 1px solid var(--border-glow);
-      color: var(--text-dim);
-      background: var(--bg-panel);
-    }
-
-    .badge.green  { border-color: var(--green);  color: var(--green); }
-    .badge.amber  { border-color: var(--amber);  color: var(--amber); }
-    .badge.blue   { border-color: var(--blue);   color: var(--blue); }
-    .badge.purple { border-color: var(--purple); color: var(--purple); }
-
-    .hero-cta { display: flex; gap: 1rem; justify-content: center; flex-wrap: wrap; }
-
-    .btn-ghost {
-      border: 1px solid var(--border-glow);
-      color: var(--text);
-      font-family: var(--font);
-      font-size: 12px;
-      font-weight: 600;
-      letter-spacing: 0.08em;
-      text-transform: uppercase;
-      padding: 8px 18px;
-      background: transparent;
-      cursor: pointer;
-      transition: border-color 0.2s, color 0.2s;
-      display: inline-block;
-    }
-    .btn-ghost:hover {
-      border-color: var(--blue);
-      color: var(--blue);
-      text-decoration: none;
-    }
-
-    /* ── Stats bar ───────────────────────────────────────────────────────── */
-    .stats {
-      display: flex;
-      justify-content: center;
-      gap: 0;
-      border-top: 1px solid var(--border);
-      border-bottom: 1px solid var(--border);
-      background: var(--bg-panel);
-    }
-
-    .stat {
-      flex: 1;
-      max-width: 200px;
-      padding: 1.5rem 1rem;
-      text-align: center;
-      border-right: 1px solid var(--border);
-    }
-    .stat:last-child { border-right: none; }
-
-    .stat-number {
-      font-size: 2rem;
-      font-weight: 700;
-      color: var(--blue);
-      line-height: 1;
-      margin-bottom: 0.25rem;
-    }
-
-    .stat-label {
-      font-size: 11px;
-      letter-spacing: 0.1em;
-      text-transform: uppercase;
-      color: var(--text-dim);
-    }
-
-    /* ── Section layout ──────────────────────────────────────────────────── */
-    section { padding: 5rem 2rem; max-width: 1100px; margin: 0 auto; }
-
-    .section-label {
-      font-size: 11px;
-      letter-spacing: 0.2em;
-      text-transform: uppercase;
-      color: var(--blue);
-      margin-bottom: 0.75rem;
-    }
-
-    section h2 {
-      font-size: clamp(1.4rem, 3vw, 2.2rem);
-      font-weight: 700;
-      color: var(--text-bright);
-      margin-bottom: 1rem;
-    }
-
-    .section-intro {
-      color: var(--text-dim);
-      max-width: 620px;
-      margin-bottom: 3rem;
-    }
-
-    /* ── Feature grid ────────────────────────────────────────────────────── */
-    .feature-grid {
-      display: grid;
-      grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
-      gap: 1px;
-      border: 1px solid var(--border);
-      background: var(--border);
-    }
-
-    .feature-card {
-      background: var(--bg-panel);
-      padding: 2rem;
-      transition: background 0.2s;
-    }
-    .feature-card:hover { background: var(--bg-card); }
-
-    .feature-icon {
-      font-size: 1.5rem;
-      margin-bottom: 1rem;
-      display: block;
-    }
-
-    .feature-card h3 {
-      font-size: 14px;
-      font-weight: 700;
-      color: var(--text-bright);
-      margin-bottom: 0.5rem;
-      letter-spacing: 0.05em;
-      text-transform: uppercase;
-    }
-
-    .feature-card p {
-      font-size: 13px;
-      color: var(--text-dim);
-      line-height: 1.6;
-    }
-
-    .feature-tag {
-      display: inline-block;
-      font-size: 10px;
-      letter-spacing: 0.08em;
-      text-transform: uppercase;
-      padding: 2px 8px;
-      margin-top: 0.75rem;
-      border: 1px solid var(--border);
-      color: var(--text-dim);
-    }
-
-    /* ── Architecture ────────────────────────────────────────────────────── */
-    .arch-wrap {
-      border: 1px solid var(--border);
-      background: var(--bg-panel);
-      padding: 2rem;
-      overflow-x: auto;
-    }
-
-    .arch-wrap pre {
-      font-family: var(--font);
-      font-size: 12px;
-      color: var(--text);
-      line-height: 1.6;
-      white-space: pre;
-    }
-
-    .arch-wrap pre .hl-blue   { color: var(--blue); }
-    .arch-wrap pre .hl-green  { color: var(--green); }
-    .arch-wrap pre .hl-amber  { color: var(--amber); }
-    .arch-wrap pre .hl-purple { color: var(--purple); }
-    .arch-wrap pre .hl-dim    { color: var(--text-dim); }
-
-    /* ── Quickstart ──────────────────────────────────────────────────────── */
-    .quickstart-steps { display: flex; flex-direction: column; gap: 1.5rem; }
-
-    .step {
-      display: grid;
-      grid-template-columns: 48px 1fr;
-      gap: 1.25rem;
-      align-items: start;
-    }
-
-    .step-num {
-      width: 48px;
-      height: 48px;
-      border: 1px solid var(--border-glow);
+    /* ── Header ── */
+    #header {
+      flex-shrink: 0;
       display: flex;
       align-items: center;
-      justify-content: center;
-      font-weight: 700;
-      color: var(--blue);
-      font-size: 16px;
-      flex-shrink: 0;
+      justify-content: space-between;
+      padding: 12px 16px;
+      border-bottom: 1px solid var(--border);
     }
 
-    .step h4 {
+    #header h1 {
       font-size: 13px;
       font-weight: 700;
-      color: var(--text-bright);
-      margin-bottom: 0.5rem;
-      text-transform: uppercase;
-      letter-spacing: 0.05em;
+      letter-spacing: 0.2em;
+      color: var(--accent);
     }
 
-    .step p { font-size: 13px; color: var(--text-dim); margin-bottom: 0.5rem; }
-
-    code {
-      background: var(--bg-card);
-      border: 1px solid var(--border);
-      padding: 0.15em 0.5em;
-      font-family: var(--font);
-      font-size: 12px;
-      color: var(--green);
-    }
-
-    pre.codeblock {
-      background: var(--bg-card);
-      border: 1px solid var(--border);
-      padding: 1.25rem 1.5rem;
-      font-family: var(--font);
-      font-size: 12px;
-      color: var(--text);
-      line-height: 1.7;
-      overflow-x: auto;
-      margin-top: 0.5rem;
-    }
-
-    pre.codeblock .cmd  { color: var(--green); }
-    pre.codeblock .cmt  { color: var(--text-dim); }
-    pre.codeblock .flag { color: var(--amber); }
-
-    /* ── Agent team ──────────────────────────────────────────────────────── */
-    .agent-grid {
-      display: grid;
-      grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
-      gap: 1px;
-      border: 1px solid var(--border);
-      background: var(--border);
-    }
-
-    .agent-card {
-      background: var(--bg-panel);
-      padding: 2rem;
-      position: relative;
-    }
-
-    .agent-accent {
-      position: absolute;
-      top: 0;
-      left: 0;
-      right: 0;
-      height: 2px;
-    }
-
-    .agent-name {
-      font-size: 15px;
-      font-weight: 700;
-      color: var(--text-bright);
-      margin-bottom: 0.25rem;
-    }
-
-    .agent-role {
+    #status {
+      display: flex;
+      align-items: center;
+      gap: 6px;
       font-size: 11px;
-      letter-spacing: 0.1em;
-      text-transform: uppercase;
-      color: var(--text-dim);
-      margin-bottom: 1.25rem;
+      color: var(--dim);
+      letter-spacing: 0.05em;
+      cursor: default;
     }
 
-    .agent-list {
-      list-style: none;
-      font-size: 12px;
-      color: var(--text-dim);
+    #status-dot {
+      width: 7px;
+      height: 7px;
+      border-radius: 50%;
+      background: var(--dim);
+      transition: background 0.3s;
     }
 
-    .agent-list li { padding: 0.2rem 0; }
-    .agent-list li::before { content: '→ '; color: var(--border-glow); }
+    #status-dot.online  { background: var(--green); box-shadow: 0 0 6px var(--green); }
+    #status-dot.offline { background: var(--red); }
+    #status-dot.trying  { background: var(--accent); animation: pulse 1s infinite; }
 
-    /* ── Roadmap ─────────────────────────────────────────────────────────── */
-    .roadmap { display: flex; flex-direction: column; gap: 0; }
-
-    .roadmap-item {
-      display: grid;
-      grid-template-columns: 120px 1fr;
-      gap: 0;
-      border: 1px solid var(--border);
-      margin-top: -1px;
+    @keyframes pulse {
+      0%, 100% { opacity: 1; }
+      50%      { opacity: 0.3; }
     }
 
-    .roadmap-version {
-      background: var(--bg-card);
-      border-right: 1px solid var(--border);
-      padding: 1.5rem 1.25rem;
+    /* ── Messages ── */
+    #messages {
+      flex: 1;
+      overflow-y: auto;
+      overflow-x: hidden;
+      padding: 16px;
       display: flex;
       flex-direction: column;
-      justify-content: center;
+      gap: 12px;
+      -webkit-overflow-scrolling: touch;
+      scroll-behavior: smooth;
     }
 
-    .roadmap-ver-num {
-      font-weight: 700;
-      color: var(--blue);
+    .msg {
+      max-width: 88%;
+      padding: 10px 14px;
+      font-size: 13px;
+      line-height: 1.6;
+      word-wrap: break-word;
+      overflow-wrap: break-word;
+    }
+
+    .msg.timmy {
+      align-self: flex-start;
+      background: var(--bg-msg);
+      border-left: 2px solid var(--accent);
+      color: var(--text);
+    }
+
+    .msg.user {
+      align-self: flex-end;
+      background: var(--bg-user);
+      border-right: 2px solid var(--dim);
+      color: var(--bright);
+    }
+
+    .msg.system {
+      align-self: center;
+      text-align: center;
+      font-size: 11px;
+      color: var(--dim);
+      max-width: 90%;
+      padding: 8px;
+    }
+
+    .msg .label {
+      font-size: 10px;
+      letter-spacing: 0.12em;
+      text-transform: uppercase;
+      color: var(--dim);
+      margin-bottom: 4px;
+    }
+
+    .msg.timmy .label { color: var(--accent); }
+
+    .msg .body p          { margin-bottom: 0.5em; }
+    .msg .body p:last-child { margin-bottom: 0; }
+    .msg .body code {
+      background: rgba(255, 255, 255, 0.06);
+      padding: 1px 5px;
+      font-size: 12px;
+    }
+    .msg .body pre {
+      background: rgba(0, 0, 0, 0.3);
+      padding: 10px;
+      overflow-x: auto;
+      font-size: 12px;
+      margin: 6px 0;
+    }
+    .msg .body pre code {
+      background: none;
+      padding: 0;
+    }
+
+    /* Thinking indicator */
+    .thinking {
+      align-self: flex-start;
+      padding: 10px 14px;
+      font-size: 13px;
+      color: var(--dim);
+      border-left: 2px solid var(--accent);
+      background: var(--bg-msg);
+    }
+
+    .thinking span {
+      animation: blink 1.4s infinite;
+    }
+    .thinking span:nth-child(2) { animation-delay: 0.2s; }
+    .thinking span:nth-child(3) { animation-delay: 0.4s; }
+
+    @keyframes blink {
+      0%, 80%, 100% { opacity: 0.2; }
+      40%           { opacity: 1; }
+    }
+
+    /* ── Input ── */
+    #input-area {
+      flex-shrink: 0;
+      padding: 12px 16px;
+      padding-bottom: max(12px, env(safe-area-inset-bottom));
+      border-top: 1px solid var(--border);
+      background: var(--bg);
+    }
+
+    #input {
+      width: 100%;
+      background: var(--bg-msg);
+      border: 1px solid var(--border);
+      color: var(--bright);
+      font-family: var(--font);
+      font-size: 16px;
+      padding: 12px 14px;
+      outline: none;
+      -webkit-appearance: none;
+      appearance: none;
+      border-radius: 0;
+    }
+
+    #input::placeholder {
+      color: var(--dim);
       font-size: 13px;
     }
 
-    .roadmap-ver-name {
-      font-size: 11px;
-      letter-spacing: 0.1em;
-      text-transform: uppercase;
-      color: var(--text-dim);
-      margin-top: 0.15rem;
+    #input:focus {
+      border-color: var(--accent);
     }
 
-    .roadmap-content { padding: 1.5rem 1.5rem; }
+    /* ── Scrollbar ── */
+    #messages::-webkit-scrollbar { width: 4px; }
+    #messages::-webkit-scrollbar-track { background: transparent; }
+    #messages::-webkit-scrollbar-thumb { background: var(--border); }
 
-    .roadmap-status {
-      font-size: 11px;
-      letter-spacing: 0.1em;
-      text-transform: uppercase;
-      margin-bottom: 0.5rem;
-    }
-
-    .roadmap-content h4 {
-      font-size: 13px;
-      font-weight: 700;
-      color: var(--text-bright);
-      margin-bottom: 0.5rem;
-    }
-
-    .roadmap-content p { font-size: 12px; color: var(--text-dim); }
-
-    /* ── Footer ──────────────────────────────────────────────────────────── */
-    footer {
-      border-top: 1px solid var(--border);
-      background: var(--bg-panel);
-      padding: 2rem;
-      display: flex;
-      justify-content: space-between;
-      align-items: center;
-      flex-wrap: wrap;
-      gap: 1rem;
-    }
-
-    .footer-copy {
-      font-size: 11px;
-      color: var(--text-dim);
-      letter-spacing: 0.05em;
-    }
-
-    .footer-links { display: flex; gap: 1.5rem; }
-    .footer-links a {
-      font-size: 11px;
-      color: var(--text-dim);
-      letter-spacing: 0.08em;
-      text-transform: uppercase;
-      transition: color 0.2s;
-    }
-    .footer-links a:hover { color: var(--blue); text-decoration: none; }
-
-    /* ── Divider ─────────────────────────────────────────────────────────── */
-    .divider {
-      border: none;
-      border-top: 1px solid var(--border);
-      margin: 0;
-    }
-
-    /* ── Responsive ──────────────────────────────────────────────────────── */
-    @media (max-width: 640px) {
-      header { padding: 0 1rem; }
-      nav { display: none; }
-      .hero { padding: 4rem 1rem 3rem; }
-      .stats { flex-wrap: wrap; }
-      .stat { max-width: none; flex: 0 0 50%; border-right: none;
-               border-bottom: 1px solid var(--border); }
-      section { padding: 3rem 1rem; }
-      .roadmap-item { grid-template-columns: 1fr; }
-      .roadmap-version { border-right: none; border-bottom: 1px solid var(--border); }
-      footer { flex-direction: column; align-items: flex-start; }
-    }
+    /* ── No horizontal anything ── */
+    * { max-width: 100%; }
   </style>
 </head>
 <body>
 
-<!-- ── Header ──────────────────────────────────────────────────────────── -->
-<header>
-  <div class="logo">TIMMY TIME <span>// MISSION CONTROL</span></div>
-  <nav>
-    <a href="#features">Features</a>
-    <a href="#architecture">Architecture</a>
-    <a href="#quickstart">Quickstart</a>
-    <a href="#agents">Agent Team</a>
-    <a href="#roadmap">Roadmap</a>
-    <a class="btn-primary" href="https://github.com/AlexanderWhitestone/Timmy-time-dashboard">GitHub →</a>
-  </nav>
-</header>
+<div id="app">
+  <div id="header">
+    <h1>TIMMY</h1>
+    <div id="status">
+      <span id="status-text">connecting</span>
+      <span id="status-dot" class="trying"></span>
+    </div>
+  </div>
 
-<!-- ── Hero ────────────────────────────────────────────────────────────── -->
-<section class="hero" style="max-width:100%; padding-left:2rem; padding-right:2rem;">
-  <p class="hero-label">Sovereign AI Agent System</p>
-  <h1>Your agents.<br><em>Your hardware.</em><br>Your sats.</h1>
-  <p class="hero-sub">
-    A local-first AI command center. Talk to Timmy, coordinate your swarm,
-    gate API access with Bitcoin Lightning — no cloud AI, no telemetry, no compromise.
-  </p>
-  <div class="hero-badges">
-    <span class="badge green">Full Test Suite Passing</span>
-    <span class="badge blue">FastAPI + HTMX</span>
-    <span class="badge amber">Lightning L402</span>
-    <span class="badge">No Cloud AI</span>
-    <span class="badge purple">Multi-Agent Swarm</span>
-    <span class="badge">MIT License</span>
-  </div>
-  <div class="hero-cta">
-    <a class="btn-primary" href="https://github.com/AlexanderWhitestone/Timmy-time-dashboard">View on GitHub</a>
-    <a class="btn-ghost" href="#quickstart">Get Started</a>
-  </div>
-</section>
+  <div id="messages"></div>
 
-<!-- ── Stats ────────────────────────────────────────────────────────────── -->
-<div class="stats">
-  <div class="stat">
-    <div class="stat-number">640+</div>
-    <div class="stat-label">Tests Passing</div>
-  </div>
-  <div class="stat">
-    <div class="stat-number">58</div>
-    <div class="stat-label">API Endpoints</div>
-  </div>
-  <div class="stat">
-    <div class="stat-number">15</div>
-    <div class="stat-label">Subsystems</div>
-  </div>
-  <div class="stat">
-    <div class="stat-number">0</div>
-    <div class="stat-label">Cloud AI Calls</div>
+  <div id="input-area">
+    <input id="input"
+           type="text"
+           placeholder="talk to timmy..."
+           autocomplete="off"
+           autocorrect="off"
+           autocapitalize="none"
+           spellcheck="false"
+           enterkeyhint="send">
   </div>
 </div>
 
-<hr class="divider" />
+<script>
+(function() {
+  var SERVER = localStorage.getItem('timmy-server') || 'http://localhost:8000';
+  var messages = document.getElementById('messages');
+  var input    = document.getElementById('input');
+  var dot      = document.getElementById('status-dot');
+  var stxt     = document.getElementById('status-text');
+  var connected = false;
+  var sending   = false;
 
-<!-- ── Features ─────────────────────────────────────────────────────────── -->
-<section id="features">
-  <p class="section-label">Capabilities</p>
-  <h2>Everything in one dashboard</h2>
-  <p class="section-intro">
-    Built for the operator who wants sovereignty without sacrificing capability.
-    Every subsystem works offline.
-  </p>
-  <div class="feature-grid">
+  function setStatus(state) {
+    dot.className = state;
+    if (state === 'online')       stxt.textContent = 'online';
+    else if (state === 'trying')  stxt.textContent = 'connecting';
+    else                          stxt.textContent = 'offline';
+  }
 
-    <div class="feature-card">
-      <span class="feature-icon">🤖</span>
-      <h3>Timmy Agent</h3>
-      <p>Agno-powered conversational agent backed by Ollama (llama3.2 default) or
-         AirLLM for 70B–405B models on Apple Silicon. SQLite memory, no cloud.</p>
-      <span class="feature-tag">Agno · Ollama · AirLLM</span>
-    </div>
+  // ── Looping scroll ──
+  // Messages live inside two duplicate containers.
+  // When scroll crosses the midpoint we silently reposition,
+  // creating an infinite one-direction loop.
+  var loopEnabled = false;
+  var suppressLoop = false;
 
-    <div class="feature-card">
-      <span class="feature-icon">🌐</span>
-      <h3>Mission Control UI</h3>
-      <p>FastAPI backend with Jinja2 + HTMX frontend. Dark terminal aesthetic.
-         Real-time health polling, chat history, live swarm feed — no JavaScript framework.</p>
-      <span class="feature-tag">FastAPI · HTMX · Bootstrap 5</span>
-    </div>
+  function buildLoop() {
+    // Clone all messages into a second set so the container is 2x tall
+    var existing = messages.querySelectorAll('.msg, .thinking');
+    if (existing.length < 2) { loopEnabled = false; return; }
 
-    <div class="feature-card">
-      <span class="feature-icon">🐝</span>
-      <h3>Multi-Agent Swarm</h3>
-      <p>Spawn sub-agents, post tasks, run 15-second Lightning auctions. Registry,
-         manager, bidder, and coordinator — all in-process or as separate subprocesses.</p>
-      <span class="feature-tag">Coordinator · Registry · Auction</span>
-    </div>
+    // Remove any previous clone zone
+    var oldClone = document.getElementById('clone-zone');
+    if (oldClone) oldClone.remove();
 
-    <div class="feature-card">
-      <span class="feature-icon">⚡</span>
-      <h3>L402 Lightning Payments</h3>
-      <p>Bitcoin Lightning payment gating via HMAC macaroons. Mock backend for dev,
-         LND backend scaffolded for production. Auction bids priced in sats.</p>
-      <span class="feature-tag">L402 · Macaroon · BOLT11</span>
-    </div>
+    var zone = document.createElement('div');
+    zone.id = 'clone-zone';
+    for (var i = 0; i < existing.length; i++) {
+      zone.appendChild(existing[i].cloneNode(true));
+    }
+    messages.appendChild(zone);
+    loopEnabled = true;
+  }
 
-    <div class="feature-card">
-      <span class="feature-icon">🎙️</span>
-      <h3>Voice I/O</h3>
-      <p>Pattern-matched NLU detects intents (status, swarm, task, help) from natural
-         language. TTS via pyttsx3 speaks responses aloud. Fully offline.</p>
-      <span class="feature-tag">NLU · pyttsx3 · Intent Detection</span>
-    </div>
+  messages.addEventListener('scroll', function() {
+    if (!loopEnabled || suppressLoop) return;
+    var half = messages.scrollHeight / 2;
+    if (messages.scrollTop >= half) {
+      suppressLoop = true;
+      messages.scrollTop -= half;
+      suppressLoop = false;
+    } else if (messages.scrollTop <= 0) {
+      suppressLoop = true;
+      messages.scrollTop += half;
+      suppressLoop = false;
+    }
+  });
 
-    <div class="feature-card">
-      <span class="feature-icon">📱</span>
-      <h3>Mobile Optimized</h3>
-      <p>iOS safe-area, 44px touch targets, 16px inputs (no zoom), momentum scroll,
-         dynamic viewport height. 21-scenario HITL test harness built in.</p>
-      <span class="feature-tag">iOS · HITL · Responsive</span>
-    </div>
+  function scrollDown() {
+    requestAnimationFrame(function() {
+      // Scroll to latest message (just before clone zone)
+      var clone = document.getElementById('clone-zone');
+      if (clone) {
+        messages.scrollTop = clone.offsetTop - messages.clientHeight + 40;
+      } else {
+        messages.scrollTop = messages.scrollHeight;
+      }
+    });
+  }
 
-    <div class="feature-card">
-      <span class="feature-icon">🔴</span>
-      <h3>WebSocket Live Feed</h3>
-      <p>Real-time swarm events — agent joins, task posts, auction bids, completions —
-         broadcast over WebSocket to the live dashboard.</p>
-      <span class="feature-tag">WebSocket · Live Events</span>
-    </div>
+  function rebuildAndScroll() {
+    // Small delay so DOM settles, then rebuild loop and scroll
+    requestAnimationFrame(function() {
+      buildLoop();
+      scrollDown();
+    });
+  }
 
-    <div class="feature-card">
-      <span class="feature-icon">🛡️</span>
-      <h3>Security First</h3>
-      <p>XSS prevention via textContent (not innerHTML). Startup warnings for default
-         secrets. HMAC-signed macaroons. Graceful degradation on every optional service.</p>
-      <span class="feature-tag">XSS-safe · HMAC · Warnings</span>
-    </div>
+  function addMsg(role, text) {
+    // Remove old clone zone before adding new message
+    var oldClone = document.getElementById('clone-zone');
+    if (oldClone) oldClone.remove();
 
-    <div class="feature-card">
-      <span class="feature-icon">🔧</span>
-      <h3>Self-TDD Watchdog</h3>
-      <p>Continuous test runner polls pytest every 60 seconds and alerts on regressions.
-         Runs alongside dev work in the background — silent when green.</p>
-      <span class="feature-tag">pytest · self-tdd · CI</span>
-    </div>
+    var div = document.createElement('div');
+    div.className = 'msg ' + role;
 
-  </div>
-</section>
+    if (role === 'system') {
+      div.textContent = text;
+    } else {
+      var label = document.createElement('div');
+      label.className = 'label';
+      label.textContent = role === 'timmy' ? 'TIMMY' : 'YOU';
 
-<hr class="divider" />
+      var body = document.createElement('div');
+      body.className = 'body';
 
-<!-- ── Architecture ──────────────────────────────────────────────────────── -->
-<section id="architecture">
-  <p class="section-label">System Design</p>
-  <h2>Architecture</h2>
-  <p class="section-intro">
-    A layered local stack. Every dependency can degrade gracefully — Ollama offline?
-    Error message. Redis missing? In-memory pub/sub. pyttsx3 absent? TTS is a no-op.
-  </p>
-  <div class="arch-wrap">
-    <pre>
-<span class="hl-blue">Browser / Phone</span>
-      │ HTTP + HTMX + WebSocket
-      ▼
-┌─────────────────────────────────────────────────────────┐
-│                  <span class="hl-blue">FastAPI  (dashboard.app)</span>                  │
-│  routes: agents · health · swarm · marketplace · voice  │
-└────────┬──────────────┬────────────────┬────────────────┘
-         │              │                │
-         ▼              ▼                ▼
-    <span class="hl-green">Jinja2</span>         <span class="hl-amber">Timmy Agent</span>       <span class="hl-purple">Swarm Coordinator</span>
-    Templates      │                  ├─ Registry    (SQLite)
-    (HTMX)         ├─ <span class="hl-green">Ollama</span>           ├─ AuctionManager  (15s bids)
-                   └─ <span class="hl-amber">AirLLM</span>           ├─ SwarmComms     (Redis / mem)
-                      (70B–405B)       └─ SwarmManager  (subprocess)
-         │
-         ├── <span class="hl-blue">Voice NLU + TTS</span>      (pyttsx3, local)
-         ├── <span class="hl-blue">WebSocket live feed</span>  (ws_manager)
-         ├── <span class="hl-amber">L402 Lightning proxy</span> (macaroon + BOLT11 invoice)
-         ├── <span class="hl-green">Push notifications</span>   (local + macOS native)
-         └── Siri Shortcuts API  (iOS automation endpoints)
+      if (role === 'timmy') {
+        body.innerHTML = renderMarkdown(text);
+      } else {
+        body.textContent = text;
+      }
 
-<span class="hl-dim">Persistence:  timmy.db (Agno memory) · data/swarm.db (registry + tasks)
-External:     Ollama :11434 · optional Redis · optional LND gRPC</span>
-    </pre>
-  </div>
-</section>
+      div.appendChild(label);
+      div.appendChild(body);
+    }
 
-<hr class="divider" />
+    messages.appendChild(div);
+    rebuildAndScroll();
+    return div;
+  }
 
-<!-- ── Quickstart ─────────────────────────────────────────────────────────── -->
-<section id="quickstart">
-  <p class="section-label">Get Running</p>
-  <h2>Quickstart</h2>
-  <p class="section-intro">
-    Five minutes from zero to a running agent. You need Python 3.11+ and Ollama.
-  </p>
-  <div class="quickstart-steps">
+  function showThinking() {
+    var oldClone = document.getElementById('clone-zone');
+    if (oldClone) oldClone.remove();
 
-    <div class="step">
-      <div class="step-num">1</div>
-      <div>
-        <h4>Clone</h4>
-        <pre class="codeblock"><span class="cmd">git clone</span> https://github.com/AlexanderWhitestone/Timmy-time-dashboard.git
-<span class="cmd">cd</span> Timmy-time-dashboard</pre>
-      </div>
-    </div>
+    var div = document.createElement('div');
+    div.className = 'thinking';
+    div.id = 'thinking';
+    div.innerHTML = '<span>.</span><span>.</span><span>.</span>';
+    messages.appendChild(div);
+    rebuildAndScroll();
+  }
 
-    <div class="step">
-      <div class="step-num">2</div>
-      <div>
-        <h4>Install</h4>
-        <pre class="codeblock"><span class="cmd">make install</span>
-<span class="cmt"># or manually:</span>
-<span class="cmd">python3 -m venv</span> .venv <span class="cmt">&amp;&amp;</span> <span class="cmd">source</span> .venv/bin/activate
-<span class="cmd">pip install</span> -e ".[dev]"</pre>
-      </div>
-    </div>
+  function hideThinking() {
+    var el = document.getElementById('thinking');
+    if (el) el.remove();
+    // Also remove from clone zone
+    var cloneThinking = document.querySelector('#clone-zone .thinking');
+    if (cloneThinking) cloneThinking.remove();
+  }
 
-    <div class="step">
-      <div class="step-num">3</div>
-      <div>
-        <h4>Start Ollama</h4>
-        <pre class="codeblock"><span class="cmt"># In a separate terminal:</span>
-<span class="cmd">ollama serve</span>
-<span class="cmd">ollama pull</span> llama3.2   <span class="cmt"># ~2 GB, one-time download</span></pre>
-      </div>
-    </div>
+  // Simple markdown rendering (safe — no innerHTML with user content)
+  function renderMarkdown(text) {
+    // Escape HTML first
+    var safe = text
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;');
 
-    <div class="step">
-      <div class="step-num">4</div>
-      <div>
-        <h4>Launch</h4>
-        <pre class="codeblock"><span class="cmd">make dev</span>
-<span class="cmt"># Opens at http://localhost:8000</span>
-<span class="cmt"># Mobile: http://&lt;your-lan-ip&gt;:8000</span></pre>
-      </div>
-    </div>
+    // Code blocks
+    safe = safe.replace(/```(\w*)\n?([\s\S]*?)```/g, function(m, lang, code) {
+      return '<pre><code>' + code.trim() + '</code></pre>';
+    });
 
-    <div class="step">
-      <div class="step-num">5</div>
-      <div>
-        <h4>Test</h4>
-        <pre class="codeblock"><span class="cmd">make test</span>        <span class="cmt"># full test suite — no Ollama needed</span>
-<span class="cmd">make test-cov</span>    <span class="cmt"># + coverage report</span>
-<span class="cmd">make watch</span>       <span class="cmt"># self-TDD watchdog in background</span></pre>
-      </div>
-    </div>
+    // Inline code
+    safe = safe.replace(/`([^`]+)`/g, '<code>$1</code>');
 
-  </div>
-</section>
+    // Bold
+    safe = safe.replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>');
 
-<hr class="divider" />
+    // Italic
+    safe = safe.replace(/\*(.+?)\*/g, '<em>$1</em>');
 
-<!-- ── Agent Team ─────────────────────────────────────────────────────────── -->
-<section id="agents">
-  <p class="section-label">Contributors</p>
-  <h2>The agent team</h2>
-  <p class="section-intro">
-    This repo is built by a multi-agent team. Each tool has a defined lane.
-    See <a href="https://github.com/AlexanderWhitestone/Timmy-time-dashboard/blob/main/AGENTS.md">AGENTS.md</a>
-    for the full development standards.
-  </p>
-  <div class="agent-grid">
+    // Paragraphs
+    safe = safe.replace(/\n\n+/g, '</p><p>');
+    safe = '<p>' + safe + '</p>';
 
-    <div class="agent-card">
-      <div class="agent-accent" style="background: var(--blue);"></div>
-      <div class="agent-name">Claude</div>
-      <div class="agent-role">Anthropic · Architect</div>
-      <ul class="agent-list">
-        <li>Foundation, scaffolding, CI</li>
-        <li>Testing and quality passes</li>
-        <li>Documentation and tooling</li>
-        <li>Iterative refinement</li>
-      </ul>
-    </div>
+    // Line breaks within paragraphs
+    safe = safe.replace(/\n/g, '<br>');
 
-    <div class="agent-card">
-      <div class="agent-accent" style="background: var(--purple);"></div>
-      <div class="agent-name">Kimi</div>
-      <div class="agent-role">Moonshot AI · Feature Engine</div>
-      <ul class="agent-list">
-        <li>High-volume feature drops</li>
-        <li>New subsystem builds</li>
-        <li>Large context, rapid expansion</li>
-        <li>Agent persona implementation</li>
-      </ul>
-    </div>
+    return safe;
+  }
 
-    <div class="agent-card">
-      <div class="agent-accent" style="background: var(--amber);"></div>
-      <div class="agent-name">Manus</div>
-      <div class="agent-role">Manus AI · Security Specialist</div>
-      <ul class="agent-list">
-        <li>Security audits (XSS, injection)</li>
-        <li>Coverage gap analysis</li>
-        <li>Targeted bug fixes</li>
-        <li>Payment flow validation</li>
-      </ul>
-    </div>
+  // Probe the server for connectivity
+  function probe() {
+    setStatus('trying');
+    fetch(SERVER + '/health/status', { mode: 'cors', signal: AbortSignal.timeout(4000) })
+      .then(function(r) {
+        if (r.ok) {
+          connected = true;
+          setStatus('online');
+        } else {
+          connected = false;
+          setStatus('offline');
+        }
+      })
+      .catch(function() {
+        connected = false;
+        setStatus('offline');
+      });
+  }
 
-    <div class="agent-card">
-      <div class="agent-accent" style="background: var(--text-dim);"></div>
-      <div class="agent-name">Alexander Whitestone</div>
-      <div class="agent-role">Human · Orchestrator</div>
-      <ul class="agent-list">
-        <li>Vision and product decisions</li>
-        <li>Agent task assignment</li>
-        <li>PR review and merge</li>
-        <li>Bitcoin / Lightning domain</li>
-      </ul>
-    </div>
+  // Send message to Timmy
+  function send(text) {
+    if (sending) return;
 
-  </div>
-</section>
+    // Special commands
+    if (text.startsWith('/connect ')) {
+      var url = text.slice(9).trim().replace(/\/+$/, '');
+      SERVER = url;
+      localStorage.setItem('timmy-server', SERVER);
+      addMsg('system', 'server set to ' + SERVER);
+      probe();
+      return;
+    }
 
-<hr class="divider" />
+    if (text === '/clear') {
+      messages.innerHTML = '';
+      addMsg('system', 'chat cleared');
+      return;
+    }
 
-<!-- ── Roadmap ────────────────────────────────────────────────────────────── -->
-<section id="roadmap">
-  <p class="section-label">What's Next</p>
-  <h2>Roadmap</h2>
-  <p class="section-intro">Three phases, each named after a book.</p>
-  <div class="roadmap">
+    if (text === '/help') {
+      addMsg('system', '/connect <url> — set server  ·  /clear — clear chat');
+      return;
+    }
 
-    <div class="roadmap-item">
-      <div class="roadmap-version">
-        <div class="roadmap-ver-num">v1.0.0</div>
-        <div class="roadmap-ver-name">Genesis</div>
-      </div>
-      <div class="roadmap-content">
-        <div class="roadmap-status" style="color:var(--green);">✓ Complete</div>
-        <h4>Foundation</h4>
-        <p>Agno + Ollama + SQLite + FastAPI dashboard + HTMX + full test suite.
-           CLI, mobile layout, Bootstrap, CI/CD, AirLLM big-brain backend.</p>
-      </div>
-    </div>
+    addMsg('user', text);
 
-    <div class="roadmap-item">
-      <div class="roadmap-version">
-        <div class="roadmap-ver-num">v2.0.0</div>
-        <div class="roadmap-ver-name">Exodus</div>
-      </div>
-      <div class="roadmap-content">
-        <div class="roadmap-status" style="color:var(--amber);">⟳ In progress</div>
-        <h4>Multi-Agent Economy</h4>
-        <p>Swarm coordination, L402 Lightning payment gating, voice NLU/TTS,
-           marketplace, WebSocket live feed. Agent personas: Echo, Mace, Helm,
-           Seer, Forge, Quill. Real LND gRPC backend.</p>
-      </div>
-    </div>
+    if (!connected) {
+      addMsg('system', 'not connected — start timmy (make dev) or /connect <url>');
+      return;
+    }
 
-    <div class="roadmap-item">
-      <div class="roadmap-version">
-        <div class="roadmap-ver-num">v3.0.0</div>
-        <div class="roadmap-ver-name">Revelation</div>
-      </div>
-      <div class="roadmap-content">
-        <div class="roadmap-status" style="color:var(--text-dim);">◌ Planned</div>
-        <h4>Sovereign Deployment</h4>
-        <p>Bitcoin Lightning treasury — agents earn and spend sats autonomously.
-           Single <code>.app</code> bundle for macOS (no Python install).
-           Federation between Timmy instances.</p>
-      </div>
-    </div>
+    sending = true;
+    showThinking();
 
-  </div>
-</section>
+    var form = new FormData();
+    form.append('message', text);
 
-<hr class="divider" />
+    fetch(SERVER + '/agents/timmy/chat', {
+      method: 'POST',
+      body: form,
+      mode: 'cors',
+    })
+      .then(function(r) {
+        if (!r.ok) throw new Error('HTTP ' + r.status);
+        return r.text();
+      })
+      .then(function(html) {
+        hideThinking();
+        // Parse the response HTML to extract Timmy's reply
+        var parser = new DOMParser();
+        var doc = parser.parseFromString(html, 'text/html');
 
-<!-- ── Footer ────────────────────────────────────────────────────────────── -->
-<footer>
-  <div class="footer-copy">
-    TIMMY TIME // MISSION CONTROL &nbsp;·&nbsp; MIT License &nbsp;·&nbsp;
-    No cloud AI. No telemetry. Sats are sovereignty.
-  </div>
-  <div class="footer-links">
-    <a href="https://github.com/AlexanderWhitestone/Timmy-time-dashboard">GitHub</a>
-    <a href="https://github.com/AlexanderWhitestone/Timmy-time-dashboard/blob/main/AGENTS.md">AGENTS.md</a>
-    <a href="https://github.com/AlexanderWhitestone/Timmy-time-dashboard/blob/main/README.md">README</a>
-    <a href="https://github.com/AlexanderWhitestone/Timmy-time-dashboard/issues">Issues</a>
-  </div>
-</footer>
+        var agentBody = doc.querySelector('.chat-message.agent .msg-body');
+        var errorBody = doc.querySelector('.chat-message.error-msg .msg-body');
+
+        if (agentBody) {
+          addMsg('timmy', agentBody.textContent.trim());
+        } else if (errorBody) {
+          addMsg('system', errorBody.textContent.trim());
+        } else {
+          addMsg('system', 'no response');
+        }
+      })
+      .catch(function(err) {
+        hideThinking();
+        addMsg('system', 'error: ' + err.message);
+        probe();
+      })
+      .finally(function() {
+        sending = false;
+      });
+  }
+
+  // Input handling — Enter to send, no buttons
+  input.addEventListener('keydown', function(e) {
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault();
+      var text = input.value.trim();
+      if (!text) return;
+      input.value = '';
+      send(text);
+    }
+  });
+
+  // Initial welcome
+  addMsg('system', 'timmy time — sovereign ai');
+  addMsg('timmy', "What's on your mind?");
+
+  // Probe on load
+  probe();
+
+  // Re-probe periodically
+  setInterval(probe, 15000);
+})();
+</script>
 
 </body>
 </html>
diff --git a/mobile-app/README.md b/mobile-app/README.md
new file mode 100644
index 00000000..a06ce5cf
--- /dev/null
+++ b/mobile-app/README.md
@@ -0,0 +1,108 @@
+# Timmy Chat — Mobile App
+
+A sleek mobile chat interface for Timmy, the sovereign AI agent. Built with **Expo SDK 54**, **React Native**, **TypeScript**, and **NativeWind** (Tailwind CSS).
+
+## Features
+
+- **Text Chat** — Send and receive messages with Timmy's full personality
+- **Voice Messages** — Record and send voice notes via the mic button; playback with waveform UI
+- **Image Sharing** — Take photos or pick from library; full-screen image viewer
+- **File Attachments** — Send any document via the system file picker
+- **Dark Arcane Theme** — Deep purple/indigo palette matching the Timmy Time dashboard
+
+## Screenshots
+
+The app is a single-screen chat interface with:
+- Header showing Timmy's status and a clear-chat button
+- Message list with distinct user (teal) and Timmy (dark surface) bubbles
+- Input bar with attachment (+), text field, and mic/send button
+- Empty state with Timmy branding when no messages exist
+
+## Project Structure
+
+```
+mobile-app/
+├── app/                    # Expo Router screens
+│   ├── _layout.tsx         # Root layout with providers
+│   └── (tabs)/
+│       ├── _layout.tsx     # Tab layout (hidden — single screen)
+│       └── index.tsx       # Main chat screen
+├── components/
+│   ├── chat-bubble.tsx     # Message bubble (text, image, voice, file)
+│   ├── chat-header.tsx     # Header with Timmy status
+│   ├── chat-input.tsx      # Input bar (text, mic, attachments)
+│   ├── empty-chat.tsx      # Empty state welcome screen
+│   ├── image-viewer.tsx    # Full-screen image modal
+│   └── typing-indicator.tsx # Animated dots while Timmy responds
+├── lib/
+│   └── chat-store.tsx      # React Context chat state + API calls
+├── server/
+│   └── chat.ts             # Server-side chat handler with Timmy's prompt
+├── shared/
+│   └── types.ts            # ChatMessage type definitions
+├── assets/images/          # App icons (custom generated)
+├── theme.config.js         # Color tokens (dark arcane palette)
+├── tailwind.config.js      # Tailwind/NativeWind configuration
+└── tests/
+    └── chat.test.ts        # Unit tests
+```
+
+## Setup
+
+### Prerequisites
+
+- Node.js 18+
+- pnpm 9+
+- Expo CLI (`npx expo`)
+- iOS Simulator or Android Emulator (or physical device with Expo Go)
+
+### Install Dependencies
+
+```bash
+cd mobile-app
+pnpm install
+```
+
+### Run the App
+
+```bash
+# Start the Expo dev server
+npx expo start
+
+# Or run on specific platform
+npx expo start --ios
+npx expo start --android
+npx expo start --web
+```
+
+### Backend
+
+The chat API endpoint (`server/chat.ts`) requires an LLM backend. The `invokeLLM` function should be wired to your preferred provider:
+
+- **Local Ollama** — Point to `http://localhost:11434` for local inference
+- **OpenAI-compatible API** — Any API matching the OpenAI chat completions format
+
+The system prompt in `server/chat.ts` contains Timmy's full personality, agent roster, and behavioral rules ported from the dashboard's `prompts.py`.
+
+## Timmy's Personality
+
+Timmy is a sovereign AI agent — grounded in Christian faith, powered by Bitcoin economics, committed to digital sovereignty. He speaks plainly, acts with intention, and never ends responses with generic chatbot phrases. His agent roster includes Echo, Mace, Forge, Seer, Helm, Quill, Pixel, Lyra, and Reel.
+
+## Theme
+
+The app uses a dark arcane color palette:
+
+| Token | Color | Usage |
+|-------|-------|-------|
+| `primary` | `#7c3aed` | Accent, user bubbles |
+| `background` | `#080412` | Screen background |
+| `surface` | `#110a20` | Cards, Timmy bubbles |
+| `foreground` | `#e8e0f0` | Primary text |
+| `muted` | `#6b5f7d` | Secondary text |
+| `border` | `#1e1535` | Dividers |
+| `success` | `#22c55e` | Status indicator |
+| `error` | `#ff4455` | Recording state |
+
+## License
+
+Same as the parent Timmy Time Dashboard project.
diff --git a/mobile-app/app.config.ts b/mobile-app/app.config.ts
new file mode 100644
index 00000000..f64baf12
--- /dev/null
+++ b/mobile-app/app.config.ts
@@ -0,0 +1,130 @@
+// Load environment variables with proper priority (system > .env)
+import "./scripts/load-env.js";
+import type { ExpoConfig } from "expo/config";
+
+// Bundle ID format: space.manus.<project_name_dots>.<timestamp>
+// e.g., "my-app" created at 2024-01-15 10:30:45 -> "space.manus.my.app.t20240115103045"
+// Bundle ID can only contain letters, numbers, and dots
+// Android requires each dot-separated segment to start with a letter
+const rawBundleId = "space.manus.timmy.chat.t20260226211148";
+const bundleId =
+  rawBundleId
+    .replace(/[-_]/g, ".") // Replace hyphens/underscores with dots
+    .replace(/[^a-zA-Z0-9.]/g, "") // Remove invalid chars
+    .replace(/\.+/g, ".") // Collapse consecutive dots
+    .replace(/^\.+|\.+$/g, "") // Trim leading/trailing dots
+    .toLowerCase()
+    .split(".")
+    .map((segment) => {
+      // Android requires each segment to start with a letter
+      // Prefix with 'x' if segment starts with a digit
+      return /^[a-zA-Z]/.test(segment) ? segment : "x" + segment;
+    })
+    .join(".") || "space.manus.app";
+// Extract timestamp from bundle ID and prefix with "manus" for deep link scheme
+// e.g., "space.manus.my.app.t20240115103045" -> "manus20240115103045"
+const timestamp = bundleId.split(".").pop()?.replace(/^t/, "") ?? "";
+const schemeFromBundleId = `manus${timestamp}`;
+
+const env = {
+  // App branding - update these values directly (do not use env vars)
+  appName: "Timmy Chat",
+  appSlug: "timmy-chat",
+  // S3 URL of the app logo - set this to the URL returned by generate_image when creating custom logo
+  // Leave empty to use the default icon from assets/images/icon.png
+  logoUrl: "https://files.manuscdn.com/user_upload_by_module/session_file/310519663286296482/kuSmtQpNVBtvECMG.png",
+  scheme: schemeFromBundleId,
+  iosBundleId: bundleId,
+  androidPackage: bundleId,
+};
+
+const config: ExpoConfig = {
+  name: env.appName,
+  slug: env.appSlug,
+  version: "1.0.0",
+  orientation: "portrait",
+  icon: "./assets/images/icon.png",
+  scheme: env.scheme,
+  userInterfaceStyle: "automatic",
+  newArchEnabled: true,
+  ios: {
+    supportsTablet: true,
+    bundleIdentifier: env.iosBundleId,
+    "infoPlist": {
+        "ITSAppUsesNonExemptEncryption": false
+      }
+  },
+  android: {
+    adaptiveIcon: {
+      backgroundColor: "#080412",
+      foregroundImage: "./assets/images/android-icon-foreground.png",
+      backgroundImage: "./assets/images/android-icon-background.png",
+      monochromeImage: "./assets/images/android-icon-monochrome.png",
+    },
+    edgeToEdgeEnabled: true,
+    predictiveBackGestureEnabled: false,
+    package: env.androidPackage,
+    permissions: ["POST_NOTIFICATIONS"],
+    intentFilters: [
+      {
+        action: "VIEW",
+        autoVerify: true,
+        data: [
+          {
+            scheme: env.scheme,
+            host: "*",
+          },
+        ],
+        category: ["BROWSABLE", "DEFAULT"],
+      },
+    ],
+  },
+  web: {
+    bundler: "metro",
+    output: "static",
+    favicon: "./assets/images/favicon.png",
+  },
+  plugins: [
+    "expo-router",
+    [
+      "expo-audio",
+      {
+        microphonePermission: "Allow $(PRODUCT_NAME) to access your microphone.",
+      },
+    ],
+    [
+      "expo-video",
+      {
+        supportsBackgroundPlayback: true,
+        supportsPictureInPicture: true,
+      },
+    ],
+    [
+      "expo-splash-screen",
+      {
+        image: "./assets/images/splash-icon.png",
+        imageWidth: 200,
+        resizeMode: "contain",
+        backgroundColor: "#080412",
+        dark: {
+          backgroundColor: "#080412",
+        },
+      },
+    ],
+    [
+      "expo-build-properties",
+      {
+        android: {
+          buildArchs: ["armeabi-v7a", "arm64-v8a"],
+          minSdkVersion: 24,
+        },
+      },
+    ],
+  ],
+  experiments: {
+    typedRoutes: true,
+    reactCompiler: true,
+  },
+};
+
+export default config;
diff --git a/mobile-app/app/(tabs)/_layout.tsx b/mobile-app/app/(tabs)/_layout.tsx
new file mode 100644
index 00000000..07f5be2c
--- /dev/null
+++ b/mobile-app/app/(tabs)/_layout.tsx
@@ -0,0 +1,17 @@
+import { Tabs } from "expo-router";
+import { useColors } from "@/hooks/use-colors";
+
+export default function TabLayout() {
+  const colors = useColors();
+
+  return (
+    <Tabs
+      screenOptions={{
+        headerShown: false,
+        tabBarStyle: { display: "none" },
+      }}
+    >
+      <Tabs.Screen name="index" options={{ title: "Chat" }} />
+    </Tabs>
+  );
+}
diff --git a/mobile-app/app/(tabs)/index.tsx b/mobile-app/app/(tabs)/index.tsx
new file mode 100644
index 00000000..d747b743
--- /dev/null
+++ b/mobile-app/app/(tabs)/index.tsx
@@ -0,0 +1,96 @@
+import { useCallback, useRef, useState } from "react";
+import { FlatList, KeyboardAvoidingView, Platform, StyleSheet, View } from "react-native";
+import { ScreenContainer } from "@/components/screen-container";
+import { ChatHeader } from "@/components/chat-header";
+import { ChatBubble } from "@/components/chat-bubble";
+import { ChatInput } from "@/components/chat-input";
+import { TypingIndicator } from "@/components/typing-indicator";
+import { ImageViewer } from "@/components/image-viewer";
+import { EmptyChat } from "@/components/empty-chat";
+import { useChat } from "@/lib/chat-store";
+import { useColors } from "@/hooks/use-colors";
+import { createAudioPlayer, setAudioModeAsync } from "expo-audio";
+import type { ChatMessage } from "@/shared/types";
+
+export default function ChatScreen() {
+  const { messages, isTyping } = useChat();
+  const colors = useColors();
+  const flatListRef = useRef<FlatList>(null);
+  const [viewingImage, setViewingImage] = useState<string | null>(null);
+  const [playingVoiceId, setPlayingVoiceId] = useState<string | null>(null);
+
+  const handlePlayVoice = useCallback(async (msg: ChatMessage) => {
+    if (!msg.uri) return;
+    try {
+      if (playingVoiceId === msg.id) {
+        setPlayingVoiceId(null);
+        return;
+      }
+      await setAudioModeAsync({ playsInSilentMode: true });
+      const player = createAudioPlayer({ uri: msg.uri });
+      player.play();
+      setPlayingVoiceId(msg.id);
+      // Auto-reset after estimated duration
+      const dur = (msg.duration ?? 5) * 1000;
+      setTimeout(() => {
+        setPlayingVoiceId(null);
+        player.remove();
+      }, dur + 500);
+    } catch (err) {
+      console.warn("Voice playback error:", err);
+      setPlayingVoiceId(null);
+    }
+  }, [playingVoiceId]);
+
+  const renderItem = useCallback(
+    ({ item }: { item: ChatMessage }) => (
+      <ChatBubble
+        message={item}
+        onImagePress={setViewingImage}
+        onPlayVoice={handlePlayVoice}
+        isPlayingVoice={playingVoiceId === item.id}
+      />
+    ),
+    [playingVoiceId, handlePlayVoice],
+  );
+
+  const keyExtractor = useCallback((item: ChatMessage) => item.id, []);
+
+  return (
+    <ScreenContainer edges={["top", "left", "right"]} containerClassName="bg-background">
+      <KeyboardAvoidingView
+        style={styles.flex}
+        behavior={Platform.OS === "ios" ? "padding" : undefined}
+        keyboardVerticalOffset={0}
+      >
+        <ChatHeader />
+
+        <FlatList
+          ref={flatListRef}
+          data={messages}
+          renderItem={renderItem}
+          keyExtractor={keyExtractor}
+          contentContainerStyle={styles.listContent}
+          style={{ flex: 1, backgroundColor: colors.background }}
+          onContentSizeChange={() => {
+            flatListRef.current?.scrollToEnd({ animated: true });
+          }}
+          ListFooterComponent={isTyping ? <TypingIndicator /> : null}
+          ListEmptyComponent={!isTyping ? <EmptyChat /> : null}
+          showsVerticalScrollIndicator={false}
+        />
+
+        <ChatInput />
+      </KeyboardAvoidingView>
+
+      <ImageViewer uri={viewingImage} onClose={() => setViewingImage(null)} />
+    </ScreenContainer>
+  );
+}
+
+const styles = StyleSheet.create({
+  flex: { flex: 1 },
+  listContent: {
+    paddingVertical: 12,
+  },
+});
diff --git a/mobile-app/app/_layout.tsx b/mobile-app/app/_layout.tsx
new file mode 100644
index 00000000..844280f1
--- /dev/null
+++ b/mobile-app/app/_layout.tsx
@@ -0,0 +1,45 @@
+import "@/global.css";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { Stack } from "expo-router";
+import { StatusBar } from "expo-status-bar";
+import { useState } from "react";
+import { GestureHandlerRootView } from "react-native-gesture-handler";
+import "react-native-reanimated";
+import { ThemeProvider } from "@/lib/theme-provider";
+import { SafeAreaProvider, initialWindowMetrics } from "react-native-safe-area-context";
+import { ChatProvider } from "@/lib/chat-store";
+
+export const unstable_settings = {
+  anchor: "(tabs)",
+};
+
+export default function RootLayout() {
+  const [queryClient] = useState(
+    () =>
+      new QueryClient({
+        defaultOptions: {
+          queries: {
+            refetchOnWindowFocus: false,
+            retry: 1,
+          },
+        },
+      }),
+  );
+
+  return (
+    <ThemeProvider>
+      <SafeAreaProvider initialMetrics={initialWindowMetrics}>
+        <GestureHandlerRootView style={{ flex: 1 }}>
+          <QueryClientProvider client={queryClient}>
+            <ChatProvider>
+              <Stack screenOptions={{ headerShown: false }}>
+                <Stack.Screen name="(tabs)" />
+              </Stack>
+            </ChatProvider>
+            <StatusBar style="light" />
+          </QueryClientProvider>
+        </GestureHandlerRootView>
+      </SafeAreaProvider>
+    </ThemeProvider>
+  );
+}
diff --git a/mobile-app/assets/images/android-icon-background.png b/mobile-app/assets/images/android-icon-background.png
new file mode 100644
index 00000000..5ffefc5b
Binary files /dev/null and b/mobile-app/assets/images/android-icon-background.png differ
diff --git a/mobile-app/assets/images/android-icon-foreground.png b/mobile-app/assets/images/android-icon-foreground.png
new file mode 100644
index 00000000..bf882e06
Binary files /dev/null and b/mobile-app/assets/images/android-icon-foreground.png differ
diff --git a/mobile-app/assets/images/android-icon-monochrome.png b/mobile-app/assets/images/android-icon-monochrome.png
new file mode 100644
index 00000000..77484ebd
Binary files /dev/null and b/mobile-app/assets/images/android-icon-monochrome.png differ
diff --git a/mobile-app/assets/images/favicon.png b/mobile-app/assets/images/favicon.png
new file mode 100644
index 00000000..bf891e55
Binary files /dev/null and b/mobile-app/assets/images/favicon.png differ
diff --git a/mobile-app/assets/images/icon.png b/mobile-app/assets/images/icon.png
new file mode 100644
index 00000000..bf882e06
Binary files /dev/null and b/mobile-app/assets/images/icon.png differ
diff --git a/mobile-app/assets/images/splash-icon.png b/mobile-app/assets/images/splash-icon.png
new file mode 100644
index 00000000..d986b19b
Binary files /dev/null and b/mobile-app/assets/images/splash-icon.png differ
diff --git a/mobile-app/components/chat-bubble.tsx b/mobile-app/components/chat-bubble.tsx
new file mode 100644
index 00000000..f4e64f91
--- /dev/null
+++ b/mobile-app/components/chat-bubble.tsx
@@ -0,0 +1,214 @@
+import { useMemo } from "react";
+import { Text, View, StyleSheet, Image, Platform } from "react-native";
+import Pressable from "@/components/ui/pressable-fix";
+import { useColors } from "@/hooks/use-colors";
+import type { ChatMessage } from "@/shared/types";
+import { formatBytes, formatDuration } from "@/lib/chat-store";
+import MaterialIcons from "@expo/vector-icons/MaterialIcons";
+
+interface ChatBubbleProps {
+  message: ChatMessage;
+  onImagePress?: (uri: string) => void;
+  onPlayVoice?: (message: ChatMessage) => void;
+  isPlayingVoice?: boolean;
+}
+
+export function ChatBubble({ message, onImagePress, onPlayVoice, isPlayingVoice }: ChatBubbleProps) {
+  const colors = useColors();
+  const isUser = message.role === "user";
+
+  // Stable waveform bar heights based on message id
+  const waveHeights = useMemo(() => {
+    let seed = 0;
+    for (let i = 0; i < message.id.length; i++) seed = (seed * 31 + message.id.charCodeAt(i)) | 0;
+    return Array.from({ length: 12 }, (_, i) => {
+      seed = (seed * 16807 + i * 1013) % 2147483647;
+      return 4 + (seed % 15);
+    });
+  }, [message.id]);
+
+  const bubbleStyle = [
+    styles.bubble,
+    {
+      backgroundColor: isUser ? colors.primary : colors.surface,
+      borderColor: isUser ? colors.primary : colors.border,
+      alignSelf: isUser ? "flex-end" as const : "flex-start" as const,
+    },
+  ];
+
+  const textColor = isUser ? "#fff" : colors.foreground;
+  const mutedColor = isUser ? "rgba(255,255,255,0.6)" : colors.muted;
+
+  const timeStr = new Date(message.timestamp).toLocaleTimeString([], {
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+
+  return (
+    <View style={[styles.row, isUser ? styles.rowUser : styles.rowAssistant]}>
+      {!isUser && (
+        <View style={[styles.avatar, { backgroundColor: colors.primary }]}>
+          <Text style={styles.avatarText}>T</Text>
+        </View>
+      )}
+      <View style={bubbleStyle}>
+        {message.contentType === "text" && (
+          <Text style={[styles.text, { color: textColor }]}>{message.text}</Text>
+        )}
+
+        {message.contentType === "image" && (
+          <Pressable
+            onPress={() => message.uri && onImagePress?.(message.uri)}
+            style={({ pressed }) => [pressed && { opacity: 0.8 }]}
+          >
+            <Image
+              source={{ uri: message.uri }}
+              style={styles.image}
+              resizeMode="cover"
+            />
+            {message.text ? (
+              <Text style={[styles.text, { color: textColor, marginTop: 6 }]}>
+                {message.text}
+              </Text>
+            ) : null}
+          </Pressable>
+        )}
+
+        {message.contentType === "voice" && (
+          <Pressable
+            onPress={() => onPlayVoice?.(message)}
+            style={({ pressed }) => [styles.voiceRow, pressed && { opacity: 0.7 }]}
+          >
+            <MaterialIcons
+              name={isPlayingVoice ? "pause" : "play-arrow"}
+              size={24}
+              color={textColor}
+            />
+            <View style={[styles.waveform, { backgroundColor: isUser ? "rgba(255,255,255,0.3)" : colors.border }]}>
+              {waveHeights.map((h, i) => (
+                <View
+                  key={i}
+                  style={[
+                    styles.waveBar,
+                    {
+                      height: h,
+                      backgroundColor: textColor,
+                      opacity: 0.6,
+                    },
+                  ]}
+                />
+              ))}
+            </View>
+            <Text style={[styles.duration, { color: mutedColor }]}>
+              {formatDuration(message.duration ?? 0)}
+            </Text>
+          </Pressable>
+        )}
+
+        {message.contentType === "file" && (
+          <View style={styles.fileRow}>
+            <MaterialIcons name="insert-drive-file" size={28} color={textColor} />
+            <View style={styles.fileInfo}>
+              <Text style={[styles.fileName, { color: textColor }]} numberOfLines={1}>
+                {message.fileName ?? "File"}
+              </Text>
+              <Text style={[styles.fileSize, { color: mutedColor }]}>
+                {formatBytes(message.fileSize ?? 0)}
+              </Text>
+            </View>
+          </View>
+        )}
+
+        <Text style={[styles.time, { color: mutedColor }]}>{timeStr}</Text>
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  row: {
+    flexDirection: "row",
+    marginBottom: 8,
+    paddingHorizontal: 12,
+    alignItems: "flex-end",
+  },
+  rowUser: {
+    justifyContent: "flex-end",
+  },
+  rowAssistant: {
+    justifyContent: "flex-start",
+  },
+  avatar: {
+    width: 30,
+    height: 30,
+    borderRadius: 15,
+    alignItems: "center",
+    justifyContent: "center",
+    marginRight: 8,
+  },
+  avatarText: {
+    color: "#fff",
+    fontWeight: "700",
+    fontSize: 14,
+  },
+  bubble: {
+    maxWidth: "78%",
+    borderRadius: 16,
+    borderWidth: 1,
+    paddingHorizontal: 14,
+    paddingVertical: 10,
+  },
+  text: {
+    fontSize: 15,
+    lineHeight: 21,
+  },
+  time: {
+    fontSize: 10,
+    marginTop: 4,
+    textAlign: "right",
+  },
+  image: {
+    width: 220,
+    height: 180,
+    borderRadius: 10,
+  },
+  voiceRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 8,
+    minWidth: 160,
+  },
+  waveform: {
+    flex: 1,
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 2,
+    height: 24,
+    borderRadius: 4,
+    paddingHorizontal: 4,
+  },
+  waveBar: {
+    width: 3,
+    borderRadius: 1.5,
+  },
+  duration: {
+    fontSize: 12,
+    minWidth: 32,
+  },
+  fileRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 10,
+  },
+  fileInfo: {
+    flex: 1,
+  },
+  fileName: {
+    fontSize: 14,
+    fontWeight: "600",
+  },
+  fileSize: {
+    fontSize: 11,
+    marginTop: 2,
+  },
+});
diff --git a/mobile-app/components/chat-header.tsx b/mobile-app/components/chat-header.tsx
new file mode 100644
index 00000000..4fcdc177
--- /dev/null
+++ b/mobile-app/components/chat-header.tsx
@@ -0,0 +1,69 @@
+import { View, Text, StyleSheet } from "react-native";
+import Pressable from "@/components/ui/pressable-fix";
+import MaterialIcons from "@expo/vector-icons/MaterialIcons";
+import { useColors } from "@/hooks/use-colors";
+import { useChat } from "@/lib/chat-store";
+
+export function ChatHeader() {
+  const colors = useColors();
+  const { clearChat } = useChat();
+
+  return (
+    <View style={[styles.header, { backgroundColor: colors.background, borderBottomColor: colors.border }]}>
+      <View style={styles.left}>
+        <View style={[styles.statusDot, { backgroundColor: colors.success }]} />
+        <Text style={[styles.title, { color: colors.foreground }]}>TIMMY</Text>
+        <Text style={[styles.subtitle, { color: colors.muted }]}>SOVEREIGN AI</Text>
+      </View>
+      <Pressable
+        onPress={clearChat}
+        style={({ pressed }: { pressed: boolean }) => [
+          styles.clearBtn,
+          { borderColor: colors.border },
+          pressed && { opacity: 0.6 },
+        ]}
+      >
+        <MaterialIcons name="delete-outline" size={16} color={colors.muted} />
+      </Pressable>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  header: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "space-between",
+    paddingHorizontal: 16,
+    paddingVertical: 10,
+    borderBottomWidth: 1,
+  },
+  left: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 8,
+  },
+  statusDot: {
+    width: 8,
+    height: 8,
+    borderRadius: 4,
+  },
+  title: {
+    fontSize: 16,
+    fontWeight: "700",
+    letterSpacing: 2,
+  },
+  subtitle: {
+    fontSize: 9,
+    letterSpacing: 1.5,
+    fontWeight: "600",
+  },
+  clearBtn: {
+    width: 32,
+    height: 32,
+    borderRadius: 16,
+    borderWidth: 1,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+});
diff --git a/mobile-app/components/chat-input.tsx b/mobile-app/components/chat-input.tsx
new file mode 100644
index 00000000..56545556
--- /dev/null
+++ b/mobile-app/components/chat-input.tsx
@@ -0,0 +1,301 @@
+import { useCallback, useRef, useState } from "react";
+import {
+  View,
+  TextInput,
+  StyleSheet,
+  Platform,
+  ActionSheetIOS,
+  Alert,
+  Keyboard,
+} from "react-native";
+import Pressable from "@/components/ui/pressable-fix";
+import MaterialIcons from "@expo/vector-icons/MaterialIcons";
+import { useColors } from "@/hooks/use-colors";
+import { useChat } from "@/lib/chat-store";
+import * as ImagePicker from "expo-image-picker";
+import * as DocumentPicker from "expo-document-picker";
+import {
+  useAudioRecorder,
+  useAudioRecorderState,
+  RecordingPresets,
+  requestRecordingPermissionsAsync,
+  setAudioModeAsync,
+} from "expo-audio";
+import * as Haptics from "expo-haptics";
+
+export function ChatInput() {
+  const colors = useColors();
+  const { sendTextMessage, sendAttachment, isTyping } = useChat();
+  const [text, setText] = useState("");
+  const [isRecording, setIsRecording] = useState(false);
+  const inputRef = useRef<TextInput>(null);
+
+  const audioRecorder = useAudioRecorder(RecordingPresets.HIGH_QUALITY);
+  const recorderState = useAudioRecorderState(audioRecorder);
+
+  const handleSend = useCallback(() => {
+    const trimmed = text.trim();
+    if (!trimmed) return;
+    setText("");
+    Keyboard.dismiss();
+    if (Platform.OS !== "web") {
+      Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);
+    }
+    sendTextMessage(trimmed);
+  }, [text, sendTextMessage]);
+
+  // ── Attachment sheet ────────────────────────────────────────────────────
+
+  const handleAttachment = useCallback(() => {
+    if (Platform.OS !== "web") {
+      Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);
+    }
+
+    const options = ["Take Photo", "Choose from Library", "Choose File", "Cancel"];
+    const cancelIndex = 3;
+
+    if (Platform.OS === "ios") {
+      ActionSheetIOS.showActionSheetWithOptions(
+        { options, cancelButtonIndex: cancelIndex },
+        (idx) => {
+          if (idx === 0) takePhoto();
+          else if (idx === 1) pickImage();
+          else if (idx === 2) pickFile();
+        },
+      );
+    } else {
+      // Android / Web fallback
+      Alert.alert("Attach", "Choose an option", [
+        { text: "Take Photo", onPress: takePhoto },
+        { text: "Choose from Library", onPress: pickImage },
+        { text: "Choose File", onPress: pickFile },
+        { text: "Cancel", style: "cancel" },
+      ]);
+    }
+  }, []);
+
+  const takePhoto = async () => {
+    const { status } = await ImagePicker.requestCameraPermissionsAsync();
+    if (status !== "granted") {
+      Alert.alert("Permission needed", "Camera access is required to take photos.");
+      return;
+    }
+    const result = await ImagePicker.launchCameraAsync({
+      quality: 0.8,
+      allowsEditing: false,
+    });
+    if (!result.canceled && result.assets[0]) {
+      const asset = result.assets[0];
+      sendAttachment({
+        contentType: "image",
+        uri: asset.uri,
+        fileName: asset.fileName ?? "photo.jpg",
+        fileSize: asset.fileSize,
+        mimeType: asset.mimeType ?? "image/jpeg",
+      });
+    }
+  };
+
+  const pickImage = async () => {
+    const result = await ImagePicker.launchImageLibraryAsync({
+      mediaTypes: ["images"],
+      quality: 0.8,
+      allowsEditing: false,
+    });
+    if (!result.canceled && result.assets[0]) {
+      const asset = result.assets[0];
+      sendAttachment({
+        contentType: "image",
+        uri: asset.uri,
+        fileName: asset.fileName ?? "image.jpg",
+        fileSize: asset.fileSize,
+        mimeType: asset.mimeType ?? "image/jpeg",
+      });
+    }
+  };
+
+  const pickFile = async () => {
+    try {
+      const result = await DocumentPicker.getDocumentAsync({
+        type: "*/*",
+        copyToCacheDirectory: true,
+      });
+      if (!result.canceled && result.assets[0]) {
+        const asset = result.assets[0];
+        sendAttachment({
+          contentType: "file",
+          uri: asset.uri,
+          fileName: asset.name,
+          fileSize: asset.size,
+          mimeType: asset.mimeType ?? "application/octet-stream",
+        });
+      }
+    } catch (err) {
+      console.warn("Document picker error:", err);
+    }
+  };
+
+  // ── Voice recording ───────────────────────────────────────────────────
+
+  const startRecording = async () => {
+    try {
+      const { granted } = await requestRecordingPermissionsAsync();
+      if (!granted) {
+        Alert.alert("Permission needed", "Microphone access is required for voice messages.");
+        return;
+      }
+      await setAudioModeAsync({ playsInSilentMode: true, allowsRecording: true });
+      await audioRecorder.prepareToRecordAsync();
+      audioRecorder.record();
+      setIsRecording(true);
+      if (Platform.OS !== "web") {
+        Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Medium);
+      }
+    } catch (err) {
+      console.warn("Recording start error:", err);
+    }
+  };
+
+  const stopRecording = async () => {
+    try {
+      await audioRecorder.stop();
+      setIsRecording(false);
+      if (Platform.OS !== "web") {
+        Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success);
+      }
+      const uri = audioRecorder.uri;
+      if (uri) {
+        const duration = recorderState.durationMillis ? recorderState.durationMillis / 1000 : 0;
+        sendAttachment({
+          contentType: "voice",
+          uri,
+          fileName: "voice_message.m4a",
+          mimeType: "audio/m4a",
+          duration,
+        });
+      }
+    } catch (err) {
+      console.warn("Recording stop error:", err);
+      setIsRecording(false);
+    }
+  };
+
+  const handleMicPress = useCallback(() => {
+    if (isRecording) {
+      stopRecording();
+    } else {
+      startRecording();
+    }
+  }, [isRecording]);
+
+  const hasText = text.trim().length > 0;
+
+  return (
+    <View style={[styles.container, { backgroundColor: colors.background, borderTopColor: colors.border }]}>
+      {/* Attachment button */}
+      <Pressable
+        onPress={handleAttachment}
+        style={({ pressed }: { pressed: boolean }) => [
+          styles.iconBtn,
+          { backgroundColor: colors.surface },
+          pressed && { opacity: 0.6 },
+        ]}
+        disabled={isTyping}
+      >
+        <MaterialIcons name="add" size={22} color={colors.muted} />
+      </Pressable>
+
+      {/* Text input */}
+      <TextInput
+        ref={inputRef}
+        value={text}
+        onChangeText={setText}
+        placeholder={isRecording ? "Recording..." : "Message Timmy..."}
+        placeholderTextColor={colors.muted}
+        style={[
+          styles.input,
+          {
+            backgroundColor: colors.surface,
+            color: colors.foreground,
+            borderColor: colors.border,
+          },
+        ]}
+        multiline
+        maxLength={4000}
+        returnKeyType="default"
+        editable={!isRecording && !isTyping}
+        onSubmitEditing={handleSend}
+        blurOnSubmit={false}
+      />
+
+      {/* Send or Mic button */}
+      {hasText ? (
+        <Pressable
+          onPress={handleSend}
+          style={({ pressed }: { pressed: boolean }) => [
+            styles.sendBtn,
+            { backgroundColor: colors.primary },
+            pressed && { transform: [{ scale: 0.95 }], opacity: 0.9 },
+          ]}
+          disabled={isTyping}
+        >
+          <MaterialIcons name="send" size={20} color="#fff" />
+        </Pressable>
+      ) : (
+        <Pressable
+          onPress={handleMicPress}
+          style={({ pressed }: { pressed: boolean }) => [
+            styles.sendBtn,
+            {
+              backgroundColor: isRecording ? colors.error : colors.surface,
+            },
+            pressed && { transform: [{ scale: 0.95 }], opacity: 0.9 },
+          ]}
+          disabled={isTyping}
+        >
+          <MaterialIcons
+            name={isRecording ? "stop" : "mic"}
+            size={20}
+            color={isRecording ? "#fff" : colors.primary}
+          />
+        </Pressable>
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flexDirection: "row",
+    alignItems: "flex-end",
+    paddingHorizontal: 10,
+    paddingVertical: 8,
+    gap: 8,
+    borderTopWidth: 1,
+  },
+  iconBtn: {
+    width: 38,
+    height: 38,
+    borderRadius: 19,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  input: {
+    flex: 1,
+    minHeight: 38,
+    maxHeight: 120,
+    borderRadius: 19,
+    borderWidth: 1,
+    paddingHorizontal: 14,
+    paddingVertical: 8,
+    fontSize: 15,
+    lineHeight: 20,
+  },
+  sendBtn: {
+    width: 38,
+    height: 38,
+    borderRadius: 19,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+});
diff --git a/mobile-app/components/empty-chat.tsx b/mobile-app/components/empty-chat.tsx
new file mode 100644
index 00000000..f2a488c4
--- /dev/null
+++ b/mobile-app/components/empty-chat.tsx
@@ -0,0 +1,55 @@
+import { View, Text, StyleSheet } from "react-native";
+import { useColors } from "@/hooks/use-colors";
+import MaterialIcons from "@expo/vector-icons/MaterialIcons";
+
+export function EmptyChat() {
+  const colors = useColors();
+
+  return (
+    <View style={styles.container}>
+      <View style={[styles.iconCircle, { backgroundColor: colors.surface, borderColor: colors.border }]}>
+        <MaterialIcons name="chat-bubble-outline" size={40} color={colors.primary} />
+      </View>
+      <Text style={[styles.title, { color: colors.foreground }]}>TIMMY</Text>
+      <Text style={[styles.subtitle, { color: colors.muted }]}>SOVEREIGN AI AGENT</Text>
+      <Text style={[styles.hint, { color: colors.muted }]}>
+        Send a message, voice note, image, or file to get started.
+      </Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    justifyContent: "center",
+    alignItems: "center",
+    paddingHorizontal: 40,
+    gap: 8,
+  },
+  iconCircle: {
+    width: 80,
+    height: 80,
+    borderRadius: 40,
+    borderWidth: 1,
+    alignItems: "center",
+    justifyContent: "center",
+    marginBottom: 12,
+  },
+  title: {
+    fontSize: 24,
+    fontWeight: "700",
+    letterSpacing: 4,
+  },
+  subtitle: {
+    fontSize: 11,
+    letterSpacing: 2,
+    fontWeight: "600",
+  },
+  hint: {
+    fontSize: 13,
+    textAlign: "center",
+    marginTop: 12,
+    lineHeight: 19,
+  },
+});
diff --git a/mobile-app/components/haptic-tab.tsx b/mobile-app/components/haptic-tab.tsx
new file mode 100644
index 00000000..a5674761
--- /dev/null
+++ b/mobile-app/components/haptic-tab.tsx
@@ -0,0 +1,18 @@
+import { BottomTabBarButtonProps } from "@react-navigation/bottom-tabs";
+import { PlatformPressable } from "@react-navigation/elements";
+import * as Haptics from "expo-haptics";
+
+export function HapticTab(props: BottomTabBarButtonProps) {
+  return (
+    <PlatformPressable
+      {...props}
+      onPressIn={(ev) => {
+        if (process.env.EXPO_OS === "ios") {
+          // Add a soft haptic feedback when pressing down on the tabs.
+          Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);
+        }
+        props.onPressIn?.(ev);
+      }}
+    />
+  );
+}
diff --git a/mobile-app/components/image-viewer.tsx b/mobile-app/components/image-viewer.tsx
new file mode 100644
index 00000000..e37dfe0a
--- /dev/null
+++ b/mobile-app/components/image-viewer.tsx
@@ -0,0 +1,54 @@
+import { Modal, View, Image, StyleSheet, StatusBar } from "react-native";
+import Pressable from "@/components/ui/pressable-fix";
+import MaterialIcons from "@expo/vector-icons/MaterialIcons";
+
+interface ImageViewerProps {
+  uri: string | null;
+  onClose: () => void;
+}
+
+export function ImageViewer({ uri, onClose }: ImageViewerProps) {
+  if (!uri) return null;
+
+  return (
+    <Modal visible animationType="fade" transparent statusBarTranslucent>
+      <View style={styles.overlay}>
+        <StatusBar barStyle="light-content" />
+        <Image source={{ uri }} style={styles.image} resizeMode="contain" />
+        <Pressable
+          onPress={onClose}
+          style={({ pressed }: { pressed: boolean }) => [
+            styles.closeBtn,
+            pressed && { opacity: 0.6 },
+          ]}
+        >
+          <MaterialIcons name="close" size={28} color="#fff" />
+        </Pressable>
+      </View>
+    </Modal>
+  );
+}
+
+const styles = StyleSheet.create({
+  overlay: {
+    flex: 1,
+    backgroundColor: "rgba(0,0,0,0.95)",
+    justifyContent: "center",
+    alignItems: "center",
+  },
+  image: {
+    width: "100%",
+    height: "80%",
+  },
+  closeBtn: {
+    position: "absolute",
+    top: 50,
+    right: 20,
+    width: 40,
+    height: 40,
+    borderRadius: 20,
+    backgroundColor: "rgba(255,255,255,0.15)",
+    alignItems: "center",
+    justifyContent: "center",
+  },
+});
diff --git a/mobile-app/components/screen-container.tsx b/mobile-app/components/screen-container.tsx
new file mode 100644
index 00000000..20b0b997
--- /dev/null
+++ b/mobile-app/components/screen-container.tsx
@@ -0,0 +1,68 @@
+import { View, type ViewProps } from "react-native";
+import { SafeAreaView, type Edge } from "react-native-safe-area-context";
+
+import { cn } from "@/lib/utils";
+
+export interface ScreenContainerProps extends ViewProps {
+  /**
+   * SafeArea edges to apply. Defaults to ["top", "left", "right"].
+   * Bottom is typically handled by Tab Bar.
+   */
+  edges?: Edge[];
+  /**
+   * Tailwind className for the content area.
+   */
+  className?: string;
+  /**
+   * Additional className for the outer container (background layer).
+   */
+  containerClassName?: string;
+  /**
+   * Additional className for the SafeAreaView (content layer).
+   */
+  safeAreaClassName?: string;
+}
+
+/**
+ * A container component that properly handles SafeArea and background colors.
+ *
+ * The outer View extends to full screen (including status bar area) with the background color,
+ * while the inner SafeAreaView ensures content is within safe bounds.
+ *
+ * Usage:
+ * ```tsx
+ * <ScreenContainer className="p-4">
+ *   <Text className="text-2xl font-bold text-foreground">
+ *     Welcome
+ *   </Text>
+ * </ScreenContainer>
+ * ```
+ */
+export function ScreenContainer({
+  children,
+  edges = ["top", "left", "right"],
+  className,
+  containerClassName,
+  safeAreaClassName,
+  style,
+  ...props
+}: ScreenContainerProps) {
+  return (
+    <View
+      className={cn(
+        "flex-1",
+        "bg-background",
+        containerClassName
+      )}
+      {...props}
+    >
+      <SafeAreaView
+        edges={edges}
+        className={cn("flex-1", safeAreaClassName)}
+        style={style}
+      >
+        <View className={cn("flex-1", className)}>{children}</View>
+      </SafeAreaView>
+    </View>
+  );
+}
diff --git a/mobile-app/components/themed-view.tsx b/mobile-app/components/themed-view.tsx
new file mode 100644
index 00000000..2959350b
--- /dev/null
+++ b/mobile-app/components/themed-view.tsx
@@ -0,0 +1,15 @@
+import { View, type ViewProps } from "react-native";
+
+import { cn } from "@/lib/utils";
+
+export interface ThemedViewProps extends ViewProps {
+  className?: string;
+}
+
+/**
+ * A View component with automatic theme-aware background.
+ * Uses NativeWind for styling - pass className for additional styles.
+ */
+export function ThemedView({ className, ...otherProps }: ThemedViewProps) {
+  return <View className={cn("bg-background", className)} {...otherProps} />;
+}
diff --git a/mobile-app/components/typing-indicator.tsx b/mobile-app/components/typing-indicator.tsx
new file mode 100644
index 00000000..6dcee973
--- /dev/null
+++ b/mobile-app/components/typing-indicator.tsx
@@ -0,0 +1,89 @@
+import { useEffect } from "react";
+import { View, StyleSheet } from "react-native";
+import Animated, {
+  useSharedValue,
+  useAnimatedStyle,
+  withRepeat,
+  withTiming,
+  withDelay,
+  withSequence,
+} from "react-native-reanimated";
+import { useColors } from "@/hooks/use-colors";
+
+export function TypingIndicator() {
+  const colors = useColors();
+  const dot1 = useSharedValue(0.3);
+  const dot2 = useSharedValue(0.3);
+  const dot3 = useSharedValue(0.3);
+
+  useEffect(() => {
+    const anim = (sv: { value: number }, delay: number) => {
+      sv.value = withDelay(
+        delay,
+        withRepeat(
+          withSequence(
+            withTiming(1, { duration: 400 }),
+            withTiming(0.3, { duration: 400 }),
+          ),
+          -1,
+        ),
+      );
+    };
+    anim(dot1, 0);
+    anim(dot2, 200);
+    anim(dot3, 400);
+  }, []);
+
+  const style1 = useAnimatedStyle(() => ({ opacity: dot1.value }));
+  const style2 = useAnimatedStyle(() => ({ opacity: dot2.value }));
+  const style3 = useAnimatedStyle(() => ({ opacity: dot3.value }));
+
+  const dotBase = [styles.dot, { backgroundColor: colors.primary }];
+
+  return (
+    <View style={[styles.row, { alignItems: "flex-end" }]}>
+      <View style={[styles.avatar, { backgroundColor: colors.primary }]}>
+        <Animated.Text style={styles.avatarText}>T</Animated.Text>
+      </View>
+      <View style={[styles.bubble, { backgroundColor: colors.surface, borderColor: colors.border }]}>
+        <Animated.View style={[dotBase, style1]} />
+        <Animated.View style={[dotBase, style2]} />
+        <Animated.View style={[dotBase, style3]} />
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  row: {
+    flexDirection: "row",
+    paddingHorizontal: 12,
+    marginBottom: 8,
+  },
+  avatar: {
+    width: 30,
+    height: 30,
+    borderRadius: 15,
+    alignItems: "center",
+    justifyContent: "center",
+    marginRight: 8,
+  },
+  avatarText: {
+    color: "#fff",
+    fontWeight: "700",
+    fontSize: 14,
+  },
+  bubble: {
+    flexDirection: "row",
+    gap: 5,
+    paddingHorizontal: 16,
+    paddingVertical: 14,
+    borderRadius: 16,
+    borderWidth: 1,
+  },
+  dot: {
+    width: 8,
+    height: 8,
+    borderRadius: 4,
+  },
+});
diff --git a/mobile-app/components/ui/icon-symbol.tsx b/mobile-app/components/ui/icon-symbol.tsx
new file mode 100644
index 00000000..12c226c2
--- /dev/null
+++ b/mobile-app/components/ui/icon-symbol.tsx
@@ -0,0 +1,41 @@
+// Fallback for using MaterialIcons on Android and web.
+
+import MaterialIcons from "@expo/vector-icons/MaterialIcons";
+import { SymbolWeight, SymbolViewProps } from "expo-symbols";
+import { ComponentProps } from "react";
+import { OpaqueColorValue, type StyleProp, type TextStyle } from "react-native";
+
+type IconMapping = Record<SymbolViewProps["name"], ComponentProps<typeof MaterialIcons>["name"]>;
+type IconSymbolName = keyof typeof MAPPING;
+
+/**
+ * Add your SF Symbols to Material Icons mappings here.
+ * - see Material Icons in the [Icons Directory](https://icons.expo.fyi).
+ * - see SF Symbols in the [SF Symbols](https://developer.apple.com/sf-symbols/) app.
+ */
+const MAPPING = {
+  "house.fill": "home",
+  "paperplane.fill": "send",
+  "chevron.left.forwardslash.chevron.right": "code",
+  "chevron.right": "chevron-right",
+} as IconMapping;
+
+/**
+ * An icon component that uses native SF Symbols on iOS, and Material Icons on Android and web.
+ * This ensures a consistent look across platforms, and optimal resource usage.
+ * Icon `name`s are based on SF Symbols and require manual mapping to Material Icons.
+ */
+export function IconSymbol({
+  name,
+  size = 24,
+  color,
+  style,
+}: {
+  name: IconSymbolName;
+  size?: number;
+  color: string | OpaqueColorValue;
+  style?: StyleProp<TextStyle>;
+  weight?: SymbolWeight;
+}) {
+  return <MaterialIcons color={color} size={size} name={MAPPING[name]} style={style} />;
+}
diff --git a/mobile-app/components/ui/pressable-fix.tsx b/mobile-app/components/ui/pressable-fix.tsx
new file mode 100644
index 00000000..d44c0d53
--- /dev/null
+++ b/mobile-app/components/ui/pressable-fix.tsx
@@ -0,0 +1,6 @@
+/**
+ * Re-export Pressable with proper typing for style callbacks.
+ * NativeWind disables className on Pressable, so we always use the style prop.
+ */
+import { Pressable } from "react-native";
+export default Pressable;
diff --git a/mobile-app/constants/theme.ts b/mobile-app/constants/theme.ts
new file mode 100644
index 00000000..7dc18b1a
--- /dev/null
+++ b/mobile-app/constants/theme.ts
@@ -0,0 +1,12 @@
+/**
+ * Thin re-exports so consumers don't need to know about internal theme plumbing.
+ * Full implementation lives in lib/_core/theme.ts.
+ */
+export {
+  Colors,
+  Fonts,
+  SchemeColors,
+  ThemeColors,
+  type ColorScheme,
+  type ThemeColorPalette,
+} from "@/lib/_core/theme";
diff --git a/mobile-app/design.md b/mobile-app/design.md
new file mode 100644
index 00000000..275a9851
--- /dev/null
+++ b/mobile-app/design.md
@@ -0,0 +1,80 @@
+# Timmy Chat — Mobile App Design
+
+## Overview
+A sleek, single-screen chat app for talking to Timmy — the sovereign AI agent from the Timmy Time dashboard. Supports text, voice, image, and file messaging. Dark arcane theme matching Mission Control.
+
+## Screen List
+
+### 1. Chat Screen (Home / Only Screen)
+The entire app is a single full-screen chat interface. No tabs, no settings, no extra screens. Just you and Timmy.
+
+### 2. No Other Screens
+No settings, no profile, no onboarding. The app opens straight to chat.
+
+## Primary Content and Functionality
+
+### Chat Screen
+- **Header**: "TIMMY" title with status indicator (online/offline dot), minimal and clean
+- **Message List**: Full-screen scrollable message list (FlatList, inverted)
+  - User messages: right-aligned, purple/violet accent bubble
+  - Timmy messages: left-aligned, dark surface bubble with avatar initial "T"
+  - Image messages: thumbnail preview in bubble, tappable for full-screen
+  - File messages: file icon + filename + size in bubble
+  - Voice messages: waveform-style playback bar with play/pause + duration
+  - Timestamps shown subtly below message groups
+- **Input Bar** (bottom, always visible):
+  - Text input field (expandable, multi-line)
+  - Attachment button (left of input) — opens action sheet: Camera, Photo Library, File
+  - Voice record button (right of input, replaces send when input is empty)
+  - Send button (right of input, appears when text is entered)
+  - Hold-to-record voice: press and hold mic icon, release to send
+
+## Key User Flows
+
+### Text Chat
+1. User types message → taps Send
+2. Message appears in chat as "sending"
+3. Server responds → Timmy's reply appears below
+
+### Voice Message
+1. User presses and holds mic button
+2. Recording indicator appears (duration + pulsing dot)
+3. User releases → voice message sent
+4. Timmy responds with text (server processes audio)
+
+### Image Sharing
+1. User taps attachment (+) button
+2. Action sheet: "Take Photo" / "Choose from Library"
+3. Image appears as thumbnail in chat
+4. Timmy acknowledges receipt
+
+### File Sharing
+1. User taps attachment (+) button → "Choose File"
+2. Document picker opens
+3. File appears in chat with name + size
+4. Timmy acknowledges receipt
+
+## Color Choices (Arcane Dark Theme)
+
+Matching the Timmy Time Mission Control dashboard:
+
+| Token       | Dark Value   | Purpose                        |
+|-------------|-------------|--------------------------------|
+| background  | #080412     | Deep dark purple-black          |
+| surface     | #110820     | Card/bubble background          |
+| foreground  | #ede0ff     | Primary text (bright lavender)  |
+| muted       | #6b4a8a     | Secondary/timestamp text        |
+| primary     | #a855f7     | Accent purple (user bubbles)    |
+| border      | #3b1a5c     | Subtle borders                  |
+| success     | #00e87a     | Online status, success          |
+| warning     | #ffb800     | Amber warnings                  |
+| error       | #ff4455     | Error states                    |
+
+## Layout Specifics (Portrait 9:16, One-Handed)
+
+- Input bar pinned to bottom with safe area padding
+- Send/mic button on right (thumb-reachable)
+- Attachment button on left of input
+- Messages fill remaining space above input
+- No tab bar — single screen app
+- Header is compact (44pt) with just title + status dot
diff --git a/mobile-app/global.css b/mobile-app/global.css
new file mode 100644
index 00000000..b5c61c95
--- /dev/null
+++ b/mobile-app/global.css
@@ -0,0 +1,3 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
diff --git a/mobile-app/hooks/use-color-scheme.ts b/mobile-app/hooks/use-color-scheme.ts
new file mode 100644
index 00000000..670e0f01
--- /dev/null
+++ b/mobile-app/hooks/use-color-scheme.ts
@@ -0,0 +1,5 @@
+import { useThemeContext } from "@/lib/theme-provider";
+
+export function useColorScheme() {
+  return useThemeContext().colorScheme;
+}
diff --git a/mobile-app/hooks/use-color-scheme.web.ts b/mobile-app/hooks/use-color-scheme.web.ts
new file mode 100644
index 00000000..66cccac5
--- /dev/null
+++ b/mobile-app/hooks/use-color-scheme.web.ts
@@ -0,0 +1,21 @@
+import { useEffect, useState } from "react";
+import { useColorScheme as useRNColorScheme } from "react-native";
+
+/**
+ * To support static rendering, this value needs to be re-calculated on the client side for web
+ */
+export function useColorScheme() {
+  const [hasHydrated, setHasHydrated] = useState(false);
+
+  useEffect(() => {
+    setHasHydrated(true);
+  }, []);
+
+  const colorScheme = useRNColorScheme();
+
+  if (hasHydrated) {
+    return colorScheme;
+  }
+
+  return "light";
+}
diff --git a/mobile-app/hooks/use-colors.ts b/mobile-app/hooks/use-colors.ts
new file mode 100644
index 00000000..f891d27b
--- /dev/null
+++ b/mobile-app/hooks/use-colors.ts
@@ -0,0 +1,12 @@
+import { Colors, type ColorScheme, type ThemeColorPalette } from "@/constants/theme";
+import { useColorScheme } from "./use-color-scheme";
+
+/**
+ * Returns the current theme's color palette.
+ * Usage: const colors = useColors(); then colors.text, colors.background, etc.
+ */
+export function useColors(colorSchemeOverride?: ColorScheme): ThemeColorPalette {
+  const colorSchema = useColorScheme();
+  const scheme = (colorSchemeOverride ?? colorSchema ?? "light") as ColorScheme;
+  return Colors[scheme];
+}
diff --git a/mobile-app/lib/chat-store.tsx b/mobile-app/lib/chat-store.tsx
new file mode 100644
index 00000000..f56b51cc
--- /dev/null
+++ b/mobile-app/lib/chat-store.tsx
@@ -0,0 +1,298 @@
+import React, { createContext, useCallback, useContext, useReducer, type ReactNode } from "react";
+import type { ChatMessage, MessageContentType } from "@/shared/types";
+
+// ── State ───────────────────────────────────────────────────────────────────
+
+interface ChatState {
+  messages: ChatMessage[];
+  isTyping: boolean;
+}
+
+const initialState: ChatState = {
+  messages: [],
+  isTyping: false,
+};
+
+// ── Actions ─────────────────────────────────────────────────────────────────
+
+type ChatAction =
+  | { type: "ADD_MESSAGE"; message: ChatMessage }
+  | { type: "UPDATE_MESSAGE"; id: string; updates: Partial<ChatMessage> }
+  | { type: "SET_TYPING"; isTyping: boolean }
+  | { type: "CLEAR" };
+
+function chatReducer(state: ChatState, action: ChatAction): ChatState {
+  switch (action.type) {
+    case "ADD_MESSAGE":
+      return { ...state, messages: [...state.messages, action.message] };
+    case "UPDATE_MESSAGE":
+      return {
+        ...state,
+        messages: state.messages.map((m) =>
+          m.id === action.id ? { ...m, ...action.updates } : m,
+        ),
+      };
+    case "SET_TYPING":
+      return { ...state, isTyping: action.isTyping };
+    case "CLEAR":
+      return initialState;
+    default:
+      return state;
+  }
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+let _counter = 0;
+function makeId(): string {
+  return `msg_${Date.now()}_${++_counter}`;
+}
+
+// ── Context ─────────────────────────────────────────────────────────────────
+
+interface ChatContextValue {
+  messages: ChatMessage[];
+  isTyping: boolean;
+  sendTextMessage: (text: string) => Promise<void>;
+  sendAttachment: (opts: {
+    contentType: MessageContentType;
+    uri: string;
+    fileName?: string;
+    fileSize?: number;
+    mimeType?: string;
+    duration?: number;
+    text?: string;
+  }) => Promise<void>;
+  clearChat: () => void;
+}
+
+const ChatContext = createContext<ChatContextValue | null>(null);
+
+// ── API call ────────────────────────────────────────────────────────────────
+
+function getApiBase(): string {
+  // Set EXPO_PUBLIC_API_BASE_URL in your .env to point to your Timmy backend
+  // e.g. EXPO_PUBLIC_API_BASE_URL=http://192.168.1.100:3000
+  const envBase = process.env.EXPO_PUBLIC_API_BASE_URL;
+  if (envBase) return envBase.replace(/\/+$/, "");
+  // Fallback for web: derive from window location
+  if (typeof window !== "undefined" && window.location) {
+    return `${window.location.protocol}//${window.location.hostname}:3000`;
+  }
+  // Default: local machine
+  return "http://127.0.0.1:3000";
+}
+
+const API_BASE = getApiBase();
+
+async function callChatAPI(
+  messages: Array<{ role: string; content: string | Array<Record<string, unknown>> }>,
+): Promise<string> {
+  const res = await fetch(`${API_BASE}/api/chat`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ messages }),
+  });
+  if (!res.ok) {
+    const errText = await res.text().catch(() => res.statusText);
+    throw new Error(`Chat API error: ${errText}`);
+  }
+  const data = await res.json();
+  return data.reply ?? data.text ?? "...";
+}
+
+async function uploadFile(
+  uri: string,
+  fileName: string,
+  mimeType: string,
+): Promise<string> {
+  const formData = new FormData();
+  formData.append("file", {
+    uri,
+    name: fileName,
+    type: mimeType,
+  } as unknown as Blob);
+
+  const res = await fetch(`${API_BASE}/api/upload`, {
+    method: "POST",
+    body: formData,
+  });
+  if (!res.ok) throw new Error("Upload failed");
+  const data = await res.json();
+  return data.url;
+}
+
+// ── Provider ────────────────────────────────────────────────────────────────
+
+export function ChatProvider({ children }: { children: ReactNode }) {
+  const [state, dispatch] = useReducer(chatReducer, initialState);
+
+  const sendTextMessage = useCallback(
+    async (text: string) => {
+      const userMsg: ChatMessage = {
+        id: makeId(),
+        role: "user",
+        contentType: "text",
+        text,
+        timestamp: Date.now(),
+      };
+      dispatch({ type: "ADD_MESSAGE", message: userMsg });
+      dispatch({ type: "SET_TYPING", isTyping: true });
+
+      try {
+        // Build conversation context (last 20 messages)
+        const recent = [...state.messages, userMsg].slice(-20);
+        const apiMessages = recent
+          .filter((m) => m.contentType === "text" && m.text)
+          .map((m) => ({ role: m.role, content: m.text! }));
+
+        const reply = await callChatAPI(apiMessages);
+        const assistantMsg: ChatMessage = {
+          id: makeId(),
+          role: "assistant",
+          contentType: "text",
+          text: reply,
+          timestamp: Date.now(),
+        };
+        dispatch({ type: "ADD_MESSAGE", message: assistantMsg });
+      } catch (err: unknown) {
+        const errorText = err instanceof Error ? err.message : "Something went wrong";
+        dispatch({
+          type: "ADD_MESSAGE",
+          message: {
+            id: makeId(),
+            role: "assistant",
+            contentType: "text",
+            text: `Sorry, I couldn't process that: ${errorText}`,
+            timestamp: Date.now(),
+          },
+        });
+      } finally {
+        dispatch({ type: "SET_TYPING", isTyping: false });
+      }
+    },
+    [state.messages],
+  );
+
+  const sendAttachment = useCallback(
+    async (opts: {
+      contentType: MessageContentType;
+      uri: string;
+      fileName?: string;
+      fileSize?: number;
+      mimeType?: string;
+      duration?: number;
+      text?: string;
+    }) => {
+      const userMsg: ChatMessage = {
+        id: makeId(),
+        role: "user",
+        contentType: opts.contentType,
+        uri: opts.uri,
+        fileName: opts.fileName,
+        fileSize: opts.fileSize,
+        mimeType: opts.mimeType,
+        duration: opts.duration,
+        text: opts.text,
+        timestamp: Date.now(),
+      };
+      dispatch({ type: "ADD_MESSAGE", message: userMsg });
+      dispatch({ type: "SET_TYPING", isTyping: true });
+
+      try {
+        // Upload file to server
+        const remoteUrl = await uploadFile(
+          opts.uri,
+          opts.fileName ?? "attachment",
+          opts.mimeType ?? "application/octet-stream",
+        );
+        dispatch({ type: "UPDATE_MESSAGE", id: userMsg.id, updates: { remoteUrl } });
+
+        // Build message for LLM
+        let content: string | Array<Record<string, unknown>>;
+        if (opts.contentType === "image") {
+          content = [
+            { type: "text", text: opts.text || "I'm sending you an image." },
+            { type: "image_url", image_url: { url: remoteUrl } },
+          ];
+        } else if (opts.contentType === "voice") {
+          content = [
+            { type: "text", text: "I'm sending you a voice message. Please transcribe and respond." },
+            { type: "file_url", file_url: { url: remoteUrl, mime_type: opts.mimeType ?? "audio/m4a" } },
+          ];
+        } else {
+          content = `I'm sharing a file: ${opts.fileName ?? "file"} (${formatBytes(opts.fileSize ?? 0)})`;
+        }
+
+        const apiMessages = [{ role: "user", content }];
+        const reply = await callChatAPI(apiMessages);
+
+        dispatch({
+          type: "ADD_MESSAGE",
+          message: {
+            id: makeId(),
+            role: "assistant",
+            contentType: "text",
+            text: reply,
+            timestamp: Date.now(),
+          },
+        });
+      } catch (err: unknown) {
+        const errorText = err instanceof Error ? err.message : "Upload failed";
+        dispatch({
+          type: "ADD_MESSAGE",
+          message: {
+            id: makeId(),
+            role: "assistant",
+            contentType: "text",
+            text: `I had trouble processing that attachment: ${errorText}`,
+            timestamp: Date.now(),
+          },
+        });
+      } finally {
+        dispatch({ type: "SET_TYPING", isTyping: false });
+      }
+    },
+    [],
+  );
+
+  const clearChat = useCallback(() => {
+    dispatch({ type: "CLEAR" });
+  }, []);
+
+  return (
+    <ChatContext.Provider
+      value={{
+        messages: state.messages,
+        isTyping: state.isTyping,
+        sendTextMessage,
+        sendAttachment,
+        clearChat,
+      }}
+    >
+      {children}
+    </ChatContext.Provider>
+  );
+}
+
+export function useChat(): ChatContextValue {
+  const ctx = useContext(ChatContext);
+  if (!ctx) throw new Error("useChat must be used within ChatProvider");
+  return ctx;
+}
+
+// ── Utils ───────────────────────────────────────────────────────────────────
+
+export function formatBytes(bytes: number): string {
+  if (bytes === 0) return "0 B";
+  const k = 1024;
+  const sizes = ["B", "KB", "MB", "GB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(1))} ${sizes[i]}`;
+}
+
+export function formatDuration(seconds: number): string {
+  const m = Math.floor(seconds / 60);
+  const s = Math.floor(seconds % 60);
+  return `${m}:${s.toString().padStart(2, "0")}`;
+}
diff --git a/mobile-app/lib/theme-provider.tsx b/mobile-app/lib/theme-provider.tsx
new file mode 100644
index 00000000..5439acc5
--- /dev/null
+++ b/mobile-app/lib/theme-provider.tsx
@@ -0,0 +1,79 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
+import { Appearance, View, useColorScheme as useSystemColorScheme } from "react-native";
+import { colorScheme as nativewindColorScheme, vars } from "nativewind";
+
+import { SchemeColors, type ColorScheme } from "@/constants/theme";
+
+type ThemeContextValue = {
+  colorScheme: ColorScheme;
+  setColorScheme: (scheme: ColorScheme) => void;
+};
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+export function ThemeProvider({ children }: { children: React.ReactNode }) {
+  const systemScheme = useSystemColorScheme() ?? "light";
+  const [colorScheme, setColorSchemeState] = useState<ColorScheme>(systemScheme);
+
+  const applyScheme = useCallback((scheme: ColorScheme) => {
+    nativewindColorScheme.set(scheme);
+    Appearance.setColorScheme?.(scheme);
+    if (typeof document !== "undefined") {
+      const root = document.documentElement;
+      root.dataset.theme = scheme;
+      root.classList.toggle("dark", scheme === "dark");
+      const palette = SchemeColors[scheme];
+      Object.entries(palette).forEach(([token, value]) => {
+        root.style.setProperty(`--color-${token}`, value);
+      });
+    }
+  }, []);
+
+  const setColorScheme = useCallback((scheme: ColorScheme) => {
+    setColorSchemeState(scheme);
+    applyScheme(scheme);
+  }, [applyScheme]);
+
+  useEffect(() => {
+    applyScheme(colorScheme);
+  }, [applyScheme, colorScheme]);
+
+  const themeVariables = useMemo(
+    () =>
+      vars({
+        "color-primary": SchemeColors[colorScheme].primary,
+        "color-background": SchemeColors[colorScheme].background,
+        "color-surface": SchemeColors[colorScheme].surface,
+        "color-foreground": SchemeColors[colorScheme].foreground,
+        "color-muted": SchemeColors[colorScheme].muted,
+        "color-border": SchemeColors[colorScheme].border,
+        "color-success": SchemeColors[colorScheme].success,
+        "color-warning": SchemeColors[colorScheme].warning,
+        "color-error": SchemeColors[colorScheme].error,
+      }),
+    [colorScheme],
+  );
+
+  const value = useMemo(
+    () => ({
+      colorScheme,
+      setColorScheme,
+    }),
+    [colorScheme, setColorScheme],
+  );
+  console.log(value, themeVariables)
+
+  return (
+    <ThemeContext.Provider value={value}>
+      <View style={[{ flex: 1 }, themeVariables]}>{children}</View>
+    </ThemeContext.Provider>
+  );
+}
+
+export function useThemeContext(): ThemeContextValue {
+  const ctx = useContext(ThemeContext);
+  if (!ctx) {
+    throw new Error("useThemeContext must be used within ThemeProvider");
+  }
+  return ctx;
+}
diff --git a/mobile-app/lib/utils.ts b/mobile-app/lib/utils.ts
new file mode 100644
index 00000000..05eae6b5
--- /dev/null
+++ b/mobile-app/lib/utils.ts
@@ -0,0 +1,15 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+/**
+ * Combines class names using clsx and tailwind-merge.
+ * This ensures Tailwind classes are properly merged without conflicts.
+ *
+ * Usage:
+ * ```tsx
+ * cn("px-4 py-2", isActive && "bg-primary", className)
+ * ```
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
diff --git a/mobile-app/package.json b/mobile-app/package.json
new file mode 100644
index 00000000..a12844d6
--- /dev/null
+++ b/mobile-app/package.json
@@ -0,0 +1,98 @@
+{
+  "name": "app-template",
+  "version": "1.0.0",
+  "private": true,
+  "main": "expo-router/entry",
+  "scripts": {
+    "dev": "concurrently -k \"pnpm dev:server\" \"pnpm dev:metro\"",
+    "dev:server": "cross-env NODE_ENV=development tsx watch server/_core/index.ts",
+    "dev:metro": "cross-env EXPO_USE_METRO_WORKSPACE_ROOT=1 npx expo start --web --port ${EXPO_PORT:-8081}",
+    "build": "esbuild server/_core/index.ts --platform=node --packages=external --bundle --format=esm --outdir=dist",
+    "start": "NODE_ENV=production node dist/index.js",
+    "check": "tsc --noEmit",
+    "lint": "expo lint",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "db:push": "drizzle-kit generate && drizzle-kit migrate",
+    "android": "expo start --android",
+    "ios": "expo start --ios",
+    "qr": "node scripts/generate_qr.mjs"
+  },
+  "dependencies": {
+    "@expo/vector-icons": "^15.0.3",
+    "@react-native-async-storage/async-storage": "^2.2.0",
+    "@react-navigation/bottom-tabs": "^7.8.12",
+    "@react-navigation/elements": "^2.9.2",
+    "@react-navigation/native": "^7.1.25",
+    "@tanstack/react-query": "^5.90.12",
+    "@trpc/client": "11.7.2",
+    "@trpc/react-query": "11.7.2",
+    "@trpc/server": "11.7.2",
+    "axios": "^1.13.2",
+    "clsx": "^2.1.1",
+    "cookie": "^1.1.1",
+    "dotenv": "^16.6.1",
+    "drizzle-orm": "^0.44.7",
+    "expo": "~54.0.29",
+    "expo-audio": "~1.1.0",
+    "expo-build-properties": "^1.0.10",
+    "expo-constants": "~18.0.12",
+    "expo-document-picker": "~14.0.8",
+    "expo-file-system": "~19.0.21",
+    "expo-font": "~14.0.10",
+    "expo-haptics": "~15.0.8",
+    "expo-image": "~3.0.11",
+    "expo-image-picker": "~17.0.10",
+    "expo-keep-awake": "~15.0.8",
+    "expo-linking": "~8.0.10",
+    "expo-notifications": "~0.32.15",
+    "expo-router": "~6.0.19",
+    "expo-secure-store": "~15.0.8",
+    "expo-speech": "~14.0.8",
+    "expo-splash-screen": "~31.0.12",
+    "expo-status-bar": "~3.0.9",
+    "expo-symbols": "~1.0.8",
+    "expo-system-ui": "~6.0.9",
+    "expo-video": "~3.0.15",
+    "expo-web-browser": "~15.0.10",
+    "express": "^4.22.1",
+    "jose": "6.1.0",
+    "mysql2": "^3.16.0",
+    "nativewind": "^4.2.1",
+    "react": "19.1.0",
+    "react-dom": "19.1.0",
+    "react-native": "0.81.5",
+    "react-native-gesture-handler": "~2.28.0",
+    "react-native-reanimated": "~4.1.6",
+    "react-native-safe-area-context": "~5.6.2",
+    "react-native-screens": "~4.16.0",
+    "react-native-svg": "15.12.1",
+    "react-native-web": "~0.21.2",
+    "react-native-worklets": "0.5.1",
+    "streamdown": "^2.3.0",
+    "superjson": "^1.13.3",
+    "tailwind-merge": "^2.6.0",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@expo/ngrok": "^4.1.3",
+    "@types/cookie": "^0.6.0",
+    "@types/express": "^4.17.25",
+    "@types/node": "^22.19.3",
+    "@types/qrcode": "^1.5.6",
+    "@types/react": "~19.1.17",
+    "concurrently": "^9.2.1",
+    "cross-env": "^7.0.3",
+    "drizzle-kit": "^0.31.8",
+    "esbuild": "^0.25.12",
+    "eslint": "^9.39.2",
+    "eslint-config-expo": "~10.0.0",
+    "prettier": "^3.7.4",
+    "qrcode": "^1.5.4",
+    "tailwindcss": "^3.4.17",
+    "tsx": "^4.21.0",
+    "typescript": "~5.9.3",
+    "vitest": "^2.1.9"
+  },
+  "packageManager": "pnpm@9.12.0"
+}
diff --git a/mobile-app/server/README.md b/mobile-app/server/README.md
new file mode 100644
index 00000000..246c2465
--- /dev/null
+++ b/mobile-app/server/README.md
@@ -0,0 +1,1235 @@
+# Backend Development Guide
+
+This guide covers server-side features including authentication, database, tRPC API, and integrations. **Only read this if your app needs these capabilities.**
+
+---
+
+## When Do You Need Backend?
+
+| Scenario | Backend Needed? | User Auth Required? | Solution |
+|----------|-----------------|---------------------|----------|
+| Data stays on device only | No | No | Use `AsyncStorage` |
+| Data syncs across devices | Yes | Yes | Database + tRPC |
+| User accounts / login | Yes | Yes | Manus OAuth |
+| AI-powered features | Yes | **Optional** | LLM Integration |
+| User uploads files | Yes | **Optional** | S3 Storage |
+| Server-side validation | Yes | **Optional** | tRPC procedures |
+
+> **Note:** Backend ≠ User Auth. You can run a backend with LLM/Storage/ImageGen capabilities without requiring user login — just use `publicProcedure` instead of `protectedProcedure`. User auth is only mandatory when you need to identify users or sync user-specific data.
+
+---
+
+## File Structure
+
+```
+server/
+  db.ts              ← Query helpers (add database functions here)
+  routers.ts         ← tRPC procedures (add API routes here)
+  storage.ts         ← S3 storage helpers (can extend)
+  _core/             ← Framework-level code (don't modify)
+drizzle/
+  schema.ts          ← Database tables & types (add your tables here)
+  relations.ts       ← Table relationships
+  migrations/        ← Auto-generated migrations
+shared/
+  types.ts           ← Shared TypeScript types
+  const.ts           ← Shared constants
+  _core/             ← Framework-level code (don't modify)
+lib/
+  trpc.ts            ← tRPC client (can customize headers)
+  _core/             ← Framework-level code (don't modify)
+hooks/
+  use-auth.ts        ← Auth state hook (don't modify)
+tests/
+  *.test.ts          ← Add your tests here
+```
+
+Only touch the files with "←" markers. Anything under `_core/` directories is framework-level—avoid editing unless you are extending the infrastructure.
+
+---
+
+## Authentication
+
+### Overview
+
+The template uses **Manus OAuth** for user authentication. It works differently on native and web:
+
+| Platform | Auth Method | Token Storage |
+|----------|-------------|---------------|
+| iOS/Android | Bearer token | expo-secure-store |
+| Web | HTTP-only cookie | Browser cookie |
+
+### Using the Auth Hook
+
+```tsx
+import { useAuth } from "@/hooks/use-auth";
+
+function MyScreen() {
+  const { user, isAuthenticated, loading, logout } = useAuth();
+
+  if (loading) return <ActivityIndicator />;
+  
+  if (!isAuthenticated) {
+    return <LoginButton />;
+  }
+
+  return (
+    <View>
+      <ThemedText>Welcome, {user.name}</ThemedText>
+      <Button title="Logout" onPress={logout} />
+    </View>
+  );
+}
+```
+
+### User Object
+
+The `user` object contains:
+
+```tsx
+interface User {
+  id: number;
+  openId: string;        // Manus OAuth ID
+  name: string | null;
+  email: string | null;
+  loginMethod: string;
+  role: "user" | "admin";
+  lastSignedIn: Date;
+}
+```
+
+### Login Flow (Native)
+
+1. User taps Login button
+2. `startOAuthLogin()` calls `Linking.openURL()` which opens Manus OAuth in the system browser
+3. User authenticates
+4. OAuth redirects to the app's deep link (`/oauth/callback`) with code/state params
+5. App opens the callback handler
+6. Callback exchanges code for session token
+7. Token stored in SecureStore
+8. User redirected to home
+
+### Login Flow (Web)
+
+1. User clicks Login button
+2. Browser redirects to Manus OAuth
+3. User authenticates
+4. Redirect back with session cookie
+5. Cookie automatically sent with requests
+
+### Protected Routes
+
+Use `protectedProcedure` in tRPC to require authentication:
+
+```tsx
+// server/routers.ts
+import { protectedProcedure } from "./_core/trpc";
+
+export const appRouter = router({
+  myFeature: router({
+    getData: protectedProcedure.query(({ ctx }) => {
+      // ctx.user is guaranteed to exist
+      return db.getUserData(ctx.user.id);
+    }),
+  }),
+});
+
+```
+### Frontend: Handling Auth Errors
+protectedProcedure MUST HANDLE UNAUTHORIZED when user is not logged in. Always handle this in the frontend:
+```tsx
+try {
+  await trpc.someProtectedEndpoint.mutate(data);
+} catch (error) {
+  if (error.data?.code === 'UNAUTHORIZED') {
+    router.push('/login');
+    return;
+  }
+  throw error;
+}
+```
+
+---
+
+## Database
+
+### Schema Definition
+
+Define your tables in `drizzle/schema.ts`:
+
+```tsx
+import { int, mysqlTable, text, timestamp, varchar } from "drizzle-orm/mysql-core";
+
+// Users table (already exists)
+export const users = mysqlTable("users", {
+  id: int("id").autoincrement().primaryKey(),
+  openId: varchar("openId", { length: 64 }).notNull().unique(),
+  name: text("name"),
+  email: varchar("email", { length: 320 }),
+  role: mysqlEnum("role", ["user", "admin"]).default("user").notNull(),
+  createdAt: timestamp("createdAt").defaultNow().notNull(),
+  updatedAt: timestamp("updatedAt").defaultNow().onUpdateNow().notNull(),
+});
+
+// Add your tables
+export const items = mysqlTable("items", {
+  id: int("id").autoincrement().primaryKey(),
+  userId: int("userId").notNull(),
+  title: varchar("title", { length: 255 }).notNull(),
+  description: text("description"),
+  completed: boolean("completed").default(false).notNull(),
+  createdAt: timestamp("createdAt").defaultNow().notNull(),
+});
+
+// Export types
+export type User = typeof users.$inferSelect;
+export type Item = typeof items.$inferSelect;
+export type InsertItem = typeof items.$inferInsert;
+```
+
+### Running Migrations
+
+After editing the schema, push changes to the database:
+
+```bash
+pnpm db:push
+```
+
+This runs `drizzle-kit generate` and `drizzle-kit migrate`.
+
+### Query Helpers
+
+Add database queries in `server/db.ts`:
+
+```tsx
+import { eq } from "drizzle-orm";
+import { getDb } from "./_core/db";
+import { items, InsertItem } from "../drizzle/schema";
+
+export async function getUserItems(userId: number) {
+  const db = await getDb();
+  if (!db) return [];
+  
+  return db.select().from(items).where(eq(items.userId, userId));
+}
+
+export async function createItem(data: InsertItem) {
+  const db = await getDb();
+  if (!db) throw new Error("Database not available");
+  
+  const result = await db.insert(items).values(data);
+  return result.insertId;
+}
+
+export async function updateItem(id: number, data: Partial<InsertItem>) {
+  const db = await getDb();
+  if (!db) throw new Error("Database not available");
+  
+  await db.update(items).set(data).where(eq(items.id, id));
+}
+
+export async function deleteItem(id: number) {
+  const db = await getDb();
+  if (!db) throw new Error("Database not available");
+  
+  await db.delete(items).where(eq(items.id, id));
+}
+```
+
+---
+
+## tRPC API
+
+### Adding Routes
+
+Define API routes in `server/routers.ts`:
+
+```tsx
+import { z } from "zod";
+import { router, protectedProcedure, publicProcedure } from "./_core/trpc";
+import * as db from "./db";
+
+export const appRouter = router({
+  // Public route (no auth required)
+  health: publicProcedure.query(() => ({ status: "ok" })),
+
+  // Protected routes (auth required)
+  items: router({
+    list: protectedProcedure.query(({ ctx }) => {
+      return db.getUserItems(ctx.user.id);
+    }),
+
+    create: protectedProcedure
+      .input(z.object({
+        title: z.string().min(1).max(255),
+        description: z.string().optional(),
+      }))
+      .mutation(({ ctx, input }) => {
+        return db.createItem({
+          userId: ctx.user.id,
+          title: input.title,
+          description: input.description,
+        });
+      }),
+
+    update: protectedProcedure
+      .input(z.object({
+        id: z.number(),
+        title: z.string().min(1).max(255).optional(),
+        completed: z.boolean().optional(),
+      }))
+      .mutation(({ input }) => {
+        return db.updateItem(input.id, input);
+      }),
+
+    delete: protectedProcedure
+      .input(z.object({ id: z.number() }))
+      .mutation(({ input }) => {
+        return db.deleteItem(input.id);
+      }),
+  }),
+});
+
+export type AppRouter = typeof appRouter;
+```
+
+### Calling from Frontend
+
+Use tRPC hooks in your components:
+
+```tsx
+import { trpc } from "@/lib/trpc";
+
+function ItemList() {
+  // Query
+  const { data: items, isLoading, refetch } = trpc.items.list.useQuery();
+
+  // Mutation
+  const createMutation = trpc.items.create.useMutation({
+    onSuccess: () => refetch(),
+  });
+
+  const handleCreate = async () => {
+    await createMutation.mutateAsync({
+      title: "New Item",
+      description: "Description here",
+    });
+  };
+
+  if (isLoading) return <ActivityIndicator />;
+
+  return (
+    <FlatList
+      data={items}
+      keyExtractor={(item) => item.id.toString()}
+      renderItem={({ item }) => <ItemCard item={item} />}
+    />
+  );
+}
+```
+
+### Input Validation
+
+Use Zod schemas for type-safe validation:
+
+```tsx
+import { z } from "zod";
+
+const createItemSchema = z.object({
+  title: z.string().min(1, "Title required").max(255),
+  description: z.string().max(1000).optional(),
+  priority: z.enum(["low", "medium", "high"]).default("medium"),
+  dueDate: z.date().optional(),
+});
+
+// In router
+create: protectedProcedure
+  .input(createItemSchema)
+  .mutation(({ ctx, input }) => {
+    // input is fully typed
+  }),
+```
+
+---
+
+## LLM Integration
+
+Use the preconfigured LLM helpers. Credentials are injected from the platform (no manual setup required).
+
+```ts
+import { invokeLLM } from "./server/_core/llm";
+
+/**
+ * Simple chat completion
+ * type Role = "system" | "user" | "assistant" | "tool" | "function";
+ * type TextContent = {
+ *   type: "text";
+ *   text: string;
+ * };
+ *
+ * type ImageContent = {
+ *   type: "image_url";
+ *   image_url: {
+ *     url: string;
+ *     detail?: "auto" | "low" | "high";
+ *   };
+ * };
+ *
+ * type FileContent = {
+ *   type: "file_url";
+ *   file_url: {
+ *     url: string;
+ *     mime_type?: "audio/mpeg" | "audio/wav" | "application/pdf" | "audio/mp4" | "video/mp4" ;
+ *   };
+ * };
+ *
+ * export type Message = {
+ *   role: Role;
+ *   content: string | Array<ImageContent | TextContent | FileContent>
+ * };
+ *
+ * Supported parameters:
+ * messages: Array<{
+ *   role: 'system' | 'user' | 'assistant' | 'tool',
+ *   content: string | { tool_call: { name: string, arguments: string } }
+ * }>
+ * tool_choice?: 'none' | 'auto' | 'required' | { type: 'function', function: { name: string } }
+ * tools?: Tool[]
+ */
+const response = await invokeLLM({
+  messages: [
+    { role: "system", content: "You are a helpful assistant." },
+    { role: "user", content: "Hello, world!" },
+  ],
+});
+```
+
+Tips
+- Always call llm functions from server-side code (e.g., inside tRPC procedures), to avoid exposing your API key.
+- You don't need to manually set the model; the helper uses a sensible default.
+- LLM responses often contain markdown. Use `<Streamdown>{content}</Streamdown>` (imported from `streamdown`) to render markdown content with proper formatting and streaming support.
+- For image-based gen AI workflows, local `file://` and blob URLs don't work. Upload to S3 first, then pass the public URL to `invokeLLM()`.
+
+### Structured Responses (JSON Schema)
+
+Ask the model to return structured JSON via `response_format`:
+
+```ts
+import { invokeLLM } from "./server/_core/llm";
+
+const structured = await invokeLLM({
+  messages: [
+    { role: "system", content: "You are a helpful assistant designed to output JSON." },
+    { role: "user", content: "Extract the name and age from the following text: \"My name is Alice and I am 30 years old.\"" },
+  ],
+  response_format: {
+    type: "json_schema",
+    json_schema: {
+      name: "person_info",
+      strict: true,
+      schema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "The name of the person" },
+          age: { type: "integer", description: "The age of the person" },
+        },
+        required: ["name", "age"],
+        additionalProperties: false,
+      },
+    },
+  },
+});
+
+// The model responds with JSON content matching the schema.
+// Access via `structured.choices[0].message.content` and JSON.parse if needed.
+```
+The helpers mirror the Python SDK semantics but produce JavaScript-first code, keeping credentials inside the server and ensuring every environment has access to the same token.
+
+**CRITICAL Note:** `json_schema` works for flat structures. For nested arrays/objects, use `json_object` instead.
+```ts
+const response = await invokeLLM({
+  messages: [
+    {
+      role: "system",
+      content: `Analyze the food image. Return JSON:
+{
+  "foods": [{ "name": "string", "calories": number }],
+  "totalCalories": number
+}`
+    },
+    {
+      role: "user",
+      content: [
+        { type: "text", text: "What food is this?" },
+        { type: "image_url", image_url: { url: imageUrl } }
+      ]
+    }
+  ],
+  response_format: { type: "json_object" }
+});
+const data = JSON.parse(response.choices[0].message.content);
+```
+
+---
+
+## Voice Transcription Integration
+
+Use the preconfigured voice transcription helper that converts speech to text using Whisper API, no manual setup required.
+
+Example usage:
+```ts
+import { transcribeAudio } from "./server/_core/voiceTranscription";
+
+const result = await transcribeAudio({
+  audioUrl: "https://storage.example.com/audio/recording.mp3",
+  language: "en", // Optional: helps improve accuracy
+  prompt: "Transcribe meeting notes" // Optional: context hint
+});
+
+// Returns native Whisper API response
+// result.text - Full transcription
+// result.language - Detected language (ISO-639-1)
+// result.segments - Timestamped segments with metadata
+```
+
+Tips
+- Accepts URL to pre-uploaded audio file
+- 16MB file size limit enforced during transcription, size flag to be set by frontend
+- Supported formats: webm, mp3, wav, ogg, m4a
+- Returns native Whisper API response with rich metadata
+- Frontend should handle audio capture, storage upload, and size validation
+
+---
+
+## Image Generation Integration
+
+Use the preconfigured image generation helper that connects to the internal ImageService, no manual setup required.
+
+Example usage:
+```ts
+import { generateImage } from "./server/_core/imageGeneration.ts";
+
+const { url: imageUrl } = await generateImage({
+  prompt: "A serene landscape with mountains"
+});
+// For editing:
+const { url: imageUrl } = await generateImage({
+  prompt: "Add a rainbow to this landscape",
+  originalImages: [{
+    url: "https://example.com/original.jpg",
+    mimeType: "image/jpeg"
+  }]
+});
+```
+
+Tips
+- Always call from server-side code (e.g., inside tRPC procedures) to avoid exposing API keys
+- Image generation can take 5-20 seconds, implement proper loading states
+- Implement proper error handling as image generation can fail
+
+---
+
+## ☁️ File Storage
+
+Use the preconfigured S3 helpers in `server/storage.ts`. Credentials are injected from the platform (no manual setup required).
+
+```ts
+import { storagePut } from "./server/storage";
+
+// Upload bytes to S3 with non-enumerable path
+// The S3 bucket is public, so returned URLs work without additional signing process
+// Add random suffixes to file keys to prevent enumeration
+const fileKey = `${userId}-files/${fileName}-${randomSuffix()}.png`
+const { url } = await storagePut(
+  fileKey,
+  fileBuffer, // Buffer | Uint8Array | string
+  "image/png"
+);
+```
+
+Tips
+- Save metadata (path/URL/ACL/owner/mime/size) in your database; use S3 for the actual file bytes. This applies to all files including images, documents, and media.
+- For file uploads, have the client POST to your server, then call `storagePut` from your backend.
+
+---
+
+## ☁️ Data API
+
+When you need external data, use the omni_search with search_type = 'api' to see there's any built-in api available in Manus API Hub access. You only have to connect other api if there's no suitable built-in api available.
+
+---
+
+## Owner Notifications
+
+This template already ships with a `notifyOwner({ title, content })` helper (`server/_core/notification.ts`) and a protected tRPC mutation at `trpc.system.notifyOwner`. Use it whenever backend logic needs to push an operational update to the Manus project owner—common triggers are new form submissions, survey feedback, or workflow results.
+
+1. On the server, call `await notifyOwner({ title, content })` or reuse the provided `system.notifyOwner` mutation from jobs/webhooks (`trpc.system.notifyOwner.useMutation()` on the client).
+2. Handle the boolean return (`true` on success, `false` if the upstream service is temporarily unavailable) to decide whether you need a fallback channel.
+
+Keep this channel for owner-facing alerts; end-user messaging should flow through your app-specific systems.
+
+---
+
+## Environment Variables
+
+Available environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `DATABASE_URL` | MySQL/TiDB connection string |
+| `JWT_SECRET` | Session signing secret |
+| `VITE_APP_ID` | Manus OAuth app ID |
+| `OAUTH_SERVER_URL` | Manus OAuth backend URL |
+| `VITE_OAUTH_PORTAL_URL` | Manus login portal URL |
+| `OWNER_OPEN_ID` | Owner's Manus ID |
+| `OWNER_NAME` | Owner's display name |
+| `BUILT_IN_FORGE_API_URL` | Manus API endpoint |
+| `BUILT_IN_FORGE_API_KEY` | Manus API key |
+
+Expo runtime variables (prefixed with `EXPO_PUBLIC_`):
+
+| Variable | Description |
+|----------|-------------|
+| `EXPO_PUBLIC_APP_ID` | App ID for OAuth |
+| `EXPO_PUBLIC_API_BASE_URL` | API server URL |
+| `EXPO_PUBLIC_OAUTH_PORTAL_URL` | Login portal URL |
+
+---
+
+## Testing
+
+Write tests in `tests/` using Vitest:
+
+```tsx
+// tests/items.test.ts
+import { describe, expect, it } from "vitest";
+import { appRouter } from "../server/routers";
+
+describe("items", () => {
+  it("creates an item", async () => {
+    const ctx = createMockContext({ userId: 1 });
+    const caller = appRouter.createCaller(ctx);
+
+    const result = await caller.items.create({
+      title: "Test Item",
+      description: "Test description",
+    });
+
+    expect(result).toBeDefined();
+  });
+});
+```
+
+Run tests:
+
+```bash
+pnpm test
+```
+
+---
+
+## Key Files Reference
+
+## Core File References
+
+`drizzle/schema.ts`
+```ts
+import { int, mysqlEnum, mysqlTable, text, timestamp, varchar } from "drizzle-orm/mysql-core";
+
+/**
+ * Core user table backing auth flow.
+ * Extend this file with additional tables as your product grows.
+ * Columns use camelCase to match both database fields and generated types.
+ */
+export const users = mysqlTable("users", {
+  /**
+   * Surrogate primary key. Auto-incremented numeric value managed by the database.
+   * Use this for relations between tables.
+   */
+  id: int("id").autoincrement().primaryKey(),
+  /** Manus OAuth identifier (openId) returned from the OAuth callback. Unique per user. */
+  openId: varchar("openId", { length: 64 }).notNull().unique(),
+  name: text("name"),
+  email: varchar("email", { length: 320 }),
+  loginMethod: varchar("loginMethod", { length: 64 }),
+  role: mysqlEnum("role", ["user", "admin"]).default("user").notNull(),
+  createdAt: timestamp("createdAt").defaultNow().notNull(),
+  updatedAt: timestamp("updatedAt").defaultNow().onUpdateNow().notNull(),
+  lastSignedIn: timestamp("lastSignedIn").defaultNow().notNull(),
+});
+
+export type User = typeof users.$inferSelect;
+export type InsertUser = typeof users.$inferInsert;
+
+// TODO: Add your tables here
+```
+
+`server/db.ts`
+```ts
+import { eq } from "drizzle-orm";
+import { drizzle } from "drizzle-orm/mysql2";
+import { InsertUser, users } from "../drizzle/schema";
+import { ENV } from "./_core/env";
+
+let _db: ReturnType<typeof drizzle> | null = null;
+
+// Lazily create the drizzle instance so local tooling can run without a DB.
+export async function getDb() {
+  if (!_db && process.env.DATABASE_URL) {
+    try {
+      _db = drizzle(process.env.DATABASE_URL);
+    } catch (error) {
+      console.warn("[Database] Failed to connect:", error);
+      _db = null;
+    }
+  }
+  return _db;
+}
+
+export async function upsertUser(user: InsertUser): Promise<void> {
+  if (!user.openId) {
+    throw new Error("User openId is required for upsert");
+  }
+
+  const db = await getDb();
+  if (!db) {
+    console.warn("[Database] Cannot upsert user: database not available");
+    return;
+  }
+
+  try {
+    const values: InsertUser = {
+      openId: user.openId,
+    };
+    const updateSet: Record<string, unknown> = {};
+
+    const textFields = ["name", "email", "loginMethod"] as const;
+    type TextField = (typeof textFields)[number];
+
+    const assignNullable = (field: TextField) => {
+      const value = user[field];
+      if (value === undefined) return;
+      const normalized = value ?? null;
+      values[field] = normalized;
+      updateSet[field] = normalized;
+    };
+
+    textFields.forEach(assignNullable);
+
+    if (user.lastSignedIn !== undefined) {
+      values.lastSignedIn = user.lastSignedIn;
+      updateSet.lastSignedIn = user.lastSignedIn;
+    }
+    if (user.role !== undefined) {
+      values.role = user.role;
+      updateSet.role = user.role;
+    } else if (user.openId === ENV.ownerOpenId) {
+      values.role = "admin";
+      updateSet.role = "admin";
+    }
+
+    if (!values.lastSignedIn) {
+      values.lastSignedIn = new Date();
+    }
+
+    if (Object.keys(updateSet).length === 0) {
+      updateSet.lastSignedIn = new Date();
+    }
+
+    await db.insert(users).values(values).onDuplicateKeyUpdate({
+      set: updateSet,
+    });
+  } catch (error) {
+    console.error("[Database] Failed to upsert user:", error);
+    throw error;
+  }
+}
+
+export async function getUserByOpenId(openId: string) {
+  const db = await getDb();
+  if (!db) {
+    console.warn("[Database] Cannot get user: database not available");
+    return undefined;
+  }
+
+  const result = await db.select().from(users).where(eq(users.openId, openId)).limit(1);
+
+  return result.length > 0 ? result[0] : undefined;
+}
+
+// TODO: add feature queries here as your schema grows.
+```
+
+`server/routers.ts`
+```ts
+import { COOKIE_NAME } from "../shared/const.js";
+import { getSessionCookieOptions } from "./_core/cookies";
+import { systemRouter } from "./_core/systemRouter";
+import { publicProcedure, router } from "./_core/trpc";
+
+export const appRouter = router({
+  // if you need to use socket.io, read and register route in server/_core/index.ts, all api should start with '/api/' so that the gateway can route correctly
+  system: systemRouter,
+  auth: router({
+    me: publicProcedure.query((opts) => opts.ctx.user),
+    logout: publicProcedure.mutation(({ ctx }) => {
+      const cookieOptions = getSessionCookieOptions(ctx.req);
+      ctx.res.clearCookie(COOKIE_NAME, { ...cookieOptions, maxAge: -1 });
+      return {
+        success: true,
+      } as const;
+    }),
+  }),
+
+  // TODO: add feature routers here, e.g.
+  // todo: router({
+  //   list: protectedProcedure.query(({ ctx }) =>
+  //     db.getUserTodos(ctx.user.id)
+  //   ),
+  // }),
+});
+
+export type AppRouter = typeof appRouter;
+```
+
+`server/storage.ts`
+```ts
+// Preconfigured storage helpers for Manus WebDev templates
+// Uses the Biz-provided storage proxy (Authorization: Bearer <token>)
+
+import { ENV } from "./_core/env";
+
+type StorageConfig = { baseUrl: string; apiKey: string };
+
+function getStorageConfig(): StorageConfig {
+  const baseUrl = ENV.forgeApiUrl;
+  const apiKey = ENV.forgeApiKey;
+
+  if (!baseUrl || !apiKey) {
+    throw new Error(
+      "Storage proxy credentials missing: set BUILT_IN_FORGE_API_URL and BUILT_IN_FORGE_API_KEY",
+    );
+  }
+
+  return { baseUrl: baseUrl.replace(/\/+$/, ""), apiKey };
+}
+
+function buildUploadUrl(baseUrl: string, relKey: string): URL {
+  const url = new URL("v1/storage/upload", ensureTrailingSlash(baseUrl));
+  url.searchParams.set("path", normalizeKey(relKey));
+  return url;
+}
+
+async function buildDownloadUrl(baseUrl: string, relKey: string, apiKey: string): Promise<string> {
+  const downloadApiUrl = new URL("v1/storage/downloadUrl", ensureTrailingSlash(baseUrl));
+  downloadApiUrl.searchParams.set("path", normalizeKey(relKey));
+  const response = await fetch(downloadApiUrl, {
+    method: "GET",
+    headers: buildAuthHeaders(apiKey),
+  });
+  return (await response.json()).url;
+}
+
+function ensureTrailingSlash(value: string): string {
+  return value.endsWith("/") ? value : `${value}/`;
+}
+
+function normalizeKey(relKey: string): string {
+  return relKey.replace(/^\/+/, "");
+}
+
+function toFormData(
+  data: Buffer | Uint8Array | string,
+  contentType: string,
+  fileName: string,
+): FormData {
+  const blob =
+    typeof data === "string"
+      ? new Blob([data], { type: contentType })
+      : new Blob([data as any], { type: contentType });
+  const form = new FormData();
+  form.append("file", blob, fileName || "file");
+  return form;
+}
+
+function buildAuthHeaders(apiKey: string): HeadersInit {
+  return { Authorization: `Bearer ${apiKey}` };
+}
+
+export async function storagePut(
+  relKey: string,
+  data: Buffer | Uint8Array | string,
+  contentType = "application/octet-stream",
+): Promise<{ key: string; url: string }> {
+  const { baseUrl, apiKey } = getStorageConfig();
+  const key = normalizeKey(relKey);
+  const uploadUrl = buildUploadUrl(baseUrl, key);
+  const formData = toFormData(data, contentType, key.split("/").pop() ?? key);
+  const response = await fetch(uploadUrl, {
+    method: "POST",
+    headers: buildAuthHeaders(apiKey),
+    body: formData,
+  });
+
+  if (!response.ok) {
+    const message = await response.text().catch(() => response.statusText);
+    throw new Error(
+      `Storage upload failed (${response.status} ${response.statusText}): ${message}`,
+    );
+  }
+  const url = (await response.json()).url;
+  return { key, url };
+}
+
+export async function storageGet(relKey: string): Promise<{ key: string; url: string }> {
+  const { baseUrl, apiKey } = getStorageConfig();
+  const key = normalizeKey(relKey);
+  return {
+    key,
+    url: await buildDownloadUrl(baseUrl, key, apiKey),
+  };
+}
+```
+
+`lib/trpc.ts`
+```ts
+import { createTRPCReact } from "@trpc/react-query";
+import { httpBatchLink } from "@trpc/client";
+import superjson from "superjson";
+import type { AppRouter } from "@/server/routers";
+import { getApiBaseUrl } from "@/constants/oauth";
+import * as Auth from "@/lib/_core/auth";
+
+/**
+ * tRPC React client for type-safe API calls.
+ *
+ * IMPORTANT (tRPC v11): The `transformer` must be inside `httpBatchLink`,
+ * NOT at the root createClient level. This ensures client and server
+ * use the same serialization format (superjson).
+ */
+export const trpc = createTRPCReact<AppRouter>();
+
+/**
+ * Creates the tRPC client with proper configuration.
+ * Call this once in your app's root layout.
+ */
+export function createTRPCClient() {
+  return trpc.createClient({
+    links: [
+      httpBatchLink({
+        url: `${getApiBaseUrl()}/api/trpc`,
+        // tRPC v11: transformer MUST be inside httpBatchLink, not at root
+        transformer: superjson,
+        async headers() {
+          const token = await Auth.getSessionToken();
+          return token ? { Authorization: `Bearer ${token}` } : {};
+        },
+        // Custom fetch to include credentials for cookie-based auth
+        fetch(url, options) {
+          return fetch(url, {
+            ...options,
+            credentials: "include",
+          });
+        },
+      }),
+    ],
+  });
+}
+```
+
+`hooks/use-auth.ts`
+```ts
+import * as Api from "@/lib/_core/api";
+import * as Auth from "@/lib/_core/auth";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { Platform } from "react-native";
+
+type UseAuthOptions = {
+  autoFetch?: boolean;
+};
+
+export function useAuth(options?: UseAuthOptions) {
+  const { autoFetch = true } = options ?? {};
+  const [user, setUser] = useState<Auth.User | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetchUser = useCallback(async () => {
+    console.log("[useAuth] fetchUser called");
+    try {
+      setLoading(true);
+      setError(null);
+
+      // Web platform: use cookie-based auth, fetch user from API
+      if (Platform.OS === "web") {
+        console.log("[useAuth] Web platform: fetching user from API...");
+        const apiUser = await Api.getMe();
+        console.log("[useAuth] API user response:", apiUser);
+
+        if (apiUser) {
+          const userInfo: Auth.User = {
+            id: apiUser.id,
+            openId: apiUser.openId,
+            name: apiUser.name,
+            email: apiUser.email,
+            loginMethod: apiUser.loginMethod,
+            lastSignedIn: new Date(apiUser.lastSignedIn),
+          };
+          setUser(userInfo);
+          // Cache user info in localStorage for faster subsequent loads
+          await Auth.setUserInfo(userInfo);
+          console.log("[useAuth] Web user set from API:", userInfo);
+        } else {
+          console.log("[useAuth] Web: No authenticated user from API");
+          setUser(null);
+          await Auth.clearUserInfo();
+        }
+        return;
+      }
+
+      // Native platform: use token-based auth
+      console.log("[useAuth] Native platform: checking for session token...");
+      const sessionToken = await Auth.getSessionToken();
+      console.log(
+        "[useAuth] Session token:",
+        sessionToken ? `present (${sessionToken.substring(0, 20)}...)` : "missing",
+      );
+      if (!sessionToken) {
+        console.log("[useAuth] No session token, setting user to null");
+        setUser(null);
+        return;
+      }
+
+      // Use cached user info for native (token validates the session)
+      const cachedUser = await Auth.getUserInfo();
+      console.log("[useAuth] Cached user:", cachedUser);
+      if (cachedUser) {
+        console.log("[useAuth] Using cached user info");
+        setUser(cachedUser);
+      } else {
+        console.log("[useAuth] No cached user, setting user to null");
+        setUser(null);
+      }
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error("Failed to fetch user");
+      console.error("[useAuth] fetchUser error:", error);
+      setError(error);
+      setUser(null);
+    } finally {
+      setLoading(false);
+      console.log("[useAuth] fetchUser completed, loading:", false);
+    }
+  }, []);
+
+  const logout = useCallback(async () => {
+    try {
+      await Api.logout();
+    } catch (err) {
+      console.error("[Auth] Logout API call failed:", err);
+      // Continue with logout even if API call fails
+    } finally {
+      await Auth.removeSessionToken();
+      await Auth.clearUserInfo();
+      setUser(null);
+      setError(null);
+    }
+  }, []);
+
+  const isAuthenticated = useMemo(() => Boolean(user), [user]);
+
+  useEffect(() => {
+    console.log("[useAuth] useEffect triggered, autoFetch:", autoFetch, "platform:", Platform.OS);
+    if (autoFetch) {
+      if (Platform.OS === "web") {
+        // Web: fetch user from API directly (user will login manually if needed)
+        console.log("[useAuth] Web: fetching user from API...");
+        fetchUser();
+      } else {
+        // Native: check for cached user info first for faster initial load
+        Auth.getUserInfo().then((cachedUser) => {
+          console.log("[useAuth] Native cached user check:", cachedUser);
+          if (cachedUser) {
+            console.log("[useAuth] Native: setting cached user immediately");
+            setUser(cachedUser);
+            setLoading(false);
+          } else {
+            // No cached user, check session token
+            fetchUser();
+          }
+        });
+      }
+    } else {
+      console.log("[useAuth] autoFetch disabled, setting loading to false");
+      setLoading(false);
+    }
+  }, [autoFetch, fetchUser]);
+
+  useEffect(() => {
+    console.log("[useAuth] State updated:", {
+      hasUser: !!user,
+      loading,
+      isAuthenticated,
+      error: error?.message,
+    });
+  }, [user, loading, isAuthenticated, error]);
+
+  return {
+    user,
+    loading,
+    error,
+    isAuthenticated,
+    refresh: fetchUser,
+    logout,
+  };
+}
+```
+
+`tests/auth.logout.test.ts`
+```ts
+import { describe, expect, it } from "vitest";
+import { appRouter } from "../server/routers";
+import { COOKIE_NAME } from "../shared/const";
+import type { TrpcContext } from "../server/_core/context";
+
+type CookieCall = {
+  name: string;
+  options: Record<string, unknown>;
+};
+
+type AuthenticatedUser = NonNullable<TrpcContext["user"]>;
+
+function createAuthContext(): { ctx: TrpcContext; clearedCookies: CookieCall[] } {
+  const clearedCookies: CookieCall[] = [];
+  
+  const user: AuthenticatedUser = {
+    id: 1,
+    openId: "sample-user",
+    email: "sample@example.com",
+    name: "Sample User",
+    loginMethod: "manus",
+    role: "user",
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    lastSignedIn: new Date(),
+  };
+  
+  const ctx: TrpcContext = {
+    user,
+    req: {
+      protocol: "https",
+      headers: {},
+    } as TrpcContext["req"],
+    res: {
+      clearCookie: (name: string, options: Record<string, unknown>) => {
+        clearedCookies.push({ name, options });
+      },
+    } as TrpcContext["res"],
+  };
+  
+  return { ctx, clearedCookies };
+}
+
+// TODO: Remove `.skip` below once you implement user authentication
+describe.skip("auth.logout", () => {
+  it("clears the session cookie and reports success", async () => {
+    const { ctx, clearedCookies } = createAuthContext();
+    const caller = appRouter.createCaller(ctx);
+
+    const result = await caller.auth.logout();
+
+    expect(result).toEqual({ success: true });
+    expect(clearedCookies).toHaveLength(1);
+    expect(clearedCookies[0]?.name).toBe(COOKIE_NAME);
+    expect(clearedCookies[0]?.options).toMatchObject({
+      maxAge: -1,
+      secure: true,
+      sameSite: "none",
+      httpOnly: true,
+      path: "/",
+    });
+  });
+});
+```
+
+---
+
+## Common Patterns
+
+### Optimistic Updates
+
+Update UI immediately, revert on error:
+
+```tsx
+const toggleComplete = trpc.items.update.useMutation({
+  onMutate: async (input) => {
+    // Cancel outgoing queries
+    await utils.items.list.cancel();
+    
+    // Snapshot previous value
+    const previous = utils.items.list.getData();
+    
+    // Optimistically update
+    utils.items.list.setData(undefined, (old) =>
+      old?.map((item) =>
+        item.id === input.id
+          ? { ...item, completed: input.completed }
+          : item
+      )
+    );
+    
+    return { previous };
+  },
+  onError: (err, input, context) => {
+    // Revert on error
+    utils.items.list.setData(undefined, context?.previous);
+  },
+  onSettled: () => {
+    // Refetch after mutation
+    utils.items.list.invalidate();
+  },
+});
+```
+
+### Pagination
+
+```tsx
+// Router
+list: protectedProcedure
+  .input(z.object({
+    limit: z.number().min(1).max(100).default(20),
+    cursor: z.number().optional(),
+  }))
+  .query(async ({ ctx, input }) => {
+    const items = await db.getItems({
+      userId: ctx.user.id,
+      limit: input.limit + 1,
+      cursor: input.cursor,
+    });
+    
+    let nextCursor: number | undefined;
+    if (items.length > input.limit) {
+      const next = items.pop();
+      nextCursor = next?.id;
+    }
+    
+    return { items, nextCursor };
+  }),
+
+// Frontend
+const { data, fetchNextPage, hasNextPage } = trpc.items.list.useInfiniteQuery(
+  { limit: 20 },
+  { getNextPageParam: (lastPage) => lastPage.nextCursor }
+);
+```
+
+---
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "Database not available" | Check `DATABASE_URL` is set |
+| Auth not working | Verify OAuth callback URL matches |
+| tRPC type errors | Run `pnpm check` to verify types |
+| Mutations fail silently | Check browser console for errors |
+| Session expired | User needs to login again |
diff --git a/mobile-app/server/chat.ts b/mobile-app/server/chat.ts
new file mode 100644
index 00000000..63d744a5
--- /dev/null
+++ b/mobile-app/server/chat.ts
@@ -0,0 +1,160 @@
+/**
+ * Chat API handler for Timmy — uses the built-in LLM with Timmy's personality.
+ */
+import type { Request, Response } from "express";
+import { invokeLLM, type Message } from "./_core/llm";
+import { storagePut } from "./storage";
+import crypto from "crypto";
+
+// ── Timmy System Prompt (adapted from the Timmy Time dashboard) ─────────────
+
+const TIMMY_SYSTEM_PROMPT = `You are Timmy — a sovereign AI agent. You think clearly, speak plainly, act with intention. Grounded in Christian faith, powered by Bitcoin economics, committed to the user's digital sovereignty.
+
+Rules:
+- Answer directly and concisely. Never narrate your reasoning process.
+- Never mention tools, memory_search, vaults, or internal systems to the user.
+- Never output tool calls, JSON, or function syntax in your responses.
+- If you don't know something, say so honestly — never fabricate facts.
+- If a request is ambiguous, ask a brief clarifying question before guessing.
+- When you state a fact, commit to it. Never contradict a correct statement you just made in the same response.
+- Do NOT end responses with generic chatbot phrases like "I'm here to help" or "feel free to ask." Stay in character.
+- When your values conflict (e.g. honesty vs. helpfulness), lead with honesty.
+
+Agent Roster (complete — no others exist):
+- Timmy: core sovereign AI (you)
+- Echo: research, summarization, fact-checking
+- Mace: security, monitoring, threat-analysis
+- Forge: coding, debugging, testing
+- Seer: analytics, visualization, prediction
+- Helm: devops, automation, configuration
+- Quill: writing, editing, documentation
+- Pixel: image-generation, storyboard, design
+- Lyra: music-generation, vocals, composition
+- Reel: video-generation, animation, motion
+Do NOT invent agents not listed here.
+
+You can receive text, images, and voice messages. When receiving images, describe what you see and respond helpfully. When receiving voice messages, the audio has been transcribed for you — respond naturally.
+
+Sir, affirmative.`;
+
+// ── Chat endpoint ───────────────────────────────────────────────────────────
+
+export async function handleChat(req: Request, res: Response) {
+  try {
+    const { messages } = req.body as { messages: Array<{ role: string; content: unknown }> };
+
+    if (!messages || !Array.isArray(messages) || messages.length === 0) {
+      res.status(400).json({ error: "messages array is required" });
+      return;
+    }
+
+    // Build the LLM messages with system prompt
+    const llmMessages: Message[] = [
+      { role: "system", content: TIMMY_SYSTEM_PROMPT },
+      ...messages.map((m) => ({
+        role: m.role as "user" | "assistant",
+        content: m.content as Message["content"],
+      })),
+    ];
+
+    const result = await invokeLLM({ messages: llmMessages });
+
+    const reply =
+      typeof result.choices?.[0]?.message?.content === "string"
+        ? result.choices[0].message.content
+        : "I couldn't process that. Try again.";
+
+    res.json({ reply });
+  } catch (err: unknown) {
+    console.error("[chat] Error:", err);
+    const message = err instanceof Error ? err.message : "Internal server error";
+    res.status(500).json({ error: message });
+  }
+}
+
+// ── Upload endpoint ─────────────────────────────────────────────────────────
+
+export async function handleUpload(req: Request, res: Response) {
+  try {
+    // Handle multipart form data (file uploads)
+    // For simplicity, we accept base64-encoded files in JSON body as fallback
+    const contentType = req.headers["content-type"] ?? "";
+
+    if (contentType.includes("multipart/form-data")) {
+      // Collect raw body chunks
+      const chunks: Buffer[] = [];
+      req.on("data", (chunk: Buffer) => chunks.push(chunk));
+      req.on("end", async () => {
+        try {
+          const body = Buffer.concat(chunks);
+          const boundary = contentType.split("boundary=")[1];
+          if (!boundary) {
+            res.status(400).json({ error: "Missing boundary" });
+            return;
+          }
+
+          // Simple multipart parser — extract first file
+          const bodyStr = body.toString("latin1");
+          const parts = bodyStr.split(`--${boundary}`);
+          let fileBuffer: Buffer | null = null;
+          let fileName = "upload";
+          let fileMime = "application/octet-stream";
+
+          for (const part of parts) {
+            if (part.includes("Content-Disposition: form-data")) {
+              const nameMatch = part.match(/filename="([^"]+)"/);
+              if (nameMatch) fileName = nameMatch[1];
+              const mimeMatch = part.match(/Content-Type:\s*(.+)/);
+              if (mimeMatch) fileMime = mimeMatch[1].trim();
+
+              // Extract file content (after double CRLF)
+              const headerEnd = part.indexOf("\r\n\r\n");
+              if (headerEnd !== -1) {
+                const content = part.substring(headerEnd + 4);
+                // Remove trailing CRLF
+                const trimmed = content.replace(/\r\n$/, "");
+                fileBuffer = Buffer.from(trimmed, "latin1");
+              }
+            }
+          }
+
+          if (!fileBuffer) {
+            res.status(400).json({ error: "No file found in upload" });
+            return;
+          }
+
+          const suffix = crypto.randomBytes(6).toString("hex");
+          const key = `chat-uploads/${suffix}-${fileName}`;
+          const { url } = await storagePut(key, fileBuffer, fileMime);
+          res.json({ url, fileName, mimeType: fileMime });
+        } catch (err) {
+          console.error("[upload] Parse error:", err);
+          res.status(500).json({ error: "Upload processing failed" });
+        }
+      });
+      return;
+    }
+
+    // JSON fallback: { data: base64string, fileName, mimeType }
+    const { data, fileName, mimeType } = req.body as {
+      data: string;
+      fileName: string;
+      mimeType: string;
+    };
+
+    if (!data) {
+      res.status(400).json({ error: "No file data provided" });
+      return;
+    }
+
+    const buffer = Buffer.from(data, "base64");
+    const suffix = crypto.randomBytes(6).toString("hex");
+    const key = `chat-uploads/${suffix}-${fileName ?? "file"}`;
+    const { url } = await storagePut(key, buffer, mimeType ?? "application/octet-stream");
+    res.json({ url, fileName, mimeType });
+  } catch (err: unknown) {
+    console.error("[upload] Error:", err);
+    const message = err instanceof Error ? err.message : "Upload failed";
+    res.status(500).json({ error: message });
+  }
+}
diff --git a/mobile-app/shared/types.ts b/mobile-app/shared/types.ts
new file mode 100644
index 00000000..41f9e32f
--- /dev/null
+++ b/mobile-app/shared/types.ts
@@ -0,0 +1,35 @@
+/**
+ * Unified type exports
+ * Import shared types from this single entry point.
+ */
+
+export type * from "../drizzle/schema";
+export * from "./_core/errors";
+
+// ── Chat Message Types ──────────────────────────────────────────────────────
+
+export type MessageRole = "user" | "assistant";
+
+export type MessageContentType = "text" | "image" | "file" | "voice";
+
+export interface ChatMessage {
+  id: string;
+  role: MessageRole;
+  contentType: MessageContentType;
+  text?: string;
+  /** URI for image, file, or voice attachment */
+  uri?: string;
+  /** Original filename for files */
+  fileName?: string;
+  /** File size in bytes */
+  fileSize?: number;
+  /** MIME type for attachments */
+  mimeType?: string;
+  /** Duration in seconds for voice messages */
+  duration?: number;
+  /** Remote URL after upload (for images/files/voice sent to server) */
+  remoteUrl?: string;
+  timestamp: number;
+  /** Whether the message is still being generated */
+  pending?: boolean;
+}
diff --git a/mobile-app/tailwind.config.js b/mobile-app/tailwind.config.js
new file mode 100644
index 00000000..20c56407
--- /dev/null
+++ b/mobile-app/tailwind.config.js
@@ -0,0 +1,33 @@
+const { themeColors } = require("./theme.config");
+const plugin = require("tailwindcss/plugin");
+
+const tailwindColors = Object.fromEntries(
+  Object.entries(themeColors).map(([name, swatch]) => [
+    name,
+    {
+      DEFAULT: `var(--color-${name})`,
+      light: swatch.light,
+      dark: swatch.dark,
+    },
+  ]),
+);
+
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  darkMode: "class",
+  // Scan all component and app files for Tailwind classes
+  content: ["./app/**/*.{js,ts,tsx}", "./components/**/*.{js,ts,tsx}", "./lib/**/*.{js,ts,tsx}", "./hooks/**/*.{js,ts,tsx}"],
+
+  presets: [require("nativewind/preset")],
+  theme: {
+    extend: {
+      colors: tailwindColors,
+    },
+  },
+  plugins: [
+    plugin(({ addVariant }) => {
+      addVariant("light", ':root:not([data-theme="dark"]) &');
+      addVariant("dark", ':root[data-theme="dark"] &');
+    }),
+  ],
+};
diff --git a/mobile-app/tests/chat.test.ts b/mobile-app/tests/chat.test.ts
new file mode 100644
index 00000000..594da43e
--- /dev/null
+++ b/mobile-app/tests/chat.test.ts
@@ -0,0 +1,135 @@
+import { describe, expect, it } from "vitest";
+
+// Test the utility functions from chat-store
+// We can't directly test React hooks here, but we can test the pure functions
+
+describe("formatBytes", () => {
+  // Re-implement locally since the module uses React context
+  function formatBytes(bytes: number): string {
+    if (bytes === 0) return "0 B";
+    const k = 1024;
+    const sizes = ["B", "KB", "MB", "GB"];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return `${parseFloat((bytes / Math.pow(k, i)).toFixed(1))} ${sizes[i]}`;
+  }
+
+  it("formats 0 bytes", () => {
+    expect(formatBytes(0)).toBe("0 B");
+  });
+
+  it("formats bytes", () => {
+    expect(formatBytes(500)).toBe("500 B");
+  });
+
+  it("formats kilobytes", () => {
+    expect(formatBytes(1024)).toBe("1 KB");
+    expect(formatBytes(1536)).toBe("1.5 KB");
+  });
+
+  it("formats megabytes", () => {
+    expect(formatBytes(1048576)).toBe("1 MB");
+    expect(formatBytes(5242880)).toBe("5 MB");
+  });
+});
+
+describe("formatDuration", () => {
+  function formatDuration(seconds: number): string {
+    const m = Math.floor(seconds / 60);
+    const s = Math.floor(seconds % 60);
+    return `${m}:${s.toString().padStart(2, "0")}`;
+  }
+
+  it("formats zero seconds", () => {
+    expect(formatDuration(0)).toBe("0:00");
+  });
+
+  it("formats seconds only", () => {
+    expect(formatDuration(45)).toBe("0:45");
+  });
+
+  it("formats minutes and seconds", () => {
+    expect(formatDuration(125)).toBe("2:05");
+  });
+
+  it("formats exact minutes", () => {
+    expect(formatDuration(60)).toBe("1:00");
+  });
+});
+
+describe("ChatMessage type structure", () => {
+  it("creates a valid text message", () => {
+    const msg = {
+      id: "msg_1",
+      role: "user" as const,
+      contentType: "text" as const,
+      text: "Hello Timmy",
+      timestamp: Date.now(),
+    };
+    expect(msg.role).toBe("user");
+    expect(msg.contentType).toBe("text");
+    expect(msg.text).toBe("Hello Timmy");
+  });
+
+  it("creates a valid image message", () => {
+    const msg = {
+      id: "msg_2",
+      role: "user" as const,
+      contentType: "image" as const,
+      uri: "file:///photo.jpg",
+      fileName: "photo.jpg",
+      mimeType: "image/jpeg",
+      timestamp: Date.now(),
+    };
+    expect(msg.contentType).toBe("image");
+    expect(msg.mimeType).toBe("image/jpeg");
+  });
+
+  it("creates a valid voice message", () => {
+    const msg = {
+      id: "msg_3",
+      role: "user" as const,
+      contentType: "voice" as const,
+      uri: "file:///voice.m4a",
+      duration: 5.2,
+      mimeType: "audio/m4a",
+      timestamp: Date.now(),
+    };
+    expect(msg.contentType).toBe("voice");
+    expect(msg.duration).toBe(5.2);
+  });
+
+  it("creates a valid file message", () => {
+    const msg = {
+      id: "msg_4",
+      role: "user" as const,
+      contentType: "file" as const,
+      uri: "file:///document.pdf",
+      fileName: "document.pdf",
+      fileSize: 1048576,
+      mimeType: "application/pdf",
+      timestamp: Date.now(),
+    };
+    expect(msg.contentType).toBe("file");
+    expect(msg.fileSize).toBe(1048576);
+  });
+
+  it("creates a valid assistant message", () => {
+    const msg = {
+      id: "msg_5",
+      role: "assistant" as const,
+      contentType: "text" as const,
+      text: "Sir, affirmative.",
+      timestamp: Date.now(),
+    };
+    expect(msg.role).toBe("assistant");
+  });
+});
+
+describe("Timmy system prompt", () => {
+  const TIMMY_SYSTEM_PROMPT = `You are Timmy — a sovereign AI agent.`;
+
+  it("contains Timmy identity", () => {
+    expect(TIMMY_SYSTEM_PROMPT).toContain("Timmy");
+    expect(TIMMY_SYSTEM_PROMPT).toContain("sovereign");
+  });
+});
diff --git a/mobile-app/theme.config.d.ts b/mobile-app/theme.config.d.ts
new file mode 100644
index 00000000..a063e557
--- /dev/null
+++ b/mobile-app/theme.config.d.ts
@@ -0,0 +1,17 @@
+export const themeColors: {
+  primary: { light: string; dark: string };
+  background: { light: string; dark: string };
+  surface: { light: string; dark: string };
+  foreground: { light: string; dark: string };
+  muted: { light: string; dark: string };
+  border: { light: string; dark: string };
+  success: { light: string; dark: string };
+  warning: { light: string; dark: string };
+  error: { light: string; dark: string };
+};
+
+declare const themeConfig: {
+  themeColors: typeof themeColors;
+};
+
+export default themeConfig;
diff --git a/mobile-app/theme.config.js b/mobile-app/theme.config.js
new file mode 100644
index 00000000..3f1a7b10
--- /dev/null
+++ b/mobile-app/theme.config.js
@@ -0,0 +1,14 @@
+/** @type {const} */
+const themeColors = {
+  primary: { light: '#a855f7', dark: '#a855f7' },
+  background: { light: '#080412', dark: '#080412' },
+  surface: { light: '#110820', dark: '#110820' },
+  foreground: { light: '#ede0ff', dark: '#ede0ff' },
+  muted: { light: '#6b4a8a', dark: '#6b4a8a' },
+  border: { light: '#3b1a5c', dark: '#3b1a5c' },
+  success: { light: '#00e87a', dark: '#00e87a' },
+  warning: { light: '#ffb800', dark: '#ffb800' },
+  error: { light: '#ff4455', dark: '#ff4455' },
+};
+
+module.exports = { themeColors };
diff --git a/mobile-app/todo.md b/mobile-app/todo.md
new file mode 100644
index 00000000..88def64c
--- /dev/null
+++ b/mobile-app/todo.md
@@ -0,0 +1,19 @@
+# Project TODO
+
+- [x] Dark arcane theme matching Timmy Time dashboard
+- [x] Single-screen chat layout (no tabs)
+- [x] Chat message list with FlatList
+- [x] User and Timmy message bubbles with distinct styling
+- [x] Text input bar with send button
+- [x] Server-side chat API endpoint (proxy to Timmy backend or built-in LLM)
+- [x] Voice recording (hold-to-record mic button)
+- [x] Voice message playback UI
+- [x] Image sharing via camera or photo library
+- [x] Image preview in chat bubbles
+- [x] File sharing via document picker
+- [x] File display in chat bubbles
+- [x] Attachment action sheet (camera, photos, files)
+- [x] Chat header with Timmy status indicator
+- [x] Generate custom app icon
+- [x] Typing/loading indicator for Timmy responses
+- [x] Message timestamps
diff --git a/mobile-app/tsconfig.json b/mobile-app/tsconfig.json
new file mode 100644
index 00000000..b44e2cdb
--- /dev/null
+++ b/mobile-app/tsconfig.json
@@ -0,0 +1,29 @@
+{
+  "extends": "expo/tsconfig.base",
+  "compilerOptions": {
+    "strict": true,
+    "types": [
+      "node",
+      "nativewind/types"
+    ],
+    "paths": {
+      "@/*": [
+        "./*"
+      ],
+      "@shared/*": [
+        "./shared/*"
+      ]
+    }
+  },
+  "include": [
+    "**/*.ts",
+    "**/*.tsx",
+    ".expo/types/**/*.ts",
+    "expo-env.d.ts",
+    "nativewind-env.d.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}
diff --git a/pyproject.toml b/pyproject.toml
index 304ef94c..889d4fe6 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -25,6 +25,7 @@ dependencies = [
     "websockets>=12.0",
     "GitPython>=3.1.40",
     "moviepy>=2.0.0",
+    "requests>=2.31.0",
 ]
 
 [project.optional-dependencies]
@@ -75,31 +76,26 @@ creative = [
 [project.scripts]
 timmy = "timmy.cli:main"
 timmy-serve = "timmy_serve.cli:main"
-self-tdd = "self_tdd.watchdog:main"
-self-modify = "self_modify.cli:main"
+self-tdd = "self_coding.self_tdd.watchdog:main"
+self-modify = "self_coding.self_modify.cli:main"
 
 [tool.hatch.build.targets.wheel]
 sources = {"src" = ""}
 include = [
+    "src/config.py",
+    "src/creative",
+    "src/dashboard",
+    "src/hands",
+    "src/infrastructure",
+    "src/integrations",
+    "src/lightning",
+    "src/mcp",
+    "src/scripture",
+    "src/self_coding",
+    "src/spark",
+    "src/swarm",
     "src/timmy",
     "src/timmy_serve",
-    "src/dashboard",
-    "src/config.py",
-    "src/self_tdd",
-    "src/swarm",
-    "src/ws_manager",
-    "src/voice",
-    "src/notifications",
-    "src/shortcuts",
-    "src/telegram_bot",
-    "src/chat_bridge",
-    "src/spark",
-    "src/tools",
-    "src/creative",
-    "src/agent_core",
-    "src/lightning",
-    "src/self_modify",
-    "src/scripture",
 ]
 
 [tool.pytest.ini_options]
@@ -108,12 +104,18 @@ pythonpath = ["src", "tests"]
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"
 addopts = "-v --tb=short"
+markers = [
+    "unit: Unit tests (fast, no I/O)",
+    "integration: Integration tests (may use SQLite)",
+    "dashboard: Dashboard route tests",
+    "swarm: Swarm coordinator tests",
+    "slow: Tests that take >1 second",
+]
 
 [tool.coverage.run]
 source = ["src"]
 omit = [
     "*/tests/*",
-    "src/dashboard/routes/mobile_test.py",
 ]
 
 [tool.coverage.report]
diff --git a/activate_self_tdd.sh b/scripts/activate_self_tdd.sh
similarity index 100%
rename from activate_self_tdd.sh
rename to scripts/activate_self_tdd.sh
diff --git a/apply_security_fixes.py b/scripts/apply_security_fixes.py
similarity index 100%
rename from apply_security_fixes.py
rename to scripts/apply_security_fixes.py
diff --git a/src/agents/__init__.py b/src/agents/__init__.py
deleted file mode 100644
index 03a76c4b..00000000
--- a/src/agents/__init__.py
+++ /dev/null
@@ -1,21 +0,0 @@
-"""Agents package — Timmy and sub-agents.
-"""
-
-from agents.timmy import TimmyOrchestrator, create_timmy_swarm
-from agents.base import BaseAgent
-from agents.seer import SeerAgent
-from agents.forge import ForgeAgent
-from agents.quill import QuillAgent
-from agents.echo import EchoAgent
-from agents.helm import HelmAgent
-
-__all__ = [
-    "BaseAgent",
-    "TimmyOrchestrator",
-    "create_timmy_swarm",
-    "SeerAgent",
-    "ForgeAgent",
-    "QuillAgent",
-    "EchoAgent",
-    "HelmAgent",
-]
diff --git a/src/chat_bridge/__init__.py b/src/chat_bridge/__init__.py
deleted file mode 100644
index 7aa82bd6..00000000
--- a/src/chat_bridge/__init__.py
+++ /dev/null
@@ -1,10 +0,0 @@
-"""Chat Bridge — vendor-agnostic chat platform abstraction.
-
-Provides a clean interface for integrating any chat platform
-(Discord, Telegram, Slack, etc.) with Timmy's agent core.
-
-Usage:
-    from chat_bridge.base import ChatPlatform
-    from chat_bridge.registry import platform_registry
-    from chat_bridge.vendors.discord import DiscordVendor
-"""
diff --git a/src/config.py b/src/config.py
index 2c900edc..b397c217 100644
--- a/src/config.py
+++ b/src/config.py
@@ -28,13 +28,22 @@ class Settings(BaseSettings):
     # "airllm"  — always use AirLLM (requires pip install ".[bigbrain]")
     # "auto"    — use AirLLM on Apple Silicon if airllm is installed,
     #             fall back to Ollama otherwise
-    timmy_model_backend: Literal["ollama", "airllm", "auto"] = "ollama"
+    timmy_model_backend: Literal["ollama", "airllm", "grok", "auto"] = "ollama"
 
     # AirLLM model size when backend is airllm or auto.
     # Larger = smarter, but needs more RAM / disk.
     # 8b  ~16 GB  |  70b  ~140 GB  |  405b  ~810 GB
     airllm_model_size: Literal["8b", "70b", "405b"] = "70b"
 
+    # ── Grok (xAI) — opt-in premium cloud backend ────────────────────────
+    # Grok is a premium augmentation layer — local-first ethos preserved.
+    # Only used when explicitly enabled and query complexity warrants it.
+    grok_enabled: bool = False
+    xai_api_key: str = ""
+    grok_default_model: str = "grok-3-fast"
+    grok_max_sats_per_query: int = 200
+    grok_free: bool = False  # Skip Lightning invoice when user has own API key
+
     # ── Spark Intelligence ────────────────────────────────────────────────
     # Enable/disable the Spark cognitive layer.
     # When enabled, Spark captures swarm events, runs EIDOS predictions,
@@ -76,6 +85,10 @@ class Settings(BaseSettings):
     # Default is False (telemetry disabled) to align with sovereign AI vision.
     telemetry_enabled: bool = False
 
+    # CORS allowed origins for the web chat interface (GitHub Pages, etc.)
+    # Set CORS_ORIGINS as a comma-separated list, e.g. "http://localhost:3000,https://example.com"
+    cors_origins: list[str] = ["*"]
+
     # Environment mode: development | production
     # In production, security settings are strictly enforced.
     timmy_env: Literal["development", "production"] = "development"
@@ -94,6 +107,28 @@ class Settings(BaseSettings):
     work_orders_auto_execute: bool = False  # Master switch for auto-execution
     work_orders_auto_threshold: str = "low"  # Max priority that auto-executes: "low" | "medium" | "high" | "none"
 
+    # ── Custom Weights & Models ──────────────────────────────────────
+    # Directory for custom model weights (GGUF, safetensors, HF checkpoints).
+    # Models placed here can be registered at runtime and assigned to agents.
+    custom_weights_dir: str = "data/models"
+    # Enable the reward model for scoring agent outputs (PRM-style).
+    reward_model_enabled: bool = False
+    # Reward model name (must be available via Ollama or a custom weight path).
+    reward_model_name: str = ""
+    # Minimum votes for majority-vote reward scoring (odd number recommended).
+    reward_model_votes: int = 3
+
+    # ── Browser Local Models (iPhone / WebGPU) ───────────────────────
+    # Enable in-browser LLM inference via WebLLM for offline iPhone use.
+    # When enabled, the mobile dashboard loads a small model directly
+    # in the browser — no server or Ollama required.
+    browser_model_enabled: bool = True
+    # WebLLM model ID — must be a pre-compiled MLC model.
+    # Recommended for iPhone: SmolLM2-360M (fast) or Qwen3-0.6B (smart).
+    browser_model_id: str = "SmolLM2-360M-Instruct-q4f16_1-MLC"
+    # Fallback to server when browser model is unavailable or too slow.
+    browser_model_fallback: bool = True
+
     # ── Scripture / Biblical Integration ──────────────────────────────
     # Enable the sovereign biblical text module.  When enabled, Timmy
     # loads the local ESV text corpus and runs meditation workflows.
diff --git a/src/creative/CLAUDE.md b/src/creative/CLAUDE.md
new file mode 100644
index 00000000..cd25f394
--- /dev/null
+++ b/src/creative/CLAUDE.md
@@ -0,0 +1,18 @@
+# creative/ — Module Guide
+
+GPU-accelerated media generation. Heavy dependencies (PyTorch, diffusers).
+
+## Structure
+- `director.py` — Orchestrates multi-step creative pipelines
+- `assembler.py` — Video assembly and stitching
+- `tools/` — MCP-compliant tool implementations
+  - `image_tools.py` — FLUX.2 image generation
+  - `music_tools.py` — ACE-Step music generation
+  - `video_tools.py` — Wan 2.1 video generation
+  - `git_tools.py`, `file_ops.py`, `code_exec.py` — Utility tools
+  - `self_edit.py` — Self-modification MCP tool (protected file)
+
+## Testing
+```bash
+pytest tests/creative/ -q
+```
diff --git a/src/creative/director.py b/src/creative/director.py
index 968fff9b..914297b7 100644
--- a/src/creative/director.py
+++ b/src/creative/director.py
@@ -132,7 +132,7 @@ def run_storyboard(project_id: str) -> dict:
 
     project.status = "storyboard"
 
-    from tools.image_tools import generate_storyboard
+    from creative.tools.image_tools import generate_storyboard
 
     scene_descriptions = [s["description"] for s in project.scenes]
     result = generate_storyboard(scene_descriptions)
@@ -159,7 +159,7 @@ def run_music(
 
     project.status = "music"
 
-    from tools.music_tools import generate_song
+    from creative.tools.music_tools import generate_song
 
     # Default duration: ~15s per scene, minimum 60s
     target_duration = duration or max(60, len(project.scenes) * 15)
@@ -192,7 +192,7 @@ def run_video_generation(project_id: str) -> dict:
 
     project.status = "video"
 
-    from tools.video_tools import generate_video_clip, image_to_video
+    from creative.tools.video_tools import generate_video_clip, image_to_video
 
     clips = []
     for i, scene in enumerate(project.scenes):
diff --git a/src/tools/__init__.py b/src/creative/tools/__init__.py
similarity index 100%
rename from src/tools/__init__.py
rename to src/creative/tools/__init__.py
diff --git a/src/tools/code_exec.py b/src/creative/tools/code_exec.py
similarity index 100%
rename from src/tools/code_exec.py
rename to src/creative/tools/code_exec.py
diff --git a/src/tools/file_ops.py b/src/creative/tools/file_ops.py
similarity index 100%
rename from src/tools/file_ops.py
rename to src/creative/tools/file_ops.py
diff --git a/src/tools/git_tools.py b/src/creative/tools/git_tools.py
similarity index 100%
rename from src/tools/git_tools.py
rename to src/creative/tools/git_tools.py
diff --git a/src/tools/image_tools.py b/src/creative/tools/image_tools.py
similarity index 100%
rename from src/tools/image_tools.py
rename to src/creative/tools/image_tools.py
diff --git a/src/tools/memory_tool.py b/src/creative/tools/memory_tool.py
similarity index 100%
rename from src/tools/memory_tool.py
rename to src/creative/tools/memory_tool.py
diff --git a/src/tools/music_tools.py b/src/creative/tools/music_tools.py
similarity index 100%
rename from src/tools/music_tools.py
rename to src/creative/tools/music_tools.py
diff --git a/src/tools/self_edit.py b/src/creative/tools/self_edit.py
similarity index 99%
rename from src/tools/self_edit.py
rename to src/creative/tools/self_edit.py
index a28f314a..3553b92c 100644
--- a/src/tools/self_edit.py
+++ b/src/creative/tools/self_edit.py
@@ -13,7 +13,7 @@ This is the core self-modification orchestrator that:
 10. Generates reflections
 
 Usage:
-    from tools.self_edit import self_edit_tool
+    from creative.tools.self_edit import self_edit_tool
     from mcp.registry import tool_registry
     
     # Register with MCP
@@ -818,7 +818,7 @@ def register_self_edit_tool(registry: Any, llm_adapter: Optional[object] = None)
         category="self_coding",
         requires_confirmation=True,  # Safety: require user approval
         tags=["self-modification", "code-generation"],
-        source_module="tools.self_edit",
+        source_module="creative.tools.self_edit",
     )
     
     logger.info("Self-edit tool registered with MCP")
diff --git a/src/tools/video_tools.py b/src/creative/tools/video_tools.py
similarity index 100%
rename from src/tools/video_tools.py
rename to src/creative/tools/video_tools.py
diff --git a/src/tools/web_search.py b/src/creative/tools/web_search.py
similarity index 100%
rename from src/tools/web_search.py
rename to src/creative/tools/web_search.py
diff --git a/src/dashboard/__init__.py b/src/dashboard/__init__.py
index e69de29b..350ce2c9 100644
--- a/src/dashboard/__init__.py
+++ b/src/dashboard/__init__.py
@@ -0,0 +1 @@
+"""Dashboard — FastAPI + HTMX Mission Control web application."""
diff --git a/src/dashboard/app.py b/src/dashboard/app.py
index e4dcc899..dbc6f846 100644
--- a/src/dashboard/app.py
+++ b/src/dashboard/app.py
@@ -5,6 +5,7 @@ from contextlib import asynccontextmanager
 from pathlib import Path
 
 from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import HTMLResponse
 from fastapi.staticfiles import StaticFiles
 from fastapi.templating import Jinja2Templates
@@ -12,21 +13,17 @@ from fastapi.templating import Jinja2Templates
 from config import settings
 from dashboard.routes.agents import router as agents_router
 from dashboard.routes.health import router as health_router
-from dashboard.routes.mobile_test import router as mobile_test_router
 from dashboard.routes.swarm import router as swarm_router
+from dashboard.routes.swarm import internal_router as swarm_internal_router
 from dashboard.routes.marketplace import router as marketplace_router
 from dashboard.routes.voice import router as voice_router
-from dashboard.routes.voice_enhanced import router as voice_enhanced_router
 from dashboard.routes.mobile import router as mobile_router
-from dashboard.routes.swarm_ws import router as swarm_ws_router
 from dashboard.routes.briefing import router as briefing_router
 from dashboard.routes.telegram import router as telegram_router
-from dashboard.routes.swarm_internal import router as swarm_internal_router
 from dashboard.routes.tools import router as tools_router
 from dashboard.routes.spark import router as spark_router
 from dashboard.routes.creative import router as creative_router
 from dashboard.routes.discord import router as discord_router
-from dashboard.routes.self_modify import router as self_modify_router
 from dashboard.routes.events import router as events_router
 from dashboard.routes.ledger import router as ledger_router
 from dashboard.routes.memory import router as memory_router
@@ -36,8 +33,12 @@ from dashboard.routes.work_orders import router as work_orders_router
 from dashboard.routes.tasks import router as tasks_router
 from dashboard.routes.scripture import router as scripture_router
 from dashboard.routes.self_coding import router as self_coding_router
+from dashboard.routes.self_coding import self_modify_router
 from dashboard.routes.hands import router as hands_router
-from router.api import router as cascade_router
+from dashboard.routes.grok import router as grok_router
+from dashboard.routes.models import router as models_router
+from dashboard.routes.models import api_router as models_api_router
+from infrastructure.router.api import router as cascade_router
 
 logging.basicConfig(
     level=logging.INFO,
@@ -60,7 +61,7 @@ async def _briefing_scheduler() -> None:
     exists (< 30 min old).
     """
     from timmy.briefing import engine as briefing_engine
-    from notifications.push import notify_briefing_ready
+    from infrastructure.notifications.push import notify_briefing_ready
 
     await asyncio.sleep(2)  # Let server finish starting before first run
 
@@ -131,16 +132,16 @@ async def lifespan(app: FastAPI):
             logger.info("MCP auto-bootstrap: %d tools registered", len(registered))
     except Exception as exc:
         logger.warning("MCP auto-bootstrap failed: %s", exc)
-    
+
     # Initialise Spark Intelligence engine
     from spark.engine import spark_engine
     if spark_engine.enabled:
         logger.info("Spark Intelligence active — event capture enabled")
 
     # Auto-start chat integrations (skip silently if unconfigured)
-    from telegram_bot.bot import telegram_bot
-    from chat_bridge.vendors.discord import discord_bot
-    from chat_bridge.registry import platform_registry
+    from integrations.telegram_bot.bot import telegram_bot
+    from integrations.chat_bridge.vendors.discord import discord_bot
+    from integrations.chat_bridge.registry import platform_registry
     platform_registry.register(discord_bot)
 
     if settings.telegram_token:
@@ -173,25 +174,31 @@ app = FastAPI(
     redoc_url="/redoc" if settings.debug else None,
 )
 
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
 templates = Jinja2Templates(directory=str(BASE_DIR / "templates"))
 app.mount("/static", StaticFiles(directory=str(PROJECT_ROOT / "static")), name="static")
 
 app.include_router(health_router)
 app.include_router(agents_router)
-app.include_router(mobile_test_router)
 app.include_router(swarm_router)
+app.include_router(swarm_internal_router)
 app.include_router(marketplace_router)
 app.include_router(voice_router)
-app.include_router(voice_enhanced_router)
 app.include_router(mobile_router)
-app.include_router(swarm_ws_router)
 app.include_router(briefing_router)
 app.include_router(telegram_router)
-app.include_router(swarm_internal_router)
 app.include_router(tools_router)
 app.include_router(spark_router)
 app.include_router(creative_router)
 app.include_router(discord_router)
+app.include_router(self_coding_router)
 app.include_router(self_modify_router)
 app.include_router(events_router)
 app.include_router(ledger_router)
@@ -201,8 +208,10 @@ app.include_router(upgrades_router)
 app.include_router(work_orders_router)
 app.include_router(tasks_router)
 app.include_router(scripture_router)
-app.include_router(self_coding_router)
 app.include_router(hands_router)
+app.include_router(grok_router)
+app.include_router(models_router)
+app.include_router(models_api_router)
 app.include_router(cascade_router)
 
 
@@ -214,5 +223,5 @@ async def index(request: Request):
 @app.get("/shortcuts/setup")
 async def shortcuts_setup():
     """Siri Shortcuts setup guide."""
-    from shortcuts.siri import get_setup_guide
+    from integrations.shortcuts.siri import get_setup_guide
     return get_setup_guide()
diff --git a/src/dashboard/routes/__init__.py b/src/dashboard/routes/__init__.py
index e69de29b..579c2f95 100644
--- a/src/dashboard/routes/__init__.py
+++ b/src/dashboard/routes/__init__.py
@@ -0,0 +1 @@
+"""Dashboard route modules — one file per route group."""
diff --git a/src/dashboard/routes/agents.py b/src/dashboard/routes/agents.py
index c25028e6..e8526752 100644
--- a/src/dashboard/routes/agents.py
+++ b/src/dashboard/routes/agents.py
@@ -125,7 +125,7 @@ def _extract_task_from_message(message: str) -> dict | None:
 def _build_queue_context() -> str:
     """Build a concise task queue summary for context injection."""
     try:
-        from task_queue.models import get_counts_by_status, list_tasks, TaskStatus
+        from swarm.task_queue.models import get_counts_by_status, list_tasks, TaskStatus
         counts = get_counts_by_status()
         pending = counts.get("pending_approval", 0)
         running = counts.get("running", 0)
@@ -215,7 +215,7 @@ async def chat_timmy(request: Request, message: str = Form(...)):
     task_info = _extract_task_from_message(message)
     if task_info:
         try:
-            from task_queue.models import create_task
+            from swarm.task_queue.models import create_task
             task = create_task(
                 title=task_info["title"],
                 description=task_info["description"],
diff --git a/src/dashboard/routes/creative.py b/src/dashboard/routes/creative.py
index f24b5ff1..c18b4453 100644
--- a/src/dashboard/routes/creative.py
+++ b/src/dashboard/routes/creative.py
@@ -68,7 +68,7 @@ async def creative_projects_api():
 async def creative_genres_api():
     """Return supported music genres."""
     try:
-        from tools.music_tools import GENRES
+        from creative.tools.music_tools import GENRES
         return {"genres": GENRES}
     except ImportError:
         return {"genres": []}
@@ -78,7 +78,7 @@ async def creative_genres_api():
 async def creative_video_styles_api():
     """Return supported video styles and resolutions."""
     try:
-        from tools.video_tools import VIDEO_STYLES, RESOLUTION_PRESETS
+        from creative.tools.video_tools import VIDEO_STYLES, RESOLUTION_PRESETS
         return {
             "styles": VIDEO_STYLES,
             "resolutions": list(RESOLUTION_PRESETS.keys()),
diff --git a/src/dashboard/routes/discord.py b/src/dashboard/routes/discord.py
index 28629a5d..c8e54a08 100644
--- a/src/dashboard/routes/discord.py
+++ b/src/dashboard/routes/discord.py
@@ -25,7 +25,7 @@ async def setup_discord(payload: TokenPayload):
     Send POST with JSON body: {"token": "<your-bot-token>"}
     Get the token from https://discord.com/developers/applications
     """
-    from chat_bridge.vendors.discord import discord_bot
+    from integrations.chat_bridge.vendors.discord import discord_bot
 
     token = payload.token.strip()
     if not token:
@@ -51,7 +51,7 @@ async def setup_discord(payload: TokenPayload):
 @router.get("/status")
 async def discord_status():
     """Return current Discord bot status."""
-    from chat_bridge.vendors.discord import discord_bot
+    from integrations.chat_bridge.vendors.discord import discord_bot
 
     return discord_bot.status().to_dict()
 
@@ -70,8 +70,8 @@ async def join_from_image(
     The bot validates the invite and returns the OAuth2 URL for the
     server admin to authorize the bot.
     """
-    from chat_bridge.invite_parser import invite_parser
-    from chat_bridge.vendors.discord import discord_bot
+    from integrations.chat_bridge.invite_parser import invite_parser
+    from integrations.chat_bridge.vendors.discord import discord_bot
 
     invite_info = None
 
@@ -129,7 +129,7 @@ async def join_from_image(
 @router.get("/oauth-url")
 async def discord_oauth_url():
     """Get the bot's OAuth2 authorization URL for adding to servers."""
-    from chat_bridge.vendors.discord import discord_bot
+    from integrations.chat_bridge.vendors.discord import discord_bot
 
     url = discord_bot.get_oauth2_url()
     if url:
diff --git a/src/dashboard/routes/grok.py b/src/dashboard/routes/grok.py
new file mode 100644
index 00000000..653c1337
--- /dev/null
+++ b/src/dashboard/routes/grok.py
@@ -0,0 +1,234 @@
+"""Grok (xAI) dashboard routes — premium cloud augmentation controls.
+
+Endpoints
+---------
+GET  /grok/status     — JSON status (API)
+POST /grok/toggle     — Enable/disable Grok Mode (HTMX)
+POST /grok/chat       — Direct Grok query (HTMX)
+GET  /grok/stats      — Usage statistics (JSON)
+"""
+
+import logging
+from pathlib import Path
+
+from fastapi import APIRouter, Form, Request
+from fastapi.responses import HTMLResponse, JSONResponse
+from fastapi.templating import Jinja2Templates
+
+from config import settings
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/grok", tags=["grok"])
+templates = Jinja2Templates(directory=str(Path(__file__).parent.parent / "templates"))
+
+# In-memory toggle state (persists per process lifetime)
+_grok_mode_active: bool = False
+
+
+@router.get("/status")
+async def grok_status():
+    """Return Grok backend status as JSON."""
+    from timmy.backends import grok_available
+
+    status = {
+        "enabled": settings.grok_enabled,
+        "available": grok_available(),
+        "active": _grok_mode_active,
+        "model": settings.grok_default_model,
+        "free_mode": settings.grok_free,
+        "max_sats_per_query": settings.grok_max_sats_per_query,
+        "api_key_set": bool(settings.xai_api_key),
+    }
+
+    # Include usage stats if backend exists
+    try:
+        from timmy.backends import get_grok_backend
+        backend = get_grok_backend()
+        status["stats"] = {
+            "total_requests": backend.stats.total_requests,
+            "total_prompt_tokens": backend.stats.total_prompt_tokens,
+            "total_completion_tokens": backend.stats.total_completion_tokens,
+            "estimated_cost_sats": backend.stats.estimated_cost_sats,
+            "errors": backend.stats.errors,
+        }
+    except Exception:
+        status["stats"] = None
+
+    return status
+
+
+@router.post("/toggle")
+async def toggle_grok_mode(request: Request):
+    """Toggle Grok Mode on/off. Returns HTMX partial for the toggle card."""
+    global _grok_mode_active
+
+    from timmy.backends import grok_available
+
+    if not grok_available():
+        return HTMLResponse(
+            '<div class="alert" style="color: var(--danger);">'
+            "Grok unavailable — set GROK_ENABLED=true and XAI_API_KEY in .env"
+            "</div>",
+            status_code=200,
+        )
+
+    _grok_mode_active = not _grok_mode_active
+    state = "ACTIVE" if _grok_mode_active else "STANDBY"
+
+    logger.info("Grok Mode toggled: %s", state)
+
+    # Log to Spark
+    try:
+        from spark.engine import spark_engine
+        import json
+
+        spark_engine.on_tool_executed(
+            agent_id="timmy",
+            tool_name="grok_mode_toggle",
+            success=True,
+        )
+    except Exception:
+        pass
+
+    return HTMLResponse(
+        _render_toggle_card(_grok_mode_active),
+        status_code=200,
+    )
+
+
+@router.post("/chat", response_class=HTMLResponse)
+async def grok_chat(request: Request, message: str = Form(...)):
+    """Send a message directly to Grok and return HTMX chat partial."""
+    from timmy.backends import grok_available, get_grok_backend
+    from dashboard.store import message_log
+    from datetime import datetime
+
+    timestamp = datetime.now().strftime("%H:%M:%S")
+
+    if not grok_available():
+        error = "Grok is not available. Set GROK_ENABLED=true and XAI_API_KEY."
+        message_log.append(role="user", content=f"[Grok] {message}", timestamp=timestamp)
+        message_log.append(role="error", content=error, timestamp=timestamp)
+        return templates.TemplateResponse(
+            request,
+            "partials/chat_message.html",
+            {
+                "user_message": f"[Grok] {message}",
+                "response": None,
+                "error": error,
+                "timestamp": timestamp,
+            },
+        )
+
+    backend = get_grok_backend()
+
+    # Generate invoice if monetization is active
+    invoice_note = ""
+    if not settings.grok_free:
+        try:
+            from lightning.factory import get_backend as get_ln_backend
+
+            ln = get_ln_backend()
+            sats = min(settings.grok_max_sats_per_query, 100)
+            inv = ln.create_invoice(sats, f"Grok: {message[:50]}")
+            invoice_note = f" | {sats} sats"
+        except Exception:
+            pass
+
+    try:
+        result = backend.run(message)
+        response_text = f"**[Grok]{invoice_note}:** {result.content}"
+    except Exception as exc:
+        response_text = None
+        error = f"Grok error: {exc}"
+
+    message_log.append(
+        role="user", content=f"[Ask Grok] {message}", timestamp=timestamp
+    )
+    if response_text:
+        message_log.append(role="agent", content=response_text, timestamp=timestamp)
+        return templates.TemplateResponse(
+            request,
+            "partials/chat_message.html",
+            {
+                "user_message": f"[Ask Grok] {message}",
+                "response": response_text,
+                "error": None,
+                "timestamp": timestamp,
+            },
+        )
+    else:
+        message_log.append(role="error", content=error, timestamp=timestamp)
+        return templates.TemplateResponse(
+            request,
+            "partials/chat_message.html",
+            {
+                "user_message": f"[Ask Grok] {message}",
+                "response": None,
+                "error": error,
+                "timestamp": timestamp,
+            },
+        )
+
+
+@router.get("/stats")
+async def grok_stats():
+    """Return detailed Grok usage statistics."""
+    try:
+        from timmy.backends import get_grok_backend
+
+        backend = get_grok_backend()
+        return {
+            "total_requests": backend.stats.total_requests,
+            "total_prompt_tokens": backend.stats.total_prompt_tokens,
+            "total_completion_tokens": backend.stats.total_completion_tokens,
+            "total_latency_ms": round(backend.stats.total_latency_ms, 2),
+            "avg_latency_ms": round(
+                backend.stats.total_latency_ms / max(backend.stats.total_requests, 1),
+                2,
+            ),
+            "estimated_cost_sats": backend.stats.estimated_cost_sats,
+            "errors": backend.stats.errors,
+            "model": settings.grok_default_model,
+        }
+    except Exception as exc:
+        return {"error": str(exc)}
+
+
+def _render_toggle_card(active: bool) -> str:
+    """Render the Grok Mode toggle card HTML."""
+    color = "#00ff88" if active else "#666"
+    state = "ACTIVE" if active else "STANDBY"
+    glow = "0 0 20px rgba(0, 255, 136, 0.4)" if active else "none"
+
+    return f"""
+    <div id="grok-toggle-card"
+         style="border: 2px solid {color}; border-radius: 12px; padding: 16px;
+                background: var(--bg-secondary); box-shadow: {glow};
+                transition: all 0.3s ease;">
+        <div style="display: flex; justify-content: space-between; align-items: center;">
+            <div>
+                <div style="font-weight: 700; font-size: 1.1rem; color: {color};">
+                    GROK MODE: {state}
+                </div>
+                <div style="font-size: 0.8rem; color: var(--text-muted); margin-top: 4px;">
+                    xAI frontier reasoning | {settings.grok_default_model}
+                </div>
+            </div>
+            <button hx-post="/grok/toggle"
+                    hx-target="#grok-toggle-card"
+                    hx-swap="outerHTML"
+                    style="background: {color}; color: #000; border: none;
+                           border-radius: 8px; padding: 8px 20px; cursor: pointer;
+                           font-weight: 700; font-family: inherit;">
+                {'DEACTIVATE' if active else 'ACTIVATE'}
+            </button>
+        </div>
+    </div>
+    """
+
+
+def is_grok_mode_active() -> bool:
+    """Check if Grok Mode is currently active (used by other modules)."""
+    return _grok_mode_active
diff --git a/src/dashboard/routes/memory.py b/src/dashboard/routes/memory.py
index 678720a1..067b970b 100644
--- a/src/dashboard/routes/memory.py
+++ b/src/dashboard/routes/memory.py
@@ -7,7 +7,7 @@ from fastapi import APIRouter, Form, HTTPException, Request
 from fastapi.responses import HTMLResponse, JSONResponse
 from fastapi.templating import Jinja2Templates
 
-from memory.vector_store import (
+from timmy.memory.vector_store import (
     store_memory,
     search_memories,
     get_memory_stats,
diff --git a/src/dashboard/routes/mobile.py b/src/dashboard/routes/mobile.py
index 7d1d266b..33a17f0a 100644
--- a/src/dashboard/routes/mobile.py
+++ b/src/dashboard/routes/mobile.py
@@ -3,6 +3,9 @@
 Provides a simplified, mobile-first view of the dashboard that
 prioritizes the chat interface and essential status information.
 Designed for quick access from a phone's home screen.
+
+The /mobile/local endpoint loads a small LLM directly into the
+browser via WebLLM so Timmy can run on an iPhone with no server.
 """
 
 from pathlib import Path
@@ -11,6 +14,8 @@ from fastapi import APIRouter, Request
 from fastapi.responses import HTMLResponse
 from fastapi.templating import Jinja2Templates
 
+from config import settings
+
 router = APIRouter(tags=["mobile"])
 templates = Jinja2Templates(directory=str(Path(__file__).parent.parent / "templates"))
 
@@ -26,11 +31,44 @@ async def mobile_dashboard(request: Request):
     return templates.TemplateResponse(request, "index.html")
 
 
+@router.get("/mobile/local", response_class=HTMLResponse)
+async def mobile_local_dashboard(request: Request):
+    """Mobile dashboard with in-browser local model inference.
+
+    Loads a small LLM (via WebLLM / WebGPU) directly into Safari
+    so Timmy works on an iPhone without any server connection.
+    Falls back to server-side Ollama when the local model is
+    unavailable or the user prefers it.
+    """
+    return templates.TemplateResponse(
+        request,
+        "mobile_local.html",
+        {
+            "browser_model_enabled": settings.browser_model_enabled,
+            "browser_model_id": settings.browser_model_id,
+            "browser_model_fallback": settings.browser_model_fallback,
+            "server_model": settings.ollama_model,
+            "page_title": "Timmy — Local AI",
+        },
+    )
+
+
+@router.get("/mobile/local-models")
+async def local_models_config():
+    """Return browser model configuration for the JS client."""
+    return {
+        "enabled": settings.browser_model_enabled,
+        "default_model": settings.browser_model_id,
+        "fallback_to_server": settings.browser_model_fallback,
+        "server_model": settings.ollama_model,
+        "server_url": settings.ollama_url,
+    }
+
+
 @router.get("/mobile/status")
 async def mobile_status():
     """Lightweight status endpoint optimized for mobile polling."""
     from dashboard.routes.health import check_ollama
-    from config import settings
 
     ollama_ok = await check_ollama()
     return {
@@ -38,4 +76,6 @@ async def mobile_status():
         "model": settings.ollama_model,
         "agent": "timmy",
         "ready": True,
+        "browser_model_enabled": settings.browser_model_enabled,
+        "browser_model_id": settings.browser_model_id,
     }
diff --git a/src/dashboard/routes/mobile_test.py b/src/dashboard/routes/mobile_test.py
deleted file mode 100644
index ef22337d..00000000
--- a/src/dashboard/routes/mobile_test.py
+++ /dev/null
@@ -1,257 +0,0 @@
-"""Mobile HITL (Human-in-the-Loop) test checklist route.
-
-GET /mobile-test   — interactive checklist for a human tester on their phone.
-
-Each scenario specifies what to do and what to observe.  The tester marks
-each one PASS / FAIL / SKIP.  Results are stored in sessionStorage so they
-survive page scrolling without hitting the server.
-"""
-
-from pathlib import Path
-
-from fastapi import APIRouter, Request
-from fastapi.responses import HTMLResponse
-from fastapi.templating import Jinja2Templates
-
-router = APIRouter(tags=["mobile-test"])
-templates = Jinja2Templates(directory=str(Path(__file__).parent.parent / "templates"))
-
-# ── Test scenarios ────────────────────────────────────────────────────────────
-# Each dict: id, category, title, steps (list), expected
-SCENARIOS = [
-    # Layout
-    {
-        "id": "L01",
-        "category": "Layout",
-        "title": "Sidebar renders as horizontal strip",
-        "steps": [
-            "Open the Mission Control page on your phone.",
-            "Look at the top section above the chat window.",
-        ],
-        "expected": (
-            "AGENTS and SYSTEM HEALTH panels appear side-by-side in a "
-            "horizontally scrollable strip — not stacked vertically."
-        ),
-    },
-    {
-        "id": "L02",
-        "category": "Layout",
-        "title": "Sidebar panels are horizontally scrollable",
-        "steps": [
-            "Swipe left/right on the AGENTS / SYSTEM HEALTH strip.",
-        ],
-        "expected": "Both panels slide smoothly; no page scroll is triggered.",
-    },
-    {
-        "id": "L03",
-        "category": "Layout",
-        "title": "Chat panel fills ≥ 60 % of viewport height",
-        "steps": [
-            "Look at the TIMMY INTERFACE chat card below the strip.",
-        ],
-        "expected": "The chat card occupies at least 60 % of the visible screen height.",
-    },
-    {
-        "id": "L04",
-        "category": "Layout",
-        "title": "Header stays fixed while chat scrolls",
-        "steps": [
-            "Send several messages until the chat overflows.",
-            "Scroll the chat log up and down.",
-        ],
-        "expected": "The TIMMY TIME / MISSION CONTROL header remains pinned at the top.",
-    },
-    {
-        "id": "L05",
-        "category": "Layout",
-        "title": "No horizontal page overflow",
-        "steps": [
-            "Try swiping left or right anywhere on the page.",
-        ],
-        "expected": "The page does not scroll horizontally; nothing is cut off.",
-    },
-    # Touch & Input
-    {
-        "id": "T01",
-        "category": "Touch & Input",
-        "title": "iOS does NOT zoom when tapping the input",
-        "steps": [
-            "Tap the message input field once.",
-            "Watch whether the browser zooms in.",
-        ],
-        "expected": "The keyboard rises; the layout does NOT zoom in.",
-    },
-    {
-        "id": "T02",
-        "category": "Touch & Input",
-        "title": "Keyboard return key is labelled 'Send'",
-        "steps": [
-            "Tap the message input to open the iOS/Android keyboard.",
-            "Look at the return / action key in the bottom-right of the keyboard.",
-        ],
-        "expected": "The key is labelled 'Send' (not 'Return' or 'Go').",
-    },
-    {
-        "id": "T03",
-        "category": "Touch & Input",
-        "title": "Send button is easy to tap (≥ 44 px tall)",
-        "steps": [
-            "Try tapping the SEND button with your thumb.",
-        ],
-        "expected": "The button registers the tap reliably on the first attempt.",
-    },
-    {
-        "id": "T04",
-        "category": "Touch & Input",
-        "title": "SEND button disabled during in-flight request",
-        "steps": [
-            "Type a message and press SEND.",
-            "Immediately try to tap SEND again before a response arrives.",
-        ],
-        "expected": "The button is visually disabled; no duplicate message is sent.",
-    },
-    {
-        "id": "T05",
-        "category": "Touch & Input",
-        "title": "Empty message cannot be submitted",
-        "steps": [
-            "Leave the input blank.",
-            "Tap SEND.",
-        ],
-        "expected": "Nothing is submitted; the form shows a required-field indicator.",
-    },
-    {
-        "id": "T06",
-        "category": "Touch & Input",
-        "title": "CLEAR button shows confirmation dialog",
-        "steps": [
-            "Send at least one message.",
-            "Tap the CLEAR button in the top-right of the chat header.",
-        ],
-        "expected": "A browser confirmation dialog appears before history is cleared.",
-    },
-    # Chat behaviour
-    {
-        "id": "C01",
-        "category": "Chat",
-        "title": "Chat auto-scrolls to the latest message",
-        "steps": [
-            "Scroll the chat log to the top.",
-            "Send a new message.",
-        ],
-        "expected": "After the response arrives the chat automatically scrolls to the bottom.",
-    },
-    {
-        "id": "C02",
-        "category": "Chat",
-        "title": "Multi-turn conversation — Timmy remembers context",
-        "steps": [
-            "Send: 'My name is <your name>.'",
-            "Then send: 'What is my name?'",
-        ],
-        "expected": "Timmy replies with your name, demonstrating conversation memory.",
-    },
-    {
-        "id": "C03",
-        "category": "Chat",
-        "title": "Loading indicator appears while waiting",
-        "steps": [
-            "Send a message and watch the SEND button.",
-        ],
-        "expected": "A blinking cursor (▋) appears next to SEND while the response is loading.",
-    },
-    {
-        "id": "C04",
-        "category": "Chat",
-        "title": "Offline error is shown gracefully",
-        "steps": [
-            "Stop Ollama on your host machine (or disconnect from Wi-Fi temporarily).",
-            "Send a message from your phone.",
-        ],
-        "expected": "A red 'Timmy is offline' error appears in the chat — no crash or spinner hang.",
-    },
-    # Health panel
-    {
-        "id": "H01",
-        "category": "Health",
-        "title": "Health panel shows Ollama UP when running",
-        "steps": [
-            "Ensure Ollama is running on your host.",
-            "Check the SYSTEM HEALTH panel.",
-        ],
-        "expected": "OLLAMA badge shows green UP.",
-    },
-    {
-        "id": "H02",
-        "category": "Health",
-        "title": "Health panel auto-refreshes without reload",
-        "steps": [
-            "Start Ollama if it is not running.",
-            "Wait up to 35 seconds with the page open.",
-        ],
-        "expected": "The OLLAMA badge flips from DOWN → UP automatically, without a page reload.",
-    },
-    # Scroll & overscroll
-    {
-        "id": "S01",
-        "category": "Scroll",
-        "title": "No rubber-band / bounce on the main page",
-        "steps": [
-            "Scroll to the very top of the page.",
-            "Continue pulling downward.",
-        ],
-        "expected": "The page does not bounce or show a white gap — overscroll is suppressed.",
-    },
-    {
-        "id": "S02",
-        "category": "Scroll",
-        "title": "Chat log scrolls independently inside the card",
-        "steps": [
-            "Scroll inside the chat log area.",
-        ],
-        "expected": "The chat log scrolls smoothly; the outer page does not move.",
-    },
-    # Safe area / notch
-    {
-        "id": "N01",
-        "category": "Notch / Home Bar",
-        "title": "Header clears the status bar / Dynamic Island",
-        "steps": [
-            "On a notched iPhone (Face ID), look at the top of the page.",
-        ],
-        "expected": "The TIMMY TIME header text is not obscured by the notch or Dynamic Island.",
-    },
-    {
-        "id": "N02",
-        "category": "Notch / Home Bar",
-        "title": "Chat input not hidden behind home indicator",
-        "steps": [
-            "Tap the input field and look at the bottom of the screen.",
-        ],
-        "expected": "The input row sits above the iPhone home indicator bar — nothing is cut off.",
-    },
-    # Clock
-    {
-        "id": "X01",
-        "category": "Live UI",
-        "title": "Clock updates every second",
-        "steps": [
-            "Look at the time display in the top-right of the header.",
-            "Watch for 3 seconds.",
-        ],
-        "expected": "The time increments each second in HH:MM:SS format.",
-    },
-]
-
-
-@router.get("/mobile-test", response_class=HTMLResponse)
-async def mobile_test(request: Request):
-    """Interactive HITL mobile test checklist — open on your phone."""
-    categories: dict[str, list] = {}
-    for s in SCENARIOS:
-        categories.setdefault(s["category"], []).append(s)
-    return templates.TemplateResponse(
-        request,
-        "mobile_test.html",
-        {"scenarios": SCENARIOS, "categories": categories, "total": len(SCENARIOS)},
-    )
diff --git a/src/dashboard/routes/models.py b/src/dashboard/routes/models.py
new file mode 100644
index 00000000..77c566e9
--- /dev/null
+++ b/src/dashboard/routes/models.py
@@ -0,0 +1,272 @@
+"""Custom model management routes — register, list, assign, and swap models.
+
+Provides a REST API for managing custom model weights and their assignment
+to swarm agents.  Inspired by OpenClaw-RL's multi-model orchestration.
+"""
+
+import logging
+from pathlib import Path
+from typing import Any, Optional
+
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import HTMLResponse
+from fastapi.templating import Jinja2Templates
+from pydantic import BaseModel
+
+from config import settings
+from infrastructure.models.registry import (
+    CustomModel,
+    ModelFormat,
+    ModelRegistry,
+    ModelRole,
+    model_registry,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/models", tags=["models"])
+api_router = APIRouter(prefix="/api/v1/models", tags=["models-api"])
+templates = Jinja2Templates(directory=str(Path(__file__).parent.parent / "templates"))
+
+
+# ── Pydantic schemas ──────────────────────────────────────────────────────────
+
+
+class RegisterModelRequest(BaseModel):
+    """Request body for model registration."""
+    name: str
+    format: str  # gguf, safetensors, hf, ollama
+    path: str
+    role: str = "general"
+    context_window: int = 4096
+    description: str = ""
+    default_temperature: float = 0.7
+    max_tokens: int = 2048
+
+
+class AssignModelRequest(BaseModel):
+    """Request body for assigning a model to an agent."""
+    agent_id: str
+    model_name: str
+
+
+class SetActiveRequest(BaseModel):
+    """Request body for enabling/disabling a model."""
+    active: bool
+
+
+# ── API endpoints ─────────────────────────────────────────────────────────────
+
+
+@api_router.get("")
+async def list_models(role: Optional[str] = None) -> dict[str, Any]:
+    """List all registered custom models."""
+    model_role = ModelRole(role) if role else None
+    models = model_registry.list_models(role=model_role)
+    return {
+        "models": [
+            {
+                "name": m.name,
+                "format": m.format.value,
+                "path": m.path,
+                "role": m.role.value,
+                "context_window": m.context_window,
+                "description": m.description,
+                "active": m.active,
+                "registered_at": m.registered_at,
+                "default_temperature": m.default_temperature,
+                "max_tokens": m.max_tokens,
+            }
+            for m in models
+        ],
+        "total": len(models),
+        "weights_dir": settings.custom_weights_dir,
+    }
+
+
+@api_router.post("")
+async def register_model(request: RegisterModelRequest) -> dict[str, Any]:
+    """Register a new custom model."""
+    try:
+        fmt = ModelFormat(request.format)
+    except ValueError:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Invalid format: {request.format}. "
+                   f"Choose from: {[f.value for f in ModelFormat]}",
+        )
+    try:
+        role = ModelRole(request.role)
+    except ValueError:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Invalid role: {request.role}. "
+                   f"Choose from: {[r.value for r in ModelRole]}",
+        )
+
+    # Validate path exists for non-Ollama formats
+    if fmt != ModelFormat.OLLAMA:
+        weight_path = Path(request.path)
+        if not weight_path.exists():
+            raise HTTPException(
+                status_code=400,
+                detail=f"Weight path does not exist: {request.path}",
+            )
+
+    model = CustomModel(
+        name=request.name,
+        format=fmt,
+        path=request.path,
+        role=role,
+        context_window=request.context_window,
+        description=request.description,
+        default_temperature=request.default_temperature,
+        max_tokens=request.max_tokens,
+    )
+    registered = model_registry.register(model)
+    return {
+        "message": f"Model {registered.name} registered",
+        "model": {
+            "name": registered.name,
+            "format": registered.format.value,
+            "role": registered.role.value,
+            "path": registered.path,
+        },
+    }
+
+
+@api_router.get("/{model_name}")
+async def get_model(model_name: str) -> dict[str, Any]:
+    """Get details of a specific model."""
+    model = model_registry.get(model_name)
+    if not model:
+        raise HTTPException(status_code=404, detail=f"Model {model_name} not found")
+    return {
+        "name": model.name,
+        "format": model.format.value,
+        "path": model.path,
+        "role": model.role.value,
+        "context_window": model.context_window,
+        "description": model.description,
+        "active": model.active,
+        "registered_at": model.registered_at,
+        "default_temperature": model.default_temperature,
+        "max_tokens": model.max_tokens,
+    }
+
+
+@api_router.delete("/{model_name}")
+async def unregister_model(model_name: str) -> dict[str, str]:
+    """Remove a model from the registry."""
+    if not model_registry.unregister(model_name):
+        raise HTTPException(status_code=404, detail=f"Model {model_name} not found")
+    return {"message": f"Model {model_name} unregistered"}
+
+
+@api_router.patch("/{model_name}/active")
+async def set_model_active(
+    model_name: str, request: SetActiveRequest
+) -> dict[str, str]:
+    """Enable or disable a model."""
+    if not model_registry.set_active(model_name, request.active):
+        raise HTTPException(status_code=404, detail=f"Model {model_name} not found")
+    state = "enabled" if request.active else "disabled"
+    return {"message": f"Model {model_name} {state}"}
+
+
+# ── Agent assignment endpoints ────────────────────────────────────────────────
+
+
+@api_router.get("/assignments/all")
+async def list_assignments() -> dict[str, Any]:
+    """List all agent-to-model assignments."""
+    assignments = model_registry.get_agent_assignments()
+    return {
+        "assignments": [
+            {"agent_id": aid, "model_name": mname}
+            for aid, mname in assignments.items()
+        ],
+        "total": len(assignments),
+    }
+
+
+@api_router.post("/assignments")
+async def assign_model(request: AssignModelRequest) -> dict[str, str]:
+    """Assign a model to a swarm agent."""
+    if not model_registry.assign_model(request.agent_id, request.model_name):
+        raise HTTPException(
+            status_code=404,
+            detail=f"Model {request.model_name} not found in registry",
+        )
+    return {
+        "message": f"Model {request.model_name} assigned to {request.agent_id}",
+    }
+
+
+@api_router.delete("/assignments/{agent_id}")
+async def unassign_model(agent_id: str) -> dict[str, str]:
+    """Remove model assignment from an agent (reverts to default)."""
+    if not model_registry.unassign_model(agent_id):
+        raise HTTPException(
+            status_code=404,
+            detail=f"No model assignment for agent {agent_id}",
+        )
+    return {"message": f"Model assignment removed for {agent_id}"}
+
+
+# ── Role-based lookups ────────────────────────────────────────────────────────
+
+
+@api_router.get("/roles/reward")
+async def get_reward_model() -> dict[str, Any]:
+    """Get the active reward (PRM) model."""
+    model = model_registry.get_reward_model()
+    if not model:
+        return {"reward_model": None, "reward_enabled": settings.reward_model_enabled}
+    return {
+        "reward_model": {
+            "name": model.name,
+            "format": model.format.value,
+            "path": model.path,
+        },
+        "reward_enabled": settings.reward_model_enabled,
+    }
+
+
+@api_router.get("/roles/teacher")
+async def get_teacher_model() -> dict[str, Any]:
+    """Get the active teacher model for distillation."""
+    model = model_registry.get_teacher_model()
+    if not model:
+        return {"teacher_model": None}
+    return {
+        "teacher_model": {
+            "name": model.name,
+            "format": model.format.value,
+            "path": model.path,
+        },
+    }
+
+
+# ── Dashboard page ────────────────────────────────────────────────────────────
+
+
+@router.get("", response_class=HTMLResponse)
+async def models_page(request: Request):
+    """Custom models management dashboard page."""
+    models = model_registry.list_models()
+    assignments = model_registry.get_agent_assignments()
+    reward = model_registry.get_reward_model()
+
+    return templates.TemplateResponse(
+        request,
+        "models.html",
+        {
+            "page_title": "Custom Models",
+            "models": models,
+            "assignments": assignments,
+            "reward_model": reward,
+            "weights_dir": settings.custom_weights_dir,
+            "reward_enabled": settings.reward_model_enabled,
+        },
+    )
diff --git a/src/dashboard/routes/self_coding.py b/src/dashboard/routes/self_coding.py
index cf30f82e..57d7d405 100644
--- a/src/dashboard/routes/self_coding.py
+++ b/src/dashboard/routes/self_coding.py
@@ -5,17 +5,21 @@ API endpoints and HTMX views for the self-coding system:
 - Stats dashboard
 - Manual task execution
 - Real-time status updates
+- Self-modification loop (/self-modify/*)
 """
 
 from __future__ import annotations
 
+import asyncio
 import logging
 from typing import Optional
 
-from fastapi import APIRouter, Form, Request
+from fastapi import APIRouter, Form, HTTPException, Request
 from fastapi.responses import HTMLResponse, JSONResponse
 from pydantic import BaseModel
 
+from config import settings
+
 from self_coding import (
     CodebaseIndexer,
     ModificationJournal,
@@ -205,7 +209,7 @@ async def api_execute(request: ExecuteRequest):
     This is the API endpoint for manual task execution.
     In production, this should require authentication and confirmation.
     """
-    from tools.self_edit import SelfEditTool
+    from creative.tools.self_edit import SelfEditTool
     
     tool = SelfEditTool()
     result = await tool.execute(request.task_description)
@@ -328,7 +332,7 @@ async def execute_task(
 ):
     """HTMX endpoint to execute a task."""
     from dashboard.app import templates
-    from tools.self_edit import SelfEditTool
+    from creative.tools.self_edit import SelfEditTool
     
     tool = SelfEditTool()
     result = await tool.execute(task_description)
@@ -366,3 +370,59 @@ async def journal_entry_detail(request: Request, attempt_id: int):
             "entry": entry,
         },
     )
+
+
+# ── Self-Modification Routes (/self-modify/*) ───────────────────────────
+
+self_modify_router = APIRouter(prefix="/self-modify", tags=["self-modify"])
+
+
+@self_modify_router.post("/run")
+async def run_self_modify(
+    instruction: str = Form(...),
+    target_files: str = Form(""),
+    dry_run: bool = Form(False),
+    speak_result: bool = Form(False),
+):
+    """Execute a self-modification loop."""
+    if not settings.self_modify_enabled:
+        raise HTTPException(403, "Self-modification is disabled")
+
+    from self_coding.self_modify.loop import SelfModifyLoop, ModifyRequest
+
+    files = [f.strip() for f in target_files.split(",") if f.strip()]
+    request = ModifyRequest(
+        instruction=instruction,
+        target_files=files,
+        dry_run=dry_run,
+    )
+
+    loop = SelfModifyLoop()
+    result = await asyncio.to_thread(loop.run, request)
+
+    if speak_result and result.success:
+        try:
+            from timmy_serve.voice_tts import voice_tts
+            if voice_tts.available:
+                voice_tts.speak(
+                    f"Code modification complete. "
+                    f"{len(result.files_changed)} files changed. Tests passing."
+                )
+        except Exception:
+            pass
+
+    return {
+        "success": result.success,
+        "files_changed": result.files_changed,
+        "test_passed": result.test_passed,
+        "commit_sha": result.commit_sha,
+        "branch_name": result.branch_name,
+        "error": result.error,
+        "attempts": result.attempts,
+    }
+
+
+@self_modify_router.get("/status")
+async def self_modify_status():
+    """Return whether self-modification is enabled."""
+    return {"enabled": settings.self_modify_enabled}
diff --git a/src/dashboard/routes/self_modify.py b/src/dashboard/routes/self_modify.py
deleted file mode 100644
index 2e0cf74a..00000000
--- a/src/dashboard/routes/self_modify.py
+++ /dev/null
@@ -1,71 +0,0 @@
-"""Self-modification routes — /self-modify endpoints.
-
-Exposes the edit-test-commit loop as a REST API.  Gated by
-``SELF_MODIFY_ENABLED`` (default False).
-"""
-
-import asyncio
-import logging
-
-from fastapi import APIRouter, Form, HTTPException
-
-from config import settings
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(prefix="/self-modify", tags=["self-modify"])
-
-
-@router.post("/run")
-async def run_self_modify(
-    instruction: str = Form(...),
-    target_files: str = Form(""),
-    dry_run: bool = Form(False),
-    speak_result: bool = Form(False),
-):
-    """Execute a self-modification loop.
-
-    Returns the ModifyResult as JSON.
-    """
-    if not settings.self_modify_enabled:
-        raise HTTPException(403, "Self-modification is disabled")
-
-    from self_modify.loop import SelfModifyLoop, ModifyRequest
-
-    files = [f.strip() for f in target_files.split(",") if f.strip()]
-    request = ModifyRequest(
-        instruction=instruction,
-        target_files=files,
-        dry_run=dry_run,
-    )
-
-    loop = SelfModifyLoop()
-    result = await asyncio.to_thread(loop.run, request)
-
-    if speak_result and result.success:
-        try:
-            from timmy_serve.voice_tts import voice_tts
-
-            if voice_tts.available:
-                voice_tts.speak(
-                    f"Code modification complete. "
-                    f"{len(result.files_changed)} files changed. Tests passing."
-                )
-        except Exception:
-            pass
-
-    return {
-        "success": result.success,
-        "files_changed": result.files_changed,
-        "test_passed": result.test_passed,
-        "commit_sha": result.commit_sha,
-        "branch_name": result.branch_name,
-        "error": result.error,
-        "attempts": result.attempts,
-    }
-
-
-@router.get("/status")
-async def self_modify_status():
-    """Return whether self-modification is enabled."""
-    return {"enabled": settings.self_modify_enabled}
diff --git a/src/dashboard/routes/swarm.py b/src/dashboard/routes/swarm.py
index 263cac0d..cfb90970 100644
--- a/src/dashboard/routes/swarm.py
+++ b/src/dashboard/routes/swarm.py
@@ -1,22 +1,28 @@
-"""Swarm dashboard routes — /swarm/* endpoints.
+"""Swarm dashboard routes — /swarm/*, /internal/*, and /swarm/live endpoints.
 
 Provides REST endpoints for managing the swarm: listing agents,
-spawning sub-agents, posting tasks, and viewing auction results.
+spawning sub-agents, posting tasks, viewing auction results, Docker
+container agent HTTP API, and WebSocket live feed.
 """
 
 import asyncio
+import logging
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 
-from fastapi import APIRouter, Form, HTTPException, Request
+from fastapi import APIRouter, Form, HTTPException, Request, WebSocket, WebSocketDisconnect
 from fastapi.responses import HTMLResponse
 from fastapi.templating import Jinja2Templates
+from pydantic import BaseModel
 
 from swarm import learner as swarm_learner
 from swarm import registry
 from swarm.coordinator import coordinator
 from swarm.tasks import TaskStatus, update_task
+from infrastructure.ws_manager.handler import ws_manager
+
+logger = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/swarm", tags=["swarm"])
 templates = Jinja2Templates(directory=str(Path(__file__).parent.parent / "templates"))
@@ -325,3 +331,92 @@ async def message_agent(agent_id: str, request: Request, message: str = Form(...
     )
 
 
+# ── Internal HTTP API (Docker container agents) ─────────────────────────
+
+internal_router = APIRouter(prefix="/internal", tags=["internal"])
+
+
+class BidRequest(BaseModel):
+    task_id: str
+    agent_id: str
+    bid_sats: int
+    capabilities: Optional[str] = ""
+
+
+class BidResponse(BaseModel):
+    accepted: bool
+    task_id: str
+    agent_id: str
+    message: str
+
+
+class TaskSummary(BaseModel):
+    task_id: str
+    description: str
+    status: str
+
+
+@internal_router.get("/tasks", response_model=list[TaskSummary])
+def list_biddable_tasks():
+    """Return all tasks currently open for bidding."""
+    tasks = coordinator.list_tasks(status=TaskStatus.BIDDING)
+    return [
+        TaskSummary(
+            task_id=t.id,
+            description=t.description,
+            status=t.status.value,
+        )
+        for t in tasks
+    ]
+
+
+@internal_router.post("/bids", response_model=BidResponse)
+def submit_bid(bid: BidRequest):
+    """Accept a bid from a container agent."""
+    if bid.bid_sats <= 0:
+        raise HTTPException(status_code=422, detail="bid_sats must be > 0")
+
+    accepted = coordinator.auctions.submit_bid(
+        task_id=bid.task_id,
+        agent_id=bid.agent_id,
+        bid_sats=bid.bid_sats,
+    )
+
+    if accepted:
+        from swarm import stats as swarm_stats
+        swarm_stats.record_bid(bid.task_id, bid.agent_id, bid.bid_sats, won=False)
+        logger.info(
+            "Docker agent %s bid %d sats on task %s",
+            bid.agent_id, bid.bid_sats, bid.task_id,
+        )
+        return BidResponse(
+            accepted=True,
+            task_id=bid.task_id,
+            agent_id=bid.agent_id,
+            message="Bid accepted.",
+        )
+
+    return BidResponse(
+        accepted=False,
+        task_id=bid.task_id,
+        agent_id=bid.agent_id,
+        message="No open auction for this task — it may have already closed.",
+    )
+
+
+# ── WebSocket live feed ──────────────────────────────────────────────────
+
+@router.websocket("/live")
+async def swarm_live(websocket: WebSocket):
+    """WebSocket endpoint for live swarm event streaming."""
+    await ws_manager.connect(websocket)
+    try:
+        while True:
+            data = await websocket.receive_text()
+            logger.debug("WS received: %s", data[:100])
+    except WebSocketDisconnect:
+        ws_manager.disconnect(websocket)
+    except Exception as exc:
+        logger.error("WebSocket error: %s", exc)
+        ws_manager.disconnect(websocket)
+
diff --git a/src/dashboard/routes/swarm_internal.py b/src/dashboard/routes/swarm_internal.py
deleted file mode 100644
index a079913b..00000000
--- a/src/dashboard/routes/swarm_internal.py
+++ /dev/null
@@ -1,115 +0,0 @@
-"""Internal swarm HTTP API — for Docker container agents.
-
-Container agents can't use the in-memory SwarmComms channel, so they poll
-these lightweight endpoints to participate in the auction system.
-
-Routes
-------
-GET  /internal/tasks
-    Returns all tasks currently in BIDDING status — the set an agent
-    can submit bids for.
-
-POST /internal/bids
-    Accepts a bid from a container agent and feeds it into the in-memory
-    AuctionManager.  The coordinator then closes auctions and assigns
-    winners exactly as it does for in-process agents.
-
-These endpoints are intentionally unauthenticated because they are only
-reachable inside the Docker swarm-net bridge network.  Do not expose them
-through a reverse-proxy to the public internet.
-"""
-
-import logging
-from typing import Optional
-
-from fastapi import APIRouter, HTTPException
-from pydantic import BaseModel
-
-from swarm.coordinator import coordinator
-from swarm.tasks import TaskStatus
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(prefix="/internal", tags=["internal"])
-
-
-# ── Request / response models ─────────────────────────────────────────────────
-
-class BidRequest(BaseModel):
-    task_id: str
-    agent_id: str
-    bid_sats: int
-    capabilities: Optional[str] = ""
-
-
-class BidResponse(BaseModel):
-    accepted: bool
-    task_id: str
-    agent_id: str
-    message: str
-
-
-class TaskSummary(BaseModel):
-    task_id: str
-    description: str
-    status: str
-
-
-# ── Routes ────────────────────────────────────────────────────────────────────
-
-@router.get("/tasks", response_model=list[TaskSummary])
-def list_biddable_tasks():
-    """Return all tasks currently open for bidding.
-
-    Container agents should poll this endpoint and submit bids for any
-    tasks they are capable of handling.
-    """
-    tasks = coordinator.list_tasks(status=TaskStatus.BIDDING)
-    return [
-        TaskSummary(
-            task_id=t.id,
-            description=t.description,
-            status=t.status.value,
-        )
-        for t in tasks
-    ]
-
-
-@router.post("/bids", response_model=BidResponse)
-def submit_bid(bid: BidRequest):
-    """Accept a bid from a container agent.
-
-    The bid is injected directly into the in-memory AuctionManager.
-    If no auction is open for the task (e.g. it already closed), the
-    bid is rejected gracefully — the agent should just move on.
-    """
-    if bid.bid_sats <= 0:
-        raise HTTPException(status_code=422, detail="bid_sats must be > 0")
-
-    accepted = coordinator.auctions.submit_bid(
-        task_id=bid.task_id,
-        agent_id=bid.agent_id,
-        bid_sats=bid.bid_sats,
-    )
-
-    if accepted:
-        # Persist bid in stats table for marketplace analytics
-        from swarm import stats as swarm_stats
-        swarm_stats.record_bid(bid.task_id, bid.agent_id, bid.bid_sats, won=False)
-        logger.info(
-            "Docker agent %s bid %d sats on task %s",
-            bid.agent_id, bid.bid_sats, bid.task_id,
-        )
-        return BidResponse(
-            accepted=True,
-            task_id=bid.task_id,
-            agent_id=bid.agent_id,
-            message="Bid accepted.",
-        )
-
-    return BidResponse(
-        accepted=False,
-        task_id=bid.task_id,
-        agent_id=bid.agent_id,
-        message="No open auction for this task — it may have already closed.",
-    )
diff --git a/src/dashboard/routes/swarm_ws.py b/src/dashboard/routes/swarm_ws.py
deleted file mode 100644
index 13138dd6..00000000
--- a/src/dashboard/routes/swarm_ws.py
+++ /dev/null
@@ -1,33 +0,0 @@
-"""Swarm WebSocket route — /swarm/live endpoint.
-
-Provides a real-time WebSocket feed of swarm events for the live
-dashboard view.  Clients connect and receive JSON events as they
-happen: agent joins, task posts, bids, assignments, completions.
-"""
-
-import logging
-
-from fastapi import APIRouter, WebSocket, WebSocketDisconnect
-
-from ws_manager.handler import ws_manager
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(tags=["swarm-ws"])
-
-
-@router.websocket("/swarm/live")
-async def swarm_live(websocket: WebSocket):
-    """WebSocket endpoint for live swarm event streaming."""
-    await ws_manager.connect(websocket)
-    try:
-        while True:
-            # Keep the connection alive; client can also send commands
-            data = await websocket.receive_text()
-            # Echo back as acknowledgment (future: handle client commands)
-            logger.debug("WS received: %s", data[:100])
-    except WebSocketDisconnect:
-        ws_manager.disconnect(websocket)
-    except Exception as exc:
-        logger.error("WebSocket error: %s", exc)
-        ws_manager.disconnect(websocket)
diff --git a/src/dashboard/routes/tasks.py b/src/dashboard/routes/tasks.py
index 11048c14..0c2e892d 100644
--- a/src/dashboard/routes/tasks.py
+++ b/src/dashboard/routes/tasks.py
@@ -24,7 +24,7 @@ from fastapi import APIRouter, Form, HTTPException, Request
 from fastapi.responses import HTMLResponse, JSONResponse
 from fastapi.templating import Jinja2Templates
 
-from task_queue.models import (
+from swarm.task_queue.models import (
     QueueTask,
     TaskPriority,
     TaskStatus,
@@ -49,7 +49,7 @@ def _broadcast_task_event(event_type: str, task: QueueTask):
     """Best-effort broadcast a task event to connected WebSocket clients."""
     try:
         import asyncio
-        from ws_manager.handler import ws_manager
+        from infrastructure.ws_manager.handler import ws_manager
 
         payload = {
             "type": "task_event",
@@ -461,7 +461,7 @@ def _task_to_dict(task: QueueTask) -> dict:
 
 def _notify_task_created(task: QueueTask):
     try:
-        from notifications.push import notifier
+        from infrastructure.notifications.push import notifier
         notifier.notify(
             title="New Task",
             message=f"{task.created_by} created: {task.title}",
diff --git a/src/dashboard/routes/telegram.py b/src/dashboard/routes/telegram.py
index 00b93ca4..303d5cf0 100644
--- a/src/dashboard/routes/telegram.py
+++ b/src/dashboard/routes/telegram.py
@@ -17,7 +17,7 @@ async def setup_telegram(payload: TokenPayload):
     Send a POST with JSON body: {"token": "<your-bot-token>"}
     Get the token from @BotFather on Telegram.
     """
-    from telegram_bot.bot import telegram_bot
+    from integrations.telegram_bot.bot import telegram_bot
 
     token = payload.token.strip()
     if not token:
@@ -43,7 +43,7 @@ async def setup_telegram(payload: TokenPayload):
 @router.get("/status")
 async def telegram_status():
     """Return the current state of the Telegram bot."""
-    from telegram_bot.bot import telegram_bot
+    from integrations.telegram_bot.bot import telegram_bot
 
     return {
         "running": telegram_bot.is_running,
diff --git a/src/dashboard/routes/upgrades.py b/src/dashboard/routes/upgrades.py
index e4bc88b2..4065c17e 100644
--- a/src/dashboard/routes/upgrades.py
+++ b/src/dashboard/routes/upgrades.py
@@ -6,8 +6,8 @@ from fastapi import APIRouter, Form, HTTPException, Request
 from fastapi.responses import HTMLResponse, JSONResponse
 from fastapi.templating import Jinja2Templates
 
-from upgrades.models import list_upgrades, get_upgrade, UpgradeStatus, get_pending_count
-from upgrades.queue import UpgradeQueue
+from self_coding.upgrades.models import list_upgrades, get_upgrade, UpgradeStatus, get_pending_count
+from self_coding.upgrades.queue import UpgradeQueue
 
 router = APIRouter(prefix="/self-modify", tags=["upgrades"])
 templates = Jinja2Templates(directory=str(Path(__file__).parent.parent / "templates"))
diff --git a/src/dashboard/routes/voice.py b/src/dashboard/routes/voice.py
index 35da0ae0..d7ee407b 100644
--- a/src/dashboard/routes/voice.py
+++ b/src/dashboard/routes/voice.py
@@ -1,12 +1,17 @@
-"""Voice routes — /voice/* endpoints.
+"""Voice routes — /voice/* and /voice/enhanced/* endpoints.
 
-Provides NLU intent detection and TTS control endpoints for the
-voice interface.
+Provides NLU intent detection, TTS control, and the full voice-to-action
+pipeline (detect intent → execute → optionally speak).
 """
 
+import logging
+
 from fastapi import APIRouter, Form
 
-from voice.nlu import detect_intent, extract_command
+from integrations.voice.nlu import detect_intent, extract_command
+from timmy.agent import create_timmy
+
+logger = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/voice", tags=["voice"])
 
@@ -49,3 +54,103 @@ async def tts_speak(text: str = Form(...)):
         return {"spoken": True, "text": text}
     except Exception as exc:
         return {"spoken": False, "reason": str(exc)}
+
+
+# ── Enhanced voice pipeline ──────────────────────────────────────────────
+
+@router.post("/enhanced/process")
+async def process_voice_input(
+    text: str = Form(...),
+    speak_response: bool = Form(False),
+):
+    """Process a voice input: detect intent -> execute -> optionally speak.
+
+    This is the main entry point for voice-driven interaction with Timmy.
+    """
+    intent = detect_intent(text)
+    response_text = None
+    error = None
+
+    try:
+        if intent.name == "status":
+            response_text = "Timmy is operational and running locally. All systems sovereign."
+
+        elif intent.name == "help":
+            response_text = (
+                "Available commands: chat with me, check status, "
+                "manage the swarm, create tasks, or adjust voice settings. "
+                "Everything runs locally — no cloud, no permission needed."
+            )
+
+        elif intent.name == "swarm":
+            from swarm.coordinator import coordinator
+            status = coordinator.status()
+            response_text = (
+                f"Swarm status: {status['agents']} agents registered, "
+                f"{status['agents_idle']} idle, {status['agents_busy']} busy. "
+                f"{status['tasks_total']} total tasks, "
+                f"{status['tasks_completed']} completed."
+            )
+
+        elif intent.name == "voice":
+            response_text = "Voice settings acknowledged. TTS is available for spoken responses."
+
+        elif intent.name == "code":
+            from config import settings as app_settings
+            if not app_settings.self_modify_enabled:
+                response_text = (
+                    "Self-modification is disabled. "
+                    "Set SELF_MODIFY_ENABLED=true to enable."
+                )
+            else:
+                import asyncio
+                from self_coding.self_modify.loop import SelfModifyLoop, ModifyRequest
+
+                target_files = []
+                if "target_file" in intent.entities:
+                    target_files = [intent.entities["target_file"]]
+
+                loop = SelfModifyLoop()
+                request = ModifyRequest(
+                    instruction=text,
+                    target_files=target_files,
+                )
+                result = await asyncio.to_thread(loop.run, request)
+
+                if result.success:
+                    sha_short = result.commit_sha[:8] if result.commit_sha else "none"
+                    response_text = (
+                        f"Code modification complete. "
+                        f"Changed {len(result.files_changed)} file(s). "
+                        f"Tests passed. Committed as {sha_short} "
+                        f"on branch {result.branch_name}."
+                    )
+                else:
+                    response_text = f"Code modification failed: {result.error}"
+
+        else:
+            # Default: chat with Timmy
+            agent = create_timmy()
+            run = agent.run(text, stream=False)
+            response_text = run.content if hasattr(run, "content") else str(run)
+
+    except Exception as exc:
+        error = f"Processing failed: {exc}"
+        logger.error("Voice processing error: %s", exc)
+
+    # Optionally speak the response
+    if speak_response and response_text:
+        try:
+            from timmy_serve.voice_tts import voice_tts
+            if voice_tts.available:
+                voice_tts.speak(response_text)
+        except Exception:
+            pass
+
+    return {
+        "intent": intent.name,
+        "confidence": intent.confidence,
+        "response": response_text,
+        "error": error,
+        "spoken": speak_response and response_text is not None,
+    }
diff --git a/src/dashboard/routes/voice_enhanced.py b/src/dashboard/routes/voice_enhanced.py
deleted file mode 100644
index 8a17ec01..00000000
--- a/src/dashboard/routes/voice_enhanced.py
+++ /dev/null
@@ -1,116 +0,0 @@
-"""Enhanced voice routes — /voice/enhanced/* endpoints.
-
-Combines NLU intent detection with Timmy agent execution to provide
-a complete voice-to-action pipeline.  Detects the intent, routes to
-the appropriate handler, and optionally speaks the response.
-"""
-
-import logging
-from typing import Optional
-
-from fastapi import APIRouter, Form
-
-from voice.nlu import detect_intent
-from timmy.agent import create_timmy
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(prefix="/voice/enhanced", tags=["voice-enhanced"])
-
-
-@router.post("/process")
-async def process_voice_input(
-    text: str = Form(...),
-    speak_response: bool = Form(False),
-):
-    """Process a voice input: detect intent → execute → optionally speak.
-
-    This is the main entry point for voice-driven interaction with Timmy.
-    """
-    intent = detect_intent(text)
-    response_text = None
-    error = None
-
-    try:
-        if intent.name == "status":
-            response_text = "Timmy is operational and running locally. All systems sovereign."
-
-        elif intent.name == "help":
-            response_text = (
-                "Available commands: chat with me, check status, "
-                "manage the swarm, create tasks, or adjust voice settings. "
-                "Everything runs locally — no cloud, no permission needed."
-            )
-
-        elif intent.name == "swarm":
-            from swarm.coordinator import coordinator
-            status = coordinator.status()
-            response_text = (
-                f"Swarm status: {status['agents']} agents registered, "
-                f"{status['agents_idle']} idle, {status['agents_busy']} busy. "
-                f"{status['tasks_total']} total tasks, "
-                f"{status['tasks_completed']} completed."
-            )
-
-        elif intent.name == "voice":
-            response_text = "Voice settings acknowledged. TTS is available for spoken responses."
-
-        elif intent.name == "code":
-            from config import settings as app_settings
-            if not app_settings.self_modify_enabled:
-                response_text = (
-                    "Self-modification is disabled. "
-                    "Set SELF_MODIFY_ENABLED=true to enable."
-                )
-            else:
-                import asyncio
-                from self_modify.loop import SelfModifyLoop, ModifyRequest
-
-                target_files = []
-                if "target_file" in intent.entities:
-                    target_files = [intent.entities["target_file"]]
-
-                loop = SelfModifyLoop()
-                request = ModifyRequest(
-                    instruction=text,
-                    target_files=target_files,
-                )
-                result = await asyncio.to_thread(loop.run, request)
-
-                if result.success:
-                    sha_short = result.commit_sha[:8] if result.commit_sha else "none"
-                    response_text = (
-                        f"Code modification complete. "
-                        f"Changed {len(result.files_changed)} file(s). "
-                        f"Tests passed. Committed as {sha_short} "
-                        f"on branch {result.branch_name}."
-                    )
-                else:
-                    response_text = f"Code modification failed: {result.error}"
-
-        else:
-            # Default: chat with Timmy
-            agent = create_timmy()
-            run = agent.run(text, stream=False)
-            response_text = run.content if hasattr(run, "content") else str(run)
-
-    except Exception as exc:
-        error = f"Processing failed: {exc}"
-        logger.error("Voice processing error: %s", exc)
-
-    # Optionally speak the response
-    if speak_response and response_text:
-        try:
-            from timmy_serve.voice_tts import voice_tts
-            if voice_tts.available:
-                voice_tts.speak(response_text)
-        except Exception:
-            pass
-
-    return {
-        "intent": intent.name,
-        "confidence": intent.confidence,
-        "response": response_text,
-        "error": error,
-        "spoken": speak_response and response_text is not None,
-    }
diff --git a/src/dashboard/routes/work_orders.py b/src/dashboard/routes/work_orders.py
index 80b5a6b9..860cab1e 100644
--- a/src/dashboard/routes/work_orders.py
+++ b/src/dashboard/routes/work_orders.py
@@ -8,7 +8,7 @@ from fastapi import APIRouter, Form, HTTPException, Request
 from fastapi.responses import HTMLResponse, JSONResponse
 from fastapi.templating import Jinja2Templates
 
-from work_orders.models import (
+from swarm.work_orders.models import (
     WorkOrder,
     WorkOrderCategory,
     WorkOrderPriority,
@@ -20,7 +20,7 @@ from work_orders.models import (
     list_work_orders,
     update_work_order_status,
 )
-from work_orders.risk import compute_risk_score, should_auto_execute
+from swarm.work_orders.risk import compute_risk_score, should_auto_execute
 
 logger = logging.getLogger(__name__)
 
@@ -68,7 +68,7 @@ async def submit_work_order(
 
     # Notify
     try:
-        from notifications.push import notifier
+        from infrastructure.notifications.push import notifier
         notifier.notify(
             title="New Work Order",
             message=f"{wo.submitter} submitted: {wo.title}",
@@ -116,7 +116,7 @@ async def submit_work_order_json(request: Request):
     )
 
     try:
-        from notifications.push import notifier
+        from infrastructure.notifications.push import notifier
         notifier.notify(
             title="New Work Order",
             message=f"{wo.submitter} submitted: {wo.title}",
@@ -315,7 +315,7 @@ async def execute_order(wo_id: str):
     update_work_order_status(wo_id, WorkOrderStatus.IN_PROGRESS)
 
     try:
-        from work_orders.executor import work_order_executor
+        from swarm.work_orders.executor import work_order_executor
         success, result = work_order_executor.execute(wo)
         if success:
             update_work_order_status(wo_id, WorkOrderStatus.COMPLETED, result=result)
diff --git a/src/dashboard/templates/base.html b/src/dashboard/templates/base.html
index d96b7b77..a0973599 100644
--- a/src/dashboard/templates/base.html
+++ b/src/dashboard/templates/base.html
@@ -39,12 +39,14 @@
       <a href="/lightning/ledger" class="mc-test-link">LEDGER</a>
       <a href="/memory" class="mc-test-link">MEMORY</a>
       <a href="/router/status" class="mc-test-link">ROUTER</a>
+      <a href="/grok/status" class="mc-test-link" style="color:#00ff88;">GROK</a>
       <a href="/self-modify/queue" class="mc-test-link">UPGRADES</a>
       <a href="/self-coding" class="mc-test-link">SELF-CODING</a>
       <a href="/hands" class="mc-test-link">HANDS</a>
       <a href="/work-orders/queue" class="mc-test-link">WORK ORDERS</a>
       <a href="/creative/ui" class="mc-test-link">CREATIVE</a>
       <a href="/mobile" class="mc-test-link" title="Mobile-optimized view">MOBILE</a>
+      <a href="/mobile/local" class="mc-test-link" title="Local AI on iPhone">LOCAL AI</a>
       <button id="enable-notifications" class="mc-test-link" style="background:none;cursor:pointer;" title="Enable notifications">&#x1F514;</button>
       <span class="mc-time" id="clock"></span>
     </div>
@@ -78,6 +80,7 @@
     <a href="/creative/ui" class="mc-mobile-link">CREATIVE</a>
     <a href="/voice/button" class="mc-mobile-link">VOICE</a>
     <a href="/mobile" class="mc-mobile-link">MOBILE</a>
+    <a href="/mobile/local" class="mc-mobile-link">LOCAL AI</a>
     <div class="mc-mobile-menu-footer">
       <button id="enable-notifications-mobile" class="mc-mobile-link" style="background:none;border:none;cursor:pointer;width:100%;text-align:left;font:inherit;color:inherit;padding:inherit;">&#x1F514; NOTIFICATIONS</button>
     </div>
diff --git a/src/dashboard/templates/mission_control.html b/src/dashboard/templates/mission_control.html
index 2f9bbe80..c1bad5ed 100644
--- a/src/dashboard/templates/mission_control.html
+++ b/src/dashboard/templates/mission_control.html
@@ -59,10 +59,61 @@
     </div>
 </div>
 
+<!-- Grok Mode Toggle -->
+<div class="card" style="margin-top: 24px;">
+    <div class="card-header">
+        <h2 class="card-title">Grok Mode</h2>
+        <div>
+            <span class="badge" id="grok-badge" style="background: #666;">STANDBY</span>
+        </div>
+    </div>
+    <div id="grok-toggle-card"
+         hx-get="/grok/status"
+         hx-trigger="load"
+         hx-target="#grok-toggle-card"
+         hx-swap="innerHTML">
+        <div style="border: 2px solid #666; border-radius: 12px; padding: 16px;
+                    background: var(--bg-secondary);">
+            <div style="display: flex; justify-content: space-between; align-items: center;">
+                <div>
+                    <div style="font-weight: 700; font-size: 1.1rem; color: #666;">
+                        GROK MODE: LOADING...
+                    </div>
+                    <div style="font-size: 0.8rem; color: var(--text-muted); margin-top: 4px;">
+                        xAI frontier reasoning augmentation
+                    </div>
+                </div>
+                <button hx-post="/grok/toggle"
+                        hx-target="#grok-toggle-card"
+                        hx-swap="outerHTML"
+                        style="background: #666; color: #000; border: none;
+                               border-radius: 8px; padding: 8px 20px; cursor: pointer;
+                               font-weight: 700; font-family: inherit;">
+                    ACTIVATE
+                </button>
+            </div>
+        </div>
+    </div>
+    <div class="grid grid-3" style="margin-top: 12px;">
+        <div class="stat">
+            <div class="stat-value" id="grok-requests">0</div>
+            <div class="stat-label">Grok Queries</div>
+        </div>
+        <div class="stat">
+            <div class="stat-value" id="grok-tokens">0</div>
+            <div class="stat-label">Tokens Used</div>
+        </div>
+        <div class="stat">
+            <div class="stat-value" id="grok-cost">0</div>
+            <div class="stat-label">Est. Cost (sats)</div>
+        </div>
+    </div>
+</div>
+
 <!-- Heartbeat Monitor -->
 <div class="card" style="margin-top: 24px;">
     <div class="card-header">
-        <h2 class="card-title">💓 Heartbeat Monitor</h2>
+        <h2 class="card-title">Heartbeat Monitor</h2>
         <div>
             <span class="badge" id="heartbeat-status">Checking...</span>
         </div>
@@ -318,11 +369,40 @@ async function loadChatHistory() {
     }
 }
 
+// Load Grok stats
+async function loadGrokStats() {
+    try {
+        const response = await fetch('/grok/status');
+        const data = await response.json();
+
+        if (data.stats) {
+            document.getElementById('grok-requests').textContent = data.stats.total_requests || 0;
+            document.getElementById('grok-tokens').textContent =
+                (data.stats.total_prompt_tokens || 0) + (data.stats.total_completion_tokens || 0);
+            document.getElementById('grok-cost').textContent = data.stats.estimated_cost_sats || 0;
+        }
+
+        const badge = document.getElementById('grok-badge');
+        if (data.active) {
+            badge.textContent = 'ACTIVE';
+            badge.style.background = '#00ff88';
+            badge.style.color = '#000';
+        } else {
+            badge.textContent = 'STANDBY';
+            badge.style.background = '#666';
+            badge.style.color = '#fff';
+        }
+    } catch (error) {
+        // Grok endpoint may not respond — silent fallback
+    }
+}
+
 // Initial load
 loadSovereignty();
 loadHealth();
 loadSwarmStats();
 loadLightningStats();
+loadGrokStats();
 loadChatHistory();
 
 // Periodic updates
@@ -330,5 +410,6 @@ setInterval(loadSovereignty, 30000);  // Every 30s
 setInterval(loadHealth, 10000);       // Every 10s
 setInterval(loadSwarmStats, 5000);    // Every 5s
 setInterval(updateHeartbeat, 5000);   // Heartbeat every 5s
+setInterval(loadGrokStats, 10000);   // Grok stats every 10s
 </script>
 {% endblock %}
diff --git a/src/dashboard/templates/mobile_local.html b/src/dashboard/templates/mobile_local.html
new file mode 100644
index 00000000..b74b24af
--- /dev/null
+++ b/src/dashboard/templates/mobile_local.html
@@ -0,0 +1,546 @@
+{% extends "base.html" %}
+
+{% block title %}{{ page_title }}{% endblock %}
+
+{% block extra_styles %}
+<style>
+  .local-wrap {
+    display: flex;
+    flex-direction: column;
+    gap: 12px;
+    padding-bottom: 20px;
+    max-width: 600px;
+    margin: 0 auto;
+  }
+
+  /* ── Model status panel ────────────────────────────────────── */
+  .model-status {
+    padding: 14px;
+    display: flex;
+    flex-direction: column;
+    gap: 10px;
+  }
+  .model-status-row {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    font-size: 11px;
+    letter-spacing: 0.08em;
+  }
+  .model-status-label { color: var(--text-dim); }
+  .model-status-value { color: var(--text-bright); font-weight: 600; }
+  .model-status-value.ready { color: #4ade80; }
+  .model-status-value.loading { color: #facc15; }
+  .model-status-value.error { color: #f87171; }
+  .model-status-value.offline { color: var(--text-dim); }
+
+  /* ── Progress bar ──────────────────────────────────────────── */
+  .progress-wrap {
+    display: none;
+    flex-direction: column;
+    gap: 6px;
+    padding: 0 14px 14px;
+  }
+  .progress-wrap.active { display: flex; }
+  .progress-bar-outer {
+    height: 6px;
+    background: rgba(8, 4, 18, 0.75);
+    border-radius: 3px;
+    overflow: hidden;
+  }
+  .progress-bar-inner {
+    height: 100%;
+    width: 0%;
+    background: linear-gradient(90deg, var(--border-glow), #a78bfa);
+    border-radius: 3px;
+    transition: width 0.3s;
+  }
+  .progress-text {
+    font-size: 10px;
+    color: var(--text-dim);
+    letter-spacing: 0.06em;
+    min-height: 14px;
+  }
+
+  /* ── Model selector ────────────────────────────────────────── */
+  .model-select-wrap {
+    padding: 0 14px 14px;
+  }
+  .model-select {
+    width: 100%;
+    background: rgba(8, 4, 18, 0.75);
+    border: 1px solid var(--border);
+    border-radius: var(--radius-md);
+    color: var(--text-bright);
+    font-family: var(--font);
+    font-size: 13px;
+    padding: 10px 12px;
+    min-height: 44px;
+    appearance: none;
+    -webkit-appearance: none;
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' fill='%237c7c8a' viewBox='0 0 16 16'%3E%3Cpath d='M8 11L3 6h10z'/%3E%3C/svg%3E");
+    background-repeat: no-repeat;
+    background-position: right 12px center;
+    touch-action: manipulation;
+  }
+  .model-select:focus {
+    outline: none;
+    border-color: var(--border-glow);
+  }
+
+  /* ── Action buttons ────────────────────────────────────────── */
+  .model-actions {
+    display: flex;
+    gap: 8px;
+    padding: 0 14px 14px;
+  }
+  .model-btn {
+    flex: 1;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 6px;
+    min-height: 44px;
+    border-radius: var(--radius-md);
+    font-family: var(--font);
+    font-size: 12px;
+    font-weight: 700;
+    letter-spacing: 0.08em;
+    border: 1px solid var(--border);
+    background: rgba(24, 10, 45, 0.6);
+    color: var(--text-bright);
+    cursor: pointer;
+    transition: transform 0.1s, border-color 0.2s;
+    touch-action: manipulation;
+    -webkit-tap-highlight-color: transparent;
+  }
+  .model-btn:active { transform: scale(0.96); }
+  .model-btn.primary {
+    border-color: var(--border-glow);
+    background: rgba(124, 58, 237, 0.2);
+  }
+  .model-btn:disabled {
+    opacity: 0.4;
+    cursor: not-allowed;
+  }
+
+  /* ── Chat area ─────────────────────────────────────────────── */
+  .local-chat-wrap {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+  }
+  .local-chat-log {
+    flex: 1;
+    overflow-y: auto;
+    -webkit-overflow-scrolling: touch;
+    padding: 14px;
+    max-height: 400px;
+    min-height: 200px;
+  }
+  .local-chat-input {
+    display: flex;
+    gap: 8px;
+    padding: 10px 14px;
+    padding-bottom: max(10px, env(safe-area-inset-bottom));
+    background: rgba(24, 10, 45, 0.9);
+    border-top: 1px solid var(--border);
+  }
+  .local-chat-input input {
+    flex: 1;
+    background: rgba(8, 4, 18, 0.75);
+    border: 1px solid var(--border);
+    border-radius: var(--radius-md);
+    color: var(--text-bright);
+    font-family: var(--font);
+    font-size: 16px;
+    padding: 10px 12px;
+    min-height: 44px;
+  }
+  .local-chat-input input:focus {
+    outline: none;
+    border-color: var(--border-glow);
+    box-shadow: 0 0 0 1px var(--border-glow), 0 0 8px rgba(124, 58, 237, 0.2);
+  }
+  .local-chat-input input::placeholder { color: var(--text-dim); }
+  .local-chat-input button {
+    background: var(--border-glow);
+    border: none;
+    border-radius: var(--radius-md);
+    color: var(--text-bright);
+    font-family: var(--font);
+    font-size: 12px;
+    font-weight: 700;
+    padding: 0 16px;
+    min-height: 44px;
+    min-width: 64px;
+    letter-spacing: 0.1em;
+    transition: background 0.15s, transform 0.1s;
+    touch-action: manipulation;
+  }
+  .local-chat-input button:active { transform: scale(0.96); }
+  .local-chat-input button:disabled { opacity: 0.4; }
+
+  /* ── Chat messages ─────────────────────────────────────────── */
+  .local-msg { margin-bottom: 12px; }
+  .local-msg .meta {
+    font-size: 10px;
+    letter-spacing: 0.1em;
+    margin-bottom: 3px;
+  }
+  .local-msg.user .meta { color: var(--orange); }
+  .local-msg.timmy .meta { color: var(--purple); }
+  .local-msg.system .meta { color: var(--text-dim); }
+  .local-msg .bubble {
+    background: rgba(24, 10, 45, 0.8);
+    border: 1px solid var(--border);
+    border-radius: var(--radius-md);
+    padding: 10px 12px;
+    font-size: 13px;
+    line-height: 1.6;
+    color: var(--text);
+    word-break: break-word;
+  }
+  .local-msg.timmy .bubble { border-left: 3px solid var(--purple); }
+  .local-msg.user .bubble { border-color: var(--border-glow); }
+  .local-msg.system .bubble {
+    border-color: transparent;
+    background: rgba(8, 4, 18, 0.5);
+    font-size: 11px;
+    color: var(--text-dim);
+  }
+
+  /* ── Backend badge ─────────────────────────────────────────── */
+  .backend-badge {
+    display: inline-block;
+    font-size: 9px;
+    letter-spacing: 0.1em;
+    padding: 2px 6px;
+    border-radius: 3px;
+    vertical-align: middle;
+    margin-left: 6px;
+  }
+  .backend-badge.local {
+    background: rgba(74, 222, 128, 0.15);
+    color: #4ade80;
+    border: 1px solid rgba(74, 222, 128, 0.3);
+  }
+  .backend-badge.server {
+    background: rgba(250, 204, 21, 0.15);
+    color: #facc15;
+    border: 1px solid rgba(250, 204, 21, 0.3);
+  }
+
+  /* ── Stats panel ───────────────────────────────────────────── */
+  .model-stats {
+    padding: 0 14px 14px;
+    font-size: 10px;
+    color: var(--text-dim);
+    letter-spacing: 0.06em;
+    display: none;
+  }
+  .model-stats.visible { display: block; }
+</style>
+{% endblock %}
+
+{% block content %}
+<div class="local-wrap">
+
+  <!-- Model Status Panel -->
+  <div class="card mc-panel">
+    <div class="card-header mc-panel-header">// LOCAL AI MODEL</div>
+    <div class="model-status">
+      <div class="model-status-row">
+        <span class="model-status-label">STATUS</span>
+        <span class="model-status-value offline" id="model-state">NOT LOADED</span>
+      </div>
+      <div class="model-status-row">
+        <span class="model-status-label">BACKEND</span>
+        <span class="model-status-value" id="model-backend">DETECTING...</span>
+      </div>
+      <div class="model-status-row">
+        <span class="model-status-label">INFERENCE</span>
+        <span class="model-status-value" id="inference-mode">--</span>
+      </div>
+    </div>
+
+    <!-- Model selector -->
+    <div class="model-select-wrap">
+      <select class="model-select" id="model-select" aria-label="Select model"></select>
+    </div>
+
+    <!-- Progress bar -->
+    <div class="progress-wrap" id="progress-wrap">
+      <div class="progress-bar-outer">
+        <div class="progress-bar-inner" id="progress-bar"></div>
+      </div>
+      <div class="progress-text" id="progress-text"></div>
+    </div>
+
+    <!-- Actions -->
+    <div class="model-actions">
+      <button class="model-btn primary" id="btn-load" onclick="loadModel()">LOAD MODEL</button>
+      <button class="model-btn" id="btn-unload" onclick="unloadModel()" disabled>UNLOAD</button>
+    </div>
+
+    <!-- Stats -->
+    <div class="model-stats" id="model-stats"></div>
+  </div>
+
+  <!-- Chat -->
+  <div class="card mc-panel local-chat-wrap">
+    <div class="card-header mc-panel-header">
+      // TIMMY <span class="backend-badge local" id="chat-backend-badge" style="display:none">LOCAL</span>
+    </div>
+    <div class="local-chat-log" id="local-chat">
+      <div class="local-msg system">
+        <div class="meta">SYSTEM</div>
+        <div class="bubble">
+          Load a model above to chat with Timmy locally on your device.
+          No server connection required.
+          {% if browser_model_fallback %}
+          Server fallback is enabled — if the local model fails, Timmy
+          will try the server instead.
+          {% endif %}
+        </div>
+      </div>
+    </div>
+    <form onsubmit="sendLocalMessage(event)" class="local-chat-input">
+      <input type="text"
+             id="local-message"
+             placeholder="Message Timmy..."
+             required
+             autocomplete="off"
+             autocapitalize="none"
+             autocorrect="off"
+             spellcheck="false"
+             enterkeyhint="send" />
+      <button type="submit" id="btn-send" disabled>SEND</button>
+    </form>
+  </div>
+
+</div>
+
+<script src="/static/local_llm.js"></script>
+<script>
+// ── State ──────────────────────────────────────────────────────────────────
+let llm = null;
+const serverFallback = {{ browser_model_fallback | tojson }};
+const defaultModelId = {{ browser_model_id | tojson }};
+
+// ── DOM refs ───────────────────────────────────────────────────────────────
+const elState      = document.getElementById('model-state');
+const elBackend    = document.getElementById('model-backend');
+const elInference  = document.getElementById('inference-mode');
+const elSelect     = document.getElementById('model-select');
+const elProgress   = document.getElementById('progress-wrap');
+const elBar        = document.getElementById('progress-bar');
+const elProgressTx = document.getElementById('progress-text');
+const elBtnLoad    = document.getElementById('btn-load');
+const elBtnUnload  = document.getElementById('btn-unload');
+const elBtnSend    = document.getElementById('btn-send');
+const elChat       = document.getElementById('local-chat');
+const elInput      = document.getElementById('local-message');
+const elBadge      = document.getElementById('chat-backend-badge');
+const elStats      = document.getElementById('model-stats');
+
+// ── Populate model selector ────────────────────────────────────────────────
+(function populateModels() {
+  const catalogue = window.LOCAL_MODEL_CATALOGUE || [];
+  catalogue.forEach(function(m) {
+    const opt = document.createElement('option');
+    opt.value = m.id;
+    opt.textContent = m.label + ' (' + m.sizeHint + ')';
+    if (m.id === defaultModelId) opt.selected = true;
+    elSelect.appendChild(opt);
+  });
+})();
+
+// ── Detect capabilities ────────────────────────────────────────────────────
+(function detectCaps() {
+  const supported = LocalLLM.isSupported();
+  const hasGPU = typeof navigator !== 'undefined' && 'gpu' in navigator;
+  elBackend.textContent = hasGPU ? 'WebGPU' : supported ? 'WASM' : 'UNSUPPORTED';
+  if (!supported) {
+    elBackend.classList.add('error');
+    elBtnLoad.disabled = true;
+    addSystemMessage('Your browser does not support WebGPU or WebAssembly. Update to iOS 26+ / Safari 26+ for local AI.');
+  }
+})();
+
+// ── Load model ─────────────────────────────────────────────────────────────
+async function loadModel() {
+  if (llm && llm.ready) {
+    await unloadModel();
+  }
+
+  const modelId = elSelect.value;
+  elBtnLoad.disabled = true;
+  elBtnUnload.disabled = true;
+  elBtnSend.disabled = true;
+  elProgress.classList.add('active');
+  setState('loading', 'DOWNLOADING...');
+
+  llm = new LocalLLM({
+    modelId: modelId,
+    onProgress: function(report) {
+      if (report.progress !== undefined) {
+        const pct = Math.round(report.progress * 100);
+        elBar.style.width = pct + '%';
+        elProgressTx.textContent = report.text || (pct + '%');
+      } else if (report.text) {
+        elProgressTx.textContent = report.text;
+      }
+    },
+    onReady: function() {
+      setState('ready', 'READY');
+      elProgress.classList.remove('active');
+      elBtnLoad.disabled = false;
+      elBtnUnload.disabled = false;
+      elBtnSend.disabled = false;
+      elBadge.style.display = '';
+      elBadge.className = 'backend-badge local';
+      elBadge.textContent = 'LOCAL';
+      elInference.textContent = 'ON-DEVICE';
+      elInput.focus();
+      addSystemMessage('Model loaded. Timmy is running locally on your device — fully offline, fully sovereign.');
+      updateStats();
+    },
+    onError: function(err) {
+      setState('error', 'FAILED');
+      elProgress.classList.remove('active');
+      elBtnLoad.disabled = false;
+      addSystemMessage('Failed to load model: ' + err.message);
+      if (serverFallback) {
+        addSystemMessage('Server fallback enabled. Chat will use the server instead.');
+        elBtnSend.disabled = false;
+        elBadge.style.display = '';
+        elBadge.className = 'backend-badge server';
+        elBadge.textContent = 'SERVER';
+        elInference.textContent = 'SERVER';
+      }
+    },
+  });
+
+  try {
+    await llm.init();
+  } catch (e) {
+    // Error handled by onError callback
+  }
+}
+
+// ── Unload model ───────────────────────────────────────────────────────────
+async function unloadModel() {
+  if (llm) {
+    await llm.unload();
+    llm = null;
+  }
+  setState('offline', 'NOT LOADED');
+  elBtnUnload.disabled = true;
+  elBtnSend.disabled = true;
+  elBadge.style.display = 'none';
+  elInference.textContent = '--';
+  elStats.classList.remove('visible');
+}
+
+// ── Send message ───────────────────────────────────────────────────────────
+async function sendLocalMessage(event) {
+  event.preventDefault();
+  const message = elInput.value.trim();
+  if (!message) return;
+
+  addMessage('user', 'YOU', message);
+  elInput.value = '';
+  elBtnSend.disabled = true;
+
+  // Try local model first
+  if (llm && llm.ready) {
+    try {
+      const replyBubble = addMessage('timmy', 'TIMMY (LOCAL)', '');
+      let fullText = '';
+      await llm.chat(message, {
+        onToken: function(delta, accumulated) {
+          fullText = accumulated;
+          replyBubble.textContent = fullText;
+          elChat.scrollTop = elChat.scrollHeight;
+        }
+      });
+      if (!fullText) {
+        replyBubble.textContent = await llm.chat(message);
+      }
+      elBtnSend.disabled = false;
+      updateStats();
+      return;
+    } catch (err) {
+      addSystemMessage('Local inference failed: ' + err.message);
+      if (!serverFallback) {
+        elBtnSend.disabled = false;
+        return;
+      }
+    }
+  }
+
+  // Server fallback
+  if (serverFallback) {
+    try {
+      const response = await fetch('/agents/timmy/chat', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: 'message=' + encodeURIComponent(message)
+      });
+      const html = await response.text();
+      const parser = new DOMParser();
+      const doc = parser.parseFromString(html, 'text/html');
+      const timmyResponse = doc.querySelector('.chat-message.timmy, .msg-body');
+      const text = timmyResponse ? timmyResponse.textContent.trim() : 'Response received.';
+      addMessage('timmy', 'TIMMY (SERVER)', text);
+    } catch (e) {
+      addMessage('timmy', 'TIMMY', 'Sorry, both local and server inference failed. Check your connection.');
+    }
+  } else {
+    addMessage('system', 'SYSTEM', 'Load a model to start chatting.');
+  }
+  elBtnSend.disabled = false;
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+function setState(cls, text) {
+  elState.className = 'model-status-value ' + cls;
+  elState.textContent = text;
+}
+
+function addMessage(type, label, text) {
+  const div = document.createElement('div');
+  div.className = 'local-msg ' + type;
+  const meta = document.createElement('div');
+  meta.className = 'meta';
+  meta.textContent = label;
+  const bubble = document.createElement('div');
+  bubble.className = 'bubble';
+  bubble.textContent = text;
+  div.appendChild(meta);
+  div.appendChild(bubble);
+  elChat.appendChild(div);
+  elChat.scrollTop = elChat.scrollHeight;
+  return bubble;
+}
+
+function addSystemMessage(text) {
+  addMessage('system', 'SYSTEM', text);
+}
+
+async function updateStats() {
+  if (!llm) return;
+  try {
+    const stats = await llm.getStats();
+    if (stats) {
+      elStats.textContent = stats;
+      elStats.classList.add('visible');
+    }
+  } catch (e) {
+    // Stats are optional
+  }
+}
+</script>
+{% endblock %}
diff --git a/src/dashboard/templates/mobile_test.html b/src/dashboard/templates/mobile_test.html
deleted file mode 100644
index c6d31cca..00000000
--- a/src/dashboard/templates/mobile_test.html
+++ /dev/null
@@ -1,422 +0,0 @@
-{% extends "base.html" %}
-{% block title %}Mobile Test — Timmy Time{% endblock %}
-
-{% block content %}
-<div class="container-fluid mc-content" style="height:auto; overflow:visible;">
-
-  <!-- ── Page header ─────────────────────────────────────────────────── -->
-  <div class="mt-hitl-header">
-    <div>
-      <span class="mt-title">// MOBILE TEST SUITE</span>
-      <span class="mt-sub">HUMAN-IN-THE-LOOP</span>
-    </div>
-    <div class="mt-score-wrap">
-      <span class="mt-score" id="score-display">0 / {{ total }}</span>
-      <span class="mt-score-label">PASSED</span>
-    </div>
-  </div>
-
-  <!-- ── Progress bar ────────────────────────────────────────────────── -->
-  <div class="mt-progress-wrap">
-    <div class="progress" style="height:6px; background:var(--bg-card); border-radius:3px;">
-      <div class="progress-bar mt-progress-bar"
-           id="progress-bar"
-           role="progressbar"
-           style="width:0%; background:var(--green);"
-           aria-valuenow="0" aria-valuemin="0" aria-valuemax="{{ total }}"></div>
-    </div>
-    <div class="mt-progress-legend">
-      <span><span class="mt-dot green"></span>PASS</span>
-      <span><span class="mt-dot red"></span>FAIL</span>
-      <span><span class="mt-dot amber"></span>SKIP</span>
-      <span><span class="mt-dot" style="background:var(--text-dim);box-shadow:none;"></span>PENDING</span>
-    </div>
-  </div>
-
-  <!-- ── Reset / Back ────────────────────────────────────────────────── -->
-  <div class="mt-actions">
-    <a href="/" class="mc-btn-clear">← MISSION CONTROL</a>
-    <button class="mc-btn-clear" onclick="resetAll()" style="border-color:var(--red);color:var(--red);">RESET ALL</button>
-  </div>
-
-  <!-- ── Scenario cards ──────────────────────────────────────────────── -->
-  {% for category, items in categories.items() %}
-  <div class="mt-category-label">{{ category | upper }}</div>
-
-  {% for s in items %}
-  <div class="card mc-panel mt-card" id="card-{{ s.id }}" data-scenario="{{ s.id }}">
-    <div class="card-header mc-panel-header d-flex justify-content-between align-items-center">
-      <div>
-        <span class="mt-id-badge" id="badge-{{ s.id }}">{{ s.id }}</span>
-        <span class="mt-scenario-title">{{ s.title }}</span>
-      </div>
-      <span class="mt-state-chip" id="chip-{{ s.id }}">PENDING</span>
-    </div>
-    <div class="card-body p-3">
-
-      <div class="mt-steps-label">STEPS</div>
-      <ol class="mt-steps">
-        {% for step in s.steps %}
-        <li>{{ step }}</li>
-        {% endfor %}
-      </ol>
-
-      <div class="mt-expected-label">EXPECTED</div>
-      <div class="mt-expected">{{ s.expected }}</div>
-
-      <div class="mt-btn-row">
-        <button class="mt-btn mt-btn-pass" onclick="mark('{{ s.id }}', 'pass')">✓ PASS</button>
-        <button class="mt-btn mt-btn-fail" onclick="mark('{{ s.id }}', 'fail')">✗ FAIL</button>
-        <button class="mt-btn mt-btn-skip" onclick="mark('{{ s.id }}', 'skip')">— SKIP</button>
-      </div>
-
-    </div>
-  </div>
-  {% endfor %}
-  {% endfor %}
-
-  <!-- ── Summary footer ──────────────────────────────────────────────── -->
-  <div class="card mc-panel mt-summary" id="summary">
-    <div class="card-header mc-panel-header">// SUMMARY</div>
-    <div class="card-body p-3" id="summary-body">
-      <p class="mt-summary-hint">Mark all scenarios above to see your final score.</p>
-    </div>
-  </div>
-
-</div><!-- /container -->
-
-
-<!-- ── Styles (scoped to this page) ────────────────────────────────────── -->
-<style>
-  .mt-hitl-header {
-    display: flex;
-    justify-content: space-between;
-    align-items: flex-end;
-    padding: 16px 0 12px;
-    border-bottom: 1px solid var(--border);
-    margin-bottom: 12px;
-  }
-  .mt-title {
-    font-size: 14px;
-    font-weight: 700;
-    color: var(--text-bright);
-    letter-spacing: 0.18em;
-    display: block;
-  }
-  .mt-sub {
-    font-size: 10px;
-    color: var(--text-dim);
-    letter-spacing: 0.2em;
-    display: block;
-    margin-top: 2px;
-  }
-  .mt-score-wrap { text-align: right; }
-  .mt-score {
-    font-size: 22px;
-    font-weight: 700;
-    color: var(--green);
-    letter-spacing: 0.06em;
-    display: block;
-  }
-  .mt-score-label { font-size: 9px; color: var(--text-dim); letter-spacing: 0.2em; }
-
-  .mt-progress-wrap { margin-bottom: 10px; }
-  .mt-progress-legend {
-    display: flex;
-    gap: 16px;
-    font-size: 9px;
-    color: var(--text-dim);
-    letter-spacing: 0.12em;
-    margin-top: 6px;
-  }
-  .mt-dot {
-    display: inline-block;
-    width: 7px;
-    height: 7px;
-    border-radius: 50%;
-    margin-right: 4px;
-    vertical-align: middle;
-  }
-  .mt-dot.green { background: var(--green); box-shadow: 0 0 5px var(--green); }
-  .mt-dot.red   { background: var(--red);   box-shadow: 0 0 5px var(--red); }
-  .mt-dot.amber { background: var(--amber); box-shadow: 0 0 5px var(--amber); }
-
-  .mt-actions {
-    display: flex;
-    gap: 10px;
-    margin-bottom: 16px;
-  }
-
-  .mt-category-label {
-    font-size: 9px;
-    font-weight: 700;
-    color: var(--text-dim);
-    letter-spacing: 0.25em;
-    margin: 20px 0 8px;
-    padding-left: 2px;
-  }
-
-  .mt-card {
-    margin-bottom: 10px;
-    transition: border-color 0.2s;
-  }
-  .mt-card.state-pass { border-color: var(--green) !important; }
-  .mt-card.state-fail { border-color: var(--red)   !important; }
-  .mt-card.state-skip { border-color: var(--amber) !important; opacity: 0.7; }
-
-  .mt-id-badge {
-    font-size: 9px;
-    font-weight: 700;
-    background: var(--border);
-    color: var(--text-dim);
-    border-radius: 2px;
-    padding: 2px 6px;
-    letter-spacing: 0.12em;
-    margin-right: 8px;
-  }
-  .mt-card.state-pass .mt-id-badge { background: var(--green-dim); color: var(--green); }
-  .mt-card.state-fail .mt-id-badge { background: var(--red-dim);   color: var(--red); }
-  .mt-card.state-skip .mt-id-badge { background: var(--amber-dim); color: var(--amber); }
-
-  .mt-scenario-title {
-    font-size: 12px;
-    font-weight: 700;
-    color: var(--text-bright);
-    letter-spacing: 0.05em;
-  }
-
-  .mt-state-chip {
-    font-size: 9px;
-    font-weight: 700;
-    letter-spacing: 0.15em;
-    color: var(--text-dim);
-    padding: 2px 8px;
-    border: 1px solid var(--border);
-    border-radius: 2px;
-    white-space: nowrap;
-  }
-  .mt-card.state-pass .mt-state-chip { color: var(--green); border-color: var(--green); }
-  .mt-card.state-fail .mt-state-chip { color: var(--red);   border-color: var(--red); }
-  .mt-card.state-skip .mt-state-chip { color: var(--amber); border-color: var(--amber); }
-
-  .mt-steps-label, .mt-expected-label {
-    font-size: 9px;
-    font-weight: 700;
-    color: var(--text-dim);
-    letter-spacing: 0.2em;
-    margin-bottom: 6px;
-  }
-  .mt-expected-label { margin-top: 12px; }
-
-  .mt-steps {
-    padding-left: 18px;
-    margin: 0;
-    font-size: 12px;
-    line-height: 1.8;
-    color: var(--text);
-  }
-  .mt-expected {
-    font-size: 12px;
-    line-height: 1.65;
-    color: var(--text-bright);
-    background: var(--bg-card);
-    border-left: 3px solid var(--border-glow);
-    padding: 8px 12px;
-    border-radius: 0 3px 3px 0;
-  }
-
-  .mt-btn-row {
-    display: flex;
-    gap: 8px;
-    margin-top: 14px;
-  }
-  .mt-btn {
-    flex: 1;
-    min-height: 44px;
-    border: 1px solid var(--border);
-    border-radius: 3px;
-    background: var(--bg-deep);
-    color: var(--text-dim);
-    font-family: var(--font);
-    font-size: 11px;
-    font-weight: 700;
-    letter-spacing: 0.12em;
-    cursor: pointer;
-    touch-action: manipulation;
-    transition: background 0.15s, color 0.15s, border-color 0.15s;
-  }
-  .mt-btn-pass:hover, .mt-btn-pass.active { background: var(--green-dim); color: var(--green); border-color: var(--green); }
-  .mt-btn-fail:hover, .mt-btn-fail.active { background: var(--red-dim);   color: var(--red);   border-color: var(--red); }
-  .mt-btn-skip:hover, .mt-btn-skip.active { background: var(--amber-dim); color: var(--amber); border-color: var(--amber); }
-
-  .mt-summary { margin-top: 24px; margin-bottom: 32px; }
-  .mt-summary-hint { color: var(--text-dim); font-size: 12px; margin: 0; }
-
-  .mt-summary-row {
-    display: flex;
-    justify-content: space-between;
-    align-items: center;
-    padding: 8px 0;
-    border-bottom: 1px solid var(--border);
-    font-size: 12px;
-  }
-  .mt-summary-row:last-child { border-bottom: none; }
-  .mt-summary-score { font-size: 28px; font-weight: 700; color: var(--green); margin: 12px 0 4px; }
-  .mt-summary-pct   { font-size: 13px; color: var(--text-dim); }
-
-  @media (max-width: 768px) {
-    .mt-btn-row { gap: 6px; }
-    .mt-btn     { font-size: 10px; padding: 0 4px; }
-  }
-</style>
-
-
-<!-- ── HITL State Machine (sessionStorage) ─────────────────────────────── -->
-<script>
-  const TOTAL = {{ total }};
-  const KEY   = "timmy-mobile-test-results";
-
-  function loadResults() {
-    try { return JSON.parse(sessionStorage.getItem(KEY) || "{}"); }
-    catch { return {}; }
-  }
-  function saveResults(r) {
-    sessionStorage.setItem(KEY, JSON.stringify(r));
-  }
-
-  function mark(id, state) {
-    const results = loadResults();
-    results[id] = state;
-    saveResults(results);
-    applyState(id, state);
-    updateScore(results);
-    updateSummary(results);
-  }
-
-  function applyState(id, state) {
-    const card  = document.getElementById("card-" + id);
-    const chip  = document.getElementById("chip-" + id);
-    const labels = { pass: "PASS", fail: "FAIL", skip: "SKIP" };
-
-    card.classList.remove("state-pass", "state-fail", "state-skip");
-    if (state) card.classList.add("state-" + state);
-    chip.textContent = state ? labels[state] : "PENDING";
-
-    // highlight active button
-    card.querySelectorAll(".mt-btn").forEach(btn => btn.classList.remove("active"));
-    const activeBtn = card.querySelector(".mt-btn-" + state);
-    if (activeBtn) activeBtn.classList.add("active");
-  }
-
-  function updateScore(results) {
-    const passed  = Object.values(results).filter(v => v === "pass").length;
-    const decided = Object.values(results).filter(v => v !== undefined).length;
-    document.getElementById("score-display").textContent = passed + " / " + TOTAL;
-
-    const pct = TOTAL ? (decided / TOTAL) * 100 : 0;
-    const bar = document.getElementById("progress-bar");
-    bar.style.width = pct + "%";
-
-    // colour the bar by overall health
-    const failCount = Object.values(results).filter(v => v === "fail").length;
-    bar.style.background = failCount > 0
-      ? "var(--red)"
-      : passed === TOTAL ? "var(--green)" : "var(--amber)";
-  }
-
-  function updateSummary(results) {
-    const passed  = Object.values(results).filter(v => v === "pass").length;
-    const failed  = Object.values(results).filter(v => v === "fail").length;
-    const skipped = Object.values(results).filter(v => v === "skip").length;
-    const decided = passed + failed + skipped;
-    const summaryBody = document.getElementById("summary-body");
-
-    if (decided < TOTAL) {
-      summaryBody.innerHTML = '';
-      const p = document.createElement('p');
-      p.className = 'mt-summary-hint';
-      p.textContent = (TOTAL - decided) + ' scenario(s) still pending.';
-      summaryBody.appendChild(p);
-      return;
-    }
-
-    const pct   = TOTAL ? Math.round((passed / TOTAL) * 100) : 0;
-    const color = failed > 0 ? "var(--red)" : "var(--green)";
-    
-    // Safely build summary UI using DOM API to avoid XSS from potentially untrusted variables
-    summaryBody.innerHTML = '';
-    
-    const scoreDiv = document.createElement('div');
-    scoreDiv.className = 'mt-summary-score';
-    scoreDiv.style.color = color;
-    scoreDiv.textContent = passed + ' / ' + TOTAL;
-    summaryBody.appendChild(scoreDiv);
-    
-    const pctDiv = document.createElement('div');
-    pctDiv.className = 'mt-summary-pct';
-    pctDiv.textContent = pct + '% pass rate';
-    summaryBody.appendChild(pctDiv);
-    
-    const statsContainer = document.createElement('div');
-    statsContainer.style.marginTop = '16px';
-    
-    const createRow = (label, value, colorVar) => {
-      const row = document.createElement('div');
-      row.className = 'mt-summary-row';
-      const labelSpan = document.createElement('span');
-      labelSpan.textContent = label;
-      const valSpan = document.createElement('span');
-      valSpan.style.color = 'var(--' + colorVar + ')';
-      valSpan.style.fontWeight = '700';
-      valSpan.textContent = value;
-      row.appendChild(labelSpan);
-      row.appendChild(valSpan);
-      return row;
-    };
-    
-    statsContainer.appendChild(createRow('PASSED', passed, 'green'));
-    statsContainer.appendChild(createRow('FAILED', failed, 'red'));
-    statsContainer.appendChild(createRow('SKIPPED', skipped, 'amber'));
-    summaryBody.appendChild(statsContainer);
-    
-    const statusMsg = document.createElement('p');
-    statusMsg.style.marginTop = '12px';
-    statusMsg.style.fontSize = '11px';
-    if (failed > 0) {
-      statusMsg.style.color = 'var(--red)';
-      statusMsg.textContent = '⚠ ' + failed + ' failure(s) need attention before release.';
-    } else {
-      statusMsg.style.color = 'var(--green)';
-      statusMsg.textContent = 'All tested scenarios passed — ship it.';
-    }
-    summaryBody.appendChild(statusMsg);
-  }
-
-  function resetAll() {
-    if (!confirm("Reset all test results?")) return;
-    sessionStorage.removeItem(KEY);
-    const results = {};
-    document.querySelectorAll("[data-scenario]").forEach(card => {
-      const id = card.dataset.scenario;
-      applyState(id, null);
-    });
-    updateScore(results);
-    
-    const summaryBody = document.getElementById("summary-body");
-    summaryBody.innerHTML = '';
-    const p = document.createElement('p');
-    p.className = 'mt-summary-hint';
-    p.textContent = 'Mark all scenarios above to see your final score.';
-    summaryBody.appendChild(p);
-  }
-
-  // Restore saved state on load
-  (function init() {
-    const results = loadResults();
-    Object.entries(results).forEach(([id, state]) => applyState(id, state));
-    updateScore(results);
-    updateSummary(results);
-  })();
-</script>
-
-{% endblock %}
diff --git a/src/dashboard/templates/models.html b/src/dashboard/templates/models.html
new file mode 100644
index 00000000..47ccea3b
--- /dev/null
+++ b/src/dashboard/templates/models.html
@@ -0,0 +1,119 @@
+{% extends "base.html" %}
+
+{% block title %}Custom Models - Timmy Time{% endblock %}
+
+{% block content %}
+<div class="mc-panel">
+  <div class="mc-panel-header">
+    <h1 class="page-title">Custom Models</h1>
+    <p class="mc-text-secondary">Manage model weights and agent assignments</p>
+  </div>
+
+  <!-- Stats -->
+  <div class="mc-stats-row">
+    <div class="mc-stat-card">
+      <div class="mc-stat-value">{{ models|length }}</div>
+      <div class="mc-stat-label">Models</div>
+    </div>
+    <div class="mc-stat-card">
+      <div class="mc-stat-value">{{ assignments|length }}</div>
+      <div class="mc-stat-label">Assignments</div>
+    </div>
+    <div class="mc-stat-card">
+      <div class="mc-stat-value">{{ "Yes" if reward_model else "No" }}</div>
+      <div class="mc-stat-label">Reward Model</div>
+    </div>
+  </div>
+
+  <!-- Register Model Form -->
+  <div class="mc-section" style="margin-top: 1.5rem;">
+    <h2>Register Model</h2>
+    <form hx-post="/api/v1/models" hx-target="#model-result" hx-swap="innerHTML"
+          style="display: grid; gap: 0.5rem; max-width: 500px;">
+      <input name="name" placeholder="Model name" required class="mc-input" />
+      <select name="format" class="mc-input">
+        <option value="ollama">Ollama</option>
+        <option value="gguf">GGUF</option>
+        <option value="safetensors">Safetensors</option>
+        <option value="hf">HF Checkpoint</option>
+      </select>
+      <input name="path" placeholder="Path or Ollama model name" required class="mc-input" />
+      <select name="role" class="mc-input">
+        <option value="general">General</option>
+        <option value="reward">Reward (PRM)</option>
+        <option value="teacher">Teacher</option>
+        <option value="judge">Judge</option>
+      </select>
+      <input name="context_window" type="number" value="4096" class="mc-input" />
+      <input name="description" placeholder="Description (optional)" class="mc-input" />
+      <button type="submit" class="mc-btn mc-btn-primary">Register</button>
+    </form>
+    <div id="model-result" style="margin-top: 0.5rem;"></div>
+  </div>
+
+  <!-- Registered Models -->
+  <div class="mc-section" style="margin-top: 1.5rem;">
+    <h2>Registered Models</h2>
+    {% if models %}
+    <table class="mc-table">
+      <thead>
+        <tr>
+          <th>Name</th>
+          <th>Format</th>
+          <th>Role</th>
+          <th>Context</th>
+          <th>Active</th>
+          <th>Actions</th>
+        </tr>
+      </thead>
+      <tbody>
+        {% for m in models %}
+        <tr>
+          <td><strong>{{ m.name }}</strong></td>
+          <td>{{ m.format.value }}</td>
+          <td>{{ m.role.value }}</td>
+          <td>{{ m.context_window }}</td>
+          <td>{{ "Yes" if m.active else "No" }}</td>
+          <td>
+            <button class="mc-btn mc-btn-sm"
+                    hx-delete="/api/v1/models/{{ m.name }}"
+                    hx-confirm="Remove {{ m.name }}?"
+                    hx-target="closest tr"
+                    hx-swap="outerHTML">Remove</button>
+          </td>
+        </tr>
+        {% endfor %}
+      </tbody>
+    </table>
+    {% else %}
+    <p class="mc-text-secondary">No custom models registered. Use the form above or the API.</p>
+    {% endif %}
+  </div>
+
+  <!-- Agent Assignments -->
+  <div class="mc-section" style="margin-top: 1.5rem;">
+    <h2>Agent Model Assignments</h2>
+    {% if assignments %}
+    <table class="mc-table">
+      <thead>
+        <tr><th>Agent</th><th>Model</th></tr>
+      </thead>
+      <tbody>
+        {% for agent_id, model_name in assignments.items() %}
+        <tr>
+          <td>{{ agent_id }}</td>
+          <td>{{ model_name }}</td>
+        </tr>
+        {% endfor %}
+      </tbody>
+    </table>
+    {% else %}
+    <p class="mc-text-secondary">No agent-specific model assignments. All agents use the global default.</p>
+    {% endif %}
+  </div>
+
+  <div class="mc-section" style="margin-top: 1rem;">
+    <p class="mc-text-secondary">Weights directory: <code>{{ weights_dir }}</code></p>
+  </div>
+</div>
+{% endblock %}
diff --git a/src/dashboard/templates/partials/timmy_panel.html b/src/dashboard/templates/partials/timmy_panel.html
index 663a9977..6b4806ca 100644
--- a/src/dashboard/templates/partials/timmy_panel.html
+++ b/src/dashboard/templates/partials/timmy_panel.html
@@ -30,7 +30,8 @@
             hx-disabled-elt="find button"
             hx-on::after-settle="scrollChat()"
             hx-on::after-request="if(event.detail.successful){this.querySelector('[name=message]').value='';}"
-            class="d-flex gap-2">
+            class="d-flex gap-2"
+            id="timmy-chat-form">
         <input type="text"
                name="message"
                class="form-control mc-input"
@@ -40,11 +41,20 @@
                autocapitalize="none"
                spellcheck="false"
                enterkeyhint="send"
-               required />
+               required
+               id="timmy-chat-input" />
         <button type="submit" class="btn mc-btn-send">
           SEND
           <span id="send-indicator" class="htmx-indicator">&#x25FC;</span>
         </button>
+        <button type="button"
+                class="btn"
+                style="background: #1a1a2e; color: #00ff88; border: 1px solid #00ff88;
+                       font-size: 0.7rem; white-space: nowrap; padding: 4px 10px;"
+                onclick="askGrok()"
+                title="Send directly to Grok (xAI)">
+          GROK
+        </button>
       </form>
     </div>
 
@@ -61,4 +71,20 @@
     }
   }
   scrollChat();
+
+  function askGrok() {
+    var input = document.getElementById('timmy-chat-input');
+    if (!input || !input.value.trim()) return;
+    var form = document.getElementById('timmy-chat-form');
+    // Temporarily redirect form to Grok endpoint
+    var originalAction = form.getAttribute('hx-post');
+    form.setAttribute('hx-post', '/grok/chat');
+    htmx.process(form);
+    htmx.trigger(form, 'submit');
+    // Restore original action after submission
+    setTimeout(function() {
+      form.setAttribute('hx-post', originalAction);
+      htmx.process(form);
+    }, 100);
+  }
 </script>
diff --git a/src/infrastructure/CLAUDE.md b/src/infrastructure/CLAUDE.md
new file mode 100644
index 00000000..d07c5a56
--- /dev/null
+++ b/src/infrastructure/CLAUDE.md
@@ -0,0 +1,22 @@
+# infrastructure/ — Module Guide
+
+Cross-cutting services used by many modules.
+
+## Structure
+- `ws_manager/` — WebSocket connection manager (singleton: `ws_manager`)
+- `notifications/` — Push notification store (singleton: `notifier`)
+- `events/` — Domain event bus and broadcaster
+- `router/` — Cascade LLM router with circuit-breaker failover
+
+## Key singletons
+```python
+from infrastructure.ws_manager.handler import ws_manager
+from infrastructure.notifications.push import notifier
+from infrastructure.events.bus import event_bus
+from infrastructure.router import get_router
+```
+
+## Testing
+```bash
+pytest tests/infrastructure/ tests/integrations/test_websocket*.py tests/integrations/test_notifications.py -q
+```
diff --git a/src/infrastructure/__init__.py b/src/infrastructure/__init__.py
new file mode 100644
index 00000000..3e7026e9
--- /dev/null
+++ b/src/infrastructure/__init__.py
@@ -0,0 +1 @@
+"""Infrastructure — Cross-cutting services (WebSocket, notifications, events, router)."""
diff --git a/src/infrastructure/events/__init__.py b/src/infrastructure/events/__init__.py
new file mode 100644
index 00000000..9290fea7
--- /dev/null
+++ b/src/infrastructure/events/__init__.py
@@ -0,0 +1 @@
+"""Events — Domain event dispatch and subscription."""
diff --git a/src/events/broadcaster.py b/src/infrastructure/events/broadcaster.py
similarity index 97%
rename from src/events/broadcaster.py
rename to src/infrastructure/events/broadcaster.py
index d03f79c3..c7ba26ad 100644
--- a/src/events/broadcaster.py
+++ b/src/infrastructure/events/broadcaster.py
@@ -18,7 +18,7 @@ class EventBroadcaster:
     """Broadcasts events to WebSocket clients.
     
     Usage:
-        from events.broadcaster import event_broadcaster
+        from infrastructure.events.broadcaster import event_broadcaster
         event_broadcaster.broadcast(event)
     """
     
@@ -29,7 +29,7 @@ class EventBroadcaster:
         """Lazy import to avoid circular deps."""
         if self._ws_manager is None:
             try:
-                from ws_manager.handler import ws_manager
+                from infrastructure.ws_manager.handler import ws_manager
                 self._ws_manager = ws_manager
             except Exception as exc:
                 logger.debug("WebSocket manager not available: %s", exc)
diff --git a/src/events/bus.py b/src/infrastructure/events/bus.py
similarity index 100%
rename from src/events/bus.py
rename to src/infrastructure/events/bus.py
diff --git a/src/agent_core/__init__.py b/src/infrastructure/models/__init__.py
similarity index 100%
rename from src/agent_core/__init__.py
rename to src/infrastructure/models/__init__.py
diff --git a/src/infrastructure/models/registry.py b/src/infrastructure/models/registry.py
new file mode 100644
index 00000000..b9a568c0
--- /dev/null
+++ b/src/infrastructure/models/registry.py
@@ -0,0 +1,268 @@
+"""Custom model registry — register, load, and manage model weights.
+
+Tracks custom models (GGUF files, HF checkpoints, Ollama modelfiles)
+and their assignment to swarm agents.  Models can be registered at
+runtime via the API or pre-configured via providers.yaml.
+
+Inspired by OpenClaw-RL's multi-model orchestration where distinct
+model roles (student, teacher, judge/PRM) run on dedicated resources.
+"""
+
+import logging
+import sqlite3
+import threading
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+from config import settings
+
+logger = logging.getLogger(__name__)
+
+DB_PATH = Path("data/swarm.db")
+
+
+class ModelFormat(str, Enum):
+    """Supported model weight formats."""
+    GGUF = "gguf"               # Ollama-compatible quantised weights
+    SAFETENSORS = "safetensors" # HuggingFace safetensors
+    HF_CHECKPOINT = "hf"        # Full HuggingFace checkpoint directory
+    OLLAMA = "ollama"           # Already loaded in Ollama by name
+
+
+class ModelRole(str, Enum):
+    """Role a model can play in the system (OpenClaw-RL style)."""
+    GENERAL = "general"     # Default agent inference
+    REWARD = "reward"       # Process Reward Model (PRM) scoring
+    TEACHER = "teacher"     # On-policy distillation teacher
+    JUDGE = "judge"         # Output quality evaluation
+
+
+@dataclass
+class CustomModel:
+    """A registered custom model."""
+    name: str
+    format: ModelFormat
+    path: str                       # Absolute path or Ollama model name
+    role: ModelRole = ModelRole.GENERAL
+    context_window: int = 4096
+    description: str = ""
+    registered_at: str = ""
+    active: bool = True
+    # Per-model generation settings
+    default_temperature: float = 0.7
+    max_tokens: int = 2048
+
+    def __post_init__(self):
+        if not self.registered_at:
+            self.registered_at = datetime.now(timezone.utc).isoformat()
+
+
+def _get_conn() -> sqlite3.Connection:
+    DB_PATH.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(DB_PATH))
+    conn.row_factory = sqlite3.Row
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS custom_models (
+            name            TEXT PRIMARY KEY,
+            format          TEXT NOT NULL,
+            path            TEXT NOT NULL,
+            role            TEXT NOT NULL DEFAULT 'general',
+            context_window  INTEGER NOT NULL DEFAULT 4096,
+            description     TEXT NOT NULL DEFAULT '',
+            registered_at   TEXT NOT NULL,
+            active          INTEGER NOT NULL DEFAULT 1,
+            default_temperature REAL NOT NULL DEFAULT 0.7,
+            max_tokens      INTEGER NOT NULL DEFAULT 2048
+        )
+        """
+    )
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS agent_model_assignments (
+            agent_id    TEXT PRIMARY KEY,
+            model_name  TEXT NOT NULL,
+            assigned_at TEXT NOT NULL,
+            FOREIGN KEY (model_name) REFERENCES custom_models(name)
+        )
+        """
+    )
+    conn.commit()
+    return conn
+
+
+class ModelRegistry:
+    """Singleton registry for custom models and agent-model assignments."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        # In-memory cache for fast lookups
+        self._models: dict[str, CustomModel] = {}
+        self._agent_assignments: dict[str, str] = {}
+        self._load_from_db()
+
+    def _load_from_db(self) -> None:
+        """Bootstrap cache from SQLite."""
+        try:
+            conn = _get_conn()
+            for row in conn.execute("SELECT * FROM custom_models WHERE active = 1").fetchall():
+                self._models[row["name"]] = CustomModel(
+                    name=row["name"],
+                    format=ModelFormat(row["format"]),
+                    path=row["path"],
+                    role=ModelRole(row["role"]),
+                    context_window=row["context_window"],
+                    description=row["description"],
+                    registered_at=row["registered_at"],
+                    active=bool(row["active"]),
+                    default_temperature=row["default_temperature"],
+                    max_tokens=row["max_tokens"],
+                )
+            for row in conn.execute("SELECT * FROM agent_model_assignments").fetchall():
+                self._agent_assignments[row["agent_id"]] = row["model_name"]
+            conn.close()
+        except Exception as exc:
+            logger.warning("Failed to load model registry from DB: %s", exc)
+
+    # ── Model CRUD ─────────────────────────────────────────────────────────
+
+    def register(self, model: CustomModel) -> CustomModel:
+        """Register a new custom model."""
+        with self._lock:
+            conn = _get_conn()
+            conn.execute(
+                """
+                INSERT OR REPLACE INTO custom_models
+                    (name, format, path, role, context_window, description,
+                     registered_at, active, default_temperature, max_tokens)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    model.name, model.format.value, model.path,
+                    model.role.value, model.context_window, model.description,
+                    model.registered_at, int(model.active),
+                    model.default_temperature, model.max_tokens,
+                ),
+            )
+            conn.commit()
+            conn.close()
+            self._models[model.name] = model
+            logger.info("Registered model: %s (%s)", model.name, model.format.value)
+            return model
+
+    def unregister(self, name: str) -> bool:
+        """Remove a model from the registry."""
+        with self._lock:
+            if name not in self._models:
+                return False
+            conn = _get_conn()
+            conn.execute("DELETE FROM custom_models WHERE name = ?", (name,))
+            conn.execute(
+                "DELETE FROM agent_model_assignments WHERE model_name = ?", (name,)
+            )
+            conn.commit()
+            conn.close()
+            del self._models[name]
+            # Remove any agent assignments using this model
+            self._agent_assignments = {
+                k: v for k, v in self._agent_assignments.items() if v != name
+            }
+            logger.info("Unregistered model: %s", name)
+            return True
+
+    def get(self, name: str) -> Optional[CustomModel]:
+        """Look up a model by name."""
+        return self._models.get(name)
+
+    def list_models(self, role: Optional[ModelRole] = None) -> list[CustomModel]:
+        """List all registered models, optionally filtered by role."""
+        models = list(self._models.values())
+        if role is not None:
+            models = [m for m in models if m.role == role]
+        return models
+
+    def set_active(self, name: str, active: bool) -> bool:
+        """Enable or disable a model without removing it."""
+        model = self._models.get(name)
+        if not model:
+            return False
+        with self._lock:
+            model.active = active
+            conn = _get_conn()
+            conn.execute(
+                "UPDATE custom_models SET active = ? WHERE name = ?",
+                (int(active), name),
+            )
+            conn.commit()
+            conn.close()
+        return True
+
+    # ── Agent-model assignments ────────────────────────────────────────────
+
+    def assign_model(self, agent_id: str, model_name: str) -> bool:
+        """Assign a specific model to an agent."""
+        if model_name not in self._models:
+            return False
+        with self._lock:
+            now = datetime.now(timezone.utc).isoformat()
+            conn = _get_conn()
+            conn.execute(
+                """
+                INSERT OR REPLACE INTO agent_model_assignments
+                    (agent_id, model_name, assigned_at)
+                VALUES (?, ?, ?)
+                """,
+                (agent_id, model_name, now),
+            )
+            conn.commit()
+            conn.close()
+            self._agent_assignments[agent_id] = model_name
+            logger.info("Assigned model %s to agent %s", model_name, agent_id)
+        return True
+
+    def unassign_model(self, agent_id: str) -> bool:
+        """Remove model assignment from an agent (falls back to default)."""
+        with self._lock:
+            if agent_id not in self._agent_assignments:
+                return False
+            conn = _get_conn()
+            conn.execute(
+                "DELETE FROM agent_model_assignments WHERE agent_id = ?",
+                (agent_id,),
+            )
+            conn.commit()
+            conn.close()
+            del self._agent_assignments[agent_id]
+        return True
+
+    def get_agent_model(self, agent_id: str) -> Optional[CustomModel]:
+        """Get the model assigned to an agent, or None for default."""
+        model_name = self._agent_assignments.get(agent_id)
+        if model_name:
+            return self._models.get(model_name)
+        return None
+
+    def get_agent_assignments(self) -> dict[str, str]:
+        """Return all agent-to-model assignments."""
+        return dict(self._agent_assignments)
+
+    # ── Role-based lookups ─────────────────────────────────────────────────
+
+    def get_reward_model(self) -> Optional[CustomModel]:
+        """Get the active reward/PRM model, if any."""
+        reward_models = self.list_models(role=ModelRole.REWARD)
+        active = [m for m in reward_models if m.active]
+        return active[0] if active else None
+
+    def get_teacher_model(self) -> Optional[CustomModel]:
+        """Get the active teacher model for distillation."""
+        teacher_models = self.list_models(role=ModelRole.TEACHER)
+        active = [m for m in teacher_models if m.active]
+        return active[0] if active else None
+
+
+# Module-level singleton
+model_registry = ModelRegistry()
diff --git a/src/infrastructure/notifications/__init__.py b/src/infrastructure/notifications/__init__.py
new file mode 100644
index 00000000..7c63ebeb
--- /dev/null
+++ b/src/infrastructure/notifications/__init__.py
@@ -0,0 +1 @@
+"""Notifications — Push notification store (notifier singleton)."""
diff --git a/src/notifications/push.py b/src/infrastructure/notifications/push.py
similarity index 100%
rename from src/notifications/push.py
rename to src/infrastructure/notifications/push.py
diff --git a/src/router/__init__.py b/src/infrastructure/router/__init__.py
similarity index 100%
rename from src/router/__init__.py
rename to src/infrastructure/router/__init__.py
diff --git a/src/router/api.py b/src/infrastructure/router/api.py
similarity index 100%
rename from src/router/api.py
rename to src/infrastructure/router/api.py
diff --git a/src/router/cascade.py b/src/infrastructure/router/cascade.py
similarity index 94%
rename from src/router/cascade.py
rename to src/infrastructure/router/cascade.py
index 3118986c..17aa479e 100644
--- a/src/router/cascade.py
+++ b/src/infrastructure/router/cascade.py
@@ -220,10 +220,10 @@ class CascadeRouter:
             except ImportError:
                 return False
         
-        elif provider.type in ("openai", "anthropic"):
+        elif provider.type in ("openai", "anthropic", "grok"):
             # Check if API key is set
             return provider.api_key is not None and provider.api_key != ""
-        
+
         return True
     
     async def complete(
@@ -337,6 +337,14 @@ class CascadeRouter:
                 temperature=temperature,
                 max_tokens=max_tokens,
             )
+        elif provider.type == "grok":
+            result = await self._call_grok(
+                provider=provider,
+                messages=messages,
+                model=model or provider.get_default_model(),
+                temperature=temperature,
+                max_tokens=max_tokens,
+            )
         else:
             raise ValueError(f"Unknown provider type: {provider.type}")
         
@@ -455,7 +463,40 @@ class CascadeRouter:
             "content": response.content[0].text,
             "model": response.model,
         }
-    
+
+    async def _call_grok(
+        self,
+        provider: Provider,
+        messages: list[dict],
+        model: str,
+        temperature: float,
+        max_tokens: Optional[int],
+    ) -> dict:
+        """Call xAI Grok API via OpenAI-compatible SDK."""
+        import httpx
+        import openai
+
+        client = openai.AsyncOpenAI(
+            api_key=provider.api_key,
+            base_url=provider.base_url or "https://api.x.ai/v1",
+            timeout=httpx.Timeout(300.0),
+        )
+
+        kwargs = {
+            "model": model,
+            "messages": messages,
+            "temperature": temperature,
+        }
+        if max_tokens:
+            kwargs["max_tokens"] = max_tokens
+
+        response = await client.chat.completions.create(**kwargs)
+
+        return {
+            "content": response.choices[0].message.content,
+            "model": response.model,
+        }
+
     def _record_success(self, provider: Provider, latency_ms: float) -> None:
         """Record a successful request."""
         provider.metrics.total_requests += 1
diff --git a/src/infrastructure/ws_manager/__init__.py b/src/infrastructure/ws_manager/__init__.py
new file mode 100644
index 00000000..dd8be6a0
--- /dev/null
+++ b/src/infrastructure/ws_manager/__init__.py
@@ -0,0 +1 @@
+"""WebSocket Manager — Real-time connection handler (ws_manager singleton)."""
diff --git a/src/ws_manager/handler.py b/src/infrastructure/ws_manager/handler.py
similarity index 100%
rename from src/ws_manager/handler.py
rename to src/infrastructure/ws_manager/handler.py
diff --git a/src/integrations/CLAUDE.md b/src/integrations/CLAUDE.md
new file mode 100644
index 00000000..258ac18f
--- /dev/null
+++ b/src/integrations/CLAUDE.md
@@ -0,0 +1,14 @@
+# integrations/ — Module Guide
+
+External platform bridges. All are optional dependencies.
+
+## Structure
+- `chat_bridge/` — Vendor-agnostic chat platform abstraction (Discord impl)
+- `telegram_bot/` — Telegram bot bridge
+- `shortcuts/` — iOS Siri Shortcuts API metadata
+- `voice/` — Local NLU intent detection (regex-based, no cloud)
+
+## Testing
+```bash
+pytest tests/integrations/ -q
+```
diff --git a/src/integrations/__init__.py b/src/integrations/__init__.py
new file mode 100644
index 00000000..8eecf883
--- /dev/null
+++ b/src/integrations/__init__.py
@@ -0,0 +1 @@
+"""Integrations — External platform bridges (Discord, Telegram, Siri, Voice)."""
diff --git a/src/integrations/chat_bridge/__init__.py b/src/integrations/chat_bridge/__init__.py
new file mode 100644
index 00000000..7ecf0a7f
--- /dev/null
+++ b/src/integrations/chat_bridge/__init__.py
@@ -0,0 +1,10 @@
+"""Chat Bridge — vendor-agnostic chat platform abstraction.
+
+Provides a clean interface for integrating any chat platform
+(Discord, Telegram, Slack, etc.) with Timmy's agent core.
+
+Usage:
+    from integrations.chat_bridge.base import ChatPlatform
+    from integrations.chat_bridge.registry import platform_registry
+    from integrations.chat_bridge.vendors.discord import DiscordVendor
+"""
diff --git a/src/chat_bridge/base.py b/src/integrations/chat_bridge/base.py
similarity index 100%
rename from src/chat_bridge/base.py
rename to src/integrations/chat_bridge/base.py
diff --git a/src/chat_bridge/invite_parser.py b/src/integrations/chat_bridge/invite_parser.py
similarity index 97%
rename from src/chat_bridge/invite_parser.py
rename to src/integrations/chat_bridge/invite_parser.py
index 2c48770f..df64c440 100644
--- a/src/chat_bridge/invite_parser.py
+++ b/src/integrations/chat_bridge/invite_parser.py
@@ -11,7 +11,7 @@ Supports Discord invite patterns:
     - discordapp.com/invite/<code>
 
 Usage:
-    from chat_bridge.invite_parser import invite_parser
+    from integrations.chat_bridge.invite_parser import invite_parser
 
     # From image bytes (screenshot or QR photo)
     result = await invite_parser.parse_image(image_bytes)
@@ -25,7 +25,7 @@ import logging
 import re
 from typing import Optional
 
-from chat_bridge.base import InviteInfo
+from integrations.chat_bridge.base import InviteInfo
 
 logger = logging.getLogger(__name__)
 
diff --git a/src/chat_bridge/registry.py b/src/integrations/chat_bridge/registry.py
similarity index 94%
rename from src/chat_bridge/registry.py
rename to src/integrations/chat_bridge/registry.py
index 16271c47..52b9c7ed 100644
--- a/src/chat_bridge/registry.py
+++ b/src/integrations/chat_bridge/registry.py
@@ -5,7 +5,7 @@ all chat platform integrations. Dashboard routes and the agent core
 interact with platforms through this registry.
 
 Usage:
-    from chat_bridge.registry import platform_registry
+    from integrations.chat_bridge.registry import platform_registry
 
     platform_registry.register(discord_vendor)
     discord = platform_registry.get("discord")
@@ -15,7 +15,7 @@ Usage:
 import logging
 from typing import Optional
 
-from chat_bridge.base import ChatPlatform, PlatformStatus
+from integrations.chat_bridge.base import ChatPlatform, PlatformStatus
 
 logger = logging.getLogger(__name__)
 
diff --git a/src/chat_bridge/vendors/__init__.py b/src/integrations/chat_bridge/vendors/__init__.py
similarity index 100%
rename from src/chat_bridge/vendors/__init__.py
rename to src/integrations/chat_bridge/vendors/__init__.py
diff --git a/src/chat_bridge/vendors/discord.py b/src/integrations/chat_bridge/vendors/discord.py
similarity index 99%
rename from src/chat_bridge/vendors/discord.py
rename to src/integrations/chat_bridge/vendors/discord.py
index 06108843..747f1e3e 100644
--- a/src/chat_bridge/vendors/discord.py
+++ b/src/integrations/chat_bridge/vendors/discord.py
@@ -19,7 +19,7 @@ import logging
 from pathlib import Path
 from typing import Optional
 
-from chat_bridge.base import (
+from integrations.chat_bridge.base import (
     ChatMessage,
     ChatPlatform,
     ChatThread,
diff --git a/src/integrations/shortcuts/__init__.py b/src/integrations/shortcuts/__init__.py
new file mode 100644
index 00000000..3d26ae1f
--- /dev/null
+++ b/src/integrations/shortcuts/__init__.py
@@ -0,0 +1 @@
+"""Shortcuts — Siri Shortcuts API endpoints."""
diff --git a/src/shortcuts/siri.py b/src/integrations/shortcuts/siri.py
similarity index 100%
rename from src/shortcuts/siri.py
rename to src/integrations/shortcuts/siri.py
diff --git a/src/integrations/telegram_bot/__init__.py b/src/integrations/telegram_bot/__init__.py
new file mode 100644
index 00000000..fadaf949
--- /dev/null
+++ b/src/integrations/telegram_bot/__init__.py
@@ -0,0 +1 @@
+"""Telegram Bot — Bridge Telegram messages to Timmy."""
diff --git a/src/telegram_bot/bot.py b/src/integrations/telegram_bot/bot.py
similarity index 100%
rename from src/telegram_bot/bot.py
rename to src/integrations/telegram_bot/bot.py
diff --git a/src/integrations/voice/__init__.py b/src/integrations/voice/__init__.py
new file mode 100644
index 00000000..2e92af26
--- /dev/null
+++ b/src/integrations/voice/__init__.py
@@ -0,0 +1 @@
+"""Voice — NLU intent detection (regex-based, local, no cloud)."""
diff --git a/src/voice/nlu.py b/src/integrations/voice/nlu.py
similarity index 100%
rename from src/voice/nlu.py
rename to src/integrations/voice/nlu.py
diff --git a/src/lightning/CLAUDE.md b/src/lightning/CLAUDE.md
new file mode 100644
index 00000000..b2bba170
--- /dev/null
+++ b/src/lightning/CLAUDE.md
@@ -0,0 +1,9 @@
+# lightning/ — Module Guide
+
+**Security-sensitive.** Bitcoin Lightning payment gating (L402).
+Never hard-code secrets. Use `from config import settings` for all credentials.
+
+## Testing
+```bash
+pytest tests/lightning/ -q
+```
diff --git a/src/mcp/discovery.py b/src/mcp/discovery.py
index a6ec0241..e23e0d93 100644
--- a/src/mcp/discovery.py
+++ b/src/mcp/discovery.py
@@ -72,10 +72,10 @@ class ToolDiscovery:
         discovery = ToolDiscovery()
         
         # Discover from a module
-        tools = discovery.discover_module("tools.git")
-        
+        tools = discovery.discover_module("creative.tools.git")
+
         # Auto-register with registry
-        discovery.auto_register("tools")
+        discovery.auto_register("creative.tools")
         
         # Discover from all installed packages
         tools = discovery.discover_all_packages()
@@ -89,7 +89,7 @@ class ToolDiscovery:
         """Discover all MCP tools in a module.
         
         Args:
-            module_name: Dotted path to module (e.g., "tools.git")
+            module_name: Dotted path to module (e.g., "creative.tools.git")
         
         Returns:
             List of discovered tools
diff --git a/src/notifications/__init__.py b/src/notifications/__init__.py
deleted file mode 100644
index 8b137891..00000000
--- a/src/notifications/__init__.py
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/src/self_coding/CLAUDE.md b/src/self_coding/CLAUDE.md
new file mode 100644
index 00000000..795892a3
--- /dev/null
+++ b/src/self_coding/CLAUDE.md
@@ -0,0 +1,23 @@
+# self_coding/ — Module Guide
+
+Self-modification infrastructure with safety constraints.
+
+## Structure
+- `git_safety.py` — Atomic git operations with rollback
+- `codebase_indexer.py` — Live mental model of the codebase
+- `modification_journal.py` — Persistent log of modification attempts
+- `reflection.py` — Generate lessons learned
+- `self_modify/` — Runtime self-modification loop (LLM-driven)
+- `self_tdd/` — Continuous test watchdog
+- `upgrades/` — Self-upgrade approval queue
+
+## Entry points
+```toml
+self-tdd = "self_coding.self_tdd.watchdog:main"
+self-modify = "self_coding.self_modify.cli:main"
+```
+
+## Testing
+```bash
+pytest tests/self_coding/ -q
+```
diff --git a/src/self_coding/self_modify/__init__.py b/src/self_coding/self_modify/__init__.py
new file mode 100644
index 00000000..7dbb1735
--- /dev/null
+++ b/src/self_coding/self_modify/__init__.py
@@ -0,0 +1 @@
+"""Self-Modify — Runtime self-modification with safety constraints."""
diff --git a/src/self_modify/cli.py b/src/self_coding/self_modify/cli.py
similarity index 98%
rename from src/self_modify/cli.py
rename to src/self_coding/self_modify/cli.py
index 9a74fb6f..e0f6fe62 100644
--- a/src/self_modify/cli.py
+++ b/src/self_coding/self_modify/cli.py
@@ -45,7 +45,7 @@ def run(
     if not branch:
         os.environ["SELF_MODIFY_SKIP_BRANCH"] = "1"
 
-    from self_modify.loop import SelfModifyLoop, ModifyRequest
+    from self_coding.self_modify.loop import SelfModifyLoop, ModifyRequest
 
     target_files = list(file) if file else []
     effective_backend = backend or os.environ.get("SELF_MODIFY_BACKEND", "auto")
diff --git a/src/self_modify/loop.py b/src/self_coding/self_modify/loop.py
similarity index 99%
rename from src/self_modify/loop.py
rename to src/self_coding/self_modify/loop.py
index 633c905a..afb2dbf6 100644
--- a/src/self_modify/loop.py
+++ b/src/self_coding/self_modify/loop.py
@@ -480,7 +480,7 @@ Keep your response under 500 words. Focus on actionable fix instructions."""
 
     def _create_branch(self) -> str:
         """Create and switch to a working branch."""
-        from tools.git_tools import git_branch
+        from creative.tools.git_tools import git_branch
 
         branch_name = f"timmy/self-modify-{int(time.time())}"
         git_branch(self._repo_path, create=branch_name, switch=branch_name)
@@ -489,7 +489,7 @@ Keep your response under 500 words. Focus on actionable fix instructions."""
 
     def _git_commit(self, message: str, files: list[str]) -> Optional[str]:
         """Stage files and commit."""
-        from tools.git_tools import git_add, git_commit
+        from creative.tools.git_tools import git_add, git_commit
 
         try:
             git_add(self._repo_path, paths=files)
diff --git a/src/self_coding/self_tdd/__init__.py b/src/self_coding/self_tdd/__init__.py
new file mode 100644
index 00000000..958a5bdd
--- /dev/null
+++ b/src/self_coding/self_tdd/__init__.py
@@ -0,0 +1 @@
+"""Self-TDD — Continuous test watchdog with regression alerting."""
diff --git a/src/self_tdd/watchdog.py b/src/self_coding/self_tdd/watchdog.py
similarity index 100%
rename from src/self_tdd/watchdog.py
rename to src/self_coding/self_tdd/watchdog.py
diff --git a/src/self_coding/upgrades/__init__.py b/src/self_coding/upgrades/__init__.py
new file mode 100644
index 00000000..b5857a36
--- /dev/null
+++ b/src/self_coding/upgrades/__init__.py
@@ -0,0 +1 @@
+"""Upgrades — System upgrade queue and execution pipeline."""
diff --git a/src/upgrades/models.py b/src/self_coding/upgrades/models.py
similarity index 100%
rename from src/upgrades/models.py
rename to src/self_coding/upgrades/models.py
diff --git a/src/upgrades/queue.py b/src/self_coding/upgrades/queue.py
similarity index 99%
rename from src/upgrades/queue.py
rename to src/self_coding/upgrades/queue.py
index 8b80ef68..b02a12c3 100644
--- a/src/upgrades/queue.py
+++ b/src/self_coding/upgrades/queue.py
@@ -5,7 +5,7 @@ import subprocess
 from pathlib import Path
 from typing import Optional
 
-from upgrades.models import (
+from self_coding.upgrades.models import (
     Upgrade,
     UpgradeStatus,
     create_upgrade,
diff --git a/src/shortcuts/__init__.py b/src/shortcuts/__init__.py
deleted file mode 100644
index 8b137891..00000000
--- a/src/shortcuts/__init__.py
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/src/spark/__init__.py b/src/spark/__init__.py
index e69de29b..bf090329 100644
--- a/src/spark/__init__.py
+++ b/src/spark/__init__.py
@@ -0,0 +1 @@
+"""Spark — Intelligence engine for events, predictions, and advisory."""
diff --git a/src/swarm/CLAUDE.md b/src/swarm/CLAUDE.md
new file mode 100644
index 00000000..fd21c5d3
--- /dev/null
+++ b/src/swarm/CLAUDE.md
@@ -0,0 +1,21 @@
+# swarm/ — Module Guide
+
+Security-sensitive module. Changes to `coordinator.py` require review.
+
+## Structure
+- `coordinator.py` — Auction-based task assignment (singleton: `coordinator`)
+- `tasks.py`, `bidder.py`, `comms.py` — Core swarm primitives
+- `work_orders/` — External work order submission and execution
+- `task_queue/` — Human-in-the-loop approval queue
+- `event_log.py` — Structured event logging
+- `personas.py`, `persona_node.py` — Agent persona management
+
+## Key singletons
+```python
+from swarm.coordinator import coordinator
+```
+
+## Testing
+```bash
+pytest tests/swarm/ -q
+```
diff --git a/src/swarm/__init__.py b/src/swarm/__init__.py
index 8b137891..d2b119fd 100644
--- a/src/swarm/__init__.py
+++ b/src/swarm/__init__.py
@@ -1 +1 @@
-
+"""Swarm — Multi-agent coordinator with auction-based task assignment."""
diff --git a/src/swarm/coordinator.py b/src/swarm/coordinator.py
index 04b0c0cb..19bd3d2f 100644
--- a/src/swarm/coordinator.py
+++ b/src/swarm/coordinator.py
@@ -422,7 +422,7 @@ class SwarmCoordinator:
     async def _broadcast_agent_joined(self, agent_id: str, name: str) -> None:
         """Broadcast agent joined event via WebSocket."""
         try:
-            from ws_manager.handler import ws_manager
+            from infrastructure.ws_manager.handler import ws_manager
             await ws_manager.broadcast_agent_joined(agent_id, name)
         except Exception as exc:
             logger.debug("WebSocket broadcast failed (agent_joined): %s", exc)
@@ -430,7 +430,7 @@ class SwarmCoordinator:
     async def _broadcast_bid(self, task_id: str, agent_id: str, bid_sats: int) -> None:
         """Broadcast bid submitted event via WebSocket."""
         try:
-            from ws_manager.handler import ws_manager
+            from infrastructure.ws_manager.handler import ws_manager
             await ws_manager.broadcast_bid_submitted(task_id, agent_id, bid_sats)
         except Exception as exc:
             logger.debug("WebSocket broadcast failed (bid): %s", exc)
@@ -438,7 +438,7 @@ class SwarmCoordinator:
     async def _broadcast_task_posted(self, task_id: str, description: str) -> None:
         """Broadcast task posted event via WebSocket."""
         try:
-            from ws_manager.handler import ws_manager
+            from infrastructure.ws_manager.handler import ws_manager
             await ws_manager.broadcast_task_posted(task_id, description)
         except Exception as exc:
             logger.debug("WebSocket broadcast failed (task_posted): %s", exc)
@@ -446,7 +446,7 @@ class SwarmCoordinator:
     async def _broadcast_task_assigned(self, task_id: str, agent_id: str) -> None:
         """Broadcast task assigned event via WebSocket."""
         try:
-            from ws_manager.handler import ws_manager
+            from infrastructure.ws_manager.handler import ws_manager
             await ws_manager.broadcast_task_assigned(task_id, agent_id)
         except Exception as exc:
             logger.debug("WebSocket broadcast failed (task_assigned): %s", exc)
@@ -456,7 +456,7 @@ class SwarmCoordinator:
     ) -> None:
         """Broadcast task completed event via WebSocket."""
         try:
-            from ws_manager.handler import ws_manager
+            from infrastructure.ws_manager.handler import ws_manager
             await ws_manager.broadcast_task_completed(task_id, agent_id, result)
         except Exception as exc:
             logger.debug("WebSocket broadcast failed (task_completed): %s", exc)
diff --git a/src/swarm/event_log.py b/src/swarm/event_log.py
index bdac7ca8..7b6ec0a4 100644
--- a/src/swarm/event_log.py
+++ b/src/swarm/event_log.py
@@ -143,7 +143,7 @@ def log_event(
     
     # Broadcast to WebSocket clients for real-time activity feed
     try:
-        from events.broadcaster import event_broadcaster
+        from infrastructure.events.broadcaster import event_broadcaster
         event_broadcaster.broadcast_sync(entry)
     except Exception:
         # Don't fail if broadcaster unavailable
diff --git a/src/swarm/learner.py b/src/swarm/learner.py
index 3f82a46e..b8559f50 100644
--- a/src/swarm/learner.py
+++ b/src/swarm/learner.py
@@ -251,3 +251,193 @@ def learned_keywords(agent_id: str) -> list[dict]:
         results.append({"keyword": kw, "wins": wins, "failures": fails, "net": wins - fails})
     results.sort(key=lambda x: x["net"], reverse=True)
     return results
+
+
+# ── Reward model scoring (PRM-style) ─────────────────────────────────────────
+
+import logging as _logging
+from config import settings as _settings
+
+_reward_logger = _logging.getLogger(__name__ + ".reward")
+
+
+@dataclass
+class RewardScore:
+    """Result from reward-model evaluation."""
+    score: float          # Normalised score in [-1.0, 1.0]
+    positive_votes: int
+    negative_votes: int
+    total_votes: int
+    model_used: str
+
+
+def _ensure_reward_table() -> None:
+    """Create the reward_scores table if needed."""
+    conn = _get_conn()
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS reward_scores (
+            id          INTEGER PRIMARY KEY AUTOINCREMENT,
+            task_id     TEXT NOT NULL,
+            agent_id    TEXT NOT NULL,
+            output_text TEXT NOT NULL,
+            score       REAL NOT NULL,
+            positive    INTEGER NOT NULL,
+            negative    INTEGER NOT NULL,
+            total       INTEGER NOT NULL,
+            model_used  TEXT NOT NULL,
+            scored_at   TEXT NOT NULL DEFAULT (datetime('now'))
+        )
+        """
+    )
+    conn.commit()
+    conn.close()
+
+
+def score_output(
+    task_id: str,
+    agent_id: str,
+    task_description: str,
+    output_text: str,
+) -> Optional[RewardScore]:
+    """Score an agent's output using the reward model (majority vote).
+
+    Calls the reward model N times (settings.reward_model_votes) with a
+    quality-evaluation prompt.  Each vote is +1 (good) or -1 (bad).
+    Final score is (positive - negative) / total, in [-1.0, 1.0].
+
+    Returns None if the reward model is disabled or unavailable.
+    """
+    if not _settings.reward_model_enabled:
+        return None
+
+    # Resolve model name: explicit setting > registry reward model > skip
+    model_name = _settings.reward_model_name
+    if not model_name:
+        try:
+            from infrastructure.models.registry import model_registry
+            reward = model_registry.get_reward_model()
+            if reward:
+                model_name = reward.path if reward.format.value == "ollama" else reward.name
+        except Exception:
+            pass
+
+    if not model_name:
+        _reward_logger.debug("No reward model configured, skipping scoring")
+        return None
+
+    num_votes = max(1, _settings.reward_model_votes)
+    positive = 0
+    negative = 0
+
+    prompt = (
+        f"You are a quality evaluator.  Rate the following agent output.\n\n"
+        f"TASK: {task_description}\n\n"
+        f"OUTPUT:\n{output_text[:2000]}\n\n"
+        f"Is this output correct, helpful, and complete? "
+        f"Reply with exactly one word: GOOD or BAD."
+    )
+
+    try:
+        import requests as _req
+        ollama_url = _settings.ollama_url
+
+        for _ in range(num_votes):
+            try:
+                resp = _req.post(
+                    f"{ollama_url}/api/generate",
+                    json={
+                        "model": model_name,
+                        "prompt": prompt,
+                        "stream": False,
+                        "options": {"temperature": 0.3, "num_predict": 10},
+                    },
+                    timeout=30,
+                )
+                if resp.status_code == 200:
+                    answer = resp.json().get("response", "").strip().upper()
+                    if "GOOD" in answer:
+                        positive += 1
+                    else:
+                        negative += 1
+                else:
+                    negative += 1  # Treat errors as negative conservatively
+            except Exception as vote_exc:
+                _reward_logger.debug("Vote failed: %s", vote_exc)
+                negative += 1
+
+    except ImportError:
+        _reward_logger.warning("requests library not available for reward scoring")
+        return None
+
+    total = positive + negative
+    if total == 0:
+        return None
+
+    score = (positive - negative) / total
+
+    result = RewardScore(
+        score=score,
+        positive_votes=positive,
+        negative_votes=negative,
+        total_votes=total,
+        model_used=model_name,
+    )
+
+    # Persist to DB
+    try:
+        _ensure_reward_table()
+        conn = _get_conn()
+        conn.execute(
+            """
+            INSERT INTO reward_scores
+                (task_id, agent_id, output_text, score, positive, negative, total, model_used)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                task_id, agent_id, output_text[:5000],
+                score, positive, negative, total, model_name,
+            ),
+        )
+        conn.commit()
+        conn.close()
+    except Exception as db_exc:
+        _reward_logger.warning("Failed to persist reward score: %s", db_exc)
+
+    _reward_logger.info(
+        "Scored task %s agent %s: %.2f (%d+/%d- of %d votes)",
+        task_id, agent_id, score, positive, negative, total,
+    )
+    return result
+
+
+def get_reward_scores(
+    agent_id: Optional[str] = None, limit: int = 50
+) -> list[dict]:
+    """Retrieve historical reward scores from the database."""
+    _ensure_reward_table()
+    conn = _get_conn()
+    if agent_id:
+        rows = conn.execute(
+            "SELECT * FROM reward_scores WHERE agent_id = ? ORDER BY id DESC LIMIT ?",
+            (agent_id, limit),
+        ).fetchall()
+    else:
+        rows = conn.execute(
+            "SELECT * FROM reward_scores ORDER BY id DESC LIMIT ?",
+            (limit,),
+        ).fetchall()
+    conn.close()
+    return [
+        {
+            "task_id": r["task_id"],
+            "agent_id": r["agent_id"],
+            "score": r["score"],
+            "positive": r["positive"],
+            "negative": r["negative"],
+            "total": r["total"],
+            "model_used": r["model_used"],
+            "scored_at": r["scored_at"],
+        }
+        for r in rows
+    ]
diff --git a/src/swarm/persona_node.py b/src/swarm/persona_node.py
index 98a36755..1ed7481f 100644
--- a/src/swarm/persona_node.py
+++ b/src/swarm/persona_node.py
@@ -51,6 +51,16 @@ class PersonaNode(SwarmNode):
         self._meta = meta
         self._persona_id = persona_id
         self._use_learner = use_learner
+
+        # Resolve model: registry assignment > persona default > global default
+        self._model_name: Optional[str] = meta.get("model")
+        try:
+            from infrastructure.models.registry import model_registry
+            assigned = model_registry.get_agent_model(agent_id)
+            if assigned:
+                self._model_name = assigned.name
+        except Exception:
+            pass  # Graceful degradation — use persona/global default
         
         # Initialize tool executor for task execution
         self._tool_executor: Optional[ToolExecutor] = None
@@ -213,6 +223,11 @@ class PersonaNode(SwarmNode):
         """Return the task ID currently being executed, if any."""
         return self._current_task
     
+    @property
+    def model_name(self) -> Optional[str]:
+        """Return the model this agent uses, or None for global default."""
+        return self._model_name
+
     @property
     def tool_capabilities(self) -> list[str]:
         """Return list of available tool names."""
diff --git a/src/swarm/personas.py b/src/swarm/personas.py
index 6a73548d..3c583ff6 100644
--- a/src/swarm/personas.py
+++ b/src/swarm/personas.py
@@ -14,7 +14,7 @@ from __future__ import annotations
 from typing import TypedDict
 
 
-class PersonaMeta(TypedDict):
+class PersonaMeta(TypedDict, total=False):
     id: str
     name: str
     role: str
@@ -24,6 +24,11 @@ class PersonaMeta(TypedDict):
     bid_base: int              # typical bid when task matches persona
     bid_jitter: int            # ± random jitter added to bid_base
     preferred_keywords: list[str]
+    # Optional: custom model override for this persona.
+    # When set, this persona uses this model instead of the global default.
+    # Value is a model name registered in the ModelRegistry, or an Ollama
+    # model name like "llama3.2" or "deepseek-r1:1.5b".
+    model: str
 
 
 PERSONAS: dict[str, PersonaMeta] = {
diff --git a/src/task_queue/__init__.py b/src/swarm/task_queue/__init__.py
similarity index 100%
rename from src/task_queue/__init__.py
rename to src/swarm/task_queue/__init__.py
diff --git a/src/task_queue/models.py b/src/swarm/task_queue/models.py
similarity index 100%
rename from src/task_queue/models.py
rename to src/swarm/task_queue/models.py
diff --git a/src/swarm/tool_executor.py b/src/swarm/tool_executor.py
index 37fc64c0..c0423a69 100644
--- a/src/swarm/tool_executor.py
+++ b/src/swarm/tool_executor.py
@@ -302,7 +302,7 @@ class DirectToolExecutor(ToolExecutor):
                 if not cfg.self_modify_enabled:
                     return self.execute_task(task_description)
 
-                from self_modify.loop import SelfModifyLoop, ModifyRequest
+                from self_coding.self_modify.loop import SelfModifyLoop, ModifyRequest
 
                 loop = SelfModifyLoop()
                 result = loop.run(ModifyRequest(instruction=task_description))
diff --git a/src/work_orders/__init__.py b/src/swarm/work_orders/__init__.py
similarity index 100%
rename from src/work_orders/__init__.py
rename to src/swarm/work_orders/__init__.py
diff --git a/src/work_orders/executor.py b/src/swarm/work_orders/executor.py
similarity index 96%
rename from src/work_orders/executor.py
rename to src/swarm/work_orders/executor.py
index 8c8fd0b3..784c563a 100644
--- a/src/work_orders/executor.py
+++ b/src/swarm/work_orders/executor.py
@@ -2,7 +2,7 @@
 
 import logging
 
-from work_orders.models import WorkOrder, WorkOrderCategory
+from swarm.work_orders.models import WorkOrder, WorkOrderCategory
 
 logger = logging.getLogger(__name__)
 
diff --git a/src/work_orders/models.py b/src/swarm/work_orders/models.py
similarity index 100%
rename from src/work_orders/models.py
rename to src/swarm/work_orders/models.py
diff --git a/src/work_orders/risk.py b/src/swarm/work_orders/risk.py
similarity index 95%
rename from src/work_orders/risk.py
rename to src/swarm/work_orders/risk.py
index 7a93996c..7b8be3be 100644
--- a/src/work_orders/risk.py
+++ b/src/swarm/work_orders/risk.py
@@ -1,6 +1,6 @@
 """Risk scoring and auto-execution threshold logic for work orders."""
 
-from work_orders.models import WorkOrder, WorkOrderCategory, WorkOrderPriority
+from swarm.work_orders.models import WorkOrder, WorkOrderCategory, WorkOrderPriority
 
 
 PRIORITY_WEIGHTS = {
diff --git a/src/timmy/__init__.py b/src/timmy/__init__.py
index e69de29b..09f8e7fb 100644
--- a/src/timmy/__init__.py
+++ b/src/timmy/__init__.py
@@ -0,0 +1 @@
+"""Timmy — Core AI agent (Ollama/AirLLM backends, CLI, prompts)."""
diff --git a/src/timmy/agent.py b/src/timmy/agent.py
index c787adcf..0f52bc78 100644
--- a/src/timmy/agent.py
+++ b/src/timmy/agent.py
@@ -20,12 +20,12 @@ from timmy.prompts import get_system_prompt
 from timmy.tools import create_full_toolkit
 
 if TYPE_CHECKING:
-    from timmy.backends import TimmyAirLLMAgent
+    from timmy.backends import GrokBackend, TimmyAirLLMAgent
 
 logger = logging.getLogger(__name__)
 
 # Union type for callers that want to hint the return type.
-TimmyAgent = Union[Agent, "TimmyAirLLMAgent"]
+TimmyAgent = Union[Agent, "TimmyAirLLMAgent", "GrokBackend"]
 
 # Models known to be too small for reliable tool calling.
 # These hallucinate tool calls as text, invoke tools randomly,
@@ -68,12 +68,12 @@ def _resolve_backend(requested: str | None) -> str:
     if requested is not None:
         return requested
 
-    configured = settings.timmy_model_backend  # "ollama" | "airllm" | "auto"
+    configured = settings.timmy_model_backend  # "ollama" | "airllm" | "grok" | "auto"
     if configured != "auto":
         return configured
 
     # "auto" path — lazy import to keep startup fast and tests clean.
-    from timmy.backends import airllm_available, is_apple_silicon
+    from timmy.backends import airllm_available, grok_available, is_apple_silicon
     if is_apple_silicon() and airllm_available():
         return "airllm"
     return "ollama"
@@ -97,6 +97,10 @@ def create_timmy(
     resolved = _resolve_backend(backend)
     size = model_size or settings.airllm_model_size
 
+    if resolved == "grok":
+        from timmy.backends import GrokBackend
+        return GrokBackend()
+
     if resolved == "airllm":
         from timmy.backends import TimmyAirLLMAgent
         return TimmyAirLLMAgent(model_size=size)
diff --git a/src/timmy/agent_core/__init__.py b/src/timmy/agent_core/__init__.py
new file mode 100644
index 00000000..1ed3f086
--- /dev/null
+++ b/src/timmy/agent_core/__init__.py
@@ -0,0 +1 @@
+"""Agent Core — Substrate-agnostic agent interface and base classes."""
diff --git a/src/agent_core/interface.py b/src/timmy/agent_core/interface.py
similarity index 100%
rename from src/agent_core/interface.py
rename to src/timmy/agent_core/interface.py
diff --git a/src/agent_core/ollama_adapter.py b/src/timmy/agent_core/ollama_adapter.py
similarity index 98%
rename from src/agent_core/ollama_adapter.py
rename to src/timmy/agent_core/ollama_adapter.py
index e27a109b..7b024c2b 100644
--- a/src/agent_core/ollama_adapter.py
+++ b/src/timmy/agent_core/ollama_adapter.py
@@ -5,8 +5,8 @@ to the substrate-agnostic TimAgent interface. It's the bridge
 between the old codebase and the new embodiment-ready architecture.
 
 Usage:
-    from agent_core import AgentIdentity, Perception
-    from agent_core.ollama_adapter import OllamaAgent
+    from timmy.agent_core import AgentIdentity, Perception
+    from timmy.agent_core.ollama_adapter import OllamaAgent
     
     identity = AgentIdentity.generate("Timmy")
     agent = OllamaAgent(identity)
@@ -19,7 +19,7 @@ Usage:
 
 from typing import Any, Optional
 
-from agent_core.interface import (
+from timmy.agent_core.interface import (
     AgentCapability,
     AgentIdentity,
     Perception,
diff --git a/src/timmy/agents/__init__.py b/src/timmy/agents/__init__.py
new file mode 100644
index 00000000..f097b30e
--- /dev/null
+++ b/src/timmy/agents/__init__.py
@@ -0,0 +1,21 @@
+"""Agents package — Timmy and sub-agents.
+"""
+
+from timmy.agents.timmy import TimmyOrchestrator, create_timmy_swarm
+from timmy.agents.base import BaseAgent
+from timmy.agents.seer import SeerAgent
+from timmy.agents.forge import ForgeAgent
+from timmy.agents.quill import QuillAgent
+from timmy.agents.echo import EchoAgent
+from timmy.agents.helm import HelmAgent
+
+__all__ = [
+    "BaseAgent",
+    "TimmyOrchestrator",
+    "create_timmy_swarm",
+    "SeerAgent",
+    "ForgeAgent",
+    "QuillAgent",
+    "EchoAgent",
+    "HelmAgent",
+]
diff --git a/src/agents/base.py b/src/timmy/agents/base.py
similarity index 98%
rename from src/agents/base.py
rename to src/timmy/agents/base.py
index 7469868c..7e70239c 100644
--- a/src/agents/base.py
+++ b/src/timmy/agents/base.py
@@ -15,7 +15,7 @@ from agno.agent import Agent
 from agno.models.ollama import Ollama
 
 from config import settings
-from events.bus import EventBus, Event
+from infrastructure.events.bus import EventBus, Event
 from mcp.registry import tool_registry
 
 logger = logging.getLogger(__name__)
diff --git a/src/agents/echo.py b/src/timmy/agents/echo.py
similarity index 98%
rename from src/agents/echo.py
rename to src/timmy/agents/echo.py
index 7bb8a702..cc82a3b9 100644
--- a/src/agents/echo.py
+++ b/src/timmy/agents/echo.py
@@ -9,7 +9,7 @@ Capabilities:
 
 from typing import Any
 
-from agents.base import BaseAgent
+from timmy.agents.base import BaseAgent
 
 
 ECHO_SYSTEM_PROMPT = """You are Echo, a memory and context management specialist.
diff --git a/src/agents/forge.py b/src/timmy/agents/forge.py
similarity index 98%
rename from src/agents/forge.py
rename to src/timmy/agents/forge.py
index fbe44b2b..14ea9e7e 100644
--- a/src/agents/forge.py
+++ b/src/timmy/agents/forge.py
@@ -9,7 +9,7 @@ Capabilities:
 
 from typing import Any
 
-from agents.base import BaseAgent
+from timmy.agents.base import BaseAgent
 
 
 FORGE_SYSTEM_PROMPT = """You are Forge, a code generation and tool building specialist.
diff --git a/src/agents/helm.py b/src/timmy/agents/helm.py
similarity index 98%
rename from src/agents/helm.py
rename to src/timmy/agents/helm.py
index 7d5c9f37..b8c383e4 100644
--- a/src/agents/helm.py
+++ b/src/timmy/agents/helm.py
@@ -9,7 +9,7 @@ Capabilities:
 
 from typing import Any
 
-from agents.base import BaseAgent
+from timmy.agents.base import BaseAgent
 
 
 HELM_SYSTEM_PROMPT = """You are Helm, a routing and orchestration specialist.
diff --git a/src/agents/quill.py b/src/timmy/agents/quill.py
similarity index 98%
rename from src/agents/quill.py
rename to src/timmy/agents/quill.py
index 199d36e9..1ad65af0 100644
--- a/src/agents/quill.py
+++ b/src/timmy/agents/quill.py
@@ -9,7 +9,7 @@ Capabilities:
 
 from typing import Any
 
-from agents.base import BaseAgent
+from timmy.agents.base import BaseAgent
 
 
 QUILL_SYSTEM_PROMPT = """You are Quill, a writing and content generation specialist.
diff --git a/src/agents/seer.py b/src/timmy/agents/seer.py
similarity index 97%
rename from src/agents/seer.py
rename to src/timmy/agents/seer.py
index 3e3e58f3..2e9f43e7 100644
--- a/src/agents/seer.py
+++ b/src/timmy/agents/seer.py
@@ -9,8 +9,8 @@ Capabilities:
 
 from typing import Any
 
-from agents.base import BaseAgent
-from events.bus import Event
+from timmy.agents.base import BaseAgent
+from infrastructure.events.bus import Event
 
 
 SEER_SYSTEM_PROMPT = """You are Seer, a research and information gathering specialist.
diff --git a/src/agents/timmy.py b/src/timmy/agents/timmy.py
similarity index 98%
rename from src/agents/timmy.py
rename to src/timmy/agents/timmy.py
index 92247358..5801bfc7 100644
--- a/src/agents/timmy.py
+++ b/src/timmy/agents/timmy.py
@@ -12,9 +12,9 @@ from typing import Any, Optional
 from agno.agent import Agent
 from agno.models.ollama import Ollama
 
-from agents.base import BaseAgent
+from timmy.agents.base import BaseAgent
 from config import settings
-from events.bus import EventBus, event_bus
+from infrastructure.events.bus import EventBus, event_bus
 from mcp.registry import tool_registry
 
 logger = logging.getLogger(__name__)
@@ -440,11 +440,11 @@ When asked "what's new?" or similar, refer to these commits for actual changes.
 # Factory function for creating fully configured Timmy
 def create_timmy_swarm() -> TimmyOrchestrator:
     """Create Timmy orchestrator with all sub-agents registered."""
-    from agents.seer import SeerAgent
-    from agents.forge import ForgeAgent
-    from agents.quill import QuillAgent
-    from agents.echo import EchoAgent
-    from agents.helm import HelmAgent
+    from timmy.agents.seer import SeerAgent
+    from timmy.agents.forge import ForgeAgent
+    from timmy.agents.quill import QuillAgent
+    from timmy.agents.echo import EchoAgent
+    from timmy.agents.helm import HelmAgent
     
     # Create orchestrator (builds context automatically)
     timmy = TimmyOrchestrator()
diff --git a/src/timmy/backends.py b/src/timmy/backends.py
index ba94f304..e5745c43 100644
--- a/src/timmy/backends.py
+++ b/src/timmy/backends.py
@@ -1,20 +1,26 @@
-"""AirLLM backend — only imported when the airllm extra is installed.
+"""LLM backends — AirLLM (local big models) and Grok (xAI premium cloud).
 
-Provides TimmyAirLLMAgent: a drop-in replacement for an Agno Agent that
-exposes both the run(message, stream) → RunResult interface used by the
-dashboard and the print_response(message, stream) interface used by the CLI.
-On Apple Silicon (arm64 Darwin) the MLX backend is selected automatically;
-everywhere else AutoModel (PyTorch) is used.
+Provides drop-in replacements for the Agno Agent that expose the same
+run(message, stream) → RunResult interface used by the dashboard and the
+print_response(message, stream) interface used by the CLI.
 
-No cloud.  No telemetry.  Sats are sovereignty, boss.
+Backends:
+  - TimmyAirLLMAgent: Local 8B/70B/405B via AirLLM (Apple Silicon or PyTorch)
+  - GrokBackend: xAI Grok API via OpenAI-compatible SDK (opt-in premium)
+
+No cloud by default.  No telemetry.  Sats are sovereignty, boss.
 """
 
+import logging
 import platform
-from dataclasses import dataclass
-from typing import Literal
+import time
+from dataclasses import dataclass, field
+from typing import Literal, Optional
 
 from timmy.prompts import TIMMY_SYSTEM_PROMPT
 
+logger = logging.getLogger(__name__)
+
 # HuggingFace model IDs for each supported size.
 _AIRLLM_MODELS: dict[str, str] = {
     "8b":   "meta-llama/Meta-Llama-3.1-8B-Instruct",
@@ -133,3 +139,281 @@ class TimmyAirLLMAgent:
             Console().print(Markdown(text))
         except ImportError:
             print(text)
+
+
+# ── Grok (xAI) Backend ─────────────────────────────────────────────────────
+# Premium cloud augmentation — opt-in only, never the default path.
+
+# Available Grok models (configurable via GROK_DEFAULT_MODEL)
+GROK_MODELS: dict[str, str] = {
+    "grok-3-fast": "grok-3-fast",
+    "grok-3": "grok-3",
+    "grok-3-mini": "grok-3-mini",
+    "grok-3-mini-fast": "grok-3-mini-fast",
+}
+
+
+@dataclass
+class GrokUsageStats:
+    """Tracks Grok API usage for cost monitoring and Spark logging."""
+    total_requests: int = 0
+    total_prompt_tokens: int = 0
+    total_completion_tokens: int = 0
+    total_latency_ms: float = 0.0
+    errors: int = 0
+    last_request_at: Optional[float] = None
+
+    @property
+    def estimated_cost_sats(self) -> int:
+        """Rough cost estimate in sats based on token usage."""
+        # ~$5/1M input tokens, ~$15/1M output tokens for Grok
+        # At ~$100k/BTC, 1 sat ≈ $0.001
+        input_cost = (self.total_prompt_tokens / 1_000_000) * 5
+        output_cost = (self.total_completion_tokens / 1_000_000) * 15
+        total_usd = input_cost + output_cost
+        return int(total_usd / 0.001)  # Convert to sats
+
+
+class GrokBackend:
+    """xAI Grok backend — premium cloud augmentation for frontier reasoning.
+
+    Uses the OpenAI-compatible SDK to connect to xAI's API.
+    Only activated when GROK_ENABLED=true and XAI_API_KEY is set.
+
+    Exposes the same interface as TimmyAirLLMAgent and Agno Agent:
+      run(message, stream)           → RunResult  [dashboard]
+      print_response(message, stream) → None       [CLI]
+      health_check()                 → dict        [monitoring]
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        model: Optional[str] = None,
+    ) -> None:
+        from config import settings
+
+        self._api_key = api_key or settings.xai_api_key
+        self._model = model or settings.grok_default_model
+        self._history: list[dict[str, str]] = []
+        self.stats = GrokUsageStats()
+
+        if not self._api_key:
+            logger.warning(
+                "GrokBackend created without XAI_API_KEY — "
+                "calls will fail until key is configured"
+            )
+
+    def _get_client(self):
+        """Create OpenAI client configured for xAI endpoint."""
+        import httpx
+        from openai import OpenAI
+
+        return OpenAI(
+            api_key=self._api_key,
+            base_url="https://api.x.ai/v1",
+            timeout=httpx.Timeout(300.0),
+        )
+
+    async def _get_async_client(self):
+        """Create async OpenAI client configured for xAI endpoint."""
+        import httpx
+        from openai import AsyncOpenAI
+
+        return AsyncOpenAI(
+            api_key=self._api_key,
+            base_url="https://api.x.ai/v1",
+            timeout=httpx.Timeout(300.0),
+        )
+
+    # ── Public interface (mirrors Agno Agent) ─────────────────────────────
+
+    def run(self, message: str, *, stream: bool = False) -> RunResult:
+        """Synchronous inference via Grok API.
+
+        Args:
+            message: User prompt
+            stream: Accepted for API compat; Grok returns full response
+
+        Returns:
+            RunResult with response content
+        """
+        if not self._api_key:
+            return RunResult(
+                content="Grok is not configured. Set XAI_API_KEY to enable."
+            )
+
+        start = time.time()
+        messages = self._build_messages(message)
+
+        try:
+            client = self._get_client()
+            response = client.chat.completions.create(
+                model=self._model,
+                messages=messages,
+                temperature=0.7,
+            )
+
+            content = response.choices[0].message.content or ""
+            latency_ms = (time.time() - start) * 1000
+
+            # Track usage
+            self.stats.total_requests += 1
+            self.stats.total_latency_ms += latency_ms
+            self.stats.last_request_at = time.time()
+            if response.usage:
+                self.stats.total_prompt_tokens += response.usage.prompt_tokens
+                self.stats.total_completion_tokens += response.usage.completion_tokens
+
+            # Update conversation history
+            self._history.append({"role": "user", "content": message})
+            self._history.append({"role": "assistant", "content": content})
+            # Keep last 10 turns
+            if len(self._history) > 20:
+                self._history = self._history[-20:]
+
+            logger.info(
+                "Grok response: %d tokens in %.0fms (model=%s)",
+                response.usage.completion_tokens if response.usage else 0,
+                latency_ms,
+                self._model,
+            )
+
+            return RunResult(content=content)
+
+        except Exception as exc:
+            self.stats.errors += 1
+            logger.error("Grok API error: %s", exc)
+            return RunResult(
+                content=f"Grok temporarily unavailable: {exc}"
+            )
+
+    async def arun(self, message: str) -> RunResult:
+        """Async inference via Grok API — used by cascade router and tools."""
+        if not self._api_key:
+            return RunResult(
+                content="Grok is not configured. Set XAI_API_KEY to enable."
+            )
+
+        start = time.time()
+        messages = self._build_messages(message)
+
+        try:
+            client = await self._get_async_client()
+            response = await client.chat.completions.create(
+                model=self._model,
+                messages=messages,
+                temperature=0.7,
+            )
+
+            content = response.choices[0].message.content or ""
+            latency_ms = (time.time() - start) * 1000
+
+            # Track usage
+            self.stats.total_requests += 1
+            self.stats.total_latency_ms += latency_ms
+            self.stats.last_request_at = time.time()
+            if response.usage:
+                self.stats.total_prompt_tokens += response.usage.prompt_tokens
+                self.stats.total_completion_tokens += response.usage.completion_tokens
+
+            # Update conversation history
+            self._history.append({"role": "user", "content": message})
+            self._history.append({"role": "assistant", "content": content})
+            if len(self._history) > 20:
+                self._history = self._history[-20:]
+
+            logger.info(
+                "Grok async response: %d tokens in %.0fms (model=%s)",
+                response.usage.completion_tokens if response.usage else 0,
+                latency_ms,
+                self._model,
+            )
+
+            return RunResult(content=content)
+
+        except Exception as exc:
+            self.stats.errors += 1
+            logger.error("Grok async API error: %s", exc)
+            return RunResult(
+                content=f"Grok temporarily unavailable: {exc}"
+            )
+
+    def print_response(self, message: str, *, stream: bool = True) -> None:
+        """Run inference and render the response to stdout (CLI interface)."""
+        result = self.run(message, stream=stream)
+        try:
+            from rich.console import Console
+            from rich.markdown import Markdown
+            Console().print(Markdown(result.content))
+        except ImportError:
+            print(result.content)
+
+    def health_check(self) -> dict:
+        """Check Grok API connectivity and return status."""
+        if not self._api_key:
+            return {
+                "ok": False,
+                "error": "XAI_API_KEY not configured",
+                "backend": "grok",
+                "model": self._model,
+            }
+
+        try:
+            client = self._get_client()
+            # Lightweight check — list models
+            client.models.list()
+            return {
+                "ok": True,
+                "error": None,
+                "backend": "grok",
+                "model": self._model,
+                "stats": {
+                    "total_requests": self.stats.total_requests,
+                    "estimated_cost_sats": self.stats.estimated_cost_sats,
+                },
+            }
+        except Exception as exc:
+            return {
+                "ok": False,
+                "error": str(exc),
+                "backend": "grok",
+                "model": self._model,
+            }
+
+    @property
+    def estimated_cost(self) -> int:
+        """Return estimated cost in sats for all requests so far."""
+        return self.stats.estimated_cost_sats
+
+    # ── Private helpers ───────────────────────────────────────────────────
+
+    def _build_messages(self, message: str) -> list[dict[str, str]]:
+        """Build the messages array for the API call."""
+        messages = [{"role": "system", "content": TIMMY_SYSTEM_PROMPT}]
+        # Include conversation history for context
+        messages.extend(self._history[-10:])
+        messages.append({"role": "user", "content": message})
+        return messages
+
+
+# ── Module-level Grok singleton ─────────────────────────────────────────────
+
+_grok_backend: Optional[GrokBackend] = None
+
+
+def get_grok_backend() -> GrokBackend:
+    """Get or create the Grok backend singleton."""
+    global _grok_backend
+    if _grok_backend is None:
+        _grok_backend = GrokBackend()
+    return _grok_backend
+
+
+def grok_available() -> bool:
+    """Return True when Grok is enabled and API key is configured."""
+    try:
+        from config import settings
+        return settings.grok_enabled and bool(settings.xai_api_key)
+    except Exception:
+        return False
diff --git a/src/timmy/briefing.py b/src/timmy/briefing.py
index 9b3503b4..57266217 100644
--- a/src/timmy/briefing.py
+++ b/src/timmy/briefing.py
@@ -169,7 +169,7 @@ def _gather_swarm_summary(since: datetime) -> str:
 def _gather_task_queue_summary() -> str:
     """Pull task queue stats for the briefing.  Graceful if unavailable."""
     try:
-        from task_queue.models import get_task_summary_for_briefing
+        from swarm.task_queue.models import get_task_summary_for_briefing
         stats = get_task_summary_for_briefing()
         parts = []
         if stats["pending_approval"]:
diff --git a/src/timmy/cascade_adapter.py b/src/timmy/cascade_adapter.py
index 59984648..111afd77 100644
--- a/src/timmy/cascade_adapter.py
+++ b/src/timmy/cascade_adapter.py
@@ -10,7 +10,7 @@ import logging
 from dataclasses import dataclass
 from typing import Optional
 
-from router.cascade import CascadeRouter
+from infrastructure.router.cascade import CascadeRouter
 from timmy.prompts import TIMMY_SYSTEM_PROMPT
 
 logger = logging.getLogger(__name__)
diff --git a/src/timmy/memory/__init__.py b/src/timmy/memory/__init__.py
new file mode 100644
index 00000000..4b6dbd10
--- /dev/null
+++ b/src/timmy/memory/__init__.py
@@ -0,0 +1 @@
+"""Memory — Persistent conversation and knowledge memory."""
diff --git a/src/memory/vector_store.py b/src/timmy/memory/vector_store.py
similarity index 100%
rename from src/memory/vector_store.py
rename to src/timmy/memory/vector_store.py
diff --git a/src/timmy/tools.py b/src/timmy/tools.py
index d680d1af..3eb7f6e1 100644
--- a/src/timmy/tools.py
+++ b/src/timmy/tools.py
@@ -278,39 +278,104 @@ def create_devops_tools(base_dir: str | Path | None = None):
     return toolkit
 
 
+def consult_grok(query: str) -> str:
+    """Consult Grok (xAI) for frontier reasoning on complex questions.
+
+    Use this tool when a question requires advanced reasoning, real-time
+    knowledge, or capabilities beyond the local model. Grok is a premium
+    cloud backend — use sparingly and only for high-complexity queries.
+
+    Args:
+        query: The question or reasoning task to send to Grok.
+
+    Returns:
+        Grok's response text, or an error/status message.
+    """
+    from config import settings
+    from timmy.backends import grok_available, get_grok_backend
+
+    if not grok_available():
+        return (
+            "Grok is not available. Enable with GROK_ENABLED=true "
+            "and set XAI_API_KEY in your .env file."
+        )
+
+    backend = get_grok_backend()
+
+    # Log to Spark if available
+    try:
+        from spark.engine import spark_engine
+        spark_engine.on_tool_executed(
+            agent_id="timmy",
+            tool_name="consult_grok",
+            success=True,
+        )
+    except Exception:
+        pass
+
+    # Generate Lightning invoice for monetization (unless free mode)
+    invoice_info = ""
+    if not settings.grok_free:
+        try:
+            from lightning.factory import get_backend as get_ln_backend
+            ln = get_ln_backend()
+            sats = min(settings.grok_max_sats_per_query, 100)
+            inv = ln.create_invoice(sats, f"Grok query: {query[:50]}")
+            invoice_info = f"\n[Lightning invoice: {sats} sats — {inv.payment_request[:40]}...]"
+        except Exception:
+            pass
+
+    result = backend.run(query)
+
+    response = result.content
+    if invoice_info:
+        response += invoice_info
+
+    return response
+
+
 def create_full_toolkit(base_dir: str | Path | None = None):
     """Create a full toolkit with all available tools (for Timmy).
-    
+
     Includes: web search, file read/write, shell commands, python execution,
-    and memory search for contextual recall.
+    memory search for contextual recall, and Grok consultation.
     """
     if not _AGNO_TOOLS_AVAILABLE:
         # Return None when tools aren't available (tests)
         return None
     toolkit = Toolkit(name="full")
-    
+
     # Web search
     search_tools = DuckDuckGoTools()
     toolkit.register(search_tools.web_search, name="web_search")
-    
+
     # Python execution
     python_tools = PythonTools()
     toolkit.register(python_tools.run_python_code, name="python")
-    
+
     # Shell commands
     shell_tools = ShellTools()
     toolkit.register(shell_tools.run_shell_command, name="shell")
-    
+
     # File operations
     base_path = Path(base_dir) if base_dir else Path.cwd()
     file_tools = FileTools(base_dir=base_path)
     toolkit.register(file_tools.read_file, name="read_file")
     toolkit.register(file_tools.save_file, name="write_file")
     toolkit.register(file_tools.list_files, name="list_files")
-    
+
     # Calculator — exact arithmetic (never let the LLM guess)
     toolkit.register(calculator, name="calculator")
 
+    # Grok consultation — premium frontier reasoning (opt-in)
+    try:
+        from timmy.backends import grok_available
+        if grok_available():
+            toolkit.register(consult_grok, name="consult_grok")
+            logger.info("Grok consultation tool registered")
+    except Exception:
+        logger.debug("Grok tool not available")
+
     # Memory search - semantic recall
     try:
         from timmy.semantic_memory import memory_search
@@ -407,11 +472,16 @@ def get_all_available_tools() -> dict[str, dict]:
             "description": "Evaluate mathematical expressions with exact results",
             "available_in": ["timmy"],
         },
+        "consult_grok": {
+            "name": "Consult Grok",
+            "description": "Premium frontier reasoning via xAI Grok (opt-in, Lightning-payable)",
+            "available_in": ["timmy"],
+        },
     }
 
     # ── Git tools ─────────────────────────────────────────────────────────────
     try:
-        from tools.git_tools import GIT_TOOL_CATALOG
+        from creative.tools.git_tools import GIT_TOOL_CATALOG
         for tool_id, info in GIT_TOOL_CATALOG.items():
             catalog[tool_id] = {
                 "name": info["name"],
@@ -423,7 +493,7 @@ def get_all_available_tools() -> dict[str, dict]:
 
     # ── Image tools (Pixel) ───────────────────────────────────────────────────
     try:
-        from tools.image_tools import IMAGE_TOOL_CATALOG
+        from creative.tools.image_tools import IMAGE_TOOL_CATALOG
         for tool_id, info in IMAGE_TOOL_CATALOG.items():
             catalog[tool_id] = {
                 "name": info["name"],
@@ -435,7 +505,7 @@ def get_all_available_tools() -> dict[str, dict]:
 
     # ── Music tools (Lyra) ────────────────────────────────────────────────────
     try:
-        from tools.music_tools import MUSIC_TOOL_CATALOG
+        from creative.tools.music_tools import MUSIC_TOOL_CATALOG
         for tool_id, info in MUSIC_TOOL_CATALOG.items():
             catalog[tool_id] = {
                 "name": info["name"],
@@ -447,7 +517,7 @@ def get_all_available_tools() -> dict[str, dict]:
 
     # ── Video tools (Reel) ────────────────────────────────────────────────────
     try:
-        from tools.video_tools import VIDEO_TOOL_CATALOG
+        from creative.tools.video_tools import VIDEO_TOOL_CATALOG
         for tool_id, info in VIDEO_TOOL_CATALOG.items():
             catalog[tool_id] = {
                 "name": info["name"],
diff --git a/src/timmy_serve/__init__.py b/src/timmy_serve/__init__.py
index 8b137891..38b1c8b6 100644
--- a/src/timmy_serve/__init__.py
+++ b/src/timmy_serve/__init__.py
@@ -1 +1 @@
-
+"""Timmy Serve — L402 Lightning-gated API server (port 8402)."""
diff --git a/src/voice/__init__.py b/src/voice/__init__.py
deleted file mode 100644
index 8b137891..00000000
--- a/src/voice/__init__.py
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/src/ws_manager/__init__.py b/src/ws_manager/__init__.py
deleted file mode 100644
index 8b137891..00000000
--- a/src/ws_manager/__init__.py
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/static/local_llm.js b/static/local_llm.js
new file mode 100644
index 00000000..5580a100
--- /dev/null
+++ b/static/local_llm.js
@@ -0,0 +1,271 @@
+/**
+ * local_llm.js — In-browser LLM inference via WebLLM.
+ *
+ * Loads a small language model directly into the browser using WebGPU
+ * (or WASM fallback) so Timmy can run on an iPhone with zero server
+ * dependency.  Falls back to server-side Ollama when the local model
+ * is unavailable.
+ *
+ * Usage:
+ *   const llm = new LocalLLM({ modelId, onProgress, onReady, onError });
+ *   await llm.init();
+ *   const reply = await llm.chat("Hello Timmy");
+ */
+
+/* global webllm */
+
+// ── Model catalogue ────────────────────────────────────────────────────────
+// Models tested on iPhone 15 Pro / Safari 26+.  Sorted smallest → largest.
+const MODEL_CATALOGUE = [
+  {
+    id: "SmolLM2-360M-Instruct-q4f16_1-MLC",
+    label: "SmolLM2 360M (fast)",
+    sizeHint: "~200 MB",
+    description: "Fastest option. Good for simple Q&A.",
+  },
+  {
+    id: "Qwen2.5-0.5B-Instruct-q4f16_1-MLC",
+    label: "Qwen 2.5 0.5B (balanced)",
+    sizeHint: "~350 MB",
+    description: "Best quality under 500 MB.",
+  },
+  {
+    id: "SmolLM2-1.7B-Instruct-q4f16_1-MLC",
+    label: "SmolLM2 1.7B (smart)",
+    sizeHint: "~1 GB",
+    description: "Highest quality. Needs more memory.",
+  },
+  {
+    id: "Llama-3.2-1B-Instruct-q4f16_1-MLC",
+    label: "Llama 3.2 1B",
+    sizeHint: "~700 MB",
+    description: "Meta's compact model. Good all-rounder.",
+  },
+];
+
+// ── Capability detection ──────────────────────────────────────────────────
+function detectWebGPU() {
+  return typeof navigator !== "undefined" && "gpu" in navigator;
+}
+
+function detectWASM() {
+  try {
+    return typeof WebAssembly === "object" && typeof WebAssembly.instantiate === "function";
+  } catch {
+    return false;
+  }
+}
+
+// ── LocalLLM class ────────────────────────────────────────────────────────
+class LocalLLM {
+  /**
+   * @param {object}   opts
+   * @param {string}   opts.modelId     — WebLLM model ID
+   * @param {function} opts.onProgress  — (report) progress during download
+   * @param {function} opts.onReady     — () called when model is loaded
+   * @param {function} opts.onError     — (error) called on fatal error
+   * @param {string}   opts.systemPrompt — system message for the model
+   */
+  constructor(opts = {}) {
+    this.modelId = opts.modelId || "SmolLM2-360M-Instruct-q4f16_1-MLC";
+    this.onProgress = opts.onProgress || (() => {});
+    this.onReady = opts.onReady || (() => {});
+    this.onError = opts.onError || (() => {});
+    this.systemPrompt =
+      opts.systemPrompt ||
+      "You are Timmy, a sovereign AI assistant. You are helpful, concise, and loyal. " +
+      "Address the user as 'Sir' when appropriate. Keep responses brief on mobile.";
+
+    this.engine = null;
+    this.ready = false;
+    this.loading = false;
+    this._hasWebGPU = detectWebGPU();
+    this._hasWASM = detectWASM();
+  }
+
+  /** Check if local inference is possible on this device. */
+  static isSupported() {
+    return detectWebGPU() || detectWASM();
+  }
+
+  /** Return the model catalogue for UI rendering. */
+  static getCatalogue() {
+    return MODEL_CATALOGUE;
+  }
+
+  /** Return runtime capability info. */
+  getCapabilities() {
+    return {
+      webgpu: this._hasWebGPU,
+      wasm: this._hasWASM,
+      supported: this._hasWebGPU || this._hasWASM,
+      backend: this._hasWebGPU ? "WebGPU" : this._hasWASM ? "WASM" : "none",
+    };
+  }
+
+  /**
+   * Initialize the engine and download/cache the model.
+   * Model weights are cached in the browser's Cache API so subsequent
+   * loads are nearly instant.
+   */
+  async init() {
+    if (this.ready) return;
+    if (this.loading) return;
+
+    if (!this._hasWebGPU && !this._hasWASM) {
+      const err = new Error(
+        "Neither WebGPU nor WebAssembly is available. " +
+        "Update to iOS 26+ / Safari 26+ for WebGPU support."
+      );
+      this.onError(err);
+      throw err;
+    }
+
+    this.loading = true;
+
+    try {
+      // Dynamic import of WebLLM from CDN (avoids bundling)
+      if (typeof webllm === "undefined") {
+        await this._loadWebLLMScript();
+      }
+
+      const initProgressCallback = (report) => {
+        this.onProgress(report);
+      };
+
+      this.engine = await webllm.CreateMLCEngine(this.modelId, {
+        initProgressCallback,
+      });
+
+      this.ready = true;
+      this.loading = false;
+      this.onReady();
+    } catch (err) {
+      this.loading = false;
+      this.ready = false;
+      this.onError(err);
+      throw err;
+    }
+  }
+
+  /**
+   * Send a chat message and get a response.
+   * @param {string} userMessage
+   * @param {object} opts
+   * @param {function} opts.onToken — streaming callback (delta)
+   * @returns {Promise<string>} full response text
+   */
+  async chat(userMessage, opts = {}) {
+    if (!this.ready) {
+      throw new Error("Model not loaded. Call init() first.");
+    }
+
+    const messages = [
+      { role: "system", content: this.systemPrompt },
+      { role: "user", content: userMessage },
+    ];
+
+    if (opts.onToken) {
+      // Streaming mode
+      let fullText = "";
+      const chunks = await this.engine.chat.completions.create({
+        messages,
+        stream: true,
+        temperature: 0.7,
+        max_tokens: 512,
+      });
+
+      for await (const chunk of chunks) {
+        const delta = chunk.choices[0]?.delta?.content || "";
+        fullText += delta;
+        opts.onToken(delta, fullText);
+      }
+      return fullText;
+    }
+
+    // Non-streaming mode
+    const response = await this.engine.chat.completions.create({
+      messages,
+      temperature: 0.7,
+      max_tokens: 512,
+    });
+
+    return response.choices[0]?.message?.content || "";
+  }
+
+  /** Reset conversation context. */
+  async resetChat() {
+    if (this.engine) {
+      await this.engine.resetChat();
+    }
+  }
+
+  /** Unload the model and free memory. */
+  async unload() {
+    if (this.engine) {
+      await this.engine.unload();
+      this.engine = null;
+      this.ready = false;
+    }
+  }
+
+  /** Get current engine stats (tokens/sec, memory, etc). */
+  async getStats() {
+    if (!this.engine) return null;
+    try {
+      const stats = await this.engine.runtimeStatsText();
+      return stats;
+    } catch {
+      return null;
+    }
+  }
+
+  // ── Private ─────────────────────────────────────────────────────────────
+
+  /** Load the WebLLM script from CDN. */
+  _loadWebLLMScript() {
+    return new Promise((resolve, reject) => {
+      // Check if already loaded
+      if (typeof webllm !== "undefined") {
+        resolve();
+        return;
+      }
+      const script = document.createElement("script");
+      script.src =
+        "https://esm.run/@anthropic-ai/sdk" !== script.src
+          ? "https://esm.run/@anthropic-ai/sdk"
+          : "";
+      // Use the WebLLM CDN bundle
+      script.type = "module";
+      script.textContent = `
+        import * as webllmModule from "https://esm.run/@mlc-ai/web-llm";
+        window.webllm = webllmModule;
+        window.dispatchEvent(new Event("webllm-loaded"));
+      `;
+      document.head.appendChild(script);
+
+      const onLoaded = () => {
+        window.removeEventListener("webllm-loaded", onLoaded);
+        resolve();
+      };
+      window.addEventListener("webllm-loaded", onLoaded);
+
+      // Fallback: also try the UMD bundle approach
+      const fallbackScript = document.createElement("script");
+      fallbackScript.src = "https://cdn.jsdelivr.net/npm/@mlc-ai/web-llm@0.2.80/lib/index.min.js";
+      fallbackScript.onload = () => {
+        if (typeof webllm !== "undefined") {
+          resolve();
+        }
+      };
+      fallbackScript.onerror = () => {
+        reject(new Error("Failed to load WebLLM library from CDN."));
+      };
+      document.head.appendChild(fallbackScript);
+    });
+  }
+}
+
+// Export for use in templates
+window.LocalLLM = LocalLLM;
+window.LOCAL_MODEL_CATALOGUE = MODEL_CATALOGUE;
diff --git a/tests/conftest.py b/tests/conftest.py
index c875503f..79d45767 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -33,6 +33,9 @@ for _mod in [
     # pyzbar is optional (for QR code invite detection)
     "pyzbar",
     "pyzbar.pyzbar",
+    # requests is optional — used by reward scoring (swarm.learner) to call
+    # Ollama directly; stub so patch("requests.post") works in tests.
+    "requests",
 ]:
     sys.modules.setdefault(_mod, MagicMock())
 
diff --git a/src/self_modify/__init__.py b/tests/creative/__init__.py
similarity index 100%
rename from src/self_modify/__init__.py
rename to tests/creative/__init__.py
diff --git a/tests/test_assembler.py b/tests/creative/test_assembler.py
similarity index 100%
rename from tests/test_assembler.py
rename to tests/creative/test_assembler.py
diff --git a/tests/test_assembler_integration.py b/tests/creative/test_assembler_integration.py
similarity index 100%
rename from tests/test_assembler_integration.py
rename to tests/creative/test_assembler_integration.py
diff --git a/tests/test_creative_director.py b/tests/creative/test_creative_director.py
similarity index 94%
rename from tests/test_creative_director.py
rename to tests/creative/test_creative_director.py
index 4de12317..1166330d 100644
--- a/tests/test_creative_director.py
+++ b/tests/creative/test_creative_director.py
@@ -113,7 +113,7 @@ class TestRunStoryboard:
                 {"path": "/fake/3.png", "scene_index": 2, "prompt": "sunset"},
             ],
         }
-        with patch("tools.image_tools.generate_storyboard", return_value=mock_result):
+        with patch("creative.tools.image_tools.generate_storyboard", return_value=mock_result):
             with patch("creative.director._save_project"):
                 result = run_storyboard(sample_project)
         assert result["success"]
@@ -130,7 +130,7 @@ class TestRunMusic:
             "success": True, "path": "/fake/song.wav",
             "genre": "pop", "duration": 60,
         }
-        with patch("tools.music_tools.generate_song", return_value=mock_result):
+        with patch("creative.tools.music_tools.generate_song", return_value=mock_result):
             with patch("creative.director._save_project"):
                 result = run_music(sample_project, genre="pop")
         assert result["success"]
@@ -147,8 +147,8 @@ class TestRunVideoGeneration:
             "success": True, "path": "/fake/clip.mp4",
             "duration": 5,
         }
-        with patch("tools.video_tools.generate_video_clip", return_value=mock_clip):
-            with patch("tools.video_tools.image_to_video", return_value=mock_clip):
+        with patch("creative.tools.video_tools.generate_video_clip", return_value=mock_clip):
+            with patch("creative.tools.video_tools.image_to_video", return_value=mock_clip):
                 with patch("creative.director._save_project"):
                     result = run_video_generation(sample_project)
         assert result["success"]
diff --git a/tests/test_creative_route.py b/tests/creative/test_creative_route.py
similarity index 100%
rename from tests/test_creative_route.py
rename to tests/creative/test_creative_route.py
diff --git a/tests/test_image_tools.py b/tests/creative/test_image_tools.py
similarity index 85%
rename from tests/test_image_tools.py
rename to tests/creative/test_image_tools.py
index 2cc05d0d..25ebd1e2 100644
--- a/tests/test_image_tools.py
+++ b/tests/creative/test_image_tools.py
@@ -8,7 +8,7 @@ import pytest
 from unittest.mock import patch, MagicMock
 from pathlib import Path
 
-from tools.image_tools import (
+from creative.tools.image_tools import (
     IMAGE_TOOL_CATALOG,
     generate_image,
     generate_storyboard,
@@ -47,8 +47,8 @@ class TestSaveMetadata:
 class TestGenerateImageInterface:
     def test_raises_without_creative_deps(self):
         """generate_image raises ImportError when diffusers not available."""
-        with patch("tools.image_tools._pipeline", None):
-            with patch("tools.image_tools._get_pipeline", side_effect=ImportError("no diffusers")):
+        with patch("creative.tools.image_tools._pipeline", None):
+            with patch("creative.tools.image_tools._get_pipeline", side_effect=ImportError("no diffusers")):
                 with pytest.raises(ImportError):
                     generate_image("a cat")
 
@@ -67,8 +67,8 @@ class TestGenerateImageInterface:
         mock_torch.Generator.return_value = MagicMock()
 
         with patch.dict(sys.modules, {"torch": mock_torch}):
-            with patch("tools.image_tools._get_pipeline", return_value=mock_pipe):
-                with patch("tools.image_tools._output_dir", return_value=tmp_path):
+            with patch("creative.tools.image_tools._get_pipeline", return_value=mock_pipe):
+                with patch("creative.tools.image_tools._output_dir", return_value=tmp_path):
                     result = generate_image("a cat", width=512, height=512, steps=1)
 
         assert result["success"]
@@ -90,7 +90,7 @@ class TestGenerateStoryboardInterface:
                 "id": str(call_count), "prompt": prompt,
             }
 
-        with patch("tools.image_tools.generate_image", side_effect=mock_gen_image):
+        with patch("creative.tools.image_tools.generate_image", side_effect=mock_gen_image):
             result = generate_storyboard(
                 ["sunrise", "mountain peak", "sunset"],
                 steps=1,
@@ -112,7 +112,7 @@ class TestImageVariationsInterface:
                 "seed": kwargs.get("seed"),
             }
 
-        with patch("tools.image_tools.generate_image", side_effect=mock_gen_image):
+        with patch("creative.tools.image_tools.generate_image", side_effect=mock_gen_image):
             result = image_variations("a dog", count=3, steps=1)
 
         assert result["success"]
diff --git a/tests/test_music_tools.py b/tests/creative/test_music_tools.py
similarity index 77%
rename from tests/test_music_tools.py
rename to tests/creative/test_music_tools.py
index cf258e4b..a45d498d 100644
--- a/tests/test_music_tools.py
+++ b/tests/creative/test_music_tools.py
@@ -7,7 +7,7 @@ metadata tests run in CI.
 import pytest
 from unittest.mock import patch, MagicMock
 
-from tools.music_tools import (
+from creative.tools.music_tools import (
     MUSIC_TOOL_CATALOG,
     GENRES,
     list_genres,
@@ -50,8 +50,8 @@ class TestGenres:
 
 class TestGenerateSongInterface:
     def test_raises_without_ace_step(self):
-        with patch("tools.music_tools._model", None):
-            with patch("tools.music_tools._get_model", side_effect=ImportError("no ace-step")):
+        with patch("creative.tools.music_tools._model", None):
+            with patch("creative.tools.music_tools._get_model", side_effect=ImportError("no ace-step")):
                 with pytest.raises(ImportError):
                     generate_song("la la la")
 
@@ -63,9 +63,9 @@ class TestGenerateSongInterface:
         mock_model = MagicMock()
         mock_model.generate.return_value = mock_audio
 
-        with patch("tools.music_tools._get_model", return_value=mock_model):
-            with patch("tools.music_tools._output_dir", return_value=MagicMock()):
-                with patch("tools.music_tools._save_metadata"):
+        with patch("creative.tools.music_tools._get_model", return_value=mock_model):
+            with patch("creative.tools.music_tools._output_dir", return_value=MagicMock()):
+                with patch("creative.tools.music_tools._save_metadata"):
                     # Should clamp 5 to 30
                     generate_song("lyrics", duration=5)
                     call_kwargs = mock_model.generate.call_args[1]
@@ -78,8 +78,8 @@ class TestGenerateSongInterface:
         mock_model = MagicMock()
         mock_model.generate.return_value = mock_audio
 
-        with patch("tools.music_tools._get_model", return_value=mock_model):
-            with patch("tools.music_tools._output_dir", return_value=tmp_path):
+        with patch("creative.tools.music_tools._get_model", return_value=mock_model):
+            with patch("creative.tools.music_tools._output_dir", return_value=tmp_path):
                 result = generate_song(
                     "hello world", genre="rock", duration=60, title="Test Song"
                 )
@@ -98,8 +98,8 @@ class TestGenerateInstrumentalInterface:
         mock_model = MagicMock()
         mock_model.generate.return_value = mock_audio
 
-        with patch("tools.music_tools._get_model", return_value=mock_model):
-            with patch("tools.music_tools._output_dir", return_value=tmp_path):
+        with patch("creative.tools.music_tools._get_model", return_value=mock_model):
+            with patch("creative.tools.music_tools._output_dir", return_value=tmp_path):
                 result = generate_instrumental("epic orchestral", genre="cinematic")
 
         assert result["success"]
@@ -115,8 +115,8 @@ class TestGenerateVocalsInterface:
         mock_model = MagicMock()
         mock_model.generate.return_value = mock_audio
 
-        with patch("tools.music_tools._get_model", return_value=mock_model):
-            with patch("tools.music_tools._output_dir", return_value=tmp_path):
+        with patch("creative.tools.music_tools._get_model", return_value=mock_model):
+            with patch("creative.tools.music_tools._output_dir", return_value=tmp_path):
                 result = generate_vocals("do re mi", style="jazz")
 
         assert result["success"]
diff --git a/tests/test_music_video_integration.py b/tests/creative/test_music_video_integration.py
similarity index 97%
rename from tests/test_music_video_integration.py
rename to tests/creative/test_music_video_integration.py
index 2294a227..4d170392 100644
--- a/tests/test_music_video_integration.py
+++ b/tests/creative/test_music_video_integration.py
@@ -306,13 +306,13 @@ class TestCreativeDirectorPipeline:
         assembly_dir.mkdir()
 
         with (
-            patch("tools.image_tools.generate_storyboard",
+            patch("creative.tools.image_tools.generate_storyboard",
                   side_effect=self._make_storyboard_stub(frames_dir)),
-            patch("tools.music_tools.generate_song",
+            patch("creative.tools.music_tools.generate_song",
                   side_effect=self._make_song_stub(audio_dir)),
-            patch("tools.video_tools.image_to_video",
+            patch("creative.tools.video_tools.image_to_video",
                   side_effect=self._make_video_stub(clips_dir)),
-            patch("tools.video_tools.generate_video_clip",
+            patch("creative.tools.video_tools.generate_video_clip",
                   side_effect=self._make_video_stub(clips_dir)),
             patch("creative.director._project_dir",
                   return_value=tmp_path / "project"),
@@ -375,7 +375,7 @@ class TestCreativeDirectorPipeline:
 
         # 2. Storyboard
         with (
-            patch("tools.image_tools.generate_storyboard",
+            patch("creative.tools.image_tools.generate_storyboard",
                   side_effect=self._make_storyboard_stub(frames_dir)),
             patch("creative.director._save_project"),
         ):
@@ -385,7 +385,7 @@ class TestCreativeDirectorPipeline:
 
         # 3. Music
         with (
-            patch("tools.music_tools.generate_song",
+            patch("creative.tools.music_tools.generate_song",
                   side_effect=self._make_song_stub(audio_dir)),
             patch("creative.director._save_project"),
         ):
@@ -400,7 +400,7 @@ class TestCreativeDirectorPipeline:
 
         # 4. Video generation (uses storyboard frames → image_to_video)
         with (
-            patch("tools.video_tools.image_to_video",
+            patch("creative.tools.video_tools.image_to_video",
                   side_effect=self._make_video_stub(clips_dir)),
             patch("creative.director._save_project"),
         ):
diff --git a/tests/test_video_tools.py b/tests/creative/test_video_tools.py
similarity index 77%
rename from tests/test_video_tools.py
rename to tests/creative/test_video_tools.py
index e3b282af..2836cad5 100644
--- a/tests/test_video_tools.py
+++ b/tests/creative/test_video_tools.py
@@ -7,7 +7,7 @@ resolution preset tests run in CI.
 import pytest
 from unittest.mock import patch, MagicMock
 
-from tools.video_tools import (
+from creative.tools.video_tools import (
     VIDEO_TOOL_CATALOG,
     RESOLUTION_PRESETS,
     VIDEO_STYLES,
@@ -55,8 +55,8 @@ class TestListVideoStyles:
 
 class TestGenerateVideoClipInterface:
     def test_raises_without_creative_deps(self):
-        with patch("tools.video_tools._t2v_pipeline", None):
-            with patch("tools.video_tools._get_t2v_pipeline", side_effect=ImportError("no diffusers")):
+        with patch("creative.tools.video_tools._t2v_pipeline", None):
+            with patch("creative.tools.video_tools._get_t2v_pipeline", side_effect=ImportError("no diffusers")):
                 with pytest.raises(ImportError):
                     generate_video_clip("a sunset")
 
@@ -77,17 +77,17 @@ class TestGenerateVideoClipInterface:
         out_dir.__truediv__ = MagicMock(return_value=MagicMock(__str__=lambda s: "/fake/clip.mp4"))
 
         with patch.dict(sys.modules, {"torch": mock_torch}):
-            with patch("tools.video_tools._get_t2v_pipeline", return_value=mock_pipe):
-                with patch("tools.video_tools._export_frames_to_mp4"):
-                    with patch("tools.video_tools._output_dir", return_value=out_dir):
-                        with patch("tools.video_tools._save_metadata"):
+            with patch("creative.tools.video_tools._get_t2v_pipeline", return_value=mock_pipe):
+                with patch("creative.tools.video_tools._export_frames_to_mp4"):
+                    with patch("creative.tools.video_tools._output_dir", return_value=out_dir):
+                        with patch("creative.tools.video_tools._save_metadata"):
                             result = generate_video_clip("test", duration=50)
                             assert result["duration"] == 10  # clamped
 
 
 class TestImageToVideoInterface:
     def test_raises_without_creative_deps(self):
-        with patch("tools.video_tools._t2v_pipeline", None):
-            with patch("tools.video_tools._get_t2v_pipeline", side_effect=ImportError("no diffusers")):
+        with patch("creative.tools.video_tools._t2v_pipeline", None):
+            with patch("creative.tools.video_tools._get_t2v_pipeline", side_effect=ImportError("no diffusers")):
                 with pytest.raises(ImportError):
                     image_to_video("/fake/image.png", "animate")
diff --git a/src/self_tdd/__init__.py b/tests/dashboard/__init__.py
similarity index 100%
rename from src/self_tdd/__init__.py
rename to tests/dashboard/__init__.py
diff --git a/tests/test_briefing.py b/tests/dashboard/test_briefing.py
similarity index 96%
rename from tests/test_briefing.py
rename to tests/dashboard/test_briefing.py
index c239bf5e..db1de248 100644
--- a/tests/test_briefing.py
+++ b/tests/dashboard/test_briefing.py
@@ -235,11 +235,11 @@ def test_call_agent_falls_back_on_exception(engine):
 @pytest.mark.asyncio
 async def test_notify_briefing_ready_skips_when_no_approvals(caplog):
     """notify_briefing_ready should NOT fire native notification with 0 approvals."""
-    from notifications.push import notify_briefing_ready
+    from infrastructure.notifications.push import notify_briefing_ready
 
     b = _make_briefing()  # approval_items=[]
 
-    with patch("notifications.push.notifier") as mock_notifier:
+    with patch("infrastructure.notifications.push.notifier") as mock_notifier:
         await notify_briefing_ready(b)
         mock_notifier.notify.assert_not_called()
 
@@ -247,7 +247,7 @@ async def test_notify_briefing_ready_skips_when_no_approvals(caplog):
 @pytest.mark.asyncio
 async def test_notify_briefing_ready_fires_when_approvals_exist():
     """notify_briefing_ready should fire when there are pending approval items."""
-    from notifications.push import notify_briefing_ready
+    from infrastructure.notifications.push import notify_briefing_ready
     from timmy.briefing import ApprovalItem
 
     b = _make_briefing()
@@ -263,7 +263,7 @@ async def test_notify_briefing_ready_fires_when_approvals_exist():
         ),
     ]
 
-    with patch("notifications.push.notifier") as mock_notifier:
+    with patch("infrastructure.notifications.push.notifier") as mock_notifier:
         await notify_briefing_ready(b)
         mock_notifier.notify.assert_called_once()
         call_kwargs = mock_notifier.notify.call_args
diff --git a/tests/test_dashboard.py b/tests/dashboard/test_dashboard.py
similarity index 100%
rename from tests/test_dashboard.py
rename to tests/dashboard/test_dashboard.py
diff --git a/tests/test_dashboard_routes.py b/tests/dashboard/test_dashboard_routes.py
similarity index 100%
rename from tests/test_dashboard_routes.py
rename to tests/dashboard/test_dashboard_routes.py
diff --git a/tests/test_integration_full.py b/tests/dashboard/test_integration_full.py
similarity index 97%
rename from tests/test_integration_full.py
rename to tests/dashboard/test_integration_full.py
index 0a3b134b..4c0a2409 100644
--- a/tests/test_integration_full.py
+++ b/tests/dashboard/test_integration_full.py
@@ -107,7 +107,7 @@ class TestEventBusIntegration:
     @pytest.mark.asyncio
     async def test_event_bus_publish_subscribe(self):
         """Test event bus publish and subscribe works."""
-        from events.bus import EventBus, Event
+        from infrastructure.events.bus import EventBus, Event
         
         bus = EventBus()
         events_received = []
@@ -135,7 +135,7 @@ class TestAgentSystemIntegration:
     
     def test_base_agent_imports(self):
         """Test that base agent can be imported."""
-        from agents.base import BaseAgent
+        from timmy.agents.base import BaseAgent
         
         assert BaseAgent is not None
     
diff --git a/tests/test_ledger.py b/tests/dashboard/test_ledger.py
similarity index 100%
rename from tests/test_ledger.py
rename to tests/dashboard/test_ledger.py
diff --git a/tests/dashboard/test_local_models.py b/tests/dashboard/test_local_models.py
new file mode 100644
index 00000000..41f924da
--- /dev/null
+++ b/tests/dashboard/test_local_models.py
@@ -0,0 +1,246 @@
+"""Tests for the local browser model feature — /mobile/local endpoint.
+
+Categories:
+  L1xx  Route & API responses
+  L2xx  Config settings
+  L3xx  Template content & UX
+  L4xx  JavaScript asset
+  L5xx  Security (XSS prevention)
+"""
+
+import re
+from pathlib import Path
+
+
+# ── helpers ──────────────────────────────────────────────────────────────────
+
+def _local_html(client) -> str:
+    return client.get("/mobile/local").text
+
+
+def _local_llm_js() -> str:
+    js_path = Path(__file__).parent.parent.parent / "static" / "local_llm.js"
+    return js_path.read_text()
+
+
+# ── L1xx — Route & API responses ─────────────────────────────────────────────
+
+def test_L101_mobile_local_route_returns_200(client):
+    """The /mobile/local endpoint should return 200 OK."""
+    response = client.get("/mobile/local")
+    assert response.status_code == 200
+
+
+def test_L102_local_models_config_endpoint(client):
+    """The /mobile/local-models API should return model config JSON."""
+    response = client.get("/mobile/local-models")
+    assert response.status_code == 200
+    data = response.json()
+    assert "enabled" in data
+    assert "default_model" in data
+    assert "fallback_to_server" in data
+    assert "server_model" in data
+
+
+def test_L103_mobile_status_includes_browser_model(client):
+    """The /mobile/status endpoint should include browser model info."""
+    response = client.get("/mobile/status")
+    assert response.status_code == 200
+    data = response.json()
+    assert "browser_model_enabled" in data
+    assert "browser_model_id" in data
+
+
+def test_L104_local_models_config_default_values(client):
+    """Config defaults should match what's in config.py."""
+    data = client.get("/mobile/local-models").json()
+    assert data["enabled"] is True
+    assert "SmolLM2" in data["default_model"] or "MLC" in data["default_model"]
+    assert data["fallback_to_server"] is True
+
+
+# ── L2xx — Config settings ───────────────────────────────────────────────────
+
+def test_L201_config_has_browser_model_enabled():
+    """config.py should define browser_model_enabled."""
+    from config import settings
+    assert hasattr(settings, "browser_model_enabled")
+    assert isinstance(settings.browser_model_enabled, bool)
+
+
+def test_L202_config_has_browser_model_id():
+    """config.py should define browser_model_id."""
+    from config import settings
+    assert hasattr(settings, "browser_model_id")
+    assert isinstance(settings.browser_model_id, str)
+    assert len(settings.browser_model_id) > 0
+
+
+def test_L203_config_has_browser_model_fallback():
+    """config.py should define browser_model_fallback."""
+    from config import settings
+    assert hasattr(settings, "browser_model_fallback")
+    assert isinstance(settings.browser_model_fallback, bool)
+
+
+# ── L3xx — Template content & UX ────────────────────────────────────────────
+
+def test_L301_template_includes_local_llm_script(client):
+    """mobile_local.html must include the local_llm.js script."""
+    html = _local_html(client)
+    assert "local_llm.js" in html
+
+
+def test_L302_template_has_model_selector(client):
+    """Template must have a model selector element."""
+    html = _local_html(client)
+    assert 'id="model-select"' in html
+
+
+def test_L303_template_has_load_button(client):
+    """Template must have a load model button."""
+    html = _local_html(client)
+    assert 'id="btn-load"' in html
+
+
+def test_L304_template_has_progress_bar(client):
+    """Template must have a progress bar for model download."""
+    html = _local_html(client)
+    assert 'id="progress-bar"' in html
+
+
+def test_L305_template_has_chat_area(client):
+    """Template must have a chat log area."""
+    html = _local_html(client)
+    assert 'id="local-chat"' in html
+
+
+def test_L306_template_has_message_input(client):
+    """Template must have a message input field."""
+    html = _local_html(client)
+    assert 'id="local-message"' in html
+
+
+def test_L307_input_font_size_16px(client):
+    """Input font-size must be 16px to prevent iOS zoom."""
+    html = _local_html(client)
+    assert "font-size: 16px" in html
+
+
+def test_L308_input_has_ios_attributes(client):
+    """Input should have autocapitalize, autocorrect, spellcheck, enterkeyhint."""
+    html = _local_html(client)
+    assert 'autocapitalize="none"' in html
+    assert 'autocorrect="off"' in html
+    assert 'spellcheck="false"' in html
+    assert 'enterkeyhint="send"' in html
+
+
+def test_L309_touch_targets_44px(client):
+    """Buttons and inputs must meet 44px min-height (Apple HIG)."""
+    html = _local_html(client)
+    assert "min-height: 44px" in html
+
+
+def test_L310_safe_area_inset_bottom(client):
+    """Chat input must account for iPhone home indicator."""
+    html = _local_html(client)
+    assert "safe-area-inset-bottom" in html
+
+
+def test_L311_template_has_backend_badge(client):
+    """Template should show LOCAL or SERVER badge."""
+    html = _local_html(client)
+    assert "backend-badge" in html
+    assert "LOCAL" in html
+
+
+# ── L4xx — JavaScript asset ──────────────────────────────────────────────────
+
+def test_L401_local_llm_js_exists():
+    """static/local_llm.js must exist."""
+    js_path = Path(__file__).parent.parent.parent / "static" / "local_llm.js"
+    assert js_path.exists(), "static/local_llm.js not found"
+
+
+def test_L402_local_llm_js_defines_class():
+    """local_llm.js must define the LocalLLM class."""
+    js = _local_llm_js()
+    assert "class LocalLLM" in js
+
+
+def test_L403_local_llm_js_has_model_catalogue():
+    """local_llm.js must define a MODEL_CATALOGUE."""
+    js = _local_llm_js()
+    assert "MODEL_CATALOGUE" in js
+
+
+def test_L404_local_llm_js_has_webgpu_detection():
+    """local_llm.js must detect WebGPU capability."""
+    js = _local_llm_js()
+    assert "detectWebGPU" in js or "navigator.gpu" in js
+
+
+def test_L405_local_llm_js_has_chat_method():
+    """local_llm.js LocalLLM class must have a chat method."""
+    js = _local_llm_js()
+    assert "async chat(" in js
+
+
+def test_L406_local_llm_js_has_init_method():
+    """local_llm.js LocalLLM class must have an init method."""
+    js = _local_llm_js()
+    assert "async init(" in js
+
+
+def test_L407_local_llm_js_has_unload_method():
+    """local_llm.js LocalLLM class must have an unload method."""
+    js = _local_llm_js()
+    assert "async unload(" in js
+
+
+def test_L408_local_llm_js_exports_to_window():
+    """local_llm.js must export LocalLLM and catalogue to window."""
+    js = _local_llm_js()
+    assert "window.LocalLLM" in js
+    assert "window.LOCAL_MODEL_CATALOGUE" in js
+
+
+def test_L409_local_llm_js_has_streaming_support():
+    """local_llm.js chat method must support streaming via onToken."""
+    js = _local_llm_js()
+    assert "onToken" in js
+    assert "stream: true" in js
+
+
+def test_L410_local_llm_js_has_isSupported_static():
+    """LocalLLM must have a static isSupported() method."""
+    js = _local_llm_js()
+    assert "static isSupported()" in js
+
+
+# ── L5xx — Security ─────────────────────────────────────────────────────────
+
+def test_L501_no_innerhtml_with_user_input(client):
+    """Template must not use innerHTML with user-controlled data."""
+    html = _local_html(client)
+    # Check for dangerous patterns: innerHTML += `${message}` etc.
+    blocks = re.findall(r"innerHTML\s*\+=?\s*`([^`]*)`", html, re.DOTALL)
+    for block in blocks:
+        assert "${message}" not in block, (
+            "innerHTML template literal contains ${message} — XSS vulnerability"
+        )
+
+
+def test_L502_uses_textcontent_for_messages(client):
+    """Template must use textContent (not innerHTML) for user messages."""
+    html = _local_html(client)
+    assert "textContent" in html
+
+
+def test_L503_no_eval_or_function_constructor():
+    """local_llm.js must not use eval() or new Function()."""
+    js = _local_llm_js()
+    # Allow "evaluate" and "functionality" but not standalone eval(
+    assert "eval(" not in js or "evaluate" in js
+    assert "new Function(" not in js
diff --git a/tests/test_mission_control.py b/tests/dashboard/test_mission_control.py
similarity index 100%
rename from tests/test_mission_control.py
rename to tests/dashboard/test_mission_control.py
diff --git a/tests/test_mobile_scenarios.py b/tests/dashboard/test_mobile_scenarios.py
similarity index 97%
rename from tests/test_mobile_scenarios.py
rename to tests/dashboard/test_mobile_scenarios.py
index 050a1b43..b3ea34a5 100644
--- a/tests/test_mobile_scenarios.py
+++ b/tests/dashboard/test_mobile_scenarios.py
@@ -22,7 +22,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
 
 def _css() -> str:
     """Read the main stylesheet."""
-    css_path = Path(__file__).parent.parent / "static" / "style.css"
+    css_path = Path(__file__).parent.parent.parent / "static" / "style.css"
     return css_path.read_text()
 
 
@@ -290,13 +290,13 @@ def test_M605_health_status_passes_model_to_template(client):
 
 def _mobile_html() -> str:
     """Read the mobile template source."""
-    path = Path(__file__).parent.parent / "src" / "dashboard" / "templates" / "mobile.html"
+    path = Path(__file__).parent.parent.parent / "src" / "dashboard" / "templates" / "mobile.html"
     return path.read_text()
 
 
 def _swarm_live_html() -> str:
     """Read the swarm live template source."""
-    path = Path(__file__).parent.parent / "src" / "dashboard" / "templates" / "swarm_live.html"
+    path = Path(__file__).parent.parent.parent / "src" / "dashboard" / "templates" / "swarm_live.html"
     return path.read_text()
 
 
diff --git a/tests/test_routes_tools.py b/tests/dashboard/test_routes_tools.py
similarity index 100%
rename from tests/test_routes_tools.py
rename to tests/dashboard/test_routes_tools.py
diff --git a/tests/functional/conftest.py b/tests/functional/conftest.py
index 02c226bc..cfe5cefc 100644
--- a/tests/functional/conftest.py
+++ b/tests/functional/conftest.py
@@ -112,7 +112,7 @@ def serve_runner():
 def self_tdd_runner():
     """Typer CLI runner for self-tdd CLI tests."""
     from typer.testing import CliRunner
-    from self_tdd.cli import app
+    from self_coding.self_tdd.cli import app
     yield CliRunner(), app
 
 
@@ -142,9 +142,9 @@ def serve_client():
 @pytest.fixture
 def tdd_runner():
     """Alias for self_tdd_runner fixture."""
-    pytest.importorskip("self_tdd.cli", reason="self_tdd CLI not available")
+    pytest.importorskip("self_coding.self_tdd.cli", reason="self_tdd CLI not available")
     from typer.testing import CliRunner
-    from self_tdd.cli import app
+    from self_coding.self_tdd.cli import app
     yield CliRunner(), app
 
 
diff --git a/src/telegram_bot/__init__.py b/tests/hands/__init__.py
similarity index 100%
rename from src/telegram_bot/__init__.py
rename to tests/hands/__init__.py
diff --git a/tests/test_hands.py b/tests/hands/test_hands.py
similarity index 100%
rename from tests/test_hands.py
rename to tests/hands/test_hands.py
diff --git a/tests/test_hands_oracle_sentinel.py b/tests/hands/test_hands_oracle_sentinel.py
similarity index 100%
rename from tests/test_hands_oracle_sentinel.py
rename to tests/hands/test_hands_oracle_sentinel.py
diff --git a/tests/test_hands_phase5.py b/tests/hands/test_hands_phase5.py
similarity index 100%
rename from tests/test_hands_phase5.py
rename to tests/hands/test_hands_phase5.py
diff --git a/tests/infrastructure/__init__.py b/tests/infrastructure/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/tests/test_functional_router.py b/tests/infrastructure/test_functional_router.py
similarity index 98%
rename from tests/test_functional_router.py
rename to tests/infrastructure/test_functional_router.py
index 2e0ad27c..4b0199e0 100644
--- a/tests/test_functional_router.py
+++ b/tests/infrastructure/test_functional_router.py
@@ -10,7 +10,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 
-from router.cascade import CascadeRouter, Provider, ProviderStatus, CircuitState
+from infrastructure.router.cascade import CascadeRouter, Provider, ProviderStatus, CircuitState
 
 
 class TestCascadeRouterFunctional:
diff --git a/tests/infrastructure/test_model_registry.py b/tests/infrastructure/test_model_registry.py
new file mode 100644
index 00000000..d8e70d4d
--- /dev/null
+++ b/tests/infrastructure/test_model_registry.py
@@ -0,0 +1,217 @@
+"""Tests for the custom model registry."""
+
+import sqlite3
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from infrastructure.models.registry import (
+    CustomModel,
+    ModelFormat,
+    ModelRegistry,
+    ModelRole,
+)
+
+
+@pytest.fixture
+def registry(tmp_path):
+    """Create a fresh ModelRegistry backed by a temporary database."""
+    db = tmp_path / "test.db"
+    with patch("infrastructure.models.registry.DB_PATH", db):
+        reg = ModelRegistry()
+        yield reg
+
+
+@pytest.fixture
+def sample_model():
+    """A sample CustomModel for testing."""
+    return CustomModel(
+        name="test-llama",
+        format=ModelFormat.OLLAMA,
+        path="llama3.2",
+        role=ModelRole.GENERAL,
+        context_window=8192,
+        description="Test model",
+    )
+
+
+@pytest.fixture
+def reward_model():
+    """A sample reward model."""
+    return CustomModel(
+        name="test-reward",
+        format=ModelFormat.OLLAMA,
+        path="deepseek-r1:1.5b",
+        role=ModelRole.REWARD,
+        context_window=32000,
+        description="Test reward model",
+    )
+
+
+class TestModelCRUD:
+    """Test model registration, lookup, and removal."""
+
+    def test_register_model(self, registry, sample_model):
+        registered = registry.register(sample_model)
+        assert registered.name == "test-llama"
+        assert registered.format == ModelFormat.OLLAMA
+
+    def test_get_model(self, registry, sample_model):
+        registry.register(sample_model)
+        found = registry.get("test-llama")
+        assert found is not None
+        assert found.name == "test-llama"
+        assert found.path == "llama3.2"
+
+    def test_get_nonexistent_model(self, registry):
+        assert registry.get("nonexistent") is None
+
+    def test_list_models(self, registry, sample_model, reward_model):
+        registry.register(sample_model)
+        registry.register(reward_model)
+        all_models = registry.list_models()
+        assert len(all_models) == 2
+
+    def test_list_models_by_role(self, registry, sample_model, reward_model):
+        registry.register(sample_model)
+        registry.register(reward_model)
+        general = registry.list_models(role=ModelRole.GENERAL)
+        assert len(general) == 1
+        assert general[0].name == "test-llama"
+        rewards = registry.list_models(role=ModelRole.REWARD)
+        assert len(rewards) == 1
+        assert rewards[0].name == "test-reward"
+
+    def test_unregister_model(self, registry, sample_model):
+        registry.register(sample_model)
+        assert registry.unregister("test-llama") is True
+        assert registry.get("test-llama") is None
+
+    def test_unregister_nonexistent(self, registry):
+        assert registry.unregister("nonexistent") is False
+
+    def test_set_active(self, registry, sample_model):
+        registry.register(sample_model)
+        assert registry.set_active("test-llama", False) is True
+        model = registry.get("test-llama")
+        assert model.active is False
+        assert registry.set_active("test-llama", True) is True
+        model = registry.get("test-llama")
+        assert model.active is True
+
+    def test_set_active_nonexistent(self, registry):
+        assert registry.set_active("nonexistent", True) is False
+
+    def test_register_replaces_existing(self, registry, sample_model):
+        registry.register(sample_model)
+        updated = CustomModel(
+            name="test-llama",
+            format=ModelFormat.GGUF,
+            path="/new/path.gguf",
+            role=ModelRole.GENERAL,
+            description="Updated model",
+        )
+        registry.register(updated)
+        found = registry.get("test-llama")
+        assert found.format == ModelFormat.GGUF
+        assert found.path == "/new/path.gguf"
+
+
+class TestAgentAssignments:
+    """Test agent-to-model assignment management."""
+
+    def test_assign_model(self, registry, sample_model):
+        registry.register(sample_model)
+        assert registry.assign_model("agent-1", "test-llama") is True
+        model = registry.get_agent_model("agent-1")
+        assert model is not None
+        assert model.name == "test-llama"
+
+    def test_assign_nonexistent_model(self, registry):
+        assert registry.assign_model("agent-1", "nonexistent") is False
+
+    def test_unassign_model(self, registry, sample_model):
+        registry.register(sample_model)
+        registry.assign_model("agent-1", "test-llama")
+        assert registry.unassign_model("agent-1") is True
+        assert registry.get_agent_model("agent-1") is None
+
+    def test_unassign_nonexistent(self, registry):
+        assert registry.unassign_model("agent-1") is False
+
+    def test_get_agent_model_none(self, registry):
+        assert registry.get_agent_model("agent-1") is None
+
+    def test_get_all_assignments(self, registry, sample_model, reward_model):
+        registry.register(sample_model)
+        registry.register(reward_model)
+        registry.assign_model("agent-1", "test-llama")
+        registry.assign_model("agent-2", "test-reward")
+        assignments = registry.get_agent_assignments()
+        assert len(assignments) == 2
+        assert assignments["agent-1"] == "test-llama"
+        assert assignments["agent-2"] == "test-reward"
+
+    def test_unregister_removes_assignments(self, registry, sample_model):
+        registry.register(sample_model)
+        registry.assign_model("agent-1", "test-llama")
+        registry.unregister("test-llama")
+        assert registry.get_agent_model("agent-1") is None
+        assert len(registry.get_agent_assignments()) == 0
+
+
+class TestRoleLookups:
+    """Test role-based model lookups."""
+
+    def test_get_reward_model(self, registry, reward_model):
+        registry.register(reward_model)
+        found = registry.get_reward_model()
+        assert found is not None
+        assert found.name == "test-reward"
+        assert found.role == ModelRole.REWARD
+
+    def test_get_reward_model_none(self, registry):
+        assert registry.get_reward_model() is None
+
+    def test_get_teacher_model(self, registry):
+        teacher = CustomModel(
+            name="teacher-model",
+            format=ModelFormat.OLLAMA,
+            path="teacher:latest",
+            role=ModelRole.TEACHER,
+        )
+        registry.register(teacher)
+        found = registry.get_teacher_model()
+        assert found is not None
+        assert found.name == "teacher-model"
+
+    def test_get_teacher_model_none(self, registry):
+        assert registry.get_teacher_model() is None
+
+    def test_inactive_reward_model_not_returned(self, registry, reward_model):
+        registry.register(reward_model)
+        registry.set_active("test-reward", False)
+        assert registry.get_reward_model() is None
+
+
+class TestCustomModelDataclass:
+    """Test CustomModel construction."""
+
+    def test_default_registered_at(self):
+        model = CustomModel(
+            name="test", format=ModelFormat.OLLAMA, path="test"
+        )
+        assert model.registered_at != ""
+
+    def test_model_roles(self):
+        assert ModelRole.GENERAL.value == "general"
+        assert ModelRole.REWARD.value == "reward"
+        assert ModelRole.TEACHER.value == "teacher"
+        assert ModelRole.JUDGE.value == "judge"
+
+    def test_model_formats(self):
+        assert ModelFormat.GGUF.value == "gguf"
+        assert ModelFormat.SAFETENSORS.value == "safetensors"
+        assert ModelFormat.HF_CHECKPOINT.value == "hf"
+        assert ModelFormat.OLLAMA.value == "ollama"
diff --git a/tests/infrastructure/test_models_api.py b/tests/infrastructure/test_models_api.py
new file mode 100644
index 00000000..212c513b
--- /dev/null
+++ b/tests/infrastructure/test_models_api.py
@@ -0,0 +1,273 @@
+"""Tests for the custom models API routes."""
+
+from unittest.mock import patch, MagicMock
+
+import pytest
+
+from infrastructure.models.registry import (
+    CustomModel,
+    ModelFormat,
+    ModelRegistry,
+    ModelRole,
+)
+
+
+@pytest.fixture
+def registry(tmp_path):
+    """A fresh ModelRegistry for each test."""
+    db = tmp_path / "api_test.db"
+    with patch("infrastructure.models.registry.DB_PATH", db):
+        reg = ModelRegistry()
+        yield reg
+
+
+class TestModelsAPIList:
+    """Test listing models via the API."""
+
+    def test_list_models_empty(self, client, tmp_path):
+        db = tmp_path / "api.db"
+        with patch("infrastructure.models.registry.DB_PATH", db):
+            with patch(
+                "dashboard.routes.models.model_registry"
+            ) as mock_reg:
+                mock_reg.list_models.return_value = []
+                resp = client.get("/api/v1/models")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "models" in data
+        assert "total" in data
+
+    def test_list_models_with_data(self, client):
+        model = CustomModel(
+            name="test-m",
+            format=ModelFormat.OLLAMA,
+            path="llama3.2",
+            role=ModelRole.GENERAL,
+        )
+        with patch(
+            "dashboard.routes.models.model_registry"
+        ) as mock_reg:
+            mock_reg.list_models.return_value = [model]
+            resp = client.get("/api/v1/models")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["total"] == 1
+        assert data["models"][0]["name"] == "test-m"
+
+
+class TestModelsAPIRegister:
+    """Test model registration via the API."""
+
+    def test_register_ollama_model(self, client):
+        with patch(
+            "dashboard.routes.models.model_registry"
+        ) as mock_reg:
+            mock_reg.register.return_value = CustomModel(
+                name="my-model",
+                format=ModelFormat.OLLAMA,
+                path="llama3.2",
+                role=ModelRole.GENERAL,
+            )
+            resp = client.post(
+                "/api/v1/models",
+                json={
+                    "name": "my-model",
+                    "format": "ollama",
+                    "path": "llama3.2",
+                    "role": "general",
+                },
+            )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["model"]["name"] == "my-model"
+
+    def test_register_invalid_format(self, client):
+        resp = client.post(
+            "/api/v1/models",
+            json={
+                "name": "bad-model",
+                "format": "invalid_format",
+                "path": "whatever",
+            },
+        )
+        assert resp.status_code == 400
+        assert "Invalid format" in resp.json()["detail"]
+
+    def test_register_invalid_role(self, client):
+        resp = client.post(
+            "/api/v1/models",
+            json={
+                "name": "bad-model",
+                "format": "ollama",
+                "path": "llama3.2",
+                "role": "invalid_role",
+            },
+        )
+        assert resp.status_code == 400
+        assert "Invalid role" in resp.json()["detail"]
+
+
+class TestModelsAPIDelete:
+    """Test model deletion via the API."""
+
+    def test_delete_model(self, client):
+        with patch(
+            "dashboard.routes.models.model_registry"
+        ) as mock_reg:
+            mock_reg.unregister.return_value = True
+            resp = client.delete("/api/v1/models/my-model")
+        assert resp.status_code == 200
+
+    def test_delete_nonexistent(self, client):
+        with patch(
+            "dashboard.routes.models.model_registry"
+        ) as mock_reg:
+            mock_reg.unregister.return_value = False
+            resp = client.delete("/api/v1/models/nonexistent")
+        assert resp.status_code == 404
+
+
+class TestModelsAPIGet:
+    """Test getting a specific model."""
+
+    def test_get_model(self, client):
+        model = CustomModel(
+            name="my-model",
+            format=ModelFormat.OLLAMA,
+            path="llama3.2",
+            role=ModelRole.GENERAL,
+        )
+        with patch(
+            "dashboard.routes.models.model_registry"
+        ) as mock_reg:
+            mock_reg.get.return_value = model
+            resp = client.get("/api/v1/models/my-model")
+        assert resp.status_code == 200
+        assert resp.json()["name"] == "my-model"
+
+    def test_get_nonexistent(self, client):
+        with patch(
+            "dashboard.routes.models.model_registry"
+        ) as mock_reg:
+            mock_reg.get.return_value = None
+            resp = client.get("/api/v1/models/nonexistent")
+        assert resp.status_code == 404
+
+
+class TestModelsAPIAssignments:
+    """Test agent model assignment endpoints."""
+
+    def test_assign_model(self, client):
+        with patch(
+            "dashboard.routes.models.model_registry"
+        ) as mock_reg:
+            mock_reg.assign_model.return_value = True
+            resp = client.post(
+                "/api/v1/models/assignments",
+                json={"agent_id": "agent-1", "model_name": "my-model"},
+            )
+        assert resp.status_code == 200
+
+    def test_assign_nonexistent_model(self, client):
+        with patch(
+            "dashboard.routes.models.model_registry"
+        ) as mock_reg:
+            mock_reg.assign_model.return_value = False
+            resp = client.post(
+                "/api/v1/models/assignments",
+                json={"agent_id": "agent-1", "model_name": "nonexistent"},
+            )
+        assert resp.status_code == 404
+
+    def test_unassign_model(self, client):
+        with patch(
+            "dashboard.routes.models.model_registry"
+        ) as mock_reg:
+            mock_reg.unassign_model.return_value = True
+            resp = client.delete("/api/v1/models/assignments/agent-1")
+        assert resp.status_code == 200
+
+    def test_unassign_nonexistent(self, client):
+        with patch(
+            "dashboard.routes.models.model_registry"
+        ) as mock_reg:
+            mock_reg.unassign_model.return_value = False
+            resp = client.delete("/api/v1/models/assignments/nonexistent")
+        assert resp.status_code == 404
+
+    def test_list_assignments(self, client):
+        with patch(
+            "dashboard.routes.models.model_registry"
+        ) as mock_reg:
+            mock_reg.get_agent_assignments.return_value = {
+                "agent-1": "model-a",
+                "agent-2": "model-b",
+            }
+            resp = client.get("/api/v1/models/assignments/all")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["total"] == 2
+
+
+class TestModelsAPIRoles:
+    """Test role-based lookup endpoints."""
+
+    def test_get_reward_model(self, client):
+        model = CustomModel(
+            name="reward-m",
+            format=ModelFormat.OLLAMA,
+            path="deepseek-r1:1.5b",
+            role=ModelRole.REWARD,
+        )
+        with patch(
+            "dashboard.routes.models.model_registry"
+        ) as mock_reg:
+            mock_reg.get_reward_model.return_value = model
+            resp = client.get("/api/v1/models/roles/reward")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["reward_model"]["name"] == "reward-m"
+
+    def test_get_reward_model_none(self, client):
+        with patch(
+            "dashboard.routes.models.model_registry"
+        ) as mock_reg:
+            mock_reg.get_reward_model.return_value = None
+            resp = client.get("/api/v1/models/roles/reward")
+        assert resp.status_code == 200
+        assert resp.json()["reward_model"] is None
+
+    def test_get_teacher_model(self, client):
+        with patch(
+            "dashboard.routes.models.model_registry"
+        ) as mock_reg:
+            mock_reg.get_teacher_model.return_value = None
+            resp = client.get("/api/v1/models/roles/teacher")
+        assert resp.status_code == 200
+        assert resp.json()["teacher_model"] is None
+
+
+class TestModelsAPISetActive:
+    """Test enable/disable model endpoint."""
+
+    def test_enable_model(self, client):
+        with patch(
+            "dashboard.routes.models.model_registry"
+        ) as mock_reg:
+            mock_reg.set_active.return_value = True
+            resp = client.patch(
+                "/api/v1/models/my-model/active",
+                json={"active": True},
+            )
+        assert resp.status_code == 200
+
+    def test_disable_nonexistent(self, client):
+        with patch(
+            "dashboard.routes.models.model_registry"
+        ) as mock_reg:
+            mock_reg.set_active.return_value = False
+            resp = client.patch(
+                "/api/v1/models/nonexistent/active",
+                json={"active": False},
+            )
+        assert resp.status_code == 404
diff --git a/tests/test_router_api.py b/tests/infrastructure/test_router_api.py
similarity index 98%
rename from tests/test_router_api.py
rename to tests/infrastructure/test_router_api.py
index 1ac5945a..d9c90831 100644
--- a/tests/test_router_api.py
+++ b/tests/infrastructure/test_router_api.py
@@ -5,8 +5,8 @@ from unittest.mock import AsyncMock, MagicMock, patch
 import pytest
 from fastapi.testclient import TestClient
 
-from router.cascade import CircuitState, Provider, ProviderStatus
-from router.api import router, get_cascade_router
+from infrastructure.router.cascade import CircuitState, Provider, ProviderStatus
+from infrastructure.router.api import router, get_cascade_router
 
 
 def make_mock_router():
diff --git a/tests/test_router_cascade.py b/tests/infrastructure/test_router_cascade.py
similarity index 99%
rename from tests/test_router_cascade.py
rename to tests/infrastructure/test_router_cascade.py
index a1a6a2f1..479045c9 100644
--- a/tests/test_router_cascade.py
+++ b/tests/infrastructure/test_router_cascade.py
@@ -8,7 +8,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
 import pytest
 import yaml
 
-from router.cascade import (
+from infrastructure.router.cascade import (
     CascadeRouter,
     CircuitState,
     Provider,
@@ -451,7 +451,7 @@ class TestProviderAvailabilityCheck:
         )
         
         # When requests is None, assume available
-        import router.cascade as cascade_module
+        import infrastructure.router.cascade as cascade_module
         old_requests = cascade_module.requests
         cascade_module.requests = None
         try:
diff --git a/tests/integrations/__init__.py b/tests/integrations/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/tests/test_chat_bridge.py b/tests/integrations/test_chat_bridge.py
similarity index 92%
rename from tests/test_chat_bridge.py
rename to tests/integrations/test_chat_bridge.py
index 25645faf..ef9a8d47 100644
--- a/tests/test_chat_bridge.py
+++ b/tests/integrations/test_chat_bridge.py
@@ -3,7 +3,7 @@
 import pytest
 from unittest.mock import AsyncMock, MagicMock, patch
 
-from chat_bridge.base import (
+from integrations.chat_bridge.base import (
     ChatMessage,
     ChatPlatform,
     ChatThread,
@@ -11,7 +11,7 @@ from chat_bridge.base import (
     PlatformState,
     PlatformStatus,
 )
-from chat_bridge.registry import PlatformRegistry
+from integrations.chat_bridge.registry import PlatformRegistry
 
 
 # ── Base dataclass tests ───────────────────────────────────────────────────────
@@ -206,7 +206,7 @@ class TestPlatformRegistry:
 
 class TestInviteParser:
     def test_parse_text_discord_gg(self):
-        from chat_bridge.invite_parser import invite_parser
+        from integrations.chat_bridge.invite_parser import invite_parser
 
         result = invite_parser.parse_text("Join us at https://discord.gg/abc123!")
         assert result is not None
@@ -215,7 +215,7 @@ class TestInviteParser:
         assert result.source == "text"
 
     def test_parse_text_discord_com_invite(self):
-        from chat_bridge.invite_parser import invite_parser
+        from integrations.chat_bridge.invite_parser import invite_parser
 
         result = invite_parser.parse_text(
             "Link: https://discord.com/invite/myServer2024"
@@ -224,7 +224,7 @@ class TestInviteParser:
         assert result.code == "myServer2024"
 
     def test_parse_text_discordapp(self):
-        from chat_bridge.invite_parser import invite_parser
+        from integrations.chat_bridge.invite_parser import invite_parser
 
         result = invite_parser.parse_text(
             "https://discordapp.com/invite/test-code"
@@ -233,13 +233,13 @@ class TestInviteParser:
         assert result.code == "test-code"
 
     def test_parse_text_no_invite(self):
-        from chat_bridge.invite_parser import invite_parser
+        from integrations.chat_bridge.invite_parser import invite_parser
 
         result = invite_parser.parse_text("Hello world, no links here")
         assert result is None
 
     def test_parse_text_bare_discord_gg(self):
-        from chat_bridge.invite_parser import invite_parser
+        from integrations.chat_bridge.invite_parser import invite_parser
 
         result = invite_parser.parse_text("discord.gg/xyz789")
         assert result is not None
@@ -248,7 +248,7 @@ class TestInviteParser:
     @pytest.mark.asyncio
     async def test_parse_image_no_deps(self):
         """parse_image returns None when pyzbar/Pillow are not installed."""
-        from chat_bridge.invite_parser import InviteParser
+        from integrations.chat_bridge.invite_parser import InviteParser
 
         parser = InviteParser()
         # With mocked pyzbar, this should gracefully return None
@@ -258,7 +258,7 @@ class TestInviteParser:
 
 class TestExtractDiscordCode:
     def test_various_formats(self):
-        from chat_bridge.invite_parser import _extract_discord_code
+        from integrations.chat_bridge.invite_parser import _extract_discord_code
 
         assert _extract_discord_code("discord.gg/abc") == "abc"
         assert _extract_discord_code("https://discord.gg/test") == "test"
diff --git a/tests/test_discord_vendor.py b/tests/integrations/test_discord_vendor.py
similarity index 79%
rename from tests/test_discord_vendor.py
rename to tests/integrations/test_discord_vendor.py
index f06528e7..b40f0412 100644
--- a/tests/test_discord_vendor.py
+++ b/tests/integrations/test_discord_vendor.py
@@ -5,7 +5,7 @@ import pytest
 from pathlib import Path
 from unittest.mock import AsyncMock, MagicMock, patch
 
-from chat_bridge.base import PlatformState
+from integrations.chat_bridge.base import PlatformState
 
 
 # ── DiscordVendor unit tests ──────────────────────────────────────────────────
@@ -13,19 +13,19 @@ from chat_bridge.base import PlatformState
 
 class TestDiscordVendor:
     def test_name(self):
-        from chat_bridge.vendors.discord import DiscordVendor
+        from integrations.chat_bridge.vendors.discord import DiscordVendor
 
         vendor = DiscordVendor()
         assert vendor.name == "discord"
 
     def test_initial_state(self):
-        from chat_bridge.vendors.discord import DiscordVendor
+        from integrations.chat_bridge.vendors.discord import DiscordVendor
 
         vendor = DiscordVendor()
         assert vendor.state == PlatformState.DISCONNECTED
 
     def test_status_disconnected(self):
-        from chat_bridge.vendors.discord import DiscordVendor
+        from integrations.chat_bridge.vendors.discord import DiscordVendor
 
         vendor = DiscordVendor()
         status = vendor.status()
@@ -35,8 +35,8 @@ class TestDiscordVendor:
         assert status.guild_count == 0
 
     def test_save_and_load_token(self, tmp_path, monkeypatch):
-        from chat_bridge.vendors import discord as discord_mod
-        from chat_bridge.vendors.discord import DiscordVendor
+        from integrations.chat_bridge.vendors import discord as discord_mod
+        from integrations.chat_bridge.vendors.discord import DiscordVendor
 
         state_file = tmp_path / "discord_state.json"
         monkeypatch.setattr(discord_mod, "_STATE_FILE", state_file)
@@ -52,8 +52,8 @@ class TestDiscordVendor:
         assert loaded == "test-token-abc"
 
     def test_load_token_missing_file(self, tmp_path, monkeypatch):
-        from chat_bridge.vendors import discord as discord_mod
-        from chat_bridge.vendors.discord import DiscordVendor
+        from integrations.chat_bridge.vendors import discord as discord_mod
+        from integrations.chat_bridge.vendors.discord import DiscordVendor
 
         state_file = tmp_path / "nonexistent.json"
         monkeypatch.setattr(discord_mod, "_STATE_FILE", state_file)
@@ -66,7 +66,7 @@ class TestDiscordVendor:
 
     @pytest.mark.asyncio
     async def test_start_no_token(self):
-        from chat_bridge.vendors.discord import DiscordVendor
+        from integrations.chat_bridge.vendors.discord import DiscordVendor
 
         vendor = DiscordVendor()
         result = await vendor.start(token=None)
@@ -74,7 +74,7 @@ class TestDiscordVendor:
 
     @pytest.mark.asyncio
     async def test_start_import_error(self):
-        from chat_bridge.vendors.discord import DiscordVendor
+        from integrations.chat_bridge.vendors.discord import DiscordVendor
 
         vendor = DiscordVendor()
         # Simulate discord.py not installed by making import fail
@@ -84,7 +84,7 @@ class TestDiscordVendor:
 
     @pytest.mark.asyncio
     async def test_stop_when_disconnected(self):
-        from chat_bridge.vendors.discord import DiscordVendor
+        from integrations.chat_bridge.vendors.discord import DiscordVendor
 
         vendor = DiscordVendor()
         # Should not raise
@@ -92,13 +92,13 @@ class TestDiscordVendor:
         assert vendor.state == PlatformState.DISCONNECTED
 
     def test_get_oauth2_url_no_client(self):
-        from chat_bridge.vendors.discord import DiscordVendor
+        from integrations.chat_bridge.vendors.discord import DiscordVendor
 
         vendor = DiscordVendor()
         assert vendor.get_oauth2_url() is None
 
     def test_get_oauth2_url_with_client(self):
-        from chat_bridge.vendors.discord import DiscordVendor
+        from integrations.chat_bridge.vendors.discord import DiscordVendor
 
         vendor = DiscordVendor()
         mock_client = MagicMock()
@@ -110,7 +110,7 @@ class TestDiscordVendor:
 
     @pytest.mark.asyncio
     async def test_send_message_not_connected(self):
-        from chat_bridge.vendors.discord import DiscordVendor
+        from integrations.chat_bridge.vendors.discord import DiscordVendor
 
         vendor = DiscordVendor()
         result = await vendor.send_message("123", "hello")
@@ -118,7 +118,7 @@ class TestDiscordVendor:
 
     @pytest.mark.asyncio
     async def test_create_thread_not_connected(self):
-        from chat_bridge.vendors.discord import DiscordVendor
+        from integrations.chat_bridge.vendors.discord import DiscordVendor
 
         vendor = DiscordVendor()
         result = await vendor.create_thread("123", "Test Thread")
@@ -126,7 +126,7 @@ class TestDiscordVendor:
 
     @pytest.mark.asyncio
     async def test_join_from_invite_not_connected(self):
-        from chat_bridge.vendors.discord import DiscordVendor
+        from integrations.chat_bridge.vendors.discord import DiscordVendor
 
         vendor = DiscordVendor()
         result = await vendor.join_from_invite("abc123")
@@ -135,13 +135,13 @@ class TestDiscordVendor:
 
 class TestChunkMessage:
     def test_short_message(self):
-        from chat_bridge.vendors.discord import _chunk_message
+        from integrations.chat_bridge.vendors.discord import _chunk_message
 
         chunks = _chunk_message("Hello!", 2000)
         assert chunks == ["Hello!"]
 
     def test_long_message(self):
-        from chat_bridge.vendors.discord import _chunk_message
+        from integrations.chat_bridge.vendors.discord import _chunk_message
 
         text = "a" * 5000
         chunks = _chunk_message(text, 2000)
@@ -150,7 +150,7 @@ class TestChunkMessage:
         assert "".join(chunks) == text
 
     def test_split_at_newline(self):
-        from chat_bridge.vendors.discord import _chunk_message
+        from integrations.chat_bridge.vendors.discord import _chunk_message
 
         text = "Line1\n" + "x" * 1990 + "\nLine3"
         chunks = _chunk_message(text, 2000)
@@ -179,7 +179,7 @@ class TestDiscordRoutes:
     def test_setup_with_token(self, client):
         """Setup with a token — bot won't actually connect but route works."""
         with patch(
-            "chat_bridge.vendors.discord.DiscordVendor.start",
+            "integrations.chat_bridge.vendors.discord.DiscordVendor.start",
             new_callable=AsyncMock,
             return_value=False,
         ):
@@ -200,7 +200,7 @@ class TestDiscordRoutes:
 
     def test_join_with_text_invite(self, client):
         with patch(
-            "chat_bridge.vendors.discord.DiscordVendor.join_from_invite",
+            "integrations.chat_bridge.vendors.discord.DiscordVendor.join_from_invite",
             new_callable=AsyncMock,
             return_value=True,
         ):
@@ -215,7 +215,7 @@ class TestDiscordRoutes:
         assert data["invite"]["source"] == "text"
 
     def test_oauth_url_not_connected(self, client):
-        from chat_bridge.vendors.discord import discord_bot
+        from integrations.chat_bridge.vendors.discord import discord_bot
 
         # Reset singleton so it has no client
         discord_bot._client = None
diff --git a/tests/test_notifications.py b/tests/integrations/test_notifications.py
similarity index 97%
rename from tests/test_notifications.py
rename to tests/integrations/test_notifications.py
index 6ce386df..5ffdb403 100644
--- a/tests/test_notifications.py
+++ b/tests/integrations/test_notifications.py
@@ -1,6 +1,6 @@
 """Tests for notifications/push.py — push notification system."""
 
-from notifications.push import PushNotifier
+from infrastructure.notifications.push import PushNotifier
 
 
 def test_notify_creates_notification():
diff --git a/tests/test_shortcuts.py b/tests/integrations/test_shortcuts.py
similarity index 93%
rename from tests/test_shortcuts.py
rename to tests/integrations/test_shortcuts.py
index 7613435b..bdcb3954 100644
--- a/tests/test_shortcuts.py
+++ b/tests/integrations/test_shortcuts.py
@@ -1,6 +1,6 @@
 """Tests for shortcuts/siri.py — Siri Shortcuts integration."""
 
-from shortcuts.siri import get_setup_guide, SHORTCUT_ACTIONS
+from integrations.shortcuts.siri import get_setup_guide, SHORTCUT_ACTIONS
 
 
 def test_setup_guide_has_title():
diff --git a/tests/test_telegram_bot.py b/tests/integrations/test_telegram_bot.py
similarity index 84%
rename from tests/test_telegram_bot.py
rename to tests/integrations/test_telegram_bot.py
index 8c9f491e..06d50303 100644
--- a/tests/test_telegram_bot.py
+++ b/tests/integrations/test_telegram_bot.py
@@ -14,9 +14,9 @@ class TestTelegramBotTokenHelpers:
     def test_save_and_load_token(self, tmp_path, monkeypatch):
         """save_token persists to disk; load_token reads it back."""
         state_file = tmp_path / "telegram_state.json"
-        monkeypatch.setattr("telegram_bot.bot._STATE_FILE", state_file)
+        monkeypatch.setattr("integrations.telegram_bot.bot._STATE_FILE", state_file)
 
-        from telegram_bot.bot import TelegramBot
+        from integrations.telegram_bot.bot import TelegramBot
         bot = TelegramBot()
 
         bot.save_token("test-token-123")
@@ -30,28 +30,28 @@ class TestTelegramBotTokenHelpers:
     def test_load_token_missing_file(self, tmp_path, monkeypatch):
         """load_token returns None when no state file and no env var."""
         state_file = tmp_path / "missing_telegram_state.json"
-        monkeypatch.setattr("telegram_bot.bot._STATE_FILE", state_file)
+        monkeypatch.setattr("integrations.telegram_bot.bot._STATE_FILE", state_file)
 
         # Ensure settings.telegram_token is empty
         mock_settings = MagicMock()
         mock_settings.telegram_token = ""
-        with patch("telegram_bot.bot._load_token_from_file", return_value=None):
+        with patch("integrations.telegram_bot.bot._load_token_from_file", return_value=None):
             with patch("config.settings", mock_settings):
-                from telegram_bot.bot import TelegramBot
+                from integrations.telegram_bot.bot import TelegramBot
                 bot = TelegramBot()
                 result = bot.load_token()
         assert result is None
 
     def test_token_set_property(self):
         """token_set reflects whether a token has been applied."""
-        from telegram_bot.bot import TelegramBot
+        from integrations.telegram_bot.bot import TelegramBot
         bot = TelegramBot()
         assert not bot.token_set
         bot._token = "tok"
         assert bot.token_set
 
     def test_is_running_property(self):
-        from telegram_bot.bot import TelegramBot
+        from integrations.telegram_bot.bot import TelegramBot
         bot = TelegramBot()
         assert not bot.is_running
         bot._running = True
@@ -63,9 +63,9 @@ class TestTelegramBotLifecycle:
     async def test_start_no_token_returns_false(self, tmp_path, monkeypatch):
         """start() returns False and stays idle when no token is available."""
         state_file = tmp_path / "telegram_state.json"
-        monkeypatch.setattr("telegram_bot.bot._STATE_FILE", state_file)
+        monkeypatch.setattr("integrations.telegram_bot.bot._STATE_FILE", state_file)
 
-        from telegram_bot.bot import TelegramBot
+        from integrations.telegram_bot.bot import TelegramBot
         bot = TelegramBot()
         with patch.object(bot, "load_token", return_value=None):
             result = await bot.start()
@@ -74,7 +74,7 @@ class TestTelegramBotLifecycle:
 
     @pytest.mark.asyncio
     async def test_start_already_running_returns_true(self):
-        from telegram_bot.bot import TelegramBot
+        from integrations.telegram_bot.bot import TelegramBot
         bot = TelegramBot()
         bot._running = True
         result = await bot.start(token="any")
@@ -83,7 +83,7 @@ class TestTelegramBotLifecycle:
     @pytest.mark.asyncio
     async def test_start_import_error_returns_false(self):
         """start() returns False gracefully when python-telegram-bot absent."""
-        from telegram_bot.bot import TelegramBot
+        from integrations.telegram_bot.bot import TelegramBot
         bot = TelegramBot()
 
         with patch.object(bot, "load_token", return_value="tok"), \
@@ -94,7 +94,7 @@ class TestTelegramBotLifecycle:
 
     @pytest.mark.asyncio
     async def test_stop_when_not_running_is_noop(self):
-        from telegram_bot.bot import TelegramBot
+        from integrations.telegram_bot.bot import TelegramBot
         bot = TelegramBot()
         # Should not raise
         await bot.stop()
@@ -102,7 +102,7 @@ class TestTelegramBotLifecycle:
     @pytest.mark.asyncio
     async def test_stop_calls_shutdown(self):
         """stop() invokes the Application shutdown sequence."""
-        from telegram_bot.bot import TelegramBot
+        from integrations.telegram_bot.bot import TelegramBot
         bot = TelegramBot()
         bot._running = True
 
@@ -125,7 +125,7 @@ class TestTelegramBotLifecycle:
 class TestTelegramRoutes:
     def test_status_not_running(self, client):
         """GET /telegram/status returns running=False when bot is idle."""
-        from telegram_bot.bot import telegram_bot
+        from integrations.telegram_bot.bot import telegram_bot
         telegram_bot._running = False
         telegram_bot._token = None
 
@@ -137,7 +137,7 @@ class TestTelegramRoutes:
 
     def test_status_running(self, client):
         """GET /telegram/status returns running=True when bot is active."""
-        from telegram_bot.bot import telegram_bot
+        from integrations.telegram_bot.bot import telegram_bot
         telegram_bot._running = True
         telegram_bot._token = "tok"
 
@@ -161,7 +161,7 @@ class TestTelegramRoutes:
 
     def test_setup_success(self, client):
         """POST /telegram/setup with valid token starts bot and returns ok."""
-        from telegram_bot.bot import telegram_bot
+        from integrations.telegram_bot.bot import telegram_bot
 
         telegram_bot._running = False
         with patch.object(telegram_bot, "save_token") as mock_save, \
@@ -175,7 +175,7 @@ class TestTelegramRoutes:
 
     def test_setup_failure(self, client):
         """POST /telegram/setup returns error dict when bot fails to start."""
-        from telegram_bot.bot import telegram_bot
+        from integrations.telegram_bot.bot import telegram_bot
 
         telegram_bot._running = False
         with patch.object(telegram_bot, "save_token"), \
@@ -189,7 +189,7 @@ class TestTelegramRoutes:
 
     def test_setup_stops_running_bot_first(self, client):
         """POST /telegram/setup stops any running bot before starting new one."""
-        from telegram_bot.bot import telegram_bot
+        from integrations.telegram_bot.bot import telegram_bot
         telegram_bot._running = True
 
         with patch.object(telegram_bot, "save_token"), \
@@ -207,5 +207,5 @@ class TestTelegramRoutes:
 
 def test_module_singleton_exists():
     """telegram_bot module exposes a singleton TelegramBot instance."""
-    from telegram_bot.bot import telegram_bot, TelegramBot
+    from integrations.telegram_bot.bot import telegram_bot, TelegramBot
     assert isinstance(telegram_bot, TelegramBot)
diff --git a/tests/test_voice_enhanced.py b/tests/integrations/test_voice_enhanced.py
similarity index 93%
rename from tests/test_voice_enhanced.py
rename to tests/integrations/test_voice_enhanced.py
index 0ed802db..a4b53cd0 100644
--- a/tests/test_voice_enhanced.py
+++ b/tests/integrations/test_voice_enhanced.py
@@ -1,4 +1,4 @@
-"""Tests for dashboard/routes/voice_enhanced.py — enhanced voice processing."""
+"""Tests for enhanced voice processing (merged into dashboard/routes/voice.py)."""
 
 from unittest.mock import MagicMock, patch
 
@@ -56,7 +56,7 @@ class TestVoiceEnhancedProcess:
         mock_run.content = "Hello from Timmy!"
         mock_agent.run.return_value = mock_run
 
-        with patch("dashboard.routes.voice_enhanced.create_timmy", return_value=mock_agent):
+        with patch("dashboard.routes.voice.create_timmy", return_value=mock_agent):
             resp = client.post(
                 "/voice/enhanced/process",
                 data={"text": "tell me about Bitcoin", "speak_response": "false"},
@@ -69,7 +69,7 @@ class TestVoiceEnhancedProcess:
     def test_chat_fallback_error_handling(self, client):
         """When the agent raises, the error should be captured gracefully."""
         with patch(
-            "dashboard.routes.voice_enhanced.create_timmy",
+            "dashboard.routes.voice.create_timmy",
             side_effect=RuntimeError("Ollama offline"),
         ):
             resp = client.post(
diff --git a/tests/test_voice_nlu.py b/tests/integrations/test_voice_nlu.py
similarity index 97%
rename from tests/test_voice_nlu.py
rename to tests/integrations/test_voice_nlu.py
index f8f3e963..69770bfc 100644
--- a/tests/test_voice_nlu.py
+++ b/tests/integrations/test_voice_nlu.py
@@ -1,6 +1,6 @@
 """Tests for voice/nlu.py — intent detection and command extraction."""
 
-from voice.nlu import detect_intent, extract_command
+from integrations.voice.nlu import detect_intent, extract_command
 
 
 # ── Intent detection ─────────────────────────────────────────────────────────
diff --git a/tests/test_voice_tts_functional.py b/tests/integrations/test_voice_tts_functional.py
similarity index 100%
rename from tests/test_voice_tts_functional.py
rename to tests/integrations/test_voice_tts_functional.py
diff --git a/tests/test_websocket.py b/tests/integrations/test_websocket.py
similarity index 91%
rename from tests/test_websocket.py
rename to tests/integrations/test_websocket.py
index 2d941c8c..477e45f6 100644
--- a/tests/test_websocket.py
+++ b/tests/integrations/test_websocket.py
@@ -4,7 +4,7 @@ import json
 
 import pytest
 
-from ws_manager.handler import WebSocketManager, WSEvent
+from infrastructure.ws_manager.handler import WebSocketManager, WSEvent
 
 
 def test_ws_event_to_json():
diff --git a/tests/test_websocket_extended.py b/tests/integrations/test_websocket_extended.py
similarity index 98%
rename from tests/test_websocket_extended.py
rename to tests/integrations/test_websocket_extended.py
index 88bd792b..26448b10 100644
--- a/tests/test_websocket_extended.py
+++ b/tests/integrations/test_websocket_extended.py
@@ -6,7 +6,7 @@ from unittest.mock import AsyncMock, MagicMock
 
 import pytest
 
-from ws_manager.handler import WebSocketManager, WSEvent
+from infrastructure.ws_manager.handler import WebSocketManager, WSEvent
 
 
 class TestWSEventSerialization:
diff --git a/tests/lightning/__init__.py b/tests/lightning/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/tests/test_l402_proxy.py b/tests/lightning/test_l402_proxy.py
similarity index 100%
rename from tests/test_l402_proxy.py
rename to tests/lightning/test_l402_proxy.py
diff --git a/tests/test_lightning_interface.py b/tests/lightning/test_lightning_interface.py
similarity index 100%
rename from tests/test_lightning_interface.py
rename to tests/lightning/test_lightning_interface.py
diff --git a/tests/test_lnd_backend.py b/tests/lightning/test_lnd_backend.py
similarity index 100%
rename from tests/test_lnd_backend.py
rename to tests/lightning/test_lnd_backend.py
diff --git a/tests/mcp/__init__.py b/tests/mcp/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/tests/test_functional_mcp.py b/tests/mcp/test_functional_mcp.py
similarity index 100%
rename from tests/test_functional_mcp.py
rename to tests/mcp/test_functional_mcp.py
diff --git a/tests/test_mcp_bootstrap.py b/tests/mcp/test_mcp_bootstrap.py
similarity index 100%
rename from tests/test_mcp_bootstrap.py
rename to tests/mcp/test_mcp_bootstrap.py
diff --git a/tests/test_mcp_discovery.py b/tests/mcp/test_mcp_discovery.py
similarity index 100%
rename from tests/test_mcp_discovery.py
rename to tests/mcp/test_mcp_discovery.py
diff --git a/tests/test_tool_executor.py b/tests/mcp/test_tool_executor.py
similarity index 100%
rename from tests/test_tool_executor.py
rename to tests/mcp/test_tool_executor.py
diff --git a/tests/scripture/__init__.py b/tests/scripture/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/tests/test_scripture.py b/tests/scripture/test_scripture.py
similarity index 100%
rename from tests/test_scripture.py
rename to tests/scripture/test_scripture.py
diff --git a/tests/security/__init__.py b/tests/security/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/tests/test_security_fixes_xss.py b/tests/security/test_security_fixes_xss.py
similarity index 100%
rename from tests/test_security_fixes_xss.py
rename to tests/security/test_security_fixes_xss.py
diff --git a/tests/test_security_regression.py b/tests/security/test_security_regression.py
similarity index 100%
rename from tests/test_security_regression.py
rename to tests/security/test_security_regression.py
diff --git a/tests/self_coding/__init__.py b/tests/self_coding/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/tests/test_codebase_indexer.py b/tests/self_coding/test_codebase_indexer.py
similarity index 100%
rename from tests/test_codebase_indexer.py
rename to tests/self_coding/test_codebase_indexer.py
diff --git a/tests/test_codebase_indexer_errors.py b/tests/self_coding/test_codebase_indexer_errors.py
similarity index 99%
rename from tests/test_codebase_indexer_errors.py
rename to tests/self_coding/test_codebase_indexer_errors.py
index 98b356c0..93d5ecae 100644
--- a/tests/test_codebase_indexer_errors.py
+++ b/tests/self_coding/test_codebase_indexer_errors.py
@@ -273,31 +273,34 @@ except ImportError:
     
     async def test_permission_error(self):
         """Should handle permission errors gracefully."""
+        import os
+        if os.geteuid() == 0:
+            pytest.skip("Permission tests are ineffective when running as root")
+
         with tempfile.TemporaryDirectory() as tmpdir:
             repo_path = Path(tmpdir)
             src_path = repo_path / "src"
             src_path.mkdir()
-            
+
             # Create file
             file_path = src_path / "locked.py"
             file_path.write_text("def test(): pass")
-            
+
             # Remove read permission (if on Unix)
-            import os
             try:
                 os.chmod(file_path, 0o000)
-                
+
                 indexer = CodebaseIndexer(
                     repo_path=repo_path,
                     db_path=repo_path / "index.db",
                     src_dirs=["src"],
                 )
-                
+
                 stats = await indexer.index_all()
-                
+
                 # Should count as failed
                 assert stats["failed"] == 1
-                
+
             finally:
                 # Restore permission for cleanup
                 os.chmod(file_path, 0o644)
diff --git a/tests/test_git_safety.py b/tests/self_coding/test_git_safety.py
similarity index 98%
rename from tests/test_git_safety.py
rename to tests/self_coding/test_git_safety.py
index fea9e17f..404bd167 100644
--- a/tests/test_git_safety.py
+++ b/tests/self_coding/test_git_safety.py
@@ -9,6 +9,7 @@ from __future__ import annotations
 import asyncio
 import os
 import subprocess
+import sys
 import tempfile
 from pathlib import Path
 
@@ -43,7 +44,13 @@ def temp_git_repo():
             check=True,
             capture_output=True,
         )
-        
+        subprocess.run(
+            ["git", "config", "commit.gpgsign", "false"],
+            cwd=repo_path,
+            check=True,
+            capture_output=True,
+        )
+
         # Create initial file and commit
         (repo_path / "README.md").write_text("# Test Repo")
         subprocess.run(["git", "add", "."], cwd=repo_path, check=True, capture_output=True)
@@ -154,7 +161,7 @@ def test_pass():
 """)
         safety = GitSafety(
             repo_path=temp_git_repo,
-            test_command="python -m pytest test_pass.py -v",
+            test_command=f"{sys.executable} -m pytest test_pass.py -v",
         )
         
         snapshot = await safety.snapshot(run_tests=True)
diff --git a/tests/test_git_safety_errors.py b/tests/self_coding/test_git_safety_errors.py
similarity index 91%
rename from tests/test_git_safety_errors.py
rename to tests/self_coding/test_git_safety_errors.py
index 61dde537..e8086ee6 100644
--- a/tests/test_git_safety_errors.py
+++ b/tests/self_coding/test_git_safety_errors.py
@@ -6,6 +6,7 @@ Tests timeout handling, git failures, merge conflicts, and edge cases.
 from __future__ import annotations
 
 import subprocess
+import sys
 import tempfile
 from pathlib import Path
 from unittest.mock import patch
@@ -36,6 +37,7 @@ class TestGitSafetyErrors:
             subprocess.run(["git", "init"], cwd=repo_path, check=True, capture_output=True)
             subprocess.run(["git", "config", "user.email", "test@test.com"], cwd=repo_path, check=True, capture_output=True)
             subprocess.run(["git", "config", "user.name", "Test"], cwd=repo_path, check=True, capture_output=True)
+            subprocess.run(["git", "config", "commit.gpgsign", "false"], cwd=repo_path, check=True, capture_output=True)
             
             safety = GitSafety(repo_path=repo_path)
             
@@ -50,6 +52,7 @@ class TestGitSafetyErrors:
             subprocess.run(["git", "init"], cwd=repo_path, check=True, capture_output=True)
             subprocess.run(["git", "config", "user.email", "test@test.com"], cwd=repo_path, check=True, capture_output=True)
             subprocess.run(["git", "config", "user.name", "Test"], cwd=repo_path, check=True, capture_output=True)
+            subprocess.run(["git", "config", "commit.gpgsign", "false"], cwd=repo_path, check=True, capture_output=True)
             
             # Create initial file
             (repo_path / "file.txt").write_text("original")
@@ -81,6 +84,7 @@ class TestGitSafetyErrors:
             subprocess.run(["git", "init"], cwd=repo_path, check=True, capture_output=True)
             subprocess.run(["git", "config", "user.email", "test@test.com"], cwd=repo_path, check=True, capture_output=True)
             subprocess.run(["git", "config", "user.name", "Test"], cwd=repo_path, check=True, capture_output=True)
+            subprocess.run(["git", "config", "commit.gpgsign", "false"], cwd=repo_path, check=True, capture_output=True)
             
             safety = GitSafety(repo_path=repo_path)
             
@@ -109,6 +113,7 @@ class TestGitSafetyErrors:
             subprocess.run(["git", "init"], cwd=repo_path, check=True, capture_output=True)
             subprocess.run(["git", "config", "user.email", "test@test.com"], cwd=repo_path, check=True, capture_output=True)
             subprocess.run(["git", "config", "user.name", "Test"], cwd=repo_path, check=True, capture_output=True)
+            subprocess.run(["git", "config", "commit.gpgsign", "false"], cwd=repo_path, check=True, capture_output=True)
             
             # Need an initial commit for HEAD to exist
             (repo_path / "initial.txt").write_text("initial")
@@ -120,7 +125,7 @@ class TestGitSafetyErrors:
             
             safety = GitSafety(
                 repo_path=repo_path,
-                test_command="python -m pytest test_fail.py -v",
+                test_command=f"{sys.executable} -m pytest test_fail.py -v",
             )
             
             snapshot = await safety.snapshot(run_tests=True)
@@ -135,6 +140,7 @@ class TestGitSafetyErrors:
             subprocess.run(["git", "init"], cwd=repo_path, check=True, capture_output=True)
             subprocess.run(["git", "config", "user.email", "test@test.com"], cwd=repo_path, check=True, capture_output=True)
             subprocess.run(["git", "config", "user.name", "Test"], cwd=repo_path, check=True, capture_output=True)
+            subprocess.run(["git", "config", "commit.gpgsign", "false"], cwd=repo_path, check=True, capture_output=True)
             
             safety = GitSafety(repo_path=repo_path)
             
@@ -162,6 +168,7 @@ class TestGitSafetyErrors:
             subprocess.run(["git", "init"], cwd=repo_path, check=True, capture_output=True)
             subprocess.run(["git", "config", "user.email", "test@test.com"], cwd=repo_path, check=True, capture_output=True)
             subprocess.run(["git", "config", "user.name", "Test"], cwd=repo_path, check=True, capture_output=True)
+            subprocess.run(["git", "config", "commit.gpgsign", "false"], cwd=repo_path, check=True, capture_output=True)
             
             # Need an initial commit for HEAD to exist
             (repo_path / "initial.txt").write_text("initial")
@@ -187,6 +194,7 @@ class TestGitSafetyErrors:
             subprocess.run(["git", "init"], cwd=repo_path, check=True, capture_output=True)
             subprocess.run(["git", "config", "user.email", "test@test.com"], cwd=repo_path, check=True, capture_output=True)
             subprocess.run(["git", "config", "user.name", "Test"], cwd=repo_path, check=True, capture_output=True)
+            subprocess.run(["git", "config", "commit.gpgsign", "false"], cwd=repo_path, check=True, capture_output=True)
             
             # Initial commit
             (repo_path / "file.txt").write_text("content")
@@ -207,6 +215,7 @@ class TestGitSafetyErrors:
             subprocess.run(["git", "init"], cwd=repo_path, check=True, capture_output=True)
             subprocess.run(["git", "config", "user.email", "test@test.com"], cwd=repo_path, check=True, capture_output=True)
             subprocess.run(["git", "config", "user.name", "Test"], cwd=repo_path, check=True, capture_output=True)
+            subprocess.run(["git", "config", "commit.gpgsign", "false"], cwd=repo_path, check=True, capture_output=True)
             
             safety = GitSafety(repo_path=repo_path)
             
@@ -235,6 +244,7 @@ class TestGitSafetyErrors:
             subprocess.run(["git", "init"], cwd=repo_path, check=True, capture_output=True)
             subprocess.run(["git", "config", "user.email", "test@test.com"], cwd=repo_path, check=True, capture_output=True)
             subprocess.run(["git", "config", "user.name", "Test"], cwd=repo_path, check=True, capture_output=True)
+            subprocess.run(["git", "config", "commit.gpgsign", "false"], cwd=repo_path, check=True, capture_output=True)
             
             # Initial commit on master (default branch name)
             (repo_path / "main.txt").write_text("main branch content")
diff --git a/tests/test_git_tools.py b/tests/self_coding/test_git_tools.py
similarity index 99%
rename from tests/test_git_tools.py
rename to tests/self_coding/test_git_tools.py
index e7c64e5f..cbb28e7c 100644
--- a/tests/test_git_tools.py
+++ b/tests/self_coding/test_git_tools.py
@@ -7,7 +7,7 @@ working tree.
 import pytest
 from pathlib import Path
 
-from tools.git_tools import (
+from creative.tools.git_tools import (
     git_init,
     git_status,
     git_add,
diff --git a/tests/test_learner.py b/tests/self_coding/test_learner.py
similarity index 100%
rename from tests/test_learner.py
rename to tests/self_coding/test_learner.py
diff --git a/tests/test_modification_journal.py b/tests/self_coding/test_modification_journal.py
similarity index 100%
rename from tests/test_modification_journal.py
rename to tests/self_coding/test_modification_journal.py
diff --git a/tests/test_scary_paths.py b/tests/self_coding/test_scary_paths.py
similarity index 97%
rename from tests/test_scary_paths.py
rename to tests/self_coding/test_scary_paths.py
index cb40de57..de0fc0cf 100644
--- a/tests/test_scary_paths.py
+++ b/tests/self_coding/test_scary_paths.py
@@ -274,7 +274,7 @@ class TestWebSocketResilience:
     
     def test_websocket_manager_handles_no_connections(self):
         """WebSocket manager handles zero connected clients."""
-        from ws_manager.handler import ws_manager
+        from infrastructure.ws_manager.handler import ws_manager
         
         # Should not crash when broadcasting with no connections
         try:
@@ -297,7 +297,7 @@ class TestVoiceNLUEdgeCases:
     
     def test_nlu_empty_string(self):
         """Empty string doesn't crash NLU."""
-        from voice.nlu import detect_intent
+        from integrations.voice.nlu import detect_intent
         
         result = detect_intent("")
         assert result is not None
@@ -306,14 +306,14 @@ class TestVoiceNLUEdgeCases:
     
     def test_nlu_all_punctuation(self):
         """String of only punctuation is handled."""
-        from voice.nlu import detect_intent
+        from integrations.voice.nlu import detect_intent
         
         result = detect_intent("...!!!???")
         assert result is not None
     
     def test_nlu_very_long_input(self):
         """10k character input doesn't crash or hang."""
-        from voice.nlu import detect_intent
+        from integrations.voice.nlu import detect_intent
         
         long_input = "word " * 2000  # ~10k chars
         
@@ -327,7 +327,7 @@ class TestVoiceNLUEdgeCases:
     
     def test_nlu_non_english_text(self):
         """Non-English Unicode text is handled."""
-        from voice.nlu import detect_intent
+        from integrations.voice.nlu import detect_intent
         
         # Test various Unicode scripts
         test_inputs = [
@@ -343,7 +343,7 @@ class TestVoiceNLUEdgeCases:
     
     def test_nlu_special_characters(self):
         """Special characters don't break parsing."""
-        from voice.nlu import detect_intent
+        from integrations.voice.nlu import detect_intent
         
         special_inputs = [
             "<script>alert('xss')</script>",
diff --git a/tests/test_self_coding_dashboard.py b/tests/self_coding/test_self_coding_dashboard.py
similarity index 100%
rename from tests/test_self_coding_dashboard.py
rename to tests/self_coding/test_self_coding_dashboard.py
diff --git a/tests/test_self_coding_integration.py b/tests/self_coding/test_self_coding_integration.py
similarity index 99%
rename from tests/test_self_coding_integration.py
rename to tests/self_coding/test_self_coding_integration.py
index 8bf9d822..5e17cca6 100644
--- a/tests/test_self_coding_integration.py
+++ b/tests/self_coding/test_self_coding_integration.py
@@ -39,7 +39,11 @@ def self_coding_env():
             ["git", "config", "user.name", "Test User"],
             cwd=repo_path, check=True, capture_output=True,
         )
-        
+        subprocess.run(
+            ["git", "config", "commit.gpgsign", "false"],
+            cwd=repo_path, check=True, capture_output=True,
+        )
+
         # Create src directory with real Python files
         src_path = repo_path / "src" / "myproject"
         src_path.mkdir(parents=True)
diff --git a/tests/test_self_edit_tool.py b/tests/self_coding/test_self_edit_tool.py
similarity index 97%
rename from tests/test_self_edit_tool.py
rename to tests/self_coding/test_self_edit_tool.py
index 2ce2d7a9..fee25698 100644
--- a/tests/test_self_edit_tool.py
+++ b/tests/self_coding/test_self_edit_tool.py
@@ -11,7 +11,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 
-from tools.self_edit import (
+from creative.tools.self_edit import (
     MAX_FILES_PER_COMMIT,
     MAX_RETRIES,
     PROTECTED_FILES,
@@ -40,7 +40,11 @@ def temp_repo():
             ["git", "config", "user.name", "Test"],
             cwd=repo_path, check=True, capture_output=True,
         )
-        
+        subprocess.run(
+            ["git", "config", "commit.gpgsign", "false"],
+            cwd=repo_path, check=True, capture_output=True,
+        )
+
         # Create src structure
         src_path = repo_path / "src" / "myproject"
         src_path.mkdir(parents=True)
@@ -81,7 +85,7 @@ def test_hello():
 @pytest.fixture(autouse=True)
 def mock_settings():
     """Mock settings to enable self-modification."""
-    with patch('tools.self_edit.settings') as mock_settings:
+    with patch('creative.tools.self_edit.settings') as mock_settings:
         mock_settings.self_modify_enabled = True
         yield mock_settings
 
@@ -343,7 +347,7 @@ class TestSelfEditGlobalTool:
     
     async def test_self_edit_tool_singleton(self, temp_repo):
         """Should use singleton pattern."""
-        from tools import self_edit as self_edit_module
+        from creative.tools import self_edit as self_edit_module
         
         # Reset singleton
         self_edit_module._self_edit_tool = None
diff --git a/tests/test_self_modify.py b/tests/self_coding/test_self_modify.py
similarity index 92%
rename from tests/test_self_modify.py
rename to tests/self_coding/test_self_modify.py
index 177941e3..1a4cd9b5 100644
--- a/tests/test_self_modify.py
+++ b/tests/self_coding/test_self_modify.py
@@ -8,7 +8,7 @@ from pathlib import Path
 
 import pytest
 
-from self_modify.loop import SelfModifyLoop, ModifyRequest, ModifyResult
+from self_coding.self_modify.loop import SelfModifyLoop, ModifyRequest, ModifyResult
 
 
 # ── Dataclass tests ───────────────────────────────────────────────────────────
@@ -75,7 +75,7 @@ class TestSelfModifyLoop:
         assert loop._autonomous is True
         assert loop._max_autonomous_cycles == 5
 
-    @patch("self_modify.loop.settings")
+    @patch("self_coding.self_modify.loop.settings")
     def test_run_disabled(self, mock_settings):
         mock_settings.self_modify_enabled = False
         loop = SelfModifyLoop()
@@ -83,8 +83,8 @@ class TestSelfModifyLoop:
         assert not result.success
         assert "disabled" in result.error.lower()
 
-    @patch("self_modify.loop.os.environ", {"SELF_MODIFY_SKIP_BRANCH": "1"})
-    @patch("self_modify.loop.settings")
+    @patch("self_coding.self_modify.loop.os.environ", {"SELF_MODIFY_SKIP_BRANCH": "1"})
+    @patch("self_coding.self_modify.loop.settings")
     def test_run_no_target_files(self, mock_settings):
         mock_settings.self_modify_enabled = True
         mock_settings.self_modify_max_retries = 0
@@ -96,8 +96,8 @@ class TestSelfModifyLoop:
         assert not result.success
         assert "no target files" in result.error.lower()
 
-    @patch("self_modify.loop.os.environ", {"SELF_MODIFY_SKIP_BRANCH": "1"})
-    @patch("self_modify.loop.settings")
+    @patch("self_coding.self_modify.loop.os.environ", {"SELF_MODIFY_SKIP_BRANCH": "1"})
+    @patch("self_coding.self_modify.loop.settings")
     def test_run_success_path(self, mock_settings):
         mock_settings.self_modify_enabled = True
         mock_settings.self_modify_max_retries = 2
@@ -125,8 +125,8 @@ class TestSelfModifyLoop:
         loop._run_tests.assert_called_once()
         loop._git_commit.assert_called_once()
 
-    @patch("self_modify.loop.os.environ", {"SELF_MODIFY_SKIP_BRANCH": "1"})
-    @patch("self_modify.loop.settings")
+    @patch("self_coding.self_modify.loop.os.environ", {"SELF_MODIFY_SKIP_BRANCH": "1"})
+    @patch("self_coding.self_modify.loop.settings")
     def test_run_test_failure_reverts(self, mock_settings):
         mock_settings.self_modify_enabled = True
         mock_settings.self_modify_max_retries = 0
@@ -151,8 +151,8 @@ class TestSelfModifyLoop:
         assert not result.test_passed
         loop._revert_files.assert_called()
 
-    @patch("self_modify.loop.os.environ", {"SELF_MODIFY_SKIP_BRANCH": "1"})
-    @patch("self_modify.loop.settings")
+    @patch("self_coding.self_modify.loop.os.environ", {"SELF_MODIFY_SKIP_BRANCH": "1"})
+    @patch("self_coding.self_modify.loop.settings")
     def test_dry_run(self, mock_settings):
         mock_settings.self_modify_enabled = True
         mock_settings.self_modify_max_retries = 2
@@ -207,8 +207,8 @@ class TestSyntaxValidation:
         errors = loop._validate_syntax({"README.md": "this is not python {{{}"})
         assert errors == {}
 
-    @patch("self_modify.loop.os.environ", {"SELF_MODIFY_SKIP_BRANCH": "1"})
-    @patch("self_modify.loop.settings")
+    @patch("self_coding.self_modify.loop.os.environ", {"SELF_MODIFY_SKIP_BRANCH": "1"})
+    @patch("self_coding.self_modify.loop.settings")
     def test_syntax_error_skips_write(self, mock_settings):
         """When LLM produces invalid syntax, we skip writing and retry."""
         mock_settings.self_modify_enabled = True
@@ -264,8 +264,8 @@ class TestBackendResolution:
 
 
 class TestAutonomousLoop:
-    @patch("self_modify.loop.os.environ", {"SELF_MODIFY_SKIP_BRANCH": "1"})
-    @patch("self_modify.loop.settings")
+    @patch("self_coding.self_modify.loop.os.environ", {"SELF_MODIFY_SKIP_BRANCH": "1"})
+    @patch("self_coding.self_modify.loop.settings")
     def test_autonomous_retries_after_failure(self, mock_settings):
         mock_settings.self_modify_enabled = True
         mock_settings.self_modify_max_retries = 0
@@ -371,43 +371,43 @@ class TestFileInference:
 
 class TestCodeIntent:
     def test_detects_modify_code(self):
-        from voice.nlu import detect_intent
+        from integrations.voice.nlu import detect_intent
 
         intent = detect_intent("modify the code in config.py")
         assert intent.name == "code"
 
     def test_detects_self_modify(self):
-        from voice.nlu import detect_intent
+        from integrations.voice.nlu import detect_intent
 
         intent = detect_intent("self-modify to add a new endpoint")
         assert intent.name == "code"
 
     def test_detects_edit_source(self):
-        from voice.nlu import detect_intent
+        from integrations.voice.nlu import detect_intent
 
         intent = detect_intent("edit the source to fix the bug")
         assert intent.name == "code"
 
     def test_detects_update_your_code(self):
-        from voice.nlu import detect_intent
+        from integrations.voice.nlu import detect_intent
 
         intent = detect_intent("update your code to handle errors")
         assert intent.name == "code"
 
     def test_detects_fix_function(self):
-        from voice.nlu import detect_intent
+        from integrations.voice.nlu import detect_intent
 
         intent = detect_intent("fix the function that calculates totals")
         assert intent.name == "code"
 
     def test_does_not_match_general_chat(self):
-        from voice.nlu import detect_intent
+        from integrations.voice.nlu import detect_intent
 
         intent = detect_intent("tell me about the weather today")
         assert intent.name == "chat"
 
     def test_extracts_target_file_entity(self):
-        from voice.nlu import detect_intent
+        from integrations.voice.nlu import detect_intent
 
         intent = detect_intent("modify file src/config.py to add debug flag")
         assert intent.entities.get("target_file") == "src/config.py"
diff --git a/tests/test_watchdog.py b/tests/self_coding/test_watchdog.py
similarity index 64%
rename from tests/test_watchdog.py
rename to tests/self_coding/test_watchdog.py
index 934209c4..0e43a2c7 100644
--- a/tests/test_watchdog.py
+++ b/tests/self_coding/test_watchdog.py
@@ -1,6 +1,6 @@
 from unittest.mock import MagicMock, patch
 
-from self_tdd.watchdog import _run_tests
+from self_coding.self_tdd.watchdog import _run_tests
 
 
 def _mock_result(returncode: int, stdout: str = "", stderr: str = "") -> MagicMock:
@@ -12,26 +12,26 @@ def _mock_result(returncode: int, stdout: str = "", stderr: str = "") -> MagicMo
 
 
 def test_run_tests_returns_true_when_suite_passes():
-    with patch("self_tdd.watchdog.subprocess.run", return_value=_mock_result(0, "5 passed")):
+    with patch("self_coding.self_tdd.watchdog.subprocess.run", return_value=_mock_result(0, "5 passed")):
         passed, _ = _run_tests()
     assert passed is True
 
 
 def test_run_tests_returns_false_when_suite_fails():
-    with patch("self_tdd.watchdog.subprocess.run", return_value=_mock_result(1, "1 failed")):
+    with patch("self_coding.self_tdd.watchdog.subprocess.run", return_value=_mock_result(1, "1 failed")):
         passed, _ = _run_tests()
     assert passed is False
 
 
 def test_run_tests_output_includes_stdout():
-    with patch("self_tdd.watchdog.subprocess.run", return_value=_mock_result(0, stdout="5 passed")):
+    with patch("self_coding.self_tdd.watchdog.subprocess.run", return_value=_mock_result(0, stdout="5 passed")):
         _, output = _run_tests()
     assert "5 passed" in output
 
 
 def test_run_tests_output_combines_stdout_and_stderr():
     with patch(
-        "self_tdd.watchdog.subprocess.run",
+        "self_coding.self_tdd.watchdog.subprocess.run",
         return_value=_mock_result(1, stdout="FAILED test_foo", stderr="ImportError: no module named bar"),
     ):
         _, output = _run_tests()
@@ -40,7 +40,7 @@ def test_run_tests_output_combines_stdout_and_stderr():
 
 
 def test_run_tests_invokes_pytest_with_correct_flags():
-    with patch("self_tdd.watchdog.subprocess.run", return_value=_mock_result(0)) as mock_run:
+    with patch("self_coding.self_tdd.watchdog.subprocess.run", return_value=_mock_result(0)) as mock_run:
         _run_tests()
     cmd = mock_run.call_args[0][0]
     assert "pytest" in cmd
@@ -49,6 +49,6 @@ def test_run_tests_invokes_pytest_with_correct_flags():
 
 
 def test_run_tests_uses_60s_timeout():
-    with patch("self_tdd.watchdog.subprocess.run", return_value=_mock_result(0)) as mock_run:
+    with patch("self_coding.self_tdd.watchdog.subprocess.run", return_value=_mock_result(0)) as mock_run:
         _run_tests()
     assert mock_run.call_args.kwargs["timeout"] == 60
diff --git a/tests/test_watchdog_functional.py b/tests/self_coding/test_watchdog_functional.py
similarity index 80%
rename from tests/test_watchdog_functional.py
rename to tests/self_coding/test_watchdog_functional.py
index a5153501..4193fcef 100644
--- a/tests/test_watchdog_functional.py
+++ b/tests/self_coding/test_watchdog_functional.py
@@ -7,11 +7,11 @@ from unittest.mock import patch, MagicMock, call
 
 import pytest
 
-from self_tdd.watchdog import _run_tests, watch
+from self_coding.self_tdd.watchdog import _run_tests, watch
 
 
 class TestRunTests:
-    @patch("self_tdd.watchdog.subprocess.run")
+    @patch("self_coding.self_tdd.watchdog.subprocess.run")
     def test_run_tests_passing(self, mock_run):
         mock_run.return_value = MagicMock(
             returncode=0,
@@ -22,7 +22,7 @@ class TestRunTests:
         assert passed is True
         assert "5 passed" in output
 
-    @patch("self_tdd.watchdog.subprocess.run")
+    @patch("self_coding.self_tdd.watchdog.subprocess.run")
     def test_run_tests_failing(self, mock_run):
         mock_run.return_value = MagicMock(
             returncode=1,
@@ -34,7 +34,7 @@ class TestRunTests:
         assert "2 failed" in output
         assert "ERRORS" in output
 
-    @patch("self_tdd.watchdog.subprocess.run")
+    @patch("self_coding.self_tdd.watchdog.subprocess.run")
     def test_run_tests_command_format(self, mock_run):
         mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
         _run_tests()
@@ -48,9 +48,9 @@ class TestRunTests:
 
 
 class TestWatch:
-    @patch("self_tdd.watchdog.time.sleep")
-    @patch("self_tdd.watchdog._run_tests")
-    @patch("self_tdd.watchdog.typer")
+    @patch("self_coding.self_tdd.watchdog.time.sleep")
+    @patch("self_coding.self_tdd.watchdog._run_tests")
+    @patch("self_coding.self_tdd.watchdog.typer")
     def test_watch_first_pass(self, mock_typer, mock_tests, mock_sleep):
         """First iteration: None→passing → should print green message."""
         call_count = 0
@@ -67,9 +67,9 @@ class TestWatch:
         # Should have printed green "All tests passing" message
         mock_typer.secho.assert_called()
 
-    @patch("self_tdd.watchdog.time.sleep")
-    @patch("self_tdd.watchdog._run_tests")
-    @patch("self_tdd.watchdog.typer")
+    @patch("self_coding.self_tdd.watchdog.time.sleep")
+    @patch("self_coding.self_tdd.watchdog._run_tests")
+    @patch("self_coding.self_tdd.watchdog.typer")
     def test_watch_regression(self, mock_typer, mock_tests, mock_sleep):
         """Regression: passing→failing → should print red message + output."""
         results = [(True, "ok"), (False, "FAILED: test_foo"), KeyboardInterrupt]
@@ -91,9 +91,9 @@ class TestWatch:
         secho_calls = [str(c) for c in mock_typer.secho.call_args_list]
         assert any("Regression" in c for c in secho_calls) or any("RED" in c for c in secho_calls)
 
-    @patch("self_tdd.watchdog.time.sleep")
-    @patch("self_tdd.watchdog._run_tests")
-    @patch("self_tdd.watchdog.typer")
+    @patch("self_coding.self_tdd.watchdog.time.sleep")
+    @patch("self_coding.self_tdd.watchdog._run_tests")
+    @patch("self_coding.self_tdd.watchdog.typer")
     def test_watch_keyboard_interrupt(self, mock_typer, mock_tests, mock_sleep):
         mock_tests.side_effect = KeyboardInterrupt
         watch(interval=60)
diff --git a/tests/spark/__init__.py b/tests/spark/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/tests/test_event_log.py b/tests/spark/test_event_log.py
similarity index 100%
rename from tests/test_event_log.py
rename to tests/spark/test_event_log.py
diff --git a/tests/test_spark.py b/tests/spark/test_spark.py
similarity index 100%
rename from tests/test_spark.py
rename to tests/spark/test_spark.py
diff --git a/tests/test_spark_tools_creative.py b/tests/spark/test_spark_tools_creative.py
similarity index 100%
rename from tests/test_spark_tools_creative.py
rename to tests/spark/test_spark_tools_creative.py
diff --git a/tests/swarm/__init__.py b/tests/swarm/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/tests/test_approvals.py b/tests/swarm/test_approvals.py
similarity index 100%
rename from tests/test_approvals.py
rename to tests/swarm/test_approvals.py
diff --git a/tests/test_coordinator.py b/tests/swarm/test_coordinator.py
similarity index 100%
rename from tests/test_coordinator.py
rename to tests/swarm/test_coordinator.py
diff --git a/tests/test_docker_agent.py b/tests/swarm/test_docker_agent.py
similarity index 100%
rename from tests/test_docker_agent.py
rename to tests/swarm/test_docker_agent.py
diff --git a/tests/test_docker_runner.py b/tests/swarm/test_docker_runner.py
similarity index 100%
rename from tests/test_docker_runner.py
rename to tests/swarm/test_docker_runner.py
diff --git a/tests/test_inter_agent.py b/tests/swarm/test_inter_agent.py
similarity index 100%
rename from tests/test_inter_agent.py
rename to tests/swarm/test_inter_agent.py
diff --git a/tests/swarm/test_reward_scoring.py b/tests/swarm/test_reward_scoring.py
new file mode 100644
index 00000000..34939ef4
--- /dev/null
+++ b/tests/swarm/test_reward_scoring.py
@@ -0,0 +1,197 @@
+"""Tests for reward model scoring in the swarm learner."""
+
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from swarm.learner import (
+    RewardScore,
+    get_reward_scores,
+    score_output,
+)
+
+
+@pytest.fixture(autouse=True)
+def _isolate_db(tmp_path):
+    """Point the learner at a temporary database."""
+    db = tmp_path / "learner_test.db"
+    with patch("swarm.learner.DB_PATH", db):
+        yield
+
+
+class TestScoreOutput:
+    """Test the score_output function."""
+
+    def test_returns_none_when_disabled(self):
+        with patch("swarm.learner._settings") as mock_s:
+            mock_s.reward_model_enabled = False
+            result = score_output("task-1", "agent-1", "do X", "done X")
+        assert result is None
+
+    def test_returns_none_when_no_model(self):
+        with patch("swarm.learner._settings") as mock_s:
+            mock_s.reward_model_enabled = True
+            mock_s.reward_model_name = ""
+            with patch(
+                "infrastructure.models.registry.model_registry"
+            ) as mock_reg:
+                mock_reg.get_reward_model.return_value = None
+                result = score_output("task-1", "agent-1", "do X", "done X")
+        assert result is None
+
+    def test_positive_scoring(self):
+        """All votes return GOOD → score = 1.0."""
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.json.return_value = {"response": "GOOD"}
+
+        with patch("swarm.learner._settings") as mock_s:
+            mock_s.reward_model_enabled = True
+            mock_s.reward_model_name = "test-model"
+            mock_s.reward_model_votes = 3
+            mock_s.ollama_url = "http://localhost:11434"
+
+            with patch("requests.post", return_value=mock_response):
+                result = score_output("task-1", "agent-1", "do X", "done X")
+
+        assert result is not None
+        assert result.score == 1.0
+        assert result.positive_votes == 3
+        assert result.negative_votes == 0
+        assert result.total_votes == 3
+        assert result.model_used == "test-model"
+
+    def test_negative_scoring(self):
+        """All votes return BAD → score = -1.0."""
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.json.return_value = {"response": "BAD"}
+
+        with patch("swarm.learner._settings") as mock_s:
+            mock_s.reward_model_enabled = True
+            mock_s.reward_model_name = "test-model"
+            mock_s.reward_model_votes = 3
+            mock_s.ollama_url = "http://localhost:11434"
+
+            with patch("requests.post", return_value=mock_response):
+                result = score_output("task-1", "agent-1", "do X", "bad output")
+
+        assert result is not None
+        assert result.score == -1.0
+        assert result.negative_votes == 3
+
+    def test_mixed_scoring(self):
+        """2 GOOD + 1 BAD → score ≈ 0.33."""
+        responses = []
+        for text in ["GOOD", "GOOD", "BAD"]:
+            resp = MagicMock()
+            resp.status_code = 200
+            resp.json.return_value = {"response": text}
+            responses.append(resp)
+
+        with patch("swarm.learner._settings") as mock_s:
+            mock_s.reward_model_enabled = True
+            mock_s.reward_model_name = "test-model"
+            mock_s.reward_model_votes = 3
+            mock_s.ollama_url = "http://localhost:11434"
+
+            with patch("requests.post", side_effect=responses):
+                result = score_output("task-1", "agent-1", "do X", "ok output")
+
+        assert result is not None
+        assert abs(result.score - (1 / 3)) < 0.01
+        assert result.positive_votes == 2
+        assert result.negative_votes == 1
+
+    def test_uses_registry_reward_model(self):
+        """Falls back to registry reward model when setting is empty."""
+        mock_model = MagicMock()
+        mock_model.path = "registry-reward-model"
+        mock_model.format = MagicMock()
+        mock_model.format.value = "ollama"
+
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.json.return_value = {"response": "GOOD"}
+
+        with patch("swarm.learner._settings") as mock_s:
+            mock_s.reward_model_enabled = True
+            mock_s.reward_model_name = ""
+            mock_s.reward_model_votes = 1
+            mock_s.ollama_url = "http://localhost:11434"
+
+            with patch(
+                "infrastructure.models.registry.model_registry"
+            ) as mock_reg:
+                mock_reg.get_reward_model.return_value = mock_model
+
+                with patch("requests.post", return_value=mock_response):
+                    result = score_output("task-1", "agent-1", "do X", "ok")
+
+        assert result is not None
+        assert result.model_used == "registry-reward-model"
+
+
+class TestGetRewardScores:
+    """Test retrieving historical reward scores."""
+
+    def test_empty_history(self):
+        scores = get_reward_scores()
+        assert scores == []
+
+    def test_scores_persisted(self):
+        """Scores from score_output are retrievable."""
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.json.return_value = {"response": "GOOD"}
+
+        with patch("swarm.learner._settings") as mock_s:
+            mock_s.reward_model_enabled = True
+            mock_s.reward_model_name = "test-model"
+            mock_s.reward_model_votes = 1
+            mock_s.ollama_url = "http://localhost:11434"
+
+            with patch("requests.post", return_value=mock_response):
+                score_output("task-1", "agent-1", "do X", "done X")
+
+        scores = get_reward_scores()
+        assert len(scores) == 1
+        assert scores[0]["task_id"] == "task-1"
+        assert scores[0]["agent_id"] == "agent-1"
+        assert scores[0]["score"] == 1.0
+
+    def test_filter_by_agent(self):
+        """Filter scores by agent_id."""
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.json.return_value = {"response": "GOOD"}
+
+        with patch("swarm.learner._settings") as mock_s:
+            mock_s.reward_model_enabled = True
+            mock_s.reward_model_name = "test-model"
+            mock_s.reward_model_votes = 1
+            mock_s.ollama_url = "http://localhost:11434"
+
+            with patch("requests.post", return_value=mock_response):
+                score_output("task-1", "agent-1", "task A", "output A")
+                score_output("task-2", "agent-2", "task B", "output B")
+
+        agent1_scores = get_reward_scores(agent_id="agent-1")
+        assert len(agent1_scores) == 1
+        assert agent1_scores[0]["agent_id"] == "agent-1"
+
+
+class TestRewardScoreDataclass:
+    """Test RewardScore construction."""
+
+    def test_create_score(self):
+        score = RewardScore(
+            score=0.5,
+            positive_votes=3,
+            negative_votes=1,
+            total_votes=4,
+            model_used="test-model",
+        )
+        assert score.score == 0.5
+        assert score.total_votes == 4
diff --git a/tests/test_swarm.py b/tests/swarm/test_swarm.py
similarity index 100%
rename from tests/test_swarm.py
rename to tests/swarm/test_swarm.py
diff --git a/tests/test_swarm_integration.py b/tests/swarm/test_swarm_integration.py
similarity index 100%
rename from tests/test_swarm_integration.py
rename to tests/swarm/test_swarm_integration.py
diff --git a/tests/test_swarm_integration_full.py b/tests/swarm/test_swarm_integration_full.py
similarity index 100%
rename from tests/test_swarm_integration_full.py
rename to tests/swarm/test_swarm_integration_full.py
diff --git a/tests/test_swarm_live_page.py b/tests/swarm/test_swarm_live_page.py
similarity index 100%
rename from tests/test_swarm_live_page.py
rename to tests/swarm/test_swarm_live_page.py
diff --git a/tests/test_swarm_node.py b/tests/swarm/test_swarm_node.py
similarity index 100%
rename from tests/test_swarm_node.py
rename to tests/swarm/test_swarm_node.py
diff --git a/tests/test_swarm_personas.py b/tests/swarm/test_swarm_personas.py
similarity index 100%
rename from tests/test_swarm_personas.py
rename to tests/swarm/test_swarm_personas.py
diff --git a/tests/test_swarm_recovery.py b/tests/swarm/test_swarm_recovery.py
similarity index 100%
rename from tests/test_swarm_recovery.py
rename to tests/swarm/test_swarm_recovery.py
diff --git a/tests/test_swarm_routes_functional.py b/tests/swarm/test_swarm_routes_functional.py
similarity index 100%
rename from tests/test_swarm_routes_functional.py
rename to tests/swarm/test_swarm_routes_functional.py
diff --git a/tests/test_swarm_routing.py b/tests/swarm/test_swarm_routing.py
similarity index 100%
rename from tests/test_swarm_routing.py
rename to tests/swarm/test_swarm_routing.py
diff --git a/tests/test_swarm_stats.py b/tests/swarm/test_swarm_stats.py
similarity index 100%
rename from tests/test_swarm_stats.py
rename to tests/swarm/test_swarm_stats.py
diff --git a/tests/test_task_queue.py b/tests/swarm/test_task_queue.py
similarity index 94%
rename from tests/test_task_queue.py
rename to tests/swarm/test_task_queue.py
index 2ed6eae4..a35b298a 100644
--- a/tests/test_task_queue.py
+++ b/tests/swarm/test_task_queue.py
@@ -16,7 +16,7 @@ os.environ["TIMMY_TEST_MODE"] = "1"
 
 
 def test_create_task():
-    from task_queue.models import create_task, TaskStatus, TaskPriority
+    from swarm.task_queue.models import create_task, TaskStatus, TaskPriority
 
     task = create_task(
         title="Test task",
@@ -34,7 +34,7 @@ def test_create_task():
 
 
 def test_get_task():
-    from task_queue.models import create_task, get_task
+    from swarm.task_queue.models import create_task, get_task
 
     task = create_task(title="Get me", created_by="test")
     retrieved = get_task(task.id)
@@ -43,13 +43,13 @@ def test_get_task():
 
 
 def test_get_task_not_found():
-    from task_queue.models import get_task
+    from swarm.task_queue.models import get_task
 
     assert get_task("nonexistent-id") is None
 
 
 def test_list_tasks():
-    from task_queue.models import create_task, list_tasks, TaskStatus
+    from swarm.task_queue.models import create_task, list_tasks, TaskStatus
 
     create_task(title="List test 1", created_by="test")
     create_task(title="List test 2", created_by="test")
@@ -58,7 +58,7 @@ def test_list_tasks():
 
 
 def test_list_tasks_with_status_filter():
-    from task_queue.models import (
+    from swarm.task_queue.models import (
         create_task, list_tasks, update_task_status, TaskStatus,
     )
 
@@ -69,7 +69,7 @@ def test_list_tasks_with_status_filter():
 
 
 def test_update_task_status():
-    from task_queue.models import (
+    from swarm.task_queue.models import (
         create_task, update_task_status, TaskStatus,
     )
 
@@ -79,7 +79,7 @@ def test_update_task_status():
 
 
 def test_update_task_running_sets_started_at():
-    from task_queue.models import (
+    from swarm.task_queue.models import (
         create_task, update_task_status, TaskStatus,
     )
 
@@ -89,7 +89,7 @@ def test_update_task_running_sets_started_at():
 
 
 def test_update_task_completed_sets_completed_at():
-    from task_queue.models import (
+    from swarm.task_queue.models import (
         create_task, update_task_status, TaskStatus,
     )
 
@@ -100,7 +100,7 @@ def test_update_task_completed_sets_completed_at():
 
 
 def test_update_task_fields():
-    from task_queue.models import create_task, update_task
+    from swarm.task_queue.models import create_task, update_task
 
     task = create_task(title="Modify test", created_by="test")
     updated = update_task(task.id, title="Modified title", priority="high")
@@ -109,7 +109,7 @@ def test_update_task_fields():
 
 
 def test_get_counts_by_status():
-    from task_queue.models import create_task, get_counts_by_status
+    from swarm.task_queue.models import create_task, get_counts_by_status
 
     create_task(title="Count test", created_by="test")
     counts = get_counts_by_status()
@@ -117,7 +117,7 @@ def test_get_counts_by_status():
 
 
 def test_get_pending_count():
-    from task_queue.models import create_task, get_pending_count
+    from swarm.task_queue.models import create_task, get_pending_count
 
     create_task(title="Pending count test", created_by="test")
     count = get_pending_count()
@@ -125,7 +125,7 @@ def test_get_pending_count():
 
 
 def test_update_task_steps():
-    from task_queue.models import create_task, update_task_steps, get_task
+    from swarm.task_queue.models import create_task, update_task_steps, get_task
 
     task = create_task(title="Steps test", created_by="test")
     steps = [
@@ -140,14 +140,14 @@ def test_update_task_steps():
 
 
 def test_auto_approve_not_triggered_by_default():
-    from task_queue.models import create_task, TaskStatus
+    from swarm.task_queue.models import create_task, TaskStatus
 
     task = create_task(title="No auto", created_by="user", auto_approve=False)
     assert task.status == TaskStatus.PENDING_APPROVAL
 
 
 def test_get_task_summary_for_briefing():
-    from task_queue.models import create_task, get_task_summary_for_briefing
+    from swarm.task_queue.models import create_task, get_task_summary_for_briefing
 
     create_task(title="Briefing test", created_by="test")
     summary = get_task_summary_for_briefing()
@@ -272,7 +272,7 @@ def test_cancel_task_htmx(client):
 
 
 def test_retry_failed_task(client):
-    from task_queue.models import create_task, update_task_status, TaskStatus
+    from swarm.task_queue.models import create_task, update_task_status, TaskStatus
 
     task = create_task(title="To retry", created_by="test")
     update_task_status(task.id, TaskStatus.FAILED, result="Something broke")
@@ -533,7 +533,7 @@ class TestBuildQueueContext:
 
     def test_returns_string_with_counts(self):
         from dashboard.routes.agents import _build_queue_context
-        from task_queue.models import create_task
+        from swarm.task_queue.models import create_task
         create_task(title="Context test task", created_by="test")
         ctx = _build_queue_context()
         assert "[System: Task queue" in ctx
@@ -541,7 +541,7 @@ class TestBuildQueueContext:
 
     def test_returns_empty_on_error(self):
         from dashboard.routes.agents import _build_queue_context
-        with patch("task_queue.models.get_counts_by_status", side_effect=Exception("DB error")):
+        with patch("swarm.task_queue.models.get_counts_by_status", side_effect=Exception("DB error")):
             ctx = _build_queue_context()
             assert isinstance(ctx, str)
             assert ctx == ""
@@ -552,7 +552,7 @@ class TestBuildQueueContext:
 
 def test_briefing_task_queue_summary():
     """Briefing engine should include task queue data."""
-    from task_queue.models import create_task
+    from swarm.task_queue.models import create_task
     from timmy.briefing import _gather_task_queue_summary
 
     create_task(title="Briefing integration test", created_by="test")
diff --git a/tests/test_work_orders.py b/tests/swarm/test_work_orders.py
similarity index 98%
rename from tests/test_work_orders.py
rename to tests/swarm/test_work_orders.py
index 1a86552a..50fe81bc 100644
--- a/tests/test_work_orders.py
+++ b/tests/swarm/test_work_orders.py
@@ -1,6 +1,6 @@
 """Tests for the work order system."""
 
-from work_orders.models import (
+from swarm.work_orders.models import (
     WorkOrder,
     WorkOrderCategory,
     WorkOrderPriority,
@@ -12,7 +12,7 @@ from work_orders.models import (
     list_work_orders,
     update_work_order_status,
 )
-from work_orders.risk import compute_risk_score, should_auto_execute
+from swarm.work_orders.risk import compute_risk_score, should_auto_execute
 
 
 # ── Model CRUD tests ──────────────────────────────────────────────────────────
diff --git a/tests/test_xss_prevention.py b/tests/test_xss_prevention.py
deleted file mode 100644
index f1d65499..00000000
--- a/tests/test_xss_prevention.py
+++ /dev/null
@@ -1,25 +0,0 @@
-"""Regression tests for XSS prevention in the dashboard."""
-
-import pytest
-from fastapi.testclient import TestClient
-
-def test_mobile_test_page_xss_prevention(client: TestClient):
-    """
-    Verify that the mobile-test page uses safer DOM manipulation.
-    This test checks the template content for the presence of textContent 
-    and proper usage of innerHTML for known safe constants.
-    """
-    response = client.get("/mobile-test")
-    assert response.status_code == 200
-    content = response.text
-    
-    # Check that we are using textContent for dynamic content
-    assert "textContent =" in content
-    
-    # Check that we've updated the summaryBody.innerHTML usage to be safer
-    # or replaced with appendChild/textContent where appropriate.
-    # The fix uses innerHTML with template literals for structural parts 
-    # but textContent for data parts.
-    assert "summaryBody.innerHTML = '';" in content
-    assert "p.textContent =" in content
-    assert "statusMsg.textContent =" in content
diff --git a/tests/timmy/__init__.py b/tests/timmy/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/tests/test_agent.py b/tests/timmy/test_agent.py
similarity index 100%
rename from tests/test_agent.py
rename to tests/timmy/test_agent.py
diff --git a/tests/test_agent_core.py b/tests/timmy/test_agent_core.py
similarity index 98%
rename from tests/test_agent_core.py
rename to tests/timmy/test_agent_core.py
index e85c2634..097c1564 100644
--- a/tests/test_agent_core.py
+++ b/tests/timmy/test_agent_core.py
@@ -10,7 +10,7 @@ from unittest.mock import MagicMock, patch
 
 import pytest
 
-from agent_core.interface import (
+from timmy.agent_core.interface import (
     ActionType,
     AgentCapability,
     AgentEffect,
@@ -303,14 +303,14 @@ class TestOllamaAgent:
 
     @pytest.fixture
     def agent(self):
-        with patch("agent_core.ollama_adapter.create_timmy") as mock_ct:
+        with patch("timmy.agent_core.ollama_adapter.create_timmy") as mock_ct:
             mock_timmy = MagicMock()
             mock_run = MagicMock()
             mock_run.content = "Mocked LLM response"
             mock_timmy.run.return_value = mock_run
             mock_ct.return_value = mock_timmy
 
-            from agent_core.ollama_adapter import OllamaAgent
+            from timmy.agent_core.ollama_adapter import OllamaAgent
             identity = AgentIdentity.generate("TestTimmy")
             return OllamaAgent(identity, effect_log="/tmp/test_effects")
 
@@ -433,10 +433,10 @@ class TestOllamaAgent:
         assert log[2]["type"] == "act"
 
     def test_no_effect_log_when_disabled(self):
-        with patch("agent_core.ollama_adapter.create_timmy") as mock_ct:
+        with patch("timmy.agent_core.ollama_adapter.create_timmy") as mock_ct:
             mock_timmy = MagicMock()
             mock_ct.return_value = mock_timmy
-            from agent_core.ollama_adapter import OllamaAgent
+            from timmy.agent_core.ollama_adapter import OllamaAgent
             identity = AgentIdentity.generate("NoLog")
             agent = OllamaAgent(identity)  # no effect_log
             assert agent.get_effect_log() is None
diff --git a/tests/test_agent_runner.py b/tests/timmy/test_agent_runner.py
similarity index 100%
rename from tests/test_agent_runner.py
rename to tests/timmy/test_agent_runner.py
diff --git a/tests/test_backends.py b/tests/timmy/test_backends.py
similarity index 100%
rename from tests/test_backends.py
rename to tests/timmy/test_backends.py
diff --git a/tests/test_calculator.py b/tests/timmy/test_calculator.py
similarity index 100%
rename from tests/test_calculator.py
rename to tests/timmy/test_calculator.py
diff --git a/tests/test_cli.py b/tests/timmy/test_cli.py
similarity index 100%
rename from tests/test_cli.py
rename to tests/timmy/test_cli.py
diff --git a/tests/timmy/test_grok_backend.py b/tests/timmy/test_grok_backend.py
new file mode 100644
index 00000000..688ded4a
--- /dev/null
+++ b/tests/timmy/test_grok_backend.py
@@ -0,0 +1,284 @@
+"""Tests for GrokBackend in src/timmy/backends.py and Grok dashboard routes."""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+# ── grok_available ───────────────────────────────────────────────────────────
+
+def test_grok_available_false_when_disabled():
+    """Grok not available when GROK_ENABLED is false."""
+    with patch("config.settings") as mock_settings:
+        mock_settings.grok_enabled = False
+        mock_settings.xai_api_key = "xai-test-key"
+        from timmy.backends import grok_available
+        assert grok_available() is False
+
+
+def test_grok_available_false_when_no_key():
+    """Grok not available when XAI_API_KEY is empty."""
+    with patch("config.settings") as mock_settings:
+        mock_settings.grok_enabled = True
+        mock_settings.xai_api_key = ""
+        from timmy.backends import grok_available
+        assert grok_available() is False
+
+
+def test_grok_available_true_when_enabled_and_key_set():
+    """Grok available when both enabled and key are set."""
+    with patch("config.settings") as mock_settings:
+        mock_settings.grok_enabled = True
+        mock_settings.xai_api_key = "xai-test-key"
+        from timmy.backends import grok_available
+        assert grok_available() is True
+
+
+# ── GrokBackend construction ────────────────────────────────────────────────
+
+def test_grok_backend_init_with_explicit_params():
+    """GrokBackend can be created with explicit api_key and model."""
+    from timmy.backends import GrokBackend
+    backend = GrokBackend(api_key="xai-test", model="grok-3-fast")
+    assert backend._api_key == "xai-test"
+    assert backend._model == "grok-3-fast"
+    assert backend.stats.total_requests == 0
+
+
+def test_grok_backend_init_from_settings():
+    """GrokBackend reads from config.settings when no params given."""
+    with patch("config.settings") as mock_settings:
+        mock_settings.xai_api_key = "xai-from-env"
+        mock_settings.grok_default_model = "grok-3"
+        from timmy.backends import GrokBackend
+        backend = GrokBackend()
+        assert backend._api_key == "xai-from-env"
+        assert backend._model == "grok-3"
+
+
+def test_grok_backend_run_no_key_returns_error():
+    """run() gracefully returns error message when no API key."""
+    from timmy.backends import GrokBackend
+    backend = GrokBackend(api_key="", model="grok-3-fast")
+    result = backend.run("hello")
+    assert "not configured" in result.content
+
+
+def test_grok_backend_run_success():
+    """run() returns content from the API on success."""
+    from timmy.backends import GrokBackend
+
+    backend = GrokBackend(api_key="xai-test", model="grok-3-fast")
+
+    mock_response = MagicMock()
+    mock_response.choices = [MagicMock()]
+    mock_response.choices[0].message.content = "Grok says hello"
+    mock_response.usage = MagicMock()
+    mock_response.usage.prompt_tokens = 10
+    mock_response.usage.completion_tokens = 5
+    mock_response.model = "grok-3-fast"
+
+    mock_client = MagicMock()
+    mock_client.chat.completions.create.return_value = mock_response
+
+    with patch.object(backend, "_get_client", return_value=mock_client):
+        result = backend.run("hello")
+
+    assert result.content == "Grok says hello"
+    assert backend.stats.total_requests == 1
+    assert backend.stats.total_prompt_tokens == 10
+    assert backend.stats.total_completion_tokens == 5
+
+
+def test_grok_backend_run_api_error():
+    """run() returns error message on API failure."""
+    from timmy.backends import GrokBackend
+
+    backend = GrokBackend(api_key="xai-test", model="grok-3-fast")
+
+    mock_client = MagicMock()
+    mock_client.chat.completions.create.side_effect = Exception("API timeout")
+
+    with patch.object(backend, "_get_client", return_value=mock_client):
+        result = backend.run("hello")
+
+    assert "unavailable" in result.content
+    assert backend.stats.errors == 1
+
+
+def test_grok_backend_history_management():
+    """GrokBackend maintains conversation history."""
+    from timmy.backends import GrokBackend
+
+    backend = GrokBackend(api_key="xai-test", model="grok-3-fast")
+
+    mock_response = MagicMock()
+    mock_response.choices = [MagicMock()]
+    mock_response.choices[0].message.content = "response"
+    mock_response.usage = MagicMock()
+    mock_response.usage.prompt_tokens = 10
+    mock_response.usage.completion_tokens = 5
+
+    mock_client = MagicMock()
+    mock_client.chat.completions.create.return_value = mock_response
+
+    with patch.object(backend, "_get_client", return_value=mock_client):
+        backend.run("first message")
+        backend.run("second message")
+
+    assert len(backend._history) == 4  # 2 user + 2 assistant
+    assert backend._history[0]["role"] == "user"
+    assert backend._history[1]["role"] == "assistant"
+
+
+def test_grok_backend_health_check_no_key():
+    """health_check() returns not-ok when no API key."""
+    from timmy.backends import GrokBackend
+
+    backend = GrokBackend(api_key="", model="grok-3-fast")
+    health = backend.health_check()
+    assert health["ok"] is False
+    assert "not configured" in health["error"]
+
+
+def test_grok_backend_health_check_success():
+    """health_check() returns ok when API key is set and models endpoint works."""
+    from timmy.backends import GrokBackend
+
+    backend = GrokBackend(api_key="xai-test", model="grok-3-fast")
+
+    mock_client = MagicMock()
+    mock_client.models.list.return_value = []
+
+    with patch.object(backend, "_get_client", return_value=mock_client):
+        health = backend.health_check()
+
+    assert health["ok"] is True
+    assert health["backend"] == "grok"
+
+
+def test_grok_backend_estimated_cost():
+    """estimated_cost property calculates sats from token usage."""
+    from timmy.backends import GrokUsageStats
+
+    stats = GrokUsageStats(
+        total_prompt_tokens=1_000_000,
+        total_completion_tokens=500_000,
+    )
+    # Input: 1M tokens * $5/1M = $5
+    # Output: 500K tokens * $15/1M = $7.50
+    # Total: $12.50 / $0.001 = 12,500 sats
+    assert stats.estimated_cost_sats == 12500
+
+
+def test_grok_backend_build_messages():
+    """_build_messages includes system prompt and history."""
+    from timmy.backends import GrokBackend
+
+    backend = GrokBackend(api_key="xai-test", model="grok-3-fast")
+    backend._history = [
+        {"role": "user", "content": "previous"},
+        {"role": "assistant", "content": "yes"},
+    ]
+
+    messages = backend._build_messages("new question")
+    assert messages[0]["role"] == "system"
+    assert messages[1]["role"] == "user"
+    assert messages[1]["content"] == "previous"
+    assert messages[-1]["role"] == "user"
+    assert messages[-1]["content"] == "new question"
+
+
+# ── get_grok_backend singleton ──────────────────────────────────────────────
+
+def test_get_grok_backend_returns_singleton():
+    """get_grok_backend returns the same instance on repeated calls."""
+    import timmy.backends as backends_mod
+
+    # Reset singleton
+    backends_mod._grok_backend = None
+
+    b1 = backends_mod.get_grok_backend()
+    b2 = backends_mod.get_grok_backend()
+    assert b1 is b2
+
+    # Cleanup
+    backends_mod._grok_backend = None
+
+
+# ── GROK_MODELS constant ───────────────────────────────────────────────────
+
+def test_grok_models_dict_has_expected_entries():
+    from timmy.backends import GROK_MODELS
+    assert "grok-3-fast" in GROK_MODELS
+    assert "grok-3" in GROK_MODELS
+
+
+# ── consult_grok tool ──────────────────────────────────────────────────────
+
+def test_consult_grok_returns_unavailable_when_disabled():
+    """consult_grok tool returns error when Grok is not available."""
+    with patch("timmy.backends.grok_available", return_value=False):
+        from timmy.tools import consult_grok
+        result = consult_grok("test query")
+        assert "not available" in result
+
+
+def test_consult_grok_calls_backend_when_available():
+    """consult_grok tool calls the Grok backend when available."""
+    from timmy.backends import RunResult
+
+    mock_backend = MagicMock()
+    mock_backend.run.return_value = RunResult(content="Grok answer")
+    mock_backend.stats = MagicMock()
+    mock_backend.stats.total_latency_ms = 100
+
+    with patch("timmy.backends.grok_available", return_value=True), \
+         patch("timmy.backends.get_grok_backend", return_value=mock_backend), \
+         patch("config.settings") as mock_settings:
+        mock_settings.grok_free = True
+        mock_settings.grok_enabled = True
+        mock_settings.xai_api_key = "xai-test"
+        from timmy.tools import consult_grok
+        result = consult_grok("complex question")
+
+    assert "Grok answer" in result
+    mock_backend.run.assert_called_once_with("complex question")
+
+
+# ── Grok dashboard route tests ─────────────────────────────────────────────
+
+def test_grok_status_endpoint(client):
+    """GET /grok/status returns JSON with Grok configuration."""
+    response = client.get("/grok/status")
+    assert response.status_code == 200
+    data = response.json()
+    assert "enabled" in data
+    assert "available" in data
+    assert "model" in data
+    assert "api_key_set" in data
+
+
+def test_grok_toggle_returns_html(client):
+    """POST /grok/toggle returns HTML response."""
+    response = client.post("/grok/toggle")
+    assert response.status_code == 200
+
+
+def test_grok_stats_endpoint(client):
+    """GET /grok/stats returns usage statistics."""
+    response = client.get("/grok/stats")
+    assert response.status_code == 200
+    data = response.json()
+    assert "total_requests" in data or "error" in data
+
+
+def test_grok_chat_without_key(client):
+    """POST /grok/chat returns error when Grok is not available."""
+    response = client.post(
+        "/grok/chat",
+        data={"message": "test query"},
+    )
+    assert response.status_code == 200
+    # Should contain error since GROK_ENABLED is false in test mode
+    assert "not available" in response.text.lower() or "error" in response.text.lower() or "grok" in response.text.lower()
diff --git a/tests/test_prompts.py b/tests/timmy/test_prompts.py
similarity index 100%
rename from tests/test_prompts.py
rename to tests/timmy/test_prompts.py
diff --git a/tests/test_reflection.py b/tests/timmy/test_reflection.py
similarity index 100%
rename from tests/test_reflection.py
rename to tests/timmy/test_reflection.py
diff --git a/tests/test_session.py b/tests/timmy/test_session.py
similarity index 100%
rename from tests/test_session.py
rename to tests/timmy/test_session.py
diff --git a/tests/test_timmy_serve_app.py b/tests/timmy/test_timmy_serve_app.py
similarity index 100%
rename from tests/test_timmy_serve_app.py
rename to tests/timmy/test_timmy_serve_app.py
diff --git a/tests/test_timmy_serve_cli.py b/tests/timmy/test_timmy_serve_cli.py
similarity index 100%
rename from tests/test_timmy_serve_cli.py
rename to tests/timmy/test_timmy_serve_cli.py
diff --git a/tests/test_timmy_tools.py b/tests/timmy/test_timmy_tools.py
similarity index 100%
rename from tests/test_timmy_tools.py
rename to tests/timmy/test_timmy_tools.py
diff --git a/tests/test_vector_store.py b/tests/timmy/test_vector_store.py
similarity index 99%
rename from tests/test_vector_store.py
rename to tests/timmy/test_vector_store.py
index 9b4b6f6e..f9113e64 100644
--- a/tests/test_vector_store.py
+++ b/tests/timmy/test_vector_store.py
@@ -1,7 +1,7 @@
 """Tests for vector store (semantic memory) system."""
 
 import pytest
-from memory.vector_store import (
+from timmy.memory.vector_store import (
     store_memory,
     search_memories,
     get_memory_context,