@proveanything/smartlinks 2.0.68 → 2.0.70

package/docs/overview.md

@@ -1,475 +1,476 @@
-# SmartLinks Microapp Development Guide
-
-> **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 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.
-
-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:
-
-- **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
-
-Each microapp can be consumed in one or more of the following ways:
-
-| Mode | Description |
-|------|-------------|
-| **Container** | Full app in parent React tree. ~150 KB+ lazy-loaded. The primary consumer surface. |
-| **Iframe App** | Full React app inside an iframe. Fallback when sandboxing is required; still the standard for setup admin screens. |
-| **Widget** | Lightweight React component in parent tree. ~10 KB, loaded immediately alongside the page. |
-| **Mobile Admin Container** | Separate bundle for in-the-field operator/admin workflows on mobile. Built independently; may use Capacitor, Preact, or any other runtime. |
-| **Executor** | JS library, no UI. Programmatic config, SEO metadata, LLM content for AI/server. |
-
-Widgets and containers run in the parent's React tree (not iframes). Mobile Admin Containers are a separate bundle loaded by a dedicated mobile shell (Capacitor or PWA). Executors have no UI — they expose functions that AI orchestrators and the server call directly.
-
-> **Admin vs consumer:** Admin experiences always ship as a **separate bundle** (`mobileAdmin` or iframe). The `containers` bundle is for consumer-facing surfaces only.
-
----
-
-## SDK Documentation Reference
-
-The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive documentation in `node_modules/@proveanything/smartlinks/docs/`. **Always read these files for detailed implementation guidance.**
-
-> Product endpoints: use `products` (plural) for new integrations. The older `product` (singular) namespace remains for backward compatibility and is deprecated.
-
-> **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 |
-|-------|------|-------------|
-| **API Reference** | `docs/API_SUMMARY.md` | Complete SDK function reference, types, error handling |
-| **Assets** | `docs/assets.md` | Asset object, AssetRef, upload, replace, soft-delete, restore, bulk-delete, public token-based uploads |
-| **Building React Components** | `docs/building-react-components.md` | **READ THIS FIRST** — Dual-mode rendering, router rules, useAppContext pattern |
-| **Multi-Page Architecture** | `docs/mpa.md` | Build pipeline, entry points, multi-page setup, content hashing |
-| **AI & Chat** | `docs/ai.md` | Chat completions, RAG, streaming, tool calling, voice, podcasts, TTS |
-| **Analytics** | `docs/analytics.md` | Fire-and-forget page/click/tag analytics plus admin dashboard queries |
-| **Translations** | `docs/translations.md` | Runtime translation lookup, local-first IndexedDB caching, and translation admin APIs |
-| **Theming** | `docs/theme.system.md` | Implementing dynamic themes via URL params or postMessage |
-| **Theme Defaults** | `docs/theme-defaults.md` | Default colour values for light/dark modes |
-| **Internationalization** | `docs/i18n.md` | Adding multi-language support, translation patterns |
-| **Widgets** | `docs/widgets.md` | Building widgets, shared deps contract, settings schema |
-| **Containers** | `docs/containers.md` | Building full-app embeddable containers (lazy-loaded) |
-| **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; **opt-in per app, additive, no migration**; complements `app.admin.json` (functions serve/adapt it, don't replace it); live loop staged |
-| **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 |
-| **CSS Baseline** (`sl-baseline` v1) | `docs/css-baseline.md` | A small, frozen, `sl-`-namespaced set of structural helpers (layout, spacing, responsive flow, type scale, motion) the SDK ships (`@proveanything/smartlinks/baseline.css`) and the host guarantees — a teachable floor for apps + AI content. No colours/fonts/components. Opt-in via `meta.cssBaseline` |
-| **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 |
-| **App Config Files** | `docs/app-manifest.md` | Full field-by-field reference for both JSON config files |
-| **Admin cards** | `docs/admin-cards.md` | Cards on the collection's dashboard in Studio: declare a card + an admin function returning its data; cached, refreshed only when its data changes |
-| **Realtime** | `docs/realtime.md` | Live updates: change events (refetch when something changes) and declared app channels (a draw, a status) — no provider library or keys |
-| **Liquid Templates** | `docs/liquid-templates.md` | Dynamic content rendering with LiquidJS |
-| **Iframe Responder** | `docs/iframe-responder.md` | Iframe communication and proxy mode internals |
-| **AI Guide Template** | `docs/ai-guide-template.md` | Template for creating `public/ai-guide.md` — customise per app |
-| **Forms** | `docs/forms.md` | Form definitions, schema-driven rendering, submission patterns |
-| **Auth Kit** | `docs/auth-kit.md` | End-user sign-in: email/password, magic links, phone OTP, Google OAuth |
-| **Portal Request Login** | `docs/portal-request-login.md` | How sub-apps ask the portal to authenticate the user; hook and iframe postMessage contracts |
-| **Portal Auth Broadcast** | `docs/portal-auth-broadcast.md` | Publishing custom auth flows to the portal; syncing sessions across containers and iframes |
-| **Contact Search** | `docs/contact-search.md` | Admin contact search: free-text, typeahead, identity/tag/JSONB filters, and pagination |
-| **App Records Pattern** | `docs/app-records-pattern.md` | Standard pattern for per-product/facet/variant/batch admin + public widget UIs |
-| **UI Utils** | `docs/ui-utils.md` | `@proveanything/smartlinks-utils-ui` — React shells, hooks, and primitives for records-based apps |
-| **Product/Proof Data Scoping** | `docs/proof-product-data-scoping.md` | Canonical spec for `product.data`/`.admin` and `proof.data`/`.admin`/`.values` (owner/personal) — who can read and write each bucket |
-| **Proof Claiming** | `docs/proof-claiming-methods.md` | The ways a user claims a proof (serial, NFC, claim-set, auto-generate) |
-| **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 |
-| **Integrations** | `docs/integrations.md` | Inbound/outbound external-system integration flows |
-| **Connectors** | `docs/connectors.md` | Connector apps: the manifest `connector` block + the functions the integration engine calls |
-| **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 |
-
----
-
-## Technical Overview
-
-- **Iframe-based** — Apps run inside iframes in both the public Portal and Admin Console
-- **Hash routing** — Uses `/#/` routes for iframe compatibility (e.g., `/#/`, `/#/admin`)
-- **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
-
----
-
-## Data Model Hierarchy
-
-```
-Collection (Business/Brand)
-  └── Product (Product Type/Definition)
-        └── Proof (Specific Instance with Owner)
-              └── Attestation (User/Admin Data on Proof)
-```
-
-| Entity | Description | Example |
-|--------|-------------|---------|
-| **Collection** | Top-level container representing a business or brand | "Acme Wine Co." |
-| **Product** | A type of product (not a specific item) | "2023 Cabernet Sauvignon" |
-| **Proof** | A specific instance of a product, often with an owner | Bottle #12345 claimed by user@email.com |
-| **Attestation** | Data attached to a proof by users or admins | Warranty registration, tasting notes |
-
-### URL Parameters
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `collectionId` | string | The collection being viewed/managed |
-| `productId` | string | The specific product (within collection) |
-| `proofId` | string | The specific proof instance |
-| `appId` | string | This app's unique identifier (for data scoping) |
-| `dark` | `1` or `0` | Whether to use dark mode |
-| `theme` | base64 | Full theme configuration (see `docs/theme.system.md`) |
-
----
-
-## Authentication & Permissions
-
-SmartLinks apps do **not** implement their own authentication. The parent platform handles all auth:
-
-- Use `SL.auth.getAccount()` to check if a user is logged in
-- The response includes whether the user is an `admin` or regular user
-- Many SmartLinks API functions behave differently based on admin status
-
-| Capability | Admin | Regular User |
-|------------|-------|-------------|
-| Read collection/product data | ✅ | ✅ |
-| Write app configuration | ✅ | ❌ |
-| Write attestations | ✅ | ✅ (own proofs only) |
-| Access admin-only API fields | ✅ | ❌ |
-
----
-
-## Data Storage Patterns
-
-### ⚠️ Critical: Admin Mode Flag
-
-**When building admin interfaces, you MUST pass `admin: true` in API options.**
-
-Without this flag, API calls use the public endpoint and will fail to write data:
-
-```typescript
-// ❌ WRONG — will fail in admin interface
-await SL.appConfiguration.setConfig({ collectionId, appId, config: myConfig });
-
-// ✅ CORRECT — include admin: true
-await SL.appConfiguration.setConfig({ collectionId, appId, config: myConfig, admin: true });
-```
-
-This applies to all write operations: `setConfig`, `setDataItem`, `updateDataItem`, etc.
-
-### Endpoint Auth vs Data Visibility
-
-`admin: true` is an endpoint selector, not a privacy marker.
-
-- It tells the SDK to call the admin endpoint.
-- It allows writes and admin reads.
-- It does **not** mean every root-level field you save becomes admin-only.
-
-For `appConfiguration` config blobs and `collection.getSettings()` groups, root-level fields are typically the public-facing settings. If you need private values such as tokens or secrets, store them inside a top-level `admin` object:
-
-```typescript
-await SL.appConfiguration.setConfig({
-  collectionId,
-  appId,
-  admin: true,
-  config: {
-    publicLabel: 'Warranty Portal',
-    color: '#B68C2A',
-    admin: {
-      accessToken: 'secret-token'
-    }
-  }
-})
-```
-
-Public reads omit the `admin` block. Admin reads include it.
-
-### Config vs Data
-
-| Storage Type | Function | Use Case |
-|-------------|---------|---------|
-| **Config** (`getConfig`/`setConfig`) | Single JSON document | App settings, feature flags, global options |
-| **Data** (`getData`/`setDataItem`) | Array of documents with IDs | Lists of items, records, entries |
-| **App Objects** (`app.records` / `app.cases` / `app.threads`) | Queryable domain objects | Real app entities, workflows, conversations, richer access control |
-
-Both can be scoped to **collection level** or **product level** by including `productId`.
-
-For config/settings visibility, remember: root fields are the normal shared payload, while a reserved top-level `admin` object is the place for admin-only values.
-
-Prefer `app.records` over `setDataItem` when the data is becoming a real entity that needs lifecycle, ownership, visibility, relationships, or filtering. Keep `setDataItem` for simple keyed scoped documents and config-adjacent content.
-
-### Feature Flags & Entitlements (`appConfig`)
-
-The platform-owned `appConfig` settings group (`system.features`, `system.meters`, `system.entitledAppGroups`, installed `apps[]`) tells a microapp what's installed and entitled for a collection. Use `SL.appConfiguration.isFeatureEnabled(collectionId, flag)` to gate a feature — it's the standard, cache-backed way to do this rather than hand-rolling a `getConfig` call:
-
-```ts
-if (await SL.appConfiguration.isFeatureEnabled(collectionId, 'custom_domain')) {
-  enableCustomDomainUI();
-}
-```
-
-It's async (the first check for a collection has nothing cached yet); `SL.appConfiguration.isFeatureEnabledSync()` gives a synchronous, cache-only read (`boolean | undefined`) for callers that warmed the cache earlier and can't await. See `docs/appConfig.md` for the full contract, including `systemPrivate` (admin-only overrides, always stripped for non-admin reads).
-
-### Attestations (Proof-level data)
-
-For data attached to specific proof instances, use `SL.attestation.create()` and `SL.attestation.list()`.
-
-### Custom Data Scoping (Product & Proof)
-
-`product.data`/`product.admin` and `proof.data`/`proof.admin`/`proof.values` are the canonical buckets for custom fields on products and proofs — `data` is public and business-writable, `admin` is business-only, and `proof.values` additionally supports owner-scoped (`values.owner`) and per-user (`values.personal[userId]`) sub-keys. This is a different mechanism from the app-scoped storage in `docs/app-data-storage.md` (which is for app-owned config/records, not the product/proof documents themselves).
-
-See `docs/proof-product-data-scoping.md` for the full read/write authority matrix, worked examples, and the `productFields`/`proofFields` collection-settings schemas that drive field-config editors.
-
----
-
-## Error Handling
-
-The SmartLinks SDK returns structured `SmartlinksApiError` objects. Use `instanceof SmartlinksApiError` to access `.statusCode`, `.message`, and helper methods:
-
-- `.isAuthError()` — 401/403 responses
-- `.isNotFound()` — 404 responses
-- `.isRateLimited()` — 429 responses
-- `.isServerError()` — 5xx responses
-
-See `docs/API_SUMMARY.md` for complete error handling documentation.
-
----
-
-## AI Integration
-
-SmartLinks provides comprehensive AI capabilities through the `SL.ai` namespace. **Always use SmartLinks AI for microapps** — do not integrate external AI services (OpenAI, Anthropic, Lovable Cloud AI, etc.) directly.
-
-Key capabilities: chat completions (streaming + tool calling), RAG document Q&A, voice input/output, podcast generation, text-to-speech, model listing.
-
-See `docs/ai.md` for complete documentation.
-
----
-
-## Interactions & Event Tracking
-
-The `SL.interactions` namespace tracks user engagement — competition entries, votes, form submissions, warranty registrations. Events can trigger automated journeys and communications.
-
-**The one rule:** you never choose an interaction id. In admin, `SL.interactions.ensureType(collectionId, { appId, key: 'vote', … })` finds-or-creates the type and returns its server-minted `id`; store it in app config (`interactionIds: { vote: type.id }`); everywhere else — public widgets included — read `interactionIds.vote` from config and pass that as `interactionId`. Never write an interactionId as a string literal.
-
-Key functions: `submitPublicEvent()`, `appendEvent()` (admin), `countsByOutcome()`, `query()`.
-
-See `docs/interactions.md` for complete documentation.
-
----
-
-## Liquid Templating
-
-Use the `<LiquidContent>` component, `useLiquidTemplate` hook, and `renderLiquid` utility for admin-configured dynamic content using Liquid syntax.
-
-See `docs/liquid-templates.md` for full context variables, filters, and examples.
-
----
-
-## Design Principles
-
-### Public Interface (Portal)
-
-- **Mobile-first** — Assume users are on phones
-- **Non-technical** — Never show raw IDs or technical data
-- **Accessible** — Follow WCAG guidelines
-
-### Admin Interface
-
-- **Feature-rich** — Power users expect advanced controls
-- **Efficient** — Minimise clicks for common tasks
-- **Desktop-optimised** — Admins typically use desktop browsers
-
-### Theming
-
-Apps receive theme configuration from the parent platform via URL parameter (`?theme=base64…`) and PostMessage updates. See `docs/theme.system.md`.
-
----
-
-## Common Hooks
-
-```typescript
-// Fetch collection/product/proof data
-useCollectionData(collectionId)
-useProductData(collectionId, productId)
-useProofData(collectionId, productId, proofId)
-
-// Fetch app configuration
-useCollectionAppConfig(collectionId, appId)
-useProductAppConfig(collectionId, productId, appId)
-
-// Fetch app data (array of items)
-useCollectionAppData(collectionId, appId)
-useProductAppData(collectionId, productId, appId)
-
-// Fetch attestations
-useAttestationsData(collectionId, productId, proofId)
-
-// URL parameter management
-usePersistentQueryParams()
-
-// Theme management
-useSmartLinksTheme()
-
-// Liquid templating
-useLiquidTemplate(templateString, contextData)
-```
-
----
-
-## API Namespaces
-
-The SmartLinks SDK is organised into namespaces. See `docs/API_SUMMARY.md` for the complete reference. Key namespaces:
-
-- `appConfiguration` — Config and data storage (most apps use this)
-- `attestation` — Proof-level user/admin data
-- `interactions` — Event tracking and analytics
-- `ai` — AI content generation, chat, RAG (see `docs/ai.md`)
-- `auth` / `authKit` — Admin and end-user authentication
-- `contact` — Customer contact management
-- `comms` / `broadcasts` — Notifications and campaigns
-- `asset` — File/image uploads
-- `adminCards` — the collection's dashboard: `list`, `refresh`, `saveLayout` (see `docs/admin-cards.md`)
-- `realtime` — SmartLinks Realtime: `onChange`, `channel`, `onMine` (see `docs/realtime.md`)
-
----
-
-## File Structure
-
-```
-├── index.html                  ← Public portal entry
-├── admin.html                  ← Admin console entry
-├── public/
-│   ├── app.manifest.json       ← Public discovery manifest
-│   ├── app.admin.json          ← Admin manifest (on-demand)
-│   └── ai-guide.md             ← AI orchestrator prose guide
-├── src/
-│   ├── main.tsx                ← Public React entry
-│   ├── admin-main.tsx          ← Admin React entry
-│   ├── App.tsx                 ← Shared providers (QueryClient, Toaster, etc.)
-│   ├── PublicApp.tsx           ← Public app shell (routes only public pages)
-│   ├── AdminApp.tsx            ← Admin app shell (routes only admin pages)
-│   ├── components/             ← Reusable UI components
-│   ├── containers/             ← Embeddable full-app containers
-│   ├── executor/               ← Executor bundle (SEO, LLM content, config API)
-│   ├── hooks/                  ← React hooks (data fetching, state)
-│   ├── pages/
-│   │   ├── PublicPage.tsx      ← Portal content (/#/)
-│   │   ├── AdminPage.tsx       ← Admin content (admin.html#/)
-│   │   └── DevPage.tsx         ← Development helper (dev only)
-│   ├── widgets/                ← Embeddable widget components
-│   └── utils/
-│       ├── smartlinks/         ← SmartLinks utilities
-│       └── theme.ts            ← Theme utilities
-├── vite.config.ts              ← Multi-page build config
-├── vite.config.widget.ts       ← Widget library build config
-├── vite.config.container.ts    ← Container library build config
-└── vite.config.executor.ts     ← Executor library build config
-```
-
----
-
-## Anti-Patterns to Avoid
-
-❌ **Don't implement custom auth** — Use SmartLinks auth via `SL.auth.getAccount()`
-
-❌ **Don't use BrowserRouter** — Always use HashRouter for iframe compatibility
-
-❌ **Don't hardcode URLs** — Use relative paths and let the platform provide context
-
-❌ **Don't store secrets in code** — Use environment variables or platform configuration
-
-❌ **Don't assume screen size** — Support both mobile (Portal) and desktop (Admin)
-
-❌ **Don't expose technical IDs** — Show human-readable names to users
-
-❌ **Don't import AdminPage in PublicApp** — Keep bundles separate for optimal size
-
-❌ **Don't use external AI services** — Use SmartLinks AI via `SL.ai`, not OpenAI/Anthropic/Lovable Cloud AI directly
-
-❌ **Don't forget `admin: true`** — All admin write operations require this flag
-
----
-
-## Quick Reference
-
-### Initialise the API
-
-```typescript
-import { initializeAPI } from '@/utils/smartlinks/initialization';
-initializeAPI(); // Call once at app startup
-```
-
-### Get Context from URL
-
-```typescript
-const { persistentQueryParams } = usePersistentQueryParams();
-const { collectionId, productId, appId } = persistentQueryParams;
-```
-
-### Check Admin Status
-
-```typescript
-const account = await SL.auth.getAccount();
-const isAdmin = account?.admin === true;
-```
-
-### Save Configuration (Admin Only)
-
-```typescript
-await SL.appConfiguration.setConfig({
-  collectionId, appId,
-  config: { myKey: 'myValue' },
-  admin: true  // Required!
-});
-```
-
-### Handle Dark Mode + Theming
-
-```typescript
-// In App.tsx — already integrated in the template
-useDarkMode();        // Handles ?dark=1 parameter
-useSmartLinksTheme(); // Handles ?theme=base64 parameter
-useDeepLinkSync();    // Syncs route changes to parent
-```
-
-### Deep Linking
-
-```typescript
-const { navigateWithState, getAppState } = usePersistentQueryParams();
-const { tab = 'general' } = getAppState();
-navigateWithState('/', { tab: 'advanced' });
-```
-
-See `docs/deep-link-discovery.md` for full implementation details.
+# SmartLinks Microapp Development Guide
+
+> **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 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.
+
+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:
+
+- **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
+
+Each microapp can be consumed in one or more of the following ways:
+
+| Mode | Description |
+|------|-------------|
+| **Container** | Full app in parent React tree. ~150 KB+ lazy-loaded. The primary consumer surface. |
+| **Iframe App** | Full React app inside an iframe. Fallback when sandboxing is required; still the standard for setup admin screens. |
+| **Widget** | Lightweight React component in parent tree. ~10 KB, loaded immediately alongside the page. |
+| **Mobile Admin Container** | Separate bundle for in-the-field operator/admin workflows on mobile. Built independently; may use Capacitor, Preact, or any other runtime. |
+| **Executor** | JS library, no UI. Programmatic config, SEO metadata, LLM content for AI/server. |
+
+Widgets and containers run in the parent's React tree (not iframes). Mobile Admin Containers are a separate bundle loaded by a dedicated mobile shell (Capacitor or PWA). Executors have no UI — they expose functions that AI orchestrators and the server call directly.
+
+> **Admin vs consumer:** Admin experiences always ship as a **separate bundle** (`mobileAdmin` or iframe). The `containers` bundle is for consumer-facing surfaces only.
+
+---
+
+## SDK Documentation Reference
+
+The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive documentation in `node_modules/@proveanything/smartlinks/docs/`. **Always read these files for detailed implementation guidance.**
+
+> Product endpoints: use `products` (plural) for new integrations. The older `product` (singular) namespace remains for backward compatibility and is deprecated.
+
+> **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 |
+|-------|------|-------------|
+| **API Reference** | `docs/API_SUMMARY.md` | Complete SDK function reference, types, error handling |
+| **Assets** | `docs/assets.md` | Asset object, AssetRef, upload, replace, soft-delete, restore, bulk-delete, public token-based uploads |
+| **Building React Components** | `docs/building-react-components.md` | **READ THIS FIRST** — Dual-mode rendering, router rules, useAppContext pattern |
+| **Multi-Page Architecture** | `docs/mpa.md` | Build pipeline, entry points, multi-page setup, content hashing |
+| **AI & Chat** | `docs/ai.md` | Chat completions, RAG, streaming, tool calling, voice, podcasts, TTS |
+| **Analytics** | `docs/analytics.md` | Fire-and-forget page/click/tag analytics plus admin dashboard queries |
+| **Translations** | `docs/translations.md` | Runtime translation lookup, local-first IndexedDB caching, and translation admin APIs |
+| **Theming** | `docs/theme.system.md` | Implementing dynamic themes via URL params or postMessage |
+| **Theme Defaults** | `docs/theme-defaults.md` | Default colour values for light/dark modes |
+| **Internationalization** | `docs/i18n.md` | Adding multi-language support, translation patterns |
+| **Widgets** | `docs/widgets.md` | Building widgets, shared deps contract, settings schema |
+| **Containers** | `docs/containers.md` | Building full-app embeddable containers (lazy-loaded) |
+| **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; **opt-in per app, additive, no migration**; complements `app.admin.json` (functions serve/adapt it, don't replace it); live loop staged |
+| **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 |
+| **CSS Baseline** (`sl-baseline` v1) | `docs/css-baseline.md` | A small, frozen, `sl-`-namespaced set of structural helpers (layout, spacing, responsive flow, type scale, motion) the SDK ships (`@proveanything/smartlinks/baseline.css`) and the host guarantees — a teachable floor for apps + AI content. No colours/fonts/components. Opt-in via `meta.cssBaseline` |
+| **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 |
+| **App Config Files** | `docs/app-manifest.md` | Full field-by-field reference for both JSON config files |
+| **Admin cards** | `docs/admin-cards.md` | Cards on the collection's dashboard in Studio: declare a card + an admin function returning its data; cached, refreshed only when its data changes |
+| **Realtime** | `docs/realtime.md` | Live updates: change events (refetch when something changes) and declared app channels (a draw, a status) — no provider library or keys |
+| **Liquid Templates** | `docs/liquid-templates.md` | Dynamic content rendering with LiquidJS |
+| **Iframe Responder** | `docs/iframe-responder.md` | Iframe communication and proxy mode internals |
+| **AI Guide Template** | `docs/ai-guide-template.md` | Template for creating `public/ai-guide.md` — customise per app |
+| **Forms** | `docs/forms.md` | Form definitions, schema-driven rendering, submission patterns |
+| **Auth Kit** | `docs/auth-kit.md` | End-user sign-in: email/password, magic links, phone OTP, Google OAuth |
+| **Members** | `docs/members.md` | Signed-in members with a level (clubs, leagues, members' areas): the level field, members-only functions, joining rules |
+| **Portal Request Login** | `docs/portal-request-login.md` | How sub-apps ask the portal to authenticate the user; hook and iframe postMessage contracts |
+| **Portal Auth Broadcast** | `docs/portal-auth-broadcast.md` | Publishing custom auth flows to the portal; syncing sessions across containers and iframes |
+| **Contact Search** | `docs/contact-search.md` | Admin contact search: free-text, typeahead, identity/tag/JSONB filters, and pagination |
+| **App Records Pattern** | `docs/app-records-pattern.md` | Standard pattern for per-product/facet/variant/batch admin + public widget UIs |
+| **UI Utils** | `docs/ui-utils.md` | `@proveanything/smartlinks-utils-ui` — React shells, hooks, and primitives for records-based apps |
+| **Product/Proof Data Scoping** | `docs/proof-product-data-scoping.md` | Canonical spec for `product.data`/`.admin` and `proof.data`/`.admin`/`.values` (owner/personal) — who can read and write each bucket |
+| **Proof Claiming** | `docs/proof-claiming-methods.md` | The ways a user claims a proof (serial, NFC, claim-set, auto-generate) |
+| **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 |
+| **Integrations** | `docs/integrations.md` | Inbound/outbound external-system integration flows |
+| **Connectors** | `docs/connectors.md` | Connector apps: the manifest `connector` block + the functions the integration engine calls |
+| **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 |
+
+---
+
+## Technical Overview
+
+- **Iframe-based** — Apps run inside iframes in both the public Portal and Admin Console
+- **Hash routing** — Uses `/#/` routes for iframe compatibility (e.g., `/#/`, `/#/admin`)
+- **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
+
+---
+
+## Data Model Hierarchy
+
+```
+Collection (Business/Brand)
+  └── Product (Product Type/Definition)
+        └── Proof (Specific Instance with Owner)
+              └── Attestation (User/Admin Data on Proof)
+```
+
+| Entity | Description | Example |
+|--------|-------------|---------|
+| **Collection** | Top-level container representing a business or brand | "Acme Wine Co." |
+| **Product** | A type of product (not a specific item) | "2023 Cabernet Sauvignon" |
+| **Proof** | A specific instance of a product, often with an owner | Bottle #12345 claimed by user@email.com |
+| **Attestation** | Data attached to a proof by users or admins | Warranty registration, tasting notes |
+
+### URL Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `collectionId` | string | The collection being viewed/managed |
+| `productId` | string | The specific product (within collection) |
+| `proofId` | string | The specific proof instance |
+| `appId` | string | This app's unique identifier (for data scoping) |
+| `dark` | `1` or `0` | Whether to use dark mode |
+| `theme` | base64 | Full theme configuration (see `docs/theme.system.md`) |
+
+---
+
+## Authentication & Permissions
+
+SmartLinks apps do **not** implement their own authentication. The parent platform handles all auth:
+
+- Use `SL.auth.getAccount()` to check if a user is logged in
+- The response includes whether the user is an `admin` or regular user
+- Many SmartLinks API functions behave differently based on admin status
+
+| Capability | Admin | Regular User |
+|------------|-------|-------------|
+| Read collection/product data | ✅ | ✅ |
+| Write app configuration | ✅ | ❌ |
+| Write attestations | ✅ | ✅ (own proofs only) |
+| Access admin-only API fields | ✅ | ❌ |
+
+---
+
+## Data Storage Patterns
+
+### ⚠️ Critical: Admin Mode Flag
+
+**When building admin interfaces, you MUST pass `admin: true` in API options.**
+
+Without this flag, API calls use the public endpoint and will fail to write data:
+
+```typescript
+// ❌ WRONG — will fail in admin interface
+await SL.appConfiguration.setConfig({ collectionId, appId, config: myConfig });
+
+// ✅ CORRECT — include admin: true
+await SL.appConfiguration.setConfig({ collectionId, appId, config: myConfig, admin: true });
+```
+
+This applies to all write operations: `setConfig`, `setDataItem`, `updateDataItem`, etc.
+
+### Endpoint Auth vs Data Visibility
+
+`admin: true` is an endpoint selector, not a privacy marker.
+
+- It tells the SDK to call the admin endpoint.
+- It allows writes and admin reads.
+- It does **not** mean every root-level field you save becomes admin-only.
+
+For `appConfiguration` config blobs and `collection.getSettings()` groups, root-level fields are typically the public-facing settings. If you need private values such as tokens or secrets, store them inside a top-level `admin` object:
+
+```typescript
+await SL.appConfiguration.setConfig({
+  collectionId,
+  appId,
+  admin: true,
+  config: {
+    publicLabel: 'Warranty Portal',
+    color: '#B68C2A',
+    admin: {
+      accessToken: 'secret-token'
+    }
+  }
+})
+```
+
+Public reads omit the `admin` block. Admin reads include it.
+
+### Config vs Data
+
+| Storage Type | Function | Use Case |
+|-------------|---------|---------|
+| **Config** (`getConfig`/`setConfig`) | Single JSON document | App settings, feature flags, global options |
+| **Data** (`getData`/`setDataItem`) | Array of documents with IDs | Lists of items, records, entries |
+| **App Objects** (`app.records` / `app.cases` / `app.threads`) | Queryable domain objects | Real app entities, workflows, conversations, richer access control |
+
+Both can be scoped to **collection level** or **product level** by including `productId`.
+
+For config/settings visibility, remember: root fields are the normal shared payload, while a reserved top-level `admin` object is the place for admin-only values.
+
+Prefer `app.records` over `setDataItem` when the data is becoming a real entity that needs lifecycle, ownership, visibility, relationships, or filtering. Keep `setDataItem` for simple keyed scoped documents and config-adjacent content.
+
+### Feature Flags & Entitlements (`appConfig`)
+
+The platform-owned `appConfig` settings group (`system.features`, `system.meters`, `system.entitledAppGroups`, installed `apps[]`) tells a microapp what's installed and entitled for a collection. Use `SL.appConfiguration.isFeatureEnabled(collectionId, flag)` to gate a feature — it's the standard, cache-backed way to do this rather than hand-rolling a `getConfig` call:
+
+```ts
+if (await SL.appConfiguration.isFeatureEnabled(collectionId, 'custom_domain')) {
+  enableCustomDomainUI();
+}
+```
+
+It's async (the first check for a collection has nothing cached yet); `SL.appConfiguration.isFeatureEnabledSync()` gives a synchronous, cache-only read (`boolean | undefined`) for callers that warmed the cache earlier and can't await. See `docs/appConfig.md` for the full contract, including `systemPrivate` (admin-only overrides, always stripped for non-admin reads).
+
+### Attestations (Proof-level data)
+
+For data attached to specific proof instances, use `SL.attestation.create()` and `SL.attestation.list()`.
+
+### Custom Data Scoping (Product & Proof)
+
+`product.data`/`product.admin` and `proof.data`/`proof.admin`/`proof.values` are the canonical buckets for custom fields on products and proofs — `data` is public and business-writable, `admin` is business-only, and `proof.values` additionally supports owner-scoped (`values.owner`) and per-user (`values.personal[userId]`) sub-keys. This is a different mechanism from the app-scoped storage in `docs/app-data-storage.md` (which is for app-owned config/records, not the product/proof documents themselves).
+
+See `docs/proof-product-data-scoping.md` for the full read/write authority matrix, worked examples, and the `productFields`/`proofFields` collection-settings schemas that drive field-config editors.
+
+---
+
+## Error Handling
+
+The SmartLinks SDK returns structured `SmartlinksApiError` objects. Use `instanceof SmartlinksApiError` to access `.statusCode`, `.message`, and helper methods:
+
+- `.isAuthError()` — 401/403 responses
+- `.isNotFound()` — 404 responses
+- `.isRateLimited()` — 429 responses
+- `.isServerError()` — 5xx responses
+
+See `docs/API_SUMMARY.md` for complete error handling documentation.
+
+---
+
+## AI Integration
+
+SmartLinks provides comprehensive AI capabilities through the `SL.ai` namespace. **Always use SmartLinks AI for microapps** — do not integrate external AI services (OpenAI, Anthropic, Lovable Cloud AI, etc.) directly.
+
+Key capabilities: chat completions (streaming + tool calling), RAG document Q&A, voice input/output, podcast generation, text-to-speech, model listing.
+
+See `docs/ai.md` for complete documentation.
+
+---
+
+## Interactions & Event Tracking
+
+The `SL.interactions` namespace tracks user engagement — competition entries, votes, form submissions, warranty registrations. Events can trigger automated journeys and communications.
+
+**The one rule:** you never choose an interaction id. In admin, `SL.interactions.ensureType(collectionId, { appId, key: 'vote', … })` finds-or-creates the type and returns its server-minted `id`; store it in app config (`interactionIds: { vote: type.id }`); everywhere else — public widgets included — read `interactionIds.vote` from config and pass that as `interactionId`. Never write an interactionId as a string literal.
+
+Key functions: `submitPublicEvent()`, `appendEvent()` (admin), `countsByOutcome()`, `query()`.
+
+See `docs/interactions.md` for complete documentation.
+
+---
+
+## Liquid Templating
+
+Use the `<LiquidContent>` component, `useLiquidTemplate` hook, and `renderLiquid` utility for admin-configured dynamic content using Liquid syntax.
+
+See `docs/liquid-templates.md` for full context variables, filters, and examples.
+
+---
+
+## Design Principles
+
+### Public Interface (Portal)
+
+- **Mobile-first** — Assume users are on phones
+- **Non-technical** — Never show raw IDs or technical data
+- **Accessible** — Follow WCAG guidelines
+
+### Admin Interface
+
+- **Feature-rich** — Power users expect advanced controls
+- **Efficient** — Minimise clicks for common tasks
+- **Desktop-optimised** — Admins typically use desktop browsers
+
+### Theming
+
+Apps receive theme configuration from the parent platform via URL parameter (`?theme=base64…`) and PostMessage updates. See `docs/theme.system.md`.
+
+---
+
+## Common Hooks
+
+```typescript
+// Fetch collection/product/proof data
+useCollectionData(collectionId)
+useProductData(collectionId, productId)
+useProofData(collectionId, productId, proofId)
+
+// Fetch app configuration
+useCollectionAppConfig(collectionId, appId)
+useProductAppConfig(collectionId, productId, appId)
+
+// Fetch app data (array of items)
+useCollectionAppData(collectionId, appId)
+useProductAppData(collectionId, productId, appId)
+
+// Fetch attestations
+useAttestationsData(collectionId, productId, proofId)
+
+// URL parameter management
+usePersistentQueryParams()
+
+// Theme management
+useSmartLinksTheme()
+
+// Liquid templating
+useLiquidTemplate(templateString, contextData)
+```
+
+---
+
+## API Namespaces
+
+The SmartLinks SDK is organised into namespaces. See `docs/API_SUMMARY.md` for the complete reference. Key namespaces:
+
+- `appConfiguration` — Config and data storage (most apps use this)
+- `attestation` — Proof-level user/admin data
+- `interactions` — Event tracking and analytics
+- `ai` — AI content generation, chat, RAG (see `docs/ai.md`)
+- `auth` / `authKit` — Admin and end-user authentication
+- `contact` — Customer contact management
+- `comms` / `broadcasts` — Notifications and campaigns
+- `asset` — File/image uploads
+- `adminCards` — the collection's dashboard: `list`, `refresh`, `saveLayout` (see `docs/admin-cards.md`)
+- `realtime` — SmartLinks Realtime: `onChange`, `channel`, `onMine` (see `docs/realtime.md`)
+
+---
+
+## File Structure
+
+```
+├── index.html                  ← Public portal entry
+├── admin.html                  ← Admin console entry
+├── public/
+│   ├── app.manifest.json       ← Public discovery manifest
+│   ├── app.admin.json          ← Admin manifest (on-demand)
+│   └── ai-guide.md             ← AI orchestrator prose guide
+├── src/
+│   ├── main.tsx                ← Public React entry
+│   ├── admin-main.tsx          ← Admin React entry
+│   ├── App.tsx                 ← Shared providers (QueryClient, Toaster, etc.)
+│   ├── PublicApp.tsx           ← Public app shell (routes only public pages)
+│   ├── AdminApp.tsx            ← Admin app shell (routes only admin pages)
+│   ├── components/             ← Reusable UI components
+│   ├── containers/             ← Embeddable full-app containers
+│   ├── executor/               ← Executor bundle (SEO, LLM content, config API)
+│   ├── hooks/                  ← React hooks (data fetching, state)
+│   ├── pages/
+│   │   ├── PublicPage.tsx      ← Portal content (/#/)
+│   │   ├── AdminPage.tsx       ← Admin content (admin.html#/)
+│   │   └── DevPage.tsx         ← Development helper (dev only)
+│   ├── widgets/                ← Embeddable widget components
+│   └── utils/
+│       ├── smartlinks/         ← SmartLinks utilities
+│       └── theme.ts            ← Theme utilities
+├── vite.config.ts              ← Multi-page build config
+├── vite.config.widget.ts       ← Widget library build config
+├── vite.config.container.ts    ← Container library build config
+└── vite.config.executor.ts     ← Executor library build config
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+❌ **Don't implement custom auth** — Use SmartLinks auth via `SL.auth.getAccount()`
+
+❌ **Don't use BrowserRouter** — Always use HashRouter for iframe compatibility
+
+❌ **Don't hardcode URLs** — Use relative paths and let the platform provide context
+
+❌ **Don't store secrets in code** — Use environment variables or platform configuration
+
+❌ **Don't assume screen size** — Support both mobile (Portal) and desktop (Admin)
+
+❌ **Don't expose technical IDs** — Show human-readable names to users
+
+❌ **Don't import AdminPage in PublicApp** — Keep bundles separate for optimal size
+
+❌ **Don't use external AI services** — Use SmartLinks AI via `SL.ai`, not OpenAI/Anthropic/Lovable Cloud AI directly
+
+❌ **Don't forget `admin: true`** — All admin write operations require this flag
+
+---
+
+## Quick Reference
+
+### Initialise the API
+
+```typescript
+import { initializeAPI } from '@/utils/smartlinks/initialization';
+initializeAPI(); // Call once at app startup
+```
+
+### Get Context from URL
+
+```typescript
+const { persistentQueryParams } = usePersistentQueryParams();
+const { collectionId, productId, appId } = persistentQueryParams;
+```
+
+### Check Admin Status
+
+```typescript
+const account = await SL.auth.getAccount();
+const isAdmin = account?.admin === true;
+```
+
+### Save Configuration (Admin Only)
+
+```typescript
+await SL.appConfiguration.setConfig({
+  collectionId, appId,
+  config: { myKey: 'myValue' },
+  admin: true  // Required!
+});
+```
+
+### Handle Dark Mode + Theming
+
+```typescript
+// In App.tsx — already integrated in the template
+useDarkMode();        // Handles ?dark=1 parameter
+useSmartLinksTheme(); // Handles ?theme=base64 parameter
+useDeepLinkSync();    // Syncs route changes to parent
+```
+
+### Deep Linking
+
+```typescript
+const { navigateWithState, getAppState } = usePersistentQueryParams();
+const { tab = 'general' } = getAppState();
+navigateWithState('/', { tab: 'advanced' });
+```
+
+See `docs/deep-link-discovery.md` for full implementation details.