familiar-vtt 0.1.0

package/BUSINESS.md

@@ -0,0 +1,547 @@
+# Familiar — Business & Strategy
+
+## Vision
+
+**Problem**: DMs with busy lives (kids, work, everything) want to run great sessions but don't have hours to prep. Existing AI DM tools are text-only (Friends & Fables) or barely functional.
+
+**Solution**: An AI DM assistant that controls a real virtual tabletop. The AI manages scenes, moves tokens on battle maps, tracks combat, rolls dice, plays music, triggers animations — everything a human DM does in Foundry, but automated. The DM stays in control; the AI handles the heavy lifting.
+
+**Who this is for**:
+- DMs who don't have time to prep but want full VTT sessions
+- Solo players or small groups without a dedicated DM
+- DMs who want AI assistance during live sessions (NPC dialogue, rule lookups, encounter management)
+
+**Positioning**: We don't compete with visual modules (Dice So Nice, Sequencer, Token Magic FX) — we **integrate** with them. We don't replace the DM — we **assist** them. We don't rebuild what exists — we **orchestrate** it.
+
+**Approach**: Build iteratively — implement a feature, test it live against the running Foundry instance, verify it works, then move on. No big-bang releases.
+
+## Market Context
+
+- Only serious AI DM project for Foundry VTT (the original foundry-vtt-mcp has 23 working tools and is largely dormant)
+- Text-only AI DMs exist (Friends & Fables with 100k+ users, AI Game Master, AI Realm) but no one else controls a real VTT with 124+ tools
+- Foundry has ~5,000 modules and 70,000+ community members — massive ecosystem to integrate with
+- The Foundry creator is anti-AI, but we're pro-creativity: helping DMs, not replacing them or artists
+
+## Business Model
+
+- **Closed source** — proprietary. Protects competitive advantage as the only serious AI DM platform for Foundry VTT
+- **Current phase**: Everything free. Focus on building the product, getting users, and proving the concept. No paywall until we have enough premium content to justify it
+- **Free tier** (built-in LLM client): User's own API key, works great for chat, moving tokens, basic AI assistance. Most users will be happy here
+- **Paid tier** (€5/month "AI DM Pro"): For power users who want the AI to fully DM sessions, prep encounters, generate battlemaps, run entire campaigns. We set up MCP integration with their existing AI subscription (Claude Max, ChatGPT Plus, Gemini Advanced, etc.) so they can use unlimited AI with their flat-fee plan. Plus premium features
+- **Planned premium features**: AI battlemap generation, AI portrait/token art generation, AI NPC voices, campaign modules (Ember etc.), premium visual effect presets, premium sound presets
+- **MCP setup service** (Phase 13): One-click MCP configs for top 3 AI platforms (Claude, Gemini, ChatGPT). Setup wizard in module settings auto-detects OS, generates config, copy-to-clipboard. Subscriber's existing AI subscription powers unlimited AI DM. Gemini is free (no subscription needed). See Phase 13 for full details
+- **Future license enforcement**: Stripe subscription → license key → verified at startup. One serverless function, no usage tracking, no metering
+
+## Installation Vision: Plug & Play
+
+**Goal**: Install module in Foundry → pick your AI → paste API key → done. No terminal, no Node.js, no MCP knowledge.
+
+### Target User Experience
+1. Foundry → Install Modules → paste manifest URL or find in package browser → Enable
+2. Module Settings → pick AI provider → paste API key → Connect
+3. Start playing with your AI DM
+
+### Supported AI Providers (planned)
+The module settings will offer pre-configured providers. User just picks one and pastes their API key:
+
+| Provider | Models | Key |
+|----------|--------|-----|
+| OpenRouter | 200+ models (Claude, GPT-4, Gemini, Llama, Mistral, etc.) — one key for everything | `sk-or-...` |
+| Anthropic | Claude Opus 4, Sonnet 4, Haiku 4 | `sk-ant-...` |
+| OpenAI | GPT-4o, GPT-4.1, o3, o4-mini | `sk-...` |
+| Google | Gemini 2.5 Pro, Gemini 2.5 Flash | `AIza...` |
+| Groq | Llama, Mistral, Gemma (fast & cheap) | `gsk_...` |
+| Mistral | Mistral Large, Medium, Small | `...` |
+| Together AI | Open source models (Llama, Qwen, DeepSeek) | `...` |
+| DeepSeek | DeepSeek V3, R1 (powerful & affordable) | `sk-...` |
+| xAI (Grok) | Grok 3, Grok 3 Mini | `xai-...` |
+| Cohere | Command R+, Command A (strong tool use) | `...` |
+| Perplexity | Sonar Pro (AI search with web access) | `pplx-...` |
+| Fireworks AI | Fast inference (Llama, DeepSeek, Qwen) | `fw_...` |
+| Cerebras | Ultra-fast inference (fastest Llama) | `csk-...` |
+| SambaNova | Fast inference with free tier | `...` |
+| LM Studio | Local models via LM Studio (free, private) | localhost |
+| Ollama | Any local model (free, private, no API key) | localhost |
+
+**Voice providers** (NPC dialogue — separate API key):
+
+| Provider | Voices | Key |
+|----------|--------|-----|
+| ElevenLabs (Recommended) | 10,000+ voices, best quality + sound effects | `sk_...` |
+| Cartesia (Sonic) | Ultra-fast (40ms latency), real-time NPC dialogue | `...` |
+| PlayHT | 600+ voices, 140+ languages, budget option | `...` |
+| OpenAI TTS | 10 voices (Alloy, Nova, Onyx, etc.), uses existing OpenAI key | `sk-...` |
+
+**Image providers** (battlemaps, portraits, tokens — separate API key):
+
+| Provider | Models | Key |
+|----------|--------|-----|
+| OpenAI (DALL-E / GPT Image) | GPT Image 1, DALL-E 3 | `sk-...` |
+| Stability AI | Stable Diffusion 3.5, Stable Image Ultra/Core | `sk-...` |
+| fal.ai (Flux) | Flux Pro, Dev, Schnell (fast & cheap) | UUID key |
+| Leonardo AI | Fantasy art specialization (great for D&D) | `...` |
+| Replicate | 200+ community models, custom fine-tunes | `r8_...` |
+
+**Recommended for beginners**: OpenRouter — one key, all models, pay per use.
+**Total**: 16 chat + 4 voice + 5 image = **25 AI providers**.
+
+### Architecture: Current (MCP) vs. Future (Built-in)
+
+**Current architecture** (works now, power users):
+```
+MCP Client (Claude Desktop/Code/Cursor)
+    ↓ stdio (MCP protocol)
+MCP Server (Node.js process)
+    ↓ WebSocket (localhost)
+Foundry Module (browser)
+    ↓ Foundry API
+Game World
+```
+
+**Future architecture** (plug & play, everyone):
+```
+Foundry Module (browser)
+    ├── Built-in LLM client (calls AI provider API directly)
+    ├── Tool execution (same 124 tools, runs in browser)
+    ├── Chat UI in Foundry sidebar
+    └── Foundry API
+Game World
+```
+
+The future architecture eliminates the MCP server entirely. The Foundry module talks directly to the AI provider API. No Node.js, no separate process, no MCP config. Everything lives inside the Foundry module.
+
+**Both architectures will be supported** — MCP for power users who want Claude Code/Cursor integration, built-in for everyone else.
+
+### Release Roadmap
+```
+PHASE 1 (now):    MCP server + Foundry module (current, working)
+PHASE 2 (next):   Foundry package browser listing + npx support
+                   → 2-step install: module + MCP config
+PHASE 3 (target): Built-in LLM client in Foundry module
+                   → 1-step install: module only, pick AI in settings
+```
+
+## Competitive Landscape
+
+### vs. FoundryAI (derekhearst — primary competitor, actively developed)
+
+FoundryAI is a browser-only Foundry module with OpenRouter integration. Open source (MIT).
+Built with AI assistance (6,600 lines first commit, 0→v1.0 in 24 hours). Study their code at github.com/derekhearst/FoundryAI
+
+| Aspect | FoundryAI | Familiar (this) |
+|--------|-----------|-------------------|
+| Working tools | ~45 | **124** (3x more) |
+| Canvas layers (walls, lights, sounds, notes) | None | **31 tools** |
+| Audio/playlists | Basic | **6 tools** (full control) |
+| Macros | None | **4 tools** (CRUD + execute) |
+| Folders/Regions | None | **6 tools** |
+| Weather/darkness/fog | None | **Yes** |
+| In-browser chat UI | **Yes (Svelte sidebar)** | **Yes** (ApplicationV2 popout, streaming, tool badges) |
+| Quick actions menu | No | **Planned** (one-click combat/scene/music/lookup actions) |
+| Plug & play install | **Yes (module + API key)** | **Yes** (settings UI + chat UI + floating button) |
+| Multi-provider | **Yes (OpenRouter)** | **Yes** (25 providers: 16 chat + 4 voice + 5 image) |
+| RAG/vector search | **Yes (IndexedDB)** | Not yet |
+| Text-to-speech | **Yes (OpenRouter TTS)** | Not yet |
+| Session recaps | **Yes (auto journal)** | Not yet |
+| NPC roleplay mode | **Yes (per-actor chat)** | Not yet |
+| Architecture | Browser-only | MCP server + browser module |
+| Status | Active (updated daily) | Active |
+
+**Their architecture (learn from this):**
+- Raw `fetch()` to OpenRouter API — no SDK, no proxy. 3 runtime deps (micromark only)
+- Tools defined in OpenAI function-calling format, executed via switch statement in browser
+- Svelte 5 (runes mode) for chat UI, mounted in ApplicationV2 via SvelteApplication bridge
+- SSE streaming with ReadableStream reader
+- Settings: all `config: false` + custom Svelte panel via `registerMenu()`
+- Chat sessions persisted as JournalEntry flags
+- Context tracking with auto-summarization when threshold hit
+- Build: Vite + Svelte 5 + SCSS
+
+**Their UX features we should adopt (observed March 2026):**
+- **AI Settings panel**: max tokens, max tool calls sliders as parameters
+- **Tool category toggles**: ~40 tools organized in categories, each toggleable on/off — lets users limit what the AI can do
+- **Text-to-speech**: Enable TTS toggle for NPC dialogue
+- **AI Data Access**: Configure which journal folders the AI can read
+- **System prompt override**: Custom system prompt field
+- **Context management**: Auto-summarize when context exceeds 85% threshold, configurable
+- **Chat session manager**: List all chats (like Claude's sidebar), new chat / archive / switch between sessions
+- **Context indicator**: Visual bubble showing token usage (e.g. "0 / 200k") — always visible
+- **Roleplay as Actor**: Button to start dedicated NPC chat session
+- **Reindex RAG**: Rebuild the vector index on demand
+- **Generate Session Recap**: One-click journal summary of the session
+
+**Where we beat them:** 3x tools (124 vs ~45), full canvas control, complete VTT coverage, 25 AI providers, quick actions menu (planned)
+**Where they beat us:** UX maturity (chat sessions, context tracking, TTS, RAG, session recaps, actor roleplay, tool toggles)
+**Strategy:** Keep our tool advantage, systematically close the UX gap. Priority order:
+1. Quick Actions menu (differentiator — they don't have this)
+2. Chat sessions (new chat / archive / switch)
+3. Context tracking with auto-summarization
+4. Tool category toggles (let users control what AI can do)
+5. Session recaps
+6. TTS / Actor roleplay / RAG
+
+### vs. foundry-vtt-mcp (adambdooley — largely dormant since Jan 2026)
+
+| Aspect | foundry-vtt-mcp | Familiar (this) |
+|--------|---------------------------|-------------------|
+| Working tools | 23 (token tools broken) | **124** (19 domains) |
+| Combat management | None | Full (start, end, turns, initiative) |
+| Canvas layers | None | 31 tools (walls, lights, sounds, notes, doors) |
+| Audio/playlists | None | 6 tools |
+| Architecture | Dual-process (wrapper + backend) | Single process |
+| Status | Last commit Jan 30, 2026 | Actively developed |
+
+### vs. Other Foundry AI modules
+
+| Module | Type | Tools | Active | Notes |
+|--------|------|-------|--------|-------|
+| Loremaster | Chat + proxy | 11 | Yes | $5-30/mo subscription, PDF adventure upload, Year Zero Engine only |
+| Cibola 8 | Image gen | 0 | Yes | AI portraits/battlemaps/TTS, Patreon subscription |
+| RPGX AI Assistant | Chat (Ollama) | 0 | Moderate | Local LLM chatbot, 0.59% market share (~500 installs) |
+| Phil's AI Assistant | Prompt gen | 0 | Yes | Copy/paste workflow, zero API cost |
+| PF2e AI Combat | Combat advisor | 0 | No | PF2e only, suggestions only |
+| foundryvtt-mcp (laurigates) | MCP + Socket.IO | 19 | Yes | No module needed, `npx` install, no canvas control |
+
+### vs. Friends & Fables (fables.gg — standalone AI TTRPG platform)
+
+Friends & Fables is a standalone web-based AI TTRPG platform (not a VTT module). Built by Sidequest Labs (cofounders Will Liu & David Melnychuk). Claims 100,000+ users, 10,000+ Discord members. Started as a Discord bot, evolved into a full web platform. Self-described as "the world's first generative tabletop roleplaying game (GTTRPG)."
+
+**How it works**: Players interact via text with an AI Game Master called "Franz." Franz narrates, adjudicates D&D 5e rules, tracks stats, manages inventory, and adapts to player choices. It's a text RPG with some visual elements (generated maps, images), not a traditional VTT.
+
+**Tech stack**: Next.js + Tailwind CSS frontend. Multi-model AI backend using a "mixture of models depending on the task" — Gemini, Llama, GPT, Grok, plus custom fine-tuned models. Two narration models: "Finch" (fast) and "Fenix" (premium, better instruction following). Powered by their "ACE-1" engine (Agentic Campaign Engine).
+
+**ACE-1 Architecture (innovative — study this)**:
+- Multiple specialized AI agents that collaborate: one for narration, one for rule-checking, one for state-tracking
+- Purpose-built TTRPG database for game state (not unstructured chat history) — character stats, coordinates, locations, quests stored structurally
+- "Atomic memory" system — memories stored as discrete facts ("Neela offered 50 gold for safe transport of her cat") rather than hierarchical summaries that lose detail
+- Smart memory prioritization by type, recency, and algorithmic scoring; users can lock critical memories
+- Memory capacity tiered: Free 30, Starter 50, Pro 70, Legend 100
+- "Unknown Entity System" — NPCs/locations stay hidden until players encounter them at matching coordinates, preventing metagaming
+- NPC relationship tracking — scores adjust based on player interactions (gifts increase, violence decreases)
+- Trope reduction algorithm — actively avoids clichés (Elara, hooded figures, windmills), steerable by user feedback
+- "View Context" button lets users inspect what Franz actually sees — great for debugging
+- "@mention" system guarantees specific entity info is included in next AI response
+
+**Key features**:
+- AI Game Master (Franz) with D&D 5e rules enforcement
+- Solo play or multiplayer (up to 6 players, async/sync)
+- World building tools: continents, cities, dungeons, NPCs, monsters, items, spells, lore pages
+- Quest system with branching paths and dynamic outcomes
+- POI (Point of Interest) maps — auto-generated, players can place tokens
+- Text-to-speech narration with per-NPC character voices
+- Image generation for characters, locations, items
+- Travel system between locations
+- Inventory management with carrying capacity
+- NPC conversation mode (isolated to nearby characters)
+- Adventure vs. Downtime pacing modes
+- Community world sharing (play worlds others created)
+- Custom instructions segmented by function (narration vs. NPC dialogue) with validation feedback
+
+**Pricing** (as of late 2025):
+- **Free**: 5-25 AI turns/day, 3-player campaigns, 30 memories
+- **Starter**: $19.95/mo — unlimited turns, 4 players, 50 memories, 100 credits, 6,500 char context
+- **Pro**: $29.95/mo — 5 players, 70 memories, 300 credits, 9,000 char context
+- **Legend**: $39.95/mo — 6 players, 100 memories, 600 credits, 13,500 char context
+- Credits used for premium narration model (Fenix) and image generation
+- Annual billing: ~17% discount
+
+**Strengths (what we can learn from)**:
+1. **Structured game state DB** — they don't store game state in chat history, they use a purpose-built database. This prevents hallucination and accuracy degradation over long sessions. We should consider structured state for our context management
+2. **Atomic memory system** — discrete facts vs. lossy summarization. Better than simple "summarize old messages" approach
+3. **Multi-agent architecture** — specialized agents for different tasks (narration, rules, state) rather than one monolithic prompt. Could inspire our tool-calling architecture
+4. **Trope reduction** — actively fighting AI clichés is a great UX touch
+5. **Context transparency** — "View Context" button builds trust and helps debugging
+6. **Entity mention system** — "@mention to guarantee context inclusion" is a smart UX pattern
+7. **Community world sharing** — marketplace/library of pre-built worlds
+8. **Async multiplayer** — play-by-post style, everyone plays at their own pace
+9. **Instruction validation** — telling users if their custom instructions will work as intended
+10. **Per-NPC voices** — Franz switches voices during dialogue automatically
+
+**Weaknesses (where we win)**:
+1. **No real VTT** — text-only with basic POI maps. No battle maps, no token movement on grids, no walls/lighting, no fog of war. Our 124 tools controlling a real VTT is a fundamentally different (superior) experience for tactical combat
+2. **No module ecosystem** — standalone platform, can't integrate with 5,000+ Foundry modules (Dice So Nice, Sequencer, Token Magic FX, etc.)
+3. **No visual combat** — no grid-based tactical combat with token positioning, line of sight, AoE templates. Their "combat" is text descriptions
+4. **Memory complaints** — users report "it needs constant reminding of what you are trying to do" and having to repeat requests. Their atomic memory helps but context windows are still small (6,500-13,500 chars on paid tiers)
+5. **Expensive** — $20-40/mo for a text RPG. We're free (user brings own API key) or $5/mo for premium
+6. **Vendor lock-in** — users can't choose their own AI model/provider. We support 25 providers
+7. **No existing content import** — can't use D&D Beyond characters, published adventures, existing Foundry worlds. We work with whatever's already in your Foundry
+8. **Closed ecosystem** — everything happens inside their platform. We integrate with the DM's existing workflow
+9. **Generic tropes** — despite their trope reduction system, users report clichéd outputs requiring careful prompting
+10. **Server reliability** — peak-hour slowdowns reported; we run locally
+
+**Key differentiator**: They're building a standalone AI-first TTRPG platform. We're building an AI assistant for an existing professional-grade VTT. Different philosophies:
+- Friends & Fables: "Replace the VTT with AI-native text RPG"
+- Familiar: "Augment the VTT with AI — keep everything DMs already love, add intelligence"
+
+Their target audience is people who want quick AI-driven text adventures (especially solo or async). Our target audience is DMs who want AI assistance while running full visual VTT sessions.
+
+**Ideas to steal**:
+- Atomic memory for session persistence (Phase 12 context management)
+- Context visibility ("View Context" equivalent in our chat UI)
+- Entity @mention system for guaranteed context inclusion
+- Trope reduction patterns in system prompts
+- Instruction validation feedback
+- Community-shared content (quest modules, world templates)
+- Adventure vs. Downtime pacing modes as system prompt presets
+
+### vs. Other Text-only AI DMs (AI Realm, AI Game Master, etc.)
+
+| Aspect | Text-only AI DMs | Familiar |
+|--------|-----------------|-------------|
+| Battle maps | No | Yes — full token/scene control |
+| Visual combat | No | Yes — initiative, conditions, HP tracking on map |
+| Music/ambiance | No | Yes — playlist control |
+| Dice with visuals | No | Yes — 3D dice (via Dice So Nice) |
+| Animations | No | Planned (via Sequencer + JB2A) |
+| Module ecosystem | N/A | Integrates with 5,000+ Foundry modules |
+
+## Implementation Phases
+
+### Phase 1 — Foundation ✅
+- [x] Project scaffold (TypeScript, ESLint, Vitest, Husky)
+- [x] Shared protocol (Zod schemas, message types)
+- [x] WebSocket connector (server-side, with ping/pong)
+- [x] Config (Zod-validated env vars)
+- [x] Logger (Pino)
+
+### Phase 2 — MCP Server Core ✅
+- [x] MCP server with stdio transport (`@modelcontextprotocol/sdk`)
+- [x] Tool registry pattern
+- [x] Wire connector to MCP tool calls
+- [x] Read-only tools: `get-world-info`, `get-character`, `list-characters`, `list-party-members`
+- [x] Tests for server + tools (protocol test fixed)
+
+### Phase 3 — Foundry Module ✅
+- [x] Module manifest (`module.json`)
+- [x] WebSocket client with reconnection logic
+- [x] Query handler routing
+- [x] Character data access (read — full D&D 5e sheet formatting)
+- [x] Scene data access (read)
+- [x] Module settings UI (port, auto-connect)
+- [x] Module deployed and live in Foundry (Ember world)
+
+### Phase 4 — Live Testing & Fixes ✅
+- [x] Live test all existing tools against Ember world
+- [x] Fix broken tools found during testing
+- [x] Verify data formats are correct (D&D 5e 2024 system paths)
+- [x] Code cleanup: 112 lint errors → 0, Foundry type declarations, registerTool API
+- [x] `toggle-pause` tool added (needs MCP server restart to test)
+
+### Phase 5 — Session Essentials (Complete the MVP) ✅
+- [x] `update-token` (hidden, elevation, size, rotation, disposition)
+- [x] `roll-dice` — roll formula (1d20+5, 2d6+3), show result in Foundry chat
+- [x] `search-compendium` — search items/creatures/spells by name
+- [x] `get-compendium-entry` — full stat block (with compact mode option)
+- [x] `list-compendium-packs` — available packs
+- [x] `switch-scene` — change active scene
+
+### Phase 6 — Encounter & Combat Management ✅
+- [x] `create-actor-from-compendium` — spawn creatures into world from compendium
+- [x] `create-tokens` — place tokens on scene at x,y (batch support)
+- [x] `delete-tokens` — remove tokens from scene
+- [x] Combat management: `start-combat`, `end-combat`, `get-combat`, `next-turn`, `next-round`
+- [x] Initiative rolls: `roll-initiative`, `roll-npc-initiative`
+- [x] `get-available-conditions` — list all system status effects
+
+### Phase 7 — Character & Inventory Deep Dive ✅
+- [x] `search-character-items` — search inventory/spells/features (token-efficient)
+- [x] `get-character-item` — full detail for specific item/spell/feature on a character
+- [x] `add-compendium-to-character` — add item/spell from compendium
+- [x] `delete-character-items` — remove items
+- [x] `rename-character`
+- [x] Creature filtering: search by CR, type, size (for encounter building)
+- [ ] `use-item` — cast spell / use ability (triggers Foundry dialog) — deferred
+
+### Phase 8 — Campaign & Journal Tools (Ember Content) ✅
+- [x] `list-journals` — list all journal entries (filter by folder)
+- [x] `search-journals` — search by title/content with snippets
+- [x] `get-journal` — full journal with all pages (HTML stripped)
+- [x] `get-journal-page` — single page with full content
+- [x] `assign-ownership` — give player access to an actor (NONE/LIMITED/OBSERVER/OWNER)
+- [x] `remove-ownership` — revoke player access
+
+### Phase 9 — Canvas Controls ✅
+- [x] 30 canvas tools: templates, tiles, drawings, walls, lights, sounds, notes (full CRUD)
+- [x] `toggle-door`, `close-all-doors` — door control
+- [x] `set-darkness` — animated darkness level transitions
+- [x] `reset-fog` — reset fog of war exploration
+- [x] `capture-screen` — screenshot the current canvas view
+
+### Phase 10 — Environment & Atmosphere ✅
+- [x] `get-weather-effects`, `set-weather` — weather effect presets (rain, snow, fog, etc.)
+- [x] `send-chat-message`, `get-recent-messages` — chat integration
+- [x] `list-playlists`, `play-playlist`, `stop-playlist`, `stop-all-playlists` — playlist control
+- [x] `play-track`, `stop-track` — individual track control
+- [x] `list-rollable-tables`, `get-rollable-table`, `roll-table` — rollable tables
+- [x] `list-card-stacks`, `get-card-stack`, `draw-cards`, `shuffle-deck`, `reset-deck` — card stacks
+- [x] `list-macros`, `create-macro`, `execute-macro`, `delete-macro` — macro management
+
+### Phase 11 — Polish & Release
+- [x] Fix ESLint violations — 0 errors
+- [x] Fix test suite — passing
+- [ ] README with setup instructions
+- [ ] Foundry package browser listing (submit to foundryvtt.com/packages/submit)
+- [ ] GitHub Actions release workflow (build → zip → upload → Foundry API)
+
+### Phase 12 — Plug & Play (Built-in LLM Client)
+The #1 priority. Eliminates the MCP server requirement. Users install the module and go.
+
+- [x] AI provider settings UI (ApplicationV2 — custom _renderHTML, no Handlebars)
+  - 16 chat providers (OpenRouter, OpenAI, Anthropic, Google, Groq, Mistral, Together AI, DeepSeek, xAI, Cohere, Perplexity, Fireworks, Cerebras, SambaNova, LM Studio, Ollama)
+  - 4 voice providers (ElevenLabs, Cartesia, PlayHT, OpenAI TTS) — separate API key for NPC dialogue
+  - 5 image providers (OpenAI DALL-E, Stability AI, fal.ai, Leonardo AI, Replicate) — separate API key for battlemaps/portraits
+  - 3 independent API keys active simultaneously (chat + voice + image)
+  - Model/voice dropdown (static defaults + dynamic fetch from provider API)
+  - Test connection button (auto-fetches models/voices on success)
+  - Enable toggles for voice and image (collapsed when disabled)
+  - Temperature slider, max tokens, streaming toggle
+  - Scrollable window for smaller screens
+  - Save/Cancel buttons
+  - Tested: OpenRouter ✅, OpenAI ✅ — all providers use same pattern
+- [x] Built-in LLM client (browser → AI provider API directly via fetch)
+  - No proxy needed — OpenAI, Anthropic, OpenRouter all support CORS from browser
+  - 124 tools in OpenAI function-calling format (src/module/ai/tools/*.ts)
+  - Tool execution calls Foundry handlers directly in-browser (no WebSocket round-trip)
+  - SSE streaming parser with async generator (src/module/ai/streaming.ts)
+  - Anthropic Messages API adapter (src/module/ai/anthropic-adapter.ts)
+  - Multi-step tool calling loop (up to 15 iterations)
+  - Provider-agnostic: works with all 16 chat providers from settings
+  - StreamCallbacks API for UI integration (onToken, onToolCallStart, onToolCallEnd, onComplete, onError)
+- [x] Lazy-loaded tool bundles (industry best practice — reduces token overhead by ~90%)
+  - 124 tools organized into 19 domain bundles (characters, scenes, combat, etc.)
+  - Core bundles always loaded: dice, world, chat, combat, characters (~29 tools)
+  - Additional bundles enabled on demand via `list-tool-bundles` / `enable-tool-bundle` meta-tools
+  - MCP server: uses SDK enable/disable + `tools/list_changed` notifications for client sync
+  - Built-in chat: `ChatBundleManager` dynamically builds tool list per API request
+  - Addresses the "too many tools" problem: LLMs degrade at >30 tools, fail at >100 (GitHub research)
+  - Files: `src/server/tools/bundles.ts`, `src/module/ai/tools/bundles.ts`
+- [x] Chat UI in Foundry (PopOut ApplicationV2 window, not sidebar — v13 sidebar tabs are buggy)
+  - Streaming text rendering (token by token with blinking cursor)
+  - Tool call badges with category icons (124 tools, color-coded: green=done, yellow=running, red=error)
+  - Hover over tool badge → shows result JSON tooltip
+  - Thinking indicator (3 pulsing dots) before first token
+  - Custom lightweight markdown renderer (no external deps) — code blocks, bold, italic, lists, headers, links
+  - Auto-scroll to newest message
+  - Enter to send, Shift+Enter for newline, auto-resize textarea
+  - Welcome screen + "not configured" state with setup button
+  - Clear chat + Settings buttons in header
+  - D&D-themed styling: warm terracotta/beige Claude color palette, wizard hat icon, fantasy language
+  - Floating terracotta button (bottom-left) to open chat — always visible
+  - Keyboard shortcut: Ctrl+Shift+Space
+  - `familiar.openChat()` / `getMessages()` / `isProcessing()` API for macro integration
+  - Multi-turn tool calling works: text → tools → more text → more tools → final response
+  - Tested live: get-world-info, roll-dice, search-compendium → create-actor → create-tokens, set-darkness + close-all-doors + send-chat-message chains all working
+  - No framework (vanilla JS/HTML/CSS in ApplicationV2) — keeps esbuild build simple
+  - Files: `src/module/ai/chat-app.ts` (chat window), `src/module/ai/markdown.ts` (renderer)
+- [ ] Quick Actions menu (Phase 12.4 — next priority)
+  - "+" button in chat input area that opens a categorized action menu
+  - One-click common actions that auto-fill or directly execute prompts
+  - Categories with pre-built prompts:
+    - **Combat**: "Start combat", "Roll initiative for all", "Next turn", "End combat"
+    - **Scene**: "Set up ambush (darkness + doors)", "Dawn/day/dusk/night lighting", "Switch scene"
+    - **Creatures**: "Summon creature from compendium", "Place random encounter"
+    - **Music**: "Play combat music", "Play exploration music", "Stop all music"
+    - **Lookup**: "Search compendium", "Check character stats", "Look up spell/item"
+    - **Narration**: "Describe the scene", "NPC dialogue", "Roll on random table"
+  - Expandable over time with user-defined custom quick actions (saved in settings)
+  - Power users type prompts, casual users click buttons — both workflows supported
+- [ ] Session persistence (save conversations as JournalEntries)
+- [ ] Context window tracking + auto-summarization
+- [ ] Keep MCP mode for power users (Claude Desktop/Code integration)
+
+### Phase 13 — MCP for Top AI Platforms (Use Your Subscription)
+The killer feature: users pay $0-20/mo for their existing AI subscription and get **unlimited** AI DM.
+No per-token costs, no "how much does this session cost" stress — just play.
+This is 10x better than Friends & Fables and every other AI DM tool.
+
+**Business model**: Free trial (1 month) → €5/mo AI DM Pro. MCP setup pays for itself after 1 session
+(API costs for a single session = $5-15, subscription = flat $0-20/mo for unlimited).
+
+**Two paths, same 124 tools:**
+- **Free tier** (API key): Module → pick AI → paste key → done. Pay per use.
+- **Pro tier** (MCP subscription): Module → click "MCP Setup" → use your Claude/Gemini subscription. Unlimited AI DM.
+
+#### Phase 13.1 — Claude Desktop & Claude Code (Priority 1) ✅→🔨
+The #1 AI for coding and reasoning. Most power users already have Claude Pro/Max.
+- [ ] Config templates for all 3 OS (Windows, Mac, Linux)
+  - Claude Desktop: `%APPDATA%\Claude\claude_desktop_config.json` (Win), `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac), `~/.config/Claude/claude_desktop_config.json` (Linux)
+  - Claude Code: `.mcp.json` (project) or `~/.claude.json` (global)
+- [ ] MCP Setup wizard in Foundry module settings
+  - Auto-detect OS → show correct config path
+  - Copy-to-clipboard button with pre-filled config
+  - Step-by-step instructions (3 steps max)
+- [ ] Claude Desktop Extension (.mcpb) — one-click install from Claude Desktop itself
+- [ ] `npx foundry-mcp setup claude` CLI command for power users
+- [ ] Test & verify with Claude Pro subscription (Sonnet 4, Opus 4)
+- Subscription needed: Claude Pro ($20/mo) or Max ($100/mo)
+- Transport: stdio ✅ (already supported, no server changes needed)
+- Tool limit: none ✅
+
+#### Phase 13.2 — Gemini CLI (Priority 1)
+The surprise winner: **completely free** with Gemini 2.5 Pro (60 req/min, 1000/day). No subscription needed.
+This alone makes foundry-mcp accessible to everyone.
+- [ ] Config template: `~/.gemini/settings.json` (same on all OS)
+- [ ] MCP Setup wizard support for Gemini (auto-detect, copy config)
+- [ ] `npx foundry-mcp setup gemini` CLI command
+- [ ] Test & verify with Gemini CLI (free tier)
+- [ ] Document folder trust requirement (`gemini trust` needed for project folder)
+- [ ] Note: no underscores in server names (Gemini parser quirk)
+- Subscription needed: **none** (free Google account) ✅
+- Transport: stdio ✅ (already supported, no server changes needed)
+- Tool limit: none ✅
+
+#### Phase 13.3 — ChatGPT Desktop (Priority 2)
+Biggest user base. Requires HTTP/SSE transport (no stdio support). More work but huge reach.
+- [ ] Add Streamable HTTP transport to MCP server (`@modelcontextprotocol/sdk` supports it)
+  - New env var: `FOUNDRY_MCP_TRANSPORT=stdio|http` (default: stdio, backward compatible)
+  - New env var: `FOUNDRY_MCP_HTTP_PORT=3006` (separate from WebSocket port)
+  - Same single-process architecture: HTTP transport + WebSocket bridge to Foundry
+- [ ] Local HTTPS setup guide (ngrok or Cloudflare Tunnel for localhost → HTTPS)
+  - Or: bundled self-signed cert option for local-only use
+- [ ] ChatGPT Developer Mode setup instructions
+  - Settings → Apps → Create → paste MCP endpoint URL
+  - Requires ChatGPT Plus ($20/mo) or Pro ($200/mo)
+- [ ] `npx foundry-mcp setup chatgpt` CLI command (starts HTTP server + ngrok tunnel)
+- [ ] Test & verify with ChatGPT Plus subscription
+- [ ] Handle ChatGPT quirks: no error passthrough, hallucinated parameters, no workspace support
+- Transport: Streamable HTTP/SSE (new, needs implementation)
+- Tool limit: unknown (needs testing)
+- Note: Once HTTP transport exists, xAI Grok API and other HTTP-only clients get support for free
+
+#### Phase 13.4 — Future MCP Clients
+Once HTTP transport is built (Phase 13.3), these become easy additions:
+- [ ] xAI Grok (API-level MCP, HTTP/SSE) — no desktop app, API only
+- [ ] Cursor (stdio ✅ but 40-tool hard limit — needs tool profiles: combat/exploration/full)
+- [ ] Windsurf (stdio ✅ but 100-tool limit — needs 24 tools disabled, or tool profiles)
+- [ ] VS Code + GitHub Copilot (stdio ✅, growing MCP support)
+- [ ] Tool profiles system: pre-configured tool subsets for clients with limits
+  - `combat` profile: ~30 tools (combat, tokens, characters, dice)
+  - `exploration` profile: ~35 tools (scenes, canvas, audio, journals)
+  - `full` profile: all 124 tools (Claude, Gemini — no limits)
+
+### Phase 14 — Premium Features (Future)
+- [ ] AI battlemap generation (user's API key → image gen → Foundry scene)
+- [ ] AI portrait/token art generation
+- [ ] AI NPC voices (TTS via OpenRouter or ElevenLabs)
+- [ ] Campaign modules (Ember etc.)
+- [ ] RAG/vector search for world lore (local IndexedDB, embeddings via user's API)
+- [ ] Session recaps (auto-generated journal summaries)
+- [ ] Actor roleplay mode (dedicated NPC chat sessions)
+
+## Dependencies
+
+### Runtime
+- `@modelcontextprotocol/sdk` — MCP protocol implementation
+- `ws` — WebSocket server (lightweight, no socket.io overhead)
+- `zod` — Schema validation for config & protocol
+- `pino` — Fast structured logging
+
+### Dev
+- `typescript`, `tsx` — TypeScript toolchain
+- `esbuild` — Fast bundler for Foundry module
+- `eslint` + plugins — Linting (security, sonarjs, unicorn, etc.)
+- `prettier` — Formatting
+- `vitest` — Testing
+- `husky` + `lint-staged` — Pre-commit hooks
+- `commitlint` — Conventional commit enforcement
+- `knip` — Dead code detection