@noeva/analytics-core 0.3.2 → 0.4.0

package/contenuto/assets/vista.js

@@ -0,0 +1,252 @@
+// Modulo condiviso delle dashboard NOEVA Analytics. La sorgente e' lib/pagina/vista.js;
+// la copia in apps/assets/ la scrive lib/snapshot/installa.sh --pagina. Non modificare la copia.
+/* La Vista dichiarata (standard §6.2, punto 9; NW-1265): una dashboard con i suoi
+ * filtri e l'eventuale fuoco, su uno snapshot preciso. La pagina la dichiara in
+ * due posti, scritti entrambi da qui con lo stesso oggetto:
+ *
+ *  - la riga di provenienza visibile (al posto di #pie e #prov scritti a mano):
+ *    data del dato, data e ora assolute dello snapshot con l'eta' accanto,
+ *    fonte, regola di lettura, la frase propria del progetto e il pulsante
+ *    «Copia la citazione». La legge chi guarda e la legge get_page_text;
+ *  - il blocco <script type="application/json" id="noeva-vista">, riscritto a
+ *    ogni cambio di filtri o di fuoco: lo leggono contesto() di commento.js
+ *    (chat, commento guidato, presentazione) e Claude nel browser integrato.
+ *
+ * Niente meta (sono statici e non seguono i filtri) e niente oggetti globali.
+ *
+ *   const vista = montaVista({
+ *     dashboard: "vendite",                       // l'id della pagina
+ *     meta: D.meta,                               // snapshot.json
+ *     filtri: { es: "Esercizio", vista: { nome: "Periodo", etichetta: (v) => NOMI[v] } },
+ *     provenienza: { sorgente: "il DWH del cliente", regola: "regole in knowledge/rules/general.md" },
+ *     frase: "…",                                 // facoltativa, HTML del progetto
+ *     dove: "#pie",                               // la riga; senza, #provenienza (o una nuova in fondo)
+ *   });
+ *
+ * I filtri sono le chiavi dell'URL (sincronizzaUrl): la chiave fa fede,
+ * l'etichetta leggibile sta accanto. Una chiave non dichiarata in `filtri` non
+ * e' un filtro (?commento=prova, ?r=2); senza `filtri` lo e' ogni chiave. Il
+ * fuoco e' quello che la pagina mostra in #fuoco (montaFuoco).
+ *
+ * La vista si riscrive da sola quando sincronizzaUrl scrive l'URL e quando il
+ * fuoco cambia (l'evento "noeva-vista" di tema.js, e #fuoco osservato); una
+ * pagina che cambia la vista per altre vie chiama vista.aggiorna().
+ */
+import { t, LINGUA, LOCALE } from "./lingua.js";
+import { PROGETTO } from "./progetto.js";
+import { etaSnapshot } from "./tema.js";
+
+export const ID_BLOCCO = "noeva-vista";
+export const FUSO = "Europe/Rome";
+export const EVENTO = "noeva-vista";
+
+/* --- la vista come dato ------------------------------------------------------------ */
+
+const pulito = (s) => String(s ?? "").replace(/[▸▾✕]/g, "").replace(/\s+/g, " ").trim();
+
+/* I filtri dalla query dell'URL, nell'ordine dei dichiarati (poi gli altri, se
+ * non ce ne sono di dichiarati). `dichiarati`: { chiave: "Nome" } oppure
+ * { chiave: { nome, etichetta(valore) } }. */
+export function filtriDaUrl(query, dichiarati = null) {
+  const p = new URLSearchParams(query);
+  const chiavi = dichiarati ? Object.keys(dichiarati).filter((k) => p.has(k)) : [...new Set(p.keys())];
+  return chiavi.map((chiave) => {
+    const valore = p.get(chiave);
+    const d = dichiarati?.[chiave];
+    const nome = (typeof d === "string" ? d : d?.nome) || chiave;
+    const etichetta = (typeof d === "object" && d?.etichetta ? d.etichetta(valore) : null) ?? valore;
+    return { chiave, valore, nome: String(nome), etichetta: String(etichetta) };
+  });
+}
+
+/* "6 novembre 2026" da "2026-11-06" (o da un timestamp: conta il giorno scritto). */
+export function giornoLungo(iso, locale = LOCALE) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(String(iso ?? ""));
+  if (!m) return String(iso ?? "");
+  return new Intl.DateTimeFormat(locale, { timeZone: "UTC", day: "numeric", month: "long", year: "numeric" })
+    .format(new Date(Date.UTC(+m[1], +m[2] - 1, +m[3])));
+}
+
+/* "8 novembre 2026, 22:21": data e ora assolute dello snapshot, nel fuso di Roma. */
+export function dataOraAssoluta(iso, locale = LOCALE) {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return String(iso ?? "");
+  const giorno = new Intl.DateTimeFormat(locale, { timeZone: FUSO, day: "numeric", month: "long", year: "numeric" }).format(d);
+  const ora = new Intl.DateTimeFormat(locale, { timeZone: FUSO, hour: "2-digit", minute: "2-digit", hourCycle: "h23" }).format(d);
+  return `${giorno}, ${ora}`;
+}
+
+/* La vista: tutto quello che la pagina dichiara, in un oggetto solo. */
+export function componiVista({ progetto, dashboard, lingua, url, filtri = [], fuoco = null, meta = {}, provenienza = {}, eta }) {
+  const generato = meta.generato ?? null;
+  const e = eta || (generato ? etaSnapshot(generato) : null);
+  return {
+    progetto: { id: progetto?.id ?? null, nome: progetto?.nome ?? null },
+    dashboard: { id: dashboard?.id ?? null, titolo: dashboard?.titolo ?? null },
+    lingua,
+    url,
+    filtri,
+    fuoco,
+    data_del_dato: meta.data_del_dato ? String(meta.data_del_dato).slice(0, 10) : null,
+    snapshot: {
+      generato,
+      data_ora: generato ? dataOraAssoluta(generato) : null,
+      fuso: FUSO,
+      eta: e?.testo ?? null,
+      stantio: e?.stantio ?? null,
+    },
+    provenienza: {
+      sorgente: provenienza.sorgente || null,
+      regola: provenienza.regola || t("letta in sola lettura attraverso il modello semantico NOEVA"),
+    },
+  };
+}
+
+/* Le voci della provenienza, le stesse per la riga visibile e per la citazione:
+ * cosi' le due non possono dire cose diverse. */
+export function vociProvenienza(v) {
+  const voci = [];
+  if (v.data_del_dato) voci.push({ nome: t("Data del dato"), testo: giornoLungo(v.data_del_dato) });
+  if (v.snapshot?.data_ora) voci.push({ nome: t("Snapshot"), testo: v.snapshot.data_ora, eta: v.snapshot.eta, stantio: v.snapshot.stantio });
+  if (v.provenienza?.sorgente) voci.push({ nome: t("Fonte"), testo: v.provenienza.sorgente });
+  if (v.provenienza?.regola) voci.push({ nome: t("Regola di lettura"), testo: v.provenienza.regola });
+  return voci;
+}
+
+const testoVoce = (x) => `${x.nome}: ${x.testo}${x.eta ? ` (${x.eta})` : ""}`;
+
+/* La citazione: la vista in testo, da incollare in una mail o in una richiesta a 4D. */
+export function testoCitazione(v) {
+  const righe = [[v.progetto?.nome, v.dashboard?.titolo].filter(Boolean).join(" · ")];
+  if (v.url) righe.push(v.url);
+  righe.push(`${t("Filtri")}: ${v.filtri?.length
+    ? v.filtri.map((f) => `${f.nome}: ${f.etichetta} (${f.chiave}=${f.valore})`).join(" · ")
+    : t("nessuno")}`);
+  if (v.fuoco) righe.push(`${t("A fuoco")}: ${v.fuoco.etichetta}`);
+  righe.push(vociProvenienza(v).map(testoVoce).join(" · "));
+  return righe.filter(Boolean).join("\n");
+}
+
+/* Il contenuto del blocco: JSON con "<" scritto <, cosi' resta un blocco
+ * solo anche quando la pagina si serializza (un "</script>" nei dati lo chiuderebbe). */
+export const jsonBlocco = (v) => JSON.stringify(v, null, 1).replace(/</g, "\\u003c");
+
+/* La vista dichiarata dalla pagina, o null se la pagina non ne ha una. */
+export function leggiVista(doc = document) {
+  const el = doc.getElementById(ID_BLOCCO);
+  if (!el) return null;
+  try { return JSON.parse(el.textContent); } catch { return null; }
+}
+
+/* --- la pagina --------------------------------------------------------------------- */
+
+async function copia(testo) {
+  // come la copia delle tabelle (tema.js): navigator.clipboard vuole un contesto
+  // sicuro e un gesto recente; se manca si ripiega sul metodo vecchio
+  if (navigator.clipboard?.writeText) {
+    try { return await navigator.clipboard.writeText(testo); } catch { /* si ripiega */ }
+  }
+  const ta = document.createElement("textarea");
+  ta.value = testo;
+  ta.style.cssText = "position:fixed;top:-1000px;opacity:0";
+  document.body.append(ta);
+  ta.select();
+  const fatto = document.execCommand("copy");
+  ta.remove();
+  if (!fatto) throw new Error("copia non riuscita");
+}
+
+function fuocoDellaPagina() {
+  const el = document.getElementById("fuoco");
+  if (!el || el.hidden) return null;
+  const etichetta = pulito(el.querySelector("b")?.textContent);
+  return etichetta ? { etichetta } : null;
+}
+
+export function montaVista({ dashboard, meta = {}, filtri = null, provenienza = {}, frase = null, dove = null, titolo = null }) {
+  const riga = (typeof dove === "string" ? document.querySelector(dove) : dove)
+    || document.getElementById("provenienza") || nuovaRiga();
+  riga.classList.add("provenienza");
+
+  let blocco = document.getElementById(ID_BLOCCO);
+  if (!blocco) {
+    blocco = document.createElement("script");
+    blocco.type = "application/json";
+    blocco.id = ID_BLOCCO;
+    riga.after(blocco);
+  }
+
+  const voci = document.createElement("span");
+  voci.className = "pv-voci";
+  const propria = document.createElement("span");
+  propria.className = "pv-frase";
+  const btn = document.createElement("button");
+  btn.type = "button";
+  btn.className = "pv-copia";
+  btn.textContent = t("Copia la citazione");
+  btn.title = t("Copia la vista in testo: dashboard, indirizzo, filtri, fuoco, dati e provenienza");
+  // separatori scritti, non solo margini: get_page_text legge il testo, non il CSS
+  riga.replaceChildren(voci, propria, " ", btn);
+
+  let attuale = null, torna = null;
+  function aggiorna() {
+    attuale = componiVista({
+      progetto: { id: meta.progetto || PROGETTO.id, nome: PROGETTO.nome },
+      dashboard: { id: dashboard, titolo: titolo || pulito(document.querySelector(".topbar h1")?.textContent) || pulito(document.title) },
+      lingua: LINGUA,
+      url: location.href,
+      filtri: filtriDaUrl(location.search, filtri),
+      fuoco: fuocoDellaPagina(),
+      meta,
+      provenienza,
+    });
+    blocco.textContent = jsonBlocco(attuale);
+    voci.replaceChildren(...vociProvenienza(attuale).flatMap((x, i) => {
+      const nome = document.createElement("b");
+      nome.textContent = `${x.nome}:`;
+      const parti = [...(i ? [" · "] : []), nome, ` ${x.testo}`];
+      if (x.eta) {
+        const eta = document.createElement("span");
+        eta.className = x.stantio ? "pv-eta stantio" : "pv-eta";
+        eta.textContent = `(${x.eta})`;
+        parti.push(" ", eta);
+      }
+      return parti;
+    }));
+    const f = typeof frase === "function" ? frase(attuale) : frase;
+    propria.innerHTML = f ? ` · ${f}` : "";
+    propria.hidden = !f;
+    return attuale;
+  }
+
+  btn.onclick = async () => {
+    try {
+      await copia(testoCitazione(aggiorna()));
+      btn.textContent = t("Citazione copiata");
+    } catch {
+      btn.textContent = t("Copia non riuscita");
+    }
+    clearTimeout(torna);
+    torna = setTimeout(() => { btn.textContent = t("Copia la citazione"); }, 2000);
+  };
+
+  document.addEventListener(EVENTO, aggiorna);
+  addEventListener("popstate", aggiorna);
+  // il fuoco lo disegna la pagina in #fuoco: anche quando lo toglie con Esc o col suo ✕
+  const elFuoco = document.getElementById("fuoco");
+  if (elFuoco && typeof MutationObserver === "function") {
+    new MutationObserver(aggiorna).observe(elFuoco, { attributes: true, attributeFilter: ["hidden"], childList: true, subtree: true, characterData: true });
+  }
+  // l'eta' dello snapshot cresce anche a pagina ferma
+  setInterval(aggiorna, 5 * 60_000).unref?.();
+
+  aggiorna();
+  return { aggiorna, vista: () => attuale };
+}
+
+function nuovaRiga() {
+  const p = document.createElement("p");
+  p.id = "provenienza";
+  (document.querySelector("#pagina") || document.querySelector("main") || document.body).append(p);
+  return p;
+}

package/contenuto/assets/voce.js

@@ -0,0 +1,127 @@
+// Modulo condiviso delle dashboard NOEVA Analytics. La sorgente e' lib/pagina/voce.js;
+// la copia in apps/assets/ la scrive lib/snapshot/installa.sh --pagina. Non modificare la copia.
+/* La voce del commento guidato sul sito pubblicato (NW-1091).
+ *
+ * Il catalogo e la voce li ha il contenitore (lib/analytics/voce.js, rotta
+ * ai/voci): la chiave ElevenLabs sta li', in un secret. Qui si sceglie la voce
+ * e si chiede l'mp3 di un testo.
+ *
+ *   montaSceltaVoce("#voce")        nella home del progetto: per ogni lingua le
+ *                                   voci, con «Ascolta»; non compare se il
+ *                                   contenitore non ha la voce online
+ *   await voceOnline()              true se il contenitore fa la voce
+ *   voceScelta("it")                l'id scelto per la lingua, o null
+ *   await parla(testo, { pagina })  l'URL (blob:) dell'mp3, dalla voce scelta
+ *
+ * La scelta e' di chi guarda: resta nel suo browser, per progetto e per lingua
+ * (`<progetto>-voce-it`, `<progetto>-voce-en`), come la lingua ricordata.
+ */
+import { rotta } from "./servizio.js";
+import { t, LINGUA } from "./lingua.js";
+import { PROGETTO } from "./progetto.js";
+
+const NOMI_LINGUE = { it: "Italiano", en: "English" };
+const PROVA = {
+  it: (nome) => `Buongiorno, sono ${nome}. Racconterò questa dashboard tappa per tappa.`,
+  en: (nome) => `Hello, I'm ${nome}. I'll walk you through this dashboard step by step.`,
+};
+const chiave = (lingua) => `${PROGETTO.id}-voce-${lingua}`;
+const esc = (s) => String(s ?? "").replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]));
+
+let _catalogo = null;
+/* Il catalogo del contenitore, o null dove la voce online non c'e' (sul Mac
+ * con il solo serve-app.py, su un server statico, o senza ELEVENLABS_API_KEY). */
+export function catalogoVoci() {
+  _catalogo ||= fetch(rotta("ai/voci"), { cache: "no-cache" })
+    .then(async (r) => (r.ok && (r.headers.get("content-type") || "").includes("json") ? r.json() : null))
+    .then((c) => (c && c.lingue ? c : null))
+    .catch(() => null);
+  return _catalogo;
+}
+
+export async function voceOnline() {
+  return Boolean(await catalogoVoci());
+}
+
+export function voceScelta(lingua = LINGUA) {
+  try { return localStorage.getItem(chiave(lingua)) || null; } catch { return null; }
+}
+
+export function scegliVoce(lingua, id) {
+  try {
+    if (id) localStorage.setItem(chiave(lingua), id);
+    else localStorage.removeItem(chiave(lingua));
+  } catch { /* senza memoria vale la predefinita */ }
+}
+
+/* L'mp3 del testo letto dalla voce scelta (o dalla predefinita della lingua),
+ * come URL da dare a un <audio>. L'errore porta il messaggio del contenitore. */
+export async function parla(testo, { lingua = LINGUA, voce = voceScelta(lingua), pagina = "" } = {}) {
+  const r = await fetch(rotta("ai/voci"), {
+    method: "POST", headers: { "content-type": "application/json" },
+    body: JSON.stringify({ testo, lingua, ...(voce ? { voce } : {}), ...(pagina ? { pagina } : {}) }),
+  });
+  if (!r.ok || !(r.headers.get("content-type") || "").includes("audio")) {
+    let j = {};
+    try { j = await r.json(); } catch { /* non JSON */ }
+    throw new Error(j.errore || `ai/voci: ${r.status}`);
+  }
+  return URL.createObjectURL(await r.blob());
+}
+
+/* La scelta della voce, nella home del progetto. Si monta in un contenitore
+ * qualunque (`dove`: selettore o elemento); resta vuoto e nascosto se il
+ * contenitore Analytics non fa la voce. */
+export async function montaSceltaVoce(dove) {
+  const el = typeof dove === "string" ? document.querySelector(dove) : dove;
+  if (!el) return null;
+  el.hidden = true;
+  const cat = await catalogoVoci();
+  if (!cat) return null;
+
+  // prima la lingua della pagina, poi le altre
+  const lingue = Object.keys(cat.lingue).sort((a, b) => (a === LINGUA ? -1 : b === LINGUA ? 1 : 0));
+  el.classList.add("scelta-voce");
+  el.innerHTML = `
+    <h3>${t("La voce del commento")}</h3>
+    <p class="nota">${t("Chi racconta le dashboard nel commento guidato, per ogni lingua. La scelta resta in questo browser.")}</p>
+    ${lingue.map((l) => {
+      const scelta = voceScelta(l) || cat.predefinite?.[l];
+      return `<div class="riga-voce" data-lingua="${esc(l)}">
+        <label for="voce-${esc(l)}">${esc(NOMI_LINGUE[l] || l)}</label>
+        <select id="voce-${esc(l)}">${cat.lingue[l].map((v) => `<option value="${esc(v.id)}"${v.id === scelta ? " selected" : ""}>${esc(v.nome)} · ${esc(v.descrizione?.[LINGUA] || v.descrizione?.it || "")}</option>`).join("")}</select>
+        <button type="button" data-ascolta="${esc(l)}">${t("Ascolta")}</button>
+        <span class="stato-voce" role="status"></span>
+      </div>`;
+    }).join("")}`;
+  el.hidden = false;
+
+  const audio = new Audio();
+  let corrente = null;
+  for (const riga of el.querySelectorAll(".riga-voce")) {
+    const l = riga.dataset.lingua;
+    const sel = riga.querySelector("select");
+    const stato = riga.querySelector(".stato-voce");
+    sel.addEventListener("change", () => {
+      // la predefinita non si scrive: se il catalogo cambia, chi non ha scelto la segue
+      scegliVoce(l, sel.value === cat.predefinite?.[l] ? null : sel.value);
+      stato.textContent = t("salvata");
+    });
+    riga.querySelector("[data-ascolta]").addEventListener("click", async () => {
+      const v = cat.lingue[l].find((x) => x.id === sel.value);
+      audio.pause();
+      stato.textContent = t("preparo…");
+      try {
+        const url = await parla(PROVA[l]?.(v?.nome || "") || v?.nome || "", { lingua: l, voce: sel.value, pagina: "home" });
+        if (corrente) URL.revokeObjectURL(corrente);
+        corrente = url;
+        audio.src = url;
+        await audio.play();
+        stato.textContent = "";
+      } catch (e) {
+        stato.textContent = t("voce non disponibile: {errore}", { errore: e.message || e });
+      }
+    });
+  }
+  return el;
+}

package/contenuto/lib/mcp-locale/cartella/CLAUDE.md

@@ -1,39 +1,18 @@
+<!-- noeva-analytics-cartella:inizio — blocco della cartella consegnata, lo riscrive l'aggiornamento di NOEVA -->
 # NOEVA Analytics · {{cliente}}
 
-Questa cartella serve a interrogare i dati di {{cliente}} con Claude. Chi la usa sono gli
-analisti di {{cliente}}: rispondi in italiano, con numeri verificabili, senza gergo tecnico se
-non lo chiedono.
+Questa cartella collega Claude ai dati di {{cliente}}, su questo PC. Come si risponde a
+una domanda sui dati lo dice il plugin `noeva-analytics` (skill `analisi`,
+`/noeva-analytics:analisi`): se in questa sessione il plugin non c'è, dillo all'analista,
+che lo fa installare a 4D. Qui ci sono solo il collegamento e le regole di sicurezza.
 
-## Da dove vengono i dati
+## Il collegamento
 
 Il server MCP **{{server}}** legge in sola lettura il database di produzione: {{cosa}}.
-È il modello semantico NOEVA: tabelle con nomi leggibili (`fatture_vendita`, `versamenti`,
-`giacenze`, …) e le regole di business già scritte dentro o accanto.
-
 Server SQL {{host}}, raggiungibile solo dalla rete di {{cliente}} (o in VPN).
 
-## Come si risponde a una domanda sui dati
-
-1. A inizio sessione chiama `get_instructions`: sono le regole di business (quali documenti
-   sono fatturato, quale data usare, i segni degli importi, le regole P1-P14 della produzione
-   e M1-M10 del magazzino). Valgono più di quello che sembra ovvio dai nomi delle colonne.
-2. `list_models` e `describe_model` per le tabelle e le colonne; `recall_queries` per le
-   domande simili già risolte.
-3. Scrivi la SQL sul modello, validala con `dry_run`, eseguila con `run_sql`.
-4. Aggrega nel database (SUM, COUNT, GROUP BY) invece di scaricare righe, e metti sempre
-   un `limit`: è il database di produzione, in orario di lavoro lo usa anche l'ERP.
-5. Nella risposta di' periodo, filtri e regole applicate. Se l'analista lo chiede, mostra
-   la query.
-
-## Cosa non fare
-
-- Non inventare né stimare cifre. Se una query fallisce o un dato manca, dillo.
-- Non collegarti al database per altre strade (sqlcmd, script, ODBC): solo {{server}}.
-- Non scrivere mai la password in chat, in un file o in un comando. Sta nella variabile
-  d'ambiente `{{password_env}}` dell'utente Windows e la legge solo il server.
-- Non modificare la cartella `noeva/`: è il motore (eseguibile, modello, regole). Le regole
-  si leggono in `noeva/modello/knowledge/rules/`, si cambiano solo con un aggiornamento
-  di NOEVA.
+Ripiego offline (snapshot delle dashboard): {{server_snapshot}}. È spento; si accende da
+`/mcp` solo se l'analista lo chiede.
 
 ## Se {{server}} non risponde
 
@@ -48,5 +27,12 @@ Dice cosa manca: la password (`imposta-password.ps1`), il driver "ODBC Driver 18
 Server", la rete verso {{host}}. Spiegalo all'analista con le istruzioni di `LEGGIMI.md`.
 Dopo aver impostato la password bisogna chiudere e riaprire Claude Code.
 
-Ripiego offline (snapshot delle dashboard): {{server_snapshot}}. È spento; si accende da
-`/mcp` solo se l'analista lo chiede, e le risposte devono dire che il dato è dello snapshot.
+## Sicurezza
+
+- Ai dati si arriva solo attraverso {{server}}: niente sqlcmd, script, ODBC, né letture
+  dirette dei file sotto `noeva/`.
+- La password non va mai in chat, in un file o in un comando. Sta nella variabile
+  d'ambiente `{{password_env}}` dell'utente Windows e la legge solo il server.
+- La cartella `noeva/` è il motore (eseguibile, modello, regole): si legge, non si
+  modifica. Cambia solo con un aggiornamento di NOEVA.
+<!-- noeva-analytics-cartella:fine -->

package/contenuto/lib/mcp-locale/costruisci.py

@@ -23,7 +23,8 @@ Scrive in dist/mcp-locale/:
   noeva-<id>/           LA CARTELLA DA CONSEGNARE
     .mcp.json           i due server: noeva-<id> (vivo) e noeva-<id>-snapshot
     .claude/            settings.json (server abilitati, permessi)
-    CLAUDE.md           le istruzioni per Claude (cartella/CLAUDE.md, compilato)
+    CLAUDE.md           collegamento e sicurezza per Claude, fra marcatori (cartella/CLAUDE.md;
+                        il metodo sta nel plugin noeva-analytics)
     LEGGIMI.md          l'installazione, per chi installa
     imposta-password.ps1  chiede la password e la mette nella variabile dell'utente
     installa.ps1        installa o aggiorna la cartella passo per passo, con l'esito finale
@@ -100,7 +101,8 @@ def pyproject(dest: pathlib.Path, nome: str, versione: str, deps: list[str]) ->
 
 
 # --- il modello dello snapshot -------------------------------------------------
-def modello_snapshot(sorgente: pathlib.Path, dest: pathlib.Path, catalogo: str, manifesto: dict) -> list[dict]:
+def modello_snapshot(sorgente: pathlib.Path, dest: pathlib.Path, catalogo: str, manifesto: dict,
+                     conf: dict) -> list[dict]:
     """Un progetto Wren su DuckDB dallo snapshot delle dashboard (ADR 0003)."""
     conf = yaml.safe_load((sorgente / "snapshot.yml").read_text(encoding="utf-8"))
     estrazioni = {e["nome"]: e for e in conf.get("estrazioni", [])}
@@ -133,6 +135,7 @@ def modello_snapshot(sorgente: pathlib.Path, dest: pathlib.Path, catalogo: str,
         shutil.copy2(sorgente / "knowledge" / "knowledge.yml", k / "knowledge.yml")
     for f in sorted((sorgente / "knowledge" / "rules").glob("*.md")):
         shutil.copy2(f, k / "rules" / f.name)
+    scheda.scrivi(sorgente, k / "rules", conf)
     date = [f"- {manifesto.get('data_del_dato')}: vendite, rete, clienti, agenti (DWH)"]
     for g, info in (manifesto.get("gruppi") or {}).items():
         date.append(f"- {info.get('data_del_dato')}: {', '.join(info.get('estrazioni', []))} (gruppo {g})")
@@ -172,6 +175,10 @@ fattura, un movimento, un dato dopo le date sopra), dirlo invece di stimarlo.
 sys.path.insert(0, str(QUI.parent / "modello"))
 from consegna import leggi_config  # noqa: E402
 from consegna import modello_di_consegna as modello_vivo  # noqa: E402
+# Le istruzioni di initialize sono quelle che il gateway da' per lo stesso progetto
+# (lib/modello/istruzioni.json, NW-1286); la scheda e' la stessa del modello pubblicato.
+from istruzioni import istruzioni_snapshot, istruzioni_vivo  # noqa: E402
+import scheda  # noqa: E402
 
 
 def progetto(arg: str, config: str | None = None) -> tuple[pathlib.Path, str, dict, pathlib.Path]:
@@ -253,7 +260,7 @@ def argomenti_pyinstaller(nome: str, build: pathlib.Path) -> list:
         # Il modello si cerca anche nel repository e su R2 (server/modello_locale.py),
         # e dal repository si compila con le trasformazioni di lib/modello/consegna.py.
         "--paths", QUI / "server", "--paths", QUI.parent / "modello",
-        "--hidden-import", "modello_locale", "--hidden-import", "consegna",
+        "--hidden-import", "modello_locale", "--hidden-import", "consegna", "--hidden-import", "scheda",
         QUI / "server" / "noeva_mcp.py",
     ]
 
@@ -280,22 +287,6 @@ def compila(modello: str, valori: dict) -> str:
     return testo
 
 
-def istruzioni_snapshot(cliente: str, manifesto: dict) -> str:
-    return (
-        f"NOEVA Analytics per {cliente}, SNAPSHOT delle dashboard (DWH al {manifesto.get('data_del_dato')}). "
-        "Prima di scrivere SQL leggi get_instructions: la regola 00-snapshot dice quali tabelle esistono e "
-        "a che data e' il dato. Dillo sempre nella risposta: e' il ripiego offline, non il database vivo."
-    )
-
-
-def istruzioni_vivo(cliente: str, s: dict) -> str:
-    return (
-        f"NOEVA Analytics per {cliente}, dal vivo sul database di produzione ({s.get('cosa', '')}), in sola "
-        "lettura. Prima di scrivere SQL leggi get_instructions e describe_model: le regole di business stanno "
-        "li'. Valida con dry_run, poi run_sql con un limit; aggrega nel database invece di scaricare righe."
-    )
-
-
 def main(argv: list[str]) -> int:
     ap = argparse.ArgumentParser()
     ap.add_argument("progetto", help="project-<id> del monorepo, o il repository del progetto (con analytics.json)")
@@ -346,7 +337,7 @@ def main(argv: list[str]) -> int:
     sorgenti = {}
     for k, s in vive.items():
         rel = "modello" if len(vive) == 1 else f"modello-{k}"
-        conta = modello_vivo(sorgente, noeva / rel, s)
+        conta = modello_vivo(sorgente, noeva / rel, s, conf)
         print(f"  {k}: {conta['rinominati']} riferimenti rinominati, {conta['catalogo']} modelli col catalogo "
               f"{s.get('catalogo_senza_nome') or '-'}")
         uv_run(amb, "wren", "context", "build", "--path", noeva / rel)
@@ -354,13 +345,13 @@ def main(argv: list[str]) -> int:
             "tipo": "mssql", "server": s["server"], "cosa": s.get("cosa", ""), "progetto": rel,
             **{c: s[c] for c in ("host", "porta", "database", "utente", "password_env", "driver", "opzioni")
                if c in s},
-            "istruzioni": istruzioni_vivo(cliente, s),
+            "istruzioni": istruzioni_vivo(ident),
             "verifiche": s.get("verifiche") or {},
             # Il modello aggiornato dal contenitore, se il progetto lo pubblica (ADR 0005, punto 6).
             **({"modello_r2": {"progetto": ident, **conf["modello_r2"]}} if conf.get("modello_r2") else {}),
         }
     if con_snapshot:
-        modelli = modello_snapshot(sorgente, noeva / "snapshot" / "modello", ident, manifesto)
+        modelli = modello_snapshot(sorgente, noeva / "snapshot" / "modello", ident, manifesto, conf)
         costruisci_duckdb(amb, noeva / "snapshot" / "dati" / f"{ident}.duckdb",
                           sorgente / "apps" / "dati", [m["name"] for m in modelli])
         uv_run(amb, "wren", "context", "build", "--path", noeva / "snapshot" / "modello")
@@ -368,7 +359,7 @@ def main(argv: list[str]) -> int:
         sorgenti["snapshot"] = {
             "tipo": "duckdb", "server": sn.get("server", f"{nome}-snapshot"),
             "cosa": "lo snapshot delle dashboard, offline", "progetto": "snapshot/modello",
-            "dati": "snapshot/dati", "istruzioni": istruzioni_snapshot(cliente, manifesto),
+            "dati": "snapshot/dati", "istruzioni": istruzioni_snapshot(ident, manifesto.get("data_del_dato")),
             "verifiche": sn.get("verifiche") or {},
         }
     (noeva / "noeva.json").write_text(json.dumps({"nome": nome, "sorgenti": sorgenti},

package/contenuto/lib/modello/consegna.py

@@ -15,6 +15,9 @@ Lo usano in tre (ADR 0005, punto 6), e per questo sta in un modulo solo:
 - il servizio locale (lib/mcp-locale/server/noeva_mcp.py), che quando Claude Code
   e' aperto nel repository compila il modello che sta li', non quello pubblicato.
 
+E nel modello consegnato scrive la scheda del progetto, knowledge/rules/00-progetto.md
+(scheda.py, NW-1286): generata qui, arriva uguale per tutte e tre le strade.
+
 Le trasformazioni:
 
     rinomina: {erp_restore: erp_prod}     <db>.dbo. nella SQL dei modelli
@@ -30,6 +33,8 @@ import shutil
 
 import yaml
 
+import scheda
+
 # Cosa del repository fa parte del modello: il resto (apps/, scripts/, docs/) no.
 FILE_MODELLO = ["wren_project.yml", "relationships.yml", "models", "knowledge"]
 # Le chiavi delle trasformazioni: il resto della configurazione di consegna
@@ -70,9 +75,12 @@ def leggi_consegna(radice: pathlib.Path) -> dict:
     return trasformazioni(leggi_config(radice))
 
 
-def modello_di_consegna(sorgente: pathlib.Path, dest: pathlib.Path, conf: dict) -> dict:
+def modello_di_consegna(sorgente: pathlib.Path, dest: pathlib.Path, conf: dict,
+                        config: dict | None = None) -> dict:
     """Scrive in `dest` il modello di `sorgente` con le trasformazioni di `conf`.
 
+    `config` e' la configurazione intera (consegna.yml, default quella di
+    `sorgente`): la scheda ne legge cliente, sorgenti e contatto.
     Restituisce i conteggi delle trasformazioni, che chi costruisce stampa."""
     rinomina = conf.get("rinomina") or {}
     senza_nome = conf.get("catalogo_senza_nome")
@@ -119,6 +127,7 @@ def modello_di_consegna(sorgente: pathlib.Path, dest: pathlib.Path, conf: dict)
         if (k / cartella).is_dir():
             shutil.copytree(k / cartella, dest / "knowledge" / cartella,
                             ignore=shutil.ignore_patterns(".gitkeep"))
+    scheda.scrivi(sorgente, dest / "knowledge" / "rules", config)
     return conta
 
 

package/contenuto/lib/modello/istruzioni.json

@@ -0,0 +1,14 @@
+{
+  "_commento": [
+    "Le istruzioni che il server MCP di un progetto da' all'initialize, uguali in locale",
+    "(lib/mcp-locale, le scrive costruisci.py in noeva.json) e dal gateway (lib/gateway, il",
+    "Worker riscrive la risposta di initialize). Una fonte sola, letta da istruzioni.py e da",
+    "istruzioni.js: i segnaposto sono {progetto} (l'id del registro e di analytics.json) e,",
+    "per lo snapshot, {data} (la data del dato). Cio' che e' vero del progetto (cliente,",
+    "cosa coprono i dati, dashboard, contatto) sta nella scheda knowledge/rules/00-progetto.md,",
+    "non qui (NW-1261)."
+  ],
+  "nome": "noeva-{progetto}",
+  "vivo": "NOEVA Analytics, progetto {progetto}: i dati del cliente dal vivo, in sola lettura. Prima di scrivere SQL leggi get_instructions: la regola 00-progetto dice di chi sono i dati, cosa coprono, dove stanno le dashboard e chi e' il contatto in 4D; le altre regole e describe_model dicono cosa significano i numeri. Valida con dry_run, poi run_sql con un limit; aggrega nel database invece di scaricare righe.",
+  "snapshot": "NOEVA Analytics, progetto {progetto}: SNAPSHOT delle dashboard (dato al {data}), il ripiego offline, non il database vivo. Prima di scrivere SQL leggi get_instructions: la regola 00-snapshot dice quali tabelle esistono e a che data e' il dato, la 00-progetto di chi sono i dati e dove stanno le dashboard. Dillo sempre nella risposta: e' il ripiego offline."
+}

package/contenuto/lib/modello/istruzioni.py

@@ -0,0 +1,48 @@
+"""Le istruzioni di initialize del server MCP di un progetto, da istruzioni.json (NW-1286).
+
+Il testo sta in istruzioni.json, una fonte sola per i due trasporti: qui lo legge
+lib/mcp-locale/costruisci.py, che lo scrive in noeva.json per il servizio locale;
+lib/gateway/istruzioni.js lo legge per il Worker, che riscrive la risposta di
+initialize dei server Wren dietro il gateway. lib/gateway/test/istruzioni.test.js
+prova che i due escono uguali.
+
+    python3 lib/modello/istruzioni.py <progetto> [vivo|snapshot] [--data <data>]
+"""
+from __future__ import annotations
+
+import json
+import pathlib
+import sys
+
+TESTI = json.loads((pathlib.Path(__file__).resolve().parent / "istruzioni.json").read_text(encoding="utf-8"))
+
+
+def _riempi(modello: str, **valori: str) -> str:
+    for k, v in valori.items():
+        modello = modello.replace("{" + k + "}", str(v))
+    return modello
+
+
+def nome_server(progetto: str) -> str:
+    return _riempi(TESTI["nome"], progetto=progetto)
+
+
+def istruzioni_vivo(progetto: str) -> str:
+    return _riempi(TESTI["vivo"], progetto=progetto)
+
+
+def istruzioni_snapshot(progetto: str, data: str | None) -> str:
+    return _riempi(TESTI["snapshot"], progetto=progetto, data=data or "l'ultimo aggiornamento delle dashboard")
+
+
+if __name__ == "__main__":
+    import argparse
+
+    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    ap.add_argument("progetto")
+    ap.add_argument("modo", nargs="?", default="vivo", choices=["vivo", "snapshot"])
+    ap.add_argument("--data")
+    a = ap.parse_args()
+    testo = istruzioni_vivo(a.progetto) if a.modo == "vivo" else istruzioni_snapshot(a.progetto, a.data)
+    json.dump({"nome": nome_server(a.progetto), "istruzioni": testo}, sys.stdout, ensure_ascii=False)
+    sys.stdout.write("\n")