@proveanything/smartlinks 1.11.1 → 1.11.2

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.11.1  |  Generated: 2026-04-30T12:17:30.051Z
+Version: 1.11.2  |  Generated: 2026-04-30T13:11:24.914Z
 
 This is a concise summary of all available API functions and types.
 

package/dist/docs/app-manifest.md

@@ -117,14 +117,18 @@ The manifest is loaded automatically by the platform for every collection page.
 
   "records": {
     "nutrition": {
-      "scopes": ["product", "facet", "batch"],
-      "defaultScope": "facet",
-      "label": "Nutrition info"
+      "label": "Nutrition info",
+      "cardinality": "singleton",
+      "allowFacetRules": true,
+      "scopes": ["collection", "rule", "product", "facet", "batch"],
+      "defaultScope": "product"
     },
     "cooking_steps": {
-      "scopes": ["product", "facet"],
-      "defaultScope": "product",
-      "label": "Cooking steps"
+      "label": "Cooking steps",
+      "cardinality": "singleton",
+      "allowFacetRules": false,
+      "scopes": ["collection", "product"],
+      "defaultScope": "product"
     }
   }
 }
@@ -268,25 +272,29 @@ See the [Deep Link Discovery guide](deep-link-discovery.md) for the full dual-so
 
 Declares which `app.records` record types the app stores, and which scopes each type supports. Required for any app that follows the [Records-Based Admin Pattern](records-admin-pattern.md). Omit if the app does not use scoped records.
 
-The platform and the `<RecordsAdminShell>` from `@proveanything/ui-utils` read this block to render only the relevant tabs and affordances.
+The platform and the `<RecordsAdminShell>` from `@proveanything/smartlinks-utils-ui` read this block to render the right scope tabs, rule editor, and cardinality-appropriate right pane.
 
 ```json
 "records": {
   "<recordType>": {
-    "scopes": ["product", "facet", "batch"],
-    "defaultScope": "facet",
-    "label": "Human-readable label"
+    "label": "Human-readable label",
+    "cardinality": "singleton",
+    "allowFacetRules": false,
+    "scopes": ["collection", "product", "variant", "batch", "facet"],
+    "defaultScope": "product"
   }
 }
 ```
 
-| Field          | Type     | Required | Description |
-|----------------|----------|----------|-------------|
-| `scopes`       | string[] | ✅ | Allowed scope kinds in resolution order. Valid values: `"product"`, `"variant"`, `"batch"`, `"facet"`, `"proof"`, `"default"`. |
-| `defaultScope` | string   | ✅ | The scope the "Create new" button targets in the admin shell. Must be one of the declared `scopes`. |
-| `label`        | string   | ✅ | Human-readable label for the record type, used in headings and tabs. |
+| Field             | Type     | Default | Description |
+|-------------------|----------|---------|-------------|
+| `label`           | string   | — | Human-readable label for the record type, used in headings and tabs. |
+| `cardinality`     | string   | `'singleton'` | `'singleton'` — one record wins per scope (e.g. ingredients, nutrition). `'collection'` — every matching record is returned in resolution order (e.g. FAQs, recipes). Drives which hook to use on the public side (`useResolvedRecord` vs `useCollectedRecords`) and how the shell lays out the right pane. |
+| `allowFacetRules` | boolean  | `false` | When `true`, the shell renders a **Rule** scope tab and embeds `<FacetRuleEditor>`. Add `'rule'` to `scopes` when setting this. |
+| `scopes`          | string[] | — | Allowed scope kinds in resolution order. Valid values: `"collection"`, `"product"`, `"variant"`, `"batch"`, `"facet"`, `"proof"`, `"rule"`. `'rule'` is a synthetic scope holding `facetRule`-targeted records. `'collection'` replaces the legacy empty-ref catch-all — **there is no `'global'` scope**. |
+| `defaultScope`    | string   | — | The scope the "Create new" button targets in the admin shell. Must be one of the declared `scopes`. |
 
-An app may declare multiple record types under different keys (e.g. `"nutrition"` and `"cooking_steps"`).
+An app may declare multiple record types under different keys (e.g. `"nutrition"` and `"cooking_steps"`). See [records-admin-pattern.md](records-admin-pattern.md) for the full admin + public pattern.
 
 #### `executor`
 

package/dist/docs/app-objects.md

@@ -495,7 +495,7 @@ The `ref` field is derived automatically from anchor fields when omitted:
 ```
 productId: 'prod_abc'                               → ref: 'product:prod_abc'
 productId: 'prod_abc', variantId: 'var_x'          → ref: 'product:prod_abc/variant:var_x'
-(no anchor fields)                                  → ref: '' (universal)
+(no anchor fields)                                  → ref: '' (collection-level catch-all)
 facetRule: { ... }                                  → ref: 'rule:<ulid>'
 ```
 
@@ -513,6 +513,20 @@ When multiple scoped records match a context, they are ordered by `specificity`.
 | Per `anyOf` value | +1 |
 | No anchors / no rule | 0 |
 
+### Resolution order
+
+When the public side of a records-based app needs "the data that applies to this product context", the platform walks a canonical chain from most-specific to least-specific:
+
+```
+proof  →  batch  →  variant  →  product  →  rule(*)  →  facet(*)  →  collection
+```
+
+- `rule(*)` — `facetRule`-targeted records are scored by **specificity** (number of clauses + number of constrained values). The most specific rule wins at its tier.
+- `facet(*)` — legacy single-facet anchors, walked alphabetically. Prefer `facetRule` for new work.
+- `collection` — the top of the chain and the catch-all for any record with no anchor fields. **There is no `'global'` tier above collection.**
+
+For a **singleton** record type (one answer wins), use `useResolvedRecord` — it performs this walk server-side and returns the first match plus a `matchedAt` tag. For a **collection** record type (every match is shown), use `useCollectedRecords`. See [records-admin-pattern.md §2](records-admin-pattern.md#2-resolution-order-one-canonical-chain) for the full guide.
+
 ### Singleton Cardinality
 
 By default, `create` always inserts a new row — calling it twice produces two records with identical anchor fields. **Singleton cardinality** changes that: pass `singletonPer` on creation and the server will **upsert** instead, ensuring at most one record of a given `recordType` exists per scope boundary.
@@ -592,12 +606,11 @@ for (const entry of data) {
     case 'product':    /* "Inherited from product" */ break;
     case 'facet':      /* "Tier-specific" */          break;
     case 'collection': /* "Collection default" */     break;
-    case 'universal':  /* "Default" */                break;
   }
 }
 ```
 
-Precedence follows: `rule > proof > batch > variant > product > facet > collection > universal`.
+Precedence follows: `proof > batch > variant > product > rule > facet > collection`. There is no scope above `collection` — a record with no anchor fields is a collection-level catch-all.
 
 #### React — `useResolvedRecord`
 
@@ -806,7 +819,7 @@ Examples:
 | `productId: 'prod_abc', variantId: 'var_500ml'` | `product:prod_abc/variant:var_500ml` |
 | `batchId: 'batch_q1'` | `batch:batch_q1` |
 | `facetRule: { ... }` | `rule:<ulid>` |
-| *(no anchor fields)* | `''` (universal) |
+| *(no anchor fields)* | `''` (collection-level catch-all) |
 
 `parseRef` / `buildRef` in `data/refs.ts` should be used for **display and URL round-tripping only**, never as upsert keys. For ETL use cases, set an explicit `ref` using a stable external key (see [External ID / ETL Workflow](#external-id--etl-workflow)).
 

package/dist/docs/mobile-admin-container.md

@@ -58,6 +58,8 @@ Your container **never** detects the host directly. It receives a `host` prop fr
 
 Every container mounted by the SmartLinks Mobile launcher receives a single `host` prop — `AdminMobileHostContext`. Do not reach for `window.SmartlinksScanner` or `window.Capacitor` directly; both are wrapped here.
 
+> **SDK export** — `AdminMobileHostContext`, `AdminMobileCapability`, `AdminMobileHostId`, `AdminMobileEvent`, `ScannerEventSubscriber`, `MobileAdminComponentManifest`, and `MobileAdminBundleManifest` are all exported from `@proveanything/smartlinks`. Import via `import type { AdminMobileHostContext } from '@proveanything/smartlinks'` — no local mirror needed.
+
 ```typescript
 interface AdminMobileHostContext {
   // Identity
@@ -460,7 +462,7 @@ vite build --config vite.config.mobile-admin.ts
 ```typescript
 // src/mobile-admin/WarehousePickContainer.tsx
 import { useEffect, useState } from 'react'
-import type { AdminMobileHostContext } from '@/lib/admin-mobile-host-context'
+import type { AdminMobileHostContext } from '@proveanything/smartlinks'
 
 interface Props {
   host: AdminMobileHostContext