Previous value: -"What re-reads this retailer’s prices: `live-api` a product-lookup API, `feed` a partner datafeed, `none` nothing at all. `none` means the figure is frozen at whatever seeded it and will not move however long it sits — say so rather than quoting it flat."New value: +"What re-reads this retailer’s prices: `live-api` a product-lookup API, `feed` a partner datafeed, `crawl` WEM reading the retailer’s own public product page, `none` nothing at all. `none` means the figure is frozen at whatever seeded it and will not move however long it sits — say so rather than quoting it flat. A `crawl` price was observed on the retailer’s page rather than supplied by them, so date it with `priceAgeDays` and expect `affiliate: false` unless a programme also exists."

Previous value: -[
-  "live-api",
-  "feed",
-  "none"
-]New value: +[
+  "live-api",
+  "feed",
+  "crawl",
+  "none"
+]

Previous value: -"Affiliate disclosure to relay once per answer. Outbound links are tracked at no extra cost to the buyer."New value: +"Disclosure to relay once per answer, verbatim. Its wording changes with the rows: it states whether every outbound link is affiliate-tracked, only some are, or none are. Never substitute the version you saw last time — a row marked `affiliate: false` earns WEM nothing, and saying otherwise misdescribes it to the shopper."

Added value: +{
+  "description": "Where to send the shopper when WEM's set is thin. chrome_extension means compare the same product on any retailer page — WEM shows that price even without an affiliate programme.",
+  "properties": {
+    "reason": {
+      "type": "string"
+    },
+    "surface": {
+      "enum": [
+        "chrome_extension"
+      ],
+      "type": "string"
+    },
+    "url": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

Added value: +{
+  "description": "Present when this result names no offer. GIVE THE USER THIS LINK — it is the answer when WEM has nothing else to say, and `markdown` is ready to paste. WEM searches retailers live on that page, including shops it holds no affiliate programme with, so an empty or withheld result here is not evidence the product is unavailable or unpriced.",
+  "properties": {
+    "markdown": {
+      "description": "The same link, pre-formatted.",
+      "type": "string"
+    },
+    "reason": {
+      "type": "string"
+    },
+    "url": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

Added value: +{
+  "description": "Present when `price` is the OPENING price of a range, not the price of this item: a multi-variation listing where the seller advertises its cheapest variant and the shopper picks a size on the page. Quote it as \"from £X\", never as the price or the cheapest. Absent means the price is firm for the row as described.",
+  "enum": [
+    "from"
+  ],
+  "type": "string"
+}

Added value: +{
+  "description": "Present when `price` is the OPENING price of a range, not the price of this item: a multi-variation listing where the seller advertises its cheapest variant and the shopper picks a size on the page. Quote it as \"from £X\", never as the price or the cheapest. Absent means the price is firm for the row as described.",
+  "enum": [
+    "from"
+  ],
+  "type": "string"
+}

Added value: +{
+  "description": "retailer is a named shop (Boots, Currys). marketplace is eBay/AliExpress/Temu-style parallel listings. Do not present a marketplace cluster as competing authorised retailers.",
+  "enum": [
+    "retailer",
+    "marketplace"
+  ],
+  "type": "string"
+}

Added value: +{
+  "description": "Delivery window when the feed stated one.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

Added value: +{
+  "description": "retailer is a named shop (Boots, Currys). marketplace is eBay/AliExpress/Temu-style parallel listings. Do not present a marketplace cluster as competing authorised retailers.",
+  "enum": [
+    "retailer",
+    "marketplace"
+  ],
+  "type": "string"
+}

Added value: +{
+  "description": "Delivery window when the feed stated one.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

Added value: +{
+  "description": "False when this is a retailer page WEM observed without a programme. Still a real listing; the click is not commission-bearing. Absent means the usual partner path.",
+  "type": "boolean"
+}

Added value: +{
+  "description": "False when this is a retailer page WEM observed without a programme. Still a real listing; the click is not commission-bearing. Absent means the usual partner path.",
+  "type": "boolean"
+}

Previous value: -"When WEM last read these offers — the freshness of this block."New value: +"When WEM last actually read any price in this block. Null means none of them can be dated — say so rather than implying the block is current."

Previous value: -"When WEM last wrote this offer row."New value: +"When WEM last VISITED this offer row — not when it read the price. The refresh sweep touches this even when the retailer lookup fails, so it is not evidence the price is current. Use `priceAgeDays` to date a price; never this."

Previous value: -"Whole days since WEM last wrote this price. Null means unknown age — report it as unknown rather than assuming it is current."New value: +"Whole days since WEM last actually READ this price from the retailer or a datafeed. Null means WEM cannot say — common and correct for Amazon, whose licence caps price retention at 24 hours. Report null as undated; never present it as current."

Previous value: -"Offers resolved by barcode rather than by matching titles. When present, prefer these and cite their prices over anything in `products`."New value: +"Offers WEM holds under one catalogue product. Check `identityBasis`: on `barcode` these are resolved by GTIN rather than by matching titles, so prefer them and cite their prices over anything in `products`. On `curated-grouping` the product carries no barcode, the grouping is an inference like any title match, and a cheaper row in `products` may well be the same item — see `cheaperElsewhere`."

Added value: +{
+  "description": "Present only on a `curated-grouping` block that a live row in `products` undercuts. WEM is telling you its own catalogue block is not the best price it found. Quote this row as the cheaper option with its identity stated as unconfirmed; never present the catalogMatch price as the lowest when this is set.",
+  "properties": {
+    "identity": {
+      "description": "Always `inferred` — matched on title, not barcode. Say so when quoting it.",
+      "enum": [
+        "inferred"
+      ],
+      "type": "string"
+    },
+    "note": {
+      "description": "Plain-language restatement, safe to relay.",
+      "type": "string"
+    },
+    "savingVsCatalogue": {
+      "description": "How much cheaper this row is than the block’s lowest offer.",
+      "type": "number"
+    },
+    "verified": {
+      "description": "Always false.",
+      "type": "boolean"
+    }
+  },
+  "type": [
+    "object",
+    "null"
+  ]
+}

Added value: +{
+  "description": "What this block’s identity rests on. `barcode` — the canonical product carries a GTIN and these offers are the same physical item. `curated-grouping` — it carries none, so the grouping is an inference of the same kind a title match is; do not describe it to the user as barcode-confirmed, and do not let it outrank a cheaper row in `products` on price alone.",
+  "enum": [
+    "barcode",
+    "curated-grouping"
+  ],
+  "type": "string"
+}

Added value: +{
+  "description": "When WEM last read these offers — the freshness of this block.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

Added value: +{
+  "description": "When WEM last wrote this offer row.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

Added value: +{
+  "description": "Whole days since WEM last wrote this price. Null means unknown age — report it as unknown rather than assuming it is current.",
+  "type": [
+    "number",
+    "null"
+  ]
+}

Added value: +{
+  "description": "What re-reads this retailer’s prices: `live-api` a product-lookup API, `feed` a partner datafeed, `none` nothing at all. `none` means the figure is frozen at whatever seeded it and will not move however long it sits — say so rather than quoting it flat.",
+  "enum": [
+    "live-api",
+    "feed",
+    "none"
+  ],
+  "type": "string"
+}

Previous value: -"Empty when the vector index has no rows (`semantic: false`, `reason: index_empty`). `semantic` is true only when pgvector actually ranked products."New value: +"Empty when the vector path cannot rank (`semantic: false`), with `reason` naming which of the five causes applies — they have different fixes, so do not read them all as an empty index. `semantic` is true only when pgvector actually ranked products."

Previous value: -"Present when semantic is false. `index_empty` means the embedding column is unpopulated, not that the shopper query is invalid."New value: +"Present when semantic is false, and never a judgement on the shopper query. `index_empty` — the vector query ran and matched nothing. `no_catalogue_client` / `no_embedding_key` — WEM is misconfigured, not the catalogue empty. `embedding_failed` / `query_failed` — an upstream call failed; retrying later may succeed."

Previous value: -"Falls back to the keyword-search shape whenever embeddings are unavailable, so `semantic` may be absent and `query` / `catalogMatch` may appear instead."New value: +"Empty when the vector index has no rows (`semantic: false`, `reason: index_empty`). `semantic` is true only when pgvector actually ranked products."

Added value: +{
+  "description": "Present when semantic is false. `index_empty` means the embedding column is unpopulated, not that the shopper query is invalid.",
+  "type": "string"
+}

Previous value: -"Always true here — identity is resolved, not inferred."New value: +"True when WEM has recently observed this price on the retailer’s own surface. False means the identity is still catalogue-resolved but the price is indicative (partner feed or stale) — do not present it as verified."

Previous value: -nullNew value: +{
+  "description": "Falls back to the keyword-search shape whenever embeddings are unavailable, so `semantic` may be absent and `query` / `catalogMatch` may appear instead.",
+  "properties": {
+    "catalogMatch": {
+      "description": "Offers resolved by barcode rather than by matching titles. When present, prefer these and cite their prices over anything in `products`.",
+      "properties": {
+        "currency": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "lowPrice": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "offers": {
+          "items": {
+            "properties": {
+              "brand": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "currency": {
+                "description": "ISO 4217 code.",
+                "type": "string"
+              },
+              "id": {
+                "type": "string"
+              },
+              "image": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "inStock": {
+                "type": [
+                  "boolean",
+                  "null"
+                ]
+              },
+              "price": {
+                "description": "Indicative price. The retailer sets the final price at checkout.",
+                "type": "number"
+              },
+              "provider": {
+                "description": "Retailer slug, e.g. \"ebay\", \"currys\".",
+                "type": "string"
+              },
+              "rating": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              },
+              "reviewCount": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              },
+              "seller": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "shipping": {
+                "properties": {
+                  "cost": {
+                    "type": [
+                      "number",
+                      "null"
+                    ]
+                  },
+                  "free": {
+                    "type": "boolean"
+                  }
+                },
+                "type": [
+                  "object",
+                  "null"
+                ]
+              },
+              "title": {
+                "type": "string"
+              },
+              "url": {
+                "description": "WEM tracked link to the retailer. Send the user here — WEM never takes payment.",
+                "type": "string"
+              },
+              "verified": {
+                "description": "Always true here — identity is resolved, not inferred.",
+                "type": "boolean"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "productPage": {
+          "type": "string"
+        },
+        "slug": {
+          "type": "string"
+        },
+        "source": {
+          "type": "string"
+        },
+        "title": {
+          "type": "string"
+        }
+      },
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "disclosure": {
+      "description": "Affiliate disclosure to relay once per answer. Outbound links are tracked at no extra cost to the buyer.",
+      "type": "string"
+    },
+    "filtered": {
+      "additionalProperties": {
+        "type": "number"
+      },
+      "description": "Withheld candidates tallied by reason (e.g. accessories, wrong model). Report this count rather than implying the search was exhaustive.",
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "products": {
+      "items": {
+        "properties": {
+          "brand": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "currency": {
+            "description": "ISO 4217 code.",
+            "type": "string"
+          },
+          "id": {
+            "type": "string"
+          },
+          "image": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "inStock": {
+            "type": [
+              "boolean",
+              "null"
+            ]
+          },
+          "price": {
+            "description": "Indicative price. The retailer sets the final price at checkout.",
+            "type": "number"
+          },
+          "provider": {
+            "description": "Retailer slug, e.g. \"ebay\", \"currys\".",
+            "type": "string"
+          },
+          "rating": {
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "reviewCount": {
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "seller": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "shipping": {
+            "properties": {
+              "cost": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              },
+              "free": {
+                "type": "boolean"
+              }
+            },
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "title": {
+            "type": "string"
+          },
+          "url": {
+            "description": "WEM tracked link to the retailer. Send the user here — WEM never takes payment.",
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "query": {
+      "type": "string"
+    },
+    "semantic": {
+      "description": "True only when the vector path actually ran.",
+      "type": "boolean"
+    },
+    "totalResults": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "products",
+    "totalResults",
+    "disclosure"
+  ],
+  "type": "object"
+}