Pro module22 abilities
Spectra One
These abilities register when Spectra One is detected on the site and a Pro licence is active. If either is missing the module stays absent rather than failing at call time.
At a glance
Spectra One registers 22 abilities: 12 that only read, 3 that write, and 7 marked destructive. That split is the practical answer to how much of this module can run unattended. Reads cost nothing and are safe to repeat, so discovery is the part to be generous with; the writes are where review belongs, and the destructive calls stop for an explicit confirmation every single time regardless of which profile is active.
What this module is for
Coordinate Spectra One theme settings, color and typography systems, style variations, patterns, templates, template parts, fonts, and post display overrides.
Before you rely on it: Capture the existing design state before applying site-wide style or navigation changes.
Typical workflows
- Export the current design before applying a new variation
- Align palette and typography tokens
- Review post-level display overrides before changing a template
The Spectra One integration page covers the same module from the workflow side, with the capability map and the questions worth asking before a first write.
Availability on your site
The Spectra One module needs three things at once: WPPilot Free as the MCP foundation, an active Pro licence, and the companion plugin detected on the site. Miss any one and the module does not register, which is deliberate: an ability that appears in the tool list but fails at call time is worse than an ability that was never offered. What the connected agent can actually call is then narrowed twice more: by the safety profile active on the site, and by the WordPress capabilities of the user behind the credential. A read that succeeds for an administrator can be absent entirely for an editor.
Every write these abilities perform is recorded in the change ledger, and destructive calls can be routed through the approval queue so a person signs off before anything is applied. A successful tool result means the operation returned, not that the front end, the cache, and every dependent template are correct: that still needs a look.
Reads
Available in every safety profile, including Read Only. Inspection costs nothing and is not rate limited.
| Ability | What it does |
|---|---|
wppilot/spectra-one-check-setupCheck Spectra One Setup | Diagnostic snapshot of the Spectra One theme install: theme active flag + version + minimum supported, whether Spectra One is the currently active WordPress stylesheet (survives mid-request switch_theme), companion Spectra (UAGB) plugin status + version + minimum supported (the plugin is optional — most spectra-one abilities work without it), companion Custom Fonts plugin presence, whether the WordPress Abilities API is available (WP 6.9+, required by the theme-native spectra-one/* surface), and current-user capability. Lean by design: does NOT echo settings / templates / patterns content here — call the corresponding get-* / list-* abilities for that. |
wppilot/spectra-one-export-designExport Spectra One Design | Returns the active Spectra One design state as a portable JSON snapshot: the wp_global_styles user overlay (palette, typography, styles), the swt_theme_options bag (scroll_top, body/headings settings), the theme identity block (name + version), an ISO 8601 export timestamp, and a stats summary (palette_count, patterns_bundled, templates_bundled). Use this as the rollback point before a destructive write — feed the snapshot back through wppilot/spectra-one-apply-design to restore the pre-write state. Schema version is 1; future major schema changes will bump this integer. Payload size: global_styles + theme_options are opaque blobs; typical size is 10–50 KiB but can exceed 100 KiB on installs with an extensive user overlay — stash the snapshot rather than re-fetching it inside a hot path. |
wppilot/spectra-one-get-color-paletteGet Spectra One Color Palette | Returns the active Spectra One color palette: 14 named color slugs (primary, secondary, heading, body, background, tertiary, quaternary, surface, foreground, outline, neutral, transparent, currentColor, inherit) with their current hex values (user overrides on top of theme.json defaults). Also returns the 1 bundled gradient + 3 duotones the theme ships. source reports whether the active palette comes from the user overlay (user), the theme.json baseline (theme), or a mix of the two (mixed). Progressive disclosure: swatches only; write via wppilot/spectra-one-set-color-palette (Sprint 3). |
wppilot/spectra-one-get-post-display-settingsGet Spectra One Post Display Settings | Returns the Spectra One per-post display overrides for the post identified by post_id (accepts both post_id and the WP-native alias id): 5 booleans that override the theme defaults on this specific post — hide_header, hide_footer, hide_title, sticky_header, transparent_header. Only post and page are supported — the theme metabox is not registered on other post types, so a call against a different type is rejected with spectra_one_unsupported_post_type. post_title is echoed so the caller can confirm the subject with the user before changing anything. Read-only; the writer is wppilot/spectra-one-set-post-display-settings. |
wppilot/spectra-one-get-theme-infoGet Spectra One Theme Info | Returns Spectra One theme metadata (name, version, slug, text domain, minimum WP + PHP versions) plus the companion Spectra (UAGB) plugin status and the counts of bundled assets: style variations (JSON files under styles/), block patterns (PHP files under patterns/), FSE templates (HTML files under templates/), and template parts (HTML files under parts/). Use this after check-setup to size the surface before exploring individual entities. |
wppilot/spectra-one-get-theme-settingsGet Spectra One Theme Settings | Returns the active Spectra One theme configuration: layout widths (contentSize + wideSize), the swt_theme_options bag (scroll_top toggle + related global flags), the 8 spacing scale sizes, the list of block styles declared by the theme (targeting core/site-title, core/navigation, etc.), and the theme.json customTemplates inventory. Progressive disclosure: block-style rows are compact (block + name + label); pattern content and template HTML are NOT echoed — use wppilot/spectra-one-list-templates + wppilot/read-file or an execute-php snippet to inspect a single template. |
wppilot/spectra-one-list-hooksList Spectra One Hooks | Returns the 11 custom filter hooks the Spectra One theme exposes (prefix swt_*), each with name, type (all filters in 1.2.x), accepted parameters, default value, source file, and human-readable description. Optional type filter narrows the list to action (empty in 1.2.x), filter, or all (default). Read-only introspection — use before proposing customization snippets that hook into the theme. |
wppilot/spectra-one-list-patternsList Spectra One Patterns | Returns the block patterns bundled with the Spectra One theme (85 files under patterns/*.php as of 1.2.2). Compact rows — slug, title, categories, keywords, file path (theme-root relative). Content is NOT echoed. limit (default 25, max 100) + offset paginate; category (optional) narrows the response to a single category slug (spectra-one-headers, spectra-one-footers, spectra-one-sections, or any Core / theme category the pattern header declares). Use wppilot/read-file or a wppilot/execute-php snippet on the returned file path to load the pattern HTML on demand. |
wppilot/spectra-one-list-posts-with-display-overridesList Posts with Spectra One Display Overrides | Enumerates posts and pages that carry at least one Spectra One per-post display override (hide_header / hide_footer / hide_title / sticky_header / transparent_header). Compact rows: post_id, post_title, post_type, and overrides — the list of override keys the row has set. Progressive disclosure: full values are NOT echoed; call wppilot/spectra-one-get-post-display-settings for a specific post. limit (default 25, max 100) + offset paginate; optional post_type filter narrows to one type (typically page or post). orderby selects sort order (defaults to modified DESC — most recently touched first). |
wppilot/spectra-one-list-spectra-blocksList Spectra (UAGB) Blocks | Returns the catalogue of Spectra (UAGB) blocks registered by the companion plugin. Compact rows: name (fully-qualified uagb/* slug), title, category. Optional category narrows the response (e.g. uagb-category). Progressive disclosure — per-block attribute schemas are NOT echoed; use the base WPPilot gutenberg / block-schema abilities for those. Requires the Spectra (UAGB) plugin: when the plugin is missing / under-min, returns spectra_one_requires_plugin. |
wppilot/spectra-one-list-style-variationsList Spectra One Style Variations | Returns a compact list of bundled Spectra One style variations (pre-configured wp_global_styles snapshots under styles/*.json). Each row: slug, title, source file path (relative to theme root), palette color count, and up-to-three sample palette hexes for a lightweight preview. Progressive disclosure — full JSON is NOT included; for the full payload load the returned file path via an execute-php snippet. Apply a variation via wppilot/spectra-one-apply-style-variation. |
wppilot/spectra-one-list-templatesList Spectra One Templates | Returns the FSE templates and template parts bundled with Spectra One. Each row: slug (file basename), type (template or part), area (header/footer/sidebar for parts; empty for templates), and file path relative to the theme root. Optional type input narrows the response: all (default), templates, or parts. Content is NOT echoed — the file paths are surfaced so a follow-up read (via the base WPPilot read-file ability, or an execute-php snippet) can pull the HTML on demand. |
Writes
Gated by the active profile and your WordPress capabilities. Rate limited to 120 per minute per credential.
| Ability | What it does |
|---|---|
wppilot/spectra-one-add-font-familyAdd Spectra One Font Family | Downloads a Google Font family and registers it with the WordPress Font Library so blocks and the Spectra One typography settings can reference it. Provide the font family name (exactly as it appears on fonts.google.com — case sensitive, e.g. "Playfair Display", "DM Sans", "Space Grotesk") and the numeric weights to install (defaults to [400, 700] when omitted). Idempotent: a subsequent call for the same font family reports the already-installed slug without redownloading. Delegates to the theme-native spectra-one/install-font ability so upstream SSRF / WOFF2 verification / host allowlist logic stays in one place. |
wppilot/spectra-one-apply-designApply Spectra One Design Snapshot | Applies a Spectra One design snapshot produced by wppilot/spectra-one-export-design to the current install: replaces the wp_global_styles user overlay AND the swt_theme_options bag with the snapshot payload. Snapshot keys are filtered against a top-level WPPilot allowlist — wp_global_styles keeps only the trusted top-level shape (settings, styles, version, isGlobalStylesUserThemeJSON); swt_theme_options keeps only the keys the per-slot set-typography / set-theme-settings writers touch. Only top-level keys are validated here; sub-shapes inside the kept keys (e.g. individual palette entries under settings.color.palette) pass through as-is. Dropped keys are reported in filtered.global_styles / filtered.theme_options. snapshot accepts the exact object shape export-design returns (schema_version, theme, global_styles, theme_options — stats + exported_at are read for compatibility hints but not required). Payload is refused above 1 MiB to keep the write in-memory-safe on a 128 M PHP limit. dry_run: true runs schema validation + theme-version comparison + allowlist filtering without persisting, so the caller can preview whether the snapshot is safe and what will be dropped. Destructive: replaces the two write surfaces wholesale (partial patches are not supported). The write is lock-protected (shared with every other design-surface writer) and flushes both the theme_json + swt_theme_options caches. Error codes: spectra_one_snapshot_unsupported_version (schema_version not 1), spectra_one_invalid_input (snapshot from a different theme), spectra_one_no_global_styles (no user global-styles post exists yet), spectra_one_snapshot_too_large (snapshot exceeds the 1 MiB ceiling). |
wppilot/spectra-one-get-typography-settingsGet Spectra One Typography Settings | Returns the active Spectra One typography configuration: body settings (font_family, font_weight, line_height, responsive font_size with desktop / tablet / mobile + unit), headings settings (font_family, font_weight, line_height), plus the theme.json presets — bundled font families with weights, the 8 fluid font-size presets (X-Small … XXXX-Large), 5 line-height presets, 9 font-weight presets, and 8 border-radius presets. Presets are the writable allowlist for wppilot/spectra-one-set-typography (Sprint 3). |
Destructive
Marked destructive in the source, so each call needs an explicit confirmation flag, every time.
| Ability | What it does |
|---|---|
wppilot/spectra-one-apply-style-variationApply Spectra One Style Variation | Applies a bundled Spectra One style variation (one of aquamarine, dark, easter-green, mango, pink, rain-forest, sweet-corn, ultra-marine as of 1.2.2) to the wp_global_styles overlay. For every top-level settings.<key> the variation declares (the bundled variations ship color and typography), the corresponding sub-tree of the overlay is replaced wholesale; other settings.* sub-trees (spacing, layout, custom tokens) are preserved. When the variation declares a styles block, the entire styles sub-tree of the overlay is wholesale-replaced by the variation's — block-level style rules the variation does not mention are dropped. Take a snapshot with wppilot/spectra-one-export-design first if you need a rollback point. dry_run: true returns the resulting overlay without persisting so the caller can preview. Discover the writable list via wppilot/spectra-one-list-style-variations. Destructive: overwrites the color palette, gradients, duotones, typography presets, and the entire styles block; the write is lock-protected and flushes the theme_json cache. Error codes: spectra_one_variation_not_found (unknown slug), spectra_one_variation_malformed (bundled JSON is corrupt). |
wppilot/spectra-one-edit-navigationEdit Spectra One Navigation | Sets or appends items to the Spectra One primary navigation menu. Accepts items — a list of { label, url, id?, children? } entries; top-level items with a non-empty children array render as hierarchical dropdowns (wp:navigation-submenu). append: true merges with the existing menu, deduplicating by id / url and unioning children by url; append: false (default) replaces the menu wholesale. Wires the header + footer template parts to reference the resulting wp_navigation post — so a single call sets the menu everywhere it renders. Delegates to the theme-native spectra-one/update-navigation. |
wppilot/spectra-one-edit-template-partEdit Spectra One Template Part | Switches the active header or footer design by activating a different Spectra One pattern on the corresponding FSE template part. Discover the available pattern slugs with wppilot/spectra-one-list-patterns filtered by category spectra-one-headers or spectra-one-footers. Optional use_site_title swaps the logo image for a wp:site-title block (useful when the install has no logo asset). Delegates to the theme-native spectra-one/update-template-part. |
wppilot/spectra-one-set-color-paletteSet Spectra One Color Palette | Replaces one or more slots in the Spectra One color palette by writing to the wp_global_styles user overlay. Accepts a colors list of { slug, color, name? } entries — slug must be one of the 14 allowed palette slugs (primary, secondary, heading, body, background, tertiary, quaternary, surface, foreground, outline, neutral, transparent, currentColor, inherit), color must be a 6-digit or 8-digit hex (#RRGGBB or #RRGGBBAA), name is optional and defaults to the current name (or a Title-Case of the slug on first-write). Slots absent from the input are left untouched — this is a partial patch, not a wholesale replace of the palette. Destructive: overwrites existing overlay values for the passed slots. The write is lock-protected against parallel writers and flushes the theme_json cache so the next request renders the new palette. |
wppilot/spectra-one-set-post-display-settingsSet Spectra One Post Display Settings | Replaces the Spectra One per-post display overrides on the post identified by post_id (accepts both post_id and the WP-native alias id). Only post and page are supported — the theme metabox is not registered on other post types, so a call against a different type is rejected up front with spectra_one_unsupported_post_type. All 5 boolean fields (hide_header, hide_footer, hide_title, sticky_header, transparent_header) are always required — passing false on a slot removes the meta row so the theme defaults render. Partial patches are NOT supported by this ability (that is the semantic of set-); call wppilot/spectra-one-get-post-display-settings first, merge the fields you want to change, then invoke this. clean_post_cache is called after every write so the next render observes the new state. |
wppilot/spectra-one-set-theme-settingsSet Spectra One Theme Settings | Updates one or more global theme options in the swt_theme_options bag. The options object accepts scroll_top (boolean — enables / disables the "back to top" button the theme renders on the frontend). Additional flags land here as later releases expose them. Every field is optional; pass only what you want to change. Destructive: overwrites the existing option value; the write is lock-protected. |
wppilot/spectra-one-set-typographySet Spectra One Typography | Updates the Spectra One typography options bag (swt_theme_options) with new body and/or headings settings. Every value is validated against the theme.json preset allowlist reported by wppilot/spectra-one-get-typography-settings — font_family must reference one of the bundled family slugs, font_weight one of the 9 declared weights, line_height one of the 5 declared line-heights. Body font_size accepts a responsive object with desktop / tablet / mobile numeric strings + a desktop_unit (defaults to px). Every field is optional — pass only what you want to change. Destructive: overwrites the existing values on the passed keys; the write is lock-protected and flushes the theme_json cache. |