> ## 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

> Connect an AI client to inspect and update a Shoppex theme, then publish through its provenance-specific workflow.

Shoppex AI tooling works with the same structured theme document as the visual Builder. The
assistant does not edit or upload executable theme code. A useful loop is:

```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."