Abilities di lettura

01Panoramica

Le ability di lettura mostrano lo stato del sito agli agenti AI e all'editor. Ogni ability ha un nome, gli argomenti, un'esecuzione e un permesso. Nucleo le registra con l'Abilities API di WordPress nella categoria nucleo, con show_in_rest: true.

Il server MCP pubblica ogni ability come tool, con / sostituito da -: nucleo/doc-get diventa nucleo-doc-get. OAuth, scope, rate limit e formato comune degli esiti sono descritti in Server MCP, OAuth e meccanismi comuni.

Regole comuni a tutte le ability di questo capitolo:

• Permesso in due passi. Per prima cosa Nucleo controlla la capability WordPress. Se la richiesta porta un token OAuth, controlla poi che il token abbia lo scope dell'ability. Senza scope risponde con WP_Error insufficient_scope e stato 403. Senza token (cookie, Application Password, WP-CLI) vale solo la capability.
• Annotazioni. Tutte dichiarano readonly: true, destructive: false, idempotent: true.
• Rate limit. Il limite di frequenza vale solo per le ability non readonly. Le ability di questo capitolo non lo consumano.
• Input vuoto. Le ability senza campi obbligatori accettano un input vuoto. Così una lettura REST in GET funziona senza parametri.
• Esito. Quasi tutte rispondono { ok: true, ... } o { ok: false, error: { code, message } }. Un input malformato produce spesso un WP_Error con codice invalid_input. Otto ability non hanno la chiave ok nell'esito: nucleo/layout-list, nucleo/layout-explain, nucleo/assets-report, nucleo/quality-scan, nucleo/site-export, nucleo/kit-list, nucleo/css-status, nucleo/menu-list.
• Edizione. Sono Pro solo queste tre ability: nucleo/assets-report, nucleo/kit-list, nucleo/css-status. Senza licenza attiva non si registrano.

Tabella riassuntiva:

02Sito e stato

nucleo/site-describe

Cosa fa: restituisce un riepilogo del sito per l'agente. Contiene nome, URL, lingua, formati di data e ora, ambiente, versione di Nucleo, breakpoint, token, blocchi disponibili, numero di documenti, tipi di contenuto e tassonomie, avvisi, stato della cache, ID delle regole di qualità e budget di performance.

Come si usa: ability nucleo/site-describe, tool MCP nucleo-site-describe. Input {}.

Parametri: nessuno. additionalProperties: false.

Esito: { ok: true, name, url, language, dateFormat, timeFormat, warnings, environment, nucleoVersion, breakpoints, tokens, blocks, documentCount, content, cache, layouts, plugins, quality, budgets }.

• environment: valore di wp_get_environment_type(), uno tra local, development, staging, production.
• breakpoints: oggetto nome → larghezza minima in pixel.
• blocks: elenco { name, title, category }.
• documentCount: post di qualunque tipo e stato con il meta _nucleo_doc.
• content: { postTypes, taxonomies }, voci { slug, label, modeled, registeredBy }. registeredBy vale nucleo-model, wordpress, plugin-or-theme o conflict. Contiene solo i tipi che l'utente può modificare.
• warnings: elenco di testi. Segnala il pacchetto di lingua mancante, il formato data inglese F j, Y su un sito non inglese, i layout con condizioni che il runtime non applica e gli avvisi del registro mail di sviluppo.
• cache: { empty: false }, oppure { empty: true, message } quando lo store di Nucleo è vuoto ma il database ha contenuti Nucleo.
• layouts: elenco dei layout attivi.
• plugins: elenco { id, name, active, does } delle integrazioni rilevate, come in nucleo/settings-get.
• quality: elenco degli ID delle regole di qualità.
• budgets: budget di performance delle regole di qualità: CSS e JS in byte serviti da Nucleo, DOM in nodi stimati. Vedi nucleo/status.

Nessun codice di errore.

Permessi: edit_posts. Scope nucleo:read.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: con locale en_US o vuoto non produce avvisi di lingua. Legge tutti i layout (numberposts: -1) per gli avvisi sulle condizioni.

nucleo/status

Cosa fa: restituisce versione di Nucleo, PHP e WordPress, il driver dello store degli artefatti, il numero di documenti, i plugin di cache in conflitto, gli artefatti salvati, la coda di ricostruzione, la data dell'ultima build e i budget di performance.

Come si usa: ability nucleo/status. Input {}.

Parametri: nessuno.

Esito: { ok: true, nucleoVersion, php, wordpress, store, documentCount, conflicts, artifacts, queue, failed, stale, lastBuild, budgets }.

• store è il nome breve dello store attivo. conflicts è un elenco { plugin, issue, fix }: plugin di cache che annullano le varianti CSS dei template Nucleo.
• artifacts: { count, bytes }, numero e dimensione dei file degli artefatti.
• queue: intero, documenti in attesa di una ricostruzione in background. Dopo un aggiornamento del plugin ogni documento entra in coda una volta, quindi queue conta tutti i documenti finché la ricostruzione non termina.
• failed: ricostruzioni in background fallite, come { id, attempts, code, message }. Dopo 3 tentativi il documento esce dalla coda.
• stale: ID dei documenti che non si possono ricostruire: una sezione non valida, o problemi di qualità bloccanti su un post pubblicato. Un documento stale conserva l'HTML precedente e può comparire anche in failed. Al massimo 50.
• lastBuild: data ISO 8601 dell'ultima modifica degli artefatti, oppure null.
• budgets: budget di performance delle regole di qualità: CSS e JS in byte serviti da Nucleo, DOM in nodi stimati. I filtri nucleo/quality/{css,js,dom}_budget li cambiano.

Nessun codice di errore.

Permessi: manage_options. Scope nucleo:admin.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: nessuno rilevato.

nucleo/settings-get

Cosa fa: restituisce le impostazioni di Nucleo e le integrazioni rilevate. La chiave del servizio esterno non esce mai: l'esito dice solo se è impostata.

Come si usa: ability nucleo/settings-get. Input {}.

Parametri: nessuno.

Esito: { ok: true, settings, integrations }.

• settings.editor.textOnlyRoles: ruoli limitati ai testi.
• settings.performance.wooFragments: keep o off. settings.performance.purgeMode: normal o strict. settings.performance.purgeSafelist: elenco di selettori. settings.performance.subsets: elenco di sottoinsiemi di caratteri.
• settings.quality.nonForcible: ID delle regole di qualità che non si possono forzare per pubblicare. settings.quality.thinWords: numero minimo di parole per tipo di post.
• settings.service: { url, keySet }.
• settings.captcha: { provider, siteKey, secretSet, threshold }.
• settings.onboarding.dismissed: stato del primo avvio per l'utente corrente.
• integrations: elenco { id, name, active, does } per woocommerce, polylang, wpml, yoast, rankmath, contact-form-7, complianz, cookiebot, cookieyes, iubenda.

Nessun codice di errore.

Permessi: manage_options. Scope nucleo:admin.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: nessuno rilevato. Per scrivere: nucleo/settings-set.

03Guida

nucleo/guide

Cosa fa: restituisce una fase della guida a fasi: stato del sito, regole della fase, cose da fare, condizioni di uscita e fase successiva. Senza phase calcola la fase corrente dallo stato del sito.

Come si usa: ability nucleo/guide. Esempio: { "phase": 2, "design": "design/home.html" }. Dettagli sulle fasi in Guida a fasi.

Parametri:

Esito: { ok: true, phase, title, state, basics, todo, rules, exit, next }.

• state: tokens, sections, layouts, menus, postTypes, documents, checks e altri dati dello stato del sito.
• basics: regole della fase 0 in forma breve { code, text }. Vuoto con phase 0.
• rules: { code, text, tools }. next: stringa o null.
• Errore: WP_Error nucleo_guide_phase se phase è fuori da 0–4.
• Se la cache è vuota, todo inizia con un avviso di cache.

Permessi: edit_posts. Scope nucleo:read.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: i controlli leggono al massimo 1000 documenti: prima layout e sezioni, poi i più recenti. Oltre il tetto todo riporta quanti documenti ha letto.

04Catalogo e componenti

nucleo/catalog-list

Cosa fa: elenca i blocchi Nucleo registrati con titolo, categoria e descrizione breve.

Come si usa: ability nucleo/catalog-list. Input {}.

Parametri: nessuno.

Esito: { ok: true, blocks }, voci { name, version, title, category, description }. Nessun codice di errore.

Permessi: edit_posts. Scope nucleo:read.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: nessuno rilevato.

nucleo/catalog-get

Cosa fa: con name restituisce il manifest completo di un blocco, le chiavi di stile dei suoi gruppi, il markup HTML e il CSS di base. Con names restituisce più blocchi in forma compatta. Con topic restituisce un argomento di riferimento che nessun manifest contiene.

Come si usa: ability nucleo/catalog-get. Esempi: { "name": "nc/heading" }, { "names": ["nc/section", "nc/heading", "nc/button"] }, { "topic": "layouts" }. Usa names per leggere i blocchi di una pagina in una chiamata, e name per il CSS di base di un singolo blocco.

Parametri:

Serve uno tra name, names e topic.

Esito:

• Con name: { ok: true, block }. block contiene name, version, title, category, description, aiHints, content, settings, supports, parts, children, parents, assets, semantics, renderer, styleKeys, markup, css. markup viene da nucleo/data/block-markup.json. css è il file style del manifest, vuoto se manca.
• Con names: { ok: true, blocks, styleKeys, remaining? }. Ogni voce di blocks è { name, ok, block }, oppure { name, ok: false, error } per un blocco sconosciuto. block ha i campi di name senza styleKeys, css, renderer e assets, e aggiunge styleGroups. styleKeys in cima elenca una volta le chiavi di tutti i gruppi. Una chiave senza number dà px a un numero. La risposta resta sotto 25.000 caratteri: il primo blocco entra sempre, i nomi successivi che non entrano vanno, in ordine, in remaining. Chiedili con una seconda chiamata.
• Con topic: { ok: true, topic: { topic, summary, rules, data } }. tokens include i token correnti. theme include base.css solo se il tema attivo è nucleo-canvas. styles include i gruppi di stile di ogni blocco. woocommerce restituisce il riferimento WooCommerce: i blocchi woo/*, le aree product e product-archive, una ricetta per pagina e gli strumenti del checkout.
• Errori: WP_Error invalid_input senza name, names o topic, oppure con names che non è una lista di 1–20 nomi. { ok: false, error: { code: "not_found" } } per blocco o argomento sconosciuto.

Permessi: edit_posts. Scope nucleo:read.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: names accetta al massimo 20 nomi. Un blocco senza gruppi di stile ha styleKeys vuoto.

nucleo/docs-search

Cosa fa: cerca per termini negli argomenti di riferimento di nucleo/catalog-get e nei manifest dei blocchi. Restituisce i risultati migliori, ordinati per numero di occorrenze dei termini: argomento o blocco, titolo e un estratto.

Come si usa: ability nucleo/docs-search, tool MCP nucleo-docs-search. Esempio: { "query": "contrast token", "limit": 5 }. Serve quando il nome dell'argomento o del blocco non è noto. Con il nome già noto si chiama direttamente nucleo/catalog-get.

Parametri:

Esito: { ok: true, results }. Ogni voce di results è { topic, title, excerpt } per un argomento, oppure { block, title, excerpt } per un blocco. Il title di un argomento è il suo nome. excerpt è il testo dell'argomento (sintesi e regole) o la descrizione del blocco, tagliato a 200 caratteri con ....

• Errore: WP_Error invalid_input se query non è una stringa di 2–100 caratteri o se limit non è un intero da 1 a 20.

Permessi: edit_posts. Scope nucleo:read.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: cerca solo negli argomenti di riferimento (gli stessi di nucleo/catalog-get con topic) e nei manifest dei blocchi. Non cerca nei documenti, nei contenuti né nelle sorgenti dei componenti. Nessuna paginazione: al massimo 20 risultati.

nucleo/components-list

Cosa fa: elenca le sorgenti dati e le azioni registrate dai plugin del sito con l'hook nucleo/register_components. Restituisce nomi e schemi, mai codice.

Come si usa: ability nucleo/components-list. Input {}. I nomi servono in nc/collection (sorgente component) e nc/native-form (azione component). Vedi dati dinamici.

Parametri: nessuno.

Esito: { ok: true, dataSources, actions }. Nessun codice di errore.

Permessi: edit_pages. Scope nucleo:read.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: i blocchi dei componenti non compaiono qui: si leggono con nucleo/catalog-get.

nucleo/tokens-get

Cosa fa: restituisce i design token correnti del sito, raggruppati per categoria.

Come si usa: ability nucleo/tokens-get. Input {}. Formato in Design token.

Parametri: nessuno.

Esito: { ok: true, tokens }. Nessun codice di errore.

Permessi: edit_posts. Scope nucleo:read.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: nessuno rilevato.

05Documenti

nucleo/doc-list

Cosa fa: elenca i post con un documento Nucleo (meta _nucleo_doc), dal più recente per data di modifica. Filtra per stato e per esito del controllo qualità.

Come si usa: ability nucleo/doc-list. Esempio: { "postType": "page", "search": "contatti", "page": 2 }.

Parametri:

Esito: { ok: true, items, page, total }. Voci { id, title, status, revision, link, modified, author, lang, quality }. modified è ISO 8601 UTC. author è il nome visualizzato o "". lang è lo slug della lingua del plugin multilingua, "" senza plugin. quality è l'ultimo controllo salvato con il documento (con score), oppure null se il documento non è mai stato controllato.

• Errori: WP_Error invalid_input per tipi sbagliati. { ok: false, error: { code: "invalid_post_type" } } per un tipo inesistente.

Permessi: edit_posts. Scope nucleo:read. La query usa perm: editable: elenca solo i post che l'utente può modificare.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: 20 voci per pagina, fisse. Include tutti gli stati tranne il cestino.

nucleo/doc-get

Cosa fa: restituisce un documento, intero o a partire da un nodo, con una profondità massima. Con format compact (predefinito) la forma è compatta; con full il documento arriva completo. Restituisce anche la revisione.

Come si usa: ability nucleo/doc-get. Esempi: { "postId": 42, "nodeId": "hero", "depth": 1 }, { "postId": 42, "format": "full" }.

Parametri:

Esito: { ok: true, postId, revision, document }. La forma compatta omette le impostazioni uguali al default del blocco.

• Errori: WP_Error invalid_input. { ok: false, error } con not_found (documento o nodo assente) o invalid_op (depth negativo).

Permessi: edit_post sul postId. Scope nucleo:read.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: depth non si applica con format full.

nucleo/doc-texts

Cosa fa: restituisce tutti i testi traducibili di un documento come { id, path, text }, senza struttura, con la revisione da passare a nucleo/doc-texts-set.

Come si usa: ability nucleo/doc-texts. Esempio: { "postId": 42 }.

Parametri:

Esito: { ok: true, revision, texts }. path vale content.<campo> oppure content.<campo>.<indice>.<sottocampo> per le liste. Ordine di albero.

• Errori: WP_Error invalid_input. { ok: false, error: { code: "not_found" } }.

Permessi: edit_post sul postId. Scope nucleo:read.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: considera solo i campi content marcati translatable: true nel manifest e solo valori stringa. Salta i nodi di blocchi non registrati.

nucleo/doc-revisions

Cosa fa: elenca le revisioni di un documento: numero, ora, utente WordPress, client e un riepilogo delle modifiche. Non include il contenuto. Per tornare a una revisione: nucleo/doc-rollback.

Come si usa: ability nucleo/doc-revisions. Esempio: { "postId": 42 }.

Parametri:

Esito: { ok: true, postId, revisions }, voci { rev, time, user, client, summary }. time è un timestamp Unix. user è l'ID utente. client identifica il client che ha scritto la revisione. summary vale created per la prima revisione, altrimenti +a ~c -r: nodi aggiunti, modificati e rimossi.

• Errori: WP_Error invalid_input. { ok: false, error: { code: "not_found" } } se il post non esiste.

Permessi: edit_post sul postId. Scope nucleo:read.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: un post senza documento restituisce revisions vuoto, non un errore.

nucleo/doc-validate

Cosa fa: valida un documento senza salvarlo. Restituisce gli errori di schema e, se il documento è valido, il report qualità.

Come si usa: ability nucleo/doc-validate. Esempio: { "document": { "schema": ..., "root": { ... } } }.

Parametri:

Esito: { ok, errors, warnings?, quality? }. ok è true se non ci sono errori. Ogni errore porta percorso JSON, valore, valori ammessi e correzione. quality è { score: { seo, a11y, perf }, blocking, issues } ed è presente solo senza errori.

• Riferimenti: media:<file> in content.src diventa un URL segnaposto e produce un warning. menu:<slug> in settings.menu di nc/menu diventa l'ID del menu, oppure un errore se il menu non esiste.
• Controlla sempre le condizioni dei layout.
• Con postType page (predefinito) un documento si controlla con i layout di una pagina generica del sito (header, prima e dopo il contenuto, footer), come al salvataggio: i loro landmark contano, i loro problemi non compaiono. Restano fuori i layout legati a un post, a un termine o alla home.
• Errore: WP_Error invalid_input se document non è un oggetto.

Permessi: edit_posts. Scope nucleo:read.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: non salva nulla. I riferimenti media:<file> non vengono risolti davvero: il file si risolve solo al push.

nucleo/doc-preview

Cosa fa: compila un documento senza salvarlo e restituisce HTML e CSS. Con postId compila il documento salvato nel contesto del post (binding, link, lingua) e aggiunge un link firmato di anteprima. Con contextPostId riempie gli slot dinamici (woo/*, binding) come nella pagina di quel post: così un layout prodotto si vede su un prodotto vero.

Come si usa: ability nucleo/doc-preview. Esempi: { "postId": 42 }, { "document": { ... } }.

Parametri:

Esito: { ok: true, html, css, previewUrl? }. previewUrl è presente solo con postId e vale 30 minuti (1800 secondi). Il token è firmato con HMAC-SHA256.

• Errori: WP_Error invalid_input con entrambi o nessuno dei campi. { ok: false, error: { code: "not_found" } }. { ok: false, error: { code: "invalid_document", message, errors } } per errori di schema.

Permessi: con postId, edit_post sul post. Senza, edit_posts. Con contextPostId, anche read_post su quel post. Scope nucleo:read.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: l'HTML è quello compilato, con il fallback degli slot dinamici: moduli, collezioni e altri slot non si riempiono. L'anteprima non compone i layout delle aree.

06Qualità

nucleo/quality-check

Cosa fa: produce il report qualità (SEO, accessibilità, performance) di un documento salvato, individuato per ID o per URL della pagina, oppure di un documento passato in input. I problemi riconosciuti con acknowledge non bloccano. Regole e codici in Motore qualità.

Come si usa: ability nucleo/quality-check. Esempio: { "postId": 42, "acknowledge": [{ "rule": "seo.h1.multiple", "node": "hero", "reason": "..." }] }.

Parametri:

Esito: { ok: true, quality: { score: { seo, a11y, perf }, blocking, issues } }. Con postId o url e un documento di tipo pagina aggiunge i controlli del post (title, description, slug). Layout, sezioni e popup non li ricevono. Con document, il contenuto si compone con i layout del suo postType (predefinito page), come in nucleo/doc-validate.

• Errori: WP_Error invalid_input se non è indicato esattamente uno tra postId, url e document, o se url è vuoto. { ok: false, error: { code: "not_found" } } se il documento o la pagina dell'URL non esistono. { ok: false, error: { code: "invalid_document" }, errors } se lo schema non è valido.

Permessi: con postId, edit_post sul post. Con url, edit_post sul post della pagina, o edit_posts se l'URL non corrisponde a un post. Senza, edit_posts. Scope nucleo:read.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: l'URL è risolto solo se corrisponde a un post di WordPress.

nucleo/quality-scan

Cosa fa: controlla a lotti tutti i documenti pubblicati: title e h1 duplicati, pagine orfane senza link interni. Restituisce i problemi del sito, il punteggio SEO delle pagine del lotto e la pagina successiva.

Come si usa: ability nucleo/quality-scan. Chiama con page 1, poi con il valore di next finché è null.

Parametri:

Esito: { site, pages, next }, senza la chiave ok. site: voci { rule, severity, message, posts }. pages: voci { postId, score }. next: intero o null.

• Errore: WP_Error invalid_input se page non è un intero ≥ 1.

Permessi: edit_posts. Scope nucleo:read.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

07Layout e sezioni

nucleo/layout-list

Cosa fa: elenca i layout Nucleo con area, condizioni e stato, più i conflitti di priorità della mappa dei layout.

Come si usa: ability nucleo/layout-list. Input {}. Aree e condizioni in Compilatore, runtime, layout e sezioni.

Parametri: nessuno.

Esito: { layouts, conflicts }, senza la chiave ok. Voci di layouts: { id, title, area, conditions, status }, lette dal meta _nucleo_doc. conflicts viene dalla mappa compilata dei layout. Nessun codice di errore.

Permessi: edit_theme_options. Scope nucleo:read.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: nessuna paginazione: legge tutti i post nucleo_layout in ordine di ID. Include tutti gli stati.

nucleo/layout-explain

Cosa fa: per un URL mostra, area per area, il layout scelto, la chiave che lo ha scelto e la regola leggibile. Se un layout è escluso per quell'URL, l'area riporta excluded con il layout e la regola. Le aree product e product-archive esistono solo con WooCommerce, su un prodotto o sulla pagina Shop e sugli archivi dei prodotti; altrove valgono null. Hanno la precedenza su single e archive (search ha la precedenza su archive): l'area perdente riporta superseded con l'area vincente. applied è quello che la pagina stampa davvero, dopo le impostazioni della pagina e un layout del documento none: leggilo prima di modificare un layout. Riconosce anche gli URL degli archivi: la pagina Shop di WooCommerce, gli archivi dei tipi di contenuto e quelli dei termini.

Come si usa: ability nucleo/layout-explain. Esempio: { "url": "https://esempio.it/blog/" }. Chiavi in docs/contracts/layout-keys.md.

Parametri:

Esito: oggetto con la chiave url (l'URL ricevuto) e una chiave per area: header, before-content, after-content, footer, single, archive, search, notfound, popup, product, product-archive. product e product-archive valgono null fuori dalla pagina prodotto e dagli archivi dei prodotti, come nel runtime. Ogni area vale { layout, matched, rule } oppure null. Con esclusioni: { layout, matched, rule, excluded }, con layout e matched a null se nessun layout vince. L'area perdente ha anche superseded, l'area vincente. Inoltre: applied, un oggetto area → ID del layout come lo stampa il runtime; postId, il post dell'URL (0 se non c'è); keys, le chiavi della richiesta provate; conflicts, i conflitti di priorità della mappa, come in nucleo/layout-list. Nessuna chiave ok.

• Errore: WP_Error invalid_input se url è vuoto.

Permessi: edit_theme_options. Scope nucleo:read.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: usa la mappa compilata nello store. Con lo store vuoto non trova layout.

nucleo/section-list

Cosa fa: elenca le sezioni riutilizzabili con i parametri e il numero di documenti che le usano.

Come si usa: ability nucleo/section-list. Input {}. Da chiamare prima di creare una sezione.

Parametri: nessuno.

Esito: { ok: true, sections }, voci { id, slug, title, status, params, uses, modified }. uses conta i documenti che citano la sezione per ID o per slug (meta _nucleo_dep), ognuno una volta. modified è ISO 8601 UTC. Nessun codice di errore.

Permessi: edit_posts. Scope nucleo:read. Con edit_theme_options vede tutte le sezioni non cestinate. Senza, vede solo le pubblicate.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: al massimo 200 sezioni, in ordine di titolo. Nessuna paginazione.

08Contenuti, termini e menu

Formato degli elementi e dei termini: docs/contracts/content-items.md.

nucleo/content-list

Cosa fa: elenca a pagine gli elementi dei tipi di contenuto ammessi. Senza full ogni elemento è un riepilogo. Non elenca mai il cestino.

Come si usa: ability nucleo/content-list. Esempio: { "type": "evento", "term": "citta/roma", "perPage": 50 }.

Parametri:

Esito: { ok: true, items, skipped, total, page, pages, types }.

• items: riepiloghi { id, type, slug, title, status, date, fields, managedBy?, protected? }, con l'id dell'elemento, o elementi completi. Un elemento completo aggiunge hash: l'impronta da passare come base a content-upsert, che salva solo se l'elemento non è cambiato. fields e terms vuoti escono come {}.
• skipped: { type, id, slug, code, message } con code missing_slug o ambiguous_slug.
• types: { type, label, hierarchical, modeled, registeredBy, taxonomies }.
• Errore: { ok: false, error: { code: "unknown_type" } } per un tipo non ammesso.

Permessi: con type ammesso, la capability edit_posts del tipo ($object->cap->edit_posts). Con type non ammesso, edit_posts. Senza type, edit_posts su almeno un tipo ammesso. Scope nucleo:read. La query usa perm: editable.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: un term malformato o di una tassonomia non ammessa restituisce un elenco vuoto, non un errore. Ordine: menu_order crescente, data decrescente, ID.

nucleo/content-get

Cosa fa: restituisce un elemento completo per tipo e slug, con il suo hash.

Come si usa: ability nucleo/content-get. Esempio: { "type": "post", "slug": "benvenuti" }.

Parametri:

Esito: { ok: true, item }. item ha hash, l'impronta da passare come base a content-upsert: hash, id e protected si ignorano in scrittura. fields e terms vuoti escono come {}.

• Errore: { ok: false, error: { code: "not_found" } } se nessun elemento del tipo ha quello slug.
• Errore: { ok: false, error: { code: "read_only_type" } } per product: i prodotti si elencano con nucleo/content-list e qui non si leggono. Usa content-list o nucleo/doc-preview con contextPostId.

Permessi: la capability edit_posts del tipo indicato. Un tipo inesistente nega il permesso. Scope nucleo:read.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: nessuno rilevato.

nucleo/terms-get

Cosa fa: restituisce le tassonomie gestite dall'API dei contenuti. Con taxonomy restituisce anche i termini, i genitori prima dei figli.

Come si usa: ability nucleo/terms-get. Esempi: {}, { "taxonomy": "category" }.

Parametri:

Esito: { ok: true, taxonomies, terms? }. taxonomies: { taxonomy, label, hierarchical, modeled, registeredBy, postTypes }. terms: { slug, name, description, parent, fields, hash }, fields vuoto come {}. hash è l'impronta del termine come letto: passala come base a nucleo/terms-set.

• Errori: { ok: false, error } con invalid_input (non stringa) o unknown_taxonomy.

Permessi: edit_posts. Con taxonomy esistente serve anche la capability assign_terms della tassonomia. Scope nucleo:read.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: nessuna paginazione dei termini.

nucleo/menu-list

Cosa fa: elenca i menu di navigazione con le voci, nello stesso formato di nucleo/menu-set.

Come si usa: ability nucleo/menu-list. Input {}.

Parametri: nessuno.

Esito: { menus }, senza la chiave ok. Voci { id, slug, name, items }. Ogni voce di items è { label, page | post | url | ref, children }. ref vale home, archive:<post-type>, <post-type>:<slug> o term:<taxonomy>/<slug>. Nessun codice di errore.

Permessi: edit_posts. Scope nucleo:read.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: le voci che l'import rifiuterebbe vengono scartate. L'ability non restituisce l'elenco delle voci scartate: lo fa nucleo/site-export in skipped.

09Modello dei contenuti e campi

nucleo/model-get

Cosa fa: restituisce il modello dei contenuti salvato (tipi, tassonomie, gruppi di campi), quanti elementi usano ogni parte e i tipi e le tassonomie del sito che il modello non dichiara.

Come si usa: ability nucleo/model-get. Input {}. Formato del modello: nucleo/catalog-get con { "topic": "model" } e docs/contracts/content-model.md.

Parametri: nessuno.

Esito: { ok: true, model, usage, unmodeled }. unmodeled: { postTypes, taxonomies }, voci { slug, label, registeredBy }. Esclude i tipi e le tassonomie di WordPress (registeredBy: wordpress). Nessun codice di errore.

Permessi: manage_options. Scope nucleo:read.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: nessuno rilevato.

nucleo/model-validate

Cosa fa: controlla un modello dei contenuti senza salvarlo, con le stesse regole di nucleo/model-set. Restituisce gli errori e le differenze dal modello salvato.

Come si usa: ability nucleo/model-validate. Esempio: { "model": { "postTypes": [ ... ] } }.

Parametri:

Esito: { ok, errors, diff, kept }. ok è true senza errori. diff è null se c'è un errore con codice schema. kept elenca le parti non inviate.

• Errore: { ok: false, error: { code: "invalid_input" } } se model non è un oggetto.

Permessi: manage_options. Scope nucleo:read.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: nessuno rilevato.

nucleo/fields-get

Cosa fa: restituisce le definizioni dei campi e i valori salvati di un post o di un termine. Un campo senza valore vale null.

Come si usa: ability nucleo/fields-get. Esempi: { "postId": 42 }, { "termId": 7 }.

Parametri:

Esito: { ok: true, fields, values, hash }. hash è l'impronta di values così come restituiti: passala come base a nucleo/fields-set.

• Errori: { ok: false, error } con invalid_input (entrambi o nessuno) o not_found (nessun tipo o tassonomia con campi per quell'ID).

Permessi: edit_post sul post oppure edit_term sul termine. Scope nucleo:read. Con entrambi o nessuno degli ID la chiamata fallisce sul permesso, prima di arrivare a invalid_input.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: lo schema non impone un minimo agli ID.

nucleo/bind-fields

Cosa fa: elenca i campi di un tipo di contenuto a cui un blocco può collegarsi: campi del modello Nucleo, meta WordPress registrati, ACF, Meta Box e sorgenti aggiunte dal filtro nucleo/bind_fields. Dice anche se nucleo/content-upsert può scrivere il campo.

Come si usa: ability nucleo/bind-fields. Esempio: { "postType": "evento" }.

Parametri:

Esito: { ok: true, fields }, voci { source, key, label, writable, readOnly? }. source vale nucleo, post, acf, metabox o una sorgente del filtro. Solo nucleo ha writable: true. Un ripetitore del modello produce una voce per sottocampo con chiave <campo>.0.<sottocampo>.

• Errore: { ok: false, error: { code: "invalid_post_type" } }.

Permessi: edit_posts. Scope nucleo:read.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: le voci del filtro senza source, key o label stringa vengono scartate. I meta con la stessa chiave di un campo del modello compaiono solo come nucleo.

10Asset e CSS

nucleo/assets-report

nucleo/css-status

11Kit

nucleo/kit-list

12Export e registri

nucleo/site-export

Cosa fa: restituisce il sito come mappa di file JSON: site.json, pagine, articoli, layout, sezioni, regole, menu. I riferimenti tra documenti diventano simboli leggibili (page:slug, section:slug). Formato dei file in Import, export e sincronizzazione.

Come si usa: ability nucleo/site-export. Input {}. L'operazione inversa è nucleo/site-import.

Parametri: nessuno.

Esito: { files, skipped }, senza la chiave ok. files: percorso relativo → contenuto JSON come stringa. skipped: voci di menu { menu, label, reason } escluse da menus/*.json perché l'import le rifiuterebbe. Nessun codice di errore.

Permessi: manage_options. Scope nucleo:admin.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: nessuna paginazione: tutto il sito in una risposta.

nucleo/audit-list

Cosa fa: restituisce le ultime scritture eseguite dalle ability, dalla più recente, con ability, esito e riepilogo. Senza edit_others_posts restituisce solo le scritture dell'utente richiesto.

Come si usa: ability nucleo/audit-list. Esempio: { "limit": 100 }.

Parametri:

Esito: { ok: true, entries }. Voci { id, time, user_id, client_id, ability, post_id, ok, summary, user_name, client_name, post_title }. client_id è null senza client OAuth. client_name e post_title valgono "" se mancano. Nessun codice di errore.

Permessi: edit_posts. Scope nucleo:read. Senza edit_others_posts vede solo le proprie voci.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

nucleo/mail-log

Cosa fa: restituisce le email di Nucleo (codici monouso, email dei moduli) scritte nel registro di sviluppo invece di partire. Le altre email di WordPress non entrano nel registro.

Come si usa: ability nucleo/mail-log. Esempio: { "limit": 5 }.

Parametri:

Esito: { ok: true, active, entries }. active dice se il registro è attivo. Voci { time, to, subject, body }, dalla più recente. Nessun codice di errore.

Permessi: manage_options. Scope nucleo:admin.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: il registro è attivo in ambiente local, oppure in development con la costante NUCLEO_DEV_MAIL a true. Mai in staging o production. Tiene al massimo 20 voci e scarta quelle oltre 24 ore. body è tagliato a 5000 caratteri.

nucleo/gap-list

Cosa fa: elenca le lacune di Nucleo segnalate dagli agenti con nucleo/gap-report, dalla più recente.

Come si usa: ability nucleo/gap-list. Input {}.

Parametri: nessuno.

Esito: { ok: true, gaps }. Voci { need, block, workaround, page, count, first, last }. count è il numero di segnalazioni. first e last sono date Y-m-d. Nessun codice di errore.

Permessi: edit_posts. Scope nucleo:read.

Annotazioni: readonly, non distruttiva, idempotente.

Edizione: Free.

Limiti noti: l'opzione nucleo_gaps conserva al massimo 200 lacune. Le voci malformate vengono scartate in lettura.