@jsonpages/cli 3.0.64 → 3.0.65

package/assets/src_tenant_alpha.sh

@@ -3,6 +3,555 @@ set -e # Termina se c'è un errore
 
 echo "Inizio ricostruzione progetto..."
 
+mkdir -p "docs"
+echo "Creating docs/01-Onboarding_Client_completo_aggiornato.md..."
+cat << 'END_OF_FILE_CONTENT' > "docs/01-Onboarding_Client_completo_aggiornato.md"
+# Onboarding — Percorso Client (senza CMS) — Versione completa
+
+**Per chi:** Sviluppo grafico e dati quando **non** usi il CMS (Studio/ICE). Il sito è un **client**: i dati arrivano da JSON locali, da API o da un CMS esterno; tu ti occupi di layout, design e rendering.
+
+**Riferimento spec:** JSONPAGES Architecture v1.2 — solo le parti che riguardano struttura sito, componenti e dati. Ignori: Studio, ICE, Form Factory, IDAC, TOCC, AddSectionConfig, schema obbligatori per l'editor.
+
+---
+
+## 1. Cosa fai tu (in sintesi)
+
+- **Grafico:** Layout e stili delle section (View + CSS / design tokens se vuoi).
+- **Dati:** Da dove prendono i dati le pagine (file JSON, API, altro CMS) e come vengono passati al motore (config + pages).
+
+Non devi: tipizzare tutto per l'editor, esporre schema Zod al Form Factory, gestire overlay Studio, Add Section, ecc. Puoi usare tipi minimi o anche `unknown`/`any` sui dati se non ti serve type-safety forte.
+
+---
+
+## 2. Struttura progetto (minima)
+
+- **`src/data/config/site.json`** — Identità, header, footer (blocchi con `id`, `type`, `data`, `settings`).
+- **`src/data/config/menu.json`** — Menu (es. `{ main: [{ label, href }] }`).
+- **`src/data/config/theme.json`** — (Opzionale) Token tema (colori, font, radius).
+- **`src/data/pages/<slug>.json`** — Una pagina = `slug`, `meta`, `sections[]` (array di blocchi `id`, `type`, `data`, `settings`). **Per creare una nuova pagina** basta aggiungere un file `<slug>.json` in `src/data/pages/`; lo slug del nome file diventa il path della pagina (es. `chi-siamo.json` → `/chi-siamo`).
+- **`src/components/<sectionType>/`** — Una cartella per tipo di blocco (hero, header, footer, feature-grid, …).
+- **`src/App.tsx`** — Carica site, menu, theme, pages; costruisce la config; renderizza **`<JsonPagesEngine config={config} />`**.
+
+Il motore (Core) si aspetta comunque un **registry** (mappa tipo → componente) e le **pagine** nel formato previsto (slug → page con `sections`). Come popoli i JSON (a mano, da script, da altro CMS) è fuori dall'editor.
+
+**Perché servono (struttura):** Path e forma (site, menu, theme, pages con sections) sono il contratto minimo che il Core usa per routing e rendering; rispettarli permette di cambiare in seguito fonte dati (JSON → API) senza riscrivere la logica. Vedi spec §2 (JSP), Appendix A.4.
+
+---
+
+## 3. Componenti (solo View)
+
+- Ogni **section type** ha almeno una **View**: riceve `data` e, se serve, `settings`. L'header riceve anche `menu` (array di `{ label, href }`).
+- **Niente obbligo di capsule "piene":** puoi avere solo `View.tsx` (e magari un `index.ts` che esporta la View). Schema Zod e types servono solo se vuoi type-safety in sviluppo o se in futuro attivi il CMS.
+- **Stili:** Puoi usare classi Tailwind "libere" o un set di variabili CSS (es. `--local-bg`, `--local-text`) per coerenza. Le spec CIP (solo variabili, niente utility nude) sono per il percorso governance; qui puoi adattare alle tue convenzioni.
+- **Asset:** Se il Core espone `resolveAssetUrl(path, tenantId)`, usalo per le immagini; altrimenti path relativi o URL assoluti.
+
+**Perché servono (componenti):** Il registry deve avere un componente per ogni `type` usato nei JSON; la View deve ricevere `data` (e `settings`/`menu` dove previsto) così il Core può renderizzare senza conoscere i dettagli. Senza registry coerente con i dati, il motore non saprebbe cosa montare. Vedi spec §3 (TBP), §4 (CIP) per il percorso completo.
+
+---
+
+## 3.1 Image e campi immagine (se usi schema in seguito)
+
+Se più avanti aggiungi schema Zod per type-safety o per attivare Studio, i **campi immagine** vanno modellati così:
+
+- **Schema:** Il campo immagine è un **oggetto** (non una stringa) con almeno `url` e opzionalmente `alt`. Lo schema di questo oggetto va marcato con **`.describe('ui:image-picker')`** così il Form Factory (Inspector) mostra il widget Image Picker. Esempio: uno sub-schema `ImageSelectionSchema = z.object({ url: z.string(), alt: z.string().optional() }).describe('ui:image-picker')` usato come `image: ImageSelectionSchema.default({ url: '', alt: '' })`.
+- **View:** Per il `src` dell'immagine usa **`resolveAssetUrl(data.image.url, tenantId)`**; sul nodo che rappresenta l'immagine imposta **`data-jp-field="image"`** (così l'Inspector lega correttamente il campo).
+
+**Riferimento:** componente `image-break` in `apps/tenant-alpha/src/components/image-break/` (schema.ts, View.tsx) come esempio completo.
+
+---
+
+## 4. Dati: da dove arrivano
+
+- **Solo JSON locali:** Leggi `site.json`, `menu.json`, `theme.json`, `pages/*.json` e li passi in `config` (siteConfig, menuConfig, themeConfig, pages). Nessun CMS.
+- **CMS esterno / API:** Invece di importare i JSON, fai fetch (o SSR) e costruisci gli stessi oggetti (siteConfig, menuConfig, pages) e li passi a `JsonPagesEngine`. La forma delle pagine resta: `{ slug, meta?, sections[] }`; ogni section: `{ id, type, data, settings? }`.
+- **Ibrido:** Header/footer da `site.json`, body da API o da altro CMS: costruisci un unico `pages[slug]` con `sections` che rispettano i tipi di blocco che hai nel registry.
+
+Non devi registrare schema o AddSectionConfig a meno che non attivi Studio.
+
+**Perché servono (dati):** La forma `sections[]` con `id`, `type`, `data`, `settings?` è ciò che il SectionRenderer e il Core si aspettano; mantenere quella forma anche quando i dati arrivano da API o altro CMS evita adattatori fragili e permette di attivare Studio in seguito senza rifare i dati. Vedi spec Appendix A.2 (PageConfig, SiteConfig, MenuConfig).
+
+---
+
+## 5. Registry e config (minimo)
+
+- **Registry:** Un oggetto che mappa ogni `sectionType` (stringa) al componente React che renderizza quel tipo. Es.: `{ header: Header, footer: Footer, hero: Hero, ... }`. Se non usi Studio, puoi tipizzare in modo lasco (es. `Record<string, React.FC<any>>` o comunque compatibile con quanto si aspetta `JsonPagesConfig['registry']`).
+- **Config da passare a JsonPagesEngine:**  
+  `tenantId`, `registry`, `pages`, `siteConfig`, `menuConfig`, `themeConfig` (o oggetto vuoto), `themeCss: { tenant: cssString }`.  
+  Se **non** usi Studio, **schemas** e **addSection** possono essere placeholder (oggetto vuoto / no-op) se il Core lo permette; altrimenti fornisci il minimo (es. schemas = `{}`, addSection = `{ addableSectionTypes: [], sectionTypeLabels: {}, getDefaultSectionData: () => ({}) }`) per non rompere l'engine.
+
+Verifica nella doc o nel tipo `JsonPagesConfig` se `schemas` e `addSection` sono opzionali quando Studio non è in uso.
+
+**Perché servono (registry e config):** Il Core deve risolvere ogni section a un componente (registry) e avere pagine, site, menu, theme e CSS tenant per renderizzare e, se serve, iniettare lo Stage in iframe; i campi obbligatori di config sono il minimo per far funzionare l'engine. Placeholder per schemas/addSection evitano errori quando Studio non è usato. Vedi spec §10 (JEB), Appendix A.
+
+---
+
+## 6. Checklist rapida (sviluppo grafico e dati, senza CMS)
+
+| Cosa | Azione |
+|------|--------|
+| **Layout / grafico** | Implementare le View (una per section type) e gli stili (CSS / Tailwind / variabili). |
+| **Dati** | Decidere fonte (JSON locali, API, altro CMS); costruire `siteConfig`, `menuConfig`, `pages` nella forma attesa e passarli in `config`. |
+| **Registry** | Mappare ogni tipo di blocco usato nei JSON al componente corrispondente. |
+| **Header / menu** | Header component riceve `data`, `settings`, `menu`; `menu` viene da `menuConfig` (es. `menuConfig.main`). |
+| **Pagine** | Ogni pagina = un entry in `pages` con `sections[]`; ogni section ha `id`, `type`, `data`, `settings?`. |
+| **Nuova pagina** | Aggiungere un file `<slug>.json` in `src/data/pages/` (lo slug diventa il path della pagina). |
+| **Image (se schema)** | Campo immagine = oggetto `{ url, alt? }` con schema `.describe('ui:image-picker')`; View usa `resolveAssetUrl` e `data-jp-field="image"`. |
+| **Studio / ICE** | Non usati: niente schema obbligatori, niente data-jp-*, niente overlay CSS, niente Add Section. |
+
+---
+
+## 7. Quando passi al percorso "Governance"
+
+Se più avanti vuoi l'editor (Studio) e la governance (tipi, schema, Add Section, overlay): usa l'onboarding **02-Onboarding_Governance_completo.md** e allinea il progetto a tipi, capsule piene (View + schema + types), IDAC, TOCC, AddSectionConfig e Appendix A delle spec v1.2.
+
+END_OF_FILE_CONTENT
+echo "Creating docs/01-Onboarding_Governance_naked.md..."
+cat << 'END_OF_FILE_CONTENT' > "docs/01-Onboarding_Governance_naked.md"
+### 📄 File 1: Client Path (No CMS)
+
+
+
+# Onboarding — Client Path (No CMS) — Complete Version
+
+**Target:** Frontend Developers & Data Entry staff who **do not** use the CMS (Studio/ICE). The site acts as a **client**: data comes from local JSON, APIs, or an external CMS; you are responsible for layout, design, and rendering.
+
+**Spec Reference:** JSONPAGES Architecture v1.2 — only the parts regarding site structure, components, and data. You ignore: Studio, ICE, Form Factory, IDAC, TOCC, AddSectionConfig, and mandatory schemas for the editor.
+
+---
+
+## 1. Your Role (Summary)
+
+-   **Visuals:** Layout and styling of sections (View + CSS / design tokens).
+-   **Data:** Where pages get their data (JSON files, API, external CMS) and how they are passed to the engine (config + pages).
+
+You **do not** need to: type everything for the editor, expose Zod schemas to the Form Factory, handle Studio overlays, Add Section logic, etc. You can use minimal types or even `unknown`/`any` on data if strong type-safety is not required.
+
+---
+
+## 2. Project Structure (Minimal)
+
+-   **`src/data/config/site.json`** — Identity, header, footer (blocks with `id`, `type`, `data`, `settings`).
+-   **`src/data/config/menu.json`** — Menu (e.g., `{ main: [{ label, href }] }`).
+-   **`src/data/config/theme.json`** — (Optional) Theme tokens (colors, fonts, radius).
+-   **`src/data/pages/<slug>.json`** — One page = `slug`, `meta`, `sections[]` (array of blocks `id`, `type`, `data`, `settings`). **To create a new page**, simply add a `<slug>.json` file in `src/data/pages/`; the filename slug becomes the page path (e.g., `about-us.json` → `/about-us`).
+-   **`src/components/<sectionType>/`** — One folder per block type (hero, header, footer, feature-grid, …).
+-   **`src/App.tsx`** — Loads site, menu, theme, pages; builds the config; renders **`<JsonPagesEngine config={config} />`**.
+
+The Engine (Core) still expects a **registry** (type → component map) and **pages** in the expected format (slug → page with `sections`). How you populate the JSONs (manually, via script, from another CMS) is outside the editor's scope.
+
+**Why this matters (Structure):** Paths and shape (site, menu, theme, pages with sections) are the minimal contract the Core uses for routing and rendering; respecting them allows you to switch data sources (JSON → API) later without rewriting logic. See Spec §2 (JSP), Appendix A.4.
+
+---
+
+## 3. Components (View Only)
+
+-   Every **section type** has at least one **View**: it receives `data` and, if needed, `settings`. The header also receives `menu` (array of `{ label, href }`).
+-   **No "Full Capsule" requirement:** you can have just `View.tsx` (and maybe an `index.ts` exporting the View). Zod schemas and types are only needed if you want dev-time type-safety or plan to activate the CMS later.
+-   **Styles:** You can use "free" Tailwind classes or a set of CSS variables (e.g., `--local-bg`, `--local-text`) for consistency. CIP specs (variables only, no naked utilities) are for the Governance path; here you can adapt to your conventions.
+-   **Assets:** If the Core exposes `resolveAssetUrl(path, tenantId)`, use it for images; otherwise, use relative paths or absolute URLs.
+
+**Why this matters (Components):** The registry must have a component for every `type` used in the JSONs; the View must receive `data` (and `settings`/`menu` where expected) so the Core can render without knowing details. Without a registry consistent with data, the engine wouldn't know what to mount. See Spec §3 (TBP), §4 (CIP) for the full path.
+
+---
+
+## 3.1 Images and Image Fields (If using Schema later)
+
+If you later add Zod schemas for type-safety or to activate Studio, **image fields** must be modeled as follows:
+
+-   **Schema:** The image field is an **object** (not a string) with at least `url` and optionally `alt`. This object's schema must be marked with **`.describe('ui:image-picker')`** so the Form Factory (Inspector) shows the Image Picker widget. Example: a sub-schema `ImageSelectionSchema = z.object({ url: z.string(), alt: z.string().optional() }).describe('ui:image-picker')` used as `image: ImageSelectionSchema.default({ url: '', alt: '' })`.
+-   **View:** For the image `src`, use **`resolveAssetUrl(data.image.url, tenantId)`**; on the node representing the image, set **`data-jp-field="image"`** (so the Inspector binds the field correctly).
+
+**Reference:** See the `image-break` component in `apps/tenant-alpha/src/components/image-break/` (schema.ts, View.tsx) for a complete example.
+
+---
+
+## 4. Data: Where it comes from
+
+-   **Local JSONs only:** Read `site.json`, `menu.json`, `theme.json`, `pages/*.json` and pass them into `config` (siteConfig, menuConfig, themeConfig, pages). No CMS.
+-   **External CMS / API:** Instead of importing JSONs, fetch (or SSR) and build the same objects (siteConfig, menuConfig, pages) and pass them to `JsonPagesEngine`. The page shape remains: `{ slug, meta?, sections[] }`; each section: `{ id, type, data, settings? }`.
+-   **Hybrid:** Header/footer from `site.json`, body from API or another CMS: build a single `pages[slug]` with `sections` that respect the block types you have in the registry.
+
+You do not need to register schemas or AddSectionConfig unless you activate Studio.
+
+**Why this matters (Data):** The `sections[]` shape with `id`, `type`, `data`, `settings?` is what the SectionRenderer and Core expect; maintaining this shape even when data comes from an API or another CMS avoids fragile adapters and allows activating Studio later without redoing data. See Spec Appendix A.2 (PageConfig, SiteConfig, MenuConfig).
+
+---
+
+## 5. Registry and Config (Minimal)
+
+-   **Registry:** An object mapping every `sectionType` (string) to the React component rendering that type. E.g.: `{ header: Header, footer: Footer, hero: Hero, ... }`. If not using Studio, you can type loosely (e.g., `Record<string, React.FC<any>>` or whatever is compatible with `JsonPagesConfig['registry']`).
+-   **Config passed to JsonPagesEngine:**
+    `tenantId`, `registry`, `pages`, `siteConfig`, `menuConfig`, `themeConfig` (or empty object), `themeCss: { tenant: cssString }`.
+    If you are **not** using Studio, **schemas** and **addSection** can be placeholders (empty object / no-op) if the Core allows it; otherwise, provide the minimum (e.g., schemas = `{}`, addSection = `{ addableSectionTypes: [], sectionTypeLabels: {}, getDefaultSectionData: () => ({}) }`) to prevent engine errors.
+
+Check docs or `JsonPagesConfig` type to see if `schemas` and `addSection` are optional when Studio is unused.
+
+**Why this matters (Registry & Config):** The Core must resolve every section to a component (registry) and have pages, site, menu, theme, and tenant CSS to render and, if needed, inject the Stage iframe; mandatory config fields are the minimum to make the engine work. Placeholders for schemas/addSection avoid errors when Studio is not used. See Spec §10 (JEB), Appendix A.
+
+---
+
+## 6. Quick Checklist (Visual Dev & Data, No CMS)
+
+| Item | Action |
+|------|--------|
+| **Layout / Visuals** | Implement Views (one per section type) and styles (CSS / Tailwind / variables). |
+| **Data** | Decide source (Local JSON, API, other CMS); build `siteConfig`, `menuConfig`, `pages` in the expected shape and pass to `config`. |
+| **Registry** | Map every block type used in JSONs to the corresponding component. |
+| **Header / Menu** | Header component receives `data`, `settings`, `menu`; `menu` comes from `menuConfig` (e.g., `menuConfig.main`). |
+| **Pages** | Each page = one entry in `pages` with `sections[]`; each section has `id`, `type`, `data`, `settings?`. |
+| **New Page** | Add a `<slug>.json` file in `src/data/pages/` (slug becomes page path). |
+| **Image (if schema)** | Image field = object `{ url, alt? }` with schema `.describe('ui:image-picker')`; View uses `resolveAssetUrl` and `data-jp-field="image"`. |
+| **Studio / ICE** | Not used: no mandatory schemas, no data-jp-*, no overlay CSS, no Add Section. |
+
+---
+
+## 7. Switching to the "Governance" Path
+
+If you later want the editor (Studio) and governance (types, schema, Add Section, overlay): use the onboarding guide **02-Onboarding_Governance.md** and align the project with types, full capsules (View + schema + types), IDAC, TOCC, AddSectionConfig, and Appendix A of Spec v1.2.
+
+
+END_OF_FILE_CONTENT
+echo "Creating docs/02-Onboarding_Governance_CMS.md..."
+cat << 'END_OF_FILE_CONTENT' > "docs/02-Onboarding_Governance_CMS.md"
+
+# Onboarding — Governance Path (With CMS) — Complete Version
+
+**Target:** Lead Developers & Architects setting up the **CMS** (Studio, ICE, Form Factory): in-app authoring, strong typing, content and component governance.
+
+**Spec Reference:** JSONPAGES Architecture Specifications v1.2 (full) + Appendix A — Tenant Type & Code-Generation Annex.
+
+---
+
+## 1. What "Governance" Implies
+
+-   **Types:** Every section type is declared in `SectionDataRegistry` / `SectionSettingsRegistry` (module augmentation) and in `SectionComponentPropsMap`. Registry and config are strictly typed.
+-   **Schema:** Every section type has a Zod schema (data, and optionally settings) used by the Form Factory to generate the editor in the Inspector. Schemas are aggregated in `SECTION_SCHEMAS`.
+-   **Studio/ICE:** The editor (Inspector) hooks into the DOM via **data-jp-field** and **data-jp-item-id** / **data-jp-item-field**. The selection overlay in the iframe requires the **tenant** to provide the CSS (TOCC).
+-   **Add Section:** The tenant exposes **AddSectionConfig** (addable types, labels, default data) so the user can add sections from the library in Studio.
+-   **Design Tokens:** Views use CSS variables (`--local-*`) and no "naked" utilities (CIP) for consistency and compatibility with themes and overlays.
+
+**Why this matters (Summary):** Types and schemas allow the Core and Form Factory to operate without knowing Tenant details; IDAC allows the Inspector to link Stage clicks to the active row in the sidebar (including active/inactive opacity); TOCC makes the overlay visible; AddSectionConfig defines the "Add Section" library; tokens and z-index avoid conflicts with the editing UI. Detailed "Whys" for each spec: see Spec v1.2 (§1–§10, JAP, Appendix A).
+
+---
+
+## 1.1 The Value of Typing: Governance vs. CMS UX
+
+Typing (TypeScript types + Zod schema) serves **two levels**: Governance (Developer/Architecture) and **CMS UX** (Author using Studio).
+
+**Governance:** Typed registry, SectionComponentPropsMap, SiteConfig/PageConfig shape, audits, code-generation → consistency across tenants, no drift, safe refactoring, spec-based tooling.
+
+**CMS UX:** The Zod schema drives the **Form Factory** (which widget for which field: text, textarea, select, list, icon-picker, **image-picker**); **data-jp-field** and **data-jp-item-id/field** bind Stage clicks to Inspector forms; **AddSectionConfig** provides addable types, labels, and defaults. Result for the author: consistent forms, "Add Section" with sensible names and initial data, correct selection (click → right form), validation with clear errors. Without schema and typed contracts, the Inspector wouldn't know which fields to show or how to validate. Thus: for governance, typing guarantees **contracts**; for CMS UX, it defines the **editing experience**. Both must be specified.
+
+---
+
+## 2. Project Structure (Complete)
+
+-   **`src/data/config/site.json`** — SiteConfig (identity, pages[], header block, footer block).
+-   **`src/data/config/menu.json`** — MenuConfig (e.g., `main: MenuItem[]`).
+-   **`src/data/config/theme.json`** — ThemeConfig (tokens).
+-   **`src/data/pages/<slug>.json`** — PageConfig (slug, meta, sections[]). **To create a new page**, simply add a `<slug>.json` file in `src/data/pages/`; the filename slug becomes the page path (e.g., `about-us.json` → `/about-us`).
+-   **`src/components/<sectionType>/`** — **Full Capsule:** View.tsx, schema.ts, types.ts, index.ts.
+-   **`src/lib/base-schemas.ts`** — BaseSectionData, BaseArrayItem, BaseSectionSettingsSchema.
+-   **`src/lib/schemas.ts`** — SECTION_SCHEMAS (aggregate of data schemas per type) + export SectionType.
+-   **`src/lib/ComponentRegistry.tsx`** — Typed Registry: `{ [K in SectionType]: React.FC<SectionComponentPropsMap[K]> }`.
+-   **`src/lib/addSectionConfig.ts`** — AddSectionConfig (addableSectionTypes, sectionTypeLabels, getDefaultSectionData).
+-   **`src/types.ts`** — SectionComponentPropsMap, PageConfig, SiteConfig, MenuConfig, ThemeConfig; **module augmentation** for SectionDataRegistry and SectionSettingsRegistry; re-export from `@jsonpages/core`.
+-   **`src/App.tsx`** — Bootstrap: config (tenantId, registry, schemas, pages, siteConfig, themeConfig, menuConfig, themeCss, addSection); `<JsonPagesEngine config={config} />`.
+-   **Global CSS** — Includes TOCC selectors for overlay (hover/selected/type label).
+
+---
+
+## 3. Components (Capsules + IDAC + Tokens)
+
+-   **Capsule:** Every section type has View, schema (Zod), types (inferred), index. The **data** schema extends BaseSectionData; array items extend BaseArrayItem.
+-   **View:** Receives `data` and `settings` (and `menu` for header). Does not import Zod. Uses **only** CSS variables for colors/radii (e.g., `bg-[var(--local-bg)]`), root section with `z-index` ≤ 1.
+-   **IDAC (ICE):** On every editable scalar field: **`data-jp-field="<fieldKey>"`**. On every editable array item: **`data-jp-item-id="<stableId>"`** and **`data-jp-item-field="<arrayKey>"`**. This allows the Inspector to bind selection and forms to the correct paths.
+-   **Schema:** Use UI vocabulary (ECIP): `.describe('ui:text')`, `ui:textarea`, `ui:select`, `ui:number`, `ui:list`, `ui:icon-picker`, **`ui:image-picker`** (see §3.1). Editable object arrays: every object must have an `id` (BaseArrayItem).
+
+**Why this matters (Components):** **data-jp-field** and **data-jp-item-*** are needed because the Stage is in an iframe, and the Core needs to know which field/item corresponds to a click without knowing the Tenant's DOM: this allows the sidebar to highlight the active row (even with active/inactive opacity), open the form on the right field, and handle lists (reorder, delete). Without IDAC, clicks on the canvas are not reflected in the sidebar. Schema with `ui:*` and BaseArrayItem are needed for the Form Factory to generate the right widgets and maintain stable keys (reorder/delete). Tokens and z-index prevent content from covering the overlay. See Spec §6 (IDAC), §5 (ECIP), §4 (CIP).
+
+---
+
+## 3.1 Image Picker: Correct Usage in Schema (Example `image-break`)
+
+For **image fields**, the Form Factory exposes the **Image Picker** widget only if the schema is modeled correctly.
+
+### Rule
+
+-   The image field is not a **string** (`z.string()`), but an **object** with at least `url` and, optionally, `alt`.
+-   The **schema of this object** (the sub-schema) must be marked with **`.describe('ui:image-picker')`**. The Form Factory recognizes `ui:image-picker` only on **ZodObject** (object schema), not on string fields.
+
+### Example (`image-break` capsule)
+
+**Schema (`schema.ts`):**
+
+```ts
+import { z } from 'zod';
+import { BaseSectionData } from '@/lib/base-schemas';
+
+const ImageSelectionSchema = z
+  .object({
+    url: z.string(),
+    alt: z.string().optional(),
+  })
+  .describe('ui:image-picker');
+
+export const ImageBreakSchema = BaseSectionData.extend({
+  label: z.string().optional().describe('ui:text'),
+  image: ImageSelectionSchema.default({ url: '', alt: '' }),
+  caption: z.string().optional().describe('ui:textarea'),
+});
+```
+
+-   **ImageSelectionSchema** is a `z.object({ url, alt })` with **`.describe('ui:image-picker')`** on the object.
+-   The **`image`** field in the section data uses that schema (with default), so the Inspector shows the Image Picker widget for `image`.
+
+**View (`View.tsx`):**
+
+-   For the image `src`: **`resolveAssetUrl(data.image.url, tenantId)`** (multi-tenant and relative paths).
+-   On the node representing the image (e.g., the `<img>` or a wrapper): **`data-jp-field="image"`** so the Stage click binds the Inspector to the `image` field.
+-   Other editable fields (caption, label) with **`data-jp-field="caption"`** and **`data-jp-field="label"`** where appropriate.
+
+**Full Reference:** `apps/tenant-alpha/src/components/image-break/` (schema.ts, types.ts, View.tsx, index.ts).
+
+### What to Avoid
+
+-   **Do not** use `.describe('ui:image-picker')` on a **string** field (e.g., `imageUrl: z.string().describe('ui:image-picker')`): the Image Picker widget expects an object `{ url, alt? }`.
+-   **Do not** forget `data-jp-field="image"` on the corresponding DOM node, otherwise Inspector ↔ Stage binding won't work for that field.
+
+---
+
+## 4. Data: Shape and Responsibility
+
+-   **site.json / menu.json / theme.json / pages/*.json** — Exact shape as in Appendix A (SiteConfig, MenuConfig, ThemeConfig, PageConfig). These are the Source of Truth when the user saves from Studio (Working Draft → persist to these files or API generating them).
+-   **Studio** updates the Working Draft; sync with the iframe and "Bake" use the same structure. Therefore, data passed to JsonPagesEngine (siteConfig, menuConfig, pages) must be compatible with what the editor modifies.
+
+If data comes from an external CMS, you must synchronize: e.g., export from Studio → push to CMS, or CMS as source and Studio in read-only; in any case, the **shape** of pages (sections with id, type, data, settings) remains that of the spec.
+
+---
+
+## 5. Registry, Schemas, Types, AddSection
+
+-   **types.ts:** Single point of **module augmentation** and definition of SectionComponentPropsMap, PageConfig, SiteConfig, MenuConfig, ThemeConfig. Header: `{ data, settings?, menu: MenuItem[] }`; all others: `{ data, settings? }`.
+-   **ComponentRegistry:** Every SectionType key has the corresponding component; type: `{ [K in SectionType]: React.FC<SectionComponentPropsMap[K]> }`.
+-   **SECTION_SCHEMAS:** Every SectionType key has the **data Zod schema** (same order as registry). Base schemas re-exported from base-schemas.ts.
+-   **addSectionConfig:** addableSectionTypes (only types the user can add from the library), sectionTypeLabels, getDefaultSectionData(type) returning valid `data` for that schema.
+
+**Why this matters (registry, schemas, types, addSection):** A single augmentation point (types.ts) and a single SECTION_SCHEMAS avoid duplication and ensure registry, Form Factory, and config use the same types. AddSectionConfig is the single source of truth for "which sections can be added" and "with what defaults"; without it, the "Add Section" modal wouldn't have valid names or initial data. See Spec §9 (ASC), Appendix A.2–A.3.
+
+---
+
+## 6. Overlay and CSS (TOCC)
+
+-   The Core injects the overlay markup (wrapper with `data-section-id`, sibling with `data-jp-section-overlay`). The **tenant** must provide the CSS so that:
+    -   `[data-jp-section-overlay]` covers the section, `pointer-events: none`, high z-index (e.g., 9999).
+    -   Hover and selected states are visible (dashed/solid border, optional tint).
+    -   The type label (e.g., `[data-jp-section-overlay] > div`) is positioned and visible on hover/selected.
+
+Without this, the overlay is invisible in the Studio iframe.
+
+**Why this matters (TOCC):** The Stage iframe loads only Tenant CSS; the Core injects overlay markup but not styles. Without TOCC selectors in Tenant CSS, hover/selected borders and type labels are invisible: the author cannot see which section is selected. See Spec §7 (TOCC).
+
+---
+
+## 7. Quick Checklist (Visual Dev & Data, With CMS)
+
+| Item | Action |
+|------|--------|
+| **Layout / Visuals** | View with `--local-*` variables, z-index ≤ 1, no naked utilities. |
+| **Data (Shape)** | SiteConfig, MenuConfig, ThemeConfig, PageConfig as in Appendix A; JSON in `data/config` and `data/pages`. |
+| **Capsules** | View + schema (with `ui:*`) + types + index; data schema extends BaseSectionData; array item with id. |
+| **IDAC** | `data-jp-field` on editable scalar fields; `data-jp-item-id` and `data-jp-item-field` on array items. |
+| **types.ts** | SectionComponentPropsMap (header with menu), augmentation, PageConfig, SiteConfig, MenuConfig, ThemeConfig. |
+| **Registry** | All types mapped to component; registry type as in Appendix A. |
+| **SECTION_SCHEMAS** | One entry per type (data schema); re-export base schemas. |
+| **addSectionConfig** | addableSectionTypes, sectionTypeLabels, getDefaultSectionData. |
+| **Config** | tenantId, registry, schemas, pages, siteConfig, themeConfig, menuConfig, themeCss, addSection. |
+| **TOCC** | CSS overlay for `[data-jp-section-overlay]`, hover, selected, type label. |
+
+---
+
+## 8. Spec References
+
+-   **Architecture and ICE:** §1–§10 (MTRP, JSP, TBP, CIP, ECIP, IDAC, TOCC, BSDS, ASC, JEB).
+-   **Types and Code-Generation:** Appendix A (Core types, Tenant types, Schema contract, File paths, Integration checklist).
+-   **Admin:** JAP (Studio topology, Working Draft, Bake, overlay, Green Build).
+
+Using this path gives you full **governance**: types, schema, editor, Add Section, and overlay aligned with Spec v1.2. For versions with all "Why this matters" explanations, use the file **JSONPAGES_Specs_v1.2_completo.md**.
+
+--- END OF FILE docs/02-Onboarding_Governance.md ---
+END_OF_FILE_CONTENT
+echo "Creating docs/02-Onboarding_Governance_completo_aggiornato.md..."
+cat << 'END_OF_FILE_CONTENT' > "docs/02-Onboarding_Governance_completo_aggiornato.md"
+# Onboarding — Percorso Governance (con CMS) — Versione completa
+
+**Per chi:** Sviluppo grafico e dati quando vuoi il **CMS** (Studio, ICE, Form Factory): authoring in-app, tipizzazione forte, governance dei contenuti e dei componenti.
+
+**Riferimento spec:** JSONPAGES Architecture Specifications v1.2 (full) + Appendix A — Tenant Type & Code-Generation Annex.
+
+---
+
+## 1. Cosa implica "governance"
+
+- **Tipi:** Ogni section type è dichiarato in `SectionDataRegistry` / `SectionSettingsRegistry` (module augmentation) e in `SectionComponentPropsMap`. Registry e config sono tipizzati.
+- **Schema:** Ogni section type ha uno schema Zod (data, e opzionalmente settings) usato dal Form Factory per generare l'editor nell'Inspector. Gli schema sono aggregati in `SECTION_SCHEMAS`.
+- **Studio/ICE:** L'editor (Inspector) si aggancia al DOM tramite **data-jp-field** e **data-jp-item-id** / **data-jp-item-field**. L'overlay di selezione in iframe richiede che il **tenant** fornisca il CSS (TOCC).
+- **Add Section:** Il tenant espone **AddSectionConfig** (tipi addabili, label, default data) così in Studio l'utente può aggiungere section dalla libreria.
+- **Design tokens:** Le View usano variabili CSS (`--local-*`) e nessuna utility "nuda" (CIP) per coerenza e compatibilità con tema e overlay.
+
+**Perché servono (in sintesi):** Tipi e schema permettono al Core e al Form Factory di operare senza conoscere i dettagli del Tenant; IDAC permette all'Inspector di legare click in Stage e riga attiva nella sidebar (inclusa opacità attivo/inattivo); TOCC rende visibile l'overlay; AddSectionConfig definisce la libreria "Aggiungi sezione"; token e z-index evitano conflitti con l'UI di editing. Dettaglio sui "perché" per ogni specifica: spec v1.2 (§1–§10, JAP, Appendix A), dove ogni sezione ha un paragrafo **Perché servono**.
+
+---
+
+## 1.1 Valore della tipizzazione: governance e CMS UX
+
+La tipizzazione (tipi TypeScript + schema Zod) serve a **due livelli**: governance (sviluppatore/architettura) e **UX del CMS** (autore che usa Studio). Spesso si menziona solo il primo.
+
+**Governance:** registry tipizzato, SectionComponentPropsMap, forma di SiteConfig/PageConfig, audit, code-generation → coerenza tra tenant, niente drift, refactor sicuro, tooling basato su spec.
+
+**CMS UX:** lo schema Zod guida il **Form Factory** (quali widget per ogni campo: text, textarea, select, list, icon-picker, **image-picker**); **data-jp-field** e **data-jp-item-id/field** legano click in Stage e form nell'Inspector; **AddSectionConfig** dà tipi addabili, label e default. Risultato per l'autore: form coerenti, "Aggiungi sezione" con nomi e dati iniziali sensati, selezione corretta (click → form giusto), validazione con errori chiari. Senza schema e contratto tipizzato l'Inspector non saprebbe quali campi mostrare né come validare. Quindi: per la governance la tipizzazione garantisce contratti; per la **CMS UX** definisce l'**esperienza di editing** (controlli, label, default, binding). Va specificato entrambi.
+
+---
+
+## 2. Struttura progetto (completa)
+
+- **`src/data/config/site.json`** — SiteConfig (identity, pages[], header block, footer block).
+- **`src/data/config/menu.json`** — MenuConfig (es. `main: MenuItem[]`).
+- **`src/data/config/theme.json`** — ThemeConfig (tokens).
+- **`src/data/pages/<slug>.json`** — PageConfig (slug, meta, sections[]). **Per creare una nuova pagina** basta aggiungere un file `<slug>.json` in `src/data/pages/`; lo slug del nome file diventa il path della pagina (es. `chi-siamo.json` → `/chi-siamo`).
+- **`src/components/<sectionType>/`** — **Capsula piena:** View.tsx, schema.ts, types.ts, index.ts.
+- **`src/lib/base-schemas.ts`** — BaseSectionData, BaseArrayItem, BaseSectionSettingsSchema.
+- **`src/lib/schemas.ts`** — SECTION_SCHEMAS (aggregato degli schema data per tipo) + export SectionType.
+- **`src/lib/ComponentRegistry.tsx`** — Registry tipizzato: `{ [K in SectionType]: React.FC<SectionComponentPropsMap[K]> }`.
+- **`src/lib/addSectionConfig.ts`** — AddSectionConfig (addableSectionTypes, sectionTypeLabels, getDefaultSectionData).
+- **`src/types.ts`** — SectionComponentPropsMap, PageConfig, SiteConfig, MenuConfig, ThemeConfig; **module augmentation** per SectionDataRegistry e SectionSettingsRegistry; re-export da `@jsonpages/core`.
+- **`src/App.tsx`** — Bootstrap: config (tenantId, registry, schemas, pages, siteConfig, themeConfig, menuConfig, themeCss, addSection); `<JsonPagesEngine config={config} />`.
+- **CSS globale** — Include i selettori TOCC per overlay (hover/selected/type label).
+
+---
+
+## 3. Componenti (capsule + IDAC + token)
+
+- **Capsula:** Ogni section type ha View, schema (Zod), types (inferiti), index. Lo schema **data** estende BaseSectionData; gli item degli array estendono BaseArrayItem.
+- **View:** Riceve `data` e `settings` (e `menu` per header). Non importa Zod. Usa **solo** variabili CSS per colori/raggi (es. `bg-[var(--local-bg)]`), sezione root con `z-index` ≤ 1.
+- **IDAC (ICE):** Su ogni campo editabile in modo scalare: **`data-jp-field="<fieldKey>"`**. Su ogni item di array editabile: **`data-jp-item-id="<stableId>"`** e **`data-jp-item-field="<arrayKey>"`**. Così l'Inspector può legare selezione e form ai path corretti.
+- **Schema:** Usa il vocabolario UI (ECIP): `.describe('ui:text')`, `ui:textarea`, `ui:select`, `ui:number`, `ui:list`, `ui:icon-picker`, **`ui:image-picker`** (vedi §3.1). Array di oggetti editabili: ogni oggetto con `id` (BaseArrayItem).
+
+**Perché servono (componenti):** **data-jp-field** e **data-jp-item-*** servono perché lo Stage è in un iframe e il Core deve sapere quale campo/item corrisponde al click senza conoscere il DOM del Tenant: così la sidebar può evidenziare la riga attiva (anche con opacità diversa per attivo/inattivo), aprire il form sul campo giusto e gestire liste (reorder, delete). Senza IDAC, click sul canvas non si riflette nella sidebar. Schema con `ui:*` e BaseArrayItem servono al Form Factory per generare i widget giusti e mantenere chiavi stabili (reorder/delete). Token e z-index evitano che il contenuto copra l'overlay. Vedi spec §6 (IDAC), §5 (ECIP), §4 (CIP).
+
+---
+
+## 3.1 Image Picker: uso corretto nello schema (esempio `image-break`)
+
+Per i **campi immagine** il Form Factory espone il widget **Image Picker** solo se lo schema è modellato correttamente.
+
+### Regola
+
+- Il campo immagine non è una **stringa** (`z.string()`), ma un **oggetto** con almeno `url` e, opzionalmente, `alt`.
+- Lo **schema di questo oggetto** (il sub-schema) va marcato con **`.describe('ui:image-picker')`**. Il Form Factory riconosce `ui:image-picker` solo su **ZodObject** (schema oggetto), non su campi stringa.
+
+### Esempio (capsula `image-break`)
+
+**Schema (`schema.ts`):**
+
+```ts
+import { z } from 'zod';
+import { BaseSectionData } from '@/lib/base-schemas';
+
+const ImageSelectionSchema = z
+  .object({
+    url: z.string(),
+    alt: z.string().optional(),
+  })
+  .describe('ui:image-picker');
+
+export const ImageBreakSchema = BaseSectionData.extend({
+  label: z.string().optional().describe('ui:text'),
+  image: ImageSelectionSchema.default({ url: '', alt: '' }),
+  caption: z.string().optional().describe('ui:textarea'),
+});
+```
+
+- **ImageSelectionSchema** è un `z.object({ url, alt })` con **`.describe('ui:image-picker')`** sull'oggetto.
+- Il campo **`image`** nella section data usa quel schema (con default) così l'Inspector mostra il widget Image Picker per `image`.
+
+**View (`View.tsx`):**
+
+- Per il `src` dell'immagine: **`resolveAssetUrl(data.image.url, tenantId)`** (multi-tenant e path relativi).
+- Sul nodo che rappresenta l'immagine (es. il `<img>` o un wrapper): **`data-jp-field="image"`** così il click in Stage lega l'Inspector al campo `image`.
+- Altri campi editabili (caption, label) con **`data-jp-field="caption"`** e **`data-jp-field="label"`** dove appropriato.
+
+**Riferimento completo:** `apps/tenant-alpha/src/components/image-break/` (schema.ts, types.ts, View.tsx, index.ts).
+
+### Cosa evitare
+
+- **Non** usare `.describe('ui:image-picker')` su un campo **stringa** (es. `imageUrl: z.string().describe('ui:image-picker')`): il widget Image Picker si aspetta un oggetto `{ url, alt? }`.
+- **Non** dimenticare `data-jp-field="image"` sul nodo corrispondente nel DOM, altrimenti il binding Inspector ↔ Stage non funziona per quel campo.
+
+---
+
+## 4. Dati: forma e responsabilità
+
+- **site.json / menu.json / theme.json / pages/*.json** — Forma esatta come in Appendix A (SiteConfig, MenuConfig, ThemeConfig, PageConfig). Sono la source of truth quando l'utente salva da Studio (Working Draft → persist su questi file o su API che li generano).
+- **Studio** aggiorna il Working Draft; il sync con l'iframe e il "Bake" usano la stessa struttura. Quindi i dati che passi a JsonPagesEngine (siteConfig, menuConfig, pages) devono essere compatibili con ciò che l'editor modifica.
+
+Se i dati arrivano da un CMS esterno, tocca a te sincronizzare: es. export da Studio → push su CMS, oppure CMS come source e Studio in read-only; in ogni caso la **forma** delle pagine (sections con id, type, data, settings) resta quella della spec.
+
+---
+
+## 5. Registry, schemas, types, addSection
+
+- **types.ts:** Unico punto di **module augmentation** e definizione di SectionComponentPropsMap, PageConfig, SiteConfig, MenuConfig, ThemeConfig. Header: `{ data, settings?, menu: MenuItem[] }`; tutti gli altri: `{ data, settings? }`.
+- **ComponentRegistry:** Ogni chiave di SectionType ha il componente corrispondente; tipo: `{ [K in SectionType]: React.FC<SectionComponentPropsMap[K]> }`.
+- **SECTION_SCHEMAS:** Ogni chiave di SectionType ha lo **schema Zod della data** (stesso ordine del registry). Base schemas re-exportati da base-schemas.ts.
+- **addSectionConfig:** addableSectionTypes (solo i tipi che l'utente può aggiungere dalla libreria), sectionTypeLabels, getDefaultSectionData(type) che restituisce `data` valido per quello schema.
+
+**Perché servono (registry, schemas, types, addSection):** Un solo punto di augmentation (types.ts) e un solo SECTION_SCHEMAS evita duplicazioni e garantisce che registry, Form Factory e config usino gli stessi tipi. AddSectionConfig è l'unica fonte di verità per "quali section si possono aggiungere" e "con quali default"; senza, il modal "Aggiungi sezione" non avrebbe nomi né dati iniziali validi. Vedi spec §9 (ASC), Appendix A.2–A.3.
+
+---
+
+## 6. Overlay e CSS (TOCC)
+
+- Il Core inietta il markup dell'overlay (wrapper con `data-section-id`, sibling con `data-jp-section-overlay`). Il **tenant** deve fornire il CSS in modo che:
+  - `[data-jp-section-overlay]` copra la section, `pointer-events: none`, z-index alto (es. 9999).
+  - Hover e selected siano visibili (bordo tratteggiato / pieno, eventuale tint).
+  - Il type label (es. `[data-jp-section-overlay] > div`) sia posizionato e visibile su hover/selected.
+
+Senza questo, in Studio l'overlay non si vede nell'iframe.
+
+**Perché servono (TOCC):** L'iframe dello Stage carica solo il CSS del Tenant; il Core inietta il markup dell'overlay ma non gli stili. Senza i selettori TOCC nel CSS tenant, bordo hover/selected e type label non sono visibili: l'autore non vede quale section è selezionata. Vedi spec §7 (TOCC).
+
+---
+
+## 7. Checklist rapida (sviluppo grafico e dati, con CMS)
+
+| Cosa | Azione |
+|------|--------|
+| **Layout / grafico** | View con variabili `--local-*`, z-index ≤ 1, nessuna utility naked. |
+| **Dati (forma)** | SiteConfig, MenuConfig, ThemeConfig, PageConfig come in Appendix A; JSON in `data/config` e `data/pages`. |
+| **Nuova pagina** | Aggiungere un file `<slug>.json` in `src/data/pages/` (lo slug diventa il path della pagina). |
+| **Capsule** | View + schema (con ui:*) + types + index; data schema estende BaseSectionData; array item con id. |
+| **IDAC** | data-jp-field su campi scalari editabili; data-jp-item-id e data-jp-item-field su item di array. |
+| **Image Picker** | Campo immagine = oggetto `{ url, alt? }` con sub-schema `.describe('ui:image-picker')`; View con `resolveAssetUrl` e `data-jp-field="image"`. Esempio: `image-break`. |
+| **types.ts** | SectionComponentPropsMap (header con menu), augmentation, PageConfig, SiteConfig, MenuConfig, ThemeConfig. |
+| **Registry** | Tutti i tipi mappati al componente; tipo registry come in Appendix A. |
+| **SECTION_SCHEMAS** | Un entry per tipo (schema data); re-export base schemas. |
+| **addSectionConfig** | addableSectionTypes, sectionTypeLabels, getDefaultSectionData. |
+| **Config** | tenantId, registry, schemas, pages, siteConfig, themeConfig, menuConfig, themeCss, addSection. |
+| **TOCC** | CSS overlay per [data-jp-section-overlay], hover, selected, type label. |
+
+---
+
+## 8. Riferimenti spec
+
+- **Architettura e ICE:** §1–§10 (MTRP, JSP, TBP, CIP, ECIP, IDAC, TOCC, BSDS, ASC, JEB).
+- **Tipi e code-generation:** Appendix A (Core types, Tenant types, Schema contract, File paths, Integration checklist).
+- **Admin:** JAP (Studio topology, Working Draft, Bake, overlay, Green Build).
+
+Usando questo percorso hai **governance** piena: tipi, schema, editor, Add Section e overlay allineati alle spec v1.2. Per le versioni con tutti i "Perché servono" usa il file **JSONPAGES_Specs_v1.2_completo.md**.
+
+END_OF_FILE_CONTENT
+mkdir -p "docs/ver"
 echo "Creating index.html..."
 cat << 'END_OF_FILE_CONTENT' > "index.html"
 <!DOCTYPE html>
@@ -35,7 +584,7 @@ cat << 'END_OF_FILE_CONTENT' > "package.json"
     "dev": "vite",
     "dev:clean": "vite --force",
     "build": "tsc && vite build",
-    "dist": "bash ./src2Code.sh src index.html package.json",
+    "dist": "bash ./src2Code.sh src index.html scripts docs package.json",
     "preview": "vite preview",
     "bake:email": "tsx scripts/bake-email.tsx",
     "bakemail": "npm run bake:email --"
@@ -45,7 +594,7 @@ cat << 'END_OF_FILE_CONTENT' > "package.json"
     "@tiptap/extension-link": "^2.11.5",
     "@tiptap/react": "^2.11.5",
     "@tiptap/starter-kit": "^2.11.5",
-    "@jsonpages/core": "^1.0.51",
+    "@jsonpages/core": "^1.0.52",
     "clsx": "^2.1.1",
     "lucide-react": "^0.474.0",
     "react": "^19.0.0",
@@ -71,6 +620,276 @@ cat << 'END_OF_FILE_CONTENT' > "package.json"
   }
 }
 
+END_OF_FILE_CONTENT
+mkdir -p "scripts"
+echo "Creating scripts/bake-email.tsx..."
+cat << 'END_OF_FILE_CONTENT' > "scripts/bake-email.tsx"
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { render } from "@react-email/render";
+import React from "react";
+
+type Args = {
+  entry?: string;
+  out?: string;
+  outDir?: string;
+  exportName?: string;
+  propsFile?: string;
+  siteConfig?: string;
+  themeConfig?: string;
+};
+
+type BakeTarget = {
+  entryAbs: string;
+  outAbs: string;
+};
+
+type SiteConfig = {
+  identity?: {
+    title?: string;
+    logoUrl?: string;
+  };
+  header?: {
+    data?: {
+      logoImageUrl?: {
+        url?: string;
+        alt?: string;
+      };
+    };
+  };
+  footer?: {
+    data?: {
+      brandText?: string;
+      brandHighlight?: string;
+      tagline?: string;
+      logoImageUrl?: {
+        url?: string;
+        alt?: string;
+      };
+    };
+  };
+};
+
+type ThemeConfig = {
+  tokens?: {
+    colors?: Record<string, string>;
+    typography?: {
+      fontFamily?: Record<string, string>;
+    };
+    borderRadius?: Record<string, string>;
+  };
+};
+
+const DEFAULT_EMAIL_DIR = "src/emails";
+const DEFAULT_OUT_DIR = "email-templates";
+const DEFAULT_SITE_CONFIG = "src/data/config/site.json";
+const DEFAULT_THEME_CONFIG = "src/data/config/theme.json";
+
+function parseArgs(argv: string[]): Args {
+  const args: Args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const key = argv[i];
+    const next = argv[i + 1];
+    if (!next) continue;
+    if (key === "--entry") {
+      args.entry = next;
+      i += 1;
+      continue;
+    }
+    if (key === "--out") {
+      args.out = next;
+      i += 1;
+      continue;
+    }
+    if (key === "--out-dir") {
+      args.outDir = next;
+      i += 1;
+      continue;
+    }
+    if (key === "--export") {
+      args.exportName = next;
+      i += 1;
+      continue;
+    }
+    if (key === "--props") {
+      args.propsFile = next;
+      i += 1;
+      continue;
+    }
+    if (key === "--site-config") {
+      args.siteConfig = next;
+      i += 1;
+      continue;
+    }
+    if (key === "--theme-config") {
+      args.themeConfig = next;
+      i += 1;
+    }
+  }
+  return args;
+}
+
+function isComponentExport(value: unknown): value is React.ComponentType<any> {
+  return typeof value === "function";
+}
+
+function toKebabCase(value: string): string {
+  return value
+    .replace(/Email$/i, "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/[_\s]+/g, "-")
+    .toLowerCase();
+}
+
+function deriveOutAbs(entryAbs: string, outDirAbs: string): string {
+  const base = path.basename(entryAbs).replace(/\.[^.]+$/, "");
+  const fileName = `${toKebabCase(base)}.html`;
+  return path.join(outDirAbs, fileName);
+}
+
+async function discoverEmailEntries(rootDir: string): Promise<string[]> {
+  const abs = path.resolve(process.cwd(), rootDir);
+  const dirEntries = await fs.readdir(abs, { withFileTypes: true }).catch(() => []);
+  return dirEntries
+    .filter((entry) => entry.isFile())
+    .map((entry) => entry.name)
+    .filter((name) => /\.(tsx|jsx)$/i.test(name))
+    .map((name) => path.join(abs, name));
+}
+
+function normalizeUrl(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+
+async function readJsonObject<T>(filePath: string): Promise<T | null> {
+  const abs = path.resolve(process.cwd(), filePath);
+  const raw = await fs.readFile(abs, "utf8").catch(() => null);
+  if (!raw) return null;
+  const parsed = JSON.parse(raw);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  return parsed as T;
+}
+
+function buildDefaultProps(site: SiteConfig | null, theme: ThemeConfig | null): Record<string, unknown> {
+  const footerBrandText = site?.footer?.data?.brandText?.trim() ?? "";
+  const footerBrandHighlight = site?.footer?.data?.brandHighlight?.trim() ?? "";
+  const brandName = `${footerBrandText}${footerBrandHighlight}`.trim() || "{{tenantName}}";
+
+  const tenantName = site?.identity?.title?.trim() || brandName;
+  const logoUrl =
+    normalizeUrl(site?.header?.data?.logoImageUrl?.url) ||
+    normalizeUrl(site?.footer?.data?.logoImageUrl?.url) ||
+    normalizeUrl(site?.identity?.logoUrl) ||
+    "";
+  const logoAlt =
+    site?.header?.data?.logoImageUrl?.alt?.trim() ||
+    site?.footer?.data?.logoImageUrl?.alt?.trim() ||
+    brandName;
+  const tagline = site?.footer?.data?.tagline?.trim() || "";
+
+  return {
+    tenantName,
+    brandName,
+    logoUrl,
+    logoAlt,
+    tagline,
+    theme: theme?.tokens ?? {},
+    correlationId: "{{correlationId}}",
+    replyTo: "{{replyTo}}",
+    leadData: {
+      name: "{{lead.name}}",
+      email: "{{lead.email}}",
+      phone: "{{lead.phone}}",
+      checkin: "{{lead.checkin}}",
+      checkout: "{{lead.checkout}}",
+      guests: "{{lead.guests}}",
+      notes: "{{lead.notes}}",
+    },
+  };
+}
+
+async function readProps(
+  propsFile: string | undefined,
+  siteConfigPath: string,
+  themeConfigPath: string
+): Promise<Record<string, unknown>> {
+  if (propsFile) {
+    const raw = await fs.readFile(path.resolve(process.cwd(), propsFile), "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("--props must point to a JSON object file");
+    }
+    return parsed as Record<string, unknown>;
+  }
+
+  const site = await readJsonObject<SiteConfig>(siteConfigPath);
+  const theme = await readJsonObject<ThemeConfig>(themeConfigPath);
+  return buildDefaultProps(site, theme);
+}
+
+async function buildTargets(args: Args): Promise<BakeTarget[]> {
+  const outDirAbs = path.resolve(process.cwd(), args.outDir ?? DEFAULT_OUT_DIR);
+
+  if (args.entry) {
+    const entryAbs = path.resolve(process.cwd(), args.entry);
+    const outAbs = args.out ? path.resolve(process.cwd(), args.out) : deriveOutAbs(entryAbs, outDirAbs);
+    return [{ entryAbs, outAbs }];
+  }
+
+  const discovered = await discoverEmailEntries(DEFAULT_EMAIL_DIR);
+  if (discovered.length === 0) {
+    throw new Error(`No templates found in ${DEFAULT_EMAIL_DIR}`);
+  }
+
+  return discovered.map((entryAbs) => ({
+    entryAbs,
+    outAbs: deriveOutAbs(entryAbs, outDirAbs),
+  }));
+}
+
+async function bakeTemplate(target: BakeTarget, args: Args, props: Record<string, unknown>) {
+  const moduleUrl = pathToFileURL(target.entryAbs).href;
+  const mod = (await import(moduleUrl)) as Record<string, unknown>;
+  const picked = args.exportName ? mod[args.exportName] : mod.default;
+
+  if (!isComponentExport(picked)) {
+    const available = Object.keys(mod).join(", ") || "(none)";
+    throw new Error(
+      `Template export not found or not a component. Requested: ${args.exportName ?? "default"}. Available exports: ${available}. Entry: ${target.entryAbs}`
+    );
+  }
+
+  const element = React.createElement(picked, props);
+  const html = await render(element, { pretty: true });
+
+  await fs.mkdir(path.dirname(target.outAbs), { recursive: true });
+  await fs.writeFile(target.outAbs, html, "utf8");
+
+  console.log(`Baked email template: ${path.relative(process.cwd(), target.outAbs)}`);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const targets = await buildTargets(args);
+  const props = await readProps(
+    args.propsFile,
+    args.siteConfig ?? DEFAULT_SITE_CONFIG,
+    args.themeConfig ?? DEFAULT_THEME_CONFIG
+  );
+
+  for (const target of targets) {
+    await bakeTemplate(target, args, props);
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+});
+
 END_OF_FILE_CONTENT
 mkdir -p "src"
 echo "Creating src/App.tsx..."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsonpages/cli",
-  "version": "3.0.64",
+  "version": "3.0.65",
   "description": "The Sovereign CLI Engine for JsonPages.",
   "type": "module",
   "bin": {