# Governance per pubblicazione documentale template-driven ## Scopo Questa nota definisce la governance minima per produrre documenti aziendali rigenerabili da Markdown verso DOCX, PDF o HTML mantenendo coerenza visiva tra modifiche successive. La regola centrale e' separare contenuto, stile, asset sorgente e artefatti finali. Template e profili sono opzionali: vanno usati quando serve controllare brand, stile o layout, mentre conversioni semplici possono restare Pandoc plain. ## Regola Di Separazione Un documento pubblicabile deve distinguere: - **Markdown sorgente**: contenuto e struttura semantica; - **template opzionali**: regole di stile per uno o piu' target; - **asset master**: SVG e sorgenti grafici originali; - **asset derivati**: PNG/JPG generati automaticamente; - **artefatti finali**: DOCX, PDF, HTML rigenerabili. Gli artefatti finali non sono la fonte di verita'. Se possibile, non vanno modificati manualmente. ## Markdown Il Markdown deve restare leggibile e portabile: - usare titoli, paragrafi, liste, tabelle semplici e immagini; - dichiarare le dimensioni delle immagini quando influenzano il layout; - evitare path assoluti; - evitare formattazione manuale specifica di Word o PDF; - non duplicare contenuti per target diversi. ## Template E Profili I template devono essere organizzati per profilo visuale o classe di documento. I profili riusabili devono vivere dentro la skill Office, cosi' restano disponibili anche fuori da questo repository: Struttura consigliata: ```text skills/mcp-office-expert/assets/templates// profile.json reference.docx reference-seed.md pdf-template.tex html-template.html ``` Esempi di profili futuri: - `sophia`; - `technical-report`; - `customer-deliverable`; - `internal-note`. Il profilo `sophia`, quando presente, deve usare i colori del logo come palette primaria: `#00205b` e `#ffffff`, con eventuali opacita' o tinte derivate solo se necessarie al contrasto. Nel repository MCP il profilo Sophia bundled si trova in: ```text skills/mcp-office-expert/assets/templates/sophia/ ``` Gli asset ufficiali del brand Sophia devono essere recuperati dalla libreria SVG interna: ```text skills/svg/assets/libraries/sophia-brand/ ``` Le copie in cartelle documento, per esempio `docs/brochure/assets/`, sono da considerare copie di lavoro o derivati specifici del documento, non fonte master. ## DOCX Il DOCX deve essere generato tramite Pandoc usando `reference_doc_path` quando serve coerenza tipografica. Il reference DOCX governa: - stili dei titoli; - font e dimensioni; - interlinea e spaziature; - liste; - citazioni; - margini, intestazioni e piedi pagina. Per compatibilita' con Word, gli SVG possono essere convertiti in PNG derivati durante la pipeline DOCX. Gli SVG restano comunque master. ## PDF Il PDF deve preferire asset vettoriali. Usare SVG diretti quando il motore PDF li supporta; se la pipeline Pandoc/LaTeX non gestisce SVG diretto, esportare gli SVG master in PDF vettoriali e usare questi derivati nel Markdown destinato al PDF. Con Pandoc, verificare sempre lo stato runtime prima della conversione. Per documenti aziendali e Unicode, `xelatex` e' il motore consigliato quando disponibile. Se un PDF minimale funziona ma fallisce solo il documento con SVG, trattare il caso come problema di conversione asset, non come semplice assenza del motore PDF. Il template PDF deve dichiarare lingua e regole di sillabazione. Per documenti Sophia con molti termini tecnici o inglesi, la policy raccomandata e' disabilitare la sillabazione automatica e aumentare lo spazio di emergenza per evitare spezzature arbitrarie come `repos-itory`. ## Asset Gli SVG e gli asset sorgente vanno mantenuti in una cartella stabile, per esempio: ```text docs//assets/ ``` Per brochure o altri deliverable separati dalla governance, preferire una cartella dedicata: ```text docs/brochure/assets/ ``` Per asset aziendali Sophia, la fonte master raccomandata e': ```text skills/svg/assets/libraries/sophia-brand/ ``` I PNG o JPG derivati devono essere rigenerabili. Non vanno considerati sorgente editoriale. Per SVG creati o modificati: - validare XML/SVG; - verificare palette e contrasto; - fare QA visiva quando cambia la resa; - usare helper geometrici della skill `svg` quando servono forme parametriche o ripetibili. ## Pipeline Minima 1. Modificare Markdown sorgente e asset master. 2. Validare eventuali template e asset. 3. Rigenerare derivati necessari al target. 4. Generare DOCX con template DOCX se richiesto, altrimenti plain. 5. Generare PDF con template o metadata PDF se richiesto, altrimenti plain. 6. Verificare presenza immagini e leggibilita' del testo. 7. Indicizzare la documentazione rilevante con docs-mcp quando deve restare ricercabile. ## Script Diretto La skill Office espone uno script Node riusabile da repository esterni: ```bash node skills/mcp-office-expert/tools/publish-markdown-document.js --list-profiles --pretty node skills/mcp-office-expert/tools/publish-markdown-document.js --source --profile sophia --pretty node skills/mcp-office-expert/tools/publish-markdown-document.js --source --no-template --targets docx --pretty ``` Lo script legge il `profile.json` quando viene usato un profilo, oppure lavora senza template con `--no-template`. Prepara derivati asset specifici per DOCX e PDF, richiama Pandoc, produce gli artefatti finali e scrive un report JSON con output, conversioni asset e controlli eseguiti. La verifica visiva PDF renderizza la prima pagina quando sono disponibili `pdftoppm`, `mutool` o `magick`. Per ambienti esterni senza PATH configurato, accetta anche `--pandoc `, `--inkscape ` e `--pdf-engine `. Le dipendenze esterne sono gestite dall'installer repository: `xelatex` e' opzionale ma raccomandato per PDF aziendali completi, Unicode e formule matematiche; `poppler` abilita la verifica visuale tramite `pdftoppm`. ## Evoluzione Questa governance resta intenzionalmente leggera. Un tool MCP dedicato ha senso solo dopo stabilizzazione di: - naming dei profili; - template disponibili; - script di export; - controlli automatici; - casi limite ricorrenti. Fino ad allora, il modello raccomandato e' skill + script locale + documentazione indicizzata.