Add a product registry and check every product name against it

.github/workflows/build-docs.yml

@@ -64,6 +64,15 @@ jobs:
       - name: Test framework registry
         run: yarn test:frameworks
 
+      # One list of products: docs-schema.yml, products.json, features.json,
+      # skills.json, URL_PRODUCT_MAPPING and page frontmatter must all agree
+      # with content/registry/products.yml.
+      - name: Test product registry check
+        run: yarn test:registry
+
+      - name: Verify product registry
+        run: yarn verify:registry
+
       - name: Build documentation
         run: yarn build
 

AGENTS.md

@@ -316,6 +316,10 @@ When working on this repository:
 
 All SDK platforms are treated equally - no platform gets special priority over others. The full list is the framework registry, `src/constants/frameworks.ts`; `npm run verify:frameworks` fails the build if the docs, the code or the data files use a framework name the registry doesn't know, or if `src/data/products.json` leaves a framework out.
 
+## Products
+
+The full list of products is the product registry, `content/registry/products.yml`. Use its `key` in frontmatter `product`, in component props and in data files. Its `aliases` (`matrixscan`, `label-capture`) are folder names under `/sdks/<framework>/` that differ from the key, and are valid only there and in `URL_PRODUCT_MAPPING`. `npm run verify:registry` fails the build if `docs-schema.yml`, the data files, `URL_PRODUCT_MAPPING` or a page's `product` disagree with it. Product Chooser text ("Choose this if / Consider another product if") goes in a separate file next to the registry, `content/registry/product-chooser.yml`, whose header comment shows the fields and how each one is displayed. Only entries with `status: approved` appear on pages; the same command checks every entry.
+
 ## Quick Reference
 
 ### File Extensions
@@ -343,6 +347,7 @@ npm run serve              # Serve built site
 npm run clear              # Clear cache
 npm run docs:gate          # Docs quality gate on changed docs
 npm run verify:frameworks  # Framework names and availability data
+npm run verify:registry    # Product names against the product registry
 npm run verify:agents-md   # This file's commands, scripts and paths
 ```
 Every script is in `package.json`; check there rather than relying on this list.

content/registry/product-chooser.yml

@@ -0,0 +1,36 @@
+# Product Chooser text: the "Choose this if / Consider another product if"
+# block at the top of a product's overview page, on every SDK framework.
+#
+# One entry per product, under `products`, keyed by the product's `key` in
+# products.yml. Only `sdk` products can have an entry. `yarn verify:registry`
+# checks every entry, draft or approved, and a docs build fails on an invalid
+# one, so keep drafts valid too.
+#
+#   status     `draft` or `approved`. Only approved entries appear on pages.
+#   choose_if  One or more lines, shown under the heading
+#              "Choose <Product> if you want to", so each line continues
+#              that sentence: "scan one barcode at a time", not "Scanning...".
+#   not_for    Optional. A list of { when, use } pairs, shown under the
+#              heading "Consider another product if" as "<when>: <Product>",
+#              linked to that product's overview. `use` is another product's
+#              key (`sdk` or `hosted`), never a topic. A row whose product
+#              is not available on the reader's framework (per
+#              src/data/products.json) is not shown there. With no row to
+#              show, or no not_for at all, the block shows one column.
+#
+# Wrap API names in backticks (`BarcodeBatch`) to show them as inline code.
+# The frameworks the product is available on come from src/data/products.json,
+# not from this file.
+#
+# Example (an entry is the indented part only, under `products:`):
+#
+#   products:
+#     sparkscan:
+#       status: draft
+#       choose_if:
+#         - <what the reader wants to do, continuing "you want to">
+#       not_for:
+#         - when: <the reader's situation where another product fits better>
+#           use: matrixscan-batch
+
+products:

content/registry/products.yml

@@ -0,0 +1,89 @@
+# The product registry: one entry per product.
+#
+# Every product identifier in the docs, the components, the docs gate and the
+# Agent Skills data is checked against this file by `yarn verify:registry`:
+#
+#   - `key` is the identifier to use everywhere: frontmatter `product`,
+#     component props, products.json, features.json and skills.json.
+#   - `aliases` are folder names under /sdks/<framework>/ that differ from the
+#     key (`matrixscan/` is MatrixScan Batch). They are valid only as folder
+#     names and in URL_PRODUCT_MAPPING (src/components/utils/frameworks.ts),
+#     which must map every alias to its key.
+#   - `kind`: `sdk` (documented per framework under /sdks/), `hosted` (under
+#     /hosted/), or `topic` (cross-product pages, not a product you install).
+#
+# The "Choose this if / Consider another product if" text for overview pages
+# lives in content/registry/product-chooser.yml, keyed by these product keys,
+# once a product owner has approved it. Per-framework availability and versions
+# still live in src/data/products.json until they are generated from SDK data.
+
+products:
+  - key: sparkscan
+    name: SparkScan
+    kind: sdk
+
+  - key: barcode-capture
+    name: Barcode Capture
+    kind: sdk
+
+  - key: matrixscan-batch
+    name: MatrixScan Batch
+    kind: sdk
+    aliases: [matrixscan]
+
+  - key: matrixscan-ar
+    name: MatrixScan AR
+    kind: sdk
+
+  - key: matrixscan-count
+    name: MatrixScan Count
+    kind: sdk
+
+  - key: matrixscan-find
+    name: MatrixScan Find
+    kind: sdk
+
+  - key: matrixscan-pick
+    name: MatrixScan Pick
+    kind: sdk
+
+  - key: barcode-selection
+    name: Barcode Selection
+    kind: sdk
+
+  - key: smart-label-capture
+    name: Smart Label Capture
+    kind: sdk
+    aliases: [label-capture]
+
+  - key: id-capture
+    name: ID Capture
+    kind: sdk
+
+  - key: parser
+    name: Parser
+    kind: sdk
+
+  - key: barcode-generator
+    name: Barcode Generator
+    kind: sdk
+
+  - key: barcode-sequence
+    name: MatrixScan Sequence
+    kind: sdk
+
+  - key: express
+    name: Scandit Express
+    kind: hosted
+
+  - key: id-bolt
+    name: ID Bolt
+    kind: hosted
+
+  - key: core
+    name: Core concepts
+    kind: topic
+
+  - key: platform
+    name: Platform
+    kind: topic

docs-schema.yml

@@ -29,11 +29,16 @@ properties:
            supported-values, configuration-reference, api-overview, deployment,
            licensing, scanning-performance, sample-catalog, use-case]
 
+  # The product keys from content/registry/products.yml. Folder names that
+  # differ from a key (`matrixscan`, `label-capture`) are aliases and not valid
+  # here. `yarn verify:registry` fails the build if this list and the registry
+  # drift.
   product:
     type: string
-    enum: [sparkscan, barcode-capture, matrixscan, matrixscan-find, matrixscan-count,
-           matrixscan-ar, matrixscan-pick, barcode-selection, barcode-generator,
-           id-capture, id-bolt, label-capture, parser, express, core, platform]
+    enum: [sparkscan, barcode-capture, matrixscan-batch, matrixscan-find,
+           matrixscan-count, matrixscan-ar, matrixscan-pick, barcode-selection,
+           barcode-generator, barcode-sequence, id-capture, id-bolt,
+           smart-label-capture, parser, express, core, platform]
 
   # Canonical framework slugs. These are the SSOT for every framework identifier
   # under docs/ and in code: they are exactly the `/sdks/<slug>/` URL segments

docs/sdks/android/label-capture/shipping-label-scanning.md

@@ -4,7 +4,7 @@ description: "Read the tracking ID, receiver address, and carrier from shipping
 sidebar_position: 4
 pagination_next: null
 framework: android
-product: label-capture
+product: smart-label-capture
 topic_type: how-to
 version_status: beta
 available_since: "8.6.0"

docs/sdks/ios/label-capture/shipping-label-scanning.md

@@ -4,7 +4,7 @@ description: "Read the tracking ID, receiver address, and carrier from shipping
 sidebar_position: 4
 pagination_next: null
 framework: ios
-product: label-capture
+product: smart-label-capture
 topic_type: how-to
 version_status: beta
 available_since: "8.6.0"

docs/sdks/web/label-capture/shipping-label-scanning.md

@@ -4,7 +4,7 @@ description: "Read the tracking ID, receiver address, and carrier from shipping
 sidebar_position: 4
 pagination_next: null
 framework: web
-product: label-capture
+product: smart-label-capture
 topic_type: how-to
 version_status: beta
 available_since: "8.6.0"

package.json

@@ -23,6 +23,8 @@
     "verify:frameworks": "node scripts/verify-frameworks.cjs",
     "verify:agents-md": "node scripts/verify-agents-md.cjs",
     "test:frameworks": "node scripts/test-frameworks.cjs",
+    "verify:registry": "node scripts/verify-registry.cjs",
+    "test:registry": "node scripts/test-registry.cjs",
     "test:docs-gate": "node scripts/test-docs-gate.cjs",
     "verify:api-reference-seo": "node scripts/verify-api-reference-seo.cjs",
     "test:api-reference-seo": "node scripts/test-api-reference-seo.cjs",