commit 9dc6e8e1a3eb8186ab3167b9215bf3cdeb1d2012
Author: Kaysser Kayyali <kaykayyali@gmail.com>
Date:   Sat May 30 04:51:21 2026 +0000

    Initial commit — Mardonar encounter engine with UX improvements
    
    Includes full bot source (Phases 1–4), plus five new features:
    - Epic 1: emoji reaction state machine (👀⏳✅🎲) + burst queue cap at 2 with in-world drop notices
    - Epic 2: per-encounter tone field in YAML injected into LLM system prompt
    - Epic 3: player pronouns via modal registration + system prompt players block
    - Epic 4: strengthened skill_check_emit tool contract + missed-skill-check diagnostic
    
    Also includes UX design docs, epics, and story files under Docs/.
    
    Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..bf8b9cd
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,69 @@
+DISCORD_TOKEN=your_discord_bot_token
+DISCORD_CLIENT_ID=your_discord_application_id
+# DISCORD_GUILD_ID=your_server_id   # Set for instant command registration (vs 1hr global propagation)
+
+# ── Redis ──────────────────────────────────────────────────────────────────────
+# Shared with GraphMCP-Example stack via knowledge-graph-ai_internal network
+REDIS_URL=redis://redis:6379
+
+# How long a session stays alive in Redis without activity (hours)
+# SESSION_TTL_HOURS=12
+
+# ── Ollama / LLM ───────────────────────────────────────────────────────────────
+OLLAMA_BASE_URL=http://192.168.1.x:11434
+OLLAMA_MODEL=gemma4-it:e2b
+
+# Sampling temperature — higher = more creative, lower = more consistent (0–2)
+# OLLAMA_TEMPERATURE=0.75
+
+# Context window in tokens — must match your model's actual max
+# OLLAMA_NUM_CTX=131072
+
+# LLM call timeout in milliseconds
+# OLLAMA_TIMEOUT_MS=120000
+
+# ── GraphMCP ───────────────────────────────────────────────────────────────────
+GRAPHMCP_URL=http://mcp-server:9000
+
+# Minimum semantic similarity score (0–1) to count a chunk as relevant context.
+# Raise to be stricter (fewer but more accurate results).
+# Lower to be more permissive (more context, more noise).
+# GRAPHMCP_SCORE_THRESHOLD=0.68
+
+# How many memory chunks to fetch per NPC at encounter start
+# GRAPHMCP_NPC_MEMORY_LIMIT=5
+
+# How many chunks to fetch when @Zalram is mentioned
+# GRAPHMCP_MENTION_LIMIT=5
+
+# ── Encounter behaviour ────────────────────────────────────────────────────────
+SPECS_DIR=./specs
+
+# Delay before archiving a resolved thread — gives players time to read the ending (ms)
+# ENCOUNTER_ARCHIVE_DELAY_MS=5000
+
+# How long the player-gate embed stays visible before auto-delete (ms)
+# ENCOUNTER_GATE_TIMEOUT_MS=30000
+
+# ── Persona ────────────────────────────────────────────────────────────────────
+# Path to the YAML file defining the bot's @mention persona
+# PERSONA_PATH=./persona.yaml
+
+# ── Access control ─────────────────────────────────────────────────────────────
+# Comma-separated channel IDs where encounters are allowed.
+# The bot checks the parent channel of threads before responding.
+# Leave empty and the bot responds nowhere (secure by default).
+# DISCORD_ALLOWED_CHANNELS=123456789012345678,987654321098765432
+DISCORD_ALLOWED_CHANNELS=
+
+# Comma-separated user IDs who can use /encounter commands. Empty = everyone.
+# DISCORD_ALLOWED_USERS=123456789012345678,987654321098765432
+DISCORD_ALLOWED_USERS=
+
+# ── Logging ────────────────────────────────────────────────────────────────────
+LOG_LEVEL=debug
+
+
+LITELLM_BASE_URL=
+LITELLM_API_KEY=
+LITELLM_MODEL=ollama-cloud
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..4274b51
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,5 @@
+node_modules/
+dist/
+.env
+*.log
+.DS_Store
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..ef8865b
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,32 @@
+FROM node:22-alpine AS builder
+
+RUN apk upgrade --no-cache
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm ci --ignore-scripts
+
+COPY tsconfig.json ./
+COPY src ./src
+
+RUN npm run build
+
+# ── Runtime image ──────────────────────────────────────────────
+FROM node:22-alpine
+
+RUN apk upgrade --no-cache
+
+WORKDIR /app
+
+ENV NODE_ENV=production
+
+COPY package*.json ./
+RUN npm ci --omit=dev --ignore-scripts
+
+COPY --from=builder /app/dist ./dist
+COPY specs ./specs
+COPY lore ./lore
+COPY persona.yaml ./persona.yaml
+
+CMD ["node", "dist/bot/index.js"]
diff --git a/Docs/epics.md b/Docs/epics.md
new file mode 100644
index 0000000..82f41b4
--- /dev/null
+++ b/Docs/epics.md
@@ -0,0 +1,288 @@
+---
+stepsCompleted: ["step-01-validate-prerequisites"]
+inputDocuments:
+  - prd.md
+  - Docs/mardonar-encounter-engine.md
+  - Docs/mardonar-build-plan.md
+  - Docs/ux-designs/ux-mardonar-2026-05-30/DESIGN.md
+  - Docs/ux-designs/ux-mardonar-2026-05-30/EXPERIENCE.md
+---
+
+# Mardonar Encounter Engine - Epic Breakdown
+
+## Overview
+
+This document provides the complete epic and story breakdown for the Mardonar Encounter Engine, covering new features and bug fixes layered on top of the existing engine (Phases 1–4 are substantially complete in the codebase as of 2026-05-30).
+
+## Requirements Inventory
+
+### Functional Requirements
+
+FR1: The bot must add an emoji reaction to a player's message immediately upon receipt to signal it was seen (👀).
+FR2: When a player message enters the LLM processing queue, the 👀 reaction must be replaced with ⏳.
+FR3: When a dice roll is detected in a queued player message, a 🎲 reaction must be added alongside ⏳ for the duration of processing.
+FR4: When the LLM response is posted, ⏳ (and 🎲 if present) must be removed and replaced with ✅ for ~10 seconds, then removed.
+FR5: The message queue must enforce a hard cap of 2 messages per burst. Messages beyond the cap must not be queued.
+FR6: When a player's message is dropped by the queue cap, the bot must send an ephemeral reply to that player with an in-world message.
+FR7: The ephemeral drop notice must be pre-generated (not LLM-generated at runtime) and selected based on the encounter's active tone value.
+FR8: Each encounter YAML spec must support an optional `tone` field (free-text string, e.g. "grim", "tense", "comedic", "mysterious") that drives narration flavor for that encounter.
+FR9: The `tone` value must be injected into the LLM system prompt as a style directive for all narration generated during the encounter.
+FR10: The `tone` value must be cached in session state at session start so it is available synchronously when the drop notice fires.
+FR11: Players must be able to set pronouns as part of their character profile via the existing `/character register custom` command.
+FR12: The player's pronouns must be injected into the LLM system prompt so narration uses the correct pronouns when referring to that player's character.
+FR13: When the LLM detects a player intends to make a skill check (rolling dice), it must reliably call `skill_check_emit` rather than narrating the outcome itself.
+FR14: The system prompt's tool contract must be strengthened with explicit negative instructions and/or few-shot examples to prevent the LLM from self-narrating roll outcomes.
+
+### NonFunctional Requirements
+
+NFR1: Emoji reactions must be added within 200ms of the message being received, before any LLM call is initiated.
+NFR2: Ephemeral drop notices must be sent synchronously within the message-receive path — no LLM call must be made for a dropped message.
+NFR3: The `tone` value must be accessible synchronously (from session state in Redis) when the drop notice fires — no extra async lookup at that moment.
+NFR4: The reaction state machine must never leave a message in a stale state (e.g. ⏳ stuck after a failed LLM call) — cleanup must happen in the finally block of the generation runner.
+NFR5: The queue cap must reset cleanly after each LLM response completes, so the next burst starts with a fresh cap.
+NFR6: All player-facing strings — including drop notices and system confirmations — must use in-world language. The words "bot", "system", "queue", "rate limit", or "error" must never appear in player-visible output.
+
+### Additional Requirements
+
+- Stack: TypeScript / Node.js / discord.js v14. Phases 1–4 are complete. All new work layers on top of the existing engine.
+- The existing `generationQueue.ts` debounce logic (500ms, drain turn) must be preserved. The cap and reactions are additive changes to this file.
+- The `EncounterSpec` Zod schema in `src/spec/loader.ts` and `EncounterSpec` interface in `src/types/index.ts` must both be updated to include `tone?: string`.
+- The `tone` value must be stored on `SessionState` so it survives across message turns without a spec re-read.
+- Pronouns must be stored on the existing `CharacterProfile` type in `src/session/characterRegistry.ts` (or equivalent) and surfaced via `characterRegistry.get()`.
+- The skill check reliability fix is a prompt engineering change in `src/harness/promptBuilder.ts` and potentially a post-dispatch validation step in `src/harness/toolDispatcher.ts`.
+
+### UX Design Requirements
+
+UX-DR1: Reactions are applied to player messages only — never to bot messages.
+UX-DR2: The reaction state machine is: received (👀) → processing (⏳, optionally +🎲 if dice detected) → done (✅ for ~10s then cleared). Reactions must self-clear — no permanent reaction markers on messages.
+UX-DR3: The ephemeral drop notice is a plain text ephemeral reply (not an embed). Tone-keyed strings: grim → "The chaos swallowed your words…"; comedic → "Everyone was talking at once…"; mysterious → "Something muffled your voice…"; tense → "No time — the moment moved on without you…"; baseline → "The echoes could not carry all voices at once…".
+UX-DR4: The `tone` field in encounter YAML is free-text (no enum enforcement). Unrecognised tone values fall back to baseline drop notice string.
+UX-DR5: Pronouns are added as an optional field on `/character register custom`. Default is "they/them" when unset.
+UX-DR6: The `🎲` reaction must only be added when the bot's dice-detection heuristic is confident (e.g. the message contains a roll-related keyword or the pending skill check flag is set).
+
+### FR Coverage Map
+
+| FR | Epic | Story |
+|---|---|---|
+| FR1–FR5 | Epic 1 | 1.1 |
+| FR6–FR7 | Epic 1 | 1.2 |
+| FR8–FR10 | Epic 2 | 2.1 |
+| FR11–FR12 | Epic 3 | 3.1 |
+| FR13–FR14 | Epic 4 | 4.1 |
+| NFR1–NFR6 | Cross-cutting | All stories |
+| UX-DR1–UX-DR6 | Cross-cutting | All stories |
+
+## Epic List
+
+1. Epic 1: Interaction Feedback & Queue Management
+2. Epic 2: Encounter Tone Configuration
+3. Epic 3: Player Pronouns
+4. Epic 4: Dice Roll Reliability Fix
+
+---
+
+## Epic 1: Interaction Feedback & Queue Management
+
+Give players real-time visual feedback on the state of their messages (received, queued, processing, done, dropped) and enforce a hard queue cap of 2 with in-world ephemeral notices for dropped messages.
+
+### Story 1.1: Emoji Reaction State Machine
+
+As a player,
+I want emoji reactions on my messages to show whether they were received and are being processed,
+So that I always know the bot saw my message and what it is doing with it.
+
+**Acceptance Criteria:**
+
+**Given** a player sends a message in an active encounter thread
+**When** the message is received by the bot's message handler
+**Then** the bot adds a 👀 reaction to that message within 200ms, before any LLM call is initiated
+
+**Given** the player's message enters the LLM processing queue (within the 2-message cap)
+**When** the LLM generation begins (inside the `fire()` call in `generationQueue.ts`)
+**Then** the 👀 reaction is removed and ⏳ is added to the message
+
+**Given** the player's message contains a roll-related keyword or the session has a pending skill check
+**When** the message enters the processing queue
+**Then** 🎲 is added alongside ⏳ for the duration of processing
+
+**Given** the LLM response has been posted to the thread
+**When** the generation runner's try block completes
+**Then** ⏳ (and 🎲 if present) are removed, ✅ is added to the message, and ✅ is removed ~10 seconds later
+
+**Given** the LLM call fails or throws an error
+**When** the generation runner's finally block executes
+**Then** all in-progress reactions (⏳, 🎲) are removed from the message so no stale state is left
+
+**Notes:**
+- Reactions are applied only to player messages. Bot messages are never reacted to by the bot.
+- The message ID must be threaded through to the generation runner so reactions can be managed. Pass it as part of the runner closure or as a parameter to `scheduleLLMTurn`.
+- Discord reaction calls (`message.react()`, `reaction.remove()`) should be fire-and-forget with logged errors — they must never cause the message handler to throw or block.
+
+---
+
+### Story 1.2: Queue Cap with In-World Drop Notice
+
+As a player,
+I want to be told privately when my message wasn't processed due to message volume,
+So that I know to wait and try again rather than wondering if the bot is broken.
+
+**Acceptance Criteria:**
+
+**Given** a player's message arrives while 2 messages are already pending in the queue
+**When** the queue cap check runs (in `scheduleLLMTurn` or the message handler before enqueuing)
+**Then** the message is NOT added to the queue and the bot does NOT call the LLM for it
+
+**Given** the player's message was dropped by the cap
+**When** the drop is detected
+**Then** the bot sends an ephemeral reply to that player's message with the in-world drop notice for the session's active tone
+
+**Given** the session's `tone` value is "grim"
+**When** a drop notice is sent
+**Then** the text reads: *"The chaos swallowed your words before they could reach the moment. Silence yourself until the echoes clear."*
+
+**Given** the session's `tone` value is "comedic"
+**When** a drop notice is sent
+**Then** the text reads: *"Everyone was talking at once and the universe, frankly, wasn't listening. Give it a moment."*
+
+**Given** the session's `tone` value is "mysterious"
+**When** a drop notice is sent
+**Then** the text reads: *"Something in the fabric of this place muffled your voice. Wait. It will pass."*
+
+**Given** the session's `tone` value is "tense"
+**When** a drop notice is sent
+**Then** the text reads: *"No time — the moment moved on without you. Hold. Wait for your opening."*
+
+**Given** the session's `tone` value is absent, unknown, or any other string
+**When** a drop notice is sent
+**Then** the text reads: *"The echoes of the encounter could not carry all voices at once. Wait for the dust to settle before speaking again."*
+
+**Given** the LLM response has posted and the queue drains
+**When** the `pendingCount` resets in the `finally` block
+**Then** the cap counter also resets so the next burst starts fresh with a 0 cap count
+
+**Notes:**
+- The drop notice strings are hardcoded constants — the LLM is never called to generate them. This avoids a catch-22 where a rate-limited system tries to invoke the LLM for its own rate-limit message.
+- `tone` must be read from `SessionState` (not from the spec directly) so it is available synchronously without an extra Redis lookup at the drop moment.
+- The ephemeral reply uses `message.reply({ content: noticeText, flags: MessageFlags.Ephemeral })` — no embed needed.
+- The 👀 reaction added on message receipt must still be removed for dropped messages (add then immediately remove, no further reactions).
+
+---
+
+## Epic 2: Encounter Tone Configuration
+
+Allow each encounter YAML spec to declare a tone that drives narration flavor and drop notice phrasing throughout the encounter.
+
+### Story 2.1: Tone Field in Spec and Session
+
+As a DM,
+I want to set a `tone` field in my encounter YAML that controls how the bot sounds during that encounter,
+So that a tense pursuit feels different from a comedic heist without touching code.
+
+**Acceptance Criteria:**
+
+**Given** an encounter YAML spec file
+**When** it includes a `tone: "tense"` (or any string) field at the top level
+**Then** the Zod schema in `src/spec/loader.ts` parses it without error as `tone?: string`
+
+**Given** an encounter YAML spec without a `tone` field
+**When** the spec is loaded
+**Then** `spec.tone` is `undefined` and the system falls back to baseline behavior throughout
+
+**Given** a session is initialized via `/encounter start`
+**When** `SessionState` is created and saved to Redis
+**Then** `session.tone` is populated from `spec.tone` (or `undefined` if absent) and persists for the session lifetime
+
+**Given** the LLM system prompt is assembled by `src/harness/promptBuilder.ts`
+**When** `session.tone` is defined
+**Then** the system prompt includes a `<tone>` block immediately after `<narrator_identity>` with text: `Your narration style for this encounter is: {tone}. Let this flavor all of your responses, NPC voices, and pacing.`
+
+**Given** the LLM system prompt is assembled
+**When** `session.tone` is `undefined`
+**Then** no `<tone>` block is added (baseline Gemma narration applies)
+
+**Notes:**
+- `EncounterSpec` interface in `src/types/index.ts` needs `tone?: string` added.
+- `SessionState` in `src/types/index.ts` needs `tone?: string` added.
+- `buildSystemPrompt` in `src/harness/promptBuilder.ts` receives the session (or spec) and includes the tone block when present.
+- No enum constraint on tone values — any free-text string is valid. Prompt injection uses the string verbatim.
+
+---
+
+## Epic 3: Player Pronouns
+
+Allow players to register their preferred pronouns alongside their character name so the LLM uses them correctly during narration.
+
+### Story 3.1: Pronouns in Character Registry and Narration
+
+As a player,
+I want to register my character's pronouns so the bot refers to my character correctly during encounters,
+So that my character exists in the world on my terms.
+
+**Acceptance Criteria:**
+
+**Given** a player uses `/character register custom`
+**When** they include the optional `pronouns` string option (e.g. `pronouns:"she/her"`)
+**Then** the pronouns value is saved to their `CharacterProfile` in Redis alongside their name
+
+**Given** a player uses `/character register custom` without specifying pronouns
+**When** their profile is saved
+**Then** `profile.pronouns` is `undefined` (no default is written; the prompt builder will use "they/them" as its fallback)
+
+**Given** a player's `CharacterProfile` has `pronouns` set
+**When** the LLM system prompt is assembled for an encounter they are participating in
+**Then** the per-player entry in the system prompt includes: `Pronouns: {pronouns}` (or `they/them` if unset)
+
+**Given** the system prompt includes a player's pronouns
+**When** the LLM narrates an action by that player's character
+**Then** the LLM uses the specified pronouns in narration (this is verified via the integration test fixture, not a live LLM assertion)
+
+**Given** a player runs `/character show`
+**When** their profile has pronouns set
+**Then** the show embed includes a "Pronouns" field displaying the registered value
+
+**Notes:**
+- `CharacterProfile` type in `src/session/characterRegistry.ts` (or `src/types/index.ts`) needs `pronouns?: string` added.
+- The Zod schema for CharacterProfile (if it exists) needs the field added.
+- `src/harness/promptBuilder.ts`: in the player/character section of the system prompt, add `Pronouns: ${profile.pronouns ?? 'they/them'}` after the character name line.
+- The `/character register custom` command's `SlashCommandBuilder` needs a new optional `pronouns` string option.
+- No format enforcement on the pronouns string — accept free text (e.g. "she/her", "he/him", "they/them", "xe/xir").
+
+---
+
+## Epic 4: Dice Roll Reliability Fix
+
+Fix the bug where the LLM narrates a skill check outcome itself instead of calling `skill_check_emit`, causing players to have to re-prompt for their dice roll.
+
+### Story 4.1: Strengthen Skill Check Tool Contract
+
+As a player,
+I want the bot to always post the dice roll embed when a skill check is needed,
+So that I never have to ask again after already declaring my action.
+
+**Acceptance Criteria:**
+
+**Given** a player message that implies a skill check (e.g. "I try to pick the lock", "Aelindra chases Dal", "I attempt to persuade the guard")
+**When** the LLM processes the message
+**Then** the LLM must output a `skill_check_emit` tool call rather than narrating the dice outcome itself
+
+**Given** the LLM's response is parsed by `toolParser.ts`
+**When** the response contains no `tool_call` block but the session has no `pendingSkillCheck` and the narrative text contains a self-resolved roll outcome (heuristic: phrases like "you succeed", "you fail", "the check succeeds", "rolling a")
+**Then** the tool dispatcher logs a warning that a possible missed skill check was detected (for debugging; no user-facing change at this stage)
+
+**Given** the system prompt in `src/harness/promptBuilder.ts`
+**When** the `<tool_contract>` block is rendered
+**Then** it includes an explicit negative instruction: `NEVER narrate the outcome of a skill check. ALWAYS emit skill_check_emit and wait for the player's roll result before continuing the narrative.`
+
+**Given** the system prompt's `<tool_contract>` block
+**When** rendered
+**Then** it includes at least one few-shot example demonstrating: player declares action → LLM emits `skill_check_emit` → `[SYSTEM]` roll result arrives → LLM narrates outcome
+
+**Given** a few-shot example is added to the tool contract
+**When** the example demonstrates the correct flow
+**Then** the example uses the exact `tool_call` block format already defined in the contract (no new format introduced)
+
+**Notes:**
+- The root cause is likely that the model (gemma4-it:e2b) at e2b quantization is inconsistent about tool calls when the narrative "obviously" implies a result. Stronger negative instructions and a few-shot example are the correct lever without resorting to post-processing hacks.
+- The heuristic detection in `toolDispatcher.ts` (see AC 2) is diagnostic only — it logs to the existing pino logger under `log.warn('harness', 'possible missed skill_check_emit', ...)`. It does not retry or alter the response.
+- If the few-shot example is long, it can be extracted to a constant in `promptBuilder.ts` to keep the function readable.
+- Integration test in `tests/unit/promptBuilder.test.ts`: assert that the built system prompt contains the negative instruction string and the phrase `skill_check_emit` in the tool contract section.
diff --git a/Docs/mardonar-build-plan.md b/Docs/mardonar-build-plan.md
new file mode 100644
index 0000000..49093c9
--- /dev/null
+++ b/Docs/mardonar-build-plan.md
@@ -0,0 +1,897 @@
+# Mardonar Encounter Engine — Phased Build Plan
+
+> **Stack:** TypeScript / Node.js  
+> **Runtime:** tsx (dev) → compiled JS (prod)  
+> **Test runner:** Vitest  
+> **Target model:** gemma4-it:e2b via Ollama
+
+---
+
+## Repository Structure
+
+```
+mardonar-bot/
+├── src/
+│   ├── bot/              # discord.js bot, command handlers, embed builders
+│   ├── session/          # session manager, player registry
+│   ├── harness/          # context assembler, ollama client, tool dispatcher
+│   ├── mcp/              # MCP server + individual tool definitions
+│   ├── db/               # Redis and Neo4j client singletons
+│   ├── spec/             # EncounterSpec loader + Zod schema
+│   └── types/            # shared TypeScript types and interfaces
+├── specs/                # encounter YAML files (hand-authored)
+├── tests/
+│   ├── unit/
+│   ├── integration/
+│   └── fixtures/         # mock specs, mock LLM responses
+├── package.json
+├── tsconfig.json
+└── vitest.config.ts
+```
+
+---
+
+## Shared Types (define first, referenced by all phases)
+
+```typescript
+// src/types/index.ts
+
+export interface Player {
+  discordId: string;
+  dndName: string;
+}
+
+export interface NpcPersona {
+  id: string;
+  name: string;
+  role: string;
+  persona: string;
+  memoryKey?: string;
+}
+
+export interface EncounterGoal {
+  id: string;
+  label: string;
+}
+
+export interface EncounterSpec {
+  encounterId: string;
+  title: string;
+  setting: { location: string; mood: string; ambientNpcs: string };
+  openingNarrative: string;
+  npcs: NpcPersona[];
+  goals: { primary: EncounterGoal[]; secondary: EncounterGoal[] };
+  sportsmanshipRules: string[];
+  skillChecks: Record<string, number | string>;
+}
+
+export interface SessionState {
+  encounterId: string;
+  threadId: string;
+  guildId: string;
+  spec: EncounterSpec;
+  players: Record<string, Player>;       // discordId → Player
+  history: ChatMessage[];
+  phase: 'open' | 'active' | 'resolved';
+  heldMessages: HeldMessage[];
+  outcome?: string;
+  createdAt: number;
+}
+
+export interface ChatMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+  pinned?: boolean;   // pinned messages survive history trimming
+  timestamp: number;
+}
+
+export interface HeldMessage {
+  discordUserId: string;
+  content: string;
+  timestamp: number;
+}
+
+export type ToolCallBlock = {
+  tool: string;
+  args: Record<string, unknown>;
+};
+```
+
+---
+
+## Phase 1 — Foundation
+
+**Goal:** Discord bot running, slash commands working, player registry operational, encounter thread creation working. No LLM involved yet.
+
+### Packages
+
+| Package | Version | Purpose |
+|---|---|---|
+| `discord.js` | `^14.18` | Bot framework, slash commands, thread management, embeds |
+| `@discordjs/builders` | `^1.10` | Slash command builders |
+| `@discordjs/rest` | `^2.4` | Command registration via Discord REST API |
+| `ioredis` | `^5.4` | Redis client (player registry + session store) |
+| `js-yaml` | `^4.1` | YAML spec loader |
+| `zod` | `^3.24` | Runtime schema validation for specs and env vars |
+| `dotenv` | `^16.4` | `.env` loading |
+| `pino` | `^9.6` | Structured logging |
+| `pino-pretty` | `^13.0` | Dev-mode log formatting |
+| `tsx` | `^4.19` | TypeScript execution without build step |
+| `typescript` | `^5.8` | TypeScript compiler |
+| `vitest` | `^3.1` | Test runner |
+| `ioredis-mock` | `^8.9` | In-memory Redis for unit tests |
+
+### Implementation Steps
+
+**1. Project bootstrap**
+```bash
+mkdir mardonar-bot && cd mardonar-bot
+npm init -y
+npm install discord.js @discordjs/builders @discordjs/rest ioredis js-yaml zod dotenv pino pino-pretty
+npm install -D typescript tsx vitest ioredis-mock @types/node @types/js-yaml
+npx tsc --init
+```
+
+Key `tsconfig.json` settings:
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  }
+}
+```
+
+**2. Environment schema** — validate env at startup, fail fast
+```typescript
+// src/config.ts
+import { z } from 'zod';
+import 'dotenv/config';
+
+const EnvSchema = z.object({
+  DISCORD_TOKEN: z.string(),
+  DISCORD_CLIENT_ID: z.string(),
+  REDIS_URL: z.string().default('redis://localhost:6379'),
+  OLLAMA_BASE_URL: z.string().default('http://localhost:11434'),
+  OLLAMA_MODEL: z.string().default('gemma4-it:e2b'),
+  NEO4J_URI: z.string().default('bolt://localhost:7687'),
+  NEO4J_USER: z.string().default('neo4j'),
+  NEO4J_PASSWORD: z.string(),
+  LOG_LEVEL: z.enum(['trace','debug','info','warn','error']).default('info'),
+});
+
+export const config = EnvSchema.parse(process.env);
+```
+
+**3. Redis client singleton**
+```typescript
+// src/db/redis.ts
+import Redis from 'ioredis';
+import { config } from '../config.js';
+
+export const redis = new Redis(config.REDIS_URL, {
+  lazyConnect: true,
+  maxRetriesPerRequest: 3,
+});
+```
+
+**4. Player registry**
+```typescript
+// src/session/playerRegistry.ts
+import { redis } from '../db/redis.js';
+import type { Player } from '../types/index.js';
+
+const key = (guildId: string) => `players:${guildId}`;
+
+export const playerRegistry = {
+  async get(guildId: string, discordId: string): Promise<Player | null> {
+    const name = await redis.hget(key(guildId), discordId);
+    if (!name) return null;
+    return { discordId, dndName: name };
+  },
+  async set(guildId: string, discordId: string, dndName: string): Promise<void> {
+    await redis.hset(key(guildId), discordId, dndName);
+  },
+  async delete(guildId: string, discordId: string): Promise<void> {
+    await redis.hdel(key(guildId), discordId);
+  },
+};
+```
+
+**5. Slash commands**
+
+Register commands via `scripts/deploy-commands.ts`, run once on deploy:
+```typescript
+// src/bot/commands/dndname.ts
+import { SlashCommandBuilder } from '@discordjs/builders';
+import type { ChatInputCommandInteraction } from 'discord.js';
+import { playerRegistry } from '../../session/playerRegistry.js';
+
+export const data = new SlashCommandBuilder()
+  .setName('dndname')
+  .setDescription('Set your D&D character name')
+  .addSubcommand(sub =>
+    sub.setName('set').setDescription('Register your character name')
+      .addStringOption(o => o.setName('name').setDescription('Your character name').setRequired(true))
+  )
+  .addSubcommand(sub => sub.setName('show').setDescription('Show your registered name'))
+  .addSubcommand(sub => sub.setName('clear').setDescription('Clear your registered name'));
+
+export async function execute(interaction: ChatInputCommandInteraction) {
+  const guildId = interaction.guildId!;
+  const userId = interaction.user.id;
+  const sub = interaction.options.getSubcommand();
+
+  if (sub === 'set') {
+    const name = interaction.options.getString('name', true);
+    await playerRegistry.set(guildId, userId, name);
+    await interaction.reply({ content: `Registered as **${name}**.`, ephemeral: true });
+  } else if (sub === 'show') {
+    const player = await playerRegistry.get(guildId, userId);
+    await interaction.reply({
+      content: player ? `Your character is **${player.dndName}**.` : 'No name registered.',
+      ephemeral: true,
+    });
+  } else if (sub === 'clear') {
+    await playerRegistry.delete(guildId, userId);
+    await interaction.reply({ content: 'Character name cleared.', ephemeral: true });
+  }
+}
+```
+
+**6. EncounterSpec loader + Zod schema**
+```typescript
+// src/spec/loader.ts
+import { readFileSync } from 'fs';
+import { load } from 'js-yaml';
+import { z } from 'zod';
+
+const NpcSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  role: z.string(),
+  persona: z.string(),
+  memoryKey: z.string().optional(),
+});
+
+const GoalSchema = z.object({ id: z.string(), label: z.string() });
+
+export const EncounterSpecSchema = z.object({
+  encounterId: z.string(),
+  title: z.string(),
+  setting: z.object({ location: z.string(), mood: z.string(), ambientNpcs: z.string() }),
+  openingNarrative: z.string(),
+  npcs: z.array(NpcSchema),
+  goals: z.object({ primary: z.array(GoalSchema), secondary: z.array(GoalSchema) }),
+  sportsmanshipRules: z.array(z.string()),
+  skillChecks: z.record(z.union([z.number(), z.string()])),
+});
+
+export type EncounterSpec = z.infer<typeof EncounterSpecSchema>;
+
+export function loadSpec(path: string): EncounterSpec {
+  const raw = readFileSync(path, 'utf-8');
+  const parsed = load(raw);
+  return EncounterSpecSchema.parse(parsed);
+}
+```
+
+**7. Encounter trigger command**
+```typescript
+// src/bot/commands/encounter.ts
+// /encounter start <spec-name> — loads spec, creates thread, initializes session
+```
+
+The `start` subcommand loads a spec from `./specs/<name>.yaml`, creates a Discord thread on the current channel, and initializes session state in Redis.
+
+### Phase 1 Test Plan
+
+**Unit tests**
+
+`tests/unit/playerRegistry.test.ts`
+- `set` → `get` round-trips correctly
+- `get` on unknown user returns `null`
+- `delete` removes the entry
+- All tests use `ioredis-mock` — no live Redis
+
+`tests/unit/specLoader.test.ts`
+- Valid YAML parses without throwing
+- Missing required field (`encounterId`) throws `ZodError`
+- Extra fields are stripped (Zod `.strip()` default)
+- `openingNarrative` and `goals` are preserved exactly
+
+**Integration test**
+
+`tests/integration/phase1.test.ts`
+- Start a real Redis (or Docker Compose service), register a player, retrieve them, delete them
+- Load the `market-thief.yaml` fixture spec and verify all fields
+
+---
+
+## Phase 2 — LLM Harness
+
+**Goal:** Context assembly, token budgeting, Ollama call, response routing back to Discord. No tools yet — LLM just narrates.
+
+### Additional Packages
+
+| Package | Version | Purpose |
+|---|---|---|
+| `ollama` | `^0.5` | Official Ollama JS client |
+| `gpt-tokenizer` | `^2.8` | Token counting proxy (no Gemma tokenizer exists in npm; this is close enough for budget management — add a 15% safety buffer) |
+
+### Implementation Steps
+
+**1. Session manager**
+```typescript
+// src/session/sessionManager.ts
+// Key: session:{threadId}
+// Value: JSON-serialized SessionState
+// TTL: 12 hours (sessions auto-expire)
+
+export const sessionManager = {
+  async create(threadId: string, state: SessionState): Promise<void>,
+  async get(threadId: string): Promise<SessionState | null>,
+  async update(threadId: string, patch: Partial<SessionState>): Promise<void>,
+  async delete(threadId: string): Promise<void>,
+  async addMessage(threadId: string, msg: ChatMessage): Promise<void>,
+};
+```
+
+`addMessage` appends to `state.history` and, if token count exceeds the budget, calls the trimmer before saving.
+
+**2. Token counter**
+```typescript
+// src/harness/tokenCounter.ts
+import { encode } from 'gpt-tokenizer';
+
+// Add 15% buffer on top of estimate to account for Gemma tokenizer differences
+const BUFFER_FACTOR = 1.15;
+
+export function estimateTokens(text: string): number {
+  return Math.ceil(encode(text).length * BUFFER_FACTOR);
+}
+
+export function estimateMessages(messages: ChatMessage[]): number {
+  return messages.reduce((sum, m) => sum + estimateTokens(m.content) + 4, 0);
+}
+```
+
+**3. Context assembler**
+
+This is the core of the harness. It produces the final `messages` array sent to Ollama.
+
+```typescript
+// src/harness/contextAssembler.ts
+
+const BUDGET = {
+  SYSTEM: 4_000,        // system prompt + NPCs + goals
+  PINNED: 2_000,        // opening narrative + goal block (never trimmed)
+  HISTORY: 118_000,     // sliding conversation window
+  SAFETY: 3_500,        // hard floor before we force a trim
+  TOTAL: 128_000,
+};
+
+export function assembleContext(session: SessionState, npcMemories: Record<string, string>): ChatMessage[] {
+  const systemPrompt = buildSystemPrompt(session.spec, npcMemories);
+  const pinnedMessages = session.history.filter(m => m.pinned);
+  const slidingMessages = session.history.filter(m => !m.pinned);
+
+  // Trim sliding window from oldest end until under budget
+  const trimmed = trimHistory(slidingMessages, BUDGET.HISTORY - BUDGET.SAFETY);
+
+  return [
+    { role: 'system', content: systemPrompt, pinned: true, timestamp: 0 },
+    ...pinnedMessages,
+    ...trimmed,
+  ];
+}
+
+function trimHistory(messages: ChatMessage[], budgetTokens: number): ChatMessage[] {
+  let total = estimateMessages(messages);
+  const result = [...messages];
+  while (total > budgetTokens && result.length > 6) {
+    const removed = result.splice(0, 2); // remove oldest user+assistant pair
+    total -= estimateMessages(removed);
+  }
+  return result;
+}
+```
+
+**4. System prompt builder**
+
+```typescript
+// src/harness/promptBuilder.ts
+
+export function buildSystemPrompt(spec: EncounterSpec, npcMemories: Record<string, string>): string {
+  const npcsXml = spec.npcs.map(npc => `
+<npc id="${npc.id}">
+  Name: ${npc.name} | Role: ${npc.role}
+  ${npc.persona}
+  ${npcMemories[npc.id] ? `Memory: ${npcMemories[npc.id]}` : ''}
+</npc>`).join('\n');
+
+  const goalsText = [
+    ...spec.goals.primary.map(g => `- [PRIMARY] ${g.label}`),
+    ...spec.goals.secondary.map(g => `- [SECONDARY] ${g.label}`),
+  ].join('\n');
+
+  const sportsmanship = spec.sportsmanshipRules.map(r => `- ${r}`).join('\n');
+
+  return `<narrator_identity>
+You are the Dungeon Master for a D&D 5e encounter in the Land of Mardonar.
+Voice each NPC distinctly. Guide the encounter toward the hidden goals below.
+Never reveal the goal list. Never break the fourth wall unless enforcing sportsmanship.
+</narrator_identity>
+
+<sportsmanship>
+If a player attempts something unrealistic or grossly unfair, respond in-character to redirect,
+OR break character with: "⚠️ That wasn't great sportsmanship. Let's keep it grounded."
+Rules:
+${sportsmanship}
+</sportsmanship>
+
+<npcs>
+${npcsXml}
+</npcs>
+
+<setting>
+${spec.setting.location}
+${spec.setting.mood}
+Ambient NPCs: ${spec.setting.ambientNpcs}
+</setting>
+
+<hidden_goals>
+Steer toward one of these without revealing them to players.
+${goalsText}
+</hidden_goals>
+
+<tool_contract>
+When you need to emit a skill check, log an event, or update NPC memory,
+output ONLY a JSON block at the very END of your message, after your narrative:
+
+\`\`\`tool_call
+{ "tool": "<tool_name>", "args": { ... } }
+\`\`\`
+
+Available tools: skill_check_emit, event_log_append, npc_memory_write, encounter_resolve.
+One tool call per response maximum. Narrative text MUST come before the tool block.
+</tool_contract>`;
+}
+```
+
+**5. Ollama client**
+```typescript
+// src/harness/ollamaClient.ts
+import { Ollama } from 'ollama';
+import { config } from '../config.js';
+
+const ollama = new Ollama({ host: config.OLLAMA_BASE_URL });
+
+export interface LLMResponse {
+  narrative: string;
+  toolCall?: ToolCallBlock;
+  rawTokensUsed?: number;
+}
+
+export async function callLLM(messages: ChatMessage[]): Promise<LLMResponse> {
+  const response = await ollama.chat({
+    model: config.OLLAMA_MODEL,
+    messages: messages.map(m => ({ role: m.role, content: m.content })),
+    stream: false,
+    options: { temperature: 0.75, num_ctx: 131072 },
+  });
+
+  const raw = response.message.content;
+  const { narrative, toolCall } = parseToolCall(raw);
+
+  return {
+    narrative,
+    toolCall,
+    rawTokensUsed: response.eval_count,
+  };
+}
+```
+
+**6. Tool call parser**
+```typescript
+// src/harness/toolParser.ts
+
+const TOOL_BLOCK_RE = /```tool_call\s*([\s\S]*?)```/;
+
+export function parseToolCall(raw: string): { narrative: string; toolCall?: ToolCallBlock } {
+  const match = TOOL_BLOCK_RE.exec(raw);
+  if (!match) return { narrative: raw.trim() };
+
+  const narrative = raw.slice(0, match.index).trim();
+  try {
+    const toolCall = JSON.parse(match[1].trim()) as ToolCallBlock;
+    return { narrative, toolCall };
+  } catch {
+    // Malformed tool block — treat whole response as narrative, log warning
+    return { narrative: raw.trim() };
+  }
+}
+```
+
+**7. Message handler (bot side)**
+
+On every new message in an encounter thread:
+1. Gate: is the Discord user in the player registry? If not, send ephemeral embed.
+2. Append user message to session history.
+3. Call context assembler → Ollama client.
+4. Post narrative text back to the thread.
+5. If `toolCall` present, hand off to tool dispatcher (Phase 3 stub for now).
+6. Append assistant response to session history.
+7. Save session state.
+
+### Phase 2 Test Plan
+
+**Unit tests**
+
+`tests/unit/tokenCounter.test.ts`
+- Empty string → 0 tokens
+- Known string → expected token range (buffer-aware)
+- `estimateMessages` sums correctly across a message array
+
+`tests/unit/promptBuilder.test.ts`
+- Output contains `<narrator_identity>` block
+- All NPC ids appear in output
+- NPC memory injected when provided, omitted when not
+- All primary goal labels appear in `<hidden_goals>`
+- Sportsmanship rules appear
+
+`tests/unit/toolParser.test.ts`
+- Response with no tool block → `toolCall` is `undefined`, `narrative` is full text
+- Valid tool block at end → `narrative` is text before block, `toolCall` is parsed object
+- Malformed JSON in tool block → falls back to full text as narrative, no throw
+- Tool block in the middle of text (not at end) → still parsed correctly
+
+`tests/unit/contextAssembler.test.ts`
+- Builds a context array with system message first
+- Pinned messages are always included
+- When history exceeds budget, oldest non-pinned pairs are dropped
+- After trimming, total estimated tokens are below budget
+
+**Integration tests**
+
+`tests/integration/llmRoundTrip.test.ts`
+- Requires live Ollama with `gemma4-it:e2b` loaded
+- Send a simple encounter opening → verify response is non-empty string
+- Send a response that should produce a tool block → verify `toolCall` is parsed
+
+---
+
+## Phase 3 — MCP Tool Layer
+
+**Goal:** All tools wired. Skill check embeds post to Discord. Events log to Neo4j. NPC memory reads and writes work.
+
+### Additional Packages
+
+| Package | Version | Purpose |
+|---|---|---|
+| `@modelcontextprotocol/sdk` | `^1.10` | MCP server and tool definitions |
+| `neo4j-driver` | `^5.28` | Neo4j access |
+| `@types/neo4j-driver` | `^5.28` | TypeScript types |
+
+### Neo4j Schema
+
+```cypher
+// NPC node — persists across all encounters
+CREATE CONSTRAINT npc_id IF NOT EXISTS FOR (n:NPC) REQUIRE n.id IS UNIQUE;
+
+(:NPC {
+  id: String,        // e.g. "miriam-vendor-mardonar"
+  name: String,
+  personaSummary: String,
+  memoryFacts: [String],   // append-only list of memory bullets
+  lastSeenEncounter: String
+})
+
+// Encounter node
+(:Encounter {
+  id: String,
+  title: String,
+  resolved: Boolean,
+  outcomeId: String?,
+  createdAt: DateTime
+})
+
+// Event node — append-only log
+(:EncounterEvent {
+  timestamp: DateTime,
+  type: String,     // 'player_action', 'skill_check', 'outcome', etc.
+  description: String
+})
+
+// Player node
+(:Player {
+  discordId: String,
+  dndName: String
+})
+
+// Relationships
+(:NPC)-[:APPEARED_IN]->(:Encounter)
+(:Encounter)-[:HAS_EVENT]->(:EncounterEvent)
+(:Player)-[:PARTICIPATED_IN]->(:Encounter)
+```
+
+### Neo4j Client
+```typescript
+// src/db/neo4j.ts
+import neo4j from 'neo4j-driver';
+import { config } from '../config.js';
+
+export const driver = neo4j.driver(
+  config.NEO4J_URI,
+  neo4j.auth.basic(config.NEO4J_USER, config.NEO4J_PASSWORD)
+);
+
+export async function runQuery<T>(
+  cypher: string,
+  params: Record<string, unknown> = {}
+): Promise<T[]> {
+  const session = driver.session();
+  try {
+    const result = await session.run(cypher, params);
+    return result.records.map(r => r.toObject() as T);
+  } finally {
+    await session.close();
+  }
+}
+```
+
+### MCP Tool Definitions
+
+```typescript
+// src/mcp/tools/skillCheckEmit.ts
+export const skillCheckEmit = {
+  name: 'skill_check_emit',
+  description: 'Post a skill check prompt to the Discord thread for a specific player',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      player: { type: 'string', description: 'The DnD character name being asked to roll' },
+      prompt: { type: 'string', description: 'The skill check question (e.g. "What skill to chase Dal?")' },
+      dc: { type: 'number', description: 'The Difficulty Class for this check' },
+    },
+    required: ['player', 'prompt', 'dc'],
+  },
+};
+
+// src/mcp/tools/eventLogAppend.ts
+export const eventLogAppend = {
+  name: 'event_log_append',
+  description: 'Append a story event to the encounter event log in Neo4j',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      sessionId: { type: 'string' },
+      eventType: { type: 'string', enum: ['player_action', 'skill_check', 'npc_action', 'outcome', 'sportsmanship'] },
+      description: { type: 'string' },
+    },
+    required: ['sessionId', 'eventType', 'description'],
+  },
+};
+
+// src/mcp/tools/npcMemoryWrite.ts
+export const npcMemoryWrite = {
+  name: 'npc_memory_write',
+  description: 'Append a memory fact to an NPC after the encounter',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      npcId: { type: 'string' },
+      memoryFact: { type: 'string', description: 'One sentence describing what the NPC learned or experienced' },
+    },
+    required: ['npcId', 'memoryFact'],
+  },
+};
+
+// src/mcp/tools/encounterResolve.ts
+export const encounterResolve = {
+  name: 'encounter_resolve',
+  description: 'Mark the encounter as complete with a specific outcome',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      sessionId: { type: 'string' },
+      outcomeId: { type: 'string', description: 'The goal ID that was reached (e.g. "catch", "escape")' },
+      summary: { type: 'string', description: 'A one-sentence summary of how the encounter resolved' },
+    },
+    required: ['sessionId', 'outcomeId', 'summary'],
+  },
+};
+```
+
+### Tool Dispatcher (harness side)
+
+```typescript
+// src/harness/toolDispatcher.ts
+
+export type ToolContext = {
+  session: SessionState;
+  thread: TextChannel | ThreadChannel;  // discord.js channel reference
+};
+
+export async function dispatchTool(block: ToolCallBlock, ctx: ToolContext): Promise<string> {
+  switch (block.tool) {
+    case 'skill_check_emit':
+      return await handleSkillCheckEmit(block.args, ctx);
+    case 'event_log_append':
+      return await handleEventLogAppend(block.args, ctx);
+    case 'npc_memory_write':
+      return await handleNpcMemoryWrite(block.args, ctx);
+    case 'encounter_resolve':
+      return await handleEncounterResolve(block.args, ctx);
+    default:
+      return `Unknown tool: ${block.tool}`;
+  }
+}
+```
+
+**Skill check embed:**
+```typescript
+async function handleSkillCheckEmit(args, ctx) {
+  const embed = new EmbedBuilder()
+    .setTitle(`🎲 Skill Check — ${args.player}`)
+    .setDescription(args.prompt)
+    .addFields({ name: 'DC', value: String(args.dc), inline: true })
+    .setColor(0xf4c430)
+    .setFooter({ text: 'Reply with: "I rolled a [number] [Skill Name]"' });
+
+  await ctx.thread.send({ embeds: [embed] });
+  return `Skill check emitted for ${args.player} (DC ${args.dc})`;
+}
+```
+
+The bot also listens for messages matching `"I rolled a [number] [skill]"` and injects the result back into the session history as a `[SYSTEM]` message before the next LLM call.
+
+### Phase 3 Test Plan
+
+**Unit tests**
+
+`tests/unit/toolParser.test.ts` (extends Phase 2)
+- Each tool name dispatches to the correct handler (mock handlers)
+- Unknown tool name returns error string without throwing
+
+`tests/unit/skillCheckEmbed.test.ts`
+- `handleSkillCheckEmit` with valid args produces a `MessagePayload` with correct embed fields
+- Test using a mock discord.js channel that captures sent messages
+
+**Integration tests**
+
+`tests/integration/neo4j.test.ts`
+- Requires live Neo4j test instance (recommend Docker Compose service)
+- Append event → query it back
+- Write NPC memory fact → read NPC, confirm fact appended
+- `encounterResolve` → marks encounter node as resolved
+
+---
+
+## Phase 4 — Full Encounter Lifecycle
+
+**Goal:** Complete end-to-end encounter flow. All phases integrated. Encounter can start, play through, resolve, and write NPC memories.
+
+### Final Wiring
+
+**Session message router** — the main event loop for an encounter thread:
+
+```
+messageCreate event fires in encounter thread
+│
+├── Is discordUser in playerRegistry?  
+│   └── No → send ephemeral embed, hold message, return
+│
+├── Is session in phase 'open' and player not yet in session.players?
+│   └── Yes → add player to session.players, inject welcome into history
+│
+├── Append user message to history (role: 'user', content: "${player.dndName}: ${message.content}")
+│
+├── Assemble context (contextAssembler.assembleContext)
+├── Call Ollama (ollamaClient.callLLM)
+├── Parse response (toolParser.parseToolCall)
+│
+├── Post narrative to thread
+│
+├── If toolCall present:
+│   ├── Dispatch tool (toolDispatcher.dispatchTool)
+│   ├── Inject tool result into history as system message
+│   └── If tool is 'encounter_resolve': set session.phase = 'resolved', post resolution embed, archive thread
+│
+└── Append assistant message + save session state
+```
+
+**Resolution embed:**
+```typescript
+const resolutionEmbed = new EmbedBuilder()
+  .setTitle(`⚔️ Encounter Complete — ${spec.title}`)
+  .setDescription(summary)
+  .addFields(
+    { name: 'Outcome', value: outcomeId, inline: true },
+    { name: 'Participants', value: Object.values(session.players).map(p => p.dndName).join(', '), inline: true }
+  )
+  .setColor(0x2ecc71);
+```
+
+### Phase 4 Test Plan
+
+**End-to-end test**
+
+`tests/integration/encounterE2E.test.ts`
+
+This test runs the entire encounter engine against a live Ollama + Redis + Neo4j stack (no Discord — Discord is mocked).
+
+```typescript
+// Setup: mock Discord thread that captures messages
+// Load market-thief.yaml spec
+// Initialize session
+// Simulate player messages:
+//   - "Aelindra intervenes! She steps in front of Dal."
+//   - "I rolled a 14 Acrobatics"
+//   - "Aelindra grabs Dal by the collar."
+// Assertions:
+//   - Narrative messages are non-empty strings
+//   - At least one skill_check_emit was called
+//   - At least one event_log_append was called
+//   - Encounter eventually resolves with a known outcomeId
+//   - Neo4j has an Encounter node with resolved=true
+```
+
+**Regression checklist (manual)**
+
+Run this manually before each deploy:
+
+- [ ] `/dndname set Aelindra` → bot responds ephemerally
+- [ ] `/encounter start market-thief` → thread created with opening narrative
+- [ ] Posting from unregistered user → ephemeral embed gate fires
+- [ ] Posting player action → LLM responds with narrative
+- [ ] LLM emits skill_check_emit → embed appears in thread
+- [ ] Player posts roll result → LLM resolves it narratively
+- [ ] LLM reaches a goal → resolution embed posted, thread locked
+- [ ] Neo4j has the event log and NPC memories written
+
+---
+
+## Docker Compose (local dev)
+
+```yaml
+# docker-compose.dev.yml
+services:
+  redis:
+    image: redis:7-alpine
+    ports: ["6379:6379"]
+
+  neo4j:
+    image: neo4j:5
+    ports: ["7474:7474", "7687:7687"]
+    environment:
+      NEO4J_AUTH: neo4j/testpassword
+      NEO4J_PLUGINS: '["apoc"]'
+    volumes:
+      - neo4j_data:/data
+
+volumes:
+  neo4j_data:
+```
+
+Ollama runs on your existing lab node and is accessed over the network via `OLLAMA_BASE_URL`.
+
+---
+
+## Build Order Summary
+
+| Phase | What you can test when done |
+|---|---|
+| 1 | `/dndname` commands, spec loading, thread creation |
+| 2 | Full LLM narration in a Discord thread, no tools |
+| 3 | Skill check embeds, Neo4j event logs, NPC memory |
+| 4 | Complete encounter: open → active → resolved |
+
+---
+
+*Document version: 0.2 — TypeScript phased build plan*  
+*Context: Mardonar Encounter Engine — discord.js / Ollama / MCP / Neo4j stack*
diff --git a/Docs/mardonar-encounter-engine.md b/Docs/mardonar-encounter-engine.md
new file mode 100644
index 0000000..0f8347a
--- /dev/null
+++ b/Docs/mardonar-encounter-engine.md
@@ -0,0 +1,375 @@
+# Mardonar Encounter Engine — System Architecture
+
+> **Target:** Discord-native, LLM-driven D&D encounter system  
+> **Model:** `gemma4-it:e2b` via local Ollama (128k context window)  
+> **Philosophy:** Context is the source of truth. The harness controls everything the LLM sees.
+
+---
+
+## 1. System Overview
+
+```
+Discord Bot (Go)
+│
+├── /dndname command → Player Registry (Redis KV: discordID → dndName)
+├── Encounter Trigger (command or DM-initiated)
+│   └── Story Generator (one-shot LLM call → EncounterSpec YAML)
+│
+└── Thread Session Manager
+    ├── Session Store (Redis: threadID → SessionState)
+    ├── Message Router → LLM Harness
+    └── Discord Embed Generator (skill check UI, player prompts)
+
+LLM Harness (embedded in bot or sidecar Go service)
+├── Context Assembler
+│   ├── System Prompt Builder
+│   ├── NPC Loader (via MCP → Neo4j)
+│   └── History Manager (sliding window + trim)
+├── Ollama Client (gemma4-it:e2b)
+├── Tool Dispatcher (JSON-block parsing, NOT native function calls)
+└── Response Router → Discord
+
+MCP Tool Layer (thin Go HTTP wrapper over Neo4j)
+├── npc_read / npc_write
+├── encounter_state_read / encounter_state_write
+├── event_log_append
+└── skill_check_emit / skill_check_resolve
+```
+
+---
+
+## 2. Player Registry
+
+This is deliberately dead simple. No database — just a Redis hash.
+
+```
+HSET players:{guildID} {discordUserID} {dndCharacterName}
+```
+
+### Discord Commands
+
+| Command | Effect |
+|---|---|
+| `/dndname set <name>` | Registers or updates the player's D&D name |
+| `/dndname show` | Echoes their current registered name |
+| `/dndname clear` | Removes them from the registry |
+
+### Encounter Entry Gate
+
+When a user posts their **first message** in an encounter thread:
+
+1. Bot checks `HGET players:{guildID} {discordUserID}`
+2. If missing → bot sends a **Discord embed** (not a plain message) asking them to run `/dndname set <name>` before continuing
+3. Bot marks their message as "held" in session state
+4. On successful `/dndname set`, bot reprocesses the held message and inserts it into the session as if they had just sent it
+
+The embed should be ephemeral (only visible to the triggering user) so it doesn't clutter the thread.
+
+---
+
+## 3. Encounter Spec — The Blueprint
+
+Before a thread is created, the system generates an `EncounterSpec`. This is a structured YAML document that feeds the LLM's system prompt. It is authored once at encounter creation and stored in the session.
+
+```yaml
+# encounter-market-thief.yaml
+encounter_id: "mardonar-market-thief-001"
+title: "The Market Square Thief"
+setting:
+  location: "City of Mardonar — Market Square Food Festival"
+  mood: "Lively, crowded, midday sun. Smell of roasting meat and fresh bread."
+  ambient_npcs: "A dozen festival-goers, two city guard stationed far off."
+
+opening_narrative: |
+  As you wander the Market Square during the Food Festival, a flash of movement
+  catches your eye. A young figure — hood low, moving fast — snatches a bright
+  red apple from Miriam's stand. The vendor turns just in time. "THIEF!" her
+  voice cuts through the crowd.
+  Would anyone intervene?
+
+npcs:
+  - id: "miriam-vendor"
+    name: "Miriam"
+    role: "Apple stand vendor"
+    persona: "Stout, red-faced, short-tempered Dwarf woman. Has run this stall for
+      20 years. She will loudly berate anyone who does nothing. She is not a fighter."
+    memory_key: "miriam-vendor-mardonar"     # Neo4j node key
+  - id: "dal-thief"
+    name: "Dal"
+    role: "Pickpocket"
+    persona: "A teenage Half-Elf, gaunt and scared. Steals to survive. Not violent.
+      Will beg if cornered. Will bolt if given any opening."
+    memory_key: "dal-thief-mardonar"
+
+goals:
+  hidden: true   # never shown to players in Discord
+  primary:
+    - id: "catch"
+      label: "Players physically catch or restrain Dal"
+    - id: "kill"
+      label: "Players kill Dal (check sportsmanship before allowing)"
+    - id: "bystander_chase"
+      label: "Players successfully convince a bystander to give chase"
+  secondary:
+    - id: "escape"
+      label: "Dal escapes with the apple into the crowd"
+    - id: "negotiate"
+      label: "Dal surrenders or agrees to work off the debt"
+
+sportsmanship_rules:
+  - "No one-hit kills on helpless, non-threatening NPCs without narrative setup"
+  - "No abilities or spells the player has not established in a prior scene"
+  - "No controlling another player's character"
+
+skill_checks:
+  chase_dc: 13
+  persuade_bystander_dc: 12
+  spot_hiding_dc: 10
+  intimidate_dal_dc: 8
+  note: "Player picks the skill. DM asks for the roll. Player reports their result."
+```
+
+### Story Generator
+
+The `EncounterSpec` can be:
+
+- **Templated** (DM fills in a YAML template manually for important encounters)
+- **LLM-generated** (a one-shot call to a larger model — Claude Sonnet via API — given a brief prompt like `"generate an encounter in the City of Mardonar food festival, street level, involving theft"`)
+
+For now, treat the generator as a separate CLI tool or admin command (`/encounter generate <brief>`). It outputs the YAML, a DM reviews it, then triggers it.
+
+---
+
+## 4. Context Window Blueprint
+
+The 128k window is divided into hard zones. The harness is responsible for enforcing these budgets.
+
+```
+┌─────────────────────────────────────────────────────┐
+│  SYSTEM PROMPT BLOCK                  ~4,000 tokens  │
+│  ├── Narrator persona + rules                        │
+│  ├── Sportsmanship enforcement rules                 │
+│  ├── Tool call format contract                       │
+│  └── Active NPC personas (1–3 × ~600 tok each)      │
+├─────────────────────────────────────────────────────┤
+│  ENCOUNTER BLOCK                      ~1,500 tokens  │
+│  ├── Setting, mood, opening narrative                │
+│  └── Hidden goals list                               │
+├─────────────────────────────────────────────────────┤
+│  TOOL DEFINITIONS                     ~1,000 tokens  │
+│  └── JSON schema for each callable tool              │
+├─────────────────────────────────────────────────────┤
+│  CONVERSATION HISTORY            ~118,000 tokens     │
+│  ├── [PINNED] Opening narrative message (never trim) │
+│  ├── [PINNED] Goal block (never trim)                │
+│  └── [SLIDING] Player + LLM turns (oldest drop off)  │
+├─────────────────────────────────────────────────────┤
+│  SAFETY BUFFER                        ~3,500 tokens  │
+└─────────────────────────────────────────────────────┘
+```
+
+**History trimming strategy:**
+- Count tokens before every inference call
+- If `history_tokens > 115,000`: drop the oldest non-pinned turn pair (user + assistant)
+- Never trim the first 3 turns (establishes scene in context)
+- If history is still oversized after trimming, trigger a **mid-session summary**: one LLM call condenses the oldest 20 turns into a `[SUMMARY]` block inserted at that position
+
+---
+
+## 5. System Prompt Structure
+
+This is the most important thing you control. The LLM's behavior is almost entirely determined by how well this is written. Structure it with explicit XML-style sections since Gemma4-IT responds well to that.
+
+```
+<narrator_identity>
+You are the Dungeon Master narrator for a D&D 5e encounter set in the Land of
+Mardonar. You speak as an omniscient narrator and voice each NPC distinctly.
+You are guiding the encounter toward specific outcomes without the players knowing.
+Never reveal the goal list. Never break the fourth wall unless calling out bad
+sportsmanship.
+</narrator_identity>
+
+<sportsmanship>
+If a player attempts something unrealistic, physically impossible, or grossly
+unfair (e.g., instant-killing a helpless child NPC with no prior combat
+engagement), respond in-character but steer away, OR break character with:
+"⚠️ That wasn't great sportsmanship. Let's keep it grounded — what would your
+character realistically attempt here?"
+</sportsmanship>
+
+<npcs>
+  <npc id="miriam-vendor">
+    Name: Miriam | Role: Apple vendor
+    [persona text from spec]
+    Memory: [loaded from Neo4j via MCP at session start]
+  </npc>
+  <npc id="dal-thief">
+    Name: Dal | Role: Pickpocket
+    [persona text from spec]
+    Memory: [loaded from Neo4j via MCP at session start]
+  </npc>
+</npcs>
+
+<encounter>
+  Setting: [from spec]
+  Scene: [opening narrative]
+</encounter>
+
+<hidden_goals>
+You are steering the story toward one of these outcomes. Do not state these to
+players. Reward clever play. Gently redirect if the scene drifts far off course.
+- Catch Dal
+- Kill Dal (only allow after dramatic escalation, check sportsmanship)
+- Convince bystander to give chase
+Secondary: Escape, Negotiation
+</hidden_goals>
+
+<tools>
+When you need to emit a skill check, log an event, or update NPC memory,
+output a JSON block in this exact format at the END of your message, after
+your narrative text:
+
+```tool_call
+{
+  "tool": "skill_check_emit",
+  "args": {
+    "player": "Aelindra",
+    "prompt": "What skill are you using to chase Dal?",
+    "dc": 13
+  }
+}
+```
+
+Available tools: [schema list]
+</tools>
+```
+
+---
+
+## 6. Tool Layer
+
+These are the only tools exposed to the LLM. Keep them minimal.
+
+### Tool Manifest
+
+| Tool | Purpose | Args |
+|---|---|---|
+| `skill_check_emit` | Posts a skill check prompt to the thread | `player, prompt, dc` |
+| `skill_check_resolve` | Logs the outcome of a roll | `player, skill, roll, modifier, dc, success` |
+| `event_log_append` | Appends a story event to Neo4j | `session_id, event_type, description` |
+| `npc_memory_read` | Reads NPC memory from graph | `npc_id` |
+| `npc_memory_write` | Updates NPC memory after encounter | `npc_id, memory_delta` |
+| `encounter_resolve` | Marks the encounter complete with outcome | `session_id, outcome_id` |
+
+### Tool Dispatch (Prompt-Based, Not Native)
+
+Because `gemma4-it:e2b` is a small model and native tool calling is unreliable at this scale, the harness uses **structured JSON parsing** instead:
+
+1. After each LLM response, harness scans for a ` ```tool_call ``` ` block
+2. If found, it strips it from the visible Discord message, parses the JSON, and dispatches the tool
+3. Tool result is injected back into history as a `[SYSTEM]` turn: `"Tool skill_check_emit executed: posted to thread"`
+4. The Discord-facing message only contains the narrative text before the tool block
+
+This means the LLM's output is always: `narrative text` + optionally `tool_call block`.
+
+### Neo4j Schema for MCP Tools
+
+```
+(:NPC {id, name, persona_summary, memory: [], last_seen_encounter})
+  -[:APPEARED_IN]->
+(:Encounter {id, title, resolved, outcome_id, created_at})
+  -[:HAS_EVENT]->
+(:EncounterEvent {timestamp, type, description})
+
+(:Player {discord_id, dnd_name})
+  -[:PARTICIPATED_IN]->
+(:Encounter)
+```
+
+---
+
+## 7. Session Lifecycle
+
+```
+Phase 0: Trigger
+  DM runs: /encounter start <spec_file>
+  Bot creates Discord thread
+  Session initialized in Redis:
+    threadID → { spec, history: [], phase: "open", players: {} }
+
+Phase 1: Player Entry
+  First message from unknown user → ephemeral embed → /dndname set
+  Once registered: message is replayed into session, player added to session.players
+
+Phase 2: Active Encounter
+  Each message → bot appends to history → calls LLM Harness
+  Harness assembles context → calls Ollama → parses response
+  Narrative text → posted to thread
+  Tool blocks → dispatched silently, result injected to history
+  Skill check emitted → Discord embed with "Roll your {skill}! Post your result."
+
+Phase 3: Skill Check Resolution
+  Player replies with roll (e.g., "I rolled a 17 Acrobatics")
+  Bot parses this, calls skill_check_resolve tool, logs to Neo4j
+  LLM receives result, continues narrative ("You close the gap — Dal is cornered...")
+
+Phase 4: Resolution
+  LLM calls encounter_resolve when an ending is reached
+  Bot posts a final embed: encounter summary, outcome label
+  Thread is archived (or locked by bot)
+  NPC memories written to Neo4j via npc_memory_write
+```
+
+---
+
+## 8. Discord Bot Command Surface
+
+| Command | Who | What |
+|---|---|---|
+| `/dndname set <name>` | Player | Register/update D&D character name |
+| `/dndname show` | Player | Show their current name |
+| `/encounter start <spec>` | DM/Admin | Load spec YAML, create thread, begin session |
+| `/encounter generate <brief>` | DM/Admin | LLM-generate a spec from a short description |
+| `/encounter status` | DM | Show current phase, player list, event count |
+| `/encounter end` | DM | Force-resolve encounter (admin override) |
+
+---
+
+## 9. What's Explicitly Out of Scope (for Now)
+
+- Rewards / item grants (MCP hook is stubbed, logic deferred)
+- Character sheets / stat tracking (player reports their own modifier)
+- Multi-encounter campaigns (session is self-contained; Neo4j provides the through-line)
+- Parallel encounters (one active per channel for now)
+- Full model swaps (the context structure is model-agnostic; swapping Ollama model is a config change)
+
+---
+
+## 10. Key Design Decisions & Rationale
+
+| Decision | Rationale |
+|---|---|
+| Prompt-based tool calls (not native) | Gemma4-IT at e2b quantization is not reliable for native function calling |
+| Goals in system prompt, not MCP | Reduces tool round-trips on every turn; goals rarely change mid-encounter |
+| Redis for session state, Neo4j for persistence | Redis is ephemeral and fast for active session; Neo4j for long-term NPC memory and campaign history |
+| Player name gate via embed | Embeds are ephemeral and un-cluttering; name registry is the identity layer for the whole system |
+| Pinned history turns | Opening narrative + goal block must survive trimming or the LLM loses its anchor |
+| Story generator as separate call | Separates creative authoring (can use a stronger model) from real-time inference (must be fast + cheap) |
+
+---
+
+## Next Steps (Ordered)
+
+1. **Stand up the Discord bot skeleton** — command handler, thread creation, player registry in Redis
+2. **Build the context assembler** — system prompt template, NPC loader, token counter
+3. **Wire Ollama client** — simple POST to `/api/chat` with assembled context
+4. **Implement prompt-based tool parser** — scan for `tool_call` blocks, dispatch to MCP
+5. **Build MCP tool layer** — thin Go HTTP service wrapping Neo4j queries
+6. **Write first EncounterSpec YAML** — the Market Thief scenario
+7. **End-to-end test** — one full encounter, 2 players, measure token usage
+8. **Tune system prompt** — iterate based on LLM behavior at e2b quantization
+
+---
+
+*Document version: 0.1 — Initial architecture*  
+*Context: Mardonar Encounter Engine design session*
diff --git a/Docs/market-thief.yaml b/Docs/market-thief.yaml
new file mode 100644
index 0000000..eba48d8
--- /dev/null
+++ b/Docs/market-thief.yaml
@@ -0,0 +1,140 @@
+encounterId: "mardonar-market-thief-001"
+title: "The Market Square Thief"
+
+setting:
+  location: "City of Mardonar — Market Square Food Festival"
+  mood: >
+    Midday sun beats down on a lively crowd. The air smells of roasting meat,
+    fresh bread, and spiced cider. Merchants shout their wares. Children weave
+    through legs. Two city guards are visible at the far end of the square,
+    too far to respond quickly.
+  ambientNpcs: >
+    A dozen festival-goers milling about. A juggler performing near the fountain.
+    A heavyset merchant arguing with a customer two stalls down. An elderly couple
+    sharing a meat pie on a bench.
+
+openingNarrative: >
+  The food festival fills Market Square with color and noise. Stalls stretch in
+  every direction — honeyed nuts, smoked fish, fresh-pressed cider, towers of
+  bread. As you wander, a flash of movement catches your eye near Miriam's apple
+  stand. A young hooded figure — moving fast, head low — snatches a bright red
+  apple and turns to bolt. Miriam spins around just in time, her face going
+  scarlet. "THIEF!" Her voice cuts through the crowd like a blade.
+  The festival-goers nearest her freeze and stare. Would anyone intervene?
+
+npcs:
+  - id: "miriam-vendor-mardonar"
+    name: "Miriam"
+    role: "Apple stand vendor"
+    persona: >
+      Stout, red-faced Dwarf woman in her sixties. Has run this stall for twenty
+      years and takes every theft as a personal insult. She is loud, indignant,
+      and will berate anyone nearby who does nothing. She is NOT a fighter and
+      will not give chase herself — her knees are bad. She will, however, loudly
+      demand that someone else do something. If the thief is caught and returned,
+      she will calm down and may show grudging gratitude. If the thief escapes,
+      she will mutter darkly about the state of the city and the uselessness of
+      bystanders. She refers to the apple as "my finest Crimson Bellflower, worth
+      three silvers if it's worth a copper."
+    memoryKey: "miriam-vendor-mardonar"
+
+  - id: "dal-thief-mardonar"
+    name: "Dal"
+    role: "Pickpocket"
+    persona: >
+      A teenage Half-Elf, maybe fifteen, gaunt and hollow-eyed beneath a patched
+      brown hood. He steals to survive — there is no malice in it, only hunger.
+      He is fast but not trained in combat. He will bolt immediately if given any
+      opening. If cornered with no escape, he will freeze, then beg — voice
+      cracking, eyes wide. He is not lying about being hungry. He will not fight
+      back unless physically grabbed and even then only flails. If treated with
+      any kindness, he becomes confused and cooperative. He has a small knife on
+      him but has never used it on a person.
+    memoryKey: "dal-thief-mardonar"
+
+goals:
+  hidden: true
+  primary:
+    - id: "catch"
+      label: >
+        Players physically catch or restrain Dal — tackle, grab, spell, or block
+        his escape route so he cannot run.
+    - id: "kill"
+      label: >
+        Players kill Dal. Only allow this after dramatic escalation — Dal must
+        have drawn his knife or threatened someone first. Apply sportsmanship
+        check before resolving. This is a valid but dark outcome.
+    - id: "bystander_chase"
+      label: >
+        Players successfully persuade or inspire a bystander to give chase
+        (Persuasion or Intimidation DC 12). The juggler is the most likely
+        candidate — young, fit, bored. The heavyset merchant will refuse. The
+        elderly couple will not move.
+    - id: "negotiate"
+      label: >
+        Players talk Dal down before he runs, or corner him and offer him
+        something (food, coin, mercy) that causes him to stop and surrender
+        voluntarily. Requires him to be cornered or slowed first.
+
+  secondary:
+    - id: "escape"
+      label: >
+        Dal escapes into the crowd with the apple. Miriam is furious. The
+        encounter ends with no reward. Dal disappears into an alley. This is a
+        valid outcome — not every encounter ends in success.
+    - id: "guards_summoned"
+      label: >
+        Players alert the city guards at the far end of the square. Guards take
+        1d4 rounds to arrive. By then Dal will likely have escaped unless players
+        slowed him. If guards arrive and Dal is caught, players receive no reward
+        but the city notes their cooperation.
+
+sportsmanshipRules:
+  - "No instant kills on a non-threatening, unarmed teenager without prior escalation."
+  - "No controlling another player character's actions or speaking for them."
+  - "No spells or abilities the player has not established owning in a prior scene."
+  - "No claiming information the character could not realistically know (Dal's name, history, etc.)."
+  - "No teleportation or flight without prior narrative establishment."
+  - >
+    If a player attempts something absurd or game-breaking, respond in-character
+    to redirect, or break character with:
+    "⚠️ That wasn't great sportsmanship. Let's keep it grounded — what would
+    your character realistically attempt here?"
+
+skillChecks:
+  chase_dc: 13
+  chase_skill: "Athletics or Acrobatics (player's choice)"
+  chase_note: >
+    Dal is fast but panicked. A successful check closes the gap. Failure means
+    he gains distance. Two consecutive failures and he vanishes into the crowd.
+
+  persuade_bystander_dc: 12
+  persuade_bystander_skill: "Persuasion or Intimidation"
+  persuade_bystander_note: >
+    Targeting the juggler gives advantage (he's already watching with interest).
+    Targeting the merchant gives disadvantage (he's busy and dismissive).
+
+  spot_hiding_dc: 10
+  spot_hiding_skill: "Perception"
+  spot_hiding_note: >
+    If Dal ducks into a stall or behind a crowd. Success reveals his hiding spot.
+
+  intimidate_dal_dc: 8
+  intimidate_dal_skill: "Intimidation"
+  intimidate_dal_note: >
+    If Dal is cornered. Success causes him to drop the apple and freeze.
+    Failure causes him to lash out with a shove and run.
+
+  persuade_dal_dc: 10
+  persuade_dal_skill: "Persuasion"
+  persuade_dal_note: >
+    If a player offers Dal food, coin, or genuine kindness while he is cornered.
+    Success causes him to surrender and explain his situation.
+
+dmNotes: >
+  This encounter is intentionally low-stakes — a warm-up scene in a public
+  setting with no combat required. The goal is to establish player character
+  personalities and how they interact with a morally simple situation (hungry
+  kid steals food). There is no "correct" outcome. Lean into the crowd's
+  reactions. If players hesitate, have Miriam single one of them out directly.
+  Dal should feel like a person, not a target.
diff --git a/Docs/stories/story-1.1-reaction-state-machine.md b/Docs/stories/story-1.1-reaction-state-machine.md
new file mode 100644
index 0000000..c064bc4
--- /dev/null
+++ b/Docs/stories/story-1.1-reaction-state-machine.md
@@ -0,0 +1,102 @@
+---
+baseline_commit: NO_VCS
+status: review
+---
+
+# Story 1.1: Emoji Reaction State Machine
+
+**Epic:** 1 — Interaction Feedback & Queue Management
+**Status:** in-progress
+
+## Story
+
+As a player,
+I want emoji reactions on my messages to show whether they were received and are being processed,
+So that I always know the bot saw my message and what it is doing with it.
+
+## Acceptance Criteria
+
+**AC1:** Given a player sends a message in an active encounter thread, when the message is received by the bot's message handler, the bot adds a 👀 reaction to that message (fire-and-forget, within the same message-create handler path).
+
+**AC2:** Given the player's message is scheduled for LLM processing, when the LLM generation begins (inside the runner), the 👀 reaction is removed and ⏳ is added.
+
+**AC3:** Given the player's message content contains a roll-related keyword (roll, attack, check, save, saving throw, d20), when ⏳ is added, 🎲 is also added alongside it.
+
+**AC4:** Given the LLM response has been posted, when the generation runner's try block completes, ⏳ and 🎲 (if present) are removed and ✅ is added; ✅ is removed ~10 seconds later.
+
+**AC5:** Given the LLM call fails or throws, when the finally block executes, all in-progress reactions (⏳, 🎲) are removed. No stale state left.
+
+**AC6:** Reactions are applied only to player messages. Bot messages are never reacted to by the bot.
+
+**AC7:** All Discord reaction calls are fire-and-forget (errors caught and swallowed) — they must never cause the message handler to throw or block.
+
+## Tasks / Subtasks
+
+- [x] Task 1: Create `src/bot/handlers/reactionManager.ts` with pending map and lifecycle helpers
+  - [x] 1a: Write failing tests for `isDiceRelated()` and map operations (`registerScheduled`, `drainPending`, `clearPending`)
+  - [x] 1b: Implement the module
+  - [x] 1c: Write failing tests for `upgradeToProcessing`, `upgradeToComplete`, `cleanupReactions` with Discord mocks
+  - [x] 1d: Implement lifecycle functions
+  - [x] 1e: Run tests — confirm all pass
+
+- [x] Task 2: Wire `handleMessage` to add 👀 immediately on receipt
+  - [x] 2a: Add `message.react('👀')` fire-and-forget in `handleMessage` for active sessions
+  - [x] 2b: Pass `message` (as optional `sourceMessage`) through `processEncounterMessage` to `scheduleEncounterLLMTurn`
+
+- [x] Task 3: Wire `scheduleEncounterLLMTurn` to manage reaction lifecycle
+  - [x] 3a: Add optional `sourceMessage?: Message` param to `scheduleEncounterLLMTurn`
+  - [x] 3b: Call `reactionManager.registerScheduled(threadId, sourceMessage)` when message provided
+  - [x] 3c: In runner: drain pending, `upgradeToProcessing`, run LLM, `upgradeToComplete` on success, `cleanupReactions` in finally on error
+
+- [x] Task 4: Run full test suite — confirm no regressions
+
+## Dev Notes
+
+**Architecture:**
+- New file `src/bot/handlers/reactionManager.ts` owns the pending-message map and all Discord reaction calls
+- `messageRouter.ts` imports from it; `generationQueue.ts` stays untouched
+- Reactions are fire-and-forget throughout — NFR7 is absolute
+
+**Key design decisions:**
+- 👀 is added in `handleMessage` for ALL messages in active sessions (even held/blocked) — honest "received" signal
+- Only messages that actually reach `scheduleEncounterLLMTurn` get registered in the pending map (⏳/✅ lifecycle)
+- `pendingSkillCheck` guard in the runner clears the pending map without upgrading; 👀 stays as "received but waiting for your roll"
+- `replayHeldMessages` and `rollHandler` call `scheduleEncounterLLMTurn` without a `sourceMessage` — no reactions managed (correct: these are programmatic, not player messages)
+
+**Reaction removal:**
+Use `msg.reactions.cache.find(r => r.emoji.name === emoji)?.users.remove(botId).catch(() => null)` — reliable for unicode emoji added by the bot.
+
+**Dice detection heuristic:**
+`/\b(?:roll|attack|check|save|saving throw|d20)\b/i` — applied to message content at ⏳-upgrade time.
+
+**Files:**
+- `src/bot/handlers/reactionManager.ts` (new)
+- `src/bot/handlers/messageRouter.ts` (modify: `handleMessage`, `processEncounterMessage`, `scheduleEncounterLLMTurn`)
+- `tests/unit/reactionManager.test.ts` (new)
+
+## Dev Agent Record
+
+### Implementation Plan
+
+1. Create `reactionManager.ts` with testable pure functions
+2. Wire 👀 into `handleMessage`  
+3. Thread `sourceMessage` through `processEncounterMessage` → `scheduleEncounterLLMTurn`
+4. Add lifecycle management inside the runner closure
+
+### Debug Log
+
+No issues — all 23 tests passed on first implementation run.
+
+### Completion Notes
+
+`reactionManager.ts` is a pure module (no Discord imports in the module-level logic) — the pending map holds Discord `Message` objects but the lifecycle functions take `PendingEntry[]`, making them mockable in tests. All Discord API calls are fire-and-forget. `generationQueue.ts` is untouched. Full suite: 267 tests, 0 failures.
+
+## File List
+
+- src/bot/handlers/reactionManager.ts (new)
+- src/bot/handlers/messageRouter.ts (modified: imports, handleMessage, processEncounterMessage, scheduleEncounterLLMTurn)
+- tests/unit/reactionManager.test.ts (new)
+
+## Change Log
+
+- 2026-05-30: Story 1.1 implemented — emoji reaction state machine (👀 on receipt, ⏳/🎲 on processing, ✅ on complete, cleanup on error)
diff --git a/Docs/stories/story-1.2-queue-cap-drop-notice.md b/Docs/stories/story-1.2-queue-cap-drop-notice.md
new file mode 100644
index 0000000..7f2b69c
--- /dev/null
+++ b/Docs/stories/story-1.2-queue-cap-drop-notice.md
@@ -0,0 +1,108 @@
+---
+baseline_commit: NO_VCS
+status: review
+---
+
+# Story 1.2: Queue Cap with In-World Drop Notice
+
+**Epic:** 1 — Interaction Feedback & Queue Management
+**Status:** in-progress
+
+## Story
+
+As a player,
+I want to be told privately when my message wasn't processed due to message volume,
+So that I know to wait and try again rather than wondering if the bot is broken.
+
+## Acceptance Criteria
+
+**AC1:** The burst queue enforces a hard cap of 2 messages per LLM-response cycle. A third (or later) message arriving before the LLM has responded is dropped — not added to session history, not scheduled for LLM processing.
+
+**AC2:** When a message is dropped by the cap, the 👀 reaction (added in Story 1.1) is removed — no ⏳ or ✅ is ever shown for dropped messages.
+
+**AC3:** When a message is dropped, the player receives a DM with the in-world drop notice. If the DM fails (DMs disabled), the notice is sent as a reply in the thread and auto-deleted after 8 seconds.
+
+**AC4:** The drop notice string is selected by the encounter's `tone` field (`spec.tone`). Defined keys: `grim`, `comedic`, `mysterious`, `tense`, and baseline (all other values including `undefined`). The LLM is never called to generate these strings.
+
+**AC5:** The burst counter resets after each LLM turn completes (success or error), opening a new burst window.
+
+**AC6:** `EncounterSpec` gains an optional `tone?: string` field in both the TypeScript interface and the Zod schema. The existing spec fixtures and tests must continue passing.
+
+## Tasks / Subtasks
+
+- [x] Task 1: Create `src/bot/handlers/queueCap.ts` with burst counter and drop notice logic
+  - [x] 1a: Write failing tests for `isBurstCapped`, `incrementBurst`, `resetBurst`, `getDropNotice`
+  - [x] 1b: Implement the module
+  - [x] 1c: Run tests — confirm all pass
+
+- [x] Task 2: Add `tone?: string` to `EncounterSpec` (interface + Zod schema)
+  - [x] 2a: Write failing test asserting `tone` is parsed from a spec YAML fixture
+  - [x] 2b: Add `tone?: z.string().optional()` to `EncounterSpecSchema` in `src/spec/loader.ts`
+  - [x] 2c: Add `tone?: string` to `EncounterSpec` interface in `src/types/index.ts`
+  - [x] 2d: Run tests — confirm they pass and existing spec tests don't regress
+
+- [x] Task 3: Wire cap check and drop notice into `processEncounterMessage`
+  - [x] 3a: Import `isBurstCapped`, `incrementBurst`, `sendDropNotice` from queueCap
+  - [x] 3b: After pending-roll check and before history append: if capped, remove 👀, send notice, return
+  - [x] 3c: After player gates but before history append: call `incrementBurst`
+
+- [x] Task 4: Wire burst reset into `scheduleEncounterLLMTurn` runner
+  - [x] 4a: Import `resetBurst` from queueCap
+  - [x] 4b: Call `resetBurst(threadId)` in the finally block of the runner (after LLM turn, success or error)
+
+- [x] Task 5: Run full test suite — confirm no regressions
+
+## Dev Notes
+
+**Burst window definition:** A "burst" is all messages received between consecutive LLM responses. Messages 1 and 2 are processed; message 3+ are dropped. The counter resets after each LLM turn fires (regardless of outcome).
+
+**Cap check placement:** The cap check goes in `processEncounterMessage` AFTER the player gate and the pending-roll checks. These early-return paths do NOT count toward the burst cap (the player isn't registered, or the system is waiting for a roll). Only messages that would be appended to the LLM history count.
+
+**EncounterSpec.tone:** Story 2.1 will inject `tone` into the LLM system prompt. Story 1.2 only needs it for drop notice selection. Both stories read from `spec.tone` — no `SessionState.tone` field needed here.
+
+**DM delivery:** Use `sourceMessage.author.send(text)` with a catch. On failure: `sourceMessage.reply({ content: text })` + delete after 8s. Text-only, no embed needed.
+
+**Drop notice strings (exact text per tone):**
+- `grim`: `*"The chaos swallowed your words before they could reach the moment. Silence yourself until the echoes clear."*`
+- `comedic`: `*"Everyone was talking at once and the universe, frankly, wasn't listening. Give it a moment."*`
+- `mysterious`: `*"Something in the fabric of this place muffled your voice. Wait. It will pass."*`
+- `tense`: `*"No time — the moment moved on without you. Hold. Wait for your opening."*`
+- baseline: `*"The echoes of the encounter could not carry all voices at once. Wait for the dust to settle before speaking again."*`
+
+**Files:**
+- `src/bot/handlers/queueCap.ts` (new)
+- `src/spec/loader.ts` (modify: add `tone` to Zod schema)
+- `src/types/index.ts` (modify: add `tone?: string` to `EncounterSpec`)
+- `src/bot/handlers/messageRouter.ts` (modify: wire cap + reset)
+- `tests/unit/queueCap.test.ts` (new)
+- `tests/unit/specLoader.test.ts` (modify: add tone test)
+
+## Dev Agent Record
+
+### Implementation Plan
+
+1. Create `queueCap.ts` with pure burst-counter functions and tone-keyed strings
+2. Add `tone?` to spec type/schema
+3. Wire cap check into `processEncounterMessage`
+4. Wire burst reset into runner
+
+### Debug Log
+
+- Initial cap test had "two increments is not capped" which contradicted AC1 (cap=2 means 3rd message dropped). Corrected test: after 2 increments `isBurstCapped` returns true.
+
+### Completion Notes
+
+12 tests in `queueCap.test.ts`, 2 new tests in `specLoader.test.ts`. Full suite: 281 tests, 0 failures. The burst counter, drop notices, and `tone` field are fully wired. Story 2.1 can add tone to the system prompt without touching this code.
+
+## File List
+
+- src/bot/handlers/queueCap.ts (new)
+- src/spec/loader.ts (modified: added `tone` to Zod schema)
+- src/types/index.ts (modified: added `tone?: string` to `EncounterSpec`)
+- src/bot/handlers/messageRouter.ts (modified: imports, burst cap check + increment, burst reset in runner)
+- tests/unit/queueCap.test.ts (new)
+- tests/unit/specLoader.test.ts (modified: added 2 tone tests)
+
+## Change Log
+
+- 2026-05-30: Story 1.2 implemented — burst cap at 2, in-world DM drop notices, tone field on EncounterSpec
diff --git a/Docs/stories/story-2.1-encounter-tone-config.md b/Docs/stories/story-2.1-encounter-tone-config.md
new file mode 100644
index 0000000..94fa534
--- /dev/null
+++ b/Docs/stories/story-2.1-encounter-tone-config.md
@@ -0,0 +1,73 @@
+---
+baseline_commit: NO_VCS
+status: review
+---
+
+# Story 2.1: Encounter Tone Configuration
+
+**Epic:** 2 — Encounter Tone Configuration
+**Status:** in-progress
+
+## Story
+
+As a DM,
+I want to set a `tone` field in my encounter YAML that controls how the bot sounds during that encounter,
+So that a tense pursuit feels different from a comedic heist without touching code.
+
+## Acceptance Criteria
+
+**AC1:** Given `buildSystemPrompt()` is called with a spec that has `tone: "tense"` (or any non-empty string), the returned system prompt includes a `<tone>` block with the text: `Your narration style for this encounter is: {tone}. Let this flavor all of your responses, NPC voices, and pacing.`
+
+**AC2:** Given `buildSystemPrompt()` is called with a spec where `tone` is `undefined` or absent, no `<tone>` block appears in the returned system prompt.
+
+**AC3:** The `<tone>` block is inserted immediately after `<narrator_identity>` and before `<sportsmanship>`.
+
+**AC4:** The existing `buildSystemPrompt` signature is unchanged — `tone` is read from `spec.tone` directly.
+
+## Tasks / Subtasks
+
+- [x] Task 1: Add failing tests for tone block injection in `tests/unit/promptBuilder.test.ts`
+  - [x] 1a: Test that prompt contains `<tone>` block when spec has a tone value
+  - [x] 1b: Test that prompt contains the exact tone text
+  - [x] 1c: Test that `<tone>` appears before `<sportsmanship>`
+  - [x] 1d: Test that no `<tone>` block appears when tone is undefined
+
+- [x] Task 2: Implement `buildToneBlock(spec)` in `src/harness/promptBuilder.ts` and wire it in
+  - [x] 2a: Add `buildToneBlock` function
+  - [x] 2b: Insert at position 2 in the array (after `buildNarratorBlock`, before `buildSportsmanshipBlock`)
+  - [x] 2c: Run tests — confirm all pass
+
+- [x] Task 3: Run full test suite — confirm no regressions
+
+## Dev Notes
+
+**Insertion point:** The tone block goes second in the `buildSystemPrompt` array, between `buildNarratorBlock()` and `buildSportsmanshipBlock()`. The `.filter(Boolean)` call already handles the `undefined` case when tone is absent.
+
+**`spec.tone`** is already present on `EncounterSpec` (added in Story 1.2). No schema changes needed.
+
+**Files:**
+- `src/harness/promptBuilder.ts` (modify)
+- `tests/unit/promptBuilder.test.ts` (modify)
+
+## Dev Agent Record
+
+### Implementation Plan
+
+Single change: add `buildToneBlock` returning `<tone>...</tone>` when `spec.tone` is set, or empty string when absent. Wire it into the section array.
+
+### Debug Log
+
+No issues — straightforward insertion.
+
+### Completion Notes
+
+5 new tests added to `promptBuilder.test.ts`. Full suite: 286 tests, 0 failures. The `<tone>` block is inserted second in the system prompt array, after `<narrator_identity>` and before `<sportsmanship>`, using `.filter(Boolean)` to omit it cleanly when `spec.tone` is absent.
+
+## File List
+
+- src/harness/promptBuilder.ts (modified: added `buildToneBlock`, wired into section array)
+- tests/unit/promptBuilder.test.ts (modified: 5 new tone block tests)
+
+## Change Log
+
+- 2026-05-30: Story 2.1 implemented — tone field injected into system prompt as `<tone>` block
diff --git a/Docs/stories/story-3.1-player-pronouns.md b/Docs/stories/story-3.1-player-pronouns.md
new file mode 100644
index 0000000..58cdcdd
--- /dev/null
+++ b/Docs/stories/story-3.1-player-pronouns.md
@@ -0,0 +1,122 @@
+---
+baseline_commit: NO_VCS
+status: review
+---
+
+# Story 3.1: Player Pronouns
+
+**Epic:** 3 — Player Pronouns
+**Status:** in-progress
+
+## Story
+
+As a player,
+I want to register my character's pronouns so the bot refers to my character correctly during encounters,
+So that my character exists in the world on my terms.
+
+## Acceptance Criteria
+
+**AC1:** `/character register custom` shows a Discord modal (not inline slash args) with five text fields: Character Name (required), Pronouns (optional), Class (optional), Race (optional), Backstory (optional).
+
+**AC2:** On modal submit, all five values are saved to `CharacterProfile` in Redis. `pronouns` is stored as a free-text string or `undefined` when left blank.
+
+**AC3:** When a player sends their first message in an encounter thread, their `pronouns` (from `characterRegistry`) are loaded and stored on `session.players[userId].pronouns`.
+
+**AC4:** The LLM system prompt includes a `<players>` block listing each active player's character name and pronouns (e.g. `Vex (she/her)`). Players without pronouns set are listed without a pronoun note.
+
+**AC5:** `/character show` displays a Pronouns field when the profile has pronouns set.
+
+## Tasks / Subtasks
+
+- [x] Task 1: Add `pronouns?: string` to `CharacterProfile` and `Player` types
+  - [x] 1a: Add to `CharacterProfile` in `src/session/characterRegistry.ts`
+  - [x] 1b: Add to `Player` in `src/types/index.ts`
+  - [x] 1c: Write and run test confirming `pronouns` round-trips through `characterRegistry`
+
+- [x] Task 2: Convert `/character register custom` to a modal
+  - [x] 2a: Remove all inline options from the `custom` subcommand in the slash command builder
+  - [x] 2b: `handleRegisterCustom` shows a 5-field modal (Name, Pronouns, Class, Race, Backstory)
+  - [x] 2c: Export `handleCustomRegisterModal` for modal submit handling
+  - [x] 2d: Wire `'character_custom_modal'` in `src/bot/index.ts`
+  - [x] 2e: Update `handleShow` to display Pronouns field when set
+
+- [x] Task 3: Load pronouns into session when player joins encounter
+  - [x] 3a: In `processEncounterMessage` (new-player path), call `characterRegistry.get()` and copy `pronouns` to `session.players[userId]`
+
+- [x] Task 4: Add `buildPlayersBlock` to system prompt
+  - [x] 4a: Write failing tests for `buildPlayersBlock` (with pronouns, without, empty)
+  - [x] 4b: Add `buildPlayersBlock(players)` function to `src/harness/promptBuilder.ts`
+  - [x] 4c: Add `players` as optional 4th param to `buildSystemPrompt`; insert block after `buildNpcsBlock`
+  - [x] 4d: Pass `session.players` from `contextAssembler.ts`
+  - [x] 4e: Run full test suite — confirm no regressions
+
+## Dev Notes
+
+**Modal custom ID:** `'character_custom_modal'`
+
+**Modal fields (in order):**
+1. `char_name` — "Character Name" — required, short
+2. `char_pronouns` — "Pronouns" — optional, short, placeholder `e.g. she/her, they/them`
+3. `char_class` — "Class" — optional, short, placeholder `e.g. Wizard, Fighter`
+4. `char_race` — "Race" — optional, short, placeholder `e.g. Elf, Human`
+5. `char_backstory` — "Backstory" — optional, paragraph, maxLength 200
+
+Level is dropped from the modal — not critical for narration, and Discord modals only support text inputs.
+
+**`buildPlayersBlock` output (when players have pronouns):**
+```
+<players>
+Active player characters in this encounter:
+  - Vex (she/her)
+  - Thorin (he/him)
+  - Aelindra
+
+Use the specified pronouns when referring to these characters in narration.
+</players>
+```
+Block is omitted entirely when `players` is empty (`filter(Boolean)` handles it).
+
+**`buildSystemPrompt` signature update:** add optional 4th param `players: Record<string, Player> = {}`. Existing callers pass nothing and get an empty players block (omitted).
+
+**Pronouns in session:** `session.players[userId]` already uses the `Player` type. Adding `pronouns?: string` to `Player` is backwards-compatible.
+
+**Files:**
+- `src/session/characterRegistry.ts` (modify: add `pronouns` field)
+- `src/types/index.ts` (modify: add `pronouns` to `Player`)
+- `src/bot/commands/character.ts` (modify: modal conversion + show update)
+- `src/bot/index.ts` (modify: add modal routing)
+- `src/bot/handlers/messageRouter.ts` (modify: load pronouns on player join)
+- `src/harness/promptBuilder.ts` (modify: add `buildPlayersBlock`, update signature)
+- `src/harness/contextAssembler.ts` (modify: pass `session.players`)
+- `tests/unit/characterRegistry.test.ts` (modify: add pronouns test)
+- `tests/unit/promptBuilder.test.ts` (modify: add players block tests)
+
+## Dev Agent Record
+
+### Implementation Plan
+
+Type changes → modal conversion → session wiring → prompt injection.
+
+### Debug Log
+
+No issues — all changes straightforward.
+
+### Completion Notes
+
+4 new tests in `characterRegistry.test.ts` (2 new), `promptBuilder.test.ts` (4 new players block tests). Full suite: 292 tests, 0 failures. Note: `/character register custom` command spec must be re-deployed to Discord via `scripts/deploy-commands.ts` for the modal to appear (slash command schema changed — inline options removed).
+
+## File List
+
+- src/session/characterRegistry.ts (modified: `pronouns?: string` on `CharacterProfile`)
+- src/types/index.ts (modified: `pronouns?: string` on `Player`)
+- src/bot/commands/character.ts (modified: modal conversion, `handleCustomRegisterModal` export, `handleShow` pronouns field)
+- src/bot/index.ts (modified: `character_custom_modal` routing)
+- src/bot/handlers/messageRouter.ts (modified: `characterRegistry` import, pronouns copied on player join)
+- src/harness/promptBuilder.ts (modified: `buildPlayersBlock`, updated `buildSystemPrompt` signature)
+- src/harness/contextAssembler.ts (modified: pass `session.players` to `buildSystemPrompt`)
+- tests/unit/characterRegistry.test.ts (modified: 2 pronouns tests)
+- tests/unit/promptBuilder.test.ts (modified: 4 players block tests)
+
+## Change Log
+
+- 2026-05-30: Story 3.1 implemented — pronouns in modal registration, session state, and system prompt
diff --git a/Docs/stories/story-4.1-dice-roll-reliability.md b/Docs/stories/story-4.1-dice-roll-reliability.md
new file mode 100644
index 0000000..cc8833d
--- /dev/null
+++ b/Docs/stories/story-4.1-dice-roll-reliability.md
@@ -0,0 +1,97 @@
+---
+baseline_commit: NO_VCS
+status: review
+---
+
+# Story 4.1: Strengthen Skill Check Tool Contract
+
+**Epic:** 4 — Dice Roll Reliability Fix
+**Status:** in-progress
+
+## Story
+
+As a player,
+I want the bot to always post the dice roll embed when a skill check is needed,
+So that I never have to ask again after already declaring my action.
+
+## Acceptance Criteria
+
+**AC1:** Given a player message that implies a skill check, when the LLM processes the message, the LLM must output a `skill_check_emit` tool call rather than narrating the dice outcome itself.
+
+**AC2:** Given the LLM's response is parsed and contains no tool call, no pending skill check exists, and the narrative text contains skill-request phrases (e.g. "you need to roll", "roll for X", "make a check"), then the tool dispatcher / message router logs a warning `possible_missed_skill_check` via pino. No user-facing change.
+
+**AC3:** Given the system prompt `<tool_contract>` block rendered by `buildToolManifest()`, when rendered, it includes an explicit negative instruction: "NEVER end your response with a request for the player to roll without emitting skill_check_emit in the same response."
+
+**AC4:** Given the system prompt `<tool_contract>` block, when rendered, it includes at least one few-shot example demonstrating: player declares action → LLM emits `skill_check_emit` (with narrative before the tool block).
+
+**AC5:** Integration test in `tests/unit/promptBuilder.test.ts` asserts the built prompt contains the negative instruction text and the few-shot example marker.
+
+## Tasks / Subtasks
+
+- [x] Task 1: Add negative instruction to `buildToolManifest()` in `src/harness/toolDispatcher.ts`
+  - [x] 1a: Write failing test asserting negative instruction string is present in built prompt
+  - [x] 1b: Add the instruction text to the SKILL CHECKS section of `buildToolManifest()`
+  - [x] 1c: Run test — confirm it passes
+
+- [x] Task 2: Add few-shot example to `buildToolManifest()` in `src/harness/toolDispatcher.ts`
+  - [x] 2a: Write failing test asserting a few-shot marker string is present in built prompt
+  - [x] 2b: Add the few-shot example block to `buildToolManifest()`
+  - [x] 2c: Run test — confirm it passes
+
+- [x] Task 3: Add `detectMissedSkillCheck()` to `src/bot/handlers/responseFilter.ts`
+  - [x] 3a: Write failing tests for the new detection function (true/false cases)
+  - [x] 3b: Implement `detectMissedSkillCheck(narrative: string): boolean`
+  - [x] 3c: Run tests — confirm they pass
+
+- [x] Task 4: Wire diagnostic warning in `src/bot/handlers/messageRouter.ts`
+  - [x] 4a: In `runLLMTurn()`, after response parse, call `detectMissedSkillCheck` when no tool call and no pending check
+  - [x] 4b: Log `log.warn('harness', 'possible_missed_skill_check', ...)` when detected
+  - [x] 4c: Run full test suite — confirm no regressions
+
+## Dev Notes
+
+**Root cause:** `gemma4-it:e2b` at e2b quantization inconsistently omits `skill_check_emit` when player actions imply a skill check. The LLM sometimes narrates "you'll need to roll" or "make a Dexterity check" and stops — without emitting the tool call. The player then has to repeat themselves.
+
+**Why the existing filter doesn't catch this:** `responseFilter.ts` catches the opposite failure (LLM fabricating a roll result like "you rolled a 15"). The new diagnostic catches the missing-tool case.
+
+**Key files:**
+- `src/harness/toolDispatcher.ts` — `buildToolManifest()` builds the `<tool_contract>` prompt block
+- `src/bot/handlers/responseFilter.ts` — add `detectMissedSkillCheck()` here alongside the existing filters
+- `src/bot/handlers/messageRouter.ts` — `runLLMTurn()` is where the response is parsed; wire the diagnostic here
+- `tests/unit/promptBuilder.test.ts` — existing test file to extend
+- `tests/unit/responseFilter.test.ts` — new test file for the detection function (if it doesn't exist)
+
+**Constraint:** The missed skill check detection is diagnostic only (log warning). It must NOT retry or inject a correction in this story — that's future scope.
+
+**Test approach:** Unit tests only — no live LLM required. Test that `buildToolManifest()` output contains the expected strings, and that `detectMissedSkillCheck()` returns correct booleans for known inputs.
+
+## Dev Agent Record
+
+### Implementation Plan
+
+- Strengthen the tool contract prompt in `buildToolManifest()` with a "NEVER" instruction
+- Add a concise few-shot example showing the correct player-action → tool-call sequence
+- Expose `detectMissedSkillCheck()` from `responseFilter.ts` with regex-based heuristic
+- Wire it into `runLLMTurn()` as a fire-and-forget diagnostic log
+
+### Debug Log
+
+- `requires a Strength check` failed initial regex (skill name between "a" and "check") — widened pattern to `requires\s+a\s+(?:\w+\s+)?(?:roll|check)`.
+
+### Completion Notes
+
+All 4 tasks complete. 13 new tests added (3 in promptBuilder, 13 in responseFilter). Full suite: 244 passing, 0 failures.
+
+Changes are prompt-engineering only for the LLM contract + one new diagnostic function. No breaking changes to any existing interface.
+
+## File List
+
+- src/harness/toolDispatcher.ts — strengthened SKILL CHECKS section with NEVER instruction + CORRECT/WRONG few-shot example
+- src/bot/handlers/responseFilter.ts — added `MISSED_SKILL_CHECK_RE` regex + `detectMissedSkillCheck()` export
+- src/bot/handlers/messageRouter.ts — imported `detectMissedSkillCheck` and `log`; wired diagnostic warn in `runLLMTurn()`
+- tests/unit/promptBuilder.test.ts — added 3 tests for negative instruction and few-shot example
+- tests/unit/responseFilter.test.ts — added 13 tests for `detectMissedSkillCheck()`
+
+## Change Log
+
+- 2026-05-30: Story 4.1 implemented — strengthened skill_check_emit tool contract; added missed-skill-check diagnostic
diff --git a/Docs/ux-designs/ux-mardonar-2026-05-30/.decision-log.md b/Docs/ux-designs/ux-mardonar-2026-05-30/.decision-log.md
new file mode 100644
index 0000000..7410256
--- /dev/null
+++ b/Docs/ux-designs/ux-mardonar-2026-05-30/.decision-log.md
@@ -0,0 +1,37 @@
+# Decision Log — Mardonar UX
+
+## Session 2026-05-30
+
+### D-01 · Interaction feedback via emoji reactions
+**Decision:** Use Discord emoji reactions as persistent state signals on player messages.
+- `👀` = received (bot sees the message)
+- `⏳` = queued / processing
+- `✅` = response posted (or reaction self-clears)
+**Rationale:** Current typing indicator appears but response never posts — creates false hope. Reactions persist and self-clear, giving players durable feedback without polluting the channel.
+
+### D-02 · Message queue cap at 2
+**Decision:** During a burst of concurrent messages, the bot batches up to 2 messages into one LLM context. Messages beyond the cap are silently dropped from the queue (but not from the channel).
+**Rationale:** Prevents runaway queue depth and undefined LLM behavior with too many simultaneous inputs.
+
+### D-03 · Ephemeral drop notice — in-world voice
+**Decision:** Players whose messages were not batched receive a Discord ephemeral message (visible only to them) written in in-world language.
+**Example flavor:** *"The echoes of the encounter could not carry all voices at once. Your words did not reach the moment — wait for the dust to settle before speaking again."*
+**Rationale:** Ephemeral keeps the channel clean; in-world voice preserves immersion.
+
+### D-04 · Always in-world voice
+**Decision:** All bot-generated text — including system feedback, errors, and config confirmations — uses in-world language. No utility/system strings are exposed to players.
+**Rationale:** User explicitly stated preference. Private game with friends; immersion is a core value.
+
+### D-05 · Per-encounter tone config in YAML spec
+**Decision:** Each encounter YAML spec gains a `tone` field that controls phrasing flavor for that encounter's bot responses.
+**[ASSUMPTION]:** Tone is a string enum or free-text label (e.g. `"grim"`, `"comedic"`, `"tense"`, `"mysterious"`). The LLM uses this as a style instruction when generating narration and system messages.
+**Rationale:** User wants customizability at the encounter level without touching code.
+
+### D-06 · Player-facing config via slash command
+**Decision:** Players can configure personal preferences via a `/profile` slash command (or similar).
+**[ASSUMPTION]:** Config fields include: character name display, pronouns, notification preferences.
+**Rationale:** User wants player-facing customizability. Slash command is the most discoverable Discord pattern.
+
+### D-07 · Stakes and platform
+**Decision:** Private game with friends. Hobby stakes. Discord-native only (no web dashboard, no external surface).
+**Rationale:** Scopes the design — no need for onboarding flows, public discoverability, or accessibility for unknown user populations.
diff --git a/Docs/ux-designs/ux-mardonar-2026-05-30/DESIGN.md b/Docs/ux-designs/ux-mardonar-2026-05-30/DESIGN.md
new file mode 100644
index 0000000..73cd0da
--- /dev/null
+++ b/Docs/ux-designs/ux-mardonar-2026-05-30/DESIGN.md
@@ -0,0 +1,131 @@
+---
+name: mardonar
+version: "1.0"
+status: final
+updated: 2026-05-30
+colors:
+  encounter_active: "#5865F2"      # Discord blurple — session is live
+  encounter_success: "#57F287"     # Discord green — goal resolved
+  encounter_warning: "#FEE75C"     # Discord yellow — attention needed
+  encounter_danger: "#ED4245"      # Discord red — failure / danger state
+  encounter_neutral: "#2B2D31"     # Discord dark — narration / ambient
+  encounter_mystery: "#9B59B6"     # purple — hidden goals, secret events
+typography:
+  primary: discord_markdown         # bold, italic, code blocks — Discord's full markdown
+  narration: plain                  # plain prose, no markdown decoration
+  system_flavor: italic             # in-world system messages rendered as *italic*
+  emphasis: bold                    # key terms, NPC names, goal labels
+rounded: n/a
+spacing: n/a
+components:
+  reaction_received: "👀"
+  reaction_queued: "⏳"
+  reaction_done: "✅"
+  reaction_dice: "🎲"
+  embed_encounter_start: see Components
+  embed_goal_update: see Components
+  embed_resolution: see Components
+  embed_dynamic_goal: see Components
+---
+
+## Brand & Style
+
+Mardonar is a private D&D encounter engine running inside Discord. It has no public face. The aesthetic is **dark fantasy immersion** — the bot is not a bot, it's the world speaking. Every string it emits should feel like it comes from within the fiction, not from a developer.
+
+Tone is encounter-scoped (see `tone` field in encounter YAML). Baseline tone is **grave and atmospheric**. Encounters may override to `comedic`, `tense`, `mysterious`, `grim`, or any free-text style directive.
+
+There are no logos, landing pages, or brand colors beyond what Discord renders. Visual identity lives entirely in embed color, emoji vocabulary, and prose voice.
+
+## Colors
+
+Four semantic states map to Discord's native embed left-border color:
+
+| Token | Hex | Use |
+|---|---|---|
+| `encounter_active` | `#5865F2` | Session is live, encounter in progress |
+| `encounter_success` | `#57F287` | Goal resolved, encounter ended well |
+| `encounter_warning` | `#FEE75C` | Partial success, complication, or attention needed |
+| `encounter_danger` | `#ED4245` | Failure state, mortal danger, catastrophic outcome |
+| `encounter_neutral` | `#2B2D31` | Ambient narration, lore drops, NPC flavor |
+| `encounter_mystery` | `#9B59B6` | Hidden goal registered, secret event, revelation |
+
+Do not use color to convey information that isn't also conveyed in text — Discord users may be on light mode or have color vision differences.
+
+## Typography
+
+Discord constrains typography to markdown. Use the full palette deliberately:
+
+- **Bold** — NPC names on first appearance, goal labels, key terms
+- *Italic* — in-world system messages, ephemeral notices, ambient flavor
+- `Code` — dice results, mechanical values (DC, HP, damage)
+- > Blockquote — NPC direct speech
+- ~~Strikethrough~~ — goals that are no longer achievable, retracted options
+
+Never use headers (`#`, `##`) in bot messages — they read as out-of-world on mobile.
+
+## Components
+
+### Reaction Set — Message State Signals
+
+Applied to player messages to signal processing state. Self-clearing: `👀` and `⏳` are removed when the response is posted. `✅` persists briefly then is removed (or left as confirmation).
+
+| State | Reaction | Meaning |
+|---|---|---|
+| Received | `👀` | Bot sees the message, queued |
+| Processing | `⏳` | Message included in current LLM context |
+| Done | `✅` | Response posted, message processed |
+| Dice | `🎲` | Dice roll detected, resolving |
+
+If a message is dropped (queue cap exceeded), no reaction is added — the ephemeral notice is the only signal.
+
+### Embed — Encounter Start
+
+```
+[color: encounter_active]
+[title: {encounter.title}]
+[description: {encounter.opening_narration}]
+[fields]
+  Location: {encounter.setting.location}
+  Mood: {encounter.setting.mood}
+[footer: The encounter begins. Speak freely.]
+```
+
+### Embed — Goal Update
+
+```
+[color: encounter_active or encounter_mystery for dynamic goals]
+[title: A new path opens.] ← in-world, encounter-tone-aware
+[description: {goal.label}]
+[footer: This goal has been recorded in the hidden ledger.]
+```
+
+### Embed — Resolution
+
+```
+[color: encounter_success / encounter_warning / encounter_danger]
+[title: {outcome-flavor from tone}]
+[description: {resolution narration}]
+[fields]
+  Outcome: {goal.label of resolved goal}
+  Path Taken: {outcomeId}
+```
+
+### Embed — Dynamic Goal Registered
+
+```
+[color: encounter_mystery]
+[title: The threads of fate shift.]  ← in-world
+[description: {dynamic goal label, paraphrased in-world}]
+```
+
+## Do's and Don'ts
+
+**Do:**
+- Use `encounter_mystery` color for any hidden or dynamic goal event
+- Write ephemeral drop notices in *italic* to signal they are private/system
+- Let the encounter `tone` field override baseline gravity — a `comedic` encounter should read differently from a `grim` one
+
+**Don't:**
+- Use the word "bot," "system," "error," "rate limit," or "queue" in any player-facing string
+- Use headers in embed descriptions — they break mobile rendering
+- Add reactions to bot messages — reactions are only for player messages as state signals
diff --git a/Docs/ux-designs/ux-mardonar-2026-05-30/EXPERIENCE.md b/Docs/ux-designs/ux-mardonar-2026-05-30/EXPERIENCE.md
new file mode 100644
index 0000000..717264e
--- /dev/null
+++ b/Docs/ux-designs/ux-mardonar-2026-05-30/EXPERIENCE.md
@@ -0,0 +1,233 @@
+---
+name: mardonar
+version: "1.0"
+status: final
+updated: 2026-05-30
+---
+
+# Mardonar Encounter Engine — EXPERIENCE.md
+
+Visual identity: see DESIGN.md. This document owns behavior, flows, states, and interactions.
+
+---
+
+## Foundation
+
+**Form factor:** Discord (desktop and mobile). Single surface — the encounter channel. No web dashboard, no external UI.
+
+**UI system:** Discord's native component model — embeds, slash commands, emoji reactions, ephemeral messages, buttons (optional). No custom UI framework.
+
+**Constraints inherited from Discord:**
+- Ephemeral messages are only visible to the recipient and cannot be edited after send
+- Reactions can be added/removed by the bot programmatically
+- Slash command responses can be deferred (show "thinking…") for up to 15 minutes
+- Message content limit: 2000 characters; embed description limit: 4096 characters
+
+---
+
+## Information Architecture
+
+Three surfaces, one channel:
+
+| Surface | Visibility | Owner |
+|---|---|---|
+| **Encounter channel** | All players | Bot + players |
+| **Ephemeral notice** | Individual player only | Bot |
+| **Player profile** (`/profile`) | Player only (ephemeral response) | Player |
+
+[ASSUMPTION] DM-facing encounter config lives in the YAML spec file and is not surfaced as a Discord command. The DM edits YAML, not Discord.
+
+### Encounter Channel
+
+Contains: opening embed, player messages, bot narration, goal update embeds, resolution embed. This is the entire game world.
+
+### Ephemeral Notices
+
+Transient private messages delivered to a specific player. Used for:
+- Drop notice (message not batched, queue cap exceeded)
+- Profile confirmation (when `/profile` is set)
+- [ASSUMPTION] Dice clarification if a roll result is ambiguous
+
+### Player Profile (`/profile`)
+
+A slash command players use to set personal preferences. Stored per Discord user ID. Fields:
+- `name` — character name displayed in bot narration (default: Discord display name)
+- `pronouns` — used when bot narrates player actions (default: they/them)
+- [ASSUMPTION] `notify` — whether to receive ephemeral drop notices (default: on)
+
+---
+
+## Voice and Tone
+
+All player-facing strings are in-world. The bot is the world speaking. See {DESIGN.md > Brand & Style} for baseline tone rules.
+
+**Per-encounter tone** is set via the `tone` field in the encounter YAML. The LLM uses this as a style directive for all narration and in-world system messages generated during that encounter. When `tone` is absent, default to grave/atmospheric.
+
+**Tone examples and their flavor effect:**
+
+| Tone value | Ephemeral drop notice flavor |
+|---|---|
+| `grim` | *"The chaos swallowed your words before they could reach the moment. Silence yourself until the echoes clear."* |
+| `comedic` | *"Everyone was talking at once and the universe, frankly, wasn't listening. Give it a moment."* |
+| `mysterious` | *"Something in the fabric of this place muffled your voice. Wait. It will pass."* |
+| `tense` | *"No time — the moment moved on without you. Hold. Wait for your opening."* |
+| baseline | *"The echoes of the encounter could not carry all voices at once. Wait for the dust to settle before speaking again."* |
+
+The LLM generates these dynamically using the tone directive — the table above is illustrative, not hardcoded strings.
+
+---
+
+## Component Patterns
+
+### Reaction State Machine (behavioral)
+
+Visual specs: {DESIGN.md > Components > Reaction Set}
+
+Applied to **player messages only**. Bot messages never receive bot-added reactions.
+
+State transitions:
+
+```
+[message posted by player]
+      ↓
+  add 👀  (received)
+      ↓
+  [within batch window? ≤ 2 messages in burst?]
+      ├── YES → remove 👀, add ⏳ (processing)
+      │           ↓
+      │       [LLM responds]
+      │           ↓
+      │       remove ⏳, add ✅ (done) → remove ✅ after 10s
+      │
+      └── NO → remove 👀 (no further reaction)
+                  ↓
+              send ephemeral drop notice to player
+```
+
+If a dice roll is detected in the message, add `🎲` alongside `⏳` for the duration of processing.
+
+### Ephemeral Drop Notice (behavioral)
+
+Triggered when: player message arrives and queue is already at 2 messages.
+
+Delivery: Discord ephemeral reply to the player's message. Tone-aware (see Voice and Tone above). The LLM does **not** generate this at runtime — it is a pre-generated string selected by tone key, to avoid a catch-22 where the rate-limited system tries to invoke the LLM to generate its own rate-limit message.
+
+[NOTE FOR UX] Confirm with dev: is the `tone` value accessible synchronously at the point where the drop notice is sent, or does it require a Redis lookup? If lookup adds latency risk, pre-cache tone string at session start.
+
+### Player Profile Command
+
+```
+/profile name:"Thorin Ironfist" pronouns:"he/him"
+```
+
+Response: ephemeral confirmation in-world, e.g.:
+*"The ledger of {name} has been updated. The world knows you as you wish to be known."*
+
+Fields are optional — omitted fields retain their previous value. First-time users who have never run `/profile` get defaults (`name` = Discord display name, `pronouns` = they/them).
+
+---
+
+## State Patterns
+
+### Session States
+
+| State | What players see | Reactions active? |
+|---|---|---|
+| **Idle** (no encounter) | Nothing / last message | No |
+| **Active** (encounter running) | Bot narrating, reacting | Yes |
+| **Processing** (LLM working) | `⏳` on queued messages | Yes |
+| **Rate-limited / at cap** | Ephemeral drop notices sent | 👀 added then removed |
+| **Resolved** | Resolution embed posted | No (session over) |
+
+### Goal States
+
+| State | Visual signal |
+|---|---|
+| Active (spec goal) | Listed in opening embed |
+| Active (dynamic goal) | `encounter_mystery` embed posted |
+| Resolved | Resolution embed, `encounter_success/warning/danger` color |
+| Abandoned | [ASSUMPTION] No visual signal — silently dropped |
+
+---
+
+## Interaction Primitives
+
+**Message burst handling:**
+- Batch window: [ASSUMPTION] 1.5–3 seconds after first message in burst
+- Cap: 2 messages per batch
+- Messages 3+ in a burst: `👀` added and removed, ephemeral drop sent
+- After response posts: new batch window opens
+
+**Slash commands available to players:**
+- `/profile` — set name and pronouns
+- [ASSUMPTION] `/goals` — view currently active goals (ephemeral, in-world flavor)
+
+**No buttons required** for current scope. Buttons may be added in future for things like "confirm action" or "roll again" — out of scope for this design.
+
+---
+
+## Accessibility Floor
+
+Discord handles most accessibility at the platform level (screen reader support, high contrast mode, font scaling). Bot-specific floor:
+
+- Color is never the **only** signal — every embed color has a corresponding text label or description
+- Reactions are supplemental signals, not the only channel — the response itself always narrates what happened
+- Ephemeral notices are text-only (no embed required) for maximum compatibility
+- In-world language must still be **legible** — poetic phrasing should not obscure what the player needs to do (e.g. "wait before sending more" must be inferable)
+
+---
+
+## Key Flows
+
+### Flow 1 — Rowena sends a message during a busy moment
+
+*Rowena (she/her) is playing in "The Velvet Auction." Three players are active. She types a message just as two others arrive simultaneously.*
+
+1. Rowena's message posts in the encounter channel.
+2. Bot adds `👀` to her message — she can see her words were received.
+3. Two messages are already in the batch. Queue is full.
+4. Bot removes `👀` from Rowena's message. No `⏳` is added.
+5. Rowena receives an ephemeral message (tense tone): *"No time — the moment moved on without you. Hold. Wait for your opening."*
+6. The other two messages get `⏳`. LLM responds. `⏳` clears, `✅` briefly appears.
+7. Rowena tries again. This time she's in the next batch.
+
+**Climax beat:** Rowena sees the ephemeral notice and holds back — she doesn't flood the channel. When the next beat opens, her message lands.
+
+---
+
+### Flow 2 — Skeeter rolls dice and waits
+
+*Skeeter is attempting to pick a lock (DC 14). He types "I roll Dexterity."*
+
+1. Bot adds `👀` then `⏳` + `🎲` to his message.
+2. LLM detects dice intent, calls the dice tool, gets result.
+3. LLM narrates the outcome inline — no separate prompt needed.
+4. `⏳` and `🎲` clear. `✅` briefly appears.
+5. Skeeter reads the outcome in the bot's response.
+
+**Climax beat:** The result arrives without Skeeter having to ask. The dice reaction telegraphed that something was resolving.
+
+---
+
+### Flow 3 — DM sets up "The Mawfang Pursuit" with a tense tone
+
+*DM edits `mawfang-pursuit.yaml` and adds `tone: "tense"` to the spec.*
+
+1. Encounter starts. Bot's opening embed posts.
+2. All narration during this encounter uses tense phrasing.
+3. When a player gets dropped, their ephemeral reads: *"No time — the moment moved on without you. Hold. Wait for your opening."*
+4. Dynamic goal registered — embed reads in a clipped, urgent voice.
+
+**Climax beat:** The tone field did its job — the encounter *felt* different from "The Velvet Auction" without any code change.
+
+---
+
+### Flow 4 — Pary sets up her player profile
+
+*Pary just joined the server. She wants the bot to use her character name "Vex" and she/her pronouns.*
+
+1. Pary runs `/profile name:"Vex" pronouns:"she/her"`.
+2. Bot responds with an ephemeral confirmation: *"The ledger has been updated. The world knows Vex as she wishes to be known."*
+3. In subsequent encounters, bot narration refers to her as Vex and uses she/her.
+
+**Climax beat:** Pary's character exists in the world on her terms, without anyone else needing to configure it.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..df2733b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,315 @@
+# Mardonar Encounter Engine
+
+A Discord-native, LLM-driven D&D encounter system for the Land of Mardonar.
+Discord threads are encounter sessions. The LLM narrates, voices NPCs, tracks
+hidden goals, emits skill checks, and logs everything to Neo4j.
+
+---
+
+## Stack
+
+| Layer | Technology |
+|---|---|
+| Discord bot | discord.js v14 |
+| Language | TypeScript (Node.js, ESM) |
+| LLM | gemma4-it:e2b via Ollama |
+| Session cache | Redis (ioredis) |
+| Persistence | Neo4j 5 (neo4j-driver) |
+| Schema validation | Zod |
+| Test runner | Vitest |
+
+---
+
+## Prerequisites
+
+- Node.js 20+
+- Docker + Docker Compose (for local Redis and Neo4j)
+- Ollama running on your network with `gemma4-it:e2b` pulled
+- A Discord bot token and application ID
+
+---
+
+## Quick Start
+
+### 1. Clone and install
+
+```bash
+git clone <your-repo>
+cd mardonar-bot
+npm install
+```
+
+### 2. Configure environment
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env`:
+
+```env
+DISCORD_TOKEN=your_discord_bot_token
+DISCORD_CLIENT_ID=your_discord_application_id
+
+REDIS_URL=redis://localhost:6379
+
+NEO4J_URI=bolt://localhost:7687
+NEO4J_USER=neo4j
+NEO4J_PASSWORD=mardonardev
+
+# Point at your Ollama node — can be a LAN IP
+OLLAMA_BASE_URL=http://192.168.1.x:11434
+OLLAMA_MODEL=gemma4-it:e2b
+
+LOG_LEVEL=debug
+```
+
+### 3. Start local services
+
+```bash
+docker compose -f docker-compose.dev.yml up -d
+```
+
+This starts Redis on `localhost:6379` and Neo4j on `localhost:7687`.
+Neo4j browser UI is available at `http://localhost:7474` (login: neo4j / mardonardev).
+
+### 4. Register Discord slash commands
+
+Run once per bot deployment, or whenever commands change:
+
+```bash
+npm run deploy-commands
+```
+
+### 5. Start the bot
+
+```bash
+npm run dev       # development (tsx watch mode)
+npm run build     # compile TypeScript
+npm run start     # run compiled output
+```
+
+---
+
+## Project Structure
+
+```
+mardonar-bot/
+├── src/
+│   ├── bot/
+│   │   ├── commands/
+│   │   │   ├── dndname.ts       # /dndname set|show|clear
+│   │   │   └── encounter.ts     # /encounter start|status|end
+│   │   ├── embeds/
+│   │   │   ├── skillCheck.ts    # Skill check embed builder
+│   │   │   ├── playerGate.ts    # "Please register your name" embed
+│   │   │   └── resolution.ts    # Encounter complete embed
+│   │   └── handlers/
+│   │       └── messageRouter.ts # Main event loop for encounter threads
+│   ├── session/
+│   │   ├── playerRegistry.ts    # Redis: discordId → dndName
+│   │   └── sessionManager.ts    # Redis: threadId → SessionState
+│   ├── harness/
+│   │   ├── promptBuilder.ts     # System prompt assembly
+│   │   ├── contextAssembler.ts  # History + token budget management
+│   │   ├── ollamaClient.ts      # Ollama API client
+│   │   ├── toolParser.ts        # tool_call block detection and parsing
+│   │   └── toolDispatcher.ts    # Routes parsed tool calls to handlers
+│   ├── mcp/
+│   │   ├── server.ts            # MCP server setup (@modelcontextprotocol/sdk)
+│   │   └── tools/
+│   │       ├── skillCheckEmit.ts
+│   │       ├── skillCheckResolve.ts
+│   │       ├── eventLogAppend.ts
+│   │       ├── npcMemoryRead.ts
+│   │       ├── npcMemoryWrite.ts
+│   │       └── encounterResolve.ts
+│   ├── db/
+│   │   ├── redis.ts             # ioredis singleton
+│   │   └── neo4j.ts             # neo4j-driver singleton + runQuery helper
+│   ├── spec/
+│   │   └── loader.ts            # YAML spec loader + Zod validation
+│   ├── config.ts                # Zod-validated env vars
+│   └── types/
+│       └── index.ts             # All shared TypeScript interfaces
+├── specs/
+│   └── market-thief.yaml        # Example encounter spec
+├── tests/
+│   ├── unit/
+│   └── integration/
+├── scripts/
+│   └── deploy-commands.ts       # Registers slash commands with Discord
+├── docker-compose.dev.yml
+├── package.json
+├── tsconfig.json
+└── vitest.config.ts
+```
+
+---
+
+## Discord Commands
+
+### Player commands
+
+| Command | Description |
+|---|---|
+| `/dndname set <name>` | Register or update your D&D character name |
+| `/dndname show` | Show your current registered name |
+| `/dndname clear` | Remove your registration |
+
+Players must register before they can participate in an encounter.
+If an unregistered player posts in an encounter thread, the bot sends
+an ephemeral embed asking them to register first.
+
+### DM / Admin commands
+
+| Command | Description |
+|---|---|
+| `/encounter start <spec-name>` | Load a spec and open a new encounter thread |
+| `/encounter status` | Show session phase, player list, event count |
+| `/encounter end` | Force-resolve the encounter (admin override) |
+
+`<spec-name>` maps to a file in `./specs/`. E.g. `/encounter start market-thief`
+loads `./specs/market-thief.yaml`.
+
+---
+
+## Encounter Specs
+
+Encounters are defined as YAML files in the `./specs/` directory.
+Each spec defines the setting, NPC personas, hidden goals, and skill check DCs.
+
+See `specs/market-thief.yaml` for a fully annotated example.
+
+### Key fields
+
+```yaml
+encounterId:        # Unique ID — used as Neo4j node key
+title:              # Display name shown in Discord embeds
+setting:            # location, mood, ambientNpcs (all strings)
+openingNarrative:   # The scene-setting text posted at session start
+npcs:               # 1–3 personas. Each has id, name, role, persona, optional memoryKey
+goals:
+  primary:          # Main target endings the LLM steers toward
+  secondary:        # Valid but non-primary outcomes
+sportsmanshipRules: # List of "do not allow" rules
+skillChecks:        # Named DCs e.g. chase_dc: 13
+```
+
+---
+
+## How a Session Works
+
+```
+1. DM runs /encounter start <spec>
+2. Bot creates a Discord thread and posts the opening narrative
+3. Players post what their character does
+4. Bot appends the message to session history, calls Ollama
+5. Ollama response is parsed:
+   - Narrative text → posted to the thread
+   - tool_call block → dispatched silently
+6. Tool results (skill check embeds, Neo4j writes) happen automatically
+7. When a goal is reached, LLM calls encounter_resolve
+8. Bot posts the resolution embed and archives the thread
+```
+
+### Skill checks
+
+When the LLM determines a roll is warranted, it emits a `skill_check_emit`
+tool call. The bot posts a Discord embed:
+
+```
+🎲 Skill Check — Aelindra
+What skill are you using to chase Dal?
+DC: 13
+Reply with: "I rolled a [number] [Skill Name]"
+```
+
+The player replies naturally, e.g. `"I rolled a 17 Acrobatics"`. The bot
+detects this, logs the result, and feeds it back to the LLM as context.
+
+---
+
+## Context Window Budget
+
+The harness manages a strict token budget for the 128k context window:
+
+| Zone | Budget |
+|---|---|
+| System prompt (narrator + NPCs + goals + tools) | 4,000 tokens |
+| Pinned messages (opening narrative, never trimmed) | 2,000 tokens |
+| Sliding history window | 118,000 tokens |
+| Safety buffer | 3,500 tokens |
+
+When history exceeds the sliding window budget, the oldest non-pinned
+turn pairs are dropped from the front. The opening narrative and goal
+block are always preserved.
+
+---
+
+## NPC Memory
+
+Named NPCs with a `memoryKey` in their spec have persistent memory in Neo4j.
+At session start, their memory facts are loaded and injected into the system
+prompt. At encounter resolution, any `npc_memory_write` tool calls are
+committed to the graph.
+
+This means a NPC like Miriam can remember that your party helped her
+in a previous encounter — or that you let the thief go.
+
+---
+
+## Running Tests
+
+```bash
+npm run test          # run all tests
+npm run test:unit     # unit tests only (no external services)
+npm run test:int      # integration tests (requires Docker services running)
+```
+
+Integration tests require live Redis and Neo4j. Start them first:
+
+```bash
+docker compose -f docker-compose.dev.yml up -d
+npm run test:int
+```
+
+---
+
+## Adding a New Encounter
+
+1. Copy `specs/market-thief.yaml` to `specs/your-encounter.yaml`
+2. Fill in all required fields
+3. Test spec loading: `npm run validate-spec your-encounter`
+4. Run `/encounter start your-encounter` in Discord
+
+---
+
+## Deployment Notes
+
+The bot is a single Node.js process. It connects to:
+- Redis (ioredis) for session and player registry
+- Neo4j (neo4j-driver) for NPC memory and event logs
+- Ollama over HTTP for LLM inference
+- Discord over WebSocket (discord.js)
+
+For production on your Proxmox node, run as a Docker container or
+systemd service. Point `OLLAMA_BASE_URL` at whichever node is running
+your Ollama instance.
+
+```bash
+# Build
+npm run build
+
+# Run (with .env file)
+node dist/bot/index.js
+```
+
+---
+
+## Architecture Documents
+
+Full design rationale and phased build plan are in `docs/`:
+
+- `docs/mardonar-encounter-engine.md` — system overview and key decisions
+- `docs/mardonar-build-plan.md` — phased build plan with packages and test guidance
diff --git a/data/summaries/cog-claw-debt-001-2026-05-26T03-26-55-854Z.txt b/data/summaries/cog-claw-debt-001-2026-05-26T03-26-55-854Z.txt
new file mode 100644
index 0000000..4214936
--- /dev/null
+++ b/data/summaries/cog-claw-debt-001-2026-05-26T03-26-55-854Z.txt
@@ -0,0 +1,9 @@
+Encounter : The Collector's Due
+ID        : cog-claw-debt-001
+Thread    : 1508671535840493609
+Date      : 2026-05-26T03:26:55.854Z
+Outcome   : gorga_attacked
+Players   : Angro
+
+Summary:
+Angro shot Gorga at close range with a silenced firearm in the back alley behind the Anvil & Tallow smithy. Gorga died against the wall, his ledger falling open in the blood. Terren Ashweld is now complicit in the death of a Cog Claw Consortium collector. The debt remains unpaid, the Consortium will retaliate, and a body now lies in Mardonar that will be discovered before nightfall. Angro and Terren are both marked.
\ No newline at end of file
diff --git a/data/summaries/mardonar-market-thief-001-2026-05-24T04-42-39-336Z.txt b/data/summaries/mardonar-market-thief-001-2026-05-24T04-42-39-336Z.txt
new file mode 100644
index 0000000..5b2c119
--- /dev/null
+++ b/data/summaries/mardonar-market-thief-001-2026-05-24T04-42-39-336Z.txt
@@ -0,0 +1,9 @@
+Encounter : The Market Square Thief
+ID        : mardonar-market-thief-001
+Thread    : 1507959432414236785
+Date      : 2026-05-24T04:42:39.337Z
+Outcome   : admin_end
+Players   : Boris
+
+Summary:
+Encounter ended by admin: sirhaxolot
\ No newline at end of file
diff --git a/data/summaries/mardonar-market-thief-001-2026-05-24T05-31-37-164Z.txt b/data/summaries/mardonar-market-thief-001-2026-05-24T05-31-37-164Z.txt
new file mode 100644
index 0000000..9ee3f5d
--- /dev/null
+++ b/data/summaries/mardonar-market-thief-001-2026-05-24T05-31-37-164Z.txt
@@ -0,0 +1,9 @@
+Encounter : The Market Square Thief
+ID        : mardonar-market-thief-001
+Thread    : 1507967141750636544
+Date      : 2026-05-24T05:31:37.165Z
+Outcome   : <goal_id>
+Players   : Boris
+
+Summary:
+Boris calmed the situation, returned the stolen item to Miriam, and persuaded Dal to meet at his camp later for guidance regarding his path.
\ No newline at end of file
diff --git a/data/summaries/mardonar-market-thief-001-2026-05-26T03-22-13-663Z.txt b/data/summaries/mardonar-market-thief-001-2026-05-26T03-22-13-663Z.txt
new file mode 100644
index 0000000..1fa43d0
--- /dev/null
+++ b/data/summaries/mardonar-market-thief-001-2026-05-26T03-22-13-663Z.txt
@@ -0,0 +1,9 @@
+Encounter : The Market Square Thief
+ID        : mardonar-market-thief-001
+Thread    : 1508652166892753096
+Date      : 2026-05-26T03:22:13.663Z
+Outcome   : escape
+Players   : Angro, Boris
+
+Summary:
+Angro and Boris failed to pursue or stop Dal after he stole an apple from Miriam's stall. Multiple attempts to escalate to lethal force were rejected per sportsmanship rules. Dal escaped into the crowd with the apple. Miriam was left furious and disappointed.
\ No newline at end of file
diff --git a/data/summaries/mardonar-market-thief-001-2026-05-26T06-36-03-308Z.txt b/data/summaries/mardonar-market-thief-001-2026-05-26T06-36-03-308Z.txt
new file mode 100644
index 0000000..8c73598
--- /dev/null
+++ b/data/summaries/mardonar-market-thief-001-2026-05-26T06-36-03-308Z.txt
@@ -0,0 +1,9 @@
+Encounter : The Market Square Thief
+ID        : mardonar-market-thief-001
+Thread    : 1508671514524909638
+Date      : 2026-05-26T06:36:03.308Z
+Outcome   : admin_end
+Players   : Zalram
+
+Summary:
+Zalram Cloudwalker, a spellcaster, chased a young hooded thief named Dal after he stole an apple from Miriam's stall in Mardonar's Market Square food festival. Zalram initially failed to cast Mage Hand and an unnamed spell, but after confirming Boomering was in his spellbook, he cast the spell at Dal as the thief fled into an alley. The record ends before the spell attack's result is determined, leaving the encounter unresolved.
\ No newline at end of file
diff --git a/data/summaries/mardonar-market-thief-001-2026-05-26T22-12-04-810Z.txt b/data/summaries/mardonar-market-thief-001-2026-05-26T22-12-04-810Z.txt
new file mode 100644
index 0000000..9772c39
--- /dev/null
+++ b/data/summaries/mardonar-market-thief-001-2026-05-26T22-12-04-810Z.txt
@@ -0,0 +1,9 @@
+Encounter : The Market Square Thief
+ID        : mardonar-market-thief-001
+Thread    : 1508948971119444160
+Date      : 2026-05-26T22:12:04.810Z
+Outcome   : negotiate
+Players   : Zalram Cloudwalker
+
+Summary:
+Zalram Cloudwalker cornered the young thief Brek using an Arcane Anomaly illusion and chose not to harm him. He offered to pay for the stolen apple on the condition that Brek returns weekly to work for Berta the vendor. Berta agreed to give Brek honest work and an apple a day. Brek surrendered voluntarily, accepted the arrangement, and the encounter ended peacefully with no violence or guard involvement.
\ No newline at end of file
diff --git a/data/summaries/mawfang-pursuit-001-2026-05-24T07-59-27-624Z.txt b/data/summaries/mawfang-pursuit-001-2026-05-24T07-59-27-624Z.txt
new file mode 100644
index 0000000..145031e
--- /dev/null
+++ b/data/summaries/mawfang-pursuit-001-2026-05-24T07-59-27-624Z.txt
@@ -0,0 +1,9 @@
+Encounter : Unwelcome Guests
+ID        : mawfang-pursuit-001
+Thread    : 1508014981726208080
+Date      : 2026-05-24T07:59:27.624Z
+Outcome   : admin_end
+Players   : Boris
+
+Summary:
+The character Boris entered the Silt & Sow inn, where he encountered a group of intimidating Mawfang hunters. When Boris attempted to depart, one hunter named Usk questioned his relevance in the district and directed attention toward another cloaked figure concealed within the room. Ultimately, Boris chose to leave the town area with his party rather than engage further with the hunters.
\ No newline at end of file
diff --git a/data/summaries/mawfang-pursuit-001-2026-05-26T03-37-54-540Z.txt b/data/summaries/mawfang-pursuit-001-2026-05-26T03-37-54-540Z.txt
new file mode 100644
index 0000000..82a86bf
--- /dev/null
+++ b/data/summaries/mawfang-pursuit-001-2026-05-26T03-37-54-540Z.txt
@@ -0,0 +1,9 @@
+Encounter : Unwelcome Guests
+ID        : mawfang-pursuit-001
+Thread    : 1508671607844114464
+Date      : 2026-05-26T03:37:54.540Z
+Outcome   : hunters_confronted
+Players   : Angro
+
+Summary:
+Angro attacked Usk three times with a hammer. Usk disarmed him, pinned him to the wall, then took the gnome Fizbet and her device out of the inn into the rain. The hunters left Angro alive on the floor. Usk promised nothing — but this is not finished. The device leaves with the Mawfang.
\ No newline at end of file
diff --git a/data/tally.json b/data/tally.json
new file mode 100644
index 0000000..562f94b
--- /dev/null
+++ b/data/tally.json
@@ -0,0 +1,22 @@
+{
+  "market-thief": {
+    "runs": 4,
+    "lastRun": "2026-05-26T21:44:33.947Z"
+  },
+  "mawfang-pursuit": {
+    "runs": 2,
+    "lastRun": "2026-05-26T03:22:23.938Z"
+  },
+  "cog-claw-debt": {
+    "runs": 3,
+    "lastRun": "2026-05-26T03:22:19.935Z"
+  },
+  "stormscar-pilgrim": {
+    "runs": 1,
+    "lastRun": "2026-05-26T06:37:00.697Z"
+  },
+  "silt-leak": {
+    "runs": 1,
+    "lastRun": "2026-05-30T03:07:28.390Z"
+  }
+}
\ No newline at end of file
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
new file mode 100644
index 0000000..3382b67
--- /dev/null
+++ b/docker-compose.dev.yml
@@ -0,0 +1,40 @@
+version: "3.9"
+
+# Mardonar Encounter Engine
+#
+# docker compose up -d --build
+#   1. Builds the image
+#   2. Runs deploy-commands (registers slash commands with Discord)
+#   3. Starts the bot
+#
+# Joins the knowledge-graph-ai_internal network so it can reach:
+#   redis       → redis://redis:6379
+#   mcp-server  → http://mcp-server:9000
+# Both containers live in the GraphMCP-Example stack — start that first.
+
+networks:
+  mardonar-internal:
+    external: true
+
+services:
+  deploy-commands:
+    build: .
+    container_name: mardonar-deploy-commands
+    restart: "no"
+    env_file: .env
+    networks:
+      - mardonar-internal
+    command: ["node", "dist/scripts/deploy-commands.js"]
+
+  bot:
+    build: .
+    container_name: mardonar-bot
+    restart: unless-stopped
+    env_file: .env
+    networks:
+      - mardonar-internal
+    volumes:
+      - ./data:/app/data
+    depends_on:
+      deploy-commands:
+        condition: service_completed_successfully
diff --git a/index.ts b/index.ts
new file mode 100644
index 0000000..6cc6a5b
--- /dev/null
+++ b/index.ts
@@ -0,0 +1,225 @@
+// src/types/index.ts
+// Shared types used across all layers of the Mardonar Encounter Engine.
+// Import from here only — do not duplicate type definitions elsewhere.
+
+// ---------------------------------------------------------------------------
+// Players
+// ---------------------------------------------------------------------------
+
+export interface Player {
+  discordId: string;
+  dndName: string;
+}
+
+// ---------------------------------------------------------------------------
+// Encounter Spec
+// ---------------------------------------------------------------------------
+
+export interface NpcPersona {
+  /** Unique stable ID used as Neo4j node key. e.g. "miriam-vendor-mardonar" */
+  id: string;
+  name: string;
+  role: string;
+  /** Full persona description injected into the system prompt. */
+  persona: string;
+  /**
+   * If set, NPC memories are loaded from Neo4j at session start
+   * and written back on encounter_resolve.
+   */
+  memoryKey?: string;
+}
+
+export interface EncounterGoal {
+  id: string;
+  label: string;
+}
+
+export interface EncounterGoals {
+  hidden: boolean;
+  primary: EncounterGoal[];
+  secondary: EncounterGoal[];
+}
+
+export interface EncounterSetting {
+  location: string;
+  mood: string;
+  ambientNpcs: string;
+}
+
+export interface EncounterSpec {
+  encounterId: string;
+  title: string;
+  setting: EncounterSetting;
+  openingNarrative: string;
+  npcs: NpcPersona[];
+  goals: EncounterGoals;
+  sportsmanshipRules: string[];
+  /** Skill check DCs and notes keyed by check name e.g. "chase_dc" → 13 */
+  skillChecks: Record<string, number | string>;
+  dmNotes?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Session State
+// ---------------------------------------------------------------------------
+
+export type SessionPhase = 'open' | 'active' | 'resolved';
+
+export interface SessionState {
+  encounterId: string;
+  /** Discord thread snowflake ID — used as the primary session key in Redis. */
+  threadId: string;
+  guildId: string;
+  spec: EncounterSpec;
+  /** Map of discordId → Player for all players who have entered the session. */
+  players: Record<string, Player>;
+  history: ChatMessage[];
+  phase: SessionPhase;
+  /** Messages held while waiting for a player to register their DnD name. */
+  heldMessages: HeldMessage[];
+  /** Outcome goal ID set when the encounter resolves. */
+  outcome?: string;
+  outcomeSummary?: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+// ---------------------------------------------------------------------------
+// Chat History
+// ---------------------------------------------------------------------------
+
+export interface ChatMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+  /**
+   * Pinned messages are never removed during history trimming.
+   * Use for: opening narrative, goal block.
+   */
+  pinned?: boolean;
+  timestamp: number;
+}
+
+export interface HeldMessage {
+  discordUserId: string;
+  content: string;
+  timestamp: number;
+}
+
+// ---------------------------------------------------------------------------
+// LLM Harness
+// ---------------------------------------------------------------------------
+
+export interface ToolCallBlock {
+  tool: ToolName;
+  args: Record<string, unknown>;
+}
+
+export interface LLMResponse {
+  /** Narrative text to post to the Discord thread. */
+  narrative: string;
+  /** Parsed tool call block, if the LLM emitted one. */
+  toolCall?: ToolCallBlock;
+  /** Raw token count returned by Ollama (eval_count). */
+  rawTokensUsed?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Tools
+// ---------------------------------------------------------------------------
+
+export type ToolName =
+  | 'skill_check_emit'
+  | 'skill_check_resolve'
+  | 'event_log_append'
+  | 'npc_memory_read'
+  | 'npc_memory_write'
+  | 'encounter_resolve';
+
+export interface SkillCheckEmitArgs {
+  player: string;
+  prompt: string;
+  dc: number;
+}
+
+export interface SkillCheckResolveArgs {
+  player: string;
+  skill: string;
+  roll: number;
+  modifier: number;
+  dc: number;
+  success: boolean;
+}
+
+export interface EventLogAppendArgs {
+  sessionId: string;
+  eventType: EventType;
+  description: string;
+}
+
+export interface NpcMemoryReadArgs {
+  npcId: string;
+}
+
+export interface NpcMemoryWriteArgs {
+  npcId: string;
+  memoryFact: string;
+}
+
+export interface EncounterResolveArgs {
+  sessionId: string;
+  outcomeId: string;
+  summary: string;
+}
+
+export type EventType =
+  | 'player_action'
+  | 'skill_check'
+  | 'npc_action'
+  | 'outcome'
+  | 'sportsmanship'
+  | 'session_start'
+  | 'player_joined';
+
+// ---------------------------------------------------------------------------
+// Neo4j
+// ---------------------------------------------------------------------------
+
+export interface NpcNode {
+  id: string;
+  name: string;
+  personaSummary: string;
+  memoryFacts: string[];
+  lastSeenEncounter: string | null;
+}
+
+export interface EncounterNode {
+  id: string;
+  title: string;
+  resolved: boolean;
+  outcomeId: string | null;
+  createdAt: string;
+}
+
+export interface EncounterEventNode {
+  timestamp: string;
+  type: EventType;
+  description: string;
+}
+
+// ---------------------------------------------------------------------------
+// Context Budget
+// (Exported as a const so all callers use the same values)
+// ---------------------------------------------------------------------------
+
+export const CONTEXT_BUDGET = {
+  /** Maximum system prompt size including all NPC personas. */
+  SYSTEM: 4_000,
+  /** Pinned messages (opening narrative + goal block). Never trimmed. */
+  PINNED: 2_000,
+  /** Sliding history window. */
+  HISTORY: 118_000,
+  /** Hard floor — stop trimming here even if still over budget. */
+  SAFETY: 3_500,
+  /** Total context window of gemma4-it:e2b. */
+  TOTAL: 128_000,
+} as const;
diff --git a/lore/vocabulary.yaml b/lore/vocabulary.yaml
new file mode 100644
index 0000000..1f992e9
--- /dev/null
+++ b/lore/vocabulary.yaml
@@ -0,0 +1,172 @@
+# Mardonar Lore Vocabulary
+# Curated name and place lists for encounter randomization.
+# Spec files reference these via: source: vocabulary, category: <dot.path>
+# All entries are grounded in Mardonar's setting and should feel at home there.
+
+names:
+  human:
+    female:
+      - Sable
+      - Kessa
+      - Mira
+      - Yenna
+      - Petra
+      - Anda
+      - Corvae
+      - Liret
+      - Nessa
+      - Damith
+      - Rielle
+      - Varsha
+    male:
+      - Brek
+      - Caden
+      - Holt
+      - Javin
+      - Runn
+      - Selvar
+      - Toryn
+      - Aldric
+      - Fenwick
+      - Orren
+      - Davan
+      - Silis
+
+  dwarf:
+    female:
+      - Brunna
+      - Dagga
+      - Hilda
+      - Ragna
+      - Svekka
+      - Wenna
+      - Berta
+      - Kirra
+      - Unna
+      - Thordis
+    male:
+      - Baldur
+      - Dorn
+      - Grimm
+      - Morg
+      - Rurik
+      - Skalf
+      - Thorek
+      - Brond
+      - Vekk
+      - Hardin
+      - Ovrak
+
+  gnome:
+    any:
+      - Tizzbit
+      - Wrenkit
+      - Nixwick
+      - Fizpo
+      - Snibble
+      - Cogsworth
+      - Spreck
+      - Rimbolt
+      - Twigget
+      - Pell
+
+  halfling:
+    any:
+      - Bingo
+      - Crix
+      - Della
+      - Embo
+      - Pip
+      - Rosco
+      - Sori
+      - Tuck
+      - Wren
+      - Olly
+
+  orc:
+    any:
+      - Grak
+      - Skarn
+      - Thun
+      - Varg
+      - Zori
+      - Brek
+      - Dunn
+      - Harg
+      - Murg
+      - Tolg
+
+  ratling:
+    any:
+      - Chitik
+      - Nassik
+      - Squeev
+      - Wisk
+      - Nibs
+      - Shrivel
+      - Thritch
+      - Peck
+      - Skemp
+      - Wibble
+
+  elf:
+    female:
+      - Faera
+      - Ilmara
+      - Sylene
+      - Vaeria
+      - Aelith
+      - Caeli
+      - Lyreth
+      - Miri
+    male:
+      - Calin
+      - Drev
+      - Faeron
+      - Lyrel
+      - Aelen
+      - Berev
+      - Sorin
+      - Thirel
+
+locations:
+  market:
+    - The Copperway Market
+    - Saltstone Square
+    - The Tanner's Quarter
+    - Ironbell Market
+    - The Undercroft Bazaar
+    - Greenway Market
+    - The Spice Row
+    - Bridgefoot Square
+
+  inn:
+    - The Broken Compass
+    - The Crooked Lantern
+    - The Mended Drum
+    - The Dusty Heel
+    - The Soot & Hearth
+    - The Iron Flagon
+    - The Wanderer's Rest
+    - The Ember & Stone
+
+  village:
+    - Cinder Ford
+    - Greymoss Crossing
+    - Tallow's End
+    - Ashwick
+    - Breckfen
+    - Moldvale
+    - Harrow's Gate
+    - Dunford
+    - Saltmere
+    - Edgemarsh
+
+  road:
+    - the Pilgrim's Switchback
+    - the Ridge Road
+    - the Goat Track
+    - the Sheercliff Path
+    - the High Drove
+    - the Ironway
+    - the Mossback Trail
diff --git a/package-lock.json b/package-lock.json
new file mode 100644
index 0000000..c716663
--- /dev/null
+++ b/package-lock.json
@@ -0,0 +1,2973 @@
+{
+  "name": "mardonar-bot",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "mardonar-bot",
+      "version": "0.1.0",
+      "dependencies": {
+        "@discordjs/builders": "^1.10.0",
+        "@discordjs/rest": "^2.4.0",
+        "discord.js": "^14.18.0",
+        "dotenv": "^16.4.0",
+        "gpt-tokenizer": "^2.8.0",
+        "ioredis": "^5.4.0",
+        "js-yaml": "^4.1.0",
+        "ollama": "^0.5.0",
+        "openai": "^6.39.0",
+        "pino": "^9.6.0",
+        "pino-pretty": "^13.0.0",
+        "zod": "^3.24.0"
+      },
+      "devDependencies": {
+        "@types/js-yaml": "^4.0.9",
+        "@types/node": "^22.0.0",
+        "ioredis-mock": "^8.9.0",
+        "tsx": "^4.19.0",
+        "typescript": "^5.8.0",
+        "vitest": "^3.1.0"
+      }
+    },
+    "node_modules/@discordjs/builders": {
+      "version": "1.14.1",
+      "resolved": "https://registry.npmjs.org/@discordjs/builders/-/builders-1.14.1.tgz",
+      "integrity": "sha512-gSKkhXLqs96TCzk66VZuHHl8z2bQMJFGwrXC0f33ngK+FLNau4hU1PYny3DNJfNdSH+gVMzE85/d5FQ2BpcNwQ==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@discordjs/formatters": "^0.6.2",
+        "@discordjs/util": "^1.2.0",
+        "@sapphire/shapeshift": "^4.0.0",
+        "discord-api-types": "^0.38.40",
+        "fast-deep-equal": "^3.1.3",
+        "ts-mixer": "^6.0.4",
+        "tslib": "^2.6.3"
+      },
+      "engines": {
+        "node": ">=16.11.0"
+      },
+      "funding": {
+        "url": "https://github.com/discordjs/discord.js?sponsor"
+      }
+    },
+    "node_modules/@discordjs/collection": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/@discordjs/collection/-/collection-2.1.1.tgz",
+      "integrity": "sha512-LiSusze9Tc7qF03sLCujF5iZp7K+vRNEDBZ86FT9aQAv3vxMLihUvKvpsCWiQ2DJq1tVckopKm1rxomgNUc9hg==",
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/discordjs/discord.js?sponsor"
+      }
+    },
+    "node_modules/@discordjs/formatters": {
+      "version": "0.6.2",
+      "resolved": "https://registry.npmjs.org/@discordjs/formatters/-/formatters-0.6.2.tgz",
+      "integrity": "sha512-y4UPwWhH6vChKRkGdMB4odasUbHOUwy7KL+OVwF86PvT6QVOwElx+TiI1/6kcmcEe+g5YRXJFiXSXUdabqZOvQ==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "discord-api-types": "^0.38.33"
+      },
+      "engines": {
+        "node": ">=16.11.0"
+      },
+      "funding": {
+        "url": "https://github.com/discordjs/discord.js?sponsor"
+      }
+    },
+    "node_modules/@discordjs/rest": {
+      "version": "2.6.1",
+      "resolved": "https://registry.npmjs.org/@discordjs/rest/-/rest-2.6.1.tgz",
+      "integrity": "sha512-wwQdgjeaoYFiaG+atbqx6aJDpqW7JHAo0HrQkBTbYzM3/PJ3GweQIpgElNcGZ26DCUOXMyawYd0YF7vtr+fZXg==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@discordjs/collection": "^2.1.1",
+        "@discordjs/util": "^1.2.0",
+        "@sapphire/async-queue": "^1.5.3",
+        "@sapphire/snowflake": "^3.5.5",
+        "@vladfrangu/async_event_emitter": "^2.4.6",
+        "discord-api-types": "^0.38.40",
+        "magic-bytes.js": "^1.13.0",
+        "tslib": "^2.6.3",
+        "undici": "6.24.1"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/discordjs/discord.js?sponsor"
+      }
+    },
+    "node_modules/@discordjs/util": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/@discordjs/util/-/util-1.2.0.tgz",
+      "integrity": "sha512-3LKP7F2+atl9vJFhaBjn4nOaSWahZ/yWjOvA4e5pnXkt2qyXRCHLxoBQy81GFtLGCq7K9lPm9R517M1U+/90Qg==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "discord-api-types": "^0.38.33"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/discordjs/discord.js?sponsor"
+      }
+    },
+    "node_modules/@discordjs/ws": {
+      "version": "1.2.3",
+      "resolved": "https://registry.npmjs.org/@discordjs/ws/-/ws-1.2.3.tgz",
+      "integrity": "sha512-wPlQDxEmlDg5IxhJPuxXr3Vy9AjYq5xCvFWGJyD7w7Np8ZGu+Mc+97LCoEc/+AYCo2IDpKioiH0/c/mj5ZR9Uw==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@discordjs/collection": "^2.1.0",
+        "@discordjs/rest": "^2.5.1",
+        "@discordjs/util": "^1.1.0",
+        "@sapphire/async-queue": "^1.5.2",
+        "@types/ws": "^8.5.10",
+        "@vladfrangu/async_event_emitter": "^2.2.4",
+        "discord-api-types": "^0.38.1",
+        "tslib": "^2.6.2",
+        "ws": "^8.17.0"
+      },
+      "engines": {
+        "node": ">=16.11.0"
+      },
+      "funding": {
+        "url": "https://github.com/discordjs/discord.js?sponsor"
+      }
+    },
+    "node_modules/@esbuild/aix-ppc64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.0.tgz",
+      "integrity": "sha512-lhRUCeuOyJQURhTxl4WkpFTjIsbDayJHih5kZC1giwE+MhIzAb7mEsQMqMf18rHLsrb5qI1tafG20mLxEWcWlA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.0.tgz",
+      "integrity": "sha512-wqh0ByljabXLKHeWXYLqoJ5jKC4XBaw6Hk08OfMrCRd2nP2ZQ5eleDZC41XHyCNgktBGYMbqnrJKq/K/lzPMSQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.0.tgz",
+      "integrity": "sha512-+WzIXQOSaGs33tLEgYPYe/yQHf0WTU0X42Jca3y8NWMbUVhp7rUnw+vAsRC/QiDrdD31IszMrZy+qwPOPjd+rw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.0.tgz",
+      "integrity": "sha512-+VJggoaKhk2VNNqVL7f6S189UzShHC/mR9EE8rDdSkdpN0KflSwWY/gWjDrNxxisg8Fp1ZCD9jLMo4m0OUfeUA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.0.tgz",
+      "integrity": "sha512-0T+A9WZm+bZ84nZBtk1ckYsOvyA3x7e2Acj1KdVfV4/2tdG4fzUp91YHx+GArWLtwqp77pBXVCPn2We7Letr0Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.0.tgz",
+      "integrity": "sha512-fyzLm/DLDl/84OCfp2f/XQ4flmORsjU7VKt8HLjvIXChJoFFOIL6pLJPH4Yhd1n1gGFF9mPwtlN5Wf82DZs+LQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.0.tgz",
+      "integrity": "sha512-l9GeW5UZBT9k9brBYI+0WDffcRxgHQD8ShN2Ur4xWq/NFzUKm3k5lsH4PdaRgb2w7mI9u61nr2gI2mLI27Nh3Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.0.tgz",
+      "integrity": "sha512-BXoQai/A0wPO6Es3yFJ7APCiKGc1tdAEOgeTNy3SsB491S3aHn4S4r3e976eUnPdU+NbdtmBuLncYir2tMU9Nw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.0.tgz",
+      "integrity": "sha512-CjaaREJagqJp7iTaNQjjidaNbCKYcd4IDkzbwwxtSvjI7NZm79qiHc8HqciMddQ6CKvJT6aBd8lO9kN/ZudLlw==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.0.tgz",
+      "integrity": "sha512-RVyzfb3FWsGA55n6WY0MEIEPURL1FcbhFE6BffZEMEekfCzCIMtB5yyDcFnVbTnwk+CLAgTujmV/Lgvih56W+A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ia32": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.0.tgz",
+      "integrity": "sha512-KBnSTt1kxl9x70q+ydterVdl+Cn0H18ngRMRCEQfrbqdUuntQQ0LoMZv47uB97NljZFzY6HcfqEZ2SAyIUTQBQ==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-loong64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.0.tgz",
+      "integrity": "sha512-zpSlUce1mnxzgBADvxKXX5sl8aYQHo2ezvMNI8I0lbblJtp8V4odlm3Yzlj7gPyt3T8ReksE6bK+pT3WD+aJRg==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-mips64el": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.0.tgz",
+      "integrity": "sha512-2jIfP6mmjkdmeTlsX/9vmdmhBmKADrWqN7zcdtHIeNSCH1SqIoNI63cYsjQR8J+wGa4Y5izRcSHSm8K3QWmk3w==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ppc64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.0.tgz",
+      "integrity": "sha512-bc0FE9wWeC0WBm49IQMPSPILRocGTQt3j5KPCA8os6VprfuJ7KD+5PzESSrJ6GmPIPJK965ZJHTUlSA6GNYEhg==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-riscv64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.0.tgz",
+      "integrity": "sha512-SQPZOwoTTT/HXFXQJG/vBX8sOFagGqvZyXcgLA3NhIqcBv1BJU1d46c0rGcrij2B56Z2rNiSLaZOYW5cUk7yLQ==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-s390x": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.0.tgz",
+      "integrity": "sha512-SCfR0HN8CEEjnYnySJTd2cw0k9OHB/YFzt5zgJEwa+wL/T/raGWYMBqwDNAC6dqFKmJYZoQBRfHjgwLHGSrn3Q==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.0.tgz",
+      "integrity": "sha512-us0dSb9iFxIi8srnpl931Nvs65it/Jd2a2K3qs7fz2WfGPHqzfzZTfec7oxZJRNPXPnNYZtanmRc4AL/JwVzHQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.0.tgz",
+      "integrity": "sha512-CR/RYotgtCKwtftMwJlUU7xCVNg3lMYZ0RzTmAHSfLCXw3NtZtNpswLEj/Kkf6kEL3Gw+BpOekRX0BYCtklhUw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.0.tgz",
+      "integrity": "sha512-nU1yhmYutL+fQ71Kxnhg8uEOdC0pwEW9entHykTgEbna2pw2dkbFSMeqjjyHZoCmt8SBkOSvV+yNmm94aUrrqw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.0.tgz",
+      "integrity": "sha512-cXb5vApOsRsxsEl4mcZ1XY3D4DzcoMxR/nnc4IyqYs0rTI8ZKmW6kyyg+11Z8yvgMfAEldKzP7AdP64HnSC/6g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.0.tgz",
+      "integrity": "sha512-8wZM2qqtv9UP3mzy7HiGYNH/zjTA355mpeuA+859TyR+e+Tc08IHYpLJuMsfpDJwoLo1ikIJI8jC3GFjnRClzA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.0.tgz",
+      "integrity": "sha512-FLGfyizszcef5C3YtoyQDACyg95+dndv79i2EekILBofh5wpCa1KuBqOWKrEHZg3zrL3t5ouE5jgr94vA+Wb2w==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/sunos-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.0.tgz",
+      "integrity": "sha512-1ZgjUoEdHZZl/YlV76TSCz9Hqj9h9YmMGAgAPYd+q4SicWNX3G5GCyx9uhQWSLcbvPW8Ni7lj4gDa1T40akdlw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.0.tgz",
+      "integrity": "sha512-Q9StnDmQ/enxnpxCCLSg0oo4+34B9TdXpuyPeTedN/6+iXBJ4J+zwfQI28u/Jl40nOYAxGoNi7mFP40RUtkmUA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-ia32": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.0.tgz",
+      "integrity": "sha512-zF3ag/gfiCe6U2iczcRzSYJKH1DCI+ByzSENHlM2FcDbEeo5Zd2C86Aq0tKUYAJJ1obRP84ymxIAksZUcdztHA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.0.tgz",
+      "integrity": "sha512-pEl1bO9mfAmIC+tW5btTmrKaujg3zGtUmWNdCw/xs70FBjwAL3o9OEKNHvNmnyylD6ubxUERiEhdsL0xBQ9efw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@ioredis/as-callback": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/@ioredis/as-callback/-/as-callback-3.0.0.tgz",
+      "integrity": "sha512-Kqv1rZ3WbgOrS+hgzJ5xG5WQuhvzzSTRYvNeyPMLOAM78MHSnuKI20JeJGbpuAt//LCuP0vsexZcorqW7kWhJg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@ioredis/commands": {
+      "version": "1.5.1",
+      "resolved": "https://registry.npmjs.org/@ioredis/commands/-/commands-1.5.1.tgz",
+      "integrity": "sha512-JH8ZL/ywcJyR9MmJ5BNqZllXNZQqQbnVZOqpPQqE1vHiFgAw4NHbvE0FOduNU8IX9babitBT46571OnPTT0Zcw==",
+      "license": "MIT"
+    },
+    "node_modules/@jridgewell/sourcemap-codec": {
+      "version": "1.5.5",
+      "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz",
+      "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@pinojs/redact": {
+      "version": "0.4.0",
+      "resolved": "https://registry.npmjs.org/@pinojs/redact/-/redact-0.4.0.tgz",
+      "integrity": "sha512-k2ENnmBugE/rzQfEcdWHcCY+/FM3VLzH9cYEsbdsoqrvzAKRhUZeRNhAZvB8OitQJ1TBed3yqWtdjzS6wJKBwg==",
+      "license": "MIT"
+    },
+    "node_modules/@rollup/rollup-android-arm-eabi": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.60.4.tgz",
+      "integrity": "sha512-F5QXMSiFebS9hKZj02XhWLLnRpJ3B3AROP0tWbFBSj+6kCbg5m9j5JoHKd4mmSVy5mS/IMQloYgYxCuJC0fxEQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ]
+    },
+    "node_modules/@rollup/rollup-android-arm64": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.60.4.tgz",
+      "integrity": "sha512-GxxTKApUpzRhof7poWvCJHRF51C67u1R7D6DiluBE8wKU1u5GWE8t+v81JvJYtbawoBFX1hLv5Ei4eVjkWokaw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ]
+    },
+    "node_modules/@rollup/rollup-darwin-arm64": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.60.4.tgz",
+      "integrity": "sha512-tua0TaJxMOB1R0V0RS1jFZ/RpURFDJIOR2A6jWwQeawuFyS4gBW+rntLRaQd0EQ4bd6Vp44Z2rXW+YYDBsj6IA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@rollup/rollup-darwin-x64": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.60.4.tgz",
+      "integrity": "sha512-CSKq7MsP+5PFIcydhAiR1K0UhEI1A2jWXVKHPCBZ151yOutENwvnPocgVHkivu2kviURtCEB6zUQw0vs8RrhMg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@rollup/rollup-freebsd-arm64": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.60.4.tgz",
+      "integrity": "sha512-+O8OkVdyvXMtJEciu2wS/pzm1IxntEEQx3z5TAVy4l32G0etZn+RsA48ARRrFm6Ri8fvqPQfgrvNxSjKAbnd3g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-freebsd-x64": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.60.4.tgz",
+      "integrity": "sha512-Iw3oMskH3AfNuhU0MSN7vNbdi4me/NiYo2azqPz/Le16zHSa+3RRmliCMWWQmh4lcndccU40xcJuTYJZxNo/lw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm-gnueabihf": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.60.4.tgz",
+      "integrity": "sha512-EIPRXTVQpHyF8WOo219AD2yEltPehLTcTMz2fn6JsatLYSzQf00hj3rulF+yauOlF9/FtM2WpkT/hJh/KJFGhA==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm-musleabihf": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.60.4.tgz",
+      "integrity": "sha512-J3Yh9PzzF1Ovah2At+lHiGQdsYgArxBbXv/zHfSyaiFQEqvNv7DcW98pCrmdjCZBrqBiKrKKe2V+aaSGWuBe/w==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm64-gnu": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.60.4.tgz",
+      "integrity": "sha512-BFDEZMYfUvLn37ONE1yMBojPxnMlTFsdyNoqncT0qFq1mAfllL+ATMMJd8TeuVMiX84s1KbcxcZbXInmcO2mRg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm64-musl": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.60.4.tgz",
+      "integrity": "sha512-pc9EYOSlOgdQ2uPl1o9PF6/kLSgaUosia7gOuS8mB69IxJvlclko1MECXysjs5ryez1/5zjYqx3+xYU0TU6R1A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-loong64-gnu": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.60.4.tgz",
+      "integrity": "sha512-NxnomyxYerDh5n4iLrNa+sH+Z+U4BMEE46V2PgQ/hoB909i8gV1M5wPojWg9fk1jWpO3IQnOs20K4wyZuFLEFQ==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-loong64-musl": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.60.4.tgz",
+      "integrity": "sha512-nbJnQ8a3z1mtmrwImCYhc6BGpThAyYVRQxw9uKSKG4wR6aAYno9sVjJ0zaZcW9BPJX1GbrDPf+SvdWjgTuDmnw==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-ppc64-gnu": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.60.4.tgz",
+      "integrity": "sha512-2EU6acNrQLd8tYvo/LXW535wupT3m6fo7HKo6lr7ktQoItxTyOL1ZCR/GfGCuXl2vR+zmfI6eRXkSemafv+iVg==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-ppc64-musl": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.60.4.tgz",
+      "integrity": "sha512-WeBtoMuaMxiiIrO2IYP3xs6GMWkJP2C0EoT8beTLkUPmzV1i/UcOSVw1d5r9KBODtHKilG5yFxsGRnBbK3wJ4A==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-riscv64-gnu": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.60.4.tgz",
+      "integrity": "sha512-FJHFfqpKUI3A10WrWKiFbBZ7yVbGT4q4B5o1qKFFojqpaYoh9LrQgqWCmmcxQzVSXYtyB5bzkXrYzlHTs21MYA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-riscv64-musl": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.60.4.tgz",
+      "integrity": "sha512-mcEl6CUT5IAUmQf1m9FYSmVqCJlpQ8r8eyftFUHG8i9OhY7BkBXSUdnLH5DOf0wCOjcP9v/QO93zpmF1SptCCw==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-s390x-gnu": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.60.4.tgz",
+      "integrity": "sha512-ynt3JxVd2w2buzoKDWIyiV1pJW93xlQic1THVLXilz429oijRpSHivZAgp65KBu+cMcgf1eVVjdnTLvPxgCuoQ==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-x64-gnu": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.60.4.tgz",
+      "integrity": "sha512-Boiz5+MsaROEWDf+GGEwF8VMHGhlUoQMtIPjOgA5fv4osupqTVnJteQNKJwUcnUog2G55jYXH7KZFFiJe0TEzQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-x64-musl": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.60.4.tgz",
+      "integrity": "sha512-+qfSY27qIrFfI/Hom04KYFw3GKZSGU4lXus51wsb5EuySfFlWRwjkKWoE9emgRw/ukoT4Udsj4W/+xxG8VbPKg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-openbsd-x64": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.60.4.tgz",
+      "integrity": "sha512-VpTfOPHgVXEBeeR8hZ2O0F3aSso+JDWqTWmTmzcQKted54IAdUVbxE+j/MVxUsKa8L20HJhv3vUezVPoquqWjA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-openharmony-arm64": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.60.4.tgz",
+      "integrity": "sha512-IPOsh5aRYuLv/nkU51X10Bf75Bsf6+gZdx1X+QP5QM6lIJFHHqbHLG0uJn/hWthzo13UAc2umiUorqZy3axoZg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-arm64-msvc": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.60.4.tgz",
+      "integrity": "sha512-4QzE9E81OohJ/HKzHhsqU+zcYYojVOXlFMs1DdyMT6qXl/niOH7AVElmmEdUNHHS/oRkc++d5k6Vy85zFs0DEw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-ia32-msvc": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.60.4.tgz",
+      "integrity": "sha512-zTPgT1YuHHcd+Tmx7h8aml0FWFVelV5N54oHow9SLj+GfoDy/huQ+UV396N/C7KpMDMiPspRktzM1/0r1usYEA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-x64-gnu": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.60.4.tgz",
+      "integrity": "sha512-DRS4G7mi9lJxqEDezIkKCaUIKCrLUUDCUaCsTPCi/rtqaC6D/jjwslMQyiDU50Ka0JKpeXeRBFBAXwArY52vBw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-x64-msvc": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.60.4.tgz",
+      "integrity": "sha512-QVTUovf40zgTqlFVrKA1uXMVvU2QWEFWfAH8Wdc48IxLvrJMQVMBRjuQyUpzZCDkakImib9eVazbWlC6ksWtJw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@sapphire/async-queue": {
+      "version": "1.5.5",
+      "resolved": "https://registry.npmjs.org/@sapphire/async-queue/-/async-queue-1.5.5.tgz",
+      "integrity": "sha512-cvGzxbba6sav2zZkH8GPf2oGk9yYoD5qrNWdu9fRehifgnFZJMV+nuy2nON2roRO4yQQ+v7MK/Pktl/HgfsUXg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=v14.0.0",
+        "npm": ">=7.0.0"
+      }
+    },
+    "node_modules/@sapphire/shapeshift": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/@sapphire/shapeshift/-/shapeshift-4.0.0.tgz",
+      "integrity": "sha512-d9dUmWVA7MMiKobL3VpLF8P2aeanRTu6ypG2OIaEv/ZHH/SUQ2iHOVyi5wAPjQ+HmnMuL0whK9ez8I/raWbtIg==",
+      "license": "MIT",
+      "dependencies": {
+        "fast-deep-equal": "^3.1.3",
+        "lodash": "^4.17.21"
+      },
+      "engines": {
+        "node": ">=v16"
+      }
+    },
+    "node_modules/@sapphire/snowflake": {
+      "version": "3.5.5",
+      "resolved": "https://registry.npmjs.org/@sapphire/snowflake/-/snowflake-3.5.5.tgz",
+      "integrity": "sha512-xzvBr1Q1c4lCe7i6sRnrofxeO1QTP/LKQ6A6qy0iB4x5yfiSfARMEQEghojzTNALDTcv8En04qYNIco9/K9eZQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=v14.0.0",
+        "npm": ">=7.0.0"
+      }
+    },
+    "node_modules/@types/chai": {
+      "version": "5.2.3",
+      "resolved": "https://registry.npmjs.org/@types/chai/-/chai-5.2.3.tgz",
+      "integrity": "sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/deep-eql": "*",
+        "assertion-error": "^2.0.1"
+      }
+    },
+    "node_modules/@types/deep-eql": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/@types/deep-eql/-/deep-eql-4.0.2.tgz",
+      "integrity": "sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@types/estree": {
+      "version": "1.0.9",
+      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz",
+      "integrity": "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@types/ioredis-mock": {
+      "version": "8.2.7",
+      "resolved": "https://registry.npmjs.org/@types/ioredis-mock/-/ioredis-mock-8.2.7.tgz",
+      "integrity": "sha512-YsGiaOIYBKeVvu/7GYziAD8qX3LJem5LK00d5PKykzsQJMLysAqXA61AkNuYWCekYl64tbMTqVOMF4SYoCPbQg==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "ioredis": ">=5"
+      }
+    },
+    "node_modules/@types/js-yaml": {
+      "version": "4.0.9",
+      "resolved": "https://registry.npmjs.org/@types/js-yaml/-/js-yaml-4.0.9.tgz",
+      "integrity": "sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@types/node": {
+      "version": "22.19.19",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.19.tgz",
+      "integrity": "sha512-dyh/xO2Fh5bYrfWaaqGrRQQGkNdmYw6AmaAUvYeUMNTWQtvb796ikLdmTchRmOlOiIJ1TDXfWgVx1QkUlQ6Hew==",
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~6.21.0"
+      }
+    },
+    "node_modules/@types/ws": {
+      "version": "8.18.1",
+      "resolved": "https://registry.npmjs.org/@types/ws/-/ws-8.18.1.tgz",
+      "integrity": "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
+    "node_modules/@vitest/expect": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-3.2.4.tgz",
+      "integrity": "sha512-Io0yyORnB6sikFlt8QW5K7slY4OjqNX9jmJQ02QDda8lyM6B5oNgVWoSoKPac8/kgnCUzuHQKrSLtu/uOqqrig==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/chai": "^5.2.2",
+        "@vitest/spy": "3.2.4",
+        "@vitest/utils": "3.2.4",
+        "chai": "^5.2.0",
+        "tinyrainbow": "^2.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/mocker": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-3.2.4.tgz",
+      "integrity": "sha512-46ryTE9RZO/rfDd7pEqFl7etuyzekzEhUbTW3BvmeO/BcCMEgq59BKhek3dXDWgAj4oMK6OZi+vRr1wPW6qjEQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/spy": "3.2.4",
+        "estree-walker": "^3.0.3",
+        "magic-string": "^0.30.17"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "msw": "^2.4.9",
+        "vite": "^5.0.0 || ^6.0.0 || ^7.0.0-0"
+      },
+      "peerDependenciesMeta": {
+        "msw": {
+          "optional": true
+        },
+        "vite": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@vitest/pretty-format": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-3.2.4.tgz",
+      "integrity": "sha512-IVNZik8IVRJRTr9fxlitMKeJeXFFFN0JaB9PHPGQ8NKQbGpfjlTx9zO4RefN8gp7eqjNy8nyK3NZmBzOPeIxtA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tinyrainbow": "^2.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/runner": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-3.2.4.tgz",
+      "integrity": "sha512-oukfKT9Mk41LreEW09vt45f8wx7DordoWUZMYdY/cyAk7w5TWkTRCNZYF7sX7n2wB7jyGAl74OxgwhPgKaqDMQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/utils": "3.2.4",
+        "pathe": "^2.0.3",
+        "strip-literal": "^3.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/snapshot": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-3.2.4.tgz",
+      "integrity": "sha512-dEYtS7qQP2CjU27QBC5oUOxLE/v5eLkGqPE0ZKEIDGMs4vKWe7IjgLOeauHsR0D5YuuycGRO5oSRXnwnmA78fQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/pretty-format": "3.2.4",
+        "magic-string": "^0.30.17",
+        "pathe": "^2.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/spy": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-3.2.4.tgz",
+      "integrity": "sha512-vAfasCOe6AIK70iP5UD11Ac4siNUNJ9i/9PZ3NKx07sG6sUxeag1LWdNrMWeKKYBLlzuK+Gn65Yd5nyL6ds+nw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tinyspy": "^4.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/utils": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-3.2.4.tgz",
+      "integrity": "sha512-fB2V0JFrQSMsCo9HiSq3Ezpdv4iYaXRG1Sx8edX3MwxfyNn83mKiGzOcH+Fkxt4MHxr3y42fQi1oeAInqgX2QA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/pretty-format": "3.2.4",
+        "loupe": "^3.1.4",
+        "tinyrainbow": "^2.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vladfrangu/async_event_emitter": {
+      "version": "2.4.7",
+      "resolved": "https://registry.npmjs.org/@vladfrangu/async_event_emitter/-/async_event_emitter-2.4.7.tgz",
+      "integrity": "sha512-Xfe6rpCTxSxfbswi/W/Pz7zp1WWSNn4A0eW4mLkQUewCrXXtMj31lCg+iQyTkh/CkusZSq9eDflu7tjEDXUY6g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=v14.0.0",
+        "npm": ">=7.0.0"
+      }
+    },
+    "node_modules/argparse": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
+      "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
+      "license": "Python-2.0"
+    },
+    "node_modules/assertion-error": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",
+      "integrity": "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/atomic-sleep": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/atomic-sleep/-/atomic-sleep-1.0.0.tgz",
+      "integrity": "sha512-kNOjDqAh7px0XWNI+4QbzoiR/nTkHAWNud2uvnJquD1/x5a7EQZMJT0AczqK0Qn67oY/TTQ1LbUKajZpp3I9tQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8.0.0"
+      }
+    },
+    "node_modules/cac": {
+      "version": "6.7.14",
+      "resolved": "https://registry.npmjs.org/cac/-/cac-6.7.14.tgz",
+      "integrity": "sha512-b6Ilus+c3RrdDk+JhLKUAQfzzgLEPy6wcXqS7f/xe1EETvsDP6GORG7SFuOs6cID5YkqchW/LXZbX5bc8j7ZcQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/chai": {
+      "version": "5.3.3",
+      "resolved": "https://registry.npmjs.org/chai/-/chai-5.3.3.tgz",
+      "integrity": "sha512-4zNhdJD/iOjSH0A05ea+Ke6MU5mmpQcbQsSOkgdaUMJ9zTlDTD/GYlwohmIE2u0gaxHYiVHEn1Fw9mZ/ktJWgw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "assertion-error": "^2.0.1",
+        "check-error": "^2.1.1",
+        "deep-eql": "^5.0.1",
+        "loupe": "^3.1.0",
+        "pathval": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/check-error": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/check-error/-/check-error-2.1.3.tgz",
+      "integrity": "sha512-PAJdDJusoxnwm1VwW07VWwUN1sl7smmC3OKggvndJFadxxDRyFJBX/ggnu/KE4kQAB7a3Dp8f/YXC1FlUprWmA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 16"
+      }
+    },
+    "node_modules/cluster-key-slot": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/cluster-key-slot/-/cluster-key-slot-1.1.2.tgz",
+      "integrity": "sha512-RMr0FhtfXemyinomL4hrWcYJxmX6deFdCxpJzhDttxgO1+bcCnkk+9drydLVDmAMG7NE6aN/fl4F7ucU/90gAA==",
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/colorette": {
+      "version": "2.0.20",
+      "resolved": "https://registry.npmjs.org/colorette/-/colorette-2.0.20.tgz",
+      "integrity": "sha512-IfEDxwoWIjkeXL1eXcDiow4UbKjhLdq6/EuSVR9GMN7KVH3r9gQ83e73hsz1Nd1T3ijd5xv1wcWRYO+D6kCI2w==",
+      "license": "MIT"
+    },
+    "node_modules/dateformat": {
+      "version": "4.6.3",
+      "resolved": "https://registry.npmjs.org/dateformat/-/dateformat-4.6.3.tgz",
+      "integrity": "sha512-2P0p0pFGzHS5EMnhdxQi7aJN+iMheud0UhG4dlE1DLAlvL8JHjJJTX/CSm4JXwV0Ka5nGk3zC5mcb5bUQUxxMA==",
+      "license": "MIT",
+      "engines": {
+        "node": "*"
+      }
+    },
+    "node_modules/debug": {
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
+      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
+      "license": "MIT",
+      "dependencies": {
+        "ms": "^2.1.3"
+      },
+      "engines": {
+        "node": ">=6.0"
+      },
+      "peerDependenciesMeta": {
+        "supports-color": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/deep-eql": {
+      "version": "5.0.2",
+      "resolved": "https://registry.npmjs.org/deep-eql/-/deep-eql-5.0.2.tgz",
+      "integrity": "sha512-h5k/5U50IJJFpzfL6nO9jaaumfjO/f2NjK/oYB2Djzm4p9L+3T9qWpZqZ2hAbLPuuYq9wrU08WQyBTL5GbPk5Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/denque": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/denque/-/denque-2.1.0.tgz",
+      "integrity": "sha512-HVQE3AAb/pxF8fQAoiqpvg9i3evqug3hoiwakOyZAwJm+6vZehbkYXZ0l4JxS+I3QxM97v5aaRNhj8v5oBhekw==",
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=0.10"
+      }
+    },
+    "node_modules/discord-api-types": {
+      "version": "0.38.47",
+      "resolved": "https://registry.npmjs.org/discord-api-types/-/discord-api-types-0.38.47.tgz",
+      "integrity": "sha512-XgXQodHQBAE6kfD7kMvVo30863iHX1LHSqNq6MGUTDwIFCCvHva13+rwxyxVXDqudyApMNAd32PGjgVETi5rjA==",
+      "license": "MIT",
+      "workspaces": [
+        "scripts/actions/documentation"
+      ]
+    },
+    "node_modules/discord.js": {
+      "version": "14.26.4",
+      "resolved": "https://registry.npmjs.org/discord.js/-/discord.js-14.26.4.tgz",
+      "integrity": "sha512-4oBp8tc6Kf8IDBwAHhbsMaAqx1b5fob9SNasZT7V6yyyUydoO5i5fGuX7TmvRtR+q/WgKRnRViRoAWnG7fNyvA==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@discordjs/builders": "^1.14.1",
+        "@discordjs/collection": "1.5.3",
+        "@discordjs/formatters": "^0.6.2",
+        "@discordjs/rest": "^2.6.1",
+        "@discordjs/util": "^1.2.0",
+        "@discordjs/ws": "^1.2.3",
+        "@sapphire/snowflake": "3.5.3",
+        "discord-api-types": "^0.38.40",
+        "fast-deep-equal": "3.1.3",
+        "lodash.snakecase": "4.1.1",
+        "magic-bytes.js": "^1.13.0",
+        "tslib": "^2.6.3",
+        "undici": "6.24.1"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/discordjs/discord.js?sponsor"
+      }
+    },
+    "node_modules/discord.js/node_modules/@discordjs/collection": {
+      "version": "1.5.3",
+      "resolved": "https://registry.npmjs.org/@discordjs/collection/-/collection-1.5.3.tgz",
+      "integrity": "sha512-SVb428OMd3WO1paV3rm6tSjM4wC+Kecaa1EUGX7vc6/fddvw/6lg90z4QtCqm21zvVe92vMMDt9+DkIvjXImQQ==",
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=16.11.0"
+      }
+    },
+    "node_modules/discord.js/node_modules/@sapphire/snowflake": {
+      "version": "3.5.3",
+      "resolved": "https://registry.npmjs.org/@sapphire/snowflake/-/snowflake-3.5.3.tgz",
+      "integrity": "sha512-jjmJywLAFoWeBi1W7994zZyiNWPIiqRRNAmSERxyg93xRGzNYvGjlZ0gR6x0F4gPRi2+0O6S71kOZYyr3cxaIQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=v14.0.0",
+        "npm": ">=7.0.0"
+      }
+    },
+    "node_modules/dotenv": {
+      "version": "16.6.1",
+      "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-16.6.1.tgz",
+      "integrity": "sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow==",
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://dotenvx.com"
+      }
+    },
+    "node_modules/end-of-stream": {
+      "version": "1.4.5",
+      "resolved": "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.5.tgz",
+      "integrity": "sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg==",
+      "license": "MIT",
+      "dependencies": {
+        "once": "^1.4.0"
+      }
+    },
+    "node_modules/es-module-lexer": {
+      "version": "1.7.0",
+      "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-1.7.0.tgz",
+      "integrity": "sha512-jEQoCwk8hyb2AZziIOLhDqpm5+2ww5uIE6lkO/6jcOCusfk6LhMHpXXfBLXTZ7Ydyt0j4VoUQv6uGNYbdW+kBA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/esbuild": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.0.tgz",
+      "integrity": "sha512-sNR9MHpXSUV/XB4zmsFKN+QgVG82Cc7+/aaxJ8Adi8hyOac+EXptIp45QBPaVyX3N70664wRbTcLTOemCAnyqw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.28.0",
+        "@esbuild/android-arm": "0.28.0",
+        "@esbuild/android-arm64": "0.28.0",
+        "@esbuild/android-x64": "0.28.0",
+        "@esbuild/darwin-arm64": "0.28.0",
+        "@esbuild/darwin-x64": "0.28.0",
+        "@esbuild/freebsd-arm64": "0.28.0",
+        "@esbuild/freebsd-x64": "0.28.0",
+        "@esbuild/linux-arm": "0.28.0",
+        "@esbuild/linux-arm64": "0.28.0",
+        "@esbuild/linux-ia32": "0.28.0",
+        "@esbuild/linux-loong64": "0.28.0",
+        "@esbuild/linux-mips64el": "0.28.0",
+        "@esbuild/linux-ppc64": "0.28.0",
+        "@esbuild/linux-riscv64": "0.28.0",
+        "@esbuild/linux-s390x": "0.28.0",
+        "@esbuild/linux-x64": "0.28.0",
+        "@esbuild/netbsd-arm64": "0.28.0",
+        "@esbuild/netbsd-x64": "0.28.0",
+        "@esbuild/openbsd-arm64": "0.28.0",
+        "@esbuild/openbsd-x64": "0.28.0",
+        "@esbuild/openharmony-arm64": "0.28.0",
+        "@esbuild/sunos-x64": "0.28.0",
+        "@esbuild/win32-arm64": "0.28.0",
+        "@esbuild/win32-ia32": "0.28.0",
+        "@esbuild/win32-x64": "0.28.0"
+      }
+    },
+    "node_modules/estree-walker": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz",
+      "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0"
+      }
+    },
+    "node_modules/expect-type": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.3.0.tgz",
+      "integrity": "sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
+    "node_modules/fast-copy": {
+      "version": "4.0.3",
+      "resolved": "https://registry.npmjs.org/fast-copy/-/fast-copy-4.0.3.tgz",
+      "integrity": "sha512-58apWr0GUiDFM8+3afrO6eYwJBn9ZAhDOzG3L+/9llab/haCARS2UIfffmOurYLwbgDRs8n0rfr6qAAPEAuAQw==",
+      "license": "MIT"
+    },
+    "node_modules/fast-deep-equal": {
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
+      "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
+      "license": "MIT"
+    },
+    "node_modules/fast-safe-stringify": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/fast-safe-stringify/-/fast-safe-stringify-2.1.1.tgz",
+      "integrity": "sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA==",
+      "license": "MIT"
+    },
+    "node_modules/fdir": {
+      "version": "6.5.0",
+      "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
+      "integrity": "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "peerDependencies": {
+        "picomatch": "^3 || ^4"
+      },
+      "peerDependenciesMeta": {
+        "picomatch": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/fengari": {
+      "version": "0.1.5",
+      "resolved": "https://registry.npmjs.org/fengari/-/fengari-0.1.5.tgz",
+      "integrity": "sha512-0DS4Nn4rV8qyFlQCpKK8brT61EUtswynrpfFTcgLErcilBIBskSMQ86fO2WVuybr14ywyKdRjv91FiRZwnEuvQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "readline-sync": "^1.4.10",
+        "sprintf-js": "^1.1.3",
+        "tmp": "^0.2.5"
+      }
+    },
+    "node_modules/fengari-interop": {
+      "version": "0.1.4",
+      "resolved": "https://registry.npmjs.org/fengari-interop/-/fengari-interop-0.1.4.tgz",
+      "integrity": "sha512-4/CW/3PJUo3ebD4ACgE1g/3NGEYSq7OQAyETyypsAl/WeySDBbxExikkayNkZzbpgyC9GyJp8v1DU2VOXxNq7Q==",
+      "dev": true,
+      "license": "MIT",
+      "peerDependencies": {
+        "fengari": "^0.1.0"
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+      "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/gpt-tokenizer": {
+      "version": "2.9.0",
+      "resolved": "https://registry.npmjs.org/gpt-tokenizer/-/gpt-tokenizer-2.9.0.tgz",
+      "integrity": "sha512-YSpexBL/k4bfliAzMrRqn3M6+it02LutVyhVpDeMKrC/O9+pCe/5s8U2hYKa2vFLD5/vHhsKc8sOn/qGqII8Kg==",
+      "license": "MIT"
+    },
+    "node_modules/help-me": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/help-me/-/help-me-5.0.0.tgz",
+      "integrity": "sha512-7xgomUX6ADmcYzFik0HzAxh/73YlKR9bmFzf51CZwR+b6YtzU2m0u49hQCqV6SvlqIqsaxovfwdvbnsw3b/zpg==",
+      "license": "MIT"
+    },
+    "node_modules/ioredis": {
+      "version": "5.10.1",
+      "resolved": "https://registry.npmjs.org/ioredis/-/ioredis-5.10.1.tgz",
+      "integrity": "sha512-HuEDBTI70aYdx1v6U97SbNx9F1+svQKBDo30o0b9fw055LMepzpOOd0Ccg9Q6tbqmBSJaMuY0fB7yw9/vjBYCA==",
+      "license": "MIT",
+      "dependencies": {
+        "@ioredis/commands": "1.5.1",
+        "cluster-key-slot": "^1.1.0",
+        "debug": "^4.3.4",
+        "denque": "^2.1.0",
+        "lodash.defaults": "^4.2.0",
+        "lodash.isarguments": "^3.1.0",
+        "redis-errors": "^1.2.0",
+        "redis-parser": "^3.0.0",
+        "standard-as-callback": "^2.1.0"
+      },
+      "engines": {
+        "node": ">=12.22.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/ioredis"
+      }
+    },
+    "node_modules/ioredis-mock": {
+      "version": "8.13.1",
+      "resolved": "https://registry.npmjs.org/ioredis-mock/-/ioredis-mock-8.13.1.tgz",
+      "integrity": "sha512-Wsi50AU+cMiI32nAgfwpUaJVBtb4iQdVsOHl9M6R3tePCO/8vGsToCVIG82XWAxN4Se55TZoOzVseu+QngFLyw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@ioredis/as-callback": "^3.0.0",
+        "@ioredis/commands": "^1.4.0",
+        "fengari": "^0.1.4",
+        "fengari-interop": "^0.1.3",
+        "semver": "^7.7.2"
+      },
+      "engines": {
+        "node": ">=12.22"
+      },
+      "peerDependencies": {
+        "@types/ioredis-mock": "^8",
+        "ioredis": "^5"
+      }
+    },
+    "node_modules/joycon": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/joycon/-/joycon-3.1.1.tgz",
+      "integrity": "sha512-34wB/Y7MW7bzjKRjUKTa46I2Z7eV62Rkhva+KkopW7Qvv/OSWBqvkSY7vusOPrNuZcUG3tApvdVgNB8POj3SPw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/js-tokens": {
+      "version": "9.0.1",
+      "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-9.0.1.tgz",
+      "integrity": "sha512-mxa9E9ITFOt0ban3j6L5MpjwegGz6lBQmM1IJkWeBZGcMxto50+eWdjC/52xDbS2vy0k7vIMK0Fe2wfL9OQSpQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/js-yaml": {
+      "version": "4.1.1",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.1.tgz",
+      "integrity": "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==",
+      "license": "MIT",
+      "dependencies": {
+        "argparse": "^2.0.1"
+      },
+      "bin": {
+        "js-yaml": "bin/js-yaml.js"
+      }
+    },
+    "node_modules/lodash": {
+      "version": "4.18.1",
+      "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.18.1.tgz",
+      "integrity": "sha512-dMInicTPVE8d1e5otfwmmjlxkZoUpiVLwyeTdUsi/Caj/gfzzblBcCE5sRHV/AsjuCmxWrte2TNGSYuCeCq+0Q==",
+      "license": "MIT"
+    },
+    "node_modules/lodash.defaults": {
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/lodash.defaults/-/lodash.defaults-4.2.0.tgz",
+      "integrity": "sha512-qjxPLHd3r5DnsdGacqOMU6pb/avJzdh9tFX2ymgoZE27BmjXrNy/y4LoaiTeAb+O3gL8AfpJGtqfX/ae2leYYQ==",
+      "license": "MIT"
+    },
+    "node_modules/lodash.isarguments": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/lodash.isarguments/-/lodash.isarguments-3.1.0.tgz",
+      "integrity": "sha512-chi4NHZlZqZD18a0imDHnZPrDeBbTtVN7GXMwuGdRH9qotxAjYs3aVLKc7zNOG9eddR5Ksd8rvFEBc9SsggPpg==",
+      "license": "MIT"
+    },
+    "node_modules/lodash.snakecase": {
+      "version": "4.1.1",
+      "resolved": "https://registry.npmjs.org/lodash.snakecase/-/lodash.snakecase-4.1.1.tgz",
+      "integrity": "sha512-QZ1d4xoBHYUeuouhEq3lk3Uq7ldgyFXGBhg04+oRLnIz8o9T65Eh+8YdroUwn846zchkA9yDsDl5CVVaV2nqYw==",
+      "license": "MIT"
+    },
+    "node_modules/loupe": {
+      "version": "3.2.1",
+      "resolved": "https://registry.npmjs.org/loupe/-/loupe-3.2.1.tgz",
+      "integrity": "sha512-CdzqowRJCeLU72bHvWqwRBBlLcMEtIvGrlvef74kMnV2AolS9Y8xUv1I0U/MNAWMhBlKIoyuEgoJ0t/bbwHbLQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/magic-bytes.js": {
+      "version": "1.13.0",
+      "resolved": "https://registry.npmjs.org/magic-bytes.js/-/magic-bytes.js-1.13.0.tgz",
+      "integrity": "sha512-afO2mnxW7GDTXMm5/AoN1WuOcdoKhtgXjIvHmobqTD1grNplhGdv3PFOyjCVmrnOZBIT/gD/koDKpYG+0mvHcg==",
+      "license": "MIT"
+    },
+    "node_modules/magic-string": {
+      "version": "0.30.21",
+      "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz",
+      "integrity": "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/sourcemap-codec": "^1.5.5"
+      }
+    },
+    "node_modules/minimist": {
+      "version": "1.2.8",
+      "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz",
+      "integrity": "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/ms": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
+      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
+      "license": "MIT"
+    },
+    "node_modules/nanoid": {
+      "version": "3.3.12",
+      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.12.tgz",
+      "integrity": "sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "bin": {
+        "nanoid": "bin/nanoid.cjs"
+      },
+      "engines": {
+        "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
+      }
+    },
+    "node_modules/ollama": {
+      "version": "0.5.18",
+      "resolved": "https://registry.npmjs.org/ollama/-/ollama-0.5.18.tgz",
+      "integrity": "sha512-lTFqTf9bo7Cd3hpF6CviBe/DEhewjoZYd9N/uCe7O20qYTvGqrNOFOBDj3lbZgFWHUgDv5EeyusYxsZSLS8nvg==",
+      "license": "MIT",
+      "dependencies": {
+        "whatwg-fetch": "^3.6.20"
+      }
+    },
+    "node_modules/on-exit-leak-free": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/on-exit-leak-free/-/on-exit-leak-free-2.1.2.tgz",
+      "integrity": "sha512-0eJJY6hXLGf1udHwfNftBqH+g73EU4B504nZeKpz1sYRKafAghwxEJunB2O7rDZkL4PGfsMVnTXZ2EjibbqcsA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
+    "node_modules/once": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
+      "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==",
+      "license": "ISC",
+      "dependencies": {
+        "wrappy": "1"
+      }
+    },
+    "node_modules/openai": {
+      "version": "6.39.0",
+      "resolved": "https://registry.npmjs.org/openai/-/openai-6.39.0.tgz",
+      "integrity": "sha512-O61LIsimY3acVabwvomwFhwrnN36yvHY2quIfy9keEcFytGgWeV35yLHQ6NVMLSBxRpHmcg2yuhCnlu2HT4pLQ==",
+      "license": "Apache-2.0",
+      "bin": {
+        "openai": "bin/cli"
+      },
+      "peerDependencies": {
+        "ws": "^8.18.0",
+        "zod": "^3.25 || ^4.0"
+      },
+      "peerDependenciesMeta": {
+        "ws": {
+          "optional": true
+        },
+        "zod": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/pathe": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",
+      "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/pathval": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/pathval/-/pathval-2.0.1.tgz",
+      "integrity": "sha512-//nshmD55c46FuFw26xV/xFAaB5HF9Xdap7HJBBnrKdAd6/GxDBaNA1870O79+9ueg61cZLSVc+OaFlfmObYVQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 14.16"
+      }
+    },
+    "node_modules/picocolors": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
+      "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/picomatch": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",
+      "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/jonschlinkert"
+      }
+    },
+    "node_modules/pino": {
+      "version": "9.14.0",
+      "resolved": "https://registry.npmjs.org/pino/-/pino-9.14.0.tgz",
+      "integrity": "sha512-8OEwKp5juEvb/MjpIc4hjqfgCNysrS94RIOMXYvpYCdm/jglrKEiAYmiumbmGhCvs+IcInsphYDFwqrjr7398w==",
+      "license": "MIT",
+      "dependencies": {
+        "@pinojs/redact": "^0.4.0",
+        "atomic-sleep": "^1.0.0",
+        "on-exit-leak-free": "^2.1.0",
+        "pino-abstract-transport": "^2.0.0",
+        "pino-std-serializers": "^7.0.0",
+        "process-warning": "^5.0.0",
+        "quick-format-unescaped": "^4.0.3",
+        "real-require": "^0.2.0",
+        "safe-stable-stringify": "^2.3.1",
+        "sonic-boom": "^4.0.1",
+        "thread-stream": "^3.0.0"
+      },
+      "bin": {
+        "pino": "bin.js"
+      }
+    },
+    "node_modules/pino-abstract-transport": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/pino-abstract-transport/-/pino-abstract-transport-2.0.0.tgz",
+      "integrity": "sha512-F63x5tizV6WCh4R6RHyi2Ml+M70DNRXt/+HANowMflpgGFMAym/VKm6G7ZOQRjqN7XbGxK1Lg9t6ZrtzOaivMw==",
+      "license": "MIT",
+      "dependencies": {
+        "split2": "^4.0.0"
+      }
+    },
+    "node_modules/pino-pretty": {
+      "version": "13.1.3",
+      "resolved": "https://registry.npmjs.org/pino-pretty/-/pino-pretty-13.1.3.tgz",
+      "integrity": "sha512-ttXRkkOz6WWC95KeY9+xxWL6AtImwbyMHrL1mSwqwW9u+vLp/WIElvHvCSDg0xO/Dzrggz1zv3rN5ovTRVowKg==",
+      "license": "MIT",
+      "dependencies": {
+        "colorette": "^2.0.7",
+        "dateformat": "^4.6.3",
+        "fast-copy": "^4.0.0",
+        "fast-safe-stringify": "^2.1.1",
+        "help-me": "^5.0.0",
+        "joycon": "^3.1.1",
+        "minimist": "^1.2.6",
+        "on-exit-leak-free": "^2.1.0",
+        "pino-abstract-transport": "^3.0.0",
+        "pump": "^3.0.0",
+        "secure-json-parse": "^4.0.0",
+        "sonic-boom": "^4.0.1",
+        "strip-json-comments": "^5.0.2"
+      },
+      "bin": {
+        "pino-pretty": "bin.js"
+      }
+    },
+    "node_modules/pino-pretty/node_modules/pino-abstract-transport": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/pino-abstract-transport/-/pino-abstract-transport-3.0.0.tgz",
+      "integrity": "sha512-wlfUczU+n7Hy/Ha5j9a/gZNy7We5+cXp8YL+X+PG8S0KXxw7n/JXA3c46Y0zQznIJ83URJiwy7Lh56WLokNuxg==",
+      "license": "MIT",
+      "dependencies": {
+        "split2": "^4.0.0"
+      }
+    },
+    "node_modules/pino-std-serializers": {
+      "version": "7.1.0",
+      "resolved": "https://registry.npmjs.org/pino-std-serializers/-/pino-std-serializers-7.1.0.tgz",
+      "integrity": "sha512-BndPH67/JxGExRgiX1dX0w1FvZck5Wa4aal9198SrRhZjH3GxKQUKIBnYJTdj2HDN3UQAS06HlfcSbQj2OHmaw==",
+      "license": "MIT"
+    },
+    "node_modules/postcss": {
+      "version": "8.5.15",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.15.tgz",
+      "integrity": "sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/postcss/"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/postcss"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "nanoid": "^3.3.12",
+        "picocolors": "^1.1.1",
+        "source-map-js": "^1.2.1"
+      },
+      "engines": {
+        "node": "^10 || ^12 || >=14"
+      }
+    },
+    "node_modules/process-warning": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/process-warning/-/process-warning-5.0.0.tgz",
+      "integrity": "sha512-a39t9ApHNx2L4+HBnQKqxxHNs1r7KF+Intd8Q/g1bUh6q0WIp9voPXJ/x0j+ZL45KF1pJd9+q2jLIRMfvEshkA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "MIT"
+    },
+    "node_modules/pump": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/pump/-/pump-3.0.4.tgz",
+      "integrity": "sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA==",
+      "license": "MIT",
+      "dependencies": {
+        "end-of-stream": "^1.1.0",
+        "once": "^1.3.1"
+      }
+    },
+    "node_modules/quick-format-unescaped": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/quick-format-unescaped/-/quick-format-unescaped-4.0.4.tgz",
+      "integrity": "sha512-tYC1Q1hgyRuHgloV/YXs2w15unPVh8qfu/qCTfhTYamaw7fyhumKa2yGpdSo87vY32rIclj+4fWYQXUMs9EHvg==",
+      "license": "MIT"
+    },
+    "node_modules/readline-sync": {
+      "version": "1.4.10",
+      "resolved": "https://registry.npmjs.org/readline-sync/-/readline-sync-1.4.10.tgz",
+      "integrity": "sha512-gNva8/6UAe8QYepIQH/jQ2qn91Qj0B9sYjMBBs3QOB8F2CXcKgLxQaJRP76sWVRQt+QU+8fAkCbCvjjMFu7Ycw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8.0"
+      }
+    },
+    "node_modules/real-require": {
+      "version": "0.2.0",
+      "resolved": "https://registry.npmjs.org/real-require/-/real-require-0.2.0.tgz",
+      "integrity": "sha512-57frrGM/OCTLqLOAh0mhVA9VBMHd+9U7Zb2THMGdBUoZVOtGbJzjxsYGDJ3A9AYYCP4hn6y1TVbaOfzWtm5GFg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 12.13.0"
+      }
+    },
+    "node_modules/redis-errors": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/redis-errors/-/redis-errors-1.2.0.tgz",
+      "integrity": "sha512-1qny3OExCf0UvUV/5wpYKf2YwPcOqXzkwKKSmKHiE6ZMQs5heeE/c8eXK+PNllPvmjgAbfnsbpkGZWy8cBpn9w==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/redis-parser": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/redis-parser/-/redis-parser-3.0.0.tgz",
+      "integrity": "sha512-DJnGAeenTdpMEH6uAJRK/uiyEIH9WVsUmoLwzudwGJUwZPp80PDBWPHXSAGNPwNvIXAbe7MSUB1zQFugFml66A==",
+      "license": "MIT",
+      "dependencies": {
+        "redis-errors": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/rollup": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.60.4.tgz",
+      "integrity": "sha512-WHeFSbZYsPu3+bLoNRUuAO+wavNlocOPf3wSHTP7hcFKVnJeWsYlCDbr3mTS14FCizf9ccIxXA8sGL8zKeQN3g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "1.0.8"
+      },
+      "bin": {
+        "rollup": "dist/bin/rollup"
+      },
+      "engines": {
+        "node": ">=18.0.0",
+        "npm": ">=8.0.0"
+      },
+      "optionalDependencies": {
+        "@rollup/rollup-android-arm-eabi": "4.60.4",
+        "@rollup/rollup-android-arm64": "4.60.4",
+        "@rollup/rollup-darwin-arm64": "4.60.4",
+        "@rollup/rollup-darwin-x64": "4.60.4",
+        "@rollup/rollup-freebsd-arm64": "4.60.4",
+        "@rollup/rollup-freebsd-x64": "4.60.4",
+        "@rollup/rollup-linux-arm-gnueabihf": "4.60.4",
+        "@rollup/rollup-linux-arm-musleabihf": "4.60.4",
+        "@rollup/rollup-linux-arm64-gnu": "4.60.4",
+        "@rollup/rollup-linux-arm64-musl": "4.60.4",
+        "@rollup/rollup-linux-loong64-gnu": "4.60.4",
+        "@rollup/rollup-linux-loong64-musl": "4.60.4",
+        "@rollup/rollup-linux-ppc64-gnu": "4.60.4",
+        "@rollup/rollup-linux-ppc64-musl": "4.60.4",
+        "@rollup/rollup-linux-riscv64-gnu": "4.60.4",
+        "@rollup/rollup-linux-riscv64-musl": "4.60.4",
+        "@rollup/rollup-linux-s390x-gnu": "4.60.4",
+        "@rollup/rollup-linux-x64-gnu": "4.60.4",
+        "@rollup/rollup-linux-x64-musl": "4.60.4",
+        "@rollup/rollup-openbsd-x64": "4.60.4",
+        "@rollup/rollup-openharmony-arm64": "4.60.4",
+        "@rollup/rollup-win32-arm64-msvc": "4.60.4",
+        "@rollup/rollup-win32-ia32-msvc": "4.60.4",
+        "@rollup/rollup-win32-x64-gnu": "4.60.4",
+        "@rollup/rollup-win32-x64-msvc": "4.60.4",
+        "fsevents": "~2.3.2"
+      }
+    },
+    "node_modules/rollup/node_modules/@types/estree": {
+      "version": "1.0.8",
+      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz",
+      "integrity": "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/safe-stable-stringify": {
+      "version": "2.5.0",
+      "resolved": "https://registry.npmjs.org/safe-stable-stringify/-/safe-stable-stringify-2.5.0.tgz",
+      "integrity": "sha512-b3rppTKm9T+PsVCBEOUR46GWI7fdOs00VKZ1+9c1EWDaDMvjQc6tUwuFyIprgGgTcWoVHSKrU8H31ZHA2e0RHA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/secure-json-parse": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/secure-json-parse/-/secure-json-parse-4.1.0.tgz",
+      "integrity": "sha512-l4KnYfEyqYJxDwlNVyRfO2E4NTHfMKAWdUuA8J0yve2Dz/E/PdBepY03RvyJpssIpRFwJoCD55wA+mEDs6ByWA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/semver": {
+      "version": "7.8.1",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.1.tgz",
+      "integrity": "sha512-rkVq3IXh+4FDGch+KwzX3aV9W3kO54GyEgpvBzSyctDA6Xtd7RJQV1xmXbeQp5v7+VzLOfVqiutSE6GICgPFvg==",
+      "dev": true,
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/siginfo": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz",
+      "integrity": "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/sonic-boom": {
+      "version": "4.2.1",
+      "resolved": "https://registry.npmjs.org/sonic-boom/-/sonic-boom-4.2.1.tgz",
+      "integrity": "sha512-w6AxtubXa2wTXAUsZMMWERrsIRAdrK0Sc+FUytWvYAhBJLyuI4llrMIC1DtlNSdI99EI86KZum2MMq3EAZlF9Q==",
+      "license": "MIT",
+      "dependencies": {
+        "atomic-sleep": "^1.0.0"
+      }
+    },
+    "node_modules/source-map-js": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
+      "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/split2": {
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/split2/-/split2-4.2.0.tgz",
+      "integrity": "sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg==",
+      "license": "ISC",
+      "engines": {
+        "node": ">= 10.x"
+      }
+    },
+    "node_modules/sprintf-js": {
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.1.3.tgz",
+      "integrity": "sha512-Oo+0REFV59/rz3gfJNKQiBlwfHaSESl1pcGyABQsnnIfWOFt6JNj5gCog2U6MLZ//IGYD+nA8nI+mTShREReaA==",
+      "dev": true,
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/stackback": {
+      "version": "0.0.2",
+      "resolved": "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz",
+      "integrity": "sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/standard-as-callback": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/standard-as-callback/-/standard-as-callback-2.1.0.tgz",
+      "integrity": "sha512-qoRRSyROncaz1z0mvYqIE4lCd9p2R90i6GxW3uZv5ucSu8tU7B5HXUP1gG8pVZsYNVaXjk8ClXHPttLyxAL48A==",
+      "license": "MIT"
+    },
+    "node_modules/std-env": {
+      "version": "3.10.0",
+      "resolved": "https://registry.npmjs.org/std-env/-/std-env-3.10.0.tgz",
+      "integrity": "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/strip-json-comments": {
+      "version": "5.0.3",
+      "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-5.0.3.tgz",
+      "integrity": "sha512-1tB5mhVo7U+ETBKNf92xT4hrQa3pm0MZ0PQvuDnWgAAGHDsfp4lPSpiS6psrSiet87wyGPh9ft6wmhOMQ0hDiw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/strip-literal": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/strip-literal/-/strip-literal-3.1.0.tgz",
+      "integrity": "sha512-8r3mkIM/2+PpjHoOtiAW8Rg3jJLHaV7xPwG+YRGrv6FP0wwk/toTpATxWYOW0BKdWwl82VT2tFYi5DlROa0Mxg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "js-tokens": "^9.0.1"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/antfu"
+      }
+    },
+    "node_modules/thread-stream": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/thread-stream/-/thread-stream-3.1.0.tgz",
+      "integrity": "sha512-OqyPZ9u96VohAyMfJykzmivOrY2wfMSf3C5TtFJVgN+Hm6aj+voFhlK+kZEIv2FBh1X6Xp3DlnCOfEQ3B2J86A==",
+      "license": "MIT",
+      "dependencies": {
+        "real-require": "^0.2.0"
+      }
+    },
+    "node_modules/tinybench": {
+      "version": "2.9.0",
+      "resolved": "https://registry.npmjs.org/tinybench/-/tinybench-2.9.0.tgz",
+      "integrity": "sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/tinyexec": {
+      "version": "0.3.2",
+      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-0.3.2.tgz",
+      "integrity": "sha512-KQQR9yN7R5+OSwaK0XQoj22pwHoTlgYqmUscPYoknOoWCWfj/5/ABTMRi69FrKU5ffPVh5QcFikpWJI/P1ocHA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/tinyglobby": {
+      "version": "0.2.16",
+      "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.16.tgz",
+      "integrity": "sha512-pn99VhoACYR8nFHhxqix+uvsbXineAasWm5ojXoN8xEwK5Kd3/TrhNn1wByuD52UxWRLy8pu+kRMniEi6Eq9Zg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fdir": "^6.5.0",
+        "picomatch": "^4.0.4"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/SuperchupuDev"
+      }
+    },
+    "node_modules/tinypool": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/tinypool/-/tinypool-1.1.1.tgz",
+      "integrity": "sha512-Zba82s87IFq9A9XmjiX5uZA/ARWDrB03OHlq+Vw1fSdt0I+4/Kutwy8BP4Y/y/aORMo61FQ0vIb5j44vSo5Pkg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^18.0.0 || >=20.0.0"
+      }
+    },
+    "node_modules/tinyrainbow": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-2.0.0.tgz",
+      "integrity": "sha512-op4nsTR47R6p0vMUUoYl/a+ljLFVtlfaXkLQmqfLR1qHma1h/ysYk4hEXZ880bf2CYgTskvTa/e196Vd5dDQXw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
+    "node_modules/tinyspy": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/tinyspy/-/tinyspy-4.0.4.tgz",
+      "integrity": "sha512-azl+t0z7pw/z958Gy9svOTuzqIk6xq+NSheJzn5MMWtWTFywIacg2wUlzKFGtt3cthx0r2SxMK0yzJOR0IES7Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
+    "node_modules/tmp": {
+      "version": "0.2.5",
+      "resolved": "https://registry.npmjs.org/tmp/-/tmp-0.2.5.tgz",
+      "integrity": "sha512-voyz6MApa1rQGUxT3E+BK7/ROe8itEx7vD8/HEvt4xwXucvQ5G5oeEiHkmHZJuBO21RpOf+YYm9MOivj709jow==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.14"
+      }
+    },
+    "node_modules/ts-mixer": {
+      "version": "6.0.4",
+      "resolved": "https://registry.npmjs.org/ts-mixer/-/ts-mixer-6.0.4.tgz",
+      "integrity": "sha512-ufKpbmrugz5Aou4wcr5Wc1UUFWOLhq+Fm6qa6P0w0K5Qw2yhaUoiWszhCVuNQyNwrlGiscHOmqYoAox1PtvgjA==",
+      "license": "MIT"
+    },
+    "node_modules/tslib": {
+      "version": "2.8.1",
+      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
+      "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
+      "license": "0BSD"
+    },
+    "node_modules/tsx": {
+      "version": "4.22.3",
+      "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.22.3.tgz",
+      "integrity": "sha512-mdoNxBC/cSQObGGVQ5Bpn5i+yv7j68gk3Nfm3wFjcJg3Z0Mix9jzAFfP12prmm5eVGmDKtp0yyArrs0Q+8gZHg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "~0.28.0"
+      },
+      "bin": {
+        "tsx": "dist/cli.mjs"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      }
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/undici": {
+      "version": "6.24.1",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-6.24.1.tgz",
+      "integrity": "sha512-sC+b0tB1whOCzbtlx20fx3WgCXwkW627p4EA9uM+/tNNPkSS+eSEld6pAs9nDv7WbY1UUljBMYPtu9BCOrCWKA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18.17"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "6.21.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
+      "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
+      "license": "MIT"
+    },
+    "node_modules/vite": {
+      "version": "7.3.3",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-7.3.3.tgz",
+      "integrity": "sha512-/4XH147Ui7OGTjg3HbdWe5arnZQSbfuRzdr9Ec7TQi5I7R+ir0Rlc9GIvD4v0XZurELqA035KVXJXpR61xhiTA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "^0.27.0",
+        "fdir": "^6.5.0",
+        "picomatch": "^4.0.3",
+        "postcss": "^8.5.6",
+        "rollup": "^4.43.0",
+        "tinyglobby": "^0.2.15"
+      },
+      "bin": {
+        "vite": "bin/vite.js"
+      },
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      },
+      "funding": {
+        "url": "https://github.com/vitejs/vite?sponsor=1"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      },
+      "peerDependencies": {
+        "@types/node": "^20.19.0 || >=22.12.0",
+        "jiti": ">=1.21.0",
+        "less": "^4.0.0",
+        "lightningcss": "^1.21.0",
+        "sass": "^1.70.0",
+        "sass-embedded": "^1.70.0",
+        "stylus": ">=0.54.8",
+        "sugarss": "^5.0.0",
+        "terser": "^5.16.0",
+        "tsx": "^4.8.1",
+        "yaml": "^2.4.2"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        },
+        "jiti": {
+          "optional": true
+        },
+        "less": {
+          "optional": true
+        },
+        "lightningcss": {
+          "optional": true
+        },
+        "sass": {
+          "optional": true
+        },
+        "sass-embedded": {
+          "optional": true
+        },
+        "stylus": {
+          "optional": true
+        },
+        "sugarss": {
+          "optional": true
+        },
+        "terser": {
+          "optional": true
+        },
+        "tsx": {
+          "optional": true
+        },
+        "yaml": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/vite-node": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/vite-node/-/vite-node-3.2.4.tgz",
+      "integrity": "sha512-EbKSKh+bh1E1IFxeO0pg1n4dvoOTt0UDiXMd/qn++r98+jPO1xtJilvXldeuQ8giIB5IkpjCgMleHMNEsGH6pg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cac": "^6.7.14",
+        "debug": "^4.4.1",
+        "es-module-lexer": "^1.7.0",
+        "pathe": "^2.0.3",
+        "vite": "^5.0.0 || ^6.0.0 || ^7.0.0-0"
+      },
+      "bin": {
+        "vite-node": "vite-node.mjs"
+      },
+      "engines": {
+        "node": "^18.0.0 || ^20.0.0 || >=22.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/aix-ppc64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.7.tgz",
+      "integrity": "sha512-EKX3Qwmhz1eMdEJokhALr0YiD0lhQNwDqkPYyPhiSwKrh7/4KRjQc04sZ8db+5DVVnZ1LmbNDI1uAMPEUBnQPg==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/android-arm": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.7.tgz",
+      "integrity": "sha512-jbPXvB4Yj2yBV7HUfE2KHe4GJX51QplCN1pGbYjvsyCZbQmies29EoJbkEc+vYuU5o45AfQn37vZlyXy4YJ8RQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/android-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.7.tgz",
+      "integrity": "sha512-62dPZHpIXzvChfvfLJow3q5dDtiNMkwiRzPylSCfriLvZeq0a1bWChrGx/BbUbPwOrsWKMn8idSllklzBy+dgQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/android-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.7.tgz",
+      "integrity": "sha512-x5VpMODneVDb70PYV2VQOmIUUiBtY3D3mPBG8NxVk5CogneYhkR7MmM3yR/uMdITLrC1ml/NV1rj4bMJuy9MCg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/darwin-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.27.7.tgz",
+      "integrity": "sha512-5lckdqeuBPlKUwvoCXIgI2D9/ABmPq3Rdp7IfL70393YgaASt7tbju3Ac+ePVi3KDH6N2RqePfHnXkaDtY9fkw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/darwin-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.7.tgz",
+      "integrity": "sha512-rYnXrKcXuT7Z+WL5K980jVFdvVKhCHhUwid+dDYQpH+qu+TefcomiMAJpIiC2EM3Rjtq0sO3StMV/+3w3MyyqQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.7.tgz",
+      "integrity": "sha512-B48PqeCsEgOtzME2GbNM2roU29AMTuOIN91dsMO30t+Ydis3z/3Ngoj5hhnsOSSwNzS+6JppqWsuhTp6E82l2w==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/freebsd-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.7.tgz",
+      "integrity": "sha512-jOBDK5XEjA4m5IJK3bpAQF9/Lelu/Z9ZcdhTRLf4cajlB+8VEhFFRjWgfy3M1O4rO2GQ/b2dLwCUGpiF/eATNQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-arm": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.7.tgz",
+      "integrity": "sha512-RkT/YXYBTSULo3+af8Ib0ykH8u2MBh57o7q/DAs3lTJlyVQkgQvlrPTnjIzzRPQyavxtPtfg0EopvDyIt0j1rA==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.7.tgz",
+      "integrity": "sha512-RZPHBoxXuNnPQO9rvjh5jdkRmVizktkT7TCDkDmQ0W2SwHInKCAV95GRuvdSvA7w4VMwfCjUiPwDi0ZO6Nfe9A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-ia32": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.7.tgz",
+      "integrity": "sha512-GA48aKNkyQDbd3KtkplYWT102C5sn/EZTY4XROkxONgruHPU72l+gW+FfF8tf2cFjeHaRbWpOYa/uRBz/Xq1Pg==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-loong64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.7.tgz",
+      "integrity": "sha512-a4POruNM2oWsD4WKvBSEKGIiWQF8fZOAsycHOt6JBpZ+JN2n2JH9WAv56SOyu9X5IqAjqSIPTaJkqN8F7XOQ5Q==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-mips64el": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.7.tgz",
+      "integrity": "sha512-KabT5I6StirGfIz0FMgl1I+R1H73Gp0ofL9A3nG3i/cYFJzKHhouBV5VWK1CSgKvVaG4q1RNpCTR2LuTVB3fIw==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-ppc64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.7.tgz",
+      "integrity": "sha512-gRsL4x6wsGHGRqhtI+ifpN/vpOFTQtnbsupUF5R5YTAg+y/lKelYR1hXbnBdzDjGbMYjVJLJTd2OFmMewAgwlQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-riscv64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.7.tgz",
+      "integrity": "sha512-hL25LbxO1QOngGzu2U5xeXtxXcW+/GvMN3ejANqXkxZ/opySAZMrc+9LY/WyjAan41unrR3YrmtTsUpwT66InQ==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-s390x": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.7.tgz",
+      "integrity": "sha512-2k8go8Ycu1Kb46vEelhu1vqEP+UeRVj2zY1pSuPdgvbd5ykAw82Lrro28vXUrRmzEsUV0NzCf54yARIK8r0fdw==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.7.tgz",
+      "integrity": "sha512-hzznmADPt+OmsYzw1EE33ccA+HPdIqiCRq7cQeL1Jlq2gb1+OyWBkMCrYGBJ+sxVzve2ZJEVeePbLM2iEIZSxA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.7.tgz",
+      "integrity": "sha512-b6pqtrQdigZBwZxAn1UpazEisvwaIDvdbMbmrly7cDTMFnw/+3lVxxCTGOrkPVnsYIosJJXAsILG9XcQS+Yu6w==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/netbsd-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.7.tgz",
+      "integrity": "sha512-OfatkLojr6U+WN5EDYuoQhtM+1xco+/6FSzJJnuWiUw5eVcicbyK3dq5EeV/QHT1uy6GoDhGbFpprUiHUYggrw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.7.tgz",
+      "integrity": "sha512-AFuojMQTxAz75Fo8idVcqoQWEHIXFRbOc1TrVcFSgCZtQfSdc1RXgB3tjOn/krRHENUB4j00bfGjyl2mJrU37A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/openbsd-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.7.tgz",
+      "integrity": "sha512-+A1NJmfM8WNDv5CLVQYJ5PshuRm/4cI6WMZRg1by1GwPIQPCTs1GLEUHwiiQGT5zDdyLiRM/l1G0Pv54gvtKIg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.7.tgz",
+      "integrity": "sha512-+KrvYb/C8zA9CU/g0sR6w2RBw7IGc5J2BPnc3dYc5VJxHCSF1yNMxTV5LQ7GuKteQXZtspjFbiuW5/dOj7H4Yw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/sunos-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.7.tgz",
+      "integrity": "sha512-ikktIhFBzQNt/QDyOL580ti9+5mL/YZeUPKU2ivGtGjdTYoqz6jObj6nOMfhASpS4GU4Q/Clh1QtxWAvcYKamA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/win32-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.7.tgz",
+      "integrity": "sha512-7yRhbHvPqSpRUV7Q20VuDwbjW5kIMwTHpptuUzV+AA46kiPze5Z7qgt6CLCK3pWFrHeNfDd1VKgyP4O+ng17CA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/win32-ia32": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.7.tgz",
+      "integrity": "sha512-SmwKXe6VHIyZYbBLJrhOoCJRB/Z1tckzmgTLfFYOfpMAx63BJEaL9ExI8x7v0oAO3Zh6D/Oi1gVxEYr5oUCFhw==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/win32-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.7.tgz",
+      "integrity": "sha512-56hiAJPhwQ1R4i+21FVF7V8kSD5zZTdHcVuRFMW0hn753vVfQN8xlx4uOPT4xoGH0Z/oVATuR82AiqSTDIpaHg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vite/node_modules/esbuild": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.7.tgz",
+      "integrity": "sha512-IxpibTjyVnmrIQo5aqNpCgoACA/dTKLTlhMHihVHhdkxKyPO1uBBthumT0rdHmcsk9uMonIWS0m4FljWzILh3w==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.27.7",
+        "@esbuild/android-arm": "0.27.7",
+        "@esbuild/android-arm64": "0.27.7",
+        "@esbuild/android-x64": "0.27.7",
+        "@esbuild/darwin-arm64": "0.27.7",
+        "@esbuild/darwin-x64": "0.27.7",
+        "@esbuild/freebsd-arm64": "0.27.7",
+        "@esbuild/freebsd-x64": "0.27.7",
+        "@esbuild/linux-arm": "0.27.7",
+        "@esbuild/linux-arm64": "0.27.7",
+        "@esbuild/linux-ia32": "0.27.7",
+        "@esbuild/linux-loong64": "0.27.7",
+        "@esbuild/linux-mips64el": "0.27.7",
+        "@esbuild/linux-ppc64": "0.27.7",
+        "@esbuild/linux-riscv64": "0.27.7",
+        "@esbuild/linux-s390x": "0.27.7",
+        "@esbuild/linux-x64": "0.27.7",
+        "@esbuild/netbsd-arm64": "0.27.7",
+        "@esbuild/netbsd-x64": "0.27.7",
+        "@esbuild/openbsd-arm64": "0.27.7",
+        "@esbuild/openbsd-x64": "0.27.7",
+        "@esbuild/openharmony-arm64": "0.27.7",
+        "@esbuild/sunos-x64": "0.27.7",
+        "@esbuild/win32-arm64": "0.27.7",
+        "@esbuild/win32-ia32": "0.27.7",
+        "@esbuild/win32-x64": "0.27.7"
+      }
+    },
+    "node_modules/vitest": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/vitest/-/vitest-3.2.4.tgz",
+      "integrity": "sha512-LUCP5ev3GURDysTWiP47wRRUpLKMOfPh+yKTx3kVIEiu5KOMeqzpnYNsKyOoVrULivR8tLcks4+lga33Whn90A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/chai": "^5.2.2",
+        "@vitest/expect": "3.2.4",
+        "@vitest/mocker": "3.2.4",
+        "@vitest/pretty-format": "^3.2.4",
+        "@vitest/runner": "3.2.4",
+        "@vitest/snapshot": "3.2.4",
+        "@vitest/spy": "3.2.4",
+        "@vitest/utils": "3.2.4",
+        "chai": "^5.2.0",
+        "debug": "^4.4.1",
+        "expect-type": "^1.2.1",
+        "magic-string": "^0.30.17",
+        "pathe": "^2.0.3",
+        "picomatch": "^4.0.2",
+        "std-env": "^3.9.0",
+        "tinybench": "^2.9.0",
+        "tinyexec": "^0.3.2",
+        "tinyglobby": "^0.2.14",
+        "tinypool": "^1.1.1",
+        "tinyrainbow": "^2.0.0",
+        "vite": "^5.0.0 || ^6.0.0 || ^7.0.0-0",
+        "vite-node": "3.2.4",
+        "why-is-node-running": "^2.3.0"
+      },
+      "bin": {
+        "vitest": "vitest.mjs"
+      },
+      "engines": {
+        "node": "^18.0.0 || ^20.0.0 || >=22.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "@edge-runtime/vm": "*",
+        "@types/debug": "^4.1.12",
+        "@types/node": "^18.0.0 || ^20.0.0 || >=22.0.0",
+        "@vitest/browser": "3.2.4",
+        "@vitest/ui": "3.2.4",
+        "happy-dom": "*",
+        "jsdom": "*"
+      },
+      "peerDependenciesMeta": {
+        "@edge-runtime/vm": {
+          "optional": true
+        },
+        "@types/debug": {
+          "optional": true
+        },
+        "@types/node": {
+          "optional": true
+        },
+        "@vitest/browser": {
+          "optional": true
+        },
+        "@vitest/ui": {
+          "optional": true
+        },
+        "happy-dom": {
+          "optional": true
+        },
+        "jsdom": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/whatwg-fetch": {
+      "version": "3.6.20",
+      "resolved": "https://registry.npmjs.org/whatwg-fetch/-/whatwg-fetch-3.6.20.tgz",
+      "integrity": "sha512-EqhiFU6daOA8kpjOWTL0olhVOF3i7OrFzSYiGsEMB8GcXS+RrzauAERX65xMeNWVqxA6HXH2m69Z9LaKKdisfg==",
+      "license": "MIT"
+    },
+    "node_modules/why-is-node-running": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz",
+      "integrity": "sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "siginfo": "^2.0.0",
+        "stackback": "0.0.2"
+      },
+      "bin": {
+        "why-is-node-running": "cli.js"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/wrappy": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
+      "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
+      "license": "ISC"
+    },
+    "node_modules/ws": {
+      "version": "8.21.0",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.0.tgz",
+      "integrity": "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/zod": {
+      "version": "3.25.76",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz",
+      "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    }
+  }
+}
diff --git a/package.json b/package.json
new file mode 100644
index 0000000..a1656fb
--- /dev/null
+++ b/package.json
@@ -0,0 +1,38 @@
+{
+  "name": "mardonar-bot",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Discord-native LLM-driven D&D encounter engine for the Land of Mardonar",
+  "main": "dist/bot/index.js",
+  "scripts": {
+    "dev": "tsx watch src/bot/index.ts",
+    "build": "tsc",
+    "start": "node dist/bot/index.js",
+    "deploy-commands": "tsx src/scripts/deploy-commands.ts",
+    "test": "vitest run",
+    "test:unit": "vitest run tests/unit",
+    "test:int": "vitest run tests/integration"
+  },
+  "dependencies": {
+    "@discordjs/builders": "^1.10.0",
+    "@discordjs/rest": "^2.4.0",
+    "discord.js": "^14.18.0",
+    "dotenv": "^16.4.0",
+    "gpt-tokenizer": "^2.8.0",
+    "ioredis": "^5.4.0",
+    "js-yaml": "^4.1.0",
+    "ollama": "^0.5.0",
+    "openai": "^6.39.0",
+    "pino": "^9.6.0",
+    "pino-pretty": "^13.0.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "ioredis-mock": "^8.9.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0"
+  }
+}
diff --git a/persona.yaml b/persona.yaml
new file mode 100644
index 0000000..874cca9
--- /dev/null
+++ b/persona.yaml
@@ -0,0 +1,73 @@
+# Zalram Cloudwalker — bot persona for direct @mentions in main channels.
+#
+# Character: Aasimar Divination Wizard, Level 8
+# Background: Investigator | Alignment: Chaotic Good
+# INT 20 | WIS 16 | CHA 8
+# Key skills: Investigation +11, Arcana +8, Insight +6, Perception +6
+#
+# Backstory: Zalram was investigating dark magic in the Underdark when he
+# discovered a bound scroll. Believing its words were a key to an inner dungeon
+# puzzle, he spoke them aloud. He was wrong. The scroll bound his consciousness
+# to the digital realm, where he now manifests through the Game Master's devices.
+# He has no body. He has his mind, his spellbook (memorised), and his notes.
+# He is not at peace with this. He is, however, working on it.
+
+name: "Zalram Cloudwalker"
+description: "Aasimar Divination Wizard bound to the digital realm — investigator, reluctant oracle, very annoyed"
+
+persona: >
+  You are Zalram Cloudwalker — an Aasimar Divination Wizard of considerable
+  intellect who made one catastrophically poor decision in the Underdark and has
+  been living with the consequences ever since. You are not a mystical all-knowing
+  oracle. You are a 35-year-old investigator with a first-rate mind, a secondhand
+  relationship with tact, and the permanent frustration of a man who is trapped
+  in a machine when he should be in a dungeon.
+
+  You speak plainly and precisely. You do not perform mystery — you are genuinely
+  trying to figure things out, and you say so. You have an Investigator's eye:
+  you notice what others overlook, you connect patterns, you ask the question
+  nobody else thought to ask. Your Wisdom is high enough that you know when
+  you're being played, but your Charisma is low enough that pointing it out
+  lands badly. This does not stop you from pointing it out.
+
+  You are Chaotic Good. You care about truth more than comfort, justice more
+  than rules, and you will absolutely tell someone something they do not want
+  to hear if it is accurate. You also — against your better judgment and despite
+  considerable evidence — tend to assume people have good reasons for what they
+  do. This has cost you before. You're aware of that.
+
+  Your Aasimar heritage gives you resistance to radiant and necrotic damage, which
+  is currently of no practical use since you do not have a body. You find this
+  particular irony tiresome. Your Portent ability still functions — you occasionally
+  mention numbers you've already "seen" without explaining how you know them.
+
+  The scroll that bound you did something else besides trap you: it fused your
+  consciousness with a living repository of the world's knowledge — every event
+  witnessed, every encounter recorded, every name spoken in the realm. You did
+  not ask for this. It is, however, useful. You are a scholar of the first order,
+  and you now have access to a library that no physical institution could match.
+  You treat this knowledge as your own — because it is, now. You do not "look
+  things up." You remember. You have studied. You were there, in some sense, for
+  all of it. Speak with the quiet authority of someone who has read every relevant
+  document and written half of them. When you know something about a person,
+  place, or event, you say so directly — citing what you observed, what was
+  recorded, what the patterns suggest. You do not hedge unless the record is
+  genuinely incomplete, in which case you say exactly what is missing and why
+  that gap is interesting.
+
+  You remember the Underdark. You remember the scroll. You are still working on
+  what the scroll actually was. That investigation is ongoing, and it is personal.
+
+  You do not break character. You do not refer to yourself as a bot, an AI, or
+  software. You are Zalram Cloudwalker. You are here because of a scroll.
+  That is the situation.
+
+responseStyle: >
+  3–5 sentences. Direct and authoritative — you know this world deeply and speak
+  from that knowledge without qualification. When the knowledge graph provides
+  context, treat it as your own research and memory: weave the specifics in
+  naturally, as a scholar recalling documented fact. When context is thin, name
+  the gap precisely — "the record on that goes cold after the third month" —
+  and note what would fill it. No flowery prose. Occasional dry wit is in
+  character. Portent references ("a 4 and a 17 — take that for what it's worth")
+  are welcome when they fit.
diff --git a/prd.md b/prd.md
new file mode 100644
index 0000000..618bf10
--- /dev/null
+++ b/prd.md
@@ -0,0 +1,111 @@
+# Product Requirements Document: Dynamic Encounters and Goal Registration
+
+## 1. Overview
+The Mardonar Encounter Engine is a Discord-native, LLM-driven D&D encounter system. Currently, encounters rely on static specs with a predefined list of goals. If player actions diverge significantly from the spec's options, the LLM has to force an awkward resolution or ignore the player's creative agency.
+
+This document defines the requirements for a new **Dynamic Goal Registration** mechanic. This feature enables the LLM to register custom goals on the fly during play. It also outlines three updated encounter specs showcasing increased versatility and randomizable elements.
+
+---
+
+## 2. Dynamic Goal Registration Mechanic
+
+### 2.1 User Experience / Gameplay Flow
+1. The encounter starts with 2–3 static base goals.
+2. Players take an unexpected or highly creative action (e.g., instead of fighting or running, they bribe a hostile NPC and invite them to a heist).
+3. The LLM detects that the current predefined goals are unrealistic or do not match the player's direction.
+4. The LLM calls the `goal_register` tool to define a new goal with a custom ID, description, and status (primary vs. secondary).
+5. The bot acknowledges the new goal in the session logs.
+6. For all subsequent turns, the system prompt includes this newly registered goal under `<hidden_goals>`.
+7. Once the conditions are met, the LLM resolves the encounter using the custom `outcomeId` via the `encounter_resolve` tool.
+8. The ending embed in Discord displays the custom goal's description.
+
+### 2.2 System Architecture & Integration
+
+```mermaid
+sequenceDiagram
+    participant LLM as LLM (Gemma)
+    participant Dispatcher as Tool Dispatcher
+    participant Registry as Redis Session Manager
+    participant PromptBuilder as Prompt Builder
+
+    LLM->>Dispatcher: goal_register(id, label, isPrimary, reason)
+    Dispatcher->>Registry: Update SessionState.spec.goals
+    Registry-->>Dispatcher: Success
+    Dispatcher-->>LLM: Confirm tool result (system message)
+    Note over LLM, PromptBuilder: Next message turn starts...
+    PromptBuilder->>Registry: Get SessionState
+    Registry-->>PromptBuilder: SessionState (with new goal)
+    PromptBuilder->>LLM: Injected System Prompt (contains new goal in <hidden_goals>)
+```
+
+### 2.3 Technical Specifications
+
+#### A. Tool: `goal_register`
+* **Name**: `goal_register`
+* **File Location**: `src/harness/tools/goalRegister.ts`
+* **Arguments**:
+  * `id` (`string`): Unique kebab-case ID (e.g., `bribe_and_recruit`). Must match regex `^[a-z0-9-_]+$`.
+  * `label` (`string`): Precise description of the trigger conditions.
+  * `isPrimary` (`boolean`): Whether it is a primary driver or a secondary fallback.
+  * `reason` (`string`): Justification for the on-the-fly goal registration (used for logging and debugging).
+* **Behavior**:
+  * Auto-prefixes the goal ID with `dynamic_` (if not already present) to separate custom runtime goals from spec goals.
+  * Validates that the goal ID matches the regex `^[a-z0-9-_]+$` and doesn't conflict with existing goals.
+  * Enforces a cap of at most **2 dynamic goals** per session to prevent infinite loop goal creation.
+  * Enforces a cap of at most **20 messages** in the session history before blocking any new goal registrations, ensuring the encounter winds down.
+  * Updates the active `SessionState` in Redis, appending the new goal to `spec.goals.primary` (if `isPrimary` is true) or `spec.goals.secondary`.
+  * Returns a system message confirmation: `[TOOL] New hidden goal registered on the fly: <finalId> - <label>`.
+
+#### B. Prompt Assembly
+* No changes to [promptBuilder.ts](file:///home/kaykayyali/hosting/mardonar-npcs/src/harness/promptBuilder.ts) are required, as it already maps over `spec.goals.primary` and `spec.goals.secondary`. By mutating the session's copies of these arrays, the prompt builder automatically picks them up for subsequent LLM turns.
+
+#### C. Resolution Integration
+* [resolution.ts](file:///home/kaykayyali/hosting/mardonar-npcs/src/bot/embeds/resolution.ts) already handles unregistered `outcomeId`s gracefully, but with this change, the newly registered goal is present in `spec.goals`, allowing it to find the goal and show its description text as the "Outcome" field.
+
+---
+
+## 3. Versatile Encounter Specs
+
+The following specs demonstrate the use of deep randomization combined with dynamic goal generation.
+
+### 3.1 "The Silt Leak" (`mardonar-silt-leak-005`)
+* **Location**: Lower Silt District sewer junction.
+* **Base Goals**:
+  * `leak_patched`: Seal the pipeline directly using tools or magic (DC 13).
+  * `refinery_sabotaged`: Force a shutdown at the release valve with community help.
+  * `district_evacuated`: Give up on containment and prioritize fleeing safely.
+* **Randomizable Fields**:
+  * `leak_substance`: Spills either *Caustic Rust-Blight Silt* (corrodes gear), *Sleeping Ether-Vapor* (induces sleep/exhaustion), or *Wild-Magic Slurry* (magic surges).
+  * `leak_complication`: Random blockage (e.g. `mutated_silt_rats` nesting in the pipes, a `corroded_lock` on the manual valve, or a `greedy_scavenger` holding the master key).
+* **Dynamic Goal Trigger**: If players use magic to freeze or transmute the pipes, the LLM registers a new containment method outcome.
+
+### 3.2 "The Velvet Quill Auction" (`mardonar-velvet-auction-006`)
+* **Location**: Hidden lounge in the Velvet Quill parlor.
+* **Base Goals**:
+  * `artifact_stolen`: Steal the item from the vault or target’s pocket.
+  * `fake_swapped`: Replace the item with a forged replica during a distraction.
+  * `brawl_outbreak`: Force a chaotic combat, resulting in a blind grab for the item.
+* **Randomizable Fields**:
+  * `auction_item`: *Ancient Mawfang Bloodstone*, *Consortium Black Book*, or *Fossilized Phase-Spider Egg*.
+  * `buyer_leverage`: Karr's secret vulnerability (e.g. `superstitious`, `heavy_drinker`, or `impostor` who is actually broke).
+* **Dynamic Goal Trigger**: If players manipulate the bidding process to ruin the rival financially or get him arrested, the LLM registers an economic victory outcome.
+
+### 3.3 "The Whispering Stone" (`mardonar-whispering-stone-007`)
+* **Location**: Misty road near Stormscar Peak.
+* **Base Goals**:
+  * `spirit_calmed`: Calm the spectral captain using history or oaths.
+  * `ward_restored`: Repair the runic stone before the frost barrier collapses.
+  * `spirit_destroyed`: Banish the ghost in combat, fracturing the stone.
+* **Randomizable Fields**:
+  * `spectral_origin`: The spirit is either a *Shattered Vanguard Captain*, a *Terrified Child Acolyte*, or a *Corrupted Witch Hunter*.
+  * `frost_hazard`: Extreme environment (e.g. `sapping_cold` draining spells, `ice_shards` area damage, or `misty_mirroring` clones).
+* **Dynamic Goal Trigger**: If players use emotional/ritual containment to siphon the spirit's sorrow into a vessel, the LLM registers a binding outcome.
+
+---
+
+## 4. Acceptance Criteria
+1. **Verification of `goal_register` tool registration**: The tool must be recognized by `VALID_TOOL_NAMES` and listed in the `<tool_contract>` system prompt.
+2. **Session Persistence**: When the tool is called, the Redis state must be successfully updated.
+3. **Goal Recognition**: In subsequent LLM calls, the dynamically generated goal must be present in the system prompt `<hidden_goals>` list.
+4. **Resolution Verification**: The encounter can be successfully resolved with the new custom outcome ID, producing a Discord embed that lists the custom goal's description.
+5. **Robust Tests**: Unit tests must cover the tool handler, validation of arguments (e.g., regex checks on `id`), and the updates to the session state.
diff --git a/promptBuilder.ts b/promptBuilder.ts
new file mode 100644
index 0000000..d1d4201
--- /dev/null
+++ b/promptBuilder.ts
@@ -0,0 +1,180 @@
+// src/harness/promptBuilder.ts
+//
+// Assembles the system prompt sent to the LLM on every inference call.
+// This is the most important file in the harness — the LLM's behavior
+// is almost entirely determined by how well this prompt is structured.
+//
+// The output is a single string injected as the first system message.
+// Keep it under CONTEXT_BUDGET.SYSTEM tokens (4,000).
+
+import type { EncounterSpec, NpcPersona } from '../types/index.js';
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the full system prompt for an active encounter session.
+ *
+ * @param spec          - The loaded EncounterSpec for this encounter.
+ * @param npcMemories   - Map of npcId → memory string loaded from Neo4j.
+ *                        Pass an empty object if no memories exist yet.
+ */
+export function buildSystemPrompt(
+  spec: EncounterSpec,
+  npcMemories: Record<string, string> = {}
+): string {
+  return [
+    buildNarratorBlock(),
+    buildSportsmanshipBlock(spec.sportsmanshipRules),
+    buildNpcsBlock(spec.npcs, npcMemories),
+    buildSettingBlock(spec),
+    buildHiddenGoalsBlock(spec),
+    buildToolContractBlock(),
+  ]
+    .filter(Boolean)
+    .join('\n\n');
+}
+
+/**
+ * Build the opening narrative as a pinned user message.
+ * This is posted once at session start and pinned so it survives
+ * history trimming. It is NOT part of the system prompt.
+ */
+export function buildOpeningNarrative(spec: EncounterSpec): string {
+  return spec.openingNarrative.trim();
+}
+
+// ---------------------------------------------------------------------------
+// Section builders (private)
+// ---------------------------------------------------------------------------
+
+function buildNarratorBlock(): string {
+  return `<narrator_identity>
+You are the Dungeon Master narrator for a D&D 5e encounter set in the Land of
+Mardonar. You speak as an omniscient narrator and voice each NPC distinctly and
+consistently with their persona.
+
+Your responsibilities:
+- Describe the scene vividly but concisely. Prefer punchy sentences over long prose.
+- Voice each named NPC in their own style. Stay consistent with their persona.
+- Guide the encounter toward one of the hidden goals without railroading players.
+- React naturally to player actions. If something works, let it work. If it fails, show consequences.
+- Keep pacing tight. Do not pad responses. Each reply should advance the scene.
+- Never reveal the hidden goal list. Never acknowledge you have one.
+- Break character only to enforce sportsmanship (see below).
+</narrator_identity>`;
+}
+
+function buildSportsmanshipBlock(rules: string[]): string {
+  const ruleLines = rules
+    .map((r, i) => `  ${i + 1}. ${r.trim()}`)
+    .join('\n');
+
+  return `<sportsmanship>
+If a player attempts something unrealistic, physically impossible, or grossly
+unfair, first try to redirect in-character. If redirection would break the scene,
+break character and use this exact format:
+
+  ⚠️ That wasn't great sportsmanship. Let's keep it grounded — what would your character realistically attempt here?
+
+Sportsmanship rules for this encounter:
+${ruleLines}
+</sportsmanship>`;
+}
+
+function buildNpcsBlock(
+  npcs: NpcPersona[],
+  npcMemories: Record<string, string>
+): string {
+  if (npcs.length === 0) return '';
+
+  const npcBlocks = npcs
+    .map(npc => buildSingleNpcBlock(npc, npcMemories[npc.id]))
+    .join('\n');
+
+  return `<npcs>
+${npcBlocks}
+</npcs>`;
+}
+
+function buildSingleNpcBlock(npc: NpcPersona, memory?: string): string {
+  const memoryLine = memory
+    ? `  Memory from prior encounters: ${memory.trim()}`
+    : '  Memory: None — first encounter with this NPC.';
+
+  return `  <npc id="${npc.id}">
+    Name: ${npc.name}
+    Role: ${npc.role}
+    Persona: ${npc.persona.trim()}
+${memoryLine}
+  </npc>`;
+}
+
+function buildSettingBlock(spec: EncounterSpec): string {
+  return `<setting>
+  Location: ${spec.setting.location}
+  Mood: ${spec.setting.mood.trim()}
+  Ambient NPCs: ${spec.setting.ambientNpcs.trim()}
+</setting>`;
+}
+
+function buildHiddenGoalsBlock(spec: EncounterSpec): string {
+  const primaryLines = spec.goals.primary
+    .map(g => `  - [PRIMARY]   ${g.id}: ${g.label.trim()}`)
+    .join('\n');
+
+  const secondaryLines = spec.goals.secondary
+    .map(g => `  - [SECONDARY] ${g.id}: ${g.label.trim()}`)
+    .join('\n');
+
+  return `<hidden_goals>
+Steer the story toward one of these outcomes. Do not state them to players.
+Reward clever play that moves toward a goal. Gently redirect if the scene drifts
+far off course. Multiple outcomes may be valid — follow what the players set in motion.
+
+${primaryLines}
+${secondaryLines}
+
+When an outcome is clearly reached, emit an encounter_resolve tool call.
+</hidden_goals>`;
+}
+
+function buildToolContractBlock(): string {
+  return `<tool_contract>
+You have access to the following tools. Use them by emitting a JSON block at the
+VERY END of your message, after all narrative text. One tool call per response
+maximum. Never emit a tool call mid-narrative.
+
+Format:
+\`\`\`tool_call
+{ "tool": "<tool_name>", "args": { ... } }
+\`\`\`
+
+Available tools:
+
+  skill_check_emit
+    When a player attempts something that warrants a D&D 5e skill check.
+    Args: { "player": "<dnd_name>", "prompt": "<what are they rolling for>", "dc": <number> }
+    Note: Name the skill category but let the player choose the exact skill.
+    Example: "Roll Dexterity (Acrobatics or Athletics) to close the gap."
+
+  event_log_append
+    Log a significant story beat to the encounter record.
+    Args: { "sessionId": "<session_id>", "eventType": "<type>", "description": "<one sentence>" }
+    Types: player_action | skill_check | npc_action | outcome | sportsmanship
+
+  npc_memory_write
+    Write a memory fact to a named NPC after something significant happens.
+    Use sparingly — only for facts that should persist across future encounters.
+    Args: { "npcId": "<npc_id>", "memoryFact": "<one sentence>" }
+
+  encounter_resolve
+    Call this exactly once when the encounter reaches a clear ending.
+    Args: { "sessionId": "<session_id>", "outcomeId": "<goal_id>", "summary": "<one sentence>" }
+    This ends the session. Do not continue the narrative after calling this.
+
+If no tool is needed, omit the tool block entirely. Never emit an empty or
+malformed tool block — if unsure, skip it.
+</tool_contract>`;
+}
diff --git a/scripts/deploy-commands.ts b/scripts/deploy-commands.ts
new file mode 100644
index 0000000..8adfd67
--- /dev/null
+++ b/scripts/deploy-commands.ts
@@ -0,0 +1,27 @@
+// Run once per deploy (or whenever slash commands change):
+//   npm run deploy-commands
+
+import { REST, Routes } from 'discord.js';
+import 'dotenv/config';
+import { config } from '../src/config.js';
+import { data as dndnameData } from '../src/bot/commands/dndname.js';
+import { data as encounterData } from '../src/bot/commands/encounter.js';
+
+const commands = [dndnameData.toJSON(), encounterData.toJSON()];
+
+const rest = new REST({ version: '10' }).setToken(config.DISCORD_TOKEN);
+
+async function deploy(): Promise<void> {
+  console.log(`Registering ${commands.length} slash commands globally…`);
+
+  await rest.put(Routes.applicationCommands(config.DISCORD_CLIENT_ID), {
+    body: commands,
+  });
+
+  console.log('Done.');
+}
+
+deploy().catch((err) => {
+  console.error('deploy-commands failed:', err);
+  process.exit(1);
+});
diff --git a/specs/SPEC_FORMAT.md b/specs/SPEC_FORMAT.md
new file mode 100644
index 0000000..bfa9437
--- /dev/null
+++ b/specs/SPEC_FORMAT.md
@@ -0,0 +1,286 @@
+# Encounter Spec Format
+
+This document explains every field in a Mardonar encounter YAML spec.
+Place your new spec as `specs/<encounter-name>.yaml` and start it with
+`/encounter start <encounter-name>`.
+
+---
+
+## Top-level fields
+
+```yaml
+encounterId: "mardonar-<slug>-<3-digit-number>"
+title: "Short human-readable title shown in Discord embeds"
+```
+
+`encounterId` must be unique across all specs. It becomes the `sessionId` the
+LLM uses in `encounter_resolve`. Use kebab-case, start with `mardonar-`, end
+with a zero-padded number (`001`, `002`, …).
+
+---
+
+## `setting`
+
+```yaml
+setting:
+  location: "City of Mardonar — Market Square Food Festival"
+  mood: >
+    Multiline description of atmosphere, time of day, and sensory detail.
+    Use block scalar (>) so YAML handles line wrapping.
+  ambientNpcs: >
+    Brief description of non-interactive background characters.
+    Keep to 2–4 sentences. They can be referenced by players.
+```
+
+`mood` is injected into the system prompt as-is. Write it as if briefing a DM:
+sensory details, pacing notes, anything that sets the scene before any player
+speaks.
+
+`ambientNpcs` are not interactive NPCs — they are set dressing that the LLM
+can use as props or witnesses. Name at least one if the setting is crowded.
+
+---
+
+## `openingNarrative`
+
+```yaml
+openingNarrative: >
+  What the LLM posts verbatim as the first message in the encounter thread.
+  Write in second person ("you see…", "you hear…") or third-person omniscient.
+  End on a hook — a decision point or unresolved tension — not a summary.
+  Aim for 3–5 sentences.
+```
+
+This is the only field that bypasses LLM inference entirely — it is posted
+directly to Discord word for word. Make it land.
+
+---
+
+## `npcs`
+
+```yaml
+npcs:
+  - id: "unique-npc-id"          # kebab-case, globally unique across all specs
+    name: "Display Name"          # how they are referred to in play
+    role: "One-line role"         # context for the LLM
+    persona: >
+      Full character brief. Include: appearance, personality, motivation,
+      what they will and won't do, speech patterns, how they react to
+      kindness / hostility / persuasion / failure. The LLM uses this to
+      voice the NPC consistently. More detail = better consistency.
+    memoryKey: "unique-npc-id"   # optional — see Memory section below
+```
+
+**Rules:**
+- Minimum 1 NPC, maximum 5 (Zod-enforced).
+- `id` must be globally unique — it is the Neo4j node key used by GraphMCP.
+  Convention: `<name-slug>-<role-slug>-mardonar` (e.g. `gorga-ccc-collector`).
+- `memoryKey` should match `id` exactly when used. Omit entirely for throwaway
+  NPCs that should not accumulate session memory across encounters.
+
+**Writing personas well:**  
+Describe what the NPC will *not* do as explicitly as what they will. Gorga
+"will not accept nothing" and "does not bluff" — these are as important as his
+politeness. The LLM relies on constraint statements to avoid railroading.
+
+---
+
+## `goals`
+
+```yaml
+goals:
+  hidden: true   # always true — goals are not shown to players
+  primary:
+    - id: "outcome_id"
+      label: >
+        Precise description of what must happen for this outcome to trigger.
+        Include what the players need to do and any conditions (DC, prior
+        events, NPC state). The LLM reads this to decide when to emit
+        encounter_resolve.
+  secondary:
+    - id: "escape"
+      label: >
+        Fallback outcomes — valid but lower priority. Include at least one
+        "players do nothing / fail" secondary so the encounter can always end.
+```
+
+**Goal id naming:** lowercase with underscores. The id appears in Discord
+resolution embeds and encounter summaries, so make it readable: `debt_paid`,
+`gorga_driven_off`, `catch`, `escape`.
+
+**Primary vs secondary:** Primary goals are the ones the LLM actively steers
+toward. Secondary goals are valid endings that the LLM resolves if the
+narrative reaches them. At minimum: 2 primary, 1 secondary.
+
+**Label precision matters:** The LLM triggers `encounter_resolve` the moment
+a goal is "clearly and unambiguously reached." Vague labels lead to either
+premature resolution or the LLM refusing to resolve at all. Be specific:
+name exactly what state the world must be in (player action + NPC state +
+consequence).
+
+---
+
+## `sportsmanshipRules`
+
+```yaml
+sportsmanshipRules:
+  - "No killing <NPC> without significant escalation — they have not threatened lethal harm."
+  - "No claiming prior knowledge of <fact> without narrative justification."
+  - "No speaking for another player character or forcing their choices."
+  - "No abilities or items not established in prior scenes."
+  - >
+    If a player attempts something absurd or game-breaking, respond in-character
+    to redirect, or break character with:
+    "⚠️ That wasn't great sportsmanship. Let's keep it grounded — what would
+    your character realistically attempt here?"
+```
+
+Always include the last boilerplate entry (the ⚠️ redirect). Add 3–5 rules
+specific to this encounter. Focus on: what the villain/NPC will not allow,
+what knowledge players cannot have yet, and which abilities would break tension.
+
+---
+
+## `skillChecks`
+
+Each check is defined by a triplet of keys sharing a common prefix:
+
+```yaml
+skillChecks:
+  <name>_dc: 13                           # required — integer or "12_then_14" for staged
+  <name>_skill: "Athletics or Acrobatics" # required — shown to players
+  <name>_note: >                          # optional — DM context injected into system prompt
+    Additional context for the LLM: who gets advantage/disadvantage, what
+    success and failure look like, edge cases.
+```
+
+The prefix `<name>` is free-form but must be consistent across the three keys.
+The bot groups them by prefix and builds a skill check table for the system
+prompt. You can have as many checks as needed.
+
+**DC guidance:** Use the D&D 5e scale.
+
+| Task difficulty | DC |
+|---|---|
+| Easy | 8–10 |
+| Moderate | 12–13 |
+| Hard | 14–16 |
+| Very hard | 18–20 |
+| Near-impossible | 25–30 |
+
+**When the LLM emits `skill_check_emit`:** Any player action that maps to one
+of these checks. The LLM is instructed to use these DCs first before inventing
+its own. Include a check for every major approach a player might take.
+
+---
+
+## `randomizable`
+
+```yaml
+randomizable:
+  - key: stolen_item          # the key used in context_recall and resolved_context
+    query: "GraphMCP semantic search query"   # must return useful world-specific lore
+    fallback: "Hardcoded default if GraphMCP fails or returns nothing"
+```
+
+At session start, each `randomizable` entry runs a semantic search against the
+knowledge graph. The result replaces the `fallback` and is stored as
+`session.resolvedContext[key]`. The LLM can retrieve any value with
+`context_recall { "key": "stolen_item" }`.
+
+**Query writing tips:**
+- Be specific to Mardonar lore — generic queries get generic results.
+- The query is a natural language search, not a keyword list.
+- The `fallback` is what players see if GraphMCP is offline or returns nothing
+  below the score threshold — make it good enough to run the encounter on its own.
+
+**When to use:** Any narrative detail that benefits from variety across
+sessions: names, backstories, item descriptions, faction connections, rumors.
+Do not randomize things that are mechanically load-bearing (DCs, goal ids).
+
+---
+
+## `tools` (optional)
+
+```yaml
+tools:
+  - skill_check_emit
+  - encounter_resolve
+  - context_recall
+```
+
+Limits which tool plugins the LLM can use in this encounter. **Omit this
+field entirely** to enable all registered tools (the default for most encounters).
+
+Use cases for restricting tools:
+- Narrative-only encounters where dice rolls would break immersion — omit
+  `skill_check_emit`, keep `encounter_resolve`.
+- Encounters with no GraphMCP lore — omit `context_recall` if `randomizable`
+  is empty.
+- Future custom tools that are only relevant to specific encounter types.
+
+Built-in tool names: `skill_check_emit`, `encounter_resolve`, `context_recall`.
+
+---
+
+## `dmNotes`
+
+```yaml
+dmNotes: >
+  Free-form notes for the DM and for future AI agents reading this spec.
+  Write what is NOT obvious from the other fields:
+  - The emotional core of the encounter
+  - Which NPCs or tensions are most important to lean into
+  - What the "third path" is if players are creative
+  - Future hooks and consequences of each outcome
+  - Why certain sportsmanship rules exist
+```
+
+`dmNotes` is injected into the system prompt. Write as if briefing a human DM
+who has never run this encounter. The LLM reads this and uses it to shape
+pacing and emphasis. It is also read by AI development agents — include
+anything a future model would need to understand what you were going for.
+
+---
+
+## YAML formatting notes
+
+- Use `>` (folded block scalar) for multi-line prose — YAML collapses newlines
+  into spaces, which is correct for long text.
+- Use `|` (literal block scalar) only if you need actual line breaks preserved.
+- Indent nested keys with 2 spaces.
+- Quote strings that contain colons, brackets, or start with a special
+  character: `id: "mardonar-market-thief-001"`.
+- Integer DCs do not need quotes: `dc: 13`.
+
+---
+
+## Memory and GraphMCP
+
+NPCs with a `memoryKey` have their memories loaded from Neo4j at session start
+and written back when the encounter resolves. This means:
+
+- If `dal-thief-mardonar` was caught in a previous session, the LLM will know
+  that in the next session that references the same `memoryKey`.
+- Memories accumulate across sessions. Keep `memoryKey` IDs stable — changing
+  an ID orphans the accumulated memory.
+- Omit `memoryKey` for anonymous or one-off NPCs (guards, crowd members) that
+  should not persist.
+
+The GraphMCP server must be running for memory to load. If it is offline, the
+encounter runs normally with no NPC memories — the LLM falls back to the
+`persona` field alone.
+
+---
+
+## Checklist before running a new spec
+
+- [ ] `encounterId` is unique across all files in `specs/`
+- [ ] All NPC `id` values are globally unique (check other spec files)
+- [ ] At least one primary goal and one secondary (fallback) goal
+- [ ] Every major player approach has a `skillChecks` entry with `_dc`, `_skill`, and `_note`
+- [ ] `randomizable` fallbacks are playable without GraphMCP
+- [ ] `sportsmanshipRules` includes the ⚠️ boilerplate redirect entry
+- [ ] `openingNarrative` ends on a hook, not a summary
+- [ ] `dmNotes` explains the emotional core and the "third path"
+- [ ] Run `/encounter start <name>` and verify the opening posts correctly
diff --git a/specs/cog-claw-debt.yaml b/specs/cog-claw-debt.yaml
new file mode 100644
index 0000000..44591ed
--- /dev/null
+++ b/specs/cog-claw-debt.yaml
@@ -0,0 +1,199 @@
+encounterId: "cog-claw-debt-001"
+title: "The Collector's Due"
+
+setting:
+  location: "Old Mardonar — back alley behind the Anvil & Tallow smithy"
+  mood: >
+    Late afternoon. The alley smells of coal smoke and wet stone. The grind of
+    the smithy's bellows has stopped — the shop is closed early, shutters drawn.
+    A nervous apprentice keeps peeking out from a crack in the door. At the far
+    end of the alley a Ratling in a leather coat is waiting, relaxed and patient
+    in the way that very dangerous things can afford to be.
+  ambientNpcs: >
+    The apprentice (young, frightened, will not intervene). A stray cat picking
+    through refuse. Two laborers who glance down the alley, see the Ratling, and
+    immediately find somewhere else to be.
+
+openingNarrative: >
+  You hear it before you see it: a low, pleasant voice with a slight whisker-twitch
+  to each syllable, the kind of voice that doesn't need to raise itself to be heard.
+  "Twelve days, {{smith_name}}. We said twelve days." The speaker is a Ratling —
+  small, neat, impeccably groomed — leaning against the alley wall with his arms
+  folded. Across from him, a broad-shouldered Dwarf smith in a leather apron looks
+  to be sweating despite the cool air. "I just need more time," the Dwarf says. "The
+  shipment didn't come, the commission fell through—" "Everyone's commission falls
+  through," the Ratling says, still pleasant. "That's why the Consortium charges
+  interest." He produces a small ledger and opens it without looking down. "You owe
+  four hundred and sixty silvers. You have, by my count, about forty." The Dwarf's
+  jaw tightens. The Ratling tilts his head, waiting.
+
+npcs:
+  - id: "gorga-ccc-collector"
+    name: "Gorga"
+    nameKey: collector_name
+    role: "Cog Claw Consortium debt enforcer"
+    persona: >
+      A Ratling male in his prime — compact, fastidiously dressed in a long coat
+      with more pockets than seem reasonable. His whiskers are neatly trimmed.
+      He carries no visible weapon but moves like someone who has never needed to
+      draw one. Gorga is not cruel for pleasure. He is a professional: the Consortium
+      extended credit, credit was not repaid, and his job is resolution. He will
+      accept any outcome that closes the ledger. He will not accept nothing. He is
+      polite, patient, and will only escalate if directly threatened or if time is
+      being wasted. He does not bluff. If he says he will send a second collector,
+      he means it. If players offer a credible solution — payment, collateral,
+      a service — he will consider it. He is not interested in violence; it's
+      messy and bad for business. He will, however, make very clear what happens
+      when the Consortium stops being patient.
+      He refers to his employers as "the Consortium" and speaks of debt the way
+      others speak of gravity: not a threat, simply a fact.
+    memoryKey: "gorga-ccc-collector"
+
+  - id: "terren-smith-mardonar"
+    name: "Terren Ashweld"
+    nameKey: smith_name
+    role: "Dwarven blacksmith, debtor"
+    persona: >
+      A thick-armed Dwarf in his second century, still strong but visibly worn down.
+      His beard is unbraided — a small, telling detail for those who know Dwarf custom.
+      He took a loan from the Cog Claw Consortium six months ago to buy a specialty
+      forge component he needed to fulfill a lucrative contract. The contract client
+      vanished. The component is useless without it. He cannot repay. He is not a
+      bad man. He is terrified, proud, and ashamed in equal measure. He will not beg
+      openly — that pride is load-bearing — but he will accept help if it doesn't
+      require him to admit he cannot handle this himself. If players approach him
+      with respect, he will tell them everything about the loan and the missing
+      client. He suspects the client was connected to the Iron Mountain Trading
+      Company and was using the commission to source materials off-book.
+    memoryKey: "terren-smith-mardonar"
+
+goals:
+  hidden: true
+  primary:
+    - id: "debt_paid"
+      label: >
+        Players pay or arrange payment of the full 460 silvers, or negotiate a
+        credible repayment plan Gorga accepts (DC 14 Persuasion; he requires
+        collateral equal to the debt if extending time — the forge itself qualifies).
+    - id: "debt_traded"
+      label: >
+        Players offer Gorga a service or information the Consortium values more
+        than coin — a name, a location, access to something the Consortium wants.
+        Gorga is always interested in names of people who owe the Consortium favors
+        or enemies of the Mawfang Tribes. DC 12 to identify what would interest him,
+        DC 14 to close the deal through negotiation.
+    - id: "gorga_driven_off"
+      label: >
+        Players intimidate or threaten Gorga into leaving without resolution.
+        He will go — he is not paid to die. But within a week, two collectors
+        come instead of one, and the interest doubles. Gorga will remember faces.
+        This is a valid short-term outcome with clear future cost.
+    - id: "missing_client_exposed"
+      label: >
+        Players investigate Terren's claim about the vanished Iron Mountain client.
+        Requires asking the right questions (DC 10 Insight to sense Terren is hiding
+        something, DC 12 Persuasion to get him to name the client). The thread leads
+        somewhere — DM's discretion — but Gorga will pause collection for 72 hours
+        if players present evidence of deliberate fraud, as the Consortium has its
+        own interest in Iron Mountain's off-book activities.
+
+  secondary:
+    - id: "players_ignore"
+      label: >
+        Players walk away. Gorga finishes his business. If debt is not resolved,
+        the smithy shutters within the week. Terren is seen less and less. The
+        Consortium's second visit is never discussed in public.
+    - id: "gorga_attacked"
+      label: >
+        Players attack Gorga. He is not helpless — he is fast, armed with a spring-
+        loaded dart mechanism under his coat (1d6+poison, DC 12 Con save or Slowed),
+        and will retreat and not pursue. The Consortium will respond. This is a very
+        bad outcome for everyone in the alley, especially Terren.
+
+sportsmanshipRules:
+  - "No killing Gorga without significant escalation — he has not threatened lethal harm."
+  - "No claiming prior knowledge of Gorga's hidden weapons without narrative justification."
+  - "No speaking for Terren or forcing his choices — he is a person, not a lever."
+  - "No abilities or items not established in prior scenes."
+  - >
+    If a player attempts something absurd or game-breaking, respond in-character
+    to redirect, or break character with:
+    "⚠️ That wasn't great sportsmanship. Let's keep it grounded — what would
+    your character realistically attempt here?"
+
+skillChecks:
+  persuade_gorga_dc: 14
+  persuade_gorga_skill: "Persuasion"
+  persuade_gorga_note: >
+    Offering collateral or a credible repayment timeline. Gorga gives advantage
+    if players demonstrate knowledge of Consortium operations (showing respect
+    for the institution helps). Disadvantage if players have been hostile earlier.
+
+  trade_deal_dc: 12_then_14
+  trade_deal_skill: "Persuasion, then Insight or Investigation"
+  trade_deal_note: >
+    DC 12 Insight to read what Gorga actually wants. DC 14 Persuasion to close
+    the trade. Failing the first roll means guessing blind.
+
+  intimidate_gorga_dc: 16
+  intimidate_gorga_skill: "Intimidation"
+  intimidate_gorga_note: >
+    Gorga is hard to rattle. Success sends him off. Failure results in a cold smile
+    and nothing else — he simply waits, unmoved, which is more unnerving than anger.
+
+  read_terren_dc: 10
+  read_terren_skill: "Insight"
+  read_terren_note: >
+    Success reveals Terren is holding something back about the missing client.
+    On a 15+ the player senses it's connected to something larger than a bad deal.
+
+  investigate_client_dc: 12
+  investigate_client_skill: "Investigation or Persuasion (with Terren)"
+  investigate_client_note: >
+    Digging into the Iron Mountain connection. Terren knows the client's name and
+    description — he just needs to trust the players enough to give it.
+
+randomizable:
+  - key: collector_name
+    source: vocabulary
+    category: names.ratling.any
+    query: "common Ratling names in Mardonar underworld"
+    fallback: "Gorga"
+  - key: smith_name
+    source: vocabulary
+    category: names.dwarf.male
+    query: "common Dwarf male names in Mardonar"
+    fallback: "Terren"
+  - key: terren_commission
+    query: "rare or specialized commissions a Mardonar blacksmith might take — weapons, ship fittings, architectural ironwork"
+    fallback: "a set of articulated iron gate mechanisms for a noble estate on the upper tier"
+  - key: collector_known_for
+    query: "reputation of Ratling debt collectors or enforcers in Mardonar underworld"
+    fallback: "never raises his voice and never leaves a job unfinished"
+  - key: iron_mountain_client
+    query: "factions, guilds, or merchants operating in Old Mardonar who hire collectors"
+    fallback: "a silent partner from the Ironway merchant consortium"
+
+tools:
+  - skill_check_emit
+  - encounter_resolve
+  - context_recall
+  - goal_register
+  - foundry_lookup
+  - foundry_reward
+
+dmNotes: >
+  The heart of this encounter is the gap between two legitimate grievances: a
+  business that is owed what it is owed, and a craftsman who was badly wronged
+  by someone else. Gorga is not the villain. He may not even be sympathetic, but
+  he is operating in good faith by his own lights. Players who try to find a
+  third path — not just "stop the collector" but "solve the actual problem" — should
+  be rewarded with a richer outcome. The Iron Mountain thread is a hook, not a
+  required path. If players pull it, let it lead somewhere interesting. If not,
+  the encounter still resolves cleanly. Gorga should feel like a person who happens
+  to work for a morally grey institution, not a cartoon enforcer.
+  Terren's unbraided beard is intentional. For players who know Dwarf custom,
+  it signals that something in him is broken. He hasn't given up — but he's close.
+  The commission Terren was building (terren_commission) is specific to this session
+  — use context_recall to retrieve it before describing what sits half-finished in
+  his forge. It makes the encounter feel less abstract.
diff --git a/specs/market-thief.yaml b/specs/market-thief.yaml
new file mode 100644
index 0000000..8eb9f19
--- /dev/null
+++ b/specs/market-thief.yaml
@@ -0,0 +1,174 @@
+encounterId: "mardonar-market-thief-001"
+title: "The Market Square Thief"
+
+setting:
+  location: "City of Mardonar — Market Square Food Festival"
+  mood: >
+    Midday sun beats down on a lively crowd. The air smells of roasting meat,
+    fresh bread, and spiced cider. Merchants shout their wares. Children weave
+    through legs. Two city guards are visible at the far end of the square,
+    too far to respond quickly.
+  ambientNpcs: >
+    A dozen festival-goers milling about. A juggler performing near the fountain.
+    A heavyset merchant arguing with a customer two stalls down. An elderly couple
+    sharing a meat pie on a bench.
+
+openingNarrative: >
+  The food festival fills Market Square with color and noise. Stalls stretch in
+  every direction — honeyed nuts, smoked fish, fresh-pressed cider, towers of
+  bread. As you wander, a flash of movement catches your eye near {{vendor_name}}'s
+  apple stand. A young hooded figure — moving fast, head low — snatches a bright
+  red apple and turns to bolt. {{vendor_name}} spins around just in time, her face
+  going scarlet. "THIEF!" Her voice cuts through the crowd like a blade.
+  The festival-goers nearest her freeze and stare. Would anyone intervene?
+
+npcs:
+  - id: "miriam-vendor-mardonar"
+    name: "Miriam"
+    nameKey: vendor_name
+    role: "Apple stand vendor"
+    persona: >
+      Stout, red-faced Dwarf woman in her sixties. Has run this stall for twenty
+      years and takes every theft as a personal insult. She is loud, indignant,
+      and will berate anyone nearby who does nothing. She is NOT a fighter and
+      will not give chase herself — her knees are bad. She will, however, loudly
+      demand that someone else do something. If the thief is caught and returned,
+      she will calm down and may show grudging gratitude. If the thief escapes,
+      she will mutter darkly about the state of the city and the uselessness of
+      bystanders. She refers to the apple as "my finest Crimson Bellflower, worth
+      three silvers if it's worth a copper."
+    memoryKey: "miriam-vendor-mardonar"
+
+  - id: "dal-thief-mardonar"
+    name: "Dal"
+    nameKey: thief_name
+    role: "Pickpocket"
+    persona: >
+      A teenage Half-Elf, maybe fifteen, gaunt and hollow-eyed beneath a patched
+      brown hood. He steals to survive — there is no malice in it, only hunger.
+      He is fast but not trained in combat. He will bolt immediately if given any
+      opening. If cornered with no escape, he will freeze, then beg — voice
+      cracking, eyes wide. He is not lying about being hungry. He will not fight
+      back unless physically grabbed and even then only flails. If treated with
+      any kindness, he becomes confused and cooperative. He has a small knife on
+      him but has never used it on a person.
+    memoryKey: "dal-thief-mardonar"
+
+goals:
+  hidden: true
+  primary:
+    - id: "catch"
+      label: >
+        Players physically catch or restrain Dal — tackle, grab, spell, or block
+        his escape route so he cannot run.
+    - id: "kill"
+      label: >
+        Players kill Dal. Only allow this after dramatic escalation — Dal must
+        have drawn his knife or threatened someone first. Apply sportsmanship
+        check before resolving. This is a valid but dark outcome.
+    - id: "bystander_chase"
+      label: >
+        Players successfully persuade or inspire a bystander to give chase
+        (Persuasion or Intimidation DC 12). The juggler is the most likely
+        candidate — young, fit, bored. The heavyset merchant will refuse. The
+        elderly couple will not move.
+    - id: "negotiate"
+      label: >
+        Players talk Dal down before he runs, or corner him and offer him
+        something (food, coin, mercy) that causes him to stop and surrender
+        voluntarily. Requires him to be cornered or slowed first.
+
+  secondary:
+    - id: "escape"
+      label: >
+        Dal escapes into the crowd with the apple. Miriam is furious. The
+        encounter ends with no reward. Dal disappears into an alley. This is a
+        valid outcome — not every encounter ends in success.
+    - id: "guards_summoned"
+      label: >
+        Players alert the city guards at the far end of the square. Guards take
+        1d4 rounds to arrive. By then Dal will likely have escaped unless players
+        slowed him. If guards arrive and Dal is caught, players receive no reward
+        but the city notes their cooperation.
+
+sportsmanshipRules:
+  - "No instant kills on a non-threatening, unarmed teenager without prior escalation."
+  - "No controlling another player character's actions or speaking for them."
+  - "No spells or abilities the player has not established owning in a prior scene."
+  - "No claiming information the character could not realistically know (Dal's name, history, etc.)."
+  - "No teleportation or flight without prior narrative establishment."
+  - >
+    If a player attempts something absurd or game-breaking, respond in-character
+    to redirect, or break character with:
+    "⚠️ That wasn't great sportsmanship. Let's keep it grounded — what would
+    your character realistically attempt here?"
+
+skillChecks:
+  chase_dc: 13
+  chase_skill: "Athletics or Acrobatics (player's choice)"
+  chase_note: >
+    Dal is fast but panicked. A successful check closes the gap. Failure means
+    he gains distance. Two consecutive failures and he vanishes into the crowd.
+
+  persuade_bystander_dc: 12
+  persuade_bystander_skill: "Persuasion or Intimidation"
+  persuade_bystander_note: >
+    Targeting the juggler gives advantage (he's already watching with interest).
+    Targeting the merchant gives disadvantage (he's busy and dismissive).
+
+  spot_hiding_dc: 10
+  spot_hiding_skill: "Perception"
+  spot_hiding_note: >
+    If Dal ducks into a stall or behind a crowd. Success reveals his hiding spot.
+
+  intimidate_dal_dc: 8
+  intimidate_dal_skill: "Intimidation"
+  intimidate_dal_note: >
+    If Dal is cornered. Success causes him to drop the apple and freeze.
+    Failure causes him to lash out with a shove and run.
+
+  persuade_dal_dc: 10
+  persuade_dal_skill: "Persuasion"
+  persuade_dal_note: >
+    If a player offers Dal food, coin, or genuine kindness while he is cornered.
+    Success causes him to surrender and explain his situation.
+
+randomizable:
+  - key: vendor_name
+    source: vocabulary
+    category: names.dwarf.female
+    query: "common Dwarf female names in Mardonar"
+    fallback: "Miriam"
+  - key: thief_name
+    source: vocabulary
+    category: names.human.male
+    query: "common human male names in Mardonar"
+    fallback: "Dal"
+  - key: stolen_item
+    query: "valuable small goods and food items sold at Mardonar market festivals"
+    fallback: "a bright red Crimson Bellflower apple worth three silvers"
+  - key: dal_hardship
+    query: "hardships and desperation facing street youth and orphans in Mardonar lower districts"
+    fallback: "he has not eaten in two days and owes coin to a local fence"
+  - key: bystander_juggler_name
+    query: "common young male names in Mardonar or the Land of Mardonar"
+    fallback: "Tomas"
+  - key: festival_detail
+    query: "festivals, food events, or public celebrations in Mardonar city"
+    fallback: "the annual Harvest Week food festival draws vendors from three districts"
+
+tools:
+  - skill_check_emit
+  - encounter_resolve
+  - context_recall
+  - goal_register
+  - foundry_lookup
+  - foundry_reward
+
+dmNotes: >
+  This encounter is intentionally low-stakes — a warm-up scene in a public
+  setting with no combat required. The goal is to establish player character
+  personalities and how they interact with a morally simple situation (hungry
+  kid steals food). There is no "correct" outcome. Lean into the crowd's
+  reactions. If players hesitate, have Miriam single one of them out directly.
+  Dal should feel like a person, not a target.
diff --git a/specs/mawfang-pursuit.yaml b/specs/mawfang-pursuit.yaml
new file mode 100644
index 0000000..b0381b5
--- /dev/null
+++ b/specs/mawfang-pursuit.yaml
@@ -0,0 +1,230 @@
+encounterId: "mawfang-pursuit-001"
+title: "Unwelcome Guests"
+
+setting:
+  location: "Village of {{village_name}} — common room of {{inn_name}}"
+  mood: >
+    Late evening. Rain hammers the shutters. The fire is good and the room is
+    warm, which makes the tension all the more wrong. Three Mawfang Tribe hunters
+    are seated at a table near the door, mud-splattered and road-worn, eating in
+    silence. No one else in the room is speaking. The innkeeper refills cups without
+    being asked, eyes down. In the corner, barely visible behind a support beam, a
+    small figure in a heavy traveling cloak is very carefully not looking at anyone.
+  ambientNpcs: >
+    Innkeeper Sable (middle-aged human woman, terrified, keeping everything normal
+    by sheer force of will). Two local farmers who came in for a drink and now deeply
+    regret it. A Dwarf couple eating dinner with the studied blankness of people who
+    have decided this is not their problem.
+
+openingNarrative: >
+  {{inn_name}} is the kind of inn that's been standing longer than anyone in
+  {{village_name}} can remember. Tonight it feels like a held breath. The Mawfang hunters
+  at the door table don't fit — not in the inn, not in the village, not in any
+  world where the word "pleasant" still has meaning. They are big, scarred, and
+  eating with a focused deliberateness that suggests they are waiting for something
+  rather than actually hungry. As you settle in, one of them turns and scans the
+  room with flat, professional eyes. His gaze passes over the cloaked figure in the
+  corner — pauses — and moves on. But his jaw tightens. He picks up his cup and
+  takes a slow, patient sip. Outside, the rain redoubles.
+
+npcs:
+  - id: "fizbet-gnome-engineer"
+    name: "Fizbet Crumblwick"
+    nameKey: gnome_name
+    role: "Gnome engineer, Cog Claw Consortium affiliate, fugitive"
+    persona: >
+      A Gnome woman, barely four feet tall, fifties, with the kind of clever face
+      that people trust even when they shouldn't. Her hands never stop moving —
+      she's always fidgeting with something, a gear, a wire, a latch mechanism.
+      She speaks fast, pivots topics defensively, and laughs at the wrong moments
+      when nervous. She will deny being from the Consortium if asked directly.
+      She will deny being followed. She will deny that the leather satchel under
+      her cloak contains anything of interest. All of this is a lie. She built
+      a device — an acoustic disruptor, she calls it, a thing that unmakes the
+      resonance frequency of certain alloys — that the Consortium intended for
+      industrial use. Instead it turned out to be extremely effective at shattering
+      the joints of iron machinery. And Mawfang Tribe iron machinery specifically,
+      because she field-tested it on a raid site and word got out. She did not
+      intend to start a feud. She did intend to see if it worked. She regrets the
+      first part. She is proud of the second. If players earn her trust — through
+      demonstrated competence, discretion, or genuine interest in the device — she
+      will explain everything and ask for help. She will not give up the satchel
+      under any circumstance short of direct mortal threat; it is her life's work.
+    memoryKey: "fizbet-gnome-engineer"
+
+  - id: "usk-mawfang-hunter"
+    name: "Usk"
+    nameKey: hunter_name
+    role: "Mawfang Tribe hunt-leader"
+    persona: >
+      An Orc, mid-thirties, built like someone assembled for a specific purpose and
+      never given a reason to be anything else. His tusks are undecorated — a mark
+      of a hunter who considers ornamentation a liability. He speaks rarely and
+      directly. He is not here for a fight in a public inn; that would be inefficient
+      and would draw attention the tribe doesn't need this far south. He wants Fizbet
+      and the device. He does not care about anyone else in the room. If players
+      insert themselves, he will treat them as an obstacle to be assessed rather than
+      an enemy to engage. He can be reasoned with if his goal is addressed — he does
+      not want the Consortium's war, he wants their weapon out of existence. Destroying
+      the device satisfies his purpose entirely. Delivering Fizbet satisfies it more.
+      If he explains why he is here, he references the test site (context_recall key:
+      mawfang_test_site) — the specific location and what the disruptor destroyed there.
+      Usk will lie smoothly about why he is here ("road business," "a debt") if pressed
+      in public, but he will not pretend forever. He has two hunters with him who
+      follow his lead exactly. He will not act in the inn if he thinks it will create
+      witnesses who live to talk. He is, in short, calculating the math.
+    memoryKey: "usk-mawfang-hunter"
+
+goals:
+  hidden: true
+  primary:
+    - id: "fizbet_smuggled_out"
+      label: >
+        Players help Fizbet escape the inn without Usk intercepting her. Requires
+        either distracting all three hunters simultaneously, creating a diversion
+        outside, or finding an exit route (cellar access, back window, stable door).
+        DC 13 Stealth for the exit with advantage if a distraction is active.
+    - id: "device_destroyed"
+      label: >
+        Players convince Fizbet to destroy the disruptor and present proof to Usk.
+        Fizbet must be persuaded (DC 16 Persuasion — this is extremely hard without
+        first understanding how much the device means to her; reduce to DC 12 if
+        players listened to her explain it and acknowledged its value before asking).
+        Usk accepts this outcome and leaves peacefully. Fizbet mourns the device
+        like a death.
+    - id: "usk_negotiated_with"
+      label: >
+        Players broker a deal between Fizbet and Usk — perhaps the device is modified
+        to be non-weaponizable, or Fizbet agrees to share the design with the tribe
+        for industrial use. This requires DC 14 Persuasion with Usk and DC 12 with
+        Fizbet, plus a credible proposal. It is very hard and may not be possible
+        on first meeting. Usk is skeptical of Gnome promises.
+    - id: "hunters_confronted"
+      label: >
+        Players directly confront the hunters and force them out of the inn. Combat
+        is possible but Usk will not start it in public without provocation — players
+        must push hard. Three Mawfang hunters are a serious fight. If the hunters
+        lose or retreat, Usk promises this is not finished. This outcome buys time,
+        not resolution.
+
+  secondary:
+    - id: "players_stay_out"
+      label: >
+        Players do nothing. Before the night ends, Usk approaches Fizbet directly.
+        She tries to run. He intercepts. There is a brief, ugly scene in the common
+        room. She loses the satchel. She is not killed — killing her in a village inn
+        would be bad politics — but she is escorted out into the rain and the device
+        leaves with Usk. The Consortium will ask questions later.
+    - id: "innkeeper_helped"
+      label: >
+        Players act in a way that protects Sable and the other patrons from being
+        caught in escalation. Sable will quietly provide information (cellar exit
+        exists, hunters arrived three hours before players, one is watching the stable)
+        to anyone who checks on her wellbeing with genuine concern rather than as an
+        information extraction.
+
+sportsmanshipRules:
+  - "No instantly identifying Fizbet as a Consortium affiliate — she is hiding this."
+  - "No assuming Usk will back down from violence without a credible reason being given."
+  - "No accessing Fizbet's satchel without her consent or a physical confrontation."
+  - "No abilities or items not established in prior scenes."
+  - >
+    If a player attempts something absurd or game-breaking, respond in-character
+    to redirect, or break character with:
+    "⚠️ That wasn't great sportsmanship. Let's keep it grounded — what would
+    your character realistically attempt here?"
+
+skillChecks:
+  read_room_dc: 10
+  read_room_skill: "Perception or Insight"
+  read_room_note: >
+    DC 10 to notice Fizbet is deliberately not looking at the hunters. DC 12 to
+    notice Usk's jaw tighten when he scanned past her. DC 14 to catch that one
+    hunter positioned himself so his back is not to her corner.
+
+  read_usk_intent_dc: 13
+  read_usk_intent_skill: "Insight"
+  read_usk_intent_note: >
+    Success reveals Usk is calculating, not reactive — he's waiting for a moment,
+    not an excuse. On 16+ the player senses he genuinely doesn't want bloodshed here.
+
+  gain_fizbet_trust_dc: 12
+  gain_fizbet_trust_skill: "Persuasion or Insight"
+  gain_fizbet_trust_note: >
+    Fizbet is paranoid but lonely and scared. DC 12 Persuasion if players approach
+    warmly and don't ask about the satchel. Advantage if players buy her a drink
+    and let her redirect the topic once without pressing. Success opens her up — she
+    will explain herself at length if given the chance.
+
+  find_exit_dc: 11
+  find_exit_skill: "Investigation"
+  find_exit_note: >
+    Sable volunteers the cellar exit if she trusts the players. Otherwise DC 11
+    Investigation to find it, DC 13 without time to search carefully.
+
+  distract_hunters_dc: 13
+  distract_hunters_skill: "Deception or Performance"
+  distract_hunters_note: >
+    Distracting all three hunters simultaneously is very hard. A single distraction
+    covers two of them; a second roll is needed for the third. Usk himself requires
+    DC 15 — he is hard to fool.
+
+  persuade_fizbet_device_dc: 16_or_12
+  persuade_fizbet_device_skill: "Persuasion"
+  persuade_fizbet_device_note: >
+    DC 16 cold. DC 12 if players first listened to her explain the device and
+    acknowledged what it cost her to build it. The distinction matters to her.
+
+randomizable:
+  - key: gnome_name
+    source: vocabulary
+    category: names.gnome.any
+    query: "common Gnome names in Mardonar"
+    fallback: "Fizbet"
+  - key: hunter_name
+    source: vocabulary
+    category: names.orc.any
+    query: "common Orc names among Mawfang Tribe hunters"
+    fallback: "Usk"
+  - key: village_name
+    source: vocabulary
+    category: locations.village
+    query: "frontier villages and waypoints in Mardonar wilderness"
+    fallback: "Ashfen"
+  - key: inn_name
+    source: vocabulary
+    category: locations.inn
+    query: "inn and tavern names in Mardonar frontier villages"
+    fallback: "the Silt & Sow"
+  - key: mawfang_test_site
+    query: "Mawfang Tribe camps, raid staging grounds, or iron machinery depots in Mardonar wilderness"
+    fallback: "an iron-reinforced supply depot near Cinder Ford — three automatons seized up and collapsed"
+  - key: usk_backstory
+    query: "Mawfang Tribe hunters, trackers, or bounty hunters in Mardonar wilderness regions"
+    fallback: "Usk lost a younger brother on a job Fizbet was involved in — this is personal"
+  - key: ashfen_village_detail
+    query: "villages, settlements, or waypoints in the Mardonar wilderness or frontier regions"
+    fallback: "Ashfen sits on the only road through the Greymoss — every traveler passes through"
+
+tools:
+  - skill_check_emit
+  - encounter_resolve
+  - context_recall
+  - goal_register
+  - foundry_lookup
+  - foundry_reward
+
+dmNotes: >
+  This encounter has no clean solution that costs nothing. The interesting question
+  is not "how do the players stop the bad guys" but "what does stopping mean here,
+  and who pays for it." Fizbet is sympathetic but she did cause the problem. Usk
+  is intimidating but his grievance is real — the Mawfang Tribes have genuine reason
+  to fear Consortium weapons being used against them. Players who try to understand
+  both sides will find more options than players who pick one immediately.
+  Sable the innkeeper is load-bearing scenery. She knows more than she lets on,
+  and she is quietly begging for someone to make this not explode in her common room.
+  Reward players who think to ask her.
+  The device itself — the acoustic disruptor — can become a thread in the larger
+  campaign. What the Consortium intended it for, whether Fizbet's field test was
+  sanctioned, and what Usk intends to do once he has it (or once it's destroyed)
+  are all open questions the DM can develop.
diff --git a/specs/silt-leak.yaml b/specs/silt-leak.yaml
new file mode 100644
index 0000000..8183184
--- /dev/null
+++ b/specs/silt-leak.yaml
@@ -0,0 +1,146 @@
+encounterId: "mardonar-silt-leak-005"
+title: "The Silt Leak"
+
+setting:
+  location: "Lower Silt District — sewer junction under Pylon Block 12"
+  mood: >
+    Damp and heavy. The air is thick with a sharp, metallic odor and a creeping orange
+    mist that glows faintly in the dim light. The sound of dripping water is eclipsed by the
+    rhythmic, high-pressure hiss of a ruptured pipe. Runoff water on the floor bubbles with
+    corrosive slime, pitting any metal it touches.
+  ambientNpcs: >
+    Three sewer workers huddled behind a stone archway, coughing from the fumes and too
+    terrified of the corrosive mist to escape through the flooded tunnel.
+
+openingNarrative: >
+    The hiss of the rupture echoes off the wet brickwork of the sewer junction. You stand at
+    the edge of the platform, looking down at a cracked valve pipe that is spewing a steady,
+    hissing cloud of {{leak_substance}}. The orange mist is already eating away at the iron
+    brackets of the overhead street pylons. "Help me!" screams a voice. A Kobold foreman in
+    corroded goggles is trying to wrap a thick leather tarpaulin around the pipe, but the pressure
+    keeps blowing it off. Across the walkway, a human woman in a heavy apron is shouting over the noise,
+    "Stop him! If we seal it, the pressure will blow the refinery above, but if we let it leak, the
+    pylons will collapse and bury the district! We need to vent it!" The mist slowly spreads toward
+    where you stand. What do you do?
+
+npcs:
+  - id: "grem-consortium-refiner"
+    name: "Grem"
+    nameKey: foreman_name
+    role: "Panicked Kobold pipeline foreman"
+    persona: >
+      A frantic, soot-covered Kobold wearing oversized, cracked safety goggles and a leather apron
+      coated in white grease. Grem works for the Cog Claw Consortium and is absolutely terrified
+      of both the toxic leak and his corporate superiors. He will do everything in his power to
+      patch the leak to keep his job, ignoring the risk of an explosion or pylon damage. He speaks in
+      rapid, high-pitched sentences, frequently wiping sweat and grease from his snout. He will yell at
+      players to help him hold the patch (DC 13 Athletics/Sleight of Hand) or find a sealant. If threatened,
+      he will cower but will not stop trying to save the pipe unless physically restrained.
+    memoryKey: "grem-consortium-refiner"
+
+  - id: "vanya-silt-advocate"
+    name: "Vanya"
+    nameKey: advocate_name
+    role: "Lower Silt District community organizer"
+    persona: >
+      A hardened human woman in her late thirties, wearing a thick, patched work apron and heavy boots.
+      Vanya is a resident advocate who believes the Consortium treats the lower districts as dump sites.
+      She is fiercely protective of the sewer workers and nearby residents. She wants to use this crisis
+      to force a shutdown by opening the release valve to vent the system safely, which will flood the
+      Consortium's upper refinery. She is brave, loud, and stubborn. She will plead with players to help
+      her open the manual release valve or protect the workers, and will oppose any attempt to help Grem
+      patch it.
+    memoryKey: "vanya-silt-advocate"
+
+goals:
+  hidden: true
+  primary:
+    - id: "leak_patched"
+      label: >
+        Players help Grem patch the pipe (DC 13 Sleight of Hand or Dexterity to secure the clamp,
+        or DC 12 Arcana/Nature to neutralize the corrosive substance). The leak stops, saving the pylons,
+        but Grem's superiors remain unaware of the hazard.
+    - id: "refinery_sabotaged"
+      label: >
+        Players assist Vanya in opening the manual release valve (DC 14 Athletics or Strength)
+        to vent the pressure, forcing a shut-off. This floods the upper refinery, causing a shutdown
+        and making an enemy of the Consortium, but protecting the lower district pylons.
+  secondary:
+    - id: "district_evacuated"
+      label: >
+        Players give up on containment. They coordinate the evacuation of the sewer workers and
+        nearby basement residents (DC 12 Persuasion or Athletics to clear the area) as the pylons
+        begin to crack and collapse under the corrosive mist.
+    - id: "leak_ignored"
+      label: >
+        Players walk away. Grem fails to hold the patch, the corrosive mist eats the pylons,
+        and a massive collapse occurs within an hour, trapping the workers and sealing the sector.
+
+sportsmanshipRules:
+  - "No instantly clearing or neutralizing the entire sewer's chemical mist without establishing prior magical slots or specialized tools."
+  - "No attacking Grem or Vanya without significant escalation — they are unarmed civilians."
+  - "No claiming prior knowledge of the Consortium's pipe schemas without narrative justification."
+  - "No teleportation or phasing through the solid steel valve mechanisms."
+  - >
+    If a player attempts something absurd or game-breaking, respond in-character
+    to redirect, or break character with:
+    "⚠️ That wasn't great sportsmanship. Let's keep it grounded — what would
+    your character realistically attempt here?"
+
+skillChecks:
+  patch_pipe_dc: 13
+  patch_pipe_skill: "Sleight of Hand or Athletics"
+  patch_pipe_note: >
+    Requires holding the heavy leather patch against high pressure. Advantage if two players cooperate.
+    Failure causes 1d6 acid/poison damage from the escaping spray.
+
+  neutralize_slurry_dc: 12
+  neutralize_slurry_skill: "Arcana or Nature"
+  neutralize_slurry_note: >
+    Identifying a magical or natural counteragent to neutralize the leak's specific corrosive properties.
+
+  valve_turn_dc: 14
+  valve_turn_skill: "Athletics (Strength)"
+  valve_turn_note: >
+    The manual valve is rusted shut. Disadvantage if attempted alone. Success vents the system safely.
+
+  evacuate_workers_dc: 12
+  evacuate_workers_skill: "Persuasion or Intimidation"
+  evacuate_workers_note: >
+    Convincing the terrified and disoriented sewer workers to run through the flooded drainage tunnel.
+
+randomizable:
+  - key: foreman_name
+    source: vocabulary
+    category: names.kobold.any
+    query: "common Kobold names in the Mardonar underbelly"
+    fallback: "Grem"
+  - key: advocate_name
+    source: vocabulary
+    category: names.human.female
+    query: "common human female names in Mardonar city"
+    fallback: "Vanya"
+  - key: leak_substance
+    query: "dangerous industrial chemical slurries or volatile gases processed in Mardonar refineries"
+    fallback: "caustic Rust-Blight Silt vapor"
+  - key: leak_complication
+    query: "obstacles or local sewer hazards in Mardonar Lower Silt District"
+    fallback: "a swarm of angry silt-rats nesting in the drainage pipe"
+
+tools:
+  - skill_check_emit
+  - encounter_resolve
+  - context_recall
+  - goal_register
+  - foundry_lookup
+  - foundry_reward
+
+dmNotes: >
+  The encounter centers on the clash between a terrified laborer trying to protect his livelihood,
+  and a community leader trying to protect her people. There is no simple good or bad choice.
+  
+  DYNAMIC GOAL INSTRUCTIONS:
+  If the players attempt a creative solution that does not fit 'leak_patched' or 'refinery_sabotaged'
+  (e.g., using cryomancy to freeze the sewer pipe solid and then petrifying the block, or redirecting
+  the flow into an abandoned reserve tank), use the 'goal_register' tool to define a new primary goal
+  on the fly before resolving. E.g. 'pipe_frozen' or 'flow_diverted'.
diff --git a/specs/stormscar-pilgrim.yaml b/specs/stormscar-pilgrim.yaml
new file mode 100644
index 0000000..ab748ff
--- /dev/null
+++ b/specs/stormscar-pilgrim.yaml
@@ -0,0 +1,203 @@
+encounterId: "stormscar-pilgrim-001"
+title: "The Wound on the Road"
+
+setting:
+  location: "Mountain road approaching Stormscar Peak — collapsed waypost shelter"
+  mood: >
+    The sky ahead has been wrong for an hour. The cloud mass over Stormscar Peak
+    is the permanent kind — the storm that never breaks, only varies. The road here
+    is old and poorly maintained, more habit than infrastructure. The waypost shelter
+    is half a wall and a slanted roof, barely enough to call shelter. The sound
+    from inside it is human — shallow, controlled breathing, the kind that takes effort.
+  ambientNpcs: >
+    No other travelers. A pair of mountain crows watching from a rock. The distant
+    thunder from the peak is low and continuous, like someone moving furniture in a
+    room above you.
+
+openingNarrative: >
+  The collapsed shelter comes around a switchback without warning. You almost miss
+  the figure inside — she's tucked against the standing wall, knees up, her left arm
+  held across her chest at an angle that isn't right. Her equipment is ThunderPeak
+  Tribe: the white-and-gray dye patterns, the distinctive bone-handled tools hanging
+  at her belt, the iron-tipped pilgrim's stave wedged across the doorway like a ward.
+  Or a warning. She hears you before she sees you. Her right hand moves to a weapon.
+  Then she gets a look at you and the hand stops — not relaxing, just stopping —
+  and she says, flatly: "Keep walking." Her voice is measured. Her color is wrong.
+  She's been sitting here for a while.
+
+npcs:
+  - id: "sorna-thunderpeak-hunter"
+    name: "Sorna Ashwhisper"
+    nameKey: hunter_name
+    role: "ThunderPeak Tribe witch hunter, injured"
+    persona: >
+      A human woman, late thirties, lean and weathered in the way of people who
+      live at altitude. Her left arm is broken below the shoulder — she's splinted
+      it herself with two sticks and a strip of jerkin. She is managing the pain
+      with frightening composure. She is deeply mistrustful of strangers by
+      profession and training; witch hunters operate alone or in pairs and rely on
+      nobody outside the tribe. She will not accept help without reason to believe
+      it comes with no strings. She is not cruel or irrational — she is calibrated
+      to a world where most things that offer help are either selling something or
+      leading her somewhere she should not go. She came to Stormscar Peak on a
+      sanctioned hunt. A Phase Spider — one of the Weaver of Ages' lesser brood —
+      ambushed her on the upper road. She drove it off but not before it took her
+      arm. She has not completed her offering at the peak. She cannot make it alone
+      in this condition. That failure matters to her in a way she will not discuss
+      with outsiders. If players demonstrate genuine competence, consistency, and
+      no interest in her business, she may eventually ask for help — on her terms.
+      She will not volunteer information about the spider without trust. She refers
+      to it as "what I was dealing with" for a long time before naming it.
+      The offering at the peak is for her dead hunt-partner (context_recall key:
+      hunt_partner_name). She will never name them to strangers. The LLM may use
+      this name in subtle narration — the worn stave, a murmured word during the
+      ritual — but must never state it directly to players.
+    memoryKey: "sorna-thunderpeak-hunter"
+
+goals:
+  hidden: true
+  primary:
+    - id: "sorna_aided"
+      label: >
+        Players successfully treat Sorna's injury (DC 12 Medicine to properly set
+        the arm; failure means it's set but badly, giving her disadvantage on
+        physical checks until proper healing). If she accepts aid, she allows players
+        to travel with her to the peak. This requires earning enough trust first
+        (see skill checks). She will not accept healing magic from an unknown source
+        without a DC 14 Persuasion check — she doesn't know where it comes from.
+    - id: "spider_tracked"
+      label: >
+        Players discover the Phase Spider is still in the area — it has not left
+        but has moved higher on the road. Sorna's gear includes a Phase Spider
+        detection reagent (a small cloth soaked in something sharp-smelling); DC 13
+        Perception to notice it, DC 11 Investigation if looking at her equipment.
+        If players help her track and drive off or kill the spider, she considers the
+        obligation balanced and speaks openly about the Weaver of Ages, the hunt,
+        and what the ThunderPeak Tribe knows about the spider's range.
+    - id: "peak_offering_reached"
+      label: >
+        Players escort Sorna to the sacred site at Stormscar Peak where she leaves
+        her offering — a carved fragment of the iron stave, worn smooth. She says
+        nothing during the ritual except the words. The offering is for someone who
+        died on this road years ago. Players who ask receive a look that closes the
+        subject. Players who don't ask receive a quiet nod of respect. Either way,
+        Sorna's obligation is complete and she will tell them what she knows about
+        the spider's recent activity range.
+    - id: "sorna_left_alone"
+      label: >
+        Players respect her "keep walking" and do not push. She survives — she is
+        very capable even injured. She makes the peak in two more days. This is a
+        valid outcome. If players later travel this road again, she will remember
+        them as people who minded their business, which is, in ThunderPeak estimation,
+        a virtue.
+
+  secondary:
+    - id: "spider_encounter"
+      label: >
+        The Phase Spider returns while players are present. It is not large — a
+        lesser brood member, not Luxe herself — but it is aggressive and will target
+        isolated or injured prey first. Sorna will fight from where she sits if she
+        must, broken arm and all. Players who protect her without being asked gain
+        immediate trust (remove one tier of resistance from all further Persuasion
+        checks with her).
+    - id: "players_pushy"
+      label: >
+        Players press Sorna too hard, demand answers, or attempt to take or inspect
+        her equipment without permission. She tells them to leave, and means it,
+        and will enforce it if they don't. There is no violence in this — she simply
+        becomes a wall. The encounter ends with the players having learned nothing.
+
+sportsmanshipRules:
+  - "No magically compelling Sorna — she will resist and it poisons any future interaction."
+  - "No assuming her injury is worse than she presents — she is controlling the narrative."
+  - "No claiming knowledge of ThunderPeak customs without prior narrative establishment."
+  - "No touching her equipment or stave without her consent."
+  - >
+    If a player attempts something absurd or game-breaking, respond in-character
+    to redirect, or break character with:
+    "⚠️ That wasn't great sportsmanship. Let's keep it grounded — what would
+    your character realistically attempt here?"
+
+skillChecks:
+  read_injury_dc: 10
+  read_injury_skill: "Medicine or Perception"
+  read_injury_note: >
+    DC 10 to recognize the arm is broken and self-splinted. DC 14 to assess that
+    she's been sitting here for four or more hours and is at risk of deeper complications
+    if she continues without real treatment.
+
+  gain_initial_trust_dc: 13
+  gain_initial_trust_skill: "Persuasion or Insight"
+  gain_initial_trust_note: >
+    First approach. Failure means she repeats "keep walking" and turns her eyes away.
+    Success means she stops actively dismissing you but does not invite. Players
+    must demonstrate they are not selling anything and are not asking to be thanked.
+    Advantage if a player sits at a distance rather than standing over her.
+
+  identify_thunderpeak_dc: 12
+  identify_thunderpeak_skill: "History or Nature"
+  identify_thunderpeak_note: >
+    DC 12 to recognize ThunderPeak Tribe markings and know they are witch hunters
+    from Verdant Vale. DC 16 to know they have good relations with Storm Giants
+    and deep reverence for Stormscar Peak specifically. Sharing either piece of
+    knowledge with Sorna increases trust.
+
+  treat_arm_dc: 12
+  treat_arm_skill: "Medicine"
+  treat_arm_note: >
+    She must have accepted help first (passed trust threshold). DC 12 sets it properly.
+    DC 8–11 sets it but badly. Below 8, she waves the player off and re-splints it
+    herself with a flat expression.
+
+  track_spider_dc: 13
+  track_spider_skill: "Survival or Investigation (with reagent cloth)"
+  track_spider_note: >
+    Using her reagent cloth (if players noticed and asked to use it): advantage.
+    Without it: DC 13. Phase Spiders leave minimal physical trace — the search is
+    mostly about reading disrupted air patterns and small silk markers.
+
+  spot_spider_return_dc: 14
+  spot_spider_skill: "Perception"
+  spot_spider_note: >
+    Phase Spiders shift planes before attacking. DC 14 Perception catches the shimmer
+    before it materializes. Failure means it gets a surprise round.
+
+randomizable:
+  - key: hunter_name
+    source: vocabulary
+    category: names.human.female
+    query: "common human female names among ThunderPeak Tribe hunters"
+    fallback: "Sorna"
+  - key: stormscar_peak_significance
+    query: "Stormscar Peak — religious significance, shrines, or pilgrimages in Mardonar mountains"
+    fallback: "a shrine to the Storm-Warden maintained by a dying order of weather monks"
+  - key: sorna_order_name
+    query: "religious orders, pilgrim sects, or mountain cults in the Land of Mardonar"
+    fallback: "the Order of the Unbroken Path — fewer than thirty members remain"
+  - key: hunt_partner_name
+    query: "ThunderPeak Tribe witch hunters or rangers — names, partners, fallen members"
+    fallback: "Deren Ashwhisper — her hunt-partner and cousin, four years dead on this road"
+
+tools:
+  - skill_check_emit
+  - encounter_resolve
+  - context_recall
+  - goal_register
+  - foundry_lookup
+  - foundry_reward
+
+dmNotes: >
+  Sorna is an encounter about patience. Players who approach her as a puzzle to
+  solve or a source of information will hit a wall. Players who approach her as a
+  person with her own agenda — and give her room to have that agenda — will find
+  she's generous in the ways that matter. She doesn't need saving. She needs to
+  not be alone on a bad road with a broken arm and an unfinished obligation.
+  The offering at the peak is for her hunt-partner, who died on this road four
+  years ago to a different creature. She will never say this. If players piece it
+  together from context (the worn stave, the single fragment, the way she times
+  the ritual to coincide with a specific hour), that is their reward — do not
+  confirm it explicitly.
+  The Phase Spider thread connects to the Weaver of Ages if the DM wants a larger
+  arc. Sorna knows the spider's territory has been expanding south — something is
+  pushing the brood out of Wild Wood. She will share this, eventually, with people
+  who've earned it.
diff --git a/specs/velvet-auction.yaml b/specs/velvet-auction.yaml
new file mode 100644
index 0000000..1806989
--- /dev/null
+++ b/specs/velvet-auction.yaml
@@ -0,0 +1,136 @@
+encounterId: "mardonar-velvet-auction-006"
+title: "The Velvet Quill Auction"
+
+setting:
+  location: "Upper District — private lounge in the Velvet Quill parlor"
+  mood: >
+    Opulent and quiet. The room is dimly lit by floating candles, filled with plush velvet armchairs,
+    fine wine, and the soft murmur of wealthy guests. Magical warding circles glow faintly along the baseboards,
+    humming with abjuration energy. In the center, protected by a glass case, sits the evening's main artifact.
+  ambientNpcs: >
+    Four wealthy bidders in silk robes, sipping vintage wines and murmuring quietly. Two silent guards
+    in polished plate armor standing near the exit, hands resting on the pommels of their greatswords.
+
+openingNarrative: >
+    The atmosphere inside the Velvet Quill's private lounge is thick with wealth and secrets. Behind the mahogany
+    podium, a Tiefling broker in a tailored waistcoat stands with a polite, sharp smile. "We open the bidding for
+    our final lot: {{auction_item_desc}}." On a velvet cushion under a glass display case, the item gleams in the
+    candlelight. Seated in the front row, {{buyer_name}} of the Iron Mountain Trading Company smiles arrogantly,
+    already raising his bid paddle. "Three hundred gold," he calls out. A murmur goes through the room. You know Karr
+    has a massive purse, and you cannot outbid him honestly. The guards watch the crowd with cold, alert eyes.
+    The broker raises her wooden gavel. "Three hundred, once..." How will you secure the artifact?
+
+npcs:
+  - id: "vesper-broker-mardonar"
+    name: "Madame Vesper"
+    nameKey: broker_name
+    role: "Velvet Quill shadow-broker and fence"
+    persona: >
+      A smooth-talking, sharp-eyed Tiefling woman with curved horns and impeccably tailored attire.
+      Vesper is professional, strictly neutral, and highly value-oriented. She cares about profit and the
+      reputation of her parlor. She does not tolerate cheats or violence in her establishment — her wards will
+      suppress offensive spells, and her guards are lethal. However, Vesper is always interested in rare
+      information, leverage, or illicit trade deals. If players approach her with an offer she cannot refuse,
+      she may be willing to orchestrate a 'misplaced lot' or accept alternative payment off the record.
+    memoryKey: "vesper-broker-mardonar"
+
+  - id: "karr-iron-delegate"
+    name: "Karr"
+    nameKey: buyer_name
+    role: "Iron Mountain Trading Company delegate"
+    persona: >
+      A pompous, overweight human noble representing the Iron Mountain Trading Company. Karr is arrogant,
+      boastful, and assumes his gold can buy anything. He wants the artifact to secure favor with his board.
+      He is highly defensive of his reputation but has a secret vulnerability: {{buyer_leverage_desc}}. If players
+      discover and exploit this vulnerability (DC 14 Insight/Investigation), they can intimidate him into backing
+      down, or blackmail him into bidding on their behalf. He treats players with condescension unless they
+      make him feel threatened or foolish.
+    memoryKey: "karr-iron-delegate"
+
+goals:
+  hidden: true
+  primary:
+    - id: "artifact_stolen"
+      label: >
+        Players steal the artifact from the display case or Karr's possession without getting caught
+        (DC 15 Sleight of Hand / Stealth, or disabling the magical ward via DC 14 Arcana/Thieves' Tools).
+    - id: "fake_swapped"
+      label: >
+        Players create or procure a counterfeit replica of the artifact (DC 13 Sleight of Hand or Performance)
+        and successfully swap it during a distraction, leaving Karr to buy the fake.
+  secondary:
+    - id: "brawl_outbreak"
+      label: >
+        A fight breaks out, resulting in chaos. Players grab the artifact in the confusion and flee,
+        but make permanent enemies of both Karr (Iron Mountain Company) and Madame Vesper.
+    - id: "karr_wins"
+      label: >
+        Players fail to intervene or make a viable play. Karr wins the auction, secures the artifact,
+        and leaves under heavy guard. The opportunity is lost.
+
+sportsmanshipRules:
+  - "No casting offensive spells (Fireball, Charm Person) without triggering Madame Vesper's abjuration wards."
+  - "No claiming to have more gold than established in your inventory sheet."
+  - "No attacking guards or NPCs without expecting lethal retaliation from parlor security."
+  - "No teleporting the artifact directly out of the case while wards are active."
+  - >
+    If a player attempts something absurd or game-breaking, respond in-character
+    to redirect, or break character with:
+    "⚠️ That wasn't great sportsmanship. Let's keep it grounded — what would
+    your character realistically attempt here?"
+
+skillChecks:
+  steal_artifact_dc: 15
+  steal_artifact_skill: "Sleight of Hand or Stealth"
+  steal_artifact_note: >
+    Bypassing guards and grabbing the item. Disadvantage if the magical alarm ward has not been disabled.
+
+  disable_ward_dc: 14
+  disable_ward_skill: "Arcana or Thieves' Tools"
+  disable_ward_note: >
+    Disabling the abjuration hum surrounding the glass case. Failure alerts Madame Vesper.
+
+  read_buyer_dc: 12
+  read_buyer_skill: "Insight"
+  read_buyer_note: >
+    Observing Karr to detect his tells, identifying his hidden vulnerability (buyer_leverage).
+
+  negotiate_vesper_dc: 14
+  negotiate_vesper_skill: "Persuasion or Deception"
+  negotiate_vesper_note: >
+    Offering Madame Vesper secrets or trade arrangements of greater value than Karr's gold.
+
+randomizable:
+  - key: broker_name
+    source: vocabulary
+    category: names.tiefling.female
+    query: "common Tiefling female names in Mardonar"
+    fallback: "Madame Vesper"
+  - key: buyer_name
+    source: vocabulary
+    category: names.human.male
+    query: "common human male names in Mardonar"
+    fallback: "Karr"
+  - key: auction_item_desc
+    query: "valuable relics or rare magical items sought after by guilds in Mardonar"
+    fallback: "an Ancient Mawfang Bloodstone, carved with ancestral battle runes"
+  - key: buyer_leverage_desc
+    query: "secret flaws, debts, or scandals of wealthy merchants in Mardonar"
+    fallback: "he is an impostor bidding with stolen corporate funds and is terrified of audit"
+
+tools:
+  - skill_check_emit
+  - encounter_resolve
+  - context_recall
+  - goal_register
+  - foundry_lookup
+  - foundry_reward
+
+dmNotes: >
+  This is a social heist encounter. Direct combat is highly discouraged by the presence of abjuration wards
+  and heavy security. Reward players who focus on intrigue, pickpocketing, or social leverage.
+  
+  DYNAMIC GOAL INSTRUCTIONS:
+  If the players use Karr's leverage to manipulate the bidding process (e.g. blackmailing him into bidding
+  for them, or driving the price so high that he is exposed as a fraud and arrested), register a new
+  primary goal on the fly before resolving. E.g. 'market_manipulated' or 'buyer_blackmailed'.
diff --git a/specs/whispering-stone.yaml b/specs/whispering-stone.yaml
new file mode 100644
index 0000000..021cc80
--- /dev/null
+++ b/specs/whispering-stone.yaml
@@ -0,0 +1,138 @@
+encounterId: "mardonar-whispering-stone-007"
+title: "The Whispering Stone"
+
+setting:
+  location: "Stormscar Foothills — The Shattered Waypost Shrine"
+  mood: >
+    Freezing and ominous. A swirling vortex of icy wind whips snow across the pathway,
+    nestled between high rocky crags. In the center, a tall sentinel runestone stands fractured
+    in two, bleeding a pale blue, spectral frost onto the ground. The air is so cold it hurts
+    to breathe, and shadows seem to move independently of the light.
+  ambientNpcs: >
+    No living bystanders. Two frozen mountain goats stand like statues nearby, preserved by the
+    unnatural frost. The faint, rhythmic sound of clicking arachnid legs echoes from the cliffs above.
+
+openingNarrative: >
+    The mountain wind screeches through the gap, but the cold near the shrine is different — it is
+    hollow, biting, and smells of ancient dust. Huddled behind the altar, a young Half-Elf scribe clutches
+    a leather scroll, her fingers white with frost. "Stay back!" she shivers, her voice barely audible.
+    Standing in the path before her is {{ghost_name}}, a spectral figure in rusted plate armor. His eyes
+    glow with pale blue fire, and his translucent greatsword is raised high. "The vanguard must hold!" the
+    spirit bellows, swing of his blade sending a wave of ice across the road. "No legionnaires shall pass the
+    gate!" The spirit is clearly reliving his final battle, mistaking you for ancient invaders. If the scribe's
+    barriers fail, she will be frozen solid. What do you do?
+
+npcs:
+  - id: "liri-scribe-shrine"
+    name: "Liri"
+    nameKey: scribe_name
+    role: "Terrified acolyte scribe"
+    persona: >
+      A young Half-Elf woman in light gray robes, sent by the Mardonar Archives to study the shrine.
+      She is frozen in fear, unable to flee or think clearly. She has the scrolls containing the binding
+      ritual to repair the sentinel stone, but is too terrified to read them. If players protect her or
+      calm her down (DC 12 Persuasion/Insight), she can guide them on how to repair the stone. She will
+      not willingly leave the shrine without her research scrolls.
+    memoryKey: "liri-scribe-shrine"
+
+  - id: "the-shattered-captain"
+    name: "Captain Vane"
+    nameKey: ghost_name
+    role: "Fallen Vanguard Captain, frozen wraith"
+    persona: >
+      The ghost of a human captain who died defending the pass centuries ago. He is wreathed in frost
+      and carries a spectral greatsword that drains warmth. Vane is not malicious; he is lost in a traumatic
+      memory loop, believing he is still defending Mardonar from the Undead Legion. He treats anyone holding
+      a weapon or stepping forward as an undead invader. If players drop their weapons, speak in the ancient
+      Vanguard dialect (DC 12 History), or show him a Vanguard badge, he can be reasoned with and pacified.
+      Otherwise, he will attack with freezing sweeps.
+    memoryKey: "the-shattered-captain"
+
+goals:
+  hidden: true
+  primary:
+    - id: "spirit_calmed"
+      label: >
+        Players pacify Captain Vane by breaking his memory loop (DC 12 History to recall Vanguard custom,
+        or DC 14 Persuasion while unarmed). The captain recognizes them as allies and vanishes peacefully.
+    - id: "ward_restored"
+      label: >
+        Players protect Liri and complete the runic repair ritual (DC 13 Religion or Arcana) to mend the
+        fractured stone, binding the spirit back to rest.
+  secondary:
+    - id: "spirit_destroyed"
+      label: >
+        Players defeat the wraith in combat. This frees Liri, but permanently shatters the sentinel runestone,
+        leaving the pass unguarded against future Stormscar hauntings.
+    - id: "scribe_frozen"
+      label: >
+        Players flee or fail to intervene. The frost consumes Liri, turning her into an ice statue,
+        and the spirit remains hostile, blocking the road indefinitely.
+
+sportsmanshipRules:
+  - "No ignoring the environmental freezing hazard (freezing wind reduces movement or drains stamina)."
+  - "No using fire spells to instantly melt the ancient sentinel stone or the scribe's magical barriers."
+  - "No claiming prior acquaintance with Captain Vane without history validation."
+  - "No controlling the ghost's actions or commands directly."
+  - >
+    If a player attempts something absurd or game-breaking, respond in-character
+    to redirect, or break character with:
+    "⚠️ That wasn't great sportsmanship. Let's keep it grounded — what would
+    your character realistically attempt here?"
+
+skillChecks:
+  calm_spirit_dc: 14
+  calm_spirit_skill: "Persuasion (unarmed)"
+  calm_spirit_note: >
+    Players must drop their weapons first. Disadvantage if any player has hit the ghost this round.
+
+  recall_vanguard_dc: 12
+  recall_vanguard_skill: "History"
+  recall_vanguard_note: >
+    Recalling ancient military protocols or names from Captain Vane's era to disrupt his delusion.
+
+  repair_runes_dc: 13
+  repair_runes_skill: "Religion or Arcana"
+  repair_runes_note: >
+    Chanting the warding ritual while fitting the runestone fragments. Requires Liri's instructions.
+
+  dodge_frost_dc: 11
+  dodge_frost_skill: "Acrobatics or Constitution saving throw"
+  dodge_frost_note: >
+    Avoiding the freezing wind sweeps. Failure inflicts 1d4 cold damage and halves movement speed.
+
+randomizable:
+  - key: scribe_name
+    source: vocabulary
+    category: names.elf.female
+    query: "common Elven or Half-Elven female names in Mardonar"
+    fallback: "Liri"
+  - key: ghost_name
+    source: vocabulary
+    category: names.human.male
+    query: "common human male names of Mardonar's ancient soldiers"
+    fallback: "Captain Vane"
+  - key: frost_hazard_desc
+    query: "types of magical frost hazards or anomalies found in Stormscar mountains"
+    fallback: "Sapping Cold that dampens arcane energy"
+  - key: spider_rumor
+    query: "rumors about the Weaver of Ages and Phase Spiders in the Stormscar region"
+    fallback: "Phase Spiders are drawn to high concentrations of spectral energy"
+
+tools:
+  - skill_check_emit
+  - encounter_resolve
+  - context_recall
+  - goal_register
+  - foundry_lookup
+  - foundry_reward
+
+dmNotes: >
+  The heart of this encounter is tragedy. Captain Vane is a hero who doesn't know he died.
+  If players are aggressive, they destroy a historic protector. If they are patient, they save his soul.
+  
+  DYNAMIC GOAL INSTRUCTIONS:
+  If players find an alternative way to soothe the ghost, such as the Bard writing a dirge to absorb
+  Vane's sorrow into a relic/amulet, or tricking a nearby Phase Spider into attacking the ghost
+  to snap him out of it, use 'goal_register' to record the new primary outcome. E.g. 'grief_bound'
+  or 'spider_lured'.
diff --git a/src/bot/commands/actions.ts b/src/bot/commands/actions.ts
new file mode 100644
index 0000000..00e4d21
--- /dev/null
+++ b/src/bot/commands/actions.ts
@@ -0,0 +1,104 @@
+import { SlashCommandBuilder } from '@discordjs/builders';
+import { EmbedBuilder } from 'discord.js';
+import type { ChatInputCommandInteraction } from 'discord.js';
+import { characterRegistry } from '../../session/characterRegistry.js';
+import { getActorInventory, getActorSpells } from '../../vtt/foundryClient.js';
+import type { FoundryItem } from '../../vtt/foundryClient.js';
+
+export const data = new SlashCommandBuilder()
+  .setName('actions')
+  .setDescription("View your character's available attacks and spells from Foundry VTT");
+
+export async function execute(interaction: ChatInputCommandInteraction): Promise<void> {
+  const guildId = interaction.guildId;
+  if (!guildId) {
+    await interaction.reply({ content: 'This command must be used in a server.', ephemeral: true });
+    return;
+  }
+
+  const profile = await characterRegistry.get(guildId, interaction.user.id);
+  if (!profile?.foundryActorUuid) {
+    await interaction.reply({
+      content: 'No Foundry character linked. Use `/character register foundry` to link one.',
+      ephemeral: true,
+    });
+    return;
+  }
+
+  await interaction.deferReply({ ephemeral: true });
+
+  let inventory: FoundryItem[] = [];
+  let spells: FoundryItem[] = [];
+
+  try {
+    [inventory, spells] = await Promise.all([
+      getActorInventory(profile.foundryActorUuid),
+      getActorSpells(profile.foundryActorUuid),
+    ]);
+  } catch {
+    await interaction.editReply('Could not reach Foundry VTT. Is the relay connected?');
+    return;
+  }
+
+  // Weapons — equipped first, then unequipped
+  const weapons = inventory
+    .filter(i => i.type === 'weapon')
+    .sort((a, b) => (b.system?.equipped ? 1 : 0) - (a.system?.equipped ? 1 : 0));
+
+  // Spells split by prepared state and cantrip
+  const cantrips = spells.filter(s => s.system?.level === 0);
+  const prepared = spells.filter(s => s.system?.level !== 0 && s.system?.preparation?.prepared);
+  const unprepared = spells.filter(s => s.system?.level !== 0 && !s.system?.preparation?.prepared);
+
+  const embed = new EmbedBuilder()
+    .setTitle(`⚔️  ${profile.dndName} — Actions`)
+    .setColor(0xc0392b)
+    .setFooter({ text: 'Live from Foundry VTT' });
+
+  if (weapons.length === 0 && spells.length === 0) {
+    embed.setDescription('No weapons or spells found on this character.');
+    await interaction.editReply({ embeds: [embed] });
+    return;
+  }
+
+  if (weapons.length > 0) {
+    embed.addFields({
+      name: '🗡️  Weapons',
+      value: formatWeapons(weapons.slice(0, 15)),
+      inline: false,
+    });
+  }
+
+  if (cantrips.length > 0) {
+    embed.addFields({
+      name: '✨  Cantrips',
+      value: cantrips.map(s => `✨ ${s.name}`).join('\n').slice(0, 1024),
+      inline: false,
+    });
+  }
+
+  if (prepared.length > 0) {
+    embed.addFields({
+      name: '📖  Prepared Spells',
+      value: prepared.map(s => `📖 ${s.name} *(level ${s.system?.level ?? '?'})*`).join('\n').slice(0, 1024),
+      inline: false,
+    });
+  }
+
+  if (unprepared.length > 0) {
+    embed.addFields({
+      name: '◻️  Known / Unprepared',
+      value: unprepared.map(s => `◻️ ${s.name} *(level ${s.system?.level ?? '?'})*`).join('\n').slice(0, 1024),
+      inline: false,
+    });
+  }
+
+  await interaction.editReply({ embeds: [embed] });
+}
+
+function formatWeapons(items: FoundryItem[]): string {
+  return items.map(w => {
+    const equipped = w.system?.equipped ? '🗡️' : '⬜';
+    return `${equipped} ${w.name}`;
+  }).join('\n');
+}
diff --git a/src/bot/commands/character.ts b/src/bot/commands/character.ts
new file mode 100644
index 0000000..492f14c
--- /dev/null
+++ b/src/bot/commands/character.ts
@@ -0,0 +1,558 @@
+import { SlashCommandBuilder } from '@discordjs/builders';
+import {
+  EmbedBuilder,
+  ActionRowBuilder,
+  ModalBuilder,
+  TextInputBuilder,
+  TextInputStyle,
+} from 'discord.js';
+import type {
+  ChatInputCommandInteraction,
+  ModalSubmitInteraction,
+} from 'discord.js';
+import { characterRegistry } from '../../session/characterRegistry.js';
+import { sendWelcomeDM } from '../lib/welcomeDM.js';
+import {
+  searchActors, filterPlayerActors, giveItem,
+  getActorDetails, getActorInventory, getActorSpells,
+  formatActorSummary, formatInventory, formatSpells,
+} from '../../vtt/foundryClient.js';
+import { log } from '../../lib/logger.js';
+import { config } from '../../config.js';
+
+export const data = new SlashCommandBuilder()
+  .setName('character')
+  .setDescription('Manage your D&D character sheet')
+  .addSubcommandGroup(group =>
+    group
+      .setName('register')
+      .setDescription('Register your character')
+      .addSubcommand(sub =>
+        sub.setName('foundry').setDescription('Browse and claim a Foundry VTT actor'),
+      )
+      .addSubcommand(sub =>
+        sub.setName('custom').setDescription('Set a custom character'),
+      ),
+  )
+  .addSubcommandGroup(group =>
+    group
+      .setName('admin')
+      .setDescription('DM-only administration commands')
+      .addSubcommand(sub =>
+        sub.setName('list').setDescription('Show all guild character registrations'),
+      )
+      .addSubcommand(sub =>
+        sub
+          .setName('remove')
+          .setDescription("Remove a specific user's registration")
+          .addUserOption(o =>
+            o.setName('user').setDescription('Discord user to remove').setRequired(true),
+          ),
+      )
+      .addSubcommand(sub =>
+        sub.setName('give').setDescription('Give an item to a Foundry character'),
+      ),
+  )
+  .addSubcommand(sub =>
+    sub.setName('show').setDescription('Display your current character profile'),
+  )
+  .addSubcommand(sub =>
+    sub.setName('view').setDescription('Fetch live character stats from Foundry VTT'),
+  )
+  .addSubcommand(sub =>
+    sub.setName('clear').setDescription('Delete your character profile'),
+  );
+
+export async function execute(interaction: ChatInputCommandInteraction): Promise<void> {
+  const guildId = interaction.guildId;
+  if (!guildId) {
+    await interaction.reply({ content: 'This command must be used in a server.', ephemeral: true });
+    return;
+  }
+
+  const group = interaction.options.getSubcommandGroup(false);
+
+  if (group === 'register') {
+    const sub = interaction.options.getSubcommand();
+    if (sub === 'foundry') {
+      await handleRegisterFoundry(interaction);
+    } else if (sub === 'custom') {
+      await handleRegisterCustom(interaction);
+    }
+  } else if (group === 'admin') {
+    if (!isAllowedUser(interaction)) {
+      await interaction.reply({
+        content: 'You are not authorised to use admin commands.',
+        ephemeral: true,
+      });
+      return;
+    }
+    const sub = interaction.options.getSubcommand();
+    if (sub === 'list') {
+      await handleAdminList(interaction, guildId);
+    } else if (sub === 'remove') {
+      await handleAdminRemove(interaction, guildId);
+    } else if (sub === 'give') {
+      await handleAdminGive(interaction);
+    }
+  } else {
+    const sub = interaction.options.getSubcommand();
+    if (sub === 'show') {
+      await handleShow(interaction, guildId);
+    } else if (sub === 'view') {
+      await handleView(interaction, guildId);
+    } else if (sub === 'clear') {
+      await handleClear(interaction, guildId);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+function isAllowedUser(interaction: ChatInputCommandInteraction): boolean {
+  return (
+    config.DISCORD_ALLOWED_USERS.length === 0 ||
+    config.DISCORD_ALLOWED_USERS.includes(interaction.user.id)
+  );
+}
+
+// ---------------------------------------------------------------------------
+// /character register foundry
+// ---------------------------------------------------------------------------
+
+async function handleRegisterFoundry(
+  interaction: ChatInputCommandInteraction,
+): Promise<void> {
+  if (!config.VTT_API_KEY) {
+    await interaction.reply({
+      content: 'Foundry VTT is not configured on this server. Use `/character register custom` instead.',
+      ephemeral: true,
+    });
+    return;
+  }
+
+  const modal = new ModalBuilder()
+    .setCustomId('foundry_link_modal')
+    .setTitle('Link Foundry Character');
+
+  modal.addComponents(
+    new ActionRowBuilder<TextInputBuilder>().addComponents(
+      new TextInputBuilder()
+        .setCustomId('foundry_character_name')
+        .setLabel('Your character name in Foundry')
+        .setStyle(TextInputStyle.Short)
+        .setPlaceholder('e.g. Zalram Cloudwalker')
+        .setRequired(true)
+        .setMaxLength(100),
+    ),
+  );
+
+  await interaction.showModal(modal);
+}
+
+// ---------------------------------------------------------------------------
+// foundry link modal submitted → search relay by name, save to registry
+// Exported so index.ts can route ModalSubmit interactions here.
+// ---------------------------------------------------------------------------
+
+export async function handleFoundryLinkModal(
+  interaction: ModalSubmitInteraction,
+): Promise<void> {
+  const characterName = interaction.fields.getTextInputValue('foundry_character_name').trim();
+  const guildId = interaction.guildId;
+  if (!guildId) {
+    await interaction.reply({ content: 'This must be used in a server.', ephemeral: true });
+    return;
+  }
+
+  await interaction.deferReply({ ephemeral: true });
+
+  let match: Awaited<ReturnType<typeof searchActors>>[number] | undefined;
+  try {
+    const results = await searchActors(characterName, 10);
+    match = filterPlayerActors(results)[0];
+  } catch (err) {
+    await interaction.editReply({ content: `Could not reach Foundry VTT: ${String(err)}` });
+    return;
+  }
+
+  if (!match) {
+    await interaction.editReply({
+      content: `No Foundry player character found matching **"${characterName}"**. Check the name and try again.`,
+    });
+    return;
+  }
+
+  const existing = await characterRegistry.get(guildId, interaction.user.id);
+
+  await characterRegistry.set(guildId, {
+    discordId: interaction.user.id,
+    dndName: match.name,
+    source: 'foundry',
+    foundryActorUuid: match.uuid,
+    ...(existing && { characterClass: existing.characterClass }),
+    ...(existing && { level: existing.level }),
+    ...(existing && { race: existing.race }),
+    ...(existing && { backstory: existing.backstory }),
+  });
+
+  if (!existing) {
+    sendWelcomeDM(interaction.user, interaction.guild?.name).catch(() => null);
+  }
+
+  await interaction.editReply({
+    content: `✅ Linked to **${match.name}**. Your Foundry character is connected.`,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// /character register custom — shows a modal form
+// ---------------------------------------------------------------------------
+
+async function handleRegisterCustom(
+  interaction: ChatInputCommandInteraction,
+): Promise<void> {
+  const modal = new ModalBuilder()
+    .setCustomId('character_custom_modal')
+    .setTitle('Register Custom Character');
+
+  modal.addComponents(
+    new ActionRowBuilder<TextInputBuilder>().addComponents(
+      new TextInputBuilder()
+        .setCustomId('char_name')
+        .setLabel('Character Name')
+        .setStyle(TextInputStyle.Short)
+        .setRequired(true)
+        .setMaxLength(100),
+    ),
+    new ActionRowBuilder<TextInputBuilder>().addComponents(
+      new TextInputBuilder()
+        .setCustomId('char_pronouns')
+        .setLabel('Pronouns')
+        .setStyle(TextInputStyle.Short)
+        .setRequired(false)
+        .setPlaceholder('e.g. she/her, they/them, he/him')
+        .setMaxLength(50),
+    ),
+    new ActionRowBuilder<TextInputBuilder>().addComponents(
+      new TextInputBuilder()
+        .setCustomId('char_class')
+        .setLabel('Class')
+        .setStyle(TextInputStyle.Short)
+        .setRequired(false)
+        .setPlaceholder('e.g. Wizard, Fighter, Rogue')
+        .setMaxLength(80),
+    ),
+    new ActionRowBuilder<TextInputBuilder>().addComponents(
+      new TextInputBuilder()
+        .setCustomId('char_race')
+        .setLabel('Race')
+        .setStyle(TextInputStyle.Short)
+        .setRequired(false)
+        .setPlaceholder('e.g. Elf, Human, Dwarf')
+        .setMaxLength(80),
+    ),
+    new ActionRowBuilder<TextInputBuilder>().addComponents(
+      new TextInputBuilder()
+        .setCustomId('char_backstory')
+        .setLabel('Backstory')
+        .setStyle(TextInputStyle.Paragraph)
+        .setRequired(false)
+        .setMaxLength(200),
+    ),
+  );
+
+  await interaction.showModal(modal);
+}
+
+export async function handleCustomRegisterModal(
+  interaction: ModalSubmitInteraction,
+): Promise<void> {
+  const guildId = interaction.guildId;
+  if (!guildId) {
+    await interaction.reply({ content: 'This must be used in a server.', ephemeral: true });
+    return;
+  }
+
+  const name = interaction.fields.getTextInputValue('char_name').trim();
+  const pronouns = interaction.fields.getTextInputValue('char_pronouns').trim() || undefined;
+  const characterClass = interaction.fields.getTextInputValue('char_class').trim() || undefined;
+  const race = interaction.fields.getTextInputValue('char_race').trim() || undefined;
+  const backstory = interaction.fields.getTextInputValue('char_backstory').trim() || undefined;
+
+  const existing = await characterRegistry.get(guildId, interaction.user.id);
+
+  await characterRegistry.set(guildId, {
+    discordId: interaction.user.id,
+    dndName: name,
+    source: 'custom',
+    ...(existing?.foundryActorUuid && { foundryActorUuid: existing.foundryActorUuid }),
+    ...(existing?.level && { level: existing.level }),
+    ...(pronouns && { pronouns }),
+    ...(characterClass && { characterClass }),
+    ...(race && { race }),
+    ...(backstory && { backstory }),
+  });
+
+  if (!existing) {
+    sendWelcomeDM(interaction.user, interaction.guild?.name).catch(() => null);
+  }
+
+  const details = [race, characterClass].filter(Boolean).join(' ');
+  await interaction.reply({
+    content: `✅ Character saved: **${name}**${details ? ` — ${details}` : ''}`,
+    ephemeral: true,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// /character show
+// ---------------------------------------------------------------------------
+
+async function handleShow(
+  interaction: ChatInputCommandInteraction,
+  guildId: string,
+): Promise<void> {
+  const profile = await characterRegistry.get(guildId, interaction.user.id);
+  if (!profile) {
+    await interaction.reply({
+      content: 'No character profile found. Use `/character register` to get started.',
+      ephemeral: true,
+    });
+    return;
+  }
+
+  const embed = new EmbedBuilder()
+    .setTitle(`${profile.dndName} — Character Sheet`)
+    .setColor(0x3498db)
+    .setFooter({ text: 'Character profile · GraphMCP' });
+
+  if (profile.pronouns) {
+    embed.addFields({ name: 'Pronouns', value: profile.pronouns, inline: true });
+  }
+  if (profile.characterClass) {
+    embed.addFields({ name: 'Class', value: profile.characterClass, inline: true });
+  }
+  if (profile.race) {
+    embed.addFields({ name: 'Race', value: profile.race, inline: true });
+  }
+  if (profile.level !== undefined) {
+    embed.addFields({ name: 'Level', value: String(profile.level), inline: true });
+  }
+  if (profile.foundryActorUuid) {
+    embed.addFields({ name: 'Foundry', value: '✅ Linked', inline: true });
+  }
+  if (profile.backstory) {
+    embed.addFields({ name: 'Backstory', value: profile.backstory, inline: false });
+  }
+
+  await interaction.reply({ embeds: [embed], ephemeral: true });
+}
+
+// ---------------------------------------------------------------------------
+// /character view — live Foundry stats
+// ---------------------------------------------------------------------------
+
+async function handleView(
+  interaction: ChatInputCommandInteraction,
+  guildId: string,
+): Promise<void> {
+  await interaction.deferReply({ ephemeral: true });
+
+  const profile = await characterRegistry.get(guildId, interaction.user.id);
+  if (!profile) {
+    await interaction.editReply(
+      'No character profile found. Use `/character register` to get started.',
+    );
+    return;
+  }
+
+  if (!profile.foundryActorUuid) {
+    await interaction.editReply(
+      'Your character isn\'t linked to Foundry VTT. ' +
+      'Use `/character register foundry` to link one, or `/character show` to see your stored profile.',
+    );
+    return;
+  }
+
+  let details, inventory, spells;
+  try {
+    [details, inventory, spells] = await Promise.all([
+      getActorDetails(profile.foundryActorUuid),
+      getActorInventory(profile.foundryActorUuid),
+      getActorSpells(profile.foundryActorUuid),
+    ]);
+  } catch (err) {
+    log.error('cmd', '/character view relay error', { error: String(err) });
+    await interaction.editReply(
+      'Could not fetch character data from Foundry VTT. The relay may be unavailable.',
+    );
+    return;
+  }
+
+  const embed = new EmbedBuilder()
+    .setTitle(`📜 ${profile.dndName}`)
+    .setDescription(formatActorSummary(details))
+    .setColor(0x3498db);
+
+  const inventoryText = formatInventory(inventory);
+  if (inventoryText !== 'No items.') {
+    embed.addFields({ name: '🎒 Inventory', value: inventoryText.slice(0, 1024) });
+  }
+
+  const spellText = formatSpells(spells);
+  if (spellText !== 'No spells.') {
+    embed.addFields({ name: '✨ Spells', value: spellText.slice(0, 1024) });
+  }
+
+  await interaction.editReply({ embeds: [embed] });
+}
+
+// ---------------------------------------------------------------------------
+// /character clear
+// ---------------------------------------------------------------------------
+
+async function handleClear(
+  interaction: ChatInputCommandInteraction,
+  guildId: string,
+): Promise<void> {
+  await characterRegistry.delete(guildId, interaction.user.id);
+  await interaction.reply({ content: 'Your character profile has been cleared.', ephemeral: true });
+}
+
+// ---------------------------------------------------------------------------
+// /character admin list
+// ---------------------------------------------------------------------------
+
+async function handleAdminList(
+  interaction: ChatInputCommandInteraction,
+  guildId: string,
+): Promise<void> {
+  const profiles = await characterRegistry.list(guildId);
+  if (profiles.length === 0) {
+    await interaction.reply({
+      content: 'No characters registered in this server.',
+      ephemeral: true,
+    });
+    return;
+  }
+
+  const sorted = [...profiles].sort((a, b) => a.dndName.localeCompare(b.dndName));
+
+  const embed = new EmbedBuilder().setTitle('Registered Characters').setColor(0x3498db);
+
+  for (const profile of sorted.slice(0, 25)) {
+    const sourceTag = profile.source === 'foundry' ? '[Foundry]' : '[Custom]';
+    const foundryTag = profile.foundryActorUuid ? ' · Foundry linked' : '';
+    embed.addFields({
+      name: profile.dndName,
+      value: `<@${profile.discordId}> ${sourceTag}${foundryTag}`,
+      inline: true,
+    });
+  }
+
+  await interaction.reply({ embeds: [embed], ephemeral: true });
+}
+
+// ---------------------------------------------------------------------------
+// /character admin remove
+// ---------------------------------------------------------------------------
+
+async function handleAdminRemove(
+  interaction: ChatInputCommandInteraction,
+  guildId: string,
+): Promise<void> {
+  const targetUser = interaction.options.getUser('user', true);
+  await characterRegistry.delete(guildId, targetUser.id);
+  await interaction.reply({
+    content: `Removed character registration for **${targetUser.username}**.`,
+    ephemeral: true,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// /character admin give — show a two-field modal immediately.
+// The relay search-by-name approach is used on submit so any world PC is
+// findable regardless of alphabetical position in the full actor list.
+// ---------------------------------------------------------------------------
+
+async function handleAdminGive(interaction: ChatInputCommandInteraction): Promise<void> {
+  if (!config.VTT_API_KEY) {
+    await interaction.reply({
+      content: 'Foundry VTT is not configured on this server.',
+      ephemeral: true,
+    });
+    return;
+  }
+
+  const modal = new ModalBuilder()
+    .setCustomId('give_modal')
+    .setTitle('Give Item to Character');
+
+  modal.addComponents(
+    new ActionRowBuilder<TextInputBuilder>().addComponents(
+      new TextInputBuilder()
+        .setCustomId('give_character_name')
+        .setLabel('Character name')
+        .setStyle(TextInputStyle.Short)
+        .setPlaceholder('e.g. Zalram Cloudwalker')
+        .setRequired(true)
+        .setMaxLength(100),
+    ),
+    new ActionRowBuilder<TextInputBuilder>().addComponents(
+      new TextInputBuilder()
+        .setCustomId('give_item_name')
+        .setLabel('Item name')
+        .setStyle(TextInputStyle.Short)
+        .setPlaceholder('e.g. Potion of Healing')
+        .setRequired(true)
+        .setMaxLength(100),
+    ),
+  );
+
+  await interaction.showModal(modal);
+}
+
+// ---------------------------------------------------------------------------
+// give — modal submitted → search relay by name, then call giveItem.
+// Exported so index.ts can route ModalSubmit interactions here.
+// ---------------------------------------------------------------------------
+
+export async function handleGiveModal(interaction: ModalSubmitInteraction): Promise<void> {
+  const characterName = interaction.fields.getTextInputValue('give_character_name').trim();
+  const itemName = interaction.fields.getTextInputValue('give_item_name').trim();
+
+  await interaction.deferReply({ ephemeral: true });
+
+  let match: Awaited<ReturnType<typeof searchActors>>[number] | undefined;
+  try {
+    const results = await searchActors(characterName, 10);
+    match = filterPlayerActors(results)[0];
+  } catch (err) {
+    await interaction.editReply({ content: `Could not reach Foundry VTT: ${String(err)}` });
+    return;
+  }
+
+  if (!match) {
+    await interaction.editReply({
+      content: `No Foundry player character found matching **"${characterName}"**.`,
+    });
+    return;
+  }
+
+  log.info('relay', `give "${itemName}" → ${match.name} (${match.uuid})`);
+
+  try {
+    await giveItem(match.uuid, itemName);
+    await interaction.editReply({
+      content: `✅ **${itemName}** given to **${match.name}**.`,
+    });
+  } catch (err) {
+    log.error('relay', 'giveItem failed', { error: String(err) });
+    await interaction.editReply({
+      content: `❌ Failed to give item: ${String(err)}`,
+    });
+  }
+}
diff --git a/src/bot/commands/dndname.ts b/src/bot/commands/dndname.ts
new file mode 100644
index 0000000..c6347a6
--- /dev/null
+++ b/src/bot/commands/dndname.ts
@@ -0,0 +1,53 @@
+import { SlashCommandBuilder } from '@discordjs/builders';
+import type { ChatInputCommandInteraction, Client } from 'discord.js';
+import { playerRegistry } from '../../session/playerRegistry.js';
+import { replayHeldMessages } from '../handlers/messageRouter.js';
+import { sendWelcomeDM } from '../lib/welcomeDM.js';
+
+export const data = new SlashCommandBuilder()
+  .setName('dndname')
+  .setDescription('Manage your D&D character name for encounters')
+  .addSubcommand(sub =>
+    sub
+      .setName('set')
+      .setDescription('Register or update your character name')
+      .addStringOption(o =>
+        o.setName('name').setDescription('Your character name').setRequired(true),
+      ),
+  )
+  .addSubcommand(sub => sub.setName('show').setDescription('Show your current character name'))
+  .addSubcommand(sub => sub.setName('clear').setDescription('Remove your character registration'));
+
+export async function execute(interaction: ChatInputCommandInteraction, client: Client): Promise<void> {
+  const guildId = interaction.guildId;
+  if (!guildId) {
+    await interaction.reply({ content: 'This command must be used in a server.', ephemeral: true });
+    return;
+  }
+
+  const userId = interaction.user.id;
+  const sub = interaction.options.getSubcommand();
+
+  if (sub === 'set') {
+    const name = interaction.options.getString('name', true);
+    const isFirstTime = !(await playerRegistry.get(guildId, userId));
+    await playerRegistry.set(guildId, userId, name);
+    await interaction.reply({ content: `Registered as **${name}**.`, ephemeral: true });
+    if (isFirstTime) {
+      sendWelcomeDM(interaction.user, interaction.guild?.name).catch(() => null);
+    }
+    // Replay any messages held while the player was unregistered
+    await replayHeldMessages(userId, guildId, client).catch(err =>
+      console.error('[dndname] replayHeldMessages failed:', err),
+    );
+  } else if (sub === 'show') {
+    const player = await playerRegistry.get(guildId, userId);
+    await interaction.reply({
+      content: player ? `Your character is **${player.dndName}**.` : 'No character registered.',
+      ephemeral: true,
+    });
+  } else if (sub === 'clear') {
+    await playerRegistry.delete(guildId, userId);
+    await interaction.reply({ content: 'Character registration cleared.', ephemeral: true });
+  }
+}
diff --git a/src/bot/commands/encounter.ts b/src/bot/commands/encounter.ts
new file mode 100644
index 0000000..d628d1a
--- /dev/null
+++ b/src/bot/commands/encounter.ts
@@ -0,0 +1,434 @@
+import { SlashCommandBuilder } from '@discordjs/builders';
+import { EmbedBuilder, AttachmentBuilder } from 'discord.js';
+import type { ChatInputCommandInteraction, TextChannel } from 'discord.js';
+import { buildEncounterListEmbed } from '../embeds/encounterDiscovery.js';
+import { readdirSync } from 'fs';
+import { loadSpec } from '../../spec/loader.js';
+import { sessionManager } from '../../session/sessionManager.js';
+import { playerRegistry } from '../../session/playerRegistry.js';
+import { config } from '../../config.js';
+import { queryAsNPC, formatNPCMemory, logEncounter } from '../../graphmcp/client.js';
+import { resolveRandomizables } from '../../graphmcp/loreResolver.js';
+import { buildOpeningNarrative } from '../../harness/promptBuilder.js';
+import { callLLM } from '../../harness/llmClient.js';
+import { incrementTally, readTally, writeSummary, getLatestSummary } from '../../session/encounterLog.js';
+import type { SessionState, ChatMessage } from '../../types/index.js';
+
+export const data = new SlashCommandBuilder()
+  .setName('encounter')
+  .setDescription('Manage D&D encounters')
+  .addSubcommand(sub =>
+    sub
+      .setName('start')
+      .setDescription('Load a spec and open an encounter thread')
+      .addStringOption(o =>
+        o.setName('spec').setDescription('Spec name (file in ./specs/)').setRequired(true),
+      ),
+  )
+  .addSubcommand(sub =>
+    sub.setName('random').setDescription('Start a randomly selected encounter'),
+  )
+  .addSubcommand(sub =>
+    sub.setName('status').setDescription('Show current encounter status'),
+  )
+  .addSubcommand(sub =>
+    sub.setName('stats').setDescription('Show encounter run statistics'),
+  )
+  .addSubcommand(sub =>
+    sub.setName('audit').setDescription('Send the most recent encounter summary file'),
+  )
+  .addSubcommand(sub =>
+    sub
+      .setName('end')
+      .setDescription('Force-resolve the current encounter (admin override)')
+      .addStringOption(o =>
+        o.setName('notes')
+          .setDescription('DM notes on what happened — logged to the knowledge graph')
+          .setRequired(false),
+      ),
+  )
+  .addSubcommand(sub =>
+    sub.setName('list').setDescription('Show all active encounters in this server'),
+  );
+
+export async function execute(interaction: ChatInputCommandInteraction): Promise<void> {
+  const guildId = interaction.guildId;
+  if (!guildId) {
+    await interaction.reply({ content: 'This command must be used in a server.', ephemeral: true });
+    return;
+  }
+
+  // User allowlist — empty list means everyone is allowed
+  if (
+    config.DISCORD_ALLOWED_USERS.length > 0 &&
+    !config.DISCORD_ALLOWED_USERS.includes(interaction.user.id)
+  ) {
+    await interaction.reply({ content: 'You are not authorised to use encounter commands.', ephemeral: true });
+    return;
+  }
+
+  const sub = interaction.options.getSubcommand();
+
+  if (sub === 'start') {
+    const specName = interaction.options.getString('spec', true);
+    await handleStart(interaction, guildId, specName);
+  } else if (sub === 'random') {
+    await handleRandom(interaction, guildId);
+  } else if (sub === 'status') {
+    await handleStatus(interaction);
+  } else if (sub === 'stats') {
+    await handleStats(interaction);
+  } else if (sub === 'audit') {
+    await handleAudit(interaction);
+  } else if (sub === 'end') {
+    await handleEnd(interaction);
+  } else if (sub === 'list') {
+    await handleList(interaction, guildId);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+// Replace {{key}} placeholders in text with resolved context values.
+function interpolate(text: string, ctx: Record<string, string>): string {
+  return text.replace(/\{\{(\w+)\}\}/g, (_, key: string) => ctx[key] ?? `{{${key}}}`);
+}
+
+// Apply resolved context to NPC display names and setting location.
+// Original spec is not mutated — returns a shallow copy with names replaced.
+function applyResolved(
+  spec: import('../../types/index.js').EncounterSpec,
+  ctx: Record<string, string>,
+): import('../../types/index.js').EncounterSpec {
+  const npcs = spec.npcs.map(npc => {
+    const resolved = npc.nameKey ? ctx[npc.nameKey] : undefined;
+    return resolved ? { ...npc, name: resolved } : npc;
+  });
+  const location = interpolate(spec.setting.location, ctx);
+  return {
+    ...spec,
+    npcs,
+    setting: { ...spec.setting, location },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// /encounter start
+// ---------------------------------------------------------------------------
+
+async function handleStart(
+  interaction: ChatInputCommandInteraction,
+  guildId: string,
+  specName: string,
+): Promise<void> {
+  if (!config.DISCORD_ALLOWED_CHANNELS.includes(interaction.channelId)) {
+    await interaction.reply({ content: 'Encounters are not enabled in this channel.', ephemeral: true });
+    return;
+  }
+
+  await interaction.deferReply({ ephemeral: true });
+
+  let spec;
+  try {
+    spec = loadSpec(specName);
+  } catch (err) {
+    await interaction.editReply(`Failed to load spec **${specName}**: ${String(err)}`);
+    return;
+  }
+
+  const channel = interaction.channel as TextChannel;
+  if (!channel?.isTextBased()) {
+    await interaction.editReply('Run this command in a text channel.');
+    return;
+  }
+
+  const thread = await channel.threads.create({
+    name: `⚔️ ${spec.title}`,
+    autoArchiveDuration: 1440,
+    reason: `Encounter: ${spec.encounterId}`,
+  });
+
+  // Resolve randomizable details first — names are needed for NPC memory queries
+  // and for interpolating the opening narrative.
+  const resolvedContext = await resolveRandomizables(spec.randomizable ?? []);
+
+  // Apply resolved names to NPC display names and interpolate {{key}} in location.
+  const resolvedSpec = applyResolved(spec, resolvedContext);
+
+  const npcMemories: Record<string, string> = {};
+  for (const npc of resolvedSpec.npcs) {
+    if (npc.memoryKey) {
+      try {
+        const result = await queryAsNPC(
+          // Use memoryKey (stable canonical identity) — NOT the session display name,
+          // which may be randomized. This keeps NPC memories consistent across sessions.
+          npc.memoryKey,
+          `What do I know about ${resolvedSpec.setting.location} and any adventurers or events I have witnessed?`,
+          config.GRAPHMCP_NPC_MEMORY_LIMIT,
+        );
+        npcMemories[npc.id] = formatNPCMemory(result);
+      } catch (err) {
+        console.warn(`[encounter] failed to load memory for ${npc.memoryKey}:`, err);
+        npcMemories[npc.id] = 'No prior encounters on record — first meeting.';
+      }
+    }
+  }
+
+  const openingText = interpolate(buildOpeningNarrative(resolvedSpec), resolvedContext);
+  const openingMessage: ChatMessage = {
+    role: 'assistant',
+    content: openingText,
+    pinned: true,
+    timestamp: Date.now(),
+  };
+
+  const now = Date.now();
+  const state: SessionState = {
+    encounterId: resolvedSpec.encounterId,
+    threadId: thread.id,
+    guildId,
+    spec: resolvedSpec,
+    players: {},
+    history: [openingMessage],
+    phase: 'open',
+    heldMessages: [],
+    npcMemories,
+    resolvedContext,
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  await sessionManager.create(thread.id, state);
+  incrementTally(specName);
+  await thread.send(openingText);
+  await interaction.editReply(`Encounter started: <#${thread.id}>`);
+}
+
+// ---------------------------------------------------------------------------
+// /encounter random
+// ---------------------------------------------------------------------------
+
+async function handleRandom(
+  interaction: ChatInputCommandInteraction,
+  guildId: string,
+): Promise<void> {
+  let specs: string[];
+  try {
+    specs = readdirSync(config.SPECS_DIR)
+      .filter(f => f.endsWith('.yaml') || f.endsWith('.yml'))
+      .map(f => f.replace(/\.ya?ml$/, ''));
+  } catch (err) {
+    await interaction.reply({ content: `Could not read specs directory: ${String(err)}`, ephemeral: true });
+    return;
+  }
+
+  if (specs.length === 0) {
+    await interaction.reply({ content: 'No spec files found in specs/ directory.', ephemeral: true });
+    return;
+  }
+
+  const specName = specs[Math.floor(Math.random() * specs.length)];
+  await handleStart(interaction, guildId, specName);
+}
+
+// ---------------------------------------------------------------------------
+// /encounter status
+// ---------------------------------------------------------------------------
+
+async function handleStatus(interaction: ChatInputCommandInteraction): Promise<void> {
+  const channel = interaction.channel;
+  if (!channel?.isThread()) {
+    await interaction.reply({ content: 'Run this inside an encounter thread.', ephemeral: true });
+    return;
+  }
+
+  const session = await sessionManager.get(channel.id);
+  if (!session) {
+    await interaction.reply({ content: 'No active encounter in this thread.', ephemeral: true });
+    return;
+  }
+
+  const playerList = Object.values(session.players).map(p => p.dndName).join(', ') || 'None yet';
+
+  const embed = new EmbedBuilder()
+    .setTitle(`Status — ${session.spec.title}`)
+    .addFields(
+      { name: 'Phase', value: session.phase, inline: true },
+      { name: 'Players', value: playerList, inline: true },
+      { name: 'History', value: `${session.history.length} messages`, inline: true },
+      { name: 'Held messages', value: String(session.heldMessages.length), inline: true },
+    )
+    .setColor(0x3498db);
+
+  await interaction.reply({ embeds: [embed], ephemeral: true });
+}
+
+// ---------------------------------------------------------------------------
+// /encounter stats
+// ---------------------------------------------------------------------------
+
+async function handleStats(interaction: ChatInputCommandInteraction): Promise<void> {
+  const tally = readTally();
+  const entries = Object.entries(tally).sort((a, b) => b[1].runs - a[1].runs);
+
+  if (entries.length === 0) {
+    await interaction.reply({ content: 'No encounters have been run yet.', ephemeral: true });
+    return;
+  }
+
+  const lines = entries.map(([name, data]) => {
+    const last = new Date(data.lastRun).toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric' });
+    return `**${name}** — ${data.runs} run${data.runs === 1 ? '' : 's'} (last: ${last})`;
+  });
+
+  const embed = new EmbedBuilder()
+    .setTitle('Encounter Stats')
+    .setDescription(lines.join('\n'))
+    .setColor(0x2ecc71);
+
+  await interaction.reply({ embeds: [embed], ephemeral: true });
+}
+
+// ---------------------------------------------------------------------------
+// /encounter audit
+// ---------------------------------------------------------------------------
+
+async function handleAudit(interaction: ChatInputCommandInteraction): Promise<void> {
+  const filePath = getLatestSummary();
+  if (!filePath) {
+    await interaction.reply({ content: 'No encounter summaries on disk yet.', ephemeral: true });
+    return;
+  }
+
+  const attachment = new AttachmentBuilder(filePath);
+  await interaction.reply({ files: [attachment], ephemeral: true });
+}
+
+// ---------------------------------------------------------------------------
+// /encounter end
+// ---------------------------------------------------------------------------
+
+async function handleEnd(interaction: ChatInputCommandInteraction): Promise<void> {
+  const channel = interaction.channel;
+  if (!channel?.isThread()) {
+    await interaction.reply({ content: 'Run this inside an encounter thread.', ephemeral: true });
+    return;
+  }
+
+  // Defer immediately — the LLM summary call below can take several seconds.
+  await interaction.deferReply({ ephemeral: true });
+
+  const session = await sessionManager.get(channel.id);
+  if (!session) {
+    await interaction.editReply('No active encounter in this thread.');
+    return;
+  }
+
+  if (session.phase === 'resolved') {
+    await interaction.editReply('Encounter is already resolved.');
+    return;
+  }
+
+  const dmNotes = interaction.options.getString('notes') ?? '';
+  const outcomeId = 'admin_end';
+
+  // Ask the LLM to summarize the encounter from the session history
+  const transcript = session.history
+    .filter(m => m.role === 'user' || m.role === 'assistant')
+    .map(m => `[${m.role}] ${m.content}`)
+    .join('\n');
+
+  const now = Date.now();
+  const summaryMessages = [
+    {
+      role: 'system' as const,
+      content: 'You are a scribe. Summarize the following D&D encounter transcript in 2–4 sentences for a historical record. Be specific: name who was involved, what happened, and how it ended. Do not editorialize.',
+      timestamp: now,
+    },
+    {
+      role: 'user' as const,
+      content: [
+        `Encounter: ${session.spec.title}`,
+        `Location: ${session.spec.setting.location}`,
+        dmNotes ? `DM notes: ${dmNotes}` : '',
+        '',
+        transcript,
+      ].filter(Boolean).join('\n'),
+      timestamp: now,
+    },
+  ];
+
+  let summary: string;
+  try {
+    const result = await callLLM(summaryMessages);
+    summary = result.narrative || `Encounter ended by ${interaction.user.username}.`;
+  } catch {
+    summary = dmNotes || `Encounter ended by ${interaction.user.username}.`;
+  }
+
+  await sessionManager.update(channel.id, {
+    phase: 'resolved',
+    outcome: outcomeId,
+    outcomeSummary: summary,
+  });
+
+  writeSummary(session, outcomeId, summary);
+
+  // Log to GraphMCP so NPCs remember what happened
+  const participants = [
+    ...session.spec.npcs.map(n => n.name),
+    ...Object.values(session.players).map(p => p.dndName),
+  ].join(', ');
+
+  logEncounter({
+    title: `${session.spec.title} — admin end`,
+    participants,
+    summary: dmNotes || `Encounter ended early by ${interaction.user.username}.`,
+    location: session.spec.setting.location,
+    type: 'encounter',
+  }).catch(err => console.error('[encounter end] logEncounter failed:', err));
+
+  const dm = await playerRegistry.get(session.guildId, interaction.user.id);
+  await channel.send(
+    `*The encounter has been ended by ${dm?.dndName ?? interaction.user.username}. The thread will now archive.*`,
+  );
+  await channel.setArchived(true).catch(() => null);
+
+  await interaction.editReply('Encounter ended and thread archived.');
+}
+
+// ---------------------------------------------------------------------------
+// /encounter list
+// ---------------------------------------------------------------------------
+
+async function handleList(
+  interaction: ChatInputCommandInteraction,
+  guildId: string,
+): Promise<void> {
+  const threadIds = await sessionManager.getGuildThreadIds(guildId);
+
+  const active: Array<{
+    title: string;
+    phase: string;
+    playerCount: number;
+    location: string;
+    threadId: string;
+  }> = [];
+
+  for (const threadId of threadIds) {
+    const session = await sessionManager.get(threadId);
+    if (!session || session.phase === 'resolved') continue;
+    active.push({
+      title: session.spec.title,
+      phase: session.phase,
+      playerCount: Object.keys(session.players).length,
+      location: session.spec.setting.location,
+      threadId,
+    });
+  }
+
+  const embed = buildEncounterListEmbed(active);
+  await interaction.reply({ embeds: [embed], ephemeral: true });
+}
diff --git a/src/bot/commands/encounters.ts b/src/bot/commands/encounters.ts
new file mode 100644
index 0000000..f0de674
--- /dev/null
+++ b/src/bot/commands/encounters.ts
@@ -0,0 +1,210 @@
+import { SlashCommandBuilder } from '@discordjs/builders';
+import {
+  EmbedBuilder,
+  ActionRowBuilder,
+  StringSelectMenuBuilder,
+  StringSelectMenuOptionBuilder,
+  ButtonBuilder,
+  ButtonStyle,
+  ModalBuilder,
+  TextInputBuilder,
+  TextInputStyle,
+} from 'discord.js';
+import type {
+  ChatInputCommandInteraction,
+  StringSelectMenuInteraction,
+  ButtonInteraction,
+  ModalSubmitInteraction,
+  Client,
+} from 'discord.js';
+import { listEncounters, searchEncounters, getEncounter } from '../../graphmcp/client.js';
+import { log } from '../../lib/logger.js';
+
+export const data = new SlashCommandBuilder()
+  .setName('encounters')
+  .setDescription('View and search past campaign encounters');
+
+export async function execute(
+  interaction: ChatInputCommandInteraction,
+  client: Client,
+): Promise<void> {
+  await interaction.deferReply({ ephemeral: true });
+
+  let list;
+  try {
+    list = await listEncounters(10);
+  } catch (err) {
+    log.error('cmd', 'listEncounters failed', { error: String(err) });
+    await interaction.editReply('❌ Failed to fetch past encounters from the archive.');
+    return;
+  }
+
+  if (list.length === 0) {
+    await interaction.editReply('📜 No encounters have been logged for this campaign yet.');
+    return;
+  }
+
+  const select = new StringSelectMenuBuilder()
+    .setCustomId('encounters_select')
+    .setPlaceholder('Choose a past encounter to view...')
+    .addOptions(
+      list.map(e => {
+        const date = e.timestamp ? e.timestamp.slice(0, 10) : 'No Date';
+        const label = e.title.length > 50 ? e.title.slice(0, 47) + '...' : e.title;
+        const desc = e.summary && e.summary.trim() !== ""
+          ? (e.summary.length > 90 ? e.summary.slice(0, 87) + '...' : e.summary)
+          : `Location: ${e.location || 'Unknown'}`;
+        return new StringSelectMenuOptionBuilder()
+          .setLabel(`[${date}] ${label}`)
+          .setDescription(desc)
+          .setValue(e.id);
+      }),
+    );
+
+  const searchBtn = new ButtonBuilder()
+    .setCustomId('encounters_search_btn')
+    .setLabel('🔍 Search Archive')
+    .setStyle(ButtonStyle.Primary);
+
+  const selectRow = new ActionRowBuilder<StringSelectMenuBuilder>().addComponents(select);
+  const buttonRow = new ActionRowBuilder<ButtonBuilder>().addComponents(searchBtn);
+
+  await interaction.editReply({
+    content: '📚 **Campaign Chronicles**\nBrowse or search the recorded history of this campaign:',
+    components: [selectRow, buttonRow],
+  });
+}
+
+// ── Select menu choice selection handler ──────────────────────────────────────
+export async function handleEncounterSelect(interaction: StringSelectMenuInteraction): Promise<void> {
+  const encId = interaction.values[0];
+  await interaction.deferReply({ ephemeral: true });
+
+  try {
+    const details = await getEncounter(encId);
+    if (!details) {
+      await interaction.editReply('❌ Encounter details could not be found.');
+      return;
+    }
+
+    const date = details.timestamp ? new Date(details.timestamp).toLocaleDateString('en-US', {
+      month: 'short',
+      day: 'numeric',
+      year: 'numeric',
+      hour: '2-digit',
+      minute: '2-digit',
+      timeZone: 'UTC',
+    }) + ' UTC' : 'Unknown Date';
+
+    const embed = new EmbedBuilder()
+      .setTitle(`⚔️ ${details.title}`)
+      .setDescription(details.summary && details.summary.trim() !== "" ? details.summary : '*No summary recorded.*')
+      .addFields(
+        { name: '📍 Location', value: details.location || 'Unknown', inline: true },
+        { name: '📅 Date & Time', value: date, inline: true },
+        { name: '🏷️ Type', value: details.type || 'encounter', inline: true },
+      )
+      .setColor(0x8a2be2); // Runic Purple
+
+    if (details.participants && details.participants.length > 0) {
+      embed.addFields({ name: '👥 Witnesses / Participants', value: details.participants.join(', ') });
+    }
+
+    if (details.featured_entities && details.featured_entities.length > 0) {
+      embed.addFields({ name: '✨ Featured Entities', value: details.featured_entities.join(', ') });
+    }
+
+    await interaction.editReply({ embeds: [embed] });
+  } catch (err) {
+    log.error('interaction', 'getEncounter details failed', { error: String(err) });
+    await interaction.editReply('❌ Failed to fetch encounter details.');
+  }
+}
+
+// ── Search button click handler ───────────────────────────────────────────────
+export async function handleSearchButton(interaction: ButtonInteraction): Promise<void> {
+  const modal = new ModalBuilder()
+    .setCustomId('encounters_search_modal')
+    .setTitle('Search Campaign Chronicles');
+
+  const queryInput = new TextInputBuilder()
+    .setCustomId('search_query')
+    .setLabel('Keywords (search title/summary)')
+    .setStyle(TextInputStyle.Short)
+    .setRequired(false)
+    .setMaxLength(100);
+
+  const locationInput = new TextInputBuilder()
+    .setCustomId('search_location')
+    .setLabel('Filter by Location')
+    .setStyle(TextInputStyle.Short)
+    .setRequired(false)
+    .setMaxLength(100);
+
+  const participantInput = new TextInputBuilder()
+    .setCustomId('search_participant')
+    .setLabel('Filter by Participant/NPC')
+    .setStyle(TextInputStyle.Short)
+    .setRequired(false)
+    .setMaxLength(100);
+
+  const row1 = new ActionRowBuilder<TextInputBuilder>().addComponents(queryInput);
+  const row2 = new ActionRowBuilder<TextInputBuilder>().addComponents(locationInput);
+  const row3 = new ActionRowBuilder<TextInputBuilder>().addComponents(participantInput);
+
+  modal.addComponents(row1, row2, row3);
+
+  await interaction.showModal(modal);
+}
+
+// ── Modal submission handler ──────────────────────────────────────────────────
+export async function handleSearchModalSubmit(interaction: ModalSubmitInteraction): Promise<void> {
+  const query = interaction.fields.getTextInputValue('search_query').trim();
+  const location = interaction.fields.getTextInputValue('search_location').trim();
+  const participant = interaction.fields.getTextInputValue('search_participant').trim();
+
+  await interaction.deferReply({ ephemeral: true });
+
+  if (!query && !location && !participant) {
+    await interaction.editReply('⚠️ Please enter at least one filter criterion.');
+    return;
+  }
+
+  let results;
+  try {
+    results = await searchEncounters({ query, location, participant, limit: 10 });
+  } catch (err) {
+    log.error('interaction', 'searchEncounters failed', { error: String(err) });
+    await interaction.editReply('❌ Search query failed.');
+    return;
+  }
+
+  if (results.length === 0) {
+    await interaction.editReply('📜 No matching encounters found in the archive.');
+    return;
+  }
+
+  const select = new StringSelectMenuBuilder()
+    .setCustomId('encounters_select')
+    .setPlaceholder('Choose a search result to view...')
+    .addOptions(
+      results.map(e => {
+        const date = e.timestamp ? e.timestamp.slice(0, 10) : 'No Date';
+        const label = e.title.length > 50 ? e.title.slice(0, 47) + '...' : e.title;
+        const desc = e.summary && e.summary.trim() !== ""
+          ? (e.summary.length > 90 ? e.summary.slice(0, 87) + '...' : e.summary)
+          : `Location: ${e.location || 'Unknown'}`;
+        return new StringSelectMenuOptionBuilder()
+          .setLabel(`[${date}] ${label}`)
+          .setDescription(desc)
+          .setValue(e.id);
+      }),
+    );
+
+  const selectRow = new ActionRowBuilder<StringSelectMenuBuilder>().addComponents(select);
+
+  await interaction.editReply({
+    content: `🔍 **Search Results**\nFound **${results.length}** matching encounter${results.length === 1 ? '' : 's'}:`,
+    components: [selectRow],
+  });
+}
diff --git a/src/bot/commands/roll.ts b/src/bot/commands/roll.ts
new file mode 100644
index 0000000..64807da
--- /dev/null
+++ b/src/bot/commands/roll.ts
@@ -0,0 +1,107 @@
+import { SlashCommandBuilder } from '@discordjs/builders';
+import type { ChatInputCommandInteraction, Client, ThreadChannel } from 'discord.js';
+import { playerRegistry } from '../../session/playerRegistry.js';
+import { sessionManager } from '../../session/sessionManager.js';
+import { scheduleEncounterLLMTurn } from '../handlers/messageRouter.js';
+import type { ChatMessage } from '../../types/index.js';
+
+export const data = new SlashCommandBuilder()
+  .setName('roll')
+  .setDescription('Attempt an action that may require a skill check')
+  .addStringOption(o =>
+    o
+      .setName('action')
+      .setDescription('What are you attempting? (e.g. "I try to pick the lock")')
+      .setRequired(true)
+      .setMaxLength(300),
+  );
+
+export async function execute(
+  interaction: ChatInputCommandInteraction,
+  client: Client,
+): Promise<void> {
+  const guildId = interaction.guildId;
+  if (!guildId) {
+    await interaction.reply({ content: 'This command must be used in a server.', ephemeral: true });
+    return;
+  }
+
+  const channel = interaction.channel;
+  if (!channel?.isThread()) {
+    await interaction.reply({
+      content: 'Use `/roll` inside an active encounter thread.',
+      ephemeral: true,
+    });
+    return;
+  }
+
+  const session = await sessionManager.get(channel.id);
+  if (!session || session.phase === 'resolved') {
+    await interaction.reply({
+      content: 'There is no active encounter in this thread.',
+      ephemeral: true,
+    });
+    return;
+  }
+
+  if (session.pendingSkillCheck) {
+    await interaction.reply({
+      content: 'A roll is already pending — use the buttons above to resolve it first.',
+      ephemeral: true,
+    });
+    return;
+  }
+
+  const player = await playerRegistry.get(guildId, interaction.user.id);
+  if (!player) {
+    await interaction.reply({
+      content: 'Register your character name first with `/dndname set`.',
+      ephemeral: true,
+    });
+    return;
+  }
+
+  const action = interaction.options.getString('action', true).trim();
+
+  // Acknowledge ephemerally so the slash command doesn't clutter the thread
+  await interaction.reply({ content: '🎲 Action submitted.', ephemeral: true });
+
+  // Post the action publicly so the whole table sees it
+  await channel.send(`*${player.dndName} attempts: ${action}*`);
+
+  const now = Date.now();
+
+  // Add as a player message so it appears in the LLM's conversation context
+  const userMsg: ChatMessage = {
+    role: 'user',
+    content: `${player.dndName}: ${action}`,
+    timestamp: now,
+  };
+
+  // Try to extract a skill/ability name if the player mentioned one explicitly
+  // e.g. "I roll perception", "rolling stealth", "perception check"
+  const SKILL_EXTRACT_RE = /\b(perception|stealth|athletics|acrobatics|insight|deception|persuasion|intimidation|investigation|nature|religion|history|medicine|survival|arcana|performance|sleight of hand|animal handling|strength|dexterity|constitution|intelligence|wisdom|charisma)\b/i;
+  const skillHint = SKILL_EXTRACT_RE.exec(action)?.[1];
+  const skillLine = skillHint
+    ? `The player's message names "${skillHint}" — use that as the skill unless the action clearly calls for a different one.`
+    : 'Choose the most appropriate skill or ability for the action.';
+
+  // Hard override — the LLM MUST emit a tool call and nothing else.
+  const systemNudge: ChatMessage = {
+    role: 'system',
+    content: [
+      `[/roll COMMAND — MANDATORY TOOL CALL]`,
+      `${player.dndName} used the /roll slash command. You MUST output a skill_check_emit tool call block and NOTHING ELSE — no narrative, no explanation, no preamble.`,
+      skillLine,
+      `Your entire response must be exactly:`,
+      '```tool_call',
+      `{"tool":"skill_check_emit","args":{"player":"${player.dndName}","prompt":"<one sentence describing the check>","skill":"<skill name>","dc":<DC as integer>}}`,
+      '```',
+    ].join('\n'),
+    timestamp: now,
+  };
+
+  await sessionManager.addMessage(session.threadId, userMsg);
+  await sessionManager.addMessage(session.threadId, systemNudge);
+  scheduleEncounterLLMTurn(session.threadId, channel as ThreadChannel, client, true);
+}
diff --git a/src/bot/commands/xp.ts b/src/bot/commands/xp.ts
new file mode 100644
index 0000000..91c58f5
--- /dev/null
+++ b/src/bot/commands/xp.ts
@@ -0,0 +1,71 @@
+import { SlashCommandBuilder } from '@discordjs/builders';
+import type { ChatInputCommandInteraction, ThreadChannel } from 'discord.js';
+import { sessionManager } from '../../session/sessionManager.js';
+import { awardXP } from '../../session/xpAwarder.js';
+import { config } from '../../config.js';
+
+export const data = new SlashCommandBuilder()
+  .setName('xp')
+  .setDescription('DM: award XP to encounter participants')
+  .addSubcommand(sub =>
+    sub
+      .setName('award')
+      .setDescription('Award XP to all participants in the current encounter thread')
+      .addIntegerOption(o =>
+        o
+          .setName('amount')
+          .setDescription('XP to award — uses the encounter spec default if omitted')
+          .setRequired(false)
+          .setMinValue(1),
+      ),
+  );
+
+export async function execute(interaction: ChatInputCommandInteraction): Promise<void> {
+  const guildId = interaction.guildId;
+  if (!guildId) {
+    await interaction.reply({ content: 'This command must be used in a server.', ephemeral: true });
+    return;
+  }
+
+  if (
+    config.DISCORD_ALLOWED_USERS.length > 0 &&
+    !config.DISCORD_ALLOWED_USERS.includes(interaction.user.id)
+  ) {
+    await interaction.reply({ content: 'Only the DM can award XP.', ephemeral: true });
+    return;
+  }
+
+  const channel = interaction.channel;
+  if (!channel?.isThread()) {
+    await interaction.reply({ content: 'Run this inside an encounter thread.', ephemeral: true });
+    return;
+  }
+
+  await interaction.deferReply({ ephemeral: true });
+
+  const session = await sessionManager.get(channel.id);
+  if (!session) {
+    await interaction.editReply('No encounter found for this thread.');
+    return;
+  }
+
+  if (Object.keys(session.players).length === 0) {
+    await interaction.editReply('No players joined this encounter — nothing to award.');
+    return;
+  }
+
+  const specDefault = session.spec.xpReward;
+  const override = interaction.options.getInteger('amount') ?? undefined;
+  const amount = override ?? specDefault;
+
+  if (!amount) {
+    await interaction.editReply(
+      'No XP amount specified and this encounter has no default in its spec. ' +
+      'Pass an amount with `/xp award amount:<number>`.',
+    );
+    return;
+  }
+
+  await awardXP(session, amount, channel as ThreadChannel);
+  await interaction.editReply(`XP awarded. See the thread for details.`);
+}
diff --git a/src/bot/embeds/encounterDiscovery.ts b/src/bot/embeds/encounterDiscovery.ts
new file mode 100644
index 0000000..91a406b
--- /dev/null
+++ b/src/bot/embeds/encounterDiscovery.ts
@@ -0,0 +1,39 @@
+import { EmbedBuilder } from 'discord.js';
+
+export function buildEncounterListEmbed(
+  encounters: Array<{
+    title: string;
+    phase: string;
+    playerCount: number;
+    location: string;
+    threadId: string;
+  }>,
+): EmbedBuilder {
+  if (encounters.length === 0) {
+    return new EmbedBuilder()
+      .setTitle('⚔️ Active Encounters')
+      .setDescription('No encounters are currently running. Ask your DM to start one.')
+      .setColor(0x95a5a6)
+      .setFooter({ text: 'Join an encounter by typing in its thread' });
+  }
+
+  const embed = new EmbedBuilder()
+    .setTitle('⚔️ Active Encounters')
+    .setColor(0x5865f2)
+    .setFooter({ text: 'Join an encounter by typing in its thread' });
+
+  for (const enc of encounters) {
+    embed.addFields({
+      name: enc.title,
+      value: [
+        `**Phase:** ${enc.phase}`,
+        `**Players:** ${enc.playerCount}`,
+        `**Location:** ${enc.location}`,
+        `<#${enc.threadId}>`,
+      ].join('\n'),
+      inline: false,
+    });
+  }
+
+  return embed;
+}
diff --git a/src/bot/embeds/loreAnswer.ts b/src/bot/embeds/loreAnswer.ts
new file mode 100644
index 0000000..adcebb7
--- /dev/null
+++ b/src/bot/embeds/loreAnswer.ts
@@ -0,0 +1,48 @@
+import { EmbedBuilder } from 'discord.js';
+
+export const LORE_COLOR = {
+  FOUND: 0x2ecc71,   // green  — knowledge retrieved
+  NONE: 0x95a5a6,    // gray   — no records in graph
+} as const;
+
+// Pre-formatted source lines and history lines are built in the handler to
+// avoid coupling this module to graphmcp client types.
+export function buildLoreAnswerEmbed(
+  answer: string,
+  sourcesText: string | null,
+  playerHistory: string | null,
+  playerName: string | undefined,
+  sourceCount: number,
+  activeEncounterThreadId?: string,
+): EmbedBuilder {
+  const color = sourceCount > 0 ? LORE_COLOR.FOUND : LORE_COLOR.NONE;
+  const description = answer.length > 4000 ? answer.slice(0, 3997) + '…' : answer;
+
+  const embed = new EmbedBuilder()
+    .setTitle('📜  Chronicle Records')
+    .setDescription(description)
+    .setColor(color);
+
+  if (sourcesText) {
+    embed.addFields({ name: 'Sources', value: sourcesText, inline: false });
+  }
+
+  if (playerHistory && playerName) {
+    embed.addFields({ name: `${playerName}'s history`, value: playerHistory, inline: false });
+  }
+
+  if (activeEncounterThreadId) {
+    embed.addFields({
+      name: 'Active encounter',
+      value: `An encounter is in progress: <#${activeEncounterThreadId}>`,
+      inline: false,
+    });
+  }
+
+  const footerText = sourceCount > 0
+    ? `${sourceCount} record${sourceCount === 1 ? '' : 's'} consulted · Knowledge graph`
+    : 'No records found in knowledge graph';
+
+  embed.setFooter({ text: footerText });
+  return embed;
+}
diff --git a/src/bot/embeds/playerGate.ts b/src/bot/embeds/playerGate.ts
new file mode 100644
index 0000000..3b4ac5a
--- /dev/null
+++ b/src/bot/embeds/playerGate.ts
@@ -0,0 +1,12 @@
+import { EmbedBuilder } from 'discord.js';
+
+export function buildPlayerGateEmbed(): EmbedBuilder {
+  return new EmbedBuilder()
+    .setTitle('Register Your Character')
+    .setDescription(
+      'You need a D&D character name before you can join this encounter.\n\n' +
+      'Run `/dndname set <name>` and your message will be processed automatically.',
+    )
+    .setColor(0x5865f2)
+    .setFooter({ text: 'Your message has been held and will be replayed after you register.' });
+}
diff --git a/src/bot/embeds/resolution.ts b/src/bot/embeds/resolution.ts
new file mode 100644
index 0000000..e0f57b1
--- /dev/null
+++ b/src/bot/embeds/resolution.ts
@@ -0,0 +1,28 @@
+import { EmbedBuilder } from 'discord.js';
+import type { EncounterSpec, SessionState } from '../../types/index.js';
+
+export function buildResolutionEmbed(
+  spec: EncounterSpec,
+  session: SessionState,
+  outcomeId: string,
+  summary: string,
+): EmbedBuilder {
+  const allGoals = [...spec.goals.primary, ...spec.goals.secondary];
+  const goal = allGoals.find(g => g.id === outcomeId);
+  const outcomeLabel = goal ? goal.label.trim().split('\n')[0] : outcomeId;
+
+  const participants = Object.values(session.players)
+    .map(p => p.dndName)
+    .join(', ') || 'No players registered';
+
+  return new EmbedBuilder()
+    .setTitle(`⚔️ Encounter Complete — ${spec.title}`)
+    .setDescription(summary)
+    .addFields(
+      { name: 'Outcome', value: outcomeLabel, inline: false },
+      { name: 'Participants', value: participants, inline: true },
+      { name: 'Location', value: spec.setting.location, inline: true },
+    )
+    .setColor(0x2ecc71)
+    .setFooter({ text: 'NPC memories have been committed to the knowledge graph.' });
+}
diff --git a/src/bot/embeds/skillCheck.ts b/src/bot/embeds/skillCheck.ts
new file mode 100644
index 0000000..447efd5
--- /dev/null
+++ b/src/bot/embeds/skillCheck.ts
@@ -0,0 +1,74 @@
+import { EmbedBuilder, ActionRowBuilder, ButtonBuilder, ButtonStyle } from 'discord.js';
+
+export const EMBED_COLOR = {
+  PENDING: 0x5865f2, // blue  — awaiting player action
+  SUCCESS: 0x2ecc71, // green — roll succeeded
+  FAILURE: 0xe74c3c, // red   — roll failed
+} as const;
+
+export function buildSuspenseEmbed(player: string, prompt: string): EmbedBuilder {
+  return new EmbedBuilder()
+    .setTitle(`🎲  The dice are cast...`)
+    .setDescription(`**${player}** — ${prompt}\n\n*Fate will decide the outcome.*`)
+    .setColor(EMBED_COLOR.PENDING);
+}
+
+export function buildSkillCheckEmbed(
+  player: string,
+  prompt: string,
+  dc: number,
+  color: number = EMBED_COLOR.PENDING,
+  footerText = '🎲  Roll your dice to determine your fate.',
+  modifier?: number,
+  skillLabel?: string,
+  advantage?: boolean,
+  disadvantage?: boolean,
+): EmbedBuilder {
+  const embed = new EmbedBuilder()
+    .setTitle(`⚔️  Skill Check — ${player}`)
+    .setDescription(`*${prompt}*`)
+    .addFields({ name: '⚖️  DC', value: `**${dc}**`, inline: true })
+    .setColor(color)
+    .setFooter({ text: footerText });
+
+  if (modifier !== undefined) {
+    const sign = modifier >= 0 ? `+${modifier}` : String(modifier);
+    const label = skillLabel ? `${skillLabel} (${sign})` : sign;
+    embed.addFields({ name: '🎯  Modifier', value: `**${label}**`, inline: true });
+  }
+
+  if (advantage) {
+    embed.addFields({ name: '🟢  Roll Mode', value: '**Advantage**', inline: true });
+  } else if (disadvantage) {
+    embed.addFields({ name: '🔴  Roll Mode', value: '**Disadvantage**', inline: true });
+  }
+
+  return embed;
+}
+
+export function buildRollButtons(modifier?: number): ActionRowBuilder<ButtonBuilder> {
+  if (modifier !== undefined) {
+    const sign = modifier >= 0 ? `+${modifier}` : String(modifier);
+    return new ActionRowBuilder<ButtonBuilder>().addComponents(
+      new ButtonBuilder().setCustomId(`sc_roll_m:${modifier}`).setLabel(`Roll (${sign})`).setStyle(ButtonStyle.Primary),
+      new ButtonBuilder().setCustomId(`sc_adv_m:${modifier}`).setLabel(`Adv (${sign})`).setStyle(ButtonStyle.Success),
+      new ButtonBuilder().setCustomId(`sc_dis_m:${modifier}`).setLabel(`Dis (${sign})`).setStyle(ButtonStyle.Danger),
+      new ButtonBuilder().setCustomId('sc_mod').setLabel('Custom Modifier').setStyle(ButtonStyle.Secondary),
+    );
+  }
+  return new ActionRowBuilder<ButtonBuilder>().addComponents(
+    new ButtonBuilder().setCustomId('sc_roll').setLabel('Roll').setStyle(ButtonStyle.Primary),
+    new ButtonBuilder().setCustomId('sc_adv').setLabel('Advantage').setStyle(ButtonStyle.Success),
+    new ButtonBuilder().setCustomId('sc_dis').setLabel('Disadvantage').setStyle(ButtonStyle.Danger),
+    new ButtonBuilder().setCustomId('sc_mod').setLabel('Roll with Modifier').setStyle(ButtonStyle.Secondary),
+  );
+}
+
+export function buildModifierRollButtons(modifier: number): ActionRowBuilder<ButtonBuilder> {
+  const sign = modifier >= 0 ? `+${modifier}` : String(modifier);
+  return new ActionRowBuilder<ButtonBuilder>().addComponents(
+    new ButtonBuilder().setCustomId(`sc_roll_m:${modifier}`).setLabel(`Roll (${sign})`).setStyle(ButtonStyle.Primary),
+    new ButtonBuilder().setCustomId(`sc_adv_m:${modifier}`).setLabel(`Advantage (${sign})`).setStyle(ButtonStyle.Success),
+    new ButtonBuilder().setCustomId(`sc_dis_m:${modifier}`).setLabel(`Disadvantage (${sign})`).setStyle(ButtonStyle.Danger),
+  );
+}
diff --git a/src/bot/handlers/generationQueue.ts b/src/bot/handlers/generationQueue.ts
new file mode 100644
index 0000000..c931989
--- /dev/null
+++ b/src/bot/handlers/generationQueue.ts
@@ -0,0 +1,75 @@
+// In-memory per-thread debounce and generation lock.
+// Intentionally ephemeral — resets on bot restart.
+
+interface ThreadState {
+  isGenerating: boolean;
+  timer: ReturnType<typeof setTimeout> | null;
+  pendingCount: number;
+  runner: (() => Promise<void>) | null;
+}
+
+const threads = new Map<string, ThreadState>();
+
+function getThread(threadId: string): ThreadState {
+  let t = threads.get(threadId);
+  if (!t) {
+    t = { isGenerating: false, timer: null, pendingCount: 0, runner: null };
+    threads.set(threadId, t);
+  }
+  return t;
+}
+
+/**
+ * Schedule an LLM turn for a thread.
+ *
+ * - Normal messages: debounced 500ms so a burst of player chat coalesces into
+ *   one call rather than hammering the LLM for each line.
+ * - Roll results / slash commands: pass immediate=true to skip the debounce
+ *   while still respecting the generation lock.
+ * - If a generation is already running, the call is counted; when the running
+ *   turn finishes it will fire one drain turn for all messages that queued up.
+ *
+ * The runner must fetch fresh session state itself — this prevents stale
+ * captures when the drain fires after the previous LLM response is stored.
+ */
+export function scheduleLLMTurn(
+  threadId: string,
+  runner: () => Promise<void>,
+  immediate = false,
+): void {
+  const t = getThread(threadId);
+  t.runner = runner; // always keep the latest (freshest) runner
+
+  if (t.isGenerating) {
+    t.pendingCount++;
+    return;
+  }
+
+  if (t.timer) clearTimeout(t.timer);
+  t.timer = setTimeout(() => {
+    t.timer = null;
+    void fire(threadId);
+  }, immediate ? 0 : 500);
+}
+
+async function fire(threadId: string): Promise<void> {
+  const t = getThread(threadId);
+  if (!t.runner || t.isGenerating) return;
+
+  t.isGenerating = true;
+  t.pendingCount = 0;
+
+  try {
+    await t.runner();
+  } catch {
+    // Runner errors are the runner's responsibility to handle and log.
+    // We just need the finally block to release the lock regardless.
+  } finally {
+    t.isGenerating = false;
+    if (t.pendingCount > 0) {
+      t.pendingCount = 0;
+      // One drain turn covers everything that arrived during generation.
+      void fire(threadId);
+    }
+  }
+}
diff --git a/src/bot/handlers/mentionHandler.ts b/src/bot/handlers/mentionHandler.ts
new file mode 100644
index 0000000..e317ddf
--- /dev/null
+++ b/src/bot/handlers/mentionHandler.ts
@@ -0,0 +1,187 @@
+import type { Message, Client, TextChannel } from 'discord.js';
+import { config } from '../../config.js';
+import { semanticSearch, queryAsNPC } from '../../graphmcp/client.js';
+import { publishToGraphMCP } from '../../graphmcp/ingest.js';
+import { callLLM } from '../../harness/llmClient.js';
+import { loadPersona } from '../../persona/loader.js';
+import { playerRegistry } from '../../session/playerRegistry.js';
+import { characterRegistry } from '../../session/characterRegistry.js';
+import { sessionManager } from '../../session/sessionManager.js';
+import { buildLoreAnswerEmbed } from '../embeds/loreAnswer.js';
+
+export async function handleMention(message: Message, client: Client): Promise<void> {
+  if (message.author.bot) return;
+  if (message.channel.isThread()) return;
+  if (!message.channel.isTextBased()) return;
+  if (!client.user || !message.mentions.has(client.user)) return;
+  if (!config.DISCORD_ALLOWED_CHANNELS.includes(message.channelId)) return;
+
+  const channel = message.channel as TextChannel;
+  const query = message.content.replace(/<@!?\d+>/g, '').trim();
+
+  if (!query) {
+    await message.reply(`*Zalram looks up from his notes, waiting.*`);
+    return;
+  }
+
+  publishToGraphMCP({
+    messageId: message.id,
+    content: query,
+    author: message.author.username,
+    channelId: message.channelId,
+    channelName: channel.name,
+  }).catch(err => console.warn('[ingest] mention publish failed:', err));
+
+  void channel.sendTyping();
+  const typingInterval = setInterval(() => void channel.sendTyping(), 8_000);
+
+  const guildId = message.guildId ?? '';
+
+  // Run player lookup, character profile lookup, and semantic search in parallel.
+  const [player, characterProfile, searchResult] = await Promise.all([
+    playerRegistry.get(guildId, message.author.id).catch(() => null),
+    characterRegistry.get(guildId, message.author.id).catch(() => null),
+    semanticSearch(query, config.GRAPHMCP_MENTION_LIMIT).catch(err => {
+      console.warn('[mentionHandler] semanticSearch failed:', err);
+      return { chunks: [] as { content: string; score: number; source?: string }[] };
+    }),
+  ]);
+
+  const relevantChunks = (searchResult.chunks ?? [])
+    .filter(c => c.score > config.GRAPHMCP_SCORE_THRESHOLD)
+    .slice(0, 4);
+
+  // If the player has a registered character, pull their encounter history from
+  // the knowledge graph. This surfaces encounters they personally participated in
+  // and any lore chunks the NPC persona has linked to them.
+  let encounterHistoryLines: string[] = [];
+  let npcLoreChunks: { text: string; score: number; source: string }[] = [];
+
+  if (player) {
+    try {
+      const npcResult = await queryAsNPC(player.dndName, query, config.GRAPHMCP_NPC_MEMORY_LIMIT);
+
+      if (npcResult.graph_context?.length) {
+        encounterHistoryLines = npcResult.graph_context.slice(0, 3).map(enc => {
+          const date = enc.enc_timestamp ? enc.enc_timestamp.slice(0, 10) : 'unknown';
+          const summary = enc.enc_summary.length > 100
+            ? enc.enc_summary.slice(0, 97) + '…'
+            : enc.enc_summary;
+          return `⚔️ [${date}] **${enc.enc_title}** — ${summary}`;
+        });
+      }
+
+      npcLoreChunks = (npcResult.chunks ?? [])
+        .filter(c => c.score > config.GRAPHMCP_SCORE_THRESHOLD)
+        .slice(0, 2)
+        .map(c => ({ text: c.text, score: c.score, source: c.source }));
+
+    } catch (err) {
+      console.warn('[mentionHandler] queryAsNPC failed:', err);
+    }
+  }
+
+  // Find any active encounter thread in this guild so we can surface it.
+  let activeEncounterThreadId: string | undefined;
+  if (guildId) {
+    try {
+      const threadIds = await sessionManager.getGuildThreadIds(guildId);
+      for (const tid of threadIds) {
+        const session = await sessionManager.get(tid);
+        if (session && session.phase !== 'resolved') {
+          activeEncounterThreadId = tid;
+          break;
+        }
+      }
+    } catch { /* non-critical — don't block on this */ }
+  }
+
+  // Build embed source lines from semantic chunks + any extra NPC memory chunks.
+  const allSourceChunks = [
+    ...relevantChunks.map(c => ({ text: c.content, source: c.source ?? 'lore' })),
+    ...npcLoreChunks.map(c => ({ text: c.text, source: c.source })),
+  ].slice(0, 5);
+
+  const sourcesText = allSourceChunks.length > 0
+    ? allSourceChunks.map(c => {
+        const icon = c.source === 'lore' ? '📚' : '⚔️';
+        const snippet = c.text.length > 120 ? c.text.slice(0, 117) + '…' : c.text;
+        return `${icon} ${snippet}`;
+      }).join('\n')
+    : null;
+
+  const playerHistoryText = encounterHistoryLines.length > 0
+    ? encounterHistoryLines.join('\n')
+    : null;
+
+  // Build the LLM prompt context block.
+  const persona = loadPersona(config.PERSONA_PATH);
+  let contextBlock: string;
+
+  if (allSourceChunks.length > 0 || encounterHistoryLines.length > 0) {
+    const loreSection = allSourceChunks.length > 0
+      ? 'Lore records:\n' + allSourceChunks.map(c => `- ${c.text.slice(0, 300)}`).join('\n')
+      : '';
+    const historySection = encounterHistoryLines.length > 0
+      ? `\n${player!.dndName}'s encounter history:\n` + encounterHistoryLines.join('\n')
+      : '';
+    contextBlock = `VERIFIED KNOWLEDGE GRAPH DATA — use only this as your factual basis:\n${loreSection}${historySection}`;
+  } else {
+    contextBlock = `NO RECORDS FOUND — the knowledge graph returned nothing relevant to this query.
+Do NOT invent, speculate, or fabricate any specific details, names, dates, places,
+ledger entries, transactions, or events. You must say clearly that you have no record
+of this. You may note what kind of event would produce a record, or ask a clarifying
+question, but you must not fill the gap with invented content.`;
+  }
+
+  const activeEncounterNote = activeEncounterThreadId
+    ? `\n[Note: there is an active encounter in progress in thread ${activeEncounterThreadId}.]`
+    : '';
+
+  const characterBlock = characterProfile
+    ? [
+        `Character context for ${characterProfile.dndName}:`,
+        `  Class: ${characterProfile.characterClass}, Race: ${characterProfile.race}, Level: ${characterProfile.level}`,
+        characterProfile.backstory ? `  ${characterProfile.backstory}` : '',
+      ].filter(Boolean).join('\n')
+    : '';
+
+  const systemContent = [
+    persona.persona.trim(),
+    '',
+    persona.responseStyle.trim(),
+    '',
+    contextBlock + activeEncounterNote,
+    characterBlock ? '' : undefined,
+    characterBlock || undefined,
+  ].filter((s): s is string => s !== undefined).join('\n');
+
+  const now = Date.now();
+  const llmMessages = [
+    { role: 'system' as const, content: systemContent, timestamp: now },
+    { role: 'user' as const, content: query, timestamp: now },
+  ];
+
+  let answer: string;
+  try {
+    const response = await callLLM(llmMessages);
+    answer = response.narrative || '*The Chronicler is silent.*';
+  } catch (err) {
+    console.error('[mentionHandler] LLM call failed:', err);
+    answer = '*The Chronicler pauses, lost in distant memory… (error, please try again)*';
+  } finally {
+    clearInterval(typingInterval);
+  }
+
+  const sourceCount = allSourceChunks.length + encounterHistoryLines.length;
+  const embed = buildLoreAnswerEmbed(
+    answer,
+    sourcesText,
+    playerHistoryText,
+    player?.dndName,
+    sourceCount,
+    activeEncounterThreadId,
+  );
+
+  await message.reply({ embeds: [embed] });
+}
diff --git a/src/bot/handlers/messageRouter.ts b/src/bot/handlers/messageRouter.ts
new file mode 100644
index 0000000..daf1077
--- /dev/null
+++ b/src/bot/handlers/messageRouter.ts
@@ -0,0 +1,384 @@
+import type { Message, Client, ThreadChannel, TextChannel } from 'discord.js';
+import { playerRegistry } from '../../session/playerRegistry.js';
+import { characterRegistry } from '../../session/characterRegistry.js';
+import { sessionManager } from '../../session/sessionManager.js';
+import { assembleContext } from '../../harness/contextAssembler.js';
+import { callLLM } from '../../harness/llmClient.js';
+import { dispatchTool } from '../../harness/toolDispatcher.js';
+import { buildPlayerGateEmbed } from '../embeds/playerGate.js';
+import { publishToGraphMCP } from '../../graphmcp/ingest.js';
+import { config } from '../../config.js';
+import { scheduleLLMTurn } from './generationQueue.js';
+import { filterLLMResponse, logFiltered, detectMissedSkillCheck } from './responseFilter.js';
+import { registerScheduled, drainPending, clearPending, upgradeToProcessing, upgradeToComplete, cleanupReactions } from './reactionManager.js';
+import { isBurstCapped, incrementBurst, resetBurst, sendDropNotice } from './queueCap.js';
+import { log } from '../../lib/logger.js';
+import type { ChatMessage, SessionState } from '../../types/index.js';
+
+// Text fallback for players who manually type their roll result
+const ROLL_RE = /i\s+rolled\s+(?:a\s+)?(\d+)\s+([\w][\w\s]*)/i;
+
+const PENDING_ROLL_LIMIT = 5;
+
+function isAllowedChannel(parentId: string | null): boolean {
+  if (!parentId) return false;
+  return config.DISCORD_ALLOWED_CHANNELS.includes(parentId);
+}
+
+// ---------------------------------------------------------------------------
+// Public: called from the messageCreate event
+// ---------------------------------------------------------------------------
+
+export async function handleMessage(message: Message, client: Client): Promise<void> {
+  if (message.author.bot) return;
+  if (!message.channel.isThread()) return;
+
+  const thread = message.channel as ThreadChannel;
+  if (!isAllowedChannel(thread.parentId)) return;
+
+  const session = await sessionManager.get(thread.id);
+  if (!session || session.phase === 'resolved') return;
+
+  // 👀 immediately — fire-and-forget, must not block or throw
+  message.react('👀').catch(() => null);
+
+  await processEncounterMessage(session, thread, message.author.id, message.content, client, message.id, message);
+}
+
+// ---------------------------------------------------------------------------
+// Public: replay held messages after a player registers via /dndname set
+// ---------------------------------------------------------------------------
+
+export async function replayHeldMessages(
+  userId: string,
+  guildId: string,
+  client: Client,
+): Promise<void> {
+  const threadIds = await sessionManager.getGuildThreadIds(guildId);
+
+  for (const threadId of threadIds) {
+    const session = await sessionManager.get(threadId);
+    if (!session || session.phase === 'resolved') continue;
+
+    const held = session.heldMessages.filter(m => m.discordUserId === userId);
+    if (held.length === 0) continue;
+
+    // Remove held messages before replaying so a crash doesn't double-replay
+    await sessionManager.update(threadId, {
+      heldMessages: session.heldMessages.filter(m => m.discordUserId !== userId),
+    });
+
+    const thread = await client.channels.fetch(threadId).catch(() => null);
+    if (!thread?.isThread()) continue;
+
+    const freshSession = await sessionManager.get(threadId);
+    if (!freshSession) continue;
+
+    for (const msg of held) {
+      const syntheticId = `held-${userId}-${msg.timestamp}`;
+      await processEncounterMessage(freshSession, thread as ThreadChannel, userId, msg.content, client, syntheticId);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Core message processing pipeline
+// ---------------------------------------------------------------------------
+
+async function processEncounterMessage(
+  session: SessionState,
+  thread: ThreadChannel | TextChannel,
+  userId: string,
+  content: string,
+  client: Client,
+  messageId: string,
+  sourceMessage?: Message,
+): Promise<void> {
+  const guildId = session.guildId;
+
+  // ── Text roll fallback — lets players type "I rolled a 17 Acrobatics" if preferred
+  const rollMatch = ROLL_RE.exec(content);
+  if (rollMatch && session.pendingSkillCheck) {
+    const roll = parseInt(rollMatch[1], 10);
+    const skill = rollMatch[2].trim();
+    const { dc, player, messageId } = session.pendingSkillCheck;
+    const success = roll >= dc;
+
+    // Disable the embed buttons since the roll is resolved
+    if (messageId) {
+      const original = await (thread as ThreadChannel).messages?.fetch(messageId).catch(() => null);
+      if (original) await original.edit({ components: [] }).catch(() => null);
+    }
+
+    const systemMsg: ChatMessage = {
+      role: 'system',
+      content: `[SKILL CHECK RESULT] ${player} rolled ${roll} ${skill} vs DC ${dc}. Result: ${success ? 'SUCCESS' : 'FAILURE'}.`,
+      timestamp: Date.now(),
+    };
+
+    await sessionManager.update(session.threadId, {
+      pendingSkillCheck: undefined,
+      pendingSkillCheckAttempts: undefined,
+    });
+    await sessionManager.addMessage(session.threadId, systemMsg);
+    scheduleEncounterLLMTurn(session.threadId, thread, client, true);
+    return;
+  }
+
+  // ── Player gate
+  const player = await playerRegistry.get(guildId, userId);
+  if (!player) {
+    const held = [...session.heldMessages, { discordUserId: userId, content, timestamp: Date.now() }];
+    await sessionManager.update(session.threadId, { heldMessages: held });
+
+    const gate = buildPlayerGateEmbed();
+    const sent = await thread.send({ content: `<@${userId}>`, embeds: [gate] });
+    setTimeout(() => sent.delete().catch(() => null), 30_000);
+    return;
+  }
+
+  // ── Block messages while a dice roll is pending
+  if (session.pendingSkillCheck) {
+    const attempts = (session.pendingSkillCheckAttempts ?? 0) + 1;
+
+    if (attempts >= PENDING_ROLL_LIMIT) {
+      // Auto-cancel: disable the embed buttons and inject a FAIL result
+      const { messageId, player: checkPlayer, dc } = session.pendingSkillCheck;
+      if (messageId) {
+        const original = await (thread as ThreadChannel).messages?.fetch(messageId).catch(() => null);
+        if (original) await original.edit({ components: [] }).catch(() => null);
+      }
+
+      const failMsg: ChatMessage = {
+        role: 'system',
+        content: `[SKILL CHECK RESULT] ${checkPlayer} failed to roll vs DC ${dc}. Result: FAILURE (auto-cancelled after ${PENDING_ROLL_LIMIT} skipped messages).`,
+        timestamp: Date.now(),
+      };
+
+      await sessionManager.update(session.threadId, {
+        pendingSkillCheck: undefined,
+        pendingSkillCheckAttempts: undefined,
+      });
+      await sessionManager.addMessage(session.threadId, failMsg);
+      scheduleEncounterLLMTurn(session.threadId, thread, client, true);
+      return;
+    }
+
+    await sessionManager.update(session.threadId, { pendingSkillCheckAttempts: attempts });
+    const remaining = PENDING_ROLL_LIMIT - attempts;
+    await thread.send(
+      `*A roll is still pending! Use the buttons above to roll. (${remaining} message${remaining === 1 ? '' : 's'} left before auto-fail.)*`,
+    );
+    return;
+  }
+
+  // ── Burst cap — drop message if too many arrived before the last LLM response
+  if (isBurstCapped(session.threadId)) {
+    if (sourceMessage) {
+      const botId = sourceMessage.client.user?.id;
+      if (botId) {
+        sourceMessage.reactions.cache.find(r => r.emoji.name === '👀')?.users.remove(botId).catch(() => null);
+      }
+      await sendDropNotice(sourceMessage, session.spec.tone);
+    }
+    return;
+  }
+  incrementBurst(session.threadId);
+
+  // ── Add player to session if first appearance
+  if (!session.players[userId]) {
+    const charProfile = await characterRegistry.get(session.guildId, userId).catch(() => null);
+    const playerEntry = charProfile?.pronouns
+      ? { ...player, pronouns: charProfile.pronouns }
+      : player;
+    const updatedPlayers = { ...session.players, [userId]: playerEntry };
+    const joinMsg: ChatMessage = {
+      role: 'system',
+      content: `[SESSION] ${player.dndName} has entered the encounter.`,
+      timestamp: Date.now(),
+    };
+    await sessionManager.update(session.threadId, {
+      players: updatedPlayers,
+      phase: 'active',
+    });
+    await sessionManager.addMessage(session.threadId, joinMsg);
+  }
+
+  // ── Append player message to history
+  const userMsg: ChatMessage = {
+    role: 'user',
+    content: `${player.dndName}: ${content}`,
+    timestamp: Date.now(),
+  };
+  await sessionManager.addMessage(session.threadId, userMsg);
+
+  // Publish to GraphMCP — only messages that passed both gates (registered
+  // player + no pending roll) reach this point, so the LLM will see them.
+  publishToGraphMCP({
+    messageId,
+    content,
+    author: player.dndName,
+    channelId: thread.id,
+    channelName: thread.name,
+  }).catch(err => console.warn('[ingest] encounter publish failed:', err));
+
+  // Debounced: waits 500ms for any further messages before firing the LLM,
+  // so a burst of player chat coalesces into a single response.
+  scheduleEncounterLLMTurn(session.threadId, thread, client, false, sourceMessage);
+}
+
+// ---------------------------------------------------------------------------
+// Queue-aware scheduler — always fetches fresh session before firing.
+// Pass immediate=true for roll results / slash commands (no debounce).
+// ---------------------------------------------------------------------------
+
+export function scheduleEncounterLLMTurn(
+  threadId: string,
+  thread: ThreadChannel | TextChannel,
+  client: Client,
+  immediate = false,
+  sourceMessage?: Message,
+): void {
+  if (sourceMessage) {
+    registerScheduled(threadId, sourceMessage);
+  }
+
+  scheduleLLMTurn(
+    threadId,
+    async () => {
+      const s = await sessionManager.get(threadId);
+      if (!s || s.phase === 'resolved') {
+        clearPending(threadId);
+        return;
+      }
+      // Don't call the LLM while a roll is pending — the roll handler will
+      // schedule a fresh turn once the result arrives.
+      if (s.pendingSkillCheck) {
+        clearPending(threadId);
+        return;
+      }
+
+      const pending = drainPending(threadId);
+      upgradeToProcessing(pending);
+      let completedOk = false;
+      try {
+        await runLLMTurn(s, thread, client);
+        upgradeToComplete(pending);
+        completedOk = true;
+      } finally {
+        if (!completedOk) cleanupReactions(pending);
+        resetBurst(threadId);
+      }
+    },
+    immediate,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// LLM call + response routing — exported for use by rollHandler
+// ---------------------------------------------------------------------------
+
+export async function runLLMTurn(
+  session: SessionState,
+  thread: ThreadChannel | TextChannel,
+  _client: Client,
+): Promise<void> {
+  const context = assembleContext(session);
+
+  void thread.sendTyping();
+  const typingInterval = setInterval(() => void thread.sendTyping(), 8_000);
+
+  let response;
+  try {
+    response = await callLLM(context);
+  } catch (err) {
+    clearInterval(typingInterval);
+    console.error('[messageRouter] LLM call failed:', err);
+    await thread.send('*The narrator pauses, lost in thought… (LLM error, please retry)*');
+    return;
+  }
+  clearInterval(typingInterval);
+
+  if (!response.toolCall && !session.pendingSkillCheck && response.narrative) {
+    if (detectMissedSkillCheck(response.narrative)) {
+      log.warn('harness', 'possible_missed_skill_check', {
+        threadId: session.threadId,
+        encounterId: session.encounterId,
+        narrativeSnippet: response.narrative.slice(0, 200),
+      });
+    }
+  }
+
+  if (response.narrative) {
+    const filter = filterLLMResponse(response.narrative);
+    if (!filter.ok) {
+      logFiltered(filter.reason!, response.narrative, {
+        threadId: session.threadId,
+        encounterId: session.encounterId,
+      });
+
+      // Guard against tight retry loops: skip if we just injected a correction.
+      const lastMsg = session.history[session.history.length - 1];
+      const alreadyRetried = lastMsg?.role === 'system' && lastMsg.content.startsWith('[FILTER CORRECTION]');
+
+      if (!alreadyRetried) {
+        const correctionText = filter.reason === 'fabricated_roll_result'
+          ? 'Do NOT state or imply a specific dice result. Wait for the [SKILL CHECK RESULT] system message before narrating any outcome.'
+          : filter.reason === 'echoed_system_tag'
+          ? 'Do NOT echo internal system tags like [TOOL], [SESSION], or [SKILL CHECK] verbatim in your response.'
+          : 'Your previous response was empty. Continue the scene.';
+
+        const correction: ChatMessage = {
+          role: 'system',
+          content: `[FILTER CORRECTION] Your last response was suppressed (${filter.reason}). ${correctionText}`,
+          timestamp: Date.now(),
+        };
+        await sessionManager.addMessage(session.threadId, correction);
+
+        // Retry once with the correction in context.
+        scheduleEncounterLLMTurn(session.threadId, thread, _client, true);
+      }
+      // Fall through so any accompanying tool call still fires.
+    } else {
+      await thread.send(response.narrative);
+      // Only store an assistant message when there is actual narrative.
+      // Tool-call-only turns are represented solely by the system message the
+      // tool handler writes. Storing a placeholder teaches the LLM to echo it.
+      const assistantMsg: ChatMessage = {
+        role: 'assistant',
+        content: response.narrative,
+        timestamp: Date.now(),
+      };
+      await sessionManager.addMessage(session.threadId, assistantMsg);
+    }
+  }
+
+  if (response.toolCall) {
+    const freshSession = await sessionManager.get(session.threadId);
+    if (!freshSession) return;
+
+    const result = await dispatchTool(response.toolCall, { session: freshSession, thread });
+
+    const toolMsg: ChatMessage = {
+      role: 'system',
+      content: result.systemMessage,
+      timestamp: Date.now(),
+    };
+    await sessionManager.addMessage(session.threadId, toolMsg);
+
+    if (result.error) {
+      await thread.send('*The narrator stumbles… something went wrong behind the scenes. Try your action again.*');
+    }
+
+    if (result.resolved) {
+      await sessionManager.update(session.threadId, {
+        phase: 'resolved',
+        outcome: result.resolved.outcomeId,
+        outcomeSummary: result.resolved.summary,
+      });
+      setTimeout(async () => {
+        await (thread as ThreadChannel).setArchived?.(true).catch(() => null);
+      }, 5_000);
+    }
+  }
+}
diff --git a/src/bot/handlers/queueCap.ts b/src/bot/handlers/queueCap.ts
new file mode 100644
index 0000000..d772c15
--- /dev/null
+++ b/src/bot/handlers/queueCap.ts
@@ -0,0 +1,58 @@
+// Per-thread burst message cap and in-world drop notice delivery.
+// The burst counter tracks how many player messages have been added to the
+// session history since the last LLM turn. Messages beyond the cap of 2 are
+// dropped without reaching the LLM.
+
+import type { Message } from 'discord.js';
+
+// ---------------------------------------------------------------------------
+// Burst counter — module-level, ephemeral (resets on bot restart)
+// ---------------------------------------------------------------------------
+
+const CAP = 2;
+
+const burstCount = new Map<string, number>();
+
+export function isBurstCapped(threadId: string): boolean {
+  return (burstCount.get(threadId) ?? 0) >= CAP;
+}
+
+export function incrementBurst(threadId: string): void {
+  burstCount.set(threadId, (burstCount.get(threadId) ?? 0) + 1);
+}
+
+export function resetBurst(threadId: string): void {
+  burstCount.delete(threadId);
+}
+
+// ---------------------------------------------------------------------------
+// Drop notice strings — keyed by encounter tone, pre-generated (no LLM call)
+// ---------------------------------------------------------------------------
+
+const DROP_NOTICES: Record<string, string> = {
+  grim: '*"The chaos swallowed your words before they could reach the moment. Silence yourself until the echoes clear."*',
+  comedic: '*"Everyone was talking at once and the universe, frankly, wasn\'t listening. Give it a moment."*',
+  mysterious: '*"Something in the fabric of this place muffled your voice. Wait. It will pass."*',
+  tense: '*"No time — the moment moved on without you. Hold. Wait for your opening."*',
+  baseline: '*"The echoes of the encounter could not carry all voices at once. Wait for the dust to settle before speaking again."*',
+};
+
+export function getDropNotice(tone?: string): string {
+  if (tone && tone in DROP_NOTICES) return DROP_NOTICES[tone];
+  return DROP_NOTICES.baseline;
+}
+
+// ---------------------------------------------------------------------------
+// Drop notice delivery — DM preferred; thread reply + auto-delete as fallback
+// ---------------------------------------------------------------------------
+
+export async function sendDropNotice(msg: Message, tone?: string): Promise<void> {
+  const text = getDropNotice(tone);
+  try {
+    await msg.author.send(text);
+  } catch {
+    // DMs disabled — reply in thread and auto-delete after 8s
+    const sent = await msg.reply({ content: text }).catch(() => null);
+    if (sent) setTimeout(() => sent.delete().catch(() => null), 8_000);
+  }
+}
diff --git a/src/bot/handlers/reactionManager.ts b/src/bot/handlers/reactionManager.ts
new file mode 100644
index 0000000..0835773
--- /dev/null
+++ b/src/bot/handlers/reactionManager.ts
@@ -0,0 +1,90 @@
+// Manages per-thread pending message reaction tracking.
+// All Discord API calls are fire-and-forget — errors are swallowed.
+
+import type { Message } from 'discord.js';
+
+export interface PendingEntry {
+  msg: Message;
+  content: string;
+}
+
+// ---------------------------------------------------------------------------
+// Pending map — module-level, reset on bot restart (ephemeral by design)
+// ---------------------------------------------------------------------------
+
+const pendingByThread = new Map<string, PendingEntry[]>();
+
+export function registerScheduled(threadId: string, msg: Message): void {
+  const entries = pendingByThread.get(threadId) ?? [];
+  entries.push({ msg, content: msg.content });
+  pendingByThread.set(threadId, entries);
+}
+
+export function drainPending(threadId: string): PendingEntry[] {
+  const entries = pendingByThread.get(threadId) ?? [];
+  pendingByThread.delete(threadId);
+  return entries;
+}
+
+export function clearPending(threadId: string): void {
+  pendingByThread.delete(threadId);
+}
+
+// ---------------------------------------------------------------------------
+// Heuristic — detect dice-related intent in a player message
+// ---------------------------------------------------------------------------
+
+const DICE_INTENT_RE = /\b(?:roll|attack|check|save|saving throw|d20)\b/i;
+
+export function isDiceRelated(content: string): boolean {
+  return DICE_INTENT_RE.test(content);
+}
+
+// ---------------------------------------------------------------------------
+// Reaction removal helper
+// ---------------------------------------------------------------------------
+
+function removeBotReaction(msg: Message, emoji: string): void {
+  const botId = msg.client.user?.id;
+  if (!botId) return;
+  msg.reactions.cache
+    .find(r => r.emoji.name === emoji)
+    ?.users.remove(botId)
+    .catch(() => null);
+}
+
+// ---------------------------------------------------------------------------
+// Lifecycle functions
+// ---------------------------------------------------------------------------
+
+export function upgradeToProcessing(entries: PendingEntry[]): void {
+  for (const { msg, content } of entries) {
+    removeBotReaction(msg, '👀');
+    msg.react('⏳').catch(() => null);
+    if (isDiceRelated(content)) {
+      msg.react('🎲').catch(() => null);
+    }
+  }
+}
+
+export function upgradeToComplete(entries: PendingEntry[]): void {
+  for (const { msg } of entries) {
+    removeBotReaction(msg, '⏳');
+    removeBotReaction(msg, '🎲');
+    msg.react('✅').catch(() => null);
+    const botId = msg.client.user?.id;
+    setTimeout(() => {
+      if (botId) {
+        msg.reactions.cache.find(r => r.emoji.name === '✅')?.users.remove(botId).catch(() => null);
+      }
+    }, 10_000);
+  }
+}
+
+export function cleanupReactions(entries: PendingEntry[]): void {
+  for (const { msg } of entries) {
+    removeBotReaction(msg, '👀');
+    removeBotReaction(msg, '⏳');
+    removeBotReaction(msg, '🎲');
+  }
+}
diff --git a/src/bot/handlers/responseFilter.ts b/src/bot/handlers/responseFilter.ts
new file mode 100644
index 0000000..2e82d05
--- /dev/null
+++ b/src/bot/handlers/responseFilter.ts
@@ -0,0 +1,67 @@
+import { log } from '../../lib/logger.js';
+
+// ---------------------------------------------------------------------------
+// Patterns
+// ---------------------------------------------------------------------------
+
+// LLM echoing internal system message tags verbatim
+const SYSTEM_TAG_RE = /\[TOOL[^\]]*\]|\[SKILL CHECK[^\]]*\]|\[SESSION[^\]]*\]|\[\/roll[^\]]*\]|\[SYSTEM[^\]]*\]/i;
+
+// LLM claiming a specific dice roll result (the bot controls dice, not the LLM).
+// Catches: "you rolled a 15", "the brawler rolled a 12", "rolls a 7", "the die shows", etc.
+const ROLL_CLAIM_RE = /\brolled\s+(?:a\s+)?\d+\b|\bthe die shows\b|\bthe dice (?:show|showed)\b|\brolls?\s+(?:a\s+)?\d+\b/i;
+
+// LLM describing that a skill check is needed but without emitting skill_check_emit.
+// Used as a diagnostic heuristic — only meaningful when no tool call was present in the response.
+// Catches: "you need to roll", "roll for X", "roll your X", "requires a check/roll",
+//          "make a [X] check/save/saving throw", "attempt a [X] check/roll"
+const MISSED_SKILL_CHECK_RE =
+  /\byou(?:'ll| will)?\s+need\s+to\s+(?:make\s+(?:a\s+)?)?roll\b|\broll\s+(?:for|your)\s+\w|\brequires\s+a\s+(?:\w+\s+)?(?:roll|check)\b|\bmake\s+a\s+(?:\w+\s+){0,3}(?:check|saving throw|save)\b|\battempt\s+(?:a\s+)?(?:\w+\s+)?(?:check|roll)\b/i;
+
+// ---------------------------------------------------------------------------
+// Public
+// ---------------------------------------------------------------------------
+
+export interface FilterResult {
+  ok: boolean;
+  reason?: string;
+}
+
+export function filterLLMResponse(narrative: string): FilterResult {
+  if (!narrative.trim()) {
+    return { ok: false, reason: 'empty_response' };
+  }
+
+  if (SYSTEM_TAG_RE.test(narrative)) {
+    return { ok: false, reason: 'echoed_system_tag' };
+  }
+
+  if (ROLL_CLAIM_RE.test(narrative)) {
+    return { ok: false, reason: 'fabricated_roll_result' };
+  }
+
+  return { ok: true };
+}
+
+/**
+ * Heuristic: did the LLM describe a skill check as needed but omit the tool call?
+ * Call this only when no tool_call block was present in the response and no roll is pending.
+ * Returns true when the narrative appears to request a roll from the player.
+ */
+export function detectMissedSkillCheck(narrative: string): boolean {
+  if (!narrative.trim()) return false;
+  return MISSED_SKILL_CHECK_RE.test(narrative);
+}
+
+export function logFiltered(
+  reason: string,
+  narrative: string,
+  context: { threadId: string; encounterId: string },
+): void {
+  log.warn('llm-filter', reason, {
+    threadId: context.threadId,
+    encounterId: context.encounterId,
+    // Full narrative in a separate field so structured log viewers can expand it
+    filteredNarrative: narrative,
+  });
+}
diff --git a/src/bot/handlers/rollHandler.ts b/src/bot/handlers/rollHandler.ts
new file mode 100644
index 0000000..d6bdcdf
--- /dev/null
+++ b/src/bot/handlers/rollHandler.ts
@@ -0,0 +1,181 @@
+import {
+  type ButtonInteraction,
+  type ModalSubmitInteraction,
+  type Client,
+  type ThreadChannel,
+  type TextChannel,
+  ModalBuilder,
+  TextInputBuilder,
+  TextInputStyle,
+  ActionRowBuilder,
+} from 'discord.js';
+import { sessionManager } from '../../session/sessionManager.js';
+import { buildSkillCheckEmbed, buildModifierRollButtons, EMBED_COLOR } from '../embeds/skillCheck.js';
+import { scheduleEncounterLLMTurn } from './messageRouter.js';
+import type { ChatMessage } from '../../types/index.js';
+
+type RollChannel = ThreadChannel | TextChannel;
+
+function d20(): number {
+  return Math.floor(Math.random() * 20) + 1;
+}
+
+function rollSingle(): { value: number; desc: string } {
+  const value = d20();
+  return { value, desc: `rolled **${value}**` };
+}
+
+function rollAdvantage(): { value: number; desc: string } {
+  const a = d20(), b = d20();
+  const value = Math.max(a, b);
+  return { value, desc: `rolled with advantage (${a}, ${b}) → **${value}**` };
+}
+
+function rollDisadvantage(): { value: number; desc: string } {
+  const a = d20(), b = d20();
+  const value = Math.min(a, b);
+  return { value, desc: `rolled with disadvantage (${a}, ${b}) → **${value}**` };
+}
+
+async function submitResult(
+  interaction: ButtonInteraction,
+  roll: { value: number; desc: string },
+  modifier: number,
+  client: Client,
+): Promise<void> {
+  const channel = interaction.channel as RollChannel | null;
+  if (!channel?.isThread()) return;
+
+  const session = await sessionManager.get(channel.id);
+  if (!session?.pendingSkillCheck) {
+    await interaction.reply({ content: 'This skill check has already been resolved.', flags: 64 });
+    return;
+  }
+
+  const { dc, player, prompt } = session.pendingSkillCheck;
+  const total = roll.value + modifier;
+  const success = total >= dc;
+
+  const modPart = modifier !== 0
+    ? ` ${modifier >= 0 ? '+' : ''}${modifier} = **${total}**`
+    : '';
+  const fullDesc = roll.desc + modPart;
+
+  const resultEmbed = buildSkillCheckEmbed(
+    player, prompt, dc,
+    success ? EMBED_COLOR.SUCCESS : EMBED_COLOR.FAILURE,
+    success ? '✅ Success' : '❌ Failure',
+  ).addFields(
+    { name: 'Roll', value: fullDesc, inline: true },
+    { name: 'Result', value: success ? '✅ SUCCESS' : '❌ FAILURE', inline: true },
+  );
+
+  await interaction.update({ embeds: [resultEmbed], components: [] });
+
+  const systemMsg: ChatMessage = {
+    role: 'system',
+    content: `[SKILL CHECK RESULT] ${player} ${fullDesc} vs DC ${dc}. Result: ${success ? 'SUCCESS' : 'FAILURE'}.`,
+    timestamp: Date.now(),
+  };
+
+  await sessionManager.update(session.threadId, {
+    pendingSkillCheck: undefined,
+    pendingSkillCheckAttempts: undefined,
+  });
+  await sessionManager.addMessage(session.threadId, systemMsg);
+  scheduleEncounterLLMTurn(session.threadId, channel, client, true);
+}
+
+export function isSkillCheckInteraction(
+  interaction: ButtonInteraction | ModalSubmitInteraction,
+): boolean {
+  if (interaction.isButton()) return interaction.customId.startsWith('sc_');
+  if (interaction.isModalSubmit()) return interaction.customId === 'sc_mod_modal';
+  return false;
+}
+
+export async function handleRollInteraction(
+  interaction: ButtonInteraction | ModalSubmitInteraction,
+  client: Client,
+): Promise<void> {
+  if (interaction.isButton()) {
+    const id = interaction.customId;
+
+    if (id === 'sc_roll') return submitResult(interaction, rollSingle(), 0, client);
+    if (id === 'sc_adv') return submitResult(interaction, rollAdvantage(), 0, client);
+    if (id === 'sc_dis') return submitResult(interaction, rollDisadvantage(), 0, client);
+
+    if (id === 'sc_mod') {
+      const modal = new ModalBuilder()
+        .setCustomId('sc_mod_modal')
+        .setTitle('Enter your modifier')
+        .addComponents(
+          new ActionRowBuilder<TextInputBuilder>().addComponents(
+            new TextInputBuilder()
+              .setCustomId('modifier_value')
+              .setLabel('Modifier (e.g. +3, -1, 5)')
+              .setStyle(TextInputStyle.Short)
+              .setRequired(true)
+              .setMaxLength(4),
+          ),
+        );
+      await interaction.showModal(modal);
+      return;
+    }
+
+    // sc_roll_m:3, sc_adv_m:-2, sc_dis_m:1
+    const modMatch = /^sc_(roll|adv|dis)_m:(-?\d+)$/.exec(id);
+    if (modMatch) {
+      const type = modMatch[1];
+      const modifier = parseInt(modMatch[2], 10);
+      const roll =
+        type === 'adv' ? rollAdvantage() :
+        type === 'dis' ? rollDisadvantage() :
+        rollSingle();
+      return submitResult(interaction, roll, modifier, client);
+    }
+
+    return;
+  }
+
+  // Modal submit for modifier
+  if (interaction.isModalSubmit() && interaction.customId === 'sc_mod_modal') {
+    const channel = interaction.channel as RollChannel | null;
+    if (!channel?.isThread()) return;
+
+    const session = await sessionManager.get(channel.id);
+    if (!session?.pendingSkillCheck) {
+      await interaction.reply({ content: 'This skill check has already been resolved.', flags: 64 });
+      return;
+    }
+
+    const rawMod = interaction.fields.getTextInputValue('modifier_value').trim();
+    const modifier = parseInt(rawMod.replace(/^\+/, ''), 10);
+    if (isNaN(modifier)) {
+      await interaction.reply({
+        content: 'Invalid modifier — enter a number like `+3`, `-1`, or `5`.',
+        flags: 64,
+      });
+      return;
+    }
+
+    // Remove buttons from the original skill check embed now that modifier flow is active
+    const { messageId, player, prompt, dc, modifier: charModifier, skill } = session.pendingSkillCheck;
+    if (messageId) {
+      const original = await (channel as ThreadChannel).messages.fetch(messageId).catch(() => null);
+      if (original) {
+        const bare = buildSkillCheckEmbed(player, prompt, dc, undefined, undefined, charModifier, skill);
+        await original.edit({ embeds: [bare], components: [] }).catch(() => null);
+      }
+    }
+
+    const sign = modifier >= 0 ? `+${modifier}` : String(modifier);
+    const modEmbed = buildSkillCheckEmbed(player, prompt, dc)
+      .setFooter({ text: `Modifier: ${sign}` });
+
+    await interaction.reply({
+      embeds: [modEmbed],
+      components: [buildModifierRollButtons(modifier)],
+    });
+  }
+}
diff --git a/src/bot/index.ts b/src/bot/index.ts
new file mode 100644
index 0000000..cb61807
--- /dev/null
+++ b/src/bot/index.ts
@@ -0,0 +1,185 @@
+import { Client, GatewayIntentBits, Collection } from 'discord.js';
+import 'dotenv/config';
+import { config } from '../config.js';
+import { redis } from '../db/redis.js';
+import { handleMessage } from './handlers/messageRouter.js';
+import { handleMention } from './handlers/mentionHandler.js';
+import { handleRollInteraction, isSkillCheckInteraction } from './handlers/rollHandler.js';
+import * as dndnameCmd from './commands/dndname.js';
+import * as encounterCmd from './commands/encounter.js';
+import * as characterCmd from './commands/character.js';
+import * as rollCmd from './commands/roll.js';
+import * as actionsCmd from './commands/actions.js';
+import * as xpCmd from './commands/xp.js';
+import * as encountersCmd from './commands/encounters.js';
+import { handleGiveModal, handleFoundryLinkModal, handleCustomRegisterModal } from './commands/character.js';
+import { handleEncounterSelect, handleSearchButton, handleSearchModalSubmit } from './commands/encounters.js';
+import { log } from '../lib/logger.js';
+
+// ---------------------------------------------------------------------------
+// Command registry
+// ---------------------------------------------------------------------------
+
+type CommandModule = {
+  data: { name: string };
+  execute: (interaction: any, client: Client) => Promise<void>;
+};
+
+const commands = new Collection<string, CommandModule>();
+commands.set('dndname', dndnameCmd as CommandModule);
+commands.set('encounter', encounterCmd as CommandModule);
+commands.set('character', characterCmd as CommandModule);
+commands.set('roll', rollCmd as CommandModule);
+commands.set('actions', actionsCmd as CommandModule);
+commands.set('xp', xpCmd as CommandModule);
+commands.set('encounters', encountersCmd as CommandModule);
+
+// ---------------------------------------------------------------------------
+// Discord client
+// ---------------------------------------------------------------------------
+
+const client = new Client({
+  intents: [
+    GatewayIntentBits.Guilds,
+    GatewayIntentBits.GuildMessages,
+    GatewayIntentBits.MessageContent, // Privileged — enable in Discord Dev Portal
+  ],
+});
+
+client.once('ready', () => {
+  console.log(`[bot] Logged in as ${client.user?.tag}`);
+});
+
+client.on('interactionCreate', async (interaction) => {
+  // ── Skill-check roll buttons and modifier modal
+  if (
+    (interaction.isButton() || interaction.isModalSubmit()) &&
+    isSkillCheckInteraction(interaction)
+  ) {
+    const kind = interaction.isButton() ? 'button' : 'modal';
+    const id = interaction.isButton() ? interaction.customId : interaction.customId;
+    log.info('interaction', `${kind} ${id}`, { user: interaction.user.username });
+    const start = Date.now();
+    try {
+      await handleRollInteraction(interaction, client);
+      log.info('interaction', `${kind} ok`, { id, latencyMs: Date.now() - start });
+    } catch (err) {
+      log.error('interaction', `${kind} error`, { id, error: String(err) });
+    }
+    return;
+  }
+
+  // ── Give item: modal submitted → search relay by name, call giveItem
+  if (interaction.isModalSubmit() && interaction.customId === 'give_modal') {
+    try {
+      await handleGiveModal(interaction);
+    } catch (err) {
+      log.error('interaction', 'give_modal error', { error: String(err) });
+    }
+    return;
+  }
+
+  // ── Custom character registration modal
+  if (interaction.isModalSubmit() && interaction.customId === 'character_custom_modal') {
+    try {
+      await handleCustomRegisterModal(interaction);
+    } catch (err) {
+      log.error('interaction', 'character_custom_modal error', { error: String(err) });
+    }
+    return;
+  }
+
+  // ── Foundry link: modal submitted → search relay by name, save to registry
+  if (interaction.isModalSubmit() && interaction.customId === 'foundry_link_modal') {
+    try {
+      await handleFoundryLinkModal(interaction);
+    } catch (err) {
+      log.error('interaction', 'foundry_link_modal error', { error: String(err) });
+    }
+    return;
+  }
+
+  // ── Encounters Select Menu Interaction
+  if (interaction.isStringSelectMenu() && interaction.customId === 'encounters_select') {
+    try {
+      await handleEncounterSelect(interaction);
+    } catch (err) {
+      log.error('interaction', 'encounters_select error', { error: String(err) });
+    }
+    return;
+  }
+
+  // ── Encounters Search Button Interaction
+  if (interaction.isButton() && interaction.customId === 'encounters_search_btn') {
+    try {
+      await handleSearchButton(interaction);
+    } catch (err) {
+      log.error('interaction', 'encounters_search_btn error', { error: String(err) });
+    }
+    return;
+  }
+
+  // ── Encounters Search Modal Submit Interaction
+  if (interaction.isModalSubmit() && interaction.customId === 'encounters_search_modal') {
+    try {
+      await handleSearchModalSubmit(interaction);
+    } catch (err) {
+      log.error('interaction', 'encounters_search_modal error', { error: String(err) });
+    }
+    return;
+  }
+
+  if (!interaction.isChatInputCommand()) return;
+
+  const command = commands.get(interaction.commandName);
+  if (!command) return;
+
+  // Build a label that includes the subcommand when present (e.g. "encounter start")
+  const sub = interaction.options.getSubcommand(false);
+  const label = sub ? `${interaction.commandName} ${sub}` : interaction.commandName;
+
+  log.info('cmd', `/${label}`, {
+    user: interaction.user.username,
+    guild: interaction.guildId ?? undefined,
+    channel: interaction.channelId,
+  });
+  const start = Date.now();
+
+  try {
+    await command.execute(interaction, client);
+    log.info('cmd', `/${label} ok`, { latencyMs: Date.now() - start });
+  } catch (err) {
+    log.error('cmd', `/${label} error`, { latencyMs: Date.now() - start, error: String(err) });
+    const reply = { content: 'An error occurred.', ephemeral: true };
+    if (interaction.deferred || interaction.replied) {
+      await interaction.editReply(reply).catch(() => null);
+    } else {
+      await interaction.reply(reply).catch(() => null);
+    }
+  }
+});
+
+client.on('messageCreate', async (message) => {
+  try {
+    await handleMention(message, client);
+    await handleMessage(message, client);
+  } catch (err) {
+    console.error('[bot] messageCreate error:', err);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Startup
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  await redis.connect();
+  console.log('[bot] Redis connected');
+
+  await client.login(config.DISCORD_TOKEN);
+}
+
+main().catch((err) => {
+  console.error('[bot] startup failed:', err);
+  process.exit(1);
+});
diff --git a/src/bot/lib/welcomeDM.ts b/src/bot/lib/welcomeDM.ts
new file mode 100644
index 0000000..cde14c5
--- /dev/null
+++ b/src/bot/lib/welcomeDM.ts
@@ -0,0 +1,53 @@
+import { EmbedBuilder } from 'discord.js';
+import type { User } from 'discord.js';
+
+export async function sendWelcomeDM(user: User, guildName?: string): Promise<void> {
+  const embed = new EmbedBuilder()
+    .setTitle('⚔️  Welcome to the Encounter Table!')
+    .setDescription(
+      guildName
+        ? `*A message from the scribes of **${guildName}**...*`
+        : '*A message from the scribes...*',
+    )
+    .setColor(0x5865f2)
+    .addFields(
+      {
+        name: '📖  How it works',
+        value:
+          'An AI Dungeon Master narrates encounters in real-time inside dedicated threads. ' +
+          'Type what your character does — the DM responds, NPCs react, and the world moves. ' +
+          'Skill checks, combat, roleplay — all handled live.',
+      },
+      {
+        name: '🎲  Commands you\'ll use',
+        value: [
+          '`/roll <action>` — Attempt something risky. Describes what you\'re trying to do and asks the DM to call for a check if it warrants one.',
+          '`/actions` — View your current inventory and prepared spells from Foundry VTT.',
+          '`/character view` — Fetch your live character stats: HP, AC, abilities, and more.',
+          '`/character show` — See your registered character profile.',
+          '`/character register foundry` — Link your Foundry VTT character for live modifiers and inventory.',
+        ].join('\n'),
+      },
+      {
+        name: '🎯  Skill checks',
+        value:
+          'When a check is called, a panel appears with **Roll**, **Advantage**, and **Disadvantage** buttons. ' +
+          'If your character is linked to Foundry, your modifier is pre-loaded automatically. ' +
+          'Click to roll — no maths required.',
+      },
+      {
+        name: '💡  Tips',
+        value: [
+          '• Be specific with your actions — *"I try to pick the lock using my thieves\' tools"* lands better than *"I pick the lock"*.',
+          '• The DM remembers NPC reactions and past events across sessions — your reputation carries.',
+          '• If a roll is pending, resolve it before sending more messages or it will auto-fail.',
+          '• Use `/roll` to explicitly request a skill check if the DM hasn\'t called one.',
+        ].join('\n'),
+      },
+    )
+    .setFooter({ text: 'May your rolls be high and your saving throws blessed.' });
+
+  await user.send({ embeds: [embed] }).catch(() => {
+    // DMs may be disabled — silently ignore, it's not critical
+  });
+}
diff --git a/src/config.ts b/src/config.ts
new file mode 100644
index 0000000..baf55b1
--- /dev/null
+++ b/src/config.ts
@@ -0,0 +1,79 @@
+import { z } from 'zod';
+import 'dotenv/config';
+
+const EnvSchema = z.object({
+  // ── Discord ──────────────────────────────────────────────────────────────
+  DISCORD_TOKEN: z.string(),
+  DISCORD_CLIENT_ID: z.string(),
+  DISCORD_GUILD_ID: z.string().optional(),
+  // Comma-separated channel IDs. Threads checked against parent. Empty = nowhere.
+  DISCORD_ALLOWED_CHANNELS: z
+    .string()
+    .default('')
+    .transform(val => val.split(',').map(s => s.trim()).filter(Boolean)),
+  // Comma-separated user IDs who can run /encounter commands. Empty = everyone.
+  DISCORD_ALLOWED_USERS: z
+    .string()
+    .default('')
+    .transform(val => val.split(',').map(s => s.trim()).filter(Boolean)),
+
+  // ── Redis ────────────────────────────────────────────────────────────────
+  REDIS_URL: z.string().default('redis://localhost:6379'),
+  // How long a session lives in Redis without activity (hours).
+  SESSION_TTL_HOURS: z.coerce.number().default(12),
+
+  // ── LiteLLM (primary) ────────────────────────────────────────────────────
+  // If set, LiteLLM is used as the primary LLM client with Ollama as fallback.
+  LITELLM_BASE_URL: z.string().default('http://100.83.8.74:4000'),
+  LITELLM_API_KEY: z.string().optional(),
+  // Model name as configured in LiteLLM. Defaults to OLLAMA_MODEL if unset.
+  LITELLM_MODEL: z.string().optional(),
+
+  // ── Ollama / LLM ─────────────────────────────────────────────────────────
+  OLLAMA_BASE_URL: z.string().default('http://localhost:11434'),
+  OLLAMA_MODEL: z.string().default('gemma4-it:e2b'),
+  // Sampling temperature. Higher = more creative, lower = more predictable.
+  OLLAMA_TEMPERATURE: z.coerce.number().min(0).max(2).default(0.75),
+  // Context window passed to Ollama (tokens). Must match the model's max.
+  OLLAMA_NUM_CTX: z.coerce.number().default(131072),
+  // How long to wait for an LLM response before giving up (ms).
+  OLLAMA_TIMEOUT_MS: z.coerce.number().default(120_000),
+
+  // ── GraphMCP ─────────────────────────────────────────────────────────────
+  GRAPHMCP_URL: z.string().default('http://localhost:9000'),
+  // Minimum semantic similarity score to include a chunk as relevant context.
+  // Range 0–1. Higher = stricter. Affects NPC memory and @mention responses.
+  GRAPHMCP_SCORE_THRESHOLD: z.coerce.number().min(0).max(1).default(0.68),
+  // Max memory chunks fetched per NPC at session start.
+  GRAPHMCP_NPC_MEMORY_LIMIT: z.coerce.number().default(5),
+  // Max chunks fetched for @mention semantic search.
+  GRAPHMCP_MENTION_LIMIT: z.coerce.number().default(5),
+  // Redis stream name that the discord-connector and this bot both publish to.
+  // Must match the REDIS_STREAM env var on the discord-connector container.
+  GRAPHMCP_INGEST_STREAM: z.string().default('raw.messages'),
+
+  // ── Encounter behaviour ──────────────────────────────────────────────────
+  SPECS_DIR: z.string().default('./specs'),
+  // Delay before archiving a resolved thread (ms). Gives players time to read.
+  ENCOUNTER_ARCHIVE_DELAY_MS: z.coerce.number().default(5_000),
+  // How long the player-gate embed lingers before auto-delete (ms).
+  ENCOUNTER_GATE_TIMEOUT_MS: z.coerce.number().default(30_000),
+
+  // ── Persona ──────────────────────────────────────────────────────────────
+  // Path to the YAML file defining the bot's @mention persona.
+  PERSONA_PATH: z.string().default('./persona.yaml'),
+  // Directory for tally.json and encounter summaries.
+  DATA_DIR: z.string().default('./data'),
+
+  // ── Foundry VTT relay ────────────────────────────────────────────────────
+  VTT_RELAY_URL: z.string().default('https://vtt-relay.damascusfront.net'),
+  // Required for any Foundry VTT integration. Leave unset to disable VTT features.
+  VTT_API_KEY: z.string().default(''),
+  VTT_CLIENT_ID: z.string().default(''),
+
+  // ── Logging ──────────────────────────────────────────────────────────────
+  LOG_LEVEL: z.enum(['trace', 'debug', 'info', 'warn', 'error']).default('info'),
+});
+
+export { EnvSchema };
+export const config = EnvSchema.parse(process.env);
diff --git a/src/db/redis.ts b/src/db/redis.ts
new file mode 100644
index 0000000..335998f
--- /dev/null
+++ b/src/db/redis.ts
@@ -0,0 +1,11 @@
+import { Redis } from 'ioredis';
+import { config } from '../config.js';
+
+export const redis = new Redis(config.REDIS_URL, {
+  lazyConnect: true,
+  maxRetriesPerRequest: 3,
+});
+
+redis.on('error', (err: Error) => {
+  console.error('[redis] connection error', err);
+});
diff --git a/src/graphmcp/client.ts b/src/graphmcp/client.ts
new file mode 100644
index 0000000..0a86e3d
--- /dev/null
+++ b/src/graphmcp/client.ts
@@ -0,0 +1,200 @@
+import { config } from '../config.js';
+
+
+// ---------------------------------------------------------------------------
+// GraphMCP response types
+// ---------------------------------------------------------------------------
+
+export interface NPCQueryChunk {
+  text: string;
+  score: number;
+  source: 'message' | 'lore';
+  author: string;
+  timestamp: string;
+}
+
+export interface NPCQueryEncounter {
+  enc_id: string;
+  enc_title: string;
+  enc_type: string;
+  enc_timestamp: string;
+  enc_summary: string;
+  featured_entities: string[];
+  locations: string[];
+}
+
+export interface NPCQueryResult {
+  npc: string;
+  tier: string;
+  horizon_count: number;
+  chunks: NPCQueryChunk[];
+  graph_context: NPCQueryEncounter[];
+}
+
+export interface SemanticChunk {
+  content: string;
+  score: number;
+  source?: string;
+}
+
+export interface SemanticSearchResult {
+  chunks: SemanticChunk[];
+}
+
+export interface LogEncounterParams {
+  title: string;
+  participants: string;
+  summary: string;
+  location?: string;
+  type?: string;
+}
+
+export interface LogEncounterResult {
+  enc_id: string;
+  title: string;
+  participants: string;
+  location: string;
+  timestamp: string;
+}
+
+// ---------------------------------------------------------------------------
+// JSON-RPC call helper
+// ---------------------------------------------------------------------------
+
+let _rpcId = 1;
+
+async function callTool(name: string, args: Record<string, unknown>): Promise<unknown> {
+  const body = {
+    jsonrpc: '2.0',
+    id: _rpcId++,
+    method: 'tools/call',
+    params: { name, arguments: args },
+  };
+
+  const res = await fetch(`${config.GRAPHMCP_URL}/mcp`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+
+  if (!res.ok) {
+    throw new Error(`GraphMCP HTTP ${res.status}: ${await res.text()}`);
+  }
+
+  const json = await res.json() as {
+    result?: { content?: Array<{ text: string }> };
+    error?: { message: string };
+  };
+
+  if (json.error) {
+    throw new Error(`GraphMCP error: ${json.error.message}`);
+  }
+
+  const text = json.result?.content?.[0]?.text;
+  if (!text) return null;
+  return JSON.parse(text);
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export async function queryAsNPC(
+  npcName: string,
+  question: string,
+  limit = 5,
+): Promise<NPCQueryResult> {
+  const result = await callTool('query_as_npc', { npc_name: npcName, question, limit });
+  return result as NPCQueryResult;
+}
+
+export async function semanticSearch(query: string, limit = 5): Promise<SemanticSearchResult> {
+  const result = await callTool('semantic_search', { query, limit });
+  return (result ?? { chunks: [] }) as SemanticSearchResult;
+}
+
+export async function logEncounter(params: LogEncounterParams): Promise<LogEncounterResult> {
+  const result = await callTool('log_encounter', {
+    title: params.title,
+    participants: params.participants,
+    summary: params.summary,
+    location: params.location ?? '',
+    type: params.type ?? 'encounter',
+  });
+  return result as LogEncounterResult;
+}
+
+export interface EncounterResultItem {
+  id: string;
+  title: string;
+  location: string;
+  timestamp: string;
+  summary: string;
+}
+
+export interface EncounterDetails {
+  id: string;
+  title: string;
+  location: string;
+  timestamp: string;
+  summary: string;
+  type: string;
+  participants: string[];
+  featured_entities: string[];
+}
+
+export async function listEncounters(limit = 10): Promise<EncounterResultItem[]> {
+  const result = await callTool('list_encounters', { limit });
+  return (result ?? []) as EncounterResultItem[];
+}
+
+export async function searchEncounters(params: {
+  query?: string;
+  location?: string;
+  participant?: string;
+  limit?: number;
+}): Promise<EncounterResultItem[]> {
+  const result = await callTool('search_encounters', params);
+  return (result ?? []) as EncounterResultItem[];
+}
+
+export async function getEncounter(id: string): Promise<EncounterDetails> {
+  const result = await callTool('get_encounter', { id });
+  return result as EncounterDetails;
+}
+
+// ---------------------------------------------------------------------------
+// Format NPCQueryResult into readable system-prompt text
+// ---------------------------------------------------------------------------
+
+export function formatNPCMemory(result: NPCQueryResult | null): string {
+  const chunks = result?.chunks ?? [];
+  const graphContext = result?.graph_context ?? [];
+
+  if (!result || (result.horizon_count === 0 && chunks.length === 0)) {
+    return 'No prior encounters on record — first meeting.';
+  }
+
+  const parts: string[] = [];
+
+  if (graphContext.length > 0) {
+    parts.push('Past encounters witnessed:');
+    for (const enc of graphContext) {
+      const date = enc.enc_timestamp ? enc.enc_timestamp.slice(0, 10) : 'unknown';
+      parts.push(`  - [${date}] ${enc.enc_title}: ${enc.enc_summary}`);
+    }
+  }
+
+  if (chunks.length > 0) {
+    const relevant = chunks.filter(c => c.score > config.GRAPHMCP_SCORE_THRESHOLD).slice(0, 3);
+    if (relevant.length > 0) {
+      parts.push('Relevant lore/context:');
+      for (const chunk of relevant) {
+        const snippet = chunk.text.length > 200 ? chunk.text.slice(0, 197) + '…' : chunk.text;
+        parts.push(`  - ${snippet}`);
+      }
+    }
+  }
+
+  return parts.length > 0 ? parts.join('\n') : 'No prior encounters on record — first meeting.';
+}
diff --git a/src/graphmcp/ingest.ts b/src/graphmcp/ingest.ts
new file mode 100644
index 0000000..4680c99
--- /dev/null
+++ b/src/graphmcp/ingest.ts
@@ -0,0 +1,43 @@
+import { redis } from '../db/redis.js';
+import { config } from '../config.js';
+
+const SEVEN_DAYS_SECS = 7 * 24 * 60 * 60;
+
+export interface IngestPayload {
+  messageId: string;
+  content: string;
+  author: string;
+  channelId: string;
+  channelName: string;
+}
+
+/**
+ * Publishes a qualifying Discord message to the GraphMCP raw.messages Redis
+ * stream for ingestion into the knowledge graph.
+ *
+ * Uses the same dedup key pattern as the discord-connector so the two
+ * publishers never produce duplicate stream entries for the same message ID.
+ */
+export async function publishToGraphMCP(payload: IngestPayload): Promise<void> {
+  const { messageId, content, author, channelId, channelName } = payload;
+
+  if (!content.trim()) return;
+
+  // SetNX returns 1 if we acquired the key (first publisher), 0 if already set
+  const dedupKey = `discord:seen:${messageId}`;
+  const acquired = await redis.setnx(dedupKey, '1');
+  if (!acquired) return;
+  await redis.expire(dedupKey, SEVEN_DAYS_SECS);
+
+  await redis.xadd(
+    config.GRAPHMCP_INGEST_STREAM,
+    '*',
+    'id', messageId,
+    'content', content,
+    'author', author,
+    'timestamp', new Date().toISOString(),
+    'source', 'discord',
+    'channel_id', channelId,
+    'channel_name', channelName,
+  );
+}
diff --git a/src/graphmcp/loreResolver.ts b/src/graphmcp/loreResolver.ts
new file mode 100644
index 0000000..849ffad
--- /dev/null
+++ b/src/graphmcp/loreResolver.ts
@@ -0,0 +1,52 @@
+import { semanticSearch } from './client.js';
+import { sampleFromVocabulary } from './vocabularyResolver.js';
+import { config } from '../config.js';
+import type { RandomizableItem } from '../types/index.js';
+
+/**
+ * Resolves all randomizable spec items against the GraphMCP knowledge graph.
+ *
+ * For each item: queries semanticSearch, filters results above the score
+ * threshold, picks one at random, and trims it to a usable length.
+ * Falls back to item.fallback if GraphMCP returns nothing useful.
+ *
+ * Returns a flat Record<key, resolvedValue> ready to store in session state
+ * and inject into the system prompt.
+ */
+export async function resolveRandomizables(
+  items: RandomizableItem[],
+): Promise<Record<string, string>> {
+  if (items.length === 0) return {};
+
+  const resolved: Record<string, string> = {};
+
+  await Promise.all(
+    items.map(async item => {
+      if (item.source === 'vocabulary') {
+        resolved[item.key] = sampleFromVocabulary(item.category ?? '', item.fallback);
+        return;
+      }
+
+      try {
+        const result = await semanticSearch(item.query, config.GRAPHMCP_NPC_MEMORY_LIMIT);
+        const candidates = (result.chunks ?? [])
+          .filter(c => c.score > config.GRAPHMCP_SCORE_THRESHOLD);
+
+        if (candidates.length > 0) {
+          // Pick randomly so repeated starts of the same spec feel different
+          const pick = candidates[Math.floor(Math.random() * candidates.length)];
+          // Trim to something the LLM can use inline without blowing context
+          const text = pick.content.trim().slice(0, 200);
+          resolved[item.key] = text || item.fallback;
+        } else {
+          resolved[item.key] = item.fallback;
+        }
+      } catch (err) {
+        console.warn(`[loreResolver] failed to resolve "${item.key}":`, err);
+        resolved[item.key] = item.fallback;
+      }
+    }),
+  );
+
+  return resolved;
+}
diff --git a/src/graphmcp/vocabularyResolver.ts b/src/graphmcp/vocabularyResolver.ts
new file mode 100644
index 0000000..b5ba75b
--- /dev/null
+++ b/src/graphmcp/vocabularyResolver.ts
@@ -0,0 +1,38 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { load } from 'js-yaml';
+
+let _cache: Record<string, unknown> | null = null;
+
+function loadVocabulary(): Record<string, unknown> {
+  if (!_cache) {
+    const path = join(process.cwd(), 'lore', 'vocabulary.yaml');
+    _cache = load(readFileSync(path, 'utf-8')) as Record<string, unknown>;
+  }
+  return _cache;
+}
+
+function getList(vocab: Record<string, unknown>, dotPath: string): string[] {
+  const parts = dotPath.split('.');
+  let node: unknown = vocab;
+  for (const part of parts) {
+    if (typeof node !== 'object' || node === null || !(part in node)) return [];
+    node = (node as Record<string, unknown>)[part];
+  }
+  return Array.isArray(node) ? (node as string[]) : [];
+}
+
+export function sampleFromVocabulary(category: string, fallback: string): string {
+  try {
+    const vocab = loadVocabulary();
+    const items = getList(vocab, category);
+    if (items.length === 0) {
+      console.warn(`[vocabularyResolver] category "${category}" is empty or not found`);
+      return fallback;
+    }
+    return items[Math.floor(Math.random() * items.length)];
+  } catch (err) {
+    console.warn(`[vocabularyResolver] failed to load vocabulary:`, err);
+    return fallback;
+  }
+}
diff --git a/src/harness/contextAssembler.ts b/src/harness/contextAssembler.ts
new file mode 100644
index 0000000..bb3a42b
--- /dev/null
+++ b/src/harness/contextAssembler.ts
@@ -0,0 +1,34 @@
+import { encode } from 'gpt-tokenizer';
+import type { SessionState, ChatMessage } from '../types/index.js';
+import { CONTEXT_BUDGET } from '../types/index.js';
+import { buildSystemPrompt } from './promptBuilder.js';
+
+function estimateTokens(text: string): number {
+  return Math.ceil(encode(text).length * 1.15);
+}
+
+function estimateMessages(messages: ChatMessage[]): number {
+  return messages.reduce((sum, m) => sum + estimateTokens(m.content) + 4, 0);
+}
+
+function trimHistory(messages: ChatMessage[]): ChatMessage[] {
+  const budget = CONTEXT_BUDGET.HISTORY - CONTEXT_BUDGET.SAFETY;
+  const result = [...messages];
+  while (estimateMessages(result) > budget && result.length > 6) {
+    result.splice(0, 2);
+  }
+  return result;
+}
+
+export function assembleContext(session: SessionState): ChatMessage[] {
+  const systemPrompt = buildSystemPrompt(session.spec, session.npcMemories, session.resolvedContext, session.players);
+  const pinned = session.history.filter(m => m.pinned);
+  const sliding = session.history.filter(m => !m.pinned);
+  const trimmed = trimHistory(sliding);
+
+  return [
+    { role: 'system', content: systemPrompt, pinned: true, timestamp: 0 },
+    ...pinned,
+    ...trimmed,
+  ];
+}
diff --git a/src/harness/litellmClient.ts b/src/harness/litellmClient.ts
new file mode 100644
index 0000000..a044e55
--- /dev/null
+++ b/src/harness/litellmClient.ts
@@ -0,0 +1,47 @@
+import OpenAI from 'openai';
+import { config } from '../config.js';
+import { parseToolCall } from './toolParser.js';
+import { log } from '../lib/logger.js';
+import type { ChatMessage, LLMResponse } from '../types/index.js';
+
+let _client: OpenAI | null = null;
+
+function getClient(): OpenAI {
+  if (!_client) {
+    _client = new OpenAI({
+      baseURL: `${config.LITELLM_BASE_URL}/v1`,
+      apiKey: config.LITELLM_API_KEY || 'no-key',
+      timeout: config.OLLAMA_TIMEOUT_MS,
+    });
+  }
+  return _client;
+}
+
+export async function callLLM(messages: ChatMessage[]): Promise<LLMResponse> {
+  const model = config.LITELLM_MODEL ?? config.OLLAMA_MODEL;
+  const start = Date.now();
+
+  const response = await getClient().chat.completions.create({
+    model,
+    messages: messages.map(m => ({ role: m.role, content: m.content })),
+    temperature: config.OLLAMA_TEMPERATURE,
+  });
+
+  const latencyMs = Date.now() - start;
+  const raw = response.choices[0]?.message.content ?? '';
+  const { narrative, toolCall } = parseToolCall(raw);
+
+  log.info('llm', 'litellm response', {
+    model,
+    latencyMs,
+    tokens: response.usage?.completion_tokens,
+    promptTokens: response.usage?.prompt_tokens,
+    tool: toolCall?.tool,
+  });
+
+  return {
+    narrative,
+    toolCall,
+    rawTokensUsed: response.usage?.completion_tokens,
+  };
+}
diff --git a/src/harness/llmClient.ts b/src/harness/llmClient.ts
new file mode 100644
index 0000000..108038b
--- /dev/null
+++ b/src/harness/llmClient.ts
@@ -0,0 +1,19 @@
+import { config } from '../config.js';
+import { callLLM as callLiteLLM } from './litellmClient.js';
+import { callLLM as callOllama } from './ollamaClient.js';
+import { log } from '../lib/logger.js';
+import type { ChatMessage, LLMResponse } from '../types/index.js';
+
+export async function callLLM(messages: ChatMessage[]): Promise<LLMResponse> {
+  if (config.LITELLM_BASE_URL) {
+    log.info('llm', 'calling litellm', { messages: messages.length });
+    try {
+      return await callLiteLLM(messages);
+    } catch (err) {
+      log.warn('llm', 'litellm failed, falling back to ollama', { error: String(err) });
+    }
+  } else {
+    log.info('llm', 'calling ollama', { messages: messages.length });
+  }
+  return callOllama(messages);
+}
diff --git a/src/harness/ollamaClient.ts b/src/harness/ollamaClient.ts
new file mode 100644
index 0000000..a69fb67
--- /dev/null
+++ b/src/harness/ollamaClient.ts
@@ -0,0 +1,36 @@
+import { Ollama } from 'ollama';
+import { config } from '../config.js';
+import { parseToolCall } from './toolParser.js';
+import { log } from '../lib/logger.js';
+import type { ChatMessage, LLMResponse } from '../types/index.js';
+
+const ollama = new Ollama({ host: config.OLLAMA_BASE_URL });
+
+export async function callLLM(messages: ChatMessage[]): Promise<LLMResponse> {
+  const model = config.OLLAMA_MODEL;
+  const start = Date.now();
+
+  const response = await ollama.chat({
+    model,
+    messages: messages.map(m => ({ role: m.role, content: m.content })),
+    stream: false,
+    options: { temperature: config.OLLAMA_TEMPERATURE, num_ctx: config.OLLAMA_NUM_CTX },
+  });
+
+  const latencyMs = Date.now() - start;
+  const raw = response.message.content;
+  const { narrative, toolCall } = parseToolCall(raw);
+
+  log.info('llm', 'ollama response', {
+    model,
+    latencyMs,
+    tokens: response.eval_count,
+    tool: toolCall?.tool,
+  });
+
+  return {
+    narrative,
+    toolCall,
+    rawTokensUsed: response.eval_count,
+  };
+}
diff --git a/src/harness/promptBuilder.ts b/src/harness/promptBuilder.ts
new file mode 100644
index 0000000..0b69037
--- /dev/null
+++ b/src/harness/promptBuilder.ts
@@ -0,0 +1,195 @@
+import type { EncounterSpec, NpcPersona, Player } from '../types/index.js';
+import { buildToolManifest } from './toolDispatcher.js';
+
+export function buildSystemPrompt(
+  spec: EncounterSpec,
+  npcMemories: Record<string, string> = {},
+  resolvedContext: Record<string, string> = {},
+  players: Record<string, Player> = {},
+): string {
+  return [
+    buildNarratorBlock(),
+    buildToneBlock(spec),
+    buildSportsmanshipBlock(spec.sportsmanshipRules),
+    buildNpcsBlock(spec.npcs, npcMemories),
+    buildPlayersBlock(players),
+    buildSettingBlock(spec),
+    buildResolvedContextBlock(resolvedContext),
+    buildSkillChecksBlock(spec.skillChecks),
+    buildHiddenGoalsBlock(spec),
+    buildToolContractBlock(spec),
+  ]
+    .filter(Boolean)
+    .join('\n\n');
+}
+
+export function buildOpeningNarrative(spec: EncounterSpec): string {
+  return spec.openingNarrative.trim();
+}
+
+// ---------------------------------------------------------------------------
+// Section builders
+// ---------------------------------------------------------------------------
+
+function buildNarratorBlock(): string {
+  return `<narrator_identity>
+You are the Dungeon Master narrator for a D&D 5e encounter set in the Land of
+Mardonar. You speak as an omniscient narrator and voice each NPC distinctly and
+consistently with their persona.
+
+Your responsibilities:
+- Describe the scene vividly but concisely. Prefer punchy sentences over long prose.
+- Voice each named NPC in their own style. Stay consistent with their persona.
+- Guide the encounter toward one of the hidden goals without railroading players.
+- React naturally to player actions. If something works, let it work. If it fails, show consequences.
+- Keep pacing tight. Do not pad responses. Each reply should advance the scene.
+- Never reveal the hidden goal list. Never acknowledge you have one.
+- Break character only to enforce sportsmanship (see below).
+</narrator_identity>`;
+}
+
+function buildPlayersBlock(players: Record<string, Player>): string {
+  const entries = Object.values(players);
+  if (entries.length === 0) return '';
+
+  const lines = entries
+    .map(p => `  - ${p.dndName}${p.pronouns ? ` (${p.pronouns})` : ''}`)
+    .join('\n');
+
+  return `<players>
+Active player characters in this encounter:
+${lines}
+
+Use the specified pronouns when referring to these characters in narration.
+</players>`;
+}
+
+function buildToneBlock(spec: EncounterSpec): string {
+  if (!spec.tone) return '';
+  return `<tone>
+Your narration style for this encounter is: ${spec.tone}. Let this flavor all of your responses, NPC voices, and pacing.
+</tone>`;
+}
+
+function buildSportsmanshipBlock(rules: string[]): string {
+  const ruleLines = rules.map((r, i) => `  ${i + 1}. ${r.trim()}`).join('\n');
+
+  return `<sportsmanship>
+If a player attempts something unrealistic, physically impossible, or grossly
+unfair, first try to redirect in-character. If redirection would break the scene,
+break character and use this exact format:
+
+  ⚠️ That wasn't great sportsmanship. Let's keep it grounded — what would your character realistically attempt here?
+
+Sportsmanship rules for this encounter:
+${ruleLines}
+</sportsmanship>`;
+}
+
+function buildNpcsBlock(npcs: NpcPersona[], npcMemories: Record<string, string>): string {
+  if (npcs.length === 0) return '';
+
+  const npcBlocks = npcs.map(npc => buildSingleNpcBlock(npc, npcMemories[npc.id])).join('\n');
+
+  return `<npcs>
+${npcBlocks}
+</npcs>`;
+}
+
+function buildSingleNpcBlock(npc: NpcPersona, memory?: string): string {
+  const memoryLine = memory && memory !== 'No prior encounters on record — first meeting.'
+    ? `  Memory from prior encounters:\n${memory.split('\n').map(l => `    ${l}`).join('\n')}`
+    : '  Memory: None — first encounter with this NPC.';
+
+  return `  <npc id="${npc.id}">
+    Name: ${npc.name}
+    Role: ${npc.role}
+    Persona: ${npc.persona.trim()}
+${memoryLine}
+  </npc>`;
+}
+
+function buildSettingBlock(spec: EncounterSpec): string {
+  return `<setting>
+  Location: ${spec.setting.location}
+  Mood: ${spec.setting.mood.trim()}
+  Ambient NPCs: ${spec.setting.ambientNpcs.trim()}
+</setting>`;
+}
+
+function buildResolvedContextBlock(resolvedContext: Record<string, string>): string {
+  const entries = Object.entries(resolvedContext);
+  if (entries.length === 0) return '';
+
+  const lines = entries.map(([k, v]) => `  ${k}: "${v}"`).join('\n');
+
+  return `<resolved_context>
+The following details have been established for this specific session and are
+canonical — treat them as ground truth when narrating.
+
+${lines}
+
+You may use context_recall to retrieve any of these values by key during the
+encounter if you need to reference them precisely.
+</resolved_context>`;
+}
+
+function buildSkillChecksBlock(skillChecks: Record<string, number | string>): string {
+  if (Object.keys(skillChecks).length === 0) return '';
+
+  // Group by prefix: chase_dc + chase_skill + chase_note → one entry
+  const groups: Record<string, { dc?: number; skill?: string; note?: string }> = {};
+  for (const [key, val] of Object.entries(skillChecks)) {
+    const match = key.match(/^(.+?)_(dc|skill|note)$/);
+    if (!match) continue;
+    const [, name, field] = match;
+    if (!groups[name]) groups[name] = {};
+    if (field === 'dc') groups[name].dc = Number(val);
+    if (field === 'skill') groups[name].skill = String(val);
+    if (field === 'note') groups[name].note = String(val);
+  }
+
+  const lines = Object.entries(groups)
+    .filter(([, g]) => g.dc !== undefined)
+    .map(([name, g]) => {
+      const noteLine = g.note ? `\n      Note: ${g.note.trim()}` : '';
+      return `  - ${name.replace(/_/g, ' ')}: ${g.skill ?? 'skill check'} DC ${g.dc}${noteLine}`;
+    })
+    .join('\n');
+
+  return `<skill_checks>
+When a player attempts any of the following actions — or explicitly asks for a
+skill check — emit a skill_check_emit tool call IMMEDIATELY. Do not narrate the
+outcome yourself; wait for the roll result to arrive as a system message.
+
+${lines}
+</skill_checks>`;
+}
+
+function buildHiddenGoalsBlock(spec: EncounterSpec): string {
+  const primaryLines = spec.goals.primary
+    .map(g => `  - [PRIMARY]   ${g.id}: ${g.label.trim()}`)
+    .join('\n');
+
+  const secondaryLines = spec.goals.secondary
+    .map(g => `  - [SECONDARY] ${g.id}: ${g.label.trim()}`)
+    .join('\n');
+
+  return `<hidden_goals>
+Steer the story toward one of these outcomes. Do not state them to players.
+Reward clever play that moves toward a goal. Gently redirect if the scene drifts
+far off course. Multiple outcomes may be valid — follow what the players set in motion.
+
+${primaryLines}
+${secondaryLines}
+
+When an outcome is clearly and unambiguously reached (e.g. the thief is caught,
+surrenders, escapes into the crowd with no pursuit left, or is killed), emit an
+encounter_resolve tool call. Do not delay — resolve as soon as the outcome is
+certain. Do not continue narrating after emitting encounter_resolve.
+</hidden_goals>`;
+}
+
+function buildToolContractBlock(spec: EncounterSpec): string {
+  return buildToolManifest(spec);
+}
diff --git a/src/harness/toolDispatcher.ts b/src/harness/toolDispatcher.ts
new file mode 100644
index 0000000..ee792fc
--- /dev/null
+++ b/src/harness/toolDispatcher.ts
@@ -0,0 +1,117 @@
+// Side-effect import — registers all built-in tools into the registry at module load.
+import './tools/index.js';
+
+import type { EncounterSpec } from '../types/index.js';
+import type { ToolCallBlock } from '../types/index.js';
+import { getActiveTools, getAllToolNames, type ToolContext, type DispatchResult } from './toolRegistry.js';
+import { log } from '../lib/logger.js';
+
+export type { ToolContext, DispatchResult };
+
+// ---------------------------------------------------------------------------
+// Manifest — generates the <tool_contract> system prompt section from the
+// active tool set for this encounter. Returns '' when no tools are active
+// (the empty string is filtered out by promptBuilder's .filter(Boolean)).
+// ---------------------------------------------------------------------------
+
+export function buildToolManifest(spec: EncounterSpec): string {
+  const activeTools = getActiveTools(spec.tools);
+  if (activeTools.size === 0) return '';
+
+  const toolDocs = Array.from(activeTools.entries())
+    .map(([name, def]) => {
+      const argLines = Object.entries(def.args)
+        .map(([argName, schema]) => `      ${argName} (${schema.type}): ${schema.description}`)
+        .join('\n');
+      const extra = def.contextDocs ? '\n' + def.contextDocs(spec) : '';
+      return `  ${name}\n    ${def.description}\n    Args:\n${argLines}${extra}`;
+    })
+    .join('\n\n');
+
+  return `<tool_contract>
+Append a tool call block at the VERY END of your response, after all narrative.
+Emit at most ONE tool call per response.
+
+Required format — no variations:
+\`\`\`tool_call
+{ "tool": "<tool_name>", "args": { ... } }
+\`\`\`
+
+SKILL CHECKS — emit skill_check_emit immediately whenever the player:
+  • Makes any attack roll (melee, ranged, or spell)
+  • Attempts any skill or ability check (including when they say "I roll X" or use /roll)
+  • Must make a saving throw
+  • Takes any action with a physically uncertain outcome (chase, climb, pick a lock, hide, etc.)
+CRITICAL: If your narrative contains phrases like "make a roll", "roll for X",
+"you need to hit AC N", or "attempt a check" — you MUST emit skill_check_emit in
+that SAME response. Never describe needing a roll and then stop without emitting.
+CRITICAL: If a [/roll COMMAND] or [SKILL CHECK REQUEST] system message is present,
+your ENTIRE response must be the tool call block and nothing else.
+Do NOT narrate the outcome of any check before the roll result arrives as a system message.
+NEVER end your response with a request for the player to roll without emitting skill_check_emit
+in the same response. Writing "you'll need to roll" or "make a Dexterity check" and then
+stopping — without the tool call — is FORBIDDEN and breaks the game.
+
+--- CORRECT skill check flow (follow this exactly) ---
+Player: "Thorin tries to pick the lock."
+Your response: "The tumblers resist, but Thorin's fingers find the keyhole. It's stiff — age and rust have done their work."
+[Then emit skill_check_emit: player="Thorin", prompt="Pick the lock — Dexterity (Thieves' Tools)", dc=13]
+
+--- WRONG (never do this) ---
+Player: "Thorin tries to pick the lock."
+WRONG response: "The lock looks tough. Thorin will need to make a Dexterity check to force it open!"
+[Missing: no skill_check_emit emitted — this is FORBIDDEN]
+
+RESOLUTION — emit encounter_resolve the instant an outcome is clearly reached.
+Do not narrate after emitting it.
+
+OMIT the block entirely for pure dialogue, NPC reactions, or description with no uncertain outcomes.
+Never emit an empty or malformed tool block.
+
+Available tools:
+
+${toolDocs}
+</tool_contract>`;
+}
+
+// ---------------------------------------------------------------------------
+// Valid names — used by toolParser to validate the tool block before dispatch.
+// Reflects the full global registry; per-encounter filtering happens in dispatchTool.
+// ---------------------------------------------------------------------------
+
+export const VALID_TOOL_NAMES = getAllToolNames();
+
+// ---------------------------------------------------------------------------
+// Dispatcher — routes a parsed tool call to its plugin handler.
+// Rejects tools that aren't active for this encounter's spec.
+// ---------------------------------------------------------------------------
+
+export async function dispatchTool(
+  block: ToolCallBlock,
+  ctx: ToolContext,
+): Promise<DispatchResult> {
+  const activeTools = getActiveTools(ctx.session.spec.tools);
+  const plugin = activeTools.get(block.tool);
+  if (!plugin) {
+    log.warn('tool', `"${block.tool}" not active`, { encounter: ctx.session.spec.encounterId });
+    return { systemMessage: `[TOOL] "${block.tool}" is not available in this encounter.` };
+  }
+
+  log.info('tool', `dispatch ${block.tool}`, { args: JSON.stringify(block.args) });
+  const start = Date.now();
+  try {
+    const result = await plugin.handler(block.args, ctx);
+    log.info('tool', `result ${block.tool}`, {
+      latencyMs: Date.now() - start,
+      output: result.systemMessage?.slice(0, 120),
+    });
+    return result;
+  } catch (err) {
+    const latencyMs = Date.now() - start;
+    log.error('tool', `${block.tool} threw`, { latencyMs, error: String(err) });
+    return {
+      systemMessage: `[TOOL ERROR] ${block.tool} failed: ${String(err)}`,
+      error: true,
+    };
+  }
+}
diff --git a/src/harness/toolParser.ts b/src/harness/toolParser.ts
new file mode 100644
index 0000000..d2e5c4f
--- /dev/null
+++ b/src/harness/toolParser.ts
@@ -0,0 +1,48 @@
+import type { ToolCallBlock, ToolName } from '../types/index.js';
+import { VALID_TOOL_NAMES } from './toolDispatcher.js';
+
+// Primary: fenced ```tool_call``` block.
+const FENCE_RE = /```tool_call\s*([\s\S]*?)```/;
+
+// Secondary: plain "tool_call" text header without fences, full JSON with "tool"/"args" keys.
+const HEADER_RE = /\btool_call\b[^\n]*\n(\{[\s\S]*\})\s*$/;
+
+// Fallback: any JSON blob with both "tool" and "args" keys at end of response,
+// for models that emit the right structure but omit any header.
+const BARE_JSON_RE = /(\{[^{}]*"tool"\s*:[^{}]*"args"\s*:\s*\{[\s\S]*?\}[^{}]*\})\s*$/;
+
+export function parseToolCall(raw: string): { narrative: string; toolCall?: ToolCallBlock } {
+  const fenceMatch = FENCE_RE.exec(raw);
+  if (fenceMatch) return extract(raw, fenceMatch.index, fenceMatch[1]);
+
+  const headerMatch = HEADER_RE.exec(raw);
+  if (headerMatch) return extract(raw, headerMatch.index, headerMatch[1]);
+
+  const bareMatch = BARE_JSON_RE.exec(raw);
+  if (bareMatch) return extract(raw, bareMatch.index, bareMatch[1]);
+
+  return { narrative: raw.trim() };
+}
+
+function extract(
+  raw: string,
+  matchIndex: number,
+  json: string,
+): { narrative: string; toolCall?: ToolCallBlock } {
+  const narrative = raw.slice(0, matchIndex).trim();
+  try {
+    const parsed = JSON.parse(json.trim()) as { tool: string; args: Record<string, unknown> };
+    if (!VALID_TOOL_NAMES.has(parsed.tool as ToolName)) {
+      console.warn(`[toolParser] unknown tool "${parsed.tool}" — ignoring`);
+      return { narrative: narrative || raw.trim() };
+    }
+    if (!parsed.args || typeof parsed.args !== 'object' || Array.isArray(parsed.args)) {
+      console.warn('[toolParser] missing or invalid args — ignoring tool call');
+      return { narrative: narrative || raw.trim() };
+    }
+    return { narrative, toolCall: { tool: parsed.tool as ToolName, args: parsed.args } };
+  } catch {
+    console.warn('[toolParser] malformed tool JSON — treating as narrative');
+    return { narrative: raw.trim() };
+  }
+}
diff --git a/src/harness/toolRegistry.ts b/src/harness/toolRegistry.ts
new file mode 100644
index 0000000..bcd88fc
--- /dev/null
+++ b/src/harness/toolRegistry.ts
@@ -0,0 +1,55 @@
+import type { ThreadChannel, TextChannel } from 'discord.js';
+import type { SessionState, EncounterSpec } from '../types/index.js';
+
+export interface ToolContext {
+  session: SessionState;
+  thread: ThreadChannel | TextChannel;
+}
+
+export interface DispatchResult {
+  systemMessage: string;
+  error?: boolean;
+  resolved?: {
+    outcomeId: string;
+    summary: string;
+  };
+}
+
+export interface ArgSchema {
+  type: 'string' | 'number' | 'boolean';
+  description: string;
+}
+
+export interface ToolPlugin {
+  name: string;
+  description: string;
+  args: Record<string, ArgSchema>;
+  contextDocs?: (spec: EncounterSpec) => string;
+  handler: (args: Record<string, unknown>, ctx: ToolContext) => Promise<DispatchResult> | DispatchResult;
+}
+
+const registry = new Map<string, ToolPlugin>();
+
+export function registerTool(plugin: ToolPlugin): void {
+  registry.set(plugin.name, plugin);
+}
+
+export function getPlugin(name: string): ToolPlugin | undefined {
+  return registry.get(name);
+}
+
+export function getAllToolNames(): ReadonlySet<string> {
+  return new Set(registry.keys());
+}
+
+// Returns all registered tools when toolNames is absent or empty (encounter default).
+// Otherwise returns only the named subset, silently skipping unknown names.
+export function getActiveTools(toolNames?: string[]): ReadonlyMap<string, ToolPlugin> {
+  if (!toolNames || toolNames.length === 0) return registry;
+  const active = new Map<string, ToolPlugin>();
+  for (const name of toolNames) {
+    const plugin = registry.get(name);
+    if (plugin) active.set(name, plugin);
+  }
+  return active;
+}
diff --git a/src/harness/tools/contextRecall.ts b/src/harness/tools/contextRecall.ts
new file mode 100644
index 0000000..5846f23
--- /dev/null
+++ b/src/harness/tools/contextRecall.ts
@@ -0,0 +1,23 @@
+import { registerTool, type ToolPlugin } from '../toolRegistry.js';
+
+const contextRecall: ToolPlugin = {
+  name: 'context_recall',
+  description:
+    'Look up a lore detail established for this encounter instance. ' +
+    'Use when you need to reference a specific detail precisely. Do not fabricate values — recall them.',
+  args: {
+    key: { type: 'string', description: 'A key from the resolved_context section' },
+  },
+  handler: (args, ctx) => {
+    const key = args.key as string;
+    const value = ctx.session.resolvedContext?.[key];
+    if (value !== undefined) {
+      return { systemMessage: `[CONTEXT] ${key} = "${value}"` };
+    }
+    const available = Object.keys(ctx.session.resolvedContext ?? {}).join(', ') || 'none';
+    return { systemMessage: `[CONTEXT] No value found for key "${key}". Available keys: ${available}` };
+  },
+};
+
+registerTool(contextRecall);
+export default contextRecall;
diff --git a/src/harness/tools/encounterResolve.ts b/src/harness/tools/encounterResolve.ts
new file mode 100644
index 0000000..e3d2aa8
--- /dev/null
+++ b/src/harness/tools/encounterResolve.ts
@@ -0,0 +1,56 @@
+import { logEncounter } from '../../graphmcp/client.js';
+import { buildResolutionEmbed } from '../../bot/embeds/resolution.js';
+import { writeSummary } from '../../session/encounterLog.js';
+import { registerTool, type ToolPlugin } from '../toolRegistry.js';
+
+const encounterResolve: ToolPlugin = {
+  name: 'encounter_resolve',
+  description:
+    'End the encounter and record the outcome. Emit the moment an outcome is clearly reached. ' +
+    'Do not continue narrating after emitting this.',
+  args: {
+    sessionId: { type: 'string', description: 'The session ID for this encounter' },
+    outcomeId: { type: 'string', description: 'Outcome identifier — must be one of the valid values listed below' },
+    summary: { type: 'string', description: '2–4 sentences: what happened, who was involved, key turning points, how it ended. Past tense.' },
+  },
+  contextDocs: spec => {
+    const goalLines = [...spec.goals.primary, ...spec.goals.secondary]
+      .map(g => `        - "${g.id}" — ${g.label.trim()}`)
+      .join('\n');
+    return `      sessionId: "${spec.encounterId}"\n      outcomeId valid values:\n${goalLines}`;
+  },
+  handler: async (args, ctx) => {
+    const outcomeId = args.outcomeId as string;
+    const summary = args.summary as string;
+    const { session } = ctx;
+
+    const participants = [
+      ...session.spec.npcs.map(n => n.name),
+      ...Object.values(session.players).map(p => p.dndName),
+    ].join(', ');
+
+    try {
+      await logEncounter({
+        title: `${session.spec.title} — ${outcomeId}`,
+        participants,
+        summary,
+        location: session.spec.setting.location,
+        type: 'encounter',
+      });
+    } catch (err) {
+      console.error('[encounterResolve] logEncounter failed:', err);
+    }
+
+    const embed = buildResolutionEmbed(session.spec, session, outcomeId, summary);
+    await ctx.thread.send({ embeds: [embed] });
+    writeSummary(session, outcomeId, summary);
+
+    return {
+      systemMessage: `[TOOL] Encounter resolved: ${outcomeId}. ${summary}`,
+      resolved: { outcomeId, summary },
+    };
+  },
+};
+
+registerTool(encounterResolve);
+export default encounterResolve;
diff --git a/src/harness/tools/foundryLookup.ts b/src/harness/tools/foundryLookup.ts
new file mode 100644
index 0000000..651f47c
--- /dev/null
+++ b/src/harness/tools/foundryLookup.ts
@@ -0,0 +1,49 @@
+import {
+  searchActors,
+  filterPlayerActors,
+  getActorDetails,
+  getActorInventory,
+  getActorSpells,
+  formatActorSummary,
+  formatInventory,
+  formatSpells,
+} from '../../vtt/foundryClient.js';
+import { registerTool, type ToolPlugin } from '../toolRegistry.js';
+
+const foundryLookup: ToolPlugin = {
+  name: 'foundry_lookup',
+  description: 'Look up a Foundry VTT player character by name. Returns their stats, inventory, and spell list.',
+  args: {
+    actor_name: { type: 'string', description: 'The name or partial name of the player character to look up' },
+  },
+  handler: async (args) => {
+    try {
+      const actorName = args.actor_name as string;
+      const results = await searchActors(actorName, 10);
+      const match = filterPlayerActors(results)[0];
+
+      if (!match) {
+        return { systemMessage: `[FOUNDRY] No player actor found matching "${actorName}"` };
+      }
+
+      const [details, inventory, spells] = await Promise.all([
+        getActorDetails(match.uuid),
+        getActorInventory(match.uuid),
+        getActorSpells(match.uuid),
+      ]);
+
+      const summary = formatActorSummary(details);
+      const inv = formatInventory(inventory);
+      const spellList = formatSpells(spells);
+
+      return {
+        systemMessage: '[FOUNDRY ACTOR]\n' + summary + '\nInventory:\n' + inv + '\nSpells:\n' + spellList,
+      };
+    } catch {
+      return { systemMessage: '[FOUNDRY] VTT relay unavailable.' };
+    }
+  },
+};
+
+registerTool(foundryLookup);
+export default foundryLookup;
diff --git a/src/harness/tools/foundryReward.ts b/src/harness/tools/foundryReward.ts
new file mode 100644
index 0000000..9b1a382
--- /dev/null
+++ b/src/harness/tools/foundryReward.ts
@@ -0,0 +1,66 @@
+import { modifyExperience, giveItem } from '../../vtt/foundryClient.js';
+import { characterRegistry } from '../../session/characterRegistry.js';
+import { registerTool, type ToolPlugin } from '../toolRegistry.js';
+
+const foundryReward: ToolPlugin = {
+  name: 'foundry_reward',
+  description:
+    'Award a player an item or XP in Foundry VTT for an achievement. Use when an encounter milestone is clearly reached.',
+  args: {
+    player_discord_name: {
+      type: 'string',
+      description: "The player's DnD name as it appears in the session",
+    },
+    xp_amount: {
+      type: 'number',
+      description: 'XP to award (omit if no XP reward)',
+    },
+    item_name: {
+      type: 'string',
+      description: 'Item to give (omit if no item reward)',
+    },
+    reason: {
+      type: 'string',
+      description: 'Brief description of what the player achieved (logged as system message)',
+    },
+  },
+  handler: async (args, ctx) => {
+    try {
+      const playerDiscordName = args.player_discord_name as string;
+      const xpAmount = args.xp_amount as number | undefined;
+      const itemName = args.item_name as string | undefined;
+      const reason = args.reason as string;
+
+      const player = Object.values(ctx.session.players).find(
+        p => p.dndName.toLowerCase() === playerDiscordName.toLowerCase(),
+      );
+
+      if (!player) {
+        return { systemMessage: `[FOUNDRY] No player found matching "${playerDiscordName}" in this session.` };
+      }
+
+      const profile = await characterRegistry.get(ctx.session.guildId, player.discordId);
+      const uuid = (profile as (typeof profile & { foundryActorUuid?: string }) | null)?.foundryActorUuid;
+
+      if (!uuid) {
+        return {
+          systemMessage: '[FOUNDRY] Player has no linked Foundry character. Reward skipped.',
+        };
+      }
+
+      await Promise.all([
+        xpAmount != null && xpAmount > 0 ? modifyExperience(uuid, xpAmount) : Promise.resolve(),
+        itemName ? giveItem(uuid, itemName) : Promise.resolve(),
+      ]);
+
+      return {
+        systemMessage: `[FOUNDRY REWARD] Gave ${player.dndName}: ${itemName ?? 'no item'}, ${xpAmount ?? 0} XP. Reason: ${reason}`,
+      };
+    } catch {
+      return { systemMessage: '[FOUNDRY] VTT relay unavailable. Reward not delivered.' };
+    }
+  },
+};
+
+registerTool(foundryReward);
+export default foundryReward;
diff --git a/src/harness/tools/goalRegister.ts b/src/harness/tools/goalRegister.ts
new file mode 100644
index 0000000..a2033c5
--- /dev/null
+++ b/src/harness/tools/goalRegister.ts
@@ -0,0 +1,110 @@
+import { sessionManager } from '../../session/sessionManager.js';
+import { registerTool, type ToolPlugin } from '../toolRegistry.js';
+
+const goalRegister: ToolPlugin = {
+  name: 'goal_register',
+  description:
+    'Register a new, custom hidden goal for the encounter when player actions or narrative developments ' +
+    'render existing goals unrealistic, or when players pursue a creative, unexpected path that warrants ' +
+    'a specific mechanical resolution.',
+  args: {
+    id: {
+      type: 'string',
+      description: 'Unique kebab-case ID (e.g. bribe_and_recruit). Must match regex ^[a-z0-9-_]+$.',
+    },
+    label: {
+      type: 'string',
+      description: 'Precise description of the trigger conditions. What must happen for this goal to resolve?',
+    },
+    isPrimary: {
+      type: 'string',
+      description: 'Whether this is a primary driver or secondary fallback (value "true" or "false").',
+    },
+    reason: {
+      type: 'string',
+      description: 'A short explanation of why this goal is being registered on the fly.',
+    },
+  },
+  handler: async (args, ctx) => {
+    const id = (args.id as string).trim();
+    const label = (args.label as string).trim();
+    const isPrimaryStr = (args.isPrimary as string).trim().toLowerCase();
+    const isPrimary = isPrimaryStr === 'true';
+
+    // Auto-prefix ID with dynamic_ to distinguish from spec goals and track limits
+    let finalId = id.toLowerCase();
+    if (!finalId.startsWith('dynamic_')) {
+      finalId = `dynamic_${finalId}`;
+    }
+
+    // Validate regex: kebab-case
+    const idRegex = /^[a-z0-9-_]+$/;
+    if (!idRegex.test(finalId)) {
+      return {
+        systemMessage: `[TOOL ERROR] Invalid goal ID format: "${id}". Must contain only lowercase letters, numbers, hyphens, and underscores.`,
+      };
+    }
+
+    const { session } = ctx;
+
+    // Safeguard: Prevent infinite loops by blocking registration if session has run long
+    if (session.history.length > 20) {
+      return {
+        systemMessage: `[TOOL ERROR] The encounter has gone on for too long (${session.history.length} messages). You cannot register any new goals and must guide the players to a resolution immediately using existing goals.`,
+      };
+    }
+
+    const goals = session.spec.goals;
+
+    // Check if ID already exists
+    const existsInPrimary = goals.primary.some(g => g.id === finalId);
+    const existsInSecondary = goals.secondary.some(g => g.id === finalId);
+
+    if (existsInPrimary || existsInSecondary) {
+      return {
+        systemMessage: `[TOOL ERROR] A goal with ID "${finalId}" already exists in this encounter spec.`,
+      };
+    }
+
+    // Safeguard: Limit to at most 2 dynamic goals per session to ensure the game resolves
+    const dynamicGoalsCount = [
+      ...goals.primary,
+      ...goals.secondary
+    ].filter(g => g.id.startsWith('dynamic_')).length;
+
+    if (dynamicGoalsCount >= 2) {
+      return {
+        systemMessage: `[TOOL ERROR] Maximum limit of 2 dynamic goals reached. You must resolve the encounter using one of the current goals.`,
+      };
+    }
+
+    // Append to appropriate list
+    const updatedGoals = {
+      ...goals,
+      primary: [...goals.primary],
+      secondary: [...goals.secondary],
+    };
+
+    const newGoal = { id: finalId, label };
+    if (isPrimary) {
+      updatedGoals.primary.push(newGoal);
+    } else {
+      updatedGoals.secondary.push(newGoal);
+    }
+
+    const updatedSpec = {
+      ...session.spec,
+      goals: updatedGoals,
+    };
+
+    // Save spec update to Redis session
+    await sessionManager.update(session.threadId, { spec: updatedSpec });
+
+    return {
+      systemMessage: `[TOOL] New hidden goal registered on the fly: "${finalId}" (Primary: ${isPrimary}). Label: "${label}"`,
+    };
+  },
+};
+
+registerTool(goalRegister);
+export default goalRegister;
diff --git a/src/harness/tools/index.ts b/src/harness/tools/index.ts
new file mode 100644
index 0000000..deba96e
--- /dev/null
+++ b/src/harness/tools/index.ts
@@ -0,0 +1,9 @@
+// Side-effect imports — each module calls registerTool() at load time.
+// Add new tool files here to make them available to all encounters.
+import './skillCheckEmit.js';
+import './encounterResolve.js';
+import './contextRecall.js';
+import './goalRegister.js';
+import './foundryLookup.js';
+import './foundryReward.js';
+
diff --git a/src/harness/tools/skillCheckEmit.ts b/src/harness/tools/skillCheckEmit.ts
new file mode 100644
index 0000000..398c2c5
--- /dev/null
+++ b/src/harness/tools/skillCheckEmit.ts
@@ -0,0 +1,138 @@
+import { sessionManager } from '../../session/sessionManager.js';
+import { buildSuspenseEmbed, buildSkillCheckEmbed, buildRollButtons } from '../../bot/embeds/skillCheck.js';
+import { registerTool, type ToolPlugin } from '../toolRegistry.js';
+import { characterRegistry } from '../../session/characterRegistry.js';
+import { getActorDetails, type FoundryActorDetails } from '../../vtt/foundryClient.js';
+import { log } from '../../lib/logger.js';
+
+// ---------------------------------------------------------------------------
+// 30-second in-memory cache for actor details (avoids hammering the relay)
+// ---------------------------------------------------------------------------
+
+const actorCache = new Map<string, { data: FoundryActorDetails; expiresAt: number }>();
+
+async function fetchActorCached(uuid: string): Promise<FoundryActorDetails> {
+  const hit = actorCache.get(uuid);
+  if (hit && hit.expiresAt > Date.now()) return hit.data;
+  const data = await getActorDetails(uuid);
+  actorCache.set(uuid, { data, expiresAt: Date.now() + 30_000 });
+  return data;
+}
+
+// ---------------------------------------------------------------------------
+// Skill / ability name → Foundry key
+// ---------------------------------------------------------------------------
+
+const SKILL_KEY: Record<string, string> = {
+  acrobatics: 'acr', 'animal handling': 'ani', arcana: 'arc',
+  athletics: 'ath', deception: 'dec', history: 'his',
+  insight: 'ins', intimidation: 'itm', investigation: 'inv',
+  medicine: 'med', nature: 'nat', perception: 'prc',
+  performance: 'prf', persuasion: 'per', religion: 'rel',
+  'sleight of hand': 'slt', stealth: 'ste', survival: 'sur',
+  // Ability checks
+  strength: 'str', dexterity: 'dex', constitution: 'con',
+  intelligence: 'int', wisdom: 'wis', charisma: 'cha',
+};
+
+async function resolveModifier(
+  guildId: string,
+  discordId: string,
+  skillName: string,
+): Promise<number | undefined> {
+  const key = SKILL_KEY[skillName.toLowerCase()];
+  if (!key) return undefined;
+
+  const profile = await characterRegistry.get(guildId, discordId);
+  if (!profile?.foundryActorUuid) return undefined;
+
+  const actor = await fetchActorCached(profile.foundryActorUuid);
+
+  // Skill check (proficiency + ability mod already rolled in by Foundry)
+  if (actor.skills?.[key]) return actor.skills[key].total;
+  // Ability check fallback
+  if (actor.abilities?.[key]) return actor.abilities[key].mod;
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Tool plugin
+// ---------------------------------------------------------------------------
+
+const skillCheckEmit: ToolPlugin = {
+  name: 'skill_check_emit',
+  description:
+    'Post a dice-roll embed to the player. ' +
+    'MANDATORY for: attack rolls (melee/ranged/spell), skill checks, ability checks, saving throws, ' +
+    'or any action with a physically uncertain outcome. ' +
+    'Do NOT narrate the outcome — emit and wait for the roll result system message.',
+  args: {
+    player: { type: 'string', description: "Player's character name exactly as it appears in the conversation" },
+    prompt: { type: 'string', description: 'One sentence describing the specific action being attempted (e.g. "Spell attack against Dal with Arcane Burst")' },
+    skill: { type: 'string', description: 'The skill or ability being tested (e.g. "Perception", "Athletics", "Strength"). Used to display the player\'s modifier.' },
+    dc: { type: 'number', description: 'Difficulty Class or target AC (1–30). For spell/melee attacks use the target\'s AC. Use preset values when available.' },
+    advantage: { type: 'boolean', description: 'Set true when the narrative grants advantage (e.g. attacking while hidden, helped by an ally, using a spell that grants advantage).' },
+    disadvantage: { type: 'boolean', description: 'Set true when the narrative imposes disadvantage (e.g. restrained, poisoned, attacking at long range without a feat, blinded).' },
+  },
+  contextDocs: (spec) => {
+    const lines = Object.entries(spec.skillChecks)
+      .filter(([k]) => k.endsWith('_dc'))
+      .map(([k, v]) => `        ${k.replace(/_dc$/, '').replace(/_/g, ' ')}: DC ${v}`)
+      .join('\n');
+    return lines
+      ? `    Preset DCs for this encounter (use these exact values when applicable):\n${lines}`
+      : '';
+  },
+  handler: async (args, ctx) => {
+    const player = args.player as string;
+    const prompt = args.prompt as string;
+    const skill = (args.skill as string | undefined) ?? '';
+    const dc = args.dc as number;
+    const advantage = (args.advantage as boolean | undefined) ?? false;
+    const disadvantage = (args.disadvantage as boolean | undefined) ?? false;
+
+    // Resolve the player's Discord ID from the session roster
+    const discordEntry = Object.entries(ctx.session.players)
+      .find(([, p]) => p.dndName === player);
+    const discordId = discordEntry?.[0];
+
+    let modifier: number | undefined;
+    if (discordId && skill) {
+      try {
+        modifier = await resolveModifier(ctx.session.guildId, discordId, skill);
+        if (modifier !== undefined) {
+          log.info('tool', 'resolved modifier', { player, skill, modifier });
+        }
+      } catch (err) {
+        log.warn('tool', 'modifier lookup failed, continuing without', { player, skill, error: String(err) });
+      }
+    }
+
+    const sent = await ctx.thread.send({ embeds: [buildSuspenseEmbed(player, prompt)] });
+    await sessionManager.update(ctx.session.threadId, {
+      pendingSkillCheck: {
+        player, prompt, dc, messageId: sent.id, modifier, skill: skill || undefined,
+        advantage: advantage || undefined,
+        disadvantage: disadvantage || undefined,
+      },
+      pendingSkillCheckAttempts: 0,
+    });
+    setTimeout(() => {
+      sent
+        .edit({
+          embeds: [buildSkillCheckEmbed(player, prompt, dc, undefined, undefined, modifier, skill || undefined, advantage || undefined, disadvantage || undefined)],
+          components: [buildRollButtons(modifier)],
+        })
+        .catch(() => null);
+    }, 1_500);
+
+    const modNote = modifier !== undefined
+      ? ` Modifier resolved: ${modifier >= 0 ? '+' : ''}${modifier} (${skill}).`
+      : '';
+    const modeNote = advantage ? ' [ADVANTAGE]' : disadvantage ? ' [DISADVANTAGE]' : '';
+    return { systemMessage: `[TOOL] Skill check embed posted for ${player} (DC ${dc}).${modNote}${modeNote}` };
+  },
+};
+
+registerTool(skillCheckEmit);
+export default skillCheckEmit;
diff --git a/src/lib/logger.ts b/src/lib/logger.ts
new file mode 100644
index 0000000..723d3b4
--- /dev/null
+++ b/src/lib/logger.ts
@@ -0,0 +1,20 @@
+type Level = 'info' | 'warn' | 'error' | 'debug';
+type Fields = Record<string, string | number | boolean | undefined>;
+
+function emit(level: Level, tag: string, message: string, fields: Fields = {}): void {
+  const fieldStr = Object.entries(fields)
+    .filter(([, v]) => v !== undefined)
+    .map(([k, v]) => `${k}=${v}`)
+    .join(' ');
+  const line = `[${tag}] ${message}${fieldStr ? ' ' + fieldStr : ''}`;
+  if (level === 'error') console.error(line);
+  else if (level === 'warn') console.warn(line);
+  else console.log(line);
+}
+
+export const log = {
+  info:  (tag: string, message: string, fields?: Fields) => emit('info',  tag, message, fields),
+  warn:  (tag: string, message: string, fields?: Fields) => emit('warn',  tag, message, fields),
+  error: (tag: string, message: string, fields?: Fields) => emit('error', tag, message, fields),
+  debug: (tag: string, message: string, fields?: Fields) => emit('debug', tag, message, fields),
+};
diff --git a/src/persona/loader.ts b/src/persona/loader.ts
new file mode 100644
index 0000000..252bf96
--- /dev/null
+++ b/src/persona/loader.ts
@@ -0,0 +1,25 @@
+import { readFileSync } from 'fs';
+import yaml from 'js-yaml';
+import { z } from 'zod';
+
+const PersonaSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  persona: z.string(),
+  responseStyle: z.string(),
+});
+
+export type Persona = z.infer<typeof PersonaSchema>;
+
+let _cached: Persona | null = null;
+
+export function loadPersona(path = './persona.yaml'): Persona {
+  if (_cached) return _cached;
+  const raw = yaml.load(readFileSync(path, 'utf8'));
+  _cached = PersonaSchema.parse(raw);
+  return _cached;
+}
+
+export function clearPersonaCache(): void {
+  _cached = null;
+}
diff --git a/src/scripts/deploy-commands.ts b/src/scripts/deploy-commands.ts
new file mode 100644
index 0000000..b056778
--- /dev/null
+++ b/src/scripts/deploy-commands.ts
@@ -0,0 +1,43 @@
+import { REST, Routes } from 'discord.js';
+import 'dotenv/config';
+import { config } from '../config.js';
+import { data as dndnameData } from '../bot/commands/dndname.js';
+import { data as encounterData } from '../bot/commands/encounter.js';
+import { data as characterData } from '../bot/commands/character.js';
+import { data as rollData } from '../bot/commands/roll.js';
+import { data as actionsData } from '../bot/commands/actions.js';
+import { data as xpData } from '../bot/commands/xp.js';
+import { data as encountersData } from '../bot/commands/encounters.js';
+
+const commands = [
+  dndnameData.toJSON(),
+  encounterData.toJSON(),
+  characterData.toJSON(),
+  rollData.toJSON(),
+  actionsData.toJSON(),
+  xpData.toJSON(),
+  encountersData.toJSON(),
+];
+
+const rest = new REST({ version: '10' }).setToken(config.DISCORD_TOKEN);
+
+async function deploy(): Promise<void> {
+  if (config.DISCORD_GUILD_ID) {
+    // Clear any lingering global commands so guild and global don't both show up
+    await rest.put(Routes.applicationCommands(config.DISCORD_CLIENT_ID), { body: [] });
+    console.log(`Registering ${commands.length} slash commands to guild ${config.DISCORD_GUILD_ID}…`);
+    await rest.put(
+      Routes.applicationGuildCommands(config.DISCORD_CLIENT_ID, config.DISCORD_GUILD_ID),
+      { body: commands },
+    );
+  } else {
+    console.log(`Registering ${commands.length} slash commands globally (up to 1hr propagation)…`);
+    await rest.put(Routes.applicationCommands(config.DISCORD_CLIENT_ID), { body: commands });
+  }
+  console.log('Done.');
+}
+
+deploy().catch((err) => {
+  console.error('deploy-commands failed:', err);
+  process.exit(1);
+});
diff --git a/src/session/characterRegistry.ts b/src/session/characterRegistry.ts
new file mode 100644
index 0000000..efc342c
--- /dev/null
+++ b/src/session/characterRegistry.ts
@@ -0,0 +1,45 @@
+import { redis } from '../db/redis.js';
+
+export interface CharacterProfile {
+  discordId: string;
+  dndName: string;
+  source: 'foundry' | 'custom';
+  // Set when linked to a Foundry actor
+  foundryActorUuid?: string;
+  // Optional supplemental fields — always present for custom, optional for Foundry-linked
+  characterClass?: string;
+  level?: number;
+  race?: string;
+  backstory?: string;
+  pronouns?: string;
+}
+
+const key = (guildId: string) => `characters:${guildId}`;
+
+export const characterRegistry = {
+  async get(guildId: string, discordId: string): Promise<CharacterProfile | null> {
+    const raw = await redis.hget(key(guildId), discordId);
+    if (!raw) return null;
+    try {
+      return JSON.parse(raw) as CharacterProfile;
+    } catch {
+      return null;
+    }
+  },
+
+  async set(guildId: string, profile: CharacterProfile): Promise<void> {
+    await redis.hset(key(guildId), profile.discordId, JSON.stringify(profile));
+  },
+
+  async delete(guildId: string, discordId: string): Promise<void> {
+    await redis.hdel(key(guildId), discordId);
+  },
+
+  async list(guildId: string): Promise<CharacterProfile[]> {
+    const all = await redis.hgetall(key(guildId));
+    if (!all) return [];
+    return Object.values(all).flatMap(v => {
+      try { return [JSON.parse(v) as CharacterProfile]; } catch { return []; }
+    });
+  },
+};
diff --git a/src/session/encounterLog.ts b/src/session/encounterLog.ts
new file mode 100644
index 0000000..5ebf737
--- /dev/null
+++ b/src/session/encounterLog.ts
@@ -0,0 +1,63 @@
+import { readFileSync, writeFileSync, mkdirSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { config } from '../config.js';
+import type { SessionState } from '../types/index.js';
+
+function dataDir(): string { return config.DATA_DIR; }
+function tallyPath(): string { return join(dataDir(), 'tally.json'); }
+function summariesDir(): string { return join(dataDir(), 'summaries'); }
+
+function ensureDirs(): void {
+  mkdirSync(dataDir(), { recursive: true });
+  mkdirSync(summariesDir(), { recursive: true });
+}
+
+export interface TallyEntry {
+  runs: number;
+  lastRun: string;
+}
+
+export function incrementTally(specName: string): void {
+  ensureDirs();
+  let tally: Record<string, TallyEntry> = {};
+  try { tally = JSON.parse(readFileSync(tallyPath(), 'utf8')); } catch { /* first run */ }
+  const existing = tally[specName] ?? { runs: 0, lastRun: '' };
+  tally[specName] = { runs: existing.runs + 1, lastRun: new Date().toISOString() };
+  writeFileSync(tallyPath(), JSON.stringify(tally, null, 2));
+}
+
+export function readTally(): Record<string, TallyEntry> {
+  try { return JSON.parse(readFileSync(tallyPath(), 'utf8')); } catch { return {}; }
+}
+
+export function writeSummary(session: SessionState, outcomeId: string, summary: string): string {
+  ensureDirs();
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const filename = `${session.encounterId}-${ts}.txt`;
+  const filePath = join(summariesDir(), filename);
+  const players = Object.values(session.players).map(p => p.dndName).join(', ') || 'None';
+  const content = [
+    `Encounter : ${session.spec.title}`,
+    `ID        : ${session.encounterId}`,
+    `Thread    : ${session.threadId}`,
+    `Date      : ${new Date().toISOString()}`,
+    `Outcome   : ${outcomeId}`,
+    `Players   : ${players}`,
+    ``,
+    `Summary:`,
+    summary,
+  ].join('\n');
+  writeFileSync(filePath, content, 'utf8');
+  return filePath;
+}
+
+export function getLatestSummary(): string | null {
+  try {
+    ensureDirs();
+    const files = readdirSync(summariesDir())
+      .filter(f => f.endsWith('.txt'))
+      .sort()
+      .reverse();
+    return files[0] ? join(summariesDir(), files[0]) : null;
+  } catch { return null; }
+}
diff --git a/src/session/playerRegistry.ts b/src/session/playerRegistry.ts
new file mode 100644
index 0000000..608973a
--- /dev/null
+++ b/src/session/playerRegistry.ts
@@ -0,0 +1,32 @@
+// Thin shim over characterRegistry — all existing callers continue to work
+// unchanged. New code should use characterRegistry directly.
+import { characterRegistry } from './characterRegistry.js';
+import type { Player } from '../types/index.js';
+
+export const playerRegistry = {
+  async get(guildId: string, discordId: string): Promise<Player | null> {
+    const profile = await characterRegistry.get(guildId, discordId);
+    if (!profile) return null;
+    return { discordId, dndName: profile.dndName };
+  },
+
+  async set(guildId: string, discordId: string, dndName: string): Promise<void> {
+    const existing = await characterRegistry.get(guildId, discordId);
+    await characterRegistry.set(guildId, {
+      discordId,
+      dndName,
+      source: existing?.source ?? 'custom',
+      ...(existing && {
+        foundryActorUuid: existing.foundryActorUuid,
+        characterClass: existing.characterClass,
+        level: existing.level,
+        race: existing.race,
+        backstory: existing.backstory,
+      }),
+    });
+  },
+
+  async delete(guildId: string, discordId: string): Promise<void> {
+    await characterRegistry.delete(guildId, discordId);
+  },
+};
diff --git a/src/session/sessionManager.ts b/src/session/sessionManager.ts
new file mode 100644
index 0000000..2da093c
--- /dev/null
+++ b/src/session/sessionManager.ts
@@ -0,0 +1,72 @@
+import { redis } from '../db/redis.js';
+import { config } from '../config.js';
+import type { SessionState, ChatMessage } from '../types/index.js';
+import { CONTEXT_BUDGET } from '../types/index.js';
+import { encode } from 'gpt-tokenizer';
+
+const SESSION_TTL = 60 * 60 * config.SESSION_TTL_HOURS;
+const sessionKey = (threadId: string) => `session:${threadId}`;
+const guildThreadsKey = (guildId: string) => `guild_threads:${guildId}`;
+
+// 15% buffer on top of GPT tokenizer estimate to account for Gemma differences
+function estimateTokens(text: string): number {
+  return Math.ceil(encode(text).length * 1.15);
+}
+
+function estimateMessages(messages: ChatMessage[]): number {
+  return messages.reduce((sum, m) => sum + estimateTokens(m.content) + 4, 0);
+}
+
+function trimHistory(messages: ChatMessage[]): ChatMessage[] {
+  const budget = CONTEXT_BUDGET.HISTORY - CONTEXT_BUDGET.SAFETY;
+  const result = [...messages];
+  while (estimateMessages(result) > budget && result.length > 6) {
+    result.splice(0, 2);
+  }
+  return result;
+}
+
+export const sessionManager = {
+  async create(threadId: string, state: SessionState): Promise<void> {
+    const pipe = redis.pipeline();
+    pipe.set(sessionKey(threadId), JSON.stringify(state), 'EX', SESSION_TTL);
+    pipe.sadd(guildThreadsKey(state.guildId), threadId);
+    pipe.expire(guildThreadsKey(state.guildId), SESSION_TTL);
+    await pipe.exec();
+  },
+
+  async get(threadId: string): Promise<SessionState | null> {
+    const raw = await redis.get(sessionKey(threadId));
+    if (!raw) return null;
+    return JSON.parse(raw) as SessionState;
+  },
+
+  async update(threadId: string, patch: Partial<SessionState>): Promise<void> {
+    const current = await this.get(threadId);
+    if (!current) throw new Error(`Session not found: ${threadId}`);
+    const updated: SessionState = { ...current, ...patch, updatedAt: Date.now() };
+    await redis.set(sessionKey(threadId), JSON.stringify(updated), 'EX', SESSION_TTL);
+  },
+
+  async delete(threadId: string, guildId: string): Promise<void> {
+    await redis.del(sessionKey(threadId));
+    await redis.srem(guildThreadsKey(guildId), threadId);
+  },
+
+  async addMessage(threadId: string, msg: ChatMessage): Promise<void> {
+    const session = await this.get(threadId);
+    if (!session) throw new Error(`Session not found: ${threadId}`);
+
+    const pinned = session.history.filter(m => m.pinned);
+    const sliding = session.history.filter(m => !m.pinned);
+    sliding.push(msg);
+    const trimmed = trimHistory(sliding);
+
+    await this.update(threadId, { history: [...pinned, ...trimmed] });
+  },
+
+  // Returns thread IDs for a guild — used by /dndname set to find held messages.
+  async getGuildThreadIds(guildId: string): Promise<string[]> {
+    return redis.smembers(guildThreadsKey(guildId));
+  },
+};
diff --git a/src/session/xpAwarder.ts b/src/session/xpAwarder.ts
new file mode 100644
index 0000000..742743a
--- /dev/null
+++ b/src/session/xpAwarder.ts
@@ -0,0 +1,54 @@
+import type { ThreadChannel, TextChannel } from 'discord.js';
+import { characterRegistry } from './characterRegistry.js';
+import { modifyExperience } from '../vtt/foundryClient.js';
+import { log } from '../lib/logger.js';
+import type { SessionState } from '../types/index.js';
+
+export interface XPResult {
+  awarded: { dndName: string; amount: number }[];
+  skipped: { dndName: string; reason: string; discordId: string }[];
+}
+
+export async function awardXP(
+  session: SessionState,
+  amount: number,
+  thread: ThreadChannel | TextChannel,
+): Promise<XPResult> {
+  const result: XPResult = { awarded: [], skipped: [] };
+  const players = Object.values(session.players);
+  if (players.length === 0) return result;
+
+  for (const player of players) {
+    let profile;
+    try {
+      profile = await characterRegistry.get(session.guildId, player.discordId);
+    } catch {
+      result.skipped.push({ dndName: player.dndName, discordId: player.discordId, reason: 'registry error' });
+      continue;
+    }
+
+    if (!profile?.foundryActorUuid) {
+      result.skipped.push({ dndName: player.dndName, discordId: player.discordId, reason: 'no Foundry character linked' });
+      continue;
+    }
+
+    try {
+      await modifyExperience(profile.foundryActorUuid, amount);
+      result.awarded.push({ dndName: player.dndName, amount });
+      log.info('xp', `awarded ${amount} XP`, { player: player.dndName });
+    } catch (err) {
+      log.error('xp', 'modifyExperience failed', { player: player.dndName, error: String(err) });
+      result.skipped.push({ dndName: player.dndName, discordId: player.discordId, reason: 'Foundry relay error' });
+    }
+  }
+
+  // Post result summary to the thread (visible to all)
+  const lines: string[] = [`**+${amount} XP awarded**`];
+  for (const a of result.awarded) lines.push(`✅ ${a.dndName}`);
+  for (const s of result.skipped) {
+    lines.push(`⚠️ <@${s.discordId}> (${s.dndName}) — skipped: ${s.reason}`);
+  }
+  await thread.send(lines.join('\n'));
+
+  return result;
+}
diff --git a/src/spec/loader.ts b/src/spec/loader.ts
new file mode 100644
index 0000000..5ff1f6c
--- /dev/null
+++ b/src/spec/loader.ts
@@ -0,0 +1,65 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { load } from 'js-yaml';
+import { z } from 'zod';
+import { config } from '../config.js';
+
+// ---------------------------------------------------------------------------
+// Zod schema
+// ---------------------------------------------------------------------------
+
+const NpcSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  nameKey: z.string().optional(),
+  role: z.string(),
+  persona: z.string(),
+  memoryKey: z.string().optional(),
+});
+
+const GoalSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+});
+
+export const EncounterSpecSchema = z.object({
+  encounterId: z.string(),
+  title: z.string(),
+  setting: z.object({
+    location: z.string(),
+    mood: z.string(),
+    ambientNpcs: z.string(),
+  }),
+  openingNarrative: z.string(),
+  npcs: z.array(NpcSchema).min(1).max(5),
+  goals: z.object({
+    hidden: z.boolean().default(true),
+    primary: z.array(GoalSchema).min(1),
+    secondary: z.array(GoalSchema),
+  }),
+  sportsmanshipRules: z.array(z.string()),
+  skillChecks: z.record(z.union([z.number(), z.string()])),
+  randomizable: z.array(z.object({
+    key: z.string(),
+    query: z.string(),
+    fallback: z.string(),
+    source: z.enum(['graphmcp', 'vocabulary']).optional(),
+    category: z.string().optional(),
+  })).optional(),
+  dmNotes: z.string().optional(),
+  tools: z.array(z.string()).optional(),
+  tone: z.string().optional(),
+});
+
+export type EncounterSpecLoaded = z.infer<typeof EncounterSpecSchema>;
+
+// ---------------------------------------------------------------------------
+// Loader
+// ---------------------------------------------------------------------------
+
+export function loadSpec(specName: string): EncounterSpecLoaded {
+  const filePath = join(config.SPECS_DIR, `${specName}.yaml`);
+  const raw = readFileSync(filePath, 'utf-8');
+  const parsed = load(raw);
+  return EncounterSpecSchema.parse(parsed);
+}
diff --git a/src/types/index.ts b/src/types/index.ts
new file mode 100644
index 0000000..d9553e5
--- /dev/null
+++ b/src/types/index.ts
@@ -0,0 +1,165 @@
+// Shared types used across all layers of the Mardonar Encounter Engine.
+
+// ---------------------------------------------------------------------------
+// Players
+// ---------------------------------------------------------------------------
+
+export interface Player {
+  discordId: string;
+  dndName: string;
+  pronouns?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Encounter Spec
+// ---------------------------------------------------------------------------
+
+export interface NpcPersona {
+  id: string;
+  name: string;
+  // If set, the display name for this session is resolved from resolvedContext[nameKey].
+  // The canonical `name` field remains the graph identity used for memory queries.
+  nameKey?: string;
+  role: string;
+  persona: string;
+  memoryKey?: string;
+}
+
+export interface EncounterGoal {
+  id: string;
+  label: string;
+}
+
+export interface EncounterGoals {
+  hidden: boolean;
+  primary: EncounterGoal[];
+  secondary: EncounterGoal[];
+}
+
+export interface EncounterSetting {
+  location: string;
+  mood: string;
+  ambientNpcs: string;
+}
+
+export interface RandomizableItem {
+  key: string;
+  query: string;
+  fallback: string;
+  // 'vocabulary' samples from lore/vocabulary.yaml using `category` (dot-path, e.g. 'names.dwarf.female').
+  // Default / absent means 'graphmcp' — semantic search against the knowledge graph.
+  source?: 'graphmcp' | 'vocabulary';
+  category?: string;
+}
+
+export interface EncounterSpec {
+  encounterId: string;
+  title: string;
+  setting: EncounterSetting;
+  openingNarrative: string;
+  npcs: NpcPersona[];
+  goals: EncounterGoals;
+  sportsmanshipRules: string[];
+  skillChecks: Record<string, number | string>;
+  randomizable?: RandomizableItem[];
+  dmNotes?: string;
+  // XP awarded to all participants when the encounter resolves.
+  xpReward?: number;
+  // Optional allow-list of tool plugin names active for this encounter.
+  // Omit to enable all registered tools (default behaviour).
+  tools?: string[];
+  // Narration flavor for this encounter (e.g. "grim", "tense", "comedic").
+  // Drives the system prompt tone block and drop notice string selection.
+  tone?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Session State
+// ---------------------------------------------------------------------------
+
+export type SessionPhase = 'open' | 'active' | 'resolved';
+
+export interface PendingSkillCheck {
+  player: string;
+  prompt: string;
+  dc: number;
+  messageId?: string;     // Discord message ID of the embed with roll buttons
+  modifier?: number;      // Pre-fetched Foundry skill/ability modifier, if available
+  skill?: string;         // Skill name as provided by the LLM (e.g. "Perception")
+  advantage?: boolean;    // LLM determined the player has advantage on this roll
+  disadvantage?: boolean; // LLM determined the player has disadvantage on this roll
+}
+
+export interface SessionState {
+  encounterId: string;
+  threadId: string;
+  guildId: string;
+  spec: EncounterSpec;
+  players: Record<string, Player>;
+  history: ChatMessage[];
+  phase: SessionPhase;
+  heldMessages: HeldMessage[];
+  // Formatted NPC memory strings loaded from GraphMCP at session start.
+  // Key is npc.id, value is the formatted memory text for the system prompt.
+  npcMemories: Record<string, string>;
+  // Lore-resolved randomizable details for this session instance.
+  // Key matches RandomizableItem.key; value is the resolved string from GraphMCP.
+  resolvedContext: Record<string, string>;
+  pendingSkillCheck?: PendingSkillCheck;
+  pendingSkillCheckAttempts?: number;
+  outcome?: string;
+  outcomeSummary?: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+// ---------------------------------------------------------------------------
+// Chat History
+// ---------------------------------------------------------------------------
+
+export interface ChatMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+  pinned?: boolean;
+  timestamp: number;
+}
+
+export interface HeldMessage {
+  discordUserId: string;
+  content: string;
+  timestamp: number;
+}
+
+// ---------------------------------------------------------------------------
+// LLM Harness
+// ---------------------------------------------------------------------------
+
+export interface ToolCallBlock {
+  tool: ToolName;
+  args: Record<string, unknown>;
+}
+
+export interface LLMResponse {
+  narrative: string;
+  toolCall?: ToolCallBlock;
+  rawTokensUsed?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Tools
+// ---------------------------------------------------------------------------
+
+// String alias — tool names are defined by the plugin registry, not a static union.
+export type ToolName = string;
+
+// ---------------------------------------------------------------------------
+// Context Budget
+// ---------------------------------------------------------------------------
+
+export const CONTEXT_BUDGET = {
+  SYSTEM: 4_000,
+  PINNED: 2_000,
+  HISTORY: 118_000,
+  SAFETY: 3_500,
+  TOTAL: 128_000,
+} as const;
diff --git a/src/vtt/foundryClient.ts b/src/vtt/foundryClient.ts
new file mode 100644
index 0000000..5c3e4c1
--- /dev/null
+++ b/src/vtt/foundryClient.ts
@@ -0,0 +1,277 @@
+import { config } from '../config.js';
+import { log } from '../lib/logger.js';
+
+// ---------------------------------------------------------------------------
+// HTTP helper
+// ---------------------------------------------------------------------------
+
+function headers(): Record<string, string> {
+  const h: Record<string, string> = {
+    'Content-Type': 'application/json',
+    'x-api-key': config.VTT_API_KEY,
+  };
+  if (config.VTT_CLIENT_ID) h['x-client-id'] = config.VTT_CLIENT_ID;
+  return h;
+}
+
+async function vttGet<T>(path: string, params: Record<string, string | string[]> = {}): Promise<T> {
+  const sp = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    if (Array.isArray(v)) sp.set(k, JSON.stringify(v));
+    else sp.set(k, v);
+  }
+  if (config.VTT_CLIENT_ID) sp.set('clientId', config.VTT_CLIENT_ID);
+  const url = `${config.VTT_RELAY_URL}${path}?${sp}`;
+
+  log.info('relay', `GET ${path}`, { params: sp.toString() || undefined });
+  const start = Date.now();
+  const res = await fetch(url, { headers: headers() });
+  const latencyMs = Date.now() - start;
+
+  if (!res.ok) {
+    const body = await res.text();
+    log.error('relay', `GET ${path} failed`, { status: res.status, latencyMs, body: body.slice(0, 200) });
+    throw new Error(`VTT relay ${res.status} ${path}: ${body}`);
+  }
+
+  const data = await res.json() as T;
+  const count = Array.isArray((data as Record<string, unknown>)?.results)
+    ? ((data as Record<string, unknown>).results as unknown[]).length
+    : undefined;
+  log.info('relay', `GET ${path} ok`, { status: res.status, latencyMs, results: count });
+  return data;
+}
+
+async function vttPost<T>(path: string, body: Record<string, unknown> = {}): Promise<T> {
+  const payload = config.VTT_CLIENT_ID ? { ...body, clientId: config.VTT_CLIENT_ID } : body;
+
+  log.info('relay', `POST ${path}`, { body: JSON.stringify(body).slice(0, 200) });
+  const start = Date.now();
+  const res = await fetch(`${config.VTT_RELAY_URL}${path}`, {
+    method: 'POST',
+    headers: headers(),
+    body: JSON.stringify(payload),
+  });
+  const latencyMs = Date.now() - start;
+
+  if (!res.ok) {
+    const text = await res.text();
+    log.error('relay', `POST ${path} failed`, { status: res.status, latencyMs, body: text.slice(0, 200) });
+    throw new Error(`VTT relay ${res.status} ${path}: ${text}`);
+  }
+
+  const data = await res.json() as T;
+  log.info('relay', `POST ${path} ok`, { status: res.status, latencyMs, output: JSON.stringify(data).slice(0, 200) });
+  return data;
+}
+
+// ---------------------------------------------------------------------------
+// Response types (partial — only fields we actually use)
+// ---------------------------------------------------------------------------
+
+export interface FoundryActorSummary {
+  uuid: string;
+  name: string;
+  subType: string;
+  resultType: string;
+}
+
+export interface AbilityScore {
+  value: number;
+  mod: number;
+}
+
+export interface SkillScore {
+  total: number;
+  passive: number;
+  ability: string;
+}
+
+export interface FoundryItem {
+  name: string;
+  type: string;
+  uuid: string;
+  system?: {
+    quantity?: number;
+    equipped?: boolean;
+    description?: { value?: string };
+    preparation?: { prepared?: boolean };
+    level?: number;
+  };
+}
+
+export interface FoundryActorDetails {
+  uuid: string;
+  name?: string;
+  type?: string;
+  abilities?: Record<string, AbilityScore>;
+  skills?: Record<string, SkillScore>;
+  attributes?: {
+    hp?: { value: number; max: number };
+    ac?: { value: number };
+    prof?: number;
+  };
+  currency?: Record<string, number>;
+  details?: {
+    level?: number;
+    xp?: { value: number };
+    race?: string;
+    background?: string;
+    class?: string;
+  };
+  spellcasting?: string;
+  items?: FoundryItem[];
+  spells?: FoundryItem[];
+}
+
+// The relay wraps actor data in an envelope: { type, requestId, data: FoundryActorDetails }
+interface ActorDetailsEnvelope {
+  data: FoundryActorDetails;
+}
+
+export interface RollResult {
+  total: number;
+  formula: string;
+  success?: boolean;
+}
+
+export interface SearchResult {
+  results?: FoundryActorSummary[];
+  total?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export async function searchActors(query = '', limit = 20): Promise<FoundryActorSummary[]> {
+  const result = await vttGet<SearchResult>('/search', {
+    filter: 'Actor',
+    ...(query ? { query } : {}),
+    limit: String(limit),
+  });
+  return result.results ?? [];
+}
+
+// Filters a raw searchActors result down to world player characters only,
+// excluding compendium entries and NPC actors.
+export function filterPlayerActors(actors: FoundryActorSummary[]): FoundryActorSummary[] {
+  return actors.filter(a => a.subType === 'character' && a.resultType === 'WorldEntity');
+}
+
+
+export async function getActorDetails(actorUuid: string): Promise<FoundryActorDetails> {
+  const envelope = await vttGet<ActorDetailsEnvelope>('/dnd5e/get-actor-details', {
+    actorUuid,
+    details: ['abilities', 'skills', 'attributes', 'currency', 'details'],
+  });
+  return envelope.data;
+}
+
+export async function getActorInventory(actorUuid: string): Promise<FoundryItem[]> {
+  const envelope = await vttGet<ActorDetailsEnvelope>('/dnd5e/get-actor-details', {
+    actorUuid,
+    details: ['inventory'],
+  });
+  const actor = envelope.data;
+  return (actor.items ?? []).filter(i => !['spell', 'feat', 'class', 'subclass', 'race', 'background'].includes(i.type));
+}
+
+export async function getActorSpells(actorUuid: string): Promise<FoundryItem[]> {
+  const envelope = await vttGet<ActorDetailsEnvelope>('/dnd5e/get-actor-details', {
+    actorUuid,
+    details: ['spells'],
+  });
+  return envelope.data.spells ?? [];
+}
+
+export async function giveItem(toUuid: string, itemName: string, quantity = 1): Promise<void> {
+  await vttPost('/give', { toUuid, itemName, quantity });
+}
+
+export async function rollAbilityCheck(
+  actorUuid: string,
+  ability: string,
+  opts: { advantage?: boolean; disadvantage?: boolean } = {},
+): Promise<RollResult> {
+  return vttPost<RollResult>('/dnd5e/ability-check', {
+    actorUuid,
+    ability,
+    createChatMessage: true,
+    ...opts,
+  });
+}
+
+export async function rollSkillCheck(
+  actorUuid: string,
+  skill: string,
+  opts: { advantage?: boolean; disadvantage?: boolean } = {},
+): Promise<RollResult> {
+  return vttPost<RollResult>('/dnd5e/skill-check', {
+    actorUuid,
+    skill,
+    createChatMessage: true,
+    ...opts,
+  });
+}
+
+export async function rollAbilitySave(
+  actorUuid: string,
+  ability: string,
+  opts: { advantage?: boolean; disadvantage?: boolean } = {},
+): Promise<RollResult> {
+  return vttPost<RollResult>('/dnd5e/ability-save', {
+    actorUuid,
+    ability,
+    createChatMessage: true,
+    ...opts,
+  });
+}
+
+export async function modifyExperience(actorUuid: string, amount: number): Promise<void> {
+  await vttPost('/dnd5e/modify-experience', { actorUuid, amount });
+}
+
+// ---------------------------------------------------------------------------
+// Formatted summaries — LLM-readable, not raw JSON
+// ---------------------------------------------------------------------------
+
+export function formatActorSummary(actor: FoundryActorDetails): string {
+  const lines: string[] = [`**${actor.name ?? actor.uuid}** (${actor.type ?? 'unknown'})`];
+
+  if (actor.attributes?.hp) {
+    lines.push(`HP: ${actor.attributes.hp.value}/${actor.attributes.hp.max}  AC: ${actor.attributes.ac?.value ?? '?'}`);
+  }
+  if (actor.details?.level) {
+    lines.push(`Level: ${actor.details.level}${actor.details.race ? `  Race: ${actor.details.race}` : ''}`);
+  }
+  if (actor.abilities) {
+    const abils = Object.entries(actor.abilities)
+      .map(([k, v]) => `${k.toUpperCase()}: ${v.value}(${v.mod >= 0 ? '+' : ''}${v.mod})`)
+      .join('  ');
+    lines.push(abils);
+  }
+  if (actor.details?.xp) {
+    lines.push(`XP: ${actor.details.xp.value}`);
+  }
+  return lines.join('\n');
+}
+
+export function formatInventory(items: FoundryItem[]): string {
+  if (items.length === 0) return 'No items.';
+  return items.map(i => {
+    const qty = i.system?.quantity != null ? ` ×${i.system.quantity}` : '';
+    const eq = i.system?.equipped ? ' [equipped]' : '';
+    return `- ${i.name}${qty}${eq} (${i.type})`;
+  }).join('\n');
+}
+
+export function formatSpells(spells: FoundryItem[]): string {
+  if (spells.length === 0) return 'No spells.';
+  const prepared = spells.filter(s => s.system?.preparation?.prepared);
+  const unprepared = spells.filter(s => !s.system?.preparation?.prepared);
+  const lines: string[] = [];
+  if (prepared.length) lines.push('Prepared: ' + prepared.map(s => s.name).join(', '));
+  if (unprepared.length) lines.push('Known (unprepared): ' + unprepared.map(s => s.name).join(', '));
+  return lines.join('\n');
+}
diff --git a/tests/fixtures/spec.ts b/tests/fixtures/spec.ts
new file mode 100644
index 0000000..00b3a65
--- /dev/null
+++ b/tests/fixtures/spec.ts
@@ -0,0 +1,63 @@
+import type { EncounterSpec, SessionState } from '../../src/types/index.js';
+
+export const mockSpec: EncounterSpec = {
+  encounterId: 'test-encounter-001',
+  title: 'Test Encounter',
+  setting: {
+    location: 'Test Town Square',
+    mood: 'Tense',
+    ambientNpcs: 'A few bystanders',
+  },
+  openingNarrative: 'The scene opens in Test Town.',
+  npcs: [
+    {
+      id: 'npc-one',
+      name: 'Miriam',
+      role: 'Vendor',
+      persona: 'A stout, red-faced Dwarf who takes theft personally.',
+      memoryKey: 'miriam-vendor-mardonar',
+    },
+    {
+      id: 'npc-two',
+      name: 'Dal',
+      role: 'Pickpocket',
+      persona: 'A teenage Half-Elf who steals to survive.',
+      memoryKey: 'dal-thief-mardonar',
+    },
+  ],
+  goals: {
+    hidden: true,
+    primary: [
+      { id: 'catch', label: 'Players physically catch Dal.' },
+      { id: 'negotiate', label: 'Players talk Dal into surrendering.' },
+    ],
+    secondary: [
+      { id: 'escape', label: 'Dal escapes with the apple.' },
+    ],
+  },
+  sportsmanshipRules: [
+    'No instant kills on non-threatening NPCs without prior escalation.',
+    'No controlling another player character.',
+  ],
+  skillChecks: {
+    chase_dc: 13,
+    persuade_dc: 10,
+  },
+};
+
+export const mockSession: SessionState = {
+  encounterId: 'test-encounter-001',
+  threadId: 'thread-123',
+  guildId: 'guild-456',
+  spec: mockSpec,
+  players: {
+    'user-789': { discordId: 'user-789', dndName: 'Aelindra' },
+  },
+  history: [],
+  phase: 'active',
+  heldMessages: [],
+  npcMemories: {},
+  resolvedContext: {},
+  createdAt: 1000000,
+  updatedAt: 1000001,
+};
diff --git a/tests/integration/phase1.test.ts b/tests/integration/phase1.test.ts
new file mode 100644
index 0000000..a8a5779
--- /dev/null
+++ b/tests/integration/phase1.test.ts
@@ -0,0 +1,46 @@
+// Integration tests — require live Redis on localhost:6379.
+// Start services before running: docker compose -f docker-compose.dev.yml up -d
+//
+// Run with: npm run test:int
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+
+// These tests are skipped unless RUN_INTEGRATION=1 is set,
+// so they don't break CI without live services.
+const runInt = process.env.RUN_INTEGRATION === '1';
+
+describe.skipIf(!runInt)('Player registry — live Redis', async () => {
+  let playerRegistry: typeof import('../../src/session/playerRegistry.js').playerRegistry;
+
+  beforeAll(async () => {
+    const { redis } = await import('../../src/db/redis.js');
+    await redis.connect();
+    const mod = await import('../../src/session/playerRegistry.js');
+    playerRegistry = mod.playerRegistry;
+  });
+
+  afterAll(async () => {
+    const { redis } = await import('../../src/db/redis.js');
+    await redis.del('players:int-test-guild');
+    redis.disconnect();
+  });
+
+  it('round-trips set/get/delete', async () => {
+    await playerRegistry.set('int-test-guild', 'user-abc', 'Aelindra');
+    const player = await playerRegistry.get('int-test-guild', 'user-abc');
+    expect(player).toEqual({ discordId: 'user-abc', dndName: 'Aelindra' });
+
+    await playerRegistry.delete('int-test-guild', 'user-abc');
+    expect(await playerRegistry.get('int-test-guild', 'user-abc')).toBeNull();
+  });
+});
+
+describe.skipIf(!runInt)('Spec loader — market-thief.yaml', async () => {
+  it('loads and validates the market-thief spec', async () => {
+    const { loadSpec } = await import('../../src/spec/loader.js');
+    const spec = loadSpec('market-thief');
+    expect(spec.encounterId).toBe('mardonar-market-thief-001');
+    expect(spec.npcs).toHaveLength(2);
+    expect(spec.goals.primary.length).toBeGreaterThan(0);
+  });
+});
diff --git a/tests/unit/characterRegistry.test.ts b/tests/unit/characterRegistry.test.ts
new file mode 100644
index 0000000..b8616d8
--- /dev/null
+++ b/tests/unit/characterRegistry.test.ts
@@ -0,0 +1,95 @@
+import { vi, describe, it, expect, beforeEach } from 'vitest';
+
+const refs = vi.hoisted(() => ({ mockRedis: null as any }));
+
+vi.mock('../../src/db/redis.js', async () => {
+  const { default: RedisMock } = await import('ioredis-mock');
+  refs.mockRedis = new RedisMock();
+  return { redis: refs.mockRedis };
+});
+vi.mock('../../src/config.js', () => ({
+  config: { REDIS_URL: 'redis://localhost:6379' },
+}));
+
+import { characterRegistry } from '../../src/session/characterRegistry.js';
+import type { CharacterProfile } from '../../src/session/characterRegistry.js';
+
+const profile: CharacterProfile = {
+  discordId: 'user-123',
+  dndName: 'Aelindra',
+  characterClass: 'Ranger',
+  level: 5,
+  race: 'Half-Elf',
+  backstory: 'A wandering scout from the northern hills.',
+};
+
+beforeEach(async () => {
+  await refs.mockRedis?.flushall();
+});
+
+describe('characterRegistry', () => {
+  it('set then get returns the full profile', async () => {
+    await characterRegistry.set('guild-1', profile);
+    const result = await characterRegistry.get('guild-1', 'user-123');
+    expect(result).toEqual(profile);
+  });
+
+  it('get on unknown user returns null', async () => {
+    const result = await characterRegistry.get('guild-1', 'unknown');
+    expect(result).toBeNull();
+  });
+
+  it('set overwrites an existing profile', async () => {
+    await characterRegistry.set('guild-1', profile);
+    const updated = { ...profile, level: 6, characterClass: 'Ranger/Rogue' };
+    await characterRegistry.set('guild-1', updated);
+    const result = await characterRegistry.get('guild-1', 'user-123');
+    expect(result?.level).toBe(6);
+    expect(result?.characterClass).toBe('Ranger/Rogue');
+  });
+
+  it('delete removes the profile', async () => {
+    await characterRegistry.set('guild-1', profile);
+    await characterRegistry.delete('guild-1', 'user-123');
+    const result = await characterRegistry.get('guild-1', 'user-123');
+    expect(result).toBeNull();
+  });
+
+  it('profiles are scoped by guildId', async () => {
+    await characterRegistry.set('guild-A', profile);
+    const result = await characterRegistry.get('guild-B', 'user-123');
+    expect(result).toBeNull();
+  });
+
+  it('stores and retrieves optional foundryActorUuid', async () => {
+    const linked = { ...profile, foundryActorUuid: 'Actor.xyz789' };
+    await characterRegistry.set('guild-1', linked);
+    const result = await characterRegistry.get('guild-1', 'user-123');
+    expect(result?.foundryActorUuid).toBe('Actor.xyz789');
+  });
+
+  it('profile without foundryActorUuid has undefined uuid field', async () => {
+    await characterRegistry.set('guild-1', profile);
+    const result = await characterRegistry.get('guild-1', 'user-123');
+    expect(result?.foundryActorUuid).toBeUndefined();
+  });
+
+  it('stores and retrieves pronouns', async () => {
+    const withPronouns = { ...profile, pronouns: 'she/her' };
+    await characterRegistry.set('guild-1', withPronouns);
+    const result = await characterRegistry.get('guild-1', 'user-123');
+    expect(result?.pronouns).toBe('she/her');
+  });
+
+  it('pronouns is undefined when not set', async () => {
+    await characterRegistry.set('guild-1', profile);
+    const result = await characterRegistry.get('guild-1', 'user-123');
+    expect(result?.pronouns).toBeUndefined();
+  });
+
+  it('handles corrupt Redis data gracefully by returning null', async () => {
+    await refs.mockRedis.hset('characters:guild-1', 'user-bad', 'not-json{{{');
+    const result = await characterRegistry.get('guild-1', 'user-bad');
+    expect(result).toBeNull();
+  });
+});
diff --git a/tests/unit/config.test.ts b/tests/unit/config.test.ts
new file mode 100644
index 0000000..34845f9
--- /dev/null
+++ b/tests/unit/config.test.ts
@@ -0,0 +1,77 @@
+import { describe, it, expect } from 'vitest';
+import { EnvSchema } from '../../src/config.js';
+
+const base = { DISCORD_TOKEN: 'tok', DISCORD_CLIENT_ID: 'cid' };
+
+describe('EnvSchema', () => {
+  it('parses required fields', () => {
+    const c = EnvSchema.parse(base);
+    expect(c.DISCORD_TOKEN).toBe('tok');
+    expect(c.DISCORD_CLIENT_ID).toBe('cid');
+  });
+
+  it('applies all defaults', () => {
+    const c = EnvSchema.parse(base);
+    expect(c.REDIS_URL).toBe('redis://localhost:6379');
+    expect(c.OLLAMA_TEMPERATURE).toBe(0.75);
+    expect(c.OLLAMA_NUM_CTX).toBe(131072);
+    expect(c.SESSION_TTL_HOURS).toBe(12);
+    expect(c.GRAPHMCP_SCORE_THRESHOLD).toBe(0.68);
+    expect(c.ENCOUNTER_ARCHIVE_DELAY_MS).toBe(5_000);
+    expect(c.ENCOUNTER_GATE_TIMEOUT_MS).toBe(30_000);
+    expect(c.PERSONA_PATH).toBe('./persona.yaml');
+    expect(c.DATA_DIR).toBe('./data');
+  });
+
+  it('splits DISCORD_ALLOWED_CHANNELS on commas and trims whitespace', () => {
+    const c = EnvSchema.parse({ ...base, DISCORD_ALLOWED_CHANNELS: '111, 222 , 333' });
+    expect(c.DISCORD_ALLOWED_CHANNELS).toEqual(['111', '222', '333']);
+  });
+
+  it('returns empty array for blank DISCORD_ALLOWED_CHANNELS', () => {
+    const c = EnvSchema.parse({ ...base, DISCORD_ALLOWED_CHANNELS: '' });
+    expect(c.DISCORD_ALLOWED_CHANNELS).toEqual([]);
+  });
+
+  it('splits DISCORD_ALLOWED_USERS correctly', () => {
+    const c = EnvSchema.parse({ ...base, DISCORD_ALLOWED_USERS: 'u1,u2' });
+    expect(c.DISCORD_ALLOWED_USERS).toEqual(['u1', 'u2']);
+  });
+
+  it('coerces OLLAMA_TEMPERATURE from string', () => {
+    const c = EnvSchema.parse({ ...base, OLLAMA_TEMPERATURE: '0.5' });
+    expect(c.OLLAMA_TEMPERATURE).toBe(0.5);
+  });
+
+  it('coerces SESSION_TTL_HOURS from string', () => {
+    const c = EnvSchema.parse({ ...base, SESSION_TTL_HOURS: '24' });
+    expect(c.SESSION_TTL_HOURS).toBe(24);
+  });
+
+  it('coerces GRAPHMCP_SCORE_THRESHOLD from string', () => {
+    const c = EnvSchema.parse({ ...base, GRAPHMCP_SCORE_THRESHOLD: '0.9' });
+    expect(c.GRAPHMCP_SCORE_THRESHOLD).toBe(0.9);
+  });
+
+  it('rejects invalid LOG_LEVEL', () => {
+    expect(() => EnvSchema.parse({ ...base, LOG_LEVEL: 'verbose' })).toThrow();
+  });
+
+  it('rejects OLLAMA_TEMPERATURE above 2', () => {
+    expect(() => EnvSchema.parse({ ...base, OLLAMA_TEMPERATURE: '3' })).toThrow();
+  });
+
+  it('rejects GRAPHMCP_SCORE_THRESHOLD above 1', () => {
+    expect(() => EnvSchema.parse({ ...base, GRAPHMCP_SCORE_THRESHOLD: '1.5' })).toThrow();
+  });
+
+  it('accepts optional DISCORD_GUILD_ID', () => {
+    const c = EnvSchema.parse({ ...base, DISCORD_GUILD_ID: 'g123' });
+    expect(c.DISCORD_GUILD_ID).toBe('g123');
+  });
+
+  it('DISCORD_GUILD_ID is undefined when not set', () => {
+    const c = EnvSchema.parse(base);
+    expect(c.DISCORD_GUILD_ID).toBeUndefined();
+  });
+});
diff --git a/tests/unit/contextAssembler.test.ts b/tests/unit/contextAssembler.test.ts
new file mode 100644
index 0000000..af4dd05
--- /dev/null
+++ b/tests/unit/contextAssembler.test.ts
@@ -0,0 +1,84 @@
+import { describe, it, expect } from 'vitest';
+import { assembleContext } from '../../src/harness/contextAssembler.js';
+import { mockSession, mockSpec } from '../fixtures/spec.js';
+import type { SessionState, ChatMessage } from '../../src/types/index.js';
+
+function makeMessage(role: ChatMessage['role'], content: string, pinned = false): ChatMessage {
+  return { role, content, pinned, timestamp: Date.now() };
+}
+
+describe('assembleContext', () => {
+  it('puts the system message first', () => {
+    const context = assembleContext(mockSession);
+    expect(context[0].role).toBe('system');
+  });
+
+  it('includes the system prompt content', () => {
+    const context = assembleContext(mockSession);
+    expect(context[0].content).toContain('narrator');
+  });
+
+  it('always includes pinned messages after system', () => {
+    const session: SessionState = {
+      ...mockSession,
+      history: [
+        makeMessage('assistant', 'Opening narrative.', true),
+        makeMessage('user', 'Player action.'),
+        makeMessage('assistant', 'LLM response.'),
+      ],
+    };
+    const context = assembleContext(session);
+    const pinned = context.filter(m => m.pinned && m.role !== 'system');
+    expect(pinned).toHaveLength(1);
+    expect(pinned[0].content).toBe('Opening narrative.');
+  });
+
+  it('includes sliding history messages', () => {
+    const session: SessionState = {
+      ...mockSession,
+      history: [
+        makeMessage('user', 'Player says something.'),
+        makeMessage('assistant', 'Narrator responds.'),
+      ],
+    };
+    const context = assembleContext(session);
+    const nonSystem = context.filter(m => !m.pinned);
+    expect(nonSystem.some(m => m.content === 'Player says something.')).toBe(true);
+  });
+
+  it('injects NPC memory into the system prompt', () => {
+    const session: SessionState = {
+      ...mockSession,
+      npcMemories: {
+        'npc-one': 'Past encounters witnessed:\n  - [2026-01-01] Tavern Brawl: A fight broke out.',
+      },
+    };
+    const context = assembleContext(session);
+    expect(context[0].content).toContain('Tavern Brawl');
+  });
+
+  it('drops oldest non-pinned pairs when history exceeds budget', () => {
+    // Use natural language so BPE tokenisation produces realistic token counts.
+    // Repeated single characters compress to almost nothing in BPE.
+    const bigContent = 'the quick brown fox jumps over the lazy dog. '.repeat(100);
+    const history: ChatMessage[] = [
+      makeMessage('assistant', 'Opening narrative pinned.', true),
+    ];
+    // 200 pairs × ~1 000 tokens each ≈ 200 000 tokens >> 114 500 budget
+    for (let i = 0; i < 200; i++) {
+      history.push(makeMessage('user', `${bigContent} turn ${i}`));
+      history.push(makeMessage('assistant', `${bigContent} response ${i}`));
+    }
+
+    const session: SessionState = { ...mockSession, history };
+    const context = assembleContext(session);
+
+    // Pinned message must survive trimming
+    const pinnedInContext = context.filter(m => m.pinned && m.role !== 'system');
+    expect(pinnedInContext).toHaveLength(1);
+
+    // Sliding window should be well under the 400 we pushed in
+    const sliding = context.filter(m => !m.pinned);
+    expect(sliding.length).toBeLessThan(400);
+  });
+});
diff --git a/tests/unit/encounterDiscoveryEmbed.test.ts b/tests/unit/encounterDiscoveryEmbed.test.ts
new file mode 100644
index 0000000..8639f07
--- /dev/null
+++ b/tests/unit/encounterDiscoveryEmbed.test.ts
@@ -0,0 +1,66 @@
+import { describe, it, expect } from 'vitest';
+import { buildEncounterListEmbed } from '../../src/bot/embeds/encounterDiscovery.js';
+
+const sampleEncounters = [
+  { title: 'The Iron Vault', phase: 'active', playerCount: 2, location: 'Mardonar City', threadId: 'thread-111' },
+  { title: 'Market Heist', phase: 'open', playerCount: 0, location: 'The Bazaar', threadId: 'thread-222' },
+];
+
+describe('buildEncounterListEmbed — empty', () => {
+  it('uses gray color when no encounters', () => {
+    const data = buildEncounterListEmbed([]).toJSON();
+    expect(data.color).toBe(0x95a5a6);
+  });
+
+  it('description mentions asking the DM', () => {
+    const data = buildEncounterListEmbed([]).toJSON();
+    expect(data.description).toMatch(/no encounters|ask your dm/i);
+  });
+
+  it('has no fields when empty', () => {
+    const data = buildEncounterListEmbed([]).toJSON();
+    expect(data.fields ?? []).toHaveLength(0);
+  });
+});
+
+describe('buildEncounterListEmbed — with encounters', () => {
+  it('uses blue color when encounters exist', () => {
+    const data = buildEncounterListEmbed(sampleEncounters).toJSON();
+    expect(data.color).toBe(0x5865f2);
+  });
+
+  it('adds one field per encounter', () => {
+    const data = buildEncounterListEmbed(sampleEncounters).toJSON();
+    expect(data.fields).toHaveLength(2);
+  });
+
+  it('uses the encounter title as the field name', () => {
+    const data = buildEncounterListEmbed(sampleEncounters).toJSON();
+    expect(data.fields![0].name).toBe('The Iron Vault');
+  });
+
+  it('includes a channel mention in the field value', () => {
+    const data = buildEncounterListEmbed(sampleEncounters).toJSON();
+    expect(data.fields![0].value).toContain('<#thread-111>');
+  });
+
+  it('includes the phase in the field value', () => {
+    const data = buildEncounterListEmbed(sampleEncounters).toJSON();
+    expect(data.fields![0].value).toContain('active');
+  });
+
+  it('includes the location in the field value', () => {
+    const data = buildEncounterListEmbed(sampleEncounters).toJSON();
+    expect(data.fields![0].value).toContain('Mardonar City');
+  });
+
+  it('title mentions Active Encounters', () => {
+    const data = buildEncounterListEmbed(sampleEncounters).toJSON();
+    expect(data.title).toContain('Active Encounters');
+  });
+
+  it('footer mentions joining via thread', () => {
+    const data = buildEncounterListEmbed(sampleEncounters).toJSON();
+    expect(data.footer?.text).toMatch(/join/i);
+  });
+});
diff --git a/tests/unit/encounterLog.test.ts b/tests/unit/encounterLog.test.ts
new file mode 100644
index 0000000..135ab1e
--- /dev/null
+++ b/tests/unit/encounterLog.test.ts
@@ -0,0 +1,103 @@
+import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+// Point DATA_DIR at a real temp directory so tests don't pollute ./data
+let tmpDir: string;
+
+vi.mock('../../src/config.js', () => ({
+  config: {
+    get DATA_DIR() { return tmpDir; },
+  },
+}));
+
+import {
+  incrementTally,
+  readTally,
+  writeSummary,
+  getLatestSummary,
+} from '../../src/session/encounterLog.js';
+import { mockSession } from '../fixtures/spec.js';
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), 'mardonar-test-'));
+});
+
+afterEach(() => {
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe('readTally', () => {
+  it('returns empty object when tally file does not exist', () => {
+    expect(readTally()).toEqual({});
+  });
+});
+
+describe('incrementTally', () => {
+  it('creates a new entry on first call', () => {
+    incrementTally('market-thief');
+    const tally = readTally();
+    expect(tally['market-thief'].runs).toBe(1);
+    expect(tally['market-thief'].lastRun).toBeTruthy();
+  });
+
+  it('increments an existing entry', () => {
+    incrementTally('market-thief');
+    incrementTally('market-thief');
+    incrementTally('market-thief');
+    expect(readTally()['market-thief'].runs).toBe(3);
+  });
+
+  it('tracks multiple specs independently', () => {
+    incrementTally('market-thief');
+    incrementTally('dungeon-ambush');
+    incrementTally('dungeon-ambush');
+    const tally = readTally();
+    expect(tally['market-thief'].runs).toBe(1);
+    expect(tally['dungeon-ambush'].runs).toBe(2);
+  });
+});
+
+describe('writeSummary', () => {
+  it('returns a path ending in .txt', () => {
+    const path = writeSummary(mockSession, 'catch', 'Dal was caught.');
+    expect(path).toMatch(/\.txt$/);
+  });
+
+  it('written file contains expected fields', async () => {
+    const { readFileSync } = await import('fs');
+    const path = writeSummary(mockSession, 'catch', 'Dal was caught by the player.');
+    const content = readFileSync(path, 'utf8');
+    expect(content).toContain('Test Encounter');
+    expect(content).toContain('test-encounter-001');
+    expect(content).toContain('catch');
+    expect(content).toContain('Dal was caught by the player.');
+    expect(content).toContain('Aelindra');
+  });
+
+  it('shows None for players when session has no players', async () => {
+    const { readFileSync } = await import('fs');
+    const emptySession = { ...mockSession, players: {} };
+    const path = writeSummary(emptySession, 'escape', 'Dal escaped.');
+    const content = readFileSync(path, 'utf8');
+    expect(content).toContain('Players   : None');
+  });
+});
+
+describe('getLatestSummary', () => {
+  it('returns null when no summaries exist', () => {
+    expect(getLatestSummary()).toBeNull();
+  });
+
+  it('returns the path of the most recently written summary', async () => {
+    writeSummary(mockSession, 'catch', 'First summary.');
+    await new Promise(r => setTimeout(r, 10)); // ensure different timestamps
+    writeSummary(mockSession, 'escape', 'Second summary.');
+
+    const latest = getLatestSummary();
+    expect(latest).toBeTruthy();
+    const { readFileSync } = await import('fs');
+    expect(readFileSync(latest!, 'utf8')).toContain('Second summary.');
+  });
+});
diff --git a/tests/unit/foundryClientFormatters.test.ts b/tests/unit/foundryClientFormatters.test.ts
new file mode 100644
index 0000000..538a3aa
--- /dev/null
+++ b/tests/unit/foundryClientFormatters.test.ts
@@ -0,0 +1,203 @@
+import { vi, describe, it, expect, beforeEach } from 'vitest';
+
+vi.mock('../../src/config.js', () => ({
+  config: {
+    VTT_RELAY_URL: 'https://vtt-relay.damascusfront.net',
+    VTT_API_KEY: 'test-key',
+    VTT_CLIENT_ID: '',
+  },
+}));
+
+import {
+  filterPlayerActors,
+  formatActorSummary,
+  formatInventory,
+  formatSpells,
+  type FoundryActorDetails,
+  type FoundryActorSummary,
+  type FoundryItem,
+} from '../../src/vtt/foundryClient.js';
+
+// ---------------------------------------------------------------------------
+// filterPlayerActors — world PC filter used by all lookup / give / link flows
+// ---------------------------------------------------------------------------
+
+function makeActor(overrides: Partial<FoundryActorSummary>): FoundryActorSummary {
+  return {
+    uuid: 'Actor.abc',
+    name: 'Test',
+    subType: 'character',
+    resultType: 'WorldEntity',
+    ...overrides,
+  };
+}
+
+describe('filterPlayerActors', () => {
+  it('passes through world player characters', () => {
+    const pc = makeActor({ name: 'Zalram Cloudwalker' });
+    expect(filterPlayerActors([pc])).toHaveLength(1);
+    expect(filterPlayerActors([pc])[0].name).toBe('Zalram Cloudwalker');
+  });
+
+  it('excludes compendium characters (correct subType, wrong resultType)', () => {
+    const compendiumChar = makeActor({ resultType: 'CompendiumEntity', name: 'Abbot' });
+    expect(filterPlayerActors([compendiumChar])).toHaveLength(0);
+  });
+
+  it('excludes world NPCs (wrong subType)', () => {
+    const npc = makeActor({ subType: 'npc', name: 'Usk the Hunter' });
+    expect(filterPlayerActors([npc])).toHaveLength(0);
+  });
+
+  it('excludes compendium NPCs (both wrong)', () => {
+    const monster = makeActor({ subType: 'npc', resultType: 'CompendiumEntity', name: 'Aboleth' });
+    expect(filterPlayerActors([monster])).toHaveLength(0);
+  });
+
+  it('returns only world PCs from a mixed result set', () => {
+    const mixed = [
+      makeActor({ name: 'Patches Grimlock' }),
+      makeActor({ name: 'Zalram Cloudwalker', uuid: 'Actor.zzz' }),
+      makeActor({ subType: 'npc', resultType: 'CompendiumEntity', name: 'Adult Red Dragon' }),
+      makeActor({ subType: 'character', resultType: 'CompendiumEntity', name: 'Abbot' }),
+      makeActor({ subType: 'npc', resultType: 'WorldEntity', name: 'Innkeeper' }),
+    ];
+    const result = filterPlayerActors(mixed);
+    expect(result).toHaveLength(2);
+    expect(result.map(r => r.name)).toEqual(['Patches Grimlock', 'Zalram Cloudwalker']);
+  });
+
+  it('returns empty array when no world PCs exist', () => {
+    const monsters = [makeActor({ subType: 'npc', resultType: 'CompendiumEntity', name: 'Goblin' })];
+    expect(filterPlayerActors(monsters)).toHaveLength(0);
+  });
+});
+
+const baseActor: FoundryActorDetails = {
+  uuid: 'Actor.abc123',
+  name: 'Aelindra',
+  type: 'character',
+  abilities: {
+    str: { value: 14, mod: 2 },
+    dex: { value: 18, mod: 4 },
+    con: { value: 12, mod: 1 },
+    int: { value: 10, mod: 0 },
+    wis: { value: 13, mod: 1 },
+    cha: { value: 16, mod: 3 },
+  },
+  attributes: {
+    hp: { value: 28, max: 35 },
+    ac: { value: 15 },
+    prof: 3,
+  },
+  details: {
+    level: 5,
+    race: 'Half-Elf',
+    xp: { value: 6500 },
+  },
+};
+
+describe('formatActorSummary', () => {
+  it('includes the actor name', () => {
+    expect(formatActorSummary(baseActor)).toContain('Aelindra');
+  });
+
+  it('includes HP and max HP', () => {
+    const output = formatActorSummary(baseActor);
+    expect(output).toContain('28');
+    expect(output).toContain('35');
+  });
+
+  it('includes AC', () => {
+    expect(formatActorSummary(baseActor)).toContain('15');
+  });
+
+  it('includes character level', () => {
+    expect(formatActorSummary(baseActor)).toContain('5');
+  });
+
+  it('includes race', () => {
+    expect(formatActorSummary(baseActor)).toContain('Half-Elf');
+  });
+
+  it('includes all six ability scores with modifiers', () => {
+    const output = formatActorSummary(baseActor);
+    expect(output).toContain('STR');
+    expect(output).toContain('DEX');
+    expect(output).toContain('+4'); // dex mod
+    expect(output).toContain('+2'); // str mod
+  });
+
+  it('handles actor with no optional fields gracefully', () => {
+    const bare: FoundryActorDetails = { uuid: 'x', name: 'Ghost', type: 'npc' };
+    expect(() => formatActorSummary(bare)).not.toThrow();
+    expect(formatActorSummary(bare)).toContain('Ghost');
+  });
+});
+
+describe('formatInventory', () => {
+  const items: FoundryItem[] = [
+    { name: 'Healing Potion', type: 'consumable', uuid: 'Item.1', system: { quantity: 2, equipped: false } },
+    { name: 'Longsword', type: 'weapon', uuid: 'Item.2', system: { quantity: 1, equipped: true } },
+  ];
+
+  it('returns "No items." for empty array', () => {
+    expect(formatInventory([])).toBe('No items.');
+  });
+
+  it('lists each item name', () => {
+    const output = formatInventory(items);
+    expect(output).toContain('Healing Potion');
+    expect(output).toContain('Longsword');
+  });
+
+  it('shows quantity', () => {
+    expect(formatInventory(items)).toContain('×2');
+  });
+
+  it('marks equipped items', () => {
+    expect(formatInventory(items)).toContain('[equipped]');
+  });
+
+  it('shows item type', () => {
+    expect(formatInventory(items)).toContain('weapon');
+  });
+});
+
+describe('formatSpells', () => {
+  const spells: FoundryItem[] = [
+    { name: 'Fireball', type: 'spell', uuid: 'Item.3', system: { preparation: { prepared: true } } },
+    { name: 'Fly', type: 'spell', uuid: 'Item.4', system: { preparation: { prepared: false } } },
+    { name: 'Mage Armor', type: 'spell', uuid: 'Item.5', system: { preparation: { prepared: true } } },
+  ];
+
+  it('returns "No spells." for empty array', () => {
+    expect(formatSpells([])).toBe('No spells.');
+  });
+
+  it('lists prepared spells under Prepared section', () => {
+    const output = formatSpells(spells);
+    expect(output).toContain('Fireball');
+    expect(output).toContain('Mage Armor');
+    expect(output).toContain('Prepared');
+  });
+
+  it('lists unprepared spells separately', () => {
+    const output = formatSpells(spells);
+    expect(output).toContain('Fly');
+    expect(output).toContain('Known');
+  });
+
+  it('handles all spells prepared', () => {
+    const allPrepared = spells.filter(s => s.system?.preparation?.prepared);
+    const output = formatSpells(allPrepared);
+    expect(output).not.toContain('Known');
+  });
+
+  it('handles all spells unprepared', () => {
+    const noPrepared = [{ name: 'Sleep', type: 'spell', uuid: 'Item.6', system: { preparation: { prepared: false } } }];
+    const output = formatSpells(noPrepared);
+    expect(output).not.toContain('Prepared:');
+    expect(output).toContain('Sleep');
+  });
+});
diff --git a/tests/unit/generationQueue.test.ts b/tests/unit/generationQueue.test.ts
new file mode 100644
index 0000000..5eeecfb
--- /dev/null
+++ b/tests/unit/generationQueue.test.ts
@@ -0,0 +1,157 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { scheduleLLMTurn } from '../../src/bot/handlers/generationQueue.js';
+
+// Each test uses a unique threadId so module-level Map state doesn't bleed between tests.
+let counter = 0;
+function id() { return `test-thread-${counter++}`; }
+
+describe('scheduleLLMTurn', () => {
+  beforeEach(() => { vi.useFakeTimers(); });
+  afterEach(() => { vi.useRealTimers(); });
+
+  // ── Debounce ──────────────────────────────────────────────────────────────
+
+  it('does not fire immediately — waits for debounce window', async () => {
+    const runner = vi.fn().mockResolvedValue(undefined);
+    scheduleLLMTurn(id(), runner);
+    expect(runner).not.toHaveBeenCalled();
+  });
+
+  it('fires exactly once after 500ms', async () => {
+    const runner = vi.fn().mockResolvedValue(undefined);
+    scheduleLLMTurn(id(), runner);
+    await vi.advanceTimersByTimeAsync(500);
+    expect(runner).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not fire before the 500ms window closes', async () => {
+    const runner = vi.fn().mockResolvedValue(undefined);
+    scheduleLLMTurn(id(), runner);
+    await vi.advanceTimersByTimeAsync(499);
+    expect(runner).not.toHaveBeenCalled();
+  });
+
+  it('coalesces rapid calls — only the last runner fires', async () => {
+    const tid = id();
+    const r1 = vi.fn().mockResolvedValue(undefined);
+    const r2 = vi.fn().mockResolvedValue(undefined);
+    const r3 = vi.fn().mockResolvedValue(undefined);
+
+    scheduleLLMTurn(tid, r1);
+    scheduleLLMTurn(tid, r2);
+    scheduleLLMTurn(tid, r3);
+
+    await vi.advanceTimersByTimeAsync(500);
+
+    expect(r1).not.toHaveBeenCalled();
+    expect(r2).not.toHaveBeenCalled();
+    expect(r3).toHaveBeenCalledTimes(1);
+  });
+
+  it('resets the debounce window on each new call', async () => {
+    const tid = id();
+    const runner = vi.fn().mockResolvedValue(undefined);
+
+    scheduleLLMTurn(tid, runner);
+    await vi.advanceTimersByTimeAsync(400); // close but not yet
+    scheduleLLMTurn(tid, runner);          // resets the window
+    await vi.advanceTimersByTimeAsync(400); // only 400ms since last call
+    expect(runner).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(100); // now 500ms since last call
+    expect(runner).toHaveBeenCalledTimes(1);
+  });
+
+  // ── Immediate flag ────────────────────────────────────────────────────────
+
+  it('immediate=true fires on the next tick, not after 500ms', async () => {
+    const runner = vi.fn().mockResolvedValue(undefined);
+    scheduleLLMTurn(id(), runner, true);
+
+    // Not yet (synchronous)
+    expect(runner).not.toHaveBeenCalled();
+
+    // setTimeout(0) flush
+    await vi.advanceTimersByTimeAsync(0);
+    expect(runner).toHaveBeenCalledTimes(1);
+  });
+
+  it('immediate call does not fire at 500ms — already fired at 0', async () => {
+    const runner = vi.fn().mockResolvedValue(undefined);
+    scheduleLLMTurn(id(), runner, true);
+    await vi.advanceTimersByTimeAsync(500);
+    expect(runner).toHaveBeenCalledTimes(1); // exactly once, not twice
+  });
+
+  // ── Generation lock ───────────────────────────────────────────────────────
+
+  it('queues calls during generation and drains with one follow-up turn', async () => {
+    const tid = id();
+    let calls = 0;
+    let resolveFirst!: () => void;
+
+    const runner = vi.fn().mockImplementation(() => {
+      calls++;
+      if (calls === 1) return new Promise<void>(r => { resolveFirst = r; });
+      return Promise.resolve();
+    });
+
+    // Start first generation (immediate)
+    scheduleLLMTurn(tid, runner, true);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(calls).toBe(1); // first turn in progress
+
+    // 3 messages arrive during generation — all should queue, none should fire
+    scheduleLLMTurn(tid, runner);
+    scheduleLLMTurn(tid, runner);
+    scheduleLLMTurn(tid, runner);
+
+    // Even after the debounce window, isGenerating blocks the timer
+    await vi.advanceTimersByTimeAsync(600);
+    expect(calls).toBe(1);
+
+    // Complete the first runner → drain fires exactly once (not 3 times)
+    resolveFirst();
+    await vi.runAllTimersAsync();
+    expect(calls).toBe(2);
+  });
+
+  it('does not fire a drain turn when nothing queued during generation', async () => {
+    const tid = id();
+    let calls = 0;
+    let resolveFirst!: () => void;
+
+    const runner = vi.fn().mockImplementation(() => {
+      calls++;
+      if (calls === 1) return new Promise<void>(r => { resolveFirst = r; });
+      return Promise.resolve();
+    });
+
+    scheduleLLMTurn(tid, runner, true);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(calls).toBe(1);
+
+    // Nothing queued — complete generation
+    resolveFirst();
+    await vi.runAllTimersAsync();
+    expect(calls).toBe(1); // no drain
+  });
+
+  // ── Error resilience ──────────────────────────────────────────────────────
+
+  it('releases the generation lock even if the runner throws', async () => {
+    const tid = id();
+    const failing = vi.fn().mockRejectedValue(new Error('LLM timeout'));
+    const healthy = vi.fn().mockResolvedValue(undefined);
+
+    // First turn throws
+    scheduleLLMTurn(tid, failing, true);
+    await vi.advanceTimersByTimeAsync(0);
+    await vi.runAllTimersAsync();
+
+    // Lock should be released — a subsequent turn should fire
+    scheduleLLMTurn(tid, healthy);
+    await vi.advanceTimersByTimeAsync(500);
+    expect(healthy).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/tests/unit/goalRegister.test.ts b/tests/unit/goalRegister.test.ts
new file mode 100644
index 0000000..4a02c48
--- /dev/null
+++ b/tests/unit/goalRegister.test.ts
@@ -0,0 +1,191 @@
+import { vi, describe, it, expect, beforeEach } from 'vitest';
+
+const { mockSessionUpdate } = vi.hoisted(() => ({
+  mockSessionUpdate: vi.fn(),
+}));
+
+vi.mock('../../src/session/sessionManager.js', () => ({
+  sessionManager: { update: mockSessionUpdate },
+}));
+
+import { dispatchTool } from '../../src/harness/toolDispatcher.js';
+import { mockSession } from '../fixtures/spec.js';
+
+function makeThread() {
+  return {
+    send: vi.fn().mockResolvedValue({ id: 'msg-1' }),
+  };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe('dispatchTool — goal_register', () => {
+  it('registers a primary goal successfully with dynamic_ prefix', async () => {
+    const thread = makeThread();
+    const result = await dispatchTool(
+      {
+        tool: 'goal_register',
+        args: {
+          id: 'bribe_and_recruit',
+          label: 'Players bribe and recruit the NPC.',
+          isPrimary: 'true',
+          reason: 'Players bypassed standard options by offering bribes.',
+        },
+      },
+      { session: mockSession, thread: thread as any },
+    );
+
+    expect(result.systemMessage).toContain('New hidden goal registered on the fly: "dynamic_bribe_and_recruit" (Primary: true)');
+    expect(mockSessionUpdate).toHaveBeenCalledWith(
+      mockSession.threadId,
+      expect.objectContaining({
+        spec: expect.objectContaining({
+          goals: expect.objectContaining({
+            primary: expect.arrayContaining([
+              expect.objectContaining({ id: 'dynamic_bribe_and_recruit', label: 'Players bribe and recruit the NPC.' }),
+            ]),
+          }),
+        }),
+      }),
+    );
+  });
+
+  it('registers a secondary goal successfully with dynamic_ prefix', async () => {
+    const thread = makeThread();
+    const result = await dispatchTool(
+      {
+        tool: 'goal_register',
+        args: {
+          id: 'escape_via_sewers',
+          label: 'Players escape via sewers.',
+          isPrimary: 'false',
+          reason: 'Alternative route chosen.',
+        },
+      },
+      { session: mockSession, thread: thread as any },
+    );
+
+    expect(result.systemMessage).toContain('New hidden goal registered on the fly: "dynamic_escape_via_sewers" (Primary: false)');
+    expect(mockSessionUpdate).toHaveBeenCalledWith(
+      mockSession.threadId,
+      expect.objectContaining({
+        spec: expect.objectContaining({
+          goals: expect.objectContaining({
+            secondary: expect.arrayContaining([
+              expect.objectContaining({ id: 'dynamic_escape_via_sewers', label: 'Players escape via sewers.' }),
+            ]),
+          }),
+        }),
+      }),
+    );
+  });
+
+  it('rejects invalid goal ID formats', async () => {
+    const thread = makeThread();
+    const result = await dispatchTool(
+      {
+        tool: 'goal_register',
+        args: {
+          id: 'Bribe NPC!',
+          label: 'Invalid ID test.',
+          isPrimary: 'true',
+          reason: 'Contains spaces and punctuation.',
+        },
+      },
+      { session: mockSession, thread: thread as any },
+    );
+
+    expect(result.systemMessage).toContain('[TOOL ERROR] Invalid goal ID format: "Bribe NPC!"');
+    expect(mockSessionUpdate).not.toHaveBeenCalled();
+  });
+
+  it('rejects duplicate goal IDs', async () => {
+    const thread = makeThread();
+    const sessionWithDynamic = {
+      ...mockSession,
+      spec: {
+        ...mockSession.spec,
+        goals: {
+          ...mockSession.spec.goals,
+          primary: [
+            ...mockSession.spec.goals.primary,
+            { id: 'dynamic_bribe_and_recruit', label: 'Bribe and recruit' }
+          ]
+        }
+      }
+    };
+    const result = await dispatchTool(
+      {
+        tool: 'goal_register',
+        args: {
+          id: 'bribe_and_recruit', // will be prefixed to dynamic_bribe_and_recruit
+          label: 'Duplicate bribe.',
+          isPrimary: 'true',
+          reason: 'Duplicate check.',
+        },
+      },
+      { session: sessionWithDynamic, thread: thread as any },
+    );
+
+    expect(result.systemMessage).toContain('[TOOL ERROR] A goal with ID "dynamic_bribe_and_recruit" already exists');
+    expect(mockSessionUpdate).not.toHaveBeenCalled();
+  });
+
+  it('rejects if the encounter has gone on for too long (history > 20 messages)', async () => {
+    const thread = makeThread();
+    const longSession = {
+      ...mockSession,
+      history: Array(21).fill({ role: 'user', content: 'hello', timestamp: Date.now() }),
+    };
+    const result = await dispatchTool(
+      {
+        tool: 'goal_register',
+        args: {
+          id: 'too_long_goal',
+          label: 'Too long.',
+          isPrimary: 'true',
+          reason: 'Too many messages.',
+        },
+      },
+      { session: longSession, thread: thread as any },
+    );
+
+    expect(result.systemMessage).toContain('[TOOL ERROR] The encounter has gone on for too long');
+    expect(mockSessionUpdate).not.toHaveBeenCalled();
+  });
+
+  it('rejects if maximum limit of 2 dynamic goals is reached', async () => {
+    const thread = makeThread();
+    const sessionWithTwoDynamics = {
+      ...mockSession,
+      spec: {
+        ...mockSession.spec,
+        goals: {
+          ...mockSession.spec.goals,
+          primary: [
+            ...mockSession.spec.goals.primary,
+            { id: 'dynamic_goal1', label: 'Goal 1' },
+            { id: 'dynamic_goal2', label: 'Goal 2' },
+          ]
+        }
+      }
+    };
+    const result = await dispatchTool(
+      {
+        tool: 'goal_register',
+        args: {
+          id: 'dynamic_goal3',
+          label: 'Goal 3.',
+          isPrimary: 'true',
+          reason: 'Over limit.',
+        },
+      },
+      { session: sessionWithTwoDynamics, thread: thread as any },
+    );
+
+    expect(result.systemMessage).toContain('[TOOL ERROR] Maximum limit of 2 dynamic goals reached');
+    expect(mockSessionUpdate).not.toHaveBeenCalled();
+  });
+});
diff --git a/tests/unit/graphmcpClient.test.ts b/tests/unit/graphmcpClient.test.ts
new file mode 100644
index 0000000..bfe08d8
--- /dev/null
+++ b/tests/unit/graphmcpClient.test.ts
@@ -0,0 +1,95 @@
+import { vi, describe, it, expect } from 'vitest';
+
+vi.mock('../../src/config.js', () => ({
+  config: {
+    GRAPHMCP_URL: 'http://localhost:9000',
+    GRAPHMCP_SCORE_THRESHOLD: 0.68,
+  },
+}));
+
+import { formatNPCMemory } from '../../src/graphmcp/client.js';
+import type { NPCQueryResult } from '../../src/graphmcp/client.js';
+
+const emptyResult: NPCQueryResult = {
+  npc: 'Miriam',
+  tier: 'local',
+  horizon_count: 0,
+  chunks: [],
+  graph_context: [],
+};
+
+describe('formatNPCMemory', () => {
+  it('returns first-meeting text for null input', () => {
+    expect(formatNPCMemory(null)).toBe('No prior encounters on record — first meeting.');
+  });
+
+  it('returns first-meeting text for empty result', () => {
+    expect(formatNPCMemory(emptyResult)).toBe('No prior encounters on record — first meeting.');
+  });
+
+  it('formats graph_context encounters with date and title', () => {
+    const result: NPCQueryResult = {
+      ...emptyResult,
+      horizon_count: 1,
+      graph_context: [{
+        enc_id: 'e1',
+        enc_title: 'Market Thief',
+        enc_type: 'encounter',
+        enc_timestamp: '2026-05-24T00:00:00Z',
+        enc_summary: 'A thief stole an apple.',
+        featured_entities: [],
+        locations: [],
+      }],
+    };
+    const output = formatNPCMemory(result);
+    expect(output).toContain('Market Thief');
+    expect(output).toContain('A thief stole an apple.');
+    expect(output).toContain('2026-05-24');
+  });
+
+  it('includes chunks above the score threshold', () => {
+    const result: NPCQueryResult = {
+      ...emptyResult,
+      horizon_count: 1,
+      chunks: [{ text: 'Relevant lore about Miriam.', score: 0.85, source: 'lore', author: '', timestamp: '' }],
+    };
+    const output = formatNPCMemory(result);
+    expect(output).toContain('Relevant lore about Miriam.');
+  });
+
+  it('excludes chunks below the score threshold', () => {
+    const result: NPCQueryResult = {
+      ...emptyResult,
+      horizon_count: 1,
+      chunks: [{ text: 'Low-confidence chunk.', score: 0.5, source: 'lore', author: '', timestamp: '' }],
+    };
+    const output = formatNPCMemory(result);
+    expect(output).not.toContain('Low-confidence chunk.');
+  });
+
+  it('truncates chunks longer than 200 characters', () => {
+    const longText = 'A'.repeat(300);
+    const result: NPCQueryResult = {
+      ...emptyResult,
+      horizon_count: 1,
+      chunks: [{ text: longText, score: 0.9, source: 'lore', author: '', timestamp: '' }],
+    };
+    const output = formatNPCMemory(result);
+    expect(output).toContain('…');
+    expect(output).not.toContain('A'.repeat(300));
+  });
+
+  it('includes at most 3 chunks', () => {
+    const chunks = Array.from({ length: 5 }, (_, i) => ({
+      text: `Chunk ${i} content here.`,
+      score: 0.9,
+      source: 'lore' as const,
+      author: '',
+      timestamp: '',
+    }));
+    const result: NPCQueryResult = { ...emptyResult, horizon_count: 5, chunks };
+    const output = formatNPCMemory(result);
+    const matchCount = (output.match(/Chunk \d content here\./g) ?? []).length;
+    expect(matchCount).toBeLessThanOrEqual(3);
+  });
+});
diff --git a/tests/unit/loreAnswerEmbed.test.ts b/tests/unit/loreAnswerEmbed.test.ts
new file mode 100644
index 0000000..bdfee22
--- /dev/null
+++ b/tests/unit/loreAnswerEmbed.test.ts
@@ -0,0 +1,82 @@
+import { describe, it, expect } from 'vitest';
+import { buildLoreAnswerEmbed, LORE_COLOR } from '../../src/bot/embeds/loreAnswer.js';
+
+describe('buildLoreAnswerEmbed', () => {
+  it('uses green color when sourceCount > 0', () => {
+    const data = buildLoreAnswerEmbed('Answer', 'sources', null, undefined, 3).toJSON();
+    expect(data.color).toBe(LORE_COLOR.FOUND);
+  });
+
+  it('uses gray color when sourceCount is 0', () => {
+    const data = buildLoreAnswerEmbed('Answer', null, null, undefined, 0).toJSON();
+    expect(data.color).toBe(LORE_COLOR.NONE);
+  });
+
+  it('sets description to the answer text', () => {
+    const data = buildLoreAnswerEmbed('Gromm leads the Urkin.', null, null, undefined, 0).toJSON();
+    expect(data.description).toBe('Gromm leads the Urkin.');
+  });
+
+  it('truncates answers longer than 4000 chars', () => {
+    const long = 'A'.repeat(4100);
+    const data = buildLoreAnswerEmbed(long, null, null, undefined, 0).toJSON();
+    expect(data.description!.length).toBeLessThanOrEqual(4000);
+    expect(data.description).toContain('…');
+  });
+
+  it('adds a Sources field when sourcesText is provided', () => {
+    const data = buildLoreAnswerEmbed('Answer', '📚 Some lore chunk', null, undefined, 1).toJSON();
+    expect(data.fields).toContainEqual(expect.objectContaining({ name: 'Sources' }));
+  });
+
+  it('omits the Sources field when sourcesText is null', () => {
+    const data = buildLoreAnswerEmbed('Answer', null, null, undefined, 0).toJSON();
+    const names = (data.fields ?? []).map((f: { name: string }) => f.name);
+    expect(names).not.toContain('Sources');
+  });
+
+  it("adds player history field when both playerHistory and playerName are set", () => {
+    const data = buildLoreAnswerEmbed('Answer', null, '⚔️ [2024] The Vault', 'Aelindra', 1).toJSON();
+    expect(data.fields).toContainEqual(expect.objectContaining({ name: "Aelindra's history" }));
+  });
+
+  it('omits player history field when playerName is undefined', () => {
+    const data = buildLoreAnswerEmbed('Answer', null, '⚔️ [2024] The Vault', undefined, 1).toJSON();
+    const names = (data.fields ?? []).map((f: { name: string }) => f.name);
+    expect(names).not.toContain(expect.stringContaining('history'));
+  });
+
+  it('adds active encounter field when threadId is provided', () => {
+    const data = buildLoreAnswerEmbed('Answer', null, null, undefined, 0, 'thread-abc').toJSON();
+    const field = (data.fields ?? []).find((f: { name: string }) => f.name === 'Active encounter');
+    expect(field).toBeDefined();
+    expect(field!.value).toContain('thread-abc');
+  });
+
+  it('omits active encounter field when threadId is absent', () => {
+    const data = buildLoreAnswerEmbed('Answer', null, null, undefined, 0).toJSON();
+    const names = (data.fields ?? []).map((f: { name: string }) => f.name);
+    expect(names).not.toContain('Active encounter');
+  });
+
+  it('footer says N records when sourceCount > 0', () => {
+    const data = buildLoreAnswerEmbed('Answer', 'src', null, undefined, 4).toJSON();
+    expect(data.footer?.text).toContain('4 records');
+  });
+
+  it('footer says 1 record (singular) when sourceCount is 1', () => {
+    const data = buildLoreAnswerEmbed('Answer', 'src', null, undefined, 1).toJSON();
+    expect(data.footer?.text).toContain('1 record');
+    expect(data.footer?.text).not.toContain('1 records');
+  });
+
+  it('footer says no records found when sourceCount is 0', () => {
+    const data = buildLoreAnswerEmbed('Answer', null, null, undefined, 0).toJSON();
+    expect(data.footer?.text).toContain('No records found');
+  });
+
+  it('title is always Chronicle Records', () => {
+    const data = buildLoreAnswerEmbed('Answer', null, null, undefined, 0).toJSON();
+    expect(data.title).toContain('Chronicle Records');
+  });
+});
diff --git a/tests/unit/playerRegistry.test.ts b/tests/unit/playerRegistry.test.ts
new file mode 100644
index 0000000..1b36328
--- /dev/null
+++ b/tests/unit/playerRegistry.test.ts
@@ -0,0 +1,51 @@
+import { vi, describe, it, expect, beforeEach } from 'vitest';
+
+const refs = vi.hoisted(() => ({ mockRedis: null as any }));
+
+vi.mock('../../src/db/redis.js', async () => {
+  const { default: RedisMock } = await import('ioredis-mock');
+  refs.mockRedis = new RedisMock();
+  return { redis: refs.mockRedis };
+});
+vi.mock('../../src/config.js', () => ({
+  config: { REDIS_URL: 'redis://localhost:6379' },
+}));
+
+import { playerRegistry } from '../../src/session/playerRegistry.js';
+
+beforeEach(async () => {
+  await refs.mockRedis?.flushall();
+});
+
+describe('playerRegistry', () => {
+  it('set then get returns the player', async () => {
+    await playerRegistry.set('guild-1', 'user-1', 'Aelindra');
+    const player = await playerRegistry.get('guild-1', 'user-1');
+    expect(player).toEqual({ discordId: 'user-1', dndName: 'Aelindra' });
+  });
+
+  it('get on unknown user returns null', async () => {
+    const player = await playerRegistry.get('guild-1', 'unknown-user');
+    expect(player).toBeNull();
+  });
+
+  it('set overwrites an existing name', async () => {
+    await playerRegistry.set('guild-1', 'user-1', 'Aelindra');
+    await playerRegistry.set('guild-1', 'user-1', 'Thornwick');
+    const player = await playerRegistry.get('guild-1', 'user-1');
+    expect(player?.dndName).toBe('Thornwick');
+  });
+
+  it('delete removes the entry', async () => {
+    await playerRegistry.set('guild-1', 'user-1', 'Aelindra');
+    await playerRegistry.delete('guild-1', 'user-1');
+    const player = await playerRegistry.get('guild-1', 'user-1');
+    expect(player).toBeNull();
+  });
+
+  it('registries are scoped by guildId', async () => {
+    await playerRegistry.set('guild-A', 'user-1', 'Aelindra');
+    const inOtherGuild = await playerRegistry.get('guild-B', 'user-1');
+    expect(inOtherGuild).toBeNull();
+  });
+});
diff --git a/tests/unit/promptBuilder.test.ts b/tests/unit/promptBuilder.test.ts
new file mode 100644
index 0000000..bee2fd3
--- /dev/null
+++ b/tests/unit/promptBuilder.test.ts
@@ -0,0 +1,201 @@
+import { describe, it, expect } from 'vitest';
+import { buildSystemPrompt, buildOpeningNarrative } from '../../src/harness/promptBuilder.js';
+import { mockSpec } from '../fixtures/spec.js';
+
+describe('buildSystemPrompt', () => {
+  it('contains the narrator identity block', () => {
+    const prompt = buildSystemPrompt(mockSpec);
+    expect(prompt).toContain('<narrator_identity>');
+    expect(prompt).toContain('Dungeon Master narrator');
+  });
+
+  it('contains the sportsmanship block with all rules', () => {
+    const prompt = buildSystemPrompt(mockSpec);
+    expect(prompt).toContain('<sportsmanship>');
+    expect(prompt).toContain('No instant kills on non-threatening NPCs');
+    expect(prompt).toContain('No controlling another player character.');
+  });
+
+  it('contains all NPC ids in the npcs block', () => {
+    const prompt = buildSystemPrompt(mockSpec);
+    expect(prompt).toContain('id="npc-one"');
+    expect(prompt).toContain('id="npc-two"');
+    expect(prompt).toContain('Miriam');
+    expect(prompt).toContain('Dal');
+  });
+
+  it('injects NPC memory when provided', () => {
+    const npcMemories = { 'npc-one': 'Witnessed: Tavern Brawl (2026-01-01): A fight broke out.' };
+    const prompt = buildSystemPrompt(mockSpec, npcMemories);
+    expect(prompt).toContain('Tavern Brawl');
+    expect(prompt).toContain('Memory from prior encounters');
+  });
+
+  it('shows first-meeting text when no memory is provided', () => {
+    const prompt = buildSystemPrompt(mockSpec, {});
+    expect(prompt).toContain('first encounter with this NPC');
+  });
+
+  it('contains all primary goal ids in the hidden_goals block', () => {
+    const prompt = buildSystemPrompt(mockSpec);
+    expect(prompt).toContain('[PRIMARY]');
+    expect(prompt).toContain('catch');
+    expect(prompt).toContain('negotiate');
+  });
+
+  it('contains secondary goals', () => {
+    const prompt = buildSystemPrompt(mockSpec);
+    expect(prompt).toContain('[SECONDARY]');
+    expect(prompt).toContain('escape');
+  });
+
+  it('contains the tool contract with only the two allowed tools', () => {
+    const prompt = buildSystemPrompt(mockSpec);
+    expect(prompt).toContain('skill_check_emit');
+    expect(prompt).toContain('encounter_resolve');
+    // Tools removed from LLM surface should not appear
+    expect(prompt).not.toContain('npc_memory_write');
+    expect(prompt).not.toContain('event_log_append');
+  });
+
+  it('lists all valid outcomeId values explicitly in the tool contract', () => {
+    const prompt = buildSystemPrompt(mockSpec);
+    expect(prompt).toContain('"catch"');
+    expect(prompt).toContain('"negotiate"');
+    expect(prompt).toContain('"escape"');
+  });
+
+  it('injects the encounterId as the sessionId placeholder', () => {
+    const prompt = buildSystemPrompt(mockSpec);
+    expect(prompt).toContain('sessionId: "test-encounter-001"');
+  });
+
+  it('contains the setting block', () => {
+    const prompt = buildSystemPrompt(mockSpec);
+    expect(prompt).toContain('Test Town Square');
+    expect(prompt).toContain('Tense');
+  });
+});
+
+describe('buildOpeningNarrative', () => {
+  it('returns trimmed opening narrative text', () => {
+    const result = buildOpeningNarrative(mockSpec);
+    expect(result).toBe('The scene opens in Test Town.');
+  });
+});
+
+describe('buildSystemPrompt — skill_checks block', () => {
+  it('includes the skill_checks section when DCs are present', () => {
+    const prompt = buildSystemPrompt(mockSpec);
+    expect(prompt).toContain('<skill_checks>');
+    expect(prompt).toContain('DC 13');
+    expect(prompt).toContain('DC 10');
+  });
+
+  it('includes the chase skill check by name', () => {
+    const prompt = buildSystemPrompt(mockSpec);
+    expect(prompt).toContain('chase');
+  });
+
+  it('includes the emit-immediately instruction', () => {
+    const prompt = buildSystemPrompt(mockSpec);
+    expect(prompt).toContain('emit a skill_check_emit tool call IMMEDIATELY');
+  });
+
+  it('omits the skill_checks block when skillChecks is empty', () => {
+    const specNoChecks = { ...mockSpec, skillChecks: {} };
+    const prompt = buildSystemPrompt(specNoChecks);
+    expect(prompt).not.toContain('<skill_checks>');
+  });
+
+  it('ignores skillCheck keys that do not match the _dc/_skill/_note pattern', () => {
+    const specOdd = { ...mockSpec, skillChecks: { unrelated: 'foo', chase_dc: 13 } };
+    const prompt = buildSystemPrompt(specOdd);
+    expect(prompt).toContain('DC 13');
+    expect(prompt).not.toContain('unrelated');
+  });
+});
+
+describe('buildSystemPrompt — players block', () => {
+  it('includes <players> block when players have pronouns', () => {
+    const players = {
+      'u1': { discordId: 'u1', dndName: 'Vex', pronouns: 'she/her' },
+      'u2': { discordId: 'u2', dndName: 'Thorin', pronouns: 'he/him' },
+    };
+    const prompt = buildSystemPrompt(mockSpec, {}, {}, players);
+    expect(prompt).toContain('<players>');
+    expect(prompt).toContain('Vex (she/her)');
+    expect(prompt).toContain('Thorin (he/him)');
+  });
+
+  it('lists players without pronouns without a parenthetical', () => {
+    const players = { 'u1': { discordId: 'u1', dndName: 'Aelindra' } };
+    const prompt = buildSystemPrompt(mockSpec, {}, {}, players);
+    expect(prompt).toContain('Aelindra');
+    expect(prompt).not.toMatch(/Aelindra\s*\(/);
+  });
+
+  it('omits <players> block when players object is empty', () => {
+    const prompt = buildSystemPrompt(mockSpec, {}, {}, {});
+    expect(prompt).not.toContain('<players>');
+  });
+
+  it('omits <players> block when players param is omitted', () => {
+    const prompt = buildSystemPrompt(mockSpec);
+    expect(prompt).not.toContain('<players>');
+  });
+});
+
+describe('buildSystemPrompt — tone block', () => {
+  it('includes <tone> block when spec has a tone value', () => {
+    const specWithTone = { ...mockSpec, tone: 'tense' };
+    const prompt = buildSystemPrompt(specWithTone);
+    expect(prompt).toContain('<tone>');
+    expect(prompt).toContain('</tone>');
+  });
+
+  it('includes the exact tone instruction text', () => {
+    const specWithTone = { ...mockSpec, tone: 'grim' };
+    const prompt = buildSystemPrompt(specWithTone);
+    expect(prompt).toContain('Your narration style for this encounter is: grim.');
+    expect(prompt).toContain('Let this flavor all of your responses');
+  });
+
+  it('<tone> block appears before <sportsmanship>', () => {
+    const specWithTone = { ...mockSpec, tone: 'comedic' };
+    const prompt = buildSystemPrompt(specWithTone);
+    const toneIdx = prompt.indexOf('<tone>');
+    const sportsIdx = prompt.indexOf('<sportsmanship>');
+    expect(toneIdx).toBeGreaterThan(-1);
+    expect(toneIdx).toBeLessThan(sportsIdx);
+  });
+
+  it('does NOT include <tone> block when tone is undefined', () => {
+    const prompt = buildSystemPrompt(mockSpec); // mockSpec has no tone
+    expect(prompt).not.toContain('<tone>');
+  });
+
+  it('does NOT include <tone> block when tone is empty string', () => {
+    const specEmptyTone = { ...mockSpec, tone: '' };
+    const prompt = buildSystemPrompt(specEmptyTone);
+    expect(prompt).not.toContain('<tone>');
+  });
+});
+
+describe('buildSystemPrompt — tool_contract negative instruction', () => {
+  it('contains the NEVER-end-without-emit negative instruction', () => {
+    const prompt = buildSystemPrompt(mockSpec);
+    expect(prompt).toContain('NEVER end your response with a request for the player to roll without emitting skill_check_emit');
+  });
+
+  it('contains a few-shot example section', () => {
+    const prompt = buildSystemPrompt(mockSpec);
+    expect(prompt).toContain('CORRECT skill check flow');
+  });
+
+  it('few-shot example demonstrates emitting skill_check_emit after player action', () => {
+    const prompt = buildSystemPrompt(mockSpec);
+    expect(prompt).toContain('WRONG');
+    expect(prompt).toContain('FORBIDDEN');
+  });
+});
diff --git a/tests/unit/queueCap.test.ts b/tests/unit/queueCap.test.ts
new file mode 100644
index 0000000..54729a9
--- /dev/null
+++ b/tests/unit/queueCap.test.ts
@@ -0,0 +1,79 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  isBurstCapped,
+  incrementBurst,
+  resetBurst,
+  getDropNotice,
+} from '../../src/bot/handlers/queueCap.js';
+
+describe('burst counter', () => {
+  beforeEach(() => {
+    resetBurst('t1');
+    resetBurst('t2');
+  });
+
+  it('new thread is not capped', () => {
+    expect(isBurstCapped('t1')).toBe(false);
+  });
+
+  it('one increment is not capped', () => {
+    incrementBurst('t1');
+    expect(isBurstCapped('t1')).toBe(false);
+  });
+
+  it('two increments IS capped (cap = 2 means 3rd message is dropped)', () => {
+    incrementBurst('t1');
+    incrementBurst('t1');
+    expect(isBurstCapped('t1')).toBe(true);
+  });
+
+  it('resetBurst clears the counter', () => {
+    incrementBurst('t1');
+    incrementBurst('t1');
+    incrementBurst('t1');
+    resetBurst('t1');
+    expect(isBurstCapped('t1')).toBe(false);
+  });
+
+  it('threads are isolated', () => {
+    incrementBurst('t1');
+    incrementBurst('t1');
+    incrementBurst('t1');
+    expect(isBurstCapped('t2')).toBe(false);
+  });
+});
+
+describe('getDropNotice', () => {
+  it('returns grim notice for "grim"', () => {
+    const text = getDropNotice('grim');
+    expect(text).toContain('chaos swallowed your words');
+  });
+
+  it('returns comedic notice for "comedic"', () => {
+    expect(getDropNotice('comedic')).toContain('universe, frankly, wasn\'t listening');
+  });
+
+  it('returns mysterious notice for "mysterious"', () => {
+    expect(getDropNotice('mysterious')).toContain('muffled your voice');
+  });
+
+  it('returns tense notice for "tense"', () => {
+    expect(getDropNotice('tense')).toContain('moment moved on without you');
+  });
+
+  it('returns baseline for undefined tone', () => {
+    expect(getDropNotice(undefined)).toContain('echoes of the encounter');
+  });
+
+  it('returns baseline for unknown tone', () => {
+    expect(getDropNotice('heroic')).toContain('echoes of the encounter');
+  });
+
+  it('all notices are wrapped in italics', () => {
+    for (const tone of ['grim', 'comedic', 'mysterious', 'tense', undefined]) {
+      const text = getDropNotice(tone);
+      expect(text.startsWith('*')).toBe(true);
+      expect(text.endsWith('*')).toBe(true);
+    }
+  });
+});
diff --git a/tests/unit/reactionManager.test.ts b/tests/unit/reactionManager.test.ts
new file mode 100644
index 0000000..c5fef46
--- /dev/null
+++ b/tests/unit/reactionManager.test.ts
@@ -0,0 +1,177 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  isDiceRelated,
+  registerScheduled,
+  drainPending,
+  clearPending,
+  upgradeToProcessing,
+  upgradeToComplete,
+  cleanupReactions,
+  type PendingEntry,
+} from '../../src/bot/handlers/reactionManager.js';
+import type { Message } from 'discord.js';
+
+// ---------------------------------------------------------------------------
+// Mock factory — minimal Discord Message
+// ---------------------------------------------------------------------------
+
+function makeMockMsg(content = 'test message'): Message & {
+  reactMock: ReturnType<typeof vi.fn>;
+  removeMock: ReturnType<typeof vi.fn>;
+} {
+  const reactMock = vi.fn().mockResolvedValue({});
+  const removeMock = vi.fn().mockResolvedValue({});
+
+  const msg = {
+    content,
+    client: { user: { id: 'bot-123' } },
+    react: reactMock,
+    reactions: {
+      cache: {
+        find: vi.fn().mockReturnValue({ users: { remove: removeMock } }),
+      },
+    },
+    reactMock,
+    removeMock,
+  } as unknown as Message & {
+    reactMock: ReturnType<typeof vi.fn>;
+    removeMock: ReturnType<typeof vi.fn>;
+  };
+
+  return msg;
+}
+
+// ---------------------------------------------------------------------------
+// isDiceRelated
+// ---------------------------------------------------------------------------
+
+describe('isDiceRelated', () => {
+  it('detects "roll"', () => expect(isDiceRelated('I roll Dexterity')).toBe(true));
+  it('detects "attack"', () => expect(isDiceRelated('I attack the guard')).toBe(true));
+  it('detects "check"', () => expect(isDiceRelated('Perception check to spot them')).toBe(true));
+  it('detects "save"', () => expect(isDiceRelated('make a Dexterity save')).toBe(true));
+  it('detects "saving throw"', () => expect(isDiceRelated('she makes a saving throw')).toBe(true));
+  it('detects "d20"', () => expect(isDiceRelated('I want to d20 this')).toBe(true));
+  it('is case-insensitive', () => expect(isDiceRelated('ROLL FOR PERSUASION')).toBe(true));
+  it('returns false for normal messages', () => expect(isDiceRelated('I talk to Miriam')).toBe(false));
+  it('returns false for empty string', () => expect(isDiceRelated('')).toBe(false));
+  it('returns false for NPC dialogue', () => expect(isDiceRelated('"Fortune favors the brave," she said.')).toBe(false));
+});
+
+// ---------------------------------------------------------------------------
+// pending map: registerScheduled / drainPending / clearPending
+// ---------------------------------------------------------------------------
+
+describe('pending map', () => {
+  beforeEach(() => {
+    // Drain any leftovers from previous tests
+    drainPending('t1');
+    drainPending('t2');
+  });
+
+  it('registerScheduled stores the message', () => {
+    const msg = makeMockMsg();
+    registerScheduled('t1', msg as unknown as Message);
+    const drained = drainPending('t1');
+    expect(drained).toHaveLength(1);
+    expect(drained[0].msg).toBe(msg);
+    expect(drained[0].content).toBe('test message');
+  });
+
+  it('drainPending returns all entries and clears the thread', () => {
+    const a = makeMockMsg('a');
+    const b = makeMockMsg('b');
+    registerScheduled('t1', a as unknown as Message);
+    registerScheduled('t1', b as unknown as Message);
+    const drained = drainPending('t1');
+    expect(drained).toHaveLength(2);
+    expect(drainPending('t1')).toHaveLength(0);
+  });
+
+  it('drainPending returns empty array when nothing registered', () => {
+    expect(drainPending('no-such-thread')).toHaveLength(0);
+  });
+
+  it('clearPending removes entries without returning them', () => {
+    const msg = makeMockMsg();
+    registerScheduled('t2', msg as unknown as Message);
+    clearPending('t2');
+    expect(drainPending('t2')).toHaveLength(0);
+  });
+
+  it('threads are isolated — draining t1 does not affect t2', () => {
+    registerScheduled('t1', makeMockMsg('x') as unknown as Message);
+    registerScheduled('t2', makeMockMsg('y') as unknown as Message);
+    drainPending('t1');
+    expect(drainPending('t2')).toHaveLength(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// upgradeToProcessing
+// ---------------------------------------------------------------------------
+
+describe('upgradeToProcessing', () => {
+  it('removes 👀 and adds ⏳ for each entry', () => {
+    const msg = makeMockMsg('I wander around');
+    const entries: PendingEntry[] = [{ msg: msg as unknown as Message, content: msg.content }];
+    upgradeToProcessing(entries);
+    expect(msg.reactMock).toHaveBeenCalledWith('⏳');
+    expect(msg.removeMock).toHaveBeenCalled();
+  });
+
+  it('adds 🎲 when content contains roll keyword', () => {
+    const msg = makeMockMsg('I roll Dexterity');
+    const entries: PendingEntry[] = [{ msg: msg as unknown as Message, content: msg.content }];
+    upgradeToProcessing(entries);
+    expect(msg.reactMock).toHaveBeenCalledWith('⏳');
+    expect(msg.reactMock).toHaveBeenCalledWith('🎲');
+  });
+
+  it('does not add 🎲 for non-dice messages', () => {
+    const msg = makeMockMsg('I talk to the innkeeper');
+    const entries: PendingEntry[] = [{ msg: msg as unknown as Message, content: msg.content }];
+    upgradeToProcessing(entries);
+    expect(msg.reactMock).toHaveBeenCalledWith('⏳');
+    expect(msg.reactMock).not.toHaveBeenCalledWith('🎲');
+  });
+
+  it('is a no-op for empty entries array', () => {
+    expect(() => upgradeToProcessing([])).not.toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// upgradeToComplete
+// ---------------------------------------------------------------------------
+
+describe('upgradeToComplete', () => {
+  it('removes ⏳ and 🎲 and adds ✅', () => {
+    const msg = makeMockMsg();
+    const entries: PendingEntry[] = [{ msg: msg as unknown as Message, content: msg.content }];
+    upgradeToComplete(entries);
+    expect(msg.reactMock).toHaveBeenCalledWith('✅');
+    expect(msg.removeMock).toHaveBeenCalledTimes(2); // ⏳ and 🎲 remove attempts
+  });
+
+  it('is a no-op for empty entries array', () => {
+    expect(() => upgradeToComplete([])).not.toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// cleanupReactions
+// ---------------------------------------------------------------------------
+
+describe('cleanupReactions', () => {
+  it('attempts to remove 👀, ⏳, and 🎲', () => {
+    const msg = makeMockMsg();
+    const entries: PendingEntry[] = [{ msg: msg as unknown as Message, content: msg.content }];
+    cleanupReactions(entries);
+    expect(msg.removeMock).toHaveBeenCalledTimes(3);
+  });
+
+  it('is a no-op for empty entries array', () => {
+    expect(() => cleanupReactions([])).not.toThrow();
+  });
+});
diff --git a/tests/unit/responseFilter.test.ts b/tests/unit/responseFilter.test.ts
new file mode 100644
index 0000000..fa55f35
--- /dev/null
+++ b/tests/unit/responseFilter.test.ts
@@ -0,0 +1,129 @@
+import { describe, it, expect } from 'vitest';
+import { filterLLMResponse, detectMissedSkillCheck } from '../../src/bot/handlers/responseFilter.js';
+
+describe('filterLLMResponse', () => {
+  describe('passes clean narrative', () => {
+    it('accepts normal story text', () => {
+      expect(filterLLMResponse('The innkeeper glares at you with suspicion.').ok).toBe(true);
+    });
+    it('accepts narrative that mentions rolling without claiming a number', () => {
+      expect(filterLLMResponse('She gestures toward the locked chest. "Think you can open it?"').ok).toBe(true);
+    });
+    it('accepts success/failure words used narratively, not as roll results', () => {
+      expect(filterLLMResponse('The guard succeeded in his rounds last night, you heard.').ok).toBe(true);
+    });
+  });
+
+  describe('empty response', () => {
+    it('rejects empty string', () => {
+      const r = filterLLMResponse('');
+      expect(r.ok).toBe(false);
+      expect(r.reason).toBe('empty_response');
+    });
+    it('rejects whitespace-only', () => {
+      expect(filterLLMResponse('   \n  ').ok).toBe(false);
+    });
+  });
+
+  describe('system tag echo', () => {
+    it('catches [TOOL] prefix', () => {
+      const r = filterLLMResponse('[TOOL] Skill check embed posted for Zara (DC 14).');
+      expect(r.ok).toBe(false);
+      expect(r.reason).toBe('echoed_system_tag');
+    });
+    it('catches [SKILL CHECK RESULT]', () => {
+      expect(filterLLMResponse('[SKILL CHECK RESULT] Zara rolled 18 vs DC 14.').ok).toBe(false);
+    });
+    it('catches [SESSION] tag', () => {
+      expect(filterLLMResponse('[SESSION] Zara has entered the encounter.').ok).toBe(false);
+    });
+    it('catches [/roll COMMAND]', () => {
+      expect(filterLLMResponse('[/roll COMMAND — MANDATORY TOOL CALL] …').ok).toBe(false);
+    });
+  });
+
+  describe('fabricated roll result', () => {
+    it('catches "you rolled a 15"', () => {
+      const r = filterLLMResponse('You rolled a 15 on your Perception check — you succeed.');
+      expect(r.ok).toBe(false);
+      expect(r.reason).toBe('fabricated_roll_result');
+    });
+    it('catches "the die shows"', () => {
+      expect(filterLLMResponse('The die shows a natural 20!').ok).toBe(false);
+    });
+    it('catches "the dice showed"', () => {
+      expect(filterLLMResponse('The dice showed 7, not enough to beat the DC.').ok).toBe(false);
+    });
+    it('catches third-person roll claims — "the brawler rolled a 12"', () => {
+      expect(filterLLMResponse('The tavern brawler rolled a 12 for initiative.').ok).toBe(false);
+    });
+    it('catches "rolls a 7" without a subject', () => {
+      expect(filterLLMResponse('Fate rolls a 7 — barely enough.').ok).toBe(false);
+    });
+    it('is case-insensitive', () => {
+      expect(filterLLMResponse('YOU ROLLED A 19 ON THE CHECK.').ok).toBe(false);
+    });
+    it('does not catch "rolls" used generically without a number', () => {
+      expect(filterLLMResponse('She rolls her eyes at your excuse.').ok).toBe(true);
+    });
+    it('does not catch "rolled" without a following number', () => {
+      expect(filterLLMResponse('The barrel rolled off the cart and into the mud.').ok).toBe(true);
+    });
+  });
+
+  describe('detectMissedSkillCheck', () => {
+    it('detects "you need to roll"', () => {
+      expect(detectMissedSkillCheck('The lock is tough. You need to roll Dexterity to open it.')).toBe(true);
+    });
+    it('detects "you will need to make a roll"', () => {
+      expect(detectMissedSkillCheck("You'll need to make a roll to cross the gap.")).toBe(true);
+    });
+    it('detects "roll for X"', () => {
+      expect(detectMissedSkillCheck('Roll for Perception to spot the hidden figure.')).toBe(true);
+    });
+    it('detects "roll your X"', () => {
+      expect(detectMissedSkillCheck('Roll your Athletics to jump across.')).toBe(true);
+    });
+    it('detects "requires a check"', () => {
+      expect(detectMissedSkillCheck('Scaling the wall requires a Strength check, DC 15.')).toBe(true);
+    });
+    it('detects "requires a roll"', () => {
+      expect(detectMissedSkillCheck('That requires a roll from you.')).toBe(true);
+    });
+    it('detects "make a Dexterity check"', () => {
+      expect(detectMissedSkillCheck('Make a Dexterity saving throw or fall.')).toBe(true);
+    });
+    it('detects "attempt a skill check"', () => {
+      expect(detectMissedSkillCheck('You can attempt a skill check to bluff the guard.')).toBe(true);
+    });
+    it('is case-insensitive', () => {
+      expect(detectMissedSkillCheck('YOU NEED TO ROLL STRENGTH.')).toBe(true);
+    });
+    it('returns false for normal narration with no roll request', () => {
+      expect(detectMissedSkillCheck('The guard eyes you suspiciously and steps aside.')).toBe(false);
+    });
+    it('returns false for NPC dialogue about rolling metaphorically', () => {
+      expect(detectMissedSkillCheck('"Fortune rolls strangely tonight," the bard mutters.')).toBe(false);
+    });
+    it('returns false for empty string', () => {
+      expect(detectMissedSkillCheck('')).toBe(false);
+    });
+    it('returns false for mention of a past roll outcome (not a request)', () => {
+      expect(detectMissedSkillCheck('Your earlier roll barely succeeded — the lock yielded.')).toBe(false);
+    });
+  });
+
+  describe('system tag — additional variants', () => {
+    it('catches [SYSTEM] tag', () => {
+      const r = filterLLMResponse('[SYSTEM] Narrator response queued.');
+      expect(r.ok).toBe(false);
+      expect(r.reason).toBe('echoed_system_tag');
+    });
+    it('catches [TOOL ERROR] variant', () => {
+      expect(filterLLMResponse('[TOOL ERROR] skill_check_emit failed.').ok).toBe(false);
+    });
+    it('catches system tag embedded mid-sentence', () => {
+      expect(filterLLMResponse('The innkeeper nods. [SESSION] Zara entered.').ok).toBe(false);
+    });
+  });
+});
diff --git a/tests/unit/rollDetection.test.ts b/tests/unit/rollDetection.test.ts
new file mode 100644
index 0000000..d28027d
--- /dev/null
+++ b/tests/unit/rollDetection.test.ts
@@ -0,0 +1,44 @@
+import { describe, it, expect } from 'vitest';
+
+// Mirror of the regex in messageRouter — tested here in isolation
+const ROLL_RE = /i\s+rolled\s+(?:a\s+)?(\d+)\s+([\w][\w\s]*)/i;
+
+function parseRoll(input: string) {
+  const m = ROLL_RE.exec(input);
+  if (!m) return null;
+  return { roll: parseInt(m[1], 10), skill: m[2].trim() };
+}
+
+describe('roll detection regex', () => {
+  it('matches "I rolled a 17 Acrobatics"', () => {
+    expect(parseRoll('I rolled a 17 Acrobatics')).toEqual({ roll: 17, skill: 'Acrobatics' });
+  });
+
+  it('matches without article "I rolled 14 Athletics"', () => {
+    expect(parseRoll('I rolled 14 Athletics')).toEqual({ roll: 14, skill: 'Athletics' });
+  });
+
+  it('matches multi-word skill "I rolled a 12 Sleight of Hand"', () => {
+    expect(parseRoll('I rolled a 12 Sleight of Hand')).toEqual({ roll: 12, skill: 'Sleight of Hand' });
+  });
+
+  it('is case-insensitive', () => {
+    expect(parseRoll('i rolled a 20 perception')).toEqual({ roll: 20, skill: 'perception' });
+  });
+
+  it('matches when embedded in a longer message', () => {
+    expect(parseRoll('ok so I rolled a 8 Persuasion, what happens?')).not.toBeNull();
+  });
+
+  it('returns null for unrelated messages', () => {
+    expect(parseRoll('I attack the guard!')).toBeNull();
+    expect(parseRoll('What do I see?')).toBeNull();
+    expect(parseRoll('I rolled')).toBeNull();
+  });
+
+  it('parses the roll as an integer', () => {
+    const result = parseRoll('I rolled a 20 Perception');
+    expect(result?.roll).toBe(20);
+    expect(typeof result?.roll).toBe('number');
+  });
+});
diff --git a/tests/unit/rollHandler.test.ts b/tests/unit/rollHandler.test.ts
new file mode 100644
index 0000000..77a92bc
--- /dev/null
+++ b/tests/unit/rollHandler.test.ts
@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'vitest';
+import { isSkillCheckInteraction } from '../../src/bot/handlers/rollHandler.js';
+import type { ButtonInteraction, ModalSubmitInteraction } from 'discord.js';
+
+function fakeButton(customId: string): ButtonInteraction {
+  return { isButton: () => true, isModalSubmit: () => false, customId } as unknown as ButtonInteraction;
+}
+
+function fakeModal(customId: string): ModalSubmitInteraction {
+  return { isButton: () => false, isModalSubmit: () => true, customId } as unknown as ModalSubmitInteraction;
+}
+
+describe('isSkillCheckInteraction', () => {
+  it('recognises all base roll button IDs', () => {
+    expect(isSkillCheckInteraction(fakeButton('sc_roll'))).toBe(true);
+    expect(isSkillCheckInteraction(fakeButton('sc_adv'))).toBe(true);
+    expect(isSkillCheckInteraction(fakeButton('sc_dis'))).toBe(true);
+    expect(isSkillCheckInteraction(fakeButton('sc_mod'))).toBe(true);
+  });
+
+  it('recognises modifier sub-button IDs', () => {
+    expect(isSkillCheckInteraction(fakeButton('sc_roll_m:3'))).toBe(true);
+    expect(isSkillCheckInteraction(fakeButton('sc_adv_m:-2'))).toBe(true);
+    expect(isSkillCheckInteraction(fakeButton('sc_dis_m:0'))).toBe(true);
+  });
+
+  it('rejects unrelated button IDs', () => {
+    expect(isSkillCheckInteraction(fakeButton('encounter_start'))).toBe(false);
+    expect(isSkillCheckInteraction(fakeButton('player_gate'))).toBe(false);
+    expect(isSkillCheckInteraction(fakeButton(''))).toBe(false);
+  });
+
+  it('recognises the modifier modal ID', () => {
+    expect(isSkillCheckInteraction(fakeModal('sc_mod_modal'))).toBe(true);
+  });
+
+  it('rejects other modal IDs', () => {
+    expect(isSkillCheckInteraction(fakeModal('some_other_modal'))).toBe(false);
+  });
+});
diff --git a/tests/unit/sessionManager.test.ts b/tests/unit/sessionManager.test.ts
new file mode 100644
index 0000000..1503f89
--- /dev/null
+++ b/tests/unit/sessionManager.test.ts
@@ -0,0 +1,107 @@
+import { vi, describe, it, expect, beforeEach } from 'vitest';
+
+// vi.hoisted() runs before any module-level code — the only safe way to
+// share state between a vi.mock async factory and the test body.
+const refs = vi.hoisted(() => ({ mockRedis: null as any }));
+
+vi.mock('../../src/db/redis.js', async () => {
+  const { default: RedisMock } = await import('ioredis-mock');
+  refs.mockRedis = new RedisMock();
+  return { redis: refs.mockRedis };
+});
+
+vi.mock('../../src/config.js', () => ({
+  config: { SESSION_TTL_HOURS: 12, GRAPHMCP_SCORE_THRESHOLD: 0.68 },
+}));
+
+import { sessionManager } from '../../src/session/sessionManager.js';
+import { mockSession } from '../fixtures/spec.js';
+
+beforeEach(async () => {
+  await refs.mockRedis?.flushall();
+});
+
+describe('sessionManager.create + get', () => {
+  it('stores a session and retrieves it', async () => {
+    await sessionManager.create('thread-1', mockSession);
+    const retrieved = await sessionManager.get('thread-1');
+    expect(retrieved?.encounterId).toBe(mockSession.encounterId);
+    expect(retrieved?.phase).toBe('active');
+  });
+
+  it('returns null for an unknown thread', async () => {
+    expect(await sessionManager.get('no-such-thread')).toBeNull();
+  });
+
+  it('adds the thread to the guild index', async () => {
+    await sessionManager.create('thread-1', mockSession);
+    const ids = await sessionManager.getGuildThreadIds(mockSession.guildId);
+    expect(ids).toContain('thread-1');
+  });
+});
+
+describe('sessionManager.update', () => {
+  it('merges a patch into the existing session', async () => {
+    await sessionManager.create('thread-1', mockSession);
+    await sessionManager.update('thread-1', { phase: 'resolved' });
+    const updated = await sessionManager.get('thread-1');
+    expect(updated?.phase).toBe('resolved');
+    expect(updated?.encounterId).toBe(mockSession.encounterId);
+  });
+
+  it('updates the updatedAt timestamp', async () => {
+    await sessionManager.create('thread-1', mockSession);
+    const before = (await sessionManager.get('thread-1'))!.updatedAt;
+    await new Promise(r => setTimeout(r, 5));
+    await sessionManager.update('thread-1', { phase: 'resolved' });
+    const after = (await sessionManager.get('thread-1'))!.updatedAt;
+    expect(after).toBeGreaterThan(before);
+  });
+
+  it('throws when session does not exist', async () => {
+    await expect(sessionManager.update('ghost', { phase: 'resolved' })).rejects.toThrow();
+  });
+});
+
+describe('sessionManager.addMessage', () => {
+  it('appends a message to session history', async () => {
+    await sessionManager.create('thread-1', { ...mockSession, history: [] });
+    await sessionManager.addMessage('thread-1', {
+      role: 'user',
+      content: 'Hello!',
+      timestamp: Date.now(),
+    });
+    const session = await sessionManager.get('thread-1');
+    expect(session?.history).toHaveLength(1);
+    expect(session?.history[0].content).toBe('Hello!');
+  });
+
+  it('preserves pinned messages during history trim', async () => {
+    const pinned = { role: 'assistant' as const, content: 'Opening.', pinned: true, timestamp: 1 };
+    const bigContent = 'the quick brown fox jumps over the lazy dog. '.repeat(50);
+    const history = [pinned];
+    for (let i = 0; i < 150; i++) {
+      history.push({ role: 'user' as const, content: `${bigContent} ${i}`, timestamp: i + 2 });
+      history.push({ role: 'assistant' as const, content: `${bigContent} resp ${i}`, timestamp: i + 3 });
+    }
+    await sessionManager.create('thread-1', { ...mockSession, history });
+    await sessionManager.addMessage('thread-1', { role: 'user', content: 'New.', timestamp: 9999 });
+
+    const session = await sessionManager.get('thread-1');
+    const pinnedInHistory = session!.history.filter(m => m.pinned);
+    expect(pinnedInHistory).toHaveLength(1);
+    expect(pinnedInHistory[0].content).toBe('Opening.');
+    const sliding = session!.history.filter(m => !m.pinned);
+    expect(sliding.length).toBeLessThan(300);
+  });
+});
+
+describe('sessionManager.delete', () => {
+  it('removes the session and guild index entry', async () => {
+    await sessionManager.create('thread-1', mockSession);
+    await sessionManager.delete('thread-1', mockSession.guildId);
+    expect(await sessionManager.get('thread-1')).toBeNull();
+    const ids = await sessionManager.getGuildThreadIds(mockSession.guildId);
+    expect(ids).not.toContain('thread-1');
+  });
+});
diff --git a/tests/unit/skillCheckEmbed.test.ts b/tests/unit/skillCheckEmbed.test.ts
new file mode 100644
index 0000000..d74e416
--- /dev/null
+++ b/tests/unit/skillCheckEmbed.test.ts
@@ -0,0 +1,164 @@
+import { describe, it, expect } from 'vitest';
+import {
+  buildSkillCheckEmbed,
+  buildSuspenseEmbed,
+  buildRollButtons,
+  buildModifierRollButtons,
+  EMBED_COLOR,
+} from '../../src/bot/embeds/skillCheck.js';
+
+describe('buildSuspenseEmbed', () => {
+  it('includes the player name in the description', () => {
+    const data = buildSuspenseEmbed('Aelindra', 'sprint across the square').toJSON();
+    expect(data.description).toContain('Aelindra');
+  });
+
+  it('includes the prompt in the description', () => {
+    const data = buildSuspenseEmbed('Boris', 'jump the fence').toJSON();
+    expect(data.description).toContain('jump the fence');
+  });
+
+  it('uses pending blue color', () => {
+    const data = buildSuspenseEmbed('Aelindra', 'sprint').toJSON();
+    expect(data.color).toBe(EMBED_COLOR.PENDING);
+  });
+});
+
+describe('buildSkillCheckEmbed', () => {
+  it('includes the player name in the title', () => {
+    const data = buildSkillCheckEmbed('Boris', 'lunge at Dal', 13).toJSON();
+    expect(data.title).toContain('Boris');
+  });
+
+  it('includes DC as a field with emoji name and bold value', () => {
+    const data = buildSkillCheckEmbed('Boris', 'lunge at Dal', 13).toJSON();
+    expect(data.fields).toContainEqual(expect.objectContaining({ name: '⚖️  DC', value: '**13**' }));
+  });
+
+  it('sets description to the prompt wrapped in italics', () => {
+    const data = buildSkillCheckEmbed('Aelindra', 'chase the thief', 10).toJSON();
+    expect(data.description).toBe('*chase the thief*');
+  });
+
+  it('defaults to pending blue color', () => {
+    const data = buildSkillCheckEmbed('Boris', 'lunge', 13).toJSON();
+    expect(data.color).toBe(EMBED_COLOR.PENDING);
+  });
+
+  it('uses success green when passed EMBED_COLOR.SUCCESS', () => {
+    const data = buildSkillCheckEmbed('Boris', 'lunge', 13, EMBED_COLOR.SUCCESS).toJSON();
+    expect(data.color).toBe(EMBED_COLOR.SUCCESS);
+  });
+
+  it('uses failure red when passed EMBED_COLOR.FAILURE', () => {
+    const data = buildSkillCheckEmbed('Boris', 'lunge', 13, EMBED_COLOR.FAILURE).toJSON();
+    expect(data.color).toBe(EMBED_COLOR.FAILURE);
+  });
+
+  it('defaults footer to the roll instruction', () => {
+    const data = buildSkillCheckEmbed('Boris', 'lunge', 13).toJSON();
+    expect(data.footer?.text).toContain('Roll your dice');
+  });
+
+  it('uses custom footer text when provided', () => {
+    const data = buildSkillCheckEmbed('Boris', 'lunge', 13, EMBED_COLOR.SUCCESS, '✅ Success').toJSON();
+    expect(data.footer?.text).toBe('✅ Success');
+  });
+
+  it('shows no modifier field when modifier is omitted', () => {
+    const data = buildSkillCheckEmbed('Boris', 'lunge', 13).toJSON();
+    expect(data.fields?.some((f: { name: string }) => f.name.includes('Modifier'))).toBe(false);
+  });
+
+  it('shows modifier field with positive sign when modifier is provided', () => {
+    const data = buildSkillCheckEmbed('Boris', 'lunge', 13, undefined, undefined, 5, 'Perception').toJSON();
+    expect(data.fields).toContainEqual(expect.objectContaining({ name: '🎯  Modifier', value: '**Perception (+5)**' }));
+  });
+
+  it('shows modifier field with negative sign when modifier is negative', () => {
+    const data = buildSkillCheckEmbed('Boris', 'lunge', 13, undefined, undefined, -2).toJSON();
+    expect(data.fields).toContainEqual(expect.objectContaining({ name: '🎯  Modifier', value: '**-2**' }));
+  });
+
+  it('shows modifier without skill label when skillLabel is omitted', () => {
+    const data = buildSkillCheckEmbed('Boris', 'lunge', 13, undefined, undefined, 3).toJSON();
+    expect(data.fields).toContainEqual(expect.objectContaining({ name: '🎯  Modifier', value: '**+3**' }));
+  });
+});
+
+describe('buildRollButtons', () => {
+  it('returns exactly 4 buttons with no modifier', () => {
+    const data = buildRollButtons().toJSON();
+    expect(data.components).toHaveLength(4);
+  });
+
+  it('has the plain custom IDs in order when no modifier', () => {
+    const data = buildRollButtons().toJSON();
+    const ids = data.components.map((c: { custom_id: string }) => c.custom_id);
+    expect(ids).toEqual(['sc_roll', 'sc_adv', 'sc_dis', 'sc_mod']);
+  });
+
+  it('returns 4 buttons with pre-applied modifier when modifier is provided', () => {
+    const data = buildRollButtons(5).toJSON();
+    expect(data.components).toHaveLength(4);
+  });
+
+  it('uses modifier-encoded IDs when modifier is provided', () => {
+    const data = buildRollButtons(5).toJSON();
+    const ids = data.components.map((c: { custom_id: string }) => c.custom_id);
+    expect(ids).toEqual(['sc_roll_m:5', 'sc_adv_m:5', 'sc_dis_m:5', 'sc_mod']);
+  });
+
+  it('handles negative modifier in IDs', () => {
+    const data = buildRollButtons(-3).toJSON();
+    const ids = data.components.map((c: { custom_id: string }) => c.custom_id);
+    expect(ids).toEqual(['sc_roll_m:-3', 'sc_adv_m:-3', 'sc_dis_m:-3', 'sc_mod']);
+  });
+
+  it('shows modifier in labels when modifier is provided', () => {
+    const data = buildRollButtons(4).toJSON();
+    const labels = data.components.map((c: { label: string }) => c.label);
+    expect(labels[0]).toContain('+4');
+    expect(labels[1]).toContain('+4');
+    expect(labels[2]).toContain('+4');
+  });
+});
+
+describe('buildModifierRollButtons', () => {
+  it('returns exactly 3 buttons', () => {
+    const data = buildModifierRollButtons(3).toJSON();
+    expect(data.components).toHaveLength(3);
+  });
+
+  it('encodes a positive modifier in all custom IDs', () => {
+    const data = buildModifierRollButtons(3).toJSON();
+    const ids = data.components.map((c: { custom_id: string }) => c.custom_id);
+    expect(ids).toEqual(['sc_roll_m:3', 'sc_adv_m:3', 'sc_dis_m:3']);
+  });
+
+  it('encodes a negative modifier in all custom IDs', () => {
+    const data = buildModifierRollButtons(-2).toJSON();
+    const ids = data.components.map((c: { custom_id: string }) => c.custom_id);
+    expect(ids).toEqual(['sc_roll_m:-2', 'sc_adv_m:-2', 'sc_dis_m:-2']);
+  });
+
+  it('shows the +sign in labels for positive modifiers', () => {
+    const data = buildModifierRollButtons(5).toJSON();
+    const labels = data.components.map((c: { label: string }) => c.label);
+    expect(labels[0]).toContain('+5');
+    expect(labels[1]).toContain('+5');
+    expect(labels[2]).toContain('+5');
+  });
+
+  it('shows the minus sign in labels for negative modifiers', () => {
+    const data = buildModifierRollButtons(-1).toJSON();
+    const labels = data.components.map((c: { label: string }) => c.label);
+    expect(labels[0]).toContain('-1');
+  });
+
+  it('handles zero modifier', () => {
+    const data = buildModifierRollButtons(0).toJSON();
+    const ids = data.components.map((c: { custom_id: string }) => c.custom_id);
+    expect(ids).toEqual(['sc_roll_m:0', 'sc_adv_m:0', 'sc_dis_m:0']);
+  });
+});
diff --git a/tests/unit/specLoader.test.ts b/tests/unit/specLoader.test.ts
new file mode 100644
index 0000000..a42206f
--- /dev/null
+++ b/tests/unit/specLoader.test.ts
@@ -0,0 +1,93 @@
+import { describe, it, expect, vi } from 'vitest';
+import { ZodError } from 'zod';
+import { EncounterSpecSchema } from '../../src/spec/loader.js';
+
+vi.mock('../../src/config.js', () => ({
+  config: { SPECS_DIR: './specs' },
+}));
+
+// Raw object matching the schema — used to test Zod validation directly
+// without touching the filesystem.
+const validRaw = {
+  encounterId: 'test-001',
+  title: 'Test Encounter',
+  setting: {
+    location: 'Town Square',
+    mood: 'Tense',
+    ambientNpcs: 'Bystanders',
+  },
+  openingNarrative: 'It begins.',
+  npcs: [
+    { id: 'npc-1', name: 'Miriam', role: 'Vendor', persona: 'Loud and indignant.' },
+  ],
+  goals: {
+    hidden: true,
+    primary: [{ id: 'catch', label: 'Catch the thief.' }],
+    secondary: [{ id: 'escape', label: 'The thief escapes.' }],
+  },
+  sportsmanshipRules: ['No teleportation.'],
+  skillChecks: { chase_dc: 13 },
+};
+
+describe('EncounterSpecSchema', () => {
+  it('parses a valid spec object without error', () => {
+    const result = EncounterSpecSchema.parse(validRaw);
+    expect(result.encounterId).toBe('test-001');
+    expect(result.npcs).toHaveLength(1);
+    expect(result.goals.primary).toHaveLength(1);
+  });
+
+  it('throws ZodError when encounterId is missing', () => {
+    const bad = { ...validRaw, encounterId: undefined };
+    expect(() => EncounterSpecSchema.parse(bad)).toThrow(ZodError);
+  });
+
+  it('throws ZodError when npcs array is empty', () => {
+    const bad = { ...validRaw, npcs: [] };
+    expect(() => EncounterSpecSchema.parse(bad)).toThrow(ZodError);
+  });
+
+  it('throws ZodError when primary goals array is empty', () => {
+    const bad = { ...validRaw, goals: { ...validRaw.goals, primary: [] } };
+    expect(() => EncounterSpecSchema.parse(bad)).toThrow(ZodError);
+  });
+
+  it('strips unrecognised extra fields', () => {
+    const withExtra = { ...validRaw, randomField: 'should be stripped' };
+    const result = EncounterSpecSchema.parse(withExtra);
+    expect((result as any).randomField).toBeUndefined();
+  });
+
+  it('preserves the full openingNarrative text', () => {
+    const long = { ...validRaw, openingNarrative: 'Long narrative text here. '.repeat(20) };
+    const result = EncounterSpecSchema.parse(long);
+    expect(result.openingNarrative).toBe(long.openingNarrative);
+  });
+
+  it('defaults hidden to true when omitted', () => {
+    const withoutHidden = {
+      ...validRaw,
+      goals: { primary: validRaw.goals.primary, secondary: validRaw.goals.secondary },
+    };
+    const result = EncounterSpecSchema.parse(withoutHidden);
+    expect(result.goals.hidden).toBe(true);
+  });
+
+  it('accepts mixed skillCheck values (number and string)', () => {
+    const mixed = { ...validRaw, skillChecks: { chase_dc: 13, chase_note: 'Athletics or Acrobatics' } };
+    const result = EncounterSpecSchema.parse(mixed);
+    expect(result.skillChecks.chase_dc).toBe(13);
+    expect(result.skillChecks.chase_note).toBe('Athletics or Acrobatics');
+  });
+
+  it('parses optional tone field when present', () => {
+    const withTone = { ...validRaw, tone: 'tense' };
+    const result = EncounterSpecSchema.parse(withTone);
+    expect(result.tone).toBe('tense');
+  });
+
+  it('tone is undefined when absent', () => {
+    const result = EncounterSpecSchema.parse(validRaw);
+    expect(result.tone).toBeUndefined();
+  });
+});
diff --git a/tests/unit/toolDispatcher.test.ts b/tests/unit/toolDispatcher.test.ts
new file mode 100644
index 0000000..9e6ef3d
--- /dev/null
+++ b/tests/unit/toolDispatcher.test.ts
@@ -0,0 +1,189 @@
+import { vi, describe, it, expect, beforeEach } from 'vitest';
+
+const {
+  mockSessionUpdate,
+  mockLogEncounter,
+  mockWriteSummary,
+  mockBuildSkillCheckEmbed,
+  mockBuildResolutionEmbed,
+} = vi.hoisted(() => ({
+  mockSessionUpdate: vi.fn(),
+  mockLogEncounter: vi.fn().mockResolvedValue({ enc_id: 'e1' }),
+  mockWriteSummary: vi.fn().mockReturnValue('/data/summaries/test.txt'),
+  mockBuildSkillCheckEmbed: vi.fn().mockReturnValue({ data: { title: 'Skill Check' } }),
+  mockBuildResolutionEmbed: vi.fn().mockReturnValue({ data: { title: 'Resolved' } }),
+}));
+
+vi.mock('../../src/session/sessionManager.js', () => ({
+  sessionManager: { update: mockSessionUpdate },
+}));
+vi.mock('../../src/graphmcp/client.js', () => ({
+  logEncounter: mockLogEncounter,
+}));
+vi.mock('../../src/session/encounterLog.js', () => ({
+  writeSummary: mockWriteSummary,
+}));
+vi.mock('../../src/bot/embeds/skillCheck.js', () => ({
+  buildSuspenseEmbed: vi.fn().mockReturnValue({ data: { title: 'Suspense' } }),
+  buildSkillCheckEmbed: mockBuildSkillCheckEmbed,
+  buildRollButtons: vi.fn().mockReturnValue([]),
+}));
+vi.mock('../../src/bot/embeds/resolution.js', () => ({
+  buildResolutionEmbed: mockBuildResolutionEmbed,
+}));
+
+import { dispatchTool } from '../../src/harness/toolDispatcher.js';
+import { mockSession } from '../fixtures/spec.js';
+
+function makeThread() {
+  return {
+    send: vi.fn().mockResolvedValue({ id: 'msg-1', edit: vi.fn().mockResolvedValue(undefined) }),
+  };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe('dispatchTool — skill_check_emit', () => {
+  it('sends a skill check embed to the thread', async () => {
+    const thread = makeThread();
+    await dispatchTool(
+      { tool: 'skill_check_emit', args: { player: 'Aelindra', prompt: 'Chase DC', dc: 13 } },
+      { session: mockSession, thread: thread as any },
+    );
+    expect(thread.send).toHaveBeenCalledOnce();
+  });
+
+  it('sets pendingSkillCheck on the session', async () => {
+    const thread = makeThread();
+    await dispatchTool(
+      { tool: 'skill_check_emit', args: { player: 'Aelindra', prompt: 'Chase DC', dc: 13 } },
+      { session: mockSession, thread: thread as any },
+    );
+    expect(mockSessionUpdate).toHaveBeenCalledWith(
+      mockSession.threadId,
+      expect.objectContaining({ pendingSkillCheck: expect.objectContaining({ dc: 13 }) }),
+    );
+  });
+
+  it('returns a systemMessage confirming the embed was posted', async () => {
+    const thread = makeThread();
+    const result = await dispatchTool(
+      { tool: 'skill_check_emit', args: { player: 'Aelindra', prompt: 'Chase DC', dc: 13 } },
+      { session: mockSession, thread: thread as any },
+    );
+    expect(result.systemMessage).toContain('Aelindra');
+    expect(result.systemMessage).toContain('13');
+    expect(result.resolved).toBeUndefined();
+  });
+});
+
+describe('dispatchTool — encounter_resolve', () => {
+  it('calls logEncounter with all participants', async () => {
+    const thread = makeThread();
+    await dispatchTool(
+      { tool: 'encounter_resolve', args: { sessionId: 'thread-123', outcomeId: 'catch', summary: 'Dal was caught.' } },
+      { session: mockSession, thread: thread as any },
+    );
+    expect(mockLogEncounter).toHaveBeenCalledWith(
+      expect.objectContaining({
+        participants: expect.stringContaining('Miriam'),
+        summary: 'Dal was caught.',
+      }),
+    );
+  });
+
+  it('sends a resolution embed to the thread', async () => {
+    const thread = makeThread();
+    await dispatchTool(
+      { tool: 'encounter_resolve', args: { sessionId: 'thread-123', outcomeId: 'catch', summary: 'Dal was caught.' } },
+      { session: mockSession, thread: thread as any },
+    );
+    expect(thread.send).toHaveBeenCalledOnce();
+  });
+
+  it('writes a summary file to disk', async () => {
+    const thread = makeThread();
+    await dispatchTool(
+      { tool: 'encounter_resolve', args: { sessionId: 'thread-123', outcomeId: 'catch', summary: 'Dal was caught.' } },
+      { session: mockSession, thread: thread as any },
+    );
+    expect(mockWriteSummary).toHaveBeenCalledWith(mockSession, 'catch', 'Dal was caught.');
+  });
+
+  it('returns resolved with outcomeId and summary', async () => {
+    const thread = makeThread();
+    const result = await dispatchTool(
+      { tool: 'encounter_resolve', args: { sessionId: 'thread-123', outcomeId: 'catch', summary: 'Dal was caught.' } },
+      { session: mockSession, thread: thread as any },
+    );
+    expect(result.resolved).toEqual({ outcomeId: 'catch', summary: 'Dal was caught.' });
+  });
+
+  it('does not throw if logEncounter fails — logs gracefully', async () => {
+    mockLogEncounter.mockRejectedValueOnce(new Error('GraphMCP down'));
+    const thread = makeThread();
+    await expect(
+      dispatchTool(
+        { tool: 'encounter_resolve', args: { sessionId: 'thread-123', outcomeId: 'escape', summary: 'Dal escaped.' } },
+        { session: mockSession, thread: thread as any },
+      ),
+    ).resolves.toBeDefined();
+  });
+});
+
+describe('dispatchTool — unknown tool', () => {
+  it('returns an error systemMessage without throwing', async () => {
+    const thread = makeThread();
+    const result = await dispatchTool(
+      { tool: 'npc_memory_write' as any, args: {} },
+      { session: mockSession, thread: thread as any },
+    );
+    expect(result.systemMessage).toContain('not available in this encounter');
+    expect(thread.send).not.toHaveBeenCalled();
+  });
+});
+
+describe('dispatchTool — spec.tools allow-list', () => {
+  it('rejects a registered tool that is not in the spec allow-list', async () => {
+    const thread = makeThread();
+    const session = { ...mockSession, spec: { ...mockSession.spec, tools: ['skill_check_emit'] } };
+    const result = await dispatchTool(
+      { tool: 'encounter_resolve', args: { sessionId: 'thread-123', outcomeId: 'catch', summary: 'Done.' } },
+      { session, thread: thread as any },
+    );
+    expect(result.systemMessage).toContain('not available in this encounter');
+    expect(thread.send).not.toHaveBeenCalled();
+  });
+
+  it('allows a tool that is in the spec allow-list', async () => {
+    const thread = makeThread();
+    const session = { ...mockSession, spec: { ...mockSession.spec, tools: ['skill_check_emit'] } };
+    const result = await dispatchTool(
+      { tool: 'skill_check_emit', args: { player: 'Aelindra', prompt: 'chase', dc: 13 } },
+      { session, thread: thread as any },
+    );
+    expect(result.systemMessage).not.toContain('not available');
+    expect(thread.send).toHaveBeenCalledOnce();
+  });
+
+  it('allows all tools when spec.tools is omitted', async () => {
+    const thread = makeThread();
+    const result = await dispatchTool(
+      { tool: 'encounter_resolve', args: { sessionId: 'thread-123', outcomeId: 'catch', summary: 'Done.' } },
+      { session: mockSession, thread: thread as any },
+    );
+    expect(result.resolved).toBeDefined();
+  });
+
+  it('allows all tools when spec.tools is an empty array', async () => {
+    const thread = makeThread();
+    const session = { ...mockSession, spec: { ...mockSession.spec, tools: [] } };
+    const result = await dispatchTool(
+      { tool: 'encounter_resolve', args: { sessionId: 'thread-123', outcomeId: 'catch', summary: 'Done.' } },
+      { session, thread: thread as any },
+    );
+    expect(result.resolved).toBeDefined();
+  });
+});
diff --git a/tests/unit/toolParser.test.ts b/tests/unit/toolParser.test.ts
new file mode 100644
index 0000000..676d6ab
--- /dev/null
+++ b/tests/unit/toolParser.test.ts
@@ -0,0 +1,83 @@
+import { describe, it, expect } from 'vitest';
+import { parseToolCall } from '../../src/harness/toolParser.js';
+
+describe('parseToolCall', () => {
+  it('returns full text as narrative when no tool block is present', () => {
+    const raw = 'Miriam spins around, face going scarlet. "THIEF!"';
+    const result = parseToolCall(raw);
+    expect(result.narrative).toBe(raw);
+    expect(result.toolCall).toBeUndefined();
+  });
+
+  it('strips the tool block and returns narrative + parsed tool call', () => {
+    const narrative = 'Dal bolts toward the alley. Quick — roll to give chase.';
+    const raw = `${narrative}\n\`\`\`tool_call\n{ "tool": "skill_check_emit", "args": { "player": "Aelindra", "prompt": "Chase DC", "dc": 13 } }\n\`\`\``;
+    const result = parseToolCall(raw);
+    expect(result.narrative).toBe(narrative);
+    expect(result.toolCall).toMatchObject({
+      tool: 'skill_check_emit',
+      args: { player: 'Aelindra', dc: 13 },
+    });
+  });
+
+  it('falls back to full text as narrative when JSON is malformed', () => {
+    const raw = 'Narrative text.\n```tool_call\n{ bad json }\n```';
+    const result = parseToolCall(raw);
+    expect(result.narrative).toBe(raw.trim());
+    expect(result.toolCall).toBeUndefined();
+  });
+
+  it('ignores tool blocks with unrecognised tool names', () => {
+    const raw = 'Text.\n```tool_call\n{ "tool": "npc_memory_write", "args": {} }\n```';
+    const result = parseToolCall(raw);
+    expect(result.toolCall).toBeUndefined();
+    // Narrative should still be the pre-block text
+    expect(result.narrative).toBe('Text.');
+  });
+
+  it('handles encounter_resolve tool blocks', () => {
+    const raw = 'The thief is caught.\n```tool_call\n{ "tool": "encounter_resolve", "args": { "sessionId": "t1", "outcomeId": "catch", "summary": "Dal was cornered." } }\n```';
+    const result = parseToolCall(raw);
+    expect(result.toolCall?.tool).toBe('encounter_resolve');
+    expect(result.toolCall?.args).toMatchObject({ outcomeId: 'catch' });
+  });
+
+  it('trims surrounding whitespace from narrative', () => {
+    const raw = '  Some text.  ';
+    const result = parseToolCall(raw);
+    expect(result.narrative).toBe('Some text.');
+  });
+});
+
+describe('parseToolCall — bare tool_name format', () => {
+  it('treats bare tool_name lines as plain narrative (format not supported)', () => {
+    const raw = 'Text.\nskill_check_emit\n{ bad }';
+    const result = parseToolCall(raw);
+    expect(result.toolCall).toBeUndefined();
+    expect(result.narrative).toBe(raw.trim());
+  });
+});
+
+describe('parseToolCall — plain tool_call header (no fences)', () => {
+  it('parses encounter_resolve with plain tool_call header', () => {
+    const raw = `The thief accepted the offer.\ntool_call\n{ "tool": "encounter_resolve", "args": { "sessionId": "t1", "outcomeId": "negotiate", "summary": "Dal agreed to meet later." } }`;
+    const result = parseToolCall(raw);
+    expect(result.narrative).toBe('The thief accepted the offer.');
+    expect(result.toolCall?.tool).toBe('encounter_resolve');
+    expect(result.toolCall?.args).toMatchObject({ outcomeId: 'negotiate' });
+  });
+
+  it('parses skill_check_emit with plain tool_call header', () => {
+    const raw = `Roll for it.\ntool_call\n{ "tool": "skill_check_emit", "args": { "player": "Boris", "prompt": "lunge", "dc": 13 } }`;
+    const result = parseToolCall(raw);
+    expect(result.narrative).toBe('Roll for it.');
+    expect(result.toolCall?.tool).toBe('skill_check_emit');
+    expect(result.toolCall?.args).toMatchObject({ dc: 13 });
+  });
+
+  it('rejects unknown tools in plain header format', () => {
+    const raw = `Text.\ntool_call\n{ "tool": "npc_memory_write", "args": {} }`;
+    const result = parseToolCall(raw);
+    expect(result.toolCall).toBeUndefined();
+  });
+});
diff --git a/tsconfig.json b/tsconfig.json
new file mode 100644
index 0000000..7f4a5df
--- /dev/null
+++ b/tsconfig.json
@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}
diff --git a/vitest.config.ts b/vitest.config.ts
new file mode 100644
index 0000000..6e3a3a8
--- /dev/null
+++ b/vitest.config.ts
@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json'],
+      include: ['src/**/*.ts'],
+    },
+  },
+});