MultiverbeBOS

Pianeta Web · Quality-Max Stack Spec

Spec di build dello stack "system-first" di Pianeta Web. Decisione founder 2026-05-14 (sprint qualità "tutto pre-gate" — hard gate 10 Giu). Questo doc è la fonte che la sessione Mother legge prima di orchestrare lo sprint. Economics: canon/06-economics.md § Costi Infrastruttura. Posizionamento prodotto: canon/02-product.md § Pianeta Web.

⚠️ Stack reale (verificato 2026-05-14 via package.json)

Due app distinte, due stack diversi — NON confonderle:

  • frontend/multiverbe-app/ (dashboard) = Vite 5 + React 19 + Tailwind 3.4 · SPA, view-switching state-based in App.tsx (no router) · serverless functions nella cartella flat api/. NON Next.js.
  • sites-runtime/ (siti generati multi-tenant) = Next.js 16 + React 19 · next.config.mjs · *.multiverbe.app.

canon/05-stack.md indica "Next.js 16.2.6" come frontend unico → drift: vale solo per sites-runtime. Da correggere nel canon (founder conferma).

Perché

Il founder vuole fare di Pianeta Web il moat di settore: mandare in giro siti di altissima qualità che "respirano" dentro il sistema Multiverbe AI — leadership di settore via qualità. Ricerca web 2026 (animation libraries, design-token systems, LLM benchmark, image models, builder leader) + modello margini esteso a 10.000 clienti → la qualità prima è margin-safe (GM ricorrente ~94% a regime). Phasing approvato: sprint "tutto pre-gate", la qualità È l'MVP.

Architettura · "system-first"

La ricerca boccia i due estremi:

  • Template-first puro (Wix/Squarespace ADI) → effetto cookie-cutter, editor vincolato, 38% bounce su layout poco attraente.
  • Full-generative puro (10Web agentic) → costoso, lento, imprevedibile per un cost cap CHF.

Il SOTA 2026 (Webflow AI, Relume) è "system-first": non un template rigido, ma una component library rigida + sistema di design-token che l'AI compone e tematizza per-cliente. La D2 Section Library è già all'~80% — va evoluta con 3 layer nuovi.

Layer 1 · D2 Section Library — RESTA

Le 15 varianti rigide (Hero/Menu/Booking/Gallery/Contact) restano: sicurezza, controllo costi, QA-abilità. Vivono in sites-runtime/components/sections/ + SectionRenderer (components/sections/index.tsx).

Layer 2 · Token DNA per-sito — NUOVO

Per ogni sito l'AI genera un set di design-token unico (kill dell'effetto cookie-cutter):

  • 3-layer: primitive → semantic → component tokens (platform-agnostic, da 1 sorgente JSON → CSS vars).
  • Palette · type scale clamp() fluida (no px fissi) · spacing/rhythm scale geometrica · radius · shadow elevation.
  • Salvato accanto a sites.brand_dna (JSONB). Generato nello stadio design/composizione (Opus 4.7).

Layer 3 · Style-tier variants — NUOVO

Ogni sezione D2 prende un prop styleTier:

  • Standard — flat, single shadow elevation, statico.
  • Premium — depth multi-livello, micro-interazioni hover, gradient/mesh accenti, scroll-reveal stagger, glass/blur opzionale, accenti R3F dove il settore lo regge.
  • Lo styleTier fa swap del token group + animation preset. Una libreria, più finiture.

Layer 4 · AI section selection + ordering — NUOVO

La struttura del sito diventa variabile (non fissa): l'AI sceglie quali sezioni includere e in che ordine, per settore + obiettivo cliente. Decisione presa nello stadio design/composizione (Opus 4.7).

Animation stack

Layered, non single-library (stack award-site 2026):

  • Lenis (~5KB, free) — smooth scroll base, sincronizzato col ticker GSAP.
  • GSAP (100% free incl. SplitText/ScrollTrigger) — choreography narrativa: hero reveal, scroll storytelling, text split.
  • CSS scroll-driven nativo (scroll-timeline/view-timeline) — reveal-on-scroll, parallax, progress bar. Compositor thread, zero JS bundle. Spingere qui il più possibile.
  • View Transitions API — transizioni di pagina native, zero bundle.
  • Motion (ex-Framer Motion) — solo per stato React genuino (route/modal/layout transitions).
  • R3F — accenti hero solo Business-tier (R3F v9, NO v10 alpha — vedi skill multiverbe-r3f-patterns).

Performance: non caricare tutte le lib JS su siti Starter. License caveat GSAP: ok perché generiamo codice — mai esporre un editor visuale di animazioni GSAP-backed al cliente.

LLM-per-task split

Abbassa i costi vs oggi (Kimi fa più volume a basso leverage) E alza la qualità (Opus possiede le decisioni ad alto leverage).

Task Modello Pricing 2026 (/1M token) Note
Copywriting Kimi K2.6 $0.60 in / $2.50 out Con prompt settoriali il gap a premium su copy SMB italiano è piccolo. ~$0.001-0.003/sito
Design / composizione / art direction (brand DNA, palette, token set, section selection+ordering, CRO, prompt immagini) Claude Opus 4.7 ~$6.50 in / ~$32.50 out Step più ad alto leverage, volume token minimo. #1 human-eval UI quality + best vision. ~$0.10-0.30/sito
Markup HTML/JSX Kimi K2.6 primario + Sonnet 4.6 QA-gate Sonnet ~$3 in / ~$15 out Kimi 8-10× più economico genera bene; Sonnet QA-gate solo su Pro/Business

Verdetto Kimi: l'istinto del founder è giusto — Kimi deve fare di più (copy + markup first-pass), MA design/composizione/art-direction restano su Claude. Lì si fa la qualità percepita e il volume token è minimo.

Image models

Multi-model per job (non un solo modello):

  • Flux.2 Pro (~$0.03/img) — foto/lifestyle, leader fotorealismo.
  • Ideogram 3 ($0.02-0.10/img) — testo-in-immagine (insegne, menu card, poster).
  • Recraft V4 ($0.03-0.09/img) — vector + icone + brand mark.
  • Imagen 4 Fast (~$0.02/img) — budget tier Starter.
  • Drop Midjourney (licenza restrittiva + no API pulita).
  • 4-10 img/sito → costo immagini CHF 0.30-0.80, dentro il cap.

Pricing per-immagine hardcoded in stage-4-visual-director.ts (~righe 98-103) — aggiornare.

Output 3-tier

Una pipeline sola, gated da tier flag (mai 3 codebase):

Leva Starter Pro Business
Pagine 1-3 5-7 8-12
Animazione solo CSS scroll-driven + GSAP choreography + R3F hero, View Transitions
Immagini 4, Imagen 4 Fast 8, Flux.2 Pro 10+, Flux Ultra + Ideogram + Recraft
Copy Kimi K2.6 Kimi + Sonnet polish Kimi + Opus polish
Markup QA solo Kimi Sonnet 4.6 QA-gate Sonnet + Opus CRO pass
Style tier token Standard token Premium Premium + tuning custom
Costo gen realistico ~CHF 2 ~CHF 6 ~CHF 12
Cost cap CHF 5 CHF 10 CHF 15

Cost cap · tier-aware

costCapChf passato in OrchestratorConfig dal caller in base a subscriptions.tier (Starter 5 / Pro 10 / Business 15). Headroom sopra il costo gen realistico per retry + multi-locale. NON toccare la funzione DB check_cost_alert (Starter 1.50 / Pro 7 / Business 18) — è il budget AI ricorrente mensile, concern separato.

I 5 build stream (per la sessione Mother)

Sprint >4h multi-stream → pattern Mother + Child (1 sessione Mother nel repo codice + N child worktree). Dipendenze: Stream 2 precede Stream 3 · Stream 4 dipende da 2+3 · Stream 1 indipendente · Stream 5 in gran parte indipendente (il solo sub-task 5d answer-first/FAQ si sincronizza con Stream 2 + Stream 4).

Stream 1 — Cap tier-aware + Observability MVV (indipendente, parti subito)

  • Cap tier-aware: costCapChf in OrchestratorConfig da subscriptions.tier. Cambia orchestrator.ts:257 (fallback || 7.0), orchestrator.ts:112 (JSDoc), PUBLISH_CONTRACT.md righe 10/107/237.
  • Observability MVV: ⚠️ multiverbe-app è Vite + React + Tailwind (NON Next.js — vedi § Stack reale). api/site-builder/status.ts ESISTE già (Vercel serverless fn, ?siteId=) — NON ricrearla. Aggiungi una serverless fn sorella api/site-builder/jobs.ts (lista ai_generation_jobs cross-site: costo per-stage, model, status, cost_cap_chf, aborted_at, abort_reason, retry) + un componente admin founder-facing React+Tailwind agganciato al view-switching state-based di App.tsx (no router). Riusa la shape di polling da Step6GeneratePreview.tsx. Le colonne cost_cap/aborted vengono dalla migration 2026-05-13b (Stream 0a).

Stream 2 — Token DNA per-sito + LLM split refinement (parti subito, precede 3)

  • Token DNA per-sito (Layer 2 sopra): generazione + storage accanto a sites.brand_dna.
  • LLM split: Kimi K2.6 per copy E markup first-pass; Opus 4.7 solo design/composizione/art-direction; Sonnet 4.6 QA-gate markup su Pro/Business. Aggiorna i prompt in ai-pipeline/prompts/.

Stream 3 — Style-tier variants + animation stack (dopo Stream 2)

  • Prop styleTier (Standard/Premium) su ogni sezione D2 in sites-runtime/components/sections/ → swap token group + animation preset.
  • Animation stack: Lenis + GSAP + CSS scroll-driven nativo + View Transitions + Motion + R3F hero Business.

Stream 4 — AI section selection/ordering + 3-tier gating (dopo 2+3)

  • AI section selection + ordering (struttura variabile).
  • 3-tier output gating: una pipeline, tier flag che gate pagine/animazioni/n.immagini/modello copy/profondità QA (tabella Output 3-tier sopra).

Stream 5 — Reach · satellite SEO / GEO / AEO

Nome user-facing: "Reach" (decisione founder 2026-05-14). Tagline per l'imprenditore inesperto: "Fatti trovare — su Google e sulle AI." Niente acronimi nell'UI cliente; internamente resta engine SEO/GEO/AEO. Principio guida: come tutto il Pianeta Web, UX semplificata sempre prima della completezza tecnica — il bar è "incredibile" non "funziona".

Oggi il satellite "SEO & Search" del canon è a ~0% nel codice. Reach lo porta a essere lo strumento SEO/GEO/AEO più indispensabile del suo genere per una PMI: ogni sito generato nasce ottimizzato, e l'imprenditore vede e capisce il valore senza sapere cos'è un canonical tag. Baseline ricerca web 2026 + gap-closure: vedi decisions-log 2026-05-14 · Reach · satellite SEO/GEO/AEO.

Stato codice · appigli esistenti (verificato 2026-05-14)

Quasi tutto Reach è greenfield, ma alcuni appigli esistono e vanno usati:

  • site_constitutions.schema_org_type (es. "Restaurant") esiste → il mapping settore→schema-type per A1 è già alimentabile.
  • site_pages.localized_seo_meta (title/description/ogImage per-locale) esiste → A2 estende, non crea da zero.
  • site_assets.alt_text colonna esiste (nullable, mai popolata) → A5 aggiunge solo la generazione.
  • frontend/multiverbe-app/api/site/publish.ts:145 ha già revalidateSiteRuntime() → hook-point pulito per A3/A4 (sitemap regen + IndexNow ping).
  • Section library sites-runtime/components/sections/ è pluggable → aggiungere la sezione FAQ è LOW effort (~3-4 file).
  • DB: nessun campo seo_config → serve nuova migration (vedi § DB proposto).

Capability map (visione completa "al massimo")

A · Foundation engine — auto, generation-time, in OGNI sito generato. Genuinamente indipendente dagli Stream 1-4 (eccetto A5):

  • A1 Structured data JSON-LD settore-aware — LocalBusiness + sotto-tipo da site_constitutions.schema_org_type · Organization (sameAs) · Service/OfferCatalog · FAQPage · BreadcrumbList · Review/AggregateRating · Menu · Event. NEW sites-runtime/lib/seo/structured-data.ts.
  • A2 Metadata completi per-pagina — estende localized_seo_meta esistente: OpenGraph + Twitter card · canonical per-URL · hreflang + canonical per-lingua IT/DE/FR · robots meta · manifest.ts PWA. NEW lib/seo/metadata.ts.
  • A3 Sitemap + robots dynamic per-tenant — sitemap.ts + robots.ts (Next 16, multi-host) · rigenerati su publish via hook publish.ts:145 · robots.txt permette TUTTI i bot AI di default (retrieval + training: Googlebot, GPTBot, OAI-SearchBot, ClaudeBot, Claude-SearchBot, PerplexityBot, CCBot, Google-Extended) + toggle per-cliente. NEW lib/seo/robots-policy.ts.
  • A4 IndexNow — ping Bing/Yandex su publish/unpublish, hook in publish.ts:145. Google non lo supporta → copertura Google via sitemap + GSC.
  • A5 Image SEO — alt-text AI-generato (popola site_assets.alt_text) · next/image responsive · lazy-load · dimensioni esplicite anti-CLS. ⚠️ La generazione alt-text tocca lo Stage 3 dell'AI pipeline → coordinare con Stream 2.
  • A6 Internal linking — link interni auto tra pagine correlate + breadcrumb.
  • A7 llms.txt — auto-generato (costo zero · NON venduto come leva: adozione reale ~0,1% dei bot AI nel 2026).
  • A8 CWV guardrail at build — budget INP<200ms / LCP<2,5s / CLS<0,1 · check build-time che fallisce il gate (coordina con Stream 3).

B · GEO/AEO content layer — rende il sito citabile dalle AI. ⚠️ NON indipendente: dipende da Stream 2 (prompt Stage 3) + Stream 4 (la composizione Stage 2 deve includere la sezione FAQ).

  • B1 Answer-first content — copy con risposta diretta 40-60 parole in apertura sezione + heading conversazionali. Prompt update Stage 3 (ai-pipeline/prompts/by-section/).
  • B2 FAQ engine settore-aware — NEW sezione FAQ in sites-runtime/components/sections/FAQ/ + NEW prompts/by-section/faq.ts + output-schemas/faq.ts (Zod) → feed sezione visibile + FAQPage schema (A1).
  • B3 Entity clarity — NAP byte-identico schema/footer/contatti/GBP · sameAs · definizione chiara dell'attività in apertura home.
  • B4 AI-readiness check pre-publish — "il sito è pronto per essere citato dalle AI?" → score + cosa manca, prima di pubblicare.
  • B5 Speakable schema — voice assistant (basso costo · post-gate).

C · Local Reach — discovery locale CH, il cuore per le PMI Ticino. Citation set core (ricerca CH 2026): local.ch + search.ch + directories.ch + Google Business Profile — bastano questi 4 fatti benissimo, non 200. Contenuti in italiano di default per i clienti Ticino.

  • C1a NAP consistency checker + guida GBP (pre-gate · no API) — confronta NAP tra sito/schema/footer e i 4 citation source · guida passo-passo per creare/ottimizzare il GBP.
  • C1b GBP API sync (post-gate · cancello approvazione Google) — sync bidirezionale orari/categoria/foto/descrizione. ⚠️ Richiede accesso API GBP (approvazione settimane · 0 query finché non concesso) + il cliente possiede il GBP e aggiunge Multiverbe come Manager. GBP accurato = leva #1 per la visibilità su Gemini.
  • C2 City/region landing page generator (dipende da Stream 4) — pagine settore×località; clientContext ha già city/region.
  • C3 Review velocity flow (post-gate) — richiesta recensione post-visita/booking (aggancio Pianeta Booking + satellite Recensioni) + reminder al titolare di rispondere.
  • C4 Local schema (post-gate) — areaServed, orari speciali.

D · Reach Cockpit — il pannello per l'imprenditore inesperto · IL differenziatore (greenfield in multiverbe-app):

  • D1 Reach Score 0-100 (pre-gate) — punteggio unico, in italiano semplice, live.
  • D2 Azioni in linguaggio naturale (pre-gate) — zero gergo: "Il tuo sito non dice gli orari in un modo che Google capisce → aggiungili" · prioritizzate per impatto.
  • D3 Correzioni 1-click / auto-fix (pre-gate · limitato ai fix del Blocco A/B) — Multiverbe genera E hosta → Reach corregge da solo o chiede "approva questa correzione". Non un report da interpretare: un risultato.
  • D4 Reach Assistant (post-gate) — ⚠️ collegato al Centro/Sole, che è al ~25% e bloccato sulle API key (22 Mag) → non realistico pre-gate.
  • D5 Progress nel tempo (post-gate) — grafico Reach Score: "questo mese da 62 a 78".

E · Monitoring & Intelligence — continuo:

  • E1 GSC + Bing Webmaster wiring (pre-gate) — OAuth client per-tenant + coverage/indexing report.
  • E2 Indexing monitor (post-gate) — alert se Google deindicizza pagine.
  • E3 CWV field monitoring (RUM) (post-gate · coordina col satellite Web Vitals).
  • E4 AI-visibility monitoring engine — in-house, gated Pro/Business. Decisione founder 2026-05-14 (gap-closure): NON esistono API ufficiali per le citazioni AI; i tracker di terzi fanno scraping dei front-end (viola ToS + rischio revFADP). Approccio: engine, scoring, dashboard, competitor benchmark 100% in-house e proprietari, alimentati da API dati legittime — Perplexity Sonar API (ufficiale, espone le citazioni) + DataForSEO (rivende dati AI Overviews, ~$0.01/query). NO scraping fatto da noi, NO tracker di terzi rivenduto. Coverage onesta: Perplexity solido → AI Overviews accettabile → ChatGPT/Gemini "roadmap". NEW tabelle ai_visibility_checks + ai_visibility_results · NEW sub-processor Perplexity + DataForSEO (→ compliance) · costo per-query → tier_caps + pricing.
  • E5 Competitor visibility benchmark (post-gate) — "i tuoi 3 concorrenti compaiono su ChatGPT, tu no": parte di E4, leva fortissima per sales + retention.

Build sequence · phasing onesto (post gap-closure)

26 giorni al gate. Phasing realistico dopo la mappatura dipendenze:

  • Pre-gate CORE (genuinamente shippable, basso rischio, alto valore — il Blocco A è il vero "parti subito"):
    • Blocco A completo (A1-A8) — indipendente; A5 coordina con Stream 2
    • C1a (NAP checker + guida GBP) + check sui 4 citation source CH
    • D1-D3 (Reach Score + azioni in italiano semplice + auto-fix sui fix del Blocco A)
    • E1 (GSC + Bing wiring)
  • Pre-gate STRETCH (dipendenze permettendo):
    • B1-B4 — solo dopo che Stream 2 (prompt) + Stream 4 (composizione) atterrano
    • C2 (city pages — dopo Stream 4)
    • E4 fase 1 — solo Perplexity Sonar (la più pulita e veloce da integrare)
  • Post-gate enrichment: B5 · C1b (GBP API sync, dopo approvazione) · C3 · C4 · D4 (dopo Centro/Sole) · D5 · E2 · E3 · E4 fasi 2-3 (AI Overviews + ChatGPT/Gemini) · E5.

DB proposto

Zona grigia · founder approva · prod DB write → autorizzazione founder. Nuova migration:

  • colonna sites.seo_config jsonb (robots toggle + flag SEO + cache Reach Score)
  • tabelle ai_visibility_checks / ai_visibility_results (workspace_id scoped, RLS)
  • eventuale reach_audits (storico Reach Score)

Founder action items (gap-closure 2026-05-14)

  • Avviare la richiesta di accesso API Google Business Profile ORA — è il collo di bottiglia: approvazione settimane, l'API è a 0 query finché non concessa. Sblocca C1b.
  • Compliance: Perplexity + DataForSEO vanno aggiunti alla sub-processor list (skill multiverbe-ch-compliance) prima che E4 vada live.

Regole sprint: 1 child worktree per stream · branch + PR per stream · gate (build + tsc + CI + review) prima di ogni merge · auto-merge PR gate-passed se esiste la permission rule Bash(gh pr merge:*) · branch lifetime max 1 giornata lavorativa · aggiorna BOS (status.json + activity.json) a ogni milestone · ZERO INFO LOSS · zona grigia naming/schema/design → opzioni con trade-off, founder decide.

Riferimenti codice (repo D:\Desktop\Multiverbe)

  • frontend/multiverbe-app/src/lib/site-design/ai-pipeline/orchestrator.ts — pipeline 6-stage, cap a ~:257, JSDoc :112
  • frontend/multiverbe-app/src/lib/site-design/ai-pipeline/stage-4-visual-director.ts — costo immagini ~:98-103
  • frontend/multiverbe-app/src/lib/site-design/ai-pipeline/prompts/ — system-prompt + by-section + output-schemas
  • frontend/multiverbe-app/src/lib/site-design/PUBLISH_CONTRACT.md — cita "CHF 7" righe 10/107/237
  • frontend/multiverbe-app/src/components/site-builder/steps/Step6GeneratePreview.tsx — consuma costCapApproached/Exceeded
  • sites-runtime/components/sections/ + components/sections/index.tsx — D2 Section Library + SectionRenderer
  • DB: ai_generation_jobs (migration 2026-05-13b), sites.brand_dna, site_versions, site_constitutions, brand_intelligence

Ultimo update: 2026-05-14 · Stream 5 Reach — gap-closure (5 gap chiusi: E4 alimentato da Perplexity Sonar + DataForSEO no-scraping · dipendenze reali mappate, solo Blocco A indipendente · D4 e C1b → post-gate · citation set CH local.ch/search.ch/directories.ch/GBP · founder action items). Precedente: NEW Stream 5 satellite SEO/GEO/AEO · creazione spec system-first. Owner: Gregorio (visione/design) · Claude (tecnico/architettura)