Backend WordPress

01Panoramica

Nucleo aggiunge alla bacheca un menu di primo livello, "Nucleo AI", con 14 voci.

Ogni voce richiede una capability di WordPress. Le voci Pro restano nel menu anche in Free, bloccate.

Quasi tutte le pagine sono app React. La pagina Agenti AI è una pagina PHP.

Le pagine non hanno una API propria. Eseguono le ability nucleo/* tramite la REST API delle Abilities di WordPress.

L'editor dei documenti è una pagina nascosta (nucleo-editor). Sostituisce Gutenberg solo per i post con un documento Nucleo.

Il modello dei contenuti registra tipi, tassonomie e campi. I campi compaiono anche nelle schermate native di WordPress.

Le funzioni Pro sono nel pacchetto Pro. Gestiscono la licenza, gli aggiornamenti e l'edizione Pro.

Il pacchetto Free per WordPress.org segue le linee guida della directory. Rispetto al Free scaricato da nucleowp.dev non contiene:

• le voci Kits, Performance e License, la scheda Critical CSS service e le opzioni di riduzione del CSS: nel menu non c'è nessuna voce bloccata;
• i blocchi nc/html e nc/shortcode e la regola di qualità perf.html.block;
• le ability nucleo/component-activate e nucleo/critical-request;
• l'installazione del pacchetto di lingua dall'import del sito: la lingua si cambia in Impostazioni > Generali;
• i file di traduzione: li fornisce translate.wordpress.org.

02Menu e accesso

Menu Nucleo AI

Cosa fa: registra il menu di primo livello nucleo ("Nucleo AI") e una sottovoce per ogni voce visibile all'utente.

Come si usa: bacheca, voce "Nucleo AI" in posizione 61. Le voci, in ordine:

In Free le voci Pro, e le voci con almeno una scheda Pro bloccata, mostrano il tag PRO.

La voce nucleo-quality mostra un contatore rosso, solo per chi ha edit_others_posts.

Permessi: la voce di primo livello richiede edit_posts. Ogni sottovoce richiede la capability della tabella. Se la capability manca, la pagina risponde 403.

Edizione: Free. In Free le voci Pro restano nel menu, bloccate.

Limiti noti: le capability della tabella valgono solo per l'interfaccia. Le ability chiamate dalle pagine controllano capability ed edizione per conto loro, e possono essere più restrittive. Vedi la sezione Modello dei contenuti.

Regole di accesso

Cosa fa: calcola per ogni voce, scheda e opzione uno stato tra ok, hidden, locked, explain e readonly, con il motivo (capability, feature, plugin, edition).

Come si usa: il menu mostra le voci non nascoste, con schede e opzioni già risolte. Le pagine leggono lo stesso risultato.

Parametri: chiavi di una regola.

L'ordine dei controlli è capability, feature, plugin, edizione, scrittura. Vince la prima condizione che manca.

Permessi: dipende dalla regola.

Edizione: Free.

Limiti noti: Nucleo riconosce i plugin dalla loro presenza attiva.

Voci bloccate

Cosa fa: mostra lo stato di accesso nelle pagine.

Come si usa:

• locked: il contenuto è sfocato e inerte sotto una scheda con i pulsanti "Upgrade to Pro" e "I already have a key". Entrambi portano alla pagina Licenza.
• readonly: il contenuto è visibile con una nota informativa.
• explain: il contenuto è visibile con un testo che spiega cosa manca.
• Pagina intera bloccata: con il pacchetto Pro installato e senza licenza mostra "Nucleo Pro is installed but the license is not active.". Senza pacchetto mostra "This page is available with Nucleo Pro.".

Permessi: nessuno oltre a quelli della pagina.

Edizione: Free.

Dati di avvio delle pagine

Cosa fa: passa alle pagine admin l'oggetto window.nucleoAdmin, scritto inline prima dello script delle pagine.

Come si usa: le pagine leggono queste chiavi.

Parametri: filtro nucleo/languages (lista di codici lingua).

Permessi: nessuno oltre a quelli della pagina.

Edizione: Free.

Limiti noti: gli script si caricano solo sulle pagine di Nucleo. Gli stili si caricano anche sulla schermata di consenso OAuth.

Esecuzione delle ability dalle pagine

Cosa fa: esegue un'ability dal browser. Pagine ed editor usano la stessa chiamata.

Come si usa: le ability con annotazione readonly si leggono con GET. Le altre usano POST con corpo {input}.

GET /wp-abilities/v1/abilities/<name>/run?input[k]=v

POST /wp-abilities/v1/abilities/<name>/run
{"input": {…}}

La chiamata non lancia eccezioni. Un errore torna come {ok: false, error: {code, message}}.

Parametri: nome dell'ability e input.

Permessi: quelli dell'ability, con l'autenticazione a cookie di WordPress.

Edizione: Free.

Limiti noti: nell'editor, se manca la lista readonly, l'elenco di riserva contiene solo nucleo/doc-get, nucleo/catalog-list, nucleo/catalog-get e nucleo/doc-texts.

03Pagine admin

Panoramica (nucleo)

Cosa fa: riepiloga il sito con documenti, qualità, attività recente, layout e stato.

Come si usa: "Nucleo AI" → "Overview". La pagina carica nucleo/site-describe, nucleo/quality-scan (page: 1), nucleo/audit-list (limit: 5) e nucleo/layout-list. Solo per gli amministratori carica anche nucleo/status e nucleo/settings-get.

• "New page" apre il dialogo Nuovo documento con tipo page.
• "Open the header editor" apre il primo layout con area header. Senza layout il pulsante è disattivato.
• "Rebuild the cache" (solo amministratori) chiama nucleo/cache-rebuild.
• Con zero documenti compare il primo avvio, con tre schede: Kit, Agenti AI e pagina vuota. "Don't show again" chiama nucleo/settings-set con onboarding.dismissed: true.

Permessi: edit_posts. Le sezioni di stato richiedono manage_options.

Edizione: Free.

Limiti noti: chi non è amministratore legge "Versions, storage and conflicts are visible to administrators only.".

Pagine (nucleo-documents)

Cosa fa: elenca pagine e articoli con stato, lingua e punteggio SEO.

Come si usa: schede page ("Pages") e post ("Posts"), scelte con ?tab=, default page. La pagina chiama nucleo/doc-list e nucleo/quality-scan.

• Menu di riga: Edit, View, Text only (&view=texts) e Translate, con almeno due lingue.
• "New document" apre il dialogo Nuovo documento con il tipo della scheda.

Parametri: ricerca per titolo, lato server. Filtri per stato e lingua, lato browser.

Permessi: edit_posts.

Edizione: Free.

Limiti noti:

• 20 righe per pagina.
• I filtri per stato e lingua agiscono solo sulla pagina caricata.
• Le caselle di selezione non hanno azioni di gruppo.
• Il link "Text only" aggiunge &view=texts e l'editor apre la vista "Solo testi".

Layout (nucleo-layouts)

Cosa fa: gestisce i layout per area e le loro condizioni di visualizzazione.

Come si usa: schede per area header, footer, single, archive e popup, default header.

• "New layout" chiama nucleo/doc-create con tipo nucleo_layout e apre l'editor.
• "Conditions" apre un pannello con "Show on", "Hide on" e "Priority". Il salvataggio chiama nucleo/layout-conditions-set.
• "Which layout applies?" chiama nucleo/layout-explain.
• I conflitti di nucleo/layout-list compaiono in un avviso con "Change priority".
• La ricerca dei valori usa gli utenti, i termini e i contenuti di WordPress, con 8 risultati.

Parametri: 14 tipi di condizione.

Permessi: edit_theme_options.

Edizione: Free. La condizione language richiede Polylang o WPML. Senza, la pagina mostra "Language requires Polylang or WPML.".

Limiti noti: i campi di attivazione e frequenza dei popup sono disattivati ("Coming soon"). L'errore conflict mostra "This layout was changed elsewhere" con Reload.

Sezioni globali (nucleo-sections)

Cosa fa: elenca le sezioni riutilizzabili (nucleo_section) con il numero di pagine che le usano.

Come si usa: la pagina chiama nucleo/doc-list con postType: nucleo_section e nucleo/section-list. "New section" apre il dialogo Nuovo documento.

Parametri: ricerca lato browser.

Permessi: edit_theme_options.

Edizione: Free.

Limiti noti: il menu di riga ha solo Edit.

Design system (nucleo-design)

Cosa fa: modifica i token di design.

Come si usa: schede colors, typography, spacing, shapes e containers, default colors.

• La pagina carica nucleo/tokens-get. "Save" chiama nucleo/tokens-set con i soli token cambiati.
• L'importazione di un font chiama nucleo/fonts-import.
• "Revert changes" ripristina i valori salvati.

Parametri: vedi la sezione Design token.

Permessi: edit_theme_options.

Edizione: Free.

Limiti noti:

• Solo colori e tipografia sono modificabili. Spazi, forme e contenitori sono in sola lettura.
• Il controllo di contrasto usa la soglia 4.5.
• Un colore esadecimale non valido disattiva "Save".
• La pagina avvisa (beforeunload) se si esce con modifiche non salvate.

Kit (nucleo-kits)

Modello dei contenuti (nucleo-content)

Cosa fa: modifica tipi di contenuto, tassonomie e gruppi di campi.

Come si usa: schede postTypes, taxonomies, fieldGroups e json, default postTypes.

• La pagina carica nucleo/model-get.
• Aggiunte, modifiche e rimozioni cambiano solo la bozza. La scheda JSON applica il testo alla bozza.
• "Save" chiama nucleo/model-validate. Senza errori mostra aggiunte, rimozioni e modifiche. Ogni modifica distruttiva va spuntata.
• "Confirm" chiama nucleo/model-set con confirm uguale agli id spuntati.

Parametri: vedi la sezione Formato del modello.

Permessi: la voce e le ability nucleo/model-get, nucleo/model-validate e nucleo/model-set richiedono manage_options.

Edizione: Free. In Free i tipi di campo relation e repeater e la posizione taxonomy sono disattivati.

Limiti noti: la pagina avvisa (beforeunload) se si esce con modifiche non salvate.

Qualità e SEO (nucleo-quality)

Cosa fa: scansiona il sito e mostra i problemi per pagina.

Come si usa: schede issues, pages, overrides e rules, default issues.

• La scansione chiama nucleo/quality-scan pagina per pagina, finché next vale null.
• Se nessuna scansione è mai partita, la pagina propone "Start the first scan".
• Un clic su un titolo apre il dettaglio con nucleo/quality-check.

Permessi: edit_posts. Senza edit_others_posts la pagina è in sola lettura e le schede issues e overrides spariscono. La scheda rules richiede edit_theme_options.

Edizione: Free.

Limiti noti: la scheda overrides mostra "Not available yet". La scheda rules è una tabella statica di 19 regole. Le regole complete sono nella sezione Motore qualità.

Prestazioni (nucleo-performance)

Agenti AI (nucleo-agents)

Cosa fa: collega agenti MCP al sito. Mostra l'URL del server MCP, i client OAuth registrati, i token attivi, l'interruttore della registrazione dinamica, i domini ammessi e la regola .htaccess per l'header Authorization.

Come si usa: la pagina mostra l'URL rest_url('nucleo/v1/mcp') e le configurazioni rapide per Claude Desktop e Claude Code.

{"mcpServers":{"nucleo":{"url":"<URL del server>"}}}

# aggiunge il server MCP di Nucleo a Claude Code
claude mcp add --transport http nucleo <URL del server>

La pagina mostra anche l'alternativa STDIO, da terminale:

# server MCP su STDIO con i permessi dell'utente indicato
wp nucleo mcp --user=<login>

• La tabella dei client mostra nome, tipo (pre Pre-registered, cimd Metadata document, dcr Dynamic registration; con l'etichetta "Confidential" se ha un secret), autore dell'autorizzazione, data, ultimo uso, token di accesso attivi e scope.
• "Add agent" crea un client pre-registrato (kind = pre). Il client_id compare una sola volta.
• "Add confidential agent" crea un client con client secret. Il secret compare una sola volta, alla pagina successiva, insieme al client_id; nel database resta solo l'hash.
• "Save domains" salva l'elenco dei domini ammessi (nucleo_oauth_domains). Lista vuota: nessun vincolo. I client aggiunti a mano non sono soggetti alla lista.
• "Write the .htaccess rule" compare se le richieste degli agenti arrivano senza l'header Authorization. Scrive nel .htaccess della radice un blocco Nucleo che passa l'header a PHP.
• "Revoke tokens" porta a revoked = 2 i token ancora attivi del client. Il client resta.
• "Delete" elimina il client e tutti i suoi token, dopo conferma.
• L'interruttore salva l'opzione nucleo_oauth_dcr.

Parametri: "Add agent" e "Add confidential agent".

Permessi: manage_options per la pagina e per ogni azione. Ogni form ha un nonce.

Edizione: Free.

Limiti noti: errori dell'aggiunta: missing_name, name_too_long, invalid_redirect e save_failed. Il secret del client confidenziale resta in un transient di 60 secondi. Se le tabelle OAuth mancano, la pagina le installa.

Attività AI (nucleo-activity)

Cosa fa: mostra il registro delle operazioni delle ability e permette di annullarle.

Come si usa: la pagina carica nucleo/audit-list con limit: 200.

• Filtri lato browser: agente, utente, azione, testo del documento e "Only errors".
• "Restore" compare sulle voci riuscite di doc-patch, doc-texts-set, doc-publish, doc-rollback e doc-translate. Chiama nucleo/doc-revisions, prende la penultima revisione e, dopo conferma, chiama nucleo/doc-rollback.

Permessi: edit_posts. Senza edit_others_posts la pagina è in sola lettura, mostra solo le proprie voci e "Restore" sparisce.

Edizione: Free.

Limiti noti: 25 voci per pagina, sulle ultime 200. "Restore" torna sempre alla penultima revisione del documento, non a quella precedente alla voce scelta.

Strumenti (nucleo-tools)

Cosa fa: esporta e importa il sito, ricostruisce la cache e mostra lo stato del sistema.

Come si usa:

• "Download zip" chiama nucleo/site-export e scarica il file nucleo-export-YYYY-MM-DD.zip.
• L'import accetta un .zip o più file .json. Prima chiama nucleo/site-import con dryRun: true e mostra l'anteprima. "Import" lo ripete con dryRun: false.
• "Overwrite changes made on the site" imposta force dopo una conferma con l'elenco dei file.
• "Rebuild all" chiama nucleo/cache-rebuild. Lo stato viene da nucleo/status, con "Copy report".

Parametri: vedi la sezione Import, export e sincronizzazione.

Permessi: manage_options.

Edizione: Free.

Impostazioni (nucleo-settings)

Cosa fa: modifica le opzioni di Nucleo. Le chiavi sono descritte nella sezione Impostazioni.

Come si usa: schede editor, performance, service ("Critical CSS service"), captcha, integrations e agents, scelte con ?tab=, default editor.

• La pagina carica nucleo/settings-get. "Save changes" chiama nucleo/settings-set con il solo gruppo della scheda attiva.
• integrations mostra i plugin rilevati in sola lettura. agents rimanda alla pagina Agenti AI.

Parametri: vedi la sezione Impostazioni.

Permessi: manage_options.

Edizione: Free. La scheda service è Pro: in Free mostra il blocco Pro.

Limiti noti: la chiave del servizio e il segreto del captcha non tornano mai al browser. Un campo lasciato vuoto non si invia e conserva il valore salvato.

Licenza (nucleo-license)

Cosa fa: mostra lo stato della licenza, i piani e i form di attivazione e disattivazione.

Come si usa: la pagina mostra uno di questi stati.

Nello stato active la scadenza mostra un avviso giallo da 0 a 30 giorni e rosso se è passata, con "Renew". Il form di attivazione è descritto nella sezione Attivazione della licenza.

Parametri: filtro nucleo/license_plans, con una lista di piani {id, name, price, period, sites, description, recommended, url}.

Permessi: manage_options.

Edizione: Free. Attivazione e disattivazione esistono solo nel pacchetto Pro.

Limiti noti: la chiave arriva al browser mascherata: 12 punti più gli ultimi 4 caratteri.

Dialogo Nuovo documento

Cosa fa: crea un documento vuoto e apre l'editor.

Come si usa: pulsanti "New page", "New document" e "New section". "Create and open the editor" chiama nucleo/doc-create con title, postType, un documento vuoto e publish.

Parametri: titolo (obbligatorio), tipo page o post (se la pagina non lo fissa), "Publish now" (solo con publish_pages).

Permessi: quelli di nucleo/doc-create.

Edizione: Free.

Limiti noti: il punto di partenza "From kit template" è disattivato ("Not available yet").

Dialogo Traduzione

04Editor dei documenti

Pagina dell'editor (nucleo-editor)

Cosa fa: monta l'editor React del documento Nucleo di un post.

Come si usa: admin.php?page=nucleo-editor&post=<ID>. La pagina non compare nel menu. Il titolo è "Nucleo editor".

Parametri: post (ID del post, nella query string).

Permessi: la pagina richiede edit_posts. Il rendering richiede edit_post sul post, altrimenti risponde 403.

Edizione: Free.

Limiti noti: sotto 1024 px di larghezza l'editor forza la vista "Solo testi".

Avvio di un documento

Cosa fa: crea il documento Nucleo per un post che non lo ha.

Come si usa: se nucleo/doc-get risponde not_found, l'editor mostra "This content has no Nucleo document yet". "Start with Nucleo" chiama nucleo/doc-create con un documento vuoto, con una sezione come radice.

Permessi: quelli di nucleo/doc-create.

Edizione: Free.

Limiti noti: se il post ha già contenuto, l'editor avvisa che paragrafi, titoli ed elenchi diventano blocchi di testo. Immagini e altri elementi non passano. Nucleo conserva una copia del testo originale. Il pulsante "Open in the WordPress editor" porta alla schermata classica di WordPress.

Convivenza con Gutenberg e post.php

Cosa fa: apre l'editor Nucleo al posto di Gutenberg solo per i post con un documento Nucleo.

Come si usa:

• Per i post Nucleo l'editor a blocchi di WordPress non si apre. Il link di modifica porta all'editor Nucleo.
• post.php?action=edit su un layout o su una sezione Nucleo reindirizza all'editor Nucleo.
• post.php su un'altra pagina Nucleo resta aperto, con titolo, campi personalizzati e pubblicazione. L'editor classico sparisce e compare l'avviso "Open the Nucleo editor".
• Una pagina Nucleo in bozza con problemi di qualità bloccanti non va online da post.php, dall'editor a blocchi o con la programmazione. La REST risponde quality_blocking; post.php mantiene lo stato precedente.

Permessi: quelli di WordPress per post.php.

Edizione: Free.

Limiti noti: dopo il salvataggio da post.php di una pagina Nucleo, il link di modifica resta su post.php.

Anteprima

Cosa fa: compila il documento in memoria, senza salvarlo, e lo mostra in un riquadro isolato.

Come si usa: 300 ms dopo l'ultima modifica l'editor chiama POST /nucleo/v1/preview con il postId della pagina. L'anteprima usa il contesto del post: binding, link e lingua. Il riquadro riceve HTML, CSS, fogli di stile del sito e CSS dei token. Un clic su un elemento seleziona il nodo più vicino.

Permessi: edit_posts. Con postId, anche edit_post sul post.

Edizione: Free.

Limiti noti: le risposte arrivate dopo una più recente si scartano.

Struttura, inserimento e ispettore

Cosa fa: modifica l'albero del documento e le proprietà dei nodi.

Come si usa: vista completa a tre colonne.

• Struttura: albero con Su, Giù, Duplica ed Elimina per ogni nodo tranne la radice. Trascinamento: quarto superiore per prima, quarto inferiore per dopo, centro per dentro. Il rilascio è ammesso solo se il nodo accetta il tipo.
• Insert: catalogo cercabile per nome, titolo e descrizione, raggruppato per categoria. Il nuovo nodo va dentro il nodo scelto se lo accetta, altrimenti dopo. Senza selezione va in fondo alla radice. Gli id nuovi sono n più 7 caratteri in base 36.
• Ispettore: schede "Content", "Settings" e "Style", generate dal tipo di nodo. Lo stile ha una barra dei breakpoint base, md, lg e xl, e mostra il valore ereditato. Il campo src di nc/image apre la libreria media.

Il catalogo arriva da nucleo/catalog-list e nucleo/catalog-get.

Permessi: edit_post sul post.

Edizione: Free.

Limiti noti: la colonna dell'albero è larga da 200 a 520 px. Il valore predefinito è 260 px e resta salvato nel browser. Annulla e Ripeti tengono in memoria 100 passi e si azzerano dopo salvataggio, ripristino o ricarica.

Vista Solo testi

Cosa fa: mostra tutti i testi del documento in un unico modulo, nell'ordine della pagina.

Come si usa: selettore "Complete" o "Text only" nella barra in alto. La vista carica nucleo/doc-texts. "Save texts" chiama nucleo/doc-texts-set con baseRevision.

Permessi: edit_post sul post.

Edizione: Free.

Limiti noti: con modifiche di struttura non salvate il salvataggio viene rifiutato: "Save the structure changes first.". Tornare alla vista testi non scarta i testi non salvati. Se editor.textOnlyRoles contiene tutti i ruoli dell'utente, la vista è sempre quella dei testi. Il parametro ?view=texts apre i testi come vista iniziale (vedi il gruppo editor).

Salvataggio, pubblicazione e conflitti

Cosa fa: salva le modifiche come operazioni e pubblica il documento.

Come si usa:

• Le modifiche si accumulano come operazioni set, move, remove, duplicate e insert.
• "Save" chiama nucleo/doc-patch con baseRevision, ops e acknowledge.
• "Publish" salva la struttura, poi i testi modificati nella vista testi, poi chiama nucleo/doc-publish.
• Un problema di qualità con gravità error blocca il salvataggio. Per accettarlo serve un motivo, inviato in acknowledge come {rule, node, reason}.
• Con errore conflict l'editor mostra "The document was changed elsewhere.", con Reload (scarta le modifiche locali) e Compare (apre le revisioni).

Permessi: quelli delle ability. nucleo/doc-publish usa lo scope nucleo:publish.

Edizione: Free.

Limiti noti: "Duplica" salva subito, perché il server riassegna gli id. Con modifiche non salvate, di struttura o di testo, la barra mostra "Unsaved changes" e il browser chiede conferma prima di uscire. Le modifiche fatte durante un salvataggio restano da salvare.

Revisioni

Cosa fa: elenca le revisioni del documento e ripristina una revisione.

Come si usa: pulsante "Revisions". Carica nucleo/doc-revisions e nucleo/audit-list (limit: 100), per mostrare l'agente che ha fatto ogni modifica. "Restore" chiede conferma e chiama nucleo/doc-rollback.

Permessi: quelli delle ability.

Edizione: Free.

Limiti noti: l'ultima revisione non ha "Restore".

Pannelli laterali

Cosa fa: aggiunge all'editor schede di contesto.

Come si usa:

La scheda Links legge le sorgenti con nucleo/bind-fields. La scheda Fields compare solo se il tipo ha gruppi di campi.

Permessi: quelli delle ability.

Edizione: Free. In Free la scheda Asset mostra "The asset report is not available in the Free edition.".

Limiti noti: "Apply" nella scheda Asset riscrive l'intera lista delle regole con la regola aggiunta. Il pannello AI activity è un registro: l'editor non genera contenuti con l'AI.

Dimensioni dell'anteprima e mockup

Cosa fa: simula dispositivi nell'anteprima.

Come si usa: pulsanti dispositivo nella vista completa.

Su mobile e tablet l'interruttore "Mockup" disegna una cornice iOS o Android con barra di stato e barra dell'indirizzo.

Permessi: nessuno.

Edizione: Free.

Limiti noti: la scala dell'anteprima va da 0,1 a 1.

Scorciatoie da tastiera

Cosa fa: azioni rapide nell'editor. Mod vale Ctrl o ⌘.

Come si usa:

Permessi: nessuno.

Edizione: Free.

Limiti noti: dentro un campo di testo funzionano solo Mod+Z, Mod+Shift+Z e Mod+S. Le azioni sul nodo non agiscono sulla radice né senza selezione.

05Impostazioni

Le impostazioni si leggono con nucleo/settings-get e si scrivono con nucleo/settings-set. Entrambe richiedono manage_options e lo scope nucleo:admin.

Il salvataggio è parziale: gruppi e chiavi assenti restano come sono. Ogni valore si controlla prima di scrivere. Un errore restituisce invalid_input e non scrive nulla.

Gruppo editor

Cosa fa: salva i ruoli con la vista "Solo testi" come vista predefinita.

Come si usa: scheda editor, campo "Default view by role" per Editor, Author e Contributor.

Permessi: manage_options.

Edizione: Free.

Limiti noti: un ruolo sconosciuto restituisce "Unknown role: <ruolo>.". Il valore si salva e l'editor lo usa: se tutti i ruoli dell'utente sono nella lista, la vista iniziale è sempre quella dei testi.

Gruppo performance

Cosa fa: regola i frammenti del carrello WooCommerce e i selettori da conservare nella riduzione del CSS.

Come si usa: scheda Prestazioni. La safelist si modifica anche dalla pagina Prestazioni.

Permessi: manage_options.

Edizione: Free. I valori si usano solo nel pacchetto Pro.

Limiti noti: la lettura accetta anche una safelist salvata come stringa separata da spazi o virgole.

Gruppo service

Gruppo captcha

Cosa fa: sceglie il captcha dei moduli nativi (nc/native-form), uno per tutto il sito.

Come si usa: scheda captcha. Ogni modulo nativo mostra il captcha, salvo settings.captcha: false sul modulo.

Parametri: opzione nucleo_captcha.

Permessi: manage_options.

Edizione: Free.

Limiti noti: un threshold fuori da 0–1 restituisce "threshold" must be a number between 0 and 1.. I dettagli dei moduli sono nella sezione Moduli, dati dinamici, componenti, bindings e media.

Gruppo onboarding

Cosa fa: nasconde il primo avvio della Panoramica per l'utente corrente.

Come si usa: pulsante "Don't show again" della Panoramica.

Permessi: manage_options, come tutto nucleo/settings-set.

Edizione: Free.

Limiti noti: un utente senza manage_options non può chiudere il primo avvio, perché l'ability lo rifiuta.

Integrazioni rilevate

Cosa fa: elenca i plugin che Nucleo riconosce e cosa fa con ciascuno.

Come si usa: scheda integrations, campo integrations di nucleo/settings-get. Plugin riconosciuti: WooCommerce, Polylang, WPML, Yoast SEO, Rank Math, Contact Form 7, Complianz, Cookiebot, CookieYes e iubenda.

Permessi: manage_options.

Edizione: Free.

Limiti noti: la rilevazione controlla solo la presenza del plugin e non verifica le versioni. I dettagli sono nella sezione Integrazioni.

Opzioni salvate da quest'area

Cosa fa: riepiloga le opzioni di WordPress scritte dal backend.

Transient: nucleo_license_check (1 giorno), nucleo_license_flash_<user> (1 minuto), nucleo_fields_errors_<user> (5 minuti), nucleo_oauth_secret_<user> (60 secondi) e nucleo_quality_badge.

Edizione: Free, salvo nucleo_license.

06Modello dei contenuti e campi

Formato del modello

Cosa fa: descrive tipi di contenuto, tassonomie e gruppi di campi in un oggetto JSON.

Come si usa: si legge con nucleo/model-get, si controlla con nucleo/model-validate, si salva con nucleo/model-set o dalla pagina Modello dei contenuti. Si salva nell'opzione nucleo_content_model.

Parametri: radice {schema: 1, postTypes, taxonomies, fieldGroups}.

Tipi di campo: text, textarea, number, url, email, image, date, select, boolean, relation, repeater.

Slug: ^[a-z][a-z0-9_-]*$.

Permessi: manage_options per le tre ability. Lo scope di nucleo/model-get e nucleo/model-validate è nucleo:read, quello di nucleo/model-set è nucleo:design.

Edizione: Free. relation, repeater e la posizione taxonomy sono Pro.

Limiti noti: nucleo/model-set è parziale. Una tra postTypes, taxonomies o fieldGroups non inviata resta com'è. Una inviata sostituisce tutta la lista.

Validazione del modello

Cosa fa: controlla il modello prima del salvataggio.

Come si usa: prima lo schema JSON (codice schema), poi le regole di WordPress e dell'edizione.

Parametri: codici di errore, ognuno con path in formato JSON Pointer.

Permessi: manage_options.

Edizione: Free, con le regole Pro sopra.

Limiti noti: uno slug già nel modello salvato, o registrato dal modello nella stessa richiesta, non conta come registrato da altri. Un errore su una parte non inviata spiega che va inviata anche quella parte.

Modifiche distruttive del modello

Cosa fa: confronta il modello salvato con quello nuovo e individua le modifiche che perdono dati.

Come si usa: il confronto restituisce added, removed, changed e destructive. Gli id hanno la forma postType:<slug>, taxonomy:<slug> o field:<gruppo>/<chiave>.

Parametri: modifiche distruttive.

Permessi: manage_options.

Edizione: Free.

Limiti noti: il conteggio dei contenuti esclude bozze automatiche e cestino.

Registrazione di tipi, tassonomie e meta

Cosa fa: registra in WordPress i tipi, le tassonomie e le meta del modello.

Come si usa: la registrazione è automatica su init, in admin e sul sito pubblico. Se lo store è vuoto e mancano i token, legge l'opzione nucleo_content_model.

• Tipi e tassonomie hanno show_in_rest: true.
• Ogni campo diventa una meta single con lo schema REST del tipo: number diventa number, boolean diventa boolean, image diventa integer, relation diventa integer o array di integer, select diventa string o array, repeater diventa array di oggetti. Gli altri diventano string.

Permessi: nessuno.

Edizione: Free.

Limiti noti: un tipo o una tassonomia già registrati da altro codice non si registrano. L'origine diventa conflict.

Tipi ammessi alle ability content e terms

Cosa fa: decide quali tipi e tassonomie le ability content-* e terms-* possono leggere e scrivere, e da dove vengono.

Come si usa: un tipo è ammesso se è registrato con show_ui.

• Tipi esclusi: revision, attachment, nav_menu_item, custom_css, customize_changeset, oembed_cache, user_request, product, product_variation, e i prefissi nucleo_, wp_ e shop_.
• Tassonomie escluse: nav_menu, link_category, post_format, i prefissi nucleo_, wp_, product_ e pa_, e quelle senza un tipo ammesso.
• Origine (registeredBy): nucleo-model, wordpress, plugin-or-theme, conflict.

Permessi: con $editable l'inventario tiene solo i tipi con edit_posts e le tassonomie con manage_terms.

Edizione: Free.

Limiti noti: le pagine di sistema non si cestinano: la pagina della home, la pagina degli articoli, la pagina della privacy e le pagine di WooCommerce (shop, carrello, checkout, il mio account, termini). Dettagli in nucleo/content-upsert e nucleo/terms-set.

Riquadri dei campi

Cosa fa: mostra un riquadro per ogni gruppo di campi nella schermata di modifica del tipo (post.php, post-new.php).

Come si usa: il riquadro compare se il gruppo ha location.postType uguale al tipo. Il salvataggio avviene con il post.

• repeater: righe con aggiungi, sposta e rimuovi, con il limite max.
• image: scelta dalla libreria media.
• relation: ricerca tra i contenuti di WordPress, con 10 risultati.

Parametri: campo POST nucleo_fields[<chiave>], nonce nucleo_fields_nonce (azione nucleo_fields).

Permessi: edit_post sul post. Il salvataggio salta autosave e revisioni.

Edizione: Free. I campi relation e repeater esistono solo con un modello salvato in Pro.

Limiti noti: con un errore nessun campo si salva. Gli errori compaiono come avviso "Fields not saved:" al caricamento successivo, per 5 minuti.

Campi dei termini

Valori dei campi

Cosa fa: valida, normalizza e salva i valori dei campi del modello su post e termini.

Come si usa: riquadri dei campi, campi dei termini, scheda Fields dell'editor, nucleo/fields-get, nucleo/fields-set, nucleo/content-upsert e nucleo/terms-set.

Parametri: regole per tipo.

Permessi: quelli del chiamante.

Edizione: Free.

Limiti noti: il salvataggio è parziale e tutto o niente. Codici: unknown_field, required, invalid_value, too_many e too_few. Un valore vuoto cancella la meta. Si scrivono solo i campi del modello Nucleo: i campi di altri plugin restano a quei plugin.

07Funzioni del sito

Opzioni del sito

Cosa fa: legge e scrive titolo, tagline, homepage, pagina degli articoli, lingua, formati di data e ora, dati aziendali, icone, formati immagine e favicon.

Come si usa: nucleo/site-options-set, l'import del sito (chiave site del file site.json) e nucleo/site-describe.

Parametri: chiavi supportate.

Permessi: manage_options, scope nucleo:admin. Il download della lingua richiede install_languages (o WP-CLI senza utente) e accesso diretto ai file.

Edizione: Free.

Limiti noti: errori invalid_input, page_not_found, same_page e language_unavailable. La lingua si applica per ultima: se il pacchetto non si scarica, le altre opzioni restano scritte. Per le pagine figlie lo slug è il percorso (servizi/consulenza).

Menu di navigazione

Cosa fa: crea un menu di WordPress per slug, sostituisce le sue voci ed esporta i menu.

Come si usa: nucleo/menu-list, nucleo/menu-set, import ed export del sito.

Parametri: una voce ha label e uno di questi bersagli.

children contiene le voci figlie.

Permessi: nucleo/menu-list richiede edit_posts (scope nucleo:read). nucleo/menu-set richiede edit_theme_options (scope nucleo:design).

Edizione: Free.

Limiti noti:

• Al massimo 3 livelli.
• Errori: invalid_items e menu_target_missing.
• I bersagli si risolvono prima di cancellare le voci vecchie: un bersaglio mancante non lascia il menu a metà.
• Dopo la scrittura i layout che usano il menu si ricompilano subito.
• L'export salta le voci senza bersaglio pubblicato.

Icone del sito

Cosa fa: salva icone SVG per il blocco nc/icon, accanto al set interno.

Come si usa: nucleo/icons-set (aggiunge, sostituisce, rimuove) oppure la chiave icons delle opzioni del sito, che sostituisce tutto. Nel blocco nc/icon un'icona del sito vince su un'icona interna con lo stesso nome.

Parametri:

Permessi: manage_options, scope nucleo:admin.

Edizione: Free.

Limiti noti:

• Al massimo 300 icone.
• Elementi ammessi: svg, g, path, circle, ellipse, rect, line, polyline e polygon. Gli altri si tolgono.
• fill e stroke diversi da none diventano currentColor.
• Il rendering aggiunge width="24" height="24" focusable="false".
• Un set vuoto cancella l'opzione nucleo_icons.

Lacune segnalate

Cosa fa: registra ciò che un design chiede e Nucleo non sa fare, con il ripiego usato.

Come si usa: nucleo/gap-report e nucleo/gap-list.

Parametri:

Permessi: nucleo/gap-report richiede edit_pages (scope nucleo:write). nucleo/gap-list richiede edit_posts (scope nucleo:read).

Edizione: Free.

Limiti noti: la stessa coppia block e need, senza maiuscole, incrementa count e aggiorna last e workaround. Si conservano le ultime 200 lacune.

Export, import e riferimenti simbolici

Cosa fa: esporta e importa il sito come file JSON. Sostituisce gli ID con simboli leggibili (page:chi-siamo, section:cta) e viceversa.

Come si usa: pagina Strumenti, nucleo/site-export, nucleo/site-import, wp nucleo export, wp nucleo import e wp nucleo sync.

Parametri: vedi la sezione Import, export e sincronizzazione.

Permessi: manage_options, scope nucleo:admin.

Edizione: Free.

Limiti noti: tipi importati: page, post, nucleo_layout e nucleo_section, in quest'ordine per cartella: sections/, pages/, posts/, layouts/. Codici di errore: error, conflict, duplicate, not_json, invalid_document e quality_blocking. Un valore senza nome resta numerico.

08Licenza Pro e aggiornamenti

Pacchetti Free e Pro

Edizione attiva

Attivazione della licenza

Disattivazione della licenza

Verifica della licenza

Licenza attiva e scadenza

Aggiornamenti del plugin Pro

09REST e azioni admin-post

POST /nucleo/v1/preview

Cosa fa: compila un documento senza salvarlo e restituisce HTML, CSS e stili per l'anteprima.

Come si usa: il corpo della richiesta contiene il documento. La risposta contiene l'esito della compilazione, più gli stili del blocco e del tema, se ci sono, e il CSS dei token.

POST /wp-json/nucleo/v1/preview
{"document": {…}}

Parametri:

Permessi: edit_posts.

Edizione: Free.

Limiti noti: un document non oggetto restituisce invalid_input con stato 400. Un documento non valido restituisce un esito con ok: false.

Azioni admin-post

Cosa fa: gestisce i form di Agenti AI e Licenza tramite admin-post.php.

Come si usa:

Parametri: ogni form ha il nonce con il nome dell'azione.

Permessi: manage_options. Senza, risposta 403.

Edizione: Free per le azioni OAuth, Pro per quelle della licenza.

Limiti noti: le azioni della licenza esistono solo nel pacchetto Pro.

Altre route chiamate dal backend

Cosa fa: elenca le route REST usate dalle pagine ma registrate fuori da quest'area.

Come si usa:

• GET /nucleo/v1/kit-preview?kit=<id>: miniatura dei kit. Richiede edit_theme_options e l'edizione Pro. Vedi la sezione Kit.
• /nucleo/v1/mcp: server MCP. Vedi la sezione Agenti AI.
• Route di WordPress: /wp/v2/search, /wp/v2/media/<id>, /wp/v2/users e /wp/v2/<taxonomy>.

Parametri: vedi le sezioni citate.

Permessi: vedi le sezioni citate.

Edizione: vedi sopra.