feat: Implement Phase 5 Quest System (100% complete)

Add YAML-driven quest system with context-aware offering: Core Implementation: - Quest data models (Quest, QuestObjective, QuestReward, QuestTriggers) - QuestService for YAML loading and caching - QuestEligibilityService with level, location, and probability filtering - LoreService stub (MockLoreService) ready for Phase 6 Weaviate integration Quest Content: - 5 example quests across difficulty tiers (2 easy, 2 medium, 1 hard) - Quest-centric design: quests define their NPC givers - Location-based probability weights for natural quest offering AI Integration: - Quest offering section in npc_dialogue.j2 template - Response parser extracts [QUEST_OFFER:quest_id] markers - AI naturally weaves quest offers into NPC conversations API Endpoints: - POST /api/v1/quests/accept - Accept quest offer - POST /api/v1/quests/decline - Decline quest offer - POST /api/v1/quests/progress - Update objective progress - POST /api/v1/quests/complete - Complete quest, claim rewards - POST /api/v1/quests/abandon - Abandon active quest - GET /api/v1/characters/{id}/quests - List character quests - GET /api/v1/quests/{quest_id} - Get quest details Frontend: - Quest tracker sidebar with HTMX integration - Quest offer modal for accept/decline flow - Quest detail modal for viewing progress - Combat service integration for kill objective tracking Testing: - Unit tests for Quest models and serialization - Integration tests for full quest lifecycle - Comprehensive test coverage for eligibility service Documentation: - Reorganized docs into /docs/phases/ structure - Added Phase 5-12 planning documents - Updated ROADMAP.md with new structure 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-29 15:42:55 -06:00
parent e7e329e6ed
commit df26abd207
42 changed files with 8421 additions and 2227 deletions
--- a/docs/phases/Phase10-Deployment.md
+++ b/docs/phases/Phase10-Deployment.md
@@ -0,0 +1,277 @@
+# Phase 10: PWA & Deployment
+
+**Goal:** Deploy to production as Progressive Web App
+**Priority:** High
+**Status:** Not Started
+**Last Updated:** November 29, 2025
+
+---
+
+## Overview
+
+Prepare the application for production deployment as a Progressive Web App (PWA) with offline support, proper infrastructure, monitoring, and security hardening.
+
+**Key Goals:**
+- PWA with installability and offline support
+- Production server setup (Nginx + Gunicorn)
+- Monitoring and alerting (Sentry, uptime)
+- Backup and disaster recovery
+- Security audit and hardening
+
+---
+
+## Task Groups
+
+### PWA Setup (4 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 10.1 | Create PWA manifest | ⬜ | `static/manifest.json` - name, icons, theme |
+| 10.2 | Create service worker | ⬜ | `static/sw.js` - caching strategy, offline support |
+| 10.3 | Create PWA icons | ⬜ | Various sizes: 72, 96, 128, 144, 152, 192, 384, 512 |
+| 10.4 | **Checkpoint:** Test PWA installation | ⬜ | Install on mobile, verify offline behavior |
+
+**Manifest Example:**
+```json
+{
+  "name": "Code of Conquest",
+  "short_name": "CoC",
+  "description": "AI-powered D&D adventure game",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#1a1a2e",
+  "theme_color": "#c9a227",
+  "icons": [
+    { "src": "/static/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
+    { "src": "/static/icons/icon-512.png", "sizes": "512x512", "type": "image/png" }
+  ]
+}
+```
+
+**Deliverable:** Installable PWA
+
+---
+
+### Production Environment (4 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 10.5 | Set up production server | ⬜ | VPS/cloud instance, domain, SSL |
+| 10.6 | Configure Nginx reverse proxy | ⬜ | SSL termination, static file serving |
+| 10.7 | Configure Gunicorn | ⬜ | 4+ workers, production settings |
+| 10.8 | Set up production Redis | ⬜ | Persistent storage, proper auth |
+
+**Nginx Configuration (Example):**
+```nginx
+server {
+    listen 443 ssl http2;
+    server_name codeofconquest.com;
+
+    ssl_certificate /etc/letsencrypt/live/codeofconquest.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/codeofconquest.com/privkey.pem;
+
+    location /static {
+        alias /var/www/coc/public_web/static;
+        expires 1y;
+    }
+
+    location /api {
+        proxy_pass http://127.0.0.1:5000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    location / {
+        proxy_pass http://127.0.0.1:5001;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+```
+
+**Deliverable:** Production server running
+
+---
+
+### Background Workers (3 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 10.9 | Set up RQ workers (production) | ⬜ | Systemd services, auto-restart |
+| 10.10 | Configure worker monitoring | ⬜ | RQ dashboard or custom monitoring |
+| 10.11 | Test job processing under load | ⬜ | Verify workers handle concurrent AI tasks |
+
+**Systemd Service (Example):**
+```ini
+[Unit]
+Description=RQ Worker for Code of Conquest
+After=redis.service
+
+[Service]
+User=www-data
+WorkingDirectory=/var/www/coc/api
+ExecStart=/var/www/coc/api/venv/bin/rq worker ai_tasks combat_tasks
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+
+**Deliverable:** Reliable background job processing
+
+---
+
+### Monitoring & Alerting (4 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 10.12 | Set up Sentry for error tracking | ⬜ | API and web frontend integration |
+| 10.13 | Set up uptime monitoring | ⬜ | External service (UptimeRobot, Better Uptime) |
+| 10.14 | Configure AI cost monitoring | ⬜ | Daily spend alerts, tier limit tracking |
+| 10.15 | **Checkpoint:** Verify alerting works | ⬜ | Trigger test alert, verify notification |
+
+**Deliverable:** Comprehensive monitoring
+
+---
+
+### Backup & Security (4 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 10.16 | Set up daily Appwrite backups | ⬜ | Automated backup to cloud storage |
+| 10.17 | Perform security audit | ⬜ | OWASP checklist, endpoint review |
+| 10.18 | Configure rate limiting (production) | ⬜ | Flask-Limiter with production limits |
+| 10.19 | Harden server security | ⬜ | Firewall, SSH keys, fail2ban |
+
+**Security Checklist:**
+- [ ] All endpoints require authentication where needed
+- [ ] Input validation on all user inputs
+- [ ] SQL/NoSQL injection prevention
+- [ ] XSS prevention (output encoding)
+- [ ] CSRF protection
+- [ ] Rate limiting on AI endpoints
+- [ ] Secrets in environment variables (not code)
+- [ ] HTTPS enforced everywhere
+- [ ] Security headers (CSP, HSTS, etc.)
+
+**Deliverable:** Secured production environment
+
+---
+
+### Deployment Automation (3 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 10.20 | Create deployment script | ⬜ | `scripts/deploy.sh` - pull, build, restart |
+| 10.21 | Write deployment documentation | ⬜ | Update `/docs/DEPLOYMENT.md` |
+| 10.22 | **Final Checkpoint:** Deploy to production | ⬜ | Go live! |
+
+**Deployment Script (Example):**
+```bash
+#!/bin/bash
+set -e
+
+echo "Pulling latest code..."
+git pull origin master
+
+echo "Updating API..."
+cd /var/www/coc/api
+source venv/bin/activate
+pip install -r requirements.txt
+sudo systemctl restart coc-api
+sudo systemctl restart coc-worker
+
+echo "Updating Web..."
+cd /var/www/coc/public_web
+source venv/bin/activate
+pip install -r requirements.txt
+sudo systemctl restart coc-web
+
+echo "Deployment complete!"
+```
+
+**Deliverable:** Automated deployment process
+
+---
+
+## Files to Create/Modify
+
+**New Files:**
+- `/public_web/static/manifest.json`
+- `/public_web/static/sw.js`
+- `/public_web/static/icons/*.png` (various sizes)
+- `/scripts/deploy.sh`
+- `/scripts/backup.sh`
+- `/config/nginx/coc.conf` (example Nginx config)
+- `/config/systemd/coc-api.service`
+- `/config/systemd/coc-web.service`
+- `/config/systemd/coc-worker.service`
+
+**Modified Files:**
+- `/public_web/templates/base.html` - PWA meta tags, manifest link
+- `/docs/DEPLOYMENT.md` - Production deployment guide
+- `/api/app/__init__.py` - Sentry integration
+- `/public_web/app/__init__.py` - Sentry integration
+
+---
+
+## Testing Criteria
+
+### PWA Testing
+- [ ] Manifest loads correctly
+- [ ] Service worker registers
+- [ ] App installable on mobile
+- [ ] Offline page displays when disconnected
+- [ ] PWA icons display correctly
+
+### Production Testing
+- [ ] HTTPS works correctly
+- [ ] API accessible via domain
+- [ ] Web frontend accessible via domain
+- [ ] Static files served correctly
+- [ ] Background workers processing jobs
+
+### Security Testing
+- [ ] Unauthorized access blocked
+- [ ] Rate limiting working
+- [ ] No sensitive data in responses
+- [ ] Security headers present
+
+### Monitoring Testing
+- [ ] Sentry capturing errors
+- [ ] Uptime monitoring active
+- [ ] Alerts trigger correctly
+
+---
+
+## Success Criteria
+
+- [ ] PWA installable and functional
+- [ ] Production server running with SSL
+- [ ] Background workers processing reliably
+- [ ] Monitoring and alerting active
+- [ ] Daily backups running
+- [ ] Security audit passed
+- [ ] Deployment automated
+
+---
+
+## Dependencies
+
+**Requires (from earlier phases):**
+- All core features complete
+- Frontend polish complete
+
+---
+
+## Task Summary
+
+| Group | Tasks | Checkpoints |
+|-------|-------|-------------|
+| PWA Setup | 3 | 1 |
+| Production Environment | 4 | 0 |
+| Background Workers | 3 | 0 |
+| Monitoring & Alerting | 3 | 1 |
+| Backup & Security | 4 | 0 |
+| Deployment Automation | 2 | 1 |
+| **Total** | **19** | **3** |
--- a/docs/phases/Phase11-BetaTesting.md
+++ b/docs/phases/Phase11-BetaTesting.md
@@ -0,0 +1,210 @@
+# Phase 11: Beta Testing & Iteration
+
+**Goal:** Gather feedback, fix issues, balance gameplay
+**Priority:** High
+**Status:** Not Started
+**Last Updated:** November 29, 2025
+
+---
+
+## Overview
+
+Launch a closed beta to gather real user feedback, identify bugs, balance gameplay mechanics, and optimize performance before public launch.
+
+**Key Goals:**
+- Recruit 10-20 beta testers
+- Systematic feedback collection
+- Bug fixing and stabilization
+- Combat and economy balancing
+- Performance optimization
+- AI prompt improvements
+
+---
+
+## Task Groups
+
+### Beta Recruitment (3 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 11.1 | Create beta signup form | ⬜ | Collect email, gaming experience, availability |
+| 11.2 | Recruit 10-20 beta testers | ⬜ | Friends, communities, Discord |
+| 11.3 | Create beta tester onboarding | ⬜ | Welcome email, how to give feedback, known issues |
+
+**Beta Tester Profile:**
+- Mix of casual and hardcore gamers
+- Some D&D/RPG experience helpful
+- Willing to provide detailed feedback
+- Available for 1-2 weeks of testing
+
+**Deliverable:** Active beta tester group
+
+---
+
+### Feedback Collection (3 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 11.4 | Create feedback form | ⬜ | Bug reports, suggestions, ratings |
+| 11.5 | Set up Discord server for testers | ⬜ | Channels: bugs, suggestions, general |
+| 11.6 | **Checkpoint:** Collect first round of feedback | ⬜ | After 3-5 days of testing |
+
+**Feedback Categories:**
+- **Bugs:** Crashes, errors, broken features
+- **UX Issues:** Confusing UI, unclear instructions
+- **Balance:** Too easy, too hard, unfair
+- **Suggestions:** Feature requests, improvements
+- **AI Quality:** Narrative quality, NPC responses
+
+**Deliverable:** Organized feedback pipeline
+
+---
+
+### Monitoring & Analysis (3 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 11.7 | Monitor Sentry error logs daily | ⬜ | Prioritize critical and frequent errors |
+| 11.8 | Monitor AI costs | ⬜ | Track daily spending, adjust limits if needed |
+| 11.9 | Analyze usage patterns | ⬜ | Popular features, drop-off points, session length |
+
+**Deliverable:** Data-driven insights
+
+---
+
+### Bug Fixing (3 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 11.10 | Triage and prioritize bugs | ⬜ | Critical → High → Medium → Low |
+| 11.11 | Fix critical and high priority bugs | ⬜ | Game-breaking issues first |
+| 11.12 | Fix medium priority bugs | ⬜ | UX issues, minor glitches |
+
+**Priority Definitions:**
+- **Critical:** Game unplayable, data loss, security issues
+- **High:** Major feature broken, frequent crashes
+- **Medium:** Minor feature broken, visual glitches
+- **Low:** Edge cases, cosmetic issues
+
+**Deliverable:** Stable, bug-free experience
+
+---
+
+### Balancing (3 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 11.13 | Balance combat difficulty | ⬜ | Adjust enemy HP, damage, encounter rates |
+| 11.14 | Balance economy | ⬜ | Gold rewards, item prices, quest rewards |
+| 11.15 | **Checkpoint:** Verify balance feels right | ⬜ | Tester feedback on difficulty |
+
+**Balancing Metrics:**
+- Average combat win rate: 70-80%
+- Time to level up: ~30 minutes per level
+- Gold earned vs. needed for upgrades
+- Quest completion rates
+
+**Deliverable:** Balanced gameplay
+
+---
+
+### Optimization (3 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 11.16 | Optimize slow API endpoints | ⬜ | Profile and improve <200ms target |
+| 11.17 | Optimize AI prompts for quality/cost | ⬜ | Better prompts, lower token usage |
+| 11.18 | Reduce page load times | ⬜ | Asset optimization, caching |
+
+**Performance Targets:**
+- API response time: <200ms (non-AI)
+- AI response time: <3s
+- Page load time: <2s
+- Time to interactive: <1s
+
+**Deliverable:** Optimized performance
+
+---
+
+### Documentation Update (2 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 11.19 | Update documentation based on learnings | ⬜ | API docs, user guide, troubleshooting |
+| 11.20 | **Final Checkpoint:** Beta sign-off | ⬜ | All critical issues resolved |
+
+**Deliverable:** Updated documentation
+
+---
+
+## Files to Create/Modify
+
+**New Files:**
+- `/docs/BETA_FEEDBACK.md` - Aggregated beta feedback
+- `/docs/KNOWN_ISSUES.md` - Known issues and workarounds
+
+**Modified Files:**
+- Various bug fixes across codebase
+- `/api/app/data/enemies/*.yaml` - Balance adjustments
+- `/api/app/data/quests/*.yaml` - Reward adjustments
+- `/api/app/ai/prompts.py` - Prompt improvements
+
+---
+
+## Testing Criteria
+
+### Bug Verification
+- [ ] All critical bugs fixed
+- [ ] All high priority bugs fixed
+- [ ] Medium priority bugs addressed or documented
+
+### Balance Verification
+- [ ] Combat feels challenging but fair
+- [ ] Economy feels rewarding
+- [ ] Progression pace feels good
+
+### Performance Verification
+- [ ] API endpoints meet targets
+- [ ] AI responses acceptable
+- [ ] No noticeable lag in UI
+
+### Beta Tester Satisfaction
+- [ ] Overall positive feedback
+- [ ] Testers would recommend to friends
+- [ ] Major concerns addressed
+
+---
+
+## Success Criteria
+
+- [ ] 10-20 active beta testers
+- [ ] Feedback collection system working
+- [ ] Zero critical bugs
+- [ ] < 5 high priority bugs remaining
+- [ ] Combat balanced (70-80% win rate)
+- [ ] Economy balanced
+- [ ] Performance targets met
+- [ ] Positive beta tester sentiment
+
+---
+
+## Dependencies
+
+**Requires (from earlier phases):**
+- Production deployment (Phase 10)
+- All features implemented
+
+---
+
+## Task Summary
+
+| Group | Tasks | Checkpoints |
+|-------|-------|-------------|
+| Beta Recruitment | 3 | 0 |
+| Feedback Collection | 2 | 1 |
+| Monitoring & Analysis | 3 | 0 |
+| Bug Fixing | 3 | 0 |
+| Balancing | 2 | 1 |
+| Optimization | 3 | 0 |
+| Documentation Update | 1 | 1 |
+| **Total** | **17** | **3** |
--- a/docs/phases/Phase12-Launch.md
+++ b/docs/phases/Phase12-Launch.md
@@ -0,0 +1,247 @@
+# Phase 12: Launch Preparation
+
+**Goal:** Marketing, final polish, and public launch
+**Priority:** High
+**Status:** Not Started
+**Last Updated:** November 29, 2025
+
+---
+
+## Overview
+
+Prepare for public launch with marketing materials, user documentation, payment integration, legal compliance, and final quality assurance.
+
+**Key Goals:**
+- Marketing landing page
+- User documentation (how to play)
+- Payment integration (Stripe subscriptions)
+- Legal compliance (privacy policy, ToS)
+- Final security and performance review
+- Public launch
+
+---
+
+## Task Groups
+
+### Marketing & Landing Page (4 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 12.1 | Design landing page | ⬜ | Hero, features, pricing, CTA |
+| 12.2 | Create landing page | ⬜ | `/public_web/templates/landing.html` |
+| 12.3 | Create marketing screenshots/videos | ⬜ | Gameplay screenshots, demo video |
+| 12.4 | Set up social media accounts | ⬜ | Twitter/X, Discord, Reddit |
+
+**Landing Page Sections:**
+- Hero: Tagline, CTA, hero image
+- Features: AI DM, character creation, combat, quests
+- Pricing: Free, Premium, Elite tiers
+- FAQ: Common questions
+- Footer: Links, legal, social
+
+**Deliverable:** Public-facing marketing presence
+
+---
+
+### User Documentation (3 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 12.5 | Write "How to Play" guide | ⬜ | Getting started, character creation, gameplay |
+| 12.6 | Write FAQ | ⬜ | Common questions and answers |
+| 12.7 | **Checkpoint:** Review documentation | ⬜ | Test with new user |
+
+**Documentation Topics:**
+- Account creation
+- Character creation
+- Gameplay basics (story, combat, quests)
+- Subscription tiers
+- Troubleshooting
+
+**Deliverable:** User-friendly documentation
+
+---
+
+### Payment Integration (4 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 12.8 | Set up Stripe account | ⬜ | Business account, test mode first |
+| 12.9 | Create subscription products | ⬜ | Free, Premium ($X/mo), Elite ($X/mo) |
+| 12.10 | Implement subscription endpoints | ⬜ | Create, cancel, webhook handling |
+| 12.11 | Create subscription management UI | ⬜ | Upgrade, downgrade, cancel |
+
+**Subscription Tiers:**
+| Tier | Price | Features |
+|------|-------|----------|
+| Free | $0 | Basic gameplay, limited AI calls |
+| Premium | $X/mo | Unlimited AI, marketplace, multiplayer |
+| Elite | $X/mo | All features, priority support, exclusive content |
+
+**Stripe Integration:**
+```python
+# Webhook endpoint for subscription events
+@app.route('/api/v1/webhooks/stripe', methods=['POST'])
+def stripe_webhook():
+    event = stripe.Webhook.construct_event(...)
+    if event['type'] == 'customer.subscription.updated':
+        # Update user tier in database
+    return '', 200
+```
+
+**Deliverable:** Working payment system
+
+---
+
+### Legal Compliance (3 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 12.12 | Create Privacy Policy | ⬜ | Data collection, usage, GDPR compliance |
+| 12.13 | Create Terms of Service | ⬜ | User responsibilities, liability, refunds |
+| 12.14 | Add cookie consent banner | ⬜ | If using analytics/tracking cookies |
+
+**Deliverable:** Legal compliance
+
+---
+
+### Analytics & Support (3 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 12.15 | Set up analytics | ⬜ | Privacy-friendly (Plausible, Fathom) or GA |
+| 12.16 | Set up support system | ⬜ | Email support, Discord, or ticketing |
+| 12.17 | Create support documentation | ⬜ | How to contact, response times |
+
+**Deliverable:** User analytics and support
+
+---
+
+### Final Reviews (3 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 12.18 | Final security review | ⬜ | Penetration testing, OWASP check |
+| 12.19 | Final performance review | ⬜ | Load testing with expected traffic |
+| 12.20 | **Checkpoint:** Launch readiness check | ⬜ | All systems go |
+
+**Launch Readiness Checklist:**
+- [ ] All features working
+- [ ] No critical bugs
+- [ ] Payment system tested
+- [ ] Legal pages in place
+- [ ] Monitoring active
+- [ ] Backups running
+- [ ] Support ready
+- [ ] Marketing ready
+
+**Deliverable:** Launch-ready application
+
+---
+
+### Launch (2 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 12.21 | Write launch announcement | ⬜ | Blog post, social media posts |
+| 12.22 | **LAUNCH!** | ⬜ | Go live, announce, celebrate! |
+
+**Launch Day Checklist:**
+1. Final backup before launch
+2. Remove any beta/test restrictions
+3. Enable payment processing (live mode)
+4. Post announcement on all channels
+5. Monitor systems closely for first 24 hours
+6. Respond quickly to any issues
+
+**Deliverable:** Public launch of Code of Conquest
+
+---
+
+## Files to Create/Modify
+
+**New Files:**
+- `/public_web/templates/landing.html` - Marketing landing page
+- `/public_web/templates/pricing.html` - Pricing page
+- `/public_web/templates/legal/privacy.html` - Privacy policy
+- `/public_web/templates/legal/terms.html` - Terms of service
+- `/public_web/templates/docs/how-to-play.html` - User guide
+- `/public_web/templates/docs/faq.html` - FAQ
+- `/api/app/api/subscriptions.py` - Subscription endpoints
+- `/api/app/api/webhooks.py` - Stripe webhook handling
+- `/api/app/services/subscription_service.py` - Subscription logic
+
+**Modified Files:**
+- `/api/app/__init__.py` - Register subscription routes
+- `/api/config/*.yaml` - Stripe configuration
+- `/public_web/templates/base.html` - Analytics, cookie consent
+
+---
+
+## Testing Criteria
+
+### Payment Testing
+- [ ] Subscription creation works (test mode)
+- [ ] Subscription cancellation works
+- [ ] Webhooks received and processed
+- [ ] Tier changes reflected immediately
+
+### Legal Review
+- [ ] Privacy policy covers all data practices
+- [ ] Terms of service protect business
+- [ ] Cookie consent compliant
+
+### Final Testing
+- [ ] Load test passed
+- [ ] Security test passed
+- [ ] All features working end-to-end
+- [ ] New user can complete full flow
+
+---
+
+## Success Criteria
+
+- [ ] Landing page live and attractive
+- [ ] User documentation complete
+- [ ] Payment system working (Stripe live)
+- [ ] Legal pages in place
+- [ ] Analytics tracking
+- [ ] Support system ready
+- [ ] Security review passed
+- [ ] Performance review passed
+- [ ] Successful public launch
+
+---
+
+## Dependencies
+
+**Requires (from earlier phases):**
+- Beta testing complete (Phase 11)
+- All bugs fixed
+- Performance optimized
+
+---
+
+## Post-Launch Priorities
+
+After launch, focus on:
+1. Monitor systems closely (first 48 hours critical)
+2. Respond to user feedback quickly
+3. Fix any launch-day bugs immediately
+4. Engage with community on Discord/social
+5. Track key metrics (signups, conversions, retention)
+
+---
+
+## Task Summary
+
+| Group | Tasks | Checkpoints |
+|-------|-------|-------------|
+| Marketing & Landing Page | 4 | 0 |
+| User Documentation | 2 | 1 |
+| Payment Integration | 4 | 0 |
+| Legal Compliance | 3 | 0 |
+| Analytics & Support | 3 | 0 |
+| Final Reviews | 2 | 1 |
+| Launch | 1 | 1 |
+| **Total** | **19** | **3** |
--- a/docs/phases/Phase5-Quests.md
+++ b/docs/phases/Phase5-Quests.md
@@ -0,0 +1,352 @@
+# Phase 5: Quest System
+
+**Goal:** YAML-driven quest system with context-aware offering
+**Priority:** High
+**Status:** Complete (100%)
+**Last Updated:** November 29, 2025
+
+---
+
+## Overview
+
+The Quest System provides structured objectives and rewards for players during their solo story progression sessions. Quests are defined in YAML files and offered to players by the AI Dungeon Master based on context-aware triggers and location-based probability.
+
+**Key Principles:**
+- **YAML-driven design** - Quests defined in data files, no code changes needed
+- **Context-aware offering** - AI analyzes narrative context to offer relevant quests
+- **Location-based triggers** - Different areas have different quest probabilities
+- **Max 2 active quests** - Prevents player overwhelm
+- **Rewarding progression** - Quests provide gold, XP, and items
+
+**Reference:** See `/api/docs/QUEST_SYSTEM.md` for detailed technical specification.
+
+---
+
+## Task Groups
+
+### Quest Data Models (3 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 5.1 | Create Quest dataclass | ✅ | `/api/app/models/quest.py` - Quest, status, progress tracking |
+| 5.2 | Create QuestObjective, QuestReward, QuestTriggers dataclasses | ✅ | Objective types: kill, collect, travel, interact, discover |
+| 5.3 | **Checkpoint:** Verify serialization | ✅ | Test round-trip to JSON with `to_dict()` / `from_dict()` |
+
+**Deliverable:** Quest data models with full serialization support ✅
+
+---
+
+### Quest Content & Loading (4 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 5.4 | Create quest YAML schema | ✅ | Quest-centric design where quests define their NPC givers |
+| 5.5 | Create `/api/app/data/quests/` directory structure | ✅ | Organized by difficulty: `easy/`, `medium/`, `hard/`, `epic/` |
+| 5.6 | Write example quests in YAML | ✅ | 5 example quests created (2 easy, 2 medium, 1 hard) |
+| 5.7 | Implement QuestService (QuestLoader) | ✅ | `/api/app/services/quest_service.py` - YAML loading, caching |
+
+**Example Quest Structure:**
+```yaml
+quest_id: "quest_rats_tavern"
+name: "Rat Problem"
+description: "The local tavern is overrun with giant rats..."
+quest_giver: "Tavern Keeper"
+difficulty: "easy"
+objectives:
+  - objective_id: "kill_rats"
+    description: "Kill 10 giant rats in the tavern basement"
+    objective_type: "kill"
+    required_progress: 10
+rewards:
+  gold: 50
+  experience: 100
+  items: []
+offering_triggers:
+  location_types: ["town"]
+  min_character_level: 1
+  max_character_level: 3
+  probability_weights:
+    town: 0.30
+narrative_hooks:
+  - "The tavern keeper frantically waves you over..."
+```
+
+**Deliverable:** 5+ quests loadable from YAML ✅
+
+---
+
+### Quest Eligibility & Offering (3 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 5.8 | Implement QuestEligibilityService | ✅ | `/api/app/services/quest_eligibility_service.py` - Core eligibility logic |
+| 5.9 | Implement `get_quests_for_npc()` | ✅ | Find quests where NPC is quest_giver |
+| 5.10 | Implement probability roll + filtering | ✅ | Location-based weights, level check, status check |
+
+**Deliverable:** Context-aware quest eligibility system ✅
+
+---
+
+### Lore Service Stub (2 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 5.11 | Create LoreService interface | ✅ | `/api/app/services/lore_service.py` - Abstract interface for Phase 6 |
+| 5.12 | Implement MockLoreService | ✅ | Returns quest's embedded lore_context |
+
+**Deliverable:** Lore service stub ready for Phase 6 Weaviate integration ✅
+
+---
+
+### AI Prompt Integration (3 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 5.13 | Add quest offering section to template | ✅ | `/api/app/ai/templates/npc_dialogue.j2` - Quest context + natural weaving |
+| 5.14 | Add lore context section to template | ✅ | Filtered lore for NPC knowledge |
+| 5.15 | Implement quest offer parsing | ✅ | `/api/app/ai/response_parser.py` - Extract `[QUEST_OFFER:quest_id]` markers |
+
+**Deliverable:** AI naturally weaves quest offers into NPC dialogue ✅
+
+---
+
+### NPC API Integration (4 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 5.16 | Integrate eligibility check into `talk_to_npc` | ✅ | `/api/app/api/npcs.py` - Check before building AI context |
+| 5.17 | Add quest context to AI task | ✅ | `/api/app/tasks/ai_tasks.py` - Modify `_process_npc_dialogue_task` |
+| 5.18 | Handle quest_offered in response | ✅ | Parse and include in API response |
+| 5.19 | Remove `quest_giver_for` from NPC model | ✅ | Quest-centric: quests now define their givers |
+
+**Deliverable:** Quest offering integrated into NPC conversation flow ✅
+
+---
+
+### Quest Accept/Manage Endpoints (4 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 5.20 | Create quests blueprint | ✅ | `/api/app/api/quests.py` - Registered in `__init__.py` |
+| 5.21 | Implement `POST /api/v1/quests/accept` | ✅ | Add to active_quests, update relationship |
+| 5.22 | Implement `POST /api/v1/quests/decline` | ✅ | Set `refused_{quest_id}` flag |
+| 5.23 | Implement `GET /api/v1/characters/{id}/quests` | ✅ | List active and completed quests |
+
+**Deliverable:** Quest management API endpoints ✅
+
+---
+
+### Testing & Validation (3 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 5.24 | Unit tests for Quest models | ✅ | `/api/tests/test_quest_models.py` - Serialization, validation |
+| 5.25 | Unit tests for QuestEligibilityService | ✅ | `/api/tests/test_quest_eligibility.py` - Filtering logic |
+| 5.26 | Integration test: full quest offer flow | ✅ | `/api/tests/test_quest_integration.py` - NPC talk → offer → accept |
+
+**Deliverable:** Comprehensive test coverage ✅
+
+---
+
+### Quest UI & Final Testing (4 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 5.27 | Create quest tracker sidebar UI | ✅ | `public_web/templates/game/partials/sidebar_quests.html` - Enhanced with HTMX |
+| 5.28 | Create quest offering modal UI | ✅ | `public_web/templates/game/partials/quest_offer_modal.html` |
+| 5.29 | Create quest detail view | ✅ | `public_web/templates/game/partials/quest_detail_modal.html` |
+| 5.30 | **Final Checkpoint:** Full integration test | ✅ | Complete quest lifecycle: offer → accept → progress → complete |
+
+**Deliverable:** Working quest UI with HTMX integration ✅
+
+---
+
+## API Endpoints
+
+| Method | Endpoint | Description | Status |
+|--------|----------|-------------|--------|
+| `POST` | `/api/v1/quests/accept` | Accept a quest offer | ✅ |
+| `POST` | `/api/v1/quests/decline` | Decline a quest offer | ✅ |
+| `GET` | `/api/v1/characters/{id}/quests` | Get character's active and completed quests | ✅ |
+| `POST` | `/api/v1/quests/progress` | Update quest objective progress | ✅ |
+| `GET` | `/api/v1/quests/{quest_id}` | Get quest details | ✅ |
+| `POST` | `/api/v1/quests/complete` | Complete a quest and claim rewards | ✅ |
+| `POST` | `/api/v1/quests/abandon` | Abandon an active quest | ✅ |
+
+---
+
+## Files Created/Modified
+
+**New Files Created:**
+- ✅ `/api/app/models/quest.py` - Quest, QuestObjective, QuestReward, QuestTriggers
+- ✅ `/api/app/services/quest_service.py` - QuestService class with YAML loading
+- ✅ `/api/app/services/quest_eligibility_service.py` - QuestEligibilityService with filtering
+- ✅ `/api/app/services/lore_service.py` - LoreService interface + MockLoreService stub
+- ✅ `/api/app/api/quests.py` - Quest API blueprint with progress endpoint
+- ✅ `/api/app/data/quests/easy/*.yaml` - Easy quests (2)
+- ✅ `/api/app/data/quests/medium/*.yaml` - Medium quests (2)
+- ✅ `/api/app/data/quests/hard/*.yaml` - Hard quests (1)
+- ✅ `/api/tests/test_quest_models.py` - Quest model unit tests
+- ✅ `/api/tests/test_quest_integration.py` - Integration tests (expanded)
+- ✅ `/public_web/templates/game/partials/quest_offer_modal.html` - Quest offer modal
+- ✅ `/public_web/templates/game/partials/quest_detail_modal.html` - Quest detail modal
+
+**Modified Files:**
+- ✅ `/api/app/models/character.py` - Added `active_quests`, `completed_quests` fields
+- ✅ `/api/app/api/npcs.py` - Integrated quest eligibility into `talk_to_npc`
+- ✅ `/api/app/tasks/ai_tasks.py` - Added quest context to dialogue generation
+- ✅ `/api/app/ai/templates/npc_dialogue.j2` - Added quest offering section
+- ✅ `/api/app/ai/response_parser.py` - Added quest offer parsing
+- ✅ `/api/app/__init__.py` - Registered quests blueprint
+- ✅ `/api/app/services/combat_service.py` - Quest progress on enemy kills
+- ✅ `/public_web/templates/game/partials/sidebar_quests.html` - Enhanced with HTMX
+- ✅ `/public_web/app/views/game_views.py` - Quest routes and modal handlers
+- ✅ `/public_web/static/css/play.css` - Quest modal and sidebar styles
+
+---
+
+## Testing Criteria
+
+### Unit Tests
+- [x] Quest loading from YAML
+- [x] Quest serialization (to_dict/from_dict)
+- [x] QuestEligibilityService filtering
+- [x] Probability roll logic
+- [x] Quest.is_complete() logic
+- [x] Quest.update_progress() logic
+
+### Integration Tests
+- [x] Quest offer during NPC talk
+- [x] Accept quest (add to active_quests)
+- [x] Decline quest (set refused flag)
+- [x] Quest limit enforced (max 2 active)
+- [x] Quest progress updates during combat
+- [x] Complete quest and receive rewards
+- [x] Level up from quest XP
+- [x] Abandon quest
+
+### Manual Testing
+- [ ] Full quest flow (offer → accept → progress → complete)
+- [ ] Multiple quests active simultaneously
+- [ ] Quest offering feels natural in narrative
+- [ ] UI components display correctly
+
+---
+
+## Success Criteria
+
+- [x] Quest data models implemented and tested
+- [x] QuestService loads quests from YAML files (5 quests created)
+- [x] Quest offering integrated into NPC conversations
+- [x] Context-aware quest selection working (eligibility + probability)
+- [x] Max 2 active quests enforced
+- [x] LoreService stub ready for Phase 6 integration
+- [x] AI naturally weaves quest offers into dialogue
+- [x] Quest offer parsing extracts `[QUEST_OFFER:id]` correctly
+- [x] Accept/decline endpoints working
+- [x] Quest progress updates automatically (combat kill tracking)
+- [x] Quest completion grants rewards correctly
+- [x] Quest UI components functional
+
+---
+
+## Dependencies
+
+**Requires (already implemented):**
+- Session system (`/api/app/services/session_service.py`)
+- Character system (`/api/app/models/character.py`)
+- Combat system (`/api/app/services/combat_service.py`)
+- Location system (`/api/app/services/location_loader.py`)
+- NPC system (`/api/app/services/npc_loader.py`)
+
+**Enables (future phases):**
+- Phase 6: Story Progression (quests provide structured objectives)
+- Phase 7: Multiplayer (party quests)
+
+---
+
+## Task Summary
+
+| Group | Tasks | Completed | Status |
+|-------|-------|-----------|--------|
+| Quest Data Models | 3 | 3 | ✅ |
+| Quest Content & Loading | 4 | 4 | ✅ |
+| Quest Eligibility & Offering | 3 | 3 | ✅ |
+| Lore Service Stub | 2 | 2 | ✅ |
+| AI Prompt Integration | 3 | 3 | ✅ |
+| NPC API Integration | 4 | 4 | ✅ |
+| Quest Accept/Manage Endpoints | 4 | 4 | ✅ |
+| Testing & Validation | 3 | 3 | ✅ |
+| Quest UI & Final Testing | 4 | 4 | ✅ |
+| **Total** | **30** | **30** | **100%** |
+
+---
+
+## Architecture Notes
+
+### Quest-Centric Design
+
+The implementation follows a quest-centric approach where:
+- **Quests define their NPC givers** via `quest_giver_npc_ids` field
+- Adding new quests doesn't require modifying NPC files
+- NPCs automatically discover which quests they can offer
+
+### NPC Conversation Flow
+
+```
+POST /api/v1/npcs/{npc_id}/talk
+         │
+         ▼
+┌─────────────────────────────┐
+│ 1. Load Context             │
+│    - NPC, Character, Location│
+└────────────┬────────────────┘
+             │
+             ▼
+┌─────────────────────────────┐
+│ 2. Quest Eligibility Check  │
+│    QuestEligibilityService  │
+│    - Find quests where NPC  │
+│      is quest_giver         │
+│    - Filter by char level,  │
+│      completed, active, etc │
+└────────────┬────────────────┘
+             │
+             ▼
+┌─────────────────────────────┐
+│ 3. Probability Roll         │
+│    - Town: 30%, Tavern: 35% │
+│    - Wilderness: 5%         │
+│    - If fail → no offer     │
+└────────────┬────────────────┘
+             │ (if success)
+             ▼
+┌─────────────────────────────┐
+│ 4. Get Lore Context (stub)  │
+│    LoreService.get_context()│
+│    - Quest embedded lore    │
+│    - Mock regional lore     │
+└────────────┬────────────────┘
+             │
+             ▼
+┌─────────────────────────────┐
+│ 5. AI Generates Dialogue    │
+│    Naturally weaves quest   │
+│    offer into conversation  │
+│    Includes [QUEST_OFFER:id]│
+└────────────┬────────────────┘
+             │
+             ▼
+┌─────────────────────────────┐
+│ 6. Parse Response           │
+│    Extract quest_offered    │
+│    Return to frontend       │
+└─────────────────────────────┘
+```
+
+### Phase 6 Integration Points
+
+The LoreService stub is ready for Phase 6 Weaviate integration:
+- Replace `MockLoreService` with `WeaviateLoreService`
+- Quest's embedded `lore_context` will be supplemented with vector DB queries
+- NPC dialogue template already has lore context section
--- a/docs/phases/Phase6-StoryProgression.md
+++ b/docs/phases/Phase6-StoryProgression.md
@@ -0,0 +1,354 @@
+# Phase 6: Story Progression & Lore System
+
+**Goal:** Vector database-powered NPC knowledge and world lore
+**Priority:** High
+**Status:** Not Started
+**Last Updated:** November 29, 2025
+
+---
+
+## Overview
+
+Implement a layered knowledge system using vector databases (Weaviate) to provide NPCs and the Dungeon Master with contextual lore, regional history, and world knowledge. This enhances NPC conversations with authentic, contextual responses.
+
+**Key Principles:**
+- **Three-tier knowledge hierarchy** - World Lore → Regional Lore → NPC Persona
+- **RAG (Retrieval-Augmented Generation)** - Semantic search for relevant context
+- **Knowledge boundaries** - NPCs only know what they should know
+- **Index-once strategy** - Embeddings generated at build time, not runtime
+
+**Reference:** See `/docs/VECTOR_DATABASE_STRATEGY.md` for detailed architecture.
+
+---
+
+## Knowledge Hierarchy
+
+### Three-Tier Structure
+
+1. **World Lore DB** (Global)
+   - Broad historical events, mythology, major kingdoms, legendary figures
+   - Accessible to all NPCs and DM for player questions
+   - Examples: "The Great War 200 years ago", "The origin of magic"
+
+2. **Regional/Town Lore DB** (Location-specific)
+   - Local history, notable events, landmarks, politics, rumors
+   - Current town leadership, recent events, local legends
+   - Trade routes, neighboring settlements, regional conflicts
+
+3. **NPC Persona** (Individual, YAML-defined)
+   - Personal background, personality, motivations
+   - Specific knowledge based on profession/role
+   - Already implemented in `/api/app/data/npcs/*.yaml`
+
+---
+
+## Task Groups
+
+### Vector Database Setup (4 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 6.1 | Add Weaviate to Docker Compose | ⬜ | Self-hosted for development |
+| 6.2 | Create Weaviate service configuration | ⬜ | `/api/config/*.yaml` - dev/prod endpoints |
+| 6.3 | Create WeaviateService class | ⬜ | `/api/app/services/weaviate_service.py` - connection, health check |
+| 6.4 | **Checkpoint:** Verify Weaviate connectivity | ⬜ | Test connection and basic operations |
+
+**Docker Compose Addition:**
+```yaml
+services:
+  weaviate:
+    image: semitechnologies/weaviate:latest
+    ports:
+      - "8080:8080"
+    environment:
+      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
+      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
+    volumes:
+      - weaviate_data:/var/lib/weaviate
+```
+
+**Deliverable:** Working Weaviate instance in development environment
+
+---
+
+### Weaviate Schema & Collections (4 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 6.5 | Define WorldLore collection schema | ⬜ | Metadata: knowledge_type, time_period, required_profession |
+| 6.6 | Define RegionalLore collection schema | ⬜ | Metadata: region_id, knowledge_type, social_class |
+| 6.7 | Create schema initialization script | ⬜ | `/api/scripts/init_weaviate_schema.py` |
+| 6.8 | **Checkpoint:** Verify collections created | ⬜ | Test schema via Weaviate console |
+
+**Collection Schema:**
+```
+WorldLore:
+  - content: text (vectorized)
+  - title: string
+  - knowledge_type: string (academic, common, secret)
+  - time_period: string (ancient, historical, recent, current)
+  - required_profession: string[] (optional filter)
+  - tags: string[]
+
+RegionalLore:
+  - content: text (vectorized)
+  - title: string
+  - region_id: string
+  - knowledge_type: string
+  - social_class: string[] (noble, merchant, commoner)
+  - tags: string[]
+```
+
+**Deliverable:** Weaviate schema ready for data ingestion
+
+---
+
+### World Lore Content (4 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 6.9 | Create lore content directory structure | ⬜ | `/api/app/data/lore/world/` |
+| 6.10 | Write world history YAML | ⬜ | Major events, wars, kingdoms, mythology |
+| 6.11 | Write mythology YAML | ⬜ | Gods, creation stories, magic origins |
+| 6.12 | Write kingdoms YAML | ⬜ | Major factions, political landscape |
+
+**Directory Structure:**
+```
+/api/app/data/lore/
+  world/
+    history.yaml        # Major historical events
+    mythology.yaml      # Gods, legends, magic
+    kingdoms.yaml       # Factions, politics
+  regions/
+    crossville/
+      history.yaml      # Local history
+      locations.yaml    # Notable places
+      rumors.yaml       # Current gossip
+```
+
+**Example Lore Entry:**
+```yaml
+- id: "great_war"
+  title: "The Great War of the Five Kingdoms"
+  content: |
+    Two hundred years ago, the Five Kingdoms united against
+    the Shadow Empire in a conflict that reshaped the world...
+  metadata:
+    knowledge_type: "common"
+    time_period: "historical"
+    required_profession: null
+  tags:
+    - "war"
+    - "five-kingdoms"
+    - "shadow-empire"
+```
+
+**Deliverable:** 20+ world lore entries ready for embedding
+
+---
+
+### Regional Lore Content (3 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 6.13 | Write Crossville regional history | ⬜ | Founding, notable events, local legends |
+| 6.14 | Write Crossville locations lore | ⬜ | Descriptions for tavern, forest, dungeon |
+| 6.15 | Write Crossville rumors | ⬜ | Current gossip, quest hooks |
+
+**Deliverable:** 15+ regional lore entries for starter region
+
+---
+
+### Embedding Generation (4 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 6.16 | Create embedding generation script | ⬜ | `/api/scripts/generate_lore_embeddings.py` |
+| 6.17 | Implement chunking strategy | ⬜ | Split by logical units (events, locations, figures) |
+| 6.18 | Generate and upload world lore embeddings | ⬜ | One-time generation, upload to Weaviate |
+| 6.19 | **Checkpoint:** Verify embedding quality | ⬜ | Test semantic search returns relevant results |
+
+**Embedding Model Options:**
+- **Development:** sentence-transformers (free, fast iteration)
+- **Production:** OpenAI text-embedding-3-large or Replicate multilingual-e5-large
+
+**Deliverable:** All lore content embedded and searchable in Weaviate
+
+---
+
+### NPC Knowledge Integration (5 tasks)
+
+> **Note:** The LoreService interface and MockLoreService stub were created in Phase 5 (`/api/app/services/lore_service.py`). This phase replaces the mock with the real Weaviate implementation.
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 6.20 | Implement WeaviateLoreService | ⬜ | Replace MockLoreService, query World + Regional DBs |
+| 6.21 | Add knowledge filtering by NPC role | ⬜ | Profession, social class, relationship level |
+| 6.22 | Integrate lore into NPC conversation prompts | ⬜ | RAG pattern: retrieve → inject → generate |
+| 6.23 | Implement "I don't know" responses | ⬜ | Authentic ignorance when NPC lacks knowledge |
+| 6.24 | **Checkpoint:** Test NPC conversations with lore | ⬜ | Verify NPCs use contextual knowledge |
+
+**RAG Pattern for NPC Dialogue:**
+```
+[NPC Persona from YAML]
+
+[Top 3-5 relevant chunks from Regional DB]
+
+[Top 2-3 relevant chunks from World Lore if historical topic]
+
+[Conversation history]
+→ Feed to Claude with instruction to stay in character
+```
+
+**Knowledge Filtering Example:**
+```python
+# Blacksmith asking about metallurgy → Return results
+# Blacksmith asking about court politics → "I don't know about that"
+
+def filter_knowledge_for_npc(results, npc):
+    return [r for r in results if npc_can_know(r.metadata, npc)]
+```
+
+**Deliverable:** NPCs respond with contextually appropriate lore
+
+---
+
+### DM Lore Access (2 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 6.25 | Implement DM lore query endpoint | ⬜ | `POST /api/v1/lore/query` - Full access, no filtering |
+| 6.26 | Integrate lore into story narration | ⬜ | DM uses lore for atmospheric descriptions |
+
+**DM vs NPC Knowledge:**
+- **DM Mode:** Access to ALL databases without restrictions
+- **NPC Mode:** Knowledge filtered by persona/role/location
+
+**Deliverable:** DM can access all lore for narrative purposes
+
+---
+
+## API Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/api/v1/lore/query` | Query lore by topic (DM access) |
+| `GET` | `/api/v1/lore/regions/{region_id}` | Get all lore for a region |
+| `GET` | `/api/v1/lore/world` | Get world lore summary |
+
+---
+
+## Files to Create/Modify
+
+**New Files:**
+- `/api/app/services/weaviate_service.py` - Weaviate connection and queries
+- `/api/scripts/init_weaviate_schema.py` - Schema initialization
+- `/api/scripts/generate_lore_embeddings.py` - Embedding generation
+- `/api/app/data/lore/world/history.yaml`
+- `/api/app/data/lore/world/mythology.yaml`
+- `/api/app/data/lore/world/kingdoms.yaml`
+- `/api/app/data/lore/regions/crossville/history.yaml`
+- `/api/app/data/lore/regions/crossville/locations.yaml`
+- `/api/app/data/lore/regions/crossville/rumors.yaml`
+- `/api/app/api/lore.py` - Lore API blueprint
+
+**Modified Files:**
+- `/api/app/services/lore_service.py` - Already exists from Phase 5 (stub). Add WeaviateLoreService implementation
+- `/docker-compose.yml` - Add Weaviate service
+- `/api/config/development.yaml` - Weaviate dev config
+- `/api/config/production.yaml` - Weaviate Cloud Services config
+- `/api/app/services/npc_loader.py` - Integrate lore queries
+- `/api/app/ai/prompts.py` - Add lore context to prompts
+
+---
+
+## Testing Criteria
+
+### Unit Tests
+- [ ] Weaviate connection and health check
+- [ ] Schema creation
+- [ ] Lore content loading from YAML
+- [ ] Embedding generation
+- [ ] Semantic search returns relevant results
+- [ ] Knowledge filtering by NPC role
+
+### Integration Tests
+- [ ] Full RAG pipeline: query → retrieve → inject → generate
+- [ ] NPC conversation includes relevant lore
+- [ ] NPC correctly says "I don't know" for unknown topics
+- [ ] DM has full lore access
+
+### Manual Testing
+- [ ] Ask NPC about local history → Returns regional lore
+- [ ] Ask NPC about world history → Returns filtered world lore
+- [ ] Ask farmer about court politics → "I wouldn't know about that"
+- [ ] Ask scholar about ancient history → Detailed response
+
+---
+
+## Success Criteria
+
+- [ ] Weaviate running in development environment
+- [ ] 20+ world lore entries embedded
+- [ ] 15+ regional lore entries for Crossville
+- [ ] NPC conversations enhanced with contextual lore
+- [ ] Knowledge filtering working by profession/class
+- [ ] DM has full lore access for narration
+- [ ] Semantic search returning relevant results
+
+---
+
+## Dependencies
+
+**Requires (already implemented):**
+- NPC system (`/api/app/services/npc_loader.py`)
+- Location system (`/api/app/services/location_loader.py`)
+- AI service (`/api/app/ai/`)
+
+**Requires (from Phase 5):**
+- Quest system (quests can reference lore) ✅
+- LoreService interface stub (`/api/app/services/lore_service.py`) ✅ - Ready to replace MockLoreService with WeaviateLoreService
+
+**Enables (future phases):**
+- Phase 7: Multiplayer (shared world lore)
+- Lore codex/discovery system (optional future feature)
+
+---
+
+## Production Migration Path
+
+### Zero-Code Migration to Weaviate Cloud Services
+
+1. Export data from self-hosted Weaviate
+2. Create Weaviate Cloud Services cluster
+3. Import data to WCS
+4. Change environment variable: `WEAVIATE_URL`
+5. Deploy (no code changes required)
+
+**Environment Configuration:**
+```yaml
+# development.yaml
+weaviate:
+  url: "http://localhost:8080"
+  api_key: null
+
+# production.yaml
+weaviate:
+  url: "https://your-cluster.weaviate.network"
+  api_key: "${WEAVIATE_API_KEY}"
+```
+
+---
+
+## Task Summary
+
+| Group | Tasks | Checkpoints |
+|-------|-------|-------------|
+| Vector Database Setup | 3 | 1 |
+| Weaviate Schema & Collections | 3 | 1 |
+| World Lore Content | 4 | 0 |
+| Regional Lore Content | 3 | 0 |
+| Embedding Generation | 3 | 1 |
+| NPC Knowledge Integration | 4 | 1 |
+| DM Lore Access | 2 | 0 |
+| **Total** | **22** | **4** |
--- a/docs/phases/Phase7-Multiplayer.md
+++ b/docs/phases/Phase7-Multiplayer.md
@@ -0,0 +1,247 @@
+# Phase 7: Multiplayer Sessions
+
+**Goal:** Invite-based, time-limited co-op sessions for Premium/Elite players
+**Priority:** Low
+**Status:** Not Started
+**Last Updated:** November 29, 2025
+
+---
+
+## Overview
+
+Multiplayer is a paid-tier feature focused on short co-op adventures. Unlike solo story progression, multiplayer sessions are time-limited (2 hours), invite-based, and combat-focused.
+
+**Key Features:**
+- Premium/Elite tier only
+- Shareable invite links (8-char alphanumeric codes)
+- 2-4 player parties
+- 2-hour session duration
+- AI-generated custom campaigns
+- Realtime synchronization via Appwrite
+- Character snapshots (doesn't affect solo campaigns)
+
+**Reference:** See `/api/docs/MULTIPLAYER.md` for detailed technical specification.
+
+---
+
+## Task Groups
+
+### Core Infrastructure (7 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 7.1 | Create MultiplayerSession dataclass | ⬜ | Extends GameSession with time limits, invite codes |
+| 7.2 | Create PartyMember dataclass | ⬜ | Player info, character snapshot, ready status |
+| 7.3 | Create MultiplayerCampaign models | ⬜ | Campaign, CampaignEncounter, CampaignRewards |
+| 7.4 | Implement invite code generation | ⬜ | 8-char alphanumeric, unique, 24hr expiration |
+| 7.5 | Implement 2-hour timer logic | ⬜ | Session expiration, warnings (10min, 5min, 1min) |
+| 7.6 | Set up Appwrite Realtime subscriptions | ⬜ | WebSocket for live session updates |
+| 7.7 | **Checkpoint:** Verify data models | ⬜ | Test serialization and Appwrite storage |
+
+**Deliverable:** Core multiplayer data structures ready
+
+---
+
+### Session Management APIs (5 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 7.8 | Implement session creation API | ⬜ | `POST /api/v1/multiplayer/create` (Premium/Elite only) |
+| 7.9 | Implement join via invite API | ⬜ | `POST /api/v1/multiplayer/join/{invite_code}` |
+| 7.10 | Implement lobby system | ⬜ | Ready status, player list, host controls |
+| 7.11 | Implement session start API | ⬜ | Host starts when all players ready |
+| 7.12 | Implement session end/cleanup | ⬜ | Auto-end at 2 hours, manual end by host |
+
+**API Endpoints:**
+```
+POST /api/v1/multiplayer/create          - Create new session (host)
+POST /api/v1/multiplayer/join/{code}     - Join via invite code
+GET  /api/v1/multiplayer/{id}/lobby      - Get lobby state
+POST /api/v1/multiplayer/{id}/ready      - Toggle ready status
+POST /api/v1/multiplayer/{id}/start      - Start session (host only)
+POST /api/v1/multiplayer/{id}/leave      - Leave session
+POST /api/v1/multiplayer/{id}/end        - End session (host only)
+```
+
+**Deliverable:** Full session lifecycle management
+
+---
+
+### Campaign Generation (4 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 7.13 | Create campaign templates | ⬜ | Pre-built structures for AI to fill |
+| 7.14 | Implement AI campaign generator | ⬜ | Generate 3-5 encounters based on party composition |
+| 7.15 | Implement encounter sequencing | ⬜ | Linear progression through encounters |
+| 7.16 | **Checkpoint:** Test campaign generation | ⬜ | Verify AI creates balanced encounters |
+
+**Campaign Structure:**
+```yaml
+campaign:
+  name: "The Cursed Crypt"
+  description: "A short adventure into an undead-infested tomb"
+  encounters:
+    - type: "exploration"
+      description: "Navigate the tomb entrance"
+    - type: "combat"
+      enemies: [skeleton_warrior, skeleton_archer]
+    - type: "puzzle"
+      description: "Ancient door mechanism"
+    - type: "boss"
+      enemies: [lich_lord]
+  rewards:
+    gold_per_player: 500
+    experience_per_player: 1000
+    item_pool: ["rare", "epic"]
+```
+
+**Deliverable:** AI-generated campaigns for parties
+
+---
+
+### Multiplayer Combat (4 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 7.17 | Implement turn management for parties | ⬜ | Initiative, turn order, action validation |
+| 7.18 | Extend combat system for multi-player | ⬜ | Reuse Phase 4 combat, add party support |
+| 7.19 | Implement disconnect handling | ⬜ | Auto-defend mode, host promotion on disconnect |
+| 7.20 | Implement reward distribution | ⬜ | Calculate and grant rewards at session end |
+
+**Turn Order:**
+```
+1. Roll initiative for all players and enemies
+2. Sort by initiative (highest first)
+3. Each turn:
+   - Notify current player via Realtime
+   - Wait for action (30 second timeout → auto-defend)
+   - Process action
+   - Update all clients via Realtime
+4. After all enemies defeated → next encounter
+```
+
+**Deliverable:** Working party combat system
+
+---
+
+### Multiplayer UI (4 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 7.21 | Create lobby UI | ⬜ | `templates/multiplayer/lobby.html` - Player list, ready status, invite link |
+| 7.22 | Create active session UI | ⬜ | `templates/multiplayer/session.html` - Timer, party status, combat, narrative |
+| 7.23 | Create session complete UI | ⬜ | `templates/multiplayer/complete.html` - Rewards, stats, MVP badges |
+| 7.24 | Implement Realtime UI updates | ⬜ | WebSocket subscription for live state |
+
+**Deliverable:** Full multiplayer UI experience
+
+---
+
+### Testing & Validation (4 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 7.25 | Write unit tests | ⬜ | Invite generation, join validation, timer logic |
+| 7.26 | Write integration tests | ⬜ | Full session flow: create → join → play → complete |
+| 7.27 | Test realtime synchronization | ⬜ | Multiple browsers simulating party gameplay |
+| 7.28 | **Final Checkpoint:** Test session expiration | ⬜ | Force expiration, verify cleanup and reward distribution |
+
+**Deliverable:** Validated multiplayer system
+
+---
+
+## API Endpoints Summary
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/api/v1/multiplayer/create` | Create new multiplayer session |
+| `POST` | `/api/v1/multiplayer/join/{code}` | Join via invite code |
+| `GET` | `/api/v1/multiplayer/{id}/lobby` | Get lobby state |
+| `POST` | `/api/v1/multiplayer/{id}/ready` | Toggle ready status |
+| `POST` | `/api/v1/multiplayer/{id}/start` | Start session (host) |
+| `POST` | `/api/v1/multiplayer/{id}/action` | Take action during session |
+| `GET` | `/api/v1/multiplayer/{id}/state` | Get current session state |
+| `POST` | `/api/v1/multiplayer/{id}/leave` | Leave session |
+| `POST` | `/api/v1/multiplayer/{id}/end` | End session (host) |
+
+---
+
+## Files to Create/Modify
+
+**New Files:**
+- `/api/app/models/multiplayer.py` - MultiplayerSession, PartyMember, Campaign
+- `/api/app/services/multiplayer_service.py` - Session management
+- `/api/app/services/campaign_service.py` - AI campaign generation
+- `/api/app/api/multiplayer.py` - Multiplayer API blueprint
+- `/public_web/templates/multiplayer/lobby.html`
+- `/public_web/templates/multiplayer/session.html`
+- `/public_web/templates/multiplayer/complete.html`
+- `/public_web/static/js/multiplayer-realtime.js` - WebSocket handling
+
+**Modified Files:**
+- `/api/app/services/combat_service.py` - Add party combat support
+- `/api/app/__init__.py` - Register multiplayer blueprint
+
+---
+
+## Testing Criteria
+
+### Unit Tests
+- [ ] Invite code generation (uniqueness, format)
+- [ ] Join validation (code exists, not expired, not full)
+- [ ] Timer logic (warnings, expiration)
+- [ ] Turn order calculation
+
+### Integration Tests
+- [ ] Full session flow: create → join → ready → start → play → complete
+- [ ] Disconnect handling (player leaves mid-session)
+- [ ] Host promotion when original host disconnects
+- [ ] Reward distribution at session end
+
+### Manual Testing
+- [ ] Multiple browsers simulating party
+- [ ] Realtime updates between players
+- [ ] Timer warnings display correctly
+- [ ] Combat turns cycle correctly
+
+---
+
+## Success Criteria
+
+- [ ] Premium/Elite tier restriction enforced
+- [ ] Invite codes work correctly
+- [ ] Lobby system functional
+- [ ] 2-hour timer with warnings
+- [ ] Realtime synchronization working
+- [ ] Party combat functional
+- [ ] Campaign generation working
+- [ ] Rewards distributed at session end
+
+---
+
+## Dependencies
+
+**Requires (already implemented):**
+- Combat system (Phase 4)
+- Character system
+- Session system
+- Authentication with tiers
+
+**Requires (from earlier phases):**
+- Quest system (optional: party quests)
+- Lore system (shared world knowledge)
+
+---
+
+## Task Summary
+
+| Group | Tasks | Checkpoints |
+|-------|-------|-------------|
+| Core Infrastructure | 6 | 1 |
+| Session Management APIs | 5 | 0 |
+| Campaign Generation | 3 | 1 |
+| Multiplayer Combat | 4 | 0 |
+| Multiplayer UI | 4 | 0 |
+| Testing & Validation | 3 | 1 |
+| **Total** | **25** | **3** |
--- a/docs/phases/Phase8-Marketplace.md
+++ b/docs/phases/Phase8-Marketplace.md
@@ -0,0 +1,206 @@
+# Phase 8: Marketplace
+
+**Goal:** Player-to-player trading system (Premium+ only)
+**Priority:** Medium
+**Status:** Not Started
+**Last Updated:** November 29, 2025
+
+---
+
+## Overview
+
+The Marketplace enables Premium and Elite players to trade items with each other through auctions and fixed-price listings. This creates a player economy and provides an additional incentive for premium subscriptions.
+
+**Key Features:**
+- Premium/Elite tier only
+- Auction and fixed-price (buyout) listings
+- 48-hour listing duration
+- 5% marketplace fee on sales
+- Bidding with outbid notifications
+- Search and filter functionality
+
+---
+
+## Task Groups
+
+### Marketplace Data Models (3 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 8.1 | Create MarketplaceListing dataclass | ⬜ | Item, seller, price, auction settings, expiration |
+| 8.2 | Create Bid dataclass | ⬜ | Bidder, amount, timestamp |
+| 8.3 | **Checkpoint:** Verify serialization | ⬜ | Test round-trip to JSON, Appwrite storage |
+
+**Listing Structure:**
+```python
+@dataclass
+class MarketplaceListing:
+    listing_id: str
+    seller_id: str
+    item: Item
+    listing_type: str  # "auction" | "fixed_price"
+    starting_price: int
+    buyout_price: Optional[int]
+    current_bid: Optional[int]
+    current_bidder_id: Optional[str]
+    bids: List[Bid]
+    created_at: datetime
+    expires_at: datetime
+    status: str  # "active" | "sold" | "expired" | "cancelled"
+```
+
+**Deliverable:** Marketplace data models ready
+
+---
+
+### Marketplace APIs (6 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 8.4 | Implement browse API | ⬜ | `GET /api/v1/marketplace` - Filtering, sorting, pagination |
+| 8.5 | Implement listing creation API | ⬜ | `POST /api/v1/marketplace/listings` - Auction + fixed price |
+| 8.6 | Implement bidding API | ⬜ | `POST /api/v1/marketplace/listings/{id}/bid` - Validate bid amounts |
+| 8.7 | Implement buyout API | ⬜ | `POST /api/v1/marketplace/listings/{id}/buyout` - Instant purchase |
+| 8.8 | Implement listing cancellation | ⬜ | `DELETE /api/v1/marketplace/listings/{id}` - Return item to seller |
+| 8.9 | Implement my listings/bids API | ⬜ | `GET /api/v1/marketplace/my-listings`, `/my-bids` |
+
+**Deliverable:** Full marketplace API
+
+---
+
+### Auction Processing (3 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 8.10 | Implement auction processing task | ⬜ | Periodic RQ job to end expired auctions |
+| 8.11 | Implement bid notifications | ⬜ | Notify when outbid (in-app notification) |
+| 8.12 | Implement sale completion | ⬜ | Transfer item, gold minus 5% fee |
+
+**Auction Processing Flow:**
+```
+Every 5 minutes:
+  1. Query listings where expires_at <= now AND status = 'active'
+  2. For each expired listing:
+     - If has bids: Award to highest bidder, transfer gold (minus fee)
+     - If no bids: Return item to seller, mark expired
+  3. Send notifications to winners/sellers
+```
+
+**Deliverable:** Automated auction resolution
+
+---
+
+### Marketplace UI (4 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 8.13 | Create marketplace browse UI | ⬜ | `templates/marketplace/browse.html` - Grid/list view, filters |
+| 8.14 | Create listing detail UI | ⬜ | `templates/marketplace/detail.html` - Item, bids, timer |
+| 8.15 | Create listing creation UI | ⬜ | `templates/marketplace/create.html` - Form for creating listings |
+| 8.16 | Create my listings/bids UI | ⬜ | `templates/marketplace/my-listings.html` |
+
+**Deliverable:** Full marketplace UI
+
+---
+
+### Testing & Validation (3 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 8.17 | Test auction flow | ⬜ | Full auction cycle: list → bid → expire → award |
+| 8.18 | Test tier restrictions | ⬜ | Verify Premium+ only |
+| 8.19 | **Final Checkpoint:** Integration test | ⬜ | Complete buy/sell flow |
+
+**Deliverable:** Validated marketplace system
+
+---
+
+## API Endpoints Summary
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/v1/marketplace` | Browse listings (filter, sort, paginate) |
+| `GET` | `/api/v1/marketplace/listings/{id}` | Get listing detail |
+| `POST` | `/api/v1/marketplace/listings` | Create new listing |
+| `POST` | `/api/v1/marketplace/listings/{id}/bid` | Place bid |
+| `POST` | `/api/v1/marketplace/listings/{id}/buyout` | Instant purchase |
+| `DELETE` | `/api/v1/marketplace/listings/{id}` | Cancel listing |
+| `GET` | `/api/v1/marketplace/my-listings` | Get user's listings |
+| `GET` | `/api/v1/marketplace/my-bids` | Get user's active bids |
+
+---
+
+## Files to Create/Modify
+
+**New Files:**
+- `/api/app/models/marketplace.py` - MarketplaceListing, Bid
+- `/api/app/services/marketplace_service.py` - Marketplace operations
+- `/api/app/api/marketplace.py` - Marketplace API blueprint
+- `/api/app/tasks/marketplace_tasks.py` - Auction processing job
+- `/public_web/templates/marketplace/browse.html`
+- `/public_web/templates/marketplace/detail.html`
+- `/public_web/templates/marketplace/create.html`
+- `/public_web/templates/marketplace/my-listings.html`
+
+**Modified Files:**
+- `/api/app/__init__.py` - Register marketplace blueprint
+- `/api/app/services/character_service.py` - Gold transfer, item transfer
+
+---
+
+## Testing Criteria
+
+### Unit Tests
+- [ ] Listing creation validation
+- [ ] Bid validation (must exceed current bid)
+- [ ] Buyout validation (sufficient gold)
+- [ ] Fee calculation (5%)
+
+### Integration Tests
+- [ ] Create listing → item removed from inventory
+- [ ] Place bid → gold held in escrow
+- [ ] Outbid → gold returned to previous bidder
+- [ ] Auction ends → item transferred, gold transferred
+- [ ] Cancel listing → item returned
+
+### Manual Testing
+- [ ] Browse and filter listings
+- [ ] Create auction and fixed-price listings
+- [ ] Bid on auctions
+- [ ] Buyout items
+- [ ] Check notifications when outbid
+
+---
+
+## Success Criteria
+
+- [ ] Premium/Elite tier restriction enforced
+- [ ] Listings created and displayed correctly
+- [ ] Bidding works with proper validation
+- [ ] Buyout works with instant purchase
+- [ ] Auctions expire and resolve correctly
+- [ ] 5% fee deducted on sales
+- [ ] Notifications sent when outbid
+- [ ] UI is responsive and functional
+
+---
+
+## Dependencies
+
+**Requires (already implemented):**
+- Character system (inventory, gold)
+- Item system
+- Authentication with tiers
+
+---
+
+## Task Summary
+
+| Group | Tasks | Checkpoints |
+|-------|-------|-------------|
+| Marketplace Data Models | 2 | 1 |
+| Marketplace APIs | 6 | 0 |
+| Auction Processing | 3 | 0 |
+| Marketplace UI | 4 | 0 |
+| Testing & Validation | 2 | 1 |
+| **Total** | **17** | **2** |
--- a/docs/phases/Phase9-FrontendPolish.md
+++ b/docs/phases/Phase9-FrontendPolish.md
@@ -0,0 +1,219 @@
+# Phase 9: Frontend Polish
+
+**Goal:** Improve UI/UX, add HTMX interactivity, create cohesive design system
+**Priority:** Medium
+**Status:** Not Started
+**Last Updated:** November 29, 2025
+
+---
+
+## Overview
+
+Polish the web frontend with a cohesive dark fantasy aesthetic, responsive design, and smooth HTMX-powered interactions. This phase focuses on user experience improvements without adding new features.
+
+**Key Goals:**
+- Dark fantasy visual theme
+- Mobile-responsive design
+- No full page reloads (HTMX everywhere)
+- Reusable component library
+- Loading states and error handling
+- Subtle animations for feedback
+
+---
+
+## Task Groups
+
+### Design System (4 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 9.1 | Design CSS color palette | ⬜ | Dark fantasy: deep purples, golds, parchment tones |
+| 9.2 | Create typography system | ⬜ | Fantasy-appropriate fonts, readable hierarchy |
+| 9.3 | Design component library | ⬜ | Buttons, cards, modals, forms, alerts |
+| 9.4 | **Checkpoint:** Review design system | ⬜ | Verify consistency across components |
+
+**Color Palette (Example):**
+```css
+:root {
+  /* Backgrounds */
+  --bg-primary: #1a1a2e;      /* Deep navy */
+  --bg-secondary: #16213e;    /* Darker blue */
+  --bg-card: #0f3460;         /* Card background */
+
+  /* Accents */
+  --accent-gold: #c9a227;     /* Gold highlights */
+  --accent-purple: #7b2cbf;   /* Magic purple */
+  --accent-red: #9e2a2b;      /* Danger/combat */
+
+  /* Text */
+  --text-primary: #e8e8e8;    /* Main text */
+  --text-secondary: #a0a0a0;  /* Muted text */
+  --text-gold: #ffd700;       /* Important text */
+}
+```
+
+**Deliverable:** Documented design system with CSS variables
+
+---
+
+### Responsive Layout (3 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 9.5 | Implement mobile navigation | ⬜ | Hamburger menu, slide-out nav |
+| 9.6 | Create responsive grid system | ⬜ | Flexbox/Grid layouts that adapt |
+| 9.7 | Test on multiple screen sizes | ⬜ | Mobile, tablet, desktop breakpoints |
+
+**Breakpoints:**
+```css
+/* Mobile first */
+@media (min-width: 640px) { /* Tablet */ }
+@media (min-width: 1024px) { /* Desktop */ }
+@media (min-width: 1280px) { /* Large desktop */ }
+```
+
+**Deliverable:** Mobile-friendly responsive layouts
+
+---
+
+### HTMX Enhancements (4 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 9.8 | Audit all pages for full page reloads | ⬜ | Identify and fix |
+| 9.9 | Implement partial updates everywhere | ⬜ | Use `hx-swap`, `hx-target` correctly |
+| 9.10 | Add `hx-indicator` loading states | ⬜ | Show spinners during requests |
+| 9.11 | Implement `hx-push-url` for history | ⬜ | Browser back/forward works |
+
+**HTMX Pattern:**
+```html
+<button hx-post="/api/action"
+        hx-target="#result-area"
+        hx-swap="innerHTML"
+        hx-indicator="#loading-spinner">
+  Take Action
+</button>
+<div id="loading-spinner" class="htmx-indicator">
+  <span class="spinner"></span> Loading...
+</div>
+```
+
+**Deliverable:** Seamless HTMX-powered interactions
+
+---
+
+### Reusable Components (4 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 9.12 | Create character card component | ⬜ | `partials/character_card.html` |
+| 9.13 | Create item card component | ⬜ | `partials/item_card.html` - rarity colors |
+| 9.14 | Create stat bar component | ⬜ | `partials/stat_bar.html` - HP, mana, XP |
+| 9.15 | Create notification/toast component | ⬜ | `partials/toast.html` - success, error, info |
+
+**Deliverable:** Reusable Jinja2 partial templates
+
+---
+
+### Feedback & Polish (4 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 9.16 | Add loading states for AI calls | ⬜ | Typing indicator, "DM is thinking..." |
+| 9.17 | Implement user-friendly error displays | ⬜ | Friendly messages, not stack traces |
+| 9.18 | Add dice roll animations | ⬜ | `static/js/dice-roller.js` - visual d20 roll |
+| 9.19 | Add combat action animations | ⬜ | Flash effects for damage, healing |
+
+**Deliverable:** Polished user feedback
+
+---
+
+### Cross-Browser Testing (2 tasks)
+
+| Task ID | Task | Status | Notes |
+|---------|------|--------|-------|
+| 9.20 | Test on Chrome, Firefox, Safari | ⬜ | Fix any browser-specific issues |
+| 9.21 | **Final Checkpoint:** UI review | ⬜ | Complete visual audit |
+
+**Deliverable:** Cross-browser compatible UI
+
+---
+
+## Files to Create/Modify
+
+**New Files:**
+- `/public_web/static/css/design-system.css` - CSS variables, base styles
+- `/public_web/static/css/components.css` - Component styles
+- `/public_web/static/js/dice-roller.js` - Dice animation
+- `/public_web/static/js/toast.js` - Toast notifications
+- `/public_web/templates/partials/character_card.html`
+- `/public_web/templates/partials/item_card.html`
+- `/public_web/templates/partials/stat_bar.html`
+- `/public_web/templates/partials/toast.html`
+- `/public_web/templates/partials/loading.html`
+
+**Modified Files:**
+- `/public_web/templates/base.html` - Include new CSS/JS, design tokens
+- `/public_web/templates/**/*.html` - Apply design system, HTMX patterns
+
+---
+
+## Testing Criteria
+
+### Visual Testing
+- [ ] Design system applied consistently
+- [ ] Colors and typography match spec
+- [ ] Components look correct in all states
+
+### Responsive Testing
+- [ ] Mobile layout works (320px - 640px)
+- [ ] Tablet layout works (640px - 1024px)
+- [ ] Desktop layout works (1024px+)
+- [ ] Navigation works on all sizes
+
+### HTMX Testing
+- [ ] No full page reloads during gameplay
+- [ ] Loading indicators show during requests
+- [ ] Browser back/forward works
+- [ ] Errors display gracefully
+
+### Browser Testing
+- [ ] Chrome (latest)
+- [ ] Firefox (latest)
+- [ ] Safari (latest)
+- [ ] Mobile Safari
+- [ ] Chrome Mobile
+
+---
+
+## Success Criteria
+
+- [ ] Cohesive dark fantasy aesthetic
+- [ ] Mobile-responsive on all pages
+- [ ] No full page reloads in main flows
+- [ ] Loading states for all async operations
+- [ ] User-friendly error messages
+- [ ] Reusable component library
+- [ ] Works across major browsers
+
+---
+
+## Dependencies
+
+**Requires (already implemented):**
+- All core gameplay features
+- HTMX integration (basic)
+
+---
+
+## Task Summary
+
+| Group | Tasks | Checkpoints |
+|-------|-------|-------------|
+| Design System | 3 | 1 |
+| Responsive Layout | 3 | 0 |
+| HTMX Enhancements | 4 | 0 |
+| Reusable Components | 4 | 0 |
+| Feedback & Polish | 4 | 0 |
+| Cross-Browser Testing | 1 | 1 |
+| **Total** | **19** | **2** |