@fluid-app/fluid-cli-theme-dev 0.1.63 → 0.1.64

package/dist/skills/themes-cart-feedback/SKILL.md

@@ -46,7 +46,7 @@ Everything here depends on exactly one `<script id="fluid-cdn-script">` with `da
 <script
   id="fluid-cdn-script"
   src="https://assets.fluid.app/scripts/fluid-sdk/latest/web-widgets/index.js"
-  data-fluid-shop="{{ shop.handle }}"
+  data-fluid-shop="{{ company.subdomain }}"
   defer
 ></script>
 ```
@@ -95,7 +95,7 @@ Add attributes to the same `<script id="fluid-cdn-script">` tag:
 <script
   id="fluid-cdn-script"
   src="https://assets.fluid.app/scripts/fluid-sdk/latest/web-widgets/index.js"
-  data-fluid-shop="{{ shop.handle }}"
+  data-fluid-shop="{{ company.subdomain }}"
   data-fluid-toast="true"
   data-fluid-toast-position="bottom-right"
   defer
@@ -147,7 +147,7 @@ In web-widgets 0.16.0 and later, any button carrying `data-fluid-add-to-cart` or
 ```liquid
 <button
   type="button"
-  data-fluid-add-to-cart="{{ product.first_variant.id }}"
+  data-fluid-add-to-cart="{{ product.selected_or_first_available_variant.id }}"
   data-fluid-loading-text="{{ 'product.adding' | t }}"
 >
   {{ 'product.add_to_cart' | t }}
@@ -292,29 +292,24 @@ window.addEventListener("CART_OPERATION_ERROR", (e) => {
 
 ### A. Live cart-count badge (product cards, shop grids, navbar)
 
-The single most common need. One listener updates the count wherever the shopper adds from — a product card, a collection grid, a quick-add. Put the badge markup where you want it and the listener once in the layout:
+The single most common need, and it needs no JavaScript. The SDK keeps the text of every element with `id="fluid-cart-count"` in sync with the cart — whenever the cart is created, refreshed, cleared, or its items change from anywhere on the page:
 
 ```html
-<span id="fluid-cart-count">{{ cart.item_count }}</span>
-
-<script>
-  window.addEventListener("CART_OPERATION_SUCCESS", () => {
-    const badge = document.getElementById("fluid-cart-count");
-    if (badge) badge.textContent = String(window.FairShareSDK?.getCartItemCount() ?? "0");
-  });
-</script>
+<span id="fluid-cart-count">0</span>
 ```
 
+Do not seed it with `{{ cart.item_count }}`: `cart` exists only in `cart_page` templates, so everywhere else it renders empty until the SDK fills it. To drive a different element, listen for the cart state events (`UPDATE_CART_ITEM`, `ADD_TO_CART`, `REMOVE_FROM_CART`) and read `window.FairShareSDK.getCartItemCount()`.
+
 ### B. Inline "Added ✓" on the exact card clicked (`variantIds` match)
 
 When a grid of product cards shares one listener, use `variantIds` to light up only the card the shopper acted on. Reveal a **separate** confirmation element rather than overwriting the button text — the button's own label is managed by `withButtonLoading`, so leave it alone:
 
 ```html
 {%- comment -%} Each card carries its variant id; a hidden confirmation sits alongside the button {%- endcomment -%}
-<div class="product-card" data-variant-id="{{ product.first_variant.id }}">
+<div class="product-card" data-variant-id="{{ product.selected_or_first_available_variant.id }}">
   <button
     type="button"
-    onclick="window.FairShareSDK?.withButtonLoading(this, () => window.FairShareSDK.addCartItems({{ product.first_variant.id }}, { quantity: 1 }))"
+    onclick="window.FairShareSDK?.withButtonLoading(this, () => window.FairShareSDK.addCartItems({{ product.selected_or_first_available_variant.id }}, { quantity: 1 }))"
   >
     {{ 'product.add_to_cart' | t }}
   </button>

package/dist/skills/themes-review/SKILL.md

@@ -35,7 +35,7 @@ Don't run end to end silently. **Once in a while — after finishing a section,
 
 ## Where themes actually live
 
-Themes are **separate Git repos**, one repo per theme. The reference starter is `git@github.com:fluid-commerce/base-theme.git`. They are not part of the fluid Rails monorepo and not part of fluid-mono — fluid-mono only ships the _tooling_ (CLI + validator) that operates on them.
+Themes are **separate Git repos**, one repo per theme. The reference starter is `git@github.com:fluid-commerce/base-theme.git`. They are not part of this monorepo — this monorepo only ships the _tooling_ (CLI + validator) that operates on them.
 
 A typical theme repo looks like this (verified against the `base-theme` starter cloned by `fluid theme init`):
 
@@ -152,28 +152,29 @@ If you feel the urge to nest, rename: `assets/icon-social-twitter.svg`, `compone
 
 Every layout file under `layouts/` **must emit both magic drops** for the engine to inject head content and page content:
 
-- `{{ content_for_header }}` — placed inside `<head>`. The engine injects meta tags, analytics, editor-mode scripts, asset preloads, and the FairShare runtime initialization here.
+- `{{ content_for_header }}` — placed inside `<head>`. The engine injects the page `<title>`, meta and Open Graph tags, canonical and `hreflang` links, structured data, the CSRF tag, Fluid's JavaScript globals (`window.fluid_shop`, …), theme stylesheets, and head Global Embeds here. It does **not** load the FairShare SDK — the layout or a Global Embed does.
 - `{{ content_for_layout }}` — placed where the page content goes (inside `<body>`, typically inside the main container). The selected page template renders into this slot.
 
 A layout missing either one is broken. Missing `content_for_header` breaks editor mode, analytics, and head-injected assets. Missing `content_for_layout` renders an empty page.
 
+Do not write your own `<title>` (or `og:*` tags): `content_for_header` already emits them, so a second one duplicates or overrides Fluid's. `page_title` is not a Fluid variable — it renders empty. Liquid comments are `{% comment %}…{% endcomment %}` or `{% # … %}`; Jinja-style `{# … #}` is printed as literal text.
+
 ```liquid
 <!doctype html>
-<html lang="{{ request.locale.iso_code }}">
+<html lang="{{ localization.language.iso_code | default: 'en' }}">
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <title>{{ page_title }}</title>
 
     {{ 'theme.css' | asset_url | stylesheet_tag }}
 
-    {{ content_for_header }}   {# ← required #}
+    {{ content_for_header }}
   </head>
   <body>
     {% section 'main_navbar' %}
 
     <main>
-      {{ content_for_layout }}  {# ← required #}
+      {{ content_for_layout }}
     </main>
 
     {% section 'main_footer' %}
@@ -267,7 +268,7 @@ The `fluid theme` command group is how a theme repo syncs with the Fluid API. Th
 
 | Tag       | Meaning                                                                                                                                   | Examples                                                                                                                                                                                      |
 | --------- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `blocker` | The validator would reject it on `fluid theme push`, OR it renders wrong / breaks a page / exposes user data. Must be fixed before merge. | Invalid `type:` value, missing `id`, duplicate `id`, missing `type:` on a block, settings shape is object not array, referenced section not on disk, unescaped user HTML, unclosed `{% if %}` |
+| `blocker` | The validator would reject it on `fluid theme push`, OR it renders wrong / breaks a page / exposes user data. Must be fixed before merge. | Invalid `type:` value, duplicate `id`, missing `id` (lint misses it, the editor can't save it), missing `type:` on a block, settings shape is object not array, referenced section not on disk, `escape` on a section/block `text`/`textarea` value, unclosed `{% if %}` |
 | `should`  | Works today but will hurt later: perf cliff, DRY violation, missing default, missing whitespace control in a hot loop.                    | `asset_url` inside a `for` loop, 3+ identical `{% render %}` snippets, multiple `product` settings playing the same role, missing `default:` on a user-facing setting                         |
 | `nit`     | Cosmetic, style, or low-impact. Leave one comment, do not block.                                                                          | Comment style, optional `default` on internal-only setting, naming nits                                                                                                                       |
 
@@ -288,8 +289,8 @@ Decision rule: if `fluid theme lint --json` would error on it, it's `blocker`. I
 
 For each entry in `"settings": [...]`:
 
-- `id` is required, non-empty, non-whitespace — **except** for `type: "header"` settings, which carry no `id` and use `content:` instead (the validator accepts them without one).
-- `id` must be unique across all settings in the same file (excluding `header` entries, which have no `id`).
+- `id`, when present, must be non-empty and non-whitespace. The validator does **not** flag a *missing* `id`, but a value-producing setting without one cannot be saved by the editor — treat it as a `blocker` yourself. `type: "header"` settings carry no `id` and use `content:` instead.
+- `id` must be unique across all settings in the same array.
 - `type` is required.
 - `type` must be one of the canonical types — see the [full list below](references/setting-types.md).
 
@@ -308,6 +309,10 @@ For each entry in `"blocks": [...]`:
 
 - Every `{% section 'name' %}` in a Liquid template must have a matching section file on disk. Missing sections produce errors.
 
+### Liquid block tags
+
+- Paired block tags (`if`/`endif`, `for`/`endfor`, `case`, `capture`, `unless`, …) must balance. The validator reports an unbalanced tag with its line. The server accepts the upload anyway, and the storefront stops rendering that file correctly, so treat it as a `blocker`.
+
 ### Template vs section block shape
 
 - **Section files** (`sections/{name}/index.liquid`): `blocks` is an **array** `[]`.
@@ -329,7 +334,7 @@ touches them. Read the matching file when you hit its topic:
 - **[Global settings](references/global-settings.md)** — typography/color/spacing tokens, dark mode, `config/settings_schema.json` + `theme.liquid` wiring.
 - **[Blocks vs. sections](references/blocks-vs-sections.md)** — when a setting belongs in a block; settings-panel ergonomics.
 - **[Liquid correctness](references/liquid-correctness.md)** — variable scope, balanced tags, whitespace control, typoed ids.
-- **[Editor attributes](references/editor-attributes.md)** — `section.fluid_attributes` / `block.fluid_attributes`.
+- **[Editor attributes](references/editor-attributes.md)** — `block.fluid_attributes` (sections are wrapped automatically).
 - **[FairShare attributes](references/fairshare-attributes.md)** — `data-fluid-*` cart / add-to-cart behavioral attributes + the CDN script.
 - **[Performance](references/performance.md)** — `asset_url` in loops, render hygiene.
 - **[Media rendering](references/media-tag.md)** — the `media_tag` filter for responsive, format-negotiated images and video; when raw `<img>`/`<video>` is wrong.
@@ -347,7 +352,7 @@ eyeballing the text.
 
 This is one of the most common smells.
 
-**If a section or block has two or more singular resource pickers playing the _same role_, collapse them to one `*_list` setting.**
+**If a section or block has two or more singular `product` pickers playing the _same role_, collapse them to one `product_list` setting.** For every other resource, collapse to **blocks** instead — see the table below.
 
 The test: would a user reasonably want N+1 items in the same role? If yes, it's a list. If the section needs _exactly one_ hero product _and separately_ one upsell product, those are two different roles — keep them singular.
 
@@ -395,18 +400,19 @@ The test: would a user reasonably want N+1 items in the same role? If yes, it's
 {%- endfor -%}
 ```
 
-### Same rule for every resource
+### Other resources: blocks, not lists
+
+`product_list` is the **only** list type Fluid resolves into objects. `collection_list`, `category_list`, `posts_list`, `enrollment_packs_list`, and the rest hand Liquid an array of **IDs**, so a loop that reads `item.title` or `item.url` renders nothing. Do not "fix" repeated singular pickers into those lists.
 
-| Singular smell                                          | List fix                                    |
-| ------------------------------------------------------- | ------------------------------------------- |
-| 2+ `product` (or `products`) settings, same role        | `product_list`                              |
-| 2+ `collection` settings, same role                     | `collection_list`                           |
-| 2+ `category` settings, same role                       | `category_list`                             |
-| 2+ `post` settings, same role                           | `posts_list`                                |
-| 2+ `enrollment` / `enrollment_pack` settings, same role | `enrollment_list` / `enrollment_packs_list` |
-| 2+ `blog` settings, same role                           | `blog_list`                                 |
+| Singular smell                                          | Fix                                                                                                    |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| 2+ `product` settings, same role                        | One `product_list` (resolved)                                                                          |
+| 2+ `collection` settings, same role                     | One block type with a single `collection` setting; the merchant adds a block per collection           |
+| 2+ `category` settings, same role                       | One block type with a single `category` setting                                                        |
+| 2+ `enrollment_pack` settings, same role                | One block type with a single `enrollment_pack` setting                                                 |
+| 2+ `post` / `blog` settings, same role                  | One block type with a single `post` setting (still an unresolved ID — look it up in `posts`)           |
 
-The benefit isn't just lines of code — a `*_list` setting lets the merchant **add or remove** items without a code change and drops the fixed per-slot count. It does **not** give per-item drag-and-drop reorder, though — that's a *blocks* feature. If the merchant needs to reorder items, model them as blocks instead.
+`product_list` lets the merchant **add or remove** products without a code change, but it does **not** give per-item drag-and-drop reorder — that's a *blocks* feature. If the merchant needs to reorder products, model them as blocks with a `product` setting instead.
 
 ---
 
@@ -539,7 +545,7 @@ For a fast first pass: `fluid theme lint --json` from the theme repo root.
 **Only after explicit approval** (`open the fix PR`, `yes do it`, `apply the fixes`):
 
 1. Branch from the PR's head (not main): `git checkout -b fix/<short-slug>`
-2. Apply ONE fix at a time, one commit per finding. Commit messages must follow Conventional Commits (this is the fluid-mono style and matches what most theme repos use):
+2. Apply ONE fix at a time, one commit per finding. Commit messages must follow Conventional Commits (this monorepo's style, and what most theme repos use):
 
 ```
 
@@ -621,15 +627,15 @@ When reviewing any theme file, run through this in order. Anything unchecked is
 - [ ] No user-visible literal text in markup (use `text`/`textarea`/`richtext`)
 - [ ] No hardcoded colors in styles (use `color` / `color_background` or a global token)
 - [ ] No hardcoded image URLs (use `image_picker` or upload to `assets/`)
-- [ ] Setting/resource images and videos render through `| media_tag` (not hand-rolled `<img>`/`<video>`)
+- [ ] Setting/resource images and videos render through `| media_tag` (not hand-rolled `<img>`/`<video>`); a `media_picker` with `fluid_media_id > 0` renders `<fluid-media-widget>` instead
 - [ ] No external CDN URLs for theme-owned assets
 - [ ] No hardcoded `href` to fixed paths the company might want to change (use `url`)
 
 **Global settings (config + layout)**
 
-- [ ] `config/settings_schema.json` defines `typography`, `color_schema`, and `spacing` groups (at minimum)
-- [ ] `layouts/theme.liquid` reads those settings and emits CSS variables on `:root`
-- [ ] Sections consume `var(--font-*)`, `var(--color-*)`, `var(--space-*)` rather than re-reading `settings.*` directly
+- [ ] `config/settings_schema.json` defines `typography` and `color_schema` groups, plus `padding` and `corner_radius` when sections use those controls — the editor builds presets only from these exact group names
+- [ ] `layouts/theme.liquid` reads those settings and emits a `--<setting_id>` CSS variable for each on `:root`
+- [ ] Sections consume those variables rather than re-reading `settings.*` directly
 - [ ] No section-level setting duplicates a global token (per-section overrides are the exception, default `unset`)
 - [ ] Schema is grouped by `name:` (not a flat array)
 - [ ] If dark mode is in schema, it's wired in `theme.liquid` (`@media (prefers-color-scheme: dark)` or `[data-theme="dark"]`)
@@ -644,13 +650,13 @@ When reviewing any theme file, run through this in order. Anything unchecked is
 **Settings ergonomics**
 
 - [ ] Section settings panel under ~15 fields, OR repeated variations moved to blocks
-- [ ] No 2+ singular resource pickers playing the same role (collapse to `*_list`)
+- [ ] No 2+ singular `product` pickers playing the same role (collapse to `product_list`); other repeated resource pickers become blocks
 - [ ] No `X_1` / `X_2` / `X_3` parallel-named settings (use blocks)
-- [ ] No `*s_list` where the canonical `*_list` exists (e.g. `product_list`, not `products_list`)
+- [ ] No `products_list` / `products` where resolved products were meant (`product_list` is the only resolved list)
 
 **Dead code**
 
-- [ ] No section files with zero `{% section 'name' %}` references (after confirming editor metadata)
+- [ ] No section files with zero `{% section 'name' %}` references in a freshly pulled theme (editor-added sections are saved into page templates)
 - [ ] No component files with zero `{% render 'name' %}` references
 - [ ] No `{% schema %}` `blocks:` declaring a `type:` the template never handles
 - [ ] No `assets/` files with zero references in any `.liquid` or `.css` (greppable from the theme root)
@@ -661,7 +667,7 @@ When reviewing any theme file, run through this in order. Anything unchecked is
 - [ ] No identical `{% render %}` snippet appearing 3+ times
 - [ ] No `asset_url` inside a `for` loop
 - [ ] All `for`/`if` in markup context use `{%-` / `-%}` whitespace control
-- [ ] `{% if %}` / `{% endif %}` (and `for`/`case`/`capture`) tags balance
+- [ ] `{% if %}` / `{% endif %}` (and `for`/`case`/`capture`) tags balance — `fluid theme lint` reports any that don't
 
 **Variable scope**
 
@@ -683,9 +689,9 @@ When reviewing any theme file, run through this in order. Anything unchecked is
 - [ ] JS tags have `defer` (or a justification for not)
 - [ ] No dead assets under `assets/`
 
-**Editor attributes (`section.fluid_attributes` / `block.fluid_attributes`)**
+**Editor attributes (`block.fluid_attributes`)**
 
-- [ ] Every section file emits `{{ section.fluid_attributes }}` on its root wrapper element
+- [ ] Sections carry no editor attributes of their own — Fluid wraps each section with `data-fluid-section` automatically; `section.fluid_attributes` does not exist and renders empty
 - [ ] Every block iterated via `{% for block in section.blocks %}` carries `{{ block.fluid_attributes }}` on its own root element
 - [ ] No typos (`fluid_attribute`, `fluid_attr`, `fluidAttributes`)
 - [ ] No hand-rolled `data-fluid-section-*` attributes — always go through the helper
@@ -699,11 +705,11 @@ When reviewing any theme file, run through this in order. Anything unchecked is
 - [ ] `data-fluid-subscription-plan-id` carries a single integer (never comma-separated)
 - [ ] JSON-valued attributes (`bundled-items`, `bundle-selections`) are valid JSON with numeric IDs and quantities
 - [ ] Attributes live on `<button>` or `<a>` (not `<div>` without semantics)
-- [ ] Exactly one `<script id="fluid-cdn-script">` with `data-fluid-shop` set is loaded by the layout
+- [ ] Exactly one `<script id="fluid-cdn-script">` with `data-fluid-shop="{{ company.subdomain }}"` is loaded by the layout (or by a head Global Embed — not both)
 
 **Security & a11y**
 
-- [ ] User content escaped (`| escape`) unless it's a HTML-shaped type (`richtext`/`html`/`html_textarea`)
+- [ ] Plain strings escaped (`| escape`): `plaintext` settings, global `settings.*` of type `text` (a plain input in the Theme panel), and resource fields such as `product.title`. HTML-shaped section/block settings — `text`, `textarea`, `richtext`/`rich_text`, `html`/`html_textarea` — render raw and never sit inside an attribute
 - [ ] Images have `alt`; below-the-fold images have `loading="lazy"`
 - [ ] Clickable elements use `<button>` (action) or `<a href>` (nav) — never `<div>`
 

package/dist/skills/themes-review/references/blocks-vs-sections.md

@@ -103,9 +103,9 @@ Rendering:
 <div class="features features--cols-{{ section.settings.columns }}">
   {%- for block in section.blocks -%}
     <article class="feature" {{ block.fluid_attributes }}>
-      {{ block.settings.icon | media_tag: alt: block.settings.title }}
+      {{ block.settings.icon | media_tag: alt: block.settings.icon_alt }}
       <h3>{{ block.settings.title }}</h3>
-      <p>{{ block.settings.body }}</p>
+      <div>{{ block.settings.body }}</div>
     </article>
   {%- endfor -%}
 </div>

package/dist/skills/themes-review/references/dead-code.md

@@ -41,7 +41,7 @@ for d in sections/*/; do
 done
 ```
 
-**False-positive guard:** some sections are added dynamically by users through the editor — these don't appear in any `{% section %}` literal but are still live. Before recommending removal, check `config/sections/*.json` (per-section metadata) — if metadata exists, the section is registered with the editor and probably in use. Drop the severity to `nit` and frame it as "appears unused in templates — confirm before removing".
+**False-positive guard:** sections a merchant adds in the Page Editor are saved into the page template itself — as a `{% section 'name', id: "…" %}` tag plus an entry in that template's `{% schema %}` `"sections"` map — so they only show up in a theme you have pulled recently. Run `fluid theme pull` before the audit, and grep the page templates' schemas for `"type": "name"` as well. If you cannot pull, drop the severity to `nit` and frame it as "appears unused in templates on disk — confirm in the editor before removing".
 
 ### Components — unused
 

package/dist/skills/themes-review/references/dynamism.md

@@ -51,10 +51,16 @@ Every one of those values — background, padding, heading text, body text, imag
 
 ```liquid
 {%- assign s = section.settings -%}
-<section style="background:{{ s.bg_color }};padding:{{ s.section_pad }};">
+{%- assign pt = s.section_pad.top -%}
+{%- assign pb = s.section_pad.bottom -%}
+<section style="
+  background: {{ s.bg_color }};
+  padding-top: {% if pt contains 'var' %}{{ pt }}{% else %}{{ pt | default: 0 }}px{% endif %};
+  padding-bottom: {% if pb contains 'var' %}{{ pb }}{% else %}{{ pb | default: 0 }}px{% endif %};
+">
   <h2 style="color:{{ s.text_color }};">{{ s.heading | default: 'Our Bestsellers' }}</h2>
-  <p>{{ s.body }}</p>
-  {{ s.banner_image | media_tag: alt: s.heading }}
+  <div>{{ s.body }}</div>
+  {{ s.banner_image | media_tag: alt: s.banner_image_alt }}
   {%- if s.show_cta -%}
     <a href="{{ s.cta_url }}" class="btn">{{ s.cta_label }}</a>
   {%- endif -%}

package/dist/skills/themes-review/references/editor-attributes.md

@@ -5,16 +5,16 @@
 ## Contents
 
 - What `fluid_attributes` emits
-- The two drops
+- Sections are wrapped for you
 - Correct usage
 - Findings to surface
 - Examples from the reference theme
 - Quick audit
 
 
-Sections and blocks have a Liquid drop called `fluid_attributes` that emits the `data-fluid-section-*` attributes the visual editor uses to find, select, click-to-edit, and drag-to-reorder the element. **Without these attributes on the right element, the editor cannot interact with the content** — click handlers don't bind, inspector panels don't open, drag-and-drop is dead.
+Blocks have a Liquid value called `fluid_attributes` that emits the `data-fluid-section-*` attributes the visual editor uses to find, select, click-to-edit, and drag-to-reorder the block. **Without these attributes on the block's root element, the editor cannot interact with the block** — click handlers don't bind, inspector panels don't open, drag-and-drop is dead.
 
-> **Note:** Despite the `data-fluid-*` prefix, these are _editor_ attributes — not the same as the runtime [FairShare behavioral attributes](#fairshare-behavioral-attributes--data-fluid-) below (which wire up cart, checkout, enrollment behavior). Keep them straight: `section.fluid_attributes` / `block.fluid_attributes` are Liquid drops the _theme engine_ emits in editor mode; FairShare attributes are _hand-written_ HTML attributes that the FairShare runtime SDK reads.
+> **Note:** Despite the `data-fluid-*` prefix, these are _editor_ attributes — not the same as the runtime [FairShare behavioral attributes](fairshare-attributes.md) (which wire up cart, checkout, enrollment behavior). Keep them straight: `block.fluid_attributes` is emitted by the _theme engine_ in editor mode; FairShare attributes are _hand-written_ HTML attributes that the FairShare runtime SDK reads.
 
 These attributes are only populated in editor preview mode; in production rendering, the drops emit an empty string. So a missing call has zero visible effect at runtime — the bug only surfaces in the editor. That's why reviewers must catch it.
 
@@ -32,25 +32,26 @@ In editor mode, `{{ block.fluid_attributes }}` expands to the full set of `data-
 ></div>
 ```
 
-### The two drops
+### Sections are wrapped for you
 
-| Drop                             | Where it's available                                                                             | Where to emit it                                |
-| -------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
-| `{{ section.fluid_attributes }}` | Inside a section file (`sections/{name}/index.liquid`)                                           | On the **root** wrapper element of the section  |
-| `{{ block.fluid_attributes }}`   | Inside a `{% for block in section.blocks %}` loop, or when a block context is passed to a render | On the **root** wrapper element of _each_ block |
+Fluid renders every section inside a wrapper element carrying `data-fluid-section="<id>"` and `data-fluid-section-type="<name>"`, in every render, editor or not. **A section needs no editor attributes of its own.** `section.fluid_attributes` does not exist — `{{ section.fluid_attributes }}` renders an empty string, so adding it changes nothing.
 
-**These are the only two.** There is no `component.fluid_attributes`, no dropzone drop, no slot drop, no inline-editing helper. Components are pure partials — they don't have editor presence on their own; the section/block that _renders_ them carries the attributes.
+| Value                          | Where it's available                                                                                   | Where to emit it                                |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
+| `{{ block.fluid_attributes }}` | Inside a `{% for block in section.blocks %}` loop, a standalone block template, or a render that receives the block | On the **root** wrapper element of _each_ block |
+
+**This is the only one.** There is no `section.fluid_attributes`, `component.fluid_attributes`, dropzone drop, slot drop, or inline-editing helper. Components are pure partials — they don't have editor presence on their own; the block that _renders_ them carries the attributes.
 
 ### Correct usage
 
 ```liquid
-{%- comment -%} Section root: section's attributes on the outer wrapper {%- endcomment -%}
-<section class="featured-products" {{ section.fluid_attributes }}>
+{%- comment -%} Section root: no attributes needed — Fluid wraps the section {%- endcomment -%}
+<section class="featured-products">
   {%- for block in section.blocks -%}
     {%- case block.type -%}
       {%- when 'heading' -%}
         <h2 class="featured-products__heading" {{ block.fluid_attributes }}>
-          {{ block.settings.text | escape }}
+          {{ block.settings.text }}
         </h2>
 
       {%- when 'product_card' -%}
@@ -76,19 +77,19 @@ When a block's content is fully delegated to a component, the standard pattern i
 
 | You see                                                                                                                      | Severity                    | Fix                                                                                                                                                                                                                   |
 | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Section file has no `{{ section.fluid_attributes }}` anywhere                                                                | `blocker`                   | Add it to the outer wrapper element of the section. Editor cannot select the section without it.                                                                                                                      |
+| Section file emits `{{ section.fluid_attributes }}`                                                                          | `nit`                       | Remove it. It renders nothing; Fluid already wraps the section with `data-fluid-section`.                                                                                                                             |
 | Section uses `{% for block in section.blocks %}` and the block's root element has no `{{ block.fluid_attributes }}`          | `blocker`                   | Each block's outer element must carry its own `block.fluid_attributes`. Without it the editor can't click-to-edit individual blocks.                                                                                  |
-| Typo: `{{ section.fluid_attribute }}` (singular)                                                                             | `blocker`                   | The drop name is `fluid_attributes` (plural). The singular form renders empty.                                                                                                                                        |
-| Typo: `{{ block.fluid_attr }}` / `{{ section.fluidAttributes }}` / `{{ section.fluid_attribute_set }}`                       | `blocker`                   | Only `fluid_attributes` exists.                                                                                                                                                                                       |
-| Attributes applied on a child element instead of the root                                                                    | `blocker`                   | Move to the outermost element of the section/block. The editor walks ancestors looking for the closest match; placing it on a child means the editor picks up _that_ element as the section bounds, not the real one. |
-| Same `{{ section.fluid_attributes }}` applied to multiple elements                                                           | `should`                    | Apply it once — to the root. Duplicates render the same `data-*` attributes twice in the DOM.                                                                                                                         |
-| Hardcoded `data-fluid-*` attributes (`data-section-id="{{ section.id }}"`) instead of the helper                             | `blocker`                   | Replace with `{{ section.fluid_attributes }}` / `{{ block.fluid_attributes }}`. The helper emits a full attribute set; hand-rolling drops most of them.                                                               |
+| Typo: `{{ block.fluid_attribute }}` (singular)                                                                               | `blocker`                   | The name is `fluid_attributes` (plural). The singular form renders empty.                                                                                                                                             |
+| Typo: `{{ block.fluid_attr }}` / `{{ block.fluidAttributes }}` / `{{ block.fluid_attribute_set }}`                           | `blocker`                   | Only `fluid_attributes` exists.                                                                                                                                                                                       |
+| Attributes applied on a child element instead of the block's root                                                            | `blocker`                   | Move to the outermost element of the block. The editor walks ancestors looking for the closest match; placing it on a child means the editor picks up _that_ element as the block bounds, not the real one.           |
+| Same `{{ block.fluid_attributes }}` applied to multiple elements                                                             | `should`                    | Apply it once — to the root. Duplicates render the same `data-*` attributes twice in the DOM.                                                                                                                         |
+| Hardcoded editor attributes (`data-fluid-section-block-id`, `data-fluid-section="{{ section.id }}"`) instead of the helper   | `blocker`                   | Remove them. Use `{{ block.fluid_attributes }}` for blocks; sections are wrapped automatically. Hand-rolling drops most of the set.                                                                                   |
 | Block-aware component (renders inside `{% for block %}`) has no `attr` parameter to receive `block.fluid_attributes`         | `should`                    | Add an `attr` argument to the component's signature and apply it on the component's root element.                                                                                                                     |
-| Conditional render without protecting against `nil`: `<div {{ section.fluid_attributes }}>` where `section` may be undefined | `should` (rarely `blocker`) | Wrap: `{% if section %}{{ section.fluid_attributes }}{% endif %}`. Same for `block`. Only relevant where the value can legitimately be nil.                                                                           |
+| Conditional render without protecting against `nil`: `<div {{ header_block.fluid_attributes }}>` where the block may be absent | `should` (rarely `blocker`) | Wrap: `{% if header_block %}{{ header_block.fluid_attributes }}{% endif %}`. Only relevant where the value can legitimately be nil.                                                                                  |
 
 ### Examples from the reference theme
 
-Section root with attributes — `sections/main_product/index.liquid:49-51` in the reference fluid theme:
+Block root with attributes — `sections/main_product/index.liquid:49-51` in the reference fluid theme:
 
 ```liquid
 <div
@@ -133,10 +134,8 @@ Multiple blocks each carrying their own attrs — `sections/main_category/index.
 From the theme repo root:
 
 ```bash
-# Sections missing section.fluid_attributes entirely
-for f in sections/*/index.liquid; do
-  grep -q 'section\.fluid_attributes' "$f" || echo "MISSING section.fluid_attributes  $f"
-done
+# Leftover section.fluid_attributes (renders nothing; remove)
+grep -rn 'section\.fluid_attributes' sections/
 
 # Sections that iterate blocks but never emit block.fluid_attributes
 for f in sections/*/index.liquid; do
@@ -150,8 +149,8 @@ done
 # Common typos
 grep -rE 'fluid_attribute[^s]|fluidAttributes|fluid_attribute_set' sections/ components/
 
-# Hardcoded data-fluid-* attributes (likely should use the helper)
-grep -rE 'data-fluid-section-id|data-fluid-section-block-id|data-fluid-parent-section-type' sections/ components/ \
+# Hardcoded editor attributes (likely should use the helper)
+grep -rE 'data-fluid-section=|data-fluid-section-id|data-fluid-section-block-id|data-fluid-parent-section-type' sections/ components/ \
   | grep -v 'fluid_attributes'
 ```
 

package/dist/skills/themes-review/references/examples.md

@@ -47,16 +47,15 @@
 ```
 ## Theme review — featured_products.liquid
 
-**8 findings** — 3 blocker, 4 should, 1 nit
+**7 findings** — 2 blocker, 4 should, 1 nit
 
 Reproduce locally with `fluid theme lint --json`.
 
 | Severity | Line | Finding |
 |---|---|---|
 | blocker | 9  | Invalid type `text_area` — use `textarea`. Validator rejects. |
-| blocker | 16 | Missing `{{ section.fluid_attributes }}` on the section root — editor cannot select or click-to-edit this section. Replace `<section>` with `<section {{ section.fluid_attributes }}>`. |
-| blocker | 18 | `{% for product in products %}` — `products` is undefined in this scope. It is not a global drop, and the schema declares no `products` setting. Loop silently iterates `nil`. Collapse to the `product_list` fix below (`section.settings.products`) or remove. |
-| should  | 10 | Type `image` is valid but `image_picker` is clearer for new code |
+| blocker | 18 | `{% for product in products %}` — `products` is Fluid's global product collection, not the products picked in this section, so the loop renders the store's catalog above the picked cards. Remove it; render the picked products through the `product_list` fix below (`section.settings.products`). |
+| should  | 10 | Type `image` works in sections only (blocks reject it) — use `image_picker` |
 | should  | 5-8 | Four `product` settings, same role — collapse to one `product_list` with `limit: 4` |
 | should  | 19 | `asset_url` resolved inside loop — hoist above |
 | should  | 16-21 | Missing whitespace control on `{% for %}` / `{% endfor %}` |

package/dist/skills/themes-review/references/fairshare-attributes.md

@@ -17,7 +17,7 @@ These are the **runtime behavioral attributes** consumed by the FairShare web-wi
 
 > These attributes **trigger** cart mutations. The **result** — confirming the change with a toast, spinning the button, or reacting in custom UI via the `CART_OPERATION_SUCCESS` / `CART_OPERATION_ERROR` events — is the `themes-cart-feedback` skill (installed as a sibling: [`../../themes-cart-feedback/SKILL.md`](../../themes-cart-feedback/SKILL.md), when present). Reach for it when reviewing product cards, shop grids, cart sections, or enrollment flows that add to cart.
 
-**This is different from `section.fluid_attributes` above.** The editor attributes are emitted by Liquid drops in editor mode. These are static HTML attributes you write into the template that the runtime SDK scans for on `DOMContentLoaded`.
+**This is different from `block.fluid_attributes`** (see [Editor attributes](editor-attributes.md)). The editor attributes are emitted by the theme engine in editor mode. These are static HTML attributes you write into the template that the runtime SDK scans for on `DOMContentLoaded`.
 
 ### Naming convention
 
@@ -29,12 +29,12 @@ All FairShare runtime attributes are `data-fluid-*` (kebab-case, `data-` prefix)
 <script
   id="fluid-cdn-script"
   src="https://assets.fluid.app/scripts/fluid-sdk/latest/web-widgets/index.js"
-  data-fluid-shop="{{ shop.handle }}"
+  data-fluid-shop="{{ company.subdomain }}"
   defer
 ></script>
 ```
 
-`data-fluid-shop` is required. Optional script-level attributes: `data-fluid-api-base-url`, `data-fluid-country` (2-letter ISO), `data-fluid-language` (2–3 letter), `data-fluid-rep-id`, `data-share-guid`, `data-debug`.
+`data-fluid-shop` is required — use `{{ company.subdomain }}`. There is no `shop` global in Fluid, so `{{ shop.handle }}` (a Shopify habit) renders an empty value and the SDK cannot resolve the store. `content_for_header` sets `window.fluid_shop` but does **not** load the SDK: add this tag to the layout once, unless the company already injects it as a head Global Embed — never both. Optional script-level attributes: `data-fluid-api-base-url`, `data-fluid-country` (2-letter ISO), `data-fluid-language` (2–3 letter), `data-fluid-rep-id`, `data-share-guid`, `data-debug`.
 
 ### The attributes
 
@@ -55,10 +55,10 @@ All FairShare runtime attributes are `data-fluid-*` (kebab-case, `data-` prefix)
 
 ```html
 {%- comment -%} Open cart drawer {%- endcomment -%}
-<button data-fluid-cart="open">Cart ({{ cart.item_count }})</button>
+<button data-fluid-cart="open">Cart</button>
 
 {%- comment -%} Add one item {%- endcomment -%}
-<button data-fluid-add-to-cart="{{ product.first_variant.id }}">
+<button data-fluid-add-to-cart="{{ product.selected_or_first_available_variant.id }}">
   Add to cart
 </button>