---
name: woodmart-mcp
description: Playbook for controlling the Woodmart theme through this plugin's woodmart_* and theme_* tools — theme options, HTML blocks, layouts, widgets, and the backup/restore safety rule. Read before changing any Woodmart theme setting.
version: 1.0.0
auto-load: false
tags: [woodmart, theme, woocommerce, options, html-blocks]
---

# Woodmart MCP — Theme Control Playbook

## When to use this skill

Load before touching anything Woodmart-specific: theme options (colors, header, shop layout), HTML blocks, mega menus, or Woodmart's own page-builder elements. For Elementor structure see `wordpress-elementor`; for store data see `woocommerce`.

---

## Step 0 — confirm Woodmart is active

Always start with `woodmart_detect`. It returns `{active, name, version, option_store}`. On this site that is Woodmart 8.4.1, option store `xts-woodmart-options`. If `active` is false, stop — none of the woodmart_* tools will do anything useful and you may be on the wrong site. (Site targeting: resolve the request against the site registry id and use only that entry's access method.)

---

## Theme options — the single source of truth

Woodmart stores its configuration in one serialized option, `xts-woodmart-options`. Read before you write.

- `woodmart_list_options` — enumerate available option keys.
- `woodmart_get_option(key)` — read one value.
- `woodmart_set_option(key, value)` — write one value.
- `woodmart_restore_option(key)` — roll back to the pre-change backup.

**The safety rule:** `woodmart_set_option` snapshots the previous value into the `amp_wd_backup` store before writing. Every change is therefore reversible with `woodmart_restore_option`. Still: change one key at a time, verify on the live page, then move on. Never batch-blind a dozen theme options — a wrong serialized value can affect the whole site chrome.

Common option domains: global colors/typography, header layout and sticky behavior, shop/catalog layout (columns, filters, quick-view), single-product layout, footer, and performance toggles. Confirm the exact key with `woodmart_list_options` rather than assuming the slug.

---

## HTML blocks — Woodmart's reusable content units

Woodmart HTML blocks are a custom post type used for headers, footers, mega-menu panels, popups, and injected sections.

- `woodmart_list_html_blocks` — list existing blocks with their ids.
- `woodmart_get_block(id)` — read a block's content.
- `woodmart_create_html_block(...)` — create a new block.

Use blocks for content that must appear in several places (a promo bar, a footer column, a mega-menu panel) — edit once, it updates everywhere it's referenced. Don't rebuild the same markup inline across pages.

---

## Layouts and widgets

- `woodmart_list_layouts` — Woodmart layout definitions (header/footer/shop layouts registered by the theme).
- `woodmart_list_widgets` — Woodmart's own widgets/elements (the theme registers ~150, including Elementor widgets). Use this to see what Woodmart gives you before pulling in a third-party addon.
- Theme-capability probes (useful for planning): `theme_woodmart_elements`, `theme_elementor_support`, `theme_elementor_tokens`, `theme_page_templates`, `theme_widget_areas`, `theme_taxonomies`, `theme_custom_post_types`.

---

## Woodmart + WooCommerce

Woodmart is a shop theme — most of its options shape the WooCommerce experience (product grid, cart, checkout, wishlist, compare, quick view). When a store task is really a *presentation* task (how products look, shop columns, catalog filters), it's a Woodmart option, not a WooCommerce setting. Rule of thumb: **what the shop sells and how it transacts = `wc_*`; how the shop looks = `woodmart_*`.** See the `woocommerce` skill for the data side.

---

## Safe-change workflow

1. `woodmart_detect` — confirm active + version.
2. `woodmart_list_options` / `woodmart_get_option` — read current state.
3. `woodmart_set_option` — change ONE key (auto-backs-up).
4. `cache_purge_all` — Woodmart and the cache layer both cache theme output; purge or you'll see the old chrome.
5. Verify on the live URL.
6. Wrong? `woodmart_restore_option(key)` and purge again.

---

## Gotchas

- **Change didn't show** → theme/cache layer served the old version. `cache_detect` then `cache_purge_all`. Woodmart also has its own CSS cache; a theme-option save usually regenerates it, but purge to be sure.
- **Guessed an option key** → `woodmart_set_option` on a wrong key is a no-op or worse. Always list first.
- **Batch theme edits** → one bad serialized value breaks site chrome globally. One key at a time, verify between.
- **Edited shop *layout* via WooCommerce settings** → wrong layer. Catalog/product presentation is Woodmart options.
- **HTML block edited but not showing** → confirm the block is actually referenced by the header/footer/menu location; creating a block doesn't place it.