# TerraVanilla

Studio narratif local pour maîtres du jeu — *l'IA propose, le MJ décide.*

Un outil calme, assisté par IA, pour concevoir des univers et des campagnes de JdR, les faire évoluer au fil des parties, et préparer ses sessions. Voir [docs/cadrage.md](docs/cadrage.md) pour la vision complète et [docs/etude-existant.md](docs/etude-existant.md) pour le positionnement.

## Démarrer

```bash
npm install
npm run graine     # sème un monde de démonstration (une seule fois)
npm run dev        # serveur API (4517) + interface Vite (5173)
npm test           # suite de tests (logique pure + indexeur)
```

Node **24+** requis (`node:sqlite`). Thème encre (sombre) par défaut — changez-le dans Paramètres.

Ouvre <http://localhost:5173> (dev) — ou, après `npm run build`, le serveur seul sert tout sur <http://localhost:4517>.

## Où vivent les mondes

Dans `~/TerraVanilla/mondes/` (modifiable via `TERRAVANILLA_HOME`). Chaque monde est un dossier de fichiers Markdown + frontmatter, avec son propre dépôt git (commit automatique à chaque changement) et un index SQLite jetable dans `.terravanilla/`.

> Les fichiers sont lisibles partout, mais **l'app est le seul écrivain** — pas d'édition externe pendant qu'elle tourne.

## Structure

- `server/` — Fastify + moteur monde : fichiers Markdown, index `node:sqlite` (FTS5 + table d'arêtes), git silencieux.
- `web/` — React + Vite : rail / scène / panneau, fiches sérif, graphe local WebGL, recherche.
- `shared/` — types partagés (entités, relations, graphe).
- `docs/` — cadrage produit et étude de l'existant.

## État d'avancement

- [x] **Jalon 1 — Le monde habite quelque part** : multi-mondes, fichiers + git, index, consultation, graphe local, recherche, édition manuelle.
- [x] **Jalon 2 — Tisser et Demander** : conversation de création via le Claude CLI (Agent SDK, Sonnet 5), session zéro, cartes Passer/Retourner/Changer de focale, propositions à valider, mode Demander canon-strict, maturité, Atelier, graphe global filtrable.
- [x] **Jalon 3 — Faire évoluer et importer** : campagnes, sessions jouées, débrief conversationnel (résumé + paquet de canon en diffs), détection d'impact sur les trames, drapeaux « à revisiter », arbitrages de cohérence, import web avec sources citées.
- [x] **Au-delà du MVP** : *Préparer la prochaine séance* (dossier de séance archivé par campagne), *le monde qui vit* (ellipses jouées en diffs, depuis l'Atelier), *machine à remonter le temps* (journal du monde, historique et restauration par fiche, sauvegarde .bundle), *à la table* (notes horodatées, questions éclair, relances, oracles en situation), *les muses* (quatre voix de questionnement au Tisser), decks de genres pour la session zéro.
- [x] **Tiers 2-3** : *codex joueurs* (fiches « partage », sections `## Secrets` toujours retranchées, export HTML autonome — depuis le Journal), *Demander par point de vue* (« que sait la Guilde ? »), *chronologie in-world* (date fictive + rang sur les événements, frise dans le Journal), *publication de trames* (dossier imprimable : la trame + ses fiches liées), *portraits* (une image par fiche), *cartes à épingles* (chaque épingle mène à sa fiche), *import d'archives locales* (md/txt/docx/pdf, borné, via propositions), *fiches parentes* (proximité de vocabulaire — doublons et échos), *dictée* (reconnaissance vocale du navigateur, si disponible).

## TerraVanilla ouvert (MCP)

Le canon est interrogeable depuis n'importe quel client MCP, **en lecture seule** (lister_mondes, lister_entites, chercher, lire_fiche) :

```bash
claude mcp add terravanilla -- npx tsx <chemin-du-repo>/server/src/mcp.ts
```

## Comment ça marche (IA)

L'IA tourne sur ton installation **Claude Code locale** via le Claude Agent SDK — même abonnement, aucune clé API. L'agent n'a **aucun droit d'écriture** : il dispose de `chercher`, `lire_fiche`, `proposer` et `signaler_tension` ; seule ta validation écrit au canon (et chaque validation fait un commit git). Chaque mode (Tisser, Session zéro, Demander, Débrief, Importer) est un profil d'agent distinct ; le mode Importer a en plus accès à la recherche web.

## Licence

MIT, voir [LICENSE](LICENSE).