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

# AI Theme Workflows

> Use AI assistants safely with Shoppex Liquid themes, CLI, MCP, preview, and publish.

# AI Theme Workflows

<Info>
  This page applies to **custom code themes** (forked or imported Liquid packages).
</Info>

AI works best when it follows the same control-plane loop as a careful developer:

```text theme={"system"}
inspect -> search -> read -> apply -> validate -> preview -> publish
```

## Good AI Tasks

Good:

* "Find the hero section and change only the CTA copy."
* "Add a testimonials section using the same spacing as the feature section."
* "Fix the Liquid validation error, then preview."
* "Update the product card markup but keep platform cart behavior."

Risky:

* "Rewrite the whole storefront."
* "Change anything you think looks bad."
* "Bypass validation."
* "Move checkout logic into the theme."

## Required Scopes

Use an API key with:

* `themes.read`
* `themes.write`

An inspect-only assistant can use `themes.read` alone.

## CLI Workflow

```bash theme={"system"}
shoppex auth login --api-key shx_your_key
shoppex theme list
shoppex theme inspect --theme "$THEME_ID"
shoppex theme pull --theme "$THEME_ID" --out ./my-theme
cd ./my-theme
shoppex theme dev
```

After edits:

```bash theme={"system"}
shoppex theme push --preview --include-typecheck
shoppex theme publish
```

## Local AI Handoff Workflow

Use this when a human starts work, an AI edits locally, and another human or AI reviews it.

<Steps>
  <Step title="Human creates a scoped key">
    Use only `themes.read` and `themes.write`.
  </Step>

  <Step title="AI pulls and inspects">
    The assistant runs `theme list`, `theme pull`, `theme inspect`, then reads only the relevant Liquid files.
  </Step>

  <Step title="AI runs local preview">
    The assistant starts `shoppex theme dev` and uses fixture data unless the change depends on real catalog, stock, product detail, or settings data.
  </Step>

  <Step title="AI makes a narrow change">
    One section, snippet, CSS area, or settings/schema change at a time.
  </Step>

  <Step title="AI validates and previews">
    The assistant runs `shoppex theme validate --include-typecheck` and `shoppex theme push --preview --include-typecheck`.
  </Step>

  <Step title="Human reviews publish decision">
    Publish only after the preview has been reviewed. AI should not publish unless explicitly asked.
  </Step>
</Steps>

Simple example:

```text theme={"system"}
Pull my active Liquid theme, inspect the file tree, find the homepage hero,
change only the CTA label, run validation, push a preview, and hand me the preview URL.
Do not publish.
```

## MCP Workflow

Set:

```bash theme={"system"}
export SHOPPEX_API_URL=https://api.shoppex.io
export SHOPPEX_API_KEY=shx_your_key
```

Useful tools:

* `theme.inspect`
* `theme.search_files`
* `theme.read_file`
* `theme.apply`
* `theme.create_section`
* `theme.create_page`
* `theme.update_config`
* `theme.validate`
* `theme.preview`
* `theme.publish`

## Liquid-Specific Prompt Rules

Tell the assistant:

* Keep templates presentational.
* Preserve `data-builder-block` and `data-builder-block-type`.
* Use static `{% render "snippets/name" %}` calls only.
* Use `safe_href` for user URLs.
* Use `| raw` only for platform-owned HTML.
* Do not compute stock, price, sorting, or checkout rules in Liquid.
* If a new file is added, declare it in `theme-package.json`.
* Keep platform commerce hooks and data attributes intact.
* Prefer preview over publish unless the prompt explicitly says publish.

Simple prompt:

> Inspect the theme, find the product card snippet, and adjust only the badge layout. Keep the existing platform data attributes and cart behavior. Validate and start a preview.

## Handoff Block

At the end of a non-trivial AI theme session, ask the assistant to leave this:

```markdown theme={"system"}
## Scope
Theme id:
Files changed:
User-facing change:

## Verification
shoppex theme validate --include-typecheck:
shoppex theme preview:
Preview URL:
Cart/checkout checked:

## Publish state
Published: yes/no
If yes, publish job id:

## Risks / not verified
-

## Next recommended action
-
```

This makes the next person or AI agent faster. Simple example: if cart/checkout was not checked because the change only touched homepage copy, say that explicitly.

## Review Before Publish

Before publishing, check:

* validation passed
* preview URL shows the change
* cart and checkout still work
* no unsafe Liquid or dynamic partials were added
* `diff` matches the intended change

## Next Steps

<CardGroup cols={2}>
  <Card title="Editing Themes" icon="sliders" href="/themes/editing">
    Shared dashboard, CLI, Dev API, and MCP workflow.
  </Card>

  <Card title="Core Contract" icon="file-code" href="/themes/core-contract">
    Liquid responsibilities and safety rules.
  </Card>
</CardGroup>