commit 2f722f541cdd6081d2dd786ed7a046ec43a0e554
Author: AdrianoDev <adrianodalpastro@gmail.com>
Date:   Tue Apr 21 11:54:46 2026 +0200

    docs: initial import design sistema documentale + docugen-mcp
    
    - Docs/sistema-documentale/: master architettura multi-wiki
    - Docs/docugen-mcp/: design + implementation plan MCP server
    
    Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

diff --git a/Docs/docugen-mcp/2026-04-21-design.md b/Docs/docugen-mcp/2026-04-21-design.md
new file mode 100644
index 0000000..ad25212
--- /dev/null
+++ b/Docs/docugen-mcp/2026-04-21-design.md
@@ -0,0 +1,600 @@
+# DocuGen MCP — Design Document
+
+> MCP server standalone per generazione di documenti Markdown
+> a partire da un template (Markdown + frontmatter + prompt),
+> contenuto grezzo e variabili. LLM via OpenRouter.
+> Deploy Docker su VPS esterna, accessibile da qualsiasi host MCP
+> (Claude Code, Claude Desktop, altri client conformi).
+
+---
+
+## Indice
+
+1. [Panoramica](#1-panoramica)
+2. [Architettura generale](#2-architettura-generale)
+3. [Componenti interni](#3-componenti-interni)
+4. [Modello dati](#4-modello-dati)
+5. [API MCP — tool esposti](#5-api-mcp--tool-esposti)
+6. [Dataflow `document_generate`](#6-dataflow-document_generate)
+7. [Gestione errori](#7-gestione-errori)
+8. [Strategia di test](#8-strategia-di-test)
+9. [Deploy e operatività](#9-deploy-e-operatività)
+10. [Stack tecnologico](#10-stack-tecnologico)
+
+---
+
+## 1. Panoramica
+
+### Scopo
+
+`docugen-mcp` è un server MCP che espone strumenti per creare documenti Markdown professionali (fatture, lettere, preventivi, report) a partire da:
+
+- un **template** persistito sul server (nome + frontmatter YAML + body Markdown con prompt e placeholder)
+- un **contenuto grezzo** Markdown fornito dal client (es. "# Ordine ACME\n- 10 unità X...")
+- un **dict di variabili** strutturate (es. `{cliente: "ACME", data: "2026-04-21", foto_prodotto: {kind: image, data_b64, mime}}`)
+- **istruzioni libere** opzionali per tweak stilistici ("tono formale", "in inglese")
+
+Il server assembla un prompt, chiama un modello LLM via OpenRouter e restituisce il Markdown finale al client.
+
+### Principi
+
+- **MCP protocol-first** — il server è un MCP server, non una API REST con wrapper MCP. FastMCP è il framework principale.
+- **Standalone** — repo dedicato, nessuna dipendenza da DocuGen. DocuGen e altri sistemi lo usano come client.
+- **Stateless sui documenti generati** — il server non tiene archivio dei MD prodotti (solo log/cost tracking in SQLite). Il client conserva l'output.
+- **Persistenza solo dove serve** — template sul filesystem (ispezionabili a mano), asset efimeri con TTL, metrica generazioni in SQLite.
+- **Validazione strict** — se il template dichiara `required_variables` e mancano, errore duro, niente chiamata LLM sprecata.
+- **Errori espliciti** — codici stringa ben definiti, retry solo su errori transitori upstream.
+
+### Cosa NON fa
+
+- Non genera PDF né HTML (solo Markdown). Conversione fuori scope.
+- Non tiene un archivio ricercabile dei documenti prodotti.
+- Non fa OCR, estrazione metadati da documenti, ricerca semantica (ruolo di DocuGen).
+- Non espone gestione utenti: una sola API key condivisa.
+
+---
+
+## 2. Architettura generale
+
+### Approccio: FastMCP principale + FastAPI sub-app
+
+Un singolo processo ASGI, un container Docker, un volume disco.
+
+```
+┌──────────────────────────────────────────────┐
+│  Container docugen-mcp (VPS esterna)         │
+│                                              │
+│  ┌────────────────────────────────────────┐  │
+│  │   FastMCP (ASGI root)                  │  │
+│  │   Streamable HTTP su /mcp              │  │
+│  │                                        │  │
+│  │   Tool esposti:                        │  │
+│  │     • template_create                  │  │
+│  │     • template_update                  │  │
+│  │     • template_delete                  │  │
+│  │     • template_list                    │  │
+│  │     • template_get                     │  │
+│  │     • document_generate                │  │
+│  └────────────────────────────────────────┘  │
+│                   │                          │
+│         mount FastAPI sub-app                │
+│                   ▼                          │
+│  ┌────────────────────────────────────────┐  │
+│  │   FastAPI sub-app                      │  │
+│  │     GET  /assets/{template}/{file}     │  │
+│  │     GET  /generated/{gen_id}/{file}    │  │
+│  │     GET  /health                       │  │
+│  └────────────────────────────────────────┘  │
+│                                              │
+│  Moduli (librerie Python):                   │
+│    • auth              — middleware API key  │
+│    • template_store    — filesystem          │
+│    • llm_client        — OpenRouter (httpx)  │
+│    • renderer          — prompt assembly     │
+│    • generation_store  — SQLite + fs         │
+│                                              │
+│  Volume Docker montato su /data:             │
+│   ├── templates/<nome>/                      │
+│   │    ├── template.md                       │
+│   │    └── assets/*                          │
+│   ├── generated/<gen_id>/                    │
+│   │    └── <var_name>.<ext>    (TTL 30gg)    │
+│   └── docugen_mcp.db                         │
+└──────────────────────────────────────────────┘
+           ▲                      │
+           │ HTTP(S) + API key    │ HTTPS
+           │                      ▼
+     ┌─────┴──────────┐     ┌──────────┐
+     │ Host MCP       │     │OpenRouter│
+     │ (Claude Code,  │     │          │
+     │  Claude Desktop│     └──────────┘
+     │  altri)        │
+     └────────────────┘
+```
+
+### Motivazioni architetturali
+
+- **MCP è il prodotto.** FastMCP guida la struttura. FastAPI compare solo per ciò che l'MCP protocol non copre: file statici per asset immagini e health check.
+- **Un processo unico** mantiene deploy banale: un container, un comando, un volume.
+- **TLS fuori container.** Reverse proxy esterno (Nginx/Traefik/Caddy) gestisce certificati e termina HTTPS. Il container espone HTTP su porta interna.
+- **Storage semplice.** Template sul filesystem (leggibili a mano, backup = copia cartella, git-friendly se l'operatore vuole). Metriche e indice TTL in SQLite per query strutturate. Nessun DB esterno.
+
+### Scalabilità
+
+Processo singolo basta per l'uso previsto (pochi client, decine di generazioni/minuto al massimo). Per picchi futuri: replicare il container dietro load balancer, spostare il volume su storage condiviso (NFS) o estrarre SQLite in Postgres. Scelte rimandate a quando il bisogno sarà concreto.
+
+---
+
+## 3. Componenti interni
+
+### `auth` — middleware API Key
+
+- Legge header `Authorization: Bearer <key>` da ogni richiesta (MCP e FastAPI).
+- Confronta con env var `API_KEY` (singola chiave condivisa).
+- Respinge 401 se assente/errata.
+- Esenzione: `/health`.
+
+### `template_store` — persistenza filesystem
+
+- Path base: `{DATA_DIR}/templates/<nome>/`.
+- File `template.md` = frontmatter YAML + body Markdown.
+- Directory `assets/` contiene risorse statiche referenziate dal template.
+- Frontmatter standard:
+
+```yaml
+---
+name: fattura-commerciale
+description: Fattura commerciale in italiano
+model: anthropic/claude-sonnet-4   # opzionale, override default
+required_variables:
+  - name: cliente
+    type: string
+  - name: data
+    type: string
+  - name: foto_prodotto
+    type: image           # trigger per shape {kind, data_b64, mime}
+instructions_hint: "tono formale, struttura blocchi"
+---
+```
+
+- Body: Markdown con prompt di sistema e placeholder `{{cliente}}`, `{{foto_prodotto}}`, `./assets/logo.png`.
+- API Python (async): `create(name, frontmatter, body, assets=None)`, `get(name)`, `update(name, ...)`, `delete(name)`, `list()`.
+- Nome template: slug `^[a-z0-9][a-z0-9-]*$`. Rifiuta path traversal, chars speciali.
+- Validazione frontmatter via Pydantic `TemplateFrontmatter`.
+
+### `llm_client` — wrapper OpenRouter
+
+- Unica responsabilità: mandare una richiesta OpenRouter e ritornare risposta + metrica utilizzo.
+- httpx async. Retry con backoff esponenziale (max 3 tentativi) su timeout/5xx/429.
+- Modello scelto da `frontmatter.model or env.LLM_MODEL_DEFAULT`.
+- Ritorna `LLMResponse(text: str, model: str, tokens_in: int, tokens_out: int, cost_usd: float, latency_ms: int)`.
+
+### `renderer` — orchestratore della generazione
+
+Riceve `(template_name, content_md, variables, instructions)` e ritorna il Markdown finale.
+
+Passi:
+1. `template_store.get(template_name)` → `(frontmatter, body, assets_dir)`.
+2. Validazione variabili (strict): ogni `required_variables` dev'essere presente con il tipo dichiarato. Fallimento → eccezione tipizzata senza chiamare LLM.
+3. Generazione `gen_id = uuid4()`.
+4. Per ogni variabile di tipo `image`: decodifica base64, valida mime, salva in `{DATA_DIR}/generated/{gen_id}/{var_name}.{ext}`, registra in `ephemeral_assets` con `expires_at = now + ASSET_TTL_DAYS`, sostituisce la variabile con URL assoluto `{PUBLIC_BASE_URL}/generated/{gen_id}/{var_name}.{ext}`.
+5. Rewrite asset paths del template: `./assets/<file>` → `{PUBLIC_BASE_URL}/assets/{template_name}/{file}`.
+6. Assembla prompt finale:
+   - **system**: body del template con placeholder sostituiti.
+   - **user**: contenuto grezzo + variabili formattate + `instructions` opzionali.
+7. Chiama `llm_client.chat(...)` con il modello selezionato.
+8. Registra la generazione in `generation_store` (success o error).
+9. Ritorna `GenerationResult(generation_id, markdown, model, tokens, cost_usd, ephemeral_assets_urls, ephemeral_expires_at)`.
+
+### `generation_store` — persistenza generazioni
+
+- SQLite via aiosqlite. Due tabelle:
+  - `generations(id TEXT PK, timestamp INTEGER, template_name TEXT, model TEXT, tokens_in INTEGER, tokens_out INTEGER, cost_usd REAL, success INTEGER, error_msg TEXT)`
+  - `ephemeral_assets(generation_id TEXT, var_name TEXT, file_path TEXT, mime TEXT, created_at INTEGER, expires_at INTEGER, PRIMARY KEY (generation_id, var_name))`
+- Cleanup job: task asyncio lanciato al bootstrap che ogni 24h cancella file e record con `expires_at < now()`.
+
+### `mcp_server` — entry point FastMCP
+
+- Definisce i 6 tool MCP con decoratori `@mcp.tool()`.
+- Ogni tool fa validazione input (Pydantic), invoca il modulo responsabile, serializza la risposta.
+- Monta la sub-app FastAPI sul path root.
+
+### `config` — Pydantic Settings
+
+Variabili d'ambiente (tutte con default dove sensato):
+
+| Variabile | Default | Descrizione |
+|-----------|---------|-------------|
+| `API_KEY` | *(obbligatoria)* | Chiave di autenticazione client MCP |
+| `OPENROUTER_API_KEY` | *(obbligatoria)* | Chiave OpenRouter |
+| `OPENROUTER_BASE_URL` | `https://openrouter.ai/api/v1` | Endpoint OpenRouter |
+| `LLM_MODEL_DEFAULT` | `anthropic/claude-sonnet-4` | Modello usato se il template non specifica override |
+| `PUBLIC_BASE_URL` | *(obbligatoria)* | URL pubblico del server, usato per costruire link asset |
+| `DATA_DIR` | `/data` | Path volume persistenza |
+| `ASSET_TTL_DAYS` | `30` | TTL asset efimeri generati |
+| `MAX_IMAGE_SIZE_MB` | `10` | Limite dimensione immagine base64 in `variables` |
+| `LLM_TIMEOUT_SECONDS` | `60` | Timeout singola richiesta OpenRouter |
+
+### Struttura sorgente
+
+```
+src/docugen_mcp/
+  ├── __init__.py
+  ├── main.py              # bootstrap FastMCP + FastAPI mount
+  ├── config.py
+  ├── auth.py
+  ├── mcp_tools.py         # definizione tool MCP
+  ├── http_routes.py       # static asset + health (FastAPI)
+  ├── template_store.py
+  ├── llm_client.py
+  ├── renderer.py
+  ├── generation_store.py
+  └── models.py            # Pydantic models condivisi
+tests/
+  ├── unit/
+  ├── integration/
+  └── e2e/
+pyproject.toml
+Dockerfile
+docker-compose.yml
+.env.example
+README.md
+```
+
+---
+
+## 4. Modello dati
+
+### Filesystem
+
+```
+{DATA_DIR}/
+├── templates/
+│   └── <nome-template>/
+│       ├── template.md          # frontmatter + body
+│       └── assets/
+│           └── logo.png         # risorse statiche del template
+├── generated/
+│   └── <gen_id>/                # uuid4, uno per generazione
+│       └── <var_name>.<ext>     # immagini inline dal client (TTL)
+└── docugen_mcp.db               # SQLite
+```
+
+### SQLite
+
+**`generations`**
+
+| Campo | Tipo | Note |
+|-------|------|------|
+| `id` | TEXT PK | uuid4 della generazione |
+| `timestamp` | INTEGER | unix epoch ms |
+| `template_name` | TEXT | |
+| `model` | TEXT | modello effettivamente usato |
+| `tokens_in` | INTEGER | da OpenRouter usage |
+| `tokens_out` | INTEGER | da OpenRouter usage |
+| `cost_usd` | REAL | calcolato da OpenRouter |
+| `success` | INTEGER | 0/1 |
+| `error_msg` | TEXT NULL | codice errore se success=0 |
+
+Indice su `timestamp` per query temporali sui costi.
+
+**`ephemeral_assets`**
+
+| Campo | Tipo | Note |
+|-------|------|------|
+| `generation_id` | TEXT | FK logica a `generations.id` |
+| `var_name` | TEXT | nome variabile (es. `foto_prodotto`) |
+| `file_path` | TEXT | path assoluto sul filesystem |
+| `mime` | TEXT | `image/png`, `image/jpeg`, `image/webp` |
+| `created_at` | INTEGER | unix epoch ms |
+| `expires_at` | INTEGER | unix epoch ms |
+
+PRIMARY KEY `(generation_id, var_name)`. Indice su `expires_at` per cleanup rapido.
+
+---
+
+## 5. API MCP — tool esposti
+
+### `template_create`
+
+**Input:**
+```json
+{
+  "name": "fattura-commerciale",
+  "frontmatter": {
+    "name": "fattura-commerciale",
+    "description": "...",
+    "model": "anthropic/claude-sonnet-4",
+    "required_variables": [
+      {"name": "cliente", "type": "string"},
+      {"name": "data", "type": "string"}
+    ],
+    "instructions_hint": "..."
+  },
+  "body": "# Template Markdown con {{cliente}} placeholder...",
+  "assets": [
+    {"filename": "logo.png", "data_b64": "...", "mime": "image/png"}
+  ]
+}
+```
+
+**Output:** `{"name": "fattura-commerciale", "created_at": "..."}` o errore.
+
+### `template_update`
+
+Stesso input di `template_create`, richiede nome esistente. Sovrascrive `template.md`; `assets` (se forniti) sostituiscono interamente la directory (nessun merge).
+
+### `template_delete`
+
+**Input:** `{"name": "fattura-commerciale"}`. Rimuove directory template.
+
+### `template_list`
+
+**Input:** vuoto. **Output:** lista di `{name, description, updated_at}`.
+
+### `template_get`
+
+**Input:** `{"name": "fattura-commerciale"}`. **Output:** frontmatter + body + elenco asset (nomi, mime, size).
+
+### `document_generate`
+
+**Input:**
+```json
+{
+  "template_name": "fattura-commerciale",
+  "content_md": "# Ordine ACME\n- 10 unità X",
+  "variables": {
+    "cliente": "ACME S.r.l.",
+    "data": "2026-04-21",
+    "foto_prodotto": {
+      "kind": "image",
+      "data_b64": "iVBOR...",
+      "mime": "image/png"
+    }
+  },
+  "instructions": "tono molto formale"
+}
+```
+
+**Output:**
+```json
+{
+  "generation_id": "<uuid>",
+  "markdown": "...output MD...",
+  "model": "anthropic/claude-sonnet-4",
+  "tokens": {"in": 1234, "out": 2345},
+  "cost_usd": 0.0123,
+  "ephemeral_assets_urls": [
+    "https://mcp.vps/generated/<uuid>/foto_prodotto.png"
+  ],
+  "ephemeral_expires_at": "2026-05-21T10:33:00Z"
+}
+```
+
+---
+
+## 6. Dataflow `document_generate`
+
+```
+Client MCP ──► document_generate(...)
+                       │
+                       ▼
+         auth: valida API key (401 se KO)
+                       │
+                       ▼
+         Pydantic: valida shape input
+                       │
+                       ▼
+         renderer.generate():
+           1. template_store.get(name)
+           2. validate variables (strict)
+           3. gen_id = uuid4()
+           4. per ogni var image:
+              - decode base64, valida mime/size
+              - salva /data/generated/<gen_id>/<var>.<ext>
+              - insert ephemeral_assets (expires_at)
+              - sostituisce var con URL assoluto
+           5. rewrite asset paths del template
+           6. assembla prompt finale
+           7. llm_client.chat(prompt, model)
+           8. generation_store.record(success|error)
+                       │
+                       ▼
+         Ritorna GenerationResult al client
+```
+
+**Flusso secondario — accesso asset:**
+
+Quando il client (o il renderer downstream) dereferenzia `![alt](https://mcp.vps/assets/...)`:
+
+- `GET /assets/<template>/<file>` → auth check → serve file da `{DATA_DIR}/templates/<template>/assets/`.
+- `GET /generated/<gen_id>/<file>` → auth check → serve file. 410 Gone se record scaduto.
+
+Anche gli asset richiedono API key: il Markdown non è pubblico.
+
+---
+
+## 7. Gestione errori
+
+### Errori di validazione (pre-LLM, nessuna registrazione)
+
+| Caso | Errore |
+|------|--------|
+| API key mancante/errata | HTTP 401 `invalid_api_key` |
+| `template_name` non esiste | `TemplateNotFound` |
+| Nome template invalido | `InvalidTemplateName` |
+| Frontmatter YAML malformato | `InvalidFrontmatter` (con dettagli Pydantic) |
+| `required_variables` mancanti | `MissingVariables: [lista]` |
+| Variabile con tipo sbagliato | `InvalidVariableType: <var> expected <type>` |
+| Immagine base64 non decodificabile | `InvalidImageEncoding: <var>` |
+| Mime image non supportato | `UnsupportedImageMime` |
+| Immagine > `MAX_IMAGE_SIZE_MB` | `ImageTooLarge` |
+
+### Errori di generazione (post-validazione)
+
+| Caso | Comportamento |
+|------|---------------|
+| I/O salvataggio asset | Rollback file già scritti, `AssetStorageError` |
+| OpenRouter timeout | Retry 3x backoff (1s, 2s, 4s), poi `LLMTimeout` |
+| OpenRouter 5xx | Retry 3x, poi `LLMUpstreamError` |
+| OpenRouter 401/403 (config server) | No retry, `LLMAuthError` |
+| OpenRouter 429 | Retry backoff lungo (5s, 10s, 20s), poi `LLMRateLimit` |
+| Risposta non parseable | `LLMInvalidResponse` |
+| Risposta vuota | `LLMEmptyResponse` |
+
+Ogni fallimento post-validazione → record `generations` con `success=0`. Asset efimeri non rimossi (scadranno col TTL).
+
+### Errori tool CRUD template
+
+| Caso | Errore |
+|------|--------|
+| Create su nome esistente | `TemplateAlreadyExists` |
+| Update/delete su nome inesistente | `TemplateNotFound` |
+| I/O filesystem | `TemplateStorageError` |
+
+### Errori serving asset HTTP
+
+| Caso | Codice |
+|------|--------|
+| Missing/invalid API key | 401 |
+| Path traversal | 400 |
+| `/assets/<template>/<file>` non trovato | 404 |
+| `/generated/<gen_id>/<file>`: record `ephemeral_assets` scaduto o `gen_id`/file assente | 410 Gone |
+
+Semantica: gli asset dei template sono persistenti, la loro assenza è 404. Gli asset generati sono effimeri: assenti = già esistiti o mai esistiti → 410 Gone in entrambi i casi (il client riconosce che è scaduto o invalido, non deve riprovare con path diverso).
+
+### Filosofia
+
+- Nessuna fallback silenziosa. Validazione strict → errore esplicito, niente chiamata LLM sprecata.
+- Retry solo su errori transitori upstream. Mai su 4xx.
+- Codici errore sono stringhe ben definite: il client sa cosa correggere.
+- Errori di config server (LLM auth, fs non scrivibile) → log ERROR, 500 con codice.
+
+---
+
+## 8. Strategia di test
+
+### Piramide
+
+```
+         ┌────────────┐
+         │   E2E (1-2)│   Container Docker reale
+         ├────────────┤
+         │ Integration│   FastMCP test client + mock OpenRouter
+         ├────────────┤
+         │    Unit    │   Moduli isolati
+         └────────────┘
+```
+
+### Unit
+
+- `test_template_store.py` — CRUD, nomi invalidi, frontmatter malformato, gestione asset dir.
+- `test_renderer.py` — validazione strict, shape image, rewrite asset paths, assemblaggio prompt, LLM mock per verifica modello scelto.
+- `test_auth.py` — header presente/assente, `/health` senza auth.
+- `test_generation_store.py` — insert, query, TTL cleanup con `expires_at` forzato.
+- `test_llm_client.py` — retry su 5xx/timeout/429, no retry su 4xx, parsing usage.
+
+### Integration
+
+- `test_mcp_tools.py` — tool call end-to-end via FastMCP test client, ogni tool happy path + error paths.
+- `test_http_routes.py` — assets auth, generated fresco vs scaduto (410), health sempre 200.
+- `test_document_generate_flow.py` — create template → generate → verifica record + file + asset URL 200.
+
+### E2E
+
+- `test_e2e_docker.py` — build container, compose up, client MCP reale, OpenRouter mockato via env var URL.
+
+### Copertura
+
+Target 85%+ sui moduli logici. `main.py` esente.
+
+### Cosa NON testiamo
+
+- OpenRouter reale (costi, flaky).
+- Qualità output LLM (responsabilità del modello).
+- Performance/load (inserire se nascerà bisogno).
+
+### Fixture principali
+
+- `tmp_data_dir` — DATA_DIR pulito per test.
+- `fake_template` — factory template valido.
+- `mock_openrouter` — respx con risposta + usage.
+- `client` — FastMCP test client autenticato.
+
+---
+
+## 9. Deploy e operatività
+
+### Container
+
+- Dockerfile basato su `python:3.11-slim`.
+- `uv` per installazione dipendenze.
+- Utente non-root.
+- Porta interna esposta: 8000.
+- Volume: `/data`.
+
+### docker-compose
+
+```yaml
+services:
+  docugen-mcp:
+    build: .
+    restart: unless-stopped
+    ports:
+      - "8000:8000"
+    env_file: .env
+    volumes:
+      - ./data:/data
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      interval: 30s
+```
+
+### TLS / reverse proxy
+
+Fuori scope del container. Esempi:
+- Traefik con label Docker.
+- Nginx con Let's Encrypt.
+- Caddy (TLS automatico).
+
+Il reverse proxy termina HTTPS e inoltra a `docugen-mcp:8000`. `PUBLIC_BASE_URL` nell'env var deve puntare al dominio esterno (`https://mcp.tuavps.com`).
+
+### Configurazione client MCP
+
+Claude Code:
+```bash
+claude mcp add --transport http docugen-mcp https://mcp.tuavps.com/mcp \
+  --header "Authorization: Bearer <api-key>"
+```
+
+Claude Desktop: entry in `claude_desktop_config.json` con URL + header.
+
+### Backup
+
+- Cartella `{DATA_DIR}/templates/` → rsync periodico o copia nel git.
+- `docugen_mcp.db` → dump SQLite regolare.
+- `{DATA_DIR}/generated/` → effimero, non critico.
+
+### Osservabilità
+
+- Log strutturati (JSON) su stdout. Tracciamento via docker logs.
+- Metriche dai record `generations`: spesa mensile, success rate, latenza media per modello. Query SQL ad-hoc o piccolo endpoint admin in fasi successive.
+
+---
+
+## 10. Stack tecnologico
+
+| Layer | Tecnologia |
+|-------|------------|
+| Runtime | Python 3.11+ |
+| Package manager | uv |
+| Validazione | Pydantic v2, Pydantic Settings |
+| MCP | `mcp` SDK (FastMCP) |
+| HTTP (sub-app) | FastAPI |
+| Client HTTP | httpx (async) |
+| Retry | httpx + wrapper custom (retry exponential backoff) |
+| DB | SQLite via aiosqlite |
+| Immagini | Pillow (validazione mime/dimensione) |
+| Test | pytest, pytest-asyncio, respx |
+| Deploy | Docker, docker-compose |
+| Reverse proxy | Nginx/Traefik/Caddy (fuori container) |
diff --git a/Docs/docugen-mcp/2026-04-21-implementation.md b/Docs/docugen-mcp/2026-04-21-implementation.md
new file mode 100644
index 0000000..375ec08
--- /dev/null
+++ b/Docs/docugen-mcp/2026-04-21-implementation.md
@@ -0,0 +1,3073 @@
+# DocuGen MCP — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build a standalone MCP server (`docugen-mcp`) that exposes 6 tools for template CRUD + document generation, using OpenRouter as LLM provider, deployed on Docker on an external VPS.
+
+**Architecture:** FastMCP as ASGI root (Streamable HTTP on `/mcp`) with a mounted FastAPI sub-app for static asset serving (`/assets/`, `/generated/`) and health. Filesystem storage for templates; SQLite for generation metrics and ephemeral asset TTL index. Single process, single container.
+
+**Tech Stack:** Python 3.11+, uv, Pydantic v2, Pydantic Settings, `mcp` SDK (FastMCP), FastAPI, httpx, aiosqlite, PyYAML, Pillow, pytest + pytest-asyncio + respx, Docker + docker-compose.
+
+**Reference spec:** `2026-04-21-docugen-mcp-design.md` (same directory).
+
+---
+
+## File Structure
+
+```
+docugen-mcp/
+├── src/
+│   └── docugen_mcp/
+│       ├── __init__.py
+│       ├── main.py                 # ASGI bootstrap (FastMCP + FastAPI mount)
+│       ├── config.py               # Pydantic Settings
+│       ├── models.py               # Shared Pydantic models
+│       ├── auth.py                 # API key middleware
+│       ├── template_store.py       # Filesystem CRUD templates
+│       ├── llm_client.py           # OpenRouter wrapper (async, retry)
+│       ├── generation_store.py     # SQLite: generations + ephemeral_assets
+│       ├── renderer.py             # Orchestrator: validate, prompt, call LLM
+│       ├── mcp_tools.py            # FastMCP tool definitions
+│       └── http_routes.py          # FastAPI sub-app (assets, generated, health)
+├── tests/
+│   ├── __init__.py
+│   ├── conftest.py                 # Fixtures
+│   ├── unit/
+│   │   ├── __init__.py
+│   │   ├── test_config.py
+│   │   ├── test_models.py
+│   │   ├── test_auth.py
+│   │   ├── test_template_store.py
+│   │   ├── test_llm_client.py
+│   │   ├── test_generation_store.py
+│   │   └── test_renderer.py
+│   └── integration/
+│       ├── __init__.py
+│       ├── test_mcp_tools.py
+│       ├── test_http_routes.py
+│       └── test_generate_flow.py
+├── .env.example
+├── .gitignore
+├── .python-version
+├── pyproject.toml
+├── Dockerfile
+├── docker-compose.yml
+└── README.md
+```
+
+---
+
+## Task 0: Bootstrap project
+
+**Files:**
+- Create: `docugen-mcp/.gitignore`
+- Create: `docugen-mcp/.python-version`
+- Create: `docugen-mcp/pyproject.toml`
+- Create: `docugen-mcp/README.md` (stub)
+- Create: `docugen-mcp/src/docugen_mcp/__init__.py`
+- Create: `docugen-mcp/tests/__init__.py`
+- Create: `docugen-mcp/tests/unit/__init__.py`
+- Create: `docugen-mcp/tests/integration/__init__.py`
+
+- [ ] **Step 1: Create directory structure**
+
+```bash
+mkdir -p docugen-mcp/src/docugen_mcp
+mkdir -p docugen-mcp/tests/unit
+mkdir -p docugen-mcp/tests/integration
+cd docugen-mcp
+git init
+```
+
+- [ ] **Step 2: Create `.python-version`**
+
+```
+3.11
+```
+
+- [ ] **Step 3: Create `.gitignore`**
+
+```
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.env
+data/
+!data/.gitkeep
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.db
+*.db-journal
+.DS_Store
+```
+
+- [ ] **Step 4: Create `pyproject.toml`**
+
+```toml
+[project]
+name = "docugen-mcp"
+version = "0.1.0"
+description = "MCP server for document generation from Markdown templates via OpenRouter"
+requires-python = ">=3.11"
+dependencies = [
+    "mcp>=1.2",
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.34",
+    "pydantic>=2.0",
+    "pydantic-settings>=2.0",
+    "httpx>=0.27",
+    "aiosqlite>=0.20",
+    "pyyaml>=6.0",
+    "pillow>=11.0",
+    "python-multipart>=0.0.9",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "respx>=0.21",
+    "pytest-cov>=5.0",
+]
+
+[project.scripts]
+docugen-mcp = "docugen_mcp.main:run"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["src/docugen_mcp"]
+omit = ["src/docugen_mcp/main.py"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/docugen_mcp"]
+```
+
+- [ ] **Step 5: Create stub files**
+
+`src/docugen_mcp/__init__.py`:
+```python
+__version__ = "0.1.0"
+```
+
+`tests/__init__.py`, `tests/unit/__init__.py`, `tests/integration/__init__.py`: empty files.
+
+`README.md`:
+```markdown
+# docugen-mcp
+
+MCP server for document generation from Markdown templates via OpenRouter.
+
+See design spec: `../2026-04-21-docugen-mcp-design.md`.
+
+## Setup
+
+```bash
+uv sync --all-extras
+cp .env.example .env  # fill in API_KEY, OPENROUTER_API_KEY, PUBLIC_BASE_URL
+uv run docugen-mcp
+```
+
+## Test
+
+```bash
+uv run pytest
+```
+```
+
+- [ ] **Step 6: Install dependencies and verify**
+
+```bash
+uv sync --all-extras
+```
+
+Expected: `.venv` created, `uv.lock` generated. No errors.
+
+- [ ] **Step 7: Initial commit**
+
+```bash
+git add .gitignore .python-version pyproject.toml uv.lock README.md src/ tests/
+git commit -m "chore: bootstrap docugen-mcp project"
+```
+
+---
+
+## Task 1: Config module (Pydantic Settings)
+
+**Files:**
+- Create: `src/docugen_mcp/config.py`
+- Create: `tests/unit/test_config.py`
+- Create: `.env.example`
+
+- [ ] **Step 1: Write failing test**
+
+`tests/unit/test_config.py`:
+```python
+import pytest
+from pydantic import ValidationError
+
+from docugen_mcp.config import Settings
+
+
+def test_settings_loads_from_env(monkeypatch, tmp_path):
+    monkeypatch.setenv("API_KEY", "test-api-key")
+    monkeypatch.setenv("OPENROUTER_API_KEY", "sk-or-test")
+    monkeypatch.setenv("PUBLIC_BASE_URL", "https://mcp.example.com")
+    monkeypatch.setenv("DATA_DIR", str(tmp_path))
+
+    settings = Settings()
+
+    assert settings.api_key == "test-api-key"
+    assert settings.openrouter_api_key == "sk-or-test"
+    assert settings.public_base_url == "https://mcp.example.com"
+    assert settings.data_dir == tmp_path
+    assert settings.llm_model_default == "anthropic/claude-sonnet-4"
+    assert settings.asset_ttl_days == 30
+    assert settings.max_image_size_mb == 10
+    assert settings.llm_timeout_seconds == 60
+    assert settings.openrouter_base_url == "https://openrouter.ai/api/v1"
+
+
+def test_settings_missing_required_fails(monkeypatch, tmp_path):
+    monkeypatch.delenv("API_KEY", raising=False)
+    monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
+    monkeypatch.delenv("PUBLIC_BASE_URL", raising=False)
+    monkeypatch.setenv("DATA_DIR", str(tmp_path))
+
+    with pytest.raises(ValidationError):
+        Settings()
+
+
+def test_public_base_url_strips_trailing_slash(monkeypatch, tmp_path):
+    monkeypatch.setenv("API_KEY", "k")
+    monkeypatch.setenv("OPENROUTER_API_KEY", "sk")
+    monkeypatch.setenv("PUBLIC_BASE_URL", "https://mcp.example.com/")
+    monkeypatch.setenv("DATA_DIR", str(tmp_path))
+
+    settings = Settings()
+
+    assert settings.public_base_url == "https://mcp.example.com"
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+```bash
+uv run pytest tests/unit/test_config.py -v
+```
+Expected: FAIL — `docugen_mcp.config` does not exist.
+
+- [ ] **Step 3: Implement config**
+
+`src/docugen_mcp/config.py`:
+```python
+from pathlib import Path
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8", extra="ignore")
+
+    api_key: str = Field(..., min_length=8)
+    openrouter_api_key: str = Field(..., min_length=8)
+    openrouter_base_url: str = "https://openrouter.ai/api/v1"
+    llm_model_default: str = "anthropic/claude-sonnet-4"
+    public_base_url: str = Field(...)
+    data_dir: Path = Path("/data")
+    asset_ttl_days: int = 30
+    max_image_size_mb: int = 10
+    llm_timeout_seconds: int = 60
+
+    @field_validator("public_base_url")
+    @classmethod
+    def strip_trailing_slash(cls, v: str) -> str:
+        return v.rstrip("/")
+```
+
+- [ ] **Step 4: Run tests to verify pass**
+
+```bash
+uv run pytest tests/unit/test_config.py -v
+```
+Expected: 3 PASSED.
+
+- [ ] **Step 5: Create `.env.example`**
+
+```
+# Authentication
+API_KEY=
+
+# OpenRouter
+OPENROUTER_API_KEY=
+OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
+LLM_MODEL_DEFAULT=anthropic/claude-sonnet-4
+
+# Public URL (used to build asset links in generated Markdown)
+PUBLIC_BASE_URL=https://mcp.example.com
+
+# Storage
+DATA_DIR=/data
+
+# Limits
+ASSET_TTL_DAYS=30
+MAX_IMAGE_SIZE_MB=10
+LLM_TIMEOUT_SECONDS=60
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/docugen_mcp/config.py tests/unit/test_config.py .env.example
+git commit -m "feat: add Settings config with env validation"
+```
+
+---
+
+## Task 2: Shared Pydantic models
+
+**Files:**
+- Create: `src/docugen_mcp/models.py`
+- Create: `tests/unit/test_models.py`
+
+- [ ] **Step 1: Write failing test**
+
+`tests/unit/test_models.py`:
+```python
+import pytest
+from pydantic import ValidationError
+
+from docugen_mcp.models import (
+    TemplateVariable,
+    TemplateFrontmatter,
+    ImageVariable,
+    GenerationResult,
+    TokenUsage,
+)
+
+
+def test_template_variable_string():
+    v = TemplateVariable(name="cliente", type="string")
+    assert v.name == "cliente"
+    assert v.type == "string"
+
+
+def test_template_variable_image():
+    v = TemplateVariable(name="foto", type="image")
+    assert v.type == "image"
+
+
+def test_template_variable_rejects_unknown_type():
+    with pytest.raises(ValidationError):
+        TemplateVariable(name="x", type="number")
+
+
+def test_template_variable_rejects_empty_name():
+    with pytest.raises(ValidationError):
+        TemplateVariable(name="", type="string")
+
+
+def test_frontmatter_minimal():
+    fm = TemplateFrontmatter(name="fattura", description="Fattura commerciale")
+    assert fm.name == "fattura"
+    assert fm.required_variables == []
+    assert fm.model is None
+    assert fm.instructions_hint is None
+
+
+def test_frontmatter_with_variables():
+    fm = TemplateFrontmatter(
+        name="fattura",
+        description="...",
+        model="anthropic/claude-sonnet-4",
+        required_variables=[
+            {"name": "cliente", "type": "string"},
+            {"name": "foto", "type": "image"},
+        ],
+        instructions_hint="tono formale",
+    )
+    assert len(fm.required_variables) == 2
+    assert fm.required_variables[1].type == "image"
+
+
+def test_frontmatter_name_slug_rules():
+    with pytest.raises(ValidationError):
+        TemplateFrontmatter(name="Fattura Commerciale", description="x")
+    with pytest.raises(ValidationError):
+        TemplateFrontmatter(name="../escape", description="x")
+    with pytest.raises(ValidationError):
+        TemplateFrontmatter(name="-starts-with-dash", description="x")
+
+
+def test_image_variable():
+    img = ImageVariable(kind="image", data_b64="aGVsbG8=", mime="image/png")
+    assert img.mime == "image/png"
+
+
+def test_image_variable_rejects_unsupported_mime():
+    with pytest.raises(ValidationError):
+        ImageVariable(kind="image", data_b64="aGVsbG8=", mime="image/bmp")
+
+
+def test_image_variable_rejects_wrong_kind():
+    with pytest.raises(ValidationError):
+        ImageVariable(kind="file", data_b64="aGVsbG8=", mime="image/png")
+
+
+def test_generation_result_shape():
+    result = GenerationResult(
+        generation_id="abc-123",
+        markdown="# hello",
+        model="anthropic/claude-sonnet-4",
+        tokens=TokenUsage(input=100, output=200),
+        cost_usd=0.01,
+        ephemeral_assets_urls=[],
+        ephemeral_expires_at=None,
+    )
+    assert result.generation_id == "abc-123"
+    assert result.tokens.input == 100
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+```bash
+uv run pytest tests/unit/test_models.py -v
+```
+Expected: FAIL — module does not exist.
+
+- [ ] **Step 3: Implement models**
+
+`src/docugen_mcp/models.py`:
+```python
+import re
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+
+_SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$")
+_SUPPORTED_MIMES = {"image/png", "image/jpeg", "image/webp"}
+
+
+class TemplateVariable(BaseModel):
+    name: str = Field(..., min_length=1)
+    type: Literal["string", "image"]
+
+
+class TemplateFrontmatter(BaseModel):
+    name: str
+    description: str = ""
+    model: str | None = None
+    required_variables: list[TemplateVariable] = Field(default_factory=list)
+    instructions_hint: str | None = None
+
+    @field_validator("name")
+    @classmethod
+    def validate_slug(cls, v: str) -> str:
+        if not _SLUG_RE.match(v):
+            raise ValueError(
+                f"invalid template name '{v}': must match {_SLUG_RE.pattern}"
+            )
+        return v
+
+
+class ImageVariable(BaseModel):
+    kind: Literal["image"]
+    data_b64: str
+    mime: str
+
+    @field_validator("mime")
+    @classmethod
+    def validate_mime(cls, v: str) -> str:
+        if v not in _SUPPORTED_MIMES:
+            raise ValueError(f"unsupported mime '{v}'; allowed: {sorted(_SUPPORTED_MIMES)}")
+        return v
+
+
+class TokenUsage(BaseModel):
+    input: int = 0
+    output: int = 0
+
+
+class GenerationResult(BaseModel):
+    generation_id: str
+    markdown: str
+    model: str
+    tokens: TokenUsage
+    cost_usd: float
+    ephemeral_assets_urls: list[str] = Field(default_factory=list)
+    ephemeral_expires_at: datetime | None = None
+
+
+class TemplateSummary(BaseModel):
+    name: str
+    description: str
+    updated_at: datetime
+
+
+class TemplateAsset(BaseModel):
+    filename: str
+    mime: str
+    size_bytes: int
+```
+
+- [ ] **Step 4: Run tests to verify pass**
+
+```bash
+uv run pytest tests/unit/test_models.py -v
+```
+Expected: 10 PASSED.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/docugen_mcp/models.py tests/unit/test_models.py
+git commit -m "feat: add shared Pydantic models"
+```
+
+---
+
+## Task 3: Auth middleware
+
+**Files:**
+- Create: `src/docugen_mcp/auth.py`
+- Create: `tests/unit/test_auth.py`
+
+- [ ] **Step 1: Write failing test**
+
+`tests/unit/test_auth.py`:
+```python
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from docugen_mcp.auth import ApiKeyAuthMiddleware
+
+
+@pytest.fixture
+def app_with_auth():
+    app = FastAPI()
+    app.add_middleware(ApiKeyAuthMiddleware, api_key="secret", exempt_paths={"/health"})
+
+    @app.get("/protected")
+    async def protected():
+        return {"ok": True}
+
+    @app.get("/health")
+    async def health():
+        return {"status": "ok"}
+
+    return app
+
+
+def test_protected_without_header_returns_401(app_with_auth):
+    client = TestClient(app_with_auth)
+    response = client.get("/protected")
+    assert response.status_code == 401
+    assert response.json() == {"error": "invalid_api_key"}
+
+
+def test_protected_with_wrong_key_returns_401(app_with_auth):
+    client = TestClient(app_with_auth)
+    response = client.get("/protected", headers={"Authorization": "Bearer wrong"})
+    assert response.status_code == 401
+
+
+def test_protected_with_correct_key_passes(app_with_auth):
+    client = TestClient(app_with_auth)
+    response = client.get("/protected", headers={"Authorization": "Bearer secret"})
+    assert response.status_code == 200
+    assert response.json() == {"ok": True}
+
+
+def test_health_bypasses_auth(app_with_auth):
+    client = TestClient(app_with_auth)
+    response = client.get("/health")
+    assert response.status_code == 200
+
+
+def test_malformed_auth_header_returns_401(app_with_auth):
+    client = TestClient(app_with_auth)
+    response = client.get("/protected", headers={"Authorization": "secret"})
+    assert response.status_code == 401
+    response = client.get("/protected", headers={"Authorization": "Basic secret"})
+    assert response.status_code == 401
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+```bash
+uv run pytest tests/unit/test_auth.py -v
+```
+Expected: FAIL — `docugen_mcp.auth` does not exist.
+
+- [ ] **Step 3: Implement auth**
+
+`src/docugen_mcp/auth.py`:
+```python
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.types import ASGIApp
+
+
+class ApiKeyAuthMiddleware(BaseHTTPMiddleware):
+    def __init__(
+        self,
+        app: ASGIApp,
+        api_key: str,
+        exempt_paths: set[str] | None = None,
+    ) -> None:
+        super().__init__(app)
+        self.api_key = api_key
+        self.exempt_paths = exempt_paths or set()
+
+    async def dispatch(self, request: Request, call_next):
+        if request.url.path in self.exempt_paths:
+            return await call_next(request)
+
+        header = request.headers.get("Authorization", "")
+        if not header.startswith("Bearer "):
+            return JSONResponse(
+                status_code=401, content={"error": "invalid_api_key"}
+            )
+
+        provided = header.removeprefix("Bearer ").strip()
+        if provided != self.api_key:
+            return JSONResponse(
+                status_code=401, content={"error": "invalid_api_key"}
+            )
+
+        return await call_next(request)
+```
+
+- [ ] **Step 4: Run tests to verify pass**
+
+```bash
+uv run pytest tests/unit/test_auth.py -v
+```
+Expected: 5 PASSED.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/docugen_mcp/auth.py tests/unit/test_auth.py
+git commit -m "feat: add API key bearer auth middleware"
+```
+
+---
+
+## Task 4: Template store (filesystem CRUD)
+
+**Files:**
+- Create: `src/docugen_mcp/template_store.py`
+- Create: `tests/unit/test_template_store.py`
+
+- [ ] **Step 1: Write failing test**
+
+`tests/unit/test_template_store.py`:
+```python
+import base64
+import pytest
+
+from docugen_mcp.template_store import (
+    TemplateStore,
+    TemplateNotFound,
+    TemplateAlreadyExists,
+    InvalidFrontmatter,
+)
+from docugen_mcp.models import TemplateFrontmatter
+
+
+@pytest.fixture
+def store(tmp_path):
+    return TemplateStore(base_dir=tmp_path)
+
+
+def _fm(name="fattura"):
+    return TemplateFrontmatter(
+        name=name,
+        description="Fattura commerciale",
+        required_variables=[{"name": "cliente", "type": "string"}],
+    )
+
+
+async def test_create_and_get(store):
+    fm = _fm()
+    await store.create(name="fattura", frontmatter=fm, body="# Body {{cliente}}")
+    got = await store.get("fattura")
+    assert got.frontmatter.name == "fattura"
+    assert "# Body {{cliente}}" in got.body
+
+
+async def test_create_duplicate_raises(store):
+    fm = _fm()
+    await store.create(name="fattura", frontmatter=fm, body="body")
+    with pytest.raises(TemplateAlreadyExists):
+        await store.create(name="fattura", frontmatter=fm, body="body")
+
+
+async def test_get_missing_raises(store):
+    with pytest.raises(TemplateNotFound):
+        await store.get("nope")
+
+
+async def test_list_returns_summaries(store):
+    await store.create(name="a", frontmatter=_fm("a"), body="b")
+    await store.create(name="b", frontmatter=_fm("b"), body="b")
+    result = await store.list()
+    names = sorted(t.name for t in result)
+    assert names == ["a", "b"]
+
+
+async def test_update_overwrites(store):
+    await store.create(name="f", frontmatter=_fm("f"), body="old")
+    new_fm = TemplateFrontmatter(name="f", description="new description")
+    await store.update(name="f", frontmatter=new_fm, body="new body")
+    got = await store.get("f")
+    assert got.body == "new body"
+    assert got.frontmatter.description == "new description"
+
+
+async def test_update_missing_raises(store):
+    with pytest.raises(TemplateNotFound):
+        await store.update(name="nope", frontmatter=_fm("nope"), body="x")
+
+
+async def test_delete_removes(store):
+    await store.create(name="f", frontmatter=_fm("f"), body="b")
+    await store.delete("f")
+    with pytest.raises(TemplateNotFound):
+        await store.get("f")
+
+
+async def test_delete_missing_raises(store):
+    with pytest.raises(TemplateNotFound):
+        await store.delete("nope")
+
+
+async def test_assets_are_saved_and_listed(store):
+    png_bytes = b"\x89PNG\r\n\x1a\n"
+    assets = [
+        {"filename": "logo.png", "data_b64": base64.b64encode(png_bytes).decode(), "mime": "image/png"}
+    ]
+    await store.create(name="f", frontmatter=_fm("f"), body="b", assets=assets)
+    got = await store.get("f")
+    asset_names = [a.filename for a in got.assets]
+    assert "logo.png" in asset_names
+    content = await store.read_asset("f", "logo.png")
+    assert content == png_bytes
+
+
+async def test_asset_filename_rejects_path_traversal(store):
+    assets = [{"filename": "../evil.png", "data_b64": "aGk=", "mime": "image/png"}]
+    with pytest.raises(ValueError):
+        await store.create(name="f", frontmatter=_fm("f"), body="b", assets=assets)
+
+
+async def test_frontmatter_parsing_rejects_malformed_yaml(store, tmp_path):
+    template_dir = tmp_path / "broken"
+    template_dir.mkdir()
+    (template_dir / "template.md").write_text("---\nname: :::broken\n---\nbody")
+    with pytest.raises(InvalidFrontmatter):
+        await store.get("broken")
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+```bash
+uv run pytest tests/unit/test_template_store.py -v
+```
+Expected: FAIL — module does not exist.
+
+- [ ] **Step 3: Implement template store**
+
+`src/docugen_mcp/template_store.py`:
+```python
+import base64
+import re
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+import aiofiles
+import yaml
+from pydantic import ValidationError
+
+from docugen_mcp.models import TemplateFrontmatter, TemplateSummary, TemplateAsset
+
+
+_SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$")
+_ASSET_FILENAME_RE = re.compile(r"^[A-Za-z0-9._-]+$")
+_FRONTMATTER_DELIM = "---"
+
+
+class TemplateNotFound(Exception):
+    pass
+
+
+class TemplateAlreadyExists(Exception):
+    pass
+
+
+class InvalidFrontmatter(Exception):
+    pass
+
+
+class InvalidTemplateName(ValueError):
+    pass
+
+
+@dataclass
+class LoadedTemplate:
+    frontmatter: TemplateFrontmatter
+    body: str
+    assets: list[TemplateAsset]
+    updated_at: datetime
+
+
+class TemplateStore:
+    def __init__(self, base_dir: Path) -> None:
+        self.base_dir = Path(base_dir)
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+
+    # ---- public API ----
+
+    async def create(
+        self,
+        name: str,
+        frontmatter: TemplateFrontmatter,
+        body: str,
+        assets: list[dict] | None = None,
+    ) -> None:
+        self._validate_name(name)
+        tdir = self.base_dir / name
+        if tdir.exists():
+            raise TemplateAlreadyExists(name)
+        tdir.mkdir(parents=True)
+        (tdir / "assets").mkdir()
+        await self._write_template_file(tdir, frontmatter, body)
+        if assets:
+            await self._write_assets(tdir, assets)
+
+    async def update(
+        self,
+        name: str,
+        frontmatter: TemplateFrontmatter,
+        body: str,
+        assets: list[dict] | None = None,
+    ) -> None:
+        self._validate_name(name)
+        tdir = self.base_dir / name
+        if not tdir.exists():
+            raise TemplateNotFound(name)
+        await self._write_template_file(tdir, frontmatter, body)
+        if assets is not None:
+            # Replace the assets dir entirely
+            assets_dir = tdir / "assets"
+            for f in assets_dir.iterdir():
+                f.unlink()
+            await self._write_assets(tdir, assets)
+
+    async def delete(self, name: str) -> None:
+        self._validate_name(name)
+        tdir = self.base_dir / name
+        if not tdir.exists():
+            raise TemplateNotFound(name)
+        for f in (tdir / "assets").iterdir():
+            f.unlink()
+        (tdir / "assets").rmdir()
+        (tdir / "template.md").unlink()
+        tdir.rmdir()
+
+    async def get(self, name: str) -> LoadedTemplate:
+        self._validate_name(name)
+        tdir = self.base_dir / name
+        tpath = tdir / "template.md"
+        if not tpath.exists():
+            raise TemplateNotFound(name)
+        frontmatter, body = await self._read_template_file(tpath)
+        assets = self._list_assets(tdir)
+        stat = tpath.stat()
+        updated_at = datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc)
+        return LoadedTemplate(frontmatter=frontmatter, body=body, assets=assets, updated_at=updated_at)
+
+    async def list(self) -> list[TemplateSummary]:
+        summaries = []
+        for tdir in sorted(self.base_dir.iterdir()):
+            if not tdir.is_dir():
+                continue
+            tpath = tdir / "template.md"
+            if not tpath.exists():
+                continue
+            try:
+                frontmatter, _ = await self._read_template_file(tpath)
+            except InvalidFrontmatter:
+                continue
+            stat = tpath.stat()
+            summaries.append(
+                TemplateSummary(
+                    name=frontmatter.name,
+                    description=frontmatter.description,
+                    updated_at=datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc),
+                )
+            )
+        return summaries
+
+    async def read_asset(self, template_name: str, filename: str) -> bytes:
+        self._validate_name(template_name)
+        self._validate_asset_filename(filename)
+        path = self.base_dir / template_name / "assets" / filename
+        if not path.exists():
+            raise FileNotFoundError(filename)
+        async with aiofiles.open(path, "rb") as f:
+            return await f.read()
+
+    def asset_path(self, template_name: str, filename: str) -> Path:
+        self._validate_name(template_name)
+        self._validate_asset_filename(filename)
+        return self.base_dir / template_name / "assets" / filename
+
+    # ---- helpers ----
+
+    def _validate_name(self, name: str) -> None:
+        if not _SLUG_RE.match(name):
+            raise InvalidTemplateName(name)
+
+    def _validate_asset_filename(self, filename: str) -> None:
+        if not _ASSET_FILENAME_RE.match(filename):
+            raise ValueError(f"invalid asset filename: {filename!r}")
+
+    async def _write_template_file(self, tdir: Path, frontmatter: TemplateFrontmatter, body: str) -> None:
+        yaml_text = yaml.safe_dump(frontmatter.model_dump(exclude_none=True), sort_keys=False)
+        content = f"{_FRONTMATTER_DELIM}\n{yaml_text}{_FRONTMATTER_DELIM}\n{body}"
+        async with aiofiles.open(tdir / "template.md", "w") as f:
+            await f.write(content)
+
+    async def _read_template_file(self, path: Path) -> tuple[TemplateFrontmatter, str]:
+        async with aiofiles.open(path, "r") as f:
+            raw = await f.read()
+        if not raw.startswith(_FRONTMATTER_DELIM):
+            raise InvalidFrontmatter("missing opening '---'")
+        parts = raw.split(_FRONTMATTER_DELIM, 2)
+        if len(parts) < 3:
+            raise InvalidFrontmatter("missing closing '---'")
+        yaml_text = parts[1]
+        body = parts[2].lstrip("\n")
+        try:
+            data = yaml.safe_load(yaml_text) or {}
+            frontmatter = TemplateFrontmatter(**data)
+        except (yaml.YAMLError, ValidationError) as exc:
+            raise InvalidFrontmatter(str(exc)) from exc
+        return frontmatter, body
+
+    async def _write_assets(self, tdir: Path, assets: list[dict]) -> None:
+        for asset in assets:
+            filename = asset["filename"]
+            self._validate_asset_filename(filename)
+            data = base64.b64decode(asset["data_b64"])
+            async with aiofiles.open(tdir / "assets" / filename, "wb") as f:
+                await f.write(data)
+
+    def _list_assets(self, tdir: Path) -> list[TemplateAsset]:
+        assets_dir = tdir / "assets"
+        if not assets_dir.exists():
+            return []
+        out = []
+        for f in sorted(assets_dir.iterdir()):
+            if not f.is_file():
+                continue
+            out.append(
+                TemplateAsset(
+                    filename=f.name,
+                    mime=_guess_mime(f.name),
+                    size_bytes=f.stat().st_size,
+                )
+            )
+        return out
+
+
+def _guess_mime(filename: str) -> str:
+    ext = filename.rsplit(".", 1)[-1].lower() if "." in filename else ""
+    return {
+        "png": "image/png",
+        "jpg": "image/jpeg",
+        "jpeg": "image/jpeg",
+        "webp": "image/webp",
+    }.get(ext, "application/octet-stream")
+```
+
+- [ ] **Step 4: Add `aiofiles` to dependencies**
+
+```bash
+uv add aiofiles
+```
+
+- [ ] **Step 5: Run tests to verify pass**
+
+```bash
+uv run pytest tests/unit/test_template_store.py -v
+```
+Expected: 10 PASSED.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/docugen_mcp/template_store.py tests/unit/test_template_store.py pyproject.toml uv.lock
+git commit -m "feat: add TemplateStore with filesystem CRUD and asset handling"
+```
+
+---
+
+## Task 5: LLM client (OpenRouter wrapper)
+
+**Files:**
+- Create: `src/docugen_mcp/llm_client.py`
+- Create: `tests/unit/test_llm_client.py`
+
+- [ ] **Step 1: Write failing test**
+
+`tests/unit/test_llm_client.py`:
+```python
+import httpx
+import pytest
+import respx
+
+from docugen_mcp.llm_client import (
+    OpenRouterClient,
+    LLMTimeout,
+    LLMUpstreamError,
+    LLMAuthError,
+    LLMRateLimit,
+    LLMInvalidResponse,
+    LLMEmptyResponse,
+)
+
+
+def _success_body(text: str = "output text") -> dict:
+    return {
+        "id": "gen-1",
+        "choices": [{"message": {"role": "assistant", "content": text}}],
+        "model": "anthropic/claude-sonnet-4",
+        "usage": {"prompt_tokens": 100, "completion_tokens": 200, "total_cost": 0.01},
+    }
+
+
+@respx.mock
+async def test_chat_success():
+    respx.post("https://openrouter.ai/api/v1/chat/completions").mock(
+        return_value=httpx.Response(200, json=_success_body("hello"))
+    )
+    client = OpenRouterClient(api_key="sk", base_url="https://openrouter.ai/api/v1", timeout=5)
+    resp = await client.chat(
+        model="anthropic/claude-sonnet-4",
+        system="sys",
+        user="user",
+    )
+    assert resp.text == "hello"
+    assert resp.tokens_in == 100
+    assert resp.tokens_out == 200
+    assert resp.cost_usd == 0.01
+    assert resp.model == "anthropic/claude-sonnet-4"
+
+
+@respx.mock
+async def test_chat_retries_on_5xx():
+    route = respx.post("https://openrouter.ai/api/v1/chat/completions").mock(
+        side_effect=[
+            httpx.Response(503),
+            httpx.Response(502),
+            httpx.Response(200, json=_success_body()),
+        ]
+    )
+    client = OpenRouterClient(api_key="sk", base_url="https://openrouter.ai/api/v1", timeout=5, retry_base_delay=0)
+    resp = await client.chat(model="m", system="s", user="u")
+    assert resp.text == "output text"
+    assert route.call_count == 3
+
+
+@respx.mock
+async def test_chat_exhausts_retries_5xx():
+    respx.post("https://openrouter.ai/api/v1/chat/completions").mock(
+        return_value=httpx.Response(500)
+    )
+    client = OpenRouterClient(api_key="sk", base_url="https://openrouter.ai/api/v1", timeout=5, retry_base_delay=0)
+    with pytest.raises(LLMUpstreamError):
+        await client.chat(model="m", system="s", user="u")
+
+
+@respx.mock
+async def test_chat_retries_on_429():
+    route = respx.post("https://openrouter.ai/api/v1/chat/completions").mock(
+        side_effect=[
+            httpx.Response(429),
+            httpx.Response(200, json=_success_body()),
+        ]
+    )
+    client = OpenRouterClient(api_key="sk", base_url="https://openrouter.ai/api/v1", timeout=5, retry_base_delay=0)
+    resp = await client.chat(model="m", system="s", user="u")
+    assert route.call_count == 2
+
+
+@respx.mock
+async def test_chat_exhausts_retries_429():
+    respx.post("https://openrouter.ai/api/v1/chat/completions").mock(
+        return_value=httpx.Response(429)
+    )
+    client = OpenRouterClient(api_key="sk", base_url="https://openrouter.ai/api/v1", timeout=5, retry_base_delay=0)
+    with pytest.raises(LLMRateLimit):
+        await client.chat(model="m", system="s", user="u")
+
+
+@respx.mock
+async def test_chat_no_retry_on_401():
+    respx.post("https://openrouter.ai/api/v1/chat/completions").mock(
+        return_value=httpx.Response(401)
+    )
+    client = OpenRouterClient(api_key="sk", base_url="https://openrouter.ai/api/v1", timeout=5, retry_base_delay=0)
+    with pytest.raises(LLMAuthError):
+        await client.chat(model="m", system="s", user="u")
+
+
+@respx.mock
+async def test_chat_timeout():
+    respx.post("https://openrouter.ai/api/v1/chat/completions").mock(
+        side_effect=httpx.ReadTimeout("timeout")
+    )
+    client = OpenRouterClient(api_key="sk", base_url="https://openrouter.ai/api/v1", timeout=1, retry_base_delay=0)
+    with pytest.raises(LLMTimeout):
+        await client.chat(model="m", system="s", user="u")
+
+
+@respx.mock
+async def test_chat_invalid_response_shape():
+    respx.post("https://openrouter.ai/api/v1/chat/completions").mock(
+        return_value=httpx.Response(200, json={"no": "choices"})
+    )
+    client = OpenRouterClient(api_key="sk", base_url="https://openrouter.ai/api/v1", timeout=5, retry_base_delay=0)
+    with pytest.raises(LLMInvalidResponse):
+        await client.chat(model="m", system="s", user="u")
+
+
+@respx.mock
+async def test_chat_empty_content():
+    respx.post("https://openrouter.ai/api/v1/chat/completions").mock(
+        return_value=httpx.Response(200, json=_success_body(text=""))
+    )
+    client = OpenRouterClient(api_key="sk", base_url="https://openrouter.ai/api/v1", timeout=5, retry_base_delay=0)
+    with pytest.raises(LLMEmptyResponse):
+        await client.chat(model="m", system="s", user="u")
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+```bash
+uv run pytest tests/unit/test_llm_client.py -v
+```
+Expected: FAIL — module does not exist.
+
+- [ ] **Step 3: Implement LLM client**
+
+`src/docugen_mcp/llm_client.py`:
+```python
+import asyncio
+from dataclasses import dataclass
+from time import perf_counter
+
+import httpx
+
+
+class LLMError(Exception):
+    pass
+
+
+class LLMTimeout(LLMError):
+    pass
+
+
+class LLMUpstreamError(LLMError):
+    pass
+
+
+class LLMAuthError(LLMError):
+    pass
+
+
+class LLMRateLimit(LLMError):
+    pass
+
+
+class LLMInvalidResponse(LLMError):
+    pass
+
+
+class LLMEmptyResponse(LLMError):
+    pass
+
+
+@dataclass
+class LLMResponse:
+    text: str
+    model: str
+    tokens_in: int
+    tokens_out: int
+    cost_usd: float
+    latency_ms: int
+
+
+class OpenRouterClient:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        timeout: float = 60,
+        max_retries: int = 3,
+        retry_base_delay: float = 1.0,
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.retry_base_delay = retry_base_delay
+
+    async def chat(self, model: str, system: str, user: str) -> LLMResponse:
+        payload = {
+            "model": model,
+            "messages": [
+                {"role": "system", "content": system},
+                {"role": "user", "content": user},
+            ],
+        }
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+        start = perf_counter()
+        last_transient_error: Exception | None = None
+
+        for attempt in range(self.max_retries):
+            try:
+                async with httpx.AsyncClient(timeout=self.timeout) as client:
+                    response = await client.post(
+                        f"{self.base_url}/chat/completions",
+                        headers=headers,
+                        json=payload,
+                    )
+            except (httpx.ReadTimeout, httpx.ConnectTimeout) as exc:
+                last_transient_error = exc
+                if attempt == self.max_retries - 1:
+                    raise LLMTimeout(str(exc)) from exc
+                await self._sleep_backoff(attempt, rate_limit=False)
+                continue
+
+            status = response.status_code
+            if status == 200:
+                return self._parse_success(response, start)
+            if status in (401, 403):
+                raise LLMAuthError(f"status {status}: {response.text[:200]}")
+            if status == 429:
+                if attempt == self.max_retries - 1:
+                    raise LLMRateLimit(response.text[:200])
+                await self._sleep_backoff(attempt, rate_limit=True)
+                continue
+            if 500 <= status < 600:
+                if attempt == self.max_retries - 1:
+                    raise LLMUpstreamError(f"status {status}: {response.text[:200]}")
+                await self._sleep_backoff(attempt, rate_limit=False)
+                continue
+            raise LLMUpstreamError(f"unexpected status {status}: {response.text[:200]}")
+
+        raise LLMUpstreamError(f"retries exhausted: {last_transient_error}")
+
+    async def _sleep_backoff(self, attempt: int, rate_limit: bool) -> None:
+        multiplier = 5 if rate_limit else 1
+        delay = self.retry_base_delay * multiplier * (2**attempt)
+        if delay > 0:
+            await asyncio.sleep(delay)
+
+    def _parse_success(self, response: httpx.Response, start: float) -> LLMResponse:
+        try:
+            data = response.json()
+            choice = data["choices"][0]
+            text = choice["message"]["content"]
+            model = data.get("model", "unknown")
+            usage = data.get("usage", {})
+        except (KeyError, IndexError, ValueError) as exc:
+            raise LLMInvalidResponse(str(exc)) from exc
+
+        if not text:
+            raise LLMEmptyResponse("LLM returned empty content")
+
+        latency_ms = int((perf_counter() - start) * 1000)
+        return LLMResponse(
+            text=text,
+            model=model,
+            tokens_in=int(usage.get("prompt_tokens", 0)),
+            tokens_out=int(usage.get("completion_tokens", 0)),
+            cost_usd=float(usage.get("total_cost", 0.0)),
+            latency_ms=latency_ms,
+        )
+```
+
+- [ ] **Step 4: Run tests to verify pass**
+
+```bash
+uv run pytest tests/unit/test_llm_client.py -v
+```
+Expected: 9 PASSED.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/docugen_mcp/llm_client.py tests/unit/test_llm_client.py
+git commit -m "feat: add OpenRouter async client with retry/backoff"
+```
+
+---
+
+## Task 6: Generation store (SQLite)
+
+**Files:**
+- Create: `src/docugen_mcp/generation_store.py`
+- Create: `tests/unit/test_generation_store.py`
+
+- [ ] **Step 1: Write failing test**
+
+`tests/unit/test_generation_store.py`:
+```python
+import pytest
+
+from docugen_mcp.generation_store import GenerationStore, GenerationRecord, EphemeralAssetRecord
+
+
+@pytest.fixture
+async def store(tmp_path):
+    s = GenerationStore(db_path=tmp_path / "gen.db", generated_dir=tmp_path / "generated")
+    await s.init()
+    return s
+
+
+async def test_record_success_generation(store):
+    await store.record_generation(
+        GenerationRecord(
+            id="g-1",
+            template_name="fattura",
+            model="m",
+            tokens_in=100,
+            tokens_out=200,
+            cost_usd=0.01,
+            success=True,
+            error_msg=None,
+        )
+    )
+    stats = await store.get_stats()
+    assert stats["total"] == 1
+    assert stats["success"] == 1
+    assert stats["failed"] == 0
+
+
+async def test_record_failed_generation(store):
+    await store.record_generation(
+        GenerationRecord(
+            id="g-2",
+            template_name="fattura",
+            model="m",
+            tokens_in=0,
+            tokens_out=0,
+            cost_usd=0.0,
+            success=False,
+            error_msg="LLMTimeout",
+        )
+    )
+    stats = await store.get_stats()
+    assert stats["failed"] == 1
+
+
+async def test_register_ephemeral_asset(store, tmp_path):
+    asset_file = tmp_path / "generated" / "g-1" / "foto.png"
+    asset_file.parent.mkdir(parents=True)
+    asset_file.write_bytes(b"png-bytes")
+
+    await store.register_ephemeral_asset(
+        EphemeralAssetRecord(
+            generation_id="g-1",
+            var_name="foto",
+            file_path=str(asset_file),
+            mime="image/png",
+            ttl_days=30,
+        )
+    )
+    asset = await store.get_ephemeral_asset("g-1", "foto.png")
+    assert asset is not None
+    assert asset.mime == "image/png"
+
+
+async def test_get_ephemeral_asset_returns_none_if_missing(store):
+    asset = await store.get_ephemeral_asset("nope", "foo.png")
+    assert asset is None
+
+
+async def test_cleanup_expired_removes_records_and_files(store, tmp_path):
+    asset_file = tmp_path / "generated" / "g-old" / "foto.png"
+    asset_file.parent.mkdir(parents=True)
+    asset_file.write_bytes(b"bytes")
+
+    await store.register_ephemeral_asset(
+        EphemeralAssetRecord(
+            generation_id="g-old",
+            var_name="foto",
+            file_path=str(asset_file),
+            mime="image/png",
+            ttl_days=-1,  # already expired
+        )
+    )
+    removed = await store.cleanup_expired()
+    assert removed == 1
+    assert not asset_file.exists()
+    assert await store.get_ephemeral_asset("g-old", "foto.png") is None
+
+
+async def test_ephemeral_asset_expired_flag(store, tmp_path):
+    f = tmp_path / "generated" / "g-e" / "img.png"
+    f.parent.mkdir(parents=True)
+    f.write_bytes(b"x")
+
+    await store.register_ephemeral_asset(
+        EphemeralAssetRecord(
+            generation_id="g-e",
+            var_name="img",
+            file_path=str(f),
+            mime="image/png",
+            ttl_days=-1,
+        )
+    )
+    # File still on disk but record expired
+    asset = await store.get_ephemeral_asset("g-e", "img.png")
+    assert asset is not None
+    assert asset.is_expired is True
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+```bash
+uv run pytest tests/unit/test_generation_store.py -v
+```
+Expected: FAIL.
+
+- [ ] **Step 3: Implement generation store**
+
+`src/docugen_mcp/generation_store.py`:
+```python
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+import aiosqlite
+
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS generations (
+    id TEXT PRIMARY KEY,
+    timestamp INTEGER NOT NULL,
+    template_name TEXT NOT NULL,
+    model TEXT NOT NULL,
+    tokens_in INTEGER NOT NULL,
+    tokens_out INTEGER NOT NULL,
+    cost_usd REAL NOT NULL,
+    success INTEGER NOT NULL,
+    error_msg TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_generations_timestamp ON generations(timestamp);
+
+CREATE TABLE IF NOT EXISTS ephemeral_assets (
+    generation_id TEXT NOT NULL,
+    var_name TEXT NOT NULL,
+    file_path TEXT NOT NULL,
+    mime TEXT NOT NULL,
+    created_at INTEGER NOT NULL,
+    expires_at INTEGER NOT NULL,
+    PRIMARY KEY (generation_id, var_name)
+);
+CREATE INDEX IF NOT EXISTS idx_assets_expires ON ephemeral_assets(expires_at);
+"""
+
+
+@dataclass
+class GenerationRecord:
+    id: str
+    template_name: str
+    model: str
+    tokens_in: int
+    tokens_out: int
+    cost_usd: float
+    success: bool
+    error_msg: str | None
+
+
+@dataclass
+class EphemeralAssetRecord:
+    generation_id: str
+    var_name: str
+    file_path: str
+    mime: str
+    ttl_days: int
+
+
+@dataclass
+class EphemeralAssetInfo:
+    generation_id: str
+    var_name: str
+    file_path: str
+    mime: str
+    created_at: datetime
+    expires_at: datetime
+    is_expired: bool
+
+
+def _now_ms() -> int:
+    return int(datetime.now(tz=timezone.utc).timestamp() * 1000)
+
+
+class GenerationStore:
+    def __init__(self, db_path: Path, generated_dir: Path) -> None:
+        self.db_path = Path(db_path)
+        self.generated_dir = Path(generated_dir)
+        self.generated_dir.mkdir(parents=True, exist_ok=True)
+
+    async def init(self) -> None:
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.executescript(_SCHEMA)
+            await db.commit()
+
+    async def record_generation(self, record: GenerationRecord) -> None:
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute(
+                """
+                INSERT INTO generations
+                  (id, timestamp, template_name, model, tokens_in, tokens_out, cost_usd, success, error_msg)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    record.id,
+                    _now_ms(),
+                    record.template_name,
+                    record.model,
+                    record.tokens_in,
+                    record.tokens_out,
+                    record.cost_usd,
+                    1 if record.success else 0,
+                    record.error_msg,
+                ),
+            )
+            await db.commit()
+
+    async def register_ephemeral_asset(self, record: EphemeralAssetRecord) -> None:
+        now = _now_ms()
+        expires = now + int(record.ttl_days * 24 * 3600 * 1000)
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute(
+                """
+                INSERT OR REPLACE INTO ephemeral_assets
+                  (generation_id, var_name, file_path, mime, created_at, expires_at)
+                VALUES (?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    record.generation_id,
+                    record.var_name,
+                    record.file_path,
+                    record.mime,
+                    now,
+                    expires,
+                ),
+            )
+            await db.commit()
+
+    async def get_ephemeral_asset(self, generation_id: str, filename: str) -> EphemeralAssetInfo | None:
+        async with aiosqlite.connect(self.db_path) as db:
+            cursor = await db.execute(
+                """
+                SELECT generation_id, var_name, file_path, mime, created_at, expires_at
+                FROM ephemeral_assets
+                WHERE generation_id = ?
+                """,
+                (generation_id,),
+            )
+            rows = await cursor.fetchall()
+        for row in rows:
+            path = Path(row[2])
+            if path.name == filename:
+                created_at = datetime.fromtimestamp(row[4] / 1000, tz=timezone.utc)
+                expires_at = datetime.fromtimestamp(row[5] / 1000, tz=timezone.utc)
+                return EphemeralAssetInfo(
+                    generation_id=row[0],
+                    var_name=row[1],
+                    file_path=row[2],
+                    mime=row[3],
+                    created_at=created_at,
+                    expires_at=expires_at,
+                    is_expired=expires_at < datetime.now(tz=timezone.utc),
+                )
+        return None
+
+    async def cleanup_expired(self) -> int:
+        now = _now_ms()
+        async with aiosqlite.connect(self.db_path) as db:
+            cursor = await db.execute(
+                "SELECT generation_id, file_path FROM ephemeral_assets WHERE expires_at < ?",
+                (now,),
+            )
+            rows = await cursor.fetchall()
+            count = 0
+            for _, fpath in rows:
+                try:
+                    Path(fpath).unlink(missing_ok=True)
+                except OSError:
+                    pass
+                count += 1
+            # Remove now-empty generation dirs
+            for gen_id, _ in rows:
+                gdir = self.generated_dir / gen_id
+                if gdir.exists() and not any(gdir.iterdir()):
+                    gdir.rmdir()
+            await db.execute(
+                "DELETE FROM ephemeral_assets WHERE expires_at < ?",
+                (now,),
+            )
+            await db.commit()
+        return count
+
+    async def get_stats(self) -> dict:
+        async with aiosqlite.connect(self.db_path) as db:
+            cur = await db.execute(
+                "SELECT COUNT(*), SUM(success), SUM(cost_usd) FROM generations"
+            )
+            total, success, cost = await cur.fetchone()
+        return {
+            "total": total or 0,
+            "success": success or 0,
+            "failed": (total or 0) - (success or 0),
+            "total_cost_usd": float(cost or 0),
+        }
+```
+
+- [ ] **Step 4: Run tests to verify pass**
+
+```bash
+uv run pytest tests/unit/test_generation_store.py -v
+```
+Expected: 6 PASSED.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/docugen_mcp/generation_store.py tests/unit/test_generation_store.py
+git commit -m "feat: add GenerationStore (SQLite) with TTL cleanup"
+```
+
+---
+
+## Task 7: Renderer (orchestrator)
+
+**Files:**
+- Create: `src/docugen_mcp/renderer.py`
+- Create: `tests/unit/test_renderer.py`
+
+- [ ] **Step 1: Write failing test**
+
+`tests/unit/test_renderer.py`:
+```python
+import base64
+from unittest.mock import AsyncMock
+
+import pytest
+
+from docugen_mcp.models import TemplateFrontmatter, TemplateVariable
+from docugen_mcp.template_store import TemplateStore, LoadedTemplate
+from docugen_mcp.generation_store import GenerationStore
+from docugen_mcp.llm_client import OpenRouterClient, LLMResponse
+from docugen_mcp.renderer import (
+    Renderer,
+    MissingVariables,
+    InvalidVariableType,
+    ImageTooLarge,
+    InvalidImageEncoding,
+)
+
+
+@pytest.fixture
+async def env(tmp_path):
+    template_store = TemplateStore(base_dir=tmp_path / "templates")
+    generation_store = GenerationStore(
+        db_path=tmp_path / "gen.db",
+        generated_dir=tmp_path / "generated",
+    )
+    await generation_store.init()
+    llm = AsyncMock(spec=OpenRouterClient)
+    llm.chat.return_value = LLMResponse(
+        text="# Output", model="anthropic/claude-sonnet-4",
+        tokens_in=10, tokens_out=20, cost_usd=0.001, latency_ms=100,
+    )
+    renderer = Renderer(
+        template_store=template_store,
+        generation_store=generation_store,
+        llm=llm,
+        public_base_url="https://mcp.example.com",
+        default_model="anthropic/claude-sonnet-4",
+        asset_ttl_days=30,
+        max_image_size_mb=10,
+    )
+    fm = TemplateFrontmatter(
+        name="fattura",
+        description="x",
+        required_variables=[
+            TemplateVariable(name="cliente", type="string"),
+        ],
+    )
+    await template_store.create(name="fattura", frontmatter=fm, body="Cliente: {{cliente}}")
+    return renderer, llm
+
+
+async def test_generate_happy_path_string_var(env):
+    renderer, llm = env
+    result = await renderer.generate(
+        template_name="fattura",
+        content_md="# Ordine",
+        variables={"cliente": "ACME"},
+        instructions=None,
+    )
+    assert result.markdown == "# Output"
+    assert result.model == "anthropic/claude-sonnet-4"
+    assert result.tokens.input == 10
+    call_kwargs = llm.chat.await_args.kwargs
+    assert "ACME" in call_kwargs["user"]
+    assert "Cliente: ACME" in call_kwargs["system"]
+
+
+async def test_generate_missing_required_variable_raises(env):
+    renderer, _ = env
+    with pytest.raises(MissingVariables) as exc:
+        await renderer.generate(
+            template_name="fattura",
+            content_md="x",
+            variables={},
+            instructions=None,
+        )
+    assert "cliente" in str(exc.value)
+
+
+async def test_generate_wrong_type_raises(env):
+    renderer, _ = env
+    with pytest.raises(InvalidVariableType):
+        await renderer.generate(
+            template_name="fattura",
+            content_md="x",
+            variables={"cliente": {"kind": "image", "data_b64": "x", "mime": "image/png"}},
+            instructions=None,
+        )
+
+
+async def test_generate_image_variable_is_saved_and_rewritten(tmp_path):
+    template_store = TemplateStore(base_dir=tmp_path / "templates")
+    generation_store = GenerationStore(
+        db_path=tmp_path / "gen.db",
+        generated_dir=tmp_path / "generated",
+    )
+    await generation_store.init()
+    llm = AsyncMock(spec=OpenRouterClient)
+    llm.chat.return_value = LLMResponse(
+        text="# OK", model="m", tokens_in=1, tokens_out=1, cost_usd=0, latency_ms=10,
+    )
+    renderer = Renderer(
+        template_store=template_store,
+        generation_store=generation_store,
+        llm=llm,
+        public_base_url="https://mcp.example.com",
+        default_model="m",
+        asset_ttl_days=30,
+        max_image_size_mb=10,
+    )
+    fm = TemplateFrontmatter(
+        name="report",
+        description="x",
+        required_variables=[TemplateVariable(name="foto", type="image")],
+    )
+    await template_store.create(name="report", frontmatter=fm, body="![foto]({{foto}})")
+
+    png = b"\x89PNG\r\n\x1a\n" + b"\x00" * 100
+    img_var = {"kind": "image", "data_b64": base64.b64encode(png).decode(), "mime": "image/png"}
+    result = await renderer.generate(
+        template_name="report",
+        content_md="content",
+        variables={"foto": img_var},
+        instructions=None,
+    )
+
+    assert result.ephemeral_assets_urls
+    url = result.ephemeral_assets_urls[0]
+    assert url.startswith("https://mcp.example.com/generated/")
+    assert url.endswith(".png")
+    gen_dir = tmp_path / "generated" / result.generation_id
+    assert gen_dir.exists()
+    assert any(gen_dir.iterdir())
+
+    call_kwargs = llm.chat.await_args.kwargs
+    assert "https://mcp.example.com/generated/" in call_kwargs["system"]
+
+
+async def test_image_too_large_raises(env):
+    renderer, _ = env
+    big = b"x" * (11 * 1024 * 1024)  # 11 MB raw
+    img_var = {"kind": "image", "data_b64": base64.b64encode(big).decode(), "mime": "image/png"}
+    fm = TemplateFrontmatter(
+        name="big",
+        description="x",
+        required_variables=[TemplateVariable(name="foto", type="image")],
+    )
+    await renderer.template_store.create(name="big", frontmatter=fm, body="{{foto}}")
+    with pytest.raises(ImageTooLarge):
+        await renderer.generate(
+            template_name="big",
+            content_md="x",
+            variables={"foto": img_var},
+            instructions=None,
+        )
+
+
+async def test_invalid_base64_raises(env):
+    renderer, _ = env
+    fm = TemplateFrontmatter(
+        name="bad",
+        description="x",
+        required_variables=[TemplateVariable(name="foto", type="image")],
+    )
+    await renderer.template_store.create(name="bad", frontmatter=fm, body="{{foto}}")
+    with pytest.raises(InvalidImageEncoding):
+        await renderer.generate(
+            template_name="bad",
+            content_md="x",
+            variables={"foto": {"kind": "image", "data_b64": "!!!not-base64!!!", "mime": "image/png"}},
+            instructions=None,
+        )
+
+
+async def test_template_asset_paths_are_rewritten(tmp_path):
+    template_store = TemplateStore(base_dir=tmp_path / "templates")
+    generation_store = GenerationStore(
+        db_path=tmp_path / "gen.db",
+        generated_dir=tmp_path / "generated",
+    )
+    await generation_store.init()
+    llm = AsyncMock(spec=OpenRouterClient)
+    llm.chat.return_value = LLMResponse(
+        text="out", model="m", tokens_in=1, tokens_out=1, cost_usd=0, latency_ms=10,
+    )
+    renderer = Renderer(
+        template_store=template_store,
+        generation_store=generation_store,
+        llm=llm,
+        public_base_url="https://mcp.example.com",
+        default_model="m",
+        asset_ttl_days=30,
+        max_image_size_mb=10,
+    )
+    fm = TemplateFrontmatter(name="brand", description="x")
+    assets = [
+        {"filename": "logo.png", "data_b64": base64.b64encode(b"\x89PNG").decode(), "mime": "image/png"}
+    ]
+    await template_store.create(
+        name="brand",
+        frontmatter=fm,
+        body="Header ![logo](./assets/logo.png) footer",
+        assets=assets,
+    )
+    await renderer.generate(
+        template_name="brand",
+        content_md="x",
+        variables={},
+        instructions=None,
+    )
+    system_prompt = llm.chat.await_args.kwargs["system"]
+    assert "https://mcp.example.com/assets/brand/logo.png" in system_prompt
+    assert "./assets/logo.png" not in system_prompt
+
+
+async def test_generate_uses_frontmatter_model_override(tmp_path):
+    template_store = TemplateStore(base_dir=tmp_path / "templates")
+    generation_store = GenerationStore(
+        db_path=tmp_path / "gen.db",
+        generated_dir=tmp_path / "generated",
+    )
+    await generation_store.init()
+    llm = AsyncMock(spec=OpenRouterClient)
+    llm.chat.return_value = LLMResponse(
+        text="out", model="openai/gpt-4o", tokens_in=1, tokens_out=1, cost_usd=0, latency_ms=10,
+    )
+    renderer = Renderer(
+        template_store=template_store,
+        generation_store=generation_store,
+        llm=llm,
+        public_base_url="https://mcp.example.com",
+        default_model="anthropic/claude-sonnet-4",
+        asset_ttl_days=30,
+        max_image_size_mb=10,
+    )
+    fm = TemplateFrontmatter(name="x", description="y", model="openai/gpt-4o")
+    await template_store.create(name="x", frontmatter=fm, body="b")
+    await renderer.generate(template_name="x", content_md="c", variables={}, instructions=None)
+    assert llm.chat.await_args.kwargs["model"] == "openai/gpt-4o"
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+```bash
+uv run pytest tests/unit/test_renderer.py -v
+```
+Expected: FAIL.
+
+- [ ] **Step 3: Implement renderer**
+
+`src/docugen_mcp/renderer.py`:
+```python
+import base64
+import binascii
+import re
+import uuid
+from pathlib import Path
+
+import aiofiles
+from pydantic import ValidationError
+
+from docugen_mcp.generation_store import (
+    EphemeralAssetRecord,
+    GenerationRecord,
+    GenerationStore,
+)
+from docugen_mcp.llm_client import LLMError, OpenRouterClient
+from docugen_mcp.models import (
+    GenerationResult,
+    ImageVariable,
+    TemplateFrontmatter,
+    TokenUsage,
+)
+from docugen_mcp.template_store import TemplateStore
+
+
+class RendererError(Exception):
+    pass
+
+
+class MissingVariables(RendererError):
+    def __init__(self, missing: list[str]) -> None:
+        super().__init__(f"missing required variables: {missing}")
+        self.missing = missing
+
+
+class InvalidVariableType(RendererError):
+    pass
+
+
+class InvalidImageEncoding(RendererError):
+    pass
+
+
+class ImageTooLarge(RendererError):
+    pass
+
+
+class AssetStorageError(RendererError):
+    pass
+
+
+_ASSET_TEMPLATE_REF_RE = re.compile(r"\.\/assets\/([A-Za-z0-9._-]+)")
+
+
+class Renderer:
+    def __init__(
+        self,
+        template_store: TemplateStore,
+        generation_store: GenerationStore,
+        llm: OpenRouterClient,
+        public_base_url: str,
+        default_model: str,
+        asset_ttl_days: int,
+        max_image_size_mb: int,
+    ) -> None:
+        self.template_store = template_store
+        self.generation_store = generation_store
+        self.llm = llm
+        self.public_base_url = public_base_url.rstrip("/")
+        self.default_model = default_model
+        self.asset_ttl_days = asset_ttl_days
+        self.max_image_size_bytes = max_image_size_mb * 1024 * 1024
+
+    async def generate(
+        self,
+        template_name: str,
+        content_md: str,
+        variables: dict,
+        instructions: str | None,
+    ) -> GenerationResult:
+        loaded = await self.template_store.get(template_name)
+        gen_id = str(uuid.uuid4())
+
+        validated = self._validate_variables(loaded.frontmatter, variables)
+        ephemeral_urls, var_strings = await self._materialize_image_variables(
+            gen_id, validated
+        )
+
+        system_prompt = self._build_system_prompt(
+            loaded.frontmatter, loaded.body, var_strings
+        )
+        user_prompt = self._build_user_prompt(content_md, var_strings, instructions)
+        model = loaded.frontmatter.model or self.default_model
+
+        try:
+            response = await self.llm.chat(model=model, system=system_prompt, user=user_prompt)
+        except LLMError as exc:
+            await self.generation_store.record_generation(
+                GenerationRecord(
+                    id=gen_id,
+                    template_name=template_name,
+                    model=model,
+                    tokens_in=0,
+                    tokens_out=0,
+                    cost_usd=0.0,
+                    success=False,
+                    error_msg=f"{type(exc).__name__}: {exc}",
+                )
+            )
+            raise
+
+        await self.generation_store.record_generation(
+            GenerationRecord(
+                id=gen_id,
+                template_name=template_name,
+                model=response.model,
+                tokens_in=response.tokens_in,
+                tokens_out=response.tokens_out,
+                cost_usd=response.cost_usd,
+                success=True,
+                error_msg=None,
+            )
+        )
+
+        expires_at = None
+        if ephemeral_urls:
+            info = await self.generation_store.get_ephemeral_asset(
+                gen_id, Path(ephemeral_urls[0]).name
+            )
+            expires_at = info.expires_at if info else None
+
+        return GenerationResult(
+            generation_id=gen_id,
+            markdown=response.text,
+            model=response.model,
+            tokens=TokenUsage(input=response.tokens_in, output=response.tokens_out),
+            cost_usd=response.cost_usd,
+            ephemeral_assets_urls=ephemeral_urls,
+            ephemeral_expires_at=expires_at,
+        )
+
+    def _validate_variables(self, fm: TemplateFrontmatter, variables: dict) -> dict:
+        missing = [v.name for v in fm.required_variables if v.name not in variables]
+        if missing:
+            raise MissingVariables(missing)
+
+        validated: dict = {}
+        for var_def in fm.required_variables:
+            raw = variables[var_def.name]
+            if var_def.type == "string":
+                if not isinstance(raw, str):
+                    raise InvalidVariableType(
+                        f"{var_def.name}: expected string, got {type(raw).__name__}"
+                    )
+                validated[var_def.name] = raw
+            elif var_def.type == "image":
+                try:
+                    img = ImageVariable(**raw) if isinstance(raw, dict) else None
+                except ValidationError as exc:
+                    raise InvalidVariableType(f"{var_def.name}: {exc}") from exc
+                if img is None:
+                    raise InvalidVariableType(
+                        f"{var_def.name}: expected image object, got {type(raw).__name__}"
+                    )
+                validated[var_def.name] = img
+        return validated
+
+    async def _materialize_image_variables(
+        self, gen_id: str, validated: dict
+    ) -> tuple[list[str], dict[str, str]]:
+        urls: list[str] = []
+        var_strings: dict[str, str] = {}
+        gen_dir = self.generation_store.generated_dir / gen_id
+
+        for name, value in validated.items():
+            if isinstance(value, ImageVariable):
+                try:
+                    raw_bytes = base64.b64decode(value.data_b64, validate=True)
+                except (binascii.Error, ValueError) as exc:
+                    raise InvalidImageEncoding(f"{name}: {exc}") from exc
+                if len(raw_bytes) > self.max_image_size_bytes:
+                    raise ImageTooLarge(
+                        f"{name}: {len(raw_bytes)} bytes > {self.max_image_size_bytes}"
+                    )
+                ext = {"image/png": "png", "image/jpeg": "jpg", "image/webp": "webp"}[value.mime]
+                filename = f"{name}.{ext}"
+                file_path = gen_dir / filename
+                gen_dir.mkdir(parents=True, exist_ok=True)
+                try:
+                    async with aiofiles.open(file_path, "wb") as f:
+                        await f.write(raw_bytes)
+                except OSError as exc:
+                    raise AssetStorageError(str(exc)) from exc
+                await self.generation_store.register_ephemeral_asset(
+                    EphemeralAssetRecord(
+                        generation_id=gen_id,
+                        var_name=name,
+                        file_path=str(file_path),
+                        mime=value.mime,
+                        ttl_days=self.asset_ttl_days,
+                    )
+                )
+                url = f"{self.public_base_url}/generated/{gen_id}/{filename}"
+                urls.append(url)
+                var_strings[name] = url
+            else:
+                var_strings[name] = str(value)
+        return urls, var_strings
+
+    def _build_system_prompt(
+        self, fm: TemplateFrontmatter, body: str, var_strings: dict[str, str]
+    ) -> str:
+        # Rewrite template-scoped asset paths to absolute URLs
+        template_name = fm.name
+
+        def _replace_asset(match: re.Match) -> str:
+            filename = match.group(1)
+            return f"{self.public_base_url}/assets/{template_name}/{filename}"
+
+        resolved = _ASSET_TEMPLATE_REF_RE.sub(_replace_asset, body)
+        # Substitute {{var}} placeholders with current values
+        for name, value in var_strings.items():
+            resolved = resolved.replace(f"{{{{{name}}}}}", value)
+        return resolved
+
+    def _build_user_prompt(
+        self, content_md: str, var_strings: dict[str, str], instructions: str | None
+    ) -> str:
+        parts = ["## Raw content", content_md]
+        if var_strings:
+            parts.append("## Variables")
+            for name, value in var_strings.items():
+                parts.append(f"- {name}: {value}")
+        if instructions:
+            parts.append("## Additional instructions")
+            parts.append(instructions)
+        return "\n\n".join(parts)
+```
+
+- [ ] **Step 4: Run tests to verify pass**
+
+```bash
+uv run pytest tests/unit/test_renderer.py -v
+```
+Expected: 8 PASSED.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/docugen_mcp/renderer.py tests/unit/test_renderer.py
+git commit -m "feat: add Renderer orchestrator with var validation and image handling"
+```
+
+---
+
+## Task 8: HTTP routes (FastAPI sub-app)
+
+**Files:**
+- Create: `src/docugen_mcp/http_routes.py`
+- Create: `tests/integration/test_http_routes.py`
+
+- [ ] **Step 1: Write failing test**
+
+`tests/integration/test_http_routes.py`:
+```python
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from docugen_mcp.auth import ApiKeyAuthMiddleware
+from docugen_mcp.generation_store import EphemeralAssetRecord, GenerationStore
+from docugen_mcp.http_routes import build_http_app
+from docugen_mcp.template_store import TemplateStore
+
+
+@pytest.fixture
+async def client(tmp_path):
+    template_store = TemplateStore(base_dir=tmp_path / "templates")
+    generation_store = GenerationStore(
+        db_path=tmp_path / "gen.db",
+        generated_dir=tmp_path / "generated",
+    )
+    await generation_store.init()
+
+    app = FastAPI()
+    app.add_middleware(ApiKeyAuthMiddleware, api_key="test-key", exempt_paths={"/health"})
+    app.mount("/", build_http_app(template_store, generation_store))
+    return TestClient(app), template_store, generation_store, tmp_path
+
+
+def _headers():
+    return {"Authorization": "Bearer test-key"}
+
+
+async def test_health_no_auth(client):
+    tc, *_ = client
+    r = tc.get("/health")
+    assert r.status_code == 200
+    assert r.json() == {"status": "ok"}
+
+
+async def test_assets_serve_existing_file(client):
+    tc, template_store, _, tmp_path = client
+    from docugen_mcp.models import TemplateFrontmatter
+    fm = TemplateFrontmatter(name="brand", description="x")
+    import base64
+    assets = [{"filename": "logo.png", "data_b64": base64.b64encode(b"\x89PNG").decode(), "mime": "image/png"}]
+    await template_store.create(name="brand", frontmatter=fm, body="b", assets=assets)
+
+    r = tc.get("/assets/brand/logo.png", headers=_headers())
+    assert r.status_code == 200
+    assert r.content == b"\x89PNG"
+
+
+async def test_assets_require_auth(client):
+    tc, *_ = client
+    r = tc.get("/assets/brand/logo.png")
+    assert r.status_code == 401
+
+
+async def test_assets_path_traversal_rejected(client):
+    tc, *_ = client
+    r = tc.get("/assets/brand/..%2Fevil.png", headers=_headers())
+    assert r.status_code == 400
+
+
+async def test_assets_missing_returns_404(client):
+    tc, *_ = client
+    r = tc.get("/assets/brand/missing.png", headers=_headers())
+    assert r.status_code == 404
+
+
+async def test_generated_fresh_returns_file(client):
+    tc, _, generation_store, tmp_path = client
+    gen_dir = tmp_path / "generated" / "g-1"
+    gen_dir.mkdir(parents=True)
+    (gen_dir / "foto.png").write_bytes(b"image-bytes")
+    await generation_store.register_ephemeral_asset(
+        EphemeralAssetRecord(
+            generation_id="g-1",
+            var_name="foto",
+            file_path=str(gen_dir / "foto.png"),
+            mime="image/png",
+            ttl_days=30,
+        )
+    )
+    r = tc.get("/generated/g-1/foto.png", headers=_headers())
+    assert r.status_code == 200
+    assert r.content == b"image-bytes"
+
+
+async def test_generated_expired_returns_410(client):
+    tc, _, generation_store, tmp_path = client
+    gen_dir = tmp_path / "generated" / "g-old"
+    gen_dir.mkdir(parents=True)
+    (gen_dir / "foto.png").write_bytes(b"x")
+    await generation_store.register_ephemeral_asset(
+        EphemeralAssetRecord(
+            generation_id="g-old",
+            var_name="foto",
+            file_path=str(gen_dir / "foto.png"),
+            mime="image/png",
+            ttl_days=-1,
+        )
+    )
+    r = tc.get("/generated/g-old/foto.png", headers=_headers())
+    assert r.status_code == 410
+
+
+async def test_generated_unknown_returns_410(client):
+    tc, *_ = client
+    r = tc.get("/generated/unknown-id/file.png", headers=_headers())
+    assert r.status_code == 410
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+```bash
+uv run pytest tests/integration/test_http_routes.py -v
+```
+Expected: FAIL.
+
+- [ ] **Step 3: Implement HTTP routes**
+
+`src/docugen_mcp/http_routes.py`:
+```python
+import re
+from pathlib import Path
+
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import FileResponse, JSONResponse
+
+from docugen_mcp.generation_store import GenerationStore
+from docugen_mcp.template_store import InvalidTemplateName, TemplateStore
+
+
+_SAFE_SEGMENT_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+
+
+def build_http_app(
+    template_store: TemplateStore,
+    generation_store: GenerationStore,
+) -> FastAPI:
+    app = FastAPI()
+
+    @app.get("/health")
+    async def health():
+        return {"status": "ok"}
+
+    @app.get("/assets/{template_name}/{filename}")
+    async def get_template_asset(template_name: str, filename: str):
+        if not _SAFE_SEGMENT_RE.match(template_name) or not _SAFE_SEGMENT_RE.match(filename):
+            raise HTTPException(status_code=400, detail="invalid path")
+        try:
+            path = template_store.asset_path(template_name, filename)
+        except (ValueError, InvalidTemplateName):
+            raise HTTPException(status_code=400, detail="invalid path")
+        if not path.exists():
+            raise HTTPException(status_code=404, detail="not found")
+        return FileResponse(path)
+
+    @app.get("/generated/{gen_id}/{filename}")
+    async def get_generated_asset(gen_id: str, filename: str):
+        if not _SAFE_SEGMENT_RE.match(gen_id) or not _SAFE_SEGMENT_RE.match(filename):
+            raise HTTPException(status_code=400, detail="invalid path")
+        info = await generation_store.get_ephemeral_asset(gen_id, filename)
+        if info is None or info.is_expired or not Path(info.file_path).exists():
+            return JSONResponse(
+                status_code=410,
+                content={"error": "gone", "reason": "ephemeral asset expired or not found"},
+            )
+        return FileResponse(info.file_path, media_type=info.mime)
+
+    return app
+```
+
+- [ ] **Step 4: Run tests to verify pass**
+
+```bash
+uv run pytest tests/integration/test_http_routes.py -v
+```
+Expected: 8 PASSED.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/docugen_mcp/http_routes.py tests/integration/test_http_routes.py
+git commit -m "feat: add FastAPI sub-app for asset serving and health"
+```
+
+---
+
+## Task 9: MCP tools (FastMCP)
+
+**Files:**
+- Create: `src/docugen_mcp/mcp_tools.py`
+- Create: `tests/integration/test_mcp_tools.py`
+
+- [ ] **Step 1: Write failing test**
+
+`tests/integration/test_mcp_tools.py`:
+```python
+from unittest.mock import AsyncMock
+
+import pytest
+
+from docugen_mcp.llm_client import LLMResponse
+from docugen_mcp.mcp_tools import build_mcp_server
+from docugen_mcp.template_store import TemplateStore
+from docugen_mcp.generation_store import GenerationStore
+
+
+@pytest.fixture
+async def mcp_env(tmp_path):
+    template_store = TemplateStore(base_dir=tmp_path / "templates")
+    generation_store = GenerationStore(
+        db_path=tmp_path / "gen.db",
+        generated_dir=tmp_path / "generated",
+    )
+    await generation_store.init()
+    llm = AsyncMock()
+    llm.chat.return_value = LLMResponse(
+        text="# Out", model="m", tokens_in=5, tokens_out=10, cost_usd=0.01, latency_ms=50,
+    )
+    from docugen_mcp.renderer import Renderer
+    renderer = Renderer(
+        template_store=template_store,
+        generation_store=generation_store,
+        llm=llm,
+        public_base_url="https://mcp.example.com",
+        default_model="m",
+        asset_ttl_days=30,
+        max_image_size_mb=10,
+    )
+    mcp = build_mcp_server(template_store, renderer)
+    return mcp, template_store
+
+
+async def test_template_create_and_get(mcp_env):
+    mcp, _ = mcp_env
+    await mcp.tools["template_create"](
+        name="demo",
+        frontmatter={"name": "demo", "description": "d"},
+        body="body",
+        assets=None,
+    )
+    got = await mcp.tools["template_get"](name="demo")
+    assert got["name"] == "demo"
+    assert got["body"] == "body"
+
+
+async def test_template_create_duplicate_errors(mcp_env):
+    mcp, _ = mcp_env
+    await mcp.tools["template_create"](
+        name="demo", frontmatter={"name": "demo", "description": "x"}, body="b", assets=None,
+    )
+    with pytest.raises(Exception):
+        await mcp.tools["template_create"](
+            name="demo", frontmatter={"name": "demo", "description": "x"}, body="b", assets=None,
+        )
+
+
+async def test_template_list_returns_summaries(mcp_env):
+    mcp, _ = mcp_env
+    await mcp.tools["template_create"](
+        name="a", frontmatter={"name": "a", "description": "A"}, body="b", assets=None,
+    )
+    await mcp.tools["template_create"](
+        name="b", frontmatter={"name": "b", "description": "B"}, body="b", assets=None,
+    )
+    result = await mcp.tools["template_list"]()
+    names = sorted(t["name"] for t in result)
+    assert names == ["a", "b"]
+
+
+async def test_template_update(mcp_env):
+    mcp, _ = mcp_env
+    await mcp.tools["template_create"](
+        name="u", frontmatter={"name": "u", "description": "d"}, body="old", assets=None,
+    )
+    await mcp.tools["template_update"](
+        name="u", frontmatter={"name": "u", "description": "new"}, body="new", assets=None,
+    )
+    got = await mcp.tools["template_get"](name="u")
+    assert got["body"] == "new"
+    assert got["frontmatter"]["description"] == "new"
+
+
+async def test_template_delete(mcp_env):
+    mcp, _ = mcp_env
+    await mcp.tools["template_create"](
+        name="d", frontmatter={"name": "d", "description": "x"}, body="b", assets=None,
+    )
+    await mcp.tools["template_delete"](name="d")
+    with pytest.raises(Exception):
+        await mcp.tools["template_get"](name="d")
+
+
+async def test_document_generate_happy_path(mcp_env):
+    mcp, _ = mcp_env
+    await mcp.tools["template_create"](
+        name="g",
+        frontmatter={
+            "name": "g",
+            "description": "x",
+            "required_variables": [{"name": "cliente", "type": "string"}],
+        },
+        body="Cliente: {{cliente}}",
+        assets=None,
+    )
+    result = await mcp.tools["document_generate"](
+        template_name="g",
+        content_md="# Ordine",
+        variables={"cliente": "ACME"},
+        instructions=None,
+    )
+    assert result["markdown"] == "# Out"
+    assert result["model"] == "m"
+    assert result["tokens"]["input"] == 5
+    assert "generation_id" in result
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+```bash
+uv run pytest tests/integration/test_mcp_tools.py -v
+```
+Expected: FAIL.
+
+- [ ] **Step 3: Implement MCP tools**
+
+`src/docugen_mcp/mcp_tools.py`:
+```python
+from mcp.server.fastmcp import FastMCP
+
+from docugen_mcp.models import TemplateFrontmatter
+from docugen_mcp.renderer import Renderer
+from docugen_mcp.template_store import TemplateStore
+
+
+def build_mcp_server(template_store: TemplateStore, renderer: Renderer) -> FastMCP:
+    mcp = FastMCP("docugen-mcp")
+
+    @mcp.tool()
+    async def template_create(
+        name: str,
+        frontmatter: dict,
+        body: str,
+        assets: list[dict] | None = None,
+    ) -> dict:
+        """Create a new template. Fails if the name already exists."""
+        fm = TemplateFrontmatter(**frontmatter)
+        await template_store.create(name=name, frontmatter=fm, body=body, assets=assets)
+        return {"name": name, "status": "created"}
+
+    @mcp.tool()
+    async def template_update(
+        name: str,
+        frontmatter: dict,
+        body: str,
+        assets: list[dict] | None = None,
+    ) -> dict:
+        """Update an existing template. Replaces frontmatter, body, and (if given) assets."""
+        fm = TemplateFrontmatter(**frontmatter)
+        await template_store.update(name=name, frontmatter=fm, body=body, assets=assets)
+        return {"name": name, "status": "updated"}
+
+    @mcp.tool()
+    async def template_delete(name: str) -> dict:
+        """Delete a template and all its assets."""
+        await template_store.delete(name)
+        return {"name": name, "status": "deleted"}
+
+    @mcp.tool()
+    async def template_get(name: str) -> dict:
+        """Return a template's frontmatter, body, and asset list."""
+        loaded = await template_store.get(name)
+        return {
+            "name": loaded.frontmatter.name,
+            "frontmatter": loaded.frontmatter.model_dump(exclude_none=True),
+            "body": loaded.body,
+            "assets": [a.model_dump() for a in loaded.assets],
+            "updated_at": loaded.updated_at.isoformat(),
+        }
+
+    @mcp.tool()
+    async def template_list() -> list[dict]:
+        """List all templates with name, description, and updated_at."""
+        summaries = await template_store.list()
+        return [s.model_dump(mode="json") for s in summaries]
+
+    @mcp.tool()
+    async def document_generate(
+        template_name: str,
+        content_md: str,
+        variables: dict,
+        instructions: str | None = None,
+    ) -> dict:
+        """Generate a Markdown document from a template, content, and variables."""
+        result = await renderer.generate(
+            template_name=template_name,
+            content_md=content_md,
+            variables=variables,
+            instructions=instructions,
+        )
+        return result.model_dump(mode="json")
+
+    # Expose callables directly for test access (FastMCP test helper)
+    mcp.tools = {
+        "template_create": template_create,
+        "template_update": template_update,
+        "template_delete": template_delete,
+        "template_get": template_get,
+        "template_list": template_list,
+        "document_generate": document_generate,
+    }
+
+    return mcp
+```
+
+- [ ] **Step 4: Run tests to verify pass**
+
+```bash
+uv run pytest tests/integration/test_mcp_tools.py -v
+```
+Expected: 6 PASSED.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/docugen_mcp/mcp_tools.py tests/integration/test_mcp_tools.py
+git commit -m "feat: add FastMCP tool definitions (6 tools)"
+```
+
+---
+
+## Task 10: Main bootstrap + end-to-end flow test
+
+**Files:**
+- Create: `src/docugen_mcp/main.py`
+- Create: `tests/integration/test_generate_flow.py`
+
+- [ ] **Step 1: Write failing integration test**
+
+`tests/integration/test_generate_flow.py`:
+```python
+import base64
+import pytest
+import respx
+import httpx
+
+from docugen_mcp.main import build_app
+
+
+def _openrouter_success(text: str = "# Generated"):
+    return httpx.Response(200, json={
+        "id": "g",
+        "choices": [{"message": {"role": "assistant", "content": text}}],
+        "model": "anthropic/claude-sonnet-4",
+        "usage": {"prompt_tokens": 50, "completion_tokens": 100, "total_cost": 0.02},
+    })
+
+
+@pytest.fixture
+async def app_env(tmp_path, monkeypatch):
+    monkeypatch.setenv("API_KEY", "test-api-key")
+    monkeypatch.setenv("OPENROUTER_API_KEY", "sk-or-test")
+    monkeypatch.setenv("PUBLIC_BASE_URL", "https://mcp.test.com")
+    monkeypatch.setenv("DATA_DIR", str(tmp_path))
+    app = await build_app()
+    return app, tmp_path
+
+
+@respx.mock
+async def test_full_generation_flow_records_and_serves_asset(app_env):
+    app, tmp_path = app_env
+    respx.post("https://openrouter.ai/api/v1/chat/completions").mock(
+        return_value=_openrouter_success("# Done")
+    )
+
+    # Find the renderer and template store via app state
+    template_store = app.state.template_store
+    renderer = app.state.renderer
+    generation_store = app.state.generation_store
+
+    from docugen_mcp.models import TemplateFrontmatter, TemplateVariable
+    fm = TemplateFrontmatter(
+        name="report",
+        description="x",
+        required_variables=[TemplateVariable(name="foto", type="image")],
+    )
+    await template_store.create(name="report", frontmatter=fm, body="![foto]({{foto}})")
+
+    png = b"\x89PNG\r\n\x1a\n" + b"\x00" * 50
+    img_var = {"kind": "image", "data_b64": base64.b64encode(png).decode(), "mime": "image/png"}
+
+    result = await renderer.generate(
+        template_name="report",
+        content_md="content",
+        variables={"foto": img_var},
+        instructions=None,
+    )
+
+    assert result.markdown == "# Done"
+    stats = await generation_store.get_stats()
+    assert stats["success"] == 1
+
+    # Asset exists on disk
+    gen_files = list((tmp_path / "generated" / result.generation_id).iterdir())
+    assert len(gen_files) == 1
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+```bash
+uv run pytest tests/integration/test_generate_flow.py -v
+```
+Expected: FAIL — `docugen_mcp.main` does not exist.
+
+- [ ] **Step 3: Implement main bootstrap**
+
+Architecturally, FastMCP exposes a Starlette/ASGI app via `streamable_http_app()` (check exact name in installed SDK — see Notes). We mount it at `/mcp` inside a root FastAPI app that also hosts the health + asset routes. This avoids root-path conflicts and gives Claude Code the URL `https://host/mcp`.
+
+`src/docugen_mcp/main.py`:
+```python
+import asyncio
+import logging
+
+import uvicorn
+from fastapi import FastAPI
+
+from docugen_mcp.auth import ApiKeyAuthMiddleware
+from docugen_mcp.config import Settings
+from docugen_mcp.generation_store import GenerationStore
+from docugen_mcp.http_routes import build_http_app
+from docugen_mcp.llm_client import OpenRouterClient
+from docugen_mcp.mcp_tools import build_mcp_server
+from docugen_mcp.renderer import Renderer
+from docugen_mcp.template_store import TemplateStore
+
+
+logger = logging.getLogger("docugen_mcp")
+
+
+async def build_app(settings: Settings | None = None) -> FastAPI:
+    settings = settings or Settings()
+    settings.data_dir.mkdir(parents=True, exist_ok=True)
+    templates_dir = settings.data_dir / "templates"
+    generated_dir = settings.data_dir / "generated"
+    db_path = settings.data_dir / "docugen_mcp.db"
+
+    template_store = TemplateStore(base_dir=templates_dir)
+    generation_store = GenerationStore(db_path=db_path, generated_dir=generated_dir)
+    await generation_store.init()
+
+    llm = OpenRouterClient(
+        api_key=settings.openrouter_api_key,
+        base_url=settings.openrouter_base_url,
+        timeout=settings.llm_timeout_seconds,
+    )
+    renderer = Renderer(
+        template_store=template_store,
+        generation_store=generation_store,
+        llm=llm,
+        public_base_url=settings.public_base_url,
+        default_model=settings.llm_model_default,
+        asset_ttl_days=settings.asset_ttl_days,
+        max_image_size_mb=settings.max_image_size_mb,
+    )
+
+    mcp = build_mcp_server(template_store, renderer)
+
+    # Root FastAPI = HTTP routes (health, assets, generated) + MCP mounted on /mcp
+    app = build_http_app(template_store, generation_store)
+    app.mount("/mcp", mcp.streamable_http_app())
+
+    app.add_middleware(
+        ApiKeyAuthMiddleware,
+        api_key=settings.api_key,
+        exempt_paths={"/health"},
+    )
+
+    # Stash for tests and cleanup task
+    app.state.settings = settings
+    app.state.template_store = template_store
+    app.state.generation_store = generation_store
+    app.state.renderer = renderer
+    app.state.llm = llm
+
+    @app.on_event("startup")
+    async def start_cleanup_task():
+        app.state._cleanup_task = asyncio.create_task(
+            _periodic_cleanup(generation_store, interval_seconds=24 * 3600)
+        )
+
+    @app.on_event("shutdown")
+    async def stop_cleanup_task():
+        task = app.state.__dict__.get("_cleanup_task")
+        if task:
+            task.cancel()
+
+    return app
+
+
+async def _periodic_cleanup(generation_store: GenerationStore, interval_seconds: int) -> None:
+    while True:
+        try:
+            removed = await generation_store.cleanup_expired()
+            if removed:
+                logger.info("cleanup_expired removed %d assets", removed)
+        except Exception as exc:  # noqa: BLE001
+            logger.error("cleanup task error: %s", exc)
+        await asyncio.sleep(interval_seconds)
+
+
+def run() -> None:
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s %(message)s")
+    uvicorn.run(
+        "docugen_mcp.main:asgi_app",
+        host="0.0.0.0",
+        port=8000,
+        factory=True,
+    )
+
+
+async def asgi_app() -> FastAPI:
+    return await build_app()
+```
+
+- [ ] **Step 4: Run tests to verify pass**
+
+```bash
+uv run pytest tests/integration/test_generate_flow.py -v
+```
+Expected: 1 PASSED.
+
+Note: if `mcp.streamable_http_app()` method name differs in the installed `mcp` SDK version, replace with the SDK-specific factory (check `FastMCP` class: likely `http_app()`, `as_asgi()`, or `create_app()`). Adjust accordingly, keeping the mount pattern intact.
+
+- [ ] **Step 5: Run full test suite**
+
+```bash
+uv run pytest -v
+```
+Expected: all tests pass. If any `mcp.streamable_http_app()`-related failure, fix per note above and rerun.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/docugen_mcp/main.py tests/integration/test_generate_flow.py
+git commit -m "feat: add bootstrap (FastMCP + FastAPI mount + cleanup task)"
+```
+
+---
+
+## Task 11: Docker packaging
+
+**Files:**
+- Create: `Dockerfile`
+- Create: `docker-compose.yml`
+- Modify: `README.md` (expand with Docker + client config sections)
+
+- [ ] **Step 1: Create Dockerfile**
+
+```dockerfile
+FROM python:3.11-slim AS base
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1
+
+RUN apt-get update && apt-get install -y --no-install-recommends curl \
+    && rm -rf /var/lib/apt/lists/* \
+    && curl -LsSf https://astral.sh/uv/install.sh | sh \
+    && mv /root/.local/bin/uv /usr/local/bin/uv
+
+WORKDIR /app
+
+COPY pyproject.toml uv.lock README.md ./
+COPY src/ ./src/
+
+RUN uv sync --frozen --no-dev
+
+RUN useradd --system --no-create-home --uid 1000 mcpuser \
+    && mkdir -p /data \
+    && chown -R mcpuser:mcpuser /app /data
+
+USER mcpuser
+
+ENV DATA_DIR=/data
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+CMD ["uv", "run", "docugen-mcp"]
+```
+
+- [ ] **Step 2: Create `docker-compose.yml`**
+
+```yaml
+services:
+  docugen-mcp:
+    build: .
+    container_name: docugen-mcp
+    restart: unless-stopped
+    ports:
+      - "8000:8000"
+    env_file:
+      - .env
+    volumes:
+      - ./data:/data
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+```
+
+- [ ] **Step 3: Expand `README.md`**
+
+```markdown
+# docugen-mcp
+
+MCP server for generating Markdown documents from templates via OpenRouter.
+
+See design spec: `../2026-04-21-docugen-mcp-design.md`.
+
+## Setup (local dev)
+
+```bash
+uv sync --all-extras
+cp .env.example .env  # fill API_KEY, OPENROUTER_API_KEY, PUBLIC_BASE_URL
+uv run docugen-mcp
+```
+
+Server listens on `http://localhost:8000`. MCP endpoint: `/mcp`.
+
+## Test
+
+```bash
+uv run pytest
+```
+
+## Docker
+
+Build and run:
+
+```bash
+docker compose up --build -d
+```
+
+Mount `./data` on the host so templates, SQLite DB, and generated assets persist across restarts.
+
+## Reverse proxy / TLS
+
+The container listens on plain HTTP. Put it behind Nginx/Traefik/Caddy for TLS termination and public exposure.
+
+Set `PUBLIC_BASE_URL` in `.env` to the external URL (e.g. `https://mcp.example.com`). This URL is used to build asset links in generated Markdown.
+
+## Client configuration
+
+### Claude Code
+
+```bash
+claude mcp add --transport http docugen-mcp https://mcp.example.com/mcp \
+  --header "Authorization: Bearer <API_KEY>"
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "docugen-mcp": {
+      "transport": "http",
+      "url": "https://mcp.example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer <API_KEY>"
+      }
+    }
+  }
+}
+```
+
+## MCP tools exposed
+
+| Tool | Purpose |
+|------|---------|
+| `template_create` | Create template (frontmatter + body + optional assets) |
+| `template_update` | Update an existing template |
+| `template_delete` | Remove a template |
+| `template_list` | List templates (name, description, updated_at) |
+| `template_get` | Load a template's frontmatter, body, asset list |
+| `document_generate` | Generate Markdown from a template + content + variables |
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `API_KEY` | *(required)* | Bearer token for MCP clients |
+| `OPENROUTER_API_KEY` | *(required)* | OpenRouter API key |
+| `OPENROUTER_BASE_URL` | `https://openrouter.ai/api/v1` | OpenRouter endpoint |
+| `LLM_MODEL_DEFAULT` | `anthropic/claude-sonnet-4` | Model used when template has no override |
+| `PUBLIC_BASE_URL` | *(required)* | Public URL of this server (for asset links) |
+| `DATA_DIR` | `/data` | Persistence directory |
+| `ASSET_TTL_DAYS` | `30` | Retention for ephemeral generated assets |
+| `MAX_IMAGE_SIZE_MB` | `10` | Maximum size for inline images passed as variables |
+| `LLM_TIMEOUT_SECONDS` | `60` | OpenRouter request timeout |
+```
+
+- [ ] **Step 4: Verify Docker build**
+
+```bash
+docker compose build
+```
+Expected: build completes without errors.
+
+- [ ] **Step 5: Smoke-test the container**
+
+Create a minimal `.env` for testing:
+```bash
+cat > .env <<EOF
+API_KEY=local-test-key
+OPENROUTER_API_KEY=sk-or-dummy
+PUBLIC_BASE_URL=http://localhost:8000
+DATA_DIR=/data
+EOF
+
+docker compose up -d
+sleep 3
+curl -f http://localhost:8000/health
+# Expected: {"status":"ok"}
+docker compose down
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add Dockerfile docker-compose.yml README.md
+git commit -m "feat: add Dockerfile, docker-compose, and expanded README"
+```
+
+---
+
+## Final verification
+
+- [ ] Run the full suite one more time:
+
+```bash
+uv run pytest --cov=src/docugen_mcp --cov-report=term-missing
+```
+Expected: all tests pass; coverage ≥ 85% on logic modules (template_store, renderer, generation_store, llm_client, auth).
+
+- [ ] Tag release candidate:
+
+```bash
+git tag v0.1.0
+```
+
+---
+
+## Notes for the implementer
+
+- **FastMCP API check:** the exact method to obtain the ASGI app from `FastMCP` depends on the installed `mcp` SDK version. In Task 10 Step 3 the code uses `mcp.streamable_http_app()`. If that method name is wrong on the installed version, check the `FastMCP` class: common alternatives are `http_app()`, `sse_app()`, `create_app()`. Adjust and re-run `test_generate_flow.py` until it passes. The structural pattern (FastMCP ASGI root + FastAPI mount on `/`) stays valid.
+- **Clock-dependent tests:** TTL tests use `ttl_days=-1` to force expiration immediately; avoid sleeping in tests.
+- **Do not commit `.env`:** it's in `.gitignore`. `.env.example` is the template.
+- **Image max size limit is pre-decode:** the 10 MB threshold checks the decoded bytes, not the base64 string. Test in Task 7 uses `11 * 1024 * 1024` raw bytes to trigger it.
+- **SQLite cleanup:** the TTL task runs on the same event loop as the server. For heavy traffic, consider a separate worker.
+- **`template_update` asset semantics:** when `assets` is passed (even empty list `[]`), the directory is wiped and replaced. Pass `None` (or omit) to leave assets untouched. The test suite covers the explicit replacement case but not the implicit preservation — add a follow-up test if this becomes a concern.
diff --git a/Docs/sistema-documentale/2026-04-21-design.md b/Docs/sistema-documentale/2026-04-21-design.md
new file mode 100644
index 0000000..5e9bb76
--- /dev/null
+++ b/Docs/sistema-documentale/2026-04-21-design.md
@@ -0,0 +1,885 @@
+# Sistema Documentale — Design Master
+
+> Sistema documentale multi-wiki (personale, aziendale, scalabile a N) come
+> vault Git di markdown, sincronizzato su Gitea (VPS), pubblicato in sola
+> lettura via Quartz, accessibile da desktop (Obsidian + Claude Code),
+> Android (Obsidian) e browser mobile, integrato con `mcp-docgen` per
+> documenti formali e predisposto per pipeline di ingest futura
+> (STT di riunioni, bot Telegram).
+
+---
+
+## Indice
+
+1. [Panoramica e scopo](#1-panoramica-e-scopo)
+2. [Componenti del sistema](#2-componenti-del-sistema)
+3. [Struttura di un singolo wiki](#3-struttura-di-un-singolo-wiki)
+4. [Configurazione multi-wiki](#4-configurazione-multi-wiki)
+5. [Flusso Git end-to-end](#5-flusso-git-end-to-end)
+6. [Integrazione con `mcp-docgen`](#6-integrazione-con-mcp-docgen)
+7. [Pubblicazione web — Quartz multi-site](#7-pubblicazione-web--quartz-multi-site)
+8. [Accesso da Android](#8-accesso-da-android)
+9. [Storage degli asset binari](#9-storage-degli-asset-binari)
+10. [Autenticazione e sicurezza](#10-autenticazione-e-sicurezza)
+11. [Backup e disaster recovery](#11-backup-e-disaster-recovery)
+12. [Setup iniziale — fasi implementative](#12-setup-iniziale--fasi-implementative)
+13. [Estensioni future pianificate](#13-estensioni-future-pianificate)
+14. [Decisioni e rationale](#14-decisioni-e-rationale)
+
+---
+
+## 1. Panoramica e scopo
+
+### Cosa stiamo costruendo
+
+Un sistema documentale che:
+
+- **Archivia** documenti (relazioni, preventivi, note commercialista, idee, verbali riunione, ecc.) in più **wiki separati per dominio** (personale, aziendale, altri futuri) — tutti come file Markdown
+- **Versiona** ogni wiki in un **repo Git separato** su Gitea self-hosted (VPS)
+- **Pubblica** ogni wiki in sola lettura su **un sotto-dominio dedicato** (Quartz statico), con auth unificata
+- **Integra** un generatore di documenti formali (`mcp-docgen`, già progettato) condiviso da tutti i wiki
+- **Resta editabile** principalmente da desktop (Obsidian + Claude Code) e occasionalmente da Android (Obsidian mobile + Git plugin)
+- **È predisposto** per estensioni future di ingest automatico: trascrizione riunioni via STT, bot Telegram per note vocali/testuali inviate da mobile
+
+### Principi cardine
+
+**Un wiki, un dominio, un repo, un ciclo di vita.** Wiki personale e wiki aziendale sono **fisicamente separati**: repo diversi, vault Obsidian diversi, siti Quartz diversi, asset separati, backup indipendenti. Una compromissione o un errore su uno non tocca l'altro. Un eventuale hand-off di un wiki (es. condivisione di `aziendale` con un collaboratore o commercialista) è possibile senza sforzo.
+
+**Pattern riusabile.** Tutti i wiki seguono la stessa struttura interna (sezione 3), la stessa convenzione di frontmatter, lo stesso workflow Git. Aggiungere un terzo wiki (`wiki-<nome>`) è una replica meccanica.
+
+**Infrastruttura condivisa.** Gitea, Quartz, nginx, Authelia, `mcp-docgen` sono servizi orizzontali usati da tutti i wiki. Una sola istanza di ciascuno.
+
+**Flat-file + Git + Claude Code + Obsidian.** Niente database applicativo nel percorso di produzione del contenuto.
+
+### Cosa NON fa
+
+- Non è un DMS con workflow di approvazione / firma digitale integrata
+- Non sostituisce il gestionale contabile
+- Non fa OCR né ricerca semantica (eventualmente integrabili in futuro)
+- Non supporta edit concorrente multi-utente (un operatore, Adriano)
+- Non espone interfaccia di editing da browser (edit solo da Obsidian/Claude Code)
+
+---
+
+## 2. Componenti del sistema
+
+### Mappa macro-componenti
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│  DESKTOP (questa macchina, Linux Ubuntu)                                │
+│                                                                         │
+│  /home/adriano/Documenti/Git_XYZ/Documentale/                           │
+│                                                                         │
+│  ├─ wiki-personale/       ← vault locale (clone git Gitea)              │
+│  ├─ wiki-aziendale/       ← vault locale (clone git Gitea)              │
+│  ├─ wiki-<altro>/         ← futuri wiki, stessa struttura               │
+│  │                                                                      │
+│  ├─ wiki-personale-assets/    ← binari fuori git, rsync → VPS           │
+│  ├─ wiki-aziendale-assets/    ← idem                                    │
+│  │                                                                      │
+│  └─ mcp-docgen/           ← sorgente MCP server (repo separato)         │
+│                                                                         │
+│  Strumenti:                                                             │
+│    • Obsidian: un vault per ogni wiki (switch-vault funzione nativa)    │
+│    • Claude Code: opera su cartelle del wiki selezionato                │
+│    • Obsidian Git plugin: auto-push per ciascun vault                   │
+│    • systemd timer: rsync asset → VPS                                   │
+└─────────────────────────────────────────────────────────────────────────┘
+          │         ▲            │         ▲             │         ▲
+          │ git     │            │ git     │             │ rsync   │
+          ▼         │            ▼         │             ▼         │
+┌─────────────────────────────────────────────────────────────────────────┐
+│  VPS Hostinger                                                          │
+│                                                                         │
+│  ┌───────────────────────────────────────────────────────────────────┐  │
+│  │  Gitea (un'istanza, più repo)                                     │  │
+│  │    • adriano/wiki-personale.git   + post-receive hook             │  │
+│  │    • adriano/wiki-aziendale.git   + post-receive hook             │  │
+│  │      ↓ (hook → quartz build per ciascun wiki)                     │  │
+│  └───────────────────────────────────────────────────────────────────┘  │
+│                                                                         │
+│  ┌───────────────────────────────────────────────────────────────────┐  │
+│  │  Quartz build pipeline (una config per wiki)                      │  │
+│  │    /opt/quartz-personale/  → build → /var/www/personale/          │  │
+│  │    /opt/quartz-aziendale/  → build → /var/www/aziendale/          │  │
+│  └───────────────────────────────────────────────────────────────────┘  │
+│                                                                         │
+│  ┌─────────────────────┐    ┌─────────────────────┐                     │
+│  │ /var/www/assets/    │    │ mcp-docgen (Docker) │                     │
+│  │  ├─ personale/      │    │ condiviso tra wiki  │                     │
+│  │  └─ aziendale/      │    │ FastMCP HTTP        │                     │
+│  └─────────────────────┘    │ OpenRouter LLM      │                     │
+│                             └─────────────────────┘                     │
+│                                                                         │
+│  ┌───────────────────────────────────────────────────────────────────┐  │
+│  │  nginx + Authelia (SSO unico)                                     │  │
+│  │    personale.<dominio>    → /var/www/personale/                   │  │
+│  │    aziendale.<dominio>    → /var/www/aziendale/                   │  │
+│  │    <w>.<dominio>/assets/  → /var/www/assets/<w>/                  │  │
+│  │    gitea.<dominio>        → Gitea web UI                          │  │
+│  │    docgen.<dominio>       → mcp-docgen (solo API key, no SSO)     │  │
+│  └───────────────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────────────┘
+          ▲
+          │ HTTPS + SSO (TOTP 2FA)
+┌─────────────────────────────────────────────────────────────────────────┐
+│  MOBILE Android                                                         │
+│   • Obsidian app + Git plugin → un vault per ciascun wiki               │
+│   • Chrome/Firefox → consultazione siti sotto-dominio                   │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### Ruoli sintetici
+
+| Componente | Dove vive | Ruolo | Molteplicità | Stato |
+|---|---|---|---|---|
+| `wiki-<nome>/` | Desktop + Gitea VPS | Vault markdown versionato | **Per wiki** | Da creare |
+| `wiki-<nome>-assets/` | Desktop + `/var/www/assets/<nome>/` | Binari | **Per wiki** | Da creare |
+| `mcp-docgen` | VPS Docker | Generazione documenti formali | **Condiviso** | Design pronto |
+| Gitea | VPS | Git remote | Unica istanza, più repo | Da installare |
+| Quartz | VPS | SSG per wiki | **Un'istanza per wiki** (config + output separati) | Da configurare |
+| nginx | VPS | Reverse proxy | Unico | Da configurare |
+| Authelia | VPS | SSO 2FA | Unico | Da configurare |
+
+---
+
+## 3. Struttura di un singolo wiki
+
+Tutti i wiki (personale, aziendale, futuri) seguono **identica struttura interna**. Schema isomorfico a `Cerbero_Brain` (raw immutabile + wiki LLM-managed), esteso con `documents/` per output prodotti e `areas/` come MOC tematiche.
+
+```
+wiki-<nome>/
+├── CLAUDE.md                      # schema e regole del vault
+├── README.md                      # intro human-readable
+├── index.md                       # catalogo content-oriented
+├── log.md                         # timeline append-only
+│
+├── raw/                           # IMMUTABILE
+│   ├── comunicazioni_in/          # mail ricevute, PEC, lettere
+│   ├── documenti_ricevuti/        # markdown ricevuti, allegati testuali
+│   ├── notes/                     # appunti grezzi, voice-to-text (manual)
+│   └── riunioni/                  # trascrizioni riunioni grezze (STT futuro)
+│
+└── wiki/                          # LLM-managed
+    ├── documents/                 # documenti prodotti da Adriano
+    │   ├── preventivi/            # (prevalente in wiki-aziendale)
+    │   ├── relazioni/
+    │   ├── verbali_riunione/      # note sintetiche strutturate da raw/riunioni/
+    │   └── comunicazioni_out/
+    │
+    ├── entities/                  # clienti, fornitori, persone, studi
+    │
+    ├── concepts/                  # procedure, template, framework
+    │
+    ├── areas/                     # MOC tematici
+    │
+    └── syntheses/                 # analisi trasversali
+```
+
+### Contenuto tipico per wiki
+
+| Wiki | Contenuto prevalente |
+|---|---|
+| **wiki-personale** | Idee, note personali, journal, documentazione privata (salute, famiglia, viaggi), inventari personali, consapevolezza finanziaria personale (distinta da Milito/Cerbero) |
+| **wiki-aziendale** | Clienti, preventivi, relazioni, fatturazione, commercialista, fornitori, procedure aziendali, contratti, verbali riunione con clienti |
+
+### Convenzioni comuni
+
+Frontmatter, naming, wikilink, log.md append-only, index content-oriented: **identici** per tutti i wiki. Vedi esempi completi in §5 e §6.
+
+Ogni wiki ha il **proprio `CLAUDE.md`** locale al suo root, che specifica:
+- Identità del wiki (es. "wiki personale di Adriano")
+- Dominio applicativo (cosa ci va, cosa non ci va)
+- Eventuali regole peculiari (es. wiki-aziendale richiede che ogni `documents/preventivi/` menzioni un `entities/cliente`)
+
+Claude Code, quando opera dentro un wiki, carica il suo `CLAUDE.md` contestuale (comportamento nativo).
+
+---
+
+## 4. Configurazione multi-wiki
+
+### Registro dei wiki
+
+File di riferimento: `/home/adriano/Documenti/Git_XYZ/Documentale/wikis.yaml`
+
+```yaml
+wikis:
+  - name: personale
+    local_path: wiki-personale
+    assets_path: wiki-personale-assets
+    remote: git@gitea.<dominio>:adriano/wiki-personale.git
+    publish_domain: personale.<dominio>
+    quartz_source: /opt/quartz-personale
+    quartz_output: /var/www/personale
+    vps_assets_path: /var/www/assets/personale
+
+  - name: aziendale
+    local_path: wiki-aziendale
+    assets_path: wiki-aziendale-assets
+    remote: git@gitea.<dominio>:adriano/wiki-aziendale.git
+    publish_domain: aziendale.<dominio>
+    quartz_source: /opt/quartz-aziendale
+    quartz_output: /var/www/aziendale
+    vps_assets_path: /var/www/assets/aziendale
+```
+
+Questo file è la **single source of truth** per scripting (sync, backup, provisioning nuovo wiki).
+
+### Aggiungere un terzo wiki
+
+Procedura meccanica:
+
+1. Aggiungi voce a `wikis.yaml`
+2. `gitea` web UI → crea repo privato `adriano/wiki-<nuovo>`
+3. Script di provisioning (da scrivere in Fase 2): `./tools/new-wiki.sh <nome>` che:
+   - Crea struttura cartelle locale
+   - Inizializza git, primo commit, push
+   - Installa plugin Obsidian Git nel nuovo vault
+   - Crea config Quartz per il nuovo sotto-dominio
+   - Aggiunge virtual host nginx + cert Let's Encrypt
+   - Registra hook post-receive Gitea
+
+### Scripting condiviso
+
+Gli script operativi (backup, sync asset, provisioning) iterano su `wikis.yaml`, zero duplicazione.
+
+---
+
+## 5. Flusso Git end-to-end
+
+### Remote e branch
+
+- **Gitea self-hosted**: un server, più repo (uno per wiki)
+- **Branch unico `main`** per repo (no PR, uso personale)
+- **Commit strategy**: piccoli e frequenti, messaggi descrittivi (`doc(acme): preventivo v1`, `ingest: PEC 2026-04-15`, `refactor: split concepts/procedura-x`)
+
+### Flusso desktop → Gitea (per ciascun wiki)
+
+1. Edit markdown (Obsidian o Claude Code) nella cartella del wiki
+2. **Obsidian Git plugin** in quel vault (configurato per-wiki):
+   - Auto-commit + push ogni 10 min
+   - Messaggio commit: `auto: {{date}}`
+3. Gitea riceve push sul repo del wiki
+4. Hook `post-receive` triggera **`quartz build` specifico di quel wiki** → `/var/www/<wiki>/`
+5. nginx serve la nuova versione di `<wiki>.<dominio>`
+
+### Flusso mobile Android → Gitea
+
+Per ciascun vault (un vault per wiki) su Obsidian mobile:
+
+1. Apri vault → pull manuale (bottone Git plugin)
+2. Edita
+3. Commit & Push manuale
+
+### Fallback systemd timer (desktop)
+
+Sotto `~/.config/systemd/user/`, un timer + service generici parametrizzati per-wiki:
+
+```ini
+# vault-sync@.service (template unit)
+[Service]
+Type=oneshot
+WorkingDirectory=/home/adriano/Documenti/Git_XYZ/Documentale/%i
+ExecStart=/usr/bin/git add -A
+ExecStart=/bin/sh -c 'git diff --cached --quiet || git commit -m "auto: $(date -Iseconds)"'
+ExecStart=/usr/bin/git pull --rebase --autostash
+ExecStart=/usr/bin/git push
+```
+
+Abilita per wiki: `systemctl --user enable vault-sync@wiki-personale.timer`, `vault-sync@wiki-aziendale.timer`.
+
+### Asset sync (per wiki)
+
+Un timer rsync per wiki:
+```bash
+rsync -az --delete \
+  /home/adriano/Documenti/Git_XYZ/Documentale/wiki-<nome>-assets/ \
+  adriano@vps:/var/www/assets/<nome>/
+```
+
+Script unico che itera `wikis.yaml` e lancia rsync per ciascuno.
+
+---
+
+## 6. Integrazione con `mcp-docgen`
+
+`mcp-docgen` è **condiviso** tra tutti i wiki. Il template selezionato determina il formato; la destinazione di archiviazione la scegli (o la suggerisce Claude Code) al momento della generazione.
+
+### Tool MCP
+
+| Tool | Uso |
+|---|---|
+| `template_create/update/delete/list/get` | Gestione template |
+| `document_generate` | Genera markdown formale |
+
+### Configurazione Claude Code
+
+`~/.claude/.mcp.json`:
+```json
+{
+  "mcpServers": {
+    "docgen": {
+      "type": "http",
+      "url": "https://docgen.<dominio>/mcp",
+      "headers": { "Authorization": "Bearer <API_KEY>" }
+    }
+  }
+}
+```
+
+### Template iniziali (condivisi, taggati per wiki di provenienza tipica)
+
+| Template | Wiki tipico | Uso |
+|---|---|---|
+| `preventivo-commerciale` | aziendale | Preventivi clienti |
+| `relazione-audit` | aziendale | Relazioni tecniche |
+| `lettera-formale` | aziendale o personale | Comunicazioni ufficiali |
+| `nota-commercialista` | aziendale | Comunicazioni al commercialista |
+| `verbale-riunione` | aziendale | Verbali post-riunione (anche da STT futuro) |
+| `journal-entry` | personale | Entry diario personale strutturato |
+
+I template hanno `tags: [wiki:aziendale]` o `[wiki:personale]` nel frontmatter per filtrarli in `template_list`, ma nulla impedisce di usarli cross-wiki se serve.
+
+### Flusso "draft → formal → archivio in wiki corretto"
+
+```
+1. Adriano: "Prepara preventivo per Acme in wiki-aziendale"
+
+2. Claude Code (contesto wiki-aziendale):
+   a) Legge wiki-aziendale/wiki/entities/Acme_SRL.md
+   b) Legge wiki-aziendale/wiki/concepts/Template_Preventivo.md
+   c) Prepara bozza grezza
+   d) Invoca mcp__docgen__document_generate:
+        template = "preventivo-commerciale"
+        content  = bozza
+        variables = {cliente: "Acme SRL", piva: "...", ...}
+   e) Salva output in wiki-aziendale/wiki/documents/preventivi/YYYY-MM-DD_Acme_v1.md
+   f) Aggiorna wiki-aziendale/wiki/entities/Acme_SRL.md (storico preventivi)
+   g) Aggiorna wiki-aziendale/index.md e log.md
+
+3. Adriano rivede in Obsidian (vault aziendale)
+
+4. Finale → export PDF in wiki-aziendale-assets/clienti/Acme_SRL/
+          → aggiorna status: sent
+          → rsync asset → VPS
+          → Git auto-push → Quartz rebuild → visibile su aziendale.<dominio>
+```
+
+### Quando NON usare `mcp-docgen`
+
+- Note grezze, appunti, idee → markdown diretto
+- Ingest di materiale ricevuto (va in `raw/` as-is)
+- Template operativi interni (scritti manualmente in `concepts/`)
+
+---
+
+## 7. Pubblicazione web — Quartz multi-site
+
+### Approccio
+
+**Un'istanza Quartz per wiki.** Stessa versione del codice sorgente Quartz, configurazione separata, output separato, sotto-dominio separato.
+
+### Layout VPS
+
+```
+/opt/quartz-personale/
+  ├── quartz.config.ts     # title: "Wiki Personale", baseUrl: "personale.<dominio>"
+  ├── content/             # git checkout di wiki-personale (pull nel hook)
+  └── ...
+
+/opt/quartz-aziendale/
+  ├── quartz.config.ts     # title: "Wiki Aziendale", baseUrl: "aziendale.<dominio>"
+  ├── content/
+  └── ...
+
+/var/www/personale/        # output Quartz personale
+/var/www/aziendale/        # output Quartz aziendale
+/var/www/assets/
+  ├── personale/
+  └── aziendale/
+```
+
+### Hook `post-receive` (per repo)
+
+```bash
+#!/bin/bash
+# hooks/post-receive di wiki-<nome>.git
+set -e
+WIKI_NAME=<nome>
+WORKDIR=/opt/quartz-$WIKI_NAME
+
+cd $WORKDIR/content
+git pull --rebase
+
+cd $WORKDIR
+npx quartz build --output /var/www/$WIKI_NAME/
+
+nginx -t && systemctl reload nginx
+```
+
+### nginx per wiki
+
+Un virtual host per sotto-dominio:
+
+```nginx
+server {
+    listen 443 ssl http2;
+    server_name personale.<dominio>;
+
+    include /etc/nginx/authelia-location.conf;
+
+    location / {
+        include /etc/nginx/authelia-authrequest.conf;
+        root /var/www/personale;
+        try_files $uri $uri/ $uri.html =404;
+    }
+
+    location /assets/ {
+        include /etc/nginx/authelia-authrequest.conf;
+        alias /var/www/assets/personale/;
+    }
+
+    ssl_certificate /etc/letsencrypt/live/<dominio>/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/<dominio>/privkey.pem;
+}
+# Stesso identico schema per aziendale.<dominio>, sostituendo "personale" con "aziendale"
+```
+
+### CSS print condiviso
+
+Custom media-query `@media print` in un file `print.scss` copiato in entrambe le config Quartz, o mantenuto in un submodule Git condiviso.
+
+---
+
+## 8. Accesso da Android
+
+Consultazione (90%) via browser sui sotto-domini. Edit occasionale via Obsidian mobile con **un vault separato per wiki**.
+
+### Obsidian mobile multi-vault
+
+Obsidian mobile supporta N vault. Ciascun vault è una cartella separata (che clona il repo Gitea del wiki corrispondente).
+
+Setup per wiki:
+1. Aggiungi vault in Obsidian Android (crea cartella locale, es. `/storage/emulated/0/Obsidian/wiki-personale/`)
+2. Installa community plugin "Obsidian Git"
+3. Clone via plugin: URL `https://gitea.<dominio>/adriano/wiki-personale.git` + **token personale Gitea** (scope: repo read/write)
+4. Configurazione plugin:
+   - Auto-pull on load: on
+   - Auto-push: off
+   - Commit message: `mobile: {{date}}`
+
+Ripeti per `wiki-aziendale`.
+
+### Switch vault
+
+Dalla home di Obsidian Android, icona a destra → lista vault → tap per switchare. Comodo e veloce.
+
+### Limiti
+
+- Android non supporta sync in background → azione manuale pull/commit/push
+- Asset binari: via browser sotto-dominio, non Obsidian
+- Evitare edit contemporaneo mobile vs desktop (pull sempre prima di editare)
+
+---
+
+## 9. Storage degli asset binari
+
+### Struttura per wiki (identica)
+
+```
+wiki-<nome>-assets/
+├── clienti/         # (prevalente in aziendale)
+├── commercialista/  # (prevalente in aziendale)
+├── personale/       # (prevalente in personale)
+└── ...
+```
+
+### Sync
+
+Systemd timer desktop, uno script, itera `wikis.yaml`:
+```bash
+for wiki in $(yq e '.wikis[].name' wikis.yaml); do
+  src="$HOME/Documenti/Git_XYZ/Documentale/wiki-$wiki-assets/"
+  dst="adriano@vps:/var/www/assets/$wiki/"
+  rsync -az --delete "$src" "$dst"
+done
+```
+
+### Referenziazione dal markdown
+
+Link assoluto al sotto-dominio del wiki:
+```markdown
+PDF firmato: [preventivo v1](https://aziendale.<dominio>/assets/clienti/Acme_SRL/2026-04-22_preventivo_v1_firmato.pdf)
+```
+
+---
+
+## 10. Autenticazione e sicurezza
+
+### Authelia SSO condiviso
+
+**Una sola istanza Authelia** protegge tutti i sotto-domini dei wiki e gli asset:
+
+- `personale.<dominio>`, `aziendale.<dominio>`, `<nuovo>.<dominio>`
+- Session cookie valido cross-subdomain (`Domain=<dominio>`)
+- Utente unico `adriano` con TOTP 2FA (Aegis/Google Authenticator)
+- Una login per aprire qualsiasi wiki
+
+### Eccezioni
+
+- `gitea.<dominio>` → login Gitea separato (con 2FA)
+- `docgen.<dominio>` → solo API key header, non per browser umano
+
+### ACL per wiki
+
+Se in futuro vuoi dare accesso a `aziendale.<dominio>` a un collaboratore senza dare accesso a `personale.<dominio>`:
+
+Authelia configurable ACL:
+```yaml
+access_control:
+  rules:
+    - domain: personale.<dominio>
+      policy: two_factor
+      subject: "user:adriano"
+    - domain: aziendale.<dominio>
+      policy: two_factor
+      subject: ["user:adriano", "user:collaboratore"]
+```
+
+Nessun lavoro extra nell'architettura — feature already-there.
+
+### TLS
+
+Let's Encrypt con cert SAN per tutti i sotto-domini, rinnovo automatico `certbot` + `systemd timer`.
+
+---
+
+## 11. Backup e disaster recovery
+
+### Cosa salvare (per wiki)
+
+| Asset | Criticità | Strategia |
+|---|---|---|
+| Repo Git Gitea (per wiki) | **Alta** | Clone desktop + Gitea VPS + snapshot settimanale |
+| Asset binari (per wiki) | **Alta** (legale in aziendale) | Desktop + VPS + backup offsite weekly |
+| `mcp-docgen` template + SQLite | Media | Snapshot volume Docker |
+| Config VPS (nginx, Authelia, Quartz, Gitea) | Media | Repo `ops-vps` versionato |
+
+### Strategia 3-2-1 (per wiki)
+
+Ogni wiki ha la sua catena 3-2-1 indipendente. Script che itera `wikis.yaml` su VPS:
+
+```bash
+# systemd timer offsite-backup.timer, weekly
+for wiki in $(yq e '.wikis[].name' /etc/documentale/wikis.yaml); do
+  rsync -az --delete \
+    /var/www/$wiki/ /var/www/assets/$wiki/ \
+    /var/opt/gitea/repositories/adriano/wiki-$wiki.git/ \
+    offsite:backups/documentale/$wiki/$(date +%Y-W%V)/
+done
+```
+
+### Retention differenziabile per wiki
+
+Potenzialmente (configurabile in `wikis.yaml`):
+- `aziendale`: retention 10+ anni (documentazione legale)
+- `personale`: retention 3 anni rotating (ok da revisione)
+
+Implementabile con policy distinte per destinazione offsite (non critico al MVP).
+
+### DR procedure
+
+Documentata per ciascun wiki in `wiki-<nome>/wiki/concepts/DR_Procedure.md`. Procedura standard:
+1. Repo perduto → clone da Gitea, riparti
+2. Gitea VPS perduta → restore volume da offsite, repush da desktop
+3. Tutto perduto → restore da offsite (perdita max 1 settimana)
+
+---
+
+## 12. Setup iniziale — fasi implementative
+
+**Strategia:** porta **un solo wiki** fino in fondo (pipeline completa funzionante) prima di clonare la configurazione per il secondo. Così validi il modello end-to-end, poi replichi.
+
+**Scelta del wiki pilota:** raccomando `wiki-aziendale` perché:
+- Ha esigenze più concrete e immediate (preventivi, commercialista)
+- Forza a testare `mcp-docgen` (template formali)
+- Il pattern è più impegnativo, quindi se funziona lì il personale è banale
+
+### Fase 1 — `wiki-aziendale` locale funzionante
+
+**Deliverable:** vault locale usabile, Claude Code e Obsidian felici, commit git a repo locale.
+
+1. Crea `Documentale/wikis.yaml` con solo `aziendale`
+2. Crea struttura `wiki-aziendale/` (raw/ + wiki/{documents,entities,concepts,areas,syntheses})
+3. Scrivi `wiki-aziendale/CLAUDE.md` (regole wiki aziendale)
+4. `README.md`, `index.md`, `log.md` iniziali
+5. `git init` + primo commit
+6. Crea `wiki-aziendale-assets/`
+7. Apri in Obsidian come vault, verifica rendering
+8. Documento di prova (cliente fittizio + preventivo prova)
+
+### Fase 2 — Gitea su VPS + sync wiki-aziendale
+
+**Deliverable:** vault sincronizzato desktop ↔ Gitea.
+
+1. Docker Gitea su VPS, `gitea.<dominio>` (TLS)
+2. Crea repo `adriano/wiki-aziendale` (privato)
+3. SSH key desktop → Gitea, token mobile Gitea
+4. `git remote add` dal desktop, primo push
+5. Plugin Obsidian Git → configura auto-push 10 min
+6. Test round-trip
+7. Systemd timer fallback
+
+### Fase 3 — `mcp-docgen` su VPS + integrazione Claude Code
+
+**Deliverable:** workflow "bozza → formale → archivio" in wiki-aziendale.
+
+1. Implementa `mcp-docgen` (vedi suo design doc in `mcp-docgen/`)
+2. Deploy Docker su `docgen.<dominio>`
+3. Aggiungi a `~/.claude/.mcp.json`
+4. Crea template: `preventivo-commerciale`, `relazione-audit`, `lettera-formale`, `nota-commercialista`, `verbale-riunione`
+5. Test end-to-end dal wiki-aziendale
+
+### Fase 4 — Quartz + nginx + TLS per wiki-aziendale
+
+**Deliverable:** `aziendale.<dominio>` consultabile via HTTPS (senza auth stringente ancora, o basic auth temporanea).
+
+1. Node su VPS, clone Quartz in `/opt/quartz-aziendale/`
+2. Config Quartz (title, baseUrl)
+3. CSS print
+4. Hook `post-receive` in `wiki-aziendale.git` → `quartz build`
+5. nginx virtual host + cert Let's Encrypt
+6. Test da browser desktop + mobile
+
+### Fase 5 — Authelia SSO + protezione
+
+**Deliverable:** `aziendale.<dominio>` privato, login con TOTP.
+
+1. Docker Authelia su VPS
+2. Utente `adriano` con password + TOTP
+3. nginx `auth_request` per dominio wiki e `/assets/`
+4. Verifica login desktop + mobile
+
+### Fase 6 — Asset sync + backup offsite (wiki-aziendale)
+
+**Deliverable:** asset sync, backup 3-2-1 attivo.
+
+1. Systemd timer rsync asset → VPS
+2. nginx serve `/var/www/assets/aziendale/` (con auth)
+3. Test link dai markdown
+4. Backup offsite weekly (Hetzner Storagebox / B2)
+
+### Fase 7 — Obsidian Android per wiki-aziendale
+
+**Deliverable:** edit mobile funzionante.
+
+1. Obsidian app + plugin Obsidian Git
+2. Clone repo via plugin, token Gitea
+3. Test edit mobile → push → verifica desktop
+
+### Fase 8 — Replica per `wiki-personale`
+
+**Deliverable:** secondo wiki operativo end-to-end.
+
+Usando script `tools/new-wiki.sh` (scritto in Fase 2 o qui):
+1. Aggiungi `personale` a `wikis.yaml`
+2. Crea struttura locale
+3. Crea repo Gitea
+4. Provisioning Quartz + nginx + cert (wildcard o nuova SAN)
+5. Clone vault Obsidian desktop + mobile
+6. Testa ciclo completo
+
+Replica banale — se Fasi 1-7 hanno validato il modello.
+
+---
+
+## 13. Estensioni future pianificate
+
+Funzionalità **non** implementate in Fasi 1-8 ma già predisposte nell'architettura. Vengono sviluppate in fasi successive con i propri design + implementation doc.
+
+### 13.1 Pipeline STT — trascrizione riunioni
+
+**Scenario:** hai una riunione con cliente Acme, registri audio (Zoom, dittafono, registratore telefono). Vuoi che l'audio diventi automaticamente una bozza di verbale nel `wiki-aziendale`, pronta per revisione.
+
+**Architettura prevista:**
+
+```
+┌─────────────────┐      ┌─────────────────┐      ┌──────────────────┐
+│  Registrazione  │      │  Upload a VPS   │      │  STT service VPS │
+│  (mobile,       │─────▶│  (curl / web    │─────▶│  (Whisper.cpp    │
+│   registratore, │      │   form / SFTP)  │      │   faster-whisper │
+│   Zoom export)  │      │                 │      │   Docker)        │
+└─────────────────┘      └─────────────────┘      └────────┬─────────┘
+                                                           │
+                                                           ▼
+                         ┌─────────────────────────────────────────┐
+                         │  Inbox Service (nuovo microservizio VPS)│
+                         │                                         │
+                         │  ├─ Riceve trascrizione grezza          │
+                         │  ├─ Normalizza a markdown + frontmatter │
+                         │  │    (source: stt, target_wiki: ?)     │
+                         │  ├─ Salva in /var/lib/inbox/drafts/     │
+                         │  └─ Espone API:                         │
+                         │     GET  /drafts                         │
+                         │     GET  /drafts/{id}                    │
+                         │     DELETE /drafts/{id} (consume)        │
+                         └────────────────┬────────────────────────┘
+                                          │
+                                          ▼
+                         ┌────────────────────────────────────────┐
+                         │  Claude Code desktop                   │
+                         │  (comando /ingest-inbox o cron locale) │
+                         │                                        │
+                         │  ├─ GET /drafts                        │
+                         │  ├─ Per ciascun draft:                 │
+                         │  │    • Identifica target wiki         │
+                         │  │      (euristica + conferma Adriano) │
+                         │  │    • Eventuale mcp-docgen format    │
+                         │  │      con template verbale-riunione  │
+                         │  │    • Commit in wiki/                │
+                         │  │      documents/verbali_riunione/    │
+                         │  │    • DELETE /drafts/{id}            │
+                         │  └─ Push git                           │
+                         └────────────────────────────────────────┘
+```
+
+**Componenti nuovi da creare:**
+
+- **`stt-service`**: container Docker con `faster-whisper` o `whisper.cpp`, API FastAPI minimale (`POST /transcribe` con audio → text). Modello `large-v3` per italiano.
+- **`inbox-service`**: microservizio FastAPI che:
+  - Riceve audio (multipart) o testo
+  - Orchestra STT se audio
+  - Salva draft markdown in `/var/lib/inbox/drafts/<uuid>.md`
+  - Espone API REST protetta da API key
+- **Claude Code skill `/ingest-inbox`**: comando che pollicia l'inbox, ingeriste nel wiki corretto con conferma utente
+
+**Predisposizione nell'architettura corrente:**
+
+- La cartella `raw/riunioni/` è **già prevista** nella struttura wiki (§3)
+- Il template `verbale-riunione` è **già previsto** tra i template iniziali `mcp-docgen` (§6)
+- nginx può ospitare `inbox.<dominio>` a un sottodomino aggiuntivo (Authelia o API key)
+- Nessuna ristrutturazione necessaria quando arriva — è un'aggiunta pulita
+
+**Fase stimata:** Fase 9 dopo completamento di Fase 8 e uso reale per qualche settimana.
+
+### 13.2 Bot Telegram — ingest da mobile
+
+**Scenario:** sei in giro, hai un'idea o vuoi registrare una nota vocale. Mandi messaggio (audio o testo) al tuo bot Telegram → finisce nel wiki corretto.
+
+**Architettura prevista:**
+
+```
+┌─────────────┐         ┌─────────────────┐       ┌───────────────┐
+│  Telegram   │────────▶│  Bot Telegram   │──────▶│ Inbox Service │
+│  (tu, mobile│ message │  (python-tele-  │  POST │ (stessa API   │
+│   vocale o  │         │   gram-bot su   │       │  di §13.1)    │
+│   testo)    │         │   VPS Docker)   │       └───────────────┘
+└─────────────┘         └─────────────────┘               │
+                                                          ▼
+                                                  (stessa pipeline
+                                                   STT se audio,
+                                                   poi drafts/,
+                                                   poi Claude Code
+                                                   desktop ingerisce)
+```
+
+**Logica minima del bot:**
+
+- Riceve messaggio da chat autorizzata (whitelist per telegram ID)
+- Se audio → forward a `stt-service`, poi `inbox-service`
+- Se testo → forward diretto a `inbox-service` come markdown con `source: telegram`
+- Risponde a Adriano: "Draft creato: ID xxx, target wiki non specificato"
+- Opzionale: comandi slash tipo `/wiki aziendale` prima del messaggio per hint di targeting
+
+**Predisposizione nell'architettura corrente:**
+
+- È già disponibile il server MCP `cerbero-telegram` (vedi `~/.claude/.mcp.json` nel progetto Cerbero). Può essere riutilizzato o duplicato per questo uso, o si scrive un bot dedicato
+- `inbox-service` previsto in §13.1 è la colonna portante di entrambe le integrazioni
+- Nessuna ristrutturazione necessaria
+
+**Fase stimata:** Fase 10 dopo §13.1.
+
+### 13.3 Principio comune
+
+Entrambe le estensioni seguono il pattern **"sorgente esterna → inbox VPS → Claude Code desktop ingerisce"**. Questo mantiene:
+
+- **Single point of ingest** — `inbox-service` è l'unico che parla col VPS per contenuti nuovi
+- **Claude Code resta autorevole** — decide target wiki, applica format, scrive il commit, mantiene coerenza
+- **Evita commit diretti al wiki da VPS** — la VPS non ha mai bisogno di scrivere nei repo (solo leggerli per Quartz build e Gitea)
+
+### 13.4 Altre estensioni meno urgenti
+
+Tracciato qui per non dimenticarle:
+
+- **OCR automatico** di scansioni ricevute (Tesseract + preprocessing, spinge output in inbox)
+- **Ricerca semantica** del vault (integrazione con `claude-mem` o sistema embedding dedicato)
+- **Auto-export PDF** per ogni `wiki/documents/` con status `final` (tramite pandoc + template LaTeX/typst)
+- **Firma digitale** integrata in workflow preventivi (via CADES o firma semplice qualificata)
+- **Collaboratore** su `wiki-aziendale` (già supportato da ACL Authelia §10)
+
+---
+
+## 14. Decisioni e rationale
+
+### Perché separazione forte (repo per wiki)
+
+- Separazione netta di ciclo di vita, backup, retention, ACL
+- Possibilità di hand-off di un wiki senza esporre l'altro
+- Un wiki rotto / corrotto non tocca gli altri
+- Tradeoff accettato: niente wikilink cross-wiki — si duplica volentieri quando un soggetto è davvero rilevante per entrambi
+
+### Perché Quartz e non SilverBullet/Wiki.js
+
+- Nessun runtime app su VPS per il publish → zero superficie d'attacco extra
+- Wikilink Obsidian nativi + backlinks + graph
+- Velocità: pagine statiche
+- Tradeoff: no edit da browser — accettato perché edit è da Obsidian/Claude Code
+
+### Perché asset fuori git
+
+- Git si gonfia con binari senza delta utili
+- rsync separato → repo leggero per sempre
+
+### Perché Authelia SSO unificato
+
+- Una login per tutti i sotto-domini (cookie cross-subdomain)
+- 2FA nativo
+- ACL configurabili future (multi-utente parziale)
+
+### Perché portare un wiki fino in fondo prima di replicare
+
+- Valida l'intero stack end-to-end (meno rischio)
+- Script di provisioning (`new-wiki.sh`) nasce dall'esperienza del primo setup
+- Replica in Fase 8 è meccanica
+
+### Perché `inbox-service` come hub per STT e Telegram
+
+- Un solo endpoint normalizza l'ingest (API, storage, retention)
+- Ogni sorgente futura (email-to-wiki, web-clipper, ecc.) riutilizza lo stesso hub
+- Claude Code desktop resta il solo autorizzato a scrivere nei repo wiki
+
+### Cose lasciate fuori scope (consapevolmente, MVP)
+
+- OCR automatico
+- Ricerca semantica / embeddings
+- Auto-export PDF
+- Firma digitale integrata
+- Workflow di approvazione multi-step
+- Multi-utente pieno
+
+---
+
+## Note finali
+
+Design **incrementale** e **decomponibile**:
+
+- Fase 1 sola → vault locale usabile (valore immediato)
+- Fasi 1-4 → vault sincronizzato + pubblicato
+- Fasi 1-7 → wiki-aziendale completo end-to-end
+- Fase 8 → secondo wiki operativo
+- Fase 9-10 → STT + Telegram (estensioni future)
+
+Ogni fase è stop accettabile. Ogni fase avrà il proprio implementation plan prodotto da **writing-plans** quando ci arriveremo.
+
+Cuore concettuale invariato: flat markdown + git + Claude Code + Obsidian + Quartz. Multi-wiki è replica di questo cuore, isolata per dominio. Estensioni future (STT, Telegram) sono aggiunte senza riarchitettura.