> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Editing with AI

> Edit an Easy theme through MCP chat or a local ThemeDocument checkout, then review and publish it.

Shoppex AI tooling works with the same structured theme document as the visual Builder.
You can use an MCP connection or a local file checkout.

## Which path to choose

| Path           | Working model                                                      | Best fit                                                   |
| -------------- | ------------------------------------------------------------------ | ---------------------------------------------------------- |
| MCP            | No local files. Ask for changes in chat.                           | Chat-first work and small Builder changes                  |
| Local checkout | Full local ThemeDocument files with generated guidance and schemas | Claude Code, Cursor, Codex, and version-controlled changes |

Both paths use the ThemeDocument contract. Neither path uploads executable theme source for an Easy theme.

Read [Advanced styling for Easy themes](/storefront/easy-theme-advanced-styling) before you ask AI to add CSS or Custom HTML.

## Edit a local checkout with AI

Use the local checkout for a document-authoritative Easy theme.
A catalog theme has a read-only checkout because Builder settings remain its source of truth.

1. Pull the theme into an empty directory.

```bash theme={"system"}
shoppex theme pull --theme <id> --dir ./theme
cd theme
```

2. Open the directory in Claude Code, Cursor, Codex, or another AI tool.
3. Ask the tool to read the generated `AGENTS.md` before it changes files.
4. Start the live preview.

```bash theme={"system"}
shoppex theme dev
```

5. Ask for one focused change.

```text theme={"system"}
Read AGENTS.md. Add the class "glitch-heading" to the home hero.
Add the matching animation to theme-level custom CSS.
Keep every other field unchanged.
```

6. Review the local diff and the live preview.
7. Push the draft, then publish its recorded revision.

```bash theme={"system"}
shoppex theme push
shoppex theme publish
```

`theme dev` reloads the hosted preview after each valid file change.
If another editor saves first, it stops with a conflict instead of replacing that change.

Read the [Theme CLI guide](/storefront/theme-cli) for checkout files, revision conflicts, scopes, and command details.

## Edit through MCP

The MCP path uses this loop:

```text theme={"system"}
inspect -> propose a small change -> save -> review -> publish
```

## Connect your AI client

* Choose the theme you want to edit in **Store → Themes**.
* Open its **⋯** menu and select **Edit with AI**.
* Create a scoped key for that theme and follow the generated setup commands for your AI
  client.

The handoff also gives read-only CLI commands for the current document and schema. Use them
for inspection. Use the MCP tools below for revision-gated saves and publishing.

<Warning>
  Give the assistant a scoped API key. Review the saved change before publishing, especially
  when it affects product purchase or checkout handoff UI. Preview stays a dashboard action.
  Publish through the MCP tool with the exact revision returned by the save, or publish the
  reviewed draft in the dashboard.
</Warning>

## Two provenance workflows

The handoff response tells the assistant which workflow to use, through `document_provenance`,
`mcp_tools`, and `instructions`:

* **`settings_derived`** is the normal workflow for hosted themes. The assistant edits Builder
  settings, through `theme_settings_get` and `theme_settings_update`.
* **`document_authoritative`** is used for ThemeDocument imports and rebuilds. The assistant
  edits the complete saved ThemeDocument, through `get_theme_document` and
  `save_theme_document`.

Both workflows publish through `publish_theme_document`. The tool description repeats this
mapping. The assistant must follow the provenance instead of trying the document save flow for
every theme.

## Make a focused change

Ask the assistant to inspect the theme before editing:

```text theme={"system"}
Inspect my active theme. On the home page, change only the hero heading to
"Your next favorite download". Keep every other setting unchanged.
```

Good tasks are narrow and observable, for example:

* "Change the homepage hero heading and keep the existing buttons."
* "Add an FAQ block after the product grid."
* "Use the current primary color for collection-card links."

The assistant must read the current schema and the provenance-specific source, identify the
target block, and apply a structured change. Ask it to list the exact fields it changed before
saving.

## Save a settings-derived hosted theme

For `settings_derived` themes, the assistant must:

1. Call `theme_settings_get` and change the returned Builder settings.
2. Call `theme_settings_update` with the changed settings and the revision from the read
   unchanged. The tool increments the revision for the update.
3. Review the saved result and keep the Builder revision returned by the update.
4. Call `publish_theme_document` with that Builder revision as `expected_revision`.

Do not call `save_theme_document` for a `settings_derived` theme. That workflow intentionally
returns `409` because Builder settings are the source of truth.

## Save a document-authoritative theme

For a `document_authoritative` import or rebuild, the assistant must:

1. Call `get_theme_document` and change the complete ThemeDocument it returns.
2. Call `save_theme_document` with the read revision as `expected_revision`.
3. Review the saved result and keep the new ThemeDocument revision returned by the save.
4. Call `publish_theme_document` with that new revision as `expected_revision`.

In both workflows, publishing validates the result and creates a new locked serving
revision. Before publishing, review the saved result in the visual Builder on desktop and
mobile, especially purchase and checkout handoff UI.

<Warning>
  If another editor saves the theme first, Shoppex returns a revision conflict instead of
  overwriting your change. Load the current source again: Builder settings for
  `settings_derived`, or the ThemeDocument for `document_authoritative`. Apply your change to
  it again, then save. Never overwrite the other editor's change.
</Warning>

## Good follow-up prompts

* "Add an FAQ block after the product grid, using the existing spacing."
* "Use the current primary color for collection-card links."
* "List the exact settings you changed and the saved revision without publishing."