navu-catalog 4.14.2

package/docs/catalog-tools-guide.md

@@ -0,0 +1,832 @@
+# How catalog tools work
+
+A plain-language guide to searching a Navu product catalog. This document is for anyone calling the catalog API directly — integrators, portal developers, or anyone exploring what the three tools do and why each request/response field exists.
+
+**Engineering context:** [catalog-overview.md](./catalog-overview.md) · **Search design detail:** [catalog-search-architecture.md](./catalog-search-architecture.md)
+
+---
+
+## What is a catalog?
+
+A **catalog** is a searchable index of a site's sellable (or listable) items. Each site can have one or more catalogs; the primary one is usually named `products`.
+
+Upstream data (Shopify, a product feed, a custom API) is **harvested** into structured records, then **indexed** in OpenSearch. At query time you never talk to Shopify directly — you talk to the catalog service, which returns consistent, site-specific fields.
+
+Every catalog exposes exactly **three tools** (three HTTP endpoints). Together they support a natural shopping flow:
+
+1. **Discovery** — “What can I narrow on?” (facet menus and price bands)
+2. **Query** — “Show me matching products” (search + filters + counts)
+3. **Get details** — “Give me the full record for these IDs or SKUs” (complete product + all variants)
+
+Default tool names are `find-products-discovery`, `find-products-query`, and `find-products-get-details`. A site may override the base name (for example `find-parts-discovery` on an industrial parts catalog).
+
+### API endpoints
+
+All three are `POST` requests under the intrasystem catalog service:
+
+| Tool | Route |
+|------|-------|
+| Discovery | `POST /d/navu-catalog/int/discovery` |
+| Query | `POST /d/navu-catalog/int/query` |
+| Get details | `POST /d/navu-catalog/int/get-details` |
+
+Every request identifies **which catalog** to search:
+
+| Field | Meaning |
+|-------|---------|
+| `siteId` | Mongo ObjectId string for the site (required) |
+| `catalogName` | Catalog slug, usually `products` (required) |
+| `siteCode` | Optional; resolved from site record if omitted |
+| `siteDomain` | Optional; used for logging/metrics if omitted |
+
+The catalog's **manifest** defines which filter **tokens** exist (`color`, `category`, `price`, …), whether each token applies at **product** or **variant** grain, and which token is the **scope** (the top-level category partition). You use manifest tokens in `filters` — not raw database field paths.
+
+---
+
+## Mental model: products, variants, and tokens
+
+### Product vs variant
+
+- A **product** is a family or style — shared name, description, images, and marketing copy.
+- A **variant** is one purchasable SKU — a specific combination of size, color, price, and availability.
+
+Many catalogs have real variants (compression socks in Navy / S/M vs Black / L/XL). Others are “products-only” (one SKU per product); the same three tools still apply.
+
+When you **query** with `type: "product"`, each row is a product with a preview of matching SKUs. When you **query** with `type: "variant"`, each row is a single SKU with its parent product name attached.
+
+### Filters use tokens
+
+A filter always looks like:
+
+```json
+{ "token": "color", "value": "Navy" }
+```
+
+Optional `op` supports comparisons for numbers: `=`, `!=`, `>`, `>=`, `<`, `<=`. Most keyword filters omit `op` (equals).
+
+The catalog translates `token` → the correct indexed field. You do not pass `variants.color` or `field_path` in tool calls.
+
+### Scope
+
+Each catalog has at most one **scope** property (for Vim & Vigr, `category` — values like `Compression Socks`, `Sleeves`). Scope is the coarsest useful partition: “what kind of thing are we looking for?” Discovery always reports scope counts so you can see how many products fall in each category.
+
+### Snapshot time (`as_of`)
+
+Responses include `as_of` — milliseconds since Unix epoch when the index snapshot was built (typically the last successful harvest/index). Indexed price and availability are **indicative** at that time (`price_indicative`, `available_indexed` on variant previews). Treat them as catalog snapshot values, not live checkout truth.
+
+---
+
+## Tool 1: Discovery
+
+### What it does
+
+Discovery answers: **“Given what I already know (optional text + optional filters), what narrowing options exist?”**
+
+It returns **facet menus** — legal values for terms facets (color, size, material, …) and min/max/avg for range facets (price). It does **not** return product rows.
+
+Use discovery when you need to populate UI chips, show “12 products in Navy”, or learn valid filter values before running a query.
+
+### Request fields
+
+| Field | Purpose |
+|-------|---------|
+| `query` | Optional free text. When present, facets are computed over a relevance-ranked preview of matching products (hybrid keyword + semantic search). When omitted, facets reflect all products matching your filters. |
+| `filters` | Optional constraints already applied. Discovery counts are **conditional** — “if I also pick this color, how many products remain?” |
+| `value_search` | Optional `{ token, query }` for high-cardinality facets (e.g. search brand names) when enumerating every value is impractical. |
+
+Discovery filters do **not** use `source` / `stated_span` — those are query-tool semantics.
+
+### Response fields
+
+| Field | Purpose |
+|-------|---------|
+| `as_of` | Index snapshot timestamp |
+| `facets[]` | One entry per advertised facet from the manifest |
+| `facets[].token` | Filter token name |
+| `facets[].grain` | `product` or `variant` — whether counts are product rows or SKU-level |
+| `facets[].scope` | Active filters this facet count is conditioned on |
+| `facets[].kind` | `terms` (value list) or `range` (numeric band) |
+| `facets[].values` | For `terms`: each value with `product_count` and optional `variant_count` |
+| `facets[].range` | For `range`: `min`, `max`, `avg` over the scoped set |
+| `applied_filters` | Filters that were understood and applied |
+| `ignored_filters` | Filters that could not be applied (unknown token, bad value, etc.) |
+
+**How to read counts:** Prefer `product_count` for “how many products match.” `variant_count` is SKU depth (one product can contribute multiple SKUs).
+
+---
+
+### Example 1 — Simplest discovery (no text, no filters)
+
+“What categories exist in the catalog?”
+
+**Request:**
+
+```json
+{
+  "siteId": "507f1f77bcf86cd799439011",
+  "catalogName": "products"
+}
+```
+
+**Response (abbreviated):**
+
+```json
+{
+  "as_of": 1735689600000,
+  "facets": [
+    {
+      "token": "category",
+      "grain": "product",
+      "scope": [],
+      "kind": "terms",
+      "values": [
+        { "value": "Compression Socks", "product_count": 28, "variant_count": 412 },
+        { "value": "Sleeves", "product_count": 6, "variant_count": 18 },
+        { "value": "Accessories", "product_count": 4, "variant_count": 9 }
+      ]
+    },
+    {
+      "token": "material",
+      "grain": "product",
+      "scope": [],
+      "kind": "terms",
+      "values": [
+        { "value": "Cotton", "product_count": 14, "variant_count": 210 },
+        { "value": "Nylon", "product_count": 11, "variant_count": 165 }
+      ]
+    },
+    {
+      "token": "price",
+      "grain": "variant",
+      "scope": [],
+      "kind": "range",
+      "range": { "min": 24.0, "max": 58.0, "avg": 34.5 }
+    }
+  ],
+  "applied_filters": [],
+  "ignored_filters": []
+}
+```
+
+`category` is the **scope** facet — start here when the visitor has not narrowed product type yet. `price` as `range` tells you the spread of SKU prices without listing every price point.
+
+---
+
+### Example 2 — Discovery with a text query
+
+“What colors appear among products matching ‘cotton compression socks’?”
+
+**Request:**
+
+```json
+{
+  "siteId": "507f1f77bcf86cd799439011",
+  "catalogName": "products",
+  "query": "cotton compression socks"
+}
+```
+
+**Response (abbreviated):**
+
+```json
+{
+  "as_of": 1735689600000,
+  "facets": [
+    {
+      "token": "color",
+      "grain": "variant",
+      "scope": [],
+      "kind": "terms",
+      "values": [
+        { "value": "Black", "product_count": 8, "variant_count": 48 },
+        { "value": "Navy", "product_count": 7, "variant_count": 42 },
+        { "value": "Cream & Cobalt", "product_count": 3, "variant_count": 12 }
+      ]
+    },
+    {
+      "token": "fit_size",
+      "grain": "variant",
+      "scope": [],
+      "kind": "terms",
+      "values": [
+        { "value": "S/M", "product_count": 9, "variant_count": 54 },
+        { "value": "L/XL", "product_count": 8, "variant_count": 46 },
+        { "value": "Wide Calf", "product_count": 4, "variant_count": 14 }
+      ]
+    }
+  ],
+  "applied_filters": [],
+  "ignored_filters": []
+}
+```
+
+The text query narrowed the population **before** facets were computed. Counts are “among products relevant to cotton compression socks,” not the whole catalog.
+
+---
+
+### Example 3 — Discovery with filters (conditional facets)
+
+“Among navy cotton socks, what sizes are still available?”
+
+**Request:**
+
+```json
+{
+  "siteId": "507f1f77bcf86cd799439011",
+  "catalogName": "products",
+  "filters": [
+    { "token": "category", "value": "Compression Socks" },
+    { "token": "material", "value": "Cotton" },
+    { "token": "color", "value": "Navy" }
+  ]
+}
+```
+
+**Response (abbreviated):**
+
+```json
+{
+  "as_of": 1735689600000,
+  "facets": [
+    {
+      "token": "fit_size",
+      "grain": "variant",
+      "scope": [
+        { "token": "category", "value": "Compression Socks" },
+        { "token": "material", "value": "Cotton" },
+        { "token": "color", "value": "Navy" }
+      ],
+      "kind": "terms",
+      "values": [
+        { "value": "S/M", "product_count": 3, "variant_count": 3 },
+        { "value": "L/XL", "product_count": 2, "variant_count": 2 }
+      ]
+    }
+  ],
+  "applied_filters": [
+    { "token": "category", "value": "Compression Socks", "resolved_value": "Compression Socks" },
+    { "token": "material", "value": "Cotton", "resolved_value": "Cotton" },
+    { "token": "color", "value": "Navy", "resolved_value": "Navy" }
+  ],
+  "ignored_filters": []
+}
+```
+
+`scope` on the facet echoes the filters already in play. `fit_size` counts mean: “if the visitor picks this size **in addition** to navy cotton compression socks, this many products remain.”
+
+---
+
+## Tool 2: Query
+
+### What it does
+
+Query answers: **“Which products (or SKUs) match my text and filters, and how many are there?”**
+
+This is the workhorse for search results pages, ranked lists, and “show me 10 options” flows.
+
+### Request fields
+
+| Field | Purpose |
+|-------|---------|
+| `query` | Optional free text (hybrid keyword + semantic when non-empty) |
+| `filters` | Optional constraints. On the query tool each filter should include `source` (see below). |
+| `type` | `"product"` (default) — one row per product with variant previews. `"variant"` — one row per matching SKU. |
+| `product_id` | Optional — restrict to a single parent product (useful for “show variants of this style only”) |
+| `limit` / `offset` | Pagination |
+| `count_only` | When `true`, return counts without hydrating rows (cheaper) |
+| `variantPreviewPerProduct` | Max SKU previews per product row (default 3) |
+
+### Filter `source` (query only)
+
+Each filter on a **query** call should declare **why** it is there. This drives honest bookkeeping in the response.
+
+| `source` | Constrains results? | Meaning |
+|----------|---------------------|---------|
+| `stated` | Yes | Explicitly named in the visitor's words. Requires `stated_span` — exact substring of `query`. |
+| `implied` | Yes | Not literal words, but clearly required (e.g. wide calf from “wide calves”). Requires `implied_span`. |
+| `instrumental` | Yes | Your system's constraint (e.g. only in-stock), not attributed to the visitor. No span required. |
+| `inferred` | **No** | A guess or suggestion. Returned in `offered_refinements` with `would_be_count`, not applied to `total`. |
+
+If a constraining filter (`stated`, `implied`, or `instrumental`) cannot be applied, it lands in `ignored_filters` and **`total` becomes `null`** — the service refuses to guess a count rather than silently dropping the constraint.
+
+### Response fields
+
+| Field | Purpose |
+|-------|---------|
+| `total` | Match count over applied constraining filters. `null` if any constraining filter was ignored. |
+| `shown_count` | Rows returned in this page |
+| `type` | `product` or `variant` projection |
+| `products[]` | Product rows when `type` is `product` |
+| `variants[]` | SKU rows when `type` is `variant` |
+| `applied_filters` | Filters that affected the search |
+| `ignored_filters` | Filters that failed (with `reason`, sometimes `did_you_mean`) |
+| `offered_refinements` | Inferred suggestions with `would_be_count` |
+| `filter_notes` | Non-blocking corrections (e.g. value retagged to canonical spelling) |
+| `narrowed_to_empty` | `true` when filters zero out results but a broader parent query still matches |
+| `parent_total` / `culprit_filter` | Diagnostic when `narrowed_to_empty` — which filter likely caused zero results |
+| `grounding_failure` | All attribution-bearing filters failed |
+| `variant_budget_exhausted` | Global preview cap limited how many SKUs were shown per product |
+
+### Product row highlights (`type: "product"`)
+
+| Field | Purpose |
+|-------|---------|
+| `product_id` | Stable ID — carry this to get-details |
+| `name`, `url`, `image_url` | Display and linking |
+| `matching_variant_count` | How many SKUs match (may exceed `shown_variant_count`) |
+| `matching_variants[]` | Preview of matching SKUs (sku, description, price_indicative, available_indexed) |
+| `product_fields` | Product-grain scalars from the manifest |
+| `variant_field_rollups` | Union summaries across SKUs (e.g. all colors available on this style) |
+
+---
+
+### Example 4 — Simplest query (text only)
+
+“Find compression socks.”
+
+**Request:**
+
+```json
+{
+  "siteId": "507f1f77bcf86cd799439011",
+  "catalogName": "products",
+  "query": "compression socks",
+  "type": "product",
+  "limit": 3
+}
+```
+
+**Response (abbreviated):**
+
+```json
+{
+  "as_of": 1735689600000,
+  "total": 28,
+  "shown_count": 3,
+  "type": "product",
+  "products": [
+    {
+      "product_id": "8919885971592",
+      "name": "Cotton Compression Socks 15-20 mmHg",
+      "url": "https://example.com/products/cotton-compression-socks",
+      "image_url": "https://cdn.example.com/solid-black-hero.jpg",
+      "matching_variant_count": 18,
+      "shown_variant_count": 3,
+      "matching_variants_truncated": true,
+      "matching_variants": [
+        {
+          "sku": "VV-CTN-1520-NVY-SM",
+          "url": "https://example.com/products/cotton-compression-socks?variant=44012",
+          "description": "Navy / S/M",
+          "fields": { "color": "Navy", "fit_size": "S/M", "compression_level": "15-20 mmHg" },
+          "price_indicative": 32.0,
+          "available_indexed": true
+        }
+      ],
+      "variant_field_rollups": {
+        "color_rollup": ["Black", "Navy", "Cream & Cobalt"],
+        "fit_size_rollup": ["S/M", "L/XL", "Wide Calf"]
+      }
+    }
+  ],
+  "applied_filters": [],
+  "ignored_filters": []
+}
+```
+
+`total` is the full match count; `products` is only the first page. `matching_variants` is a **preview** — use get-details for every SKU.
+
+---
+
+### Example 5 — Query with filters (product rows)
+
+“Navy cotton compression socks in size S/M.”
+
+**Request:**
+
+```json
+{
+  "siteId": "507f1f77bcf86cd799439011",
+  "catalogName": "products",
+  "query": "compression socks",
+  "type": "product",
+  "limit": 5,
+  "filters": [
+    {
+      "token": "color",
+      "value": "Navy",
+      "source": "stated",
+      "stated_span": "navy"
+    },
+    {
+      "token": "material",
+      "value": "Cotton",
+      "source": "implied",
+      "implied_span": "cotton"
+    },
+    {
+      "token": "fit_size",
+      "value": "S/M",
+      "source": "stated",
+      "stated_span": "S/M"
+    }
+  ]
+}
+```
+
+**Response (abbreviated):**
+
+```json
+{
+  "as_of": 1735689600000,
+  "total": 3,
+  "shown_count": 3,
+  "type": "product",
+  "products": [
+    {
+      "product_id": "8919885971592",
+      "name": "Cotton Compression Socks 15-20 mmHg",
+      "matching_variant_count": 1,
+      "shown_variant_count": 1,
+      "matching_variants_truncated": false,
+      "matching_variants": [
+        {
+          "sku": "VV-CTN-1520-NVY-SM",
+          "description": "Navy / S/M",
+          "price_indicative": 32.0,
+          "available_indexed": true
+        }
+      ]
+    }
+  ],
+  "applied_filters": [
+    { "token": "color", "value": "Navy", "source": "stated", "resolved_value": "Navy" },
+    { "token": "material", "value": "Cotton", "source": "implied", "resolved_value": "Cotton" },
+    { "token": "fit_size", "value": "S/M", "source": "stated", "resolved_value": "S/M" }
+  ],
+  "ignored_filters": []
+}
+```
+
+Color, material, and size must all be satisfied by **the same SKU** (variant-grain conjunction). That is why `matching_variant_count: 1` — one purchasable option matches all three constraints.
+
+---
+
+### Example 6 — Variant projection (SKU rows)
+
+“List every navy S/M SKU under $35.”
+
+**Request:**
+
+```json
+{
+  "siteId": "507f1f77bcf86cd799439011",
+  "catalogName": "products",
+  "type": "variant",
+  "limit": 20,
+  "filters": [
+    { "token": "color", "value": "Navy", "source": "instrumental" },
+    { "token": "fit_size", "value": "S/M", "source": "instrumental" },
+    { "token": "price", "op": "<=", "value": 35, "source": "instrumental" }
+  ]
+}
+```
+
+**Response (abbreviated):**
+
+```json
+{
+  "as_of": 1735689600000,
+  "total": 5,
+  "shown_count": 5,
+  "type": "variant",
+  "variants": [
+    {
+      "product_id": "8919885971592",
+      "name": "Cotton Compression Socks 15-20 mmHg",
+      "sku": "VV-CTN-1520-NVY-SM",
+      "description": "Navy / S/M",
+      "price_indicative": 32.0,
+      "available_indexed": true,
+      "fields": { "color": "Navy", "fit_size": "S/M" }
+    }
+  ],
+  "applied_filters": [
+    { "token": "color", "value": "Navy", "source": "instrumental", "resolved_value": "Navy" },
+    { "token": "fit_size", "value": "S/M", "source": "instrumental", "resolved_value": "S/M" },
+    { "token": "price", "op": "<=", "value": 35, "source": "instrumental", "resolved_value": 35 }
+  ],
+  "ignored_filters": []
+}
+```
+
+Use `type: "variant"` when the UI is a SKU picker (size/color matrix, cart add) rather than a product grid.
+
+---
+
+### Example 7 — Inferred refinements (suggestions that do not filter)
+
+“Show cotton socks” while suggesting wide-calf as an optional refinement.
+
+**Request:**
+
+```json
+{
+  "siteId": "507f1f77bcf86cd799439011",
+  "catalogName": "products",
+  "query": "cotton socks",
+  "filters": [
+    { "token": "material", "value": "Cotton", "source": "stated", "stated_span": "cotton" },
+    { "token": "wide_calf", "value": true, "source": "inferred" }
+  ]
+}
+```
+
+**Response (abbreviated):**
+
+```json
+{
+  "as_of": 1735689600000,
+  "total": 14,
+  "type": "product",
+  "products": [ "..." ],
+  "applied_filters": [
+    { "token": "material", "value": "Cotton", "source": "stated", "resolved_value": "Cotton" }
+  ],
+  "ignored_filters": [],
+  "offered_refinements": [
+    {
+      "token": "wide_calf",
+      "value": true,
+      "reason": "inferred",
+      "would_be_count": 4
+    }
+  ]
+}
+```
+
+`total: 14` is **all cotton socks**. The wide-calf filter did not apply. `would_be_count: 4` means “if they also wanted wide calf, 4 products would match” — useful for “Did you mean wide calf?” UI without over-filtering.
+
+---
+
+### Example 8 — Failed filter (honest `null` total)
+
+“Cherry red socks” when `Cherry` is not a catalog color.
+
+**Request:**
+
+```json
+{
+  "siteId": "507f1f77bcf86cd799439011",
+  "catalogName": "products",
+  "query": "cherry red socks",
+  "filters": [
+    {
+      "token": "color",
+      "value": "Cherry",
+      "source": "stated",
+      "stated_span": "cherry"
+    }
+  ]
+}
+```
+
+**Response (abbreviated):**
+
+```json
+{
+  "as_of": 1735689600000,
+  "total": null,
+  "type": "product",
+  "products": [],
+  "applied_filters": [],
+  "ignored_filters": [
+    {
+      "token": "color",
+      "value": "Cherry",
+      "source": "stated",
+      "reason": "value_unresolved",
+      "did_you_mean": ["Red", "Burgundy"]
+    }
+  ],
+  "grounding_failure": true
+}
+```
+
+When a constraining filter fails, **`total` is `null`**, not zero. Zero means “valid filters, no matches.” `null` means “we could not honor your constraint — fix the filter and retry.” `did_you_mean` carries canonical facet values.
+
+---
+
+### Example 9 — Narrowed to empty (wrong filter, not empty catalog)
+
+Filters are valid but over-restrictive; removing one filter would restore results.
+
+**Response (abbreviated):**
+
+```json
+{
+  "as_of": 1735689600000,
+  "total": 0,
+  "type": "product",
+  "products": [],
+  "applied_filters": [ "..." ],
+  "ignored_filters": [],
+  "narrowed_to_empty": true,
+  "parent_total": 7,
+  "culprit_filter": { "token": "fit_size", "value": "Wide Calf" }
+}
+```
+
+`parent_total: 7` — without the culprit filter, seven products match. This signals a **filter mismatch** (perhaps that size does not exist in navy cotton), not that the catalog lacks socks.
+
+---
+
+## Tool 3: Get details
+
+### What it does
+
+Get details answers: **“Give me the complete indexed record for these products or SKUs.”**
+
+Use it after query when you need:
+
+- Every variant on a product (not just the preview)
+- Full `description`, `narrative`, and manifest fields
+- Stable hydration by `product_id` or `sku` without re-running search
+
+Query ranks and filters; get-details **hydrates by identifier**. If you already have `product_id` values from a prior query, fetch details directly — do not re-search the same question.
+
+### Request fields
+
+| Field | Purpose |
+|-------|---------|
+| `product_ids` | Array of parent product IDs (from query results) |
+| `skus` | Array of SKU strings — resolves to parent product(s) |
+
+Provide at least one of `product_ids` or `skus`.
+
+### Response fields
+
+| Field | Purpose |
+|-------|---------|
+| `as_of` | Index snapshot timestamp |
+| `items[]` | One entry per product found |
+| `items[].product` | Full `CatalogIndexedProduct` document |
+| `items[].variants` | Complete variant array (uncapped) |
+| `items[].variant_previews` | Human-readable SKU summaries (same shape as query previews) |
+| `items[].product_fields` | Product-grain manifest fields |
+| `items[].variant_field_rollups` | Union rollups across all variants |
+
+---
+
+### Example 10 — Get details by product ID
+
+**Request:**
+
+```json
+{
+  "siteId": "507f1f77bcf86cd799439011",
+  "catalogName": "products",
+  "product_ids": ["8919885971592"]
+}
+```
+
+**Response (abbreviated):**
+
+```json
+{
+  "as_of": 1735689600000,
+  "items": [
+    {
+      "product": {
+        "product_id": "8919885971592",
+        "name": "Cotton Compression Socks 15-20 mmHg",
+        "description": "Everyday graduated compression in a soft cotton blend…",
+        "canonical_url": "https://example.com/products/cotton-compression-socks",
+        "image_url": "https://cdn.example.com/solid-black-hero.jpg",
+        "material": "Cotton",
+        "pattern": "Solid",
+        "min_price": 30.0,
+        "max_price": 44.0,
+        "variants": [
+          {
+            "sku": "VV-CTN-1520-NVY-SM",
+            "color": "Navy",
+            "fit_size": "S/M",
+            "compression_level": "15-20 mmHg",
+            "price_indicative": 32.0,
+            "available_indexed": true,
+            "webpage_url": "https://example.com/products/cotton-compression-socks?variant=44012"
+          },
+          {
+            "sku": "VV-CTN-1520-BLK-SM",
+            "color": "Black",
+            "fit_size": "S/M",
+            "price_indicative": 30.0,
+            "available_indexed": true
+          }
+        ]
+      },
+      "variants": [ "..." ],
+      "variant_previews": [
+        { "sku": "VV-CTN-1520-NVY-SM", "description": "Navy / S/M", "price_indicative": 32.0 }
+      ],
+      "product_fields": { "material": "Cotton", "pattern": "Solid" },
+      "variant_field_rollups": {
+        "color_rollup": ["Black", "Navy", "Cream & Cobalt"]
+      },
+      "as_of": 1735689600000
+    }
+  ]
+}
+```
+
+Compare to query: get-details returns **all** variants and full `description` / `narrative`, not a relevance-ranked subset.
+
+---
+
+### Example 11 — Get details by SKU
+
+Useful when the visitor arrives with a SKU from a receipt, email, or URL.
+
+**Request:**
+
+```json
+{
+  "siteId": "507f1f77bcf86cd799439011",
+  "catalogName": "products",
+  "skus": ["VV-CTN-1520-NVY-SM"]
+}
+```
+
+**Response:** Same `items[]` shape as Example 10 — one parent product containing that SKU.
+
+---
+
+### Example 12 — Batch hydration
+
+**Request:**
+
+```json
+{
+  "siteId": "507f1f77bcf86cd799439011",
+  "catalogName": "products",
+  "product_ids": ["8919885971592", "8919886004360", "8919886111122"]
+}
+```
+
+**Response:** `items` may contain fewer than three entries if some IDs are unknown or deleted. Each returned item is independent — order is not guaranteed to match request order.
+
+---
+
+## Putting it together: a typical flow
+
+A guided shopping experience usually alternates discovery and query, then hydrates winners:
+
+```text
+1. discovery (no filters)
+   → show category scope + coarse facets
+
+2. discovery (category = Compression Socks)
+   → show color / size / price band menus
+
+3. query (text + filters, type=product, limit=8)
+   → ranked product cards with variant previews
+
+4. get-details (product_id from selected card)
+   → full variant matrix for PDP or compare view
+```
+
+| Step | Tool | You get |
+|------|------|---------|
+| Browse categories | discovery | Facet menus, no rows |
+| Narrow options | discovery + filters | Conditional facet counts |
+| Search / list | query | `total`, product or SKU rows |
+| Product page | get-details | Complete product + all variants |
+
+**Discovery does not replace query.** Discovery suggests values; query returns actual matches and authoritative totals (when filters are valid).
+
+**Query does not replace get-details.** Query previews cap how many SKUs appear per product; get-details is the source of truth for the full variant list.
+
+---
+
+## Per-catalog differences
+
+Tokens, scope property, and facet menus are **not hard-coded**. They come from each site's manifest:
+
+| Site style | Scope token | Example facet tokens |
+|------------|-------------|----------------------|
+| Apparel (Vim & Vigr) | `category` | `color`, `fit_size`, `compression_level`, `material`, `price` |
+| Industrial (Cisco-Eagle) | `product_type` | `manufacturer`, dimensions, capacity |
+| Parts (Custom Truck) | varies | part category, fitment, specifications |
+
+Call `POST /d/navu-catalog/int/get-catalog-tools` or `get-site-catalog` to inspect which tokens and tool names a site exposes before building requests.
+
+---
+
+## Related documents
+
+- [catalog-overview.md](./catalog-overview.md) — system architecture and ingestion
+- [catalog-search-architecture.md](./catalog-search-architecture.md) — products vs variants, grains, hybrid search
+- [catalog-pipeline-guidelines.md](./catalog-pipeline-guidelines.md) — adding a new catalog site
+
+*When this guide disagrees with `@hivepoint/navu-apis` types (`catalog-tool-api.ts`), treat the API types as source of truth.*