familiar-vtt 2.5.16

package/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2026 Ryan Jansen. All rights reserved.
+
+This software and associated documentation files (the "Software") are proprietary
+and confidential. Unauthorized copying, distribution, modification, or use of this
+Software, via any medium, is strictly prohibited without prior written permission
+from the copyright holder.
+
+The Software is provided "as is", without warranty of any kind, express or implied.

package/README.md

@@ -0,0 +1,265 @@
+<div align="center">
+
+# Familiar
+
+### Your AI co-pilot for Foundry VTT
+
+**176 tools. 25 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.
+
+[![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-proprietary-lightgrey)](#license)
+
+<!-- 🎬 Demo video coming soon -->
+<!-- ![Familiar in action](docs/assets/hero-demo.gif) -->
+
+[Installation](#installation) | [Quick Start](#quick-start) | [Features](#features) | [Connect Your AI](#connect-your-ai) | [FAQ](#faq)
+
+</div>
+
+---
+
+## The story behind Familiar
+
+I'm Ryan — a busy dad of two young kids and a loving wife. After a couple of hectic years, my group wanted to get back to playing D&D together. But finding time to prep sessions? Nearly impossible.
+
+I also love running 1-on-1 campaigns for my wife, but solo DMing is *hard*. You're the storyteller, every NPC, the rules engine, and the atmosphere all at once. I needed a co-pilot — something that could voice a tavern keeper, roll initiative for a goblin ambush, conjure a battlemap on the fly, and pick the perfect background music, all while I focused on the story.
+
+So I built one.
+
+Familiar started as a personal tool. It grew into 176 tools across 24 domains because every session I kept thinking: *"what if it could also..."* Now it can. And I think it might help you too.
+
+---
+
+## What can Familiar do?
+
+Familiar turns any large language model into a full VTT operator. Your AI doesn't just *talk about* your game — it **controls** it.
+
+<table>
+<tr>
+<td width="50%">
+
+### Run combat encounters
+Start combat, roll initiative, track turns, apply damage, manage conditions — all through natural conversation.
+
+*"Roll initiative for everyone and start the encounter."*
+
+</td>
+<td width="50%">
+
+### Play NPCs with unique voices
+Generate speech for any character using AI voice providers. Each NPC gets their own voice, accent, and personality.
+
+*"Have the innkeeper warn the party about the forest, in a raspy old voice."*
+
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+### Generate images on demand
+Create character portraits, item illustrations, battlemaps, and handouts during play. Five image providers to choose from.
+
+*"Generate a portrait of a half-orc blacksmith with a missing tusk."*
+
+</td>
+<td width="50%">
+
+### Control the atmosphere
+Switch scenes, adjust lighting, change weather, play music — set the mood without ever leaving the conversation.
+
+*"Transition to the forest scene, dim the lights, start the rain, and play something ominous."*
+
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+### Manage characters & inventory
+Read full character sheets, update HP, import items from the compendium, manage spell slots — the AI sees everything.
+
+*"Give Elara the Cloak of Elvenkind from the compendium."*
+
+</td>
+<td width="50%">
+
+### Improvise on the fly
+Players went off-script? The AI creates NPCs, spawns tokens, builds encounters, writes journal entries — in seconds.
+
+*"The party decides to rob the bank. Set up a heist encounter."*
+
+</td>
+</tr>
+</table>
+
+---
+
+## Features at a glance
+
+| Domain | Tools | Highlights |
+|--------|------:|------------|
+| **Characters & Actors** | 14 | Full sheet access, create/update/delete, ownership management |
+| **Combat & Initiative** | 13 | Start/end encounters, turn tracking, conditions, batch damage |
+| **Combat AI** | 6 | AI-driven attacks, spells, movement, saving throws, death saves |
+| **Scenes & Tokens** | 19 | Create scenes, place/move tokens, weather, darkness, fog of war |
+| **Canvas Drawing** | 8 | Tiles, drawings — spell effects and decorations |
+| **Canvas Environment** | 18 | Walls, doors, lights, ambient sounds, map pins |
+| **Audio & Playlists** | 14 | Full playlist control, play/stop tracks, create playlists on the fly |
+| **Journals & Notes** | 10 | Session notes, lore pages, searchable campaign knowledge |
+| **Compendium & Rules** | 4 | Search monsters/spells/items, spawn creatures into the world |
+| **Image Generation** | 1 | AI-generated portraits, tokens, maps, handouts (5 providers) |
+| **Voice Generation** | 4 | Text-to-speech for NPCs, multi-voice dialogue, character voices |
+| **Scene Generator** | 1 | Generate complete scenes from structured blueprints |
+| **Knowledge & Memory** | 3 | Campaign lore search, persistent memories |
+| **+ 11 more domains** | 61 | Macros, effects, items, folders, tables, cards, regions, events... |
+| **Total** | **176** | |
+
+---
+
+## Connect your AI
+
+Familiar works three ways. Pick what suits you.
+
+### Built-in chat (easiest)
+No server, no config. Install the module, pick an AI provider, paste your API key, and start talking.
+
+> Works with **16 chat providers**: OpenAI, Anthropic, Google, Mistral, Groq, DeepSeek, xAI, Cohere, Together, Fireworks, Perplexity, Cerebras, SambaNova, OpenRouter, and local models via **Ollama** and **LM Studio**.
+
+### MCP — use your existing AI subscription
+Already paying for Claude Pro, ChatGPT Plus, or Gemini? Connect them directly via the [Model Context Protocol](https://modelcontextprotocol.io). Your AI subscription becomes your DM assistant at no extra cost.
+
+| Client | Transport | Setup |
+|--------|-----------|-------|
+| **Claude Desktop** | stdio | `npx familiar-vtt` |
+| **Claude Code** | stdio | `npx familiar-vtt` |
+| **ChatGPT** | Streamable HTTP | Remote via Cloudflare tunnel |
+| **Gemini CLI** | stdio | `npx familiar-vtt` — free with Gemini 2.5 Pro |
+| **Cursor / Windsurf / VS Code** | stdio | Via MCP config |
+
+The module includes a step-by-step **MCP Setup Wizard** to guide you through connecting any client.
+
+### BYOK philosophy
+Familiar never proxies, meters, or marks up your AI costs. You bring your own API keys, and every token goes straight to the provider. With 25 providers to choose from, you're never locked in.
+
+---
+
+## Installation
+
+### From Foundry (recommended)
+1. Open Foundry VTT as GM
+2. Go to **Settings** > **Manage Modules** > **Install Module**
+3. Search for **"Familiar"** or paste the manifest URL:
+   ```
+   https://github.com/Ryanjansen92/familiar/releases/latest/download/module.json
+   ```
+4. Click **Install**, then enable the module in your world
+
+### For MCP clients (npm)
+```bash
+npx familiar-vtt
+```
+Or install globally:
+```bash
+npm install -g familiar-vtt
+```
+
+---
+
+## Quick start
+
+1. **Install & enable** the Familiar module in your Foundry world
+2. **Open settings** — go to Module Settings > Familiar
+3. **Pick a chat provider** (e.g., OpenAI, Anthropic, or a free local model via Ollama)
+4. **Paste your API key**
+5. **Open the Familiar chat** from the sidebar button
+6. **Start playing** — ask your AI to roll dice, run combat, describe a scene, or generate an image
+
+That's it. No Node.js server needed, no terminal, no config files.
+
+> **Power users**: Want to use Claude Desktop, ChatGPT, or Gemini CLI? Open the MCP Setup Wizard in the module settings for step-by-step instructions.
+
+---
+
+## Supported systems
+
+Familiar is designed for **D&D 5e (2024)** on Foundry VTT and works with both **Foundry v13** and **v14**.
+
+Other game systems may work for basic features (dice rolling, scenes, journals) but are not officially tested yet.
+
+---
+
+## FAQ
+
+<details>
+<summary><b>Is it free?</b></summary>
+
+Yes. All 176 tools, all 25 providers, the built-in chat, and full MCP support are free. A Pro tier with premium features (session persistence, auto-summarization, NPC memory) is coming soon for a small monthly fee.
+</details>
+
+<details>
+<summary><b>Does my game data leave my computer?</b></summary>
+
+Only when you talk to an AI provider — the same as any other AI chat. Familiar runs locally inside Foundry. No telemetry, no analytics, no data collection. If you use a local model (Ollama/LM Studio), nothing ever leaves your machine.
+</details>
+
+<details>
+<summary><b>Can the AI break my world?</b></summary>
+
+Familiar has built-in safety rails. Document updates are sanitized — the AI can't change ownership, permissions, or document IDs. Destructive operations (delete character, end combat) require explicit confirmation in the conversation. That said, it's always smart to back up your world before trying new tools.
+</details>
+
+<details>
+<summary><b>Can I use it for solo play?</b></summary>
+
+Absolutely — that's one of the main use cases. The AI can run NPCs, manage encounters, describe scenes, and make rulings. It's like having a DM available whenever you want to play.
+</details>
+
+<details>
+<summary><b>Does it work with other modules?</b></summary>
+
+Familiar works alongside any Foundry module. Dedicated integrations with Midi-QOL, Sequencer, Token Magic FX, and JB2A are on the roadmap.
+</details>
+
+<details>
+<summary><b>What AI model should I use?</b></summary>
+
+For the best experience, use a model with a large context window and strong tool-use support: **Claude 4 Sonnet/Opus**, **GPT-4o**, or **Gemini 2.5 Pro**. For free/local options, **Gemini CLI** (free tier) or **Ollama with Qwen/Llama** work well.
+</details>
+
+---
+
+## Roadmap
+
+- [ ] Session persistence (conversations saved to journal entries)
+- [ ] Context management & auto-summarization
+- [ ] NPC character cards (personality, speech patterns, memory)
+- [ ] Session recaps (one-click journal summary)
+- [ ] Module integrations (Midi-QOL, Sequencer, Token Magic FX)
+- [ ] AI Campaign Setup (import an adventure, auto-prep your sessions)
+
+---
+
+## Contributing & feedback
+
+Familiar is in early access. If you run into bugs, have feature ideas, or just want to share how you're using it — I'd love to hear from you.
+
+- [Open an issue](https://github.com/Ryanjansen92/familiar/issues)
+- [Join the discussion](https://github.com/Ryanjansen92/familiar/discussions)
+
+---
+
+## License
+
+Familiar is proprietary software. See [LICENSE](LICENSE) for details.
+
+---
+
+<div align="center">
+
+Built with care by a DM who'd rather be playing.
+
+*Now go roll some dice.*
+
+</div>