familiar-vtt 2.5.18 → 2.5.20

package/README.md

@@ -4,15 +4,15 @@
 
 ### Your AI co-pilot for Foundry VTT
 
-**176 tools. 28 AI providers. Zero prep.**
+**175 tools. 28 AI providers. Zero prep.**
 
-Give your favorite AI full control of your virtual tabletop - characters, combat, scenes, music, lighting, images, voices, and everything in between.
+Give your favorite AI full control of your virtual tabletop, characters, combat, scenes, music, lighting, images, voices, and everything in between.
 
 [![Foundry v13+](https://img.shields.io/badge/Foundry-v13%2B-orange?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA1MTIgNTEyIj48cGF0aCBmaWxsPSIjZmZmIiBkPSJNMjU2IDhDMTE5LjA0MyA4IDggMTE5LjA4MyA4IDI1NmMwIDEzNi45OTcgMTExLjA0MyAyNDggMjQ4IDI0OHMyNDgtMTExLjAwMyAyNDgtMjQ4QzUwNCAxMTkuMDgzIDM5Mi45NTcgOCAyNTYgOHoiLz48L3N2Zz4=)](https://foundryvtt.com)
 [![npm](https://img.shields.io/npm/v/familiar-vtt?color=blue&label=npm)](https://www.npmjs.com/package/familiar-vtt)
 [![License](https://img.shields.io/badge/license-PolyForm%20Shield-lightgrey)](#license)
 
-[Installation](#installation) | [Quick Start](#quick-start) | [Features](#features) | [Connect Your AI](#connect-your-ai) | [FAQ](#faq)
+[Installation](#installation) | [Connect Your AI](#connect-your-ai) | [FAQ](#faq) | [Roadmap](#roadmap)
 
 </div>
 
@@ -20,13 +20,17 @@ Give your favorite AI full control of your virtual tabletop - characters, combat
 
 I'm Ryan. Dad of two young kids, married to my favorite person, and perpetually short on free time.
 
-My wife and I play D&D together - just the two of us, 1-on-1 campaigns. It's our thing. But solo DMing is a lot. You're the storyteller, every NPC, the rules engine, the sound guy, and the atmosphere all at once. I'd be mid-monologue as a mysterious stranger and then have to break character to roll initiative, look up a spell range, adjust the lighting, and find that one tavern ambience track I swore I bookmarked. By the time I got back to the scene, the moment was gone.
+My wife and I play D&D together, just the two of us, 1-on-1 campaigns. It's our thing. But solo DMing is a lot. You're the storyteller, every NPC, the rules engine, the sound guy, and the atmosphere all at once. I'd be mid-monologue as a mysterious stranger and then have to break character to roll initiative, look up a spell range, adjust the lighting, and find that one tavern ambience track I swore I bookmarked. By the time I got back to the scene, the moment was gone.
 
-I wanted something that could handle the mechanical side of the table so I could stay in the story. Not a replacement DM - a co-pilot. Something I could say "roll initiative for the goblins, dim the torches, and start combat music" to, and it would just... do it. While I kept talking.
+I wanted something that could handle the mechanical side of the table so I could stay in the story. Not a replacement DM, a co-pilot. Something I could say "roll initiative for the goblins, dim the torches, and start combat music" to, and it would just... do it. While I kept talking.
 
-So I started building. First it was a handful of tools to move tokens and roll dice. Then I added combat tracking. Then scene management. Then I thought "what if it could also generate NPC portraits on the fly?" and "what if it could voice the tavern keeper?" and that's basically how you end up with 176 tools across 24 domains and 28 AI providers.
+So I started building. First it was a handful of tools to move tokens and roll dice. Then I added combat tracking. Then scene management. Then I thought "what if it could also generate NPC portraits on the fly?" and "what if it could voice the tavern keeper?" and that's basically how you end up with 175 tools across 24 domains and 28 AI providers.
 
-Familiar started as a personal itch-scratcher for a dad who wanted to run better D&D games for his wife. It turns out a lot of GMs have the same itch.
+The thing is, Familiar works best when there is already great content in your world. The Foundry community has spent years building incredible modules, battle maps, character sheets, compendium packs, and ready-to-play adventures. Familiar does not try to replace any of that. It reads what is already there and uses it. Right now I'm running [Ember](https://foundryvtt.com/packages/ember), Foundry's own 500-hour sandbox campaign, with Familiar as my co-pilot. Every quest, NPC, map, and encounter is already in the world. The AI just picks it up and runs with it. That beautifully lit dungeon map someone spent weeks on? The AI can place tokens on it, trigger the right music, and run the encounter. Those compendium entries with pre-built monsters, spells, and items? The AI pulls from them instead of making things up. The more content your world has, the better Familiar gets.
+
+That is also why module integrations are high on the roadmap. Tools like Midi-QOL, Sequencer, and JB2A already do amazing things, Familiar just needs to learn how to talk to them. The community built the stage. Familiar helps you run the show.
+
+It started as a personal itch-scratcher for a dad who wanted to run better D&D games for his wife. It turns out a lot of GMs have the same itch.
 
 ## What can Familiar do?
 
@@ -38,11 +42,11 @@ Ask your AI to do things that would normally take you minutes of clicking throug
 
 > "What spells does Elara have prepared? Does she have enough slots to cast Fireball?"
 
-> "Dim the lights, start rain and thunder, and have the innkeeper whisper a warning about the road ahead - in his voice."
+> "Dim the lights, start rain and thunder, and have the innkeeper whisper a warning about the road ahead, in his voice."
 
 > "We're done for tonight. Summarize what happened this session and save it."
 
-Familiar exposes **176 tools across 24 domains** through the Model Context Protocol. Five core bundles are always available; the rest load on demand when your AI needs them.
+Familiar exposes **175 tools across 24 domains** through the Model Context Protocol. Five core bundles are always available; the rest load on demand when your AI needs them.
 
 ### Highlights
 
@@ -52,7 +56,7 @@ Familiar exposes **176 tools across 24 domains** through the Model Context Proto
 
 **Combat & AI**
 
-Run full encounters hands-free. Roll initiative, resolve attacks, apply damage, track conditions - or let the AI play NPCs with tactical decision-making.
+Run full encounters hands-free. Roll initiative, resolve attacks, apply damage, track conditions, or let the AI play NPCs with tactical decision-making.
 
 </td>
 <td width="33%" valign="top">
@@ -66,7 +70,7 @@ Give every NPC a unique AI-generated voice. Generate scene illustrations and cha
 
 **Scenes & Canvas**
 
-Build maps on the fly. Place tokens, draw walls, set lighting and weather, configure regions - control the entire canvas through natural language.
+Build maps on the fly. Place tokens, draw walls, set lighting and weather, configure regions, control the entire canvas through natural language.
 
 </td>
 </tr>
@@ -110,7 +114,7 @@ Create, update, and inspect actors, inventory, spells, features, and active effe
 | **Rollable Tables** | 7 | Create tables and roll on them for random encounters or loot |
 | **Macros** | 7 | Create, edit, and execute Foundry macros |
 | **World & System** | 6 | World info, system settings, time, pause, and user management |
-| **Combat AI** | 6 | NPC tactical decisions - target selection, ability usage, positioning |
+| **Combat AI** | 6 | NPC tactical decisions, target selection, ability usage, positioning |
 | **Items** | 6 | Create, update, delete, and search world-level items |
 | **Active Effects** | 5 | Apply, remove, and toggle buffs, debuffs, and status effects |
 | **Folders** | 5 | Organize documents into folder hierarchies |
@@ -126,9 +130,9 @@ Create, update, and inspect actors, inventory, spells, features, and active effe
 
 ## Connect your AI
 
-There are three ways to connect an AI to your game. They all give the AI the same 176 tools - the difference is where the AI runs.
+There are two ways to connect an AI to your game. Both give the AI the same tools, the difference is where the AI runs and how you pay.
 
-### Option 1: Built-in chat (easiest)
+### Option 1: Built-in chat (API key)
 
 No server. No terminal. No config files. Just install the module, pick a provider, paste an API key, and start talking to your game.
 
@@ -143,33 +147,26 @@ Familiar connects directly to **28 AI providers** across four categories:
 
 This is the right choice if you want the simplest setup, or if you want voice, images, and transcription alongside chat. It is also the only option that supports local models (Ollama, LM Studio) for fully offline play.
 
-### Option 2: MCP - use your existing AI subscription
+### Option 2: MCP (your existing subscription)
 
-Already paying for Claude, ChatGPT, or Gemini? You can connect them directly to Familiar through the [Model Context Protocol](https://modelcontextprotocol.io). Your subscription becomes a DM assistant at no extra cost.
+Already paying for Claude, ChatGPT, or Gemini? Connect them directly to Familiar through the [Model Context Protocol](https://modelcontextprotocol.io). Your subscription becomes a DM assistant at no extra API cost.
 
-The MCP server ships as an npm package. Most clients just need one line:
+Familiar supports four MCP clients out of the box:
 
-```bash
-npx familiar-vtt
-```
-
-| Client | Transport | Config |
-|--------|-----------|--------|
+| Client | Transport | Setup |
+|--------|-----------|-------|
 | Claude Desktop | stdio | Add to `claude_desktop_config.json` |
-| Claude Code | stdio | `claude mcp add familiar -- npx familiar-vtt` |
+| Claude Code (CLI) | stdio | `claude mcp add familiar -- npx familiar-vtt` |
+| Gemini CLI | stdio | Add to MCP settings (free with Gemini 3.1 Pro) |
 | ChatGPT | Streamable HTTP | Remote URL via Cloudflare tunnel |
-| Gemini CLI | stdio | Add to MCP settings (free with Gemini 2.5 Pro) |
-| Cursor | stdio | Add to `.cursor/mcp.json` |
-| Windsurf | stdio | Add to MCP config |
-| VS Code (Copilot) | stdio | Add to `.vscode/mcp.json` |
-
-You do not need to configure each client by hand. The module includes a step-by-step **MCP Setup Wizard** (in Module Settings > Familiar) that generates the exact config block for your chosen client - just copy and paste.
 
-### Option 3: MCP subscription providers
+The MCP server ships as an npm package:
 
-This is a hybrid of the first two. ChatGPT and Mistral's Le Chat can connect as subscription-based providers inside the built-in chat UI. They bring their own models - you authenticate with your existing account, and Familiar handles the rest through MCP.
+```bash
+npx familiar-vtt
+```
 
-You get the convenience of the built-in chat window with the cost advantage of your existing subscription.
+You do not need to configure each client by hand. The module includes a step-by-step **MCP Setup Wizard** (in Module Settings > Familiar) that detects your connected client and generates the exact config, just copy and paste.
 
 ### Which should I pick?
 
@@ -179,63 +176,38 @@ You get the convenience of the built-in chat window with the cost advantage of y
 | Use my Claude/ChatGPT/Gemini subscription | **MCP** |
 | Run everything offline | **Built-in chat** with Ollama or LM Studio |
 | Have voice, images, and transcription | **Built-in chat** (MCP is text-only) |
-| Use the AI from my code editor | **MCP** via Cursor, Windsurf, or VS Code |
 
 ### Your keys, your cost
 
-Familiar never proxies, meters, or marks up your AI usage. API keys go straight from your browser to the provider. With MCP, your existing subscription handles it. Either way, there is no middleman.
-
-## Installation
+Most AI tabletop tools lock you into their ecosystem. They charge per turn, per credit, or per token, and you're stuck with whatever model they picked for you. Run out of credits mid-session? Too bad.
 
-In Foundry VTT, go to **Settings > Manage Modules > Install Module**, then search for **Familiar**.
+Familiar works differently. You bring your own AI, whether that is an API key you already have or a subscription to Claude, ChatGPT, or Gemini. Familiar never proxies, meters, or marks up your usage. Your API keys go straight from your browser to the provider. With MCP, your existing subscription handles it. There is no middleman, no per-turn limits, and no credits that run out.
 
-Or paste the manifest URL directly:
-
-```
-https://github.com/Ryanjansen92/familiar-releases/releases/latest/download/module.json
-```
-
-Enable the module in your world under **Settings > Manage Modules**.
+## Installation
 
-### For MCP Clients (Claude Desktop, ChatGPT, etc.)
+In Foundry VTT, go to **Settings > Manage Modules > Install Module** and search for **Familiar**. Enable it in your world under **Settings > Manage Modules**.
 
-If you want to connect an external AI client via the [Model Context Protocol](https://modelcontextprotocol.io), you need the MCP server:
+If you want to connect an MCP client (Claude Desktop, Claude Code, Gemini CLI, or ChatGPT), you also need the MCP server:
 
 ```sh
 npx familiar-vtt
 ```
 
-Or install it globally:
-
-```sh
-npm install -g familiar-vtt
-```
-
-The **Setup Wizard** in Module Settings > Familiar walks you through connecting your MCP client step by step - config snippets, WebSocket port, the works.
-
-## Quick Start
-
-1. Open **Module Settings > Familiar**
-2. Pick a chat provider - [OpenAI](https://platform.openai.com/api-keys), [Anthropic](https://console.anthropic.com/), or run local models free with [Ollama](https://ollama.com)
-3. Paste your API key
-4. Open the Familiar chat panel from the sidebar
-5. Start playing
-
-That's it. No server to run, no terminal, no config files. The built-in chat works entirely inside Foundry.
+The **MCP Setup Wizard** in Module Settings > Familiar walks you through connecting your client step by step.
 
 ### Compatibility
 
 | | Supported |
 |---|---|
 | **Foundry VTT** | v13, v14 |
-| **Game System** | D&D 5e (2024 rules) - full support. Other systems work for general features (chat, journals, scenes, audio) but lack system-specific tools like character sheets and combat automation. |
+| **Game System** | D&D 5e (2024 rules), full support. Other systems work for general features (chat, journals, scenes, audio) but lack system-specific tools like character sheets and combat automation. |
 
 ## FAQ
 
 <details>
-<summary><b>Is Familiar free?</b></summary>
+<summary><b>How much does Familiar cost?</b></summary>
 
-The core module is free and includes all 176 tools, 28 providers, built-in chat, and full MCP support. There is a Pro tier with premium features like session persistence, auto-summarization, campaign memory, knowledge base RAG, and voice transcription - pricing is handled through Polar.sh.
+Familiar is a paid module with a free 1-month trial so you can try everything before you commit. All features are available during the trial, no restrictions.
 
 </details>
 
@@ -249,28 +221,28 @@ No. There is no telemetry, no analytics, and no data collection of any kind. Fam
 <details>
 <summary><b>Can the AI break my world?</b></summary>
 
-Familiar sanitizes all document updates so the AI cannot change ownership, permissions, or internal IDs. Prototype pollution protection is built in, destructive operations require confirmation, and WebSocket connections use shared-secret authentication. That said, always keep backups of your world - that is good practice regardless.
+Familiar sanitizes all document updates so the AI cannot change ownership, permissions, or internal IDs. Prototype pollution protection is built in, destructive operations require confirmation, and WebSocket connections use shared-secret authentication. That said, always keep backups of your world, that is good practice regardless.
 
 </details>
 
 <details>
 <summary><b>What is the difference between MCP mode and built-in chat?</b></summary>
 
-Built-in chat runs directly inside Foundry with no server required - it makes API calls straight to your AI provider and is the fastest way to get started. MCP mode connects Familiar to external clients like Claude Desktop, ChatGPT, or Gemini through a local server, which lets you use your existing subscriptions and is more powerful for complex multi-step tasks. Both modes have access to the same 176 tools.
+Built-in chat runs directly inside Foundry with no server required, it makes API calls straight to your AI provider and is the fastest way to get started. MCP mode connects Familiar to external clients like Claude Desktop, ChatGPT, or Gemini through a local server, which lets you use your existing subscriptions and is more powerful for complex multi-step tasks. Both modes have access to the same 175 tools.
 
 </details>
 
 <details>
 <summary><b>Which AI models work best?</b></summary>
 
-For the best experience: Claude Sonnet 4.6 or Opus 4.6, GPT-4.1, or Gemini 2.5 Pro. If you want free options, Gemini CLI has a free tier, and Ollama runs local models like Qwen3 or Llama 4 with no API costs at all.
+For the best experience: Claude Opus 4.6 or Sonnet 4.6 (Anthropic), GPT-5.4 (OpenAI), Gemini 3.1 Pro (Google), Grok 4 (xAI), Mistral 3 (Mistral), or DeepSeek V3.2 (DeepSeek).
 
 </details>
 
 <details>
 <summary><b>Can I use this for solo play?</b></summary>
 
-Absolutely - solo and small-group play is one of the main use cases. I built Familiar for 1-on-1 D&D campaigns with my wife. The AI can run NPCs, manage encounters, describe scenes, and help with rulings so you can play without a dedicated DM.
+Absolutely, solo and small-group play is one of the main use cases. I built Familiar for 1-on-1 D&D campaigns with my wife. The AI can run NPCs, manage encounters, describe scenes, and help with rulings so you can play without a dedicated DM.
 
 </details>
 
@@ -290,19 +262,72 @@ No. Familiar operates through its own namespaced flags and does not monkey-patch
 
 ## Roadmap
 
-These are things I'm actively working toward. No promises on timelines - this is a nights-and-weekends project.
+Things I'm actively working toward. No promises on timelines.
+
+### Module Integrations
+
+Let the AI control the most popular Foundry modules, automated rolls, visual effects, animations, loot, and more.
+
+| Module | What Familiar will do with it |
+|--------|-------------------------------|
+| Midi-QOL | Automated attack rolls, saving throws, and damage application |
+| Sequencer | Orchestrate animation sequences and visual storytelling |
+| JB2A (Animated Assets) | Trigger spell effects, explosions, and environmental animations |
+| Automated Animations | Auto-apply JB2A effects to spells and abilities |
+| Token Magic FX | Apply shader effects to tokens and tiles (fire auras, glowing shields) |
+| Dice So Nice | Sync 3D dice rolls with AI-triggered actions |
+| Item Piles | Create and manage loot drops, merchants, and treasure hoards |
+| Monk's Active Tile Triggers | Set up interactive tiles (traps, doors, teleporters) by voice |
+| Tidy 5e Sheets | Read and update the enhanced character sheet layout |
+| DFreds Convenient Effects | Apply and manage curated status effects and buffs |
+
+### Ready-to-Play Adventures
+
+Plug-and-play support for the most popular published adventures. Import the adventure, enable Familiar, and the AI already knows the story, NPCs, maps, and encounters.
+
+| Adventure | Publisher |
+|-----------|-----------|
+| Ember | Foundry VTT |
+| Curse of Strahd | Wizards of the Coast |
+| Phandelver and Below: The Shattered Obelisk | Wizards of the Coast |
+| Tomb of Annihilation | Wizards of the Coast |
+| Waterdeep: Dragon Heist | Wizards of the Coast |
+| Storm King's Thunder | Wizards of the Coast |
+| Ghosts of Saltmarsh | Wizards of the Coast |
+| Descent into Avernus | Wizards of the Coast |
+| Rime of the Frostmaiden | Wizards of the Coast |
+| Crown of the Oathbreaker | Elderbrain |
+
+### Game System Support
+
+Expanding beyond D&D 5e with full system-specific tools (character sheets, combat automation, spell resolution).
+
+| System | Status |
+|--------|--------|
+| D&D 5e (2024) | Supported |
+| Pathfinder 2e | Planned |
+| Call of Cthulhu | Planned |
+| Savage Worlds | Planned |
+| Warhammer Fantasy Roleplay | Planned |
+
+### Improvements
+
+- **Voice generation**: more natural NPC voices, emotion control, multi-voice conversations
+- **Image generation**: faster scene art, consistent character portraits across sessions, style presets
+- **Transcription**: improved accuracy, real-time command detection, multi-language support
+- **Combat AI**: smarter NPC tactics, group coordination, retreat behavior, morale
+- **Built-in chat**: conversation memory across sessions, campaign knowledge base, auto-summarization
+- **MCP**: faster tool execution, better multi-step task handling, richer feedback to clients
+
+### Bug Fixes & Stability
 
-- Module integrations (Midi-QOL, Sequencer, Token Magic FX, JB2A) for automated rolls, visual effects, and animations
-- AI Campaign Setup - import a published adventure and let the AI help you prep sessions
-- Pathfinder 2e support
-- More game systems beyond D&D 5e
+Active bug triage through the [Discord](https://discord.gg/3633wB9yp). Foundry version compatibility (v13, v14, and future releases) is always a priority.
 
 ## Feedback
 
 Familiar's source code is private, but your input matters. If you run into bugs, have feature ideas, or just want to tell me about the weird thing the AI did to your goblin encounter:
 
-- Drop a message in the [Foundry VTT Discord](https://discord.gg/foundryvtt)
-- Use the built-in feedback button inside the module
+- Join the [Discord](https://discord.gg/3633wB9yp)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "familiar-vtt",
-  "version": "2.5.18",
+  "version": "2.5.20",
   "description": "Your AI familiar for Foundry VTT. 176 tools across 24 domains — characters, scenes, combat, canvas, audio, macros, and more.",
   "type": "module",
   "engines": {