Initial commit

docs/setup/QUICKSTART.md

@@ -0,0 +1,96 @@
+# 🚀 Quick Start Guide
+
+## Installation (5 minutes)
+
+### 1. Backend Setup
+```bash
+# Install Python dependencies
+pip install -r requirements.txt
+
+# Create environment file (optional - only for AI suggestions)
+cp .env.example .env
+# Edit .env and add your OpenAI API key if desired
+```
+
+### 2. Frontend Setup
+```bash
+cd frontend
+npm install
+cd ..
+```
+
+## Running the App
+
+### Terminal 1 - Backend
+```bash
+python main.py
+# Server runs on http://localhost:8000
+```
+
+### Terminal 2 - Frontend
+```bash
+cd frontend
+npm start
+# Opens browser at http://localhost:3000
+```
+
+## First Session
+
+### As Storyteller:
+1. Open http://localhost:3000
+2. Enter session name → "My Adventure"
+3. Click "Create New Session"
+4. **Copy the session ID** (shows at top of dashboard)
+5. Share session ID with players
+
+### As Player:
+1. Open http://localhost:3000 (in different browser/tab)
+2. Paste the session ID
+3. Enter character details:
+   - Name: "Aragorn"
+   - Description: "A ranger from the north"
+   - Personality: "Brave and noble"
+4. Click "Join Session"
+5. Send private message to storyteller
+
+### Storyteller Dashboard:
+- See new character appear in left panel
+- Click character name to view their private message
+- Type response in bottom text area
+- Click "Send Private Response"
+- Use scene narration to broadcast to all characters
+
+## Key Features
+
+✅ **Private Messaging**: Each character's conversation is completely isolated
+✅ **Real-time Updates**: WebSocket communication for instant delivery
+✅ **Scene Narration**: Broadcast story updates to all characters
+✅ **Pending Indicators**: Red badges show which characters need responses
+✅ **Conversation History**: Full chat history preserved per character
+
+## Troubleshooting
+
+**Backend won't start?**
+- Check Python version: `python --version` (needs 3.8+)
+- Install dependencies: `pip install -r requirements.txt`
+
+**Frontend won't start?**
+- Check Node version: `node --version` (needs 16+)
+- Install dependencies: `cd frontend && npm install`
+
+**WebSocket not connecting?**
+- Ensure backend is running on port 8000
+- Check browser console for errors
+- Try refreshing the page
+
+**Characters can't join?**
+- Verify session ID is correct
+- Ensure storyteller session is active
+- Check that backend is running
+
+## Next Steps
+
+- Invite multiple players to test isolated conversations
+- Try narrating scenes visible to all characters
+- Experiment with rich character descriptions
+- Optionally add OpenAI API key for AI-assisted storyteller suggestions