Kit

01Panoramica

Un kit è un sito di partenza: colori, pagine, header e footer pronti, scritti come documenti JSON.

Ogni kit è una cartella con lo stesso formato di un export del sito.

L'elenco dei kit legge i file di ogni kit. nucleo/kit-apply li importa con lo stesso import di nucleo push e di nucleo/site-import.

La route nucleo/v1/kit-preview compila la home del kit con header e footer, per la miniatura nella pagina admin Kit.

I kit sono una funzione Pro: le ability nucleo/kit-list e nucleo/kit-apply si registrano solo con licenza attiva, e la route di anteprima la controlla.

Il plugin contiene quattro kit: artigiano, ecommerce, ristorante e studio-professionale.

02Struttura di un kit

Cartella e manifest kit.json

Cosa fa: identifica il kit e ne descrive nome e requisiti.

Come si usa: una cartella con un file kit.json. L'id del kit è il nome della cartella.

Parametri:

Permessi: Nessuno.

Edizione: Pro.

Limiti noti:

• Un kit.json non leggibile, non JSON o senza name e description di tipo stringa esclude il kit dall'elenco.
• L'id deve rispettare ^[a-z0-9-]+$. Altrimenti il kit non viene letto.
• Un requisito sconosciuto non è mai soddisfatto.

File del kit

Cosa fa: forniscono token e documenti nel formato della cartella del sito.

Come si usa: Nucleo legge tutti i file .json della cartella, sottocartelle comprese.

Parametri: file presenti nei kit del plugin.

Il blocco wp di ogni documento porta title, slug, status e postType. L'import lo usa per creare il post.

Permessi: Nessuno.

Edizione: Pro.

Limiti noti:

• Nessun kit ha cartelle sections/, menus/, media/ o un blocco site in site.json. Il kit non crea sezioni globali, menu, media né impostazioni del sito.
• Il nodo nc/menu dell'header non ha l'impostazione menu: non mostra voci finché qualcuno non assegna un menu.
• Le immagini puntano a URL esterni https://picsum.photos/seed/…. L'import non le scarica nella libreria media.
• site.json non ha base né tokensBase: l'import non rileva conflitti con il sito (vedi nucleo/kit-apply).
• Ogni kit deve rispettare queste regole di stile: 8 colori esadecimali a 6 cifre; almeno 2 fasce nc/section con padding per pagina; almeno una fascia con background; almeno una griglia nella home; header e footer con padding e background.

03Kit disponibili

artigiano

Cosa fa: sito per una bottega artigiana di arredi su misura, "Bottega Gallo" di Verona. Descrizione: "Sito per una bottega artigiana: lavorazioni, progetti su misura e preventivi."

Come si usa: nucleo/kit-apply con {"kit": "artigiano"}.

Parametri: contenuto.

Colori: primary #2F6B4F, secondary #5B3A29, accent #E8C9A0, text #222222, muted #5A554D, background #F7F4EF, surface #E9E4DA, border #D8CFBF.

Permessi: come nucleo/kit-apply.

Edizione: Pro.

Limiti noti: Nessun requisito. Indirizzi, telefoni ed email sono dati di esempio (dominio .example).

ecommerce

Cosa fa: negozio online di ceramiche artigianali, "Officina Argilla" di Faenza. Descrizione: "Negozio online di ceramiche artigianali: catalogo, schede prodotto, carrello e pagine informative."

Come si usa: nucleo/kit-apply con {"kit": "ecommerce"}. Richiede WooCommerce attivo.

Parametri: contenuto.

Colori: primary #8A4B2A, secondary #2F4858, accent #F2D2B6, text #2E2620, muted #5F554C, background #FAF7F2, surface #EFE7DC, border #E0D4C4.

Permessi: come nucleo/kit-apply.

Edizione: Pro.

Limiti noti: senza WooCommerce il kit non compare in nucleo/kit-list, e nucleo/kit-apply risponde kit_unknown. I blocchi woo/* sono descritti nella documentazione delle integrazioni.

ristorante

Cosa fa: sito per un ristorante, "Trattoria Il Faro" di Firenze. Descrizione: "Sito per un ristorante: menu, storia della cucina, prenotazioni e orari."

Come si usa: nucleo/kit-apply con {"kit": "ristorante"}.

Parametri: contenuto.

Colori: primary #9C2F1F, secondary #2E3B2C, accent #F1D7A6, text #2B1B12, muted #5E4A3C, background #FBF6EE, surface #F3E9DA, border #E4D5BF.

Permessi: come nucleo/kit-apply.

Edizione: Pro.

Limiti noti: Nessun requisito. La sezione "Il menu" è testo statico: non usa il blocco nc/menu.

studio-professionale

Cosa fa: sito per uno studio di consulenza fiscale e aziendale, "Studio Bianchi Consulenza" di Milano. Descrizione: "Sito per uno studio di consulenza: servizi, team e contatti in tono sobrio."

Come si usa: nucleo/kit-apply con {"kit": "studio-professionale"}.

Parametri: contenuto.

Colori: primary #1E4D78, secondary #16324A, accent #BFD7EE, text #1F2933, muted #4B5563, background #FFFFFF, surface #EEF3F8, border #D5DEE8.

Permessi: come nucleo/kit-apply.

Edizione: Pro.

Limiti noti: Nessun requisito.

04Elenco, anteprima e applicazione

nucleo/kit-list

Cosa fa: restituisce i kit disponibili con id, name, description e requires, in ordine alfabetico di cartella.

Come si usa: ability via MCP o dalla pagina admin Kit. Vedi nucleo/kit-list nelle abilities di lettura.

Parametri: Nessuno. Uscita {"kits": [...]}.

Permessi: edit_posts; scope nucleo:read.

Edizione: Pro (senza licenza l'ability non esiste).

Limiti noti: esclude i kit con requisiti non soddisfatti. Il kit ecommerce sparisce senza WooCommerce invece di comparire come non disponibile.

Anteprima GET /nucleo/v1/kit-preview

Cosa fa: compila header, home e footer del kit, in quest'ordine. Aggiunge alle variabili del sito quelle dei token del kit, così vincono i colori del kit.

Come si usa: GET /wp-json/nucleo/v1/kit-preview?kit=artigiano. La pagina admin Kit la usa per la miniatura di ogni kit.

Parametri:

Risposta: ok, html, css, styles (bundle dei blocchi e base.css del tema), tokensCss.

Permessi: edit_theme_options e licenza Pro attiva. Senza uno dei due: HTTP 403.

Edizione: Pro.

Limiti noti: kit sconosciuto o id non valido: not_found, HTTP 404. Non controlla i requisiti del kit. Un documento che non compila si salta senza errore. Il blocco wp dei documenti si toglie prima della compilazione.

nucleo/kit-apply

Cosa fa: applica un kit al sito. Scrive i token del kit, crea o aggiorna pagine e layout per slug e tipo di post, e pubblica le pagine. Con dryRun conta senza scrivere.

Come si usa: ability via MCP o dalla pagina admin Kit. Esempio: {"kit": "ristorante", "dryRun": true}.

Parametri:

Uscita: il report dell'import, con created, updated, unchanged, errors (file, message, code), warnings, ids (simbolo → ID, per esempio page:home) e base.

Permessi: edit_theme_options; scope nucleo:design.

Edizione: Pro.

Limiti noti:

• Token uniti, non sostituiti: per ogni chiave vince il valore del kit, le altre chiavi salvate nel sito restano. Il kit definisce solo il gruppo color (8 chiavi): spazi, font, raggi e ombre del sito restano invariati.
• Pagine e layout sovrascritti: un post con lo stesso slug e tipo si aggiorna. Il kit non ha base, quindi l'import non segnala conflitti con modifiche fatte sul sito. Un post uguale al documento del kit resta invariato (unchanged).
• Pagina iniziale: se il sito mostra gli articoli in home (show_on_front diverso da page), la home del kit diventa la pagina iniziale. Un sito con una pagina iniziale già scelta la tiene.
• Non ha un'opzione force e non accetta consensi (acknowledge) per le segnalazioni bloccanti del motore qualità.
• Errori: invalid_input (tipi errati), kit_unknown (kit inesistente o con requisiti non soddisfatti). Il codice requires_missing non è raggiungibile con i requisiti attuali, perché il kit esce già dall'elenco.
• Le annotazioni dichiarano destructive: false e idempotent: true.
• Il registro di attività registra kit-apply con esito dry-run o import.

Pagina admin Kit

Cosa fa: mostra una card per kit con miniatura, nome, descrizione e requisiti. Offre "Preview changes" (dry run) e "Apply" con conferma.

Come si usa: menu Nucleo AI → Kit. La pagina chiama nucleo/kit-list, la route nucleo/v1/kit-preview e nucleo/kit-apply.

Parametri: Nessuno.

Permessi: edit_theme_options.

Edizione: Pro. Senza licenza la pagina mostra un blocco e non chiama nucleo/kit-list.

Limiti noti:

• Senza WooCommerce il pulsante "Apply" del kit ecommerce è disattivato e la card spiega il motivo. Poiché nucleo/kit-list nasconde il kit, la card in pratica non compare.
• La conferma ricorda che i token del kit si uniscono al design system e che le pagine con lo stesso slug vengono aggiornate.