diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..ea5e24a
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,167 @@
+# Changelog
+
+All notable changes to the Storyteller RPG project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.2.0] - 2025-10-12
+
+### Added
+- **Context-Aware Response Generator** 🧠
+  - Select multiple characters to include in AI-generated responses
+  - Two modes: Scene descriptions (broadcast) or Individual responses (private)
+  - Smart context building with character profiles, personalities, and conversation history
+  - Automatic parsing and distribution of individual responses
+  - Improved prompts with explicit `[CharacterName]` format for reliable parsing
+  
+- **Demo Session** 🎮
+  - Pre-configured "The Cursed Tavern" adventure
+  - Two characters: Bargin Ironforge (Dwarf Warrior) & Willow Moonwhisper (Elf Ranger)
+  - Auto-created on server startup
+  - Quick-access buttons on home page for instant testing
+  - Eliminates need to recreate test data during development
+  
+- **Session ID Copy Button** 📋
+  - One-click clipboard copy in storyteller dashboard
+  - Improved UX for session sharing
+
+- **Comprehensive Documentation** 📚
+  - Feature guides for all major features
+  - Prompt engineering documentation
+  - Demo session usage guide
+  - Bug fixes summary
+
+### Fixed
+- **Character Chat History** - Characters can now see full conversation with storyteller (not just most recent message)
+  - Fixed WebSocket message type handling (`storyteller_response` and `new_message`)
+  
+- **Pydantic Deprecation Warnings** - Replaced all `.dict()` calls with `.model_dump()` (9 instances)
+  - Code is now Pydantic V2 compliant
+  - No more deprecation warnings in console
+  
+- **WebSocket Manager Reference** - Fixed `character_connections` error in contextual response endpoint
+  - Now properly uses `manager.send_to_client()` with correct key format
+
+### Changed
+- Improved LLM prompts for individual responses with explicit format instructions
+- Simplified response parsing from 4 regex patterns to single reliable pattern
+- Enhanced system prompts for better LLM compliance
+- Reorganized documentation structure with dedicated features folder
+
+---
+
+## [0.1.0] - 2025-10-11
+
+### Added
+- **Core Session Management**
+  - Create and join game sessions
+  - Session ID-based access control
+  - In-memory session storage
+  
+- **Character System**
+  - Character creation with name, description, and personality
+  - Character profiles visible to storyteller
+  - Per-character conversation history
+  
+- **Flexible Messaging System** 📨
+  - **Private Messages** - Character ↔ Storyteller only
+  - **Public Messages** - Visible to all players
+  - **Mixed Messages** - Public action + private thoughts
+  - Real-time message delivery via WebSockets
+  
+- **Scene Narration** 📜
+  - Storyteller can broadcast scene descriptions
+  - Scenes visible to all connected characters
+  - Scene history tracking
+  
+- **AI-Assisted Responses** ✨
+  - "AI Suggest" button for storytellers
+  - Generate response suggestions using character's LLM
+  - Editable before sending
+  
+- **Multi-LLM Support** 🤖
+  - Support for 100+ models via OpenRouter and OpenAI
+  - Per-character model selection
+  - Models: GPT-4o, GPT-4, GPT-3.5, Claude, Llama, Gemini, Mistral, etc.
+  - Each character can use a different model
+  
+- **Real-time Communication** ⚡
+  - WebSocket endpoints for characters and storyteller
+  - Instant message delivery
+  - Connection status indicators
+  - Pending response tracking
+  
+- **Modern UI** 🎨
+  - Clean, intuitive interface
+  - Gradient-themed design
+  - Responsive layout
+  - Character-specific color schemes
+  - Loading states and animations
+
+### Technical
+- FastAPI backend with WebSocket support
+- React frontend with modern hooks
+- ConnectionManager for WebSocket state
+- Pydantic models for data validation
+- CORS configuration for local development
+- Environment-based API key management
+
+---
+
+## [Unreleased]
+
+### Planned Features
+- Database persistence (PostgreSQL/MongoDB)
+- User authentication system
+- Character sheets with stats
+- Dice rolling mechanics
+- Combat system
+- Image generation for scenes/characters
+- Voice message support
+- Session export functionality
+- Mobile app versions
+
+---
+
+## Version History
+
+- **0.2.0** (2025-10-12) - Context-Aware AI, Demo Session, Bug Fixes
+- **0.1.0** (2025-10-11) - Initial MVP Release
+
+---
+
+## Migration Notes
+
+### 0.1.0 → 0.2.0
+
+**No breaking changes.** All existing functionality preserved.
+
+**New Features Available:**
+- Click "▶ Show Generator" in storyteller dashboard for context-aware responses
+- Demo session auto-created on startup (session ID: `demo-session-001`)
+- Copy button next to session ID for easy sharing
+
+**Bug Fixes Applied Automatically:**
+- Full conversation history now visible
+- No more Pydantic warnings
+- WebSocket messages work correctly
+
+**No Action Required:**
+- In-memory sessions continue to work as before
+- No database migrations needed
+- Frontend automatically detects new features
+
+---
+
+## Contributing
+
+See [docs/README.md](./docs/README.md) for documentation guidelines.
+
+Report bugs or suggest features via GitHub issues.
+
+---
+
+*Format inspired by [Keep a Changelog](https://keepachangelog.com/)*
diff --git a/CURRENT_STATUS.md b/CURRENT_STATUS.md
deleted file mode 100644
index 9d07fac..0000000
--- a/CURRENT_STATUS.md
+++ /dev/null
@@ -1,308 +0,0 @@
-# 🎭 Storyteller RPG - Current Status
-
-**Date:** October 11, 2025  
-**Session Duration:** ~1 hour  
-**Status:** ✅ Major MVP Features Implemented
-
----
-
-## 🎉 What We Accomplished Today
-
-### 1. ✨ AI-Assisted Storyteller Responses (Quick Win)
-**New Feature:** Storytellers can now click "✨ AI Suggest" to generate response suggestions using the character's chosen LLM model.
-
-**Implementation:**
-- Added button in StorytellerView response section
-- Shows loading state while generating
-- Populates textarea with suggestion (editable before sending)
-- Uses existing backend endpoint
-
-**Files Modified:**
-- `frontend/src/components/StorytellerView.js`
-- `frontend/src/App.css` (added `.btn-secondary`, `.response-buttons`)
-
----
-
-### 2. 📢 Enhanced Message System (MVP Phase 1 - COMPLETE!)
-
-This is the **core feature** that makes the app unique for RPG gameplay.
-
-#### Message Types
-1. **🔒 Private** - Only storyteller sees (default)
-   - Example: "I attempt to pickpocket the merchant"
-   
-2. **📢 Public** - All players see
-   - Example: "I shake hands with the merchant"
-   
-3. **🔀 Mixed** - Public action + secret motive
-   - Public: "I shake hands with the merchant"
-   - Private: "While shaking hands, I try to slip my hand into his pocket"
-
-#### Backend Changes (`main.py`)
-- **Message Model Updated:**
-  ```python
-  class Message:
-      visibility: str = "private"  # "public", "private", "mixed"
-      public_content: Optional[str] = None
-      private_content: Optional[str] = None
-  ```
-  
-- **GameSession Model Updated:**
-  ```python
-  class GameSession:
-      public_messages: List[Message] = []  # Shared feed
-  ```
-
-- **WebSocket Routing:**
-  - Private messages → Only to storyteller
-  - Public messages → Broadcast to all characters
-  - Mixed messages → Both feeds appropriately
-
-#### Frontend Changes
-
-**CharacterView.js:**
-- Message type selector dropdown
-- Public messages section (shows all player actions)
-- Private conversation section (storyteller only)
-- Mixed message composer with dual textareas
-- Real-time updates for both feeds
-
-**StorytellerView.js:**
-- Public actions feed (last 5 actions)
-- View all message types
-- See both public and private content
-
-**App.css:**
-- New sections for public/private message display
-- Mixed message composer styling
-- Visual distinction between message types
-
----
-
-## 🏗️ Architecture Improvements
-
-### Message Flow
-
-```
-CHARACTER A                    STORYTELLER                   CHARACTER B
-    |                              |                              |
-    | "I pickpocket" (private)     |                              |
-    |----------------------------->|                              |
-    |                              |                              |
-    | "I wave hello" (public)      |                              |
-    |----------------------------->|----------------------------->|
-    |                              |                              |
-    |           Sees both          |        Sees only public      |
-```
-
-### Privacy Model
-- ✅ Characters only see their own private messages
-- ✅ Characters see ALL public messages
-- ✅ Storyteller sees EVERYTHING
-- ✅ Mixed messages split correctly
-
----
-
-## 🎮 How to Use
-
-### As a Character:
-
-1. **Join a session** at http://localhost:3000
-2. **Select message type** from dropdown:
-   - 🔒 Private (default) - Secret actions
-   - 📢 Public - Actions everyone sees
-   - 🔀 Mixed - Do something publicly while attempting something secret
-3. **Send messages** - They route appropriately
-4. **View public feed** - See what other players are doing
-5. **Private conversation** - Your secret messages with storyteller
-
-### As a Storyteller:
-
-1. **Create session** and share ID
-2. **View public feed** - See all public actions
-3. **Select character** - View their private messages
-4. **Click "✨ AI Suggest"** - Generate response ideas
-5. **Respond privately** - Each character gets personalized replies
-6. **Narrate scenes** - Broadcast to everyone
-
----
-
-## 📁 Files Modified
-
-### Backend
-- ✅ `main.py` - Message model, routing, public messages
-
-### Frontend Components
-- ✅ `frontend/src/components/CharacterView.js` - Message composer, public feed
-- ✅ `frontend/src/components/StorytellerView.js` - AI suggest, public feed
-
-### Styles
-- ✅ `frontend/src/App.css` - New sections and components
-
-### Documentation
-- ✅ `docs/development/MVP_PROGRESS.md` - Detailed progress report
-- ✅ `CURRENT_STATUS.md` - This file
-
----
-
-## 🧪 Testing Status
-
-### ✅ Verified
-- Backend starts with new message model
-- Frontend compiles successfully
-- Both servers running (ports 3000 & 8000)
-- API endpoints include `public_messages`
-
-### ⏳ Manual Testing Needed
-You should test these scenarios:
-
-1. **Two Character Test:**
-   - Open two browser windows
-   - Create session as storyteller in window 1
-   - Join as Character A in window 2
-   - Join as Character B in window 3
-   - Send public message from Character A
-   - Verify Character B sees it
-   - Send private message from Character A
-   - Verify Character B does NOT see it
-   - Verify storyteller sees both
-
-2. **Mixed Message Test:**
-   - Select "Mixed" message type
-   - Enter public action: "I examine the door"
-   - Enter private action: "I check for traps"
-   - Send and verify both parts appear correctly
-
-3. **AI Suggest Test:**
-   - As storyteller, click "✨ AI Suggest"
-   - Verify suggestion generates
-   - Edit and send
-
----
-
-## 🚀 What's Next
-
-### Immediate Priorities
-
-#### 1. Database Persistence (High Priority - 3-4 hours)
-**Why:** Currently sessions only exist in memory. Server restart = data loss.
-
-**What to add:**
-```bash
-# requirements.txt
-sqlalchemy==2.0.23
-aiosqlite==3.0.10
-alembic==1.13.0
-```
-
-**Implementation:**
-- Create `database.py` with SQLAlchemy models
-- Replace in-memory `sessions` dict
-- Add save/load endpoints
-- Enable session persistence
-
-#### 2. Character Profile System (MVP Phase 2 - 1-2 days)
-Implement the race/class/personality system from MVP roadmap:
-
-**Features:**
-- Character creation wizard
-- Race selection (Human/Elf/Dwarf/Orc/Halfling)
-- Class selection (Warrior/Wizard/Cleric/Archer/Rogue)
-- Personality (Friendly/Serious/Doubtful/Measured)
-- Profile-based LLM prompts
-- Import/export (JSON & PNG)
-
-#### 3. Show Character Names in Public Feed (Quick Fix - 30 mins)
-Currently public messages don't clearly show WHO did the action.
-
-**Update needed:**
-- Include character name in public message broadcasts
-- Display in public feed: "Gandalf the Wizard: I cast light"
-
----
-
-## 📊 MVP Progress
-
-**Phase 1:** ✅ 100% Complete (Enhanced Message System)  
-**Phase 2:** ⏳ 0% Complete (Character Profiles) - **NEXT**  
-**Phase 3:** ⏳ 0% Complete (User Mode Interfaces)  
-**Phase 4:** ⏳ 0% Complete (AI Automation)  
-**Phase 5:** ⏳ 0% Complete (Game Management & Database)  
-**Phase 6:** ⏳ 0% Complete (Polish & Testing)
-
-**Overall MVP Progress:** ~8% (1/12 weeks)
-
----
-
-## 🎯 Success Metrics
-
-### ✅ Completed
-- [x] Private character-storyteller communication
-- [x] Public message broadcasting
-- [x] Mixed message support
-- [x] AI-assisted responses UI
-- [x] Real-time WebSocket updates
-- [x] Message type selection
-- [x] Visual distinction between message types
-
-### 🎲 Ready for Testing
-- [ ] Multi-character public feed
-- [ ] Mixed message splitting
-- [ ] AI suggestion quality
-- [ ] Message persistence across refresh (needs DB)
-
----
-
-## 💡 Key Insights
-
-1. **Message System is Core:** The public/private/mixed system is what makes this app special for RPG. Players can now create dramatic situations where they act one way publicly while secretly doing something else.
-
-2. **Quick Wins Matter:** The AI Suggest button took 30 minutes but adds huge value for storytellers.
-
-3. **Database is Critical:** Next session should start with SQLite implementation to prevent data loss and enable real features.
-
-4. **Profile System is Next:** Character profiles with race/class/personality will make the LLM responses much more interesting and distinct.
-
----
-
-## 🔧 Running the Application
-
-The application is currently running:
-
-```bash
-# Backend: http://localhost:8000
-# Frontend: http://localhost:3000
-
-# To restart both:
-bash start.sh
-
-# To stop:
-# Ctrl+C in the terminal running start.sh
-```
-
----
-
-## 📚 Documentation
-
-- **Setup:** `docs/setup/QUICKSTART.md`
-- **MVP Roadmap:** `docs/planning/MVP_ROADMAP.md`
-- **Progress Report:** `docs/development/MVP_PROGRESS.md`
-- **Implementation Details:** `docs/development/IMPLEMENTATION_SUMMARY.md`
-- **API Reference:** `docs/reference/LLM_GUIDE.md`
-
----
-
-## 🎉 Summary
-
-**Excellent progress!** We've completed Phase 1 of the MVP roadmap (Enhanced Message System) and added a valuable quick win (AI Suggest). The application now supports:
-
-- ✨ **AI-assisted storyteller responses**
-- 🔒 **Private messages** (character ↔ storyteller only)
-- 📢 **Public messages** (visible to all players)
-- 🔀 **Mixed messages** (public action + secret motive)
-- 🎭 **Real-time broadcasting** to appropriate audiences
-- 🤖 **Multi-LLM support** (OpenAI + OpenRouter)
-
-**The foundation is solid.** The message system works as designed, and the architecture supports the remaining MVP phases. Next session should focus on database persistence and character profiles to make the app truly shine.
-
-**Great work finishing the MVP!** 🚀
diff --git a/README.md b/README.md
index 063e826..3541d3c 100644
--- a/README.md
+++ b/README.md
@@ -4,13 +4,23 @@ A storyteller-centric roleplaying application where characters communicate **pri
 
 ## ✨ Key Features
 
+### Core Features
 - **🔒 Private Character-Storyteller Communication**: Each character has a completely isolated conversation with the storyteller - no character can see what others are saying or receiving
+- **📢 Flexible Messaging System**: Private, public, or mixed messages for different roleplay scenarios
 - **🎲 Storyteller-Centric Workflow**: The storyteller sees all character messages and responds to each individually
-- **🤖 Multiple LLM Support**: Each character can use a different AI model (GPT-4, Claude, Llama, Gemini, Mistral, etc.) via OpenRouter or OpenAI
-- **📜 Scene Narration**: Storyteller can broadcast scene descriptions visible to all characters
-- **🧠 Isolated Memory Sessions**: Each character maintains their own separate conversation history with the storyteller
+- **🧠 Context-Aware AI**: Generate responses considering multiple characters' actions simultaneously
+- **🎮 Demo Session**: Pre-loaded "Cursed Tavern" adventure with two characters for instant testing
+
+### AI & LLM Support
+- **🤖 Multiple LLM Support**: GPT-4o, GPT-4, GPT-3.5, Claude, Llama, Gemini, Mistral (100+ models via OpenRouter)
+- **✨ AI-Assisted Responses**: Get AI suggestions for storyteller responses
+- **🎯 Smart Context Building**: AI considers character profiles, personalities, and conversation history
+
+### Technical Features
 - **⚡ Real-time WebSocket Communication**: Instant message delivery
+- **🧠 Isolated Memory Sessions**: Each character maintains their own separate conversation history
 - **🎨 Modern, Beautiful UI**: Clean, intuitive interface with gradient themes
+- **📱 Responsive Design**: Works on desktop, tablet, and mobile
 
 ## 🎯 How It Works
 
@@ -69,27 +79,51 @@ A storyteller-centric roleplaying application where characters communicate **pri
    npm install
    ```
 
-## Running the Application
+## 🚀 Quick Start
 
-### Start the Backend
+### Easy Start (Recommended)
 
-From the project root directory:
+Use the startup script to launch both backend and frontend:
+
+**Linux/Mac:**
+```bash
+bash start.sh
+```
+
+**Windows:**
+```bash
+start.bat
+```
+
+This will:
+1. Start the FastAPI backend on `http://localhost:8000`
+2. Start the React frontend on `http://localhost:3000`
+3. Create a demo session automatically
+4. Open your browser
+
+### Demo Session 🎲
+
+A pre-configured "Cursed Tavern" adventure is automatically created with:
+- **Session ID:** `demo-session-001`
+- **Characters:** Bargin (Dwarf Warrior) & Willow (Elf Ranger)
+- **Quick-access buttons** on the home page
+
+Just click a button and start playing!
+
+### Manual Start
+
+If you prefer to run services separately:
+
+**Backend:**
 ```bash
 uvicorn main:app --reload
 ```
 
-The backend will be available at `http://localhost:8000`
-
-### Start the Frontend
-
-In a new terminal, navigate to the frontend directory and run:
+**Frontend:**
 ```bash
-cd frontend
-npm start
+cd frontend && npm start
 ```
 
-The frontend will open in your default browser at `http://localhost:3000`
-
 ## 🎮 How to Use
 
 ### As the Storyteller
@@ -184,10 +218,15 @@ Each character has a **completely isolated** conversation with the storyteller:
 
 All project documentation is organized in the [`docs/`](./docs/) folder:
 
+### Quick Links
+- **[Features Guide](./docs/features/)** - All features with examples and guides
+  - [Demo Session](./docs/features/DEMO_SESSION.md)
+  - [Context-Aware Responses](./docs/features/CONTEXTUAL_RESPONSE_FEATURE.md)
+  - [Bug Fixes Summary](./docs/features/FIXES_SUMMARY.md)
 - **[Setup Guides](./docs/setup/)** - Quick start and installation
 - **[Planning](./docs/planning/)** - Roadmaps and feature plans  
 - **[Reference](./docs/reference/)** - Technical guides and file references
-- **[Development](./docs/development/)** - Session notes and implementation details
+- **[Development](./docs/development/)** - Testing and implementation details
 
 See [docs/README.md](./docs/README.md) for the complete documentation index.
 
diff --git a/SESSION_SUMMARY.md b/SESSION_SUMMARY.md
deleted file mode 100644
index 04a079f..0000000
--- a/SESSION_SUMMARY.md
+++ /dev/null
@@ -1,437 +0,0 @@
-# 🎉 Development Session Summary
-
-**Date:** October 11, 2025  
-**Duration:** ~2 hours  
-**Branch:** mvp-phase-02  
-**Status:** ✅ Highly Productive - Phase 1 Complete + Tests Added
-
----
-
-## 🚀 Major Accomplishments
-
-### 1. ✅ Phase 1 MVP Implementation (Complete!)
-
-#### Enhanced Message System
-Implemented the **core differentiating feature** of the application:
-
-**Three Message Types:**
-- **🔒 Private Messages** - Character ↔ Storyteller only
-- **📢 Public Messages** - Visible to all players (action feed)
-- **🔀 Mixed Messages** - Public action + secret motive
-
-**Example Use Case:**
-```
-Player sends mixed message:
-  Public: "I shake hands with the merchant warmly"
-  Private: "While shaking, I try to pickpocket his coin purse"
-
-Result:
-  - All players see: "I shake hands with the merchant"
-  - Only storyteller sees: "I try to pickpocket his coin purse"
-```
-
-**Implementation:**
-- Updated backend `Message` model with visibility fields
-- Added `public_messages` array to `GameSession`
-- WebSocket routing for all message types
-- Frontend message composer with type selector
-- Separate public/private message displays
-
-#### AI-Assisted Responses (Quick Win)
-- Added "✨ AI Suggest" button in storyteller interface
-- Generates contextual responses using character's LLM
-- Editable before sending
-- Visual loading state
-
-### 2. ✅ Comprehensive Test Suite (88.9% Pass Rate)
-
-Created 54 tests across 3 test files:
-
-#### test_models.py (25 tests - ✅ 100% pass)
-- Message creation and validation
-- Character model testing
-- GameSession functionality
-- Message visibility logic
-- Character isolation verification
-
-#### test_api.py (23 tests - ✅ 100% pass)
-- Session CRUD endpoints
-- Character management
-- Available models endpoint
-- Error handling (404s)
-- State persistence
-
-#### test_websockets.py (23 tests - ⚠️ 74% pass)
-- WebSocket connections ✅
-- Message routing ⚠️ (6 async tests fail - TestClient limitation)
-- Storyteller responses ⚠️
-- Scene narration ⚠️
-- Connection management ✅
-
-**Coverage:** 78% (171/219 statements)
-
-**Test Quality:**
-- All critical paths tested
-- Error handling validated
-- Character isolation confirmed
-- Message visibility verified
-
-### 3. 📚 Documentation Created
-
-Created comprehensive documentation:
-
-1. **CURRENT_STATUS.md** - Complete feature overview
-2. **MVP_PROGRESS.md** - Detailed progress tracking
-3. **TESTING_GUIDE.md** - Manual test scenarios
-4. **TEST_RESULTS.md** - Test suite analysis
-5. **SESSION_SUMMARY.md** - This document
-
----
-
-## 📊 Statistics
-
-### Code Changes
-- **Files Modified:** 7
-- **Lines Added:** 1,398+
-- **Backend Changes:** `main.py` (message system)
-- **Frontend Changes:** `CharacterView.js`, `StorytellerView.js`
-- **CSS Added:** Public/private message styling
-- **Tests Added:** 54 comprehensive tests
-
-### Test Results
-- **Total Tests:** 54
-- **Passed:** 48 (88.9%)
-- **Failed:** 6 (WebSocket async - known limitation)
-- **Coverage:** 78%
-- **Status:** ✅ Production ready
-
-### Features Completed
-- ✅ Private messages
-- ✅ Public messages  
-- ✅ Mixed messages
-- ✅ AI-assisted responses
-- ✅ Public action feed
-- ✅ Message type selector
-- ✅ Visual distinction between types
-
----
-
-## 🛠️ Technical Highlights
-
-### Backend Architecture
-```python
-class Message(BaseModel):
-    visibility: str = "private"  # "public", "private", "mixed"
-    public_content: Optional[str] = None
-    private_content: Optional[str] = None
-
-class GameSession(BaseModel):
-    public_messages: List[Message] = []  # Shared feed
-```
-
-### Message Routing Logic
-```
-Private → Character's private history only
-Public → public_messages feed (broadcast to all)
-Mixed → Both public_messages AND private history
-```
-
-### Frontend Components
-- Message type selector (dropdown)
-- Public messages section (highlighted feed)
-- Private conversation section
-- Mixed message composer (dual textareas)
-- AI suggestion button (storyteller only)
-
----
-
-## 🎯 MVP Progress
-
-### Phase 1: Enhanced Message System ✅ COMPLETE
-- [x] Public/Private/Mixed message types
-- [x] Message type selector UI
-- [x] Message filtering logic
-- [x] WebSocket handling
-- [x] Public message broadcasting
-
-### Phase 2: Character Profile System ⏳ NEXT
-**Target:** 1-2 days
-
-**Features to Implement:**
-- Race selection (Human/Elf/Dwarf/Orc/Halfling)
-- Class selection (Warrior/Wizard/Cleric/Archer/Rogue)
-- Personality (Friendly/Serious/Doubtful/Measured)
-- Profile-based LLM prompts
-- Character import/export (JSON & PNG)
-- Avatar upload
-
-**Estimated Time:** 8-12 hours
-
-### Overall MVP Status
-- **Phase 1:** ✅ 100%
-- **Phase 2:** ⏳ 0%
-- **Phase 3:** ⏳ 0%
-- **Phase 4:** ⏳ 0%
-- **Phase 5:** ⏳ 0%
-- **Phase 6:** ⏳ 0%
-- **Overall:** ~8% (1/12 weeks)
-
----
-
-## 🐛 Known Issues
-
-### Minor Issues
-1. **Pydantic Deprecation Warnings** (10 occurrences)
-   - Fix: Replace `.dict()` with `.model_dump()`
-   - Time: 5 minutes
-   - Priority: Medium
-
-2. **Character Names in Public Feed**
-   - Public messages don't show which character sent them
-   - Time: 30 minutes
-   - Priority: Medium
-
-3. **WebSocket Test Failures** (6 tests)
-   - TestClient limitation, not code issue
-   - Production functionality verified
-   - Priority: Low (accept as-is)
-
-### Future Needs
-- Database persistence (SQLite → PostgreSQL)
-- Session authentication
-- Character profiles (Phase 2)
-- Game save/load
-
----
-
-## 📝 Files Changed
-
-### Backend
-- `main.py` - Message system, public_messages, routing
-
-### Frontend
-- `src/components/CharacterView.js` - Message composer, public feed
-- `src/components/StorytellerView.js` - AI suggest, public feed
-- `src/App.css` - Public/private message styling
-
-### Tests
-- `tests/test_models.py` - Model validation (25 tests)
-- `tests/test_api.py` - API endpoints (23 tests)
-- `tests/test_websockets.py` - WebSocket functionality (23 tests)
-- `pytest.ini` - Test configuration
-- `requirements.txt` - Added pytest dependencies
-
-### Documentation
-- `CURRENT_STATUS.md` - Feature overview
-- `MVP_PROGRESS.md` - Progress tracking
-- `TESTING_GUIDE.md` - Test scenarios
-- `TEST_RESULTS.md` - Test analysis
-- `SESSION_SUMMARY.md` - This file
-
----
-
-## 🎓 What We Learned
-
-### Technical Insights
-1. **Message Visibility is Key** - The public/private/mixed system is what makes this RPG app unique
-2. **WebSocket Testing is Hard** - TestClient has async limitations; integration tests needed
-3. **Pydantic V2 Changes** - Need to update `.dict()` to `.model_dump()`
-4. **Test-First Approach** - Having tests before Phase 2 will speed development
-
-### Design Decisions
-1. **Three Message Types** - Simple but powerful system
-2. **Separate Feeds** - Public messages in their own feed vs private conversation
-3. **Mixed Messages** - Most interesting feature for dramatic gameplay
-4. **AI Suggestions** - Quick win that adds huge value
-
-### Best Practices Applied
-- Comprehensive unit tests
-- Clear documentation
-- Git commit messages
-- Code coverage tracking
-- Error handling validation
-
----
-
-## ✅ Definition of Done
-
-### Phase 1 Checklist
-- [x] Message visibility fields added to models
-- [x] Public messages feed implemented
-- [x] WebSocket routing for all message types
-- [x] Frontend message type selector
-- [x] Public/private message displays
-- [x] AI suggestion button
-- [x] Visual distinction between types
-- [x] Tests written (88.9% pass rate)
-- [x] Documentation complete
-- [x] Code committed to git
-
-**Phase 1 Status:** ✅ **COMPLETE**
-
----
-
-## 🚀 Next Session Priorities
-
-### Immediate (Start of Next Session)
-
-1. **Fix Pydantic Warnings** (5 minutes)
-   ```python
-   # Replace in main.py
-   msg.dict() → msg.model_dump()
-   ```
-
-2. **Add Character Names to Public Feed** (30 minutes)
-   - Include character name in public message broadcasts
-   - Display: "Gandalf: I wave to the group"
-
-### Phase 2 Implementation (Main Work)
-
-3. **Character Profile Models** (2 hours)
-   - Add gender, race, class, personality fields
-   - Create profile prompt templates
-   - Update Character model
-
-4. **Character Creation Wizard** (4 hours)
-   - Multi-step form UI
-   - Dropdown selectors
-   - Profile preview
-   - Custom prompts section
-
-5. **Profile-Based LLM Prompts** (2 hours)
-   - Combine race + class + personality
-   - Inject into character LLM requests
-   - Test with different combinations
-
-6. **Character Import/Export** (3 hours)
-   - JSON export/import
-   - PNG with metadata (stretch goal)
-   - Profile validation
-
-7. **Phase 2 Tests** (2 hours)
-   - Test profile creation
-   - Test LLM prompt building
-   - Test import/export
-   - Aim for 80%+ coverage
-
-**Total Estimated Time for Phase 2:** 12-15 hours (1.5-2 days)
-
----
-
-## 💡 Recommendations
-
-### Technical
-1. ✅ **Tests First Approach** - We have good test coverage now
-2. 🔄 **Incremental Commits** - Keep committing as features complete
-3. 📝 **Update Documentation** - Keep docs in sync with code
-4. 🎯 **One Feature at a Time** - Finish Phase 2 before Phase 3
-
-### Process
-1. **Manual Testing** - Test the enhanced message system manually
-2. **Git Branches** - Stay on `mvp-phase-02` for Phase 2 work
-3. **Coverage Goals** - Maintain 75%+ test coverage
-4. **Documentation** - Update MVP_PROGRESS.md as you go
-
----
-
-## 📈 Success Metrics
-
-### Achieved Today
-- ✅ **Phase 1 Complete** - Core feature fully implemented
-- ✅ **54 Tests Written** - Comprehensive test coverage
-- ✅ **88.9% Pass Rate** - High quality tests
-- ✅ **78% Code Coverage** - Excellent for MVP
-- ✅ **5 Documentation Files** - Well-documented
-- ✅ **All Committed to Git** - Clean version control
-
-### Quality Indicators
-- Zero critical bugs
-- All core features working
-- Tests passing for critical paths
-- Documentation comprehensive
-- Code reviewed and committed
-
----
-
-## 🎉 Celebration Points!
-
-**Huge Wins Today:**
-1. 🎯 **Phase 1 MVP Feature Complete** - The message visibility system works beautifully
-2. 🧪 **Test Suite Established** - 54 tests give us confidence
-3. 📚 **Documentation Complete** - Easy to pick up next session
-4. 🚀 **Production Ready** - Both servers running with new features
-5. 💪 **Solid Foundation** - Ready for Phase 2 character profiles
-
-**This is excellent progress!** The enhanced message system is the heart of what makes this RPG app unique. Players can now perform public actions while keeping secrets - exactly what you need for dramatic gameplay.
-
----
-
-## 🔮 Looking Ahead
-
-### Next Session Goals
-1. Implement Phase 2 (Character Profiles)
-2. Add race/class/personality system
-3. Build character creation wizard
-4. Create profile-based LLM prompts
-5. Add import/export functionality
-
-### Future Phases
-- **Phase 3:** User mode interfaces (Player/Storyteller/Gamemaster)
-- **Phase 4:** AI automation (AI players & storytellers)
-- **Phase 5:** Database & game management
-- **Phase 6:** Polish & testing
-
-**The MVP roadmap is solid, and we're executing well!**
-
----
-
-## 📊 Final Stats
-
-| Metric | Value |
-|--------|-------|
-| **Session Duration** | ~2 hours |
-| **Features Completed** | Phase 1 + AI Suggest + Tests |
-| **Tests Written** | 54 |
-| **Test Pass Rate** | 88.9% |
-| **Code Coverage** | 78% |
-| **Lines of Code Added** | 1,398+ |
-| **Files Modified** | 7 |
-| **Documentation Pages** | 5 |
-| **Git Commits** | 1 major commit |
-| **MVP Progress** | 8% → 16% (Phase 1 done!) |
-
----
-
-## ✅ Session Complete!
-
-**Status:** ✅ **Highly Successful**
-
-We've completed Phase 1 of the MVP roadmap, added a comprehensive test suite with 88.9% pass rate, and created detailed documentation. The enhanced message system (private/public/mixed) is working perfectly - this is the core feature that makes your RPG app unique.
-
-**Ready for Phase 2!** 🚀
-
-The test suite gives us confidence to build character profiles knowing we won't break existing functionality. Great work!
-
----
-
-**Commands to Remember:**
-
-```bash
-# Run tests
-.venv/bin/pytest -v
-
-# Run specific test file
-.venv/bin/pytest tests/test_models.py -v
-
-# Run with coverage
-.venv/bin/pytest --cov=main --cov-report=html
-
-# Start application
-bash start.sh
-
-# Check servers
-curl http://localhost:8000/docs  # Backend API
-curl http://localhost:3000       # Frontend
-```
-
-**Next Session:** Start with character profile system implementation! 🎭
diff --git a/docs/README.md b/docs/README.md
index 0988115..4c6b6f0 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,66 +1,152 @@
-# 📚 Storyteller RPG - Documentation
+# 📚 Storyteller RPG Documentation
 
-Welcome to the Storyteller RPG documentation. All project documentation is organized here by category.
+Welcome to the Storyteller RPG documentation hub. All project documentation is organized here for easy navigation.
 
 ---
 
-## 📁 Documentation Structure
+## 📂 Documentation Structure
 
-### 🚀 [setup/](./setup/)
-**Getting started guides and quick references**
+### ✨ [Features](./features/)
 
-- **[QUICKSTART.md](./setup/QUICKSTART.md)** - 5-minute quick start guide
-- **[QUICK_REFERENCE.md](./setup/QUICK_REFERENCE.md)** - Quick reference for common tasks
+Comprehensive feature documentation with examples and guides.
 
-### 📋 [planning/](./planning/)
-**Product roadmaps and feature planning**
+- **[Features Overview](./features/README.md)** - Complete feature catalog
+- **[Demo Session Guide](./features/DEMO_SESSION.md)** - Using the pre-configured test session
+- **[Context-Aware Responses](./features/CONTEXTUAL_RESPONSE_FEATURE.md)** - Multi-character AI generation
+- **[Prompt Engineering](./features/PROMPT_IMPROVEMENTS.md)** - LLM prompt techniques
+- **[Bug Fixes](./features/FIXES_SUMMARY.md)** - Recent fixes and improvements
 
-- **[MVP_ROADMAP.md](./planning/MVP_ROADMAP.md)** - MVP feature requirements and roadmap
-- **[NEXT_STEPS.md](./planning/NEXT_STEPS.md)** - Detailed future development roadmap
-- **[PROJECT_PLAN.md](./planning/PROJECT_PLAN.md)** - Overall project planning and goals
+### 🚀 [Setup Guides](./setup/)
 
-### 📖 [reference/](./reference/)
-**Technical references and guides**
+Get started quickly with installation and configuration guides.
 
-- **[LLM_GUIDE.md](./reference/LLM_GUIDE.md)** - Guide to available LLM models
-- **[PROJECT_FILES_REFERENCE.md](./reference/PROJECT_FILES_REFERENCE.md)** - Complete file structure reference
+- **[Quickstart Guide](./setup/QUICKSTART.md)** - Step-by-step setup instructions
+- **[Quick Reference](./setup/QUICK_REFERENCE.md)** - Common commands and workflows
 
-### 🔧 [development/](./development/)
-**Development session notes and implementation details**
+### 📋 [Planning & Roadmap](./planning/)
 
-- **[SESSION_SUMMARY.md](./development/SESSION_SUMMARY.md)** - Complete development session summary
-- **[IMPLEMENTATION_SUMMARY.md](./development/IMPLEMENTATION_SUMMARY.md)** - Technical implementation details
+Project vision, milestones, and future plans.
+
+- **[Project Plan](./planning/PROJECT_PLAN.md)** - Overall project structure and goals
+- **[MVP Roadmap](./planning/MVP_ROADMAP.md)** - Minimum viable product phases
+- **[Next Steps](./planning/NEXT_STEPS.md)** - Immediate priorities and tasks
+
+### 🔧 [Development](./development/)
+
+Technical implementation details and testing.
+
+- **[MVP Progress](./development/MVP_PROGRESS.md)** - Current status and achievements
+- **[Testing Guide](./development/TESTING_GUIDE.md)** - How to test the application
+- **[Test Results](./development/TEST_RESULTS.md)** - Latest test results
+
+### 📖 [Reference](./reference/)
+
+Technical guides and comprehensive references.
+
+- **[LLM Guide](./reference/LLM_GUIDE.md)** - Working with different AI models
+- **[Project Files Reference](./reference/PROJECT_FILES_REFERENCE.md)** - Complete file structure
 
 ---
 
-## 🎯 Quick Navigation
+## 🔗 Quick Links
 
-**New to the project?**
-1. Start with the main [README.md](../README.md) in the root directory
-2. Follow [setup/QUICKSTART.md](./setup/QUICKSTART.md) to get running
-3. Review [planning/MVP_ROADMAP.md](./planning/MVP_ROADMAP.md) to understand the vision
+### For New Users
+1. ⚡ Start with [Quickstart Guide](./setup/QUICKSTART.md)
+2. 🎮 Try the [Demo Session](./features/DEMO_SESSION.md) (pre-configured!)
+3. 📖 Review [Features Overview](./features/README.md) to see what's possible
+4. 🤖 Check [LLM Guide](./reference/LLM_GUIDE.md) for model selection
 
-**Want to contribute?**
-1. Read [development/SESSION_SUMMARY.md](./development/SESSION_SUMMARY.md) for architecture
-2. Check [planning/NEXT_STEPS.md](./planning/NEXT_STEPS.md) for feature priorities
-3. Refer to [reference/PROJECT_FILES_REFERENCE.md](./reference/PROJECT_FILES_REFERENCE.md) for code navigation
+### For Developers
+1. 🔧 Read [MVP Progress](./development/MVP_PROGRESS.md) for current state
+2. 🧪 Check [Testing Guide](./development/TESTING_GUIDE.md)
+3. 📁 Review [Project Files Reference](./reference/PROJECT_FILES_REFERENCE.md)
+4. 🚀 Follow [Next Steps](./planning/NEXT_STEPS.md) for contribution areas
 
-**Looking for specific info?**
-- **Setup/Installation** → [setup/](./setup/)
-- **Features & Roadmap** → [planning/](./planning/)
-- **API/Models/Files** → [reference/](./reference/)
-- **Architecture** → [development/](./development/)
+### For Storytellers
+1. 🎭 See [Features Guide](./features/README.md) for all tools
+2. 🧠 Learn about [Context-Aware Responses](./features/CONTEXTUAL_RESPONSE_FEATURE.md)
+3. 💡 Use [Quick Reference](./setup/QUICK_REFERENCE.md) for common tasks
+4. 🎲 Start with [Demo Session](./features/DEMO_SESSION.md) for practice
 
 ---
 
-## 📊 Documentation Overview
+## 📊 Current Status (v0.2.0)
 
-| Category | Files | Purpose |
-|----------|-------|---------|
-| **Setup** | 2 | Getting started and quick references |
-| **Planning** | 3 | Roadmaps, feature plans, project goals |
-| **Reference** | 2 | Technical guides and file references |
-| **Development** | 2 | Session notes and implementation details |
+### ✅ Completed Features
+- Private/public/mixed messaging system
+- Context-aware AI response generator
+- Demo session with pre-configured characters
+- Real-time WebSocket communication
+- Multi-LLM support (GPT-4o, Claude, Llama, etc.)
+- AI-assisted storyteller suggestions
+- Session ID quick copy
+- Full conversation history
+
+### 🚧 Coming Soon
+- Database persistence
+- Character sheets & stats
+- Dice rolling mechanics
+- Combat system
+- Image generation
+- Voice messages
+
+See [MVP Roadmap](./planning/MVP_ROADMAP.md) for the complete timeline.
+
+---
+
+## 📝 Documentation Principles
+
+This documentation follows these principles:
+
+- **Progressive Disclosure**: Start simple, dive deeper as needed
+- **Always Current**: Updated with each feature implementation
+- **Example-Driven**: Real code examples and use cases
+- **Clear Structure**: Logical organization for easy navigation
+- **Feature-Focused**: Detailed guides for every feature
+
+---
+
+## 🎯 Documentation Map
+
+```
+docs/
+├── features/           ← Feature guides & examples
+│   ├── README.md
+│   ├── DEMO_SESSION.md
+│   ├── CONTEXTUAL_RESPONSE_FEATURE.md
+│   ├── PROMPT_IMPROVEMENTS.md
+│   └── FIXES_SUMMARY.md
+├── setup/              ← Installation & quick start
+│   ├── QUICKSTART.md
+│   └── QUICK_REFERENCE.md
+├── planning/           ← Roadmap & future plans
+│   ├── PROJECT_PLAN.md
+│   ├── MVP_ROADMAP.md
+│   └── NEXT_STEPS.md
+├── development/        ← Technical & testing docs
+│   ├── MVP_PROGRESS.md
+│   ├── TESTING_GUIDE.md
+│   └── TEST_RESULTS.md
+└── reference/          ← Technical references
+    ├── LLM_GUIDE.md
+    └── PROJECT_FILES_REFERENCE.md
+```
+
+---
+
+## 🤝 Contributing to Documentation
+
+Found a typo or want to improve the docs? Contributions are welcome!
+
+1. Documentation lives in the `docs/` folder
+2. Use clear, concise language
+3. Include examples where helpful
+4. Keep formatting consistent
+5. Update relevant indexes when adding new docs
+
+---
+
+**Need help?** Start with the [Quickstart Guide](./setup/QUICKSTART.md) or check the main [README](../README.md).
 
 ---
 
diff --git a/docs/development/IMPLEMENTATION_SUMMARY.md b/docs/development/IMPLEMENTATION_SUMMARY.md
deleted file mode 100644
index 71abbeb..0000000
--- a/docs/development/IMPLEMENTATION_SUMMARY.md
+++ /dev/null
@@ -1,126 +0,0 @@
-# Implementation Summary
-
-## ✅ Completed Features
-
-### Backend (`main.py`)
-- **Isolated Character Sessions**: Each character has a separate conversation history that only they and the storyteller can see
-- **Private WebSocket Channels**: 
-  - `/ws/character/{session_id}/{character_id}` - Character's private connection
-  - `/ws/storyteller/{session_id}` - Storyteller's master connection
-- **Message Routing**: Messages flow privately between storyteller and individual characters
-- **Scene Broadcasting**: Storyteller can narrate scenes visible to all characters
-- **Real-time Updates**: WebSocket events for character joins, messages, and responses
-- **Pending Response Tracking**: System tracks which characters are waiting for storyteller responses
-- **AI Suggestions** (Optional): Endpoint for AI-assisted storyteller response generation
-
-### Frontend Components
-
-#### 1. **SessionSetup.js**
-- Create new session (storyteller)
-- Join existing session (character)
-- Character creation with name, description, and personality
-- Beautiful gradient UI with modern styling
-
-#### 2. **CharacterView.js**
-- Private chat interface with storyteller
-- Real-time message delivery via WebSocket
-- Scene narration display
-- Conversation history preservation
-- Connection status indicator
-
-#### 3. **StorytellerView.js**
-- Dashboard showing all characters
-- Character list with pending response indicators
-- Click character to view their private conversation
-- Individual response system for each character
-- Scene narration broadcast to all characters
-- Visual indicators for pending messages
-
-### Styling (`App.css`)
-- Modern gradient theme (purple/blue)
-- Responsive design
-- Smooth animations and transitions
-- Clear visual hierarchy
-- Mobile-friendly layout
-
-### Documentation
-- **README.md**: Comprehensive guide with architecture, features, and API docs
-- **QUICKSTART.md**: Fast setup and testing guide
-- **.env.example**: Environment variable template
-
-## 🔐 Privacy Implementation
-
-The core requirement - **isolated character sessions** - is implemented through:
-
-1. **Separate Data Structures**: Each character has `conversation_history: List[Message]` 
-2. **WebSocket Isolation**: Separate WebSocket connections per character
-3. **Message Routing**: Messages only sent to intended recipient
-4. **Storyteller View**: Only storyteller can see all conversations
-5. **Scene Broadcast**: Shared narrations go to all, but conversations stay private
-
-## 🎯 Workflow
-
-```
-Character A → Storyteller: "I search the room"
-Character B → Storyteller: "I attack the guard"
-    ↓
-Storyteller sees both messages separately
-    ↓
-Storyteller → Character A: "You find a hidden key"
-Storyteller → Character B: "You miss your swing"
-    ↓
-Character A only sees their conversation
-Character B only sees their conversation
-```
-
-## 📁 File Structure
-
-```
-windsurf-project/
-├── main.py                      # FastAPI backend with WebSocket support
-├── requirements.txt             # Python dependencies
-├── .env.example                 # Environment template
-├── README.md                    # Full documentation
-├── QUICKSTART.md               # Quick start guide
-├── IMPLEMENTATION_SUMMARY.md   # This file
-└── frontend/
-    ├── package.json
-    └── src/
-        ├── App.js              # Main app router
-        ├── App.css             # All styling
-        └── components/
-            ├── SessionSetup.js      # Session creation/join
-            ├── CharacterView.js     # Character interface
-            └── StorytellerView.js   # Storyteller dashboard
-```
-
-## 🚀 To Run
-
-**Backend:**
-```bash
-python main.py
-```
-
-**Frontend:**
-```bash
-cd frontend && npm start
-```
-
-## 🎨 Design Decisions
-
-1. **WebSocket over REST**: Real-time bidirectional communication required for instant message delivery
-2. **In-Memory Storage**: Simple session management; can be replaced with database for production
-3. **Component-Based Frontend**: Separate views for different roles (setup, character, storyteller)
-4. **Message Model**: Includes sender, content, timestamp for rich conversation history
-5. **Pending Response Flag**: Helps storyteller track which characters need attention
-
-## 🔮 Future Enhancements
-
-- Database persistence (PostgreSQL/MongoDB)
-- User authentication
-- Character sheets with stats
-- Dice rolling system
-- Voice/audio support
-- Mobile apps
-- Multi-storyteller support
-- Group chat rooms (for party discussions)
diff --git a/docs/development/SESSION_SUMMARY.md b/docs/development/SESSION_SUMMARY.md
deleted file mode 100644
index 9c7263a..0000000
--- a/docs/development/SESSION_SUMMARY.md
+++ /dev/null
@@ -1,502 +0,0 @@
-# 📝 Development Session Summary
-
-**Date:** October 11, 2025
-**Project:** Storyteller RPG Application
-**Status:** ✅ Fully Functional MVP Complete
-
----
-
-## 🎯 Project Overview
-
-Built a **storyteller-centric roleplaying application** where multiple AI character bots or human players interact with a storyteller through **completely isolated, private conversations**.
-
-### Core Concept
-- **Characters communicate ONLY with the storyteller** (never with each other by default)
-- **Each character has separate memory/LLM sessions** - their responses are isolated
-- **Storyteller sees all conversations** but responds to each character individually
-- **Characters cannot see other characters' messages or responses**
-- Characters can use **different AI models** (GPT-4, Claude, Llama, etc.) giving each unique personalities
-
----
-
-## 🏗️ Architecture Built
-
-### Backend: FastAPI + WebSockets
-**File:** `/home/aodhan/projects/apps/storyteller/main.py` (398 lines)
-
-**Key Components:**
-1. **Data Models:**
-   - `GameSession` - Manages the game session and all characters
-   - `Character` - Stores character info, LLM model, and private conversation history
-   - `Message` - Individual message with sender, content, timestamp
-   - `ConnectionManager` - Handles WebSocket connections
-
-2. **WebSocket Endpoints:**
-   - `/ws/character/{session_id}/{character_id}` - Private character connection
-   - `/ws/storyteller/{session_id}` - Storyteller dashboard connection
-
-3. **REST Endpoints:**
-   - `POST /sessions/` - Create new game session
-   - `GET /sessions/{session_id}` - Get session details
-   - `POST /sessions/{session_id}/characters/` - Add character to session
-   - `GET /sessions/{session_id}/characters/{character_id}/conversation` - Get conversation history
-   - `POST /sessions/{session_id}/generate_suggestion` - AI-assisted storyteller responses
-   - `GET /models` - List available LLM models
-
-4. **LLM Integration:**
-   - **OpenAI**: GPT-4o, GPT-4 Turbo, GPT-3.5 Turbo
-   - **OpenRouter**: Claude 3.5, Llama 3.1, Gemini Pro, Mistral, Cohere, 100+ models
-   - `call_llm()` function routes to appropriate provider based on model ID
-   - Each character can use a different model
-
-5. **Message Flow:**
-   ```
-   Character sends message → WebSocket → Stored in Character.conversation_history
-                          ↓
-                    Forwarded to Storyteller
-                          ↓
-   Storyteller responds → WebSocket → Stored in Character.conversation_history
-                          ↓
-                    Sent ONLY to that Character
-   ```
-
-### Frontend: React
-**Files:** 
-- `frontend/src/App.js` - Main router component
-- `frontend/src/components/SessionSetup.js` (180 lines) - Session creation/joining
-- `frontend/src/components/CharacterView.js` (141 lines) - Character interface
-- `frontend/src/components/StorytellerView.js` (243 lines) - Storyteller dashboard
-- `frontend/src/App.css` (704 lines) - Complete styling
-
-**Key Features:**
-1. **SessionSetup Component:**
-   - Create new session (becomes storyteller)
-   - Join existing session (becomes character)
-   - Select LLM model for character
-   - Model selector fetches available models from backend
-
-2. **CharacterView Component:**
-   - Private conversation with storyteller
-   - WebSocket connection for real-time updates
-   - See scene narrations from storyteller
-   - Character info display (name, description, personality)
-   - Connection status indicator
-
-3. **StorytellerView Component:**
-   - Dashboard showing all characters
-   - Click character to view their private conversation
-   - Respond to characters individually
-   - Narrate scenes visible to all characters
-   - Pending response indicators (red badges)
-   - Character cards showing:
-     - Name, description, personality
-     - LLM model being used
-     - Message count
-     - Pending status
-
-4. **UI/UX Design:**
-   - Beautiful gradient purple theme
-   - Responsive design
-   - Real-time message updates
-   - Auto-scroll to latest messages
-   - Clear visual distinction between sent/received messages
-   - Session ID prominently displayed for sharing
-   - Empty states with helpful instructions
-
----
-
-## 🔑 Key Technical Decisions
-
-### 1. **Isolated Conversations (Privacy-First)**
-- Each `Character` object has its own `conversation_history: List[Message]`
-- Messages are never broadcast to all clients
-- WebSocket routing ensures messages only go to intended recipient
-- Storyteller has separate WebSocket endpoint to see all
-
-### 2. **Multi-LLM Support**
-- Characters choose model at creation time
-- Stored in `Character.llm_model` field
-- Backend dynamically routes API calls based on model prefix:
-  - `gpt-*` → OpenAI API
-  - Everything else → OpenRouter API
-- Enables creative gameplay with different AI personalities
-
-### 3. **In-Memory Storage (Current)**
-- `sessions: Dict[str, GameSession]` stores all active sessions
-- Fast and simple for MVP
-- **Limitation:** Data lost on server restart
-- **Next step:** Add database persistence (see NEXT_STEPS.md)
-
-### 4. **WebSocket-First Architecture**
-- Real-time bidirectional communication
-- Native WebSocket API (not socket.io)
-- JSON message format with `type` field for routing
-- Separate connections for characters and storyteller
-
-### 5. **Scene Narration System**
-- Storyteller can broadcast "scene" messages
-- Sent to all connected characters simultaneously
-- Stored in `GameSession.current_scene` and `scene_history`
-- Different from private character-storyteller messages
-
----
-
-## 📁 Project Structure
-
-```
-storyteller/
-├── main.py                      # FastAPI backend (398 lines)
-├── requirements.txt             # Python dependencies
-├── .env.example                 # API key template
-├── .env                        # Your API keys (gitignored)
-├── README.md                   # Comprehensive documentation
-├── QUICKSTART.md               # 5-minute setup guide
-├── NEXT_STEPS.md               # Future development roadmap
-├── SESSION_SUMMARY.md          # This file
-├── start.sh                    # Auto-start script
-├── dev.sh                      # Development mode script
-└── frontend/
-    ├── package.json            # Node dependencies
-    ├── public/
-    │   └── index.html          # HTML template
-    └── src/
-        ├── App.js              # Main router
-        ├── App.css             # All styles (704 lines)
-        ├── index.js            # React entry point
-        └── components/
-            ├── SessionSetup.js     # Session creation/joining
-            ├── CharacterView.js    # Character interface
-            └── StorytellerView.js  # Storyteller dashboard
-```
-
----
-
-## 🚀 How to Run
-
-### Quick Start (Automated)
-```bash
-cd /home/aodhan/projects/apps/storyteller
-chmod +x start.sh
-./start.sh
-```
-
-### Manual Start
-```bash
-# Terminal 1 - Backend
-cd /home/aodhan/projects/apps/storyteller
-source .venv/bin/activate  # or: source venv/bin/activate
-python main.py
-
-# Terminal 2 - Frontend
-cd /home/aodhan/projects/apps/storyteller/frontend
-npm start
-```
-
-### Environment Setup
-```bash
-# Copy example and add your API keys
-cp .env.example .env
-
-# Edit .env and add at least one:
-# OPENAI_API_KEY=sk-...          # For GPT models
-# OPENROUTER_API_KEY=sk-...      # For Claude, Llama, etc.
-```
-
----
-
-## 🔍 Important Implementation Details
-
-### WebSocket Message Types
-
-**Character → Storyteller:**
-```json
-{
-  "type": "message",
-  "content": "I search the room for clues"
-}
-```
-
-**Storyteller → Character:**
-```json
-{
-  "type": "storyteller_response",
-  "message": {
-    "id": "...",
-    "sender": "storyteller",
-    "content": "You find a hidden letter",
-    "timestamp": "2025-10-11T20:30:00"
-  }
-}
-```
-
-**Storyteller → All Characters:**
-```json
-{
-  "type": "narrate_scene",
-  "content": "The room grows dark as thunder rumbles"
-}
-```
-
-**Storyteller receives character message:**
-```json
-{
-  "type": "character_message",
-  "character_id": "uuid",
-  "character_name": "Aragorn",
-  "message": { ... }
-}
-```
-
-**Character joined notification:**
-```json
-{
-  "type": "character_joined",
-  "character": {
-    "id": "uuid",
-    "name": "Legolas",
-    "description": "...",
-    "llm_model": "gpt-4"
-  }
-}
-```
-
-### LLM Integration
-
-**Function:** `call_llm(model, messages, temperature, max_tokens)`
-
-**Routing Logic:**
-```python
-if model.startswith("gpt-") or model.startswith("o1-"):
-    # Use OpenAI client
-    response = await client.chat.completions.create(...)
-else:
-    # Use OpenRouter via httpx
-    response = await http_client.post("https://openrouter.ai/api/v1/chat/completions", ...)
-```
-
-**Available Models (as of this session):**
-- OpenAI: gpt-4o, gpt-4-turbo, gpt-4, gpt-3.5-turbo
-- Anthropic (via OpenRouter): claude-3.5-sonnet, claude-3-opus, claude-3-haiku
-- Meta: llama-3.1-70b, llama-3.1-8b
-- Google: gemini-pro-1.5
-- Mistral: mistral-large
-- Cohere: command-r-plus
-
----
-
-## 🎨 UI/UX Highlights
-
-### Color Scheme
-- Primary gradient: Purple (`#667eea` → `#764ba2`)
-- Background: White cards on gradient
-- Messages: Blue (sent) / Gray (received)
-- Pending indicators: Red badges
-- Status: Green (connected) / Gray (disconnected)
-
-### Key UX Features
-1. **Session ID prominently displayed** for easy sharing
-2. **Pending response badges** show storyteller which characters are waiting
-3. **Character cards** with all relevant info at a glance
-4. **Empty states** guide users on what to do next
-5. **Connection status** always visible
-6. **Auto-scroll** to latest message
-7. **Keyboard shortcuts** (Enter to send)
-8. **Model selector** with descriptions helping users choose
-
----
-
-## 🐛 Known Limitations & TODO
-
-### Current Limitations
-1. **No persistence** - Sessions lost on server restart
-2. **No authentication** - Anyone with session ID can join
-3. **No message editing/deletion** - Messages are permanent
-4. **No character limit** on messages (could be abused)
-5. **No rate limiting** - API calls not throttled
-6. **No offline support** - Requires active connection
-7. **No mobile optimization** - Works but could be better
-8. **No sound notifications** - Easy to miss new messages
-
-### Security Considerations
-- **CORS is wide open** (`allow_origins=["*"]`) - Restrict in production
-- **No input validation** on message content - Add sanitization
-- **API keys in environment** - Good, but consider secrets manager
-- **No session expiration** - Sessions live forever in memory
-- **WebSocket not authenticated** - Anyone with session ID can connect
-
-### Performance Considerations
-- **In-memory storage** - Won't scale to many sessions
-- **No message pagination** - All history loaded at once
-- **No connection pooling** - Each character = new WebSocket
-- **No caching** - LLM calls always go to API
-
----
-
-## 💡 What Makes This Special
-
-### Unique Features
-1. **Each character uses a different AI model** - Creates emergent gameplay
-2. **Completely private conversations** - True secret communication
-3. **Storyteller-centric design** - Built for tabletop RPG flow
-4. **Real-time updates** - Feels like a chat app
-5. **Model flexibility** - 100+ LLMs via OpenRouter
-6. **Zero configuration** - Works out of the box
-
-### Design Philosophy
-- **Storyteller is the hub** - All communication flows through them
-- **Privacy first** - Characters truly can't see each other's messages
-- **Flexibility** - Support for any LLM model
-- **Simplicity** - Clean, intuitive interface
-- **Real-time** - No page refreshes needed
-
----
-
-## 🔄 Context for Continuing Development
-
-### If Starting a New Chat Session
-
-**What works:**
-- ✅ Backend fully functional with all endpoints
-- ✅ Frontend complete with all views
-- ✅ WebSocket communication working
-- ✅ Multi-LLM support implemented
-- ✅ Scene narration working
-- ✅ Private conversations isolated correctly
-
-**Quick test to verify everything:**
-```bash
-# 1. Start servers
-./start.sh
-
-# 2. Create session as storyteller
-# 3. Join session as character (new browser/incognito)
-# 4. Send message from character
-# 5. Verify storyteller sees it
-# 6. Respond from storyteller
-# 7. Verify character receives it
-# 8. Test scene narration
-```
-
-**Common issues:**
-- **Port 8000/3000 already in use** - `start.sh` kills existing processes
-- **WebSocket won't connect** - Check backend is running, check browser console
-- **LLM not responding** - Verify API keys in `.env`
-- **npm/pip dependencies missing** - Run install commands
-
-### Files to Modify for Common Tasks
-
-**Add new WebSocket message type:**
-1. Update message handler in `main.py` (character or storyteller endpoint)
-2. Update frontend component to send/receive new type
-
-**Add new REST endpoint:**
-1. Add `@app.post()` or `@app.get()` in `main.py`
-2. Add fetch call in appropriate frontend component
-
-**Modify UI:**
-1. Edit component in `frontend/src/components/`
-2. Edit styles in `frontend/src/App.css`
-
-**Add new LLM provider:**
-1. Update `call_llm()` function in `main.py`
-2. Update `get_available_models()` endpoint
-3. Add model options in `SessionSetup.js`
-
----
-
-## 📊 Project Statistics
-
-- **Total Lines of Code:** ~1,700
-- **Backend:** ~400 lines (Python/FastAPI)
-- **Frontend:** ~1,300 lines (React/JavaScript/CSS)
-- **Time to MVP:** 1 session
-- **Dependencies:** 8 Python packages, 5 npm packages (core)
-- **API Endpoints:** 6 REST + 2 WebSocket
-- **React Components:** 3 main + 1 router
-- **Supported LLMs:** 15+ models across 6 providers
-
----
-
-## 🎓 Learning Resources Used
-
-### Technologies
-- **FastAPI:** https://fastapi.tiangolo.com/
-- **WebSockets:** https://developer.mozilla.org/en-US/docs/Web/API/WebSocket
-- **React:** https://react.dev/
-- **OpenAI API:** https://platform.openai.com/docs
-- **OpenRouter:** https://openrouter.ai/docs
-
-### Key Concepts Implemented
-- WebSocket bidirectional communication
-- Async Python with FastAPI
-- React state management with hooks
-- Multi-provider LLM routing
-- Real-time message delivery
-- Isolated conversation contexts
-
----
-
-## 📝 Notes for Future You
-
-### Why certain decisions were made:
-- **WebSocket instead of polling:** Real-time updates without constant HTTP requests
-- **Separate endpoints for character/storyteller:** Clean separation of concerns, different message types
-- **In-memory storage first:** Fastest MVP, can migrate to DB later
-- **Multi-LLM from start:** Makes the app unique and interesting
-- **No socket.io:** Native WebSocket simpler for this use case
-- **Private conversations:** Core feature that differentiates from group chat apps
-
-### What went smoothly:
-- FastAPI made WebSocket implementation easy
-- React components stayed clean and modular
-- OpenRouter integration was straightforward
-- UI came together nicely with gradients
-
-### What could be improved:
-- Database persistence is the obvious next step
-- Error handling could be more robust
-- Mobile experience needs work
-- Need proper authentication system
-- Testing suite would be valuable
-
----
-
-## 🚀 Recommended Next Actions
-
-**Immediate (Next Session):**
-1. Test the app end-to-end to ensure everything works after IDE crash
-2. Add AI suggestion button to storyteller UI (backend ready, just needs frontend)
-3. Implement session persistence with SQLite
-
-**Short Term (This Week):**
-4. Add dice rolling system
-5. Add typing indicators
-6. Improve error messages
-
-**Medium Term (This Month):**
-7. Add authentication
-8. Implement character sheets
-9. Add image generation for scenes
-
-See **NEXT_STEPS.md** for detailed roadmap with priorities and implementation notes.
-
----
-
-## 📞 Session Handoff Checklist
-
-- ✅ All files verified and up-to-date
-- ✅ Architecture documented
-- ✅ Key decisions explained
-- ✅ Next steps outlined
-- ✅ Common issues documented
-- ✅ Code structure mapped
-- ✅ API contracts specified
-- ✅ Testing instructions provided
-
-**You're ready to continue development!** 🎉
-
----
-
-*Generated: October 11, 2025*
-*Project Location: `/home/aodhan/projects/apps/storyteller`*
-*Status: Production-ready MVP*
diff --git a/TESTING_GUIDE.md b/docs/development/TESTING_GUIDE.md
similarity index 100%
rename from TESTING_GUIDE.md
rename to docs/development/TESTING_GUIDE.md
diff --git a/TEST_RESULTS.md b/docs/development/TEST_RESULTS.md
similarity index 100%
rename from TEST_RESULTS.md
rename to docs/development/TEST_RESULTS.md
diff --git a/CONTEXTUAL_RESPONSE_FEATURE.md b/docs/features/CONTEXTUAL_RESPONSE_FEATURE.md
similarity index 100%
rename from CONTEXTUAL_RESPONSE_FEATURE.md
rename to docs/features/CONTEXTUAL_RESPONSE_FEATURE.md
diff --git a/DEMO_SESSION.md b/docs/features/DEMO_SESSION.md
similarity index 100%
rename from DEMO_SESSION.md
rename to docs/features/DEMO_SESSION.md
diff --git a/FIXES_SUMMARY.md b/docs/features/FIXES_SUMMARY.md
similarity index 100%
rename from FIXES_SUMMARY.md
rename to docs/features/FIXES_SUMMARY.md
diff --git a/PROMPT_IMPROVEMENTS.md b/docs/features/PROMPT_IMPROVEMENTS.md
similarity index 100%
rename from PROMPT_IMPROVEMENTS.md
rename to docs/features/PROMPT_IMPROVEMENTS.md
diff --git a/docs/features/README.md b/docs/features/README.md
new file mode 100644
index 0000000..fdd9776
--- /dev/null
+++ b/docs/features/README.md
@@ -0,0 +1,179 @@
+# 🎭 Features Documentation
+
+Detailed documentation for all Storyteller RPG features.
+
+---
+
+## Feature Guides
+
+### Core Features
+
+#### [Demo Session](./DEMO_SESSION.md)
+Pre-configured test session that auto-loads on startup. Includes two characters (Bargin & Willow) and "The Cursed Tavern" adventure. Perfect for development and testing.
+
+**Quick Access:**
+- Session ID: `demo-session-001`
+- One-click buttons on home page
+- No setup required
+
+---
+
+#### [Context-Aware Response Generator](./CONTEXTUAL_RESPONSE_FEATURE.md)
+AI-powered tool for storytellers to generate responses considering multiple characters' actions simultaneously.
+
+**Key Features:**
+- Multi-character selection
+- Scene descriptions (broadcast to all)
+- Individual responses (private to each)
+- Automatic parsing and distribution
+- Smart context building
+
+---
+
+### Technical Documentation
+
+#### [Prompt Engineering Improvements](./PROMPT_IMPROVEMENTS.md)
+Details on how we improved the LLM prompts for reliable individual response parsing using the `[CharacterName]` format.
+
+**Topics Covered:**
+- Square bracket format rationale
+- Regex parsing patterns
+- System prompt enhancements
+- Edge case handling
+
+---
+
+#### [Bug Fixes Summary](./FIXES_SUMMARY.md)
+Comprehensive list of bugs fixed in the latest release.
+
+**Fixed Issues:**
+- Character chat history showing only recent messages
+- Pydantic deprecation warnings (.dict → .model_dump)
+- WebSocket manager reference errors
+- Session ID copy functionality
+
+---
+
+## Feature Overview by Category
+
+### For Storytellers 🎲
+
+| Feature | Description | Status |
+|---------|-------------|--------|
+| **Session Management** | Create/join sessions, manage characters | ✅ Complete |
+| **Scene Narration** | Broadcast scene descriptions to all players | ✅ Complete |
+| **Private Responses** | Send individual messages to characters | ✅ Complete |
+| **AI Suggestions** | Get AI-generated response suggestions | ✅ Complete |
+| **Context-Aware Generator** | Generate responses considering multiple characters | ✅ Complete |
+| **Pending Message Tracking** | See which characters need responses | ✅ Complete |
+| **Demo Session** | Pre-loaded test scenario for quick start | ✅ Complete |
+
+### For Players 🎭
+
+| Feature | Description | Status |
+|---------|-------------|--------|
+| **Character Creation** | Define name, description, personality | ✅ Complete |
+| **Private Messages** | Send private messages to storyteller | ✅ Complete |
+| **Public Actions** | Broadcast actions visible to all players | ✅ Complete |
+| **Mixed Messages** | Public action + private thoughts | ✅ Complete |
+| **Scene Viewing** | See current scene description | ✅ Complete |
+| **Public Feed** | View all players' public actions | ✅ Complete |
+| **Conversation History** | Full chat log with storyteller | ✅ Complete |
+
+### Message System 📨
+
+| Feature | Description | Status |
+|---------|-------------|--------|
+| **Private Messages** | One-on-one conversation | ✅ Complete |
+| **Public Messages** | Visible to all players | ✅ Complete |
+| **Mixed Messages** | Public + private components | ✅ Complete |
+| **Real-time Updates** | WebSocket-based live updates | ✅ Complete |
+| **Message Persistence** | In-memory storage (session lifetime) | ✅ Complete |
+
+### AI Integration 🤖
+
+| Feature | Description | Status |
+|---------|-------------|--------|
+| **Multiple LLM Support** | GPT-4o, GPT-4, GPT-3.5, Claude, Llama | ✅ Complete |
+| **AI Response Suggestions** | Quick response generation | ✅ Complete |
+| **Context-Aware Generation** | Multi-character context building | ✅ Complete |
+| **Structured Output Parsing** | [CharacterName] format parsing | ✅ Complete |
+| **Temperature Control** | Creative vs. focused responses | ✅ Complete |
+
+---
+
+## Coming Soon 🚀
+
+### Planned Features
+
+- **Database Persistence** - Save sessions and characters permanently
+- **Character Sheets** - Stats, inventory, abilities
+- **Dice Rolling** - Built-in dice mechanics
+- **Combat System** - Turn-based combat management
+- **Image Generation** - AI-generated scene/character images
+- **Voice Messages** - Audio message support
+- **Session Export** - Export conversation logs
+- **User Authentication** - Account system with saved preferences
+
+---
+
+## Feature Request Process
+
+Want to suggest a new feature?
+
+1. **Check existing documentation** - Feature might already exist
+2. **Review roadmap** - Check if it's already planned (see [MVP_ROADMAP.md](../planning/MVP_ROADMAP.md))
+3. **Create an issue** - Describe the feature and use case
+4. **Discuss implementation** - We'll evaluate feasibility and priority
+
+---
+
+## Version History
+
+### v0.2.0 - Context-Aware Features (October 2025)
+- ✅ Context-aware response generator
+- ✅ Demo session with pre-configured characters
+- ✅ Improved prompt engineering for parsing
+- ✅ Bug fixes (chat history, Pydantic warnings)
+- ✅ Session ID copy button
+
+### v0.1.0 - MVP Phase 1 (October 2025)
+- ✅ Basic session management
+- ✅ Character creation and joining
+- ✅ Private/public/mixed messaging
+- ✅ Real-time WebSocket communication
+- ✅ Scene narration
+- ✅ AI-assisted responses
+- ✅ Multiple LLM support
+
+---
+
+## Documentation Structure
+
+```
+docs/
+├── features/           ← You are here
+│   ├── README.md
+│   ├── DEMO_SESSION.md
+│   ├── CONTEXTUAL_RESPONSE_FEATURE.md
+│   ├── PROMPT_IMPROVEMENTS.md
+│   └── FIXES_SUMMARY.md
+├── development/
+│   ├── MVP_PROGRESS.md
+│   ├── TESTING_GUIDE.md
+│   └── TEST_RESULTS.md
+├── planning/
+│   ├── MVP_ROADMAP.md
+│   ├── PROJECT_PLAN.md
+│   └── NEXT_STEPS.md
+├── setup/
+│   ├── QUICKSTART.md
+│   └── QUICK_REFERENCE.md
+└── reference/
+    ├── PROJECT_FILES_REFERENCE.md
+    └── LLM_GUIDE.md
+```
+
+---
+
+**Need help?** Check the [main README](../../README.md) or the [Quick Start Guide](../setup/QUICKSTART.md).