> For the complete documentation index, see [llms.txt](https://wishlist.nativeappco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wishlist.nativeappco.com/install-and-setup/installing-using-ai-tools/agent-setup-guide.md).

# Setup instructions for AI agents

Step-by-step instructions for AI agents installing Fish Wishlist on a Shopify theme. Point your AI tool at this page.

{% hint style="info" %}
**This page is written for AI tools.** Give its link to Claude Code, Codex, Cursor, Claude, ChatGPT or any other AI assistant and ask it to follow the instructions. See [Install with an AI tool](https://wishlist.nativeappco.com/install-and-setup/installing-using-ai-tools/install-with-ai.md) for how to set each one up.

Developers can also save this page as `FISH_WISHLIST_SETUP.md` in the theme repo, so the agent can read it offline.
{% endhint %}

## Instructions for the agent

You are adding the Fish Wishlist app to a Shopify Online Store 2.0 theme. Fish ships a theme app extension (app embed + app blocks) and a few custom elements. Your job is to wire them into this theme so it looks native, then hand back a short report.

**How you work depends on what you can access:**

* **You can edit the theme files** (a local copy pulled with Shopify CLI): follow every step below, making the edits yourself.
* **You are connected to the Fish Wishlist MCP server:** start with `verify_theme_setup` on the theme and `get_settings`, install the required steps with their defaults, send `links.preview`, then offer customisation (`ask_setup_questions`). The first returns the setup checklist: every step with its status, the merchant's instructions and theme editor link, and an `apply` payload (file, block type with the extension ID, JSON or Liquid) you can use when you also have a way to write theme files (Shopify's MCP server, Shopify CLI). Through the Fish MCP alone you can read theme files but not change them, so treat theme edits as instructions for the user (next point). You can save app settings yourself (`update_settings`) and, once the required steps verify, mark the installation complete (`complete_setup`) if the connection has write access.
* **You can't edit files** (a chat assistant): follow the same steps, but ask the user for the theme files you need to read (Step 0 lists them). For each change, tell them the exact file (Shopify admin → Online Store → Themes → ⋯ → Edit code), where to put it, and the full code to paste. Where a step offers an app block, prefer telling them to add it in the theme editor (Customize → Add block → Apps) over editing JSON templates by hand. One change at a time; ask them to save and check the preview before the next.

### Ground rules

* **Install the defaults first, without asking questions.** Reading the theme (Step 0) and the three required steps with their defaults (Steps 2–4) on an unpublished theme need no confirmation. Ask before anything beyond that: the live theme, the optional steps, and customisation (see [Customisation options](#customisation-options)).
* **Never push to the live theme.** Preview with `shopify theme dev`, or push to an unpublished theme (`shopify theme push --unpublished` or `--theme <id>`). Only push to the live theme if the user explicitly tells you to in this session.
* **Push only the files you changed** (`shopify theme push --only <file> ...`). A full push overwrites edits the merchant made in the theme editor since your last pull. Run `shopify theme pull --only <file>` right before editing any `templates/*.json`, `sections/*.json` or `config/settings_data.json`.
* **Never invent the app's extension ID.** App embed and app block types look like `shopify://apps/fish-wishlist/blocks/<block-handle>/<extension-id>`. Copy the prefix from an entry that already exists in the theme (see Step 2). Do not guess it.
* **Prefer app blocks over hand-written markup.** Use the custom elements below only where the theme's sections don't accept app blocks (`{"type": "@app"}` in the section schema), or where blocks can't reach (product cards, mobile menus).
* **Enable only one wishlist embed.** "Wishlist Drawer 2.0" (`wishlist-v2`) is the current one. "Wishlist" (`wishlist`) is the classic drawer kept for older installs. With both on, the store loads two wishlists.
* **Match the theme.** Reuse the theme's own icon sizes, button classes, spacing and CSS variables. Keep diffs small and leave a short Liquid comment (`{%- comment -%} Fish Wishlist {%- endcomment -%}`) at each insertion point so the next developer can find it.
* **Don't edit Fish's own files or assets**, and don't add external scripts.
* If something in this guide doesn't match what you see in the theme, stop and ask the user instead of guessing.

### Step 0: Recon (read only)

Before changing anything, find and note:

1. **Theme name and version:** `config/settings_schema.json` → `theme_info`.
2. **Current Fish state:** search `config/settings_data.json`, `templates/*.json` and `sections/*.json` for `fish-wishlist`. Note which embed is enabled (`wishlist-v2`, `wishlist`, or neither) and which blocks are already placed. An entry with `"disabled": true` counts as off.
3. **Header:** the header section file (often `sections/header.liquid`, referenced from `sections/header-group.json`), where the cart/account icons render, and whether its schema accepts `@app` blocks.
4. **Product page:** every product template (`templates/product*.json`), the main product section each one uses, and whether that section accepts `@app` blocks.
5. **Product card:** the snippet that renders product cards in collections, search and recommendations (often `snippets/card-product.liquid`, `product-card.liquid` or `product-grid-item.liquid`) and the variable name for the product inside it (`card_product`, `product`, `item`...). Also check for a search/filter app (Boost, Searchspring, Algolia...) that renders its own cards in JavaScript.
6. **Variant picker:** how the theme announces a variant change (see Step 4).
7. **Cart drawer:** the JavaScript that renders or refreshes the cart drawer and cart count (see Step 7).

Don't change anything yet. Use what you found for the one-line summary and the defaults in Step 1.

### Step 1: Install the defaults, then offer customisation

Keep the first message short: the theme name, what Fish already has in place, and what you are about to install. Then do Steps 2–4 with the defaults below without asking anything (the only exception: if the live theme is the only theme and you would edit it, ask once, or duplicate it first if your tool can).

**Defaults**

* App embed: Wishlist Drawer 2.0, embed settings untouched.
* Header icon: left of the cart icon, with the saved-item count badge, in the theme's own icon style. Mobile menu too if the theme renders icons there.
* Product page button: next to Add to cart on the same row, with its label, styled like the theme's secondary button, on every product template.
* App settings: unchanged (heart icon, guests can save, one wishlist per customer, the drawer opens after adding).

As soon as the three steps are in, send the user the preview link, `https://<shop>.myshopify.com/?preview_theme_id=<theme id>` for an unpublished theme or the storefront URL for the live one, with one line on what to try (save a product, open the drawer). Over the Fish MCP, `verify_theme_setup` returns it as `links.preview`; call `complete_setup` once the required steps verify.

Then say the basic version is installed and offer customisation in one sentence. Only if the user wants changes, go through the [Customisation options](#customisation-options) (over the MCP, `ask_setup_questions` shows them as a card or form) or act on what they ask for. Skip questions that do not apply, never ask for things you can find out yourself (file names, class names, the extension ID), and do not re-ask what the user already said.

### Step 2: Enable the app embed

Look in `config/settings_data.json` → `current.blocks` for an entry whose `type` contains `/blocks/wishlist-v2/`.

* **Present and not disabled:** done. Copy its type prefix (everything before `wishlist-v2`) and the extension ID after it. You need them for the blocks below. Over the Fish MCP, `verify_theme_setup` gives you the full block types in `steps[].apply.block.type`.
* **Missing, and you can write theme files** (Shopify's MCP connector, Shopify CLI): on an unpublished theme add the entry yourself. Over the Fish MCP, `verify_theme_setup` gives the complete block in `steps[].apply` for the `app-embed` step: write `apply.block` (id `fish_wishlist_drawer_2`, the exact `type`, `"disabled": false`) into `current.blocks` of `config/settings_data.json`, read right before editing, keep every other block, set any entry whose type contains `/blocks/wishlist/` to `"disabled": true`, push only that file. Do this only when `apply.recommended` is true (the block type was seen in the theme); otherwise, or on the live theme, use the theme editor route below once so Shopify writes the exact type with its default settings.
* **Missing, and you cannot write theme files:** ask the user to enable it:

  > Online Store → Themes → *(this theme)* → Customize → **App embeds** → turn on **Wishlist Drawer 2.0** → Save.

  The Fish admin's **Setup** page has a button that opens this screen directly. When they confirm, run `shopify theme pull --only config/settings_data.json` (or `verify_theme_setup`) and continue.
* **Classic `wishlist` embed is on** (existing store): leave it alone unless the user asks to switch. If they do, set the classic entry to `"disabled": true` and make sure `wishlist-v2` is on. Customer wishlists are kept either way.

Drawer choices from the customisation step (presentation, corner radius, colours) go in the `wishlist-v2` entry's `settings` in `config/settings_data.json`. Use only setting IDs that already appear in that entry, or tell the user to set them in the theme editor (App embeds → Wishlist Drawer 2.0).

The embed alone gives the store the add-to-wishlist and view-wishlist drawers. The steps below add the buttons that open them.

### Step 3: Header "open wishlists" icon

Put it next to the account/cart icons, sized like them, on desktop and mobile.

**A. App block** (if the header section accepts `@app` blocks). In the header group JSON, add to the header section's `blocks` and `block_order`:

```json
"fish_open_wishlists": {
  "type": "shopify://apps/fish-wishlist/blocks/open-wishlists-button/<extension-id>",
  "settings": { "icon_color": "#2D2D2D", "count": true, "count_color": "#ffffff" }
}
```

Use the exact prefix and ID from Step 2. Pick an `icon_color` that matches the theme's header icons.

**B. Custom element** (most headers, including Dawn-family themes). In the header Liquid, next to the cart icon:

```liquid
{%- comment -%} Fish Wishlist: opens the wishlists drawer {%- endcomment -%}
<open-wishlists-button role="button" data-primary class="header__icon">
  <svg xmlns="http://www.w3.org/2000/svg" width="26" height="24" fill="none" aria-hidden="true"><path d="M20.583 22.75 13 17.333 5.417 22.75V5.417A2.167 2.167 0 0 1 7.583 3.25h10.834a2.167 2.167 0 0 1 2.166 2.167V22.75Z" stroke="currentColor"></path></svg>
  <div class="wishlist-count-bubble"></div>
</open-wishlists-button>
```

* Replace the SVG with the theme's own icon style (a heart or bookmark drawn like its other icons) and swap `header__icon` for the class the theme's icons actually use.
* `.wishlist-count-bubble` shows the saved-item count (Fish fills it with `<span>N</span>` and empties it at 0). Remove it if the design has no count.

**Count badge position: it must sit exactly where the cart's badge sits.** Fish's default badge CSS (`position: absolute; left: 25px; top: 0`, 20×20px, inverted text colour) won't match the theme, so always override it:

1. Read the cart icon's markup and CSS: which element is `position: relative`, the badge's `top`/`right`/`bottom`/`left`, `transform`, size, border radius, font size and weight, line height, background and text colour, and any mobile breakpoint overrides.
2. Give `<open-wishlists-button>` the same wrapper structure and size as the cart link (same classes, same padding), so the offsets mean the same thing.
3. Reset Fish's defaults and copy the cart badge's values, scoped to the header so it beats Fish's stylesheet. For example:

   ```css
   /* Fish Wishlist: match the cart count badge */
   .header open-wishlists-button { position: relative; padding: 0; width: auto; }
   .header open-wishlists-button .wishlist-count-bubble {
     left: auto; top: auto; transform: none;   /* clear Fish's defaults */
     /* then the cart badge's values, e.g. */
     right: -0.6rem; bottom: 0.6rem; width: 1.7rem; height: 1.7rem;
     font-size: 0.9rem; background: rgb(var(--color-button)); color: rgb(var(--color-button-text));
   }
   .header open-wishlists-button .wishlist-count-bubble span { color: inherit; filter: none; }
   ```

   If the cart badge uses a class of its own (e.g. `cart-count-bubble`), adding that class to the badge `<div>` next to `wishlist-count-bubble` is often simplest. Still reset `left`, `top` and `transform`.
4. Check in the preview with items in both the cart and the wishlist: the two badges must line up at desktop and mobile widths, with 1-digit and 2-digit counts, and on transparent or sticky header states.

* If the mobile menu or drawer renders icons separately, add a second `<open-wishlists-button>` there.
* If the header has no good spot, a link to the wishlist page (Step 6) in the account menu works too.

### Step 4: "Add to wishlist" button on the product page

Place it near the Add to cart / Buy buttons. Do this for **every** product template the store uses.

**With its label by default.** The button shows the icon and the "Add to wishlist" label (the text comes from the app's languages), the same height as Add to cart, next to it on the same row, styled like the theme's secondary/outline button. Icon only is a customisation the user has to ask for; the Fish admin and `verify_theme_setup` treat an icon-only block as not installed.

**A. App block** (if the main product section accepts `@app` blocks). In each `templates/product*.json`, add to the main product section's `blocks`, and to `block_order` right after the buy buttons block:

```json
"fish_pdp_button": {
  "type": "shopify://apps/fish-wishlist/blocks/atw-button-pdp/<extension-id>",
  "settings": { "icon_only": false, "apply_custom_styles": false }
}
```

With `apply_custom_styles: false` the button takes its look from the theme's button classes. That is usually what you want. Set `icon_only` to `true` only if the user asked for icon only.

**B. Custom element** (sections without `@app` support, or custom builds). In the product form area:

```liquid
{%- comment -%} Fish Wishlist: add to wishlist {%- endcomment -%}
<wishlist-button-pdp
  role="button"
  class="fish-wishlist-button--pdp fish-wishlist-button--secondary button button--secondary"
  data-variant-id="{{ product.variants | map: 'id' | join: ',' }}"
  data-preselected-id="{{ product.selected_or_first_available_variant.id }}">
</wishlist-button-pdp>
```

* Swap the `button button--secondary` classes for the theme's secondary button classes.
* The label text comes from the app (Fish admin → **Languages**); don't hard-code it. Add the class `fish-no-label` (and an `aria-label`) only if the user asked for icon only.
* **`data-variant-id` must list every variant ID**, comma-separated, exactly as above. `data-preselected-id` holds the selected one. With only one ID in `data-variant-id`, the button saves that ID straight away and ignores the variant the shopper picked.

**Variant changes.** The button follows the selected variant by itself when the theme fires any of these:

* the standard `shopify:product:select` event (Horizon, Atelier, Dwell and other recent Shopify themes)
* Dawn's pub/sub `PUB_SUB_EVENTS.variantChange`
* a jQuery `onVariantChange` event

If the theme does none of these, find where its variant picker resolves the new variant and add:

```js
// Fish Wishlist: keep the wishlist button on the selected variant
document.querySelectorAll('wishlist-button-pdp').forEach((btn) => btn.updateAfterVariantChange?.({ id: variantId }));
```

`variantId` is the numeric ID or the `gid://shopify/ProductVariant/...` GID.

**Always test this**, even when the theme fires one of the events above. Some themes fire them before the new variant is known, or re-render the product section and replace the button. On a product with several variants: pick a variant other than the first, save it, then open the wishlist and check that the saved item shows the picked variant's option, image and price. Repeat on a page opened with `?variant=<id>` in the URL.

**Optional:** the "Wishlists Social Proof" block (`wishlists-social-proof`, product templates only) shows how many shoppers saved the product. Add it the same way only if the user asks.

### Step 5: Wishlist icon on product cards

Over the Fish MCP, `find_product_card_snippets` finds the card snippet, the product variable it uses and the line to paste after, and drafts the code below with the right variable.

In the product card snippet, inside the card's media/image wrapper:

```liquid
{%- comment -%} Fish Wishlist: card button {%- endcomment -%}
<wishlist-button class="position-absolute top-right" data-variant-id="{{ card_product.variants | map: 'id' | join: ',' }}"></wishlist-button>
```

* Use the snippet's real product variable instead of `card_product`.
* Positions: `top-right`, `top-left`, `bottom-right`, `bottom-left`. The element is `position: absolute`, so its wrapper must be `position: relative`. Check this, and make sure it sits above any full-card link overlay (`z-index`) without blocking clicks on the card.
* Put it in the shared card snippet once, not in every section, so collections, search, recommendations and quick view all get it.
* Products with several variants open the drawer's variant picker. Single-variant products save directly.
* **Search/filter apps** that render cards in JavaScript (Boost, Searchspring, Algolia...): add the same element to that app's card template, with `data-variant-id` set to the comma-separated variant IDs. Elements added later upgrade on their own; no init call is needed.

### Step 6: Wishlist page link (optional)

Each customer has a wishlist page at `/apps/fish-wishlist/customer-wishlist/WL1`. Add it to the account menu or footer if the user wants a page in addition to the drawer. Use `{{ routes.root_url }}` as the prefix on multi-language stores. The page template is edited in the Fish admin, not in the theme.

### Step 7: Cart refresh after "Add to cart" from the wishlist

Shoppers can add wishlist items to the cart from the drawer. Fish posts to `/cart/add.js`, then:

* publishes Dawn's pub/sub `PUB_SUB_EVENTS.cartUpdate` when the theme has it
* runs built-in refresh code for some themes (Dawn, Horizon family, Symmetry, Impact and a few others)
* dispatches `fishwishlist:item-added-to-cart` on `document`, with `detail: { variantId, quantity }` (or `{ items }`, the `/cart/add.js` response items, for a bulk add from a quote or the account page)

If the theme's cart drawer or count doesn't update after an add from the wishlist:

1. Read the theme's cart JavaScript and find how it refreshes itself: a custom event, a section re-render via the Section Rendering API, or a `renderContents()`-style method on the cart drawer element.
2. Write a short snippet (under \~30 lines, no external requests except the theme's own `/cart.js` or section renders) that **listens for `fishwishlist:item-added-to-cart`** and triggers that refresh. It should also open the cart drawer if the theme normally does after an add. The snippet runs once when the page loads, inside a `try/catch`, so it must register the listener rather than refresh straight away:

   ```js
   document.addEventListener('fishwishlist:item-added-to-cart', (event) => {
     // call the theme's own cart refresh here, e.g. re-render the cart drawer section
   });
   ```
3. **Don't put it in the theme.** It goes in **Fish admin → Developer → Theme integration → Cart refresh code**. Save it there through the MCP connection (`update_settings` → `cartRefreshCode`) if you have one; otherwise give the user the code to paste. That page also has a **Build with AI** button that writes the code from the downloaded theme.
4. **It is one setting for the whole store.** The code runs on every theme, including the live one while you work on a copy. Read the current value first and add to it with feature detection (for example `if (document.querySelector('cart-items-component'))`) instead of replacing code another theme still needs. With the MCP, `verify_theme_setup` reports `builtIn` on the cart refresh step when the app already handles the theme.

### Step 8: Styling

* Card and PDP buttons and the header icon are theme markup. Style them in the theme's CSS, scoped to the Fish elements (`wishlist-button`, `wishlist-button-pdp`, `open-wishlists-button`).
* The drawer belongs to the app. Its layout and colours are set in the embed's settings (theme editor → App embeds → Wishlist Drawer 2.0), and anything beyond that goes in **Fish admin → Settings → General → Custom CSS**. Drawer 2.0 uses `fw2-*` elements and classes (`fw2-drawer`, `.fw2-card__name`...); the classic drawer uses different ones. Don't guess selectors. With the MCP connected, call `get_component_structure`; otherwise inspect the drawer in the preview.
* Never style the drawer by editing theme files that load before the app's stylesheet. Scope rules to the drawer's host element so they win.

### Step 9: Test in the preview

Send the user the preview link (`?preview_theme_id=<id>`, or `links.preview` over the MCP) as soon as the defaults are in, then run `shopify theme dev` (or open that preview) and check every item on desktop **and** mobile width. If you can drive a browser, run the checks yourself. Otherwise give the user this list and ask them to report back. In the hand-off report, mark each item passed, failed or not tested.

**General**

* [ ] Only one wishlist drawer loads, and the console shows no Fish errors
* [ ] The header doesn't jump when the page loads (no layout shift around the new icon)

**Header**

* [ ] The icon matches the other header icons in size, colour, spacing and hover state, including transparent and sticky header states
* [ ] The count badge lines up exactly with the cart badge, at both widths, with 1-digit and 2-digit counts
* [ ] The badge is hidden at 0 and updates straight away after adding or removing (no reload)
* [ ] It opens the wishlists drawer by click and by keyboard (Tab, then Enter)
* [ ] The mobile menu icon (if added) works too

**Product page** (on a product with several variants)

* [ ] Icon only, unless a label was asked for; same height as Add to cart, aligned on the same row
* [ ] Pick a variant other than the first and save it: the wishlist shows that variant's option, image and price
* [ ] Switch variants: the button's saved/empty state follows the selected variant
* [ ] Open the page with `?variant=<id>`: that variant is the one saved
* [ ] Save variant A, switch to B and click again: B is saved (or the picker opens on B), and A stays
* [ ] Removing from the product page removes the selected variant, not the one selected on page load
* [ ] A single-variant product saves in one click, with no variant picker
* [ ] Every product template has the button; quick view / quick add modals too, if the theme has them

**Product cards**

* [ ] Visible on collection, search, recommendation and featured collection grids, and in any search/filter app
* [ ] Still there after filtering, sorting, "load more" or infinite scroll, with the right saved/empty state
* [ ] Clicking it doesn't open the product page, on desktop and on touch devices
* [ ] It doesn't cover the theme's quick add button, sale badge or hover image swap

**Customers**

* [ ] Guest: saving works, or the sign-in prompt shows (depends on the guest wishlist setting)
* [ ] Logged-in: items are still there after a reload and on another browser
* [ ] Guest saves, then logs in: the items are kept
* [ ] Multiple lists (if enabled): create a list from the drawer and save to it

**Cart and drawer**

* [ ] "Add to cart" from the drawer adds the right variant and updates the theme's cart drawer and count
* [ ] The wishlist drawer and the theme's cart drawer don't overlap, and the theme's cart close (X) button still works
* [ ] After closing the drawer the page scrolls again; Esc closes it
* [ ] No `_fish_wishlist` line property is visible in the cart (themes that print every line property need it hidden)
* [ ] Prices show in the right currency with Markets, and the drawer text is in the right language on each store language

### Step 10: Hand-off report

Finish with:

1. Files changed, one line each saying what was added.
2. What the user still has to do by hand (enable the embed, paste the cart refresh code, review on the live theme, publish).
3. The Step 9 checklist, with each item marked passed, failed or not tested.
4. Any theme quirks you found.

The merchant can confirm the install in **Fish admin → Setup**, which checks the embed and blocks on a chosen theme. End by offering customisation: the options below, or whatever the user asks for.

***

## Customisation options

Offer these only after the defaults are installed and the user has seen the preview, or when they ask for changes. Over the Fish MCP, `ask_setup_questions` builds this list from the theme (only the options that still apply, current values as defaults) and shows it as a card or form where the client supports it; `apply_setup_answers` saves the answers. Without the MCP, offer them in one message, grouped as below, each with its options and the recommended default, so the user can answer "keep the defaults" or pick a few. Skip what does not apply and what the user already decided.

**Placement**

1. **Header icon:** where should the "open wishlists" icon go (next to cart, account or search)? Also in the mobile menu? Show the saved-item count bubble? Or no header icon at all (e.g. a link in the account menu instead)?
2. **Product page button:** where should it go: next to the Add to cart button on the same row (recommended), below it, or over the product image? Which product templates should get it? List the templates you found.
3. **Product cards:** show a heart on product cards? Which corner? On which grids: collections, search, recommendations, featured collection sections, and any search/filter app you found?
4. **Wishlist page link:** add a link to the wishlist page (Step 6) to the account menu, footer, or nowhere?
5. **Social proof** (optional): show "X people saved this" on product pages?

**Styling** 6. **Icon:** heart, bookmark, or the theme's own icon style? On the storefront the icon comes from the app setting `icon.type` (`HEARTH`, `BOOKMARK` or `CUSTOM`; Fish admin → Settings → Appearance), and the header custom element uses whatever SVG you put in it. 7. **Product page button look:** icon only (recommended), or icon with a label such as "Add to wishlist"? Match the theme's secondary/outline button (recommended), primary button, or a plain icon with no button frame? 8. **Card icon look:** plain icon, or icon on a small round background so it shows on any product photo? 9. **Wishlist drawer:** "Inset drawer" or "Liquid glass modal"? Match the theme's colours and corner radius, or keep Fish's defaults? These are the Wishlist Drawer 2.0 embed settings (`presentation`, `panel_radius`, `card_radius`, `button_radius`, colours...).

**Functionality** (app settings: change them with `update_settings` over MCP, or tell the user where to find them in Fish admin → Settings) 10. **Guest wishlists:** can shoppers who aren't logged in save items, or only logged-in customers? (`wishlists.limitToLoggedInCustomers`) 11. **Multiple wishlists:** one wishlist per customer, or up to 10 named lists? (`wishlists.maxPerCustomer`: `"1"` or `"10"`. With multiple lists, adding always opens the drawer so the shopper can pick a list.) 12. **After adding an item** (single list only): open the drawer, show a toast, play an animation, or do nothing? (`appearance.atwAction`: `OPEN_DRAWER`, `TOAST`, `ANIMATION`, `NO_ACTION`) 13. **Adding to cart from the wishlist:** should the theme's cart drawer open afterwards, or only the cart count update? (Step 7) 14. **Classic drawer** (only if the classic `wishlist` embed is on): keep it, or switch to Wishlist Drawer 2.0? Switching changes how the drawer looks, so confirm. 15. **Theme and publishing:** which theme should you work on (confirm it isn't the live one), and should you push your changes to it or leave them local for the user to review?

**Confirm the plan.** When the user has answered, write the plan back as a short checklist: each change, the file or setting it touches, and what the user still has to do by hand. Wait for the user to approve it before starting Step 2. If the user changes their mind later, update the checklist and confirm again before continuing.

Steps 2 to 8 below explain *how* to make each change. The user's answers decide *where* things go and how they look. Where an answer differs from a default in these steps, follow the answer.

## Troubleshooting

| Symptom                                                | Likely cause                                                                                                                          |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| Nothing Fish-related renders                           | Embed not enabled on *this* theme, or you're previewing a different theme than the one you edited                                     |
| Two drawers / duplicate buttons                        | Both `wishlist` and `wishlist-v2` embeds are on. Disable one                                                                          |
| Buttons render but are hidden for everyone             | The store hit the Free plan's customer limit, or wishlists are limited to B2B customers in the app settings                           |
| PDP button stuck on the first variant                  | Theme fires none of the variant events above. Add the `updateAfterVariantChange` call                                                 |
| PDP button saves the wrong variant                     | `data-variant-id` holds only one ID. It must list every variant ID; the selected one goes in `data-preselected-id`                    |
| Count badge in a different spot from the cart badge    | Fish's default `left`/`top`/`transform` still apply, or the wrapper differs from the cart link's. See the count badge steps in Step 3 |
| Line property `_fish_wishlist` shows in the cart       | The theme prints every line property. Skip properties starting with `_` in the cart template, as most themes do                       |
| Card button opens the product page                     | It sits under the card's link overlay. Raise its `z-index` or move it inside the overlay's stacking context                           |
| `Fish Wishlist Error: Incorrect variant id` in console | `data-variant-id` is empty. Wrong product variable in the card snippet                                                                |
| App block missing from theme editor "Apps" list        | That section doesn't accept `@app` blocks. Use the custom element instead                                                             |

Still stuck? Email **<fish@nativeappco.com>** with the store URL, theme name and what you changed. The team can apply theme-specific fixes.
