@proveanything/smartlinks 2.0.5 → 2.0.9

package/docs/host-dependency-contract.md

@@ -0,0 +1,159 @@
+# Host dependency contract (R5)
+
+> **SmartLinks SDK 2.x** (current `latest`). The portal host (R5) provides a fixed set of runtime
+> libraries as window globals. Micro-apps **externalise** these and resolve them from the host —
+> they must **not** bundle their own copies. This keeps one instance of React (and friends) on the
+> page and keeps bundles small.
+
+## The one rule that matters: externalise, never bundle
+
+A container/widget/executor bundle **must externalise `react`, `react-dom`, and every shared
+dependency below**, resolving them from the host globals. **Bundling your own React is the one
+hard failure** — two React instances on the page → hooks break → crash. (Bundling `liquidjs` or
+another shared lib is wasteful and can double-load, but React is the fatal one.)
+
+React-18-built bundles keep working on the R5 host: they externalise React and run against the
+host's **React 19** runtime. A bundle compiled against React 18 *typings* runs fine on the 19
+*runtime* — see backwards-compatibility below.
+
+## Vite / Rollup config
+
+Externalise the shared deps and map each to its window global:
+
+```ts
+// vite.config.ts (library build for a container/widget/executor)
+import { defineConfig } from 'vite'
+export default defineConfig({
+  build: {
+    lib: { entry: 'src/index.tsx', formats: ['umd'], name: 'MyApp', fileName: () => 'widgets.umd.js' },
+    rollupOptions: {
+      // Everything the host provides — do NOT bundle these.
+      external: [
+        'react', 'react-dom', 'react/jsx-runtime',
+        '@proveanything/smartlinks',
+        'react-router-dom', '@tanstack/react-query',
+        'lucide-react', 'date-fns', 'liquidjs', 'class-variance-authority',
+        '@radix-ui/react-slot', '@radix-ui/react-dialog', '@radix-ui/react-popover',
+        '@radix-ui/react-tooltip', '@radix-ui/react-tabs', '@radix-ui/react-accordion',
+        '@radix-ui/react-select', '@radix-ui/react-scroll-area', '@radix-ui/react-label',
+        '@radix-ui/react-toast', '@radix-ui/react-progress', '@radix-ui/react-avatar',
+      ],
+      output: {
+        globals: {
+          'react': 'React', 'react-dom': 'ReactDOM', 'react/jsx-runtime': 'jsxRuntime',
+          '@proveanything/smartlinks': 'SL',
+          'react-router-dom': 'ReactRouterDOM', '@tanstack/react-query': 'ReactQuery',
+          'lucide-react': 'LucideReact', 'date-fns': 'dateFns', 'liquidjs': 'LiquidJS',
+          'class-variance-authority': 'CVA',
+          '@radix-ui/react-slot': 'RadixSlot', '@radix-ui/react-dialog': 'RadixDialog',
+          '@radix-ui/react-popover': 'RadixPopover', '@radix-ui/react-tooltip': 'RadixTooltip',
+          '@radix-ui/react-tabs': 'RadixTabs', '@radix-ui/react-accordion': 'RadixAccordion',
+          '@radix-ui/react-select': 'RadixSelect', '@radix-ui/react-scroll-area': 'RadixScrollArea',
+          '@radix-ui/react-label': 'RadixLabel', '@radix-ui/react-toast': 'RadixToast',
+          '@radix-ui/react-progress': 'RadixProgress', '@radix-ui/react-avatar': 'RadixAvatar',
+        },
+      },
+    },
+  },
+})
+```
+
+## Host-provided globals (build against versions ≤ these)
+
+| Import | Window global | Host provides (R5) |
+|---|---|---|
+| `react` | `React` | 19.3 (accepts 18.3 builds) |
+| `react-dom` | `ReactDOM` | 19.3 (accepts 18.3 builds) |
+| `react/jsx-runtime` | `jsxRuntime` | 19.3 |
+| `@proveanything/smartlinks` | `SL` | 2.0.5 |
+| `react-router-dom` | `ReactRouterDOM` | 7.18 (accepts 6.x builds) |
+| `@tanstack/react-query` | `ReactQuery` | 5.103 |
+| `lucide-react` | `LucideReact` | 1.47 |
+| `date-fns` | `dateFns` | 4.4 |
+| `liquidjs` | `LiquidJS` | 10.27+ |
+| `class-variance-authority` | `CVA` | 0.7 |
+| `@radix-ui/react-slot` | `RadixSlot` | 1.2.4 |
+| `@radix-ui/react-dialog` | `RadixDialog` | 1.1.23 |
+| `@radix-ui/react-popover` | `RadixPopover` | 1.1.1 |
+| `@radix-ui/react-tooltip` | `RadixTooltip` | 1.2.8 |
+| `@radix-ui/react-tabs` | `RadixTabs` | 1.1.13 |
+| `@radix-ui/react-accordion` | `RadixAccordion` | 1.2.12 |
+| `@radix-ui/react-select` | `RadixSelect` | 2.3.7 |
+| `@radix-ui/react-scroll-area` | `RadixScrollArea` | 1.2.10 |
+| `@radix-ui/react-label` | `RadixLabel` | 2.1.8 |
+| `@radix-ui/react-toast` | `RadixToast` | 1.2.15 |
+| `@radix-ui/react-progress` | `RadixProgress` | 1.1.8 |
+| `@radix-ui/react-avatar` | `RadixAvatar` | 1.1.11 |
+
+`liquidjs` is **host-provided** — externalise it, don't ship a second copy (frequently missed).
+
+## Backwards compatibility
+
+React-18-built containers and widgets keep working unchanged on R5. A pre-existing bundle only
+breaks if it:
+
+- calls `ReactDOM.render` / `hydrate` / `unmountComponentAtNode` (self-mounting — containers are
+  mounted by the host, so this only affects apps that mount themselves);
+- relies on `defaultProps` / `propTypes` on **function** components (React 19 silently ignores
+  these → missing defaults, not a crash);
+- uses string refs, `findDOMNode`, or legacy context;
+- **bundles its own React** instead of externalising it → two instances → crash (the one hard
+  failure);
+- imports a `lucide-react` icon renamed/removed in the 0.x → 1.x move.
+
+## Tailwind is *not* part of the contract
+
+Bundles ship their own compiled CSS, so the host's Tailwind version is irrelevant to them. A
+micro-app can stay on **Tailwind 3 indefinitely**, or adopt Tailwind 4 — its choice. (The starter
+app ships the Tailwind 4 CSS-first layout as the default; see its README.)
+
+## The R5 host stack (reference)
+
+React **19.3** · Vite **8.3** · react-router-dom **7.18** · Tailwind **4.3** (CSS-first) ·
+TypeScript **6.0** · ESLint **10.11** · `@proveanything/smartlinks` **2.0.5** ·
+`@proveanything/smartlinks-utils-ui` **1.16.4** · liquidjs **10.29**.
+
+> **TypeScript 7** (the native/Go compiler) is **deliberately deferred** — tooling hasn't settled.
+> Target **TS 6** for R5; it compiles existing code with no source changes.
+
+## Security floor
+
+An R5 app must ship with **`npm audit` reporting zero vulnerabilities**. Run it against the real
+registry — `npm audit --registry=https://registry.npmjs.org` — because the sandbox mirror doesn't
+implement the audit endpoint. Two high-severity advisories are already pinned out in the R5 set and
+must stay pinned:
+
+- **`react-router` 7.12.0–7.18.1** — RSC-mode CSRF bypass. Build against **7.18.4+** (the host
+  provides ≥7.18.4). Never ship a router below 7.18.4.
+- **`browserslist` ≤4.28.6** — unbounded memory growth / prototype write. It's a transitive build
+  dependency, so pin it with an `overrides` entry (`"overrides": { "browserslist": "^4.29" }`), not
+  a direct dependency.
+
+Both are compile-time/build-time concerns for the app's own toolchain; neither is a host global.
+
+## Reading the contract programmatically (one source of truth)
+
+Don't hard-code the externalized list — import it from the SDK, so hosts and apps
+never drift:
+
+```ts
+import {
+  SHARED_DEPENDENCY_CONTRACT_VERSION, // 'v5'
+  SHARED_DEPENDENCIES,                // [{ specifier, globalName, minVersion, importMapPath }, …] (25)
+  SHARED_DEPENDENCY_SPECIFIERS,       // bare specifiers — drop straight into a bundler `external` list
+  getHostSharedDependencies,          // what the live host advertises at runtime, or null
+} from '@proveanything/smartlinks'
+
+// Build config: externalize exactly the contract.
+export const external = [...SHARED_DEPENDENCY_SPECIFIERS]
+
+// Runtime: degrade gracefully on an older host that lacks the import map.
+const host = getHostSharedDependencies()
+if (host && host.version !== SHARED_DEPENDENCY_CONTRACT_VERSION) {
+  console.warn(`Built against ${SHARED_DEPENDENCY_CONTRACT_VERSION}, host serves ${host.version}`)
+}
+```
+
+The host publishes its live contract on `window.__SMARTLINKS_SHARED__` (`{ version, specifiers }`),
+which `getHostSharedDependencies()` reads. Import-map shim paths follow `importMapPathFor(specifier)`
+(`/sl-shared/<version>/<slug>.js`), so both the portal and the SDK generate identical paths.

package/docs/iframe-responder.md

@@ -468,3 +468,311 @@ import type {
 ### Portal back exits the app too early
 - Set `state.parentPath` on route changes for screens that should navigate "up" inside the app.
 - Make sure the receiving app listens for `smartlinks-navigate` if the SDK version in use does not already handle it.
+
+---
+
+## Streaming in a hand-rolled parent (without IframeResponder)
+
+The following applies **only if you build your own parent proxy** instead of using the `IframeResponder` class above — which already handles AI streaming for you. It is the wire protocol for forwarding SSE/streaming responses to a child app in proxy mode.
+### Goal
+
+Keep the existing architecture:
+
+- local mode: child calls API directly
+- iframe proxy mode: child never owns auth state and streams through the parent
+
+This keeps user/session authority in the parent while making AI streaming behave like the rest of the SDK transport.
+
+### What changed
+
+Previously, proxy mode only supported one-shot request/response messages:
+
+- `_smartlinksProxyRequest`
+- `_smartlinksProxyResponse`
+
+Streaming now adds a second protocol for long-lived responses:
+
+- `_smartlinksProxyStreamRequest`
+- `_smartlinksProxyStream`
+- `_smartlinksProxyStreamAbort`
+
+### New parent message handling
+
+#### 1. Listen for stream requests
+
+The iframe child may now send this message:
+
+```ts
+{
+  _smartlinksProxyStreamRequest: true,
+  id: string,
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+  path: string,
+  body?: any,
+  headers?: Record<string, string>
+}
+```
+
+Parent behavior:
+
+- treat this like a proxied API request
+- build the real API URL from your configured base URL plus `path`
+- send the request using the parent's current auth/session context
+- expect an SSE / streaming response body
+- keep the request open until the stream ends or is aborted
+
+#### 2. Forward stream lifecycle messages back to the child
+
+The parent should send messages back to the iframe using this envelope:
+
+```ts
+{
+  _smartlinksProxyStream: true,
+  id: string,
+  phase: 'open' | 'event' | 'end' | 'error',
+  data?: any,
+  error?: string,
+  status?: number
+}
+```
+
+Phases:
+
+- `open`
+  - optional but recommended
+  - indicates the upstream streaming request was accepted and a body exists
+- `event`
+  - contains one parsed JSON event from an SSE `data:` frame
+  - send one message per logical event payload
+- `end`
+  - sent once when the stream finishes normally
+- `error`
+  - sent if the upstream request fails before or during streaming
+
+#### 3. Support abort from the child
+
+The child may stop reading early and send:
+
+```ts
+{
+  _smartlinksProxyStreamAbort: true,
+  id: string
+}
+```
+
+Parent behavior:
+
+- look up the active stream by `id`
+- abort the underlying fetch / reader
+- clean up any local state for that stream
+- do not keep streaming after abort
+
+### SSE forwarding rules
+
+The upstream AI endpoints return SSE-like frames. The parent should:
+
+- read the response body as a stream
+- buffer text until line boundaries
+- collect `data:` lines for a single event
+- join multi-line `data:` payloads with `\n`
+- ignore blank events
+- stop on `data: [DONE]`
+- JSON-parse each event payload
+- forward parsed payloads to the iframe as `_smartlinksProxyStream` with `phase: 'event'`
+
+Minimal parsing behavior:
+
+1. accumulate bytes into text
+2. split on `\r?\n`
+3. collect each `data:` line
+4. on blank line, finalize the event
+5. if payload is `[DONE]`, finish
+6. otherwise `JSON.parse(payload)` and forward
+
+### Auth and session expectations
+
+The parent remains the source of truth for auth.
+
+That means the parent stream handler should:
+
+- use the same auth headers/token source as normal proxied requests
+- not require the iframe to know the bearer token or API key
+- naturally pick up the current logged-in user when the stream starts
+- cancel active streams if your app invalidates session state on logout or account switch
+
+In practice, the stream request should use the same header-building logic as your normal parent proxy transport.
+
+### Error handling expectations
+
+If the upstream fetch returns a non-2xx status:
+
+- try to read the JSON error body
+- derive a useful message
+- send one `_smartlinksProxyStream` message with `phase: 'error'`
+- include `status` when available
+- do not send `end` afterward
+
+If the stream body is missing unexpectedly:
+
+- send `phase: 'error'`
+
+If JSON parsing fails for a single event chunk:
+
+- safest behavior is to ignore that malformed chunk and continue
+
+### State the parent should keep
+
+Track active streams in a map keyed by `id`:
+
+```ts
+Map<string, AbortController>
+```
+
+Recommended cleanup points:
+
+- on normal stream end
+- on error
+- on child abort
+- on iframe detach/unmount
+- on parent auth reset/logout if you want all in-flight streams cancelled immediately
+
+### Parent implementation outline
+
+```ts
+const activeStreams = new Map<string, AbortController>()
+
+window.addEventListener('message', async (event) => {
+  const msg = event.data
+
+  if (msg?._smartlinksProxyStreamAbort && msg.id) {
+    activeStreams.get(msg.id)?.abort()
+    activeStreams.delete(msg.id)
+    return
+  }
+
+  if (msg?._smartlinksProxyStreamRequest && msg.id) {
+    const controller = new AbortController()
+    activeStreams.set(msg.id, controller)
+
+    try {
+      const response = await fetch(buildUrl(msg.path), {
+        method: msg.method,
+        headers: msg.headers,
+        body: msg.body ? JSON.stringify(msg.body) : undefined,
+        signal: controller.signal,
+      })
+
+      if (!response.ok || !response.body) {
+        postError(...)
+        return
+      }
+
+      postOpen(...)
+      await forwardSse(response.body, parsed => postEvent(...parsed))
+      postEnd(...)
+    } catch (err) {
+      if (err?.name !== 'AbortError') postError(...)
+    } finally {
+      activeStreams.delete(msg.id)
+    }
+  }
+})
+```
+
+### Exact protocol summary
+
+#### Child → parent
+
+Standard stream request:
+
+```ts
+{
+  _smartlinksProxyStreamRequest: true,
+  id,
+  method,
+  path,
+  body,
+  headers
+}
+```
+
+Abort request:
+
+```ts
+{
+  _smartlinksProxyStreamAbort: true,
+  id
+}
+```
+
+#### Parent → child
+
+Open:
+
+```ts
+{
+  _smartlinksProxyStream: true,
+  id,
+  phase: 'open'
+}
+```
+
+Event:
+
+```ts
+{
+  _smartlinksProxyStream: true,
+  id,
+  phase: 'event',
+  data: parsedJsonEvent
+}
+```
+
+End:
+
+```ts
+{
+  _smartlinksProxyStream: true,
+  id,
+  phase: 'end'
+}
+```
+
+Error:
+
+```ts
+{
+  _smartlinksProxyStream: true,
+  id,
+  phase: 'error',
+  error: 'message',
+  status?: number
+}
+```
+
+### What does not change
+
+These parts of the parent iframe integration stay the same:
+
+- normal `_smartlinksProxyRequest` request/response flow
+- upload proxy flow
+- auth login/logout postMessage handling
+- route/deep-link handling
+- resize handling
+
+This is an additive protocol, not a replacement.
+
+### Current SDK reference
+
+The SDK implementation lives in:
+
+- [src/http.ts](src/http.ts)
+- [src/iframeResponder.ts](src/iframeResponder.ts)
+- [src/types/iframeResponder.ts](src/types/iframeResponder.ts)
+- [src/api/ai.ts](src/api/ai.ts)
+
+### Practical recommendation
+
+If your parent already uses `IframeResponder`, prefer upgrading to the SDK version with these changes instead of re-implementing the protocol manually.
+
+If your parent has a custom iframe bridge, implement exactly the three new message types above and reuse your existing auth/header logic from normal proxied requests.

package/docs/item-context.md

@@ -1,7 +1,5 @@
 # Item Context (container prop)
 
-> **Copy this file into `node_modules/@proveanything/smartlinks/docs/item-context.md`** in the published SDK package.
-
 When the URL points at a specific item — either a **serial proof URL** or an
 **NFC tap** — the portal derives an `ItemContext` describing what it found
 and hands it to the container as the **`itemContext`** prop.

package/docs/mobile-admin-container.md

@@ -1,6 +1,6 @@
 # Mobile Admin Container SDK
 
-> **Version:** 1.0 · **Platform:** SmartLinks R4 · **Last updated:** 2026-04-30
+> **Version:** 1.0 · **Platform:** SmartLinks R5 · **Last updated:** 2026-09-21
 
 This document describes how to build a **Mobile Admin Container** — a SmartLinks microapp that provides an in-the-field operator/admin surface optimised for mobile devices. These containers ship as a **separate `mobileAdmin` bundle** (not inside the `containers` bundle) so that Capacitor plugins, offline helpers, and operator-only code never reach the public consumer bundle.
 
@@ -271,7 +271,7 @@ Declare the bundle under the top-level `mobileAdmin` key in `app.manifest.json`.
   "meta": { "appId": "my-app", "name": "My App", "version": "1.0.0" },
 
   "containers": {
-    "files": { "js": { "umd": "dist/containers.umd.js", "esm": "dist/containers.es.js" }, "css": "dist/containers.css" },
+    "files": { "js": { "umd": "dist/containers.umd.js", "esm": "dist/containers.esm.js" }, "css": "dist/containers.css" },
     "components": [
       { "name": "PublicContainer", "description": "Default consumer experience" }
     ]
@@ -281,7 +281,7 @@ Declare the bundle under the top-level `mobileAdmin` key in `app.manifest.json`.
     "files": {
       "js": {
         "umd": "dist/mobile-admin.umd.js",
-        "esm": "dist/mobile-admin.es.js"
+        "esm": "dist/mobile-admin.esm.js"
       },
       "css": null
     },
@@ -416,7 +416,7 @@ The mobile admin bundle has its own Vite config: `vite.config.mobile-admin.ts`.
 
 ```
 dist/mobile-admin.umd.js
-dist/mobile-admin.es.js
+dist/mobile-admin.esm.js
 dist/mobile-admin.css    (if needed)
 ```
 

package/docs/mpa.md

@@ -56,9 +56,9 @@ vite build
 | Step | Config / Script | Gate env var | Output |
 |------|----------------|-------------|--------|
 | 1 | `vite.config.ts` | Always runs | `index.html`, `admin.html`, `assets/*` |
-| 2 | `vite.config.widget.ts` | `VITE_ENABLE_WIDGETS=true` | `widgets.umd.js`, `widgets.es.js`, `widgets.css` |
-| 3 | `vite.config.container.ts` | `VITE_ENABLE_CONTAINERS=true` | `containers.umd.js`, `containers.es.js`, `containers.css` |
-| 4 | `vite.config.executor.ts` | `VITE_ENABLE_EXECUTOR!=false` | `executor.umd.js`, `executor.es.js` |
+| 2 | `vite.config.widget.ts` | `VITE_ENABLE_WIDGETS=true` | `widgets.umd.js`, `widgets.esm.js`, `widgets.css` |
+| 3 | `vite.config.container.ts` | `VITE_ENABLE_CONTAINERS=true` | `containers.umd.js`, `containers.esm.js`, `containers.css` |
+| 4 | `vite.config.executor.ts` | `VITE_ENABLE_EXECUTOR!=false` | `executor.umd.js`, `executor.esm.js` |
 | 5 | `scripts/hash-bundles.mjs` | Always runs | Renames bundles with content hashes; patches `dist/app.manifest.json` |
 
 Steps 2–4 produce a harmless stub file when their gate env var is not set. Step 5 detects and skips stub files automatically.
@@ -107,7 +107,7 @@ dist/
 └── executor-[hash].es.js           ← Executor bundle (ESM)
 ```
 
-> Widget and container CSS files are only present when the bundle ships custom styles. Most apps set `"css": null` in the manifest because they rely entirely on Tailwind/shadcn from the parent. See the [AI-Native App Manifests](manifests.md) guide for the CSS null warning.
+> Widget and container CSS files are only present when the bundle ships custom styles. Most apps set `"css": null` in the manifest because they rely entirely on Tailwind/shadcn from the parent. See the [App Configuration Files](app-manifest.md) for the CSS null warning.
 
 ---
 
@@ -133,6 +133,6 @@ If the embedded app exposes nested screens, document its "up" navigation path wi
 | [Widgets](widgets.md) | Widget bundle: components, props, settings |
 | [Containers](containers.md) | Container bundle: full-app embeds |
 | [Executor Model](executor.md) | Executor bundle: SEO, LLM content, config mutations |
-| [AI-Native App Manifests](manifests.md) | How manifests wire all bundles together for AI discovery |
+| [App Configuration Files](app-manifest.md) | Manifest + admin reference; widget settings schema; AI workflows |
 | [iframe Responder](iframe-responder.md) | Reading context params inside the iframe |
 | [Portal Back Button](portal-back-button.md) | Hierarchy-aware back navigation for embedded apps |

package/docs/native-facade.md

@@ -1,6 +1,6 @@
 # Native Capability Facade (`host.native` / `SL.native`)
 
-> **Version:** 1.12 · **Platform:** SmartLinks R4 · **Last updated:** 2026-04-30
+> **Version:** 1.12 · **Platform:** SmartLinks R5 · **Last updated:** 2026-09-21
 
 The `NativeFacade` is a thin contract layer between microapps and the device capabilities available on the current host shell (Kotlin, Capacitor iOS/Android, PWA, or browser). It lets a microapp call `host.native.share.share({...})` without knowing whether it's running over `window.SmartlinksScanner`, a Capacitor plugin, or `navigator.share`.
 

package/docs/overview.md

@@ -1,25 +1,21 @@
 # SmartLinks Microapp Development Guide
 
-> **Platform revision:** R4.6 · **SDK minimum:** `@proveanything/smartlinks@1.4.1`  
-> **Last updated:** 2026-03-03
+> **Platform revision:** R5 · **SDK:** `@proveanything/smartlinks@^2` · React 19 · Vite 8 · Router 7 · Tailwind 4 · TS 6.
+> The canonical version/host stack lives in [host-dependency-contract.md](host-dependency-contract.md).
 
 ---
 
 ## What Is a SmartLinks Microapp?
 
-SmartLinks microapps are **modular, embeddable React applications** that extend the SmartLinks digital twin platform. They provide specialised functionality — product information displays, warranty registration, competitions, pamphlet generators, and more — while inheriting context, authentication, and theming from the parent platform.
+SmartLinks connects **physical products to digital experiences**: each item has a digital identity — a **proof** — that a consumer reaches by scanning a QR / NFC tag, then claims and enriches over time. A **microapp** is a focused, embeddable React experience a brand adds to that product's digital life: product info, warranty registration, authenticity checks, manuals, competitions, loyalty, post-purchase support, and more.
 
-### The Digital Twin Ecosystem
+Rather than baking every feature into the core platform, functionality is distributed across purpose-built apps, so a brand adds exactly the experiences its product needs. Each app:
 
-SmartLinks is a **digital twin platform** that connects physical products to digital experiences. Each physical item (a wine bottle, a luxury handbag, a piece of equipment) has a corresponding digital identity — a "proof" — that can be scanned, claimed, and enriched with data over time.
-
-Microapps are the **extensibility layer** of this ecosystem. Rather than building monolithic features into the core platform, functionality is distributed across purpose-built apps that:
-
-- **Embed seamlessly** via iframes in the SmartLinks Portal (public) and Admin Console (management)
-- **Share context** through URL parameters (collection, product, or proof being viewed)
-- **Inherit identity** from the parent platform's authentication system
-- **Adapt visually** to the brand's theme configuration
-- **Communicate bidirectionally** with the parent via postMessage for deep linking and navigation
+- **Embeds** in the SmartLinks Portal (public) and Admin Console (management)
+- **Shares context** through URL parameters (collection, product, proof)
+- **Inherits identity** from the parent platform's auth
+- **Adapts** to the brand's theme
+- **Communicates** with the parent via postMessage for deep linking and navigation
 
 ### Deployment Modes
 
@@ -45,7 +41,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 
 > Product endpoints: use `products` (plural) for new integrations. The older `product` (singular) namespace remains for backward compatibility and is deprecated.
 
-> **Minimum SDK version: `1.4.1`** — Ensure `@proveanything/smartlinks` is at least this version. If not, update with `npm install @proveanything/smartlinks@latest`.
+> **SDK baseline: `@proveanything/smartlinks@^2.0`** (R5). Install/update with `npm install @proveanything/smartlinks@^2.0`. Individual features may need a higher minor — see the relevant doc. The single source of truth for the R5 host/version stack is [`host-dependency-contract.md`](host-dependency-contract.md).
 
 | Topic | File | When to Use |
 |-------|------|-------------|
@@ -64,12 +60,13 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Mobile Admin Container** | `docs/mobile-admin-container.md` | Building a separate Capacitor-aware mobile admin bundle for field operators |
 | **Executors** | `docs/executor.md` | Building executor bundles for SEO, LLM content, programmatic config |
 | **Server Functions** | `docs/server-functions.md` | App-authored server-side functions `(ctx, event) ⇒ result`: security model, runtime surface, invoking |
+| **Agent Tools** | `docs/agent-tools.md` | Exposing your app's actions to the SmartLinks agent — an MCP facade over server functions; declare now, live loop staged; replaces `app.admin.json` AI setup |
 | **Deploying & Registering** | `docs/deploying-apps.md` | Getting your app into the platform: fast dev publish, channels, deploy keys, registering releases |
+| **Host Dependency Contract (R5)** | `docs/host-dependency-contract.md` | The libraries the host provides (React 19, Router 7, Radix, liquidjs, …), the externalise-don't-bundle rule + Vite config, and React-18 backwards-compat |
 | **Deep Linking** | `docs/deep-link-discovery.md` | URL state management, navigable states, portal menus, AI nav |
 | **Portal Back Button** | `docs/portal-back-button.md` | Hierarchy-aware "up" navigation inside embedded apps |
 | **Portal Request Action** | `docs/portal-request-action.md` | Triggering portal built-in actions (__qrScanner, __share, __logout, etc.) from sub-apps |
 | **Interactions** | `docs/interactions.md` | Business events, outcomes, voting, competitions, and journey triggers |
-| **AI-Native Manifests** | `docs/manifests.md` | `app.manifest.json`, `app.admin.json`, `ai-guide.md` structure |
 | **App Config Files** | `docs/app-manifest.md` | Full field-by-field reference for both JSON config files |
 | **Real-time Messaging** | `docs/realtime.md` | Adding Ably real-time features (chat, live updates) |
 | **Liquid Templates** | `docs/liquid-templates.md` | Dynamic content rendering with LiquidJS |
@@ -87,6 +84,21 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Proof Share Grants** | `docs/proof-share-grants.md` | Delegated, scoped, revocable bearer access to a single proof (read/comment/verify-owner) |
 | **Proof Ownership Transfer** | `docs/proof-ownership-transfer.md` | Moving a proof's single owner (directed transfer / open release), accept/cancel, and the state machine |
 | **appConfig / Feature Flags** | `docs/appConfig.md` | `appConfig` settings contract — installed apps, `system.features`/`entitledAppGroups`/`meters`, `isFeatureEnabled()` helper |
+| **App Objects** | `docs/app-objects.md` | Queryable domain objects — `app.records` / `app.cases` / `app.threads`: JSONB zones, visibility, policies, aggregations |
+| **App Data Storage** | `docs/app-data-storage.md` | Decision guide: pick between `appConfiguration` / `userAppData` / `app.records` |
+| **Attestations** | `docs/attestations.md` | Postgres attestations API (proof-level user/admin data; replaces the legacy Firestore path) |
+| **Caching** | `docs/caching.md` | SDK GET cache tiers + TTLs, `invalidateCache({ exact })`, and `force`/push guidance |
+| **Comms & Broadcasts** | `docs/comms.md` | Transactional comms, campaigns, consent, push |
+| **Container Tracking** | `docs/container-tracking.md` | Physical/logical **item** container groupings — *not* app containers (see containers.md) |
+| **Lots** | `docs/lots.md` | Cross-SKU production "Lot" entity |
+| **Loyalty** | `docs/loyalty.md` | Points, members, earning rules |
+| **Sequences** | `docs/sequences.md` | Atomic monotonic number allocation (raffle / queue / edition) |
+| **Integrations** | `docs/integrations.md` | Inbound/outbound external-system integration flows |
+| **Item Context** | `docs/item-context.md` | The `itemContext` container prop (serial / NFC authenticity context) |
+| **Native Facade** | `docs/native-facade.md` | `host.native` / `SL.native` device-capability facade |
+| **Product Facets** | `docs/PRODUCT_FACETS_SDK.md` | Facet API reference (admin + public endpoints, types) |
+| **AI Tools & Skills** | `docs/ai-tools-and-skills.md` | Platform AI capability registry (web research, extraction, images) |
+| **Proof Comms Triggers** | `docs/proof-comms-triggers.md` | Transactional comms fired as a side-effect of proof actions |
 
 ---
 
@@ -97,6 +109,15 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 - **Context via URL params** — All contextual data is passed through URL parameters
 - **SmartLinks NPM module** — All data access and platform interaction goes through `@proveanything/smartlinks`
 - **No standalone auth** — Authentication is handled by the parent SmartLinks platform
+
+> **Use the host-provided `SL`, don't instantiate your own.** When your app runs in a
+> container/iframe, the host injects an already-initialized, authenticated SDK instance (the
+> `SL` prop / the externalized `@proveanything/smartlinks` singleton). Import and use *that*.
+> Calling `initializeApi()` yourself to spin up a **second** SDK instance is a common source
+> of bugs: it won't share the host's auth (so it looks signed-out), won't share the host's
+> cache (duplicate requests, stale data), and in proxy mode it bypasses the host's request
+> routing. Rule of thumb: **host-provided `SL` for anything the platform owns** (auth, config,
+> data, cache); only app-owned state is yours.
 - **Multi-page build** — Separate bundles for public and admin — see `docs/mpa.md`
 - **Embedded back navigation** — Use `docs/portal-back-button.md` when a sub-app has a real content hierarchy
 

package/docs/portal-back-button.md

@@ -1,8 +1,7 @@
 # Portal Back Button — "Up" Navigation Inside Sub-Apps
 
-> **For sub-app authors.** Drop this file into the SmartLinks SDK docs (e.g.
-> `docs/portal-back-button.md`) and link it from `routing.md` / `mpa.md` so
-> microapp authors discover it.
+> **For sub-app authors.** How to cooperate with the portal shell's top-level
+> back/up control. See also [`mpa.md`](mpa.md).
 
 When a sub-app is embedded by a portal shell, the shell renders a top-level
 back button. By default that button **exits the app entirely** when tapped —