Read abilities

01Overview

Read abilities show the state of the site to AI agents and the editor. Each ability has a name, arguments, the code that runs it and a permission check. Nucleo registers them with the WordPress Abilities API in the nucleo category, with show_in_rest: true.

The MCP server publishes each ability as a tool, with / replaced by -: nucleo/doc-get becomes nucleo-doc-get. OAuth, scopes, rate limits and the common result format are described in MCP server, OAuth and common mechanisms.

Common rules for all abilities in this chapter:

• Two-step permission. First, Nucleo checks the WordPress capability. If the request carries an OAuth token, it then checks that the token has the scope of the ability. Without the scope it returns a WP_Error insufficient_scope with status 403. Without a token (cookie, Application Password, WP-CLI) only the capability applies.
• Annotations. All of them declare readonly: true, destructive: false, idempotent: true.
• Rate limit. The rate limit applies only to abilities that are not readonly. The abilities in this chapter do not consume it.
• Empty input. Abilities without required fields accept an empty input. This way a REST read in GET works without parameters.
• Result. Almost all return { ok: true, ... } or { ok: false, error: { code, message } }. Malformed input often produces a WP_Error with code invalid_input. Eight abilities have no ok key in the result: nucleo/layout-list, nucleo/layout-explain, nucleo/assets-report, nucleo/quality-scan, nucleo/site-export, nucleo/kit-list, nucleo/css-status, nucleo/menu-list.
• Edition. Only these three abilities are Pro: nucleo/assets-report, nucleo/kit-list, nucleo/css-status. Without an active license they are not registered.

Summary table:

02Site and status

nucleo/site-describe

What it does: returns a summary of the site for the agent. It contains the name, URL, language, date and time formats, environment, Nucleo version, breakpoints, tokens, available blocks, number of documents, content types and taxonomies, warnings, cache status, the IDs of the quality rules and the performance budgets.

How to use it: ability nucleo/site-describe, MCP tool nucleo-site-describe. Input {}.

Parameters: none. additionalProperties: false.

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

• environment: value of wp_get_environment_type(), one of local, development, staging, production.
• breakpoints: object from name to minimum width in pixels.
• blocks: list of { name, title, category }.
• documentCount: posts of any type and status with the _nucleo_doc meta.
• content: { postTypes, taxonomies }, entries { slug, label, modeled, registeredBy }. registeredBy is nucleo-model, wordpress, plugin-or-theme or conflict. It contains only the types the user can edit.
• warnings: list of texts. It reports the missing language pack, the English date format F j, Y on a non-English site, layouts with conditions the runtime does not apply, and the warnings of the development mail log.
• cache: { empty: false }, or { empty: true, message } when the Nucleo store is empty but the database has Nucleo content.
• layouts: list of the active layouts.
• plugins: list of { id, name, active, does } for the detected integrations, as in nucleo/settings-get.
• quality: list of the IDs of the quality rules.
• budgets: performance budgets of the quality rules: CSS and JS in bytes served by Nucleo, DOM in estimated nodes. See nucleo/status.

No error code.

Permissions: edit_posts. Scope nucleo:read.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: with the en_US locale or an empty locale it produces no language warnings. It reads all layouts (numberposts: -1) for the warnings on conditions.

nucleo/status

What it does: returns the versions of Nucleo, PHP and WordPress, the driver of the artifact store, the number of documents, the conflicting cache plugins, the saved artifacts, the rebuild queue, the date of the last build and the performance budgets.

How to use it: ability nucleo/status. Input {}.

Parameters: none.

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

• store is the short name of the active store. conflicts is a list of { plugin, issue, fix }: cache plugins that cancel the CSS variants of Nucleo templates.
• artifacts: { count, bytes }, number and size of the artifact files.
• queue: integer, documents waiting for a background rebuild. After a plugin update every document is queued once, so queue counts all of them until the rebuild ends.
• failed: failed background rebuilds, as { id, attempts, code, message }. After 3 attempts the document leaves the queue.
• stale: IDs of the documents that cannot be rebuilt: an invalid section, or blocking quality issues on a published post. A stale document keeps its previous HTML, and it may also appear in failed. At most 50.
• lastBuild: ISO 8601 date of the last change to the artifacts, or null.
• budgets: performance budgets of the quality rules: CSS and JS in bytes served by Nucleo, DOM in estimated nodes. The filters nucleo/quality/{css,js,dom}_budget change them.

No error code.

Permissions: manage_options. Scope nucleo:admin.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: none found.

nucleo/settings-get

What it does: returns the Nucleo settings and the detected integrations. The key of the external service never leaves the site: the result only says whether it is set.

How to use it: ability nucleo/settings-get. Input {}.

Parameters: none.

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

• settings.editor.textOnlyRoles: roles limited to text.
• settings.performance.wooFragments: keep or off. settings.performance.purgeMode: normal or strict. settings.performance.purgeSafelist: list of selectors. settings.performance.subsets: list of character subsets.
• settings.quality.nonForcible: IDs of the quality rules that cannot be forced to publish. settings.quality.thinWords: minimum word count per post type.
• settings.service: { url, keySet }.
• settings.captcha: { provider, siteKey, secretSet, threshold }.
• settings.onboarding.dismissed: first-run state for the current user.
• integrations: list of { id, name, active, does } for woocommerce, polylang, wpml, yoast, rankmath, contact-form-7, complianz, cookiebot, cookieyes, iubenda.

No error code.

Permissions: manage_options. Scope nucleo:admin.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: none found. To write: nucleo/settings-set.

03Guide

nucleo/guide

What it does: returns one phase of the phased guide: site state, phase rules, things to do, exit conditions and next phase. Without phase it computes the current phase from the site state.

How to use it: ability nucleo/guide. Example: { "phase": 2, "design": "design/home.html" }. Details on the phases in Guide by phases.

Parameters:

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

• state: tokens, sections, layouts, menus, postTypes, documents, checks and other site state data.
• basics: rules of phase 0 in short form { code, text }. Empty with phase 0.
• rules: { code, text, tools }. next: string or null.
• Error: WP_Error nucleo_guide_phase if phase is outside 0–4.
• If the cache is empty, todo starts with a cache warning.

Permissions: edit_posts. Scope nucleo:read.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: the checks read at most 1000 documents: first layouts and sections, then the most recent ones. Beyond the cap, todo reports how many documents it has read.

04Catalog and components

nucleo/catalog-list

What it does: lists the registered Nucleo blocks with title, category and short description.

How to use it: ability nucleo/catalog-list. Input {}.

Parameters: none.

Result: { ok: true, blocks }, entries { name, version, title, category, description }. No error code.

Permissions: edit_posts. Scope nucleo:read.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: none found.

nucleo/catalog-get

What it does: with name it returns the full manifest of a block, the style keys of its groups, the HTML markup and the base CSS. With names it returns several blocks in a compact form. With topic it returns a reference topic that no manifest contains.

How to use it: ability nucleo/catalog-get. Examples: { "name": "nc/heading" }, { "names": ["nc/section", "nc/heading", "nc/button"] }, { "topic": "layouts" }. Use names to read the blocks of a page in one call, and name for the base CSS of a single block.

Parameters:

One of name, names and topic is required.

Result:

• With name: { ok: true, block }. block contains name, version, title, category, description, aiHints, content, settings, supports, parts, children, parents, assets, semantics, renderer, styleKeys, markup, css. markup comes from nucleo/data/block-markup.json. css is the style file of the manifest, empty if missing.
• With names: { ok: true, blocks, styleKeys, remaining? }. Each entry of blocks is { name, ok, block }, or { name, ok: false, error } for an unknown block. block has the fields of name without styleKeys, css, renderer and assets, and adds styleGroups. The top-level styleKeys lists the keys of all the groups once. A key without number gets px for a number. The response stays under 25,000 characters: the first block always fits, the following names that do not fit go, in order, to remaining. Request them with a second call.
• With topic: { ok: true, topic: { topic, summary, rules, data } }. tokens includes the current tokens. theme includes base.css only if the active theme is nucleo-canvas. styles includes the style groups of each block. woocommerce returns the WooCommerce reference: the woo/* blocks, the product and product-archive areas, one recipe per page and the checkout tools.
• Errors: WP_Error invalid_input without name, names or topic, or with names that is not a list of 1–20 names. { ok: false, error: { code: "not_found" } } for an unknown block or topic.

Permissions: edit_posts. Scope nucleo:read.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: names accepts at most 20 names. A block without style groups has an empty styleKeys.

nucleo/docs-search

What it does: searches by terms in the reference topics of nucleo/catalog-get and in the block manifests. It returns the best matches, ranked by the number of occurrences of the terms: topic or block, title and an excerpt.

How to use it: ability nucleo/docs-search, MCP tool nucleo-docs-search. Example: { "query": "contrast token", "limit": 5 }. Use it when the name of the topic or block is not known. With a known name, call nucleo/catalog-get directly.

Parameters:

Result: { ok: true, results }. Each entry of results is { topic, title, excerpt } for a topic, or { block, title, excerpt } for a block. The title of a topic is its name. excerpt is the text of the topic (summary and rules) or the description of the block, cut to 200 characters with ....

• Error: WP_Error invalid_input if query is not a string of 2–100 characters or if limit is not an integer from 1 to 20.

Permissions: edit_posts. Scope nucleo:read.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: it searches only the reference topics (the same as nucleo/catalog-get with topic) and the block manifests. It does not search documents, content or component sources. No pagination: at most 20 results.

nucleo/components-list

What it does: lists the data sources and the actions registered by the site plugins with the nucleo/register_components hook. It returns names and schemas, never code.

How to use it: ability nucleo/components-list. Input {}. The names are used in nc/collection (source component) and nc/native-form (action component). See dynamic data.

Parameters: none.

Result: { ok: true, dataSources, actions }. No error code.

Permissions: edit_pages. Scope nucleo:read.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: the blocks of the components do not appear here: read them with nucleo/catalog-get.

nucleo/tokens-get

What it does: returns the current design tokens of the site, grouped by category.

How to use it: ability nucleo/tokens-get. Input {}. Format in Design tokens.

Parameters: none.

Result: { ok: true, tokens }. No error code.

Permissions: edit_posts. Scope nucleo:read.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: none found.

05Documents

nucleo/doc-list

What it does: lists the posts with a Nucleo document (meta _nucleo_doc), from the most recently modified. It filters by status and by the result of the quality check.

How to use it: ability nucleo/doc-list. Example: { "postType": "page", "search": "contatti", "page": 2 }.

Parameters:

Result: { ok: true, items, page, total }. Entries { id, title, status, revision, link, modified, author, lang, quality }. modified is ISO 8601 UTC. author is the display name or "". lang is the language slug of the multilingual plugin, "" without plugin. quality is the last check saved with the document (with score), or null if the document was never checked.

• Errors: WP_Error invalid_input for wrong types. { ok: false, error: { code: "invalid_post_type" } } for a type that does not exist.

Permissions: edit_posts. Scope nucleo:read. The query uses perm: editable: it lists only the posts the user can edit.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: 20 entries per page, fixed. It includes all statuses except the trash.

nucleo/doc-get

What it does: returns a document, whole or starting from a node, with a maximum depth. With format compact (the default) the form is compact; with full the document comes complete. It also returns the revision.

How to use it: ability nucleo/doc-get. Examples: { "postId": 42, "nodeId": "hero", "depth": 1 }, { "postId": 42, "format": "full" }.

Parameters:

Result: { ok: true, postId, revision, document }. The compact form omits the settings equal to the block default.

• Errors: WP_Error invalid_input. { ok: false, error } with not_found (document or node missing) or invalid_op (negative depth).

Permissions: edit_post on the postId. Scope nucleo:read.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: depth does not apply with format full.

nucleo/doc-texts

What it does: returns all translatable texts of a document as { id, path, text }, without structure, with the revision to pass to nucleo/doc-texts-set.

How to use it: ability nucleo/doc-texts. Example: { "postId": 42 }.

Parameters:

Result: { ok: true, revision, texts }. path is content.<field> or content.<field>.<index>.<subfield> for lists. Tree order.

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

Permissions: edit_post on the postId. Scope nucleo:read.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: it considers only the content fields marked translatable: true in the manifest, and only string values. It skips the nodes of unregistered blocks.

nucleo/doc-revisions

What it does: lists the revisions of a document: number, time, WordPress user, client and a summary of the changes. It does not include the content. To go back to a revision: nucleo/doc-rollback.

How to use it: ability nucleo/doc-revisions. Example: { "postId": 42 }.

Parameters:

Result: { ok: true, postId, revisions }, entries { rev, time, user, client, summary }. time is a Unix timestamp. user is the user ID. client identifies the client that wrote the revision. summary is created for the first revision, otherwise +a ~c -r: nodes added, changed and removed.

• Errors: WP_Error invalid_input. { ok: false, error: { code: "not_found" } } if the post does not exist.

Permissions: edit_post on the postId. Scope nucleo:read.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: a post without a document returns an empty revisions, not an error.

nucleo/doc-validate

What it does: validates a document without saving it. It returns the schema errors and, if the document is valid, the quality report.

How to use it: ability nucleo/doc-validate. Example: { "document": { "schema": ..., "root": { ... } } }.

Parameters:

Result: { ok, errors, warnings?, quality? }. ok is true if there are no errors. Each error carries the JSON path, the value, the allowed values and the fix. quality is { score: { seo, a11y, perf }, blocking, issues } and is present only without errors.

• References: media:<file> in content.src becomes a placeholder URL and produces a warning. menu:<slug> in settings.menu of nc/menu becomes the menu ID, or an error if the menu does not exist.
• Always check the layout conditions.
• With postType page (default) the document is checked with the layouts of a generic page of the site (header, before and after the content, footer), as on save: their landmarks count, their own problems are not reported. Layouts bound to a post, a term or the home page are left out.
• Error: WP_Error invalid_input if document is not an object.

Permissions: edit_posts. Scope nucleo:read.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: it saves nothing. The media:<file> references are not really resolved: the file is resolved only on push.

nucleo/doc-preview

What it does: compiles a document without saving it and returns HTML and CSS. With postId it compiles the saved document in the post context (bindings, links, language) and adds a signed preview link. With contextPostId it fills the dynamic slots (woo/*, bindings) as on the page of that post: this way a product layout shows on a real product.

How to use it: ability nucleo/doc-preview. Examples: { "postId": 42 }, { "document": { ... } }.

Parameters:

Result: { ok: true, html, css, previewUrl? }. previewUrl is present only with postId and is valid for 30 minutes (1800 seconds). The token is signed with HMAC-SHA256.

• Errors: WP_Error invalid_input with both or neither of the fields. { ok: false, error: { code: "not_found" } }. { ok: false, error: { code: "invalid_document", message, errors } } for schema errors.

Permissions: with postId, edit_post on the post. Without it, edit_posts. With contextPostId, also read_post on that post. Scope nucleo:read.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: the HTML is the compiled one, with the fallback of the dynamic slots: forms, collections and other slots are not filled. The preview does not compose the area layouts.

06Quality

nucleo/quality-check

What it does: produces the quality report (SEO, accessibility, performance) of a saved document, identified by ID or by the URL of its page, or of a document passed as input. Problems acknowledged with acknowledge do not block. Rules and codes in Quality engine.

How to use it: ability nucleo/quality-check. Example: { "postId": 42, "acknowledge": [{ "rule": "seo.h1.multiple", "node": "hero", "reason": "..." }] }.

Parameters:

Result: { ok: true, quality: { score: { seo, a11y, perf }, blocking, issues } }. With postId or url and a page-type document it adds the post checks (title, description, slug). Layouts, sections and popups do not receive them. With document, the content is composed with the layouts of its postType (default page), as in nucleo/doc-validate.

• Errors: WP_Error invalid_input if exactly one of postId, url and document is not given, or if url is empty. { ok: false, error: { code: "not_found" } } if the document or the page of the URL does not exist. { ok: false, error: { code: "invalid_document" }, errors } if the schema is not valid.

Permissions: with postId, edit_post on the post. With url, edit_post on the post of the page, or edit_posts if the URL does not match a post. Without them, edit_posts. Scope nucleo:read.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: the URL is resolved only if it matches a WordPress post.

nucleo/quality-scan

What it does: checks all published documents in batches: duplicate titles and h1, orphan pages without internal links. It returns the site problems, the SEO score of the pages in the batch and the next page.

How to use it: ability nucleo/quality-scan. Call with page 1, then with the value of next until it is null.

Parameters:

Result: { site, pages, next }, without the ok key. site: entries { rule, severity, message, posts }. pages: entries { postId, score }. next: integer or null.

• Error: WP_Error invalid_input if page is not an integer ≥ 1.

Permissions: edit_posts. Scope nucleo:read.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

07Layouts and sections

nucleo/layout-list

What it does: lists the Nucleo layouts with area, conditions and status, plus the priority conflicts of the layout map.

How to use it: ability nucleo/layout-list. Input {}. Areas and conditions in Compiler, runtime, layouts and sections.

Parameters: none.

Result: { layouts, conflicts }, without the ok key. Entries of layouts: { id, title, area, conditions, status }, read from the _nucleo_doc meta. conflicts comes from the compiled layout map. No error code.

Permissions: edit_theme_options. Scope nucleo:read.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: no pagination: it reads all nucleo_layout posts in ID order. It includes all statuses.

nucleo/layout-explain

What it does: for a URL it shows, area by area, the chosen layout, the key that chose it and the readable rule. If a layout is excluded for that URL, the area reports excluded with the layout and the rule. The product and product-archive areas exist only with WooCommerce, on a product or on the Shop and product archives; elsewhere they are null. They win over single and archive (search also wins over archive): the losing area reports superseded with the winning area. applied is what the page really prints, after the page settings and a document layout none: read it before editing a layout. It also recognizes archive URLs: the WooCommerce Shop page, post type archives and term archives.

How to use it: ability nucleo/layout-explain. Example: { "url": "https://esempio.it/blog/" }. Keys in docs/contracts/layout-keys.md.

Parameters:

Result: object with the key url (the URL received) and one key per area: header, before-content, after-content, footer, single, archive, search, notfound, popup, product, product-archive. product and product-archive are null outside the product page and the product archives, as in the runtime. Each area is { layout, matched, rule } or null. With exclusions: { layout, matched, rule, excluded }, with layout and matched set to null if no layout wins. A losing area also has superseded, the winning area. Also: applied, an object area → layout id as printed by the runtime; postId, the post of the URL (0 if none); keys, the request keys tried; conflicts, the priority conflicts of the map, as in nucleo/layout-list. No ok key.

• Error: WP_Error invalid_input if url is empty.

Permissions: edit_theme_options. Scope nucleo:read.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: it uses the map compiled in the store. With an empty store it finds no layout.

nucleo/section-list

What it does: lists the reusable sections with their parameters and the number of documents that use them.

How to use it: ability nucleo/section-list. Input {}. Call it before creating a section.

Parameters: none.

Result: { ok: true, sections }, entries { id, slug, title, status, params, uses, modified }. uses counts the documents that cite the section by ID or by slug (meta _nucleo_dep), each one once. modified is ISO 8601 UTC. No error code.

Permissions: edit_posts. Scope nucleo:read. With edit_theme_options it sees all sections that are not in the trash. Without it, it sees only the published ones.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: at most 200 sections, in title order. No pagination.

08Content, terms and menus

Format of items and terms: docs/contracts/content-items.md.

nucleo/content-list

What it does: lists, page by page, the items of the allowed content types. Without full each item is a summary. It never lists the trash.

How to use it: ability nucleo/content-list. Example: { "type": "evento", "term": "citta/roma", "perPage": 50 }.

Parameters:

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

• items: summaries { id, type, slug, title, status, date, fields, managedBy?, protected? }, with the id of the item, or complete items. A complete item adds hash: the fingerprint to send as base to content-upsert, which then saves only if the item did not change. fields and terms empty come out as {}.
• skipped: { type, id, slug, code, message } with code missing_slug or ambiguous_slug.
• types: { type, label, hierarchical, modeled, registeredBy, taxonomies }.
• Error: { ok: false, error: { code: "unknown_type" } } for a type that is not allowed.

Permissions: with an allowed type, the edit_posts capability of the type ($object->cap->edit_posts). With a type that is not allowed, edit_posts. Without type, edit_posts on at least one allowed type. Scope nucleo:read. The query uses perm: editable.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: a malformed term or a term of a taxonomy that is not allowed returns an empty list, not an error. Order: menu_order ascending, date descending, ID.

nucleo/content-get

What it does: returns a complete item by type and slug, with its hash.

How to use it: ability nucleo/content-get. Example: { "type": "post", "slug": "benvenuti" }.

Parameters:

Result: { ok: true, item }. item has hash, the fingerprint to send as base to content-upsert: hash, id and protected are ignored on write. fields and terms empty come out as {}.

• Error: { ok: false, error: { code: "not_found" } } if no item of the type has that slug.
• Error: { ok: false, error: { code: "read_only_type" } } for product: products are listed by nucleo/content-list and are not read here. Use content-list or nucleo/doc-preview with contextPostId.

Permissions: the edit_posts capability of the indicated type. A type that does not exist denies the permission. Scope nucleo:read.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: none found.

nucleo/terms-get

What it does: returns the taxonomies managed by the content API. With taxonomy it also returns the terms, parents before children.

How to use it: ability nucleo/terms-get. Examples: {}, { "taxonomy": "category" }.

Parameters:

Result: { ok: true, taxonomies, terms? }. taxonomies: { taxonomy, label, hierarchical, modeled, registeredBy, postTypes }. terms: { slug, name, description, parent, fields, hash }, fields empty as {}. hash is the fingerprint of the term as read: send it as base to nucleo/terms-set.

• Errors: { ok: false, error } with invalid_input (not a string) or unknown_taxonomy.

Permissions: edit_posts. With an existing taxonomy the assign_terms capability of the taxonomy is also required. Scope nucleo:read.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: no pagination of the terms.

nucleo/menu-list

What it does: lists the navigation menus with their items, in the same format as nucleo/menu-set.

How to use it: ability nucleo/menu-list. Input {}.

Parameters: none.

Result: { menus }, without the ok key. Entries { id, slug, name, items }. Each entry of items is { label, page | post | url | ref, children }. ref is home, archive:<post-type>, <post-type>:<slug> or term:<taxonomy>/<slug>. No error code.

Permissions: edit_posts. Scope nucleo:read.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: items that the import would reject are discarded. The ability does not return the list of discarded items: nucleo/site-export does it, in skipped.

09Content model and fields

nucleo/model-get

What it does: returns the saved content model (types, taxonomies, field groups), how many items use each part, and the site types and taxonomies that the model does not declare.

How to use it: ability nucleo/model-get. Input {}. Model format: nucleo/catalog-get with { "topic": "model" } and docs/contracts/content-model.md.

Parameters: none.

Result: { ok: true, model, usage, unmodeled }. unmodeled: { postTypes, taxonomies }, entries { slug, label, registeredBy }. It excludes the WordPress types and taxonomies (registeredBy: wordpress). No error code.

Permissions: manage_options. Scope nucleo:read.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: none found.

nucleo/model-validate

What it does: checks a content model without saving it, with the same rules as nucleo/model-set. It returns the errors and the differences from the saved model.

How to use it: ability nucleo/model-validate. Example: { "model": { "postTypes": [ ... ] } }.

Parameters:

Result: { ok, errors, diff, kept }. ok is true without errors. diff is null if there is an error with code schema. kept lists the parts not sent.

• Error: { ok: false, error: { code: "invalid_input" } } if model is not an object.

Permissions: manage_options. Scope nucleo:read.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: none found.

nucleo/fields-get

What it does: returns the field definitions and the saved values of a post or a term. A field without a value is null.

How to use it: ability nucleo/fields-get. Examples: { "postId": 42 }, { "termId": 7 }.

Parameters:

Result: { ok: true, fields, values, hash }. hash is the fingerprint of values as returned: send it as base to nucleo/fields-set.

• Errors: { ok: false, error } with invalid_input (both or neither) or not_found (no type or taxonomy with fields for that ID).

Permissions: edit_post on the post, or edit_term on the term. Scope nucleo:read. With both or neither of the IDs the call fails on the permission, before reaching invalid_input.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: the schema does not impose a minimum on the IDs.

nucleo/bind-fields

What it does: lists the fields of a content type that a block can bind to: fields of the Nucleo model, registered WordPress meta, ACF, Meta Box and sources added by the nucleo/bind_fields filter. It also says whether nucleo/content-upsert can write the field.

How to use it: ability nucleo/bind-fields. Example: { "postType": "evento" }.

Parameters:

Result: { ok: true, fields }, entries { source, key, label, writable, readOnly? }. source is nucleo, post, acf, metabox or a source of the filter. Only nucleo has writable: true. A repeater of the model produces one entry per subfield with key <field>.0.<subfield>.

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

Permissions: edit_posts. Scope nucleo:read.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: filter entries without a string source, key or label are discarded. Meta with the same key as a field of the model appear only as nucleo.

10Assets and CSS

nucleo/assets-report

nucleo/css-status

11Kits

nucleo/kit-list

12Export and logs

nucleo/site-export

What it does: returns the site as a map of JSON files: site.json, pages, articles, layouts, sections, rules, menus. The references between documents become readable symbols (page:slug, section:slug). File format in Import, export and sync.

How to use it: ability nucleo/site-export. Input {}. The inverse operation is nucleo/site-import.

Parameters: none.

Result: { files, skipped }, without the ok key. files: relative path → JSON content as a string. skipped: menu items { menu, label, reason } excluded from menus/*.json because the import would reject them. No error code.

Permissions: manage_options. Scope nucleo:admin.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: no pagination: the whole site in one response.

nucleo/audit-list

What it does: returns the latest writes performed by the abilities, from the most recent, with ability, result and summary. Without edit_others_posts it returns only the writes of the requesting user.

How to use it: ability nucleo/audit-list. Example: { "limit": 100 }.

Parameters:

Result: { ok: true, entries }. Entries { id, time, user_id, client_id, ability, post_id, ok, summary, user_name, client_name, post_title }. client_id is null without an OAuth client. client_name and post_title are "" if missing. No error code.

Permissions: edit_posts. Scope nucleo:read. Without edit_others_posts it sees only its own entries.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

nucleo/mail-log

What it does: returns the Nucleo emails (one-time codes, form emails) written to the development log instead of being sent. The other WordPress emails do not enter the log.

How to use it: ability nucleo/mail-log. Example: { "limit": 5 }.

Parameters:

Result: { ok: true, active, entries }. active says whether the log is active. Entries { time, to, subject, body }, from the most recent. No error code.

Permissions: manage_options. Scope nucleo:admin.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: the log is active in the local environment, or in development with the constant NUCLEO_DEV_MAIL set to true. Never in staging or production. It keeps at most 20 entries and discards those older than 24 hours. body is cut at 5000 characters.

nucleo/gap-list

What it does: lists the Nucleo gaps reported by the agents with nucleo/gap-report, from the most recent.

How to use it: ability nucleo/gap-list. Input {}.

Parameters: none.

Result: { ok: true, gaps }. Entries { need, block, workaround, page, count, first, last }. count is the number of reports. first and last are dates Y-m-d. No error code.

Permissions: edit_posts. Scope nucleo:read.

Annotations: readonly, non-destructive, idempotent.

Edition: Free.

Known limits: the option nucleo_gaps keeps at most 200 gaps. Malformed entries are discarded when read.