# Nexus — Scope & Acceptance Criteria

**Issue:** #1208
**Date:** 2026-03-23
**Status:** Initial implementation complete; teaching/RL harness deferred

---

## Summary

The **Nexus** is a persistent conversational space where Timmy lives with full
access to his live memory. Unlike the main dashboard chat (which uses tools and
has a transient feel), the Nexus is:

- **Conversational only** — no tool approval flow; pure dialogue
- **Memory-aware** — semantically relevant memories surface alongside each exchange
- **Teachable** — the operator can inject facts directly into Timmy's live memory
- **Persistent** — the session survives page refreshes; history accumulates over time
- **Local** — always backed by Ollama; no cloud inference required

This is the foundation for future LoRA fine-tuning, RL training harnesses, and
eventually real-time self-improvement loops.

---

## Scope (v1 — this PR)

| Area | Included | Deferred |
|------|----------|----------|
| Conversational UI | ✅ Chat panel with HTMX streaming | Streaming tokens |
| Live memory sidebar | ✅ Semantic search on each turn | Auto-refresh on teach |
| Teaching panel | ✅ Inject personal facts | Bulk import, LoRA trigger |
| Session isolation | ✅ Dedicated `nexus` session ID | Per-operator sessions |
| Nav integration | ✅ NEXUS link in INTEL dropdown | Mobile nav |
| CSS/styling | ✅ Two-column responsive layout | Dark/light theme toggle |
| Tests | ✅ 9 unit tests, all green | E2E with real Ollama |
| LoRA / RL harness | ❌ deferred to future issue | |
| Auto-falsework | ❌ deferred | |
| Bannerlord interface | ❌ separate track | |

---

## Acceptance Criteria

### AC-1: Nexus page loads
- **Given** the dashboard is running
- **When** I navigate to `/nexus`
- **Then** I see a two-panel layout: conversation on the left, memory sidebar on the right
- **And** the page title reads "// NEXUS"
- **And** the page is accessible from the nav (INTEL → NEXUS)

### AC-2: Conversation-only chat
- **Given** I am on the Nexus page
- **When** I type a message and submit
- **Then** Timmy responds using the `nexus` session (isolated from dashboard history)
- **And** no tool-approval cards appear — responses are pure text
- **And** my message and Timmy's reply are appended to the chat log

### AC-3: Memory context surfaces automatically
- **Given** I send a message
- **When** the response arrives
- **Then** the "LIVE MEMORY CONTEXT" panel shows up to 4 semantically relevant memories
- **And** each memory entry shows its type and content

### AC-4: Teaching panel stores facts
- **Given** I type a fact into the "TEACH TIMMY" input and submit
- **When** the request completes
- **Then** I see a green confirmation "✓ Taught: <fact>"
- **And** the fact appears in the "KNOWN FACTS" list
- **And** the fact is stored in Timmy's live memory (`store_personal_fact`)

### AC-5: Empty / invalid input is rejected gracefully
- **Given** I submit a blank message or fact
- **Then** no request is made and the log is unchanged
- **Given** I submit a message over 10 000 characters
- **Then** an inline error is shown without crashing the server

### AC-6: Conversation can be cleared
- **Given** the Nexus has conversation history
- **When** I click CLEAR and confirm
- **Then** the chat log shows only a "cleared" confirmation
- **And** the Agno session for `nexus` is reset

### AC-7: Graceful degradation when Ollama is down
- **Given** Ollama is unavailable
- **When** I send a message
- **Then** an error message is shown inline (not a 500 page)
- **And** the app continues to function

### AC-8: No regression on existing tests
- **Given** the nexus route is registered
- **When** `tox -e unit` runs
- **Then** all 343+ existing tests remain green

---

## Future Work (separate issues)

1. **LoRA trigger** — button in the teaching panel to queue a fine-tuning run
   using the current Nexus conversation as training data
2. **RL harness** — reward signal collection during conversation for RLHF
3. **Auto-falsework pipeline** — scaffold harness generation from conversation
4. **Bannerlord interface** — Nexus as the live-memory bridge for in-game Timmy
5. **Streaming responses** — token-by-token display via WebSocket
6. **Per-operator sessions** — isolate Nexus history by logged-in user