familiar-vtt 2.13.3 → 2.14.0

package/README.md

@@ -4,7 +4,7 @@
 
 ### Your AI co-pilot for Foundry VTT
 
-**193 tools. 25 AI providers. Zero prep.**
+**193 tools. 23 AI providers. Zero prep.**
 
 Run combat, set the mood, and voice your NPCs, all by talking to your AI.
 
@@ -23,7 +23,7 @@ Run combat, set the mood, and voice your NPCs, all by talking to your AI.
 
 ## Plays at any table
 
-However many show up, you get to play. Familiar takes the DM's side of the table: the rules, the dice, the monsters, and every NPC in its own voice. You take a seat at the game you usually run for everyone else.
+However many show up, you get to play. Familiar covers the DM's side of the table — the cast, the dice, the monsters, the lighting — so you take a seat at the game you usually run for everyone else.
 
 And it scales to whoever shows up. The fewer humans at the table, the more of the world Familiar runs. With a full group, it quietly co-pilots the monsters and the mood while you tell the story.
 
@@ -108,7 +108,7 @@ Play, stop, and crossfade playlists and individual tracks with volume and fade c
 
 **Knowledge & Memory**
 
-Full-text search across every journal, character, scene, item, and recorded transcript. A persistent memory bank stores campaign facts that carry over between sessions, plus a continuously-rewritten plot summary the GM can read later.
+Full-text search across every journal, character, scene, item, and recorded transcript. A persistent memory bank stores campaign facts that carry over between sessions, plus a continuously rewritten plot summary the GM can read later.
 
 </td>
 <td width="33%" valign="top">
@@ -146,7 +146,7 @@ Build NPCs, manage party inventory, apply buffs, and clone monsters from any com
 | **Macros** | 7 | Create, edit, and execute Foundry macros |
 | **World & System** | 7 | World info, system settings, time, pause, and user management |
 | **Items** | 6 | Create, update, delete, and search world-level items |
-| **Ember Events** | 6 | Custom event system for module-to-module hooks |
+| **Ember Events** | 6 | Quests, story events, and hex-crawl exploration via the Ember module |
 | **Active Effects** | 5 | Apply, remove, and toggle buffs, debuffs, and status effects |
 | **Folders** | 5 | Organize documents into folder hierarchies |
 | **Regions** | 5 | Define map regions with triggered behaviors |
@@ -156,7 +156,7 @@ Build NPCs, manage party inventory, apply buffs, and clone monsters from any com
 | **Chat Messages** | 2 | Send and read chat messages in the Foundry sidebar |
 | **Scene Generator** | 2 | Generate AI battle-map backgrounds from a text description (image only, no walls or tokens) |
 | **Dice** | 1 | Roll any dice expression with full Foundry roll parsing |
-| **Image Generation** | 1 | Generate scene art or character portraits on demand |
+| **Image Generation** | 1 | Generate character portraits, item art, or concept art on demand |
 
 </details>
 
@@ -173,13 +173,13 @@ Familiar ships directly from GitHub and installs like any other Foundry module.
 
 3. Enable Familiar in your world, open its settings, pick a provider, and paste an API key.
 
-That is the whole setup for the built-in chat. If you would rather drive your game from an MCP client (Claude Desktop, Claude Code, Codex CLI / Desktop, Antigravity CLI / Editor, Gemini CLI, or ChatGPT), you also need the local MCP server:
+That is the whole setup for the built-in chat. If you would rather drive your game from an MCP client (Claude Desktop, Claude Code, Codex CLI / Desktop, Antigravity CLI / Editor, LM Studio, or ChatGPT), you also need the local MCP server:
 
 ```sh
 npx familiar-vtt
 ```
 
-The **MCP Setup Wizard** in Module Settings → Familiar walks you through connecting your client step by step, including the auto-generated `FAMILIAR_WS_SECRET`. No JSON editing.
+The **MCP Setup Wizard** on the **MCP / Subs** tab in Module Settings → Familiar walks you through connecting your client step by step, including the auto-generated `FAMILIAR_WS_SECRET`. No JSON editing.
 
 ### Compatibility
 
@@ -196,18 +196,18 @@ There are two ways to connect an AI to your game. Both reach the same 193 tools.
 
 No server, no terminal, no config files. Install the module, pick a provider, paste an API key, and start talking to your game. Your key goes straight from your browser to the provider, which bills you per token for what you use.
 
-Familiar connects directly to **25 AI providers** across four categories:
+Familiar connects directly to **23 AI providers** across four categories:
 
 | Category | Providers |
 |----------|-----------|
-| **Chat** (16) | OpenRouter¹, Anthropic, OpenAI, Google, Groq, Mistral, Together AI, DeepSeek, xAI, Cohere, Perplexity, Fireworks AI, Cerebras, SambaNova, Ollama (local), LM Studio (local) |
+| **Chat** (14) | OpenRouter¹, Anthropic, OpenAI, Google, Groq, Mistral, Together AI, DeepSeek, xAI, Cohere, Perplexity, Fireworks AI, Cerebras, SambaNova |
 | **Voice** (3) | ElevenLabs, Cartesia, OpenAI TTS |
 | **Image** (3) | OpenAI (GPT Image), fal.ai, Leonardo AI |
 | **Transcription** (3) | Gladia, Deepgram, AssemblyAI |
 
 ¹ *OpenRouter unlocks 300+ models on a single key.*
 
-This is the right choice if you want the simplest setup, or if you want voice, images, and live transcription alongside chat. It is also the only path that runs fully offline through a local model (Ollama, LM Studio), at no per-token cost. A Thinking control lets you set how hard the model reasons: up for hard fights, down for quick lookups.
+This is the right choice if you want the simplest setup, or if you want voice, images, and live transcription alongside chat. For an open model at near-zero cost, pick a hosted open-weight provider (Groq, Cerebras, DeepSeek, OpenRouter). A Thinking control lets you set how hard the model reasons: up for hard fights, down for quick lookups.
 
 ### Option 2: MCP (your existing subscription)
 
@@ -223,20 +223,18 @@ Familiar supports eight MCP clients out of the box:
 | Codex Desktop | ChatGPT Plus / Pro / Team | stdio | Add `[mcp_servers.familiar]` block to `~/.codex/config.toml` (shared with CLI / IDE) |
 | Antigravity CLI (`agy`) | Google free / Pro / Ultra | stdio | Generates `~/.gemini/config/mcp_config.json`; sign in via `agy` → Google OAuth |
 | Antigravity Editor | Google free / Pro / Ultra | stdio | Add to `~/.gemini/antigravity/mcp_config.json` (desktop IDE; separate install from CLI) |
-| Gemini CLI ¹ | Google | stdio | Add to MCP settings with the `env` block |
+| LM Studio | Local models (free, no key) | stdio | In LM Studio → Program tab → Edit `mcp.json`, paste the `familiar` block (LM Studio 0.3.17+, tool-trained model ≥14B) |
 | ChatGPT | ChatGPT Plus / Pro / Team | Streamable HTTP | Remote URL via Cloudflare tunnel |
 
-¹ *Gemini CLI is deprecated by Google on 2026-06-18: use Antigravity CLI instead.*
-
-You don't configure each client by hand. The **MCP Setup Wizard** in Module Settings → Familiar detects your connected client and generates the exact config, including the auto-generated `FAMILIAR_WS_SECRET` baked in. Copy and paste. Your model and how hard it reasons are set in your own client, not here.
+You don't configure each client by hand. The **MCP Setup Wizard** on the **MCP / Subs** tab detects your connected client and generates the exact config, including the auto-generated `FAMILIAR_WS_SECRET` baked in. Copy and paste. Your model and how hard it reasons are set in your own client, not here.
 
 ### Which should I pick?
 
 | I want to... | Use |
 |--------------|-----|
 | Get started in under a minute | **Built-in chat** with any API key |
-| Use my Claude / ChatGPT / Codex / Gemini / Antigravity subscription | **MCP** |
-| Run everything offline | **Built-in chat** with Ollama or LM Studio |
+| Use my Claude / ChatGPT / Codex / Antigravity subscription | **MCP** |
+| Run everything offline | **MCP** with a local model in LM Studio |
 | Have live transcription, auto-pilot, and drag-and-drop | **Built-in chat** (these live only in the Foundry chat window) |
 | Run long, multi-step chains | **MCP** (external clients handle long chains better) |
 
@@ -247,7 +245,7 @@ All 193 tools work from both paths. Two things differ:
 - **Media renders in Foundry, not in your MCP client.** When an external client (ChatGPT, Claude Desktop, Codex) calls a voice or scene tool, the audio plays and the scene updates in your Foundry browser tab. The MCP client only gets a text confirmation. Generated images are the exception: they come back inline, so clients that render images can show them.
 - **A few features are built-in-chat only.** Live transcription, auto-pilot for NPC turns, automatic memory and knowledge-base context, slash commands, and drag-and-drop attachments live only in the in-Foundry chat window. MCP clients reach every tool, but not these chat-UI features.
 
-A full surface-by-surface capability matrix lives in [docs/chat-vs-mcp.md](docs/chat-vs-mcp.md).
+A full surface-by-surface capability comparison lives at [familiarvtt.com](https://familiarvtt.com).
 
 ## Works with what you already have
 
@@ -263,9 +261,7 @@ Familiar doesn't ship its own adventures, maps, or compendia. The content is you
 
 ## Pricing
 
-**$3 a month, or $25 a year.** Start with a free 1-month trial: every feature unlocked, no restrictions, cancel anytime. That price keeps Familiar maintained. Your AI provider bills you directly for the tokens you spend. No markup, no middleman, no per-turn limits.
-
-That price is the whole cost of Familiar. No per-message fee, no token metering, no credits to top up.
+**$4 a month, or $36 a year** — the annual plan saves you three months. Start with a free 1-month trial: every feature unlocked, no restrictions, cancel anytime. That price is the whole cost of Familiar — no markup, no per-message fee, no token metering, no credits to top up. Your AI provider bills you directly for the tokens you spend; we never touch that.
 
 ### Do I pay twice?
 
@@ -273,16 +269,16 @@ Fair question. You pay for Familiar, and you pay for the AI that powers it, but
 
 | What you pay for | Who you pay | Typical cost |
 |---|---|---|
-| Familiar (the module + all 193 tools) | Us | $3 / month or $25 / year |
+| Familiar (the module + all 193 tools) | Us | $4 / month or $36 / year |
 | The AI itself | Your provider, directly | $0.50–$3 per session, or $0 |
 
-That $0 is real. If you connect a subscription you already pay for (Claude, ChatGPT/Codex, Gemini, Antigravity) through MCP, the AI cost is already covered. The same goes for local models through Ollama or LM Studio: nothing leaves your machine, and nothing hits a bill. Bring your own API key instead, and a typical session costs about the price of a coffee, paid straight to the provider.
+That $0 is real. If you connect a subscription you already pay for (Claude, ChatGPT/Codex, or Antigravity) through MCP, the AI cost is already covered. The same goes for a local model run in LM Studio and connected through MCP: nothing leaves your machine, and nothing hits a bill. Bring your own API key instead, and a typical session costs about the price of a coffee, paid straight to the provider.
 
 ### Your keys, your cost
 
 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.
 
-Familiar works differently. You bring your own AI, an API key you already have or a subscription to Claude, ChatGPT/Codex, or Gemini. Your keys go straight from your browser to the provider. Familiar never proxies, meters, or marks up your usage: no middleman, no per-turn limits, no credits to run out of. With MCP, your existing subscription handles it.
+Familiar works differently. You bring your own AI, an API key you already have or a subscription to Claude, ChatGPT/Codex, or Antigravity. Your keys go straight from your browser to the provider. Familiar never proxies, meters, or marks up your usage: no middleman, no per-turn limits, no credits to run out of. With MCP, your existing subscription handles it.
 
 ## Why I built this
 
@@ -292,7 +288,7 @@ My wife and I play D&D together, just the two of us, 1-on-1 campaigns. It's our
 
 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 handle 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 "what if it could also generate NPC portraits on the fly?" and "what if it could voice the tavern keeper?" That's how you end up with 193 tools across 24 domains and 25 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 "what if it could also generate NPC portraits on the fly?" and "what if it could voice the tavern keeper?" That's how you end up with 193 tools across 24 domains and 23 AI providers.
 
 I took my time with this. I ran Familiar at my own table, session after session, before opening it up. I didn't want to ship another AI that turns your campaign into nonsense the moment it forgets last week.
 
@@ -303,14 +299,14 @@ It started as a personal itch-scratcher for a dad who wanted to run better D&D g
 <details>
 <summary><b>Does Familiar collect my data?</b></summary>
 
-No. There's no telemetry, no analytics, and no calls home. Familiar runs entirely inside your local Foundry world, and your data only leaves your machine when you choose to send a message to an external AI provider. If you use local models through Ollama or LM Studio, nothing ever leaves your network. (In MCP mode, the server validates your license with Polar; that request carries only your license key, never any world content.)
+No. There's no telemetry, no analytics, and no calls home. Familiar runs entirely inside your local Foundry world, and your data only leaves your machine when you choose to send a message to an external AI provider. If you run a local model (for example in LM Studio, connected through MCP), nothing ever leaves your network. (In MCP mode, the server validates your license with Polar; that request carries only your license key, never any world content.)
 
 </details>
 
 <details>
 <summary><b>How hard is it to set up?</b></summary>
 
-For the built-in chat, about as easy as it gets: install the module, open Familiar's settings, pick a provider, paste an API key, and start talking. No terminal, no config files. If you'd rather use an existing Claude, ChatGPT, or Gemini subscription through MCP, there's one extra piece, a small local server you start with `npx familiar-vtt`, and the in-app MCP Setup Wizard detects your client and generates the exact config to copy and paste.
+For the built-in chat, about as easy as it gets: install the module, open Familiar's settings, pick a provider, paste an API key, and start talking. No terminal, no config files. If you'd rather use an existing Claude, ChatGPT/Codex, or Antigravity subscription through MCP, there's one extra piece, a small local server you start with `npx familiar-vtt`, and the in-app MCP Setup Wizard detects your client and generates the exact config to copy and paste.
 
 </details>
 
@@ -352,14 +348,14 @@ Built-in chat works anywhere Foundry runs, including The Forge. The module makes
 <details>
 <summary><b>What's the difference between MCP mode and built-in chat?</b></summary>
 
-Built-in chat runs inside Foundry with no extra server, the fastest way to start. MCP connects Familiar to external clients (Claude Desktop, Codex CLI / Desktop, Antigravity CLI / Editor, ChatGPT, Gemini) through a small local server, letting you use existing subscriptions and handling complex multi-step tasks better. Both reach the same 193 tools, though media (voice, scenes) renders in your Foundry tab rather than the MCP client.
+Built-in chat runs inside Foundry with no extra server, the fastest way to start. MCP connects Familiar to external clients (Claude Desktop, Codex CLI / Desktop, Antigravity CLI / Editor, ChatGPT, LM Studio) through a small local server, letting you use existing subscriptions and handling complex multi-step tasks better. Both reach the same 193 tools, though media (voice, scenes) renders in your Foundry tab rather than the MCP client.
 
 </details>
 
 <details>
 <summary><b>Which AI models work best?</b></summary>
 
-For the best experience: Claude Opus 4.8 or Sonnet 4.7 (Anthropic), GPT-5.5 (OpenAI), Gemini 3.1 Pro (Google), Grok 4.3 (xAI), Mistral Large 3 (Mistral), or DeepSeek V3.2 (DeepSeek). Familiar works with any model these providers expose, but the larger flagship models follow multi-step tool instructions most reliably. That reliability matters most in combat, where one turn is a chain of tool calls. For a budget option, DeepSeek V3.2 is capable and inexpensive; for fully offline play, any strong local model through Ollama or LM Studio works.
+For the best experience: Claude Opus 4.8 or Sonnet 4.6 (Anthropic), GPT-5.5 (OpenAI), Gemini 3.1 Pro (Google), Grok 4.3 (xAI), Mistral Large 3 (Mistral), or DeepSeek V3.2 (DeepSeek). Familiar works with any model these providers expose, but the larger flagship models follow multi-step tool instructions most reliably. That reliability matters most in combat, where one turn is a chain of tool calls. For a budget option, DeepSeek V3.2 is capable and inexpensive; for fully offline play, run a strong local model in LM Studio and connect it through MCP.
 
 Reasoning headroom is the other lever. The built-in chat has a Thinking control you can turn up for a hard combat or a tangled scene and back down for quick lookups; over MCP, that dial lives in your own client.
 
@@ -401,11 +397,11 @@ Things I'm working toward. No promises on timelines, but this is roughly the pri
 
 ### Better solo and duet play
 
-For the DM who runs the table for everyone else and wants to play for once. Familiar already runs the DM's side; these sharpen it for a table of one or two. Full plan in [docs/solo-play.md](docs/solo-play.md).
+For the DM who runs the table for everyone else and wants to play for once. Familiar already runs the DM's side; these sharpen it for a table of one or two.
 
 - **Companion party-fill**: let the AI run a designated ally's combat turns, so one hero against four goblins is a fight again, not a mugging
 - **Encounter scaling**: balance a fight for a solo or duet party
-- **Solo mode**: a one-click preset that puts the AI on the rules, the monsters, and the NPC voices so you can sit in a player's seat at your own table
+- **Solo mode**: a one-click preset for what already works manually today — it puts the AI on the rules, the monsters, and the NPC voices in a single toggle, so you can sit in a player's seat at your own table
 
 ### Module integrations
 
@@ -436,7 +432,7 @@ Import a published adventure, enable Familiar, and the AI already knows the stor
 
 ### Sharpening what already ships
 
-- **Combat AI**: retreat behavior, morale, and group coordination beyond what shipped
+- **Combat AI**: retreat behavior, morale, and group coordination beyond what ships today
 - **Voice generation**: emotion control, more natural multi-voice conversations
 - **Image generation**: consistent character portraits across sessions, plus style presets
 - **MCP**: richer `notifications/message` feedback so external clients see tool progress in real time