Kits

01Overview

A kit is a starter site: colors, pages, header and footer ready to use, written as JSON documents.

Each kit is a folder with the same format as a site export.

The kit list reads the files of each kit. nucleo/kit-apply imports them with the same import used by nucleo push and nucleo/site-import.

The route nucleo/v1/kit-preview compiles the kit home page with header and footer, for the thumbnail on the Kits admin page.

Kits are a Pro feature: the abilities nucleo/kit-list and nucleo/kit-apply register only with an active license, and the preview route checks it.

The plugin contains four kits: artigiano, ecommerce, ristorante and studio-professionale.

02Structure of a kit

Folder and manifest kit.json

What it does: identifies the kit and describes its name and requirements.

How to use it: a folder with a kit.json file. The id of the kit is the folder name.

Parameters:

Permissions: None.

Edition: Pro.

Known limits:

• A kit.json that cannot be read, is not JSON, or has no name and description of type string removes the kit from the list.
• The id must match ^[a-z0-9-]+$. Otherwise the kit is not read.
• An unknown requirement is never met.

Kit files

What it does: provide tokens and documents in the format of the site folder.

How to use it: Nucleo reads all the .json files of the folder, including subfolders.

Parameters: files present in the kits of the plugin.

The wp block of each document holds title, slug, status and postType. The import uses it to create the post.

Permissions: None.

Edition: Pro.

Known limits:

• No kit has sections/, menus/, media/ folders or a site block in site.json. The kit does not create global sections, menus, media or site settings.
• The nc/menu node of the header does not have the menu setting: it shows no items until someone assigns a menu.
• Images point to external https://picsum.photos/seed/… URLs. The import does not download them into the media library.
• site.json has no base or tokensBase: the import does not detect conflicts with the site (see nucleo/kit-apply).
• Every kit must follow these style rules: 8 six-digit hexadecimal colors; at least 2 nc/section bands with padding per page; at least one band with background; at least one grid on the home page; header and footer with padding and background.

03Available kits

artigiano

What it does: site for a craft workshop that makes custom furniture, "Bottega Gallo" in Verona. Description: "Sito per una bottega artigiana: lavorazioni, progetti su misura e preventivi."

How to use it: nucleo/kit-apply with {"kit": "artigiano"}.

Parameters: content.

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

Permissions: as for nucleo/kit-apply.

Edition: Pro.

Known limits: No requirements. Addresses, phone numbers and emails are sample data (domain .example).

ecommerce

What it does: online shop for handmade ceramics, "Officina Argilla" in Faenza. Description: "Negozio online di ceramiche artigianali: catalogo, schede prodotto, carrello e pagine informative."

How to use it: nucleo/kit-apply with {"kit": "ecommerce"}. Requires WooCommerce to be active.

Parameters: content.

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

Permissions: as for nucleo/kit-apply.

Edition: Pro.

Known limits: without WooCommerce the kit does not appear in nucleo/kit-list, and nucleo/kit-apply returns kit_unknown. The woo/* blocks are described in the integrations documentation.

ristorante

What it does: site for a restaurant, "Trattoria Il Faro" in Florence. Description: "Sito per un ristorante: menu, storia della cucina, prenotazioni e orari."

How to use it: nucleo/kit-apply with {"kit": "ristorante"}.

Parameters: content.

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

Permissions: as for nucleo/kit-apply.

Edition: Pro.

Known limits: No requirements. The section "Il menu" is static text: it does not use the nc/menu block.

studio-professionale

What it does: site for a tax and business consulting firm, "Studio Bianchi Consulenza" in Milan. Description: "Sito per uno studio di consulenza: servizi, team e contatti in tono sobrio."

How to use it: nucleo/kit-apply with {"kit": "studio-professionale"}.

Parameters: content.

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

Permissions: as for nucleo/kit-apply.

Edition: Pro.

Known limits: No requirements.

04List, preview and apply

nucleo/kit-list

What it does: returns the available kits with id, name, description and requires, in alphabetical order of folder.

How to use it: ability via MCP or from the Kits admin page. See nucleo/kit-list in the read abilities.

Parameters: None. Output {"kits": [...]}.

Permissions: edit_posts; scope nucleo:read.

Edition: Pro (without a license the ability does not exist).

Known limits: excludes the kits whose requirements are not met. The ecommerce kit disappears without WooCommerce instead of appearing as unavailable.

Preview GET /nucleo/v1/kit-preview

What it does: compiles the kit header, home page and footer, in this order. It adds the kit token variables after the site variables, so the kit colors win.

How to use it: GET /wp-json/nucleo/v1/kit-preview?kit=artigiano. The Kits admin page uses it for the thumbnail of each kit.

Parameters:

Response: ok, html, css, styles (block bundle and the theme base.css), tokensCss.

Permissions: edit_theme_options and an active Pro license. Without either: HTTP 403.

Edition: Pro.

Known limits: unknown kit or invalid id: not_found, HTTP 404. It does not check the requirements of the kit. A document that does not compile is skipped without error. The wp block of the documents is removed before compiling.

nucleo/kit-apply

What it does: applies a kit to the site. It writes the kit tokens, creates or updates pages and layouts by slug and post type, and publishes the pages. With dryRun it counts without writing.

How to use it: ability via MCP or from the Kits admin page. Example: {"kit": "ristorante", "dryRun": true}.

Parameters:

Output: the import report, with created, updated, unchanged, errors (file, message, code), warnings, ids (symbol → ID, for example page:home) and base.

Permissions: edit_theme_options; scope nucleo:design.

Edition: Pro.

Known limits:

• Tokens merged, not replaced: for each key the kit value wins; the other keys saved on the site stay. The kit defines only the color group (8 keys): spacing, fonts, radii and shadows of the site stay unchanged.
• Pages and layouts overwritten: a post with the same slug and type is updated. The kit has no base, so the import does not report conflicts with changes made on the site. A post identical to the kit document stays unchanged (unchanged).
• Home page: if the site shows posts on the home page (show_on_front other than page), the kit home page becomes the front page. A site with a front page already chosen keeps it.
• It has no force option and does not accept acknowledgements (acknowledge) for the blocking issues of the quality engine.
• Errors: invalid_input (wrong types), kit_unknown (kit not found or with unmet requirements). The requires_missing code is not reachable with the current requirements, because the kit is already removed from the list.
• The annotations declare destructive: false and idempotent: true.
• The activity log records kit-apply with outcome dry-run or import.

Kits admin page

What it does: shows a card per kit with thumbnail, name, description and requirements. It offers "Preview changes" (dry run) and "Apply" with confirmation.

How to use it: menu Nucleo AI → Kits. The page calls nucleo/kit-list, the route nucleo/v1/kit-preview and nucleo/kit-apply.

Parameters: None.

Permissions: edit_theme_options.

Edition: Pro. Without a license the page shows a block and does not call nucleo/kit-list.

Known limits:

• Without WooCommerce the "Apply" button of the ecommerce kit is disabled and the card explains why. Since nucleo/kit-list hides the kit, in practice the card does not appear.
• The confirmation says that the kit tokens are merged into the design system and that pages with the same slug are updated.