feat: initial DCC RPG knowledge base + AI DM design

CHECKLIST.md

@@ -0,0 +1,152 @@
+# Checklist: Da Design a Prototipo Giocabile
+
+**Obiettivo**: Qualcuno clona il repo e in <30 min gioca un turno.
+**Target**: Singolo utente, browser, esecuzione locale on-premise.
+
+---
+
+## Fase 0 — Setup Progetto (priorità: critica)
+
+- [ ] `git init` nella directory /home/codex/rpg/
+- [ ] Struttura directory (src/, tests/, data/, frontend/)
+- [ ] `requirements.txt`: FastAPI, uvicorn, ollama-python, aiohttp
+- [ ] `docker-compose.yml` opzionale (per isolamento)
+- [ ] Script `start.sh` / `start.bat` che avvia tutto con un comando
+- [ ] `.gitignore`: dcc/pdf_pages/, __pycache__, *.db
+
+---
+
+## Fase 1 — Backend Core (priorità: critica)
+
+### 1.1 State Machine
+- [ ] `src/engine/state_machine.py`: orchestratore turni (Leggi -> LLM -> Valida -> Esegui -> Scrivi)
+- [ ] Retry logic con backoff esponenziale + jitter
+- [ ] Idempotenza: cache risultati per turn_id
+- [ ] Safe fallback narrativo su errore
+
+### 1.2 SQLite / Stato Gioco
+- [ ] `src/engine/db.py`: connessione, init schema, migrazioni
+- [ ] Implementare schema: campaign, characters, adventure_state, quest_log, turn_log
+- [ ] CRUD base per ogni tabella
+- [ ] Backup automatico (copia .db a ogni avvio)
+
+### 1.3 Approved Tools (10)
+- [ ] `roll-dice`: d20, d%, d24, catena dadi, modificatori
+- [ ] `combat`: iniziativa, attacco, mighty-deed, furtivo, critico, fumble
+- [ ] `ability-check`: abilità ladro (con dado dedicato) e altri (d20+mod)
+- [ ] `saving-throw`: Tempra/Riflessi/Volontà
+- [ ] `movement`: esplorazione stanze, distanza, incontri
+- [ ] `spellcasting`: prova incantesimo, tabella risultati, corruzione/ritorsione
+- [ ] `update-inventory`: aggiungi/rimuovi/equipaggia
+- [ ] `award-xp`: 0-4 PE per incontro, avanzamento livello
+- [ ] `update-quest`: stato missioni
+- [ ] `dm-override`: modifica stato, forza risultato, ignora regola
+
+---
+
+## Fase 2 — LLM Integration (priorità: critica)
+
+- [ ] `src/llm/client.py`: wrapper chiamate Ollama API (gemma2:9b)
+- [ ] `src/llm/prompts.py`: template system prompt con:
+  - Regole fondamentali (d20, CD/CA, catena dadi)
+  - Approved Tools (nome, parametri, quando usarli)
+  - Mappa avventura (aree, CD, statistiche mostri)
+  - Regole classi (Dado Cimento, abilità ladro, ecc.)
+- [ ] `src/llm/parser.py`: parsing risposta LLM -> tool calls strutturati
+- [ ] Tool calling: filtraggio tool contro allowlist + validazione parametri
+- [ ] Test: chiamata singola a Ollama, verificare risposta in italiano
+
+---
+
+## Fase 3 — Avventura Machine-Readable (priorità: alta)
+
+- [ ] `data/adventure/areas.json`: tutte le 9 aree con descrizione, CD, mostri, tesori
+- [ ] `data/adventure/monsters.json`: tutte le creature con statistiche complete
+- [ ] `data/adventure/items.json`: oggetti recuperabili (corno demoniaco, soldatini, ecc.)
+- [ ] `data/adventure/quests.json`: quest principale + secondaria della driade
+- [x] Completare Aree 1.1, 1.3 e 1.9 (mancano) — scrivere descrizioni originali ispirate al tema
+- [x] Completare pagina 39 (setup avventura, plot hook: Vorkhul Ksh'tharan, il Vincolato alle Stelle)
+- [x] Completare tabelle equipaggiamento (armi, armature, equipaggiamento — tradotte dal Reference Booklet)
+- [x] Completa tabella critici (I-V) e fumble in italiano (tradotta dal Reference Booklet)
+- [x] Completa tabella mestieri d100 (tradotta dal Reference Booklet)
+- [x] Completa tabelle classi + abilità ladro + mighty deeds (tradotte dal Reference Booklet)
+
+---
+
+## Fase 4 — Frontend (priorità: alta)
+
+- [ ] `frontend/index.html`: pagina singola con chat + pannello stato
+- [ ] `frontend/style.css`: tema scuro DCC, leggibile, essenziale
+- [ ] `frontend/app.js`: connessione WebSocket/Fetch al backend
+- [ ] Pannello stato personaggi (PF, classe, PE, equipaggiamento)
+- [ ] Pannello mappa (aree visitate/da visitare)
+- [ ] Log azioni recenti (ultimi N turni)
+- [ ] Input testuale per azioni giocatore
+- [ ] DM-Override: pulsante per attivare modalità DM + comandi
+- [ ] Adattamento mobile (giocabile da telefono)
+
+---
+
+## Fase 5 — Colmare Gap OCR (priorità: media)
+
+- [x] Recuperare pagina 39: scritta ex-novo (Vorkhul Ksh'tharan background)
+- [x] Estrarre strutturalmente le tabelle critici/fumble (formato Markdown, tradotte dal Reference Booklet)
+- [x] Completare tabella equipaggiamento (Reference Booklet → Italiano)
+- [ ] Ripetere OCR pagine 1-2 con pre-processing (contrasto, bianco/nero)
+- [ ] Completare risultati incantesimi fascia alta (20-31+) da screenshot
+
+---
+
+## Fase 6 — Testing (priorità: media)
+
+- [ ] `tests/test_tools.py`: test unitari per ogni Approved Tool
+  - roll-dice: distribuzione, catena dadi, modificatori
+  - combat: critico/fumble, mighty-deed, CA
+  - ability-check: dado ladro vs d20 standard
+  - spellcasting: corruzione, ritorsione, tabella risultati
+- [ ] `tests/test_state_machine.py`: flusso completo di un turno
+- [ ] `tests/test_avventura.py`: integrità dati (aree collegabili, mostri referenziati)
+- [ ] `tests/test_llm_parser.py`: parsing risposte LLM, filtraggio allowlist
+
+---
+
+## Fase 7 — Documentazione (priorità: media)
+
+- [ ] `README.md` aggiornato con "Come avviare":
+  - Prerequisiti (Python 3.11+, Ollama in esecuzione)
+  - `pip install -r requirements.txt`
+  - `python start.py`
+  - Aprire browser a http://localhost:8000
+- [ ] `docs/setup.md`: configurazione Ollama, gestione API key
+- [ ] `docs/architettura.md`: diagramma flusso, spiegazione pattern NSL
+- [ ] `docs/dm-guide.md`: come usare DM-Override, comandi disponibili
+
+---
+
+## Fase 8 — Rifiniture (priorità: bassa)
+
+- [ ] Rate limiting azioni (anti-spam)
+- [ ] Salvataggio automatico ogni N turni
+- [ ] Logging strutturato (token usage, latenza, errori)
+- [ ] Backup automatico SQLite
+- [ ] Supporto "setaccio": 4 personaggi per giocatore da gestire in UI
+- [ ] Excalidraw/mappa visuale delle stanze
+- [ ] Effetti sonori (opzionale, per atmosfera)
+
+---
+
+## Riepilogo Tempo Stimato
+
+| Fase | Ore | Priorità |
+|------|-----|----------|
+| 0 — Setup Progetto | 0.5 | 🔴 Critica |
+| 1 — Backend Core | 4-6 | 🔴 Critica |
+| 2 — LLM Integration | 2-3 | 🔴 Critica |
+| 3 — Avventura Machine-Readable | 2-3 | 🟡 Alta |
+| 4 — Frontend | 3-4 | 🟡 Alta |
+| 5 — Gap OCR | 2 | 🟠 Media |
+| 6 — Testing | 2 | 🟠 Media |
+| 7 — Documentazione | 1 | 🟠 Media |
+| 8 — Rifiniture | 2-3 | 🔵 Bassa |
+
+**Totale**: ~18-25 ore per MVP giocabile da altri.