@orderlyshop/web-components 0.1.0-build.7068 → 0.1.0-build.7075

package/AGENTS.md

@@ -13,7 +13,8 @@ Use this package as a headless storefront component library. Prefer native custo
 
 - Read `README.md`, `DESIGN.md`, `docs/shop-best-practices.md`, `docs/components/README.md`, then `custom-elements.json` or `html-custom-data.json` before shop-specific edits. Read `docs/components/product-rail.md` and `docs/components/product-grid.md` before product listing work.
 - Use `docs/shop-best-practices.md` as the completion checklist for branded shop work. A finished shop must not look like the default scaffold with minor token changes.
-- For new shops, run `npx orderly-init-shop` first. Ask for the Orderly account id and a reference website URL; if no reference exists, ask for a short style description.
+- For new shops, run `npx orderly-init-shop` first. Ask for the Orderly account id, legal webshop owner name, legal owner CVR, and a reference website URL; if no reference exists, ask for a short style description.
+- Set `defaultShop.legalOwnerName` and `defaultShop.legalOwnerCvr`. `orderly-page-layout` renders the required ownership notice after footer content, and shop templates must not replace it.
 - Use the account id for tenant-scoped `src/shop-query.ts`. Use the reference, catalog inspection, and online research as design direction for `src/style.css`; never copy proprietary assets, text, logos, or brand marks without user confirmation.
 - Build the first version around catalog-driven content: homepage sections, category introductions, product context, useful navigation, and a visual system based on `DESIGN.md` tokens plus scoped CSS.
 - Aim for current premium frontend craft: responsive art direction, strong imagery, clear interaction states, appropriate motion, performance, and accessibility.
@@ -23,6 +24,7 @@ Use this package as a headless storefront component library. Prefer native custo
 
 - Use `configureShop({ defaultShop: { defaultQuery } })` for shop-wide query scope. `defaultQuery` is a full Core `SearchQuery`.
 - Do not create package-specific account id shortcuts. Tenant scoping is just `SearchQuery.SourceAccountId`.
+- Read `docs/search-syntax.md` before writing category or rail queries. Whitespace in `SearchQuery.Query` is narrowing; use `|` for OR alternatives such as `lego | matchbox | playmobil`. Multiple `SearchQuery.Tags` are narrowing AND-style filters, not broad alternatives.
 - For simple markup-driven searches, use declarative query attributes:
   - `keywords` maps to `SearchQuery.Query`.
   - `tags` maps to `SearchQuery.Tags`.
@@ -51,14 +53,14 @@ Use this package as a headless storefront component library. Prefer native custo
 - Product images should default to `fit="contain"`, white background, and square aspect ratio in product tiles.
 - Use `orderly-stored-image` for package/product images when possible and set the appropriate `image-role` (`product-tile`, `product-detail`, `thumbnail`, `basket-line`, `checkout-line`, or `fullsize`) so image URLs reuse configured CDN dimensions.
 - Product grids should support continuation-token based dynamic paging without requiring a visible load-more button.
-- Use `orderly-home-page` for default storefront homepages instead of generating product rails in app code. Set `basket-mode="inline-desktop"` when the design needs a package-owned desktop basket rail instead of custom portal glue.
+- Use `orderly-home-page` for default storefront homepages instead of generating product rails in app code. Use its `hero` slot/template for a custom homepage hero before replacing the full layout. Set `basket-mode="inline-desktop"` when the design needs a package-owned desktop basket rail instead of custom portal glue.
 - Use `orderly-category-page` for category routes. Default category links should use `/categories/<category-path>/` so builds can generate and hydrate server-rendered category pages. Use `/category.html#id=<encoded-category-path-or-slug>` only for shops that explicitly opt into hash routing. Prefer navigation `heroImage`, `heroLayout: "covers"`, `heroCoverCount`, and category `description` before replacing the category hero template.
 - Keep `orderly-navigation` sticky by default. Use `sticky="false"` only when a shop intentionally wants navigation to scroll away. Use `persist-state state-key="main-menu"` for vertical desktop menus that should remember open branches, and use `slot="menu-before"`/`slot="menu-after"` for store finder, campaign, volunteer, or other menu promo links.
 - Use package-owned basket and checkout surfaces first: `<orderly-basket-icon href="/checkout.html" placement="mobile-fixed" hide-when-empty>`, `basket-mode="inline-desktop"`, and `orderly-checkout-page`.
 - Use `orderly-product-detail-page` for full product routes. Set `share-url` to the product `SearchObject.ShareURL.URL`; the component loads the product through `SearchQuery.ShareUrl`.
-- Keep category page generation in the normal shop build. Use `orderly-build-category-pages` without `--no-hydrate` so homepage/category pages get initial HTML for SEO and less visible loading shift. Pass `--base-url` or set `VITE_ORDERLY_BASE_URL` to override the default `https://service.orderly.shop` snapshot backend.
+- Keep category page generation in the normal shop build. Use `orderly-build-category-pages` without `--no-hydrate` so homepage/category pages get initial HTML for SEO and less visible loading shift. Pass `--base-url` or set `VITE_ORDERLY_BASE_URL` to override the default `https://service.orderly.shop` snapshot backend. Treat warnings about category pages or homepage rails matching 0 products as blockers; use `--strict-empty-categories` in CI when empty categories should fail the build.
 - For real product URLs on traditional hosting, use the package-owned helpers in `server/`: Apache `.htaccess`, Nginx rewrite config, PHP product renderer, and optional Node product snapshot endpoint. Do not copy this logic into example-shop.
-- Use `navigation.ts` for category/navigation structure. Run `npx orderly-init-navigation --suggest --account-id <account-id>` when sampling helps, then export `navigationDefinitions: NavigationDefinition[]` with stable unique slugs, at most two levels, optional hero/content fields, and plain `SearchQueryInput` values such as `query: { query: "sko sneakers", tags: ["sko"] }`.
+- Use `navigation.ts` for category/navigation structure. Run `npx orderly-init-navigation --suggest --account-id <account-id>` when sampling helps, then read `querySyntax` and `navigationSuggestions` in `navigation-products.json` before exporting `navigationDefinitions: NavigationDefinition[]` with stable unique slugs, at most two levels, optional hero/content fields, and plain `SearchQueryInput` values such as `query: { query: "sko | sneakers" }` or `query: { query: "kjole | sommerkjole", tags: ["dametøj"] }`.
 
 ## Common Patterns
 
@@ -69,8 +71,8 @@ Declarative product rail:
   title="Sko"
   cta-label="Se alle"
   cta-href="/categories/sko/"
-  keywords="H&M"
-  tags="børnetøj,bluser">
+  keywords="sneakers | støvler | sandaler"
+  tags="sko">
 </orderly-product-rail>
 ```
 
@@ -79,8 +81,8 @@ Structured query markup:
 ```html
 <orderly-product-rail title="Sko">
   <query>
-    <tags>børnetøj,bluser</tags>
-    <keywords>H&M</keywords>
+    <tags>sko</tags>
+    <keywords>sneakers | støvler | sandaler</keywords>
     <order-by>CreatedTime desc</order-by>
   </query>
 </orderly-product-rail>
@@ -93,7 +95,7 @@ import { create } from "@bufbuild/protobuf";
 import { SearchQuerySchema } from "@orderlyshop/core-client";
 
 productRail.query = create(SearchQuerySchema, {
-  Query: "H&M",
+  Query: "sneakers | støvler | sandaler",
   OrderBy: ["CreatedTime desc"]
 });
 ```
@@ -108,7 +110,7 @@ Standalone browser setup:
     uiLanguage: "DA",
     defaultShop: {
       navigationDefinitions: [
-        { label: "Sko", slug: "sko", query: { query: "sko sneakers" } }
+        { label: "Sko", slug: "sko", query: { query: "sko | sneakers" } }
       ]
     }
   });

package/DESIGN.md

@@ -0,0 +1,224 @@
+# Design Contract
+
+This file is the source of truth for theming `@orderlyshop/web-components`.
+
+If a shop, coding agent, or LLM needs to restyle the package, start here before touching component selectors.
+
+## Rules For Agents And LLMs
+
+1. Keep design work outcome-first: produce a coherent shop theme with the smallest token and selector changes that satisfy the requested visual behavior.
+2. Set semantic design tokens first. Override them on `:root`, `html`, `body`, `orderly-page-layout`, or another shop shell element.
+3. Do not start by hunting through `.orderly-*` selectors. Component selectors are for deliberate exceptions, not for the base theme.
+4. Treat `--orderly-color-accent` and `--orderly-color-accent-soft` as legacy compatibility aliases. New themes should set `--orderly-color-primary`, `--orderly-color-primary-soft`, and `--orderly-color-primary-contrast`.
+5. If a color change should apply to buttons, badges, selection states, navigation hovers, and CTA links, change the semantic tokens below instead of patching each component separately.
+6. If shape changes should apply to tiles, panels, inputs, buttons, and icon buttons, change the radius tokens below instead of hardcoding `border-radius` on component selectors.
+7. Use component-specific selectors only when the token system cannot express the requested exception. Keep that exception scoped to the component and avoid redesigning unrelated surfaces.
+
+Package defaults are intentionally declared with `:where(:root)` so they have zero selector specificity. A shop-level `:root { --orderly-color-primary: ... }` is therefore authoritative even if the package CSS is injected later by `defineOrderlyWebComponents()`. Do not repeat token overrides on `body` just to win the cascade; use `body` or a shell element only when you deliberately want a narrower theme scope.
+
+## Reference Website Workflow
+
+When an agent or LLM builds a new shop, ask for a reference website URL before choosing the visual style. Inspect the reference for reusable design direction:
+
+- foundation palette and contrast
+- action, badge, link, and selection colors
+- shape language and radius scale
+- spacing density and page rhythm
+- header, navigation, card, product tile, and checkout surface patterns
+
+Translate those observations into this package's semantic tokens and the shop stylesheet. Keep the result recognizably aligned with the reference, but do not copy proprietary assets, copy, logos, or brand marks unless the user explicitly confirms they own or may use them.
+
+## Token Layers
+
+### Foundation Tokens
+
+Use these for the base palette:
+
+- `--orderly-color-primary`
+- `--orderly-color-primary-soft`
+- `--orderly-color-primary-contrast`
+- `--orderly-color-text`
+- `--orderly-color-muted`
+- `--orderly-color-border`
+- `--orderly-color-surface`
+- `--orderly-color-surface-muted`
+- `--orderly-color-page`
+- `--orderly-color-danger`
+
+`--orderly-color-accent` and `--orderly-color-accent-soft` still exist, but they now default to the primary tokens and should not be the first place new themes start.
+
+### Semantic Interaction Tokens
+
+Use these when the shop wants a coherent interactive theme:
+
+- `--orderly-link-accent-color`
+- `--orderly-selection-border`
+- `--orderly-selection-background`
+- `--orderly-badge-background`
+- `--orderly-badge-color`
+- `--orderly-action-primary-background`
+- `--orderly-action-primary-border`
+- `--orderly-action-primary-color`
+- `--orderly-action-primary-hover-background`
+- `--orderly-action-primary-hover-border`
+- `--orderly-action-primary-hover-color`
+- `--orderly-action-primary-hover-shadow`
+- `--orderly-action-secondary-background`
+- `--orderly-action-secondary-border`
+- `--orderly-action-secondary-color`
+- `--orderly-action-secondary-hover-background`
+- `--orderly-action-secondary-hover-border`
+- `--orderly-action-secondary-hover-color`
+- `--orderly-action-secondary-hover-shadow`
+- `--orderly-focus-ring`
+- `--orderly-focus-outline`
+
+These tokens drive the default styles for:
+
+- primary actions such as product tile add-to-basket, product page add-to-basket, checkout submit, and basket checkout
+- secondary actions such as close buttons, expand buttons, and outlined remove/toggle actions
+- navigation hover states, inline CTA links, hero eyebrows, and footer links
+- basket count badges and other count/status pills
+- selected thumbnails, selected checkout options, and form/radio focus states
+
+### Radius Tokens
+
+Use the radius scale to define the shop's shape language:
+
+- `--orderly-radius-none`
+- `--orderly-radius-xs`
+- `--orderly-radius-sm`
+- `--orderly-radius-md`
+- `--orderly-radius-lg`
+- `--orderly-radius-pill`
+
+Use semantic radius tokens for components. This keeps related UI aligned while still allowing smaller elements to use smaller radii than large panels:
+
+- `--orderly-radius-card`: product tiles, basket/order lines, checkout option cards, and other card-like rows
+- `--orderly-radius-panel`: checkout cards, payment/result cards, dialogs, empty states, and larger panels
+- `--orderly-radius-control`: default control radius foundation
+- `--orderly-radius-control-sm`: compact skeletons and small control details
+- `--orderly-radius-button`: primary and secondary buttons, CTA links, and add-to-basket controls
+- `--orderly-radius-icon-button`: square icon buttons such as search, basket, burger menu, and close controls
+- `--orderly-radius-input`: text inputs, selects, search inputs, and quantity controls
+- `--orderly-radius-image`: small image frames inside basket/order summaries
+- `--orderly-radius-indicator`: active navigation indicators and other pill indicators
+
+Compatibility aliases still exist:
+
+- `--orderly-radius` defaults to `--orderly-radius-sm`
+- `--orderly-icon-button-radius` defaults to `--orderly-radius-icon-button`
+
+### Layout Tokens
+
+These are not color tokens, but they are part of the default design contract and should be preferred over ad hoc layout overrides:
+
+- `--orderly-content-max-width`
+- `--orderly-section-gap`
+- `--orderly-item-gap`
+- `--orderly-control-height`
+- `--orderly-icon-button-size`
+- `--orderly-product-grid-gap`
+- `--orderly-product-grid-item-min-width`
+- `--orderly-product-tile-border`
+- `--orderly-product-tile-radius`
+- `--orderly-product-tile-background`
+- `--orderly-product-tile-shadow`
+- `--orderly-product-tile-hover-border-color`
+- `--orderly-product-tile-image-background`
+- `--orderly-product-tile-body-padding`
+- `--orderly-product-tile-title-color`
+- `--orderly-product-tile-title-font-weight`
+- `--orderly-product-tile-price-color`
+- `--orderly-product-price-color`
+- `--orderly-product-rail-header-padding`
+- `--orderly-product-rail-title-font-size`
+- `--orderly-product-rail-cta-color`
+- `--orderly-collection-hero-height`
+- `--orderly-collection-hero-background`
+- `--orderly-collection-hero-color`
+- `--orderly-collection-hero-image-opacity`
+- `--orderly-collection-hero-cover-shadow`
+- `--orderly-checkout-card-border`
+- `--orderly-checkout-card-radius`
+- `--orderly-checkout-card-background`
+- `--orderly-checkout-card-shadow`
+- `--orderly-checkout-option-border`
+- `--orderly-checkout-option-background`
+- `--orderly-checkout-option-selected-border`
+- `--orderly-checkout-option-selected-background`
+- `--orderly-checkout-option-selected-shadow`
+
+## Recommended Styling Workflow
+
+When building a new shop or retheming an existing one:
+
+1. Set the foundation palette.
+2. Set the semantic interaction tokens so buttons, badges, links, and selection states stay aligned.
+3. Set the radius scale and semantic radius tokens so tiles, checkout surfaces, buttons, inputs, and icon buttons share one shape system.
+4. Review the shop.
+5. Only then use component-specific hooks such as navigation or product-grid variables for intentional deviations.
+
+## Example: Green Theme
+
+```css
+:root {
+  --orderly-color-primary: #1f7a43;
+  --orderly-color-primary-soft: #e7f4eb;
+  --orderly-color-primary-contrast: #ffffff;
+
+  --orderly-link-accent-color: var(--orderly-color-primary);
+  --orderly-selection-border: var(--orderly-color-primary);
+  --orderly-selection-background: var(--orderly-color-primary-soft);
+  --orderly-badge-background: var(--orderly-color-primary);
+  --orderly-badge-color: var(--orderly-color-primary-contrast);
+
+  --orderly-action-primary-background: var(--orderly-color-primary);
+  --orderly-action-primary-border: var(--orderly-color-primary);
+  --orderly-action-primary-color: var(--orderly-color-primary-contrast);
+  --orderly-action-primary-hover-background: #166338;
+  --orderly-action-primary-hover-border: #166338;
+  --orderly-action-primary-hover-color: #ffffff;
+  --orderly-action-primary-hover-shadow: inset 0 -3px 0 rgba(0, 0, 0, 0.22);
+
+  --orderly-action-secondary-background: #ffffff;
+  --orderly-action-secondary-border: var(--orderly-color-primary);
+  --orderly-action-secondary-color: var(--orderly-color-primary);
+  --orderly-action-secondary-hover-background: #dff0e5;
+  --orderly-action-secondary-hover-border: var(--orderly-color-primary);
+  --orderly-action-secondary-hover-color: var(--orderly-color-primary);
+  --orderly-action-secondary-hover-shadow: inset 0 -3px 0 rgba(31, 122, 67, 0.14);
+
+  --orderly-focus-ring: 0 0 0 3px rgba(31, 122, 67, 0.24);
+  --orderly-focus-outline: 3px solid rgba(31, 122, 67, 0.34);
+
+  --orderly-radius-sm: 4px;
+  --orderly-radius-md: 10px;
+  --orderly-radius-lg: 14px;
+  --orderly-radius-card: var(--orderly-radius-md);
+  --orderly-radius-panel: var(--orderly-radius-lg);
+  --orderly-radius-control: var(--orderly-radius-md);
+  --orderly-radius-button: var(--orderly-radius-control);
+  --orderly-radius-icon-button: var(--orderly-radius-control);
+  --orderly-radius-input: var(--orderly-radius-control);
+  --orderly-radius-image: var(--orderly-radius-sm);
+}
+```
+
+That one block is enough to restyle color and shape consistently without editing component markup or package CSS.
+
+## Component-Specific Hooks
+
+Component-specific variables still exist and are useful, but they are a second step.
+
+Examples:
+
+- navigation active states: `--orderly-navigation-indicator-color`, `--orderly-navigation-link-active-background`, `--orderly-navigation-link-active-color`, `--orderly-navigation-link-padding`
+- product tile surfaces: `--orderly-product-tile-background`, `--orderly-product-tile-border`, `--orderly-product-tile-radius`, `--orderly-product-tile-shadow`, `--orderly-product-tile-image-background`
+- product rail headers: `--orderly-product-rail-header-padding`, `--orderly-product-rail-title-font-size`, `--orderly-product-rail-cta-color`
+- category hero covers: `--orderly-collection-hero-background`, `--orderly-collection-hero-color`, `--orderly-collection-hero-image-opacity`, `--orderly-collection-hero-cover-shadow`
+- checkout cards/options: `--orderly-checkout-card-*`, `--orderly-checkout-option-*`
+- product grid: `--orderly-product-grid-gap`, `--orderly-product-grid-item-min-width`
+- page layout: `--orderly-content-max-width`
+
+Use these only when a specific component should differ from the shared design system.

package/README.md

@@ -15,6 +15,8 @@ Inputs:
 - Project directory: ASK
 - Shop name: ASK
 - Orderly account id: ASK
+- Legal webshop owner name: ASK
+- Legal webshop owner CVR: ASK
 - Visual style reference: ASK
 - Deployment target: ASK
 - Google Tag Manager container id: NONE
@@ -26,8 +28,8 @@ Use any provided input above without asking again. Ask only for values that are
 
 Workflow:
 1. Install @orderlyshop/core-client and @orderlyshop/web-components if needed. Run npx orderly-init-shop for a new shop, pass --account-id when available, and preserve existing files unless I approve overwrite.
-2. Read node_modules/@orderlyshop/web-components/AGENTS.md, DESIGN.md, README.md, docs/components/README.md, and docs/shop-best-practices.md before changing shop files. Treat docs/shop-best-practices.md as a completion checklist, not optional inspiration.
-3. Scope the shop with the Orderly account id in src/shop-query.ts. When product sampling is possible, run npx orderly-init-navigation --suggest --account-id <account-id>, then build src/navigation.ts manually with stable unique slugs, at most two category levels, and plain SearchQueryInput objects.
+2. Read node_modules/@orderlyshop/web-components/AGENTS.md, DESIGN.md, README.md, docs/components/README.md, docs/search-syntax.md, and docs/shop-best-practices.md before changing shop files. Treat docs/shop-best-practices.md as a completion checklist, not optional inspiration.
+3. Scope the shop with the Orderly account id in src/shop-query.ts and set `defaultShop.legalOwnerName` plus `defaultShop.legalOwnerCvr` from the legal owner inputs. When product sampling is possible, run npx orderly-init-navigation --suggest --account-id <account-id>, read querySyntax and navigationSuggestions, then build src/navigation.ts manually with stable unique slugs, at most two category levels, and plain SearchQueryInput objects.
 4. Use package-owned components and configuration first: orderly-home-page, orderly-category-page, orderly-product-detail-page, orderly-checkout-page, configureShop(...), templates, generated Vite setup, generated category URLs, and package SSR helpers.
 5. Use the visual style reference as design direction, not as copy material. Start src/style.css from DESIGN.md semantic tokens, then add scoped component selectors only where tokens are insufficient.
 6. Do not ship the package default look and feel with minor color changes. Inspect the catalog, research the reference site and comparable modern shops, and create homepage/category/product context that is visually and editorially specific to this shop.
@@ -59,11 +61,11 @@ Agents and developers should use `npx orderly-init-shop` before hand-writing sho
 npx orderly-init-shop --account-id 00000000-0000-0000-0000-000000000000
 ```
 
-For agent-assisted shop creation, ask for both the Orderly account id and a reference website URL for visual style before customizing the scaffold. Use the account id for `src/shop-query.ts`, use the reference website and catalog research to shape `src/style.css`, and follow [`docs/shop-best-practices.md`](./docs/shop-best-practices.md) as the completion checklist. The first pass should already feel visually distinct, editorially useful, and technically polished; it should not look like the default package scaffold with small token changes.
+For agent-assisted shop creation, ask for the Orderly account id, legal webshop owner name, legal owner CVR, and a reference website URL for visual style before customizing the scaffold. Use the account id for `src/shop-query.ts`, use the legal owner values for `defaultShop.legalOwnerName` and `defaultShop.legalOwnerCvr`, use the reference website and catalog research to shape `src/style.css`, and follow [`docs/shop-best-practices.md`](./docs/shop-best-practices.md) as the completion checklist. The first pass should already feel visually distinct, editorially useful, and technically polished; it should not look like the default package scaffold with small token changes.
 
 Re-running `npx orderly-init-shop` in an existing shop is non-destructive by default. Existing scaffold files are left unchanged with warnings, while missing new scaffold files are added. Use `--force` only when you explicitly want scaffold files overwritten.
 
-The scaffold uses Vite for local development and static builds, but Vite is added to the generated shop's `devDependencies`. Dev mode SSR for product/category URLs is enabled by default, so View Source on local category/product URLs shows semantic server-rendered markup. Consumers should test locally from `http://localhost:61677` or `https://localhost:61677` because those are the expected local development origins for backend CORS. The generated Vite setup defaults to `http://localhost:61677`; if a local reverse proxy or TLS terminator is added, keep the same `localhost:61677` origin over HTTPS. `@orderlyshop/web-components` does not depend on Vite at runtime.
+The scaffold uses Vite for local development and static builds, but Vite is added to the generated shop's `devDependencies`. Dev mode SSR for product/category URLs is enabled by default, so View Source on local category/product URLs shows semantic server-rendered markup. Consumers should test locally from `http://localhost:61677` or `https://localhost:61677` because those are the expected local development origins for backend CORS. Do not switch to `127.0.0.1`, `0.0.0.0`, or a random Vite fallback port when debugging API calls; close the conflicting process and keep the origin on `localhost:61677`. The generated Vite setup defaults to `http://localhost:61677`; if a local reverse proxy or TLS terminator is added, keep the same `localhost:61677` origin over HTTPS. `@orderlyshop/web-components` does not depend on Vite at runtime.
 
 ## Browser Standalone Bundle
 
@@ -84,9 +86,9 @@ Use the configurable bundle when a vanilla HTML site needs to set shop options b
         {
           label: "Sko",
           slug: "sko",
-          query: { query: "sko sneakers" },
+          query: { query: "sko | sneakers" },
           children: [
-            { label: "Dame sko", slug: "dame-sko", query: { query: "dame sko sneakers" } }
+            { label: "Dame sko", slug: "dame-sko", query: { query: "damesko | sneakers" } }
           ]
         }
       ]
@@ -176,6 +178,7 @@ Developers and coding agents should start with these package-owned docs:
 - [`DESIGN.md`](./DESIGN.md) defines the package-wide design tokens and the recommended theming workflow for consistent styling across all components.
 - [`docs/components/README.md`](./docs/components/README.md) lists every custom element, common attributes, typed properties, events, and template hooks.
 - [`docs/shop-best-practices.md`](./docs/shop-best-practices.md) is the practical checklist for turning the package scaffold into a branded, editorial storefront without replacing package-owned component behavior.
+- [`docs/search-syntax.md`](./docs/search-syntax.md) explains `SearchQuery.Query`, `|` OR queries, tag narrowing, and the recommended category query workflow.
 - [`docs/components/product-grid.md`](./docs/components/product-grid.md) documents search loading, sorting, paging, default query merging, and declarative query markup.
 - [`docs/components/product-rail.md`](./docs/components/product-rail.md) documents homepage/category rails and their query configuration.
 - [`AGENTS.md`](./AGENTS.md) gives coding agents the conventions for building shops with this package.
@@ -201,12 +204,13 @@ The most important convention is that Core contracts use typed JavaScript proper
   title="Sko"
   cta-label="Se alle"
   cta-href="/categories/sko/"
-  keywords="H&M"
-  tags="børnetøj,bluser"
+  keywords="sneakers | støvler | sandaler"
   order-by="CreatedTime desc">
 </orderly-product-rail>
 ```
 
+`keywords` maps to `SearchQuery.Query`. Spaces narrow the text query; they are not OR. Use `|` for broad alternatives, for example `lego | matchbox | playmobil`. `tags="a,b"` maps to multiple `SearchQuery.Tags` and should be treated as an AND-style narrowing filter, not as category alternatives. For the full guidance, read [`docs/search-syntax.md`](./docs/search-syntax.md).
+
 ## Default Shop
 
 The package can render a working default storefront with the built-in backend, navigation, sorting, basket, product detail, and footer defaults:
@@ -246,6 +250,8 @@ The simplest setup needs no router block:
 configureShop({
   defaultShop: {
     homeHref: "/",
+    legalOwnerName: "Example Shop ApS",
+    legalOwnerCvr: "12345678",
     productHref: "/products/",
     productUrlMode: "path",
     productPathRoot: "/products/",
@@ -373,7 +379,7 @@ After installing from the repository workspace, run it with:
 npm run dev --workspace @orderlyshop/example-shop
 ```
 
-Open the local shop from `http://localhost:61677` during normal development, or `https://localhost:61677` when a local TLS proxy is in front of the dev server. Consumers should keep that exact localhost origin because the backend CORS development policy expects it.
+Open the local shop from `http://localhost:61677` during normal development, or `https://localhost:61677` when a local TLS proxy is in front of the dev server. Consumers should keep that exact localhost origin because the backend CORS development policy expects it. If live API requests work from one local URL but fail from another, use `localhost:61677` and stop any process that forced Vite onto a different port; avoid `127.0.0.1` for package shop development.
 
 Inside an installed package, inspect the same reference implementation at:
 
@@ -414,7 +420,7 @@ Agent workflow for a new shop:
 npx orderly-init-navigation --suggest --account-id <account-id>
 ```
 
-3. Create `navigation.ts` manually from `navigation-products.json`. Export `navigationDefinitions: NavigationDefinition[]`; each item needs `label`, a globally unique `slug`, optional hero/content fields, optional `children`, and plain `SearchQueryInput` values such as `{ query: "sko sneakers", tags: ["sko"] }`. Keep navigation to at most two category levels and avoid empty or tiny categories.
+3. Create `navigation.ts` manually from `navigation-products.json`. Read `querySyntax` and `navigationSuggestions` first. Export `navigationDefinitions: NavigationDefinition[]`; each item needs `label`, a globally unique `slug`, optional hero/content fields, optional `children`, and plain `SearchQueryInput` values such as `{ query: "sko | sneakers" }` or `{ query: "kjole | sommerkjole", tags: ["dametøj"] }`. Keep navigation to at most two category levels and avoid empty or tiny categories.
 4. Configure shop scope with a Core `SearchQuery` through `configureShop({ defaultShop: { defaultQuery } })`.
 5. Read and follow `docs/shop-best-practices.md`, translate the reference into `DESIGN.md` tokens plus scoped CSS, and add homepage/category content from catalog and research.
 6. Run the dev server when a browser is available and visually inspect homepage, category, product, basket, and checkout on desktop and mobile. Fix visible issues before reporting completion; visual QA is required for finished shop work.
@@ -477,7 +483,7 @@ Build with generated category pages and then clean the generated source files. S
 npx orderly-build-category-pages
 ```
 
-`orderly-build-category-pages` also hydrates the built `dist/index.html` and generated `dist/categories/**/index.html` pages with SEO-friendly fallback HTML. The hydration step embeds semantic product cards per category using `SearchService.Search`; it reads `--base-url`, `VITE_ORDERLY_BASE_URL`, or `ORDERLY_BASE_URL`, and otherwise uses the default `https://service.orderly.shop` backend. Live web components read the semantic fallback as initial visible state, hide the raw fallback markup, and then continue as normal client components. Product grids still run their first live `SearchService.Search()` after hydration when a client or backend URL is configured, so fallback products are replaced by current backend data and continuation-token paging starts from the live result set.
+`orderly-build-category-pages` also hydrates the built `dist/index.html` and generated `dist/categories/**/index.html` pages with SEO-friendly fallback HTML. The hydration step embeds semantic product cards per category using `SearchService.Search`; it reads `--base-url`, `VITE_ORDERLY_BASE_URL`, or `ORDERLY_BASE_URL`, and otherwise uses the default `https://service.orderly.shop` backend. It warns loudly when a category page or homepage rail query matches 0 products, because that almost always means `src/navigation.ts` needs a broader OR query or fewer tag filters. Live web components read the semantic fallback as initial visible state, hide the raw fallback markup, and then continue as normal client components. Product grids still run their first live `SearchService.Search()` after hydration when a client or backend URL is configured, so fallback products are replaced by current backend data and continuation-token paging starts from the live result set.
 
 Hydrate an already-built site manually, for example in a nightly job:
 
@@ -485,7 +491,7 @@ Hydrate an already-built site manually, for example in a nightly job:
 npx orderly-hydrate-static-pages --base-url https://service.orderly.shop --products-per-category 12
 ```
 
-Use `--skip-products` for metadata-only hydration, `--strict-products` when a nightly job should fail on backend search errors, and `--no-hydrate` on `orderly-build-category-pages` to keep the older unhydrated build behavior.
+Use `--skip-products` for metadata-only hydration, `--strict-products` when a nightly job should fail on backend search errors, `--strict-empty-categories` when CI should fail on empty category pages/homepage rails, and `--no-hydrate` on `orderly-build-category-pages` to keep the older unhydrated build behavior.
 
 The category generator expects `src/navigation.ts` or `src/navigation.js` to export `navigationDefinitions` and the template page to contain `<orderly-category-page></orderly-category-page>`. TypeScript navigation files use the current shop project's `typescript` dependency for one-off transpilation. Useful options include `--navigation`, `--template`, `--categories-dir`, `--site-title`, `--component-tag`, and `--export`. The older `--taxonomy` flag and `categoryDefinitions` export are still accepted as compatibility aliases.
 
@@ -693,8 +699,8 @@ For a fuller real-shop checklist, read [Shop Best Practices](./docs/shop-best-pr
 
 ## Components
 
-- `orderly-page-layout` provides reusable page regions for header, header actions, responsive primary navigation placement, left/right sidebars, content, footer, and overlay content. It includes a default logo image using `https://orderly.shop/home/App_Icon.svg`; override it with `logo-src`, `logo-alt`, and `logo-href`. Use `primary-nav-mobile-placement="header"` for the common mobile header burger pattern without a duplicate mobile layout template.
-- `orderly-home-page` composes page layout, responsive primary navigation, one product rail per top-level category, basket icon, basket drawer, optional inline desktop basket rail, product detail dialog, and footer. Configure it with `configureShop({ defaultShop })` plus attributes such as `title`, `eyebrow`, `rail-cta-label`, `product-href`, and `basket-mode="inline-desktop"`. The product dialog is fullscreen on mobile, keeps a bounded image column on desktop through `--orderly-product-dialog-image-size`, and pushes a same-URL history entry when opened, so browser back closes the overlay before leaving the homepage. The expand link follows the configured product URL mode, and compact `https://orderly.shop/...` product URLs are preserved when it builds hash or path routes.
+- `orderly-page-layout` provides reusable page regions for header, header actions, responsive primary navigation placement, left/right sidebars, content, footer, and overlay content. It includes a default logo image using `https://orderly.shop/home/App_Icon.svg`; override it with `logo-src`, `logo-alt`, and `logo-href`. It always appends the package-owned legal ownership notice after footer content using `defaultShop.legalOwnerName` and `defaultShop.legalOwnerCvr`; shop templates cannot replace that notice. Use `primary-nav-mobile-placement="header"` for the common mobile header burger pattern without a duplicate mobile layout template.
+- `orderly-home-page` composes page layout, responsive primary navigation, one product rail per top-level category, basket icon, basket drawer, optional inline desktop basket rail, product detail dialog, and footer. Configure it with `configureShop({ defaultShop })` plus attributes such as `title`, `eyebrow`, `rail-cta-label`, `product-href`, and `basket-mode="inline-desktop"`. Use the `hero` slot or `hero` template for a custom premium homepage hero while keeping package-owned rails, basket, product overlay, and generated URLs. The product dialog is fullscreen on mobile, keeps a bounded image column on desktop through `--orderly-product-dialog-image-size`, and pushes a same-URL history entry when opened, so browser back closes the overlay before leaving the homepage. The expand link follows the configured product URL mode, and compact `https://orderly.shop/...` product URLs are preserved when it builds hash or path routes.
 - `orderly-category-page` composes page layout, navigation, search, product grid, product detail, basket icon, and basket around a navigation category. Without properties it uses the package default shop configuration. Override with `configureShop({ defaultShop })` once per shop, set `base-url` or `product-href` in markup, or assign `category`, `navigationItems`, `sortOptions`, `client`, `defaultQuery`, and `basketController` from JavaScript for advanced cases. Configure `defaultShop.navigationLayout` or top-level `navigationLayout` to switch the package-owned category page from desktop side navigation to top horizontal category navigation while keeping the mobile burger in the header. Set `basket-mode="inline-desktop"` when the desktop category page should show a right basket rail only after the basket has lines. The product dialog is fullscreen on mobile, keeps a bounded image column on desktop through `--orderly-product-dialog-image-size`, and pushes a same-URL history entry when opened, so browser back closes the overlay before leaving the category. The expand link uses the configured product URL mode and still supports explicit per-page `product-href` overrides when a shop wants a different physical product page URL.
 - `orderly-checkout-page` composes page layout, responsive primary navigation, checkout form, basket order summary, footer, shared basket state, delivery loading, and order-created cleanup. Delivery methods render as radio cards after address entry, service points render as radio-card pickup choices when required, and delivery changes verify the draft so totals update. If a persisted draft already contains a complete address, delivery methods are restored on mount; if it also contains a delivery choice, the draft is verified so the basket summary can show backend shipping and total prices. Configure copy through `configureShop({ defaultShop: { checkoutPageTitle, checkoutPageDescription, checkoutOrderTitle, checkoutTermsHref, checkoutLabels, basketLabels } })`, or assign `client`, `basketController`, `navigationItems`, `checkoutLabels`, and `basketLabels` from JavaScript.
 - `orderly-product-detail-page` composes page layout, navigation, product detail, basket drawer, optional inline desktop basket rail, and footer for a product route. Set `share-url`, the `shareUrl` property, or pass `#url=<encoded-share-url>` in the page URL; compact Orderly slugs are restored to `https://orderly.shop/...` before it calls `SearchService.Search` with `SearchQuery.ShareUrl` and renders the resolved `SearchObject`. It forwards `details-before`, `purchase-note`, `secondary-cta`, and `details-after` slots to the nested product page. Set `basket-mode="inline-desktop"` when a product page should keep the basket visible as a desktop right rail after add-to-basket. Shops can tune outer gutters with `--orderly-product-detail-page-padding`, `--orderly-product-detail-page-mobile-padding`, `--orderly-product-detail-page-inline-padding`, and `--orderly-product-detail-page-mobile-inline-padding`.
@@ -707,7 +713,7 @@ For a fuller real-shop checklist, read [Shop Best Practices](./docs/shop-best-pr
 - `orderly-product-rail` accepts `query: SearchQuery`, title, CTA label, and CTA href, then renders the search as a horizontal scroll list by composing `orderly-product-grid`. It is useful for homepages and editorial rows where several category searches should be stacked vertically.
 - `orderly-collection-page` accepts `query: SearchQuery`, title, description, hero image, `hero-layout`, and `hero-cover-count`, then delegates fetching to `orderly-product-grid`. Use `hero-layout="covers"` to show product-cover previews from the loaded category products without custom category header HTML.
 - `orderly-shop-footer` renders configurable logo, about text, address, contact information, opening hours, and information links.
-- `orderly-basket-icon` and `orderly-basket` share a `BasketController` backed by `DraftOrder` persistence. Basket state events such as `orderly-basket-open`, `orderly-basket-change`, and `orderly-basket-verified` use the current `DraftOrder` directly as `event.detail`, so consumers can derive counts and totals from Core contracts instead of an internal basket data shape. `orderly-basket-icon` can also render a checkout/cart link with `href`, `placement="mobile-fixed"`, and `hide-when-empty` for a package-owned mobile button with count. `orderly-basket-checkout` includes `{ draft, count, href }` when the checkout action is triggered. `orderly-basket` renders an item overview, verifies non-empty persisted drafts on load plus later basket mutations through `OrderService.VerifyDraft` when a client or `base-url` is configured, includes a configurable checkout link through `checkout-href` and `checkout-label`, and only exposes quantity selection for lines where `MaxQuantity > 1`. Summary rows now render only backend-provided `DraftOrder` values, never local subtotal/total math, and the component renders both `DraftOrder.Errors` and `DraftOrderLine.Errors`. Custom basket templates can project order-level errors through `data-orderly-slot="errors"`.
+- `orderly-basket-icon` and `orderly-basket` share a `BasketController` backed by `DraftOrder` persistence. Basket state events such as `orderly-basket-open`, `orderly-basket-change`, and `orderly-basket-verified` use the current `DraftOrder` directly as `event.detail`, so consumers can derive counts and totals from Core contracts instead of an internal basket data shape. Product add/remove and in-basket UI state are matched only by `SearchObject.SKU.Value` and `DraftOrderLine.SKU.Value`; titles, barcodes, target ids, and share URLs are not basket identity. `orderly-basket-icon` can also render a checkout/cart link with `href`, `placement="mobile-fixed"`, and `hide-when-empty` for a package-owned mobile button with count. `orderly-basket-checkout` includes `{ draft, count, href }` when the checkout action is triggered. `orderly-basket` renders an item overview, verifies non-empty persisted drafts on load plus later basket mutations through `OrderService.VerifyDraft` when a client or `base-url` is configured, includes a configurable checkout link through `checkout-href` and `checkout-label`, and only exposes quantity selection for lines where `MaxQuantity > 1`. Summary rows now render only backend-provided `DraftOrder` values, never local subtotal/total math, and the component renders both `DraftOrder.Errors` and `DraftOrderLine.Errors`. Custom basket templates can project order-level errors through `data-orderly-slot="errors"`.
 - `orderly-checkout` persists checkout contact and address fields directly on `DraftOrder.Transport`, defaults the phone country picker to `+45`, validates email and phone values with built-in component logic, looks up Danish city names from the entered postal code through Dataforsyningen's `https://api.dataforsyningen.dk/postnumre/{postnr}` endpoint, loads delivery methods and service points, verifies the draft, and calls `OrderService.Create`. On mount it restores delivery methods for a persisted complete address and verifies a persisted delivery/service-point choice once, so shared basket summaries receive backend shipping and total prices without waiting for another address edit.
 - `orderly-navigation` uses `NavigationController` and can be subclassed with site-specific `NavigationItem[]`. It is sticky by default, including when placed in `left`, `right`, or `primary-nav`; set `sticky="false"` to opt out. Use `layout="vertical"` for disclosure side navigation, `layout="horizontal"` for the tiered desktop bar, or `layout="burgermenu"` for an icon trigger that expands into the same nested disclosure menu inside a floating panel. Use `layout-desktop="horizontal" layout-mobile="burgermenu"` with `orderly-page-layout primary-nav-mobile-placement="header"` for desktop horizontal nav plus inline mobile burger. Add `persist-state state-key="main-menu"` to remember expanded category branches across navigation, and use `slot="menu-before"`/`slot="menu-after"` for shop-owned links such as store finder, campaigns, or volunteer pages.
 - `orderly-search-box`, `orderly-sort-select`, `orderly-filter-panel`, and `orderly-load-more` bind to `orderly-product-grid`.
@@ -761,6 +767,7 @@ Use the package basket primitives before writing custom state glue:
 Basket count contract:
 
 - `BasketController.count` is derived from `DraftOrder.OrderLines[].Quantity`.
+- Product identity in the basket is `SKU.Value` only. Products that share titles, barcodes, target ids, or share URLs must still have distinct SKUs to avoid being treated as the same basket line.
 - `orderly-basket-icon`, `orderly-basket`, product tiles/grids/rails, product pages, and checkout should share the same `BasketController` instance.
 - `orderly-basket-change` and `orderly-basket-verified` expose the current `DraftOrder` as `event.detail`; custom UI can derive counts from that draft without copying package state.
 - Verified and persisted drafts still use the same `DraftOrder`; backend-provided prices and errors are rendered by `orderly-basket`.
@@ -778,7 +785,7 @@ When customizing checkout layout, do not override the package mobile collapse ac
 
 The package ships baseline default CSS and uses light DOM. Default markup uses stable `orderly-*` class names and CSS variables, so host CSS can style or replace the default look directly.
 
-For consistent theming across the whole package, start with the semantic design contract in [`DESIGN.md`](./DESIGN.md). In practice that means overriding `--orderly-color-primary`, `--orderly-color-primary-soft`, `--orderly-color-primary-contrast`, the `--orderly-action-primary-*` and `--orderly-action-secondary-*` tokens, plus shared tokens such as `--orderly-link-accent-color`, `--orderly-selection-*`, and `--orderly-badge-*`. `--orderly-color-accent` is kept as a compatibility alias, but new themes should treat `--orderly-color-primary` as the source of truth.
+For consistent theming across the whole package, start with the semantic design contract in [`DESIGN.md`](./DESIGN.md). In practice that means overriding `--orderly-color-primary`, `--orderly-color-primary-soft`, `--orderly-color-primary-contrast`, the `--orderly-action-primary-*` and `--orderly-action-secondary-*` tokens, plus shared tokens such as `--orderly-link-accent-color`, `--orderly-selection-*`, `--orderly-badge-*`, `--orderly-product-tile-*`, `--orderly-product-rail-*`, `--orderly-collection-hero-*`, and `--orderly-checkout-*`. `--orderly-color-accent` is kept as a compatibility alias, but new themes should treat `--orderly-color-primary` as the source of truth.
 
 The package declares its fallback tokens with `:where(:root)`, which has zero selector specificity. If your shop sets tokens on `:root`, those values win even when `defineOrderlyWebComponents()` injects the package CSS after your stylesheet. You should not need to duplicate token overrides on `body` unless you intentionally want a scoped override.
 
@@ -873,8 +880,8 @@ Simple product queries can be declared in markup on `orderly-product-grid`, `ord
   title="Sko"
   cta-label="Se alle"
   cta-href="/categories/sko/"
-  keywords="H&M"
-  tags="børnetøj,bluser"
+  keywords="sneakers | støvler | sandaler"
+  tags="sko"
   order-by="CreatedTime desc">
 </orderly-product-rail>
 ```
@@ -887,14 +894,14 @@ The same query can be grouped as child markup:
   cta-label="Se alle"
   cta-href="/categories/sko/">
   <query>
-    <tags>børnetøj,bluser</tags>
-    <keywords>H&M</keywords>
+    <tags>sko</tags>
+    <keywords>sneakers | støvler | sandaler</keywords>
     <order-by>CreatedTime desc</order-by>
   </query>
 </orderly-product-rail>
 ```
 
-Declarative query fields map to `SearchQuery.Query`, `SearchQuery.Tags`, `SearchQuery.HiddenQuery`, `SearchQuery.OrderBy`, `SearchQuery.StoreId`, and `SearchQuery.Featured`. For the full Core contract, assign the typed `query` property from JavaScript.
+Declarative query fields map to `SearchQuery.Query`, `SearchQuery.Tags`, `SearchQuery.HiddenQuery`, `SearchQuery.OrderBy`, `SearchQuery.StoreId`, and `SearchQuery.Featured`. Use `|` for OR text and avoid multiple tags for alternatives. For the full Core contract, assign the typed `query` property from JavaScript.
 
 Templates can be viewport-specific on every component:
 

package/bin/orderly-build-category-pages.mjs

@@ -120,7 +120,9 @@ function hydrateOnlyArgs() {
     "product-root",
     "image-base-url",
     "skip-products",
-    "strict-products"
+    "strict-products",
+    "strict-empty-categories",
+    "fail-empty-categories"
   ]);
 }
 

package/bin/orderly-hydrate-static-pages.mjs

@@ -43,6 +43,7 @@ const imageBaseUrl = args["image-base-url"] ?? process.env.VITE_ORDERLY_IMAGE_BA
 const dryRun = Boolean(args["dry-run"]);
 const skipProducts = Boolean(args["skip-products"]);
 const strictProducts = Boolean(args["strict-products"]);
+const strictEmptyCategories = Boolean(args["strict-empty-categories"] ?? args["fail-empty-categories"]);
 
 if (!existsSync(distDir)) {
   throw new Error(`Build output directory not found: ${relativePath(distDir)}`);
@@ -71,6 +72,8 @@ const client = skipProducts || !baseUrl
   ? undefined
   : createOrderlyNodeClient({ baseUrl, protocol });
 const productCache = new Map();
+const emptyProductWarnings = [];
+const failedProductSnapshots = new Set();
 let updatedPages = 0;
 let hydratedProducts = 0;
 
@@ -80,6 +83,7 @@ if (existsSync(homeFile)) {
   const homeProducts = new Map();
   for (const category of homeCategories) {
     const products = await productsForCategory(category, homeProductsPerCategory);
+    reportEmptyProducts(category, products, "homepage rail", homeProductsPerCategory);
     hydratedProducts += products.length;
     homeProducts.set(category.id, products);
   }
@@ -97,6 +101,7 @@ for (const category of categories) {
     continue;
   }
   const products = await productsForCategory(category, productsPerCategory);
+  reportEmptyProducts(category, products, "category page", productsPerCategory);
   hydratedProducts += products.length;
   const html = readFileSync(file, "utf8");
   const next = hydrateCategoryHtml(html, category, products);
@@ -110,6 +115,13 @@ const productSuffix = skipProducts
   ? "Product snapshots were skipped."
   : `${hydratedProducts} product snapshot${hydratedProducts === 1 ? "" : "s"} embedded.`;
 console.log(`Hydrated ${updatedPages} static page${updatedPages === 1 ? "" : "s"}. ${productSuffix}`);
+if (emptyProductWarnings.length > 0) {
+  const summary = `${emptyProductWarnings.length} category/rail product snapshot quer${emptyProductWarnings.length === 1 ? "y" : "ies"} matched 0 products.`;
+  if (strictEmptyCategories) {
+    throw new Error(`${summary} Rework src/navigation.ts queries or remove --strict-empty-categories.`);
+  }
+  console.warn(`Warning: ${summary}`);
+}
 
 function writePage(file, html) {
   if (dryRun) {
@@ -143,6 +155,7 @@ async function fetchProducts(category, limit) {
       .slice(0, limit);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
+    failedProductSnapshots.add(category.id);
     if (strictProducts) {
       throw new Error(`Could not hydrate products for ${category.id}: ${message}`, { cause: error });
     }
@@ -151,6 +164,16 @@ async function fetchProducts(category, limit) {
   }
 }
 
+function reportEmptyProducts(category, products, surface, requestedLimit) {
+  if (skipProducts || !client || requestedLimit <= 0 || products.length > 0 || failedProductSnapshots.has(category.id)) {
+    return;
+  }
+  const label = categoryLabelPath(category).join(" / ") || category.label || category.id;
+  const message = `${surface} "${label}" (${category.id}) matched 0 products. Check its SearchQuery.Query, SearchQuery.Tags, and the shop defaultQuery; use "|" for OR terms and avoid multiple tags for alternatives.`;
+  emptyProductWarnings.push(message);
+  console.warn(`Warning: ${message}`);
+}
+
 function hydrateHomeHtml(html, categories, productsByCategory) {
   const title = readAttribute(html, "orderly-home-page", "title") ?? siteTitle;
   const eyebrow = readAttribute(html, "orderly-home-page", "eyebrow");
@@ -624,6 +647,7 @@ Options:
   --image-base-url <url>       StoredImage CDN prefix. Defaults to Orderly production CDN.
   --skip-products              Hydrate category/home text only, without backend product calls.
   --strict-products            Fail when a product snapshot call fails.
+  --strict-empty-categories    Fail when a category page or homepage rail query returns 0 products.
   --dry-run                    Print files that would change without writing.
   --help, -h                   Show this help.
 `);