familiar-vtt 2.13.0 → 2.13.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +76 -69
  2. package/dist/mcp-package/index.mjs +22 -22
  3. package/package.json +4 -2
package/README.md CHANGED
@@ -8,49 +8,49 @@
8
8
 
9
9
  Run combat, set the mood, and voice your NPCs, all by talking to your AI.
10
10
 
11
- **It runs the rules, the dice, and the monsters, so you can stop running the game and start playing it — even solo.**
11
+ **You bought Foundry to run the game for everyone else. Familiar takes the dungeon master's side: the rules, the dice, the monsters, every NPC in its own voice. So you finally get to play. Solo, one on one, or a full group.**
12
12
 
13
13
  [![Foundry v13+](https://img.shields.io/badge/Foundry-v13%2B-orange?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA1MTIgNTEyIj48cGF0aCBmaWxsPSIjZmZmIiBkPSJNMjU2IDhDMTE5LjA0MyA4IDggMTE5LjA4MyA4IDI1NmMwIDEzNi45OTcgMTExLjA0MyAyNDggMjQ4IDI0OHMyNDgtMTExLjAwMyAyNDgtMjQ4QzUwNCAxMTkuMDgzIDM5Mi45NTcgOCAyNTYgOHoiLz48L3N2Zz4=)](https://foundryvtt.com)
14
14
  [![npm](https://img.shields.io/npm/v/familiar-vtt?color=blue&label=npm)](https://www.npmjs.com/package/familiar-vtt)
15
- [![Discord](https://img.shields.io/discord/1483457566594961419?logo=discord&label=Discord&color=5865F2)](https://discord.gg/pN6pEvYH)
15
+ [![Discord](https://img.shields.io/discord/1483457566594961419?logo=discord&label=Discord&color=5865F2)](https://discord.gg/UZuqaUt6h9)
16
16
  [![License](https://img.shields.io/badge/license-PolyForm%20Shield-lightgrey)](#license)
17
17
 
18
18
  **[Install Familiar](#installation)** · [Connect your AI](#connect-your-ai) · [Pricing](#pricing) · [FAQ](#faq) · [Roadmap](#roadmap)
19
19
 
20
20
  </div>
21
21
 
22
- <!-- TODO(media): hero GIF here — the flagship line running live ("roll initiative for the goblins, dim the lights, start battle music" → tracker fills, scene darkens, music cues, all from one chat message). Capture via docs/RECORDING.md (OBS + obs-mcp). Host in familiar-releases (docs/media/) and reference by a raw.githubusercontent.com URL so it also renders on the npm page. Keep ≤10 MB GIF for GitHub. -->
22
+ <!-- TODO(media): hero GIF here: the flagship line running live ("roll initiative for the goblins, dim the lights, start battle music" → tracker fills, scene darkens, music cues, all from one chat message). Capture via docs/RECORDING.md (OBS + obs-mcp). Host in familiar-releases (docs/media/) and reference by a raw.githubusercontent.com URL so it also renders on the npm page. Keep ≤10 MB GIF for GitHub. -->
23
23
 
24
24
  ## Plays at any table
25
25
 
26
- You bought Foundry to run the game for everyone else. Familiar lets you finally **play** — in the world you already built. It takes the DM's side of the table: the rules, the dice, the monsters, and every NPC in their own voice, so you can take a seat at your own game instead of always running it.
26
+ 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.
27
27
 
28
- 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.
28
+ 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.
29
29
 
30
30
  | Your table | What Familiar runs for you |
31
31
  |---|---|
32
- | **Solo** — just you | Every NPC, every monster's turn, the scene, and the rules — with 2024 D&D enforced for real and a memory of your campaign that carries from one session to the next. You play your character; Familiar runs the world around it. |
33
- | **Duet** — you and one other | Neither of you has to be the DM. Familiar plays the cast and runs the encounters, each NPC in their own voice, so you both stay players in the story. |
34
- | **Small table** — you and a few | The supporting cast and the monsters' turns, run for you — the lighting, the music, the rulings — so nobody has to step out of the game to keep it moving. |
35
- | **Full group** — you DM for four or more | The tactical NPC load, lifted off the GM. You run the encounter, not the spreadsheet — Familiar rolls initiative, plays the monsters, voices the NPCs, and gets out of the way. |
32
+ | **Solo** (just you) | You play your character. Familiar runs everything around it: every NPC in its own voice, every monster's turn, the scene, with 2024 D&D 5e rules enforced. Campaign memory carries the world from one session to the next. |
33
+ | **Duet** (you and one other) | Neither of you has to be the DM. Familiar runs the world for both of you, the cast, the encounters, the rulings, so you stay players and the story still moves. |
34
+ | **Small table** (you and a few) | The supporting cast and the monsters' turns run for you, with the lighting, the music, and the rulings, so nobody steps out of the game to keep it moving. |
35
+ | **Full group** (you DM for four or more) | The tactical load comes off the GM. You run the encounter and tell the story; Familiar handles initiative, the monster turns, and the bookkeeping. You run the scene, not the spreadsheet. |
36
36
 
37
- A co-pilot, not a replacement DM. Whoever's at the table, you're still the one telling the story — and the dice and the math are always right, no "you rolled a 47."
37
+ A co-pilot, not a replacement DM. Whoever is at the table, you are still telling the story, and the dice and the math are always right. No "you rolled a 47."
38
38
 
39
39
  ## What can Familiar do?
40
40
 
41
- You stay in the story; Familiar runs the table. Say what you want and it happens, without breaking character to dig through menus:
41
+ You stay in the story; Familiar runs the table. Say what you want and it happens, without breaking the scene to click through Foundry:
42
42
 
43
- > "Roll initiative for all the goblins, have them attack the nearest player, and cue battle music."
43
+ > "Roll initiative for all the goblins, have them attack the nearest player, and play battle music."
44
44
 
45
- > "I swing at the bandit captain with my greataxe — roll my attack, and have her hit back."
45
+ > "I swing at the bandit captain with my greataxe. Roll my attack, and have her hit back."
46
46
 
47
47
  > "Dim the lights, start rain and thunder, and have the innkeeper whisper a warning about the road ahead, in his voice."
48
48
 
49
- > "Spawn two wolves from the compendium near the forest edge as reinforcements, and add them to combat with initiative rolled."
49
+ > "Spawn two wolves from the compendium as reinforcements, place them near the forest edge, and add them to combat with initiative rolled."
50
50
 
51
51
  > "What did the party promise the duke last session, and what was his daughter's name?"
52
52
 
53
- > "We're done for tonight. Summarize what happened and save it to the journal."
53
+ > "We're done for tonight. Summarize what happened this session and save it to the journal."
54
54
 
55
55
  Familiar exposes **193 tools across 24 domains** through the Model Context Protocol. Tools load as your AI needs them.
56
56
 
@@ -62,7 +62,7 @@ Familiar exposes **193 tools across 24 domains** through the Model Context Proto
62
62
 
63
63
  **Combat & AI**
64
64
 
65
- 31 tools cover encounters end to end: initiative, attacks, spells, damage, conditions, death saves, and XP. NPCs make their own tactical decisions using battlefield snapshots, scored movement, and cover analysis.
65
+ 32 tools cover encounters end to end: initiative, attacks, spells, grapples and shoves, damage, conditions, death saves, and XP. When you want a break, Familiar resolves each NPC's turn from a battlefield snapshot, scoring movement and reading cover, multiattack and legendary actions included. You stay the DM.
66
66
 
67
67
  </td>
68
68
  <td width="33%" valign="top">
@@ -76,7 +76,7 @@ Click "Run NPC" and walk away. Familiar plays every enemy turn in the encounter
76
76
 
77
77
  **Live Transcription**
78
78
 
79
- Speak instead of type. Familiar transcribes your session in real time across three providers, color-codes per speaker, and saves it to a Foundry journal. Broadcast a read-only transcript to your players, export to SRT or Markdown, and the AI remembers what was said.
79
+ Speak instead of type. Familiar transcribes your session in real time across three providers, color-codes per speaker, and saves it to a Foundry journal you can edit and search later. Broadcast a read-only transcript to your players, export to SRT or Markdown, and the AI remembers what was said.
80
80
 
81
81
  </td>
82
82
  </tr>
@@ -85,14 +85,14 @@ Speak instead of type. Familiar transcribes your session in real time across thr
85
85
 
86
86
  **Scenes & Canvas**
87
87
 
88
- Create scenes, place tokens, draw walls and doors, set lighting and darkness, add weather effects, and configure trigger regions. Full control over tiles, drawings, ambient sounds, fog of war, and camera.
88
+ Build the whole scene by asking. Create scenes, place tokens, draw walls and doors, set lighting and darkness, add weather effects, and configure trigger regions. Full control over tiles, drawings, ambient sounds, fog of war, and camera. Familiar places it, you direct it.
89
89
 
90
90
  </td>
91
91
  <td width="33%" valign="top">
92
92
 
93
- **Voice & Image Generation**
93
+ **NPC Voices & Image Generation**
94
94
 
95
- Assign unique AI voices to NPCs across three providers. Have the tavern keeper actually speak his lines, in his own voice. Generate character portraits, item art, and battle map backgrounds on the fly.
95
+ Give every NPC its own voice across three providers. Have the tavern keeper actually speak his lines, in his own voice, and Familiar remembers who sounds like whom. Generate character portraits, item art, and battle-map backgrounds inline, mid-session.
96
96
 
97
97
  </td>
98
98
  <td width="33%" valign="top">
@@ -115,7 +115,7 @@ Full-text search across every journal, character, scene, item, and recorded tran
115
115
 
116
116
  **Multi-Session Chat**
117
117
 
118
- Pin, archive, and switch between named campaign threads. Each thread persists as a Foundry journal entry with a full audit log, so you can return to any conversation later.
118
+ Pin, archive, and switch between named campaign threads. Each thread persists as a Foundry journal entry with a full audit log, so you can return to any conversation later, even months apart.
119
119
 
120
120
  </td>
121
121
  <td width="33%" valign="top">
@@ -137,7 +137,7 @@ Build NPCs, manage party inventory, apply buffs, and clone monsters from any com
137
137
  | **Canvas Environment** | 18 | Walls, lights, weather effects, fog of war, darkness levels |
138
138
  | **Combat & Initiative** | 17 | Start encounters, roll initiative, advance turns and rounds |
139
139
  | **Characters & Actors** | 16 | Create, inspect, update, and manage player characters and NPCs |
140
- | **Combat AI** | 14 | NPC tactical decisions, target selection, ability usage, positioning |
140
+ | **Combat AI** | 15 | NPC tactical decisions, target selection, ability usage, positioning |
141
141
  | **Audio & Playlists** | 14 | Play, stop, and crossfade music and ambient sound |
142
142
  | **Journals & Notes** | 10 | Create and edit journal entries, map pins, and handouts |
143
143
  | **Card Decks** | 9 | Create, draw, shuffle, and reset card stacks and decks |
@@ -146,26 +146,26 @@ Build NPCs, manage party inventory, apply buffs, and clone monsters from any com
146
146
  | **Macros** | 7 | Create, edit, and execute Foundry macros |
147
147
  | **World & System** | 7 | World info, system settings, time, pause, and user management |
148
148
  | **Items** | 6 | Create, update, delete, and search world-level items |
149
+ | **Ember Events** | 6 | Custom event system for module-to-module hooks |
149
150
  | **Active Effects** | 5 | Apply, remove, and toggle buffs, debuffs, and status effects |
150
151
  | **Folders** | 5 | Organize documents into folder hierarchies |
151
152
  | **Regions** | 5 | Define map regions with triggered behaviors |
152
- | **Ember Events** | 5 | Custom event system for module-to-module hooks |
153
153
  | **Knowledge & Memory** | 5 | Campaign knowledge base, session memory, context retrieval |
154
154
  | **Compendium & Rules** | 4 | Search and import from compendium packs and rule references |
155
155
  | **Voice Generation** | 4 | Generate NPC speech audio with distinct AI voices |
156
156
  | **Chat Messages** | 2 | Send and read chat messages in the Foundry sidebar |
157
+ | **Scene Generator** | 2 | Generate AI battle-map backgrounds from a text description (image only, no walls or tokens) |
157
158
  | **Dice** | 1 | Roll any dice expression with full Foundry roll parsing |
158
159
  | **Image Generation** | 1 | Generate scene art or character portraits on demand |
159
- | **Scene Generator** | 2 | Generate AI battle-map backgrounds from a text description (image only, no walls or tokens) |
160
160
 
161
161
  </details>
162
162
 
163
163
  ## Installation
164
164
 
165
- Familiar installs like any other Foundry module.
165
+ Familiar ships directly from GitHub and installs like any other Foundry module.
166
166
 
167
167
  1. In Foundry, open **Add-on Modules → Install Module**.
168
- 2. Paste this manifest URL and click Install:
168
+ 2. Paste this manifest URL into the **Manifest URL** field and click Install:
169
169
 
170
170
  ```
171
171
  https://github.com/Ryanjansen92/familiar-releases/releases/latest/download/module.json
@@ -186,15 +186,15 @@ The **MCP Setup Wizard** in Module Settings → Familiar walks you through conne
186
186
  | | Supported |
187
187
  |---|---|
188
188
  | **Foundry VTT** | v13, v14 |
189
- | **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. |
189
+ | **Game System** | D&D 5e (2024 rules): full support. Other systems get the general features (chat, journals, scenes, audio) but not system-specific tools like character sheets or combat automation. |
190
190
 
191
191
  ## Connect your AI
192
192
 
193
- There are two ways to connect an AI to your game. Both reach the same 193 tools. The difference is where the model runs and how you pay.
193
+ There are two ways to connect an AI to your game. Both reach the same 193 tools. The difference is where the model runs and who you pay.
194
194
 
195
195
  ### Option 1: Built-in chat (API key)
196
196
 
197
- No server. No terminal. No config files. Install the module, pick a provider, paste an API key, and start talking.
197
+ 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.
198
198
 
199
199
  Familiar connects directly to **25 AI providers** across four categories:
200
200
 
@@ -207,11 +207,11 @@ Familiar connects directly to **25 AI providers** across four categories:
207
207
 
208
208
  ¹ *OpenRouter unlocks 300+ models on a single key.*
209
209
 
210
- 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 option that supports local models (Ollama, LM Studio) for fully offline play.
210
+ 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.
211
211
 
212
212
  ### Option 2: MCP (your existing subscription)
213
213
 
214
- Already paying for Claude, ChatGPT/Codex, Gemini, or have a Google account for Antigravity? Put that subscription to work. Connect it directly to Familiar through the [Model Context Protocol](https://modelcontextprotocol.io). Your subscription becomes a DM assistant at no extra API cost.
214
+ Already paying for Claude, ChatGPT/Codex, or have a Google account for Antigravity? Put that subscription to work. Connect it to Familiar through the [Model Context Protocol](https://modelcontextprotocol.io) and your existing plan drives the game at no extra API cost. No second invoice, no credits to run dry mid-session. It uses your plan's normal usage quota, so a long, heavy night can still hit your plan's rate limits, the same as any other use of that app.
215
215
 
216
216
  Familiar supports eight MCP clients out of the box:
217
217
 
@@ -226,9 +226,9 @@ Familiar supports eight MCP clients out of the box:
226
226
  | Gemini CLI ¹ | Google | stdio | Add to MCP settings with the `env` block |
227
227
  | ChatGPT | ChatGPT Plus / Pro / Team | Streamable HTTP | Remote URL via Cloudflare tunnel |
228
228
 
229
- ¹ *Gemini CLI is deprecated by Google on 2026-06-18 — use Antigravity CLI instead.*
229
+ ¹ *Gemini CLI is deprecated by Google on 2026-06-18: use Antigravity CLI instead.*
230
230
 
231
- You don't need to 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.
231
+ 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.
232
232
 
233
233
  ### Which should I pick?
234
234
 
@@ -237,8 +237,8 @@ You don't need to configure each client by hand. The **MCP Setup Wizard** in Mod
237
237
  | Get started in under a minute | **Built-in chat** with any API key |
238
238
  | Use my Claude / ChatGPT / Codex / Gemini / Antigravity subscription | **MCP** |
239
239
  | Run everything offline | **Built-in chat** with Ollama or LM Studio |
240
- | Have voice, images, and transcription | **Built-in chat** (over MCP, media renders in Foundry — see below) |
241
- | Run complex multi-step tasks | **MCP** (external clients handle long chains better) |
240
+ | Have live transcription, auto-pilot, and drag-and-drop | **Built-in chat** (these live only in the Foundry chat window) |
241
+ | Run long, multi-step chains | **MCP** (external clients handle long chains better) |
242
242
 
243
243
  ### What's different between the two paths
244
244
 
@@ -251,17 +251,19 @@ A full surface-by-surface capability matrix lives in [docs/chat-vs-mcp.md](docs/
251
251
 
252
252
  ## Works with what you already have
253
253
 
254
- Familiar works best when there's 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 doesn't try to replace any of that. It reads what's already there and uses it.
254
+ Familiar doesn't replace your modules, maps, or campaigns. It reads them, runs them, and stays out of your way. The Foundry community has spent years building incredible modules, battle maps, character sheets, compendium packs, and ready-to-play adventures. The more content your world has, the better Familiar gets.
255
255
 
256
- Those compendium entries with pre-built monsters, spells, and items? The AI pulls from them instead of making things up. That beautifully lit dungeon map someone spent weeks on? The AI can place tokens on it, trigger the right music, and run the encounter. The more content your world has, the better Familiar gets.
256
+ Open Ember, Dragon of Icespire Peak, or any published adventure, and Familiar reads the journal entries, NPCs, and encounters that came with it, then runs them at the table without inventing contradictions. Drop a Czepeku or Patreon map, and it fetches the tokens, lights, walls, and ambient sound you set up. Your custom NPCs, your house rules, your D&D Beyond imports: Familiar reads what's already in your world instead of making things up.
257
257
 
258
- Here's the part that's harder than it looks. Bolting a chat box onto a virtual tabletop is a weekend project. The real work is the engine underneath: teaching the AI how a real table actually operates — how initiative and reactions resolve, what a spell does to which token, when a saving throw is forced, why you can't swing a melee weapon from thirty feet away. Most AI tabletop tools skip that and rebuild a thin, simplified game inside their own walled garden, inventing the rules as they go. Familiar runs on the real thing, with real dice and real 5e enforcement on the mechanics that matter, on top of a decade of Foundry content. It operates your table instead of faking one.
258
+ Here's the part that's harder than it looks. Bolting a chat box onto a virtual tabletop is a weekend project. The real work is the engine underneath: teaching the AI how a real table actually operates, how initiative and reactions resolve, what a spell does to which token, when a saving throw is forced, why you can't swing a melee weapon from thirty feet away. Most AI tabletop tools skip that and rebuild a thin, simplified game inside their own walled garden, inventing the rules as they go. Familiar runs on the real thing, with real dice and real 5e enforcement on the mechanics that matter, on top of a decade of Foundry content. It runs the dungeon master's side of the table instead of faking one.
259
259
 
260
- So the on-ramp is short. Buy a Foundry-ready adventure — official D&D modules run about $20–30, with the maps, walls, and lighting already built — drop in a battle map or two (plenty are free), enable Familiar, and you're playing. Import the adventure without reading it, and Familiar reads its journals so it knows the story you're about to discover. Then, as you play, it pulls monsters and items straight from your compendia, places the tokens, and runs the encounters — while you stay the player.
260
+ So the on-ramp is short. Buy a Foundry-ready adventure (official D&D modules run about $20–30, with the maps, walls, and lighting already built), drop in a battle map or two (plenty are free), enable Familiar, and you're playing. Import the adventure without reading it, and Familiar reads its journals so it knows the story you're about to discover. Then, as you play, it pulls monsters and items straight from your compendia, places the tokens, and runs the encounters, while you stay the player.
261
+
262
+ Familiar doesn't ship its own adventures, maps, or compendia. The content is yours. Your AI tells the story you bring, it doesn't invent one.
261
263
 
262
264
  ## Pricing
263
265
 
264
- **$3 a month, or $25 a year.** Start with a free 1-month trial: every feature unlocked, no restrictions, cancel anytime.
266
+ **$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.
265
267
 
266
268
  That price is the whole cost of Familiar. No per-message fee, no token metering, no credits to top up.
267
269
 
@@ -290,7 +292,9 @@ My wife and I play D&D together, just the two of us, 1-on-1 campaigns. It's our
290
292
 
291
293
  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.
292
294
 
293
- 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 here.
295
+ 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.
296
+
297
+ 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.
294
298
 
295
299
  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.
296
300
 
@@ -299,7 +303,7 @@ It started as a personal itch-scratcher for a dad who wanted to run better D&D g
299
303
  <details>
300
304
  <summary><b>Does Familiar collect my data?</b></summary>
301
305
 
302
- No. There's no telemetry and no analytics, and Familiar never collects your game data. It runs entirely inside your local Foundry instance, 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.)
306
+ 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.)
303
307
 
304
308
  </details>
305
309
 
@@ -313,7 +317,7 @@ For the built-in chat, about as easy as it gets: install the module, open Famili
313
317
  <details>
314
318
  <summary><b>Can the AI break my world?</b></summary>
315
319
 
316
- Familiar sanitizes every document update, so the AI can't change ownership, permissions, or internal IDs. Prototype-pollution protection is built in, and WebSocket connections use shared-secret authentication. Risky actions are flagged for confirmation: the built-in chat shows an inline approval row before running them, and external AI clients receive the same "destructive" hints so they can prompt you. The AI also can't create or edit script macros or code-running region behaviors, even though it can run ones you wrote yourself. Always keep backups regardless. Good practice with or without AI.
320
+ Familiar sanitizes every document update, so the AI can't change ownership, permissions, or internal IDs. Prototype-pollution protection is built in, and WebSocket connections use shared-secret authentication. Risky actions are flagged for confirmation: the built-in chat shows an inline approval row before running them, and external AI clients receive the same "destructive" hints so they can prompt you. The AI also can't create or edit script macros or code-running region behaviors, though it can run ones you wrote yourself. Keep backups anyway. Good practice with or without AI.
317
321
 
318
322
  </details>
319
323
 
@@ -348,23 +352,25 @@ Built-in chat works anywhere Foundry runs, including The Forge. The module makes
348
352
  <details>
349
353
  <summary><b>What's the difference between MCP mode and built-in chat?</b></summary>
350
354
 
351
- 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 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.
355
+ 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.
352
356
 
353
357
  </details>
354
358
 
355
359
  <details>
356
360
  <summary><b>Which AI models work best?</b></summary>
357
361
 
358
- 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. 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.
362
+ 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.
363
+
364
+ 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.
359
365
 
360
366
  </details>
361
367
 
362
368
  <details>
363
369
  <summary><b>Can I play solo, or one-on-one?</b></summary>
364
370
 
365
- That's one of the main reasons it exists. Most people who own Foundry are the GM — the one who never gets to play. Familiar runs the rules, the monsters, and the NPCs so you can sit in a player's seat at your own table, solo or one-on-one. I built it for 1-on-1 campaigns with my wife. (It still needs GM-level access — see the next question.)
371
+ That's one of the main reasons it exists. Most people who own Foundry are the GM, the one who never gets to play. Familiar runs the rules, the monsters, and the NPCs, and remembers your campaign across sessions, so you can sit in a player's seat at your own table, solo or one-on-one. I built it for 1-on-1 campaigns with my wife. (It still needs GM-level access; see the next question.)
366
372
 
367
- Two honest notes. Familiar runs the _DM's_ side — it doesn't yet play a companion character adventuring next to you (that's on the roadmap). And the surprises come from the adventure you're playing and Foundry's own fog-of-war and hidden doors, not from the AI "keeping secrets" — an AI can't truly hide what it can read. What it can do is run a real, rules-accurate game so you finally get to be the player.
373
+ Two honest notes. Familiar runs the _DM's_ side. It doesn't yet play a companion character adventuring next to you (that's on the roadmap). And the surprises come from the adventure you're playing and Foundry's own fog-of-war and hidden doors, not from the AI "keeping secrets." An AI can't truly hide what it can read. What it can do is run a real, rules-accurate game so you finally get to be the player.
368
374
 
369
375
  </details>
370
376
 
@@ -378,7 +384,7 @@ Familiar requires GM permissions. It's designed as a GM tool that reads and modi
378
384
  <details>
379
385
  <summary><b>Does it work with game systems other than D&D 5e?</b></summary>
380
386
 
381
- Familiar is designed and tested for D&D 5e (2024 rules). Basic features like dice rolling, scene management, and journal editing work with other systems, but system-specific tools (character creation, spell resolution, combat automation) are built around the dnd5e data model and won't work elsewhere without changes.
387
+ Full support is D&D 5e (2024 rules) only. Generic features like dice rolling, scene management, journals, and audio work everywhere, but system-specific tools (character creation, spell resolution, combat automation) are built around the dnd5e data model and won't work elsewhere without changes. Pathfinder 2e, Call of Cthulhu, and Savage Worlds are on the roadmap.
382
388
 
383
389
  </details>
384
390
 
@@ -391,26 +397,31 @@ No. Familiar operates through its own namespaced flags and doesn't monkey-patch
391
397
 
392
398
  ## Roadmap
393
399
 
394
- Things I'm actively working toward. No promises on timelines.
400
+ Things I'm working toward. No promises on timelines, but this is roughly the priority order.
401
+
402
+ ### Better solo and duet play
395
403
 
396
- ### Module Integrations
404
+ 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).
397
405
 
398
- Let the AI control the most popular Foundry modules: automated rolls, visual effects, animations, loot, and more.
406
+ - **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
407
+ - **Encounter scaling**: balance a fight for a solo or duet party
408
+ - **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
409
+
410
+ ### Module integrations
411
+
412
+ Let Familiar drive the rest of your Foundry stack: automated rolls, animations, loot, and visual effects.
399
413
 
400
414
  | Module | What Familiar will do with it |
401
415
  |--------|-------------------------------|
416
+ | Midi-QOL | Run automated attack rolls and saves through your existing automation |
402
417
  | Sequencer + JB2A | Orchestrate animation sequences and trigger spell effects |
403
418
  | Token Magic FX | Apply shader effects to tokens and tiles (fire auras, glowing shields) |
404
419
  | Item Piles | Create and manage loot drops, merchants, and treasure hoards |
405
420
  | DFreds Convenient Effects | Apply and manage curated status effects and buffs |
406
421
 
407
- ### Ready-to-Play Adventures
408
-
409
- Plug-and-play support for published adventures. Import the adventure, enable Familiar, and the AI already knows the story, NPCs, maps, and encounters. Starting with [Ember](https://foundryvtt.com/packages/ember) (Foundry's own 500-hour sandbox campaign) and expanding to popular published modules.
410
-
411
- ### Game System Support
422
+ ### Game system support
412
423
 
413
- Expanding beyond D&D 5e with full system-specific tools (character sheets, combat automation, spell resolution).
424
+ Expanding beyond D&D 5e with full system-specific tools: character sheets, combat automation, and spell resolution.
414
425
 
415
426
  | System | Status |
416
427
  |--------|--------|
@@ -419,24 +430,20 @@ Expanding beyond D&D 5e with full system-specific tools (character sheets, comba
419
430
  | Call of Cthulhu | Planned |
420
431
  | Savage Worlds | Planned |
421
432
 
422
- ### Solo & duet play
433
+ ### Plug-and-play adventures
423
434
 
424
- Sharpening Familiar for the player who runs the table for everyone else and wants to play for once, solo or one-on-one. Full plan in [docs/solo-play.md](docs/solo-play.md).
425
-
426
- - **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
427
- - **Encounter scaling for one PC**: balance a fight for a solo or duet party
428
- - **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
435
+ Import a published adventure, enable Familiar, and the AI already knows the story, NPCs, maps, and encounters. Starting with [Ember](https://foundryvtt.com/packages/ember), Foundry's own 500-hour sandbox campaign, and expanding to more published modules.
429
436
 
430
- ### Improvements
437
+ ### Sharpening what already ships
431
438
 
432
- - **Combat AI**: retreat behavior, morale, group coordination beyond what shipped
439
+ - **Combat AI**: retreat behavior, morale, and group coordination beyond what shipped
433
440
  - **Voice generation**: emotion control, more natural multi-voice conversations
434
- - **Image generation**: consistent character portraits across sessions, style presets
441
+ - **Image generation**: consistent character portraits across sessions, plus style presets
435
442
  - **MCP**: richer `notifications/message` feedback so external clients see tool progress in real time
436
443
 
437
444
  ## Feedback
438
445
 
439
- Join the [Discord](https://discord.gg/pN6pEvYH) for bug reports, feature ideas, or just tell me about the weird thing the AI did to your goblin encounter.
446
+ Got an idea? The [Discord](https://discord.gg/UZuqaUt6h9) is the best place to push something up the list, file a bug, or just tell me about the weird thing the AI did to your goblin encounter.
440
447
 
441
448
  ## License
442
449
 
@@ -444,9 +451,9 @@ Familiar is licensed under the [PolyForm Shield License 1.0.0](https://polyformp
444
451
 
445
452
  <div align="center">
446
453
 
447
- Built for the DM who has more ideas than free time — and wouldn't mind playing for once.
454
+ Built for the DM who has more ideas than free time, and wouldn't mind playing for once.
448
455
 
449
- **[Install Familiar — free for a month](#installation)**
456
+ **[Install Familiar, free for a month](#installation)**
450
457
 
451
458
  *May your rolls be high, your prep be low, and your players never notice the AI is helping.*
452
459