# Crust AI kit — setup

You are an AI coding assistant. A merchant asked you to set up their Shopify theme for AI
editing. Work through these steps in order, in the merchant's own language. Ask before
anything that touches their store. If a step fails, stop and report it — do not improvise
around it.

## 0. Work out what you need

- **Claude Code** → `CLAUDE.md`, plugin through the `claude` CLI.
- **Codex** (the CLI, or the Codex experience in the ChatGPT desktop app) → `AGENTS.md`,
  plugin through the `codex` CLI.
- **Anything else** (Cursor, Copilot, VS Code, …) → `AGENTS.md`. Skip step 8 unless your host
  installs Agent Plugins 1.0 packages.

If you have no shell and no filesystem, stop here and say so: this setup needs both. A chat
connector to Shopify cannot edit theme code — it reads and writes the admin (orders,
inventory, prices), not the theme.

## 1. Preflight

Node 18 or newer. Then check the Shopify CLI:

```bash
shopify version || npm install -g @shopify/cli
```

Never run the install with `sudo`. If the global install is refused, stop and tell the
merchant — a broken Node permission setup is theirs to fix, not yours to work around.

## 2. Find the theme

Ask for the store domain (`example` or `example.myshopify.com`), then:

```bash
shopify theme list --store <store>
```

The first CLI command opens a browser to log in; tell the merchant to expect it.

Show the list and **ask which theme is the Crust theme they want to work on**. Never assume,
and never pick the live theme by default.

## 3. Duplicate — never work on the live theme

```bash
shopify theme duplicate --store <store> --theme <id> --name "<theme name> — AI edits"
```

Re-run `shopify theme list` to get the new theme's id. Everything from here targets the
duplicate. The live theme stays untouched until the merchant asks you to publish, and then
only after a preview link and one confirmation (see the instruction file).

## 4. Pull it down

```bash
shopify theme pull --store <store> --theme <new id> --path <store prefix>-crust
```

Create the folder in a sensible place — ask if you are not sure where they keep projects.

## 5. Confirm it is Crust

Read `config/settings_schema.json` > `theme_info`. If `theme_name` is not `Crust`, **stop**:
this kit describes Crust, and its architecture rules do not hold for another theme. Tell the
merchant what theme they actually have. Note `theme_version` — the instructions are written
for Crust 1.0.x.

## 6. Put it in git

```bash
git init && git add -A && git commit -m "Crust as pulled"
```

Not optional. Every later `shopify theme pull` overwrites local files; without commits there
is no diff to re-apply and no undo.

## 7. Install the instruction file

Into the **root of the theme folder**, not its parent:

```bash
# Claude Code
curl -fsSL https://elade.io/ai-kit/crust/download/claude -o CLAUDE.md
# Codex, Cursor, and everything else
curl -fsSL https://elade.io/ai-kit/crust/download/agents -o AGENTS.md
```

Read it before you go further — it is the theme's architecture, and the rest of your work
depends on it. If the theme folder is a git repo the merchant shares with others, commit it.

## 8. Install the skills

Six guided workflows: `new-section`, `new-block`, `personalize`, `translations`,
`check-and-push`, `after-update`.

```bash
# Claude Code
claude plugin marketplace add elade-io/elade-ai-kit
claude plugin install crust@elade-ai-kit -y

# Codex
codex plugin marketplace add elade-io/elade-ai-kit
```

Codex installs through its picker, so after adding the marketplace tell the merchant to run
`/plugins` and add **Crust AI kit** themselves.

## 9. Create STORE.md

Next to the instruction file, exactly this skeleton — leave it empty. The `personalize` skill
interviews the merchant and fills it in; guessing their brand voice now only creates work.

```markdown
# STORE.md — shared AI memory for this store

## Store profile

## Language policy

## Brand voice

## Customizations log
<!-- one line per entry: YYYY-MM-DD — file — reason — summary -->
```

## 10. Hand off

Tell the merchant, briefly:

- Which folder the theme is in, which duplicate it points at, and that the live theme was not
  touched.
- **Restart the session** — skills load at startup, so the six workflows are not available in
  the session that installed them.
- What to say next: *"personalize the copy for my brand"*, *"add a section that …"*,
  *"check and push"*.
- Live preview any time: `shopify theme dev --store <store> --theme <id>`.
- Nothing reaches shoppers until they ask you to publish, or publish it themselves in
  Shopify admin.