familiar-vtt 2.10.0 → 2.11.1

package/README.md

@@ -4,34 +4,55 @@
 
 ### Your AI co-pilot for Foundry VTT
 
-**188 tools. 26 AI providers. Zero prep.**
+**191 tools. 25 AI providers. Zero prep.**
 
 Run combat, set the mood, and voice your NPCs, all by talking to your AI.
 
+**It runs the rules, the dice, and the monsters, so you can stop running the game and start playing it — even solo.**
+
 [![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)
 [![Discord](https://img.shields.io/discord/1483457566594961419?logo=discord&label=Discord&color=5865F2)](https://discord.gg/pN6pEvYH)
 [![License](https://img.shields.io/badge/license-PolyForm%20Shield-lightgrey)](#license)
 
-[Installation](#installation) | [Connect Your AI](#connect-your-ai) | [Pricing](#pricing) | [FAQ](#faq) | [Roadmap](#roadmap)
+**[Install Familiar](#installation)** · [Connect your AI](#connect-your-ai) · [Pricing](#pricing) · [FAQ](#faq) · [Roadmap](#roadmap)
 
 </div>
 
+<!-- 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. -->
+
+## Plays at any table
+
+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.
+
+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.
+
+| Your table | What Familiar runs for you |
+|---|---|
+| **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. |
+| **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. |
+| **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. |
+| **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. |
+
+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."
+
 ## What can Familiar do?
 
-Ask your AI to do things that would normally take you minutes of clicking through menus:
+You stay in the story; Familiar runs the table. Say what you want and it happens, without breaking character to dig through menus:
 
-> "Roll initiative for all the goblins, have them attack the nearest player, and play battle music."
+> "Roll initiative for all the goblins, have them attack the nearest player, and cue battle music."
 
-> "Spawn two Wolves from the compendium as reinforcements, place them near the forest edge, and add them to combat with initiative rolled."
+> "I swing at the bandit captain with my greataxe — roll my attack, and have her hit back."
 
 > "Dim the lights, start rain and thunder, and have the innkeeper whisper a warning about the road ahead, in his voice."
 
-> "Find a CR 3 werewolf in the compendium, drop it into the scene as a boss, and give it resistance to non-silvered weapons."
+> "Spawn two wolves from the compendium near the forest edge as reinforcements, and add them to combat with initiative rolled."
+
+> "What did the party promise the duke last session, and what was his daughter's name?"
 
-> "We're done for tonight. Summarize what happened and save it."
+> "We're done for tonight. Summarize what happened and save it to the journal."
 
-Familiar exposes **188 tools across 24 domains** through the Model Context Protocol. Tools load as your AI needs them. No upfront configuration.
+Familiar exposes **191 tools across 24 domains** through the Model Context Protocol. Tools load as your AI needs them.
 
 ### Highlights
 
@@ -41,7 +62,7 @@ Familiar exposes **188 tools across 24 domains** through the Model Context Proto
 
 **Combat & AI**
 
-29 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.
+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.
 
 </td>
 <td width="33%" valign="top">
@@ -55,7 +76,7 @@ Click "Run NPC" and walk away. Familiar plays every enemy turn in the encounter
 
 **Live Transcription**
 
-Speak instead of type. Familiar transcribes your session in real time across three providers, color-codes per speaker, and saves the transcript to a Foundry journal.
+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.
 
 </td>
 </tr>
@@ -71,7 +92,7 @@ Create scenes, place tokens, draw walls and doors, set lighting and darkness, ad
 
 **Voice & Image Generation**
 
-Assign unique AI voices to NPCs across four 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.
+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.
 
 </td>
 <td width="33%" valign="top">
@@ -87,7 +108,7 @@ Play, stop, and crossfade playlists and individual tracks with volume and fade c
 
 **Knowledge & Memory**
 
-Semantic search across every journal, character, scene, and item. 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">
@@ -116,10 +137,10 @@ Build NPCs, manage party inventory, apply buffs, and clone monsters from any com
 | **Canvas Environment** | 18 | Walls, lights, weather effects, fog of war, darkness levels |
 | **Combat & Initiative** | 17 | Start encounters, roll initiative, advance turns and rounds |
 | **Characters & Actors** | 16 | Create, inspect, update, and manage player characters and NPCs |
+| **Combat AI** | 14 | NPC tactical decisions, target selection, ability usage, positioning |
 | **Audio & Playlists** | 14 | Play, stop, and crossfade music and ambient sound |
-| **Combat AI** | 12 | NPC tactical decisions, target selection, ability usage, positioning |
 | **Journals & Notes** | 10 | Create and edit journal entries, map pins, and handouts |
-| **Card Decks** | 9 | Draw, deal, shuffle, pass, and manage card hands and decks |
+| **Card Decks** | 9 | Create, draw, shuffle, and reset card stacks and decks |
 | **Canvas Drawing** | 8 | Draw shapes, text, and freehand annotations on the canvas |
 | **Rollable Tables** | 7 | Create tables and roll on them for random encounters or loot |
 | **Macros** | 7 | Create, edit, and execute Foundry macros |
@@ -135,33 +156,30 @@ 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 |
 | **Dice** | 1 | Roll any dice expression with full Foundry roll parsing |
 | **Image Generation** | 1 | Generate scene art or character portraits on demand |
-| **Scene Generator** | 1 | Generate complete scenes from text blueprints |
+| **Scene Generator** | 2 | Generate AI battle-map backgrounds from a text description (image only, no walls or tokens) |
 
 </details>
 
-## Pricing
-
-**$3/month** with a **free 1-month trial** so you can try everything before you commit. All features are available during the trial, no restrictions.
-
-Familiar itself costs $3/month. AI provider costs are separate and depend on your usage and chosen provider. A typical D&D session runs roughly **$0.50–$3** in API costs depending on the model, or **$0** if you use a subscription (Claude, ChatGPT/Codex, Antigravity/Gemini) through MCP or local models through Ollama.
-
-### Your keys, your cost
+## 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.
+Familiar installs like any other Foundry module.
 
-Familiar works differently. You bring your own AI, whether that's an API key you already have or a subscription to Claude, ChatGPT/Codex, 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's no middleman, no per-turn limits, and no credits that run out.
+1. In Foundry, open **Add-on Modules → Install Module**.
+2. Paste this manifest URL and click Install:
 
-## Installation
+   ```
+   https://github.com/Ryanjansen92/familiar-releases/releases/latest/download/module.json
+   ```
 
-Install the Foundry module, pick a provider, and start talking to your game.
+3. Enable Familiar in your world, open its settings, pick a provider, and paste an API key.
 
-If you want to connect an MCP client (Claude Desktop, Claude Code, Codex CLI / Desktop, Antigravity CLI / Editor, Gemini CLI, or ChatGPT), you also need the 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, Gemini CLI, 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. No JSON editing.
+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.
 
 ### Compatibility
 
@@ -172,24 +190,24 @@ The **MCP Setup Wizard** in Module Settings → Familiar walks you through conne
 
 ## Connect your AI
 
-There are two ways to connect an AI to your game. Both give the AI the same 188 tools. The difference is where the model runs and how you pay.
+There are two ways to connect an AI to your game. Both reach the same 191 tools. The difference is where the model runs and how you pay.
 
 ### Option 1: Built-in chat (API key)
 
 No server. No terminal. No config files. Install the module, pick a provider, paste an API key, and start talking.
 
-Familiar connects directly to **26 AI providers** across four categories:
+Familiar connects directly to **25 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) |
-| **Voice** (4) | ElevenLabs, Cartesia, OpenAI TTS, PlayHT |
+| **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's also the only option that supports local models (Ollama, LM Studio) for fully offline play.
+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.
 
 ### Option 2: MCP (your existing subscription)
 
@@ -200,7 +218,7 @@ Familiar supports eight MCP clients out of the box:
 | Client | Subscription | Transport | Setup |
 |--------|-------------|-----------|-------|
 | Claude Desktop | Anthropic Pro / Max / Team | stdio | Add to `claude_desktop_config.json` with `env: { FAMILIAR_WS_SECRET }` |
-| Claude Code (CLI) | Anthropic Pro / Max / Team | stdio | `claude mcp add --env FAMILIAR_WS_SECRET=… familiar -- npx familiar-vtt` |
+| Claude Code (CLI) | Anthropic Pro / Max / Team | stdio | `claude mcp add --scope user --env FAMILIAR_WS_SECRET=… familiar -- npx familiar-vtt` |
 | Codex CLI | ChatGPT Plus / Pro / Team | stdio | `codex mcp add familiar --env FAMILIAR_WS_SECRET=… -- npx -y familiar-vtt` |
 | 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 |
@@ -210,7 +228,7 @@ Familiar supports eight MCP clients out of the box:
 
 ¹ *Gemini CLI is deprecated by Google on 2026-06-18 — use Antigravity CLI instead.*
 
-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.
+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.
 
 ### Which should I pick?
 
@@ -219,15 +237,51 @@ You don't need to configure each client by hand. The **MCP Setup Wizard** in Mod
 | 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 |
-| Have voice, images, and transcription | **Built-in chat** (MCP is text-only) |
+| Have voice, images, and transcription | **Built-in chat** (over MCP, media renders in Foundry — see below) |
 | Run complex multi-step tasks | **MCP** (external clients handle long chains better) |
 
+### What's different between the two paths
+
+All 191 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).
+
 ## Works with what you already have
 
 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.
 
 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.
 
+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.
+
+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.
+
+## Pricing
+
+**$3 a month, or $25 a year.** Start with a free 1-month trial: every feature unlocked, no restrictions, cancel anytime.
+
+That price is the whole cost of Familiar. No per-message fee, no token metering, no credits to top up.
+
+### Do I pay twice?
+
+Fair question. You pay for Familiar, and you pay for the AI that powers it, but never to us and never marked up. Here is how it breaks down:
+
+| What you pay for | Who you pay | Typical cost |
+|---|---|---|
+| Familiar (the module + all 191 tools) | Us | $3 / month or $25 / 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.
+
+### 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.
+
 ## Why I built this
 
 I'm Ryan. Dad of two young kids, married to my favorite person, with the free time you'd expect.
@@ -236,7 +290,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 188 tools across 24 domains and 26 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 here.
 
 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.
 
@@ -245,21 +299,42 @@ 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 data collection of any kind. Familiar runs entirely inside your local Foundry instance. 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.
+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.)
+
+</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.
 
 </details>
 
 <details>
 <summary><b>Can the AI break my world?</b></summary>
 
-Familiar sanitizes all document updates so the AI can't change ownership, permissions, or internal IDs. Prototype pollution protection is built in, destructive operations require confirmation, and WebSocket connections use shared-secret authentication. Always keep backups regardless. Good practice with or without AI.
+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.
+
+</details>
+
+<details>
+<summary><b>How does the free trial work, and will I be charged automatically?</b></summary>
+
+The trial is a full month with every feature unlocked, no restrictions. Billing runs through Polar. Cancel any time before the month is up and you won't be charged. If you do cancel, Familiar simply stops running new AI tool calls once the license check lapses; everything the AI already created stays in your Foundry world, untouched.
 
 </details>
 
 <details>
 <summary><b>What happens to my data if I cancel?</b></summary>
 
-Everything stays in your Foundry world. Memory banks, knowledge base indexes, session transcripts, generated portraits, all of it lives in your local Foundry data directory, owned by your world. Cancelling stops Familiar from running new tool calls once the license check fails, but nothing the AI already created gets touched.
+Everything stays in your Foundry world. Memory banks, knowledge base indexes, session transcripts, generated portraits, all of it lives in your local Foundry data directory, owned by your world. Cancelling stops Familiar from running new tool calls once the license check lapses, but nothing the AI already created gets touched.
+
+</details>
+
+<details>
+<summary><b>Will Familiar slow down my Foundry or cause lag?</b></summary>
+
+No meaningful impact on Foundry's frame rate. The chat window is a plain DOM panel; it doesn't touch the canvas renderer, so it doesn't add to the per-token rendering cost that bogs down big battles. The AI's tool calls run the same Foundry operations you'd do by hand, just triggered by text. The only thing that takes a moment is the AI itself thinking and streaming its reply, which happens on the provider's side, not in your game.
 
 </details>
 
@@ -273,21 +348,23 @@ 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 local server, letting you use existing subscriptions and handling complex multi-step tasks better. Both have access to the same 188 tools.
+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 191 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.7 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).
+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.
 
 </details>
 
 <details>
-<summary><b>Can I use this for solo play?</b></summary>
+<summary><b>Can I play solo, or one-on-one?</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.
+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.)
+
+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.
 
 </details>
 
@@ -342,6 +419,14 @@ Expanding beyond D&D 5e with full system-specific tools (character sheets, comba
 | Call of Cthulhu | Planned |
 | Savage Worlds | Planned |
 
+### Solo & duet play
+
+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).
+
+- **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 for one PC**: 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
+
 ### Improvements
 
 - **Combat AI**: retreat behavior, morale, group coordination beyond what shipped
@@ -355,11 +440,13 @@ Join the [Discord](https://discord.gg/pN6pEvYH) for bug reports, feature ideas,
 
 ## License
 
-Familiar is licensed under the [PolyForm Shield License 1.0.0](https://polyformproject.org/licenses/shield/1.0.0/). You can use, read, and modify the software freely, but you may not use it to build a competing product. See [LICENSE](https://github.com/Ryanjansen92/familiar-releases/blob/main/LICENSE) for the full text.
+Familiar is licensed under the [PolyForm Shield License 1.0.0](https://polyformproject.org/licenses/shield/1.0.0/): you can use and self-host it for any purpose except building a competing product. It ships as a compiled build, and the source repository is private. See [LICENSE](https://github.com/Ryanjansen92/familiar-releases/blob/main/LICENSE) for the full text.
 
 <div align="center">
 
-Built for the DM who has more ideas than free time.
+Built for the DM who has more ideas than free time — and wouldn't mind playing for once.
+
+**[Install Familiar — free for a month](#installation)**
 
 *May your rolls be high, your prep be low, and your players never notice the AI is helping.*